apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/parsing/services.py

@@ -0,0 +1,544 @@
+"""
+Abstract service protocols for language-agnostic analysis.
+
+These protocols define the contracts that language-specific implementations
+must fulfill. Framework plugins depend on these abstractions, NOT on
+language-specific implementations directly.
+
+DESIGN PRINCIPLES:
+1. Framework plugins should ONLY depend on these protocols
+2. Language-specific implementations live in parsing/{language}/
+3. This enables adding new languages without changing framework plugins
+4. DRY: Common concepts are defined once, implemented per-language
+
+Example:
+    # Framework plugin uses protocol, not implementation
+    class FastAPIPlugin(BaseFrameworkPlugin):
+        def extract_routes(self, file: ParsedFile, ctx: AnalysisContext):
+            # Uses abstract TypeResolver, not Python-specific CrossFileResolver
+            model_fields = ctx.type_resolver.get_model_fields("UserRequest")
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .base import ParsedClass, ParsedFile
+
+
+# =============================================================================
+# Type Resolution Protocol
+# =============================================================================
+
+
+@dataclass
+class ResolvedType:
+    """
+    A resolved type reference.
+
+    This is the language-agnostic representation of a resolved type.
+    """
+
+    name: str
+    qualified_name: str
+    file_path: Path | None = None
+
+    # Type classification
+    is_class: bool = False
+    is_model: bool = False  # Pydantic, dataclass, DTO, etc.
+    is_enum: bool = False
+    is_external: bool = False  # From external package
+    external_package: str | None = None
+
+    # Inheritance info
+    base_classes: list[str] = field(default_factory=list)
+    all_ancestors: list[str] = field(default_factory=list)  # Full chain
+    mro: list[str] = field(default_factory=list)  # Method Resolution Order
+
+    # For models: field information
+    fields: list[ResolvedField] = field(default_factory=list)
+
+    # The original parsed class, if available
+    definition: ParsedClass | None = None
+
+
+@dataclass
+class ResolvedField:
+    """A resolved field within a model/class."""
+
+    name: str
+    type_annotation: str | None = None
+    default_value: str | None = None
+    is_required: bool = True
+
+    # For nested types
+    nested_type_name: str | None = None
+    nested_type_qualified: str | None = None
+
+    # Field metadata
+    alias: str | None = None
+    description: str | None = None
+    constraints: dict[str, Any] = field(default_factory=dict)
+
+    # Source
+    defined_in_class: str | None = None  # Which class in MRO defines this
+
+
+@runtime_checkable
+class TypeResolver(Protocol):
+    """
+    Protocol for cross-file type resolution.
+
+    Language implementations provide their own resolvers that fulfill
+    this contract. Framework plugins depend on this protocol, not on
+    language-specific implementations.
+
+    Implementations:
+    - Python: CrossFileResolver (uses import graph, MRO)
+    - Java: Would use package/import resolution
+    - TypeScript: Would use module resolution
+    """
+
+    def resolve_type(
+        self,
+        name: str,
+        in_file: Path | None = None,
+    ) -> ResolvedType | None:
+        """
+        Resolve a type reference to its definition.
+
+        Args:
+            name: Type name (simple or qualified)
+            in_file: File context for import resolution
+
+        Returns:
+            ResolvedType if found, None otherwise
+        """
+        ...
+
+    def is_model_type(
+        self,
+        name: str,
+        in_file: Path | None = None,
+    ) -> bool:
+        """
+        Check if a type is a data model (Pydantic, dataclass, DTO, etc.).
+
+        This is framework-agnostic: each language defines what constitutes
+        a "model" (Python: Pydantic/dataclass, Java: POJO/DTO, etc.)
+        """
+        ...
+
+    def get_model_fields(
+        self,
+        model_name: str,
+        in_file: Path | None = None,
+        include_inherited: bool = True,
+    ) -> list[ResolvedField]:
+        """
+        Get fields for a model type, optionally including inherited fields.
+
+        Args:
+            model_name: Name of the model class
+            in_file: File context
+            include_inherited: Whether to include fields from base classes
+
+        Returns:
+            List of resolved fields
+        """
+        ...
+
+    def is_subclass_of(
+        self,
+        class_name: str,
+        base_name: str,
+        in_file: Path | None = None,
+    ) -> bool:
+        """
+        Check if a class inherits from another.
+
+        Uses the full inheritance chain, not just direct bases.
+        """
+        ...
+
+    def get_all_models(self) -> dict[str, ResolvedType]:
+        """Get all detected model types in the project."""
+        ...
+
+
+# =============================================================================
+# Constant/Config Resolution Protocol
+# =============================================================================
+
+
+@dataclass
+class ResolvedConstant:
+    """A resolved constant or configuration value."""
+
+    name: str
+    value: str
+
+    # Source info
+    source_file: Path | None = None
+    source_line: int = 0
+    source_type: str = ""  # "literal", "env_default", "config_attr", etc.
+
+    # Override tracking
+    is_default: bool = True  # True if can be overridden at runtime
+    override_sources: list[str] = field(default_factory=list)  # e.g., ["ENV:API_PREFIX"]
+
+    # Confidence
+    confidence: float = 1.0
+
+
+@runtime_checkable
+class ConstantResolver(Protocol):
+    """
+    Protocol for resolving constants and configuration values.
+
+    Language implementations handle their specific patterns:
+    - Python: module constants, Pydantic Settings, os.getenv()
+    - Java: application.properties, @Value annotations
+    - TypeScript: .env, config objects
+    """
+
+    def resolve(
+        self,
+        expression: str,
+        in_file: Path | None = None,
+    ) -> ResolvedConstant | None:
+        """
+        Resolve a constant expression to its value.
+
+        Handles:
+        - Simple names: API_PREFIX
+        - Attribute access: config.PREFIX, settings.api.prefix
+        - Env var defaults: os.getenv("X", "default")
+        """
+        ...
+
+    def resolve_value(
+        self,
+        expression: str,
+        in_file: Path | None = None,
+    ) -> str | None:
+        """Convenience method to just get the value string."""
+        ...
+
+    def get_all_constants(self) -> dict[str, str]:
+        """Get all resolved constants as name -> value mapping."""
+        ...
+
+
+# =============================================================================
+# Path Resolution Protocol
+# =============================================================================
+
+
+@dataclass
+class ResolvedPath:
+    """A resolved route path."""
+
+    path: str  # The resolved path string
+
+    # Resolution quality
+    confidence: float = 1.0
+    is_fully_resolved: bool = True
+    unresolved_vars: list[str] = field(default_factory=list)
+
+    # Notes about resolution
+    notes: list[str] = field(default_factory=list)
+
+
+@runtime_checkable
+class PathResolver(Protocol):
+    """
+    Protocol for resolving computed route paths.
+
+    Handles dynamic path construction:
+    - Python: f-strings, string concatenation
+    - Java: String.format(), concatenation
+    - TypeScript: template literals
+    """
+
+    def resolve(
+        self,
+        path_expression: str,
+        file_path: Path,
+        additional_context: dict[str, str] | None = None,
+    ) -> ResolvedPath:
+        """
+        Resolve a path expression to its final value.
+
+        Args:
+            path_expression: The path expression (may contain variables)
+            file_path: Source file for context
+            additional_context: Additional variable bindings
+
+        Returns:
+            ResolvedPath with the resolved string and confidence
+        """
+        ...
+
+    def get_all_constants(self) -> dict[str, str]:
+        """Get all path-related constants."""
+        ...
+
+
+# =============================================================================
+# Router Registry Protocol (Web Frameworks)
+# =============================================================================
+
+
+@dataclass
+class RouterInfo:
+    """Information about a router/controller definition."""
+
+    name: str  # Variable name
+    qualified_name: str
+    file_path: Path
+
+    router_type: str  # "app", "router", "controller", "blueprint"
+    prefix: str = ""
+    tags: list[str] = field(default_factory=list)
+
+
+@runtime_checkable
+class RouterRegistry(Protocol):
+    """
+    Protocol for tracking router definitions and hierarchies.
+
+    Web frameworks often have router nesting:
+    - FastAPI: app.include_router(router, prefix="/api")
+    - Express: app.use("/api", router)
+    - Spring: @RequestMapping("/api") on controller
+
+    This protocol abstracts the concept of router hierarchies.
+    """
+
+    def resolve_path(
+        self,
+        router_var: str,
+        route_path: str,
+        file_path: Path,
+    ) -> str:
+        """
+        Resolve full path including router prefixes.
+
+        Args:
+            router_var: The router variable name
+            route_path: The route's local path
+            file_path: Source file
+
+        Returns:
+            Full path with all prefixes applied
+        """
+        ...
+
+    def get_router(self, name: str, file_path: Path) -> RouterInfo | None:
+        """Get router info by variable name."""
+        ...
+
+    def get_all_routers(self) -> dict[str, RouterInfo]:
+        """Get all registered routers."""
+        ...
+
+    def get_router_dependencies(
+        self,
+        router_var: str,
+        file_path: Path,
+    ) -> list[str]:
+        """Return accumulated dependency function names for a router.
+
+        These are the dependency names declared via ``dependencies=[Depends(...)]``
+        on ``include_router()`` calls in the ancestry chain plus constructor-level
+        dependencies on the routers themselves.
+        """
+        ...
+
+
+# =============================================================================
+# Analysis Context
+# =============================================================================
+
+
+@dataclass
+class AnalysisContext:
+    """
+    Context object passed to framework plugins during analysis.
+
+    This replaces the multiple setter methods on plugins with a single,
+    immutable context object. All services are accessed through this.
+
+    DESIGN:
+    - Plugins receive context, don't store mutable state
+    - Services are language-specific implementations of protocols
+    - Framework plugins only depend on protocols, not implementations
+
+    Usage:
+        def extract_routes(self, file: ParsedFile, ctx: AnalysisContext):
+            # Resolve a model type
+            fields = ctx.type_resolver.get_model_fields("UserRequest", file.path)
+
+            # Resolve a computed path
+            path = ctx.path_resolver.resolve(f_string_expr, file.path)
+
+            # Get full path with router prefix
+            full_path = ctx.router_registry.resolve_path("router", "/users", file.path)
+    """
+
+    # Required services (always available)
+    type_resolver: TypeResolver
+
+    # Optional services (may be None depending on language/framework)
+    constant_resolver: ConstantResolver | None = None
+    path_resolver: PathResolver | None = None
+    router_registry: RouterRegistry | None = None
+
+    # Project info
+    project_root: Path | None = None
+    all_parsed_files: list[ParsedFile] = field(default_factory=list)
+
+    # Language-specific services (escape hatch for edge cases)
+    # Access via: ctx.language_services.get("some_python_thing")
+    language_services: dict[str, Any] = field(default_factory=dict)
+
+    def get_service(self, name: str) -> Any | None:
+        """Get a language-specific service by name."""
+        return self.language_services.get(name)
+
+
+# =============================================================================
+# Language Services Factory
+# =============================================================================
+
+
+class LanguageServices(ABC):
+    """
+    Abstract factory for language-specific analysis services.
+
+    Each language implements this to provide its own:
+    - Type resolver (import/inheritance resolution)
+    - Constant resolver (config/env var resolution)
+    - Path resolver (string interpolation)
+    - Any framework-specific services
+
+    DESIGN:
+    - One implementation per language (PythonLanguageServices, JavaLanguageServices)
+    - Built from parsed files during analysis
+    - Returns protocol implementations, not concrete classes
+    """
+
+    @abstractmethod
+    def build_type_resolver(
+        self,
+        parsed_files: list[ParsedFile],
+        project_root: Path | None = None,
+    ) -> TypeResolver:
+        """
+        Build the type resolver for this language.
+
+        Args:
+            parsed_files: All successfully parsed files
+            project_root: Project root directory
+
+        Returns:
+            TypeResolver implementation for this language
+        """
+        ...
+
+    @abstractmethod
+    def build_constant_resolver(
+        self,
+        parsed_files: list[ParsedFile],
+        project_root: Path | None = None,
+    ) -> ConstantResolver | None:
+        """
+        Build the constant resolver for this language.
+
+        Returns None if the language doesn't have meaningful constant resolution.
+        """
+        ...
+
+    @abstractmethod
+    def build_path_resolver(
+        self,
+        parsed_files: list[ParsedFile],
+        project_root: Path | None = None,
+    ) -> PathResolver | None:
+        """
+        Build the path resolver for this language.
+
+        Returns None if the language doesn't need path resolution.
+        """
+        ...
+
+    def build_framework_services(
+        self,
+        framework: str,
+        parsed_files: list[ParsedFile],
+        project_root: Path | None = None,
+    ) -> dict[str, Any]:
+        """
+        Build framework-specific services.
+
+        Override to provide framework-specific services like RouterRegistry.
+        Default returns empty dict.
+
+        Args:
+            framework: Framework name (e.g., "fastapi", "flask", "spring")
+            parsed_files: All parsed files
+            project_root: Project root
+
+        Returns:
+            Dict of service_name -> service_instance
+        """
+        return {}
+
+    def build_context(
+        self,
+        parsed_files: list[ParsedFile],
+        project_root: Path | None = None,
+        framework: str | None = None,
+    ) -> AnalysisContext:
+        """
+        Build complete analysis context for this language.
+
+        This is the main entry point. It builds all services and
+        packages them into an AnalysisContext.
+        """
+        type_resolver = self.build_type_resolver(parsed_files, project_root)
+        constant_resolver = self.build_constant_resolver(parsed_files, project_root)
+        path_resolver = self.build_path_resolver(parsed_files, project_root)
+
+        # Build framework-specific services
+        framework_services = {}
+        if framework:
+            framework_services = self.build_framework_services(
+                framework, parsed_files, project_root
+            )
+
+        # Wire up dependencies between services
+        if constant_resolver and path_resolver:
+            # Path resolver may need constant resolver
+            if hasattr(path_resolver, "set_constant_resolver"):
+                path_resolver.set_constant_resolver(constant_resolver)
+
+        router_registry = framework_services.get("router_registry")
+        if router_registry and constant_resolver:
+            if hasattr(router_registry, "set_constant_resolver"):
+                router_registry.set_constant_resolver(constant_resolver)
+
+        return AnalysisContext(
+            type_resolver=type_resolver,
+            constant_resolver=constant_resolver,
+            path_resolver=path_resolver,
+            router_registry=router_registry,
+            project_root=project_root,
+            all_parsed_files=parsed_files,
+            language_services=framework_services,
+        )

apisec_code_bolt/query/__init__.py

@@ -0,0 +1 @@
+"""Query API executor for extended analysis."""