@avi2dg/checks 0.51.0 → 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,12 +22,15 @@ 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 inputs a test reads at runtime stay untracked.
+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, package.json apart from its version, a patch its patchedDependencies names, a file the active config loads at either revision, or the bunfig preload set or a file it loads changed.
+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.
@@ -53,9 +56,10 @@ It reads `RUNNER_ENVIRONMENT` and `HOME` to place the runner cache, and `GITHUB_
 `--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`, `package.json`, every tracked `package.json`, and the files the active Stryker config imports at both revisions.
+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 as a known limitation.
+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
 
@@ -178,7 +182,7 @@ 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 baseline job restores the previous full state before its incremental Stryker run, so it retests the mutants its changes reach, while inputs a test reads at runtime stay untracked.
+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

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.md

@@ -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.
-A first baseline with no state costs a full Stryker run, and each later one retests the mutants its changes reach, while inputs a test reads at runtime stay untracked.
+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
 
@@ -97,7 +97,7 @@ jobs:
     permissions:
       contents: read
       actions: read
-    runs-on: [self-hosted, Linux, X64, winbox]
+    runs-on: [self-hosted, gpu, x64]
     steps:
       - uses: actions/checkout@v5
         with:
@@ -121,7 +121,11 @@ jobs:
 
 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, package.json apart from its version, a patch its patchedDependencies names, a file the active config loads at either revision, or the bunfig preload set or a file it loads changed, and fails the restore when the state does not parse, so the run retests every mutant those changes reach and reuses the rest, while inputs a test reads at runtime stay untracked.
+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.
@@ -131,8 +135,8 @@ The restore reads only a successful run of `mutation.yml` on `main`, so a sweep
 The artifact keeps 30 days, so the newest full baseline outlives the week between full runs.
 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)

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
+  "author": {
+    "name": "avi2d",
+    "email": "avi2dg@gmail.com"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,10 +17,14 @@
   "type": "module",
   "files": [
     "CHANGELOG.md",
+    "docs/bins.md",
     "docs/configs/",
     "docs/design.md",
     "docs/gates/",
+    "docs/how-to/",
+    "docs/shipped-files.md",
     "bunfig.toml",
+    ".bun-version",
     "commitlint.config.ts",
     "dependency-cruiser.config.js",
     "knip-base.json",
@@ -60,6 +68,7 @@
     "src/delivery/workflow-references.ts",
     "src/delivery/bun-pin.ts",
     "src/delivery/mutation-job.ts",
+    "src/delivery/runner-policy.ts",
     "src/delivery/secrets.ts",
     "src/delivery/gitleaks.ts",
     "src/delivery/gitleaks.toml",
@@ -95,6 +104,7 @@
     "src/docs/doc-snapshot.ts",
     "src/docs/doc-templates.ts",
     "src/docs/doc-names.ts",
+    "src/docs/doc-versions.ts",
     "dist/templates/",
     "src/quality/presets/effect.language-service.json",
     "src/quality/presets/oxlint.ts",

package/src/delivery/bun-pin.ts

@@ -2,12 +2,12 @@ import { Effect, FileSystem, Path, Schema } from "effect";
 import { within } from "./mutation-job.ts";
 import { isRecord, locate, workflowJobs, type Workflow } from "./workflow-references.ts";
 
-export const FLEET_BUN_VERSION = "1.4.3";
 const ROOT_MANIFEST = "package.json";
 
 export type BunPinPolicy = {
   readonly files: ReadonlyMap<string, string>;
   readonly manifests: ReadonlyMap<string, unknown>;
+  readonly fleet: string;
 };
 
 export type BunPinFault = {
@@ -94,12 +94,12 @@ function bunPinRequest(policy: BunPinPolicy, step: Readonly<Record<string, unkno
 function bunPinFault(policy: BunPinPolicy, step: Readonly<Record<string, unknown>>): string | undefined {
   const request = bunPinRequest(policy, step);
   if (request.expression !== undefined) {
-    return `requests bun ${request.expression} from ${request.source}, which cannot be shown equal to ${FLEET_BUN_VERSION} before the run`;
+    return `requests bun ${request.expression} from ${request.source}, which cannot be shown equal to ${policy.fleet} before the run`;
   }
   if (request.version === undefined) {
-    return `pins no bun version from ${request.source}, so setup-bun installs latest, want ${FLEET_BUN_VERSION}`;
+    return `pins no bun version from ${request.source}, so setup-bun installs latest, want ${policy.fleet}`;
   }
-  return request.version === FLEET_BUN_VERSION ? undefined : `requests bun ${request.version} from ${request.source}, want ${FLEET_BUN_VERSION}`;
+  return request.version === policy.fleet ? undefined : `requests bun ${request.version} from ${request.source}, want ${policy.fleet}`;
 }
 
 function unknownRefFault(ref: string): string {
@@ -156,6 +156,20 @@ const readJsonFile = Effect.fn("readJsonFile")(function* (file: string) {
   );
 });
 
+export class BunPinError extends Schema.TaggedError<BunPinError>()("BunPinError", {
+  message: Schema.String,
+}) {}
+
+// The kit ships its own .bun-version, so the check reads the fleet pin from that file rather than a constant.
+const kitBunVersion = Effect.gen(function* () {
+  const file = (yield* Path.Path).join(import.meta.dir, "..", "..", ".bun-version");
+  const version = (yield* (yield* FileSystem.FileSystem).readFileString(file).pipe(
+    Effect.mapError((cause) => new BunPinError({ message: `cannot read the kit .bun-version at ${file}: ${cause.message}` })),
+  )).trim();
+  if (version === "") return yield* new BunPinError({ message: `the kit .bun-version at ${file} pins no version` });
+  return version;
+});
+
 export const readBunPinPolicy = Effect.fn("readBunPinPolicy")(function* (root: string, workflows: readonly Workflow[]) {
   const path = yield* Path.Path;
   const fs = yield* FileSystem.FileSystem;
@@ -170,5 +184,5 @@ export const readBunPinPolicy = Effect.fn("readBunPinPolicy")(function* (root: s
       if (text !== undefined) files.set(name, text);
     }
   }
-  return { files, manifests };
+  return { files, manifests, fleet: yield* kitBunVersion };
 });