Skip to content

Graph

graph rules check the whole import graph: cycles, files nothing imports, and whether one layer reaches another through any number of hops, which per-file rules can’t see.

graph:
cycles:
- name: no-cycles
message: "These files import each other."
within: "packages/*/src/**"
withinNot: "**/*.test.ts"
orphans:
- name: no-dead-modules
message: "Nothing imports this file. Register it, or delete it."
within: "packages/*/src/**"
withinNot: "**/*.test.ts"
entry: ["packages/*/src/index.ts", "packages/*/src/main.ts"]
reach:
- name: adapters-through-ports
message: "An adapter reaches infrastructure only through a port."
from: "packages/*/src/adapters/**"
to: "packages/*/src/infrastructure/**"
via: "packages/*/src/ports/**"

graph is a top-level key. Its globs expand aliases.

The three graph rulesCycles: order.ts imports invoice.ts, which imports customer.ts, which imports order.ts; the cycle is one violation named by the set of its files. Orphans: index.ts is an entry that imports app.ts, which imports util.ts; a test outside the scope imports repo.fake.ts, so it is not an orphan; nothing imports legacy.ts, so it is. Reach: http.ts reaches pg-live.ts through the port repo.ts, which is allowed; cli.ts reaches pg-live.ts through shared/db.ts, avoiding every port, which is reported.cyclesfiles that import each otherindex.tsorder.tsinvoice.tscustomer.tsOne violation, named by the set{customer, invoice, order}.orphansfiles nothing importsentryindex.tsapp.tsutil.tsnot in scoperepo.test.tsrepo.fake.tslegacy.tslegacy.ts is an orphan. A test importsrepo.fake.ts, so it is not.reachtiers reached by any routeadaptershttp.tsports · viarepo.tsinfrastructurepg-live.tsadapterscli.tsshareddb.tscli.ts reaches pg-live.ts withoutpassing through a port: reported.
Each rule is a question about the whole graph at once, which is why only the CLI answers them: the plugin sees one file at a time.

Every rule needs name and message.

Rule Field Meaning
cycles within, withinNot Files to check. Required: within.
orphans within, withinNot Files to check. Required: within.
orphans entry Entry points, which nothing needs to import. Required.
reach from, fromNot Origin files. Required: from.
reach to, toNot Files they must not reach. Required: to.
reach via Files a path may pass through. Omit to forbid every route.

Reports each group of files that import each other, once. A cycle through a file outside within isn’t seen. Its baseline entry is keyed on the set of files.

Reports a file in scope that nothing imports and isn’t an entry. An import from anywhere counts, including tests.

Reports a from file that can reach a to file without passing through a via file. The route is appended to the message:

packages/server/src/adapters/http/todos.ts
[adapters-through-ports] An adapter reaches infrastructure only through a port.
(route: packages/server/src/adapters/http/todos.ts → packages/server/src/shared/db.ts → packages/server/src/infrastructure/pg-live.ts)

The baseline entry is keyed on origin and target, not the route.

Every walked file, with an edge per import that resolves to another walked file, type-only imports included. External packages and builtins aren’t in it. check reports unresolved imports separately.