@avi2dg/checks 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 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.
+
+### Fixes
+
+- **scripts:** list commits merged in after a bump under that release [#82](https://github.com/avi2d/checks/pull/82)
+- **scripts:** leave versions with no listable commits out of the changelog [#81](https://github.com/avi2d/checks/pull/81)
+
 ## 0.24.1
 
 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,24 @@ 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` |
+| 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 +135,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,12 +165,12 @@ 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 |
+| `knip-base.json` | the Knip base a repository's configuration imports |
+| `src/` | every bin, which a package script calls by its `checks-` name, and the modules the bins import |
 | `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 |
 | `oxlintrc.json` | the oxlint base config `.oxlintrc.json` extends |
@@ -179,4 +188,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/native-settings.md

@@ -14,6 +14,7 @@ A consuming repository puts each setting in the file its tool reads.
 | `.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` |
 | `.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 and `checks-unused` |
 | `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 +56,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.
@@ -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 `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-changelog.md

@@ -10,11 +10,15 @@ audience: consumers
 
 It reads the version from `package.json` and treats that version as the release being prepared.
 It lists every conventional commit the release closes, grouped as Features, Fixes, Performance, Reverts and Breaking changes.
+It lists the commits a branch merged in after its bump under that bump, since the squash merge releases them there.
+It leaves out what the branch added past its bump, since the squash merge folds it into the release commit.
+Only a branch carrying its own unlanded bump lists the commits of an unlanded branch it merges, so such a branch takes in only main.
+CI must build the pull request head commit, the `actions/checkout` ref `github.event.pull_request.head.sha`, and not the GitHub merge ref, since the merge ref puts main first and the branch's own bump off the first-parent chain.
 It links each entry to its pull request under the repository address `package.json` names.
 It keeps the date a released section already carries and dates a new section today.
 It writes the whole file newest first, so the changelog is never edited by hand.
 A repository with no tag yet releases from its first commit.
-A release with no conventional commit worth listing keeps only its heading and its date.
+A version with no conventional commit worth listing writes no section.
 
 ## What it reads
 

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

@@ -17,7 +17,7 @@ The package ships one template per kind under `templates/`, and a repository sta
 cp node_modules/@avi2dg/checks/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 -->
+<!-- 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 |
 | --- | --- | --- |
@@ -60,7 +60,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 +77,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 +98,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-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:

package/docs/gates/checks-unused.md

@@ -0,0 +1,65 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-unused
+
+`checks-unused` is the gate that refuses a TypeScript file no entry point reaches, and a reader looks it up when a file seems dead but every other check passes.
+
+## What it checks
+
+It runs Knip with the repository's own configuration and names each `.ts` or `.tsx` file no entry reaches.
+It reads only the files issue type, so an unused export or dependency never fails it.
+It asks Knip for that issue type itself, so a configuration that narrows `include`, excludes files or turns the files rule off still has its files judged.
+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 file from an entry point.
+
+## What it reads
+
+It reads the working tree, so an uncommitted file is judged like a committed one.
+It reads the repository's Knip configuration, which names the entries.
+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
+
+It takes none.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | no tracked file is unreferenced |
+| 1 | a tracked file is unreferenced or the repository holds no Knip configuration |
+| 2 | the repository tracks no TypeScript source, Knip cannot run, or its configuration does not parse |
+
+## Sample output
+
+```
+unused: 1 unreferenced file(s):
+  src/planted-dead.ts
+```
+
+A passing run counts the files it judged:
+
+```
+unused: no unreferenced files among 110 tracked .ts/.tsx file(s)
+```
+
+## 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-repetition](checks-repetition.md)

package/knip-base.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/knip@6.38.0/schema.json",
+  "include": ["files"]
+}