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

apisec_code_bolt/parsing/python/router_registry.py

@@ -0,0 +1,806 @@
+"""
+Router registry for tracking FastAPI/Starlette routers and their relationships.
+
+This module handles:
+- Tracking router variable definitions (app = FastAPI(), router = APIRouter())
+- Tracking include_router() calls with prefix resolution
+- Building the final router tree with merged prefixes
+- Resolving route paths to their final URLs
+- Resolving constant-based prefixes (settings.PREFIX, config.api_prefix)
+
+CRITICAL: This enables correct path resolution in multi-file FastAPI applications
+where routers are defined in one file and included with prefixes in another.
+
+PHILOSOPHY: Even if prefix values CAN be overridden at runtime, resolve the
+default/static value. This captures the most common deployment configuration.
+"""
+
+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 ParsedAssignment, ParsedFile
+    from .constant_resolver import ConstantResolver
+
+
+# =============================================================================
+# Data Types
+# =============================================================================
+
+
+@dataclass
+class RouterDefinition:
+    """Definition of a router or app variable."""
+
+    name: str  # Variable name (e.g., "app", "router", "user_router")
+    file_path: Path
+    line: int
+
+    # What type is it?
+    router_type: str  # "FastAPI", "APIRouter", "Starlette"
+
+    # Constructor arguments
+    prefix: str = ""  # For APIRouter(prefix="/api")
+    tags: list[str] = field(default_factory=list)
+
+    # Dependencies declared on the constructor (e.g. APIRouter(dependencies=[...]))
+    constructor_dependencies: list[str] = field(default_factory=list)
+
+    # Qualified name for cross-file reference
+    qualified_name: str = ""
+
+    # Is this a re-assignment?
+    source_router: str | None = None  # For router = other_router
+
+
+@dataclass
+class RouterInclusion:
+    """Record of an include_router() call."""
+
+    # Where the inclusion happens
+    file_path: Path
+    line: int
+
+    # The parent (app/router being added to)
+    parent_var: str
+
+    # The router being included
+    included_router: str  # Variable name or module.var reference
+    included_router_qualified: str | None = None  # Resolved qualified name
+
+    # Arguments to include_router
+    prefix: str = ""  # Path prefix to add
+    tags: list[str] = field(default_factory=list)
+    dependencies: list[str] = field(default_factory=list)
+
+    # Resolution status
+    resolved: bool = False
+
+
+@dataclass
+class RouterNode:
+    """Node in the router tree."""
+
+    definition: RouterDefinition
+
+    # Parent router (None for root FastAPI apps)
+    parent: RouterNode | None = None
+
+    # Included routers
+    children: list[RouterNode] = field(default_factory=list)
+
+    # Computed full prefix (including all parent prefixes)
+    computed_prefix: str = ""
+
+    # All tags (inherited + own)
+    computed_tags: list[str] = field(default_factory=list)
+
+    # Accumulated dependency function names from all ancestor include_router()
+    # calls.  For example, if a parent router is included with
+    # ``dependencies=[Depends(get_current_user)]``, every child route
+    # inherits ``["get_current_user"]``.
+    computed_dependencies: list[str] = field(default_factory=list)
+
+
+@dataclass
+class RouterTree:
+    """Complete router tree for a project."""
+
+    # All router definitions by qualified name
+    routers: dict[str, RouterDefinition] = field(default_factory=dict)
+
+    # All inclusions
+    inclusions: list[RouterInclusion] = field(default_factory=list)
+
+    # Root nodes (FastAPI apps)
+    roots: list[RouterNode] = field(default_factory=list)
+
+    # Variable name to qualified name mapping per file
+    var_to_qualified: dict[Path, dict[str, str]] = field(default_factory=dict)
+
+
+# =============================================================================
+# Router Registry
+# =============================================================================
+
+
+class RouterRegistry:
+    """
+    Tracks router definitions and inclusions across a project.
+
+    Supports resolving constant-based prefixes like:
+    - settings.API_PREFIX
+    - config.prefix
+    - os.getenv("PREFIX", "/api")
+
+    Usage:
+        registry = RouterRegistry()
+
+        # Add parsed files
+        for parsed in parsed_files:
+            registry.process_file(parsed)
+
+        # Optionally set constant resolver for config values
+        registry.set_constant_resolver(constant_resolver)
+
+        # Build the router tree
+        tree = registry.build_tree()
+
+        # Get the full prefix for a route
+        full_path = registry.resolve_path(router_var, route_path, file_path)
+    """
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize the registry."""
+        self._project_root = project_root
+        self._routers: dict[str, RouterDefinition] = {}
+        self._inclusions: list[RouterInclusion] = []
+        self._var_to_qualified: dict[Path, dict[str, str]] = {}
+        self._tree: RouterTree | None = None
+        self._import_mappings: dict[Path, dict[str, str]] = {}
+        self._constant_resolver: ConstantResolver | None = None
+
+    def set_constant_resolver(self, resolver: ConstantResolver) -> None:
+        """Set a constant resolver for resolving config-based prefixes."""
+        self._constant_resolver = resolver
+
+    def process_file(self, parsed: ParsedFile) -> None:
+        """Process a parsed file to extract router information."""
+        if not parsed.success:
+            return
+
+        file_path = parsed.path
+        self._var_to_qualified[file_path] = {}
+        self._import_mappings[file_path] = {}
+
+        # Build import mappings first
+        self._build_import_mappings(parsed)
+
+        # Find router definitions in assignments
+        for assign in parsed.assignments:
+            router_def = self._extract_router_definition(assign, file_path)
+            if router_def:
+                qualified = self._make_qualified_name(router_def.name, file_path)
+                router_def.qualified_name = qualified
+                self._routers[qualified] = router_def
+                self._var_to_qualified[file_path][router_def.name] = qualified
+
+        # Find include_router calls
+        for call in parsed.call_sites:
+            inclusion = self._extract_router_inclusion(call, file_path)
+            if inclusion:
+                self._inclusions.append(inclusion)
+
+    def _build_import_mappings(self, parsed: ParsedFile) -> None:
+        """Build import alias mappings for the file."""
+        file_path = parsed.path
+        mappings = {}
+
+        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
+                    mappings[local_name] = f"{imp.module}.{name}" if imp.module else name
+            else:
+                local_name = imp.alias or imp.module.split(".")[-1]
+                mappings[local_name] = imp.module
+
+        self._import_mappings[file_path] = mappings
+
+    def _extract_router_definition(
+        self,
+        assign: ParsedAssignment,
+        file_path: Path,
+    ) -> RouterDefinition | None:
+        """Extract router definition from an assignment."""
+        if assign.source_type != "call":
+            return None
+
+        called = assign.source_call or ""
+
+        # Resolve aliases
+        resolved = self._resolve_call_name(called, file_path)
+
+        # Check for router types
+        router_type = None
+        if resolved in {"FastAPI", "fastapi.FastAPI", "fastapi.applications.FastAPI"}:
+            router_type = "FastAPI"
+        elif resolved in {"APIRouter", "fastapi.APIRouter", "fastapi.routing.APIRouter"}:
+            router_type = "APIRouter"
+        elif resolved in {"Starlette", "starlette.applications.Starlette"}:
+            router_type = "Starlette"
+        elif resolved in {"Router", "starlette.routing.Router"}:
+            router_type = "Router"
+
+        if not router_type:
+            return None
+
+        # Extract constructor arguments
+        source = assign.value_source or ""
+        prefix = self._extract_string_kwarg(source, "prefix")
+        tags = self._extract_list_kwarg(source, "tags")
+
+        # Extract constructor-level dependencies (e.g. APIRouter(dependencies=[...]))
+        constructor_deps: list[str] = []
+        dep_match = re.findall(r"Depends\s*\(\s*([\w.]+)\s*\)", source)
+        if dep_match and "dependencies" in source:
+            constructor_deps = [f"Depends({d})" for d in dep_match]
+
+        return RouterDefinition(
+            name=assign.target,
+            file_path=file_path,
+            line=assign.location.line,
+            router_type=router_type,
+            prefix=prefix,
+            tags=tags,
+            constructor_dependencies=constructor_deps,
+        )
+
+    def _extract_router_inclusion(
+        self,
+        call,
+        file_path: Path,
+    ) -> RouterInclusion | None:
+        """Extract include_router call information."""
+        # Check if this is an include_router call
+        callee = call.callee_name
+        if not callee.endswith("include_router"):
+            return None
+
+        # Extract parent router name
+        parts = callee.rsplit(".", 1)
+        parent_var = parts[0] if len(parts) > 1 else ""
+
+        if not parent_var:
+            return None
+
+        # Extract the router being included (first argument)
+        included_router = ""
+        prefix = ""
+        tags: list[str] = []
+        dependencies: list[str] = []
+
+        for arg in call.arguments:
+            if arg.position == 0 or arg.name == "router":
+                included_router = arg.variable_name or arg.expression_text or ""
+            elif arg.name == "prefix":
+                prefix = self._extract_string_value(arg, file_path)
+            elif arg.name == "tags":
+                tags = self._extract_list_value(arg)
+            elif arg.name == "dependencies":
+                dependencies = self._extract_list_value(arg)
+
+        if not included_router:
+            return None
+
+        # Try to resolve qualified name
+        qualified = self._resolve_included_router(included_router, file_path)
+
+        return RouterInclusion(
+            file_path=file_path,
+            line=call.location.line,
+            parent_var=parent_var,
+            included_router=included_router,
+            included_router_qualified=qualified,
+            prefix=prefix,
+            tags=tags,
+            dependencies=dependencies,
+        )
+
+    def _resolve_call_name(self, name: str, file_path: Path) -> str:
+        """Resolve a call name using import mappings."""
+        mappings = self._import_mappings.get(file_path, {})
+
+        parts = name.split(".")
+        if parts[0] in mappings:
+            resolved_first = mappings[parts[0]]
+            if len(parts) > 1:
+                return f"{resolved_first}.{'.'.join(parts[1:])}"
+            return resolved_first
+
+        return name
+
+    def _resolve_import_reference(self, ref: str, file_path: Path) -> str | None:
+        """Resolve a module.var reference to a qualified name."""
+        mappings = self._import_mappings.get(file_path, {})
+
+        parts = ref.split(".", 1)
+        if parts[0] in mappings:
+            module = mappings[parts[0]]
+            if len(parts) > 1:
+                return f"{module}.{parts[1]}"
+            return module
+
+        return None
+
+    def _resolve_included_router(
+        self,
+        included_router: str,
+        file_path: Path,
+    ) -> str | None:
+        """Resolve an included router reference to its qualified name.
+
+        Tries three strategies in order:
+        1. Dotted reference (``module.router``) — resolve via imports
+        2. Local variable defined in the same file (``my_router = APIRouter()``)
+        3. Import alias (``from views import router as my_router``) — resolve
+           the import to a module-qualified name then match against known
+           routers registered from other files.
+        """
+        if "." in included_router:
+            return self._resolve_import_reference(included_router, file_path)
+
+        # Local variable defined in this file
+        if file_path in self._var_to_qualified:
+            qualified = self._var_to_qualified[file_path].get(included_router)
+            if qualified:
+                return qualified
+
+        # Import alias — the variable is imported, not locally defined.
+        # _import_mappings maps the local name to a module-qualified path
+        # (e.g. "ai_router" → "dispatch.ai.prompt.views.router").  We need
+        # to find the matching entry in _routers which uses file-system
+        # qualified names (e.g. "src.dispatch.ai.prompt.views.router").
+        mappings = self._import_mappings.get(file_path, {})
+        module_qualified = mappings.get(included_router)
+        if module_qualified:
+            matched = self._match_module_to_router(module_qualified)
+            if matched:
+                return matched
+
+        return None
+
+    def _match_module_to_router(self, module_qualified: str) -> str | None:
+        """Match a Python module path to a registered router's qualified name.
+
+        The registry keys are file-system based (``src.dispatch.auth.views.router``)
+        while import mappings produce module paths (``dispatch.auth.views.router``).
+        We match by checking if any registered router's qualified name ends with
+        the module path, handling the ``src.`` / ``src/`` prefix difference.
+        """
+        # Exact match first (unlikely but cheap)
+        if module_qualified in self._routers:
+            return module_qualified
+
+        # Suffix match: "dispatch.auth.views.router" matches
+        # "src.dispatch.auth.views.router"
+        suffix = f".{module_qualified}"
+        for qualified_name in self._routers:
+            if qualified_name.endswith(suffix) or qualified_name == module_qualified:
+                return qualified_name
+
+        return None
+
+    def _make_qualified_name(self, var_name: str, file_path: Path) -> str:
+        """Create a qualified name for a variable."""
+        # Use file path as module identifier
+        rel_path = file_path
+        if self._project_root and file_path.is_relative_to(self._project_root):
+            rel_path = file_path.relative_to(self._project_root)
+
+        module = str(rel_path.with_suffix("")).replace("/", ".").replace("\\", ".")
+        return f"{module}.{var_name}"
+
+    def _extract_string_kwarg(self, source: str, key: str) -> str:
+        """Extract a string keyword argument from source code."""
+        import re
+
+        pattern = rf'{key}\s*=\s*["\']([^"\']*)["\']'
+        match = re.search(pattern, source)
+        return match.group(1) if match else ""
+
+    def _extract_list_kwarg(self, source: str, key: str) -> list[str]:
+        """Extract a list keyword argument from source code."""
+        import re
+
+        pattern = rf"{key}\s*=\s*\[([^\]]*)\]"
+        match = re.search(pattern, source)
+        if not match:
+            return []
+
+        items = match.group(1)
+        # Extract quoted strings
+        strings = re.findall(r'["\']([^"\']*)["\']', items)
+        return strings
+
+    def _extract_string_value(self, arg, file_path: Path | None = None) -> str:
+        """
+        Extract string value from a call argument.
+
+        Handles:
+        - Literal strings: "/api"
+        - Variable references: PREFIX (resolved via constant resolver)
+        - Attribute access: settings.PREFIX (resolved via constant resolver)
+        - Env vars with defaults: os.getenv("PREFIX", "/api") -> "/api"
+        """
+        # 1. Direct literal value
+        if arg.literal_value and isinstance(arg.literal_value, str):
+            return arg.literal_value
+
+        if arg.expression_text:
+            expr = arg.expression_text.strip()
+
+            # 2. Try to extract literal string from expression
+            string_match = re.search(r'^["\']([^"\']*)["\']$', expr)
+            if string_match:
+                return string_match.group(1)
+
+            # 3. Try constant resolver for variable/attribute access
+            if self._constant_resolver:
+                resolved = self._constant_resolver.resolve(expr, file_path)
+                if resolved:
+                    return resolved.value
+
+            # 4. Try to extract default from os.getenv
+            env_match = re.search(
+                r'(?:os\.)?(?:getenv|environ\.get)\s*\(\s*["\'][^"\']+["\']\s*,\s*["\']([^"\']*)["\']',
+                expr,
+            )
+            if env_match:
+                return env_match.group(1)
+
+            # 5. Fallback: try to extract any string in the expression
+            fallback_match = re.search(r'["\']([^"\']*)["\']', expr)
+            if fallback_match:
+                return fallback_match.group(1)
+
+        # 6. Try variable name resolution
+        if arg.variable_name and self._constant_resolver:
+            resolved = self._constant_resolver.resolve(arg.variable_name, file_path)
+            if resolved:
+                return resolved.value
+
+        return ""
+
+    def _extract_list_value(self, arg) -> list[str]:
+        """Extract list value from a call argument.
+
+        Handles three representations:
+        1. Actual Python list in literal_value
+        2. String-encoded list in literal_value (e.g. ``'[Depends(func)]'``)
+        3. expression_text containing a list expression
+        """
+        # Real Python list
+        if isinstance(arg.literal_value, list):
+            return [str(v) for v in arg.literal_value]
+
+        # Pick the best raw text to parse
+        raw = ""
+        if isinstance(arg.literal_value, str) and arg.literal_value.strip().startswith("["):
+            raw = arg.literal_value
+        elif arg.expression_text and str(arg.expression_text) not in ("None", ""):
+            raw = str(arg.expression_text)
+
+        if raw:
+            # Quoted strings (tags, etc.)
+            strings = re.findall(r'["\']([^"\']*)["\']', raw)
+            if strings:
+                return strings
+            # Depends() expressions (dependencies lists)
+            depends = re.findall(r"Depends\s*\(\s*([\w.]+)\s*\)", raw)
+            if depends:
+                return [f"Depends({d})" for d in depends]
+
+        return []
+
+    # =========================================================================
+    # Tree Building
+    # =========================================================================
+
+    def build_tree(self) -> RouterTree:
+        """Build the complete router tree."""
+        tree = RouterTree(
+            routers=dict(self._routers),
+            inclusions=list(self._inclusions),
+            var_to_qualified=dict(self._var_to_qualified),
+        )
+
+        # Deferred resolution: re-resolve inclusions whose qualified name
+        # couldn't be determined during process_file() because the target
+        # router's file hadn't been processed yet.
+        for inclusion in self._inclusions:
+            if inclusion.included_router_qualified is None:
+                inclusion.included_router_qualified = self._resolve_included_router(
+                    inclusion.included_router, inclusion.file_path
+                )
+
+        # Create nodes for all routers
+        nodes: dict[str, RouterNode] = {}
+        for qualified, router_def in self._routers.items():
+            nodes[qualified] = RouterNode(
+                definition=router_def,
+                computed_prefix=router_def.prefix,
+                computed_tags=list(router_def.tags),
+            )
+
+        # Index inclusions by child for the propagation pass
+        inclusions_by_child: dict[str, RouterInclusion] = {}
+
+        # Resolve inclusions and build parent-child relationships
+        for inclusion in self._inclusions:
+            parent_qualified = self._resolve_parent(inclusion)
+            child_qualified = inclusion.included_router_qualified
+
+            if not parent_qualified or not child_qualified:
+                continue
+
+            parent_node = nodes.get(parent_qualified)
+            child_node = nodes.get(child_qualified)
+
+            if not parent_node or not child_node:
+                continue
+
+            # Set up relationship
+            child_node.parent = parent_node
+            parent_node.children.append(child_node)
+
+            # Compute full prefix
+            child_node.computed_prefix = self._join_paths(
+                parent_node.computed_prefix,
+                inclusion.prefix,
+                child_node.definition.prefix,
+            )
+
+            # Merge tags
+            child_node.computed_tags = (
+                parent_node.computed_tags + inclusion.tags + child_node.definition.tags
+            )
+
+            # Propagate dependencies — parent's accumulated deps + this
+            # inclusion's own deps flow to all routes under the child.
+            inclusion_dep_names = self._parse_depends_names(inclusion.dependencies)
+            child_node.computed_dependencies = (
+                list(parent_node.computed_dependencies) + inclusion_dep_names
+            )
+
+            inclusion.resolved = True
+            inclusions_by_child[child_qualified] = inclusion
+
+        # Find root nodes (no parent)
+        for node in nodes.values():
+            if node.parent is None:
+                tree.roots.append(node)
+
+        # Propagate prefixes and dependencies down the tree.  The initial
+        # assignment above only uses the parent's state at processing time,
+        # which may be incomplete for deeply nested trees.  A top-down pass
+        # from each root ensures correct accumulation.
+        for root in tree.roots:
+            self._propagate_tree(root, inclusions_by_child)
+
+        self._tree = tree
+        return tree
+
+    def _resolve_parent(self, inclusion: RouterInclusion) -> str | None:
+        """Resolve the parent router's qualified name."""
+        file_path = inclusion.file_path
+        parent_var = inclusion.parent_var
+
+        # Check local mappings first
+        if file_path in self._var_to_qualified:
+            if parent_var in self._var_to_qualified[file_path]:
+                return self._var_to_qualified[file_path][parent_var]
+
+        # Try as qualified name directly
+        if parent_var in self._routers:
+            return parent_var
+
+        return None
+
+    def _join_paths(self, *parts: str) -> str:
+        """Join path parts, handling slashes correctly."""
+        result = ""
+        for part in parts:
+            if not part:
+                continue
+            part = part.strip("/")
+            if not part:
+                continue
+            result = f"{result}/{part}" if result else part
+        return f"/{result}" if result else "/"
+
+    @staticmethod
+    def _parse_depends_names(raw_deps: list[str]) -> list[str]:
+        """Extract function names from ``Depends(func)`` expressions.
+
+        Handles raw strings like ``"Depends(get_current_user)"`` as well as
+        plain function names.
+        """
+        names: list[str] = []
+        for dep in raw_deps:
+            match = re.match(r"Depends\s*\(\s*(\w[\w.]*)\s*\)", dep)
+            if match:
+                names.append(match.group(1))
+            elif dep and re.match(r"^[\w.]+$", dep):
+                names.append(dep)
+        return names
+
+    def _propagate_tree(
+        self,
+        node: RouterNode,
+        inclusions_by_child: dict[str, RouterInclusion],
+    ) -> None:
+        """Recursively recompute prefixes and dependencies top-down.
+
+        This ensures deeply nested routers get the full accumulated state
+        from all ancestors, regardless of the order inclusions were processed.
+        """
+        for child in node.children:
+            child_q = child.definition.qualified_name
+            inclusion = inclusions_by_child.get(child_q)
+
+            # Recompute prefix from the (now-stable) parent
+            child.computed_prefix = self._join_paths(
+                node.computed_prefix,
+                inclusion.prefix if inclusion else "",
+                child.definition.prefix,
+            )
+
+            # Recompute tags
+            child.computed_tags = (
+                list(node.computed_tags)
+                + (inclusion.tags if inclusion else [])
+                + list(child.definition.tags)
+            )
+
+            # Recompute dependencies: parent's accumulated + inclusion-level + constructor-level
+            inclusion_dep_names = (
+                self._parse_depends_names(inclusion.dependencies) if inclusion else []
+            )
+            constructor_dep_names = self._parse_depends_names(
+                child.definition.constructor_dependencies
+            )
+            child.computed_dependencies = (
+                list(node.computed_dependencies) + inclusion_dep_names + constructor_dep_names
+            )
+
+            self._propagate_tree(child, inclusions_by_child)
+
+    # =========================================================================
+    # Query Methods
+    # =========================================================================
+
+    def resolve_path(
+        self,
+        router_var: str,
+        route_path: str,
+        file_path: Path,
+    ) -> str:
+        """
+        Resolve a route path to its final URL.
+
+        Args:
+            router_var: The router variable name (e.g., "router", "app")
+            route_path: The path from the decorator (e.g., "/users")
+            file_path: The file where the route is defined
+
+        Returns:
+            The fully resolved path with all prefixes applied
+        """
+        if not self._tree:
+            self.build_tree()
+
+        # Find the router
+        qualified = None
+        if file_path in self._var_to_qualified:
+            qualified = self._var_to_qualified[file_path].get(router_var)
+
+        if not qualified:
+            # Return path as-is
+            return route_path
+
+        # Find the node
+        for root in self._tree.roots:
+            node = self._find_node(root, qualified)
+            if node:
+                return self._join_paths(node.computed_prefix, route_path)
+
+        return route_path
+
+    def _find_node(self, node: RouterNode, qualified: str) -> RouterNode | None:
+        """Find a node by qualified name."""
+        if node.definition.qualified_name == qualified:
+            return node
+
+        for child in node.children:
+            found = self._find_node(child, qualified)
+            if found:
+                return found
+
+        return None
+
+    def get_router_dependencies(
+        self,
+        router_var: str,
+        file_path: Path,
+    ) -> list[str]:
+        """Return the accumulated dependency names for a router.
+
+        These are the dependency function names declared via
+        ``dependencies=[Depends(...)]`` on ``include_router()`` calls in the
+        ancestry chain.  They apply to every route under this router.
+        """
+        if not self._tree:
+            self.build_tree()
+
+        qualified = None
+        if file_path in self._var_to_qualified:
+            qualified = self._var_to_qualified[file_path].get(router_var)
+
+        if not qualified:
+            return []
+
+        for root in self._tree.roots:
+            node = self._find_node(root, qualified)
+            if node:
+                return list(node.computed_dependencies)
+
+        return []
+
+    def get_router_by_var(self, var_name: str, file_path: Path) -> RouterDefinition | None:
+        """Get router definition by variable name in a file."""
+        if file_path in self._var_to_qualified:
+            qualified = self._var_to_qualified[file_path].get(var_name)
+            if qualified:
+                return self._routers.get(qualified)
+        return None
+
+    def get_all_routers(self) -> dict[str, RouterDefinition]:
+        """Get all registered routers."""
+        return dict(self._routers)
+
+    def get_root_apps(self) -> list[RouterDefinition]:
+        """Get all root FastAPI/Starlette applications."""
+        return [r for r in self._routers.values() if r.router_type in {"FastAPI", "Starlette"}]
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+
+def build_router_registry(
+    parsed_files: list[ParsedFile],
+    project_root: Path | None = None,
+) -> RouterRegistry:
+    """
+    Build a router registry from parsed files.
+
+    Args:
+        parsed_files: List of successfully parsed files
+        project_root: Optional project root for path resolution
+
+    Returns:
+        Configured RouterRegistry with tree built
+    """
+    registry = RouterRegistry(project_root)
+
+    for parsed in parsed_files:
+        registry.process_file(parsed)
+
+    registry.build_tree()
+    return registry