ast-common-core

Production-ready shared utilities and interfaces for the AST ecosystem

Overview

ast-common-core provides the foundational components shared across all AST (Abstract Syntax Tree) analysis and refactoring tools. This production-ready library (v2.0.0) features 92% test coverage, comprehensive type safety, and professional-grade implementations.

Ecosystem Integration:

• ast-dependency-analyzer: Dependency graph analysis and visualization
• ast-refactor-agent: Intelligent code refactoring tools
• Other AST ecosystem tools

📚 Complete Documentation | 🚀 Quickstart Guide | 📖 API Reference | 🏗️ Architecture

Features

🧩 Core Interfaces

Define contracts for extensible components (API Docs):

• ILogger: Logging interface with debug/info/warning/error/critical levels
• IParser: Parser interface for different programming languages
• IPerformanceTracker: Performance monitoring and metrics collection

📦 Data Models

Pydantic-based models with comprehensive validation (API Docs):

• Package: Software package representation with dependencies, versions, and metadata
• Vulnerability: Security vulnerability information with CVSS scoring, CWE IDs, and remediation
• Severity: Standardized severity levels (CRITICAL, HIGH, MEDIUM, LOW, INFO)
• PackageType: Support for 12 package ecosystems (Python, JavaScript, Rust, Go, Java, Ruby, PHP, C#, etc.)

🔌 Dependency Injection Framework

Lightweight DI framework for loose coupling (API Docs):

• Container: Service registration and resolution
• Lifecycle Management: Singleton, Transient, and Scoped lifecycles
• Type-Safe: Full type hint support
• Thread-Safe: Production-ready concurrency handling

🚨 Exception Hierarchy

Comprehensive exception system with context (API Docs):

• DependencyGraphError - Base exception with context preservation
• PackageError, VulnerabilityError, DependencyError - Domain-specific errors
• CircularDependencyError, VersionConflictError - Specialized errors
• Smart Default Messages: Automatic context-aware error message generation
• 16 total exceptions covering all use cases

Installation

From PyPI (Recommended)

pip install ast-common-core

From Source (Development)

# Clone repository
git clone https://github.com/username/ast-common-core.git
cd ast-common-core

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

📖 Complete Installation Guide - Includes Docker, CI/CD, troubleshooting

Quick Start

Using Data Models

from ast_common.models import Package, Severity, Vulnerability

# Create a package
package = Package(
    name="example-package",
    version="1.0.0",
    dependencies={"dep1", "dep2"}
)

# Create a vulnerability
vuln = Vulnerability(
    id="CVE-2024-1234",
    package="example-package",
    severity=Severity.HIGH,
    cvss_score=7.5,
    description="Example vulnerability"
)

# Derive severity from CVSS score
severity = Severity.from_cvss_score(8.5)  # Returns Severity.HIGH

Using Dependency Injection

from ast_common.di import Container, inject
from ast_common.interfaces import ILogger

# Create and configure container
container = Container()
container.register_singleton(ILogger, MyLoggerImplementation)

# Use inject decorator
@inject(container)
def my_function(logger: ILogger):
    logger.info("Dependency injected automatically!")

my_function()  # Logger is injected automatically

Using Exceptions

from ast_common.exceptions import CircularDependencyError

# Detect and report circular dependencies
cycle = ["pkg-a", "pkg-b", "pkg-c"]
raise CircularDependencyError(cycle=cycle)
# Output: "Circular dependency detected: pkg-a -> pkg-b -> pkg-c -> pkg-a"

Architecture

ast-common-core/
├── src/ast_common/
│   ├── __init__.py          # Main package exports
│   ├── interfaces/          # Core interfaces (ILogger, IParser, IPerformanceTracker)
│   ├── models/              # Pydantic data models (Package, Vulnerability)
│   ├── exceptions/          # Exception hierarchy (16 exceptions)
│   ├── di/                  # Dependency injection framework
│   ├── core/                # Core implementations (Logger)
│   └── py.typed             # PEP 561 type checking marker
├── docs/                    # Comprehensive documentation
│   ├── api/                 # API reference documentation
│   ├── architecture/        # System architecture docs
│   ├── user-guides/         # User tutorials and guides
│   └── operations/          # Installation and deployment
├── tests/                   # Test suite (181 tests, 92% coverage)
│   ├── test_logging.py      # Logger tests (43 tests, 100% coverage)
│   ├── test_models.py       # Model tests (62 tests)
│   ├── test_interfaces.py   # Interface tests
│   └── test_exceptions.py   # Exception tests
└── pyproject.toml          # Package configuration

🏗️ Architecture Documentation - Design principles, patterns, and diagrams

Development

Running Tests

# Run all tests with coverage
pytest tests/ -v --cov=ast_common --cov-report=term-missing

# Run specific test file
pytest tests/test_models.py -v

# Current coverage: 92% (181 tests passing)

Code Quality

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

# Type checking
mypy src/ast_common --ignore-missing-imports

# All checks should pass before committing

📚 Development Guide | 🤝 Contributing Guidelines

Requirements

• Python: 3.10+ (tested on 3.10, 3.11, 3.12)
• Required Dependencies:
  • pydantic >= 2.0.0, < 3.0.0
• Development Dependencies (optional):
  • pytest >= 7.0.0
  • pytest-cov >= 4.0.0
  • pytest-asyncio >= 0.21.0
  • mypy >= 1.0.0
  • ruff >= 0.1.0

What's New in v2.0.0

✨ Major Production Release:

• Enhanced Models: Added 5 new Vulnerability fields (affected_versions, fixed_version, cwe_ids, etc.)
• Expanded Package Types: Support for 9 additional ecosystems (Rust, Go, Java, Ruby, PHP, C#, etc.)
• Improved Exceptions: 7 exceptions enhanced with smart default messages and better context
• Complete Testing: 92% coverage with 181 professional-grade tests
• Type Safety: Added py.typed marker for full type checking support
• Production Quality: Zero shortcuts, comprehensive validation, professional implementations

📋 Complete Changelog | 🔄 Migration Guide

License

MIT License - see LICENSE file for details

Documentation

Complete documentation is available in the docs/ directory:

• 📖 Quickstart Guide - Get started in 5 minutes
• 🔧 API Reference - Complete API documentation
  • Interfaces
  • Models
  • Exceptions
• 🏗️ Architecture - System design and patterns
• 📦 Installation Guide - All installation methods
• 🤝 Contributing - Contribution guidelines and standards
• 📝 Changelog - Version history and migration guides

Contributing

Contributions are welcome! Please read our Contributing Guidelines for:

• Development environment setup
• Code style and quality standards (PEP 8, type hints, 85%+ test coverage)
• Pull request process and review guidelines
• Testing requirements and best practices

Key Requirements:

• All code must have type hints
• Test coverage must be 85%+ for new code
• Follow PEP 8 with 100-character line limit
• Write comprehensive docstrings (Google style)

Related Projects

• ast-dependency-analyzer: Dependency graph analysis tool
• ast-refactor-agent: Intelligent refactoring assistant
• PDF-Preprocessing (document-ai-pipeline): Document processing pipeline

Support

• 📖 Documentation: docs/
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• ❓ FAQ: docs/user-guides/faq.md

---

Version: 2.0.0 (Changelog) Status: Production Ready (92% Test Coverage) License: MIT (LICENSE) Maintainer: PredX007

Quality Metrics:

• ✅ 181 tests passing
• ✅ 92% code coverage
• ✅ 100% type hint coverage
• ✅ Zero known bugs
• ✅ Production-ready code quality