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

apisec_code_bolt/parsing/python/cross_file_resolver.py

@@ -0,0 +1,1054 @@
+"""
+Cross-file type and symbol resolution for Python projects.
+
+This module handles:
+- Building an import graph across all parsed files
+- Resolving type references to their definitions
+- Resolving import aliases
+- Building multi-level inheritance hierarchies (transitive closure)
+- Tracking Pydantic model relationships through inheritance chains
+- Computing Method Resolution Order (MRO) for diamond inheritance
+- Supporting src-layout and non-standard project structures
+
+CRITICAL: This enables proper analysis of enterprise-scale codebases
+where types and models are defined in separate files from their usage.
+
+IMPROVEMENTS:
+1. Multi-level inheritance with cycle detection
+2. src-layout project structure support
+3. External package detection (pydantic, etc.)
+4. Full MRO computation for correct field inheritance
+5. Inherited field deduplication
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ..base import ParsedClass, ParsedFile, ParsedFunction, ParsedImport
+
+if TYPE_CHECKING:
+    pass
+
+
+# =============================================================================
+# Known External Packages
+# =============================================================================
+
+
+# Pydantic base classes that indicate a model
+PYDANTIC_BASE_CLASSES = frozenset(
+    {
+        "BaseModel",
+        "BaseSettings",
+        "pydantic.BaseModel",
+        "pydantic.BaseSettings",
+        "pydantic.main.BaseModel",
+        "pydantic_settings.BaseSettings",
+    }
+)
+
+# Dataclass indicators
+DATACLASS_DECORATORS = frozenset(
+    {
+        "dataclass",
+        "dataclasses.dataclass",
+        "attrs.define",
+        "attr.s",
+    }
+)
+
+# Known external packages (for detecting external dependencies)
+KNOWN_EXTERNAL_PACKAGES = frozenset(
+    {
+        "pydantic",
+        "fastapi",
+        "starlette",
+        "sqlalchemy",
+        "sqlmodel",
+        "typing",
+        "typing_extensions",
+        "collections",
+        "abc",
+        "enum",
+        "datetime",
+        "decimal",
+        "uuid",
+        "pathlib",
+        "os",
+        "sys",
+        "re",
+    }
+)
+
+
+# =============================================================================
+# Resolution Data Types
+# =============================================================================
+
+
+@dataclass
+class ResolvedSymbol:
+    """A fully resolved symbol with its definition location."""
+
+    name: str
+    qualified_name: str
+    kind: str  # "class", "function", "variable", "module"
+
+    # Where it's defined
+    defined_in_file: Path | None = None
+    defined_at_line: int = 0
+
+    # For classes
+    is_pydantic_model: bool = False
+    is_dataclass: bool = False
+    base_classes: list[str] = field(default_factory=list)
+
+    # Multi-level inheritance (full chain)
+    all_bases: list[str] = field(default_factory=list)  # All ancestors
+    mro: list[str] = field(default_factory=list)  # Method Resolution Order
+
+    # External dependency info
+    is_external: bool = False
+    external_package: str | None = None
+
+    # The actual definition object
+    definition: ParsedClass | ParsedFunction | None = None
+
+    @property
+    def file_path(self) -> Path | None:
+        """Alias for defined_in_file (used by language_services)."""
+        return self.defined_in_file
+
+    @property
+    def bases(self) -> list[str]:
+        """Alias for base_classes (used by language_services)."""
+        return self.base_classes
+
+    @property
+    def is_class(self) -> bool:
+        """Whether this symbol is a class."""
+        return self.kind == "class"
+
+
+@dataclass
+class ResolvedImport:
+    """A resolved import with its target."""
+
+    local_name: str  # Name as used in the importing file
+    original_name: str  # Original name in source module
+    source_module: str  # Module path
+
+    # Resolution status
+    resolved: bool = False
+    target: ResolvedSymbol | None = None
+
+    # For re-exports
+    is_reexport: bool = False
+    reexport_chain: list[str] = field(default_factory=list)
+
+    # External package info
+    is_external: bool = False
+
+
+@dataclass
+class ImportGraph:
+    """Graph of imports across the project."""
+
+    # File -> list of imports
+    file_imports: dict[Path, list[ResolvedImport]] = field(default_factory=dict)
+
+    # qualified_name -> ResolvedSymbol
+    symbols: dict[str, ResolvedSymbol] = field(default_factory=dict)
+
+    # local_name -> qualified_name per file
+    name_to_qualified: dict[Path, dict[str, str]] = field(default_factory=dict)
+
+    # Module path -> file path
+    module_to_file: dict[str, Path] = field(default_factory=dict)
+
+    # Inheritance graph (child -> [parents])
+    inheritance_graph: dict[str, list[str]] = field(default_factory=dict)
+
+    # Reverse inheritance (parent -> [children])
+    reverse_inheritance: dict[str, list[str]] = field(default_factory=dict)
+
+
+# =============================================================================
+# Module Path Utilities
+# =============================================================================
+
+
+def detect_src_layout(project_root: Path) -> tuple[bool, Path | None]:
+    """
+    Detect if project uses src-layout.
+
+    Common layouts:
+    1. Standard: project/package/__init__.py
+    2. src-layout: project/src/package/__init__.py
+    3. Namespace: project/src/namespace/package/__init__.py
+
+    Returns:
+        Tuple of (is_src_layout, src_path)
+    """
+    src_dir = project_root / "src"
+    if src_dir.is_dir():
+        # Check if src contains packages (dirs with __init__.py)
+        for child in src_dir.iterdir():
+            if child.is_dir():
+                init_file = child / "__init__.py"
+                if init_file.exists():
+                    return True, src_dir
+                # Also check for namespace packages (PEP 420)
+                if any(
+                    (child / subdir / "__init__.py").exists()
+                    for subdir in child.iterdir()
+                    if subdir.is_dir()
+                ):
+                    return True, src_dir
+    return False, None
+
+
+def infer_module_path(
+    file_path: Path,
+    project_root: Path | None = None,
+    src_path: Path | None = None,
+) -> str:
+    """
+    Infer the Python module path from a file path.
+
+    Handles:
+    - Standard layout: project/package/module.py -> package.module
+    - src-layout: project/src/package/module.py -> package.module
+    - Namespace packages: project/src/ns/package/module.py -> ns.package.module
+    - __init__.py files correctly
+
+    Args:
+        file_path: Path to the Python file
+        project_root: Optional project root for relative resolution
+        src_path: Optional src directory for src-layout projects
+
+    Returns:
+        Module path like "app.models.user"
+    """
+    # Determine effective root (either src_path or project_root)
+    effective_root = src_path or project_root
+
+    # Try to make path relative to effective root
+    try:
+        if effective_root and file_path.is_relative_to(effective_root):
+            rel_path = file_path.relative_to(effective_root)
+        elif project_root and file_path.is_relative_to(project_root):
+            rel_path = file_path.relative_to(project_root)
+        else:
+            rel_path = file_path
+    except ValueError:
+        rel_path = file_path
+
+    # Remove .py extension
+    stem = file_path.stem
+    if stem == "__init__":
+        # For __init__.py, use parent directory as module
+        parts = list(rel_path.parent.parts) if len(rel_path.parts) > 1 else [file_path.parent.name]
+    else:
+        parts = list(rel_path.with_suffix("").parts)
+
+    # Remove 'src' from path if present at start (src-layout)
+    if parts and parts[0] == "src":
+        parts = parts[1:]
+
+    # Join parts to form module path
+    module_path = ".".join(parts)
+
+    # Fallback to walking up from file
+    if not module_path or module_path == stem:
+        return _infer_module_path_by_walk(file_path, project_root)
+
+    return module_path
+
+
+def _infer_module_path_by_walk(file_path: Path, project_root: Path | None = None) -> str:
+    """Fallback module path inference by walking up directory tree."""
+    stem = file_path.stem
+    if stem == "__init__":
+        stem = file_path.parent.name
+        parts = []
+        current = file_path.parent.parent
+    else:
+        parts = [stem]
+        current = file_path.parent
+
+    # Walk up looking for __init__.py or until we hit project_root
+    max_depth = 20  # Prevent infinite loops
+    depth = 0
+
+    while current.name and depth < max_depth:
+        if project_root and current == project_root:
+            break
+
+        init_file = current / "__init__.py"
+        pyproject = current / "pyproject.toml"
+        setup_py = current / "setup.py"
+
+        # Stop at project root markers
+        if pyproject.exists() or setup_py.exists():
+            break
+
+        if init_file.exists():
+            parts.append(current.name)
+            current = current.parent
+            depth += 1
+        else:
+            # Check if this is a namespace package (PEP 420)
+            # by looking if parent contains other packages
+            has_sibling_packages = (
+                any(
+                    (sibling / "__init__.py").exists()
+                    for sibling in current.parent.iterdir()
+                    if sibling.is_dir() and sibling != current
+                )
+                if current.parent.exists()
+                else False
+            )
+
+            if has_sibling_packages:
+                parts.append(current.name)
+                current = current.parent
+                depth += 1
+            else:
+                break
+
+    parts.reverse()
+    return ".".join(parts) if parts else stem
+
+
+def resolve_relative_import(
+    importing_file: Path,
+    module: str,
+    level: int,
+    project_root: Path | None = None,
+) -> str:
+    """
+    Resolve a relative import to an absolute module path.
+
+    Args:
+        importing_file: File containing the import
+        module: The module being imported (may be empty for "from . import x")
+        level: Number of dots (1 = ".", 2 = "..", etc.)
+        project_root: Optional project root
+
+    Returns:
+        Absolute module path
+    """
+    # Start from importing file's directory
+    current = importing_file.parent
+
+    # Go up 'level' directories (level=1 means same package)
+    for _ in range(level - 1):
+        if current.parent.exists():
+            current = current.parent
+
+    # Get the base package path
+    base_parts = []
+    temp = current
+    max_depth = 20
+    depth = 0
+
+    while temp.name and depth < max_depth:
+        # Stop at project root
+        if project_root and temp == project_root:
+            break
+
+        # Check for package indicators
+        init_exists = (temp / "__init__.py").exists()
+        at_project_root = (temp / "pyproject.toml").exists() or (temp / "setup.py").exists()
+
+        if at_project_root:
+            break
+
+        if init_exists or _is_namespace_package(temp):
+            base_parts.append(temp.name)
+            temp = temp.parent
+            depth += 1
+        else:
+            break
+
+    base_parts.reverse()
+
+    # Combine with the module being imported
+    if module:
+        return ".".join(base_parts + [module]) if base_parts else module
+    return ".".join(base_parts) if base_parts else ""
+
+
+def _is_namespace_package(path: Path) -> bool:
+    """Check if path is a PEP 420 namespace package."""
+    if not path.is_dir():
+        return False
+
+    # A namespace package contains subpackages but no __init__.py
+    has_init = (path / "__init__.py").exists()
+    if has_init:
+        return False
+
+    # Check for subpackages
+    return any(child.is_dir() and (child / "__init__.py").exists() for child in path.iterdir())
+
+
+def is_external_module(module: str) -> bool:
+    """Check if a module is from an external package."""
+    if not module:
+        return False
+
+    root_module = module.split(".")[0]
+    return root_module in KNOWN_EXTERNAL_PACKAGES
+
+
+def get_external_package(module: str) -> str | None:
+    """Get the external package name for a module."""
+    if not module:
+        return None
+
+    root_module = module.split(".")[0]
+    if root_module in KNOWN_EXTERNAL_PACKAGES:
+        return root_module
+    return None
+
+
+# =============================================================================
+# Cross-File Resolver
+# =============================================================================
+
+
+class CrossFileResolver:
+    """
+    Resolves types and symbols across multiple Python files.
+
+    Features:
+    - Multi-level inheritance with full transitive closure
+    - MRO (Method Resolution Order) computation for diamond inheritance
+    - src-layout project support
+    - External package detection
+    - Inherited field aggregation with deduplication
+
+    Usage:
+        resolver = CrossFileResolver()
+
+        # Add all parsed files
+        for parsed in parsed_files:
+            resolver.add_file(parsed)
+
+        # Build the resolution graph
+        resolver.resolve()
+
+        # Query resolved types
+        symbol = resolver.resolve_name("UserModel", in_file=some_path)
+    """
+
+    def __init__(self, project_root: Path | None = None):
+        """
+        Initialize the resolver.
+
+        Args:
+            project_root: Optional project root for module path inference
+        """
+        self._project_root = project_root
+        self._src_path: Path | None = None
+        self._parsed_files: dict[Path, ParsedFile] = {}
+        self._graph = ImportGraph()
+        self._resolved = False
+
+        # Detect src-layout
+        if project_root:
+            is_src_layout, src_path = detect_src_layout(project_root)
+            if is_src_layout:
+                self._src_path = src_path
+
+    def add_file(self, parsed: ParsedFile) -> None:
+        """Add a parsed file to the resolver."""
+        if not parsed.success:
+            return
+
+        self._parsed_files[parsed.path] = parsed
+        self._resolved = False
+
+        # Infer module path and map it
+        module_path = infer_module_path(parsed.path, self._project_root, self._src_path)
+        self._graph.module_to_file[module_path] = parsed.path
+
+    def resolve(self) -> ImportGraph:
+        """
+        Build the complete resolution graph.
+
+        This performs:
+        1. Symbol registration (all classes, functions)
+        2. Import resolution
+        3. Alias tracking
+        4. Multi-level inheritance chain building
+        5. MRO computation
+        6. Pydantic model detection through inheritance
+
+        Returns:
+            The completed ImportGraph
+        """
+        # Phase 1: Register all symbols
+        self._register_all_symbols()
+
+        # Phase 2: Resolve all imports
+        self._resolve_all_imports()
+
+        # Phase 3: Build inheritance graph (direct parents)
+        self._build_direct_inheritance()
+
+        # Phase 4: Compute transitive closure (all ancestors)
+        self._compute_inheritance_closure()
+
+        # Phase 5: Compute MRO for all classes
+        self._compute_all_mro()
+
+        # Phase 6: Propagate Pydantic model status
+        self._propagate_pydantic_status()
+
+        self._resolved = True
+        return self._graph
+
+    def _register_all_symbols(self) -> None:
+        """Register all symbols from all files."""
+        for file_path, parsed in self._parsed_files.items():
+            module_path = infer_module_path(file_path, self._project_root, self._src_path)
+
+            # Register classes
+            for cls in parsed.classes:
+                qualified_name = f"{module_path}.{cls.name}" if module_path else cls.name
+
+                # Check for direct Pydantic inheritance
+                is_direct_pydantic = any(base in PYDANTIC_BASE_CLASSES for base in cls.base_classes)
+
+                symbol = ResolvedSymbol(
+                    name=cls.name,
+                    qualified_name=qualified_name,
+                    kind="class",
+                    defined_in_file=file_path,
+                    defined_at_line=cls.location.line,
+                    is_pydantic_model=cls.is_pydantic_model or is_direct_pydantic,
+                    is_dataclass=cls.is_dataclass,
+                    base_classes=list(cls.base_classes),
+                    definition=cls,
+                )
+
+                self._graph.symbols[qualified_name] = symbol
+
+                # Also register by simple name for same-file resolution
+                # But don't overwrite if already exists (prefer qualified)
+                if cls.name not in self._graph.symbols:
+                    self._graph.symbols[cls.name] = symbol
+
+            # Register functions
+            for func in parsed.functions:
+                qualified_name = f"{module_path}.{func.name}" if module_path else func.name
+
+                self._graph.symbols[qualified_name] = ResolvedSymbol(
+                    name=func.name,
+                    qualified_name=qualified_name,
+                    kind="function",
+                    defined_in_file=file_path,
+                    defined_at_line=func.location.line,
+                    definition=func,
+                )
+
+    def _resolve_all_imports(self) -> None:
+        """Resolve imports in all files."""
+        for file_path, parsed in self._parsed_files.items():
+            resolved_imports: list[ResolvedImport] = []
+            name_mapping: dict[str, str] = {}
+
+            for imp in parsed.imports:
+                resolved_list = self._resolve_import(imp, file_path)
+                resolved_imports.extend(resolved_list)
+
+                # Build name mapping
+                for resolved in resolved_list:
+                    if resolved.resolved and resolved.target:
+                        name_mapping[resolved.local_name] = resolved.target.qualified_name
+                    elif resolved.is_external:
+                        # Map external imports to their full names
+                        name_mapping[resolved.local_name] = (
+                            f"{resolved.source_module}.{resolved.original_name}"
+                        )
+
+            self._graph.file_imports[file_path] = resolved_imports
+            self._graph.name_to_qualified[file_path] = name_mapping
+
+    def _resolve_import(
+        self,
+        imp: ParsedImport,
+        importing_file: Path,
+    ) -> list[ResolvedImport]:
+        """Resolve a single import statement."""
+        results: list[ResolvedImport] = []
+
+        # Handle relative imports
+        source_module = imp.module
+        if imp.is_relative:
+            source_module = resolve_relative_import(
+                importing_file, imp.module, imp.relative_level, self._project_root
+            )
+
+        # Check if external
+        is_external = is_external_module(source_module)
+
+        if imp.is_from_import:
+            # "from X import a, b, c"
+            for name in imp.names:
+                # Check if imported as alias
+                alias = imp.alias if len(imp.names) == 1 else None
+                local_name = alias or name
+
+                # Try to resolve the imported name
+                qualified_name = f"{source_module}.{name}" if source_module else name
+                target = self._graph.symbols.get(qualified_name)
+
+                results.append(
+                    ResolvedImport(
+                        local_name=local_name,
+                        original_name=name,
+                        source_module=source_module,
+                        resolved=target is not None,
+                        target=target,
+                        is_external=is_external,
+                    )
+                )
+        else:
+            # "import X" or "import X as Y"
+            local_name = imp.alias or source_module.split(".")[-1]
+
+            # Check if module itself is registered
+            target = self._graph.symbols.get(source_module)
+
+            results.append(
+                ResolvedImport(
+                    local_name=local_name,
+                    original_name=source_module,
+                    source_module=source_module,
+                    resolved=target is not None,
+                    target=target,
+                    is_external=is_external,
+                )
+            )
+
+        return results
+
+    def _build_direct_inheritance(self) -> None:
+        """Build direct inheritance relationships."""
+        for symbol in self._graph.symbols.values():
+            if symbol.kind != "class":
+                continue
+
+            resolved_bases = []
+            for base in symbol.base_classes:
+                # Try to find the base class
+                base_symbol = self._resolve_type_name(base, symbol.defined_in_file)
+                if base_symbol:
+                    resolved_bases.append(base_symbol.qualified_name)
+                elif base in PYDANTIC_BASE_CLASSES:
+                    # Keep Pydantic bases as-is for detection
+                    resolved_bases.append(base)
+                    symbol.is_pydantic_model = True
+                else:
+                    # Unknown base - might be external
+                    resolved_bases.append(base)
+
+            # Update base classes with resolved names
+            symbol.base_classes = resolved_bases
+
+            # Add to inheritance graph
+            self._graph.inheritance_graph[symbol.qualified_name] = resolved_bases
+
+            # Build reverse inheritance
+            for base in resolved_bases:
+                if base not in self._graph.reverse_inheritance:
+                    self._graph.reverse_inheritance[base] = []
+                self._graph.reverse_inheritance[base].append(symbol.qualified_name)
+
+    def _compute_inheritance_closure(self) -> None:
+        """Compute transitive closure of inheritance (all ancestors)."""
+        for symbol in self._graph.symbols.values():
+            if symbol.kind != "class":
+                continue
+
+            # BFS/DFS to find all ancestors
+            all_bases: set[str] = set()
+            visited: set[str] = set()
+            queue = list(symbol.base_classes)
+
+            while queue:
+                base = queue.pop(0)
+                if base in visited:
+                    continue
+                visited.add(base)
+                all_bases.add(base)
+
+                # Get parents of this base
+                base_symbol = self._graph.symbols.get(base)
+                if base_symbol and base_symbol.kind == "class":
+                    for parent in base_symbol.base_classes:
+                        if parent not in visited:
+                            queue.append(parent)
+
+                # Also check inheritance graph
+                if base in self._graph.inheritance_graph:
+                    for parent in self._graph.inheritance_graph[base]:
+                        if parent not in visited:
+                            queue.append(parent)
+
+            symbol.all_bases = list(all_bases)
+
+    def _compute_all_mro(self) -> None:
+        """Compute Method Resolution Order for all classes."""
+        for symbol in self._graph.symbols.values():
+            if symbol.kind != "class":
+                continue
+
+            mro = self._compute_mro(symbol.qualified_name)
+            symbol.mro = mro
+
+    def _compute_mro(self, class_name: str, visited: set[str] | None = None) -> list[str]:
+        """
+        Compute MRO using C3 linearization algorithm.
+
+        Simplified version that handles most cases.
+        """
+        if visited is None:
+            visited = set()
+
+        if class_name in visited:
+            return []  # Cycle detected
+
+        visited.add(class_name)
+
+        symbol = self._graph.symbols.get(class_name)
+        if not symbol or symbol.kind != "class":
+            return [class_name]
+
+        # Start with this class
+        mro = [class_name]
+
+        # Get parent MROs
+        parent_mros = []
+        for base in symbol.base_classes:
+            base_mro = self._compute_mro(base, visited.copy())
+            if base_mro:
+                parent_mros.append(base_mro)
+
+        # Add parents list
+        if symbol.base_classes:
+            parent_mros.append(list(symbol.base_classes))
+
+        # Merge using C3 linearization
+        while parent_mros:
+            # Find a good head (not in tail of any other list)
+            head = None
+            for mro_list in parent_mros:
+                if not mro_list:
+                    continue
+                candidate = mro_list[0]
+
+                # Check if candidate is in tail of any other list
+                in_tail = False
+                for other_list in parent_mros:
+                    if candidate in other_list[1:]:
+                        in_tail = True
+                        break
+
+                if not in_tail:
+                    head = candidate
+                    break
+
+            if head is None:
+                # No valid head found - inconsistent hierarchy
+                break
+
+            mro.append(head)
+
+            # Remove head from all lists
+            new_parent_mros = []
+            for mro_list in parent_mros:
+                if mro_list and mro_list[0] == head:
+                    mro_list = mro_list[1:]
+                if mro_list:
+                    new_parent_mros.append(mro_list)
+            parent_mros = new_parent_mros
+
+        return mro
+
+    def _propagate_pydantic_status(self) -> None:
+        """Propagate Pydantic model status through inheritance."""
+        # Mark classes whose ancestors include Pydantic bases
+        for symbol in self._graph.symbols.values():
+            if symbol.kind != "class" or symbol.is_pydantic_model:
+                continue
+
+            # Check if any ancestor is a Pydantic model
+            for base in symbol.all_bases:
+                if base in PYDANTIC_BASE_CLASSES:
+                    symbol.is_pydantic_model = True
+                    break
+
+                base_symbol = self._graph.symbols.get(base)
+                if base_symbol and base_symbol.is_pydantic_model:
+                    symbol.is_pydantic_model = True
+                    break
+
+    # =========================================================================
+    # Query Methods
+    # =========================================================================
+
+    def resolve_name(
+        self,
+        name: str,
+        in_file: Path | None = None,
+    ) -> ResolvedSymbol | None:
+        """
+        Resolve a name to its symbol.
+
+        Args:
+            name: The name to resolve
+            in_file: Optional file context for local name resolution
+
+        Returns:
+            ResolvedSymbol if found, None otherwise
+        """
+        if not self._resolved:
+            self.resolve()
+
+        return self._resolve_type_name(name, in_file)
+
+    def _resolve_type_name(
+        self,
+        name: str,
+        in_file: Path | None,
+    ) -> ResolvedSymbol | None:
+        """Internal resolution of a type name."""
+        # 1. Check if it's already a qualified name
+        if name in self._graph.symbols:
+            return self._graph.symbols[name]
+
+        # 2. Check file-local name mapping (import aliases)
+        if in_file and in_file in self._graph.name_to_qualified:
+            mapping = self._graph.name_to_qualified[in_file]
+            if name in mapping:
+                qualified = mapping[name]
+                return self._graph.symbols.get(qualified)
+
+        # 3. Check symbols defined in the same file
+        if in_file:
+            module_path = infer_module_path(in_file, self._project_root, self._src_path)
+            qualified = f"{module_path}.{name}" if module_path else name
+            if qualified in self._graph.symbols:
+                return self._graph.symbols[qualified]
+
+        # 4. Check by simple name (might be ambiguous, prefer local file)
+        candidates = []
+        for _qname, symbol in self._graph.symbols.items():
+            if symbol.name == name:
+                candidates.append(symbol)
+
+        if candidates:
+            # Prefer symbol from same file if available
+            if in_file:
+                for symbol in candidates:
+                    if symbol.defined_in_file == in_file:
+                        return symbol
+            return candidates[0]
+
+        return None
+
+    def resolve_symbol(self, name: str, in_file: Path | None = None) -> ResolvedSymbol | None:
+        """Resolve a symbol by name (alias for resolve_name)."""
+        return self.resolve_name(name, in_file)
+
+    def get_class_definition(self, name: str, in_file: Path | None = None) -> ParsedClass | None:
+        """Get the ParsedClass definition for a type name."""
+        symbol = self.resolve_name(name, in_file)
+        if symbol and symbol.kind == "class" and isinstance(symbol.definition, ParsedClass):
+            return symbol.definition
+        return None
+
+    def is_pydantic_model(self, name: str, in_file: Path | None = None) -> bool:
+        """Check if a type name refers to a Pydantic model."""
+        symbol = self.resolve_name(name, in_file)
+        return symbol.is_pydantic_model if symbol else False
+
+    def get_all_pydantic_models(self) -> dict[str, ParsedClass]:
+        """Get all Pydantic models in the project."""
+        if not self._resolved:
+            self.resolve()
+
+        models = {}
+        for _name, symbol in self._graph.symbols.items():
+            if symbol.is_pydantic_model and isinstance(symbol.definition, ParsedClass):
+                # Only include once per unique qualified name
+                if symbol.qualified_name not in models:
+                    models[symbol.qualified_name] = symbol.definition
+        return models
+
+    def get_import_aliases(self, file_path: Path) -> dict[str, str]:
+        """
+        Get import alias mapping for a file.
+
+        Returns:
+            Dict mapping local names to their original/qualified names
+        """
+        if not self._resolved:
+            self.resolve()
+
+        result = {}
+        if file_path in self._graph.file_imports:
+            for imp in self._graph.file_imports[file_path]:
+                if imp.local_name != imp.original_name:
+                    result[imp.local_name] = imp.original_name
+        return result
+
+    def get_model_fields(
+        self,
+        model_name: str,
+        in_file: Path | None = None,
+        include_inherited: bool = True,
+    ) -> list[dict]:
+        """
+        Get fields for a Pydantic model.
+
+        Uses MRO for correct field inheritance order and deduplication.
+
+        Args:
+            model_name: Name of the model class
+            in_file: File context for resolution
+            include_inherited: Whether to include fields from base classes
+
+        Returns:
+            List of field dicts with name, type, required, etc.
+        """
+        symbol = self.resolve_name(model_name, in_file)
+        if not symbol or symbol.kind != "class":
+            return []
+
+        cls = symbol.definition
+        if not isinstance(cls, ParsedClass):
+            return []
+
+        if not include_inherited:
+            # Only this class's fields
+            return self._class_fields_to_dicts(cls)
+
+        # Use MRO for correct inheritance order
+        all_fields: list[dict] = []
+        seen_names: set[str] = set()
+
+        # Walk MRO in reverse (base classes first)
+        mro = symbol.mro if symbol.mro else [symbol.qualified_name]
+
+        for class_name in reversed(mro):
+            class_symbol = self._graph.symbols.get(class_name)
+            if not class_symbol or not isinstance(class_symbol.definition, ParsedClass):
+                continue
+
+            class_def = class_symbol.definition
+            for f in class_def.fields:
+                if f.name not in seen_names:
+                    all_fields.append(self._field_to_dict(f))
+                    seen_names.add(f.name)
+                else:
+                    # Field override - update existing
+                    for i, existing in enumerate(all_fields):
+                        if existing["name"] == f.name:
+                            all_fields[i] = self._field_to_dict(f)
+                            break
+
+        return all_fields
+
+    def _class_fields_to_dicts(self, cls: ParsedClass) -> list[dict]:
+        """Convert class fields to dicts."""
+        return [self._field_to_dict(f) for f in cls.fields]
+
+    def _field_to_dict(self, f) -> dict:
+        """Convert a ParsedField to a dict."""
+        return {
+            "name": f.name,
+            "type_annotation": f.type_annotation,
+            "required": f.is_required,
+            "default": f.default_value,
+            "alias": f.alias,
+            "description": f.description,
+            "constraints": f.constraints,
+            "nested_model": f.nested_model_name,
+        }
+
+    def get_inheritance_chain(self, class_name: str, in_file: Path | None = None) -> list[str]:
+        """
+        Get the full inheritance chain for a class.
+
+        Returns:
+            List of all ancestor class names
+        """
+        symbol = self.resolve_name(class_name, in_file)
+        if symbol and symbol.kind == "class":
+            return list(symbol.all_bases)
+        return []
+
+    def get_mro(self, class_name: str, in_file: Path | None = None) -> list[str]:
+        """
+        Get the Method Resolution Order for a class.
+
+        Returns:
+            List of class names in MRO order
+        """
+        symbol = self.resolve_name(class_name, in_file)
+        if symbol and symbol.kind == "class":
+            return list(symbol.mro)
+        return []
+
+    def get_subclasses(self, class_name: str) -> list[str]:
+        """
+        Get all direct subclasses of a class.
+
+        Returns:
+            List of subclass qualified names
+        """
+        if not self._resolved:
+            self.resolve()
+
+        symbol = self.resolve_name(class_name, None)
+        if not symbol:
+            return []
+
+        return self._graph.reverse_inheritance.get(symbol.qualified_name, [])
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+
+def build_cross_file_resolver(
+    parsed_files: list[ParsedFile],
+    project_root: Path | None = None,
+) -> CrossFileResolver:
+    """
+    Build a cross-file resolver from parsed files.
+
+    Args:
+        parsed_files: List of successfully parsed files
+        project_root: Optional project root
+
+    Returns:
+        Configured and resolved CrossFileResolver
+    """
+    resolver = CrossFileResolver(project_root)
+
+    for parsed in parsed_files:
+        resolver.add_file(parsed)
+
+    resolver.resolve()
+    return resolver