@avi2dg/checks 0.24.2 → 0.26.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.26.0
+
+Released 2026-09-27.
+
+### Breaking changes
+
+- **complexity:** add checks-exports gate holding unused exports to a shrinking baseline [#89](https://github.com/avi2d/checks/pull/89)
+- move doc templates into dist/templates and presets into src/quality [#88](https://github.com/avi2d/checks/pull/88)
+
+## 0.25.0
+
+Released 2026-09-27.
+
+### Breaking changes
+
+- stop shipping checks-backtest and unused exports keys, guard the tarball with Knip [#86](https://github.com/avi2d/checks/pull/86)
+- sort the kit into src/<vector>/ and require tests/<level>/ [#84](https://github.com/avi2d/checks/pull/84)
+
+### Features
+
+- add checks-unused gate that rejects unreferenced TypeScript files via Knip [#85](https://github.com/avi2d/checks/pull/85)
+
 ## 0.24.2
 
 Released 2026-09-27.

package/README.md

@@ -65,6 +65,14 @@ To consume the kit from a repository:
    cp node_modules/@avi2dg/checks/bunfig.toml bunfig.toml
    ```
 
+1. Name the repository's entry files in `knip.config.ts`, spreading the kit's Knip base:
+
+   ```ts
+   import base from "@avi2dg/checks/knip-base.json";
+
+   export default { ...base, entry: ["src/index.ts", "tests/**/*.test.ts"] };
+   ```
+
 1. Add scripts to `package.json`, replacing the build entry with the repository's own build command:
 
    ```json
@@ -100,22 +108,25 @@ Add a pull request title lint step in another workflow using `./node_modules/.bi
 
 ## What runs
 
-`checks-lint` runs these gates in this order, each over the working tree or over the range it resolves, and names every one that fails.
+`checks-lint` runs these gates, each over the working tree or over the range it resolves, and names every one that fails.
 `checks-lint` runs every applicable gate, including the TypeScript gates once the repository tracks TypeScript.
-
-<!-- generated gates: bun run build writes it from KIT_GATES in scripts/gates.ts and scripts/doc-blocks.ts -->
-
-| Gate | Reads | Runs in |
-| --- | --- | --- |
-| [`checks-lint-coverage`](docs/gates/checks-lint-coverage.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
-| [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
-| [`checks-commit-identity`](docs/gates/checks-commit-identity.md) | the range | every repository |
-| [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
-| [`checks-suppressions-ratchet`](docs/gates/checks-suppressions-ratchet.md) | the range | every repository |
-| [`checks-ci-wiring`](docs/gates/checks-ci-wiring.md) | the working tree | every repository |
-| [`checks-docs`](docs/gates/checks-docs.md) | the range | every repository |
-| [`checks-repetition`](docs/gates/checks-repetition.md) | the range | a repository tracking `*.ts` or `*.tsx` |
-| [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |
+Each gate belongs to the vector it judges a repository on, and the table groups the gates by vector.
+
+<!-- generated gates: bun run build writes it from KIT_GATES in src/core/gates.ts and scripts/doc-blocks.ts -->
+
+| Vector | Gate | Reads | Runs in |
+| --- | --- | --- | --- |
+| complexity | [`checks-suppressions-ratchet`](docs/gates/checks-suppressions-ratchet.md) | the range | every repository |
+| complexity | [`checks-repetition`](docs/gates/checks-repetition.md) | the range | a repository tracking `*.ts` or `*.tsx` |
+| complexity | [`checks-unused`](docs/gates/checks-unused.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
+| complexity | [`checks-exports`](docs/gates/checks-exports.md) | the range | a repository tracking `*.ts` or `*.tsx` |
+| quality | [`checks-lint-coverage`](docs/gates/checks-lint-coverage.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
+| quality | [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
+| testing | [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
+| testing | [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |
+| docs | [`checks-docs`](docs/gates/checks-docs.md) | the range | every repository |
+| delivery | [`checks-commit-identity`](docs/gates/checks-commit-identity.md) | the range | every repository |
+| delivery | [`checks-ci-wiring`](docs/gates/checks-ci-wiring.md) | the working tree | every repository |
 
 <!-- end generated gates -->
 
@@ -125,7 +136,6 @@ These bins run on their own:
 - [`checks-flake`](docs/gates/checks-flake.md) runs the suite on a schedule and records the seeds a flaky test fails with.
 - [`checks-mutation-compare`](docs/gates/checks-mutation-compare.md) holds every mutant in a pull request to no regression.
 - [`checks-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
-- [`checks-backtest`](docs/gates/checks-backtest.md) reports what the comment check would have refused in recent history.
 - [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
 - [`checks-release-notes`](docs/gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
 - [`checks-release-report`](docs/gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.
@@ -156,18 +166,16 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 | Path | What it holds |
 | --- | --- |
 | `CHANGELOG.md` | every release, and what it changed |
-| `CONTRIBUTING.md` | how this repository is developed and released |
 | `docs/` | a reference page per bin and per shared config, and why the kit is shaped this way |
 | `bunfig.toml` | the bunfig preset a repository copies |
 | `commitlint.config.js` | the shared commitlint config |
 | `dependency-cruiser.config.js` | the shared dependency-cruiser base |
-| `scripts/` | every bin, which a package script calls by its `checks-` name |
-| `templates/` | one template per kind of doc file, which a new doc file starts from |
-| `presets/` | the Effect rule blocks a repository copies into its native config |
+| `knip-base.json` | the Knip base a repository's configuration imports |
+| `src/` | every bin, which a package script calls by its `checks-` name, the modules the bins import, and the Effect rule blocks under `src/quality/presets/` |
+| `dist/` | the compiled oxlint plugins and the doc templates, one template per kind of doc file |
 | `oxlintrc.json` | the oxlint base config `.oxlintrc.json` extends |
 | `stryker.preset.js` | the Stryker mutation-testing preset |
 | `tsconfig.effect.json` | the tsconfig fragment with the Effect language-service block |
-| `dist/` | the compiled oxlint plugins, one per purpose |
 
 <!-- end generated shipped -->
 
@@ -179,4 +187,3 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 - [The dependency rules](docs/configs/dependency-rules.md)
 - [The commit message lint](docs/configs/commit-messages.md)
 - [Why it is shaped this way](docs/design.md)
-- [Contribute to checks](CONTRIBUTING.md)

package/dist/effect-channel/index.js

@@ -1,4 +1,4 @@
-// effect-channel/no-error-channel-escape.ts
+// src/quality/effect-channel/no-error-channel-escape.ts
 var EFFECT_SOURCES = new Set(["effect", "effect/Effect"]);
 var INSTEAD = {
   drops: "it drops the failure and the success together, so no caller can tell one from the other. Handle the error by tag, or keep it as a value with Effect.result or Effect.exit",
@@ -69,7 +69,7 @@ var rule = {
 };
 var no_error_channel_escape_default = rule;
 
-// effect-channel/no-throw.ts
+// src/quality/effect-channel/no-throw.ts
 var rule2 = {
   meta: {
     type: "problem",
@@ -88,7 +88,7 @@ var rule2 = {
 };
 var no_throw_default = rule2;
 
-// effect-channel/no-try-catch.ts
+// src/quality/effect-channel/no-try-catch.ts
 var rule3 = {
   meta: {
     type: "problem",
@@ -107,7 +107,7 @@ var rule3 = {
 };
 var no_try_catch_default = rule3;
 
-// effect-channel/index.ts
+// src/quality/effect-channel/index.ts
 var plugin = {
   meta: { name: "effect-channel" },
   rules: {

package/dist/readability/index.js

@@ -1,4 +1,4 @@
-// readability/cognitive-nodes.ts
+// src/complexity/readability/cognitive-nodes.ts
 var CONTROL_TYPES = ["IfStatement", "ConditionalExpression", "SwitchStatement", "SwitchCase", "TryStatement", "CatchClause"];
 var LOOP_TYPES = ["ForStatement", "ForInStatement", "ForOfStatement", "WhileStatement", "DoWhileStatement", "LabeledStatement"];
 var CALL_TYPES = ["LogicalExpression", "BreakStatement", "ContinueStatement", "CallExpression", "NewExpression", "ImportExpression"];
@@ -7,7 +7,7 @@ var PLAIN_A_TYPES = ["BlockStatement", "ExpressionStatement", "ReturnStatement",
 var PLAIN_B_TYPES = ["ClassDeclaration", "ClassExpression", "ClassBody", "MethodDefinition", "TSAbstractMethodDefinition", "PropertyDefinition", "TSAbstractPropertyDefinition", "AccessorProperty", "TSAbstractAccessorProperty", "ObjectExpression", "ArrayExpression"];
 var PLAIN_C_TYPES = ["AwaitExpression", "UnaryExpression", "UpdateExpression", "SpreadElement", "YieldExpression", "BinaryExpression", "AssignmentExpression", "TSAsExpression", "TSSatisfiesExpression", "TSTypeAssertion", "TSNonNullExpression", "ChainExpression", "ParenthesizedExpression", "Decorator", "TSInstantiationExpression", "MemberExpression", "JSXMemberExpression", "TemplateLiteral", "TaggedTemplateExpression", "SequenceExpression", "JSXElement", "JSXFragment", "JSXOpeningElement", "JSXAttribute", "JSXExpressionContainer", "JSXSpreadChild", "JSXSpreadAttribute"];
 
-// readability/cognitive-plain.ts
+// src/complexity/readability/cognitive-plain.ts
 function isControl(node) {
   return CONTROL_TYPES.includes(node.type);
 }
@@ -142,7 +142,7 @@ function plainChildrenC(node) {
   }
 }
 
-// readability/cognitive.ts
+// src/complexity/readability/cognitive.ts
 function unreachable2(_value) {}
 function scoreList(state, nodes, nesting, parent) {
   for (const node of nodes) {
@@ -334,7 +334,7 @@ function cognitiveComplexity(root, names) {
   return state.recursive ? state.total + 1 : state.total;
 }
 
-// readability/cognitive-complexity.ts
+// src/complexity/readability/cognitive-complexity.ts
 var DEFAULT_MAX = 15;
 function maxOf(options) {
   const [first] = options;
@@ -416,7 +416,7 @@ var rule = {
 };
 var cognitive_complexity_default = rule;
 
-// readability/index.ts
+// src/complexity/readability/index.ts
 var plugin = {
   meta: { name: "readability" },
   rules: {

package/docs/configs/commit-messages.md

@@ -8,7 +8,7 @@ The shared commitlint config holds each pull request title to conventional commi
 
 ## Config
 
-Commits follow `@commitlint/config-conventional` plus the house prefixes `commitlint.config.js` lists, shared from `@avi2dg/checks/commitlint.config.js`.
+Commits follow `@commitlint/config-conventional` plus the house prefixes `commitlint.config.js` lists, shared from `node_modules/@avi2dg/checks/commitlint.config.js`.
 It arrives with the kit, since `@commitlint/cli` and `@commitlint/config-conventional` are dependencies, not peers.
 
 ## Workflow

package/docs/configs/effect-rules.md

@@ -31,7 +31,7 @@ The repo's `.oxlintrc.json` owns its Effect paths and exemptions in an override:
 }
 ```
 
-The kit ships the rule block in `presets/effect.oxlint.json` for copying into the override.
+The kit ships the rule block in `src/quality/presets/effect.oxlint.json` for copying into the override.
 Each config in an oxlint `extends` chain sets `plugins` explicitly, because an omitted list enables defaults across the chain.
 `unicorn/no-process-exit` does not check a shebang script, so a bin can use `eslint/no-restricted-properties` for `process.exit`.
 
@@ -39,7 +39,7 @@ Each config in an oxlint `extends` chain sets `plugins` explicitly, because an o
 
 The repository's `tsconfig.json` holds its Effect override under `compilerOptions.plugins`.
 The override includes the same source paths and excludes the same exempt paths as oxlint.
-The kit ships severity values in `presets/effect.language-service.json` for the override's `options`.
+The kit ships severity values in `src/quality/presets/effect.language-service.json` for the override's `options`.
 The kit's `tsconfig.effect.json` keeps the shared language service diagnostics.
 
 ## Related topics

package/docs/configs/native-settings.md

@@ -13,7 +13,9 @@ A consuming repository puts each setting in the file its tool reads.
 | `.github/workflows/*.yml` | Pull request commands, scheduled commands, runner labels | GitHub Actions and `checks-ci-wiring` |
 | `.oxlintrc.json` | Effect paths, exemptions, file size, function size, statements, cognitive complexity and depth | oxlint |
 | `oxlint-suppressions.json` | The existing violations oxlint suppresses, per file and rule | oxlint and `checks-suppressions-ratchet` |
+| `exports-baseline.json` | The existing unused exports and types, per file, kind and name | `checks-exports` |
 | `.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, spread over the kit's `knip-base.json` | Knip, `checks-unused` and `checks-exports` |
 | `tsconfig.json` | Effect language service scope and severity | 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` |
@@ -55,9 +57,9 @@ A repository records its existing violations with `oxlint --suppress-all`, which
 `checks-suppressions-ratchet` refuses any count in that file that rises, so the recorded debt only falls.
 The kit's own `.oxlintrc.json` sets these limits for each size override, and a repository may copy them:
 
-<!-- generated size-limits: bun run build writes it from .oxlintrc.json, SIZE_RULES in scripts/size-rules.ts and scripts/doc-blocks.ts -->
+<!-- generated size-limits: bun run build writes it from .oxlintrc.json, SIZE_RULES in src/complexity/size-rules.ts and scripts/doc-blocks.ts -->
 
-| Limits | oxlint rule | `effect-channel/**/*.ts`, `readability/**/*.ts`, `scripts/**/*.ts` | `tests/**/*.ts` |
+| Limits | oxlint rule | `src/**/*.ts`, `scripts/**/*.ts` | `tests/**/*.ts` |
 | --- | --- | --- | --- |
 | The most lines a file may hold, blank and comment lines counted | `max-lines` | 400 | 600 |
 | The most lines a function may span, blank and comment lines counted | `max-lines-per-function` | 100 | off |

package/docs/design.md

@@ -12,8 +12,14 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
 - `files` in package.json is the published surface: `tests/`, `AGENTS.md` and the `.ts` plugin source never reach an install.
   npm adds `package.json`, `README` and `LICENSE` to the tarball whatever `files` says.
   `bun pm pack` builds the same tarball the registry serves, which is what the packed-tarball consumer e2e test installs.
-- Each plugin ships compiled under `dist/`, built with `bun build <name>/index.ts --outdir dist/<name> --target node --format esm`.
+- Each plugin ships compiled under `dist/`, built with `bun build src/<vector>/<name>/index.ts --outdir dist/<name> --target node --format esm`.
   Node refuses to type-strip a `.ts` plugin under `node_modules`, so the `.ts` source would fail to load from an installed package.
+- The source sits under `src/<vector>/`, one directory for each thing the kit judges a repository on: complexity, quality, testing, docs, delivery and dependencies.
+  `src/core/` holds what every vector runs on, and `scripts/` holds only the kit's own build, which nothing ships.
+  Sorting by what loads a file put the two oxlint plugins at the root and every bin in one flat `scripts/`, so the files for one purpose sat in several places and nothing said which gate a helper served.
+  A mutation runner's default scope covers `src/`, so the kit's own Stryker run mutates its source without a `mutate` list.
+  The testing vector and its directory are named testing rather than tests, since a `src/tests/` beside the root `tests/` would read as a second suite.
+  An `exports` key a consumer resolves as a specifier keeps pointing at the file's new home, so that specifier resolves as before while a path read without resolution does not.
 - The size rules are plain oxlint rules at `error` in `.oxlintrc.json`, and `bun run lint` enforces them on the whole tree.
   A repository records its existing violations with `oxlint --suppress-all`, and `checks-suppressions-ratchet` refuses any count that rises.
   The kit runs no size script of its own, since restating how oxlint reads its config and compares sites left corners the native rules never had.
@@ -24,7 +30,7 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
 - `dist/` is committed.
   No `prepack` or `prepublishOnly` builds it, so a publish ships whatever bundle the publishing worktree holds.
   Rebuild it after pulling with `bun run build`.
-  `bun run build` also emits `templates/` and `CHANGELOG.md`, which are committed the same way.
+  `bun run build` also emits `dist/templates/` and `CHANGELOG.md`, which are committed the same way.
   CI runs `git diff --exit-code` over the whole tree after the build, because a test that compares a generated file with its source passes on the copy the build just rewrote.
 - `CHANGELOG.md` is generated, so a release commit carries it and the tarball ships it.
   The commit that bumps package.json `version` closes its release, and the `v*` tag goes on that commit, so commits merged after it wait for the next release.
@@ -72,7 +78,7 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   Setting your own `options.enhancedResolveOptions` replaces the base's, so restate `exportsFields` and `conditionNames` if you do.
 - dependency-cruiser `extends` merges same-name `forbidden` rules with the child's fields winning.
   That is the entry-point and layer recipe under Boundaries in [The dependency rules](configs/dependency-rules.md).
-- The templates in `templates/` are rendered from `scripts/doc-templates.ts`, the spec `checks-docs` reads.
+- The templates in `dist/templates/` are rendered from `src/docs/doc-templates.ts`, the spec `checks-docs` reads.
   A template written by hand beside the check agrees with it only until someone edits one of them.
 - A page's Diátaxis mode comes from `kind` front matter on the page, whatever directory holds it.
   The repository makes the judgment beside the page, and the check holds it to that template.
@@ -86,7 +92,7 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   Under a hard wrap a one-word edit reflows a paragraph, and the gate would then demand fixes to sentences the edit never touched.
 - An agent file such as `AGENTS.md` takes the separator rules and no other prose rule.
   One sentence per line serves the people who review a doc's diffs, and an agent file keeps each entry to one line however many sentences it holds.
-- `scripts/prose-matchers.ts` imports nothing, so the gate and a write-time hook run one matcher and refuse in the same words.
+- `src/docs/prose-matchers.ts` imports nothing, so the gate and a write-time hook run one matcher and refuse in the same words.
   A hook bundle ships without `node_modules`, so a matcher that needed Vale or a package could not refuse at write time.
 - Readability grades and words such as easy stay out of the prose rules.
   A score cannot fail a change without failing correct prose, and a suggestion nobody runs an editor for is never seen.

package/docs/gates/checks-comment-gate.md

@@ -16,15 +16,15 @@ A refusal counts when any line of the comment carrying it was added.
 
 ## What it reads
 
-It reads the diff between two commits, and the added lines of each file whose extension has a comment syntax in `scripts/comment-matchers.ts`.
+It reads the diff between two commits, and the added lines of each file whose extension has a comment syntax in `src/quality/comment-matchers.ts`.
 It passes over a file with any other extension.
 
-`scripts/comment-matchers.ts` holds the scanner, the comment syntaxes and a synchronous `refused()`, and imports nothing.
+`src/quality/comment-matchers.ts` holds the scanner, the comment syntaxes and a synchronous `refused()`, and imports nothing.
 A host such as a hook bundle can therefore copy it alone into a directory with no `node_modules` and import it as `@avi2dg/checks/scripts/comment-matchers.ts`.
 The kit's own dependency cruise fails when that file gains an import.
 `REFUSED_DIRECTIVES` in that file owns the refused directive names, and the checker builds its directive pattern from that list, so the two cannot disagree.
 A consumer reads the same contract by importing `REFUSED_DIRECTIVES` from `@avi2dg/checks/scripts/comment-matchers.ts`.
-`scripts/comments.ts` wraps the same matchers in Effect for the gate and for [checks-backtest](checks-backtest.md).
+`src/quality/comments.ts` wraps the same matchers in Effect for the gate.
 
 ## Arguments
 
@@ -60,5 +60,4 @@ It applies to every repository, so no selection leaves it out.
 
 ## Related topics
 
-- [checks-backtest](checks-backtest.md)
 - [checks-lint](checks-lint.md)

package/docs/gates/checks-docs.md

@@ -11,23 +11,25 @@ audience: consumers
 It holds each doc file a change touches to the template for its kind, and lists every other doc file that does not conform yet without failing.
 It holds each line a change adds or edits in a living doc or an agent file to the prose rules, as [The prose rules](#the-prose-rules) says.
 It fails when a living doc names a path, link or command that does not resolve, and the range added it or broke it, as [Paths, links and commands](#paths-links-and-commands) says.
-The package ships one template per kind under `templates/`, and a repository starts a new doc file by copying one:
+The package ships one template per kind under `dist/templates/`, and a repository starts a new doc file by copying one:
 
 ```sh
-cp node_modules/@avi2dg/checks/templates/how-to.md docs/add-a-supplier.md
+cp node_modules/@avi2dg/checks/dist/templates/how-to.md docs/add-a-supplier.md
 ```
 
-<!-- generated doc-kinds: bun run build writes it from scripts/doc-rules.ts, scripts/doc-templates.ts and scripts/doc-blocks.ts -->
+A host resolves a template as `@avi2dg/checks/templates/how-to.md`, which keeps pointing at it wherever the package holds the templates.
+
+<!-- generated doc-kinds: bun run build writes it from src/docs/doc-rules.ts, src/docs/doc-templates.ts and scripts/doc-blocks.ts -->
 
 | File | Kind | Template |
 | --- | --- | --- |
-| `README.md` | readme | `templates/readme.md` |
-| `CHANGELOG.md` | changelog | `templates/changelog.md` |
-| `AGENTS.md` | agents | `templates/agents.md` |
-| `CLAUDE.md` | claude | `templates/claude.md` |
-| `CONTRIBUTING.md` | how-to | `templates/how-to.md` |
-| each file in `docs/adr/` but its generated index, `README.md` | adr | `templates/adr.md` |
-| a page with `kind` in front matter | tutorial, how-to, reference or explanation | `templates/<mode>.md` |
+| `README.md` | readme | `dist/templates/readme.md` |
+| `CHANGELOG.md` | changelog | `dist/templates/changelog.md` |
+| `AGENTS.md` | agents | `dist/templates/agents.md` |
+| `CLAUDE.md` | claude | `dist/templates/claude.md` |
+| `CONTRIBUTING.md` | how-to | `dist/templates/how-to.md` |
+| each file in `docs/adr/` but its generated index, `README.md` | adr | `dist/templates/adr.md` |
+| a page with `kind` in front matter | tutorial, how-to, reference or explanation | `dist/templates/<mode>.md` |
 
 <!-- end generated doc-kinds -->
 
@@ -60,7 +62,7 @@ A template decides a file's structure, and the template file itself is the refer
 
 A line a change adds or edits in a living doc or an agent file is held to the prose rules, and a line the change leaves alone is not, so a repository needs no cleanup pass before it runs them.
 
-<!-- generated living-docs: bun run build writes it from scripts/prose-matchers.ts and scripts/doc-blocks.ts -->
+<!-- generated living-docs: bun run build writes it from src/docs/prose-matchers.ts and scripts/doc-blocks.ts -->
 
 A living doc is one of these:
 
@@ -77,7 +79,7 @@ These are records, and take no prose rule:
 
 <!-- end generated living-docs -->
 
-<!-- generated prose-rules: bun run build writes it from PROSE_RULES in scripts/prose-matchers.ts and scripts/doc-blocks.ts -->
+<!-- generated prose-rules: bun run build writes it from PROSE_RULES in src/docs/prose-matchers.ts and scripts/doc-blocks.ts -->
 
 | Refused | For example | Write instead | In agent files |
 | --- | --- | --- | --- |
@@ -98,14 +100,14 @@ A bold label that opens a line, as in `**Status.**`, heads the sentence after it
 Fenced code, inline code, link destinations, URLs, HTML comments and front matter are not prose, so no rule reads them.
 Readability scores and word choice, such as easy, are not checked.
 
-`scripts/prose-matchers.ts` holds the rules and a synchronous `proseRefused()`, and imports nothing.
+`src/docs/prose-matchers.ts` holds the rules and a synchronous `proseRefused()`, and imports nothing.
 A host such as a hook bundle can therefore copy it alone into a directory with no `node_modules` and import it as `@avi2dg/checks/scripts/prose-matchers.ts`, to refuse the same lines at write time.
 
 ## Paths, links and commands
 
 Each reference a living doc names has to resolve at the head commit:
 
-- A path in inline code that ends in a file extension, such as `scripts/lint.ts`, names a file from the root or from the doc's directory.
+- A path in inline code that ends in a file extension, such as `src/core/lint.ts`, names a file from the root or from the doc's directory.
 - A relative Markdown link names a file or a directory, and its anchor names a heading in the file it links, as GitHub derives the anchor, or an explicit `id`.
 - A `bun run` command in code names a script in the nearest `package.json`, a bin in `node_modules/.bin`, or a file that exists.
 

package/docs/gates/checks-exports.md

@@ -0,0 +1,104 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-exports
+
+`checks-exports` is the gate that refuses an exported value or type nothing imports, and a reader looks it up when Knip names a symbol no file reaches.
+
+## What it checks
+
+It runs Knip with the repository's own configuration and names each exported value and type no file imports.
+It reads only the exports and types issue types, so an unreferenced file or an unused dependency never fails it.
+It asks Knip for those issue types itself, so a configuration that narrows `include` or excludes them still has its exports judged.
+A configuration that turns the exports or types rules off silences those symbols, so keep both rules on.
+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 fails when the repository tracks no TypeScript source, 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 export from a public one.
+
+## What it reads
+
+It runs Knip 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.
+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 base loads there too.
+Knip configurations do not extend a package file, so the consumer configuration imports the kit's base and spreads it:
+
+```ts
+import base from "@avi2dg/checks/knip-base.json";
+
+export default { ...base, entry: ["src/index.ts", "tests/**/*.test.ts"] };
+```
+
+The base in `knip-base.json` reports only unreferenced files.
+The gate resolves the Knip binary from the installed kit, so a consumer installs nothing beyond the kit.
+
+## Arguments
+
+```sh
+checks-exports <base-ref> <head-ref>
+checks-exports <ref>
+checks-exports --write
+```
+
+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 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 `--write` it records every unused export and type Knip reports into `exports-baseline.json`, the way `oxlint --suppress-all` seeds `oxlint-suppressions.json`.
+
+## Seeding a baseline
+
+A repository adopting the gate runs `checks-exports --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 reported symbol is unlisted, no baseline entry is added or stale, or `--write` recorded the baseline |
+| 1 | a reported symbol is unlisted, a baseline entry is added or stale or the repository holds no Knip configuration |
+| 2 | a ref does not resolve, the repository tracks no TypeScript source, Knip cannot run, or a report or baseline does not parse |
+
+## Sample output
+
+```
+exports: 2 unused export(s) not in exports-baseline.json:
+  src/used.ts: unusedExport (export)
+  src/used.ts: UnusedOptions (type)
+```
+
+A baseline entry the range adds fails when Knip does not report its symbol unused at the base:
+
+```
+exports: 1 exports-baseline.json export(s) the range adds that its base did not leave unused, remove the export instead:
+  src/used.ts: unusedExport (export)
+```
+
+A passing run with a held baseline counts what it holds:
+
+```
+exports: 2 unused export(s) in exports-baseline.json, and no new ones
+```
+
+A passing run with an empty baseline says so:
+
+```
+exports: no unused exports or types
+```
+
+## Opting out
+
+`checks-lint` runs this gate only when the repository tracks `.ts` or `.tsx` files.
+A repository that tracks one names its entries in a Knip configuration.
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [checks-suppressions-ratchet](checks-suppressions-ratchet.md)
+- [checks-unused](checks-unused.md)

package/docs/gates/checks-flake.md

@@ -43,7 +43,7 @@ checks-flake: 3 of 10 run(s) failed, 1 test(s) failing in them
 
 | Test | Failed | Seeds |
 | --- | --- | --- |
-| tests/cache.test.ts:6 reads the cache | 3 of 10 runs | 2170533150, 4046124386, 180394251 |
+| tests/unit/cache.test.ts:6 reads the cache | 3 of 10 runs | 2170533150, 4046124386, 180394251 |
 
 Reproduce a failing run with bun test --randomize --seed=<seed>.
 ```

package/docs/gates/checks-lint.md

@@ -8,7 +8,7 @@ audience: consumers
 
 ## What it checks
 
-It runs the gates under [What runs](../../README.md#what-runs) in table order, each in its own process.
+It runs the gates under [What runs](../../README.md#what-runs), each in its own process.
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
 All other gates run for every repository.
 

package/docs/gates/checks-quarantine-clock.md

@@ -43,7 +43,7 @@ With one it judges that commit, including a repository's first commit.
 
 ```
 quarantine-clock: 1 test(s) in tests/quarantine/ is past 30 days; fix each and move it back, or delete it:
-  tests/quarantine/billing.test.ts entered quarantine on 2026-08-01 (45 days ago)
+  tests/quarantine/unit/billing.test.ts entered quarantine on 2026-08-01 (45 days ago)
 ```
 
 ## Opting out

package/docs/gates/checks-test-layout.md

@@ -10,18 +10,20 @@ audience: consumers
 
 It fails unless the repository holds this shape, and names the file and the path to move it to when it does not.
 
-- Every test file is `tests/**/*.test.ts` or `.tsx`.
-  A `*.test.ts`, `*.spec.ts` or `*_test.ts` under `src/`, `test/`, `__tests__/` or the repository root fails.
+- Every test file is `tests/<level>/**/*.test.ts` or `.tsx`, and the level is `unit`, `e2e`, `live` or `pixel`.
+  A quarantined test keeps its level as `tests/quarantine/<level>/**/*.test.ts`.
+  A `*.test.ts`, `*.spec.ts` or `*_test.ts` under `src/`, `test/`, `__tests__/`, the repository root or a directory under `tests/` that names no level fails.
+  The path it names for the move is under `tests/unit/` unless the file already sits under a level.
 - `tests/lib/**` holds helpers and `tests/fixtures/**` holds data, and neither may hold a test file.
-  Every other directory directly under `tests/` is a test group and may nest as deep as it likes.
+  Under its level, a test may sit in groups nested as deep as it likes.
 - `tests/live/**` holds tests that need a live machine, and `tests/pixel/**` holds tests that need a display.
   Bun ignores both directories in the default suite.
   A live tier with test files requires `test:live` set to `checks-test --tier=live`.
   A pixel tier with test files requires `test:pixel` set to `checks-test --tier=pixel`.
-- A test runs at one of two levels.
-  A test outside `tests/e2e/`, `tests/live/` and `tests/pixel/` runs in-process, so it may not import `node:child_process`, `net`, `http`, `https`, `http2`, `tls` or `dgram`.
+- A test runs in-process or in a process of its own.
+  A test outside the `e2e`, `live` and `pixel` levels runs in-process, quarantined or not, so it may not import `node:child_process`, `net`, `http`, `https`, `http2`, `tls` or `dgram`.
   It may not import `$`, `spawn`, `spawnSync`, `connect`, `serve` or `listen` from `bun`, may not touch `Bun.$` or `Bun.spawn`, and may not call `fetch`.
-  A test inside `tests/e2e/`, `tests/live/` or `tests/pixel/` may do all of it.
+  A test at the `e2e`, `live` or `pixel` level may do all of it, under `tests/quarantine/` as well.
   Helpers in `tests/lib/**` answer to the same rule, since an in-process test reaches them.
 - `scripts.test` is exactly `checks-test`, which runs `bun test --randomize` as [checks-test](checks-test.md) says.
 - `scripts.lint` runs this check, itself or through `checks-lint` called by its bare bin name.
@@ -30,12 +32,15 @@ It fails unless the repository holds this shape, and names the file and the path
   The check also accepts the list without `repos/**`, so a repository that links no library under `repos/` may drop it.
   Other tables, and extra `[test]` keys, are the repository's own.
 
-The in-process half is what a mutation run can mutate.
+The in-process tests under `tests/unit/` are what a mutation run takes as its tests, and a runner names them by that path rather than by a list of paths to ignore.
 `tests/e2e/**` is left out of a mutate scope by construction, because a subprocess kills both the speed and the coverage signal a mutant needs.
 
 The preset also skips `tests/quarantine/**` and `repos/**` on a default run.
 The `repos/**` entry keeps the suite from following the library links `checks-vendor` manages into trees whose tests are not this repository's.
-A test that turns flaky moves there, so the suite stays trustworthy, and the flake still runs on demand:
+A test that turns flaky moves there at its own level, so the suite stays trustworthy.
+A flaky test under `tests/e2e/stack/` moves to the same path under `tests/quarantine/e2e/stack/`, where it may still spawn, and moves back once fixed.
+A `quarantine` directory below a level is refused, since the preset's ignore does not reach it and the test would still run.
+The flake still runs on demand:
 
 ```sh
 bun test --path-ignore-patterns='' tests/quarantine
@@ -72,7 +77,7 @@ It checks the directory it runs in, or the directory it is given.
 
 ```
 test-layout: 4 violation(s)
-  src/a.test.ts: a test file must live at tests/**/*.test.ts; move it to tests/a.test.ts
+  src/a.test.ts: a test file must live at tests/<level>/**/*.test.ts, or tests/quarantine/<level>/**/*.test.ts while quarantined, with unit, e2e, live, or pixel as the level; move it to tests/unit/a.test.ts
   package.json: scripts.test must be exactly "checks-test", which runs bun test --randomize and judges its skips, found "bun test"
   package.json: scripts.lint must run the layout check: add "checks-lint"
   bunfig.toml: bunfig.toml is missing; bun has no bunfig extends, so copy node_modules/@avi2dg/checks/bunfig.toml

package/docs/gates/checks-test.md

@@ -87,7 +87,7 @@ It refuses test filters because every test excluded by a filter would look skipp
 
 ```
 checks-test: 1 skipped test(s) undeclared in this local run:
-  tests/pricing.test.ts:12 rounds half to even: skipped with no reason at its test site; use test.skipIf(condition)(skipReason(reason, name), fn)
+  tests/unit/pricing.test.ts:12 rounds half to even: skipped with no reason at its test site; use test.skipIf(condition)(skipReason(reason, name), fn)
 ```
 
 A run with no skipped tests ends with: