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

apisec_code_bolt/parsing/python/constant_resolver.py

@@ -0,0 +1,500 @@
+"""
+Constant and configuration value resolver for Python projects.
+
+This module handles resolving constants, config attributes, and settings
+even when they CAN be overwritten by environment variables. The philosophy:
+
+  "Resolve what we can statically. Note that it may vary at runtime."
+
+Handles:
+1. Module-level constants: API_PREFIX = "/api"
+2. Class attributes: class Config: PREFIX = "/api"
+3. Pydantic Settings with defaults: class Settings(BaseSettings): prefix: str = "/api"
+4. Attribute chains: config.api.prefix
+5. Environment variable defaults: os.getenv("PREFIX", "/api") -> "/api"
+
+CRITICAL: Enterprise apps often use configuration objects. Even if values CAN
+be overridden, the default value is usually what's deployed in most environments.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..base import ParsedClass, ParsedFile
+
+
+# =============================================================================
+# Data Types
+# =============================================================================
+
+
+@dataclass
+class ResolvedConstant:
+    """A resolved constant value."""
+
+    name: str  # Full name (e.g., "config.api.PREFIX")
+    value: str  # Resolved value
+
+    # Source information
+    source_file: Path | None = None
+    source_line: int = 0
+    source_type: str = ""  # "module_var", "class_attr", "settings", "env_default"
+
+    # Confidence and notes
+    is_default: bool = True  # True if this is a default that could be overridden
+    confidence: float = 1.0
+    override_sources: list[str] = field(default_factory=list)  # e.g., ["ENV:API_PREFIX"]
+
+    # For documentation
+    description: str = ""
+
+
+@dataclass
+class ConfigClass:
+    """A configuration class definition."""
+
+    name: str
+    qualified_name: str
+    file_path: Path
+
+    # Is it a Pydantic Settings class?
+    is_pydantic_settings: bool = False
+
+    # Attributes with their default values
+    attributes: dict[str, ResolvedConstant] = field(default_factory=dict)
+
+    # For nested config: config.api.prefix
+    nested_configs: dict[str, str] = field(default_factory=dict)  # attr_name -> class_name
+
+
+# =============================================================================
+# Constant Resolver
+# =============================================================================
+
+
+class ConstantResolver:
+    """
+    Resolves constants and configuration values across a project.
+
+    Strategy:
+    1. Scan all files for module-level constants (UPPER_CASE assignments)
+    2. Identify configuration classes (Settings, Config, etc.)
+    3. Extract default values from class attributes
+    4. Build an attribute chain resolver for nested access
+    5. Track which values can be overridden and how
+
+    Usage:
+        resolver = ConstantResolver()
+
+        for parsed in parsed_files:
+            resolver.process_file(parsed)
+
+        resolver.build_resolution_graph()
+
+        value = resolver.resolve("settings.API_PREFIX", file_path)
+    """
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize the resolver."""
+        self._project_root = project_root
+
+        # Module-level constants per file
+        self._module_constants: dict[Path, dict[str, ResolvedConstant]] = {}
+
+        # Configuration classes
+        self._config_classes: dict[str, ConfigClass] = {}
+
+        # Variable to class instance mapping per file
+        # e.g., {"settings": "app.config.Settings"}
+        self._instance_mapping: dict[Path, dict[str, str]] = {}
+
+        # Global constant lookup (name -> value)
+        self._global_lookup: dict[str, str] = {}
+
+        # Import mappings per file
+        self._imports: dict[Path, dict[str, str]] = {}
+
+    def process_file(self, parsed: ParsedFile) -> None:
+        """Process a parsed file to extract constants."""
+        if not parsed.success:
+            return
+
+        file_path = parsed.path
+        self._module_constants[file_path] = {}
+        self._instance_mapping[file_path] = {}
+        self._imports[file_path] = {}
+
+        # 1. Build import mappings
+        self._extract_imports(parsed)
+
+        # 2. Extract module-level constants
+        self._extract_module_constants(parsed)
+
+        # 3. Extract configuration classes
+        self._extract_config_classes(parsed)
+
+        # 4. Track config instance assignments
+        self._extract_config_instances(parsed)
+
+    def _extract_imports(self, parsed: ParsedFile) -> None:
+        """Extract import mappings."""
+        file_path = parsed.path
+
+        for imp in parsed.imports:
+            if imp.is_from_import:
+                for name in imp.names:
+                    local_name = imp.alias if len(imp.names) == 1 and imp.alias else name
+                    self._imports[file_path][local_name] = f"{imp.module}.{name}"
+            else:
+                local_name = imp.alias or imp.module.split(".")[-1]
+                self._imports[file_path][local_name] = imp.module
+
+    def _extract_module_constants(self, parsed: ParsedFile) -> None:
+        """Extract module-level constant assignments."""
+        file_path = parsed.path
+
+        for assign in parsed.assignments:
+            # Skip function-local assignments
+            if assign.in_function:
+                continue
+
+            name = assign.target
+            source = assign.value_source or ""
+
+            # Check for constant naming (UPPER_CASE or Title_Case with underscore)
+            if not (name.isupper() or (name[0].isupper() and "_" in name)):
+                # Also accept common config names
+                if name.lower() not in {
+                    "prefix",
+                    "api_prefix",
+                    "base_path",
+                    "root_path",
+                    "version",
+                }:
+                    continue
+
+            # Try to extract value
+            value, source_type, override_sources = self._extract_constant_value(source)
+
+            if value is not None:
+                const = ResolvedConstant(
+                    name=name,
+                    value=value,
+                    source_file=file_path,
+                    source_line=assign.location.line,
+                    source_type=source_type,
+                    is_default=len(override_sources) > 0,
+                    override_sources=override_sources,
+                )
+
+                self._module_constants[file_path][name] = const
+                self._global_lookup[name] = value
+
+    def _extract_constant_value(self, source: str) -> tuple[str | None, str, list[str]]:
+        """
+        Extract constant value from source code.
+
+        Returns:
+            Tuple of (value, source_type, override_sources)
+        """
+        source = source.strip()
+        override_sources: list[str] = []
+
+        # 1. Simple string literal
+        string_match = re.match(r'^["\']([^"\']*)["\']$', source)
+        if string_match:
+            return string_match.group(1), "literal", []
+
+        # 2. os.getenv() or os.environ.get() with default
+        env_match = re.search(
+            r'(?:os\.)?(?:getenv|environ\.get)\s*\(\s*["\']([^"\']+)["\']\s*(?:,\s*["\']([^"\']*)["\'])?\s*\)',
+            source,
+        )
+        if env_match:
+            env_name = env_match.group(1)
+            default = env_match.group(2)
+            override_sources.append(f"ENV:{env_name}")
+            return default, "env_default", override_sources
+
+        # 3. f-string without variables (just a literal)
+        fstring_match = re.match(r'^f["\']([^{}"\']*)["\']\s*$', source)
+        if fstring_match:
+            return fstring_match.group(1), "literal", []
+
+        # 4. Integer literal
+        if source.isdigit():
+            return source, "literal", []
+
+        # 5. Name reference to another constant
+        if re.match(r"^[A-Z][A-Z0-9_]*$", source):
+            # It's a reference to another constant
+            if source in self._global_lookup:
+                return self._global_lookup[source], "reference", []
+
+        return None, "unknown", []
+
+    def _extract_config_classes(self, parsed: ParsedFile) -> None:
+        """Extract configuration class definitions."""
+        file_path = parsed.path
+
+        for cls in parsed.classes:
+            # Check if it's a config class
+            is_config = self._is_config_class(cls)
+            if not is_config:
+                continue
+
+            # Check for Pydantic Settings
+            is_settings = any(
+                base in {"BaseSettings", "pydantic_settings.BaseSettings", "pydantic.BaseSettings"}
+                for base in cls.base_classes
+            )
+
+            config = ConfigClass(
+                name=cls.name,
+                qualified_name=cls.qualified_name.full,
+                file_path=file_path,
+                is_pydantic_settings=is_settings,
+            )
+
+            # Extract attributes from fields
+            for f in cls.fields:
+                value, source_type, overrides = self._extract_field_default(f, is_settings)
+
+                if value is not None:
+                    config.attributes[f.name] = ResolvedConstant(
+                        name=f"{cls.name}.{f.name}",
+                        value=value,
+                        source_file=file_path,
+                        source_line=f.location.line if f.location else 0,
+                        source_type=source_type,
+                        is_default=is_settings or len(overrides) > 0,
+                        override_sources=overrides,
+                        description=f.description or "",
+                    )
+
+            self._config_classes[config.qualified_name] = config
+
+            # Also register by simple name
+            if cls.name not in self._config_classes:
+                self._config_classes[cls.name] = config
+
+    def _is_config_class(self, cls: ParsedClass) -> bool:
+        """Check if a class is a configuration class."""
+        name_lower = cls.name.lower()
+
+        # Name-based detection
+        config_names = {"config", "settings", "configuration", "options", "params"}
+        if any(n in name_lower for n in config_names):
+            return True
+
+        # Base class detection
+        config_bases = {
+            "BaseSettings",
+            "BaseConfig",
+            "Configuration",
+            "pydantic.BaseSettings",
+            "pydantic_settings.BaseSettings",
+        }
+        return bool(any(base in config_bases for base in cls.base_classes))
+
+    def _extract_field_default(
+        self,
+        field,
+        is_pydantic: bool,
+    ) -> tuple[str | None, str, list[str]]:
+        """Extract default value from a class field."""
+        default = field.default_value
+        override_sources: list[str] = []
+
+        if not default:
+            # For Pydantic Settings, field might be set from env
+            if is_pydantic:
+                # Env var name is typically UPPER_CASE of field name
+                env_name = field.name.upper()
+                override_sources.append(f"ENV:{env_name}")
+            return None, "no_default", override_sources
+
+        # Try to extract the value
+        value, source_type, overrides = self._extract_constant_value(default)
+        override_sources.extend(overrides)
+
+        # For Pydantic Settings, always add potential env override
+        if is_pydantic and not any("ENV:" in o for o in override_sources):
+            env_name = field.name.upper()
+            override_sources.append(f"ENV:{env_name}")
+
+        return value, source_type, override_sources
+
+    def _extract_config_instances(self, parsed: ParsedFile) -> None:
+        """Track assignments of config class instances."""
+        file_path = parsed.path
+
+        for assign in parsed.assignments:
+            if assign.in_function:
+                continue
+
+            source = assign.source_call or ""
+
+            # Check if it's instantiating a known config class
+            resolved = self._resolve_call_name(source, file_path)
+
+            if resolved in self._config_classes:
+                self._instance_mapping[file_path][assign.target] = resolved
+
+    def _resolve_call_name(self, name: str, file_path: Path) -> str:
+        """Resolve a call name using imports."""
+        imports = self._imports.get(file_path, {})
+
+        parts = name.split(".")
+        if parts[0] in imports:
+            resolved = imports[parts[0]]
+            if len(parts) > 1:
+                return f"{resolved}.{'.'.join(parts[1:])}"
+            return resolved
+
+        return name
+
+    # =========================================================================
+    # Resolution
+    # =========================================================================
+
+    def build_resolution_graph(self) -> None:
+        """Build the resolution graph after processing all files."""
+        # Add all config class attributes to global lookup
+        for config in self._config_classes.values():
+            for attr_name, const in config.attributes.items():
+                # Register with full name
+                self._global_lookup[const.name] = const.value
+                # Register with class.attr format
+                self._global_lookup[f"{config.name}.{attr_name}"] = const.value
+
+    def resolve(
+        self,
+        expression: str,
+        in_file: Path | None = None,
+    ) -> ResolvedConstant | None:
+        """
+        Resolve a constant expression.
+
+        Handles:
+        - Simple names: API_PREFIX
+        - Attribute access: config.PREFIX
+        - Nested access: settings.api.prefix
+
+        Args:
+            expression: The expression to resolve
+            in_file: File context for local resolution
+
+        Returns:
+            ResolvedConstant if resolvable, None otherwise
+        """
+        expression = expression.strip()
+
+        # 1. Direct lookup
+        if expression in self._global_lookup:
+            return ResolvedConstant(
+                name=expression,
+                value=self._global_lookup[expression],
+                source_type="direct",
+            )
+
+        # 2. Check file-local constants
+        if in_file and in_file in self._module_constants:
+            if expression in self._module_constants[in_file]:
+                return self._module_constants[in_file][expression]
+
+        # 3. Handle attribute access: config.PREFIX
+        if "." in expression:
+            parts = expression.split(".")
+
+            # Try to resolve the base object
+            base = parts[0]
+            attr_path = ".".join(parts[1:])
+
+            # Check if base is a config instance in this file
+            if in_file and in_file in self._instance_mapping:
+                instance_map = self._instance_mapping[in_file]
+                if base in instance_map:
+                    config_name = instance_map[base]
+                    config = self._config_classes.get(config_name)
+                    if config:
+                        # Look up the attribute
+                        if attr_path in config.attributes:
+                            return config.attributes[attr_path]
+                        # Try lowercase version
+                        if attr_path.lower() in config.attributes:
+                            return config.attributes[attr_path.lower()]
+
+            # Try looking up the full expression in global
+            if expression in self._global_lookup:
+                return ResolvedConstant(
+                    name=expression,
+                    value=self._global_lookup[expression],
+                    source_type="config_attr",
+                )
+
+            # Try class.attr format directly
+            for config_name, _config in self._config_classes.items():
+                full_name = f"{config_name}.{attr_path}"
+                if full_name in self._global_lookup:
+                    return ResolvedConstant(
+                        name=full_name,
+                        value=self._global_lookup[full_name],
+                        source_type="config_attr",
+                    )
+
+        return None
+
+    def resolve_value(
+        self,
+        expression: str,
+        in_file: Path | None = None,
+    ) -> str | None:
+        """Convenience method to just get the value."""
+        const = self.resolve(expression, in_file)
+        return const.value if const else None
+
+    def get_all_constants(self) -> dict[str, str]:
+        """Get all resolved constants."""
+        return dict(self._global_lookup)
+
+    def get_config_classes(self) -> dict[str, ConfigClass]:
+        """Get all detected configuration classes."""
+        return dict(self._config_classes)
+
+    def get_constants_for_file(self, file_path: Path) -> dict[str, ResolvedConstant]:
+        """Get constants defined in a specific file."""
+        return self._module_constants.get(file_path, {})
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+
+def build_constant_resolver(
+    parsed_files: list[ParsedFile],
+    project_root: Path | None = None,
+) -> ConstantResolver:
+    """
+    Build a constant resolver from parsed files.
+
+    Args:
+        parsed_files: List of successfully parsed files
+        project_root: Optional project root
+
+    Returns:
+        Configured ConstantResolver
+    """
+    resolver = ConstantResolver(project_root)
+
+    for parsed in parsed_files:
+        resolver.process_file(parsed)
+
+    resolver.build_resolution_graph()
+    return resolver