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

apisec_code_bolt/parsing/base.py

@@ -0,0 +1,554 @@
+"""
+Base classes and protocols for language-specific parsers.
+
+Each language (Python, Java, etc.) implements the Parser protocol
+to provide parsing capabilities. This module defines the contract
+that all parsers must fulfill.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from ..core.types import (
+    AnalysisNote,
+    CodeLocation,
+    Confidence,
+    Language,
+    ParseError,
+    QualifiedName,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+
+# =============================================================================
+# Parsed Symbol Types
+# =============================================================================
+
+
+@dataclass
+class ParsedSymbol:
+    """
+    Base class for all parsed symbols (functions, classes, variables).
+
+    Symbols are the named entities we extract from source code.
+    """
+
+    name: str
+    qualified_name: QualifiedName
+    location: CodeLocation
+
+    # Documentation
+    docstring: str | None = None
+
+    # Analysis metadata
+    confidence: Confidence = Confidence.HIGH
+
+    @property
+    def file_path(self) -> Path | None:
+        """File path where this symbol is defined (from location)."""
+        return self.location.file if self.location else None
+
+    notes: list[AnalysisNote] = field(default_factory=list)
+
+
+@dataclass
+class ParsedParameter:
+    """A function/method parameter."""
+
+    name: str
+    type_annotation: str | None = None
+    default_value: str | None = None
+    is_variadic: bool = False  # *args
+    is_keyword_variadic: bool = False  # **kwargs
+
+    # Location of parameter in source
+    location: CodeLocation | None = None
+
+    # Additional metadata (framework-specific annotations, etc.)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ParsedDecorator:
+    """A decorator/annotation on a function or class."""
+
+    name: str
+    qualified_name: QualifiedName | None = None
+    arguments: dict[str, Any] = field(default_factory=dict)
+    positional_args: list[Any] = field(default_factory=list)
+    location: CodeLocation | None = None
+
+    # Raw argument string for complex cases
+    raw_arguments: str | None = None
+
+
+@dataclass
+class ParsedFunction(ParsedSymbol):
+    """
+    A parsed function or method definition.
+
+    This captures all information about a function that we need
+    for analysis: parameters, return type, decorators, body info.
+    """
+
+    # Function signature
+    parameters: list[ParsedParameter] = field(default_factory=list)
+    return_type: str | None = None
+
+    # Decorators/annotations
+    decorators: list[ParsedDecorator] = field(default_factory=list)
+
+    # Function properties
+    is_async: bool = False
+    binding: str = "free"  # "instance", "static", or "free"
+    is_abstract: bool = False
+
+    # For methods
+    owner_type: str | None = None
+    class_qualified_name: QualifiedName | None = None
+
+    # Body analysis
+    body_line_count: int = 0
+    body_source: str | None = None
+    has_yield: bool = False  # Generator
+    has_return: bool = False
+
+    # Internal variables (for data flow)
+    local_variables: list[str] = field(default_factory=list)
+
+    # Control flow information for flow-sensitive analysis
+    control_flow_info: dict[str, Any] = field(default_factory=dict)
+
+    # Return statement analysis
+    return_statements: list[ParsedReturn] = field(default_factory=list)
+
+
+@dataclass
+class ParsedReturn:
+    """A return (or yield) statement analysis."""
+
+    line: int
+
+    # What is being returned
+    returns_none: bool = False
+    returns_call: bool = False
+    returns_variable: bool = False
+    returns_literal: bool = False
+    returns_expression: bool = False
+    returns_lambda: bool = False
+    returns_comprehension: bool = False
+
+    # Details
+    call_name: str | None = None
+    variable_name: str | None = None
+    literal_type: str | None = None
+    expression_text: str | None = None
+
+
+@dataclass
+class ParsedField:
+    """A class field (for Pydantic models, dataclasses, etc.)."""
+
+    name: str
+    type_annotation: str | None = None
+    # "public", "protected", "private", "internal", "protected internal", etc.
+    access_modifier: str = "public"
+    default_value: str | None = None
+
+    # Field() metadata
+    field_info: dict[str, Any] = field(default_factory=dict)
+
+    # For Pydantic
+    is_required: bool = True
+    alias: str | None = None
+    description: str | None = None
+
+    # Validation constraints
+    constraints: dict[str, Any] = field(default_factory=dict)
+
+    # Nested type reference
+    nested_model_name: str | None = None
+
+    location: CodeLocation | None = None
+
+    # Annotations / decorators on this field (e.g. @Value, @NotNull, @Column)
+    decorators: list[ParsedDecorator] = field(default_factory=list)
+
+
+@dataclass
+class ParsedClass(ParsedSymbol):
+    """A parsed class definition."""
+
+    # Inheritance
+    base_classes: list[str] = field(default_factory=list)
+    base_class_qualified_names: list[QualifiedName] = field(default_factory=list)
+
+    # Decorators/annotations
+    decorators: list[ParsedDecorator] = field(default_factory=list)
+
+    # Class properties
+    is_abstract: bool = False
+    is_dataclass: bool = False
+    is_enum: bool = False
+    is_pydantic_model: bool = False  # NEW: Track Pydantic models explicitly
+
+    # Fields (for Pydantic models and dataclasses)
+    fields: list[ParsedField] = field(default_factory=list)  # NEW: Preserve field info
+
+    # Members
+    methods: list[ParsedFunction] = field(default_factory=list)
+    class_variables: list[str] = field(default_factory=list)
+    instance_variables: list[str] = field(default_factory=list)
+
+    # Nested classes
+    nested_classes: list[ParsedClass] = field(default_factory=list)
+
+    @property
+    def bases(self) -> list[str]:
+        """Alias for base_classes (used by language_services/type_resolver)."""
+        return self.base_classes
+
+
+@dataclass
+class ParsedImport:
+    """An import statement."""
+
+    module: str
+    names: list[str] = field(default_factory=list)  # Empty for "import module"
+    alias: str | None = None
+    is_relative: bool = False
+    relative_level: int = 0  # Number of dots in relative import
+
+    location: CodeLocation | None = None
+
+    @property
+    def is_from_import(self) -> bool:
+        """Check if this is a 'from x import y' style import."""
+        return len(self.names) > 0
+
+
+@dataclass
+class ParsedCallSite:
+    """
+    A function/method call site.
+
+    This captures where functions are called and with what arguments.
+    """
+
+    # What is being called
+    callee_name: str
+
+    # Where the call is
+    location: CodeLocation
+
+    # Optional fields with defaults
+    callee_qualified_name: QualifiedName | None = None
+    callee_resolved: bool = False
+    caller_function: QualifiedName | None = None
+
+    # Arguments
+    arguments: list[ParsedArgument] = field(default_factory=list)
+
+    # Call context
+    is_method_call: bool = False
+    receiver_expression: str | None = None  # The object before the dot
+    receiver_type: str | None = None
+
+    # Control flow context
+    in_loop: bool = False
+    in_conditional: bool = False
+    in_try: bool = False
+    in_except: bool = False
+    in_finally: bool = False
+    in_with: bool = False
+    in_comprehension: bool = False
+    loop_depth: int = 0
+    conditional_depth: int = 0
+
+    # If we couldn't resolve, possible targets
+    possible_callees: list[QualifiedName] = field(default_factory=list)
+
+
+@dataclass
+class ParsedArgument:
+    """An argument in a function call."""
+
+    position: int | None = None
+    name: str | None = None  # For keyword arguments
+
+    # Value information
+    is_literal: bool = False
+    literal_value: Any = None
+    literal_type: str | None = None  # "str", "int", "float", "bool", "None"
+
+    is_variable: bool = False
+    variable_name: str | None = None
+
+    is_expression: bool = False
+    expression_text: str | None = None
+
+    # For complex expressions
+    is_call_result: bool = False
+    called_function: str | None = None
+
+    # Spread arguments (Python *args, JS spread, Java varargs)
+    is_spread: bool = False
+    # Keyword spread (Python **kwargs, JS object spread)
+    is_keyword_spread: bool = False
+
+    # Argument construction evidence (language-agnostic).
+    # Python f-strings, JS template literals, Kotlin string templates, C# interpolated strings.
+    is_string_interpolation: bool = False
+    # String concatenation with + operator (all languages)
+    is_concatenation: bool = False
+    # .format(), String.format(), fmt.Sprintf(), etc.
+    is_format_call: bool = False
+    container_type: str | None = None  # "list", "tuple", "dict", "set", "array", "map"
+    source_variables: list[str] = field(default_factory=list)
+
+    # Attribute names applied directly to a lambda argument (e.g. [Authorize], [AllowAnonymous])
+    lambda_attribute_names: list[str] = field(default_factory=list)
+
+    # Lambda / anonymous function argument (C# Minimal API, Java lambdas, etc.)
+    # Each tuple is (type_annotation, parameter_name).  Only populated when the
+    # argument is a typed lambda expression, not a bare variable reference.
+    lambda_parameter_types: list[tuple[str, str]] = field(default_factory=list)
+
+
+@dataclass
+class ParsedAssignment:
+    """A variable assignment."""
+
+    target: str  # Variable name
+    location: CodeLocation
+
+    # Source information
+    source_type: str  # "literal", "variable", "call", "expression", "parameter"
+
+    # Optional fields
+    target_qualified_name: QualifiedName | None = None
+    source_value: str | None = None
+    source_call: str | None = None  # If assigned from function call
+
+    # Enclosing function (for scoping: None = module level)
+    in_function: str | None = None
+
+    # Type information
+    type_annotation: str | None = None
+    inferred_type: str | None = None
+
+    # Variables in the RHS expression that the target value derives from.
+    # Language-agnostic: set by each language parser during extraction.
+    # Examples: "x = int(y)" → ["y"], "q = f'{a} {b}'" → ["a", "b"].
+    source_variables: list[str] = field(default_factory=list)
+
+    # True when the value is a method call on a variable (y = x.strip())
+    is_method_call: bool = False
+
+    # True when the value is a string interpolation (f-string, template literal, etc.)
+    is_string_interpolation: bool = False
+
+    @property
+    def value_source(self) -> str | None:
+        """Alias for source_value (used by constant/path resolvers)."""
+        return self.source_value
+
+    @property
+    def is_literal(self) -> bool:
+        """Whether the assignment source is a literal."""
+        return self.source_type == "literal"
+
+    @property
+    def is_call(self) -> bool:
+        """Whether the assignment source is a function call."""
+        return self.source_type == "call"
+
+    @property
+    def is_name(self) -> bool:
+        """Whether the assignment source is a variable reference."""
+        return self.source_type == "variable"
+
+
+# =============================================================================
+# Parsed File
+# =============================================================================
+
+
+@dataclass
+class ParsedFile:
+    """
+    Result of parsing a single source file.
+
+    Contains all extracted information from the file.
+    """
+
+    path: Path
+    language: Language
+
+    # Parse success
+    success: bool = True
+    error: ParseError | None = None
+
+    # Module info
+    module_name: str | None = None  # Inferred module name
+    module_docstring: str | None = None
+
+    # Imports
+    imports: list[ParsedImport] = field(default_factory=list)
+
+    # Definitions
+    functions: list[ParsedFunction] = field(default_factory=list)
+    classes: list[ParsedClass] = field(default_factory=list)
+
+    # All symbols (including nested)
+    all_symbols: dict[str, ParsedSymbol] = field(default_factory=dict)
+
+    # Call sites
+    call_sites: list[ParsedCallSite] = field(default_factory=list)
+
+    # Assignments (for data flow)
+    assignments: list[ParsedAssignment] = field(default_factory=list)
+
+    # Module-level variables
+    module_variables: list[str] = field(default_factory=list)
+
+    # Analysis metadata
+    line_count: int = 0
+    parse_time_ms: int = 0
+    notes: list[AnalysisNote] = field(default_factory=list)
+
+
+# =============================================================================
+# Abstract Parser Base
+# =============================================================================
+
+
+class BaseParser(ABC):
+    """
+    Abstract base class for language-specific parsers.
+
+    Implementations must override all abstract methods.
+    This provides a common interface for all parsers while
+    allowing language-specific implementation details.
+    """
+
+    # Class-level constants to be overridden
+    LANGUAGE: ClassVar[Language]
+    SUPPORTED_EXTENSIONS: ClassVar[frozenset[str]]
+
+    @property
+    def language(self) -> Language:
+        """The language this parser handles."""
+        return self.LANGUAGE
+
+    @property
+    def supported_extensions(self) -> frozenset[str]:
+        """File extensions this parser handles."""
+        return self.SUPPORTED_EXTENSIONS
+
+    def can_parse(self, file_path: Path) -> bool:
+        """Check if this parser can handle the given file."""
+        return file_path.suffix.lower() in self.supported_extensions
+
+    @abstractmethod
+    def parse_file(self, file_path: Path) -> ParsedFile:
+        """
+        Parse a single file and return structured data.
+
+        Args:
+            file_path: Path to the source file
+
+        Returns:
+            ParsedFile containing all extracted information
+
+        Raises:
+            ParseError: If the file cannot be parsed
+        """
+        ...
+
+    def parse_files(self, file_paths: Sequence[Path]) -> Iterator[ParsedFile]:
+        """
+        Parse multiple files, yielding results.
+
+        Default implementation parses sequentially.
+        Subclasses may override for parallel parsing.
+
+        Args:
+            file_paths: Paths to source files
+
+        Yields:
+            ParsedFile for each successfully parsed file
+        """
+        for path in file_paths:
+            if self.can_parse(path):
+                yield self.parse_file(path)
+
+    @abstractmethod
+    def parse_source(self, source: str, file_path: Path | None = None) -> ParsedFile:
+        """
+        Parse source code string directly.
+
+        Useful for testing and for parsing code fragments.
+
+        Args:
+            source: Source code string
+            file_path: Optional path for location info
+
+        Returns:
+            ParsedFile containing all extracted information
+        """
+        ...
+
+
+# =============================================================================
+# Parser Registry
+# =============================================================================
+
+
+class ParserRegistry:
+    """
+    Registry of available parsers.
+
+    Parsers register themselves and the registry provides
+    lookup by language or file extension.
+    """
+
+    _parsers: dict[Language, BaseParser] = {}
+    _extension_map: dict[str, Language] = {}
+
+    @classmethod
+    def register(cls, parser: BaseParser) -> None:
+        """Register a parser."""
+        cls._parsers[parser.language] = parser
+        for ext in parser.supported_extensions:
+            cls._extension_map[ext] = parser.language
+
+    @classmethod
+    def get_parser(cls, language: Language) -> BaseParser | None:
+        """Get parser for a language."""
+        return cls._parsers.get(language)
+
+    @classmethod
+    def get_parser_for_file(cls, file_path: Path) -> BaseParser | None:
+        """Get parser for a file based on extension."""
+        ext = file_path.suffix.lower()
+        language = cls._extension_map.get(ext)
+        if language:
+            return cls._parsers.get(language)
+        return None
+
+    @classmethod
+    def supported_languages(cls) -> frozenset[Language]:
+        """Get set of supported languages."""
+        return frozenset(cls._parsers.keys())
+
+    @classmethod
+    def supported_extensions(cls) -> frozenset[str]:
+        """Get set of supported file extensions."""
+        return frozenset(cls._extension_map.keys())

apisec_code_bolt/parsing/csharp/__init__.py

@@ -0,0 +1,5 @@
+"""C# parser package — auto-registers CSharpParser with ParserRegistry on import."""
+
+from .parser import CSharpParser
+
+__all__ = ["CSharpParser"]