@avi2dg/checks 0.50.1 → 0.52.0

package/docs/gates/checks-docs.md

@@ -12,6 +12,7 @@ It also fails when a doc names a file, a heading or a script that does not exist
 It holds each doc file a change touches to the template for its kind.
 It lists every other doc file that does not match its template yet, and does not fail on it.
 It holds each line a change adds or edits in a living doc or an agent file to the prose rules, as [The prose rules](#the-prose-rules) says.
+It fails when such a line copies a version `package.json` or `.bun-version` pins, as [Pinned versions](#pinned-versions) says.
 It fails when a living doc or an agent file names a path, link or command that does not resolve, and the range added or broke it.
 It fails when an agent file holds more than 3,000 characters or a `## Maintaining this file` section, whatever the range touches, as [Agent files](#agent-files) says.
 It fails when an entry in an agent file names no tracked path, link or `bun run` command, whatever the range touches.
@@ -119,6 +120,24 @@ The cap is 20 words in an ordered list item and 25 words elsewhere.
 The package exports it as `@avi2dg/checks/scripts/prose-matchers.ts`.
 A host such as a write-time hook can copy that one file into a directory with no `node_modules`, and refuse the same lines.
 
+## Pinned versions
+
+A version a manifest pins has one home, and a doc that copies it by hand goes stale when the pin moves.
+Prose and code are judged alike.
+A line a change adds or edits in a living doc or an agent file fails when it carries one of these:
+
+- A package `package.json` lists in `dependencies`, `devDependencies`, `peerDependencies` or `optionalDependencies` at one version, written as `name@version` or beside the name in prose or a table.
+- The `version`, `packageManager` or an `engines` version from `package.json`, or the version in `.bun-version`, written on its own.
+
+The doc names the file that holds the version instead, as in `Bun, at the version .bun-version pins`.
+A command that needs the exact version sits in a generated block, between a `<!-- generated <name>: ... -->` line and its `<!-- end generated <name> -->` line, which a build writes from the manifest.
+No line in a complete same-named generated block is judged.
+A version the manifests do not pin passes, such as a sample's `lodash@4.17.20`.
+So does a longer version that opens with a pin.
+A manifest range with no single version pins nothing, as in `>=1.2.3 <2` in `package.json`.
+A doc line that carries a pinned version still fails when that version sits inside a range.
+It reads the root `package.json` and `.bun-version`, so a nested package's pins are not checked.
+
 ## Paths, links and commands
 
 Each reference a living doc or an agent file names has to resolve at the head commit:
@@ -177,6 +196,7 @@ It reads the lines the range adds or edits from the diff, with renames detected,
 It reads the files tracked at both ends of the range, and the `scripts` of each `package.json` a living doc or an agent file sits under.
 It compares each code span a living doc or an agent file names with the text git tracks outside the docs at both ends of the range.
 It reads the repository's own name and its direct dependencies from the root `package.json` at the head commit.
+It reads the versions the root `package.json` and `.bun-version` pin at the head commit.
 It reads each agent file at the head commit for the ceiling, its sections and its entries, whatever the range touches.
 A name that an installed direct dependency still holds counts as present.
 From the working tree it reads the ignore files git reads, `node_modules/.bin`, and the directory of each direct dependency under `node_modules`.
@@ -195,16 +215,17 @@ With one it is that commit against its parent, or against the empty tree for a r
 
 | Code | When |
 | --- | --- |
-| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules, it adds or breaks no reference that does not resolve, every agent file holds to the ceiling and holds no `## Maintaining this file`, every entry in an agent file names a tracked path, a link or a command, and no code span a living doc or an agent file names vanished from every file outside the docs |
-| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule, the range adds or breaks a reference that does not resolve, an agent file is over the ceiling or holds `## Maintaining this file`, an entry in an agent file names no tracked path, link or command, or the range removes a name a living doc or an agent file still carries |
+| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules and copies no pinned version, it adds or breaks no reference that does not resolve, every agent file holds to the ceiling and holds no `## Maintaining this file`, every entry in an agent file names a tracked path, a link or a command, and no code span a living doc or an agent file names vanished from every file outside the docs |
+| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule or copies a pinned version, the range adds or breaks a reference that does not resolve, an agent file is over the ceiling or holds `## Maintaining this file`, an entry in an agent file names no tracked path, link or command, or the range removes a name a living doc or an agent file still carries |
 | 2 | a `package.json` does not decode, a ref does not resolve, or `grep` cannot read an installed direct dependency |
 
 ## Sample output
 
 ```
-docs: 6 violation(s):
+docs: 7 violation(s):
   README.md:1: lacks `## Before you begin`
   README.md:12: carries `;`, a semicolon. Use two sentences
+  README.md:13: carries `1.3.5`, a version .bun-version pins. Name .bun-version instead, or let a build write the line between generated markers
   README.md:14: carries `former`, a report about the past. Say what is true now, and leave what changed to the changelog, a commit message or a decision record
   README.md:20: names `scripts/bild.ts`, which is not in the repository
   docs/parts.md: is a page under docs/ with no mode; add kind: tutorial, how-to, reference, explanation in YAML front matter

package/docs/gates/checks-exports.md

@@ -34,7 +34,7 @@ import { defineConfig } from "@avi2dg/checks/knip";
 export default defineConfig({ entry: ["src/index.ts"] });
 ```
 
-The builder sets `include` to unreferenced files alone, and adds `tests/**/*.test.ts` and `dependency-cruiser.config.ts` to the entries.
+The builder sets `include` to unreferenced files alone, and adds `tests/**/*.test.ts`, `dependency-cruiser.config.ts` and `oxlint.config.ts` to the entries.
 The gate resolves the Knip binary from the installed kit, so a consumer installs nothing beyond the kit.
 
 ## Arguments

package/docs/gates/checks-frontend-syntax.md

@@ -133,10 +133,14 @@ A config not built with `defineConfig` names its own `customSyntax` for markup,
 
 The repository installs the optional peers the gate loads, at the versions the kit pins:
 
+<!-- generated install: bun run build writes it from package.json and scripts/doc-blocks.ts -->
+
 ```sh
-bun add -d stylelint@17.16.0 postcss-html@2.0.0 stylelint-config-standard@40.0.0 stylelint-plugin-use-baseline@1.4.7 postcss-value-parser@4.2.0
+bun add -d postcss-html@2.0.0 postcss-value-parser@4.2.0 stylelint@17.16.0 stylelint-config-standard@40.0.0 stylelint-plugin-use-baseline@1.4.7
 ```
 
+<!-- end generated install -->
+
 ## Arguments
 
 ```sh

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), each in its own process.
+It runs the gates under [What runs](../bins.md#what-runs), each in its own process.
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
 `checks-lint-coverage` and `checks-unused` also begin running when the repository tracks an `.astro` file.
 `checks-advisories` begins running when the repository tracks `bun.lock`.
@@ -62,5 +62,5 @@ It never runs `checks-browser`, which a product runs after it builds its site.
 
 ## Related topics
 
-- [What runs](../../README.md#what-runs)
+- [What runs](../bins.md#what-runs)
 - [checks-ci-wiring](checks-ci-wiring.md)

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

@@ -22,6 +22,16 @@ With `--full` it lists up to 50 `schedule` runs and up to 50 `workflow_dispatch`
 It tries those runs newest first, and restores the first `mutation-baseline-full` artifact that has not expired, downloads and holds the report.
 It tries no run after that one.
 It takes the report from `mutation.json` at the artifact's root, or else from `mutation/mutation.json`, and copies it to the destination.
+With an incremental destination it also copies `stryker-incremental.json` when the artifact holds one, so the next full run retests the mutants its changes reach, while a result made stale by a file a test reads at runtime lasts until the next 28-day refresh.
+The restore then drops each test that reads a changed file and each mutant result for a changed source from the copied state.
+It drops non-killed results when any test goes stale.
+It drops the whole state when a Stryker config, stryker.preset.js, the lockfile, the Bun version, a file the active config reaches through a relative import at either revision, or the bunfig preload set or a file it reaches through a relative import changed.
+It walks the config and preload dependencies at both revisions, so a file only the older revision resolved still drops the state when it changes.
+A file a config or preload reaches only through a package main escapes invalidation until the next 28-day refresh.
+A state that does not parse fails the restore instead of running on unknown results.
+It drops the whole state when the restored run started before the current 28-day refresh window, and the windows count from the Unix epoch.
+Every state a window keeps was built inside it, so each reused result is at most 28 days old, and a weekly full baseline retests every mutant every fourth week.
+Without the state file the report still restores.
 
 It creates the directories each destination needs.
 
@@ -41,9 +51,15 @@ It deletes through `gh`, which needs a token that deletes the repository's Actio
 
 It reads the runs and their artifacts through `gh`, which needs a token that reads the repository's Actions, such as `GH_TOKEN: ${{ github.token }}` with `actions: read`.
 The `mutation-baseline` artifact holds `stryker-incremental.json` and `mutation/mutation.json`, which an upload of `reports/stryker-incremental.json` and `reports/mutation/mutation.json` writes.
-The `mutation-baseline-full` artifact holds `mutation.json` at its root, which an upload of `reports/mutation/mutation.json` alone writes.
+The `mutation-baseline-full` artifact holds `mutation.json` and `stryker-incremental.json` at its root, which an upload of `${{ runner.temp }}/full/` writes.
 It reads `RUNNER_ENVIRONMENT` and `HOME` to place the runner cache, and `GITHUB_REPOSITORY_ID` to find the saved baselines.
 `--save` and `--prune` read `GITHUB_RUN_ID`.
+With `--full` and an incremental destination it reads the run's head through `gh run view <run> --json headSha`.
+It diffs that head against `HEAD`, which needs the checkout's full history.
+It shows `bunfig.toml` and the files the active Stryker config imports at both revisions.
+It reads every tracked `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, and `.cjs` file from the working tree for their relative imports.
+Inputs a test reads at runtime without a static import, such as markdown files, escape invalidation until the next refresh window.
+It reads the restored run's `createdAt` from the run list to place that run in a refresh window.
 
 ## The runner cache
 
@@ -91,13 +107,13 @@ It also refuses when `HOME`, `GITHUB_REPOSITORY_ID` or `GITHUB_RUN_ID` is unset.
 
 ```sh
 checks-mutation-baseline <incremental-dest> [mutation-json-dest]
-checks-mutation-baseline --full <mutation-json-dest>
+checks-mutation-baseline --full <mutation-json-dest> [incremental-dest]
 checks-mutation-baseline --save <incremental-src> [mutation-json-src]
 checks-mutation-baseline --slim <mutation-json-src> <dest>
 checks-mutation-baseline --prune [--dry-run]
 ```
 
-`--full` restores only the report of a run that started with no state.
+`--full` restores the report of a full run, and its incremental state when given an incremental destination.
 `--save` keeps this run's baseline on the runner's disk in place of an upload.
 `--slim` writes a report without `statusReason` to `<dest>`, for a report that still goes up as an artifact.
 `--prune` deletes superseded baselines after a save or an upload.
@@ -108,7 +124,7 @@ checks-mutation-baseline --prune [--dry-run]
 | Code | When |
 | --- | --- |
 | 0 | it restored a baseline, found none to restore, saved the baseline or wrote the slim report |
-| 2 | the arguments do not parse, `gh` cannot list the runs, the cache cannot be written, another job removed the entry before it was copied, a file to save or slim does not parse, or `--save` runs where it refuses |
+| 2 | the arguments do not parse, `gh` cannot list the runs, the cache cannot be written, another job removed the entry before it was copied, a file to save or slim does not parse, `--save` runs where it refuses, or `--full` with an incremental destination cannot read the run's head, diff it, or parse the restored state |
 
 A failed artifact lookup or download prints the `gh` error and moves on, as a missing artifact does.
 With `--prune`, `0` means it deleted the superseded artifacts, found none, or could not delete some.
@@ -166,15 +182,28 @@ The saved baseline uses none of the account's Actions storage, which every priva
 That storage accrues by the hour over the month, so an artifact deleted early still counts until the month ends.
 A baseline job on a GitHub-hosted runner uploads the same two files as a `mutation-baseline` artifact with `retention-days: 7` instead, since the restore reads only the newest `main` run.
 
-A full run uploads its report as the `mutation-baseline-full` artifact, which a branch comparison's scope step reads on any runner.
-It slims the report first, so the artifact holds about 0.5 MB in place of about 100 MB:
+A full baseline job restores the previous full state before its incremental Stryker run, so it retests the mutants its changes reach, while a result made stale by a file a test reads at runtime lasts until the next 28-day refresh.
+The checkout behind that step fetches the full history, so the restore can diff the restored run against `HEAD`:
+
+```yaml
+- name: Restore previous full baseline state
+  env:
+    GH_TOKEN: ${{ github.token }}
+  run: bunx checks-mutation-baseline --full reports/mutation/mutation.json reports/stryker-incremental.json
+```
+
+The restore reads the repository's Actions through `gh`, so the job that holds it grants `contents: read` and `actions: read`.
+
+A full run uploads its slimmed report and its slimmed state as the `mutation-baseline-full` artifact, which a branch comparison's scope step reads on any runner.
+It slims the report and the state first, so the one directory holds about 10 MB in place of about 500 MB:
 
 ```yaml
 - run: bunx checks-mutation-baseline --slim reports/mutation/mutation.json "$RUNNER_TEMP/full/mutation.json"
+- run: bunx checks-mutation-baseline --slim reports/stryker-incremental.json "$RUNNER_TEMP/full/stryker-incremental.json"
 - uses: actions/upload-artifact@v4
   with:
     name: mutation-baseline-full
-    path: ${{ runner.temp }}/full/mutation.json
+    path: ${{ runner.temp }}/full/
     retention-days: 30
 ```
 

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

@@ -136,9 +136,9 @@ A changed unit test that `main` edited after that baseline widens the scope to e
 Start a full baseline with `gh workflow run mutation`, as [checks-mutation](checks-mutation.md#running-it-in-ci) shows.
 A run with `--mutate` is scoped, so the preset lets it through without `CI=true`.
 The base worktree's path carries the run's id and attempt, and the last step removes it even when a run fails, so a runner kept between jobs starts each job clean.
-A public repository keeps `runs-on: ubuntu-latest`, as [checks-ci-wiring](checks-ci-wiring.md#runners) allows a public repository on every job.
-A private repository sets `runs-on: [self-hosted, Linux, X64, winbox]` instead, which is the fleet's self-hosted Linux runner where it sends its mutation runs.
-The job never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the comparison waiting for `winbox`.
+A public repository keeps `runs-on: ubuntu-latest`, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires of a job a fork can reach.
+A private repository sets `runs-on` to the labels it declares in `package.json` under `checks.mutationRunner` instead, which is where it sends its mutation runs.
+The job never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the comparison waiting for those labels.
 [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names it in `runs-on`.
 
 ## Related topics

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

@@ -53,7 +53,7 @@ So a helper, fixture or preload changed on `main` since that baseline can hide a
 - The full baseline report that `checks-mutation-baseline --full` restores, for each mutant's `coveredBy` and `killedBy` and the `testFiles` that own those tests.
 
 Stryker leaves `coveredBy` empty on a static mutant, so only `killedBy` names its tests.
-The report must come from a run that restored no state, so each mutant's tests are the ones it ran against.
+A reused result needs its affected tests, sources, and configuration invalidated before reuse, so each mutant's tests are the ones the run recorded.
 With bail, Stryker's default, `killedBy` names the one test that killed the mutant first.
 One killer is enough, since a branch loses a kill through its tests only when it changes every test that made the kill.
 A test left alone, whose sources the branch also leaves alone, still kills the mutant at `HEAD`.

package/docs/gates/checks-mutation.md

@@ -30,7 +30,7 @@ So when a `stryker run` without `--ignoreStatic` loads the preset, the preset fi
 `unitTestFiles` then lists each file with a leading `./`, fastest first, and Bun runs such paths in the order given.
 It then lists each path again without the `./`, the spelling the runner matches a covering test against.
 Bun loads a file once however often the list names it.
-When that timing run fails, the preset prints why on stderr and `unitTestFiles` keeps the path order.
+When that timing run fails, the preset prints why on stderr and `unitTestFiles` keeps Bun's default directory order.
 The config then reads:
 
 ```js
@@ -82,7 +82,7 @@ An `--incremental` run with no report stops before instrumenting with the missin
 A repository runs full baselines from the mutation workflow on `workflow_dispatch`.
 A repository that picks a branch scope from a baseline starts that workflow weekly with `gh workflow run mutation`, because a GitHub schedule can start hours late.
 Run scoped checks locally during development.
-Each baseline costs a full Stryker run.
+A first baseline with no state costs a full Stryker run, and each later one retests the mutants its changes reach, while a result made stale by a file a test reads at runtime lasts until the next 28-day refresh.
 
 ## Running it in CI
 
@@ -94,32 +94,49 @@ on:
   workflow_dispatch:
 jobs:
   mutation:
-    runs-on: [self-hosted, Linux, X64, winbox]
+    permissions:
+      contents: read
+      actions: read
+    runs-on: [self-hosted, gpu, x64]
     steps:
       - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
-      - run: bunx stryker run
+      - env:
+          GH_TOKEN: ${{ github.token }}
+        run: bunx checks-mutation-baseline --full reports/mutation/mutation.json reports/stryker-incremental.json
+      - run: bunx stryker run --incremental
       - run: bunx checks-mutation-baseline --slim reports/mutation/mutation.json "$RUNNER_TEMP/full/mutation.json"
+      - run: bunx checks-mutation-baseline --slim reports/stryker-incremental.json "$RUNNER_TEMP/full/stryker-incremental.json"
       - uses: actions/upload-artifact@v4
         with:
           name: mutation-baseline-full
-          path: ${{ runner.temp }}/full/mutation.json
+          path: ${{ runner.temp }}/full/
           retention-days: 30
 ```
 
-The run restores no state, so its report names every test that covers each covered mutant and the first test that killed each killed mutant.
+A first baseline with no state tests every mutant.
+Each later restore drops the tests that read a changed file and the mutant results for a changed source from the restored state, and drops non-killed results when any test goes stale.
+It drops the whole state when a Stryker config, stryker.preset.js, the lockfile, the Bun version, a file the active config reaches through a relative import at either revision, or the bunfig preload set or a file it reaches through a relative import changed.
+It fails the restore when the state does not parse.
+The run retests every mutant those changes reach and reuses the rest.
+A result made stale by a file a test reads at runtime lasts until the next 28-day refresh.
+A file a config or preload reaches only through a package main escapes invalidation until the next 28-day refresh.
+The checkout fetches the full history, so the restore can tell which files changed since the previous full run.
+Its report names every test that covers each covered mutant and the first test that killed each killed mutant.
 [checks-mutation-scope](checks-mutation-scope.md#what-it-reads) says why that one killer is enough.
 The upload is the `mutation-baseline-full` artifact that a branch comparison's scope step restores with `checks-mutation-baseline --full`.
 [checks-mutation-scope](checks-mutation-scope.md) reads it to bring in the sources a changed unit test covers or kills.
 The restore reads only a successful run of `mutation.yml` on `main`, so a sweep that fails publishes nothing a scope step reads.
 The artifact keeps 30 days, so the newest full baseline outlives the week between full runs.
-The upload holds the report without each mutant's `statusReason`, as [checks-mutation-baseline](checks-mutation-baseline.md#the-saved-baselines) says, since the full report of a large repository passes 100 MB as an artifact.
+The upload holds the slimmed report and the slimmed state without each mutant's `statusReason`, as [checks-mutation-baseline](checks-mutation-baseline.md#the-saved-baselines) says, so the one directory holds about 10 MB in place of about 500 MB.
 
-The job runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a repository sends its full sweeps.
-It never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the sweep waiting for `winbox`.
+The job runs on the self-hosted labels the repository declares in `package.json` under `checks.mutationRunner`, which is where a repository sends its full sweeps.
+It never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the sweep waiting for those labels.
 [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names it in `runs-on`.
 The `name: mutation` line is what `gh workflow run mutation` looks up.
 GitHub sets `CI=true` on every runner, so the preset lets the full run through there.

package/docs/gates/checks-night-run.md

@@ -177,7 +177,7 @@ The concurrency group queues a run started by hand behind the scheduled one, so
 A dispatch on a branch runs both jobs and lists its findings in the report job's log, and `if-no-files-found: ignore` lets that run upload no record.
 `issues: write` on the report job is the one permission beyond reading the repository and its runs.
 A public repository keeps `runs-on: ubuntu-latest` on the mutation job.
-A private repository sets `runs-on: [self-hosted, Linux, X64, winbox]` on the mutation job, and [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names `CI_RUNS_ON`.
+A private repository sets `runs-on` on the mutation job to the labels declared under `checks.mutationRunner` in `package.json`, and [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names `CI_RUNS_ON`.
 The report job reads `CI_RUNS_ON`, because it runs no mutant.
 A successful run uploads `night-run`, so the next night compares with it, and a failed run uploads nothing a later night reads.
 The artifact keeps 90 days, so a gap of nights still leaves a previous night to compare with.

package/docs/gates/checks-secrets.md

@@ -46,8 +46,8 @@ It reads the commits of the range from git, not the working tree.
 It needs git 2.36 or newer, which diffs a merge against the merge git would make on its own, and it exits 2 on an older git.
 It reads its rules from `src/delivery/gitleaks.toml` in the installed package.
 
-It runs gitleaks 8.30.1, pinned by the SHA-256 of each platform's archive and of the binary inside it.
-On first use it downloads the archive from the scanner's GitHub release and unpacks the binary into `~/.cache/avi2dg-checks/gitleaks/8.30.1/`.
+It runs the gitleaks release `src/delivery/gitleaks.ts` pins, by the SHA-256 of each platform's archive and of the binary inside it.
+On first use it downloads the archive from the scanner's GitHub release and unpacks the binary into `~/.cache/avi2dg-checks/gitleaks/<version>/`.
 It checks the binary's SHA-256 again on every run and exits 2 on a copy that differs.
 Builds are pinned for macOS and Linux, each on x64 and arm64.
 On any other platform it exits 2, and no setting runs a scanner other than the pinned build.

package/docs/gates/checks-unused.md

@@ -26,7 +26,7 @@ import { defineConfig } from "@avi2dg/checks/knip";
 export default defineConfig({ entry: ["src/index.ts"] });
 ```
 
-The builder sets `include` to unreferenced files alone, and adds `tests/**/*.test.ts` and `dependency-cruiser.config.ts` to the entries.
+The builder sets `include` to unreferenced files alone, and adds `tests/**/*.test.ts`, `dependency-cruiser.config.ts` and `oxlint.config.ts` to the entries.
 In a repository that depends on `astro`, Knip reads `.astro` imports, so a file only an `.astro` entry imports counts as used and an `.astro` file no entry reaches is named.
 The gate resolves the Knip binary from the installed kit, so a consumer installs nothing beyond the kit.
 

package/docs/how-to/set-up-a-repository.md

@@ -0,0 +1,142 @@
+---
+kind: how-to
+audience: consumers
+---
+# Set up a repository
+
+A repository owner follows these steps once, after [Install](../../README.md#install), so each gate `checks-lint` runs finds the file it reads.
+
+## Before you begin
+
+- The kit in `devDependencies` and the kit's `.bun-version` copied, as [Install](../../README.md#install) says.
+
+## Write the tool configs
+
+To give each tool the config it reads:
+
+1. Write `oxlint.config.ts` with the kit's builder, saying whether the sources are Effect programs:
+
+   ```ts
+   import { defineConfig } from "@avi2dg/checks/oxlint";
+
+   export default defineConfig({ effect: true });
+   ```
+
+1. Keep oxlint out of `node_modules/` through `.gitignore`:
+
+   ```
+   node_modules/
+   ```
+
+1. Add the Bun types, which the kit's config builders need to typecheck:
+
+   ```sh
+   bun add -d @types/bun
+   ```
+
+1. Extend the tsconfig fragment in `tsconfig.json`, naming the Bun types:
+
+   ```json
+   {
+     "extends": "@avi2dg/checks/tsconfig.effect.json",
+     "compilerOptions": { "types": ["bun"] }
+   }
+   ```
+
+1. Copy the bunfig preset:
+
+   ```sh
+   cp node_modules/@avi2dg/checks/bunfig.toml bunfig.toml
+   ```
+
+1. Name the files nothing imports in `knip.config.ts`:
+
+   ```ts
+   import { defineConfig } from "@avi2dg/checks/knip";
+
+   export default defineConfig({ entry: ["src/index.ts"] });
+   ```
+
+1. Write `dependency-cruiser.config.ts` only when the kit's import rules need an entry point or a boundary of the repository's own:
+
+   ```ts
+   import { defineConfig } from "@avi2dg/checks/dependency-cruiser";
+
+   export default defineConfig({ orphans: ["^src/bin[.]ts$"] });
+   ```
+
+## Run the checks on every pull request
+
+To run the gates in CI:
+
+1. Add scripts to `package.json`, replacing the build entry with the repository's own build command:
+
+   ```json
+   "build": "bun build src/index.ts --outdir dist --target node && checks-effect-scope",
+   "lint": "oxlint && checks-lint",
+   "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
+   "test": "checks-test"
+   ```
+
+1. Run the scripts on every pull request in `.github/workflows/ci.yml`, fetching the whole history the range needs:
+
+   ```yaml
+   on:
+     pull_request:
+   jobs:
+     checks:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v5
+           with:
+             fetch-depth: 0
+         - uses: oven-sh/setup-bun@v2
+           with:
+             bun-version-file: .bun-version
+         - run: bun install --frozen-lockfile
+         - run: bun run build
+         - run: git diff --exit-code
+         - run: bun run lint
+         - run: bun run typecheck
+         - run: bun run test
+   ```
+
+Lint the pull request title in the same job with one step:
+
+   ```yaml
+         - id: title
+           name: lint the title
+           env:
+             PR_TITLE: ${{ github.event.pull_request.title }}
+             GH_TOKEN: ${{ github.token }}
+           run: bunx checks-commit-title
+   ```
+
+A repository whose branch protection requires a `commitlint` status reports the title step under that name using the following step.
+The same job reports the title step's outcome under that name on every run, which needs `statuses: write`:
+
+   ```yaml
+         - name: report the title as commitlint
+           if: always()
+           env:
+             GH_TOKEN: ${{ github.token }}
+             HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+             OUTCOME: ${{ steps.title.outcome }}
+           run: |
+             state=failure
+             if [ "$OUTCOME" = success ]; then state=success; fi
+             gh api "repos/$GITHUB_REPOSITORY/statuses/${HEAD_SHA:-$GITHUB_SHA}" -f state="$state" -f context=commitlint -f target_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --silent
+   ```
+
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job, as [checks-ci-wiring](../gates/checks-ci-wiring.md#runners) requires.
+`checks-effect-scope` writes the Effect paths of `oxlint.config.ts` and the kit's severities into `tsconfig.json`, as [The Effect rules](../configs/effect-rules.md#language-service) says.
+`bun run lint` then ends with `checks-lint: <count> gate(s) pass`.
+
+## Related topics
+
+- [The bins](../bins.md)
+- [Native settings](../configs/native-settings.md)
+- [The Effect rules](../configs/effect-rules.md)
+- [The TypeScript rules](../configs/typescript-rules.md)
+- [The dependency rules](../configs/dependency-rules.md)
+- [The commit message lint](../configs/commit-messages.md)

package/docs/how-to/turn-on-the-css-families.md

@@ -0,0 +1,35 @@
+---
+kind: how-to
+audience: consumers
+---
+# Turn on the CSS families
+
+A repository owner follows these steps to judge the repository's CSS with the stylelint families it needs.
+
+## Turn them on
+
+To turn on the CSS families:
+
+1. Install the peers [checks-frontend-syntax](../gates/checks-frontend-syntax.md#what-it-reads) loads, with the `bun add` line on its page.
+1. Declare `frontend-syntax.json`, which turns the gate on, as its page says.
+1. Write `stylelint.config.ts` with the families the repository needs:
+
+   ```ts
+   import { defineConfig } from "@avi2dg/checks/stylelint";
+
+   export default defineConfig({
+     baseline: "widely",
+     tokens: ["src/styles/tokens.css"],
+     bem: true,
+     flatSelectors: true,
+     noPageHas: true,
+   });
+   ```
+
+[checks-frontend-syntax](../gates/checks-frontend-syntax.md#what-it-reads) says what each key takes and which family it turns on.
+`noPageHas` sees a `:has` nested under a page selector only together with `flatSelectors`, which refuses the nesting.
+
+## Related topics
+
+- [checks-frontend-syntax](../gates/checks-frontend-syntax.md)
+- [checks-css-size](../gates/checks-css-size.md)

package/docs/how-to/upgrade-the-kit.md

@@ -0,0 +1,42 @@
+---
+kind: how-to
+audience: consumers
+---
+# Upgrade the kit
+
+A repository owner follows these steps to move a repository the kit holds to a newer release.
+
+## Before you begin
+
+- A repository set up as [Set up a repository](set-up-a-repository.md) says.
+
+## Upgrade
+
+To move a repository to a newer release of the kit:
+
+1. Rerun the [install line](../../README.md#install), which moves the kit to its newest release.
+   A repository that lists a required peer explicitly also reruns the upgrade line below.
+   The upgrade line keeps each declaration the repository imports.
+   The upgrade line writes the lockfile, so the checks below run on the new pins.
+
+   <!-- generated install: bun run build writes it from package.json and scripts/doc-blocks.ts -->
+
+   ```sh
+   bun add -d @effect/tsgo@0.45.0 @swc/core@1.16.2 dependency-cruiser@18.4.0 effect@4.0.0 jscpd@5.3.2 oxlint@1.83.0 oxlint-tsgolint@7.0.2002 typescript@7.0.2
+   ```
+
+   <!-- end generated install -->
+
+   A repository that opted in to `checks-browser`, `checks-frontend-syntax` or `checks-copy` also reruns the `bun add` line on its page.
+1. Run `bun run build`, whose `checks-effect-scope` rewrites the Effect override and the kit's severities in `tsconfig.json` when a release changes them.
+   A severity key the release drops stays in `tsconfig.json` until the repository removes it.
+1. Copy `node_modules/@avi2dg/checks/bunfig.toml` over `bunfig.toml` again, since `checks-test-layout` compares the copy with the installed preset.
+1. Run `bun run lint`, `bun run typecheck` and `bun run test`.
+
+The repository's lockfile pins the kit, so a repository moves only when it runs these steps.
+[CHANGELOG.md](../../CHANGELOG.md), shipped in the package, lists what each release changed.
+
+## Related topics
+
+- [The shipped files](../shipped-files.md)
+- [CHANGELOG.md](../../CHANGELOG.md)

package/docs/shipped-files.md

@@ -0,0 +1,36 @@
+---
+kind: reference
+audience: consumers
+---
+# The shipped files
+
+The package ships these paths, and a repository reads or copies them from its install.
+
+## Where things are
+
+Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
+
+<!-- generated shipped: bun run build writes it from package.json and scripts/doc-blocks.ts -->
+
+| Path | What it holds |
+| --- | --- |
+| `CHANGELOG.md` | every release, and what it changed |
+| `docs/` | the how-to guides, 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 |
+| `.bun-version` | the fleet bun version the bun pin check reads |
+| `commitlint.config.ts` | the shared commitlint config |
+| `dependency-cruiser.config.js` | the kit's dependency-cruiser rules as a base a `.dependency-cruiser.cjs` extends by path, which the build writes |
+| `knip-base.json` | the Knip `include` setting, for a configuration that spreads it |
+| `src/` | every bin, which a package script calls by its `checks-` name, the modules the bins import, and the Effect language service severities under `src/quality/presets/` |
+| `dist/` | the compiled oxlint plugins, the config builders `@avi2dg/checks/oxlint`, `@avi2dg/checks/knip`, `@avi2dg/checks/dependency-cruiser` and `@avi2dg/checks/stylelint` resolve to, and the doc templates, one template per kind of doc file |
+| `oxlintrc.json` | the oxlint `base` as a config a `.oxlintrc.json` extends by path, which the build writes |
+| `stryker.preset.js` | the Stryker mutation-testing preset, which refuses a full run outside CI |
+| `tsconfig.effect.json` | the tsconfig fragment with the shared compiler options and the Effect language-service block |
+| `ts-reset.d.ts` | the two ts-reset rules `tsconfig.effect.json` lists in `files` |
+
+<!-- end generated shipped -->
+
+## Related topics
+
+- [Set up a repository](how-to/set-up-a-repository.md)
+- [Upgrade the kit](how-to/upgrade-the-kit.md)