Codependix Navigate

Navigating a codebase with codependix

Codependix builds and queries dependency graphs across Nx workspaces, NestJS containers, and file-level TypeScript and Python imports. When asking "how does X reach Y?", "what breaks if I change Z?", or "what does this package depend on?", use codependix commands to query relationships directly, or inspect committed graphs already on disk.

Command first: querying dependency paths

Reach for codependix path to trace directed dependency paths between two nodes without parsing diagrams or grepping source files by hand. Every invocation names the configuration with --config <path> — in this repository projects/configuration/codependix.config.ts — because nothing is searched for and there is no default.

# How does project-a reach project-c?
codependix path project-a project-c --config projects/configuration/codependix.config.ts

# How does one file import another?
codependix path src/modules/auth/auth.service.ts src/modules/users/user.entity.ts --config projects/configuration/codependix.config.ts

# What NestJS modules connect two modules in a container?
codependix path AuthModule DatabaseModule --config projects/configuration/codependix.config.ts

Path query flags and narrowing

Running across a full workspace can be expensive because it parses Nx projects, TypeScript ASTs, and container registrations across the entire monorepo. Use narrowing flags to scope the run and minimize execution time:

Path results

• Path found: Prints the shortest directed path connecting <from> to <to> (for example project-a → project-b → project-c).
• No path: Reports _No path connects "<from>" to "<to>"._ (or an empty list in JSON) and exits 0. A missing path is an answer, not an error.

When to read a committed diagram instead of running the CLI

Running the CLI builds graph representations from source files. Before running a command, check if the question is already answered by committed artifacts on disk:

1. Every package in the monorepo commits its own graphs. Look in any project's README.md under the ## 🕸️ Codependix section or between <!-- codependix:start name="..." --> markers.
2. Immediate blast radius (1 hop): The project's committed Nx Neighborhood diagram lists all immediate dependencies (what it reaches) and dependents (what breaks if its public API changes).
3. Internal file structure: The project's committed File import graph lists all file-to-file imports and isolated files within that project.
4. Container structure: The project's committed NestJS module graph lists wired container modules.
5. Whole-workspace structure: The repository root README.md carries the committed workspace graph.

Cost rule of thumb:

• Read README diagrams or JSON for single-hop dependencies, immediate blast radius, or local file layout (zero build cost, instant answer on disk).
• Run codependix path for multi-hop transitive paths, cross-project reachability, verifying unstaged changes, or generating machine-readable JSON.

The four graph types and their questions

Interpreting graph artifacts

Nx Neighborhood: blast radius

A Neighborhood covers one hop in each direction from the focal project (highlighted in diagrams):

• dependents is the blast radius of a breaking change: every listed project must build against the new shape. For breaking changes spanning deeper layers, walk outward neighborhood by neighborhood or run codependix path.
• dependencies is the allowed surface: A project may only import what is declared here.
• Edges marked implicit are Nx workspace configuration dependencies rather than code imports.

File import graph: refactoring and moves

Edges are strictly between files inside the same project:

• External packages and cross-project imports are excluded by design (they live in the Nx Neighborhood).
• isolatedFileNames is a shortlist to investigate, not dead code. An isolated file may be an entry point, an external export, or a configuration file.
• Cycles are real: An import cycle within a project produces runtime undefined bindings or initialization order bugs. Walk the cycle edges to locate where to decouple.
• Renaming a file? Edges pointing to the old relative path show the exact blast radius.

NestJS module graph: DI container wiring

Built by evaluating container modules:

• Global or ambient modules: Modules imported by nearly all others (for example core logging or configuration) have individual edges omitted to reduce visual noise; they are listed under ambientModuleNames and drawn with rounded corners.
• Dynamic wrapper modules: Private internal host modules created by forRoot or dynamic providers are collapsed into the declaring module.
• A missing module was never registered in the container hierarchy, meaning its exported providers are unavailable.

Confirming freshness before trusting committed graphs

A committed graph reflects the repository state at the last codependix map --write. To check whether committed graphs are up to date:

# Check if any committed reports are stale without modifying files
codependix map --check reports --config projects/configuration/codependix.config.ts

# Update all committed graphs across the workspace
codependix map --write --config projects/configuration/codependix.config.ts

If committed graphs are stale with respect to recent local edits, either re-run codependix map --write or use codependix path for real-time queries.