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.
# How does project-a reach project-c?
codependix path project-a project-c
# How does one file import another?
codependix path src/modules/auth/auth.service.ts src/modules/users/user.entity.ts
codependix path AuthModule DatabaseModule
### 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:
| Flag | Purpose |
| ---- | ------- |
| `-f, --format <format>` | Output format: `markdown` (default), `json`, or `mermaid` |
| `--nx-projects` / `--no-nx-projects` | Toggle Nx workspace project dependency graph search |
| `--file-imports` / `--no-file-imports` | Toggle internal file-level import graph search |
| `--nestjs-modules` / `--no-nestjs-modules` | Toggle NestJS container module graph search |
| `--projects <names>` | Comma-separated project names or globs to search across |
| `-d, --directory <dir>` | Directory whose Nx workspace to read |
| `--include <globs>` / `--exclude <globs>` | Override configured project inclusion or exclusion globs |
| `--tags <tags>` | Comma-separated Nx project tags to filter by |
| `--config <path>` | Path to a specific `codependix.config.ts` |
### 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
| Graph | Scope | Answers |
| ----- | ----- | ------- |
| **Nx Neighborhood** | Project | What one project reaches (dependencies) and who breaks if it changes (dependents) |
| **Workspace graph** | Workspace | High-level architectural layering and cross-package relationships |
| **NestJS module graph** | Container | What modules the DI container wires together at runtime |
| **File import graph** | Project files | File-to-file import relationships, cycles, and local refactoring fan-out |
## 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:
```bash
# Check if any committed reports are stale without modifying files
codependix map --check reports
# Update all committed graphs across the workspace
codependix map --write
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.