@avi2dg/checks 0.50.1 → 0.52.0

package/.bun-version

@@ -0,0 +1 @@
+1.4.3

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.52.0
+
+Released 2026-10-25.
+
+### Features
+
+- **docs:** short front door README and refuse hand copied pinned versions [#206](https://github.com/avi2d/checks/pull/206)
+- **testing:** add 28-day refresh window for restored mutation baselines [#205](https://github.com/avi2d/checks/pull/205)
+
+### Fixes
+
+- **delivery:** refuse fork-reachable self-hosted runners, read fleet pins from config [#204](https://github.com/avi2d/checks/pull/204)
+- upgrade fast-uri and zod past the October advisories [#202](https://github.com/avi2d/checks/pull/202)
+
+## 0.51.0
+
+Released 2026-10-23.
+
+### Features
+
+- **testing:** reuse full baseline results for unchanged files [#197](https://github.com/avi2d/checks/pull/197)
+
+### Fixes
+
+- **delivery:** accept GitHub display name on commits GitHub made [#198](https://github.com/avi2d/checks/pull/198)
+- **testing:** correct unit test fallback order wording to Bun default directory order [#195](https://github.com/avi2d/checks/pull/195)
+
 ## 0.50.1
 
 Released 2026-10-20.

package/README.md

@@ -1,276 +1,51 @@
 # checks
 
-`@avi2dg/checks` is the kit of deterministic checks a TypeScript repository installs to hold its code, tests, commits, CI wiring and docs to one shared standard.
-It ships the lint gates `checks-lint` runs over each pull request, the test runners, and a `defineConfig` for oxlint, Knip, dependency-cruiser and stylelint.
-It also ships the configs a repository extends for tsc, commitlint, bun and Stryker.
-Each repository owns its workflows and native tool configs, as [Native settings](docs/configs/native-settings.md) maps.
+`@avi2dg/checks` turns each rule a reviewer would otherwise have to remember into a program that runs on every pull request.
+One command, `checks-lint`, judges a TypeScript repository's code, tests, commits, CI wiring and docs, and each failure names the file or line to fix.
+Every Bun repository it holds moves to a new rule by upgrading one package, rather than by copying configs between repositories.
 
 ## Before you begin
 
-<!-- generated prerequisites: bun run build writes it from package.json, .bun-version and scripts/doc-blocks.ts -->
-
 - A git repository, whose history the range gates read.
-- Bun 1.4.3, which runs every bin.
-- The peer dependencies, at the exact versions the kit pins:
-  - `@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
-- The optional peers, which only an opt-in check loads, at the exact versions the kit pins:
-  - `@axe-core/playwright` 4.13.0
-  - `html-validate` 11.16.0
-  - `playwright-core` 1.63.0
-  - `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 prerequisites -->
+- Bun, at the version the kit's `.bun-version` pins.
 
 ## Install
 
-To consume the kit from a repository:
+To hold a repository to the kit:
 
-1. Add the kit and its peers:
-
-   <!-- generated install: bun run build writes it from package.json and scripts/doc-blocks.ts -->
+1. Add the kit:
 
    ```sh
-   bun add -d @avi2dg/checks @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 -->
-
-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 });
+   bun add -d @avi2dg/checks
    ```
 
-1. Keep oxlint out of `node_modules/` through `.gitignore`:
-
-   ```
-   node_modules/
-   ```
-
-1. Extend the tsconfig fragment in `tsconfig.json`:
-
-   ```json
-   {
-     "extends": "@avi2dg/checks/tsconfig.effect.json"
-   }
-   ```
-
-1. Copy the bunfig preset:
+1. Pin the Bun version the kit runs on:
 
    ```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$"] });
-   ```
-
-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. Write the Bun version [Before you begin](#before-you-begin) names to `.bun-version`, which [checks-ci-wiring](docs/gates/checks-ci-wiring.md#bun-version) holds every setup-bun step to.
-
-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
+   cp node_modules/@avi2dg/checks/.bun-version .bun-version
    ```
 
-Lint the pull request title in the same job with one step:
+1. Run the gates:
 
-   ```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 `commitlint` keeps that required status name while `commitlint.yml` goes away.
-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
+   ```sh
+   bunx checks-lint
    ```
 
-A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job, as [checks-ci-wiring](docs/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](docs/configs/effect-rules.md#language-service) says.
-`bun run lint` then ends with `checks-lint: <count> gate(s) pass`.
-
-## What runs
-
-`checks-lint` runs each of these gates that applies to the repository, and names every one that fails.
-A gate reads either the working tree or the range `checks-lint` resolves.
-The table groups the gates by vector, the part of a repository each one judges.
-
-<!-- generated gates: bun run build writes it from KIT_GATES in src/core/gates.ts and scripts/doc-blocks.ts -->
-
-| Vector | Gate | Reads | Runs in |
-| --- | --- | --- | --- |
-| complexity | [`checks-suppressions-ratchet`](docs/gates/checks-suppressions-ratchet.md) | the range | every repository |
-| complexity | [`checks-repetition`](docs/gates/checks-repetition.md) | the range | a repository tracking `*.ts` or `*.tsx` |
-| complexity | [`checks-unused`](docs/gates/checks-unused.md) | the working tree | a repository tracking `*.ts` or `*.tsx` or `*.astro` |
-| complexity | [`checks-exports`](docs/gates/checks-exports.md) | the range | a repository tracking `*.ts` or `*.tsx` |
-| quality | [`checks-lint-coverage`](docs/gates/checks-lint-coverage.md) | the working tree | a repository tracking `*.ts` or `*.tsx` or `*.astro` |
-| quality | [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
-| quality | [`checks-effect-scope`](docs/gates/checks-effect-scope.md) | the working tree | a repository tracking `oxlint.config.ts` |
-| quality | [`checks-frontend-syntax`](docs/gates/checks-frontend-syntax.md) | the working tree | a repository tracking `frontend-syntax.json` |
-| quality | [`checks-css-size`](docs/gates/checks-css-size.md) | the working tree | a repository tracking `*.css` |
-| quality | [`checks-no-plain-js`](docs/gates/checks-no-plain-js.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
-| testing | [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
-| testing | [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |
-| docs | [`checks-docs`](docs/gates/checks-docs.md) | the range, and every agent file at the head commit | every repository |
-| docs | [`checks-copy`](docs/gates/checks-copy.md) | the working tree | a repository tracking `copy.json` |
-| delivery | [`checks-commit-identity`](docs/gates/checks-commit-identity.md) | the range | every repository |
-| delivery | [`checks-ci-wiring`](docs/gates/checks-ci-wiring.md) | the working tree | every repository |
-| delivery | [`checks-secrets`](docs/gates/checks-secrets.md) | the range | every repository |
-| dependencies | [`checks-imports`](docs/gates/checks-imports.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
-| dependencies | [`checks-advisories`](docs/gates/checks-advisories.md) | the range | a repository tracking `bun.lock` |
-
-<!-- end generated gates -->
-
-These bins run on their own:
-
-- [`checks-test`](docs/gates/checks-test.md) runs the suite as `scripts.test` and refuses a skip without a reason at its test site.
-- [`checks-flake`](docs/gates/checks-flake.md) runs the suite on a schedule and records the seeds a flaky test fails with.
-- [`checks-mutation`](docs/gates/checks-mutation.md) runs Stryker for scoped checks and refuses a full run outside CI.
-- [`checks-mutation-compare`](docs/gates/checks-mutation-compare.md) compares the mutants of two reports and lists each one that regresses.
-- [`checks-mutation-baseline`](docs/gates/checks-mutation-baseline.md) restores the newest mutation baseline from `main`, saves it on a self-hosted runner's disk in place of an artifact, and deletes superseded baselines after a `main` run.
-- [`checks-mutation-scope`](docs/gates/checks-mutation-scope.md) turns a branch's diff into the files its mutation runs mutate.
-- [`checks-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
-- [`checks-night-run`](docs/gates/checks-night-run.md) opens or comments on one GitHub issue per finding of a night run on `main`, each file whose mutation score fell and each failing test.
-- [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
-- [`checks-release-notes`](docs/gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
-- [`checks-release-report`](docs/gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.
-- [`checks-release-pr`](docs/gates/checks-release-pr.md) opens or refreshes the pull request that releases the next version, and dispatches its checks.
-- [`checks-release-tag`](docs/gates/checks-release-tag.md) tags a landed release commit with its version and dispatches the release workflow on the tag.
-- [`checks-vendor`](docs/gates/checks-vendor.md) pins each library its `prepare` arguments name to a shared read-only clone and links it under `repos/`.
-- [`checks-browser`](docs/gates/checks-browser.md) opens a product's built pages in Chrome and fails on the layout, keyboard, motion, accessibility, nesting and asset checks its `browser-checks.json` declares.
-- [`checks-commit-title`](docs/gates/checks-commit-title.md) lints the pull request title in one step of the `ci` job.
-- [`checks-docs-only`](docs/gates/checks-docs-only.md) tells whether a change touches only top-level Markdown and Markdown under `docs/`, so a docs-only change skips the full run.
+Each gate that fails names the file it needs, and [Set up a repository](docs/how-to/set-up-a-repository.md) writes every one.
+A repository the kit holds ends with `checks-lint: <count> gate(s) pass`.
 
-`checks-lint` has [its own page](docs/gates/checks-lint.md), which says which range it resolves.
-oxlint runs through its own tool, as the pages under Related topics say.
+## Find the page you need
 
-## Upgrade
-
-To move a repository to a newer release of the kit:
-
-1. Run the install line again, which moves the kit to its newest release and the peers to the versions it pins.
-   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.
-
-## Turn on the CSS families a repository needs
-
-A repository that declares `frontend-syntax.json` writes `stylelint.config.ts` with the families it 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](docs/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.
-
-## 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 |
+| To | Read |
 | --- | --- |
-| `CHANGELOG.md` | every release, and what it changed |
-| `docs/` | a reference page per bin and per shared config, and why the kit is shaped this way |
-| `bunfig.toml` | the bunfig preset a repository copies |
-| `commitlint.config.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 -->
+| write every file the gates ask for | [Set up a repository](docs/how-to/set-up-a-repository.md) |
+| move to a newer release | [Upgrade the kit](docs/how-to/upgrade-the-kit.md) |
+| turn on the CSS checks | [Turn on the CSS families](docs/how-to/turn-on-the-css-families.md) |
+| look up a gate or a bin | [The bins](docs/bins.md) |
+| look up a shared config | [Native settings](docs/configs/native-settings.md) |
+| find a file the package ships | [The shipped files](docs/shipped-files.md) |
+| learn why the kit is shaped this way | [Why it is shaped this way](docs/design.md) |
 
 ## Related topics
 
-- [Native settings](docs/configs/native-settings.md)
-- [The Effect rules](docs/configs/effect-rules.md)
-- [The TypeScript rules](docs/configs/typescript-rules.md)
-- [The dependency rules](docs/configs/dependency-rules.md)
-- [The commit message lint](docs/configs/commit-messages.md)
-- [Why it is shaped this way](docs/design.md)
+- [CHANGELOG.md](CHANGELOG.md)

package/commitlint.config.ts

@@ -2,7 +2,6 @@ import configConventional from "@commitlint/config-conventional";
 
 const houseTypes: ReadonlyArray<string> = [
   "theme",
-  "herdr",
   "renamer",
   "shell",
   "pi",

package/dist/mutation/unit-test-order.js

@@ -150,7 +150,7 @@ var timedFiles = Effect2.fn("timedFiles")(function* (listed) {
   return fastestFirst(yield* fileSeconds(yield* fs.readFileString(outfile)));
 }, Effect2.scoped);
 var NodeServices = NodeChildProcessSpawner.layer.pipe(Layer.provideMerge(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer)));
-var runOrder = (listed) => Effect2.runPromise(timedFiles(listed).pipe(Effect2.map((timed) => inRunOrder(listed, timed)), Effect2.catch((failure) => Console.error(`checks: ${failure.message}, so each static mutant runs the unit tests in path order`).pipe(Effect2.as(listed))), Effect2.provide(NodeServices)));
+var runOrder = (listed) => Effect2.runPromise(timedFiles(listed).pipe(Effect2.map((timed) => inRunOrder(listed, timed)), Effect2.catch((failure) => Console.error(`checks: ${failure.message}, so each static mutant runs the unit tests in Bun's default directory order`).pipe(Effect2.as(listed))), Effect2.provide(NodeServices)));
 export {
   fastestFirst,
   inRunOrder,

package/dist/presets/knip.d.ts

@@ -2,5 +2,5 @@ import type { KnipConfiguration } from "knip";
 export type ChecksKnipConfig = Omit<KnipConfiguration, "entry" | "include"> & {
     readonly entry: readonly string[];
 };
-export declare const DEFAULT_ENTRY: readonly ["tests/**/*.test.ts", "dependency-cruiser.config.ts"];
+export declare const DEFAULT_ENTRY: readonly ["tests/**/*.test.ts", "dependency-cruiser.config.ts", "oxlint.config.ts"];
 export declare function defineConfig({ entry, ...rest }: ChecksKnipConfig): KnipConfiguration;

package/dist/presets/knip.js

@@ -1,5 +1,5 @@
 // src/quality/presets/knip.ts
-var DEFAULT_ENTRY = ["tests/**/*.test.ts", "dependency-cruiser.config.ts"];
+var DEFAULT_ENTRY = ["tests/**/*.test.ts", "dependency-cruiser.config.ts", "oxlint.config.ts"];
 var REFUSED_ENTRY = "@avi2dg/checks/knip: set entry to the files nothing imports, or [] when package.json scripts and tests name them all";
 function isGlobList(value) {
   return Array.isArray(value) && value.every((glob) => typeof glob === "string" && glob !== "");

package/dist/templates/how-to.md

@@ -6,7 +6,7 @@
 
 <Leave this section out when the task needs nothing set up first.>
 
-- <each prerequisite, with the version it is tested on>
+- <each prerequisite, naming the file that pins its version rather than the version>
 
 ## <Part of the task, verb first>
 

package/dist/templates/readme.md

@@ -4,7 +4,7 @@
 
 ## Before you begin
 
-- <each prerequisite, with the version it is tested on>
+- <each prerequisite, naming the file that pins its version rather than the version>
 
 ## Install
 

package/dist/templates/tutorial.md

@@ -4,7 +4,7 @@
 
 ## Before you begin
 
-- <each prerequisite, with the version it is tested on>
+- <each prerequisite, naming the file that pins its version rather than the version>
 
 ## <Step, verb first>
 

package/docs/bins.md

@@ -0,0 +1,67 @@
+---
+kind: reference
+audience: consumers
+---
+# The bins
+
+The kit ships one bin per check, each named `checks-` and called from a package script.
+
+## What runs
+
+`checks-lint` runs each of these gates that applies to the repository, and names every one that fails.
+A gate reads either the working tree or the range `checks-lint` resolves.
+The table groups the gates by vector, the part of a repository each one judges.
+
+<!-- generated gates: bun run build writes it from KIT_GATES in src/core/gates.ts and scripts/doc-blocks.ts -->
+
+| Vector | Gate | Reads | Runs in |
+| --- | --- | --- | --- |
+| complexity | [`checks-suppressions-ratchet`](gates/checks-suppressions-ratchet.md) | the range | every repository |
+| complexity | [`checks-repetition`](gates/checks-repetition.md) | the range | a repository tracking `*.ts` or `*.tsx` |
+| complexity | [`checks-unused`](gates/checks-unused.md) | the working tree | a repository tracking `*.ts` or `*.tsx` or `*.astro` |
+| complexity | [`checks-exports`](gates/checks-exports.md) | the range | a repository tracking `*.ts` or `*.tsx` |
+| quality | [`checks-lint-coverage`](gates/checks-lint-coverage.md) | the working tree | a repository tracking `*.ts` or `*.tsx` or `*.astro` |
+| quality | [`checks-comment-gate`](gates/checks-comment-gate.md) | the range | every repository |
+| quality | [`checks-effect-scope`](gates/checks-effect-scope.md) | the working tree | a repository tracking `oxlint.config.ts` |
+| quality | [`checks-frontend-syntax`](gates/checks-frontend-syntax.md) | the working tree | a repository tracking `frontend-syntax.json` |
+| quality | [`checks-css-size`](gates/checks-css-size.md) | the working tree | a repository tracking `*.css` |
+| quality | [`checks-no-plain-js`](gates/checks-no-plain-js.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
+| testing | [`checks-test-layout`](gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
+| testing | [`checks-quarantine-clock`](gates/checks-quarantine-clock.md) | the range | every repository |
+| docs | [`checks-docs`](gates/checks-docs.md) | the range, and every agent file at the head commit | every repository |
+| docs | [`checks-copy`](gates/checks-copy.md) | the working tree | a repository tracking `copy.json` |
+| delivery | [`checks-commit-identity`](gates/checks-commit-identity.md) | the range | every repository |
+| delivery | [`checks-ci-wiring`](gates/checks-ci-wiring.md) | the working tree | every repository |
+| delivery | [`checks-secrets`](gates/checks-secrets.md) | the range | every repository |
+| dependencies | [`checks-imports`](gates/checks-imports.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
+| dependencies | [`checks-advisories`](gates/checks-advisories.md) | the range | a repository tracking `bun.lock` |
+
+<!-- end generated gates -->
+
+These bins run on their own:
+
+- [`checks-test`](gates/checks-test.md) runs the suite as `scripts.test` and refuses a skip without a reason at its test site.
+- [`checks-flake`](gates/checks-flake.md) runs the suite on a schedule and records the seeds a flaky test fails with.
+- [`checks-mutation`](gates/checks-mutation.md) runs Stryker for scoped checks and refuses a full run outside CI.
+- [`checks-mutation-compare`](gates/checks-mutation-compare.md) compares the mutants of two reports and lists each one that regresses.
+- [`checks-mutation-baseline`](gates/checks-mutation-baseline.md) restores the newest mutation baseline from `main`, saves it on a self-hosted runner's disk in place of an artifact, and deletes superseded baselines after a `main` run.
+- [`checks-mutation-scope`](gates/checks-mutation-scope.md) turns a branch's diff into the files its mutation runs mutate.
+- [`checks-subsumed-tests`](gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
+- [`checks-night-run`](gates/checks-night-run.md) opens or comments on one GitHub issue per finding of a night run on `main`, each file whose mutation score fell and each failing test.
+- [`checks-changelog`](gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
+- [`checks-release-notes`](gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
+- [`checks-release-report`](gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.
+- [`checks-release-pr`](gates/checks-release-pr.md) opens or refreshes the pull request that releases the next version, and dispatches its checks.
+- [`checks-release-tag`](gates/checks-release-tag.md) tags a landed release commit with its version and dispatches the release workflow on the tag.
+- [`checks-vendor`](gates/checks-vendor.md) pins each library its `prepare` arguments name to a shared read-only clone and links it under `repos/`.
+- [`checks-browser`](gates/checks-browser.md) opens a product's built pages in Chrome and fails on the layout, keyboard, motion, accessibility, nesting and asset checks its `browser-checks.json` declares.
+- [`checks-commit-title`](gates/checks-commit-title.md) lints the pull request title in one step of the `ci` job.
+- [`checks-docs-only`](gates/checks-docs-only.md) tells whether a change touches only top-level Markdown and Markdown under `docs/`, so a docs-only change skips the full run.
+
+`checks-lint` has [its own page](gates/checks-lint.md), which says which range it resolves.
+oxlint runs through its own tool, as [Native settings](configs/native-settings.md) says.
+
+## Related topics
+
+- [Set up a repository](how-to/set-up-a-repository.md)
+- [Native settings](configs/native-settings.md)

package/docs/gates/checks-advisories.md

@@ -22,8 +22,8 @@ It reads `bun.lock` at the base and at the head of the range from git, not from
 It scans copies of both in a scratch directory with an empty config, so a repository's own `osv-scanner.toml` takes no part.
 It reads the advisories OSV.dev exports for npm, which hold GitHub's reviewed advisories and OpenSSF's reports of malicious packages.
 
-It runs OSV-Scanner 2.6.0, pinned by the SHA-256 of each platform's build.
-On first use it downloads the build from the scanner's GitHub release into `~/.cache/avi2dg-checks/osv-scanner/2.6.0/`.
+It runs the OSV-Scanner release `src/dependencies/osv-scanner.ts` pins, by the SHA-256 of each platform's build.
+On first use it downloads the build from the scanner's GitHub release into `~/.cache/avi2dg-checks/osv-scanner/<version>/`.
 It checks the 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-browser.md

@@ -156,10 +156,14 @@ So are a `motion` check with no state whose `reducedMotion` is `reduce`, a `keyb
 It drives the Chrome the machine has, which `CHROME_PATH` names, or Chrome's standard install when it is unset.
 The product installs the optional peers the runner 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 playwright-core@1.63.0 @axe-core/playwright@4.13.0 html-validate@11.16.0
+bun add -d @axe-core/playwright@4.13.0 html-validate@11.16.0 playwright-core@1.63.0
 ```
 
+<!-- end generated install -->
+
 ## Arguments
 
 ```sh

package/docs/gates/checks-ci-wiring.md

@@ -47,10 +47,18 @@ The call counts as a command of its own or inside a command substitution, never
 A here-document that `sh`, `bash`, `dash`, `ksh` or `zsh` reads is a script, and its calls count.
 The text of any other here-document is data, so a call there counts only inside a command substitution when the delimiter is unquoted.
 A mutation job never names `CI_RUNS_ON` directly in `runs-on`, as `vars.CI_RUNS_ON` or `vars['CI_RUNS_ON']`, so an override for an outage cannot send its mutation runs to hosted runners.
-Any other job that names `CI_RUNS_ON` in `runs-on` carries exactly the hosted-default expression `${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}`.
-In a private repository each mutation job carries exactly the labels `[self-hosted, Linux, X64, winbox]`.
-Every other job there carries exactly the hosted-default expression, or exactly the labels `[self-hosted, macOS, iphone]` of the Mac CI runner that holds the iPhone Simulator.
-A public repository may keep `runs-on: ubuntu-latest` on every job, because a pull request from a fork runs its own code on the runner.
+In a private repository any other job that names `CI_RUNS_ON` in `runs-on` carries exactly the hosted-default expression `${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}`.
+A public repository carries no self-hosted runner on a job a fork can reach, because a pull request from a fork would run its own code on that runner.
+A fork reaches a job through `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` or `issue_comment`, directly, through a local reusable workflow a reached job calls, or through a `workflow_run` trigger that names a reached workflow.
+Such a job refuses a literal `self-hosted` label, a label that interpolates an expression, a label in a set declared under `checks.mutationRunner` or `checks.selfHostedRunners`, a runner `group` and any other expression.
+A `runs-on` that is exactly `${{ matrix.<key> }}` judges each matrix value as its own labels.
+The values for the key are the combinations its axis values form, without combinations an `exclude` entry removes, plus its `include` rows, which merge into the original combinations they match and otherwise run as their own combinations.
+It refuses a value that names `self-hosted` or falls inside a label set declared under `checks.mutationRunner` or `checks.selfHostedRunners`.
+Any other expression refuses as unresolvable.
+A job on `push` or another trigger no fork reaches may still name self-hosted labels.
+In a private repository each mutation job carries exactly the labels the consumer declares in `package.json` under `checks.mutationRunner`.
+Every other job there carries exactly the hosted-default expression, or exactly one of the label sets the consumer declares under `checks.selfHostedRunners`.
+A repository without those declarations fails each job they would pin until it declares them.
 The check knows a repository is private only from GitHub's event, so a run outside CI judges only the rules that hold in either.
 
 ### Bun version
@@ -68,18 +76,19 @@ Else the `package.json` at the workspace root reads the same way.
 Else setup-bun installs latest.
 A blank version counts as none.
 A repository passes by writing the fleet version to `.bun-version` and naming that file in each step's `with.bun-version-file`.
+The fleet version is the version the kit ships in its own `.bun-version`.
 The step fails the check when the version is missing or differs from the fleet bun version.
 A range fails because it differs from the fleet version.
 A version built from an expression fails because it cannot be shown equal before the run.
 This rule skips a repository with no setup-bun step.
-The fleet bun version equals the dotfiles mise pin.
-A bump moves both together, so a kit release that moves the fleet version turns each consumer red until its pin follows.
+A kit release that moves the fleet version turns each consumer red until its pin follows.
 Each refusal names the workflow file and line, the version found and where it was read, and the fleet version.
 
 ## What it reads
 
-The bin reads `.github/workflows/*.yml`, `*.yaml`, the `scripts` in `package.json` and the shell scripts those steps and scripts run from the working tree.
+The bin reads `.github/workflows/*.yml`, `*.yaml`, the `scripts` and `checks` runners in `package.json` and the shell scripts those steps and scripts run from the working tree.
 It reads each file a setup-bun step names for its version.
+It reads the fleet pin from the kit's own `.bun-version`.
 It reads the target branch from `GITHUB_BASE_REF`, then from `refs/remotes/origin/HEAD` and then from the event file `GITHUB_EVENT_PATH` names.
 It reads whether the repository is private from `repository.private` in that event file.
 It parses the workflows with `Bun.YAML` without executing them.
@@ -94,7 +103,7 @@ It takes no arguments.
 | --- | --- |
 | 0 | Every required command has a reachable step. |
 | 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, or a setup-bun step drifts from the fleet bun version. |
-| 2 | A workflow or `package.json` cannot be decoded. |
+| 2 | A workflow or `package.json` cannot be decoded, or the kit's own `.bun-version` is missing, unreadable or blank. |
 
 ## Sample output
 
@@ -110,7 +119,7 @@ A mutation job that names `CI_RUNS_ON` in `runs-on` produces a report like this:
 
 ```
 ci-wiring: 1 job(s) run on the wrong runner:
-  .github/workflows/mutation-compare.yml job mutation-compare: a mutation job reads CI_RUNS_ON, so an override moves its mutation runs off winbox; set runs-on: [self-hosted, Linux, X64, winbox]
+  .github/workflows/mutation-compare.yml job mutation-compare: a mutation job reads CI_RUNS_ON, so an override moves its mutation runs off [self-hosted, gpu, x64]; set runs-on: [self-hosted, gpu, x64]
 ```
 
 A reference to a missing workflow produces a report like this:

package/docs/gates/checks-commit-identity.md

@@ -11,6 +11,9 @@ audience: consumers
 The author and committer of each commit must be allowed.
 A commit whose trailer block carries a `Co-authored-by` trailer, as git parses it, is refused.
 `GitHub <noreply@github.com>` is allowed as committer only.
+A commit that GitHub committed allows any author name with an allowed email.
+GitHub authors a web merge under the account's display name.
+The same author on a commit with any other committer must match the allowed name too.
 `github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>` is allowed as author only of a commit whose subject is `chore: release <version>`, with or without the pull request number a squash merge adds.
 GitHub attributes the release commit [checks-release-pr](checks-release-pr.md) makes to that bot, since it commits through the workflow token.
 Such a commit may carry a `Co-authored-by` trailer naming that bot, since GitHub adds one to some squash merges of a pull request the bot opened, and every other trailer is refused.
@@ -21,7 +24,7 @@ Such a commit may carry a `Co-authored-by` trailer naming that bot, since GitHub
 Each person can be any form npm allows, an object with `name` and optional `email` and `url`, or a string such as `Avi <avi@example.com> (https://example.com)`.
 A person with both a name and an email is an allowed author.
 A person without an email is ignored.
-When no person carries an email, the kit allows `avi2d <avi2dg@gmail.com>`.
+When no person carries an email, no identity is allowed, so the check fails every commit until the repository declares its owners.
 The bin reads commits from git and parses their trailer blocks.
 
 ## Arguments
@@ -39,7 +42,7 @@ With one argument, it checks that commit alone.
 | Code | Result |
 | --- | --- |
 | 0 | Every commit carries an allowed identity. |
-| 1 | A commit carries a foreign identity. |
+| 1 | A commit carries a foreign identity, or `package.json` declares no authors. |
 | 2 | A ref, argument or `package.json` cannot be decoded. |
 
 ## Sample output
@@ -48,7 +51,7 @@ With one argument, it checks that commit alone.
 commit-identity: 1 of 1 commit(s) in HEAD carry a foreign identity:
   79fa94f9f027 feat: foreign
     author someone <someone@example.com>
-  allowed: avi2d <avi2dg@gmail.com>
+  allowed: Repo Owner <owner@example.com>
 ```
 
 ## When it runs

package/docs/gates/checks-copy.md

@@ -66,10 +66,14 @@ It reads the working tree, so an uncommitted file is judged like a committed one
 
 A repository that declares an HTML file installs the optional peer the gate loads for it, at the version the kit pins:
 
+<!-- generated install: bun run build writes it from package.json and scripts/doc-blocks.ts -->
+
 ```sh
 bun add -d html-validate@11.16.0
 ```
 
+<!-- end generated install -->
+
 ## Arguments
 
 ```sh