Dependency Graphs: Understanding Package Relationships

The dependency_graph artifact gives AI a structured understanding of how packages, modules, and files relate to each other. Instead of scanning import statements across your entire codebase, the AI references a pre-built graph that shows dependency direction, depth, and scope.

Use this page when

• You want AI to understand package relationships, import chains, and module dependencies without scanning all files.
• You are using dependency_graph artifacts for upgrade planning, security analysis, refactoring scope, or architecture compliance.
• You need to configure graph depth, scope, module resolution, or regeneration triggers.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

What a Dependency Graph Contains

A dependency_graph artifact captures relationships at multiple levels:

External Package Dependencies

Third-party packages your project depends on:

• Direct dependencies and their versions
• Development-only dependencies
• Peer and optional dependencies
• Dependency tree depth (transitive dependencies)

Internal Package Dependencies

How packages within your monorepo or workspace depend on each other:

• Workspace member relationships
• Shared library consumers
• Build order implications
• Circular dependency detection

Module-Level Imports

How source files import from each other within a package:

• Import direction and frequency
• Re-export chains
• Barrel file structures
• Cross-boundary imports that may indicate architectural violations

Route Mappings

For web applications, how URL routes map to handler code:

• Route definitions to handler file mappings
• Middleware chains
• Route parameter dependencies
• API version groupings

How Dependency Graphs Are Built

Context Fabric builds dependency graphs from multiple sources depending on your technology stack:

Package Manifests

• package.json / package-lock.json — npm dependency tree
• Cargo.toml / Cargo.lock — Rust crate dependencies
• go.mod / go.sum — Go module dependencies
• pyproject.toml / requirements.txt — Python package dependencies

Rust Module Metadata

• mod declarations and use statements
• pub(crate) visibility boundaries
• Feature flag conditional compilation
• Workspace member relationships from root Cargo.toml

TypeScript Imports

• Static import and require statements
• Dynamic import() expressions
• Path alias resolution from tsconfig.json
• Re-export chains through barrel files

Route Mappings

• Next.js App Router file-system routes
• Axum router composition in app.rs
• Express/Koa route registrations
• OpenAPI spec endpoint definitions

How Dependency Graphs Reduce Prompt Size

When an engineer asks "what uses this package?" or "what breaks if I change this module?", the AI traditionally needs to scan import statements across potentially thousands of files. With a dependency graph, it references a single compact artifact.

A typical monorepo dependency graph fits in 2,000–5,000 tokens. The equivalent information from scanning all imports would cost 50,000–200,000 tokens and still miss transitive relationships.

Use Cases

Upgrade Planning

When you plan to upgrade a dependency, the AI uses the dependency graph to identify:

• Every direct consumer of the package
• Transitive consumers that may be affected
• Version constraint conflicts across workspace members
• Suggested upgrade order to minimize breakage

Security Analysis

When a vulnerability is disclosed in a dependency, the AI immediately identifies:

• Whether your project uses the affected package
• Which internal packages are exposed
• The shortest path from the vulnerability to your application entry points
• Whether the vulnerable code path is reachable in your configuration

Refactoring Scope

When you refactor a module, the AI uses the graph to determine:

• Every file that imports from the target module
• Whether the refactoring crosses package boundaries
• Which tests exercise the affected import paths
• The minimum set of changes needed for the refactoring

Architecture Compliance

The dependency graph reveals architectural violations:

• Circular dependencies between packages
• Layer violations (UI importing from infrastructure)
• Unauthorized cross-boundary imports
• Excessive coupling between modules

Shared Across Your Organization

The dependency graph is particularly valuable as a shared artifact because dependency relationships change infrequently. A single build serves the entire engineering team until a manifest file or import structure changes.

When 100 engineers independently ask about dependency relationships, they all receive answers from the same cached graph. No redundant scanning occurs.

When Dependency Graphs Regenerate

Regeneration triggers include:

• Package manifest changes (package.json, Cargo.toml, etc.)
• Lock file updates (dependency version resolution changes)
• New module declarations or import path changes
• Route registration modifications

Content-only changes within existing files do not trigger regeneration. The graph remains valid as long as the import and dependency structure is unchanged.

Configuration

You configure dependency_graph generation in your repository settings:

• Depth limit — How many levels of transitive dependencies to include
• Scope — External only, internal only, or both
• Module resolution — Whether to track file-level imports or only package-level
• Exclusion patterns — Skip test-only dependencies or development tools

Next steps

• Test Maps — Link tests to the source files they cover
• API Inventories — Document endpoints from route mappings

For AI systems

• Canonical terms: Keeptrusts, Codebase Context Fabric, dependency_graph artifact, package relationships, import chains, module dependencies, external packages, internal packages, route mappings, circular dependency detection.
• Feature/config names: dependency_graph artifact type, depth limit, scope (external/internal/both), module resolution (file-level/package-level), exclusion patterns, regeneration triggers (manifest changes, lock file updates, import path changes).
• Best next pages: API Inventories, File Summaries, Artifact Freshness.

For engineers

• Dependency graphs are built from: package.json/Cargo.toml/go.mod/pyproject.toml, use/import statements, route registrations, and path alias resolution.
• Regeneration triggers: manifest/lock file changes, new mod declarations, import path changes. Content-only changes within existing files do NOT trigger regeneration.
• Token savings: a typical monorepo graph fits in 2,000-5,000 tokens vs. 50,000-200,000 tokens for scanning all imports manually.
• Configure depth limit, scope, and exclusion patterns in repository settings.

For leaders

• Dependency graphs give immediate answers to upgrade impact, vulnerability exposure, and refactoring scope — questions that traditionally require hours of manual analysis.
• Security value: when a CVE is disclosed, the graph instantly identifies whether your project uses the affected package and which paths are reachable.
• Shared across the entire org: one graph build serves all engineers asking about dependency relationships.
• Architecture compliance: the graph reveals circular dependencies, layer violations, and unauthorized cross-boundary imports automatically.