@avi2dg/checks 0.13.0 → 0.14.0

package/docs/gates/checks-docs.md

@@ -0,0 +1,98 @@
+# checks-docs
+
+`checks-docs` is the gate that holds each doc file a change touches to the template for its kind, and a reader looks it up to learn which template a file answers to.
+
+## What it checks
+
+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.
+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
+```
+
+<!-- generated doc-kinds: bun run build writes it from scripts/doc-rules.ts, scripts/quality-file.ts, scripts/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 `docs.pages` declares | tutorial, how-to, reference or explanation | `templates/<mode>.md` |
+
+<!-- end generated doc-kinds -->
+
+A file the table names on its own, such as `README.md`, sits 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.
+  It is a fixed agent pointer rather than a people doc, so the separator ban does not apply to it: people docs take no em dash, en dash, parenthesis or hyphen used as a dash, and no semicolon, and `checks-docs` does not check separators.
+
+## What it reads
+
+It reads each Markdown file from the head commit, and `docs.pages` from `quality.json`.
+A file the range adds, changes or renames is held to its template, and a file it deletes is not.
+
+## Arguments
+
+```sh
+checks-docs <base-ref> <head-ref>
+checks-docs <ref>
+```
+
+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.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every doc file the range touches holds to its template |
+| 1 | a doc file the range touches does not |
+| 2 | `quality.json` does not decode, or a ref does not resolve |
+
+## Sample output
+
+```
+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)
+```
+
+## Opting out
+
+It applies to every repository, so no selection leaves it out.
+A file the range leaves alone is only listed as advisory, so a repository adopts the templates as its files change.
+`checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
+
+## Related topics
+
+- [Why it is shaped this way](../design.md)
+- [checks-lint](checks-lint.md)

package/docs/gates/checks-feature-owners.md

@@ -0,0 +1,113 @@
+# checks-feature-owners
+
+`checks-feature-owners` is the gate that holds each declared feature to a runnable proof and lists the feature owners a change touches, and a reader looks it up to declare a feature.
+
+## What it checks
+
+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, since 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.
+
+The gate fails when a feature's proof cannot prove it:
+
+- the proof or an entry is not in the head commit
+- the proof does not parse
+- the proof 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.
+It names the entry by its own name, by the `.js`, `.jsx`, `.mjs` or `.cjs` spelling of it, or without an extension, the way a directory `index` is imported.
+`.js` names a `.tsx` entry as well as a `.ts` one.
+`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.
+
+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 passes.
+Whether a change that spans owners is one coherent slice is for a reviewer to judge.
+A rename counts at both of its paths.
+
+## What it reads
+
+It reads `features` and `changeSignal` from `quality.json`, each proof and entry from the head commit, and the paths the range touches.
+
+## Arguments
+
+```sh
+checks-feature-owners <base-ref> <head-ref>
+checks-feature-owners <ref>
+```
+
+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.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every feature's proof imports one of its entries |
+| 1 | a feature's proof cannot prove it |
+| 2 | `quality.json` does not decode, which is where a proof outside `tests/e2e/` is refused, or a ref does not resolve |
+
+## Sample output
+
+```
+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`:
+
+```
+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
+```
+
+## Opting out
+
+A repository that declares no feature passes.
+`quality.json` refuses a `changeSignal` without features, which would map a change to no owner.
+A repository that tracks no `.ts` or `.tsx` file leaves it out of `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
+
+## Import boundary
+
+`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.
+
+## Related topics
+
+- [The dependency rules](../configs/dependency-rules.md)
+- [The quality file](../configs/quality-file.md)

package/docs/gates/checks-flake.md

@@ -0,0 +1,88 @@
+# checks-flake
+
+`checks-flake` is the scheduled run that finds flaky tests and records the seeds each one fails with, and a reader looks it up to reproduce a flaky failure.
+
+## What it checks
+
+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 own `--seed`, and records per failing test the seeds it failed with.
+`bun test --randomize --seed=<seed>` puts the suite in the same order, so a seed reproduces a failure that hangs on order.
+A run that fails with no failing test, such as a test file that throws while loading, is listed with its seed on its own line.
+
+## What it reads
+
+It reads bun's JUnit report of each run.
+Under GitHub Actions it appends its summary to the file `GITHUB_STEP_SUMMARY` names, which is the job summary.
+
+## Arguments
+
+```sh
+checks-flake [--runs <count> | --seed <seed>...] [--report <file>]
+```
+
+`--runs` sets the number of runs on random seeds, 10 when absent.
+`--seed`, given once per run, replays chosen seeds, such as the ones a report recorded.
+`--report` writes the record as JSON, holding every run's seed and failing tests and every failing test's seeds.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every run passed |
+| 1 | a run failed |
+| 2 | an argument does not parse, or bun passed without writing its report |
+
+## Sample output
+
+```
+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 |
+
+Reproduce a failing run with bun test --randomize --seed=<seed>.
+```
+
+## Opting out
+
+Nothing runs it but a schedule the repository writes.
+A repository that stops scheduling it also drops it from `gates.scheduled`, which `checks-ci-wiring` otherwise fails on.
+
+## Running it on a schedule
+
+A repository runs it on a schedule and keeps the record as an artifact:
+
+```yaml
+on:
+  schedule:
+    - cron: "17 5 * * *"
+  workflow_dispatch:
+jobs:
+  flake:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx checks-flake --runs 10 --report flake-report.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: flake-report
+          path: flake-report.json
+```
+
+It declares the step in `gates.scheduled`, so `checks-ci-wiring` fails once the schedule stops running it:
+
+```json
+"gates": {
+  "ci": ["bun run lint", "bun run typecheck", "bun run test"],
+  "scheduled": ["bunx checks-flake --runs 10 --report flake-report.json"]
+}
+```
+
+## Related topics
+
+- [checks-test](checks-test.md)
+- [checks-ci-wiring](checks-ci-wiring.md)

package/docs/gates/checks-lint-coverage.md

@@ -0,0 +1,49 @@
+# checks-lint-coverage
+
+`checks-lint-coverage` is the gate that fails when oxlint silently skips a tracked TypeScript file, and a reader looks it up when a file seems never to be linted.
+
+## What it checks
+
+It fails when oxlint skips a tracked `.ts` or `.tsx` file, for example through a stray `.gitignore` entry.
+It compares `git ls-files` against oxlint's own file walk and names the missing files.
+
+## What it reads
+
+It reads the working tree: the `*.ts` and `*.tsx` files `git ls-files` lists, and the files `oxlint --debug=files` walks.
+It walks without naming a path, since an explicit path bypasses the ignore files whose skips it looks for.
+oxlint must be on `PATH`, as it is under a package script.
+
+## Arguments
+
+It takes none.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | oxlint walks every tracked `.ts` and `.tsx` file, or the repository tracks none |
+| 1 | oxlint skips a tracked file |
+| 2 | oxlint cannot walk the tree, as when it is not on `PATH` or its config does not parse |
+
+## Sample output
+
+```
+lint-coverage: oxlint skips 1/3 tracked .ts/.tsx files; missing:
+ignored/b.ts
+```
+
+A passing run counts the files:
+
+```
+lint-coverage: 71/71 tracked .ts/.tsx files
+```
+
+## Opting out
+
+A repository that tracks no `.ts` or `.tsx` file leaves it out of `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
+A repository that tracks one keeps it.
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [The Effect rules](../configs/effect-rules.md)

package/docs/gates/checks-lint.md

@@ -0,0 +1,136 @@
+# checks-lint
+
+`checks-lint` is the entry point that runs every lint gate of the kit over one range, and a reader looks it up to learn which range it resolves and how a repository selects its gates.
+
+## What it checks
+
+It runs each gate the table under [What runs](../../README.md#what-runs) lists, in that table's order, and names every one that fails rather than stopping at the first.
+Each gate runs as its own bin in a child process, with its output passed straight through, so a gate behaves the same called alone or through `checks-lint`.
+`checks-ci-wiring` always runs, so a repository on `checks-lint` declares `gates.ci`, as [checks-ci-wiring](checks-ci-wiring.md) says.
+It holds the test layout unless the selection leaves out `checks-test-layout`.
+
+## What it reads
+
+It reads `quality.json` for `defaultBranch` and `gates.lint`, and resolves the range once, handing the same one to every range gate.
+A tree gate reads the working tree and is handed no range.
+
+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.
+That branch is `origin/HEAD`.
+When `origin/HEAD` is not set, as in an `actions/checkout` clone, it is `origin/<defaultBranch>` from `quality.json`, and `origin/main` when that is not declared.
+
+In a GitHub Actions pull request, where `GITHUB_EVENT_NAME` is `pull_request`, the range ends at the event's head sha and starts where that branched from `origin/<base branch>`, so GitHub's merge commit is never in it.
+The base branch is read from the fetch, not from the event's recorded base sha, which GitHub leaves stale once the base branch advances after the pull request opens.
+
+The range always starts at the merge base, never at the base branch's tip, since commits the base branch gained after the head branched off would otherwise count against the head.
+When the head is the merge base, as on a push to the default branch or a local run on it, the range would be empty.
+Each range gate is then handed that tip commit alone, and checks it against its parent, or against the empty tree when it is a repository's first commit:
+
+```
+checks-lint: tip 10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
+```
+
+A clone with no remote-tracking refs at all has no default branch to start from, such as a freshly initialised repository with no remote or one whose remote was never fetched.
+Each range gate is then handed `HEAD` alone the same way:
+
+```
+checks-lint: tip 10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD alone, as the clone has no remote-tracking refs
+```
+
+Once any ref sits under `refs/remotes/`, a missing `origin/<default branch>` exits 2 instead.
+That is the shape of a shallow CI checkout, where `HEAD` alone would leave the commits before it unchecked.
+
+## Arguments
+
+```sh
+checks-lint
+checks-lint <base-ref> <head-ref>
+```
+
+With no arguments it resolves the range as What it reads says.
+A base and a head override that resolution.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every gate passed |
+| 1 | a gate found a violation |
+| 2 | the range or the selection does not resolve, or no failing gate could decide |
+
+## Sample output
+
+It prints the range, the declared selection if there is one, each gate's own report, then its verdict:
+
+```
+checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
+...
+checks-lint: 3 of 10 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
+```
+
+## Opting out
+
+A repository leaves out a gate that does not apply to it, as Gate selection says.
+A repository that runs its gates without `checks-lint` calls each gate's bin in its own CI step and declares each command in `gates.ci`.
+
+## Gate selection
+
+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 would still refuse its missing `bun test` script and `bunfig.toml`.
+It declares the gates `checks-lint` runs as `gates.lint`:
+
+```json
+"gates": {
+  "ci": ["bun run lint"],
+  "lint": [
+    "checks-commit-identity",
+    "checks-comment-gate",
+    "checks-suppressions-ratchet",
+    "checks-ci-wiring",
+    "checks-docs",
+    "checks-quality"
+  ]
+}
+```
+
+`checks-lint` runs exactly those, in the order of the table under What runs, and every gate 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` keeps.
+
+A selection may leave out only a gate that does not apply, and the Runs in column of the table under What runs says where each gate applies.
+Both `checks-lint` and `checks-ci-wiring` exit 2 on a `gates.lint` that names an unknown gate or leaves out one that applies to every repository.
+`checks-ci-wiring` exits 1 when the 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 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 adds the first TypeScript file is the one refused.
+
+## Running it in CI
+
+CI runs it through `lint`.
+The checkout fetches the whole history, which the merge base needs:
+
+```yaml
+on:
+  pull_request:
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run lint
+```
+
+## Related topics
+
+- [What runs](../../README.md#what-runs)
+- [checks-ci-wiring](checks-ci-wiring.md)
+- [The quality file](../configs/quality-file.md)

package/docs/gates/checks-mutation-compare.md

@@ -0,0 +1,84 @@
+# checks-mutation-compare
+
+`checks-mutation-compare` is the gate that holds a pull request's mutation score to no regression rather than an absolute threshold, and a reader looks it up to wire mutation testing into CI.
+
+## What it checks
+
+The head mutation score may not fall below the score at the merge-base.
+The score is Stryker's, `Killed` and `Timeout` over those plus `Survived` and `NoCoverage`, so `CompileError`, `RuntimeError`, `Ignored` and `Pending` mutants leave it.
+Every file in a report counts toward that report's score, including files present in only one of the two.
+
+## What it reads
+
+It reads two Stryker `mutation.json` reports, one built at the merge-base and one at the head.
+The shared Stryker preset's `json` reporter writes `reports/mutation/mutation.json` in each worktree.
+
+A repository that runs mutation testing installs `@stryker-mutator/core` and `@hughescr/stryker-bun-runner`, then spreads the shipped preset in `stryker.conf.mjs`:
+
+```js
+import preset from "@avi2dg/checks/stryker.preset.js";
+
+export default {
+  ...preset,
+};
+```
+
+Keys the repository sets after the spread win.
+
+## Arguments
+
+```sh
+checks-mutation-compare [--advisory] <base-report> <head-report>
+```
+
+`--advisory`, anywhere among the arguments, prints the same verdict and always exits 0.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | the head score is not below the base score, or `--advisory` is given |
+| 1 | the head score is below the base score |
+| 2 | a report is not a Stryker mutation report, or the arguments do not parse |
+
+## Sample output
+
+It prints the overall score of each report and the per-file scores that differ:
+
+```
+mutation-compare: base 83.33% (5/6) head 66.67% (4/6) delta -16.67pp
+  src/billing.ts: 75.00% (3/4) -> 50.00% (2/4)
+  1 unchanged file(s)
+mutation-compare: REGRESSION (-16.67pp)
+```
+
+## Opting out
+
+Nothing runs it but a CI step the repository writes.
+A repository runs it with `--advisory` for its first month, then drops the flag so it blocks.
+
+## Running it in CI
+
+It runs on pull requests, comparing the head report against a report built at the merge-base:
+
+```yaml
+jobs:
+  mutation-compare:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx stryker run
+      - run: |
+          base="$(git merge-base HEAD origin/main)"
+          git worktree add /tmp/mutation-base "$base"
+          (cd /tmp/mutation-base && bun install --frozen-lockfile && bunx stryker run)
+      - run: bun run checks-mutation-compare --advisory /tmp/mutation-base/reports/mutation/mutation.json reports/mutation/mutation.json
+```
+
+## Related topics
+
+- [checks-test-layout](checks-test-layout.md)

package/docs/gates/checks-quality.md

@@ -0,0 +1,94 @@
+# checks-quality
+
+`checks-quality` is the bin that writes what `quality.json` declares for oxlint and tsc into generated fragments and checks them, and a reader looks it up when a fragment is stale.
+
+## What it checks
+
+oxlint and tsc read their own JSON and nothing else, so `checks-quality generate` writes what `sources.effect` declares into two fragments at the repository root, and the hand-written configs extend them.
+Both fragments are committed.
+
+`oxlintrc.quality.json` holds one override: the declared paths as `files`, the exempt ones as `excludeFiles`, and the kit's Effect rule block, `presets/effect.oxlint.json`.
+`tsconfig.quality.json` holds the language-service override: the same paths as `include`, the exempt ones as `exclude`, and `presets/effect.language-service.json`.
+A kit release that changes a preset reaches the repository through its next `generate`.
+A rule only this repository needs stays in its own `.oxlintrc.json`, whose overrides come after the fragment's and so win.
+
+`.oxlintrc.json` extends its fragment:
+
+```json
+{
+  "extends": ["./node_modules/@avi2dg/checks/oxlintrc.json", "./oxlintrc.quality.json"],
+  "plugins": ["typescript", "oxc", "eslint", "import"]
+}
+```
+
+`tsconfig.json` extends its fragment:
+
+```json
+{
+  "extends": ["@avi2dg/checks/tsconfig.effect.json", "./tsconfig.quality.json"]
+}
+```
+
+`checks-quality --check` fails when any of these holds:
+
+- A fragment is missing, or differs from what `generate` would write from `quality.json` and the installed kit's presets.
+- A fragment is left over once `quality.json` stops declaring `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, or a `sources.production` glob while `size` is declared, matches no tracked or untracked file, so it holds nothing.
+
+Two details of the fragments are easy to get wrong, so the kit's tests pin both:
+
+- A fragment sits at the repository root.
+  oxlint resolves an override's `files`, and the language service an override's `include`, against the directory of the config holding it.
+  From `.quality/` the language service reports no error at all on an `async function` planted under a declared path.
+- The oxlint fragment always sets `plugins`, to the kit's.
+  A config in `extends` that sets none brings in oxlint's default plugins, whose category rules then fire across the whole tree.
+  The override names the kit's plugins beside the preset's `node`, `promise` and `unicorn`, because one that leaves any of the kit's out turns on the category rules of the plugins it adds under every declared path.
+
+## What it reads
+
+It reads the working tree: `quality.json`, the presets of the installed kit, `.oxlintrc.json`, `tsconfig.json` and the two fragments.
+It lists the tracked and untracked files to see what each declared glob matches.
+
+## Arguments
+
+```sh
+checks-quality generate
+checks-quality --check
+```
+
+`generate` writes the fragments, removes a left-over one, then runs the same check as `--check`.
+`--check` writes nothing.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | the fragments hold what `quality.json` declares |
+| 1 | a fragment is stale, missing, left over or not extended, or a declared glob matches no file |
+| 2 | `quality.json` does not decode, or the arguments are neither `generate` nor `--check` |
+
+## Sample output
+
+```
+checks-quality: 2 problem(s) with what quality.json declares:
+  oxlintrc.quality.json is stale against quality.json and the kit's presets; run checks-quality generate
+  tsconfig.json does not extend ./tsconfig.quality.json, so the language service never reads it
+```
+
+A passing run says what the fragments hold:
+
+```
+checks-quality: oxlintrc.quality.json and tsconfig.quality.json hold what quality.json declares
+```
+
+## Opting out
+
+It runs only in a repository that tracks `quality.json`, and a selection in `quality.json` always keeps it, since the file it sits in is what makes it apply.
+A repository that declares no `sources.effect` gets no fragment, and the check then only refuses a left-over one.
+
+## Related topics
+
+- [The quality file](../configs/quality-file.md)
+- [The Effect rules](../configs/effect-rules.md)
+- [checks-lint](checks-lint.md)