Running a codependix export

Codependix reads what each project in an Nx workspace depends on and renders it four ways — the Nx project graph, a NestJS project's module graph, a TypeScript project's file-level import graph, and a Python project's — then delivers each one to whichever destinations the configuration names for that project: a JSON file, a Markdown anchor block spliced into an existing file, or both.

The configuration decides everything

There is no flag that selects a graph type, and no per-graph-type subcommand. Which graphs run, for which projects, and where each export lands is entirely a function of codependix.config.ts. Looking for --nestjs, --imports, or --only nx is looking for something that does not exist.

The corollary is the failure mode worth learning first:

A configuration that selects no project resolves every graph type for every project to target: "none" and produces nothing. The run succeeds, exits 0, logs that every configured export is current, and writes no files — because nothing was configured. That is correct behavior, not a bug.

So a --write that wrote nothing is a configuration question, never a debugging one. Before looking for a defect, confirm in this order:

1. The --config file is the one you meant. The flag is required and its file must exist, so a run naming none or a missing file fails loudly rather than writing nothing — but a file that is the wrong one reads exactly like an empty one.
2. The graph types you expected carry a target other than "none", which is what every unset target defaults to.
3. The projects you expected match the configured include globs and no exclude glob. include defaults to nothing, so a configuration that never names one selects no project at all — the run warns, and still exits zero.

The codependix-configure skill covers all three.

One --write, and two things --check can gate

--check takes a comma-separated set, and naming the set is what selects which finding fails the run.

The two --check names exist because the findings belong on opposite sides of a pull request. A broken boundary is caused by the branch and fixed by the branch, so it gates every branch. A stale export moves with the workspace it describes, so gating it on a branch fails every branch that changed a project graph rather than anything the branch did. reports is deliberately spelled the same as callidescope's and codometer's, because it is the same finding.

Combinations:

• --write --check boundaries is legal — a boundary has no destination to be stale.
• --check boundaries also accepts --format, --json-output, and --markdown-output, which print its findings as a report — see The boundary report below.
• --write --check reports is refused — an export cannot be stale in the run that just wrote it.
• A bare --check, or one whose value is only commas, is refused. Read as "gate nothing" it would be a gate that cannot fail. If a run is rejected with --check needs a value, the fix is to name the set, not to drop the flag.
• Naming neither --check nor --write is asked which was meant, as a three-item menu. No mode is ever inferred and no default write happens.

An agent should always name the mode explicitly. There is no flag that suppresses the prompt, because an agent's run has no terminal to draw it on: that run fails immediately, naming the flag it wanted. Reading that failure as a broken tool is the mistake to avoid — it is a missing flag, and the fix is to add --check <set> or --write.

Two options qualify whichever mode was picked, the first of them mandatory:

codependix map --write --config projects/configuration/codependix.config.ts
codependix map --check boundaries --directory . --config projects/configuration/codependix.config.ts
codependix map --check reports --directory . --config projects/configuration/codependix.config.ts

Codependix reads the Nx project graph

This is the trait that separates it from measurement tools that walk a directory. Nx resolves the project graph itself, from the process working directory — no flag points at it. What --directory names is the workspace root every project's path is resolved against. It has no bearing on where the configuration is: that is always the --config path.

So --directory is not a subtree to scan, and pointing it at a single project's folder does not export that project alone. It makes every project's root resolve underneath that folder, and the exports land in the wrong place — or fail on a readme that is not there — while the graph itself is unaffected.

Run codependix from the workspace root, pass --directory ., and select projects through the configuration's include/exclude globs, or through --projects/--tags, rather than through the directory.

Graphing a workspace the process is not standing in

A configuration may name a projectGraph file to read instead of resolving one:

{ projectGraph: "artifacts/graph.json" }

It is a path, relative to the workspace root, to the JSON that nx graph --file=graph.json emits. That is the only way to graph a workspace the process is not inside — a job that checked out one repository and graphs another, or a run with no Nx workspace under it at all. The path resolves against the same root every export path does, and a supplied graph's node roots are workspace-relative and resolve underneath it too.

It is a configuration field rather than a flag: what graph a run reads is a property of the workspace being described, and pinning it once is what a job graphing a fixed checkout wants.

A supplied graph is trusted, not validated. Nx wrote it, so its contents are taken as given; only a file that is not a project graph at all is refused, by name, rather than crashing later with nothing pointing at the file. A stale or hand-edited graph will produce a diagram that is wrong rather than one that fails.

Two things still need real files on disk regardless, so a supplied graph does not make a whole run workspace-free: the nestjs level boots each container, and the imports level builds a real ts.Program. The nx level reads only the graph.

Four graph types, plus the workspace

Each is keyed by name in the configuration:

The whole-workspace Nx graph is configured separately, under workspace.nx. It is exported once for the repository rather than once per project, has no per-project override, and is unaffected by include/exclude. Its node set is what --projects/--tags narrow — see below.

Participation is per graph type and is not one rule. A project a given graph type does not apply to simply never appears in that type's results, which is why configuring a graph type for every project costs nothing: a project with no NestJS container is absent from the NestJS pass rather than failing it.

--projects and --tags select projects from the command line

Both take a comma-separated list, and both do two things at once:

codependix map --write --projects widgets,tools/reporting --config projects/configuration/codependix.config.ts
codependix map --write --tags framework:nestjs,language:python --config projects/configuration/codependix.config.ts

They widen what gets exported. A project participates when anything claims it — an include glob, a --projects glob, or a --tags tag. The flags add to what the configuration already selected rather than replacing it, so --projects widgets on a workspace whose include is ["**"] exports exactly what it did before. exclude still wins over all three: a flag that could resurrect an excluded project would make exclude advisory.

--projects matches the way include does, as a glob against a project's name or its workspace-relative root, so --projects packages/* and --projects codependix-* both work and mean what they look like. --tags matches a project's own Nx tags exactly.

They narrow what gets drawn and judged. Naming a selection also narrows the whole-workspace graph's node set to the selected projects, and makes them the only projects --check boundaries judges. Naming neither selects everything, which is why the default behavior of both is unchanged.

The gate builds over their dependencies. --check boundaries builds every level's graph over the selected projects plus everything they transitively depend on, and charges each finding to projects: a cycle to every project on it, a forbidden edge to its source's project, a container boot failure to the container's project. A finding fails the run only when it is charged to a selected project; one charged only to a dependency is logged as a non-failing note "in dependency". --no-dependencies builds over the selected projects alone — faster, but an edge leaving the selection is no longer drawn, so a cycle closing through a dependency goes unseen. A green --no-dependencies run means less than a green default run: keep it for local iteration.

A selection that matches nothing is refused, in every mode: a misspelled name, a tag no project carries, or the workspace root (which is never a selectable project) exits non-zero as a rejected command line naming the patterns, rather than passing a gate that judged nothing.

A selection that matches only in part is warned about, not refused. --projects widgets,typo judges widgets and logs the warning 🕸️ Ignored selection entries that matched no project on stderr. It lists the projects and tags that matched nothing, with a hint to check the spelling. The exit code is unchanged, so a misspelled entry beside a good one shows up in the log rather than in the verdict.

include/exclude never do this — they decide which projects have exports written for them, and have never reached the workspace graph or the gate. That difference is the whole reason the flags exist as flags rather than as configuration fields.

Two flags rather than Nx's own --projects=tag:foo spelling, deliberately: each shows up in --help under its own name. Do not "fix" the divergence.

Gating one project at a time

--check boundaries --projects <name> is a per-project gate from a plain shell, and an Nx workspace gets it inferred. The @codependix/nx plugin adds a cached codependix-gate target to every project described by a project.json, except the workspace root. It runs exactly that command from the workspace root, under the decorator-preserving loader NestJS needs, which the plugin registers from its own dependencies:

nx run lexico-entities:codependix-gate   # one project
nx affected -t codependix-gate           # only what a change touched

Each project's gate fails for findings charged to that project. A broken boundary therefore fails the project that owns the edge — and every project on a cycle — rather than one workspace-wide task that names none of them. A dependent that merely builds on a broken project prints the finding as a note and passes; the broken project's own gate is the one that fails, so reproduce a failure by running the gate of the project it names.

The cache keys on the project, its dependencies, the configuration, and the codependix command line, test files excluded. A gate whose selection differs from its own project judges projects those inputs do not cover, so it is never replayed from the cache; one judging only its own project is cached as usual. The target declares no configurations, so an aggregator run with --configuration=check falls through to its defaults, as callidescope's callidescope-gate does. In this repository guard-code depends on it. The workspace-wide configuration:codependix target is write-only: it publishes the exports on the default branch and gates nothing.

What the run reports

Every pass is attempted regardless of whether an earlier one failed, and one project's failure is isolated to that project — a missing README, or a NestJS project that fails to boot its container, is collected as a failure while every other project still runs. --write either fully succeeds or names exactly which projects failed.

Three findings are reported separately, and any one of them fails the run:

• Failures — projects that raised before their exports could be resolved, or whose graph could not be built to judge.
• Stale exports — under --check reports, configured exports that disagree with a freshly built graph.
• Boundary violations — under --check boundaries, edges and cycles breaking a declared rule. Each names its level, its scope, the rule, both endpoints, the project or projects it is charged to, and whatever the rule says about why it exists. They go to the console and the exit code, and into a report only when --format, --json-output, or --markdown-output asks for one. A list of things currently wrong is not a document worth committing, so the exports --write splices into READMEs never hold it.

A project resolving to target: "none" is left out of the results entirely rather than reported as up to date, so an exit code depends only on exports codependix was actually configured to produce. A --check run reporting 0 projects is telling you it was configured to produce nothing.

The boundary report

Give a --check boundaries run --format json, --json-output <path>, or --markdown-output <path> and it prints its findings as a report. In JSON it is a boundaries key beside the graph types; in Markdown it is a ### Boundaries section. A --check boundaries-only run exports nothing, so the report is all it prints. Without one of those flags a boundaries-only run prints nothing, and a run that also exports prints its graphs as it always did.

codependix map --check boundaries --projects lexico-entities --format json --config projects/configuration/codependix.config.ts

boundaries.judgedProjects lists the projects whose findings fail the run. Each entry of violations and failures carries the charged projects and a verdict: fail fails the run, note is a finding in a dependency of a judged project and does not. A failures entry — a container that would not boot — also names ownerProject when the class it failed on belongs to a different project than the one whose container failed. Read the fail rows, and treat note rows as the dependency's own gate's business.

A failure at the nxProjects level — the Nx project graph could not be built — is charged to every judged project, because none of them could be judged. When more than one is judged it prints as all N judged projects rather than a list, and the Markdown report lists it once under #### All judged projects instead of under each project. The JSON keeps the full projects array. Every other level builds its graph per project, so a failure there, a container that would not boot included, is charged to that one project. A bullet's error text keeps its line breaks, indented under the bullet, and --> is written --> so the text cannot close an HTML comment.

Reading an export

A Markdown destination writes a Mermaid diagram. In anchor mode the diagram is spliced between two HTML comment markers naming the anchor:

<!-- codependix:start name="codependix-nx-projects" -->
```mermaid
graph LR
  widgets["widgets"]
  logger["logger"]
  widgets --> logger
  classDef subject fill:#7c3aed,color:#fff,stroke:#4c1d95,stroke-width:2px
  class widgets subject
```
<!-- codependix:end name="codependix-nx-projects" -->

The highlighted subject node is the project the Neighborhood is centered on. Node identifiers are sanitized from names and paths, so read the quoted label rather than the identifier.

A JSON destination writes the graph's own shape — an Nx Neighborhood carries dependencies, dependents, edges, and projectName; an import graph carries fileNames, edges, isolatedFileNames, and projectName; a NestJS module graph adds ambientModuleNames for the global modules whose edges were deliberately left out of the diagram.

For using a committed graph to answer a question about the codebase — what depends on this, what a rename would touch, whether an import cycle is real — reach for the codependix-navigate skill.

Never hand-edit inside the markers

The next --write replaces an anchor block wholesale. A diagram edited by hand is a diff that silently disappears on the following run, and reviewers see a change that reverts itself for no visible reason.

Re-running --write is the entire fix for a stale --check reports. It is never the fix for a --check boundaries failure — that is a real edge in real code, and writing an export does not remove it. Reach for the codependix-triage skill for either one, and for codependix-configure to read or change the rules themselves.