@avi2dg/checks 0.56.0 → 0.56.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.56.1
+
+Released 2026-10-27.
+
+### Fixes
+
+- **complexity:** merge unused, exports and imports walks into one pass [#12](https://github.com/avi2d/checks/pull/12)
+
 ## 0.56.0
 
 Released 2026-10-27.

package/docs/bins.md

@@ -19,8 +19,7 @@ The table groups the gates by vector, the part of a repository each one judges.
 | --- | --- | --- | --- |
 | complexity | [`checks-suppressions-ratchet`](gates/checks-suppressions-ratchet.md) | the range | every repository |
 | complexity | [`checks-repetition`](gates/checks-repetition.md) | the range | a repository tracking `*.ts` or `*.tsx` |
-| complexity | [`checks-unused`](gates/checks-unused.md) | the working tree | a repository tracking `*.ts` or `*.tsx` or `*.astro` |
-| complexity | [`checks-exports`](gates/checks-exports.md) | the range | a repository tracking `*.ts` or `*.tsx` |
+| complexity | [`checks-graphwalk`](gates/checks-graphwalk.md) | the range | a repository tracking `*.ts` or `*.tsx` or `*.astro` |
 | quality | [`checks-lint-coverage`](gates/checks-lint-coverage.md) | the working tree | a repository tracking `*.ts` or `*.tsx` or `*.astro` |
 | quality | [`checks-comment-gate`](gates/checks-comment-gate.md) | the range | every repository |
 | quality | [`checks-effect-scope`](gates/checks-effect-scope.md) | the working tree | a repository tracking `oxlint.config.ts` |
@@ -34,7 +33,6 @@ The table groups the gates by vector, the part of a repository each one judges.
 | delivery | [`checks-commit-identity`](gates/checks-commit-identity.md) | the range | every repository |
 | delivery | [`checks-ci-wiring`](gates/checks-ci-wiring.md) | the working tree | every repository |
 | delivery | [`checks-secrets`](gates/checks-secrets.md) | the range | every repository |
-| dependencies | [`checks-imports`](gates/checks-imports.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | dependencies | [`checks-advisories`](gates/checks-advisories.md) | the range | a repository tracking `bun.lock` |
 
 <!-- end generated gates -->

package/docs/configs/dependency-rules.md

@@ -11,7 +11,7 @@ The kit's dependency-cruiser rules hold a repository's imports, and a repository
 `defineConfig` from `@avi2dg/checks/dependency-cruiser` returns these rules, with or without a config of the repository's own:
 
 - `no-circular`
-- `no-orphans`, which a repository that depends on `astro` gets only by listing its own, as [checks-imports](../gates/checks-imports.md) explains
+- `no-orphans`, which a repository that depends on `astro` gets only by listing its own, as [checks-graphwalk](../gates/checks-graphwalk.md) explains
 - `not-to-dev-dep`, which refuses shipped source importing a dev-only package, and a package listed in `peerDependencies` too is not dev-only
 - `no-non-package-json`, which refuses an import of an installed package that the nearest `package.json` does not declare, and counts a peer that `peerDependenciesMeta` marks optional as declared
 - `not-to-unresolvable`, which refuses a specifier nothing installed answers
@@ -61,9 +61,9 @@ A rule under `forbidden` that takes a kit rule's name replaces that rule whole,
 
 ## Running it
 
-`checks-lint` runs [checks-imports](../gates/checks-imports.md) in the full run, which cruises every tracked TypeScript file against `dependency-cruiser.config.ts`, or against the kit's defaults when the repository holds no config.
+`checks-lint` runs [checks-graphwalk](../gates/checks-graphwalk.md) in the full run, which cruises every tracked TypeScript file against `dependency-cruiser.config.ts`, or against the kit's defaults when the repository holds no config.
 
 ## Related topics
 
-- [checks-imports](../gates/checks-imports.md)
+- [checks-graphwalk](../gates/checks-graphwalk.md)
 - [Why it is shaped this way](../design.md)

package/docs/configs/native-settings.md

@@ -14,11 +14,11 @@ A consuming repository puts each setting in the file its tool reads, and no mani
 | `oxlint.config.ts` | Effect paths and their exemptions, ignore patterns, and any rule or budget the repository sets over the kit's defaults | oxlint and `checks-effect-scope` |
 | `oxlint-suppressions.json` | The existing violations oxlint suppresses, per file and rule | oxlint and `checks-suppressions-ratchet` |
 | `stylelint-suppressions.json` | The existing violations stylelint suppresses, per file and rule | stylelint, `checks-frontend-syntax` and `checks-suppressions-ratchet` |
-| `exports-baseline.json` | The existing unused exports and types, per file, kind and name | `checks-exports` |
+| `exports-baseline.json` | The existing unused exports and types, per file, kind and name | `checks-graphwalk` |
 | `.jscpd.json` | The `path` and `ignore` globs of the files repetition is measured in | jscpd and `checks-repetition` |
-| `knip.config.ts` | The `entry` globs Knip traces unreferenced files from | Knip, `checks-unused` and `checks-exports` |
+| `knip.config.ts` | The `entry` globs Knip traces unreferenced files from | Knip and `checks-graphwalk` |
 | `stylelint.config.ts` | The Baseline target, the token files, the CSS families the repository turns on, and any stylelint rule the repository sets over the kit's families | `checks-frontend-syntax` |
-| `dependency-cruiser.config.ts` | Entry points nothing imports, paths that may import dev dependencies, and import boundaries, when the kit's defaults do not fit | `checks-imports` |
+| `dependency-cruiser.config.ts` | Entry points nothing imports, paths that may import dev dependencies, and import boundaries, when the kit's defaults do not fit | `checks-graphwalk` |
 | `tsconfig.json` | Compiler options, and the Effect language service plugin whose `overrides` and kit severities `checks-effect-scope` writes, keeping every other key | TypeScript and Effect language service |
 | `package.json` | `scripts` with the `checks-vendor` arguments in `prepare`, `author` and `contributors` | Bun, `checks-commit-identity` and `checks-vendor` |
 | `bunfig.toml` | Test discovery and quarantine exclusion | Bun and `checks-test-layout` |
@@ -69,7 +69,7 @@ import { defineConfig } from "@avi2dg/checks/knip";
 export default defineConfig({ entry: ["src/index.ts"] });
 ```
 
-`dependency-cruiser.config.ts` is optional, since `checks-imports` cruises against the kit's defaults without one:
+`dependency-cruiser.config.ts` is optional, since `checks-graphwalk` cruises against the kit's defaults without one:
 
 ```ts
 import { defineConfig } from "@avi2dg/checks/dependency-cruiser";

package/docs/design.md

@@ -125,9 +125,9 @@ A gate then behaves the same alone or through `checks-lint`, and `lint-coverage.
 The gates run one at a time and pass their output straight through, so each report reads whole and in the order of the gate table.
 `checks-lint` picks the gates that apply from the tracked files for the full run, and a repository cannot select gates.
 A scoped run selects a subset by changed paths, and the desk run selects the fast tree gates.
-A TypeScript gate applies as soon as the repository tracks TypeScript source, and `checks-lint-coverage` and `checks-unused` also apply on tracked Astro source.
+A TypeScript gate applies as soon as the repository tracks TypeScript source, and `checks-lint-coverage` and `checks-graphwalk` also apply on tracked Astro source.
 
-dependency-cruiser runs as the `checks-imports` gate rather than as a script each repository adds to `lint`, so the full run keeps it.
+dependency-cruiser runs inside the `checks-graphwalk` gate rather than as a script each repository adds to `lint`, so the full run keeps it.
 A repository with no config of its own is cruised against the kit's defaults, since every rule has one.
 The gate cruises the tracked TypeScript, so a build output or a linked library outside git never reaches the cruise.
 It runs dependency-cruiser under Bun, which loads a TypeScript config wherever it sits, the kit's defaults under `node_modules` among them.

package/docs/gates/checks-graphwalk.md

@@ -0,0 +1,126 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-graphwalk
+
+`checks-graphwalk` is the gate that judges unreferenced files, unused exports and import violations together, running Knip once over the working tree for unreferenced files and unused exports and dependency-cruiser once for import violations, plus Knip once more on the base checkout when the range adds baseline entries.
+
+## What it checks
+
+It runs Knip once with the repository's own configuration and names each `.ts`, `.tsx` or `.astro` file no entry reaches.
+It names each exported value and type no file imports from the same run, so one graph build feeds both findings.
+It reads only the files, exports and types issue types, so an unused dependency never fails it.
+It asks Knip for those issue types itself, so a configuration that narrows `include` or excludes them still judges them.
+A configuration that turns the exports or types rules off silences those symbols, so keep both rules on.
+A configuration that turns the files rule off still has its files judged.
+It holds each reported symbol against `exports-baseline.json`, and fails on any symbol the baseline does not hold.
+It fails on any baseline entry the range adds unless Knip reports that same symbol unused at the base, so the baseline records debt that already existed and never debt the range creates.
+It fails on any baseline entry Knip no longer reports, so the baseline only shrinks.
+It runs dependency-cruiser over every tracked `.ts`, `.tsx`, `.mts` and `.cts` file and names each violation with its rule, the importing module and the module it reaches.
+It fails on a violation whose rule has `error` severity, and lists a `warn` or `info` violation without failing.
+It fails when the repository tracks no `.ts`, `.tsx`, `.astro`, `.mts` or `.cts` file, since an empty scan would pass without judging anything.
+It fails when the repository holds no Knip configuration, since Knip's default entries cannot tell a dead file from an entry point.
+
+In a repository whose `package.json` lists `astro` under `dependencies` or `devDependencies`, the kit's defaults leave `no-orphans` out.
+The cruise never reads an `.astro` file, so a `.ts` module only a page imports would read as an orphan.
+The unreferenced-files section already names each file no entry reaches there, and it reads `.astro` imports.
+A repository that wants the rule back lists its own `no-orphans` under `forbidden` in `dependency-cruiser.config.ts`.
+
+## What it reads
+
+It runs Knip and dependency-cruiser over the working tree, so an uncommitted file is judged like a committed one.
+It reads the repository's Knip configuration, which names the entries.
+The repository writes `knip.config.ts` with the kit's builder, which requires `entry`, the files nothing imports:
+
+```ts
+import { defineConfig } from "@avi2dg/checks/knip";
+
+export default defineConfig({ entry: ["src/index.ts"] });
+```
+
+The builder sets `include` to unreferenced files alone, and adds `tests/**/*.test.ts`, `dependency-cruiser.config.ts` and `oxlint.config.ts` to the entries.
+In a repository that depends on `astro`, Knip reads `.astro` imports, so a file only an `.astro` entry imports counts as used and an `.astro` file no entry reaches is named.
+The gate resolves the Knip binary from the installed kit, so a consumer installs nothing beyond the kit.
+It reads `exports-baseline.json` in the repository root, which holds each accepted unused export as a file, kind and name triple.
+It reads `exports-baseline.json` again at the base of the range, where a commit without the file counts as empty.
+When the range adds baseline entries, it runs Knip again on a temporary checkout of the base and removes the checkout when it ends.
+That checkout links the repository's `node_modules`, so a configuration importing the kit's builder loads there too.
+It cruises against the first config it finds there:
+
+1. `dependency-cruiser.config.ts`, which calls `defineConfig` from `@avi2dg/checks/dependency-cruiser`.
+1. A config under one of dependency-cruiser's own names, such as `.dependency-cruiser.cjs`.
+1. The kit's defaults, which `defineConfig()` returns with no argument.
+
+It runs dependency-cruiser from the installed kit under Bun, which loads a TypeScript config wherever it sits.
+It leaves out a tracked file the working tree no longer holds.
+
+## Arguments
+
+```sh
+checks-graphwalk
+checks-graphwalk <ref>
+checks-graphwalk <base-ref> <head-ref>
+checks-graphwalk --write
+```
+
+With no argument it judges `HEAD` alone.
+With one the base is that commit's parent, or the empty tree for a repository's first commit, where nothing counts as already unused.
+With two arguments the base is where the head branched off, at their merge-base.
+When the checked-out commit is a merge of the head ref and one other commit, as a pull request's default checkout is, the base is that other commit instead.
+So under `checks-lint` a pull request's merge checkout is judged against the base branch tip it merges, and a symbol that branch already baselined does not count as added.
+With `--write` it records every unused export and type Knip reports into `exports-baseline.json`, the way `oxlint --suppress-all` seeds `oxlint-suppressions.json`.
+
+A repository adopting the gate runs `checks-graphwalk --write` on a branch that changes no source and commits the file it writes.
+The gate passes that range, since Knip reports every seeded symbol unused at the base too.
+A seed written after the range adds a dead export, or after it removes the last import of one, fails on that symbol.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | no file is unreferenced, no symbol is unlisted, added or stale, and no import breaks an `error` rule, or `--write` recorded the baseline |
+| 1 | a file is unreferenced, a symbol is unlisted, added or stale, an import breaks an `error` rule, or the repository holds no Knip configuration |
+| 2 | a ref does not resolve, a scanner cannot run, or a Knip report, a cruise report or the baseline does not parse |
+
+The gate exits 1 when any section reports a violation, and exits 2 only when no section reports one and at least one section cannot decide.
+
+It also exits 2 when the repository tracks no `.ts`, `.tsx`, `.astro`, `.mts` or `.cts` file, or, with `--write`, when it tracks no TypeScript file.
+A repository that tracks `.astro` files but no `.ts`, `.tsx`, `.mts` or `.cts` file prints only the unreferenced-files section.
+
+## Sample output
+
+```
+unused: 1 unreferenced file(s):
+  src/dead.ts
+exports: 2 unused export(s) not in exports-baseline.json:
+  src/used.ts: unusedExport (export)
+  src/used.ts: UnusedOptions (type)
+imports: 1 violation(s) in 5 module(s) cruised against the kit's defaults
+  error no-orphans: src/dead.ts
+```
+
+A passing run counts what each section judged:
+
+```
+unused: no unreferenced files among 3 tracked .ts/.tsx/.astro file(s)
+exports: no unused exports or types
+imports: 3 module(s) cruised against the kit's defaults, no violation
+```
+
+A passing run with a held baseline counts what it holds:
+
+```
+exports: 2 unused export(s) in exports-baseline.json, and no new ones
+```
+
+## When it runs
+
+`checks-lint` runs it over each pull request's range when the repository tracks a `.ts`, `.tsx` or `.astro` file.
+Such a repository names its entries in a Knip configuration.
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [checks-repetition](checks-repetition.md)
+- [The dependency rules](../configs/dependency-rules.md)

package/docs/gates/checks-lint.md

@@ -15,7 +15,7 @@ A Markdown change runs the range gates plus `checks-copy`.
 A TypeScript source change runs every applicable gate.
 A test file classifies as TypeScript, so its change runs every applicable gate too.
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
-`checks-lint-coverage` and `checks-unused` also begin running when the repository tracks an `.astro` file.
+`checks-lint-coverage` and `checks-graphwalk` also begin running when the repository tracks an `.astro` file.
 `checks-advisories` begins running when the repository tracks `bun.lock`.
 `checks-lint` defers its scan to the scheduled run, so the desk and the pull request fetch no database.
 `checks-frontend-syntax` begins running when the repository tracks `frontend-syntax.json` at its root.
@@ -58,7 +58,7 @@ With two arguments, the base and head override range discovery.
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 19 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 17 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->
@@ -66,7 +66,7 @@ checks-lint: 1 of 19 gate(s) failed: checks-comment-gate
 ## When it runs
 
 A repository runs it from `bun run lint` in a pull request workflow that fetches the whole git history.
-It leaves out the TypeScript gates while the repository tracks no TypeScript file, except that `checks-lint-coverage` and `checks-unused` run when it tracks an `.astro` file.
+It leaves out the TypeScript gates while the repository tracks no TypeScript file, except that `checks-lint-coverage` and `checks-graphwalk` run when it tracks an `.astro` file.
 It never runs `checks-browser`, which a product runs after it builds its site.
 A pull request run scopes the gates to the change.
 

package/docs/gates/checks-no-plain-js.md

@@ -57,4 +57,4 @@ no-plain-js: 2 violation(s)
 
 - [checks-lint](checks-lint.md)
 - [checks-test-layout](checks-test-layout.md)
-- [checks-unused](checks-unused.md)
+- [checks-graphwalk](checks-graphwalk.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.56.0",
+  "version": "0.56.1",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -90,8 +90,7 @@
     "src/quality/browser/",
     "src/complexity/suppressions-ratchet.ts",
     "src/complexity/repetition.ts",
-    "src/complexity/unused.ts",
-    "src/complexity/exports.ts",
+    "src/complexity/graphwalk.ts",
     "src/complexity/knip.ts",
     "src/testing/quarantine-clock.ts",
     "src/docs/sentence-length.ts",
@@ -121,7 +120,6 @@
     "src/quality/presets/stylelint.ts",
     "src/quality/effect-scope.ts",
     "src/quality/jsonc-patch.ts",
-    "src/dependencies/imports.ts",
     "src/dependencies/kit-defaults.ts",
     "oxlintrc.json",
     "stryker.preset.js",
@@ -188,8 +186,7 @@
     "checks-css-size": "src/quality/css-size.ts",
     "checks-suppressions-ratchet": "src/complexity/suppressions-ratchet.ts",
     "checks-repetition": "src/complexity/repetition.ts",
-    "checks-unused": "src/complexity/unused.ts",
-    "checks-exports": "src/complexity/exports.ts",
+    "checks-graphwalk": "src/complexity/graphwalk.ts",
     "checks-quarantine-clock": "src/testing/quarantine-clock.ts",
     "checks-docs": "src/docs/docs.ts",
     "checks-copy": "src/docs/copy.ts",
@@ -201,7 +198,6 @@
     "checks-frontend-syntax": "src/quality/frontend-syntax.ts",
     "checks-no-plain-js": "src/quality/no-plain-js.ts",
     "checks-browser": "src/quality/browser/browser.ts",
-    "checks-imports": "src/dependencies/imports.ts",
     "checks-effect-scope": "src/quality/effect-scope.ts"
   },
   "scripts": {