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

apisec_code_bolt/parsing/python/parameter_analyzer.py

@@ -0,0 +1,789 @@
+"""
+Parameter analysis for Python function signatures.
+
+This module provides robust analysis of function parameters to determine:
+- Parameter location (path, query, body, header, cookie)
+- Type information and constraints
+- Default value semantics
+- Dependency injection patterns
+
+CRITICAL: This replaces fragile string-based detection with proper CST analysis.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+import libcst as cst
+
+if TYPE_CHECKING:
+    from ..base import ParsedParameter
+
+
+# =============================================================================
+# Parameter Analysis Results
+# =============================================================================
+
+
+@dataclass
+class AnalyzedParameter:
+    """
+    Result of analyzing a function parameter.
+
+    Contains semantic understanding of what the parameter represents
+    in the context of an HTTP handler.
+    """
+
+    name: str
+
+    # Determined location
+    location: (
+        str  # "path", "query", "body", "header", "cookie", "form", "file", "dependency", "unknown"
+    )
+    location_confidence: float  # 0.0 to 1.0
+
+    # Type information
+    type_annotation: str | None = None
+    base_type: str | None = None  # Unwrapped from Optional, Annotated, etc.
+    is_optional: bool = False
+    is_list: bool = False
+
+    # Default value analysis
+    has_default: bool = False
+    default_value: str | None = None
+    default_is_dependency: bool = False  # Depends(...)
+    default_is_marker: bool = False  # Query(...), Path(...), etc.
+
+    # Marker details (when default_is_marker=True)
+    marker_type: str | None = None  # "Query", "Path", "Body", etc.
+    marker_args: dict[str, Any] = field(default_factory=dict)
+
+    # Dependency details (when default_is_dependency=True)
+    dependency_function: str | None = None
+
+    # Validation constraints extracted from marker
+    constraints: dict[str, Any] = field(default_factory=dict)
+
+    # Analysis notes
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class RoutePathAnalysis:
+    """Analysis of a route path for parameter extraction."""
+
+    path: str
+    path_params: list[str] = field(default_factory=list)  # Names of {param} in path
+    has_path_params: bool = False
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+
+# FastAPI/Starlette parameter marker functions
+FASTAPI_MARKERS = {
+    "Path": "path",
+    "Query": "query",
+    "Header": "header",
+    "Cookie": "cookie",
+    "Body": "body",
+    "Form": "form",
+    "File": "body",  # Files are body content
+    "UploadFile": "body",
+}
+
+# Import aliases we should recognize
+FASTAPI_MARKER_MODULES = frozenset(
+    {
+        "fastapi",
+        "fastapi.param_functions",
+        "starlette",
+    }
+)
+
+# Dependency injection markers
+DEPENDENCY_MARKERS = frozenset({"Depends", "Security"})
+
+# Known model base classes (for body detection)
+BODY_MODEL_BASES = frozenset(
+    {
+        "BaseModel",
+        "BaseSettings",
+        "pydantic.BaseModel",
+        "pydantic.BaseSettings",
+    }
+)
+
+# Special parameters to skip
+SKIP_PARAMS = frozenset({"self", "cls", "request", "response", "websocket", "background_tasks"})
+
+
+# =============================================================================
+# Path Parameter Extractor
+# =============================================================================
+
+
+def extract_path_params(route_path: str) -> RoutePathAnalysis:
+    """
+    Extract path parameters from a route path.
+
+    Handles:
+    - Simple params: /users/{user_id}
+    - Typed params: /users/{user_id:int}
+    - Multiple params: /users/{user_id}/posts/{post_id}
+    - Path params: /files/{file_path:path}
+
+    Args:
+        route_path: The route path string (e.g., "/users/{user_id}")
+
+    Returns:
+        RoutePathAnalysis with extracted parameter names
+    """
+    # Pattern to match {param} or {param:type}
+    pattern = r"\{([^}:]+)(?::[^}]+)?\}"
+
+    matches = re.findall(pattern, route_path)
+
+    return RoutePathAnalysis(
+        path=route_path,
+        path_params=matches,
+        has_path_params=len(matches) > 0,
+    )
+
+
+# =============================================================================
+# Default Value Analyzer
+# =============================================================================
+
+
+class DefaultValueAnalyzer:
+    """
+    Analyzes default value expressions to determine parameter semantics.
+
+    This parses the default value AST to properly identify:
+    - Depends(func) patterns
+    - Query(...), Path(...), etc. markers
+    - Literal defaults
+    - Complex expressions
+    """
+
+    def __init__(self, import_aliases: dict[str, str] | None = None):
+        """
+        Initialize analyzer with import context.
+
+        Args:
+            import_aliases: Mapping of local names to their original imports.
+                           e.g., {"Q": "Query"} if `from fastapi import Query as Q`
+        """
+        self._aliases = import_aliases or {}
+
+    def analyze(self, default_value: str | None) -> dict[str, Any]:
+        """
+        Analyze a default value string.
+
+        Args:
+            default_value: The default value source code string
+
+        Returns:
+            Dict with analysis results:
+            - is_marker: bool
+            - marker_type: str | None
+            - marker_args: dict
+            - is_dependency: bool
+            - dependency_function: str | None
+            - is_literal: bool
+            - literal_value: Any
+        """
+        if not default_value:
+            return {"is_marker": False, "is_dependency": False, "is_literal": False}
+
+        default_value = default_value.strip()
+
+        # Try to parse as CST
+        try:
+            expr = cst.parse_expression(default_value)
+            return self._analyze_expression(expr)
+        except Exception:
+            # Fallback to pattern matching
+            return self._analyze_fallback(default_value)
+
+    def _analyze_expression(self, expr: cst.BaseExpression) -> dict[str, Any]:
+        """Analyze a parsed CST expression."""
+        result = {
+            "is_marker": False,
+            "marker_type": None,
+            "marker_args": {},
+            "is_dependency": False,
+            "dependency_function": None,
+            "is_literal": False,
+            "literal_value": None,
+        }
+
+        # Check if it's a function call
+        if isinstance(expr, cst.Call):
+            func_name = self._get_call_name(expr.func)
+
+            # Resolve alias
+            resolved_name = self._aliases.get(func_name, func_name)
+
+            # Check for dependency markers
+            if resolved_name in DEPENDENCY_MARKERS:
+                result["is_dependency"] = True
+                # Extract dependency function from first argument
+                if expr.args:
+                    first_arg = expr.args[0]
+                    result["dependency_function"] = self._expr_to_string(first_arg.value)
+
+            # Check for FastAPI parameter markers
+            elif resolved_name in FASTAPI_MARKERS:
+                result["is_marker"] = True
+                result["marker_type"] = resolved_name
+                result["marker_args"] = self._extract_call_kwargs(expr)
+
+            # Check for common aliases
+            elif func_name.split(".")[-1] in FASTAPI_MARKERS:
+                actual_name = func_name.split(".")[-1]
+                result["is_marker"] = True
+                result["marker_type"] = actual_name
+                result["marker_args"] = self._extract_call_kwargs(expr)
+
+        # Check for literals
+        elif isinstance(expr, (cst.Integer, cst.Float, cst.SimpleString)):
+            result["is_literal"] = True
+            result["literal_value"] = self._extract_literal_value(expr)
+
+        elif isinstance(expr, cst.Name):
+            if expr.value in {"None", "True", "False"}:
+                result["is_literal"] = True
+                result["literal_value"] = {"None": None, "True": True, "False": False}.get(
+                    expr.value
+                )
+
+        return result
+
+    def _get_call_name(self, func: cst.BaseExpression) -> str:
+        """Get the name of a called function."""
+        if isinstance(func, cst.Name):
+            return func.value
+        elif isinstance(func, cst.Attribute):
+            # Handle chained attributes like fastapi.Query
+            parts = []
+            current = func
+            while isinstance(current, cst.Attribute):
+                parts.append(current.attr.value)
+                current = current.value
+            if isinstance(current, cst.Name):
+                parts.append(current.value)
+            parts.reverse()
+            return ".".join(parts)
+        return ""
+
+    def _extract_call_kwargs(self, call: cst.Call) -> dict[str, Any]:
+        """Extract keyword arguments from a call."""
+        kwargs = {}
+
+        for i, arg in enumerate(call.args):
+            if arg.keyword:
+                key = arg.keyword.value
+                kwargs[key] = self._expr_to_string(arg.value)
+            elif i == 0 and isinstance(arg.value, (cst.SimpleString, cst.ConcatenatedString)):
+                # First positional arg might be description
+                kwargs["_positional_0"] = self._extract_string_value(arg.value)
+
+        return kwargs
+
+    def _expr_to_string(self, expr: cst.BaseExpression) -> str:
+        """Convert expression back to source string."""
+        try:
+            module = cst.parse_module("")
+            return module.code_for_node(expr)
+        except Exception:
+            return str(expr)
+
+    def _extract_literal_value(self, node: cst.BaseExpression) -> Any:
+        """Extract literal value from a node."""
+        if isinstance(node, cst.Integer):
+            return int(node.value)
+        elif isinstance(node, cst.Float):
+            return float(node.value)
+        elif isinstance(node, (cst.SimpleString, cst.ConcatenatedString)):
+            return self._extract_string_value(node)
+        return None
+
+    def _extract_string_value(self, node: cst.BaseExpression) -> str:
+        """Extract actual string value from string node."""
+        if isinstance(node, cst.SimpleString):
+            raw = node.value
+            # Remove quotes and prefixes
+            for prefix in ["r", "b", "f", "u", "fr", "rf", "br", "rb"]:
+                if raw.lower().startswith(prefix):
+                    raw = raw[len(prefix) :]
+                    break
+            if raw.startswith('"""') or raw.startswith("'''"):
+                return raw[3:-3]
+            elif raw.startswith('"') or raw.startswith("'"):
+                return raw[1:-1]
+        return str(node)
+
+    def _analyze_fallback(self, default_value: str) -> dict[str, Any]:
+        """Fallback analysis using pattern matching."""
+        result = {
+            "is_marker": False,
+            "marker_type": None,
+            "marker_args": {},
+            "is_dependency": False,
+            "dependency_function": None,
+            "is_literal": False,
+            "literal_value": None,
+        }
+
+        # Check for dependency markers (Depends / Security), including
+        # qualified callables like Depends(auth.get_current_user).
+        dep_match = re.match(r"^(?:Depends|Security)\s*\(\s*([\w.]+)\s*\)", default_value)
+        if dep_match:
+            result["is_dependency"] = True
+            result["dependency_function"] = dep_match.group(1)
+            return result
+
+        # Check for marker patterns
+        for marker in FASTAPI_MARKERS:
+            pattern = rf"^{marker}\s*\("
+            if re.match(pattern, default_value):
+                result["is_marker"] = True
+                result["marker_type"] = marker
+                return result
+
+        # Check for simple literals
+        if default_value in {"None", "True", "False"}:
+            result["is_literal"] = True
+            result["literal_value"] = {"None": None, "True": True, "False": False}.get(
+                default_value
+            )
+        elif default_value.startswith(('"', "'")) and default_value.endswith(('"', "'")):
+            result["is_literal"] = True
+            result["literal_value"] = default_value[1:-1]
+        elif default_value.isdigit():
+            result["is_literal"] = True
+            result["literal_value"] = int(default_value)
+
+        return result
+
+
+# =============================================================================
+# Type Annotation Analyzer
+# =============================================================================
+
+
+class TypeAnnotationAnalyzer:
+    """
+    Analyzes type annotations to extract semantic information.
+
+    Handles:
+    - Optional[X] -> X with is_optional=True
+    - Annotated[X, ...] -> X with markers extracted
+    - list[X] -> X with is_list=True
+    - Union[X, None] -> X with is_optional=True
+    - Type aliases (e.g. SessionDep = Annotated[Session, Depends(get_db)])
+    """
+
+    def __init__(
+        self,
+        known_models: set[str] | None = None,
+        type_aliases: dict[str, str] | None = None,
+    ):
+        """
+        Initialize with known model names and type alias mappings.
+
+        Args:
+            known_models: Set of known Pydantic model names
+            type_aliases: Mapping of alias name to its expanded RHS text,
+                e.g. ``{"SessionDep": "Annotated[Session, Depends(get_db)]"}``
+        """
+        self._known_models = known_models or set()
+        self._type_aliases = type_aliases or {}
+
+    def add_known_model(self, name: str) -> None:
+        """Register a known model name."""
+        self._known_models.add(name)
+
+    def _expand_aliases(self, annotation: str) -> str:
+        """Expand known type aliases in *annotation* (single-hop)."""
+        stripped = annotation.strip()
+        if stripped in self._type_aliases:
+            return self._type_aliases[stripped]
+        for wrapper in ("Optional[", "Union["):
+            if stripped.startswith(wrapper) and stripped.endswith("]"):
+                inner = stripped[len(wrapper) : -1].strip()
+                parts = self._split_type_args(inner)
+                changed = False
+                new_parts = []
+                for p in parts:
+                    p_stripped = p.strip()
+                    if p_stripped in self._type_aliases:
+                        new_parts.append(self._type_aliases[p_stripped])
+                        changed = True
+                    else:
+                        new_parts.append(p)
+                if changed:
+                    return f"{wrapper}{', '.join(new_parts)}]"
+        return annotation
+
+    def analyze(self, annotation: str | None) -> dict[str, Any]:
+        """
+        Analyze a type annotation string.
+
+        Returns:
+            Dict with:
+            - base_type: str | None - The innermost type
+            - is_optional: bool
+            - is_list: bool
+            - is_model: bool - Whether base_type is a known Pydantic model
+            - annotated_markers: list - Markers from Annotated[X, marker1, marker2]
+        """
+        if not annotation:
+            return {
+                "base_type": None,
+                "is_optional": False,
+                "is_list": False,
+                "is_model": False,
+                "annotated_markers": [],
+            }
+
+        annotation = self._expand_aliases(annotation.strip())
+
+        # Track properties as we unwrap
+        is_optional = False
+        is_list = False
+        annotated_markers = []
+
+        # Unwrap layers
+        unwrapped = annotation
+
+        # Handle Optional[X] or X | None
+        if unwrapped.startswith("Optional[") and unwrapped.endswith("]"):
+            is_optional = True
+            unwrapped = unwrapped[9:-1].strip()
+        elif " | None" in unwrapped:
+            is_optional = True
+            unwrapped = unwrapped.replace(" | None", "").replace("None | ", "").strip()
+        elif unwrapped.startswith("Union[") and ", None]" in unwrapped:
+            is_optional = True
+            # Extract non-None type from Union
+            inner = unwrapped[6:-1]
+            types = self._split_type_args(inner)
+            non_none = [t for t in types if t.strip() != "None"]
+            if len(non_none) == 1:
+                unwrapped = non_none[0].strip()
+
+        # Handle Annotated[X, ...]
+        if unwrapped.startswith("Annotated[") and unwrapped.endswith("]"):
+            inner = unwrapped[10:-1]
+            parts = self._split_type_args(inner)
+            if parts:
+                unwrapped = parts[0].strip()
+                annotated_markers = [p.strip() for p in parts[1:]]
+
+        # Handle list[X], List[X], Sequence[X]
+        list_prefixes = ["list[", "List[", "Sequence[", "typing.List["]
+        for prefix in list_prefixes:
+            if unwrapped.startswith(prefix) and unwrapped.endswith("]"):
+                is_list = True
+                unwrapped = unwrapped[len(prefix) : -1].strip()
+                break
+
+        # Check if it's a known model
+        is_model = unwrapped in self._known_models
+
+        return {
+            "base_type": unwrapped,
+            "is_optional": is_optional,
+            "is_list": is_list,
+            "is_model": is_model,
+            "annotated_markers": annotated_markers,
+        }
+
+    def _split_type_args(self, args_str: str) -> list[str]:
+        """Split type arguments respecting nested brackets."""
+        result = []
+        current = []
+        depth = 0
+
+        for char in args_str:
+            if char == "[":
+                depth += 1
+                current.append(char)
+            elif char == "]":
+                depth -= 1
+                current.append(char)
+            elif char == "," and depth == 0:
+                result.append("".join(current))
+                current = []
+            else:
+                current.append(char)
+
+        if current:
+            result.append("".join(current))
+
+        return [r.strip() for r in result if r.strip()]
+
+
+# =============================================================================
+# Parameter Analyzer
+# =============================================================================
+
+
+class ParameterAnalyzer:
+    """
+    Comprehensive parameter analyzer for HTTP handler functions.
+
+    Combines:
+    - Path parameter extraction from route
+    - Type annotation analysis
+    - Default value analysis
+    - Known model detection
+    - Import alias resolution
+
+    This is the main entry point for parameter analysis.
+    """
+
+    def __init__(
+        self,
+        import_aliases: dict[str, str] | None = None,
+        known_models: set[str] | None = None,
+        type_aliases: dict[str, str] | None = None,
+    ):
+        """
+        Initialize the analyzer.
+
+        Args:
+            import_aliases: Mapping of local import names to original names
+            known_models: Set of known Pydantic model names
+            type_aliases: Mapping of type alias names to their expanded RHS text
+        """
+        self._import_aliases = import_aliases or {}
+        self._known_models = known_models or set()
+        self._type_aliases = type_aliases or {}
+
+        self._default_analyzer = DefaultValueAnalyzer(self._import_aliases)
+        self._type_analyzer = TypeAnnotationAnalyzer(self._known_models, self._type_aliases)
+
+    def add_import_alias(self, local_name: str, original_name: str) -> None:
+        """Add an import alias mapping."""
+        self._import_aliases[local_name] = original_name
+        self._default_analyzer = DefaultValueAnalyzer(self._import_aliases)
+
+    def add_known_model(self, name: str) -> None:
+        """Register a known Pydantic model."""
+        self._known_models.add(name)
+        self._type_analyzer.add_known_model(name)
+
+    def analyze_function_params(
+        self,
+        params: list[ParsedParameter],
+        route_path: str | None = None,
+    ) -> list[AnalyzedParameter]:
+        """
+        Analyze all parameters of a function.
+
+        Args:
+            params: List of ParsedParameter from the function
+            route_path: Optional route path for path parameter detection
+
+        Returns:
+            List of AnalyzedParameter with full semantic analysis
+        """
+        # Extract path parameters from route
+        path_params: set[str] = set()
+        if route_path:
+            path_analysis = extract_path_params(route_path)
+            path_params = set(path_analysis.path_params)
+
+        results = []
+
+        for param in params:
+            # Skip special parameters
+            if param.name in SKIP_PARAMS:
+                continue
+
+            analyzed = self._analyze_single_param(param, path_params)
+            results.append(analyzed)
+
+        return results
+
+    def _analyze_single_param(
+        self,
+        param: ParsedParameter,
+        path_params: set[str],
+    ) -> AnalyzedParameter:
+        """Analyze a single parameter."""
+        # Start with analysis results
+        result = AnalyzedParameter(
+            name=param.name,
+            location="unknown",
+            location_confidence=0.0,
+            type_annotation=param.type_annotation,
+            has_default=param.default_value is not None,
+            default_value=param.default_value,
+        )
+
+        # Analyze type annotation
+        type_info = self._type_analyzer.analyze(param.type_annotation)
+        result.base_type = type_info["base_type"]
+        result.is_optional = type_info["is_optional"]
+        result.is_list = type_info["is_list"]
+
+        # Check for Annotated markers (e.g. Annotated[Session, Depends(get_db)])
+        annotated_markers = type_info.get("annotated_markers", [])
+        for marker in annotated_markers:
+            marker_info = self._default_analyzer.analyze(marker)
+            if marker_info.get("is_dependency"):
+                result.default_is_dependency = True
+                result.dependency_function = marker_info.get("dependency_function")
+                result.location = "dependency"
+                result.location_confidence = 1.0
+                return result
+            if marker_info.get("is_marker"):
+                result.default_is_marker = True
+                result.marker_type = marker_info.get("marker_type")
+                result.marker_args = marker_info.get("marker_args", {})
+                break
+
+        # Analyze default value
+        default_info = self._default_analyzer.analyze(param.default_value)
+
+        if default_info["is_dependency"]:
+            result.default_is_dependency = True
+            result.dependency_function = default_info.get("dependency_function")
+            result.location = "dependency"
+            result.location_confidence = 1.0
+            return result
+
+        if default_info["is_marker"]:
+            result.default_is_marker = True
+            result.marker_type = default_info.get("marker_type")
+            result.marker_args = default_info.get("marker_args", {})
+
+            # Extract constraints from marker args
+            for key in ["min_length", "max_length", "gt", "ge", "lt", "le", "regex", "pattern"]:
+                if key in result.marker_args:
+                    result.constraints[key] = result.marker_args[key]
+
+        # Determine location with precedence rules
+        location, confidence = self._determine_location(
+            param_name=param.name,
+            path_params=path_params,
+            marker_type=result.marker_type,
+            base_type=result.base_type,
+            is_model=type_info["is_model"],
+            has_default=result.has_default,
+            default_value=param.default_value,
+        )
+
+        result.location = location
+        result.location_confidence = confidence
+
+        return result
+
+    def _determine_location(
+        self,
+        param_name: str,
+        path_params: set[str],
+        marker_type: str | None,
+        base_type: str | None,
+        is_model: bool,
+        has_default: bool,
+        default_value: str | None,
+    ) -> tuple[str, float]:
+        """
+        Determine parameter location with confidence score.
+
+        Precedence (highest to lowest):
+        1. Explicit marker (Query, Path, Header, etc.) - 1.0
+        2. Path parameter match from route - 1.0
+        3. Pydantic model type - 0.95
+        4. Type-based inference - 0.7
+        5. Name-based inference - 0.5
+        6. Default: query - 0.3
+
+        Returns:
+            Tuple of (location, confidence)
+        """
+        # 1. Explicit marker takes highest precedence
+        if marker_type:
+            location = FASTAPI_MARKERS.get(marker_type, "query")
+            return (location, 1.0)
+
+        # 2. Path parameter from route
+        if param_name in path_params:
+            return ("path", 1.0)
+
+        # 3. Pydantic model = body
+        if is_model:
+            return ("body", 0.95)
+
+        # Check base type for special cases
+        if base_type:
+            base_lower = base_type.lower()
+
+            # 4. Type-based inference
+            if base_type in {"UploadFile", "bytes"} or "uploadfile" in base_lower:
+                return ("body", 0.9)
+
+            # Common body type names
+            if any(
+                pattern in base_lower
+                for pattern in ["request", "payload", "input", "create", "update"]
+            ):
+                if base_type[0].isupper():  # Looks like a class name
+                    return ("body", 0.8)
+
+        # 5. Name-based inference (lower confidence)
+        name_lower = param_name.lower()
+
+        # Header patterns
+        if any(
+            pattern in name_lower for pattern in ["header", "x_", "authorization", "content_type"]
+        ):
+            return ("header", 0.6)
+
+        # Cookie patterns
+        if any(pattern in name_lower for pattern in ["cookie", "session_id", "csrf"]):
+            return ("cookie", 0.6)
+
+        # 6. Default: query parameters
+        # But with even lower confidence if no type annotation
+        if base_type:
+            return ("query", 0.5)
+        else:
+            return ("query", 0.3)
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+
+def analyze_route_parameters(
+    params: list[ParsedParameter],
+    route_path: str,
+    import_aliases: dict[str, str] | None = None,
+    known_models: set[str] | None = None,
+) -> list[AnalyzedParameter]:
+    """
+    Convenience function to analyze route handler parameters.
+
+    Args:
+        params: Function parameters
+        route_path: The route path (e.g., "/users/{user_id}")
+        import_aliases: Import alias mappings
+        known_models: Known Pydantic model names
+
+    Returns:
+        List of analyzed parameters
+    """
+    analyzer = ParameterAnalyzer(import_aliases, known_models)
+    return analyzer.analyze_function_params(params, route_path)