@avi2dg/checks 0.43.0 → 0.45.0

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

@@ -4,11 +4,18 @@ audience: consumers
 ---
 # checks-frontend-syntax
 
-`checks-frontend-syntax` is the opt-in gate that refuses two CSS constraints a program can decide: a transition over `all` and a body-wide `user-select`.
+`checks-frontend-syntax` is the opt-in gate that holds a repository's CSS to stylelint, under the kit's two rules of its own and the rule families of `@avi2dg/checks/stylelint`.
 
 ## What it checks
 
-It runs stylelint with two of stylelint's own rules, and with no other rule and no repository config:
+It runs stylelint twice over each declared input.
+The repository run holds the families the repository's `stylelint.config.ts` sets, and applies `--fix`.
+The kit run then holds the kit's two rules over each file the repository run matched.
+It reads no repository config and no count in `stylelint-suppressions.json`, so neither turns those rules off.
+
+### The kit's two rules
+
+The kit run refuses two CSS constraints a program can decide, a transition over `all` and a body-wide `user-select`:
 
 | Rule | What it refuses | Why |
 | --- | --- | --- |
@@ -19,7 +26,37 @@ The second rule refuses any value on those selectors, so `body { user-select: te
 It matches each item of the selector list as a whole.
 So it does not follow `:is()`, `:where()` or `:not()`, nor a compound such as `html body` or `body *`.
 A nested rule is judged by its own selector, so `.card { * { user-select: none; } }` fails as `*`.
-A control that needs selection off sets it on its own selector, such as `.drag-handle { user-select: none; }`, which passes.
+A control that needs selection off sets it on its own selector, such as `.drag-handle { user-select: none; }`, which this rule passes and the Baseline family reports.
+
+### The rule families
+
+`defineConfig` from `@avi2dg/checks/stylelint` builds the config the repository run holds:
+
+| Family | Rules | Default |
+| --- | --- | --- |
+| G1 correctness | `stylelint-config-recommended`, the stylelint team's rules for likely mistakes, such as `font-variant-numeric: oldstyle-num` for `oldstyle-nums` | on |
+| G2 conventions | `stylelint-config-standard`, which extends G1 with the stylelint team's notation and spacing rules | on |
+| G3 selector complexity | `selector-max-specificity` at `0,3,2` and `selector-max-compound-selectors` at 3 | on |
+| G4 design tokens | `color-no-hex`, `color-named: "never"`, `function-disallowed-list` over `rgb`, `rgba`, `hsl`, `hsla`, `hwb`, `lab`, `lch`, `oklab`, `oklch` and `color`, and `font-size` only as one `var(--…)` with no fallback, or `inherit` | off until `tokens` names the token files, and off in those files |
+| G5 Baseline target | `plugin/use-baseline` from `stylelint-plugin-use-baseline`, which judges each property, value, function, at-rule, selector and unit against the Baseline data, and passes a property inside an `@supports` block | on, at the target `baseline` sets |
+
+The builder changes three of the shared config's rules:
+
+- `no-descending-specificity` is off, since it compares only the last compound selector and has no access to the DOM.
+  It reports components that never match one element.
+- `property-no-vendor-prefix` keeps reporting without a fix, and passes `-webkit-user-select`, since its fix deletes the prefix Safari still needs.
+- In an `.html` or `.astro` file, `declaration-block-single-line-max-declarations` is off, since a `style` attribute is one line.
+
+CSS repetition is not a family of this gate: a repository adds `"css"` to `format` in `.jscpd.json`, and [checks-repetition](checks-repetition.md) then fails when a stylesheet's repeated lines grow.
+
+### What no comment turns off
+
+It sets stylelint's `ignoreDisables`, so a `stylelint-disable` comment silences nothing in either run, and [checks-comment-gate](checks-comment-gate.md) refuses one on the line that adds it.
+A repository adopts a family over existing problems by counting them in `stylelint-suppressions.json` with `--suppress`.
+stylelint lets a file and rule through while its problems stay within the count, and [checks-suppressions-ratchet](checks-suppressions-ratchet.md) fails a change that raises a count.
+`--suppress` counts only what the repository run reports, and a file that does not parse still fails in the kit run.
+
+### Files
 
 It judges each `.css` file, and each `<style>` block and `style` attribute in an `.html`, `.astro`, `.vue` or `.svelte` file, through `postcss-html`.
 It reports a file that does not parse, since it cannot judge one.
@@ -28,7 +65,7 @@ It fails on each declared input that matches no file, so an input that a renamed
 These are outside what it decides:
 
 - A `transition` shorthand that names no property, such as `transition: 200ms`, which the browser reads as `all`.
-- A value it cannot see, such as `transition: var(--motion)` or a style a script sets.
+- A value it cannot see, such as `transition: var(--motion)`, a style a script sets, or a colour a build writes into CSS outside the declared inputs.
 - `user-select: none` in a `style` attribute on `<body>`, which has no selector to judge.
 - A viewport that disables zoom, since stylelint reads only CSS.
   A repository that runs only this gate gets no viewport check, and [checks-browser](checks-browser.md) refuses one on the rendered page through axe's `meta-viewport` rule.
@@ -49,35 +86,69 @@ A glob over built output, such as `dist/**/*.html`, judges the styles a framewor
 stylelint resolves each glob from that directory, skips `node_modules/` and honours `.stylelintignore`.
 It reads the working tree, so an uncommitted file is judged like a committed one.
 
-The repository installs the two optional peers the gate loads, at the versions the kit pins:
+It imports `stylelint.config.ts` from the same directory, and passes its default export to stylelint:
+
+```ts
+import { defineConfig } from "@avi2dg/checks/stylelint";
+
+export default defineConfig({
+  baseline: "widely",
+  tokens: ["src/styles/tokens.css"],
+});
+```
+
+`baseline` and `tokens` have no default, since only the repository knows them, so `tsc` refuses a config that leaves either out.
+The builder throws when the gate loads such a config anyway.
+
+| Key | Takes |
+| --- | --- |
+| `baseline` | `"widely"`, `"newly"` or a year such as `2024`, which allows what became Baseline newly available in that year or earlier |
+| `tokens` | the globs of the files that declare the design tokens, which turns G4 on in every other file, or `false` |
+
+`rules`, `overrides`, `ignoreFiles` and the other keys mean what they mean in stylelint's own docs, and land after the kit's.
+An accepted exception lives there rather than in a comment, such as a property the Baseline rule passes:
+
+```ts
+rules: { "plugin/use-baseline": [true, { available: "widely", ignoreProperties: { "user-select": ["none"] } }] },
+```
+
+The builder owns `extends` and `plugins`.
+It resolves the shared config, the plugin and `postcss-html` beside the kit, so they need not sit under the directory the gate runs in.
+stylelint cannot load `stylelint.config.ts` itself under TypeScript 7, so a bare `stylelint --fix` finds no config, and the gate's `--fix` stands in for it.
+A config not built with `defineConfig` names its own `customSyntax` for markup, or each `.html` or `.astro` file fails to parse in the repository run.
+
+The repository installs the optional peers the gate loads, at the versions the kit pins:
 
 ```sh
-bun add -d stylelint@17.16.0 postcss-html@2.0.0
+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
 ```
 
 ## Arguments
 
 ```sh
-checks-frontend-syntax [<directory>]
+checks-frontend-syntax [--fix] [--suppress] [<directory>]
 ```
 
 It checks the directory it runs in, or the directory it is given.
+`--fix` rewrites what a rule of the config fixes, such as `#ffffff` to `#fff`, and reports what is left.
+`--suppress` writes each problem the config reports into `stylelint-suppressions.json`, and drops a count whose problems are gone.
 
 ## Exit codes
 
 | Code | When |
 | --- | --- |
-| 0 | every declared input matches a file, and no file holds a refused declaration |
-| 1 | a file holds a refused declaration or does not parse, or a declared input matches no file |
-| 2 | `frontend-syntax.json` is missing or does not decode, its input list is empty, or stylelint or `postcss-html` cannot load |
+| 0 | every declared input matches a file, and no file holds a problem beyond its suppressed count |
+| 1 | a file holds a problem or does not parse, or a declared input matches no file |
+| 2 | `frontend-syntax.json` is missing or does not decode, its input list is empty, `stylelint.config.ts` is missing or does not load, stylelint refuses an option, a peer cannot load, or an argument is unknown |
 
 ## Sample output
 
 ```
-frontend-syntax: 3 problem(s) in 2 file(s) from 3 declared input(s):
+frontend-syntax: 4 problem(s) in 2 file(s) from 3 declared input(s):
   dist/**/*.html: the declared input matches no file
   src/layouts/Base.astro:4:15 Disallowed property "user-select" for selector "body". Leave text selectable across the page, and turn selection off only on the control that needs it.
   src/styles/site.css:1:17 Disallowed value "all 200ms" for property "transition". Name the properties the transition animates.
+  src/styles/site.css:9:1 Too high specificity in ".nav .item.is-open > a:hover", maximum "0,3,2" (selector-max-specificity)
 ```
 
 A passing run counts what it judged:
@@ -89,9 +160,13 @@ frontend-syntax: no violation in 2 file(s) from 2 declared input(s)
 ## When it runs
 
 `checks-lint` runs it when the repository tracks `frontend-syntax.json` at its root.
-A repository without that file never runs it and needs neither stylelint nor `postcss-html`.
+A repository without that file never runs it and needs neither `stylelint.config.ts` nor the peers.
 
 ## Related topics
 
 - [checks-browser](checks-browser.md)
 - [checks-lint](checks-lint.md)
+- [checks-comment-gate](checks-comment-gate.md)
+- [checks-suppressions-ratchet](checks-suppressions-ratchet.md)
+- [checks-repetition](checks-repetition.md)
+- [Native settings](../configs/native-settings.md)

package/docs/gates/checks-lint.md

@@ -13,6 +13,7 @@ Gates requiring tracked TypeScript files begin running when the repository track
 `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`.
 `checks-frontend-syntax` begins running when the repository tracks `frontend-syntax.json` at its root.
+`checks-copy` begins running when the repository tracks `copy.json` at its root.
 All other gates run for every repository.
 
 ## What it reads
@@ -47,7 +48,7 @@ With two arguments, the base and head override range discovery.
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 16 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 18 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->

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

@@ -181,13 +181,15 @@ It slims the report first, so the artifact holds about 0.5 MB in place of about
 The full upload keeps 30 days, so the newest full baseline outlives the gap between full runs.
 A pull request's scope step loses its coverage when no full baseline outlives the gap.
 
-A pull request's scope step restores the full report with `--full`:
+A pull request's scope step restores the full report with `--full`, and [checks-mutation-scope](checks-mutation-scope.md) reads it:
 
 ```yaml
 - name: Select mutation scope
   env:
     GH_TOKEN: ${{ github.token }}
-  run: bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
+  run: |
+    bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
+    bunx checks-mutation-scope "$(git merge-base HEAD origin/main)" "$RUNNER_TEMP/baseline-full/mutation.json" >> "$GITHUB_ENV"
 ```
 
 ## Related topics

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

@@ -78,7 +78,7 @@ The shared preset refuses a full `stryker run` outside CI and names that workflo
 
 ## Running it in CI
 
-It runs on pull requests from a workflow named `mutation-compare`, comparing the head report against a report built at the merge-base:
+It runs on pull requests from a workflow named `mutation-compare`, comparing the head report against a report built at the merge-base over the same scope:
 
 ```yaml
 name: mutation-compare
@@ -87,6 +87,9 @@ on:
 jobs:
   mutation-compare:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
     steps:
       - uses: actions/checkout@v5
         with:
@@ -95,28 +98,50 @@ jobs:
         with:
           bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
-      - run: bunx stryker run
-      - run: |
+      - name: Select mutation scope
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
+          echo "BASE_SHA=$base" >> "$GITHUB_ENV"
+          bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
+          bunx checks-mutation-scope "$base" "$RUNNER_TEMP/baseline-full/mutation.json" >> "$GITHUB_ENV"
+      - if: env.SCOPE == ''
+        run: echo "::notice::mutation-compare: nothing in mutation scope changed, so neither Stryker run starts"
+      - if: env.SCOPE != ''
+        run: bunx stryker run --mutate "$SCOPE"
+      - if: env.SCOPE != ''
+        run: |
           base_worktree="$RUNNER_TEMP/mutation-base-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
           echo "BASE_WORKTREE=$base_worktree" >> "$GITHUB_ENV"
           git worktree prune
-          git worktree add "$base_worktree" "$(git merge-base HEAD origin/main)"
-          (cd "$base_worktree" && bun install --frozen-lockfile && bunx stryker run)
-      - run: bun run checks-mutation-compare --advisory "$BASE_WORKTREE/reports/mutation/mutation.json" reports/mutation/mutation.json
+          git worktree add "$base_worktree" "$BASE_SHA"
+          (cd "$base_worktree" && bun install --frozen-lockfile && bunx stryker run --mutate "$SCOPE")
+      - if: env.SCOPE != ''
+        run: bun run checks-mutation-compare --advisory "$BASE_WORKTREE/reports/mutation/mutation.json" reports/mutation/mutation.json
       - if: always() && env.BASE_WORKTREE != ''
         run: |
           git worktree remove --force "$BASE_WORKTREE"
           git worktree prune
 ```
 
-Both Stryker runs are full sweeps, and GitHub sets `CI=true` on every runner, so the preset lets them through.
+The scope step picks the files the pull request changes and the sources its changed unit tests cover or kill, as [checks-mutation-scope](checks-mutation-scope.md) says.
+Neither run mutates a file outside that scope, so the job's time follows the size of the change and not the size of the repository.
+Both runs take the same `--mutate "$SCOPE"`, so the two reports hold the same files.
+A scope file the merge base lacks matches nothing there, and Stryker still writes a report.
+An empty scope skips both runs and the comparison, and the notice names the skip on the run's summary.
+A changed unit test with no full baseline on `main` fails the scope step, since no report then says which sources the test covers.
+A changed unit test that `main` edited after that baseline widens the scope to every file the `mutate` globs match.
+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`, because a pull request from a fork runs its own code on the runner.
-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 full sweeps.
+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`.
 [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names it in `runs-on`.
 
 ## Related topics
 
 - [checks-mutation](checks-mutation.md)
+- [checks-mutation-scope](checks-mutation-scope.md)
 - [checks-test-layout](checks-test-layout.md)

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

@@ -0,0 +1,140 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-mutation-scope
+
+`checks-mutation-scope` turns a pull request's diff into the files its mutation runs mutate, and prints them as lines for `GITHUB_ENV`.
+
+## What it checks
+
+It picks a scope rather than judging one, so it fails only when it cannot pick one.
+It reads `git diff --name-status -M` from the merge base of `<base>` and `HEAD` to `HEAD`.
+A changed source enters the scope when the repository's own Stryker `mutate` globs match it, with each negated glob applied in order.
+It resolves each glob and each path against the working directory, as Stryker does, so an absolute glob matches too.
+A `mutate` entry with a mutation range, such as `src/a.ts:1-10`, fails the run, since a scope of whole files cannot keep the range.
+`--mutate` replaces those globs, so a path the config excludes, such as `packages/*/src/live/**` or `packages/*/src/bin.ts`, stays out of the scope.
+A renamed source enters under both names, and a deleted source does not enter.
+
+A unit test is a `.test.ts` or `.test.tsx` file under `tests/unit/`, the files the preset's `unitTestFiles` lists.
+A unit test the pull request adds, edits, deletes or renames is changed.
+A unit test that reads a changed file under `tests/` is changed too.
+It reads a file when it imports it, directly or through another file under `tests/`.
+An import resolves as Bun resolves it, to the file it names, then with an extension added, and only then to the directory's `index`.
+A unit test also reads a changed fixture under `tests/fixtures/` when it names the fixture's path or a directory above it.
+Bun loads each `[test] preload` in `bunfig.toml` before every test file.
+So every unit test is changed when the preload list differs between the merge base and `HEAD`.
+The same holds when the pull request changes a preload or a file a preload imports, wherever that file lives.
+
+Each source whose mutants a changed unit test covers or kills in the full baseline report then enters the scope, when it still exists at `HEAD`.
+So a kill lost through a test change alone still shows in the comparison, in a source the pull request leaves alone.
+A changed unit test with no baseline report fails the run rather than reading incomplete coverage.
+Stryker records each test file's source in the report's `testFiles`.
+A changed unit test the merge base holds must have that recorded source match its content at the merge base.
+Otherwise the report ran an older test, so its coverage cannot say what the test covers now.
+The scope then widens to every file at `HEAD` the `mutate` globs match.
+A unit test the pull request adds is new to every report, so it needs no entry.
+Stryker writes no source without mutants into the report, so a mutated source the report lacks may be newer than it.
+When a unit test changed, each such source that exists at `HEAD` enters the scope.
+A change under `tests/e2e/` changes no unit test, so it needs no baseline report.
+The scope trusts the coverage edges of the latest full baseline.
+So a helper, fixture or preload changed on `main` since that baseline can hide a lost kill until the scheduled full baseline refreshes.
+
+## What it reads
+
+- The diff from the merge base to `HEAD`, and the files git tracks at both.
+- The Stryker config file `stryker run` loads from the working directory, such as `stryker.conf.mjs`, for its `mutate` globs.
+  It imports a JavaScript config, so the step runs after `bun install`.
+  With no config file, or a config with no `mutate`, it takes Stryker's default globs.
+- `bunfig.toml` at the merge base and at `HEAD`, for its `[test] preload` entries.
+- Each preload at `HEAD`, and each file it imports through a relative path, for the files the preloads load.
+- Each tracked `.ts` and `.tsx` file under `tests/` from the working tree, for its relative imports and the fixture paths it names.
+- Each changed unit test at the merge base, to match it against the source the report recorded.
+- 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 and passed `--disableBail`, which lists every killing test.
+
+## Arguments
+
+```sh
+checks-mutation-scope <base> [<full-baseline-report>]
+```
+
+`<base>` is the branch the pull request merges into, such as `origin/main`, or the merge base itself.
+`<full-baseline-report>` is the path the full baseline was restored to, and a path with no file reads as no report.
+
+## Output
+
+It prints one line for each list, as `NAME=a,b`, with each list sorted by path:
+
+| Line | What it lists |
+| --- | --- |
+| `SCOPE` | the files the base and head runs both mutate, empty when nothing in mutation scope changed |
+| `STALE_TESTS` | the unit tests that count as changed only because they read a changed file |
+
+Stryker reads each `--mutate` entry as a glob and turns each backslash into a `/`.
+So `SCOPE` wraps each glob character in a path in a class of its own.
+`app/routes/[id].ts` prints as `app/routes/[[]id[]].ts`, which matches that file and not `app/routes/i.ts`.
+`STALE_TESTS` names each test by its literal path, as the incremental state keys it.
+
+Stryker compares only a test file's own source when it resumes from incremental state.
+A run that resumes from the merge base's state drops each `STALE_TESTS` entry from that state first, so Stryker retests the mutants those tests cover.
+
+On stderr it names each unit test that reads a changed file, and each source a changed unit test brings in.
+It also names each stale test that widens the scope.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | it printed the scope, an empty one included |
+| 2 | the arguments do not parse, git fails, the Stryker config, `bunfig.toml` or the baseline report does not load, a `mutate` entry names a mutation range, or a unit test changed with no baseline report |
+
+## Sample output
+
+A helper change that reaches a source the pull request leaves alone:
+
+```
+mutation-scope: tests/unit/dashboard/snapshot.test.ts reads tests/lib/session-fixture.ts
+mutation-scope: packages/ui/src/layout.ts enters through tests/unit/dashboard/snapshot.test.ts
+SCOPE=packages/session-quota/src/notes.ts,packages/ui/src/layout.ts
+STALE_TESTS=tests/unit/dashboard/snapshot.test.ts
+```
+
+A changed unit test with no full baseline on `main`, on stderr:
+
+```
+mutation-scope: tests/unit/dashboard/snapshot.test.ts changed, but no baseline report at /runner/temp/baseline-full/mutation.json says which sources they cover
+```
+
+A changed unit test that `main` edited after its newest full baseline, on stderr:
+
+```
+mutation-scope: the baseline report did not run tests/unit/dashboard/snapshot.test.ts as the merge base holds it, so every mutated source enters
+```
+
+## When it runs
+
+Only a CI step the repository writes runs it, in the pull request's mutation comparison, before either Stryker run:
+
+```yaml
+- name: Select mutation scope
+  env:
+    GH_TOKEN: ${{ github.token }}
+  run: |
+    base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
+    echo "BASE_SHA=$base" >> "$GITHUB_ENV"
+    bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
+    bunx checks-mutation-scope "$base" "$RUNNER_TEMP/baseline-full/mutation.json" >> "$GITHUB_ENV"
+```
+
+Each later step reads `$SCOPE` from the environment, and a failed scope step adds nothing to it.
+[checks-mutation-compare](checks-mutation-compare.md#running-it-in-ci) shows the whole job.
+The full baseline comes from the `mutation` workflow, as [checks-mutation](checks-mutation.md#running-it-in-ci) shows.
+
+## Related topics
+
+- [checks-mutation-compare](checks-mutation-compare.md)
+- [checks-mutation](checks-mutation.md)
+- [checks-mutation-baseline](checks-mutation-baseline.md)

package/docs/gates/checks-mutation.md

@@ -96,17 +96,20 @@ jobs:
         with:
           bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
-      - run: bunx stryker run
-      - if: always()
-        run: bunx checks-mutation-baseline --slim reports/mutation/mutation.json "$RUNNER_TEMP/report/mutation.json"
+      - run: bunx stryker run --disableBail
+      - run: bunx checks-mutation-baseline --slim reports/mutation/mutation.json "$RUNNER_TEMP/full/mutation.json"
       - uses: actions/upload-artifact@v4
-        if: always()
         with:
-          name: mutation-report
-          path: ${{ runner.temp }}/report/mutation.json
-          retention-days: 7
+          name: mutation-baseline-full
+          path: ${{ runner.temp }}/full/mutation.json
+          retention-days: 30
 ```
 
+The run restores no state and passes `--disableBail`, so its report names every test that covers or kills each mutant.
+The upload is the `mutation-baseline-full` artifact that a pull request'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 pull request 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 job runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a repository sends its full sweeps.
@@ -118,4 +121,5 @@ GitHub sets `CI=true` on every runner, so the preset lets the full run through t
 ## Related topics
 
 - [checks-mutation-compare](checks-mutation-compare.md)
+- [checks-mutation-scope](checks-mutation-scope.md)
 - [checks-subsumed-tests](checks-subsumed-tests.md)

package/docs/gates/checks-no-plain-js.md

@@ -0,0 +1,60 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-no-plain-js
+
+`checks-no-plain-js` is the gate that refuses a plain JavaScript source file in a repository that tracks TypeScript.
+
+## What it checks
+
+It fails on every `.js` or `.mjs` file in the working tree that none of the exemptions below covers.
+Each line names the file and tells its writer to convert it to TypeScript.
+`dist/` holds the committed build output, so the check passes over it.
+`dependency-cruiser.config.js` at the repository root is written by `bun run build` from the TypeScript builder, so the check passes over that one path.
+`node_modules/` and `repos/` hold installed and vendored trees, so the check passes over both.
+`public/` holds assets the server sends verbatim, which no compiler reads, so the check passes over it.
+`tests/fixtures/` holds data the suite never parses, so the check passes over it.
+Stryker loads its config only as JSON or JavaScript, so the check passes over a config file carrying a Stryker config name, such as `stryker.conf.mjs`.
+The Stryker preset ships as `stryker.preset.js` under its documented import path, so the check passes over that name.
+A JavaScript config whose tool also loads TypeScript fails, such as a commitlint or dependency-cruiser config.
+
+## What it reads
+
+It reads the working tree.
+It scans the tracked and untracked files that `git ls-files --exclude-standard` reports, so `node_modules/` and every gitignored tree are out of reach.
+A local run agrees with CI before `git add`.
+
+## Arguments
+
+```sh
+checks-no-plain-js [<directory>]
+```
+
+It checks the directory it runs in, or the directory it is given.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | the working tree holds no plain JavaScript source |
+| 1 | a file in the working tree is plain JavaScript |
+| 2 | git does not list the working tree |
+
+## Sample output
+
+```
+no-plain-js: 2 violation(s)
+  src/legacy.js: plain JavaScript source in a TypeScript repository; convert it to TypeScript
+  tools/build.mjs: plain JavaScript source in a TypeScript repository; convert it to TypeScript
+```
+
+## When it runs
+
+`checks-lint` runs it when the repository tracks TypeScript.
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [checks-test-layout](checks-test-layout.md)
+- [checks-unused](checks-unused.md)

package/docs/gates/checks-repetition.md

@@ -23,6 +23,8 @@ A `path` entry the base revision lacks reads as empty there, so a newly measured
 { "path": ["src"], "format": ["typescript"], "ignore": ["**/*.d.ts"] }
 ```
 
+A repository that lists `"css"` in `format` measures its stylesheets the same way, and [checks-frontend-syntax](checks-frontend-syntax.md) leaves CSS repetition to this gate.
+
 The gate sets the 50 tokens and 5 lines itself, over any the file names.
 A `threshold` the file names never fails the gate, which reads jscpd's report once the scan finishes.
 The bin reads the base and head commits rather than the working tree's file contents.
@@ -56,5 +58,6 @@ When the head holds no `.jscpd.json`, the gate reports that no file was measured
 
 ## Related topics
 
+- [checks-frontend-syntax](checks-frontend-syntax.md)
 - [Native settings](../configs/native-settings.md)
 - [checks-suppressions-ratchet](checks-suppressions-ratchet.md)

package/docs/gates/checks-suppressions-ratchet.md

@@ -4,18 +4,19 @@ audience: consumers
 ---
 # checks-suppressions-ratchet
 
-`checks-suppressions-ratchet` is the gate that fails when a change raises a count in `oxlint-suppressions.json`.
+`checks-suppressions-ratchet` is the gate that fails when a change raises a count in `oxlint-suppressions.json` or `stylelint-suppressions.json`.
 
 ## What it checks
 
 oxlint accepts whatever `oxlint --suppress-all` writes to `oxlint-suppressions.json`, so raising a count to let a new site through passes the lint.
-The ratchet fails naming each file and rule whose count rose or that appeared.
+stylelint accepts `stylelint-suppressions.json` the same way, and writes it in the same shape, a count per rule per file.
+The ratchet fails naming the suppressions file, the file and the rule of each count that rose or appeared.
 A count that fell and an entry that went both pass.
 
 ## What it reads
 
-It reads `oxlint-suppressions.json` at a base and at a head, from the directory the command runs in, which is where oxlint writes it.
-A commit without the file counts as empty, so the commit that first adds a baseline fails with every entry appearing.
+It reads `oxlint-suppressions.json` and `stylelint-suppressions.json` at a base and at a head, from the directory the command runs in, which is where oxlint and stylelint write them.
+A commit without a file counts it as empty, so the commit that first adds a baseline fails with every entry appearing.
 
 ## Arguments
 
@@ -33,22 +34,23 @@ With one it compares that commit with its parent, or with the empty tree for a r
 | --- | --- |
 | 0 | no count rose and no entry appeared |
 | 1 | a count rose or an entry appeared |
-| 2 | a ref does not resolve, the parent exists but is not in the clone, or the file is not oxlint's count per rule per file |
+| 2 | a ref does not resolve, the parent exists but is not in the clone, or a file is not a count per rule per file |
 
 ## Sample output
 
 ```
-suppressions-ratchet: 2 count(s) in oxlint-suppressions.json rose or appeared; fix the site instead of suppressing it:
-  src/added.ts typescript/no-unsafe-type-assertion appeared with 1
-  src/dispatch.ts typescript/no-non-null-assertion rose from 12 to 13
+suppressions-ratchet: 2 count(s) rose or appeared; fix the site instead of suppressing it:
+  oxlint-suppressions.json src/dispatch.ts typescript/no-non-null-assertion rose from 12 to 13
+  stylelint-suppressions.json src/styles.css selector-max-specificity appeared with 1
 ```
 
 ## When it runs
 
 `checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
-A repository with no `oxlint-suppressions.json` passes, since both ends count as empty.
+A repository with neither file passes, since both ends count as empty.
 
 ## Related topics
 
 - [The Effect rules](../configs/effect-rules.md)
+- [checks-frontend-syntax](checks-frontend-syntax.md)
 - [checks-lint](checks-lint.md)

package/docs/gates/checks-test.md

@@ -49,7 +49,9 @@ It counts a run as `ci` when `CI` is true and as `local` otherwise.
 
 The command takes no arguments for the default suite, except the worker count of [Parallel runs](#parallel-runs).
 Use `checks-test --tier=live` or `checks-test --tier=pixel` for a named test tier.
-A tier run clears Bun's ignored paths, runs only `./tests/live` or `./tests/pixel`, and still checks each skip.
+Use `checks-test --tier=unit` or `checks-test --tier=e2e` to run only one level of the default suite.
+A live or pixel run clears Bun's ignored paths, runs only `./tests/live` or `./tests/pixel`, and still checks each skip.
+A unit or e2e run keeps Bun's ignored paths, runs only `./tests/unit` or `./tests/e2e`, and still checks each skip.
 
 Files under `tests/quarantine/` are not run or judged, as [checks-test-layout](checks-test-layout.md) says.
 
@@ -90,6 +92,7 @@ The count is a whole number from 1 up, and without the option the suite runs ser
 Tests still run in random order, and `test.only` still fails the run.
 Bun merges every worker's results into the one JUnit report, so each skipped test and each todo is judged as in a serial run.
 A tier script takes the same option, as in `checks-test --tier=live --parallel=4`.
+[checks-flake](checks-flake.md#parallel-hunts) hunts with the worker count the `test` script sets.
 
 A file whose worker crashes, for example when a test calls `process.exit`, fails the run.
 Bun reports no result from that file, so its skips are not judged and its declarations are not reported as stale.
@@ -100,7 +103,7 @@ A timings option waits for Bun to honour timings under random order.
 ## Arguments
 
 The default command takes no arguments except `--parallel=<workers>`, as [Parallel runs](#parallel-runs) says.
-Its named tier options are `--tier=live` and `--tier=pixel`, and a tier run takes `--parallel=<workers>` too.
+Its named tier options are `--tier=live`, `--tier=pixel`, `--tier=unit` and `--tier=e2e`, and a tier run takes `--parallel=<workers>` too.
 Each option appears at most once.
 It refuses test filters because every test excluded by a filter would look skipped.