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

apisec_code_bolt/parsing/python/path_resolver.py

@@ -0,0 +1,576 @@
+"""
+Path resolver for computed route paths in FastAPI/Starlette applications.
+
+This module handles:
+- f-string path resolution: f"/api/{version}/users" -> "/api/v1/users"
+- Constant/variable path resolution: PREFIX + "/users" -> "/api/users"
+- Config attribute resolution: settings.API_PREFIX -> "/api"
+- Module-level variable tracking
+- Partial resolution with confidence levels
+
+CRITICAL: Many enterprise applications use computed paths for versioning,
+tenant isolation, or dynamic configuration. This enables accurate path resolution.
+
+PHILOSOPHY: Resolve what we can statically. Even if a value CAN be overridden
+at runtime (env vars, settings), the default value is valuable information.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import libcst as cst
+
+if TYPE_CHECKING:
+    from ..base import ParsedAssignment, ParsedFile
+    from .constant_resolver import ConstantResolver
+
+
+# =============================================================================
+# Data Types
+# =============================================================================
+
+
+@dataclass
+class ResolvedPath:
+    """Result of path resolution."""
+
+    # The resolved path (may be partial)
+    path: str
+
+    # Original path expression
+    original: str
+
+    # How much was resolved (0.0 = nothing, 1.0 = fully resolved)
+    resolution_confidence: float
+
+    # Unresolved variables (for partial resolution)
+    unresolved_vars: list[str] = field(default_factory=list)
+
+    # Notes about resolution
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class TrackedVariable:
+    """A module-level variable that might be used in paths."""
+
+    name: str
+    value: str | None  # Resolved value if known
+    value_source: str  # Original source code
+    file_path: Path
+    line: int
+
+    # Type of variable
+    var_type: str  # "constant", "env_var", "computed", "unknown"
+
+    # If env var: the env var name
+    env_var_name: str | None = None
+
+    # Default value for env vars
+    env_default: str | None = None
+
+
+# =============================================================================
+# Path Expression Analyzer
+# =============================================================================
+
+
+class PathExpressionAnalyzer(cst.CSTVisitor):
+    """
+    CST visitor to analyze path expressions.
+
+    Extracts:
+    - String literals
+    - f-string components
+    - Variable references
+    - Concatenation operations
+    """
+
+    def __init__(self):
+        self.components: list[dict[str, Any]] = []
+        self._in_fstring = False
+
+    def visit_SimpleString(self, node: cst.SimpleString) -> bool:
+        """Extract simple string literals."""
+        value = self._extract_string_value(node)
+        self.components.append(
+            {
+                "type": "literal",
+                "value": value,
+            }
+        )
+        return False
+
+    def visit_FormattedString(self, node: cst.FormattedString) -> bool:
+        """Start of f-string."""
+        self._in_fstring = True
+        return True
+
+    def leave_FormattedString(self, node: cst.FormattedString) -> None:
+        """End of f-string."""
+        self._in_fstring = False
+
+    def visit_FormattedStringText(self, node: cst.FormattedStringText) -> bool:
+        """Literal text within f-string."""
+        self.components.append(
+            {
+                "type": "literal",
+                "value": node.value,
+            }
+        )
+        return False
+
+    def visit_FormattedStringExpression(self, node: cst.FormattedStringExpression) -> bool:
+        """Expression within f-string: {expr}."""
+        expr = node.expression
+
+        # Check if it's a simple name reference
+        if isinstance(expr, cst.Name):
+            self.components.append(
+                {
+                    "type": "variable",
+                    "name": expr.value,
+                }
+            )
+        elif isinstance(expr, cst.Attribute):
+            # Handle obj.attr references
+            self.components.append(
+                {
+                    "type": "attribute",
+                    "source": self._node_to_code(expr),
+                }
+            )
+        else:
+            # Complex expression
+            self.components.append(
+                {
+                    "type": "expression",
+                    "source": self._node_to_code(expr),
+                }
+            )
+
+        return False
+
+    def visit_ConcatenatedString(self, node: cst.ConcatenatedString) -> bool:
+        """Handle string concatenation."""
+        # Process each part
+        return True
+
+    def visit_BinaryOperation(self, node: cst.BinaryOperation) -> bool:
+        """Handle + operator for string concatenation."""
+        if isinstance(node.operator, cst.Add):
+            # Process left and right separately
+            return True
+        return False
+
+    def visit_Name(self, node: cst.Name) -> bool:
+        """Handle standalone variable references."""
+        if not self._in_fstring:
+            self.components.append(
+                {
+                    "type": "variable",
+                    "name": node.value,
+                }
+            )
+        return False
+
+    def _extract_string_value(self, node: cst.SimpleString) -> str:
+        """Extract the actual string value from a string node."""
+        raw = node.value
+
+        # Remove prefixes (r, b, f, etc.)
+        for prefix in ["r", "b", "f", "u", "fr", "rf", "br", "rb"]:
+            if raw.lower().startswith(prefix):
+                raw = raw[len(prefix) :]
+                break
+
+        # Remove quotes
+        if raw.startswith('"""') or raw.startswith("'''"):
+            return raw[3:-3]
+        elif raw.startswith('"') or raw.startswith("'"):
+            return raw[1:-1]
+
+        return raw
+
+    def _node_to_code(self, node: cst.CSTNode) -> str:
+        """Convert a CST node to source code."""
+        try:
+            module = cst.parse_module("")
+            return module.code_for_node(node)
+        except Exception:
+            return str(node)
+
+
+# =============================================================================
+# Path Resolver
+# =============================================================================
+
+
+class PathResolver:
+    """
+    Resolves computed route paths to their final values.
+
+    Handles:
+    - f-string interpolation: f"/api/{VERSION}/users"
+    - String concatenation: PREFIX + "/users"
+    - Module-level constants: API_VERSION = "v1"
+    - Config attributes: settings.API_PREFIX, config.prefix
+    - Environment variables with defaults: os.getenv("API_VERSION", "v1")
+
+    PHILOSOPHY: Even if a value CAN be overridden at runtime, resolve the
+    default/static value. This captures the most common deployment configuration.
+
+    Usage:
+        resolver = PathResolver()
+
+        # Register known variables from parsed files
+        for parsed in parsed_files:
+            resolver.process_file(parsed)
+
+        # Optionally set a constant resolver for cross-file resolution
+        resolver.set_constant_resolver(constant_resolver)
+
+        # Resolve a path expression
+        result = resolver.resolve(path_expression, file_path)
+    """
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize the resolver."""
+        self._project_root = project_root
+        self._variables: dict[Path, dict[str, TrackedVariable]] = {}
+        self._global_constants: dict[str, str] = {}
+        self._constant_resolver: ConstantResolver | None = None
+
+    def set_constant_resolver(self, resolver: ConstantResolver) -> None:
+        """Set a constant resolver for cross-file config resolution."""
+        self._constant_resolver = resolver
+
+    def process_file(self, parsed: ParsedFile) -> None:
+        """Process a file to extract path-relevant variables."""
+        if not parsed.success:
+            return
+
+        file_path = parsed.path
+        self._variables[file_path] = {}
+
+        for assign in parsed.assignments:
+            var = self._extract_variable(assign, file_path)
+            if var:
+                self._variables[file_path][var.name] = var
+
+                # Track as global constant if it looks like one
+                if var.var_type == "constant" and var.value:
+                    self._global_constants[var.name] = var.value
+
+    def _extract_variable(
+        self,
+        assign: ParsedAssignment,
+        file_path: Path,
+    ) -> TrackedVariable | None:
+        """Extract a tracked variable from an assignment."""
+        # Skip assignments inside functions
+        if assign.in_function:
+            return None
+
+        name = assign.target
+        source = assign.value_source or ""
+
+        # Check for env var pattern: os.getenv("VAR", "default")
+        env_match = re.search(
+            r'(?:os\.)?(?:getenv|environ\.get)\s*\(\s*["\']([^"\']+)["\']\s*(?:,\s*["\']([^"\']*)["\'])?\s*\)',
+            source,
+        )
+        if env_match:
+            return TrackedVariable(
+                name=name,
+                value=env_match.group(2),  # Use default as value
+                value_source=source,
+                file_path=file_path,
+                line=assign.location.line,
+                var_type="env_var",
+                env_var_name=env_match.group(1),
+                env_default=env_match.group(2),
+            )
+
+        # Check for string literal
+        if assign.is_literal:
+            string_match = re.search(r'^["\']([^"\']*)["\']$', source.strip())
+            if string_match:
+                return TrackedVariable(
+                    name=name,
+                    value=string_match.group(1),
+                    value_source=source,
+                    file_path=file_path,
+                    line=assign.location.line,
+                    var_type="constant",
+                )
+
+        # Check for UPPER_CASE constant naming convention
+        if name.isupper() and "_" in name or name.isupper():
+            # Try to extract value
+            value = self._try_extract_string_value(source)
+            return TrackedVariable(
+                name=name,
+                value=value,
+                value_source=source,
+                file_path=file_path,
+                line=assign.location.line,
+                var_type="constant" if value else "unknown",
+            )
+
+        return None
+
+    def _try_extract_string_value(self, source: str) -> str | None:
+        """Try to extract a string value from source code."""
+        # Simple string literal
+        match = re.search(r'^["\']([^"\']*)["\']$', source.strip())
+        if match:
+            return match.group(1)
+
+        # f-string with no variables
+        match = re.search(r'^f["\']([^{}"\']*)["\']$', source.strip())
+        if match:
+            return match.group(1)
+
+        return None
+
+    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 to resolve
+            file_path: File where the expression is used
+            additional_context: Additional variable bindings
+
+        Returns:
+            ResolvedPath with resolution details
+        """
+        if not path_expression:
+            return ResolvedPath(
+                path="/",
+                original="",
+                resolution_confidence=1.0,
+            )
+
+        # Check for simple string literal (most common case)
+        if path_expression.startswith('"') and path_expression.endswith('"'):
+            return ResolvedPath(
+                path=path_expression[1:-1],
+                original=path_expression,
+                resolution_confidence=1.0,
+            )
+        if path_expression.startswith("'") and path_expression.endswith("'"):
+            return ResolvedPath(
+                path=path_expression[1:-1],
+                original=path_expression,
+                resolution_confidence=1.0,
+            )
+
+        # If it's already a simple path (no quotes, starts with /), return as-is
+        if path_expression.startswith("/") and "{" not in path_expression:
+            return ResolvedPath(
+                path=path_expression,
+                original=path_expression,
+                resolution_confidence=1.0,
+            )
+
+        # Parse and analyze the expression
+        try:
+            expr = cst.parse_expression(path_expression)
+            analyzer = PathExpressionAnalyzer()
+            expr.walk(analyzer)
+            components = analyzer.components
+        except Exception:
+            # Fallback: treat as literal
+            return ResolvedPath(
+                path=path_expression,
+                original=path_expression,
+                resolution_confidence=0.5,
+                notes=["Failed to parse path expression"],
+            )
+
+        # Build context for resolution
+        context = dict(self._global_constants)
+        if file_path in self._variables:
+            for var in self._variables[file_path].values():
+                if var.value:
+                    context[var.name] = var.value
+        if additional_context:
+            context.update(additional_context)
+
+        # Add constants from constant resolver
+        if self._constant_resolver:
+            context.update(self._constant_resolver.get_all_constants())
+
+        # Resolve components
+        resolved_parts: list[str] = []
+        unresolved: list[str] = []
+        confidence = 1.0
+        notes: list[str] = []
+
+        for comp in components:
+            if comp["type"] == "literal":
+                resolved_parts.append(comp["value"])
+            elif comp["type"] == "variable":
+                var_name = comp["name"]
+                if var_name in context:
+                    resolved_parts.append(context[var_name])
+                else:
+                    # Try constant resolver
+                    resolved_value = self._try_resolve_name(var_name, file_path)
+                    if resolved_value:
+                        resolved_parts.append(resolved_value)
+                        notes.append(f"Resolved {var_name} to default value (may vary at runtime)")
+                        confidence *= 0.9  # Slight reduction since it's a default
+                    else:
+                        # Use placeholder
+                        resolved_parts.append(f"{{{var_name}}}")
+                        unresolved.append(var_name)
+                        confidence *= 0.5
+                        notes.append(f"Unresolved variable: {var_name}")
+            elif comp["type"] == "attribute":
+                # Try to resolve attribute access (config.PREFIX, settings.api_prefix)
+                source = comp.get("source", "?")
+                resolved_value = self._try_resolve_name(source, file_path)
+                if resolved_value:
+                    resolved_parts.append(resolved_value)
+                    notes.append(f"Resolved {source} to default value (may vary at runtime)")
+                    confidence *= 0.85  # Config values can be overridden
+                else:
+                    resolved_parts.append(f"{{{source}}}")
+                    unresolved.append(source)
+                    confidence *= 0.3
+                    notes.append(f"Cannot resolve attribute access: {source}")
+            elif comp["type"] == "expression":
+                # Complex expression - try to resolve if it's a simple call
+                source = comp.get("source", "?")
+                resolved_value = self._try_resolve_expression(source, file_path)
+                if resolved_value:
+                    resolved_parts.append(resolved_value)
+                    notes.append(f"Resolved {source} to default value")
+                    confidence *= 0.8
+                else:
+                    resolved_parts.append(f"{{{source}}}")
+                    unresolved.append(source)
+                    confidence *= 0.2
+                    notes.append(f"Cannot resolve complex expression: {source}")
+
+        resolved_path = "".join(resolved_parts)
+
+        # Normalize path
+        if resolved_path and not resolved_path.startswith("/"):
+            resolved_path = "/" + resolved_path
+
+        return ResolvedPath(
+            path=resolved_path,
+            original=path_expression,
+            resolution_confidence=confidence,
+            unresolved_vars=unresolved,
+            notes=notes,
+        )
+
+    def _try_resolve_name(self, name: str, file_path: Path) -> str | None:
+        """
+        Try to resolve a name using all available sources.
+
+        Checks in order:
+        1. Global constants
+        2. File-local variables
+        3. Constant resolver (config classes, settings)
+        """
+        # 1. Check global constants
+        if name in self._global_constants:
+            return self._global_constants[name]
+
+        # 2. Check file-local variables
+        if file_path in self._variables:
+            var = self._variables[file_path].get(name)
+            if var and var.value:
+                return var.value
+
+        # 3. Check constant resolver
+        if self._constant_resolver:
+            resolved = self._constant_resolver.resolve(name, file_path)
+            if resolved:
+                return resolved.value
+
+        return None
+
+    def _try_resolve_expression(self, expr: str, file_path: Path) -> str | None:
+        """
+        Try to resolve a simple expression.
+
+        Handles:
+        - os.getenv("VAR", "default") -> "default"
+        - config.get("key", "default") -> "default"
+        """
+        import re
+
+        # os.getenv with default
+        env_match = re.search(
+            r'(?:os\.)?(?:getenv|environ\.get)\s*\(\s*["\'][^"\']+["\']\s*,\s*["\']([^"\']*)["\']',
+            expr,
+        )
+        if env_match:
+            return env_match.group(1)
+
+        # .get() with default
+        get_match = re.search(
+            r'\.get\s*\(\s*["\'][^"\']+["\']\s*,\s*["\']([^"\']*)["\']',
+            expr,
+        )
+        if get_match:
+            return get_match.group(1)
+
+        return None
+
+    def get_variable(self, name: str, file_path: Path) -> TrackedVariable | None:
+        """Get a tracked variable by name."""
+        if file_path in self._variables:
+            return self._variables[file_path].get(name)
+        return None
+
+    def get_all_constants(self) -> dict[str, str]:
+        """Get all global constants."""
+        result = dict(self._global_constants)
+        if self._constant_resolver:
+            result.update(self._constant_resolver.get_all_constants())
+        return result
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+
+def resolve_route_path(
+    path_expression: str,
+    parsed_file: ParsedFile,
+    resolver: PathResolver | None = None,
+) -> ResolvedPath:
+    """
+    Resolve a route path expression.
+
+    Args:
+        path_expression: The path expression from decorator
+        parsed_file: The parsed file containing the route
+        resolver: Optional pre-configured resolver
+
+    Returns:
+        ResolvedPath with resolution details
+    """
+    if resolver is None:
+        resolver = PathResolver()
+        resolver.process_file(parsed_file)
+
+    return resolver.resolve(path_expression, parsed_file.path)