Cross-Module Dependency Graphs: Resolving Multi-File Symbol References

The Danger of Isolated File Edits

In single-file AI editing configurations:

• The Import Disconnect: Modifying a utility function's return type breaks caller functions in separate package subdirectories ^[1].
• Incomplete Refactoring: The agent updates the core module but overlooks test suites and API handlers that import the modified symbol.
• The Solution: Dependency Graph Analysis. We parse import statements across all project modules, building a directed graph where nodes represent files and edges represent import dependencies.

1. Building the Module Import Graph

To map cross-file dependencies:

• Extract Import Statements: Scan Python source files for import and from ... import statements.
• Construct Graph Adjacency Lists: Maintain directed edges mapping imported modules to target caller files.

2. Resolving Downstream Affected Files

The dependency graph parser identifies impacted modules:

1. Locate Target Node: Select the file being refactored (e.g. auth_service.py).
2. Traverse Dependents: Perform a Breadth-First Search (BFS) to retrieve all upstream files that depend on the target symbol.

Code Demo: Dependency Graph Compiler

Below is a Python implementation of a cross-module dependency graph parser. It extracts import statements, constructs dependency trees, and identifies downstream files affected by code changes.

import ast
import os
from typing import Dict, Set, List

class ModuleDependencyGraph:
    def __init__(self):
        # Maps file path to set of imported module paths
        self.dependencies: Dict[str, Set[str]] = {}
        # Maps module path to set of dependent files (reverse lookup)
        self.reverse_dependents: Dict[str, Set[str]] = {}

    def parse_file_imports(self, file_path: str, source_code: str):
        self.dependencies[file_path] = set()
        tree = ast.parse(source_code)

        for node in ast.walk(tree):
            if isinstance(node, ast.Import):
                for alias in node.names:
                    self._add_dependency(file_path, alias.name)
            elif isinstance(node, ast.ImportFrom):
                if node.module:
                    self._add_dependency(file_path, node.module)

    def _add_dependency(self, caller_file: str, imported_module: str):
        self.dependencies[caller_file].add(imported_module)
        if imported_module not in self.reverse_dependents:
            self.reverse_dependents[imported_module] = set()
        self.reverse_dependents[imported_module].add(caller_file)

    def get_affected_files(self, target_module: str) -> List[str]:
        affected = set()
        queue = [target_module]

        print(f"🌲 [Graph Search] Tracing downstream dependents for module: '{target_module}'")
        
        while queue:
            current = queue.pop(0)
            dependents = self.reverse_dependents.get(current, set())
            for dep in dependents:
                if dep not in affected:
                    affected.add(dep)
                    queue.append(dep)

        return list(affected)

if __name__ == "__main__":
    graph = ModuleDependencyGraph()

    # Mock codebase files and their import statements
    files_mock = {
        "services/auth.py": "import utils.crypto\nimport models.user",
        "api/routes.py": "import services.auth\nimport utils.logger",
        "tests/test_auth.py": "import services.auth",
        "main.py": "import api.routes"
    }

    print("🛡️ Building Cross-Module Dependency Graph...")
    print("---------------------------------------------")

    for path, code in files_mock.items():
        graph.parse_file_imports(path, code)

    # Resolve files affected if 'services.auth' is refactored
    target = "services.auth"
    impacted = graph.get_affected_files(target)

    print(f"\n📈 --- Downstream Impact Analysis for '{target}' ---")
    print(f"Total Affected Files: {len(impacted)}")
    for f in impacted:
        print(f"   ⚠️ File requires inspection/refactoring: {f}")

Dependency Graph Takeaways

• Map Imports Before Editing: Parse project import statements into a directed graph before performing codebase modifications.
• Use BFS Traversal: Execute Breadth-First Search traversals to capture multi-level downstream dependencies.
• Audit Import Signatures: Verify that call sites in caller files match updated module function signatures. ^[2]

Antithesis & Production Trade-Offs: When NOT to Use This Architecture

Even a high-throughput Architecture, Autocoding architecture introduces non-trivial operational complexity. Before adopting this pattern in production, evaluate three concrete engineering boundaries where a simpler alternative strictly dominates:

1. Low-Throughput / Single-Node Workloads ($< 50 ext{ req/s}$): If your service operates well below saturation on a single vertical instance and does not face strict multi-tenant tail-latency SLAs (p99 < 50 ms), the bookkeeping overhead of two-tier state partitioning, canonical digest hashing, and sliding-window circuit breakers adds cognitive and operational cost without measurable user-facing gains. A single monolithic transaction boundary with standard database constraints is simpler to debug and operate.
2. Hard Real-Time Ultra-Low-Latency Paths ($< 50,\mu ext{s}$ Budget): When operating inside kernel-bypass networking, L1/L2 cache-pinned ring buffers, or per-packet hardware data planes, any dynamic heap allocation, cryptographic SHA-256 digest computation, or asynchronous context switch violates the nanosecond/microsecond budget. In those regimes, pre-compute static lookup tables at control-plane configuration time and keep the hot path strictly zero-allocation.
3. Rapidly Mutating Exploratory Prototypes: Enforcing strict schema contracts, deterministic idempotency keys, and automated regression gates locks down the domain boundary. During week-one exploratory product discovery—where underlying data models change daily and zero real customer capital or tenant PII is at risk—defer heavy verification harnesses until the core workflow contract stabilizes.

References & Further Reading

1. Lamport, L. (1978). Time, Clocks, and the Ordering of Events in a Distributed System. CACM. https://lamport.azurewebsites.net/pubs/time-clocks.pdf ↩︎
2. Gilbert, S., & Lynch, N. (2002). Brewer's Conjecture and the Feasibility of Consistent, Available, Partition-Tolerant Web Services. ACM SIGACT News. https://web.mit.edu/6.033/www/papers/p80-gilbert.pdf ↩︎
3. OpenTelemetry Authors (2024). OpenTelemetry Specification. CNCF. https://opentelemetry.io/docs/specs/otel/ ↩︎