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

apisec_code_bolt/parsing/python/dynamic_route_detector.py

@@ -0,0 +1,532 @@
+"""
+Dynamic route detection for FastAPI/Starlette applications.
+
+This module handles routes that are registered programmatically rather than
+via decorators:
+
+1. Direct registration: app.add_api_route("/path", handler, methods=["GET"])
+2. Factory functions: create_crud_routes(model=User) returning routes
+3. Loop-based registration: for r in routes: app.add_api_route(...)
+4. Route tables: routes = [Route("/path", handler, methods=["GET"])]
+
+CRITICAL: Enterprise applications often use these patterns for:
+- CRUD generation (SQLAlchemy-Admin, FastAPI-CRUD)
+- Dynamic plugin systems
+- Multi-tenant routing
+- Generic REST resource creation
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..base import ParsedFile, ParsedFunction
+
+
+# =============================================================================
+# Data Types
+# =============================================================================
+
+
+@dataclass
+class DynamicRoute:
+    """A route registered dynamically (not via decorator)."""
+
+    # Route info (may be partially resolved)
+    path: str
+    methods: list[str]  # ["GET"], ["GET", "POST"], etc.
+
+    # Handler info
+    handler_name: str  # Function name or reference
+
+    # Registration details
+    registration_type: str  # "add_api_route", "add_route", "route_table", "factory"
+
+    # Optional fields with defaults
+    handler_qualified: str | None = None
+    file_path: Path | None = None
+    line: int = 0
+
+    # Resolution status
+    is_fully_resolved: bool = False
+    confidence: float = 0.5
+
+    # For factory-generated routes
+    factory_function: str | None = None
+    factory_arguments: dict[str, Any] = field(default_factory=dict)
+
+    # Notes about detection
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class RouteFactory:
+    """A function that generates routes."""
+
+    name: str
+    qualified_name: str
+    file_path: Path
+    line: int
+
+    # What kind of factory?
+    factory_type: str  # "crud", "resource", "generic", "unknown"
+
+    # Parameters that affect route generation
+    model_param: str | None = None  # Parameter name for model class
+    prefix_param: str | None = None  # Parameter name for path prefix
+
+    # Detected route patterns
+    generated_routes: list[DynamicRoute] = field(default_factory=list)
+
+    # Confidence in detection
+    confidence: float = 0.5
+
+
+@dataclass
+class LoopRouteRegistration:
+    """Route registration happening in a loop."""
+
+    # Loop info
+    file_path: Path
+    line: int
+
+    # What's being iterated
+    iterable_name: str  # e.g., "routes", "endpoints"
+
+    # Registration call info
+    registration_call: str  # e.g., "app.add_api_route"
+
+    # Optional fields with defaults
+    iterable_source: str | None = None  # Where the iterable comes from
+
+    # Detected static routes from the iterable
+    detected_routes: list[DynamicRoute] = field(default_factory=list)
+
+    # Notes
+    notes: list[str] = field(default_factory=list)
+
+
+# =============================================================================
+# Dynamic Route Detector
+# =============================================================================
+
+
+class DynamicRouteDetector:
+    """
+    Detects dynamically registered routes in FastAPI/Starlette applications.
+
+    This handles cases where routes are not registered via decorators but
+    through programmatic calls like:
+
+    - app.add_api_route("/users", list_users, methods=["GET"])
+    - routes = [Route("/users", endpoint=list_users)]
+    - for route in crud_routes: app.add_api_route(...)
+
+    Usage:
+        detector = DynamicRouteDetector()
+
+        # Process files
+        for parsed in parsed_files:
+            detector.process_file(parsed)
+
+        # Get detected routes
+        routes = detector.get_all_routes()
+    """
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize the detector."""
+        self._project_root = project_root
+        self._dynamic_routes: list[DynamicRoute] = []
+        self._factories: dict[str, RouteFactory] = {}
+        self._loop_registrations: list[LoopRouteRegistration] = []
+        self._route_tables: dict[Path, dict[str, list[DynamicRoute]]] = {}
+        self._app_vars: dict[Path, set[str]] = {}
+
+    def process_file(self, parsed: ParsedFile) -> None:
+        """Process a parsed file to detect dynamic routes."""
+        if not parsed.success:
+            return
+
+        file_path = parsed.path
+        self._app_vars[file_path] = set()
+        self._route_tables[file_path] = {}
+
+        # Step 1: Identify app/router variables
+        self._identify_app_routers(parsed)
+
+        # Step 2: Find add_api_route / add_route calls
+        self._detect_add_route_calls(parsed)
+
+        # Step 3: Find route table definitions
+        self._detect_route_tables(parsed)
+
+        # Step 4: Find factory functions
+        self._detect_factory_functions(parsed)
+
+        # Step 5: Find loop-based registrations
+        self._detect_loop_registrations(parsed)
+
+    def _identify_app_routers(self, parsed: ParsedFile) -> None:
+        """Identify FastAPI/Router variables."""
+        file_path = parsed.path
+
+        for assign in parsed.assignments:
+            if assign.source_type == "call":
+                called = assign.source_call or ""
+                if any(x in called for x in ["FastAPI", "APIRouter", "Starlette", "Router"]):
+                    self._app_vars[file_path].add(assign.target)
+
+    def _detect_add_route_calls(self, parsed: ParsedFile) -> None:
+        """Detect add_api_route and add_route calls."""
+        file_path = parsed.path
+        app_vars = self._app_vars.get(file_path, set())
+
+        for call in parsed.call_sites:
+            callee = call.callee_name
+
+            # Check for add_api_route or add_route
+            is_add_route = False
+            if callee.endswith("add_api_route") or callee.endswith("add_route"):
+                # Verify it's on an app/router variable
+                parts = callee.rsplit(".", 1)
+                if len(parts) >= 2:
+                    var_name = parts[0].split(".")[-1]  # Handle chained attrs
+                    if var_name in app_vars or var_name in {"app", "router", "api"}:
+                        is_add_route = True
+
+            if not is_add_route:
+                continue
+
+            # Extract route info from call arguments
+            route = self._extract_route_from_add_call(call, file_path)
+            if route:
+                self._dynamic_routes.append(route)
+
+    def _extract_route_from_add_call(self, call, file_path: Path) -> DynamicRoute | None:
+        """Extract route info from add_api_route call."""
+        path = ""
+        handler = ""
+        methods: list[str] = []
+
+        for arg in call.arguments:
+            # Path is typically first positional arg
+            if arg.position == 0 or arg.name == "path":
+                path = self._extract_arg_value(arg)
+
+            # Handler is second positional or 'endpoint'
+            elif arg.position == 1 or arg.name == "endpoint":
+                handler = arg.variable_name or self._extract_arg_value(arg)
+
+            # Methods
+            elif arg.name == "methods":
+                methods = self._extract_methods(arg)
+
+        if not path:
+            return None
+
+        # Default method is GET
+        if not methods:
+            methods = ["GET"]
+
+        return DynamicRoute(
+            path=path,
+            methods=methods,
+            handler_name=handler,
+            registration_type="add_api_route",
+            file_path=file_path,
+            line=call.location.line,
+            is_fully_resolved=not self._has_variable_ref(path),
+            confidence=0.9 if not self._has_variable_ref(path) else 0.6,
+        )
+
+    def _detect_route_tables(self, parsed: ParsedFile) -> None:
+        """Detect route table assignments like routes = [Route(...), ...]."""
+        file_path = parsed.path
+
+        for assign in parsed.assignments:
+            # Look for list assignments with Route() calls
+            source = assign.value_source or ""
+
+            # Check for Route or APIRoute in a list
+            if not ("[" in source and "Route(" in source):
+                continue
+
+            routes = self._parse_route_table(source, file_path, assign.location.line)
+            if routes:
+                self._route_tables[file_path][assign.target] = routes
+                self._dynamic_routes.extend(routes)
+
+    def _parse_route_table(
+        self,
+        source: str,
+        file_path: Path,
+        line: int,
+    ) -> list[DynamicRoute]:
+        """Parse a route table definition."""
+        routes: list[DynamicRoute] = []
+
+        # Pattern for Route("/path", endpoint=handler, methods=["GET"])
+        route_pattern = r'(?:API)?Route\s*\(\s*["\']([^"\']+)["\']\s*(?:,\s*(?:endpoint\s*=\s*)?(\w+))?\s*(?:,\s*methods\s*=\s*\[([^\]]*)\])?'
+
+        for match in re.finditer(route_pattern, source):
+            path = match.group(1)
+            handler = match.group(2) or ""
+            methods_str = match.group(3) or ""
+
+            # Parse methods
+            methods = re.findall(r'["\'](\w+)["\']', methods_str) or ["GET"]
+
+            routes.append(
+                DynamicRoute(
+                    path=path,
+                    methods=[m.upper() for m in methods],
+                    handler_name=handler,
+                    registration_type="route_table",
+                    file_path=file_path,
+                    line=line,
+                    is_fully_resolved=True,
+                    confidence=0.95,
+                )
+            )
+
+        return routes
+
+    def _detect_factory_functions(self, parsed: ParsedFile) -> None:
+        """Detect functions that generate routes."""
+
+        for func in parsed.functions:
+            factory = self._analyze_factory_function(func, parsed)
+            if factory:
+                self._factories[factory.qualified_name] = factory
+
+    def _analyze_factory_function(
+        self,
+        func: ParsedFunction,
+        parsed: ParsedFile,
+    ) -> RouteFactory | None:
+        """Analyze a function to determine if it's a route factory."""
+        file_path = parsed.path
+        name = func.name.lower()
+
+        # Check naming patterns
+        factory_patterns = [
+            "create_routes",
+            "create_crud",
+            "generate_routes",
+            "make_routes",
+            "crud_routes",
+            "resource_routes",
+            "register_routes",
+            "build_routes",
+            "create_api",
+            "crud_generator",
+            "crud_factory",
+        ]
+
+        is_likely_factory = False
+        factory_type = "unknown"
+
+        for pattern in factory_patterns:
+            if pattern in name:
+                is_likely_factory = True
+                if "crud" in pattern:
+                    factory_type = "crud"
+                elif "resource" in pattern:
+                    factory_type = "resource"
+                else:
+                    factory_type = "generic"
+                break
+
+        # Check return type
+        if func.return_type:
+            ret_lower = func.return_type.lower()
+            if any(x in ret_lower for x in ["router", "apirouter", "list[route"]):
+                is_likely_factory = True
+
+        if not is_likely_factory:
+            return None
+
+        # Analyze parameters
+        model_param = None
+        prefix_param = None
+
+        for param in func.parameters:
+            param_name = param.name.lower()
+            if param_name in {"model", "model_class", "schema", "orm_model"}:
+                model_param = param.name
+            elif param_name in {"prefix", "path_prefix", "base_path"}:
+                prefix_param = param.name
+
+        # Try to detect generated routes from function body
+        generated_routes = self._detect_routes_in_function(func, parsed)
+
+        return RouteFactory(
+            name=func.name,
+            qualified_name=func.qualified_name.full,
+            file_path=file_path,
+            line=func.location.line,
+            factory_type=factory_type,
+            model_param=model_param,
+            prefix_param=prefix_param,
+            generated_routes=generated_routes,
+            confidence=0.7 if generated_routes else 0.4,
+        )
+
+    def _detect_routes_in_function(
+        self,
+        func: ParsedFunction,
+        parsed: ParsedFile,
+    ) -> list[DynamicRoute]:
+        """Detect routes defined within a function (factory pattern)."""
+        routes: list[DynamicRoute] = []
+        file_path = parsed.path
+
+        # Find decorators within the function that create routes
+        # This is tricky because we need to look at nested functions
+
+        # For now, look for common CRUD patterns
+        crud_methods = [
+            ("", ["GET"], "list"),
+            ("/{id}", ["GET"], "read"),
+            ("", ["POST"], "create"),
+            ("/{id}", ["PUT", "PATCH"], "update"),
+            ("/{id}", ["DELETE"], "delete"),
+        ]
+
+        # Check if function body contains these patterns
+        if func.docstring and "crud" in func.docstring.lower():
+            for path_suffix, methods, operation in crud_methods:
+                routes.append(
+                    DynamicRoute(
+                        path=f"{{prefix}}{path_suffix}",
+                        methods=methods,
+                        handler_name=f"{func.name}_{operation}",
+                        registration_type="factory",
+                        file_path=file_path,
+                        line=func.location.line,
+                        factory_function=func.name,
+                        is_fully_resolved=False,
+                        confidence=0.5,
+                        notes=[f"Inferred from CRUD factory: {func.name}"],
+                    )
+                )
+
+        return routes
+
+    def _detect_loop_registrations(self, parsed: ParsedFile) -> None:
+        """Detect loop-based route registrations."""
+        file_path = parsed.path
+
+        # This requires more sophisticated analysis of control flow
+        # For now, we look for patterns in call sites
+
+        for call in parsed.call_sites:
+            if not (
+                call.callee_name.endswith("add_api_route") or call.callee_name.endswith("add_route")
+            ):
+                continue
+
+            # Check if any argument references a loop variable
+            # This is a heuristic - we check for common patterns
+            for arg in call.arguments:
+                expr = arg.expression_text or ""
+
+                # Patterns like: route["path"], route.path, item["endpoint"]
+                if re.search(r"\w+\[.+\]|\w+\.\w+", expr):
+                    loop_reg = LoopRouteRegistration(
+                        file_path=file_path,
+                        line=call.location.line,
+                        iterable_name="routes",  # Inferred
+                        registration_call=call.callee_name,
+                        notes=["Detected dictionary/attribute access in route registration"],
+                    )
+                    self._loop_registrations.append(loop_reg)
+                    break
+
+    def _extract_arg_value(self, arg) -> str:
+        """Extract value from a call argument."""
+        if arg.literal_value is not None:
+            return str(arg.literal_value)
+        if arg.expression_text:
+            # Try to extract string literal
+            match = re.search(r'["\']([^"\']*)["\']', arg.expression_text)
+            if match:
+                return match.group(1)
+            return arg.expression_text
+        return ""
+
+    def _extract_methods(self, arg) -> list[str]:
+        """Extract HTTP methods from argument."""
+        methods = []
+
+        if isinstance(arg.literal_value, list):
+            return [str(m).upper() for m in arg.literal_value]
+
+        if arg.expression_text:
+            matches = re.findall(r'["\'](\w+)["\']', arg.expression_text)
+            methods = [m.upper() for m in matches]
+
+        return methods or ["GET"]
+
+    def _has_variable_ref(self, value: str) -> bool:
+        """Check if value contains unresolved variable references."""
+        # f-string variables: {var}
+        if re.search(r"\{[^}]+\}", value):
+            return True
+        # Not a literal
+        return bool(not (value.startswith("/") or value.startswith('"') or value.startswith("'")))
+
+    # =========================================================================
+    # Query Methods
+    # =========================================================================
+
+    def get_all_routes(self) -> list[DynamicRoute]:
+        """Get all detected dynamic routes."""
+        return list(self._dynamic_routes)
+
+    def get_routes_for_file(self, file_path: Path) -> list[DynamicRoute]:
+        """Get dynamic routes defined in a specific file."""
+        return [r for r in self._dynamic_routes if r.file_path == file_path]
+
+    def get_factories(self) -> dict[str, RouteFactory]:
+        """Get all detected route factories."""
+        return dict(self._factories)
+
+    def get_loop_registrations(self) -> list[LoopRouteRegistration]:
+        """Get all detected loop-based registrations."""
+        return list(self._loop_registrations)
+
+    def get_route_tables(self, file_path: Path) -> dict[str, list[DynamicRoute]]:
+        """Get route tables defined in a file."""
+        return self._route_tables.get(file_path, {})
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+
+def detect_dynamic_routes(
+    parsed_files: list[ParsedFile],
+    project_root: Path | None = None,
+) -> tuple[list[DynamicRoute], dict[str, RouteFactory]]:
+    """
+    Detect all dynamic routes in a project.
+
+    Args:
+        parsed_files: List of successfully parsed files
+        project_root: Optional project root
+
+    Returns:
+        Tuple of (dynamic_routes, factories)
+    """
+    detector = DynamicRouteDetector(project_root)
+
+    for parsed in parsed_files:
+        detector.process_file(parsed)
+
+    return detector.get_all_routes(), detector.get_factories()