@avi2dg/checks 0.11.0 → 0.13.0

package/README.md

@@ -8,15 +8,25 @@ run that records the seeds a failing test fails with, the oxlint base
 config, the tsconfig fragment with the Effect language-service block,
 the `quality.json` schema with the generator that turns its Effect paths
 into oxlint and tsconfig fragments, the shared commitlint config, the
-shared dependency-cruiser base, the test-layout check with its bunfig preset, the commit-identity check, the
+shared dependency-cruiser base with the feature-owner rules `quality.json`
+compiles into it, the test-layout check with its bunfig preset, the commit-identity check, the
 comment gate with its backtest, the oxlint suppressions ratchet, the
+size budget, the feature-owner change signal and proof check, the
 Stryker mutation-testing preset with its no-regression comparator, the
-CI-wiring check, and the Effect error-channel plugin compiled to
-JavaScript.
+CI-wiring check, a template for each kind of doc file with the gate that
+holds each doc file to its template, and the Effect error-channel plugin
+compiled to JavaScript.
 
 Published as `@avi2dg/checks` on the public npm registry.
 
-## Consume it
+## Before you begin
+
+- Bun, which runs every bin.
+  The kit is tested on the version its own `.bun-version` pins.
+- A git repository, whose history the range gates read.
+- The peer versions the install line below pins, which `peerDependencies` in `package.json` holds.
+
+## Install
 
 From the consuming repo:
 
@@ -48,7 +58,7 @@ node_modules/
 ```
 
 `quality.json` at the repository root declares what the repository
-opts into, starting with the commands its CI runs; see "Quality file"
+opts into, starting with the commands its CI runs. See "Declare policy in the quality file"
 below:
 
 ```json
@@ -73,9 +83,9 @@ cp node_modules/@avi2dg/checks/bunfig.toml bunfig.toml
 ```
 
 `checks-test` runs `bun test --randomize` and fails on a skip the
-repository has not declared; see "Test entry point" below.
+repository has not declared. See "Run the suite" below.
 
-`checks-lint` runs every kit gate a lint needs; see "Lint entry point"
+`checks-lint` runs every kit gate a lint needs. See "Run every lint gate"
 below. Three of them:
 
 `lint-coverage.sh` fails when oxlint silently skips a tracked `.ts` or
@@ -87,7 +97,7 @@ or its config does not parse.
 `test-layout.ts` decides the test layout described below.
 
 `commit-identity.ts` refuses a commit with an author other than the
-repository owner; see "Commit identity" below.
+repository owner. See "Check commit identities" below.
 
 A repo that runs mutation testing installs `@stryker-mutator/core` and
 `@hughescr/stryker-bun-runner`, then spreads the shipped preset in
@@ -104,7 +114,7 @@ export default {
 The registry version is pinned by the consumer's lockfile; bump
 `@avi2dg/checks` to adopt a new release.
 
-## Quality file
+## Declare policy in the quality file
 
 `quality.json` at the repository root says what the repository has
 opted into. The kit's bins find it at the git root and read it there:
@@ -122,26 +132,43 @@ opted into. The kit's bins find it at the git root and read it there:
     "production": ["src/**/*.ts"],
     "effect": { "paths": ["src/**/*.ts"], "exempt": ["src/host/*.ts"] }
   },
-  "agentRules": { "on": [], "off": [] }
+  "size": { "fileLines": 400, "functionLines": 100, "applies": "changed" },
+  "features": [
+    {
+      "name": "billing",
+      "root": "src/billing",
+      "entries": ["src/billing/index.ts"],
+      "allowFrom": ["src/main.ts"],
+      "proof": "tests/e2e/billing.test.ts"
+    }
+  ],
+  "changeSignal": "advisory",
+  "agentRules": { "on": [], "off": [] },
+  "docs": { "pages": { "reference": ["docs/gates/*.md"], "explanation": ["docs/design.md"] } }
 }
 ```
 
 | Key | Read by | Holds |
 | --- | --- | --- |
 | `defaultBranch` | `checks-lint`, `checks-ci-wiring` | the branch pull requests merge into, `main` when absent |
-| `gates.ci` | `checks-ci-wiring` | the commands CI runs on every pull request; see "CI wiring" |
+| `gates.ci` | `checks-ci-wiring` | the commands CI runs on every pull request. See "Check the CI wiring" |
 | `gates.scheduled` | `checks-ci-wiring` | the commands a schedule runs |
-| `gates.lint` | `checks-lint`, `checks-ci-wiring` | the gates `checks-lint` runs when not all apply; see "Gate selection" |
-| `commitIdentity.authors` | `checks-commit-identity` | the identities allowed to author and commit; see "Commit identity" |
-| `sources.effect` | `checks-quality` | the paths held to the Effect rules, and the files under them that are not; see "Effect rules" |
-| `sources.production` | no kit gate yet | the source the repository ships |
+| `gates.lint` | `checks-lint`, `checks-ci-wiring` | the gates `checks-lint` runs when not all apply. See "Gate selection" |
+| `commitIdentity.authors` | `checks-commit-identity` | the identities allowed to author and commit. See "Check commit identities" |
+| `sources.effect` | `checks-quality` | the paths held to the Effect rules, and the files under them that are not. See "Enforce the Effect rules" |
+| `sources.production` | `checks-size-budget`, `checks-quality` | the source the repository ships. See "Hold files to a size budget" |
+| `size` | `checks-size-budget` | the line budget, and which production files it holds. See "Hold files to a size budget" |
+| `features` | `featureRules`, `checks-feature-owners` | each feature's root, entries, exempt importers and proof. See "Declare feature owners" |
+| `changeSignal` | `checks-feature-owners` | `advisory` to list the feature owners a change touches. See "Declare feature owners" |
 | `agentRules.on`, `agentRules.off` | agent Rule selection, not the kit | catalogued Rules switched on or off for this repository |
+| `docs.pages` | `checks-docs` | the Diátaxis mode of each page, by glob. See "Hold docs to their templates" |
 
 Every key is optional. The bins decode the file with one Effect
 `Schema`, and the package ships `quality.schema.json` emitted from that
 schema, so the `$schema` line gives an editor the verdict the bins
-reach, save one: a Rule switched both on and off, which the bins refuse
-and no JSON Schema can express across two lists. A key the schema does
+reach, save what no JSON Schema can express across two values, which
+the bins refuse: a Rule switched both on and off, a feature entry
+outside its root, and two features with one name or sharing a root. A key the schema does
 not name is refused, not ignored, so a misspelt `sources` cannot switch
 the Effect rules off unnoticed. A glob in `sources`
 starts at the repository root, names a directory first, uses `*`
@@ -213,8 +240,9 @@ that changes a preset reaches the repository through its next
   `sources.effect`;
 - `.oxlintrc.json` or `tsconfig.json` does not list its fragment in
   `extends`, so the tool never reads it;
-- a `sources.effect.paths` glob matches no tracked or untracked file,
-  so it holds nothing to the rules.
+- a `sources.effect.paths` glob, or a `sources.production` glob while
+  `size` is declared, matches no tracked or untracked file, so it holds
+  nothing.
 
 It exits 2 when `quality.json` does not decode. `generate` writes the
 fragments, removes a left-over one, then runs the same check.
@@ -240,12 +268,12 @@ pin both:
   because one that leaves any of the kit's out turns on the category
   rules of the plugins it adds under every declared path.
 
-## Lint entry point
+## Run every lint gate
 
 `checks-lint` runs each of the kit's lint gates in turn and names every
 one that fails, rather than stopping at the first. A repository whose
 tracked files give a gate nothing to check can leave it out through
-`gates.lint`; see "Gate selection" under "CI wiring".
+`gates.lint`. See "Gate selection" under "Check the CI wiring".
 
 | Gate | Reads |
 | --- | --- |
@@ -255,7 +283,10 @@ tracked files give a gate nothing to check can leave it out through
 | `checks-comment-gate` | the range |
 | `checks-suppressions-ratchet` | the range |
 | `checks-ci-wiring` | the working tree |
+| `checks-docs` | the range |
 | `checks-quality` | the working tree |
+| `checks-size-budget` | the range |
+| `checks-feature-owners` | the range |
 
 ```sh
 checks-lint
@@ -267,7 +298,7 @@ Locally, and on any event other than a pull request, the range ends at
 `HEAD` and starts where `HEAD` branched from the origin default branch:
 `origin/HEAD`, or when `origin/HEAD` is not set, as in an
 `actions/checkout` clone, `origin/<defaultBranch>` from the
-repository's `quality.json` (see "Quality file"), and `origin/main` when
+repository's `quality.json`, as "Declare policy in the quality file" says, and `origin/main` when
 that is not declared. In a GitHub Actions pull request, where
 `GITHUB_EVENT_NAME` is `pull_request`, it ends
 at the event's head sha and starts where that branched from
@@ -308,13 +339,13 @@ gate's own report, then its verdict:
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
 ...
-checks-lint: 3 of 7 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
+checks-lint: 3 of 9 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
 ```
 
 It exits 1 when any gate found a violation, and 2 when the range or the
 selection does not resolve, or no failing gate could decide. ci-wiring
-always runs, so a repository on `checks-lint` declares `gates.ci`
-(see "CI wiring"), and it holds the test layout unless its selection
+always runs, so a repository on `checks-lint` declares `gates.ci`,
+as "Check the CI wiring" says, and it holds the test layout unless its selection
 leaves out `checks-test-layout`.
 
 CI runs it through `lint`. The checkout fetches the whole history, which
@@ -335,7 +366,7 @@ jobs:
       - run: bun run lint
 ```
 
-## Effect rules
+## Enforce the Effect rules
 
 The base config loads the `effect-channel` plugin and turns on
 `effect-channel/no-error-channel-escape`, which refuses `Effect.ignore`,
@@ -356,7 +387,7 @@ through `Effect.fail`, a throwing call wrapped in `Effect.try` or
 
 A repository turns them on for the paths it writes in Effect by
 declaring those paths in `quality.json` and extending the generated
-fragments; see "Generated fragments" under "Quality file":
+fragments. See "Generated fragments" under "Declare policy in the quality file":
 
 ```json
 "sources": {
@@ -392,7 +423,7 @@ the tsconfig fragment's override, whose severities are
 effect-tsgo keeps the severities `tsconfig.effect.json` sets when a later
 config in `extends` restates the plugin with only its overrides.
 
-## Test layout
+## Lay out the tests
 
 `checks-test-layout` fails unless the repo holds this shape, and names the
 file and the path to move it to when it does not:
@@ -415,7 +446,7 @@ file and the path to move it to when it does not:
   with swc and reads import specifiers and identifier use, so a test that
   only carries `"node:child_process"` as a string is not a violation.
 - `scripts.test` is exactly `checks-test`, which runs `bun test --randomize`
-  (see "Test entry point"), and `scripts.lint` runs this check, itself or
+  as "Run the suite" says, and `scripts.lint` runs this check, itself or
   through `checks-lint` called by its bare bin name.
 - `bunfig.toml` carries every `[test]` key of the shipped preset with the
   same value, and `[test].pathIgnorePatterns` is always
@@ -435,7 +466,7 @@ still run on demand:
 bun test --path-ignore-patterns='' tests/quarantine
 ```
 
-## Test entry point
+## Run the suite
 
 `checks-test` runs the whole suite with `bun test --randomize`, passes
 bun's output through, and then reads bun's JUnit report of the same run.
@@ -478,10 +509,10 @@ passed without writing its report. It takes no arguments: a `-t`
 filter reports every test it leaves out as skipped and a path filter
 drops files a declaration names, so a narrowed run is plain
 `bun test --randomize` with the arguments. Files under
-`tests/quarantine/` are never run and so never reported; see "Test
+`tests/quarantine/` are never run and so never reported. See "Test
 layout".
 
-## Flake run
+## Find flaky tests
 
 A green run proves nothing failed in that run, not that no test is
 flaky. `checks-flake` runs the whole suite several times, each with its
@@ -536,9 +567,9 @@ jobs:
 ```
 
 and declares the step in `gates.scheduled`, so `checks-ci-wiring`
-fails once the schedule stops running it; see "CI wiring".
+fails once the schedule stops running it. See "Check the CI wiring".
 
-## Dependency rules
+## Enforce dependency rules
 
 `.dependency-cruiser.cjs` extends the shared base, which carries
 `no-circular`, `no-orphans`, `not-to-dev-dep` (shipped source importing
@@ -566,7 +597,9 @@ boundary you own. A rule that restates a base name overrides it field
 by field, which is how an entry point stops being an orphan:
 redeclare `no-orphans` with your entry added to its `pathNot`.
 This repo's own `.dependency-cruiser.cjs` does that for the plugin
-entry.
+entry. A repository that declares feature owners spreads the rules
+`quality.json` compiles to into the same `forbidden`. See "Feature
+owners".
 
 `package.json` gains the script:
 
@@ -586,7 +619,7 @@ jobs:
       - run: bun run lint:deps
 ```
 
-## Commit lint
+## Lint commit messages
 
 Commits follow `@commitlint/config-conventional` plus the house
 prefixes listed in `commitlint.config.js`, shared from
@@ -625,7 +658,7 @@ It never sees a commit's author or committer fields, nor the
 squashes, so it cannot enforce who a commit belongs to. The
 commit-identity check below is the enforcement.
 
-## Commit identity
+## Check commit identities
 
 `scripts/commit-identity.ts` walks every commit in a range and fails when
 one carries an identity other than the repository owner's:
@@ -651,9 +684,10 @@ owners restates it in `quality.json`:
 }
 ```
 
-`checks-lint` runs it over each pull request's range; see "Lint entry point".
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
 
-## Comment gate
+## Refuse banned comments
 
 `scripts/comment-gate.ts` runs the comment check over a diff and fails
 when an added line carries a banned comment:
@@ -682,9 +716,10 @@ and import it as `@avi2dg/checks/scripts/comment-matchers.ts`. The repo's
 cruise fails when it gains an import. `scripts/comments.ts` wraps the
 same matchers in Effect for the gate and the backtest.
 
-`checks-lint` runs it over each pull request's range; see "Lint entry point".
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
 
-## Suppressions ratchet
+## Ratchet the suppressions
 
 `scripts/suppressions-ratchet.ts` holds oxlint's bulk-suppression
 baseline, `oxlint-suppressions.json`, to counts that only fall. oxlint
@@ -715,9 +750,234 @@ suppressions-ratchet: 2 count(s) in oxlint-suppressions.json rose or appeared; f
   src/dispatch.ts typescript/no-non-null-assertion rose from 12 to 13
 ```
 
-`checks-lint` runs it over each pull request's range; see "Lint entry point".
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
+
+## Hold files to a size budget
+
+`checks-size-budget` holds production files to the line budget
+`quality.json` declares, and lists every other file over it without
+failing:
+
+```json
+"sources": { "production": ["src/**/*.ts"] },
+"size": { "fileLines": 400, "functionLines": 100, "applies": "changed" }
+```
+
+```sh
+checks-size-budget <base-ref> <head-ref>
+checks-size-budget <ref>
+```
+
+It runs oxlint with a configuration of two rules and nothing else:
+`max-lines` at `fileLines` and `max-lines-per-function` at
+`functionLines`, both counting blank and comment lines. With `applies`
+set to `changed` it holds the files under `sources.production` that the
+range adds or changes, a rename that edits the file included. With
+`all` it holds every file under `sources.production`. A file the range
+deletes or only renames is not held. Every other tracked `.ts` or
+`.tsx` file over the budget, tests and unchanged production files alike,
+is listed as advisory and never fails the gate; `.d.ts` files are not
+measured.
+
+It reads each file from the head commit rather than the working tree,
+so an uncommitted edit neither fails nor passes a range, and a pull
+request's merge checkout measures what the pull request holds. With two
+arguments the range starts where the head branched from the base, at
+their merge-base. With one it is that commit against its parent, or
+against the empty tree for a repository's first commit. oxlint must be
+on `PATH`, as it is under a package script.
+
+```
+size-budget: 1 overrun(s) of 400 lines per file and 100 per function in the production files the range adds or changes:
+  src/billing/ledger.ts:12: The function `settle` has too many lines (131). Maximum allowed is 100.
+size-budget: advisory, 1 overrun(s) where the budget does not hold yet:
+  tests/e2e/billing.test.ts: File has too many lines (512).
+```
+
+It exits 1 on an overrun in a file it holds, and 2 when `quality.json`
+does not decode, a ref does not resolve or oxlint cannot run. A
+repository that declares no `size` passes. `quality.json` refuses a
+`size` without `sources.production`, which would hold nothing, and
+with `size` declared `checks-quality` refuses a `sources.production`
+glob that matches no file. Moving `applies` from `changed` to `all`
+tightens the budget to every production file, once the advisory list
+names none.
+
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
+
+## Declare feature owners
+
+A repository opts a feature in by declaring, in `quality.json`, the
+directory it owns, the files code outside it imports it through, the
+files that may reach past those, and the end-to-end test that proves it
+runs:
+
+```json
+"features": [
+  {
+    "name": "billing",
+    "root": "src/billing",
+    "entries": ["src/billing/index.ts"],
+    "allowFrom": ["src/main.ts", "src/cli/*.ts"],
+    "proof": "tests/e2e/billing.test.ts"
+  }
+],
+"changeSignal": "advisory"
+```
+
+`root` is a directory and `entries` are files under it, both without
+globs. `allowFrom` holds globs of the same shape as `sources`. `proof`
+is a `.test.ts` or `.test.tsx` file under `tests/e2e/`. Nothing moves:
+a root is wherever the feature already lives. `quality.json` refuses an
+entry outside its root, a name used twice, and two features sharing a
+root or one root inside another, so a file has at most one owner.
+
+### Import boundary
 
-## CI wiring
+`dist/feature-rules.js` compiles `features` into one dependency-cruiser
+rule per feature, which `.dependency-cruiser.cjs` spreads beside its
+own:
+
+```js
+const { featureRules } = require("@avi2dg/checks/dist/feature-rules.js");
+
+module.exports = {
+  extends: "./node_modules/@avi2dg/checks/dependency-cruiser.config.js",
+  forbidden: [...featureRules(require("./quality.json"))],
+};
+```
+
+A module outside a feature's root that imports a file inside it must
+import one of the feature's `entries`. Modules under `tests/` and the
+files `allowFrom` matches, such as a CLI or a harness, may import any
+file in it:
+
+```
+error feature-billing-entries: src/report.ts → src/billing/charge.ts
+```
+
+`featureRules` decodes its argument with the schema the bins use and
+throws the schema's refusal when it does not decode, which stops the
+cruise. It is an ES module, as `effect` is, so a `.cjs` config loads it
+through `require`, which needs node 20.19, 22.12 or later.
+
+### Change signal and proof
+
+`checks-feature-owners` reads the same declaration over a range:
+
+```sh
+checks-feature-owners <base-ref> <head-ref>
+checks-feature-owners <ref>
+```
+
+It exits 1 when a feature's proof cannot prove it: the proof or an
+entry is not in the head commit, the proof does not parse, or it
+imports none of the feature's entries. An import counts when it is a
+runtime `import`, `export ... from` or `export * from` of a relative
+path that names an entry: by its own name, by the `.js`, `.jsx`, `.mjs`
+or `.cjs` spelling of it, `.js` naming a `.tsx` entry as well as a
+`.ts` one, or without an extension, the way a directory `index` is
+imported. `import type` does not count, and neither does a
+path alias. The proof runs in `bun run test` like any end-to-end test,
+which is what shows it passes.
+
+```
+feature-owners: 1 problem(s) with the features' runnable proofs:
+  billing: proof tests/e2e/billing.test.ts imports none of its entries, src/billing/index.ts
+```
+
+With `changeSignal` set to `advisory` it also lists each owner the
+range touches, with the paths it touched under the owner's root or at
+its proof, and still exits 0. Whether a change that spans owners is one
+coherent slice is for a reviewer to judge. A rename counts at both of
+its paths:
+
+```
+feature-owners: advisory, the range touches 2 feature owner(s); a reviewer judges whether they make one slice:
+  billing: src/billing/charge.ts, src/billing/tax.ts
+  invoices: src/invoices/tax.ts, tests/e2e/invoices.test.ts
+```
+
+It exits 2 when `quality.json` does not decode, which is where a proof
+outside `tests/e2e/` is refused, or a ref does not resolve. A
+repository that declares no feature passes, and `quality.json` refuses
+a `changeSignal` without features, which would map a change to no
+owner.
+
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
+
+## Hold docs to their templates
+
+`checks-docs` 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.
+The package ships one template per kind under `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
+```
+
+| 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` |
+| each file in `docs/adr/` but its generated index, `README.md` | adr | `templates/adr.md` |
+| a page `docs.pages` declares | tutorial, how-to, reference or explanation | `templates/<mode>.md` |
+
+The first four are the files at the repository root.
+No other Markdown file is judged, save a page under `docs/`, which needs a mode.
+Which Diátaxis mode a page is written in is a judgment, so `quality.json` declares it:
+
+```json
+"docs": {
+  "pages": {
+    "reference": ["docs/gates/*.md"],
+    "explanation": ["docs/design.md"]
+  }
+}
+```
+
+A template decides a file's structure, and the template file itself is the reference for each kind:
+
+- A file opens with one `# ` title on its first line and has text before its first section.
+  It skips no heading level, and no heading is Overview, Introduction or How it works.
+- Its sections are the template's headings in the template's order.
+  A heading in angle brackets is one the writer names.
+  One marked verb first is left to review, since no program tells a verb from a noun there.
+  A heading the template does not have, in that place, is refused.
+- A record in `docs/adr/` is named for its four-digit number, and its title opens with the same number.
+  A `Date: YYYY-MM-DD` line follows the title, the first word under Status is Proposed, Accepted, Rejected, Deprecated, Superseded or Retired, and no other record holds its number.
+- A changelog lists its releases newest first, each opening with a `Released YYYY-MM-DD.` line.
+- A how-to or tutorial page numbers its steps.
+- `CLAUDE.md` is its template word for word.
+
+```sh
+checks-docs <base-ref> <head-ref>
+checks-docs <ref>
+```
+
+It reads each file from the head commit.
+With two arguments the range starts where the head branched from the base, at their merge-base.
+With one it is that commit against its parent, or against the empty tree for a repository's first commit.
+A file the range adds, changes or renames is held to its template, and a file it deletes is not.
+
+```
+docs: 2 violation(s) in the doc files the range touches:
+  README.md:1: lacks `## Where things are`
+  docs/parts.md: is a page under docs/ with no mode; declare it under docs.pages in quality.json as tutorial, how-to, reference, explanation
+docs: advisory, 1 doc file(s) the range leaves alone do not hold to their templates yet:
+  docs/adr/0001-quality-gates.md: 5 violation(s)
+```
+
+It exits 1 on a violation in a file the range touches, and 2 when `quality.json` does not decode or a ref does not resolve.
+
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
+
+## Check the CI wiring
 
 `checks-ci-wiring` fails when a command the repository's CI must run no
 longer runs on pull requests to the default branch. No local check sees
@@ -820,8 +1080,9 @@ ci-wiring: 1 of 1 scheduled command(s) do not run on a schedule:
 
 ### Gate selection
 
-A repository with no TypeScript source gives `checks-lint-coverage` and
-`checks-test-layout` nothing to check, and test-layout still refuses its
+A repository with no TypeScript source gives `checks-lint-coverage`,
+`checks-test-layout`, `checks-size-budget` and `checks-feature-owners`
+nothing to check, and test-layout still refuses its
 missing `bun test` script and `bunfig.toml`. It declares the gates
 `checks-lint` runs as `gates.lint`:
 
@@ -833,13 +1094,14 @@ missing `bun test` script and `bunfig.toml`. It declares the gates
     "checks-comment-gate",
     "checks-suppressions-ratchet",
     "checks-ci-wiring",
+    "checks-docs",
     "checks-quality"
   ]
 }
 ```
 
-`checks-lint` runs exactly those, in the "Lint entry point" table's
-order, and all seven when `gates.lint` is absent. A selection in
+`checks-lint` runs exactly those, in the "Run every lint gate" table's
+order, and all ten when `gates.lint` is absent. A selection in
 `quality.json` always keeps `checks-quality`, since the file it sits in
 is what makes that gate apply. A step running
 `checks-lint` then counts only for a declared gate that `gates.lint`
@@ -855,7 +1117,10 @@ A selection may leave out only a gate that does not apply:
 | `checks-comment-gate` | always |
 | `checks-suppressions-ratchet` | always |
 | `checks-ci-wiring` | always |
+| `checks-docs` | always |
 | `checks-quality` | tracks a `quality.json` |
+| `checks-size-budget` | tracks a `.ts` or `.tsx` file |
+| `checks-feature-owners` | tracks a `.ts` or `.tsx` file |
 
 Both bins exit 2 on a `gates.lint` that names an unknown gate or leaves
 out one that always applies. ci-wiring exits 1 when the
@@ -863,9 +1128,11 @@ selection leaves out a gate the repository's tracked files make
 applicable, and names the gate and the files:
 
 ```
-ci-wiring: quality.json gates.lint leaves out 2 gate(s) this repository's contents make applicable:
+ci-wiring: quality.json gates.lint leaves out 4 gate(s) this repository's contents make applicable:
   checks-lint-coverage: the repository tracks TypeScript source (src/widget.ts)
   checks-test-layout: the repository tracks TypeScript source (src/widget.ts)
+  checks-size-budget: the repository tracks TypeScript source (src/widget.ts)
+  checks-feature-owners: the repository tracks TypeScript source (src/widget.ts)
 ```
 
 It reads the files tracked at the checkout, so the pull request that
@@ -886,7 +1153,7 @@ does not evaluate:
   command itself does, the shell's options, and a step or job that
   fails or times out before the gate step.
 
-## Backtest
+## Backtest the comment check
 
 `scripts/backtest.ts` reports what the comment check would have refused
 at each recent commit, so a repository can measure its own history:
@@ -902,7 +1169,7 @@ comment text as a share of added lines.
 `generated/`, `vendor/`, `repos/`, `node_modules/` and `dist/` are out
 of reach, so the figures are authored code.
 
-## Mutation compare
+## Compare mutation scores
 
 `checks-mutation-compare` gates a pull request on no-regression rather
 than an absolute threshold: the head mutation score may not fall below
@@ -948,107 +1215,6 @@ jobs:
 The shared Stryker preset's `json` reporter writes
 `reports/mutation/mutation.json` in each worktree.
 
-## Why it is shaped this way
-
-- Every config in an oxlint `extends` chain brings its own `plugins`,
-  and one that sets none brings oxlint's default plugins, whose
-  category rules the base's `categories` then turn on across the tree.
-  `rules`, `categories` and `jsPlugins` inherit as expected. That is why
-  the consumer snippet restates `plugins` and nothing else, and why the
-  generated fragment always sets them.
-- `node_modules/` is excluded through the consumer's `.gitignore`, not
-  `ignorePatterns`: oxlint still walks the installed package when only
-  `ignorePatterns` names it.
-- `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.
-- The plugin ships compiled as `dist/index.js`, built with
-  `bun build effect-channel/index.ts --outdir dist --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.
-- `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`; CI fails when the committed bundle
-  is stale. `bun run build` also emits `quality.schema.json`, which is
-  committed the same way, and a test fails when it differs from what
-  the schema emits.
-- `quality.json` is JSON, not TOML or a TypeScript module: a bun bin, a
-  hook running without `node_modules`, a `.cjs` or `.mjs` config and
-  `jq` all parse it with nothing installed, and nobody runs a
-  repository's own code to learn its policy. It holds declarations
-  only. The kit's bins read it directly; oxlint and tsc read nothing but
-  their own JSON, so they extend generated fragments, which
-  `checks-quality --check` holds to the declarations.
-- `quality.json` refuses a key its schema does not name, so a kit that
-  cannot enforce a newer key refuses it rather than let the repository
-  believe it enforced.
-- The base parses with swc because typescript 7 (tsgo) has no compiler
-  API for dependency-cruiser to use. Without `@swc/core` installed the
-  cruise silently skips every `.ts` file, so this repo's test asserts its
-  own TypeScript is cruised.
-- `bunfig.toml` has no `extends` and no include: bun ignores an unknown
-  top-level key in silence, so a preset cannot be inherited and the
-  consumer's copy is compared key by key against the installed one
-  instead. `[test] pathIgnorePatterns` is a real bunfig key, and an empty
-  `--path-ignore-patterns` flag overrides the file's own list.
-- The Stryker preset is a JavaScript module, not JSON: Stryker 10 does
-  not resolve `extends` in a JSON config, but a `.mjs` config that
-  spreads an imported object consumes it. Keys the consumer sets after
-  the spread win.
-- The `.ts` bins are written in Effect, so `effect` is a peer dependency
-  and `@effect/platform-bun`, which only the bins use, is a dependency.
-  `@effect/platform-node-shared` is a direct dependency at the same exact
-  version only to pin it: `@effect/platform-bun` asks for it with a `^`
-  range, and a newer rc peers on a newer `effect` than consumers install,
-  so all three move together.
-- Each runnable script ships a `checks-` bin entry, so consumer
-  `package.json` scripts call the short name, which the package manager
-  puts on `PATH` only there; a shell runs it through `bun run`, which
-  never falls back to the registry the way `bunx` does. The `.ts` checks
-  keep a `bun` shebang, which needs no build step and no `dist/`
-  entry, unlike the oxlint plugin that node loads.
-- `checks-lint` runs each gate as its own bin in a child process rather
-  than importing it, so a gate behaves the same called alone or through
-  the entry point, and `lint-coverage.sh` stays a shell script. The
-  gates run one at a time with their output passed straight through, so
-  each report reads whole and in the table's order.
-- A gate selection is checked against the repository's contents rather
-  than trusted, so it cannot skip a gate that applies. ci-wiring does
-  that check, which is why a selection without it, or without another
-  gate that applies everywhere, is refused as `checks-lint` reads it:
-  nothing would check the selection otherwise.
-- `checks-test` runs bun itself rather than reading a report some other
-  run left: a skip taken only on CI is visible only in CI's own run, and
-  an earlier run's report may be stale or narrowed. It reads the JUnit
-  report bun writes to a temporary directory, since bun has no other
-  per-test output meant for a program.
-- `checks-ci-wiring` runs inside `lint`, not in a workflow of its own:
-  deleting the step that runs a check is the violation it catches, so the
-  local `lint` is where it has to fail.
-- Workflows are parsed with `Bun.YAML`, which the `bun` shebang already
-  provides, so the check adds no dependency. It reads `on` as a string
-  key, not as the YAML 1.1 boolean.
-- `bun` counts as a built-in module. Nothing installed resolves it except
-  `@types/bun`, which would otherwise make every runtime `bun` import look
-  like a dev-only dependency.
-- The pull request merge commit GitHub builds is authored by `GitHub
-  <noreply@github.com>`, which commit-identity refuses as an author.
-  `checks-lint` ends a pull request's range at the event's head sha, so
-  the merge commit is never in it. A `lint` that calls
-  `checks-commit-identity HEAD` itself checks out
-  `github.event.pull_request.head.sha` instead of the default merge ref.
-- `no-deep-imports` judges the import specifier, never the resolved file.
-  The base honours `exports` maps, so a subpath the map publishes resolves
-  and passes, one it omits fails to resolve and is reported, and a package
-  without an `exports` map publishes every file. A bare import always
-  passes whatever file its entry lives in. 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 above.
-
 ## Develop
 
 ```sh
@@ -1082,3 +1248,20 @@ every later tag publishes through the workflow.
 
 `publishConfig.access` in package.json is what makes the scoped package
 public.
+
+## Where things are
+
+| Path | What it holds |
+| --- | --- |
+| `scripts/` | every bin, and the modules they share |
+| `effect-channel/` | the Effect error-channel oxlint plugin |
+| `dist/` | the committed bundles of the plugin and of `featureRules` |
+| `presets/` | the Effect presets `checks-quality` builds its fragments from |
+| `templates/` | one template per kind of doc file, which `bun run build` renders |
+| `tests/` | the suite, with the tests that spawn a process under `tests/e2e/` |
+| `docs/` | pages for whoever develops the kit |
+| the root configs | `oxlintrc.json`, `tsconfig.effect.json`, `bunfig.toml`, `commitlint.config.js`, `dependency-cruiser.config.js`, `stryker.preset.js` and `quality.schema.json`, which a consuming repository extends or copies |
+
+## Related topics
+
+- [Why it is shaped this way](docs/design.md)