codependix-export
/codependix-export
Run a codependix dependency graph export or boundary check, choose between --check boundaries, --check reports, and --write, point a run at a workspace root or a configuration file, or read a Mermaid block or JSON graph it produced. Use when running codependix or npx codependix, when a run exits 0 having written nothing, when --check is refused for carrying no value, when looking for a flag that selects one graph type, when wiring codependix into a CI step or an Nx task, when a codependix-gate target failed, or when reading an exported Nx Neighborhood, NestJS module graph, or file-level import
- Author
- organizzolini ↗
- Repository
- codebase ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 2
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Run a codependix dependency graph export or boundary check, choose between --check boundaries, --check reports, and --write, point a run at a workspace root or a configuration file, or read a Mermaid block or JSON graph it produced. Use when running codependix or npx codependix, when a run exits 0 having written nothing, when --check is refused for carrying no value, when looking for a flag that selects one graph type, when wiring codependix into a CI step or an Nx task, when a codependix-gate target failed, or when reading an exported Nx Neighborhood, NestJS module graph, or file-level import
Original author description
Run a codependix dependency graph export or boundary check, choose between --check boundaries, --check reports, and --write, point a run at a workspace root or a configuration file, or read a Mermaid block or JSON graph it produced. Use when running codependix or npx codependix, when a run exits 0 having written nothing, when --check is refused for carrying no value, when looking for a flag that selects one graph type, when wiring codependix into a CI step or an Nx task, when a codependix-gate target failed, or when reading an exported Nx Neighborhood, NestJS module graph, or file-level import
How it works
- The configuration decides everything
- One --write, and two things --check can gate
- Codependix reads the Nx project graph
- Four graph types, plus the workspace
- --projects and --tags select projects from the command line
- Gating one project at a time
- What the run reports
- The boundary report
- Reading an export
- Never hand-edit inside the markers
SKILL.md preview
---
name: codependix-export
description: Run a codependix dependency graph export or boundary check, choose between --check boundaries, --check reports, and --write, point a run at a workspace root or a configuration file, or read a Mermaid block or JSON graph it produced. Use when running codependix or npx codependix, when a run exits 0 having written nothing, when --check is refused for carrying no value, when looking for a flag that selects one graph type, when wiring codependix into a CI step or an Nx task, when a codependix-gate target failed, or when reading an exported Nx Neighborhood, NestJS module graph, or file-level import graph. Covers the command-line host directly, without assuming any task runner.
license: MIT
---
# 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.
| Mode | Meaning |
| ---- | ------- |
| `--check boundaries` | Fails on an edge or a cycle breaking a declared rule. Reads no destination and writes nothing |
| `--check reports` | Fails on a configured destination no longer holding what a fresh run would write |
| `--write` | Writes every configured export |
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:
| Option | Meaning |
| ------ | ------- |
| `--config <config>` | **Required.** Path to the codependix configuration file, resolved against the working directory, then the workspace root. Omitting it fails the run; nothing is searched for |
| `-d, --directory [directory]` | Workspace root whose Nx project graph this run reads. Defaults to the working directory |
```bash
codependix map --write --config configuration/codependix.config.ts
codependix map --check boundaries --directory . --config configuration/codependix.config.ts
codependix map --check reports --directory . --config 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:
```ts
{ 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:
| Key | What it exports | Which projects appear |
| --- | --------------- | --------------------- |
| `nx` | A project's one-hop Neighborhood — what it depends on, and what depends on it | Every project the Nx graph knows, except the workspace root itself |
| `nestjs` | A project's NestJS module import graph | Only projects tagged `framework:nestjs` |
| `imports` | A project's own file-level TypeScript import graph | Every project carrying its own `tsconfig.json` |
| `pythonImports` | The Python equivalent, parsed from `import` / `from ... import` statements | Only projects tagged `language:python` |
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:
```bash
codependix map --write --projects widgets,tools/reporting --config configuration/codependix.config.ts
codependix map --write --tags framework:nestjs,language:python --config 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:
```bash
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.
```bash
codependix map --check boundaries --projects lexico-entities --format json --config 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:
````markdown
<!-- 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.
Versions
The database has no other skills named codependix-export.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version c1ad254d77f6 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90codependix-triage
Act on a codependix run that failed or reported drift — a boundary violation, a --check reports run that found stale exports, a project that failed its export, a missing anchor block, a NestJS container that failed to boot, a rejected command line, or a --write that produced no… - 100codependix-configure
Write or edit a codependix.config.ts — which graph types run, per-project overrides, include and exclude globs, the whole-workspace graph, where each export lands, and the boundary rules every built graph is judged against. Use when a workspace has no codependix configuration… - 100dependency-graph
Generates a Mermaid dependency graph showing import relationships between modules. Use when analyzing coupling, finding circular deps, or planning refactors. - 100dependency-graph
Use when a JavaScript or TypeScript project's dependencies must be seen as they are in the code: the whole graph, what one module depends on, who depends on it, or its neighbourhood, at file or folder level. Produces a Mermaid graph document in aiview, parsed by a deterministic… - 100dependency-graph
Use when the user wants module or file dependencies, an import graph, "what depends on what", or circular dependency detection. Reads real import/require statements and writes docs/codemap/dependency-graph.md. - 90graph-code
[Code Intelligence] Use when building/syncing the code graph, querying callers/imports/tests, tracing flow, checking blast radius, linking APIs or exporting JSON/Mermaid. --mode={build|query|trace|blast-radius|connect-api|export}.