@avi2dg/checks 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.31.0
+
+Released 2026-09-28.
+
+### Features
+
+- lint .astro files in lint coverage, unused and a thin-frontmatter rule [#108](https://github.com/avi2d/checks/pull/108)
+
+## 0.30.0
+
+Released 2026-09-28.
+
+### Features
+
+- **testing:** refuse full mutation runs outside CI [#106](https://github.com/avi2d/checks/pull/106)
+- **docs:** refuse a decision-record revision link named on one side only [#105](https://github.com/avi2d/checks/pull/105)
+
 ## 0.29.0
 
 Released 2026-09-28.

package/README.md

@@ -118,9 +118,9 @@ The table groups the gates by vector, the part of a repository each one judges.
 | --- | --- | --- | --- |
 | 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` |
+| 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` |
+| 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 |
 | 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 |
@@ -135,6 +135,7 @@ 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) holds every mutant in a pull request to no regression.
 - [`checks-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
 - [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
@@ -174,7 +175,7 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 | `src/` | every bin, which a package script calls by its `checks-` name, the modules the bins import, and the Effect rule blocks under `src/quality/presets/` |
 | `dist/` | the compiled oxlint plugins and the doc templates, one template per kind of doc file |
 | `oxlintrc.json` | the oxlint base config `.oxlintrc.json` extends |
-| `stryker.preset.js` | the Stryker mutation-testing preset |
+| `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` |
 

package/dist/readability/index.js

@@ -416,11 +416,104 @@ var rule = {
 };
 var cognitive_complexity_default = rule;
 
+// src/complexity/readability/thin-astro.ts
+function unwrapped(expression) {
+  let current = expression;
+  while (current.type === "TSAsExpression" || current.type === "TSSatisfiesExpression" || current.type === "TSNonNullExpression" || current.type === "TSTypeAssertion") {
+    current = current.expression;
+  }
+  return current;
+}
+function isAstroProps(value) {
+  if (value.type !== "MemberExpression" || value.computed)
+    return false;
+  const { object, property } = value;
+  return object.type === "Identifier" && object.name === "Astro" && property.type === "Identifier" && property.name === "props";
+}
+function isPlainValue(value, bound) {
+  return value.type === "Literal" || value.type === "Identifier" && bound.has(value.name);
+}
+function readsProps(expression, bound) {
+  const value = unwrapped(expression);
+  if (value.type !== "MemberExpression")
+    return value.type === "Identifier" && bound.has(value.name);
+  if (value.computed && !isPlainValue(value.property, bound))
+    return false;
+  return isAstroProps(value) || readsProps(value.object, bound);
+}
+function isPlainPattern(pattern, bound) {
+  if (pattern === null)
+    return true;
+  if (pattern.type === "RestElement")
+    return isPlainPattern(pattern.argument, bound);
+  if (pattern.type === "AssignmentPattern")
+    return isPlainValue(pattern.right, bound) && isPlainPattern(pattern.left, bound);
+  if (pattern.type === "ArrayPattern")
+    return pattern.elements.every((element) => isPlainPattern(element, bound));
+  if (pattern.type === "Identifier")
+    return true;
+  return pattern.properties.every((property) => property.type === "RestElement" ? isPlainPattern(property.argument, bound) : (!property.computed || isPlainValue(property.key, bound)) && isPlainPattern(property.value, bound));
+}
+function isPropsRead(declarator, bound) {
+  return declarator.init !== null && readsProps(declarator.init, bound) && isPlainPattern(declarator.id, bound);
+}
+function boundName(pattern, found) {
+  if (pattern === null)
+    return;
+  if (pattern.type === "RestElement")
+    boundName(pattern.argument, found);
+  else if (pattern.type === "AssignmentPattern")
+    boundName(pattern.left, found);
+  else if (pattern.type === "ObjectPattern") {
+    for (const property of pattern.properties)
+      boundName(property.type === "Property" ? property.value : property.argument, found);
+  } else if (pattern.type === "ArrayPattern") {
+    for (const element of pattern.elements)
+      boundName(element, found);
+  } else
+    found.add(pattern.name);
+}
+function isTypeDeclaration(statement) {
+  const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+  return declaration?.type === "TSInterfaceDeclaration" || declaration?.type === "TSTypeAliasDeclaration";
+}
+var rule2 = {
+  meta: {
+    type: "problem",
+    docs: { description: 'Disallow logic in .astro frontmatter and script blocks: only imports, props and markup, with client code loaded by a side-effect import such as import "../client.ts"' }
+  },
+  create(context) {
+    if (!context.filename.endsWith(".astro"))
+      return {};
+    const bound = new Set;
+    return {
+      Program(node) {
+        for (const statement of node.body) {
+          if (statement.type === "ImportDeclaration" || statement.type === "EmptyStatement" || statement.type === "ExportNamedDeclaration" && statement.source !== null || isTypeDeclaration(statement)) {
+            continue;
+          }
+          if (statement.type === "VariableDeclaration" && statement.declarations.length > 0 && statement.declarations.every((declarator) => isPropsRead(declarator, bound))) {
+            for (const declarator of statement.declarations)
+              boundName(declarator.id, bound);
+            continue;
+          }
+          context.report({
+            node: statement,
+            message: 'an .astro frontmatter or script block holds more than imports and props: move this statement into a .ts file and import it, so the .astro file holds only imports, props and markup; a script block loads client code with a side-effect import such as import "../client.ts"'
+          });
+        }
+      }
+    };
+  }
+};
+var thin_astro_default = rule2;
+
 // src/complexity/readability/index.ts
 var plugin = {
   meta: { name: "readability" },
   rules: {
-    "cognitive-complexity": cognitive_complexity_default
+    "cognitive-complexity": cognitive_complexity_default,
+    "thin-astro": thin_astro_default
   }
 };
 var readability_default = plugin;

package/docs/configs/typescript-rules.md

@@ -43,6 +43,16 @@ The base loads the kit's `data-shape` plugin from `dist/` with one rule for ever
 - Derive such a type from the schema with `typeof Name.Type` instead of writing both.
 - The twin rule runs on production files only, so a test that declares its own schema as an oracle stays green.
 
+## Astro rules
+
+An override in `oxlintrc.json` turns on one rule of the kit's `readability` plugin in each `.astro` file:
+
+- `readability/thin-astro` refuses a statement in the frontmatter or a script block that is neither an import, a re-export from another module, a type or interface declaration, nor a variable read from `Astro.props`.
+- A default inside an `Astro.props` destructuring passes only when it is a literal or a name read from `Astro.props` earlier, so `const { title = "Home" } = Astro.props;` passes and a call or `await` in a default is refused.
+- Move a refused statement into a `.ts` file and import it, so the `.astro` file holds only imports, props and markup.
+- A script block loads client code with a side-effect import, as in `<script>import "../client.ts";</script>`, and the override turns off `import/no-unassigned-import` so that import passes.
+- A dynamic route re-exports `getStaticPaths` from a `.ts` file, as in `export { getStaticPaths } from "../lib/paths.ts";`.
+
 ## Rules outside tests
 
 An override in `oxlintrc.json` turns on these type-aware rules in each `.ts` and `.tsx` file outside `tests/`:

package/docs/design.md

@@ -86,7 +86,7 @@ npm adds `package.json`, `README.md` and `LICENSE` whatever `files` says.
 `bun pm pack` builds the same tarball the registry serves, and the consumer e2e test installs that tarball.
 
 Each oxlint plugin ships compiled under `dist/`, because Node refuses to strip types from a `.ts` file under `node_modules`.
-`@oxlint/plugins` ships no RuleTester, so each `effect-channel`, `readability` and `data-shape` rule is proven red and green against an installed consumer in `tests/e2e/consumer.test.ts`.
+`@oxlint/plugins` ships no RuleTester, so each `effect-channel`, `readability` and `data-shape` rule is proven red and green against an installed consumer in `tests/e2e/consumer.test.ts`, except `readability/thin-astro`, which `tests/e2e/astro-consumer.test.ts` proves against a consumer tree linked to the checkout.
 `dist/` is committed, with the doc templates in `dist/templates/`, and so is `CHANGELOG.md`, which the same build writes.
 No `prepack` or `prepublishOnly` script rebuilds them, so a publish ships the committed files.
 CI runs `git diff --exit-code` over the whole tree after `bun run build`.
@@ -109,7 +109,7 @@ So the three packages move together at one exact version.
 A gate then behaves the same alone or through `checks-lint`, and `lint-coverage.sh` can stay a shell script.
 The gates run one at a time and pass their output straight through, so each report reads whole and in the order of the gate table.
 `checks-lint` picks the gates that apply from the tracked files, and a repository cannot select gates.
-A TypeScript gate runs as soon as the repository tracks TypeScript source.
+A TypeScript gate runs as soon as the repository tracks TypeScript source, and `checks-lint-coverage` and `checks-unused` also run on tracked Astro source.
 
 GitHub authors the pull request merge commit it builds as `GitHub <noreply@github.com>`, and `checks-commit-identity` refuses that author.
 So `checks-lint` ends a pull request's range at the event's head commit, and the merge commit is never in it.

package/docs/gates/checks-docs.md

@@ -61,6 +61,7 @@ A template decides a file's structure, and the template file itself is the refer
   A `Date: YYYY-MM-DD` line follows the title.
   The first word under Status is Proposed, Accepted, Rejected, Deprecated, Superseded or Retired.
   No other record holds its number.
+  A Status that amends, narrows or supersedes another record names it, and the other record names it back.
 - A changelog lists its releases newest first, and each opens with a `Released YYYY-MM-DD.` line.
 - A how-to or tutorial page numbers its steps.
 - `CLAUDE.md` is its template word for word.

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

@@ -4,12 +4,13 @@ audience: consumers
 ---
 # checks-lint-coverage
 
-`checks-lint-coverage` is the gate that fails when oxlint skips a tracked TypeScript file, or when the program `tsconfig.json` builds drops the ts-reset rules, without saying so.
+`checks-lint-coverage` is the gate that fails when oxlint skips a tracked TypeScript or Astro file, or when the program `tsconfig.json` builds drops the ts-reset rules, without saying so.
 
 ## What it checks
 
-It fails when oxlint skips a tracked `.ts` or `.tsx` file, for example through a stray `.gitignore` entry.
+It fails when oxlint skips a tracked `.ts`, `.tsx` or `.astro` file, for example through a stray `.gitignore` entry.
 It compares `git ls-files` against oxlint's own file walk and names the missing files.
+It lists each tracked `.astro` file the same way, since oxlint lints the frontmatter and script blocks of an `.astro` file, where a script block loads client code with a side-effect import such as `import "../client.ts";`.
 
 It fails when the program `tsconfig.json` builds leaves out the `is-array` or the `json-parse` rule of `@total-typescript/ts-reset`, which `tsconfig.effect.json` lists.
 A `tsconfig.json` that does not extend `@avi2dg/checks/tsconfig.effect.json`, or that sets both `files` and `include`, leaves both rules out.
@@ -17,9 +18,9 @@ A `tsconfig.json` that does not extend `@avi2dg/checks/tsconfig.effect.json`, or
 
 ## What it reads
 
-It reads the working tree: the `*.ts` and `*.tsx` files `git ls-files` lists, and the files `oxlint --debug=files` walks.
+It reads the working tree: the `*.ts`, `*.tsx` and `*.astro` files `git ls-files` lists, and the files `oxlint --debug=files` walks.
 It walks without naming a path, since an explicit path bypasses the ignore files whose skips it looks for.
-It reads the program from `tsc --listFilesOnly -p tsconfig.json`, and passes over the program when the root holds no `tsconfig.json`.
+It reads the program from `tsc --listFilesOnly -p tsconfig.json`, and passes over the program when the repository tracks no `.ts` or `.tsx` file or the root holds no `tsconfig.json`.
 oxlint and tsc must be on `PATH`, as they are under a package script.
 
 ## Arguments
@@ -30,14 +31,14 @@ It takes none.
 
 | Code | When |
 | --- | --- |
-| 0 | the repository tracks no `.ts` or `.tsx` file, or oxlint walks each one and the program holds both ts-reset rules or the root holds no `tsconfig.json` |
+| 0 | the repository tracks no `.ts`, `.tsx` or `.astro` file, or oxlint walks each one and the program holds both ts-reset rules, the repository tracks no `.ts` or `.tsx` file or the root holds no `tsconfig.json` |
 | 1 | oxlint skips a tracked file, or the program drops a ts-reset rule |
 | 2 | oxlint cannot walk the tree, or tsc cannot list the program after oxlint walks every tracked file, as when either is not on `PATH` or a config does not parse |
 
 ## Sample output
 
 ```
-lint-coverage: oxlint skips 1/3 tracked .ts/.tsx files; missing:
+lint-coverage: oxlint skips 1/3 tracked .ts/.tsx/.astro files; missing:
 ignored/b.ts
 lint-coverage: the program tsconfig.json builds drops the ts-reset rules: is-array json-parse
   extend @avi2dg/checks/tsconfig.effect.json, and set files or include in tsconfig.json but not both
@@ -46,13 +47,13 @@ lint-coverage: the program tsconfig.json builds drops the ts-reset rules: is-arr
 A passing run counts the files and names the rules:
 
 ```
-lint-coverage: 71/71 tracked .ts/.tsx files
+lint-coverage: 71/71 tracked .ts/.tsx/.astro files
 lint-coverage: the program tsconfig.json builds holds the ts-reset rules is-array and json-parse
 ```
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `.ts` or `.tsx` file.
+`checks-lint` runs it when the repository tracks a `.ts`, `.tsx` or `.astro` file.
 
 ## Related topics
 

package/docs/gates/checks-lint.md

@@ -10,6 +10,7 @@ audience: consumers
 
 It runs the gates under [What runs](../../README.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`.
 All other gates run for every repository.
 
@@ -53,7 +54,7 @@ checks-lint: 1 of 12 gate(s) failed: checks-comment-gate
 ## When it runs
 
 A repository runs it from `bun run lint` in a pull request workflow that fetches the whole git history.
-It leaves out the TypeScript gates while the repository tracks no TypeScript file.
+It leaves out the TypeScript gates while the repository tracks no TypeScript file, except that `checks-lint-coverage` and `checks-unused` run when it tracks an `.astro` file.
 
 ## Related topics
 

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

@@ -69,12 +69,18 @@ mutation-compare: REGRESSION (1 mutant(s))
 
 Only a CI step the repository writes runs it.
 A repository runs it with `--advisory` for its first month, then drops the flag so it blocks.
+A full sweep runs in CI and never on a laptop.
+Start a baseline with `gh workflow run mutation` and keep its report as an artifact.
+The shared preset refuses a full `stryker run` outside CI and names that workflow command instead, as [checks-mutation](checks-mutation.md) says.
 
 ## Running it in CI
 
-It runs on pull requests, 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:
 
 ```yaml
+name: mutation-compare
+on:
+  pull_request:
 jobs:
   mutation-compare:
     runs-on: ubuntu-latest
@@ -86,12 +92,25 @@ jobs:
       - run: bun install --frozen-lockfile
       - run: bunx stryker run
       - run: |
-          base="$(git merge-base HEAD origin/main)"
-          git worktree add /tmp/mutation-base "$base"
-          (cd /tmp/mutation-base && bun install --frozen-lockfile && bunx stryker run)
-      - run: bun run checks-mutation-compare --advisory /tmp/mutation-base/reports/mutation/mutation.json reports/mutation/mutation.json
+          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
+      - 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 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: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}` instead.
+With `CI_RUNS_ON` unset, the job then runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a private repository sends its full sweeps.
+
 ## Related topics
 
+- [checks-mutation](checks-mutation.md)
 - [checks-test-layout](checks-test-layout.md)

package/docs/gates/checks-mutation.md

@@ -0,0 +1,98 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-mutation
+
+`checks-mutation` runs Stryker and refuses a full run outside CI.
+
+## What it checks
+
+It refuses a full mutation run when `CI` is not `true`.
+A full run is one with no `--mutate <glob>` and no `--incremental` flag.
+A `--mutate` without a glob, `--incrementalFile` alone or `--incremental` with `--force` is still a full run.
+Its refusal names `gh workflow run mutation` as the command that starts the same run in CI.
+A run scoped with `--mutate <glob>`, `--mutate=<glob>` or `-m <glob>` stays allowed locally, because pull request comparisons scope to named files.
+An incremental run stays allowed locally only when its incremental report exists, because it reuses the results of mutants that did not change.
+That report is the `incrementalFile` Stryker resolves from the command line and the config file, else `reports/stryker-incremental.json`.
+With no report there, the refusal says to pass `--mutate <glob>`, or to start the full baseline in CI with `gh workflow run mutation`.
+`--help`, `-h` and `--version` are not runs, so they pass straight through to Stryker.
+A laptop with `CI=true` set opts in to a full run on purpose, and the refusal lets it through.
+
+The shared Stryker preset makes the same decision from `process.argv` when a `stryker run` loads it.
+So a bare `bunx stryker run` in a repository whose `stryker.conf.mjs` spreads the preset is refused the same way, and `checks-mutation` is a thin wrapper over that decision.
+The preset also registers an ignore plugin that checks the incremental report once Stryker has resolved its options, because a config file can set `incrementalFile` after the preset loads.
+A config that replaces `plugins` or `ignorers` must keep the preset's entries, or that check does not run.
+
+## What it reads
+
+It reads `CI` from the environment.
+It forwards every argument to `stryker run` through `bun x stryker run`.
+
+## Arguments
+
+```sh
+checks-mutation [--mutate <glob>] [--incremental] [<stryker args>...]
+```
+
+Every argument after the bin name forwards to `stryker run`.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | Stryker exited 0 |
+| 1 | Stryker exited nonzero, including an incremental run refused for a missing report |
+| 2 | a full run outside CI was refused, or Stryker could not start |
+
+## Sample output
+
+A full run outside CI prints its refusal and exits 2:
+
+```
+checks-mutation: refusing a full mutation run outside CI; start the same run in CI with `gh workflow run mutation`, or scope this run with `--mutate <glob>` or `--incremental`
+```
+
+A bare `bunx stryker run` fails to load its config with the same refusal as the error and exits 1.
+An `--incremental` run with no report stops before instrumenting with the missing-report refusal as the error and exits 1.
+
+## When it runs
+
+A repository runs full baselines from the mutation workflow on `workflow_dispatch`.
+Run scoped checks locally during development.
+A scheduled run never starts one, because a baseline costs a full Stryker run.
+
+## Running it in CI
+
+A repository starts a baseline by hand from a workflow named `mutation` and keeps its report as an artifact:
+
+```yaml
+name: mutation
+on:
+  workflow_dispatch:
+jobs:
+  mutation:
+    runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - run: bunx stryker run
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: mutation-report
+          path: reports/mutation/mutation.json
+```
+
+With `CI_RUNS_ON` unset, the job runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a private repository sends its full sweeps.
+A repository sets `CI_RUNS_ON` only to name a different runner.
+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.
+
+## Related topics
+
+- [checks-mutation-compare](checks-mutation-compare.md)
+- [checks-subsumed-tests](checks-subsumed-tests.md)

package/docs/gates/checks-subsumed-tests.md

@@ -30,6 +30,8 @@ Build a bail-off report with this command:
 bunx stryker run --disableBail
 ```
 
+It is a full sweep, so outside CI the shared preset refuses it unless `--mutate <glob>` scopes it, as [checks-mutation](checks-mutation.md) says.
+
 The report records each killer as a test index, so it names each test by its file and its name from the report's `testFiles` table.
 
 ## Arguments

package/docs/gates/checks-unused.md

@@ -4,14 +4,14 @@ audience: consumers
 ---
 # checks-unused
 
-`checks-unused` is the gate that refuses a TypeScript file no entry point reaches.
+`checks-unused` is the gate that refuses a TypeScript or Astro file no entry point reaches.
 
 ## What it checks
 
-It runs Knip with the repository's own configuration and names each `.ts` or `.tsx` file no entry reaches.
+It runs Knip with the repository's own configuration and names each `.ts`, `.tsx` or `.astro` file no entry reaches.
 It reads only the files issue type, so an unused export or dependency never fails it.
 It asks Knip for that issue type itself, so a configuration that narrows `include`, excludes files or turns the files rule off still has its files judged.
-It fails when the repository tracks no TypeScript source, since an empty scan would pass without judging anything.
+It fails when the repository tracks no `.ts`, `.tsx` or `.astro` file, since an empty scan would pass without judging anything.
 It fails when the repository holds no Knip configuration, since Knip's default entries cannot tell a dead file from an entry point.
 
 ## What it reads
@@ -27,6 +27,7 @@ export default { ...base, entry: ["src/index.ts", "tests/**/*.test.ts"] };
 ```
 
 The base in `knip-base.json` reports only unreferenced files.
+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.
 
 ## Arguments
@@ -39,7 +40,7 @@ It takes none.
 | --- | --- |
 | 0 | no tracked file is unreferenced |
 | 1 | a tracked file is unreferenced or the repository holds no Knip configuration |
-| 2 | the repository tracks no TypeScript source, Knip cannot run, or its configuration does not parse |
+| 2 | the repository tracks no TypeScript or Astro source, Knip cannot run, or its configuration does not parse |
 
 ## Sample output
 
@@ -51,12 +52,12 @@ unused: 1 unreferenced file(s):
 A passing run counts the files it judged:
 
 ```
-unused: no unreferenced files among 110 tracked .ts/.tsx file(s)
+unused: no unreferenced files among 110 tracked .ts/.tsx/.astro file(s)
 ```
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `.ts` or `.tsx` file.
+`checks-lint` runs it when the repository tracks a `.ts`, `.tsx` or `.astro` file.
 Such a repository names its entries in a Knip configuration.
 
 ## Related topics

package/oxlintrc.json

@@ -37,6 +37,13 @@
         "typescript/no-unsafe-return": "error",
         "typescript/no-unsafe-call": "error"
       }
+    },
+    {
+      "files": ["**/*.astro"],
+      "rules": {
+        "readability/thin-astro": "error",
+        "import/no-unassigned-import": "off"
+      }
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,9 @@
     "src/testing/test-report.ts",
     "src/testing/flake.ts",
     "src/delivery/commit-identity.ts",
+    "src/testing/mutation.ts",
+    "src/testing/mutation-scope.js",
+    "src/testing/mutation-guard-plugin.js",
     "src/testing/mutation-compare.ts",
     "src/testing/subsumed-tests.ts",
     "src/delivery/ci-wiring.ts",
@@ -95,6 +98,7 @@
     "checks-test": "src/testing/test.ts",
     "checks-flake": "src/testing/flake.ts",
     "checks-commit-identity": "src/delivery/commit-identity.ts",
+    "checks-mutation": "src/testing/mutation.ts",
     "checks-mutation-compare": "src/testing/mutation-compare.ts",
     "checks-subsumed-tests": "src/testing/subsumed-tests.ts",
     "checks-ci-wiring": "src/delivery/ci-wiring.ts",
@@ -113,7 +117,9 @@
     "build": "bun build src/quality/effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build src/complexity/readability/index.ts --outdir dist/readability --target node --format esm && bun build src/quality/data-shape/index.ts --outdir dist/data-shape --target node --format esm && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
     "lint": "oxlint --type-aware && bun src/core/lint.ts && depcruise --config .dependency-cruiser.cjs .",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
-    "test": "bun src/testing/test.ts"
+    "test": "bun src/testing/test.ts",
+    "mutate": "bunx stryker run",
+    "mutate:incremental": "bunx stryker run --incremental"
   },
   "peerDependencies": {
     "@swc/core": "1.16.2",
@@ -127,7 +133,9 @@
   },
   "devDependencies": {
     "@effect/tsgo": "0.45.0",
+    "@hughescr/stryker-bun-runner": "1.4.0",
     "@oxlint/plugins": "1.83.0",
+    "@stryker-mutator/core": "10.0.0",
     "@swc/core": "1.16.2",
     "@types/bun": "^1.3.0",
     "dependency-cruiser": "18.4.0",
@@ -144,5 +152,9 @@
     "@effect/platform-node-shared": "4.0.0-rc.115",
     "@total-typescript/ts-reset": "0.6.1",
     "knip": "6.38.0"
+  },
+  "overrides": {
+    "qs": "6.16.0",
+    "smol-toml": "1.9.0"
   }
 }

package/src/complexity/exports.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { TYPESCRIPT_SOURCE } from "../core/gates.ts";
 import { checkoutFiles, commitOf, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { knipReport, scanTree } from "./knip.ts";
@@ -127,7 +128,7 @@ export function report(head: Baseline, { unlisted, added, stale }: Drift): strin
     : `${NAME}: ${head.length} unused export(s) in ${BASELINE_FILE}, and no new ones`;
 }
 
-const scan = scanTree(NAME, INCLUDED).pipe(Effect.mapError((cause) => new ExportsError({ message: cause.message })));
+const scan = scanTree(NAME, INCLUDED, TYPESCRIPT_SOURCE).pipe(Effect.mapError((cause) => new ExportsError({ message: cause.message })));
 
 // Knip loads the configuration's imports, such as the kit's knip-base.json, from a node_modules the checkout lacks.
 const unusedAt = Effect.fn("unusedAt")(

package/src/complexity/knip.ts

@@ -1,4 +1,5 @@
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import type { TrackedContent } from "../core/gates.ts";
 import { collect, git } from "../core/git.ts";
 
 class KnipError extends Schema.TaggedError<KnipError>()("KnipError", {
@@ -16,8 +17,6 @@ const CONFIGS = [
   "knip.config.ts",
 ] as const;
 
-const TYPESCRIPT = ["*.ts", "*.tsx"];
-
 const hasKnipConfig = Effect.fn("hasKnipConfig")(function* (root: string) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
@@ -55,13 +54,13 @@ export const knipReport = Effect.fn("knipReport")(function* (root: string, args:
   return { kind: "reported", stdout: run.stdout } as const;
 });
 
-export const scanTree = Effect.fn("scanTree")(function* (name: string, args: readonly string[]) {
+export const scanTree = Effect.fn("scanTree")(function* (name: string, args: readonly string[], source: TrackedContent) {
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const tracked = (yield* git(["ls-files", "--", ...TYPESCRIPT], root))
+  const tracked = (yield* git(["ls-files", "--", ...source.pathspecs], root))
     .split("\n")
     .map((line) => line.trim())
     .filter((line) => line !== "");
-  if (tracked.length === 0) return yield* new KnipError({ message: "no tracked .ts or .tsx files to scan" });
+  if (tracked.length === 0) return yield* new KnipError({ message: `no tracked ${source.content} to scan` });
   const reported = yield* knipReport(root, args);
   if (reported.kind === "unconfigured") {
     yield* Console.log(`${name}: no knip configuration names entry files, so add one extending the kit's knip-base.json`);

package/src/complexity/unused.ts

@@ -1,12 +1,13 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
+import { LINTED_SOURCE } from "../core/gates.ts";
 import { runMain } from "../core/main.ts";
 import { scanTree } from "./knip.ts";
 
 export type Scan = { readonly tracked: number; readonly files: readonly string[] };
 
 const NAME = "unused";
-const JUDGED = /\.tsx?$/;
+const JUDGED = /[.]tsx?$|[.]astro$/;
 
 class UnusedError extends Schema.TaggedError<UnusedError>()("UnusedError", {
   message: Schema.String,
@@ -31,12 +32,12 @@ export const filesOf = Effect.fn("filesOf")(function* (stdout: string) {
 });
 
 export function report({ tracked, files }: Scan): string {
-  if (files.length === 0) return `${NAME}: no unreferenced files among ${tracked} tracked .ts/.tsx file(s)`;
+  if (files.length === 0) return `${NAME}: no unreferenced files among ${tracked} tracked .ts/.tsx/.astro file(s)`;
   return [`${NAME}: ${files.length} unreferenced file(s):`, ...files.map((file) => `  ${file}`)].join("\n");
 }
 
 const unused = Effect.gen(function* () {
-  const { tracked, reported } = yield* scanTree(NAME, ["--files"]).pipe(
+  const { tracked, reported } = yield* scanTree(NAME, ["--files"], LINTED_SOURCE).pipe(
     Effect.mapError((cause) => new UnusedError({ message: cause.message })),
   );
   if (reported.kind === "unconfigured") return false;

package/src/core/gates.ts

@@ -3,7 +3,7 @@ export type Program = {
   readonly script: string;
 };
 
-type TrackedContent = {
+export type TrackedContent = {
   readonly pathspecs: readonly string[];
   readonly content: string;
 };
@@ -30,12 +30,14 @@ export const TEST_ENTRY_POINT: Program = { bin: "checks-test", script: "testing/
 
 export const DEFAULT_BRANCH = "main";
 
-const TYPESCRIPT_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
+export const TYPESCRIPT_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
+
+export const LINTED_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx", "*.astro"], content: "TypeScript or Astro source" };
 
 const BUN_LOCKFILE: TrackedContent = { pathspecs: ["bun.lock"], content: "a bun lockfile" };
 
 export const KIT_GATES = [
-  { bin: "checks-lint-coverage", vector: "quality", file: "lint-coverage.sh", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-lint-coverage", vector: "quality", file: "lint-coverage.sh", reads: "tree", appliesTo: LINTED_SOURCE },
   { bin: "checks-test-layout", vector: "testing", file: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-commit-identity", vector: "delivery", file: "commit-identity.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
@@ -43,7 +45,7 @@ export const KIT_GATES = [
   { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", alsoReads: "every agent file at the head commit", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-repetition", vector: "complexity", file: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
-  { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: LINTED_SOURCE },
   { bin: "checks-exports", vector: "complexity", file: "exports.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-quarantine-clock", vector: "testing", file: "quarantine-clock.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-advisories", vector: "dependencies", file: "advisories.ts", reads: "range", appliesTo: BUN_LOCKFILE },

package/src/delivery/commit-identity.ts

@@ -152,4 +152,4 @@ const check = Effect.gen(function* () {
   return true;
 });
 
-runMain("commit-identity", check);
+if (import.meta.main) runMain("commit-identity", check);

package/src/docs/doc-rules.ts

@@ -8,6 +8,7 @@ import {
   ruleProblem,
   type Heading,
   type Outline,
+  type Section,
   type Violation,
   VERSION,
 } from "./doc-outline.ts";
@@ -93,8 +94,76 @@ function recordNumber(path: string): number | undefined {
   return name === undefined ? undefined : Number(name);
 }
 
+const REVISION_CLAUSE = /\b(?:amend(?:s|ed)|narrow(?:s|ed)|supersede[sd])\b(?:[^.]|\.(?=\S))*/gi;
+const RECORD_REFERENCE = /\b(\d{4})\b/g;
+
+function numbersIn(text: string): ReadonlySet<number> {
+  return new Set(Array.from(text.matchAll(RECORD_REFERENCE), (match) => Number(match[1])));
+}
+
+function revisedIn(status: string): ReadonlySet<number> {
+  return new Set((status.match(REVISION_CLAUSE) ?? []).flatMap((clause) => [...numbersIn(clause)]));
+}
+
+function padded(number: number): string {
+  return String(number).padStart(4, "0");
+}
+
+function outlineOf(text: string): Outline {
+  return parseOutline(text.slice(frontMatterOf(text).text.length));
+}
+
+function statusSection(outline: Outline): Section | undefined {
+  return outline.sections.find(({ heading }) => heading.title === "Status");
+}
+
+type StatusLinks = {
+  readonly cited: ReadonlySet<number>;
+  readonly revised: ReadonlySet<number>;
+};
+
+function statusLinks(section: Section): StatusLinks {
+  const text = section.body.map(({ text: body }) => body).join("\n");
+  return { cited: numbersIn(text), revised: revisedIn(text) };
+}
+
+export type Records = {
+  readonly paths: readonly string[];
+  readonly links: ReadonlyMap<number, StatusLinks>;
+};
+
+export function recordsOf(records: readonly Doc[]): Records {
+  const links = new Map<number, StatusLinks>();
+  for (const { path, text } of records) {
+    const number = recordNumber(path);
+    const section = number === undefined || links.has(number) ? undefined : statusSection(outlineOf(text));
+    if (number !== undefined && section !== undefined) links.set(number, statusLinks(section));
+  }
+  return { paths: records.map(({ path }) => path), links };
+}
+
+function pairProblems(filed: number, own: Section, mine: StatusLinks, number: number, other: StatusLinks): readonly Violation[] {
+  if (number === filed) return [];
+  if (mine.revised.has(number) && !other.cited.has(filed)) {
+    const line = own.body.find(({ text: body }) => body.includes(padded(number)))?.line ?? own.heading.line;
+    return [{ line, message: `\`## Status\` names ${padded(number)} without ${padded(number)} naming ${padded(filed)} back` }];
+  }
+  if (other.revised.has(filed) && !mine.cited.has(number)) {
+    return [{ line: own.heading.line, message: `\`## Status\` is named by ${padded(number)} without naming ${padded(number)} back` }];
+  }
+  return [];
+}
+
+function revisionLinkProblems(path: string, outline: Outline, links: ReadonlyMap<number, StatusLinks>): readonly Violation[] {
+  const filed = recordNumber(path);
+  const own = filed === undefined ? undefined : statusSection(outline);
+  if (filed === undefined || own === undefined) return [];
+  const mine = statusLinks(own);
+  return [...links].flatMap(([number, other]) => pairProblems(filed, own, mine, number, other));
+}
+
 function statusProblem(outline: Outline): Violation | undefined {
-  const status = outline.sections.find(({ heading }) => heading.title === "Status");
+  const status = statusSection(outline);
   if (status === undefined) return undefined;
   const opening = firstText(status.body);
   const word = opening?.text.trim().split(/\s+/, 1)[0]?.replace(/[.,;:]+$/, "");
@@ -126,7 +195,7 @@ function sharedNumberProblem(path: string, filed: number | undefined, records: r
   return sharing.length === 0 ? undefined : { line: 1, message: `shares number ${filed} with ${sharing.join(", ")}` };
 }
 
-function adrProblems(path: string, outline: Outline, records: readonly string[]): readonly Violation[] {
+function adrProblems(path: string, outline: Outline, records: Records): readonly Violation[] {
   const filed = recordNumber(path);
   const misnamed: Violation | undefined =
     filed === undefined
@@ -137,7 +206,8 @@ function adrProblems(path: string, outline: Outline, records: readonly string[])
     recordTitleProblem(outline, filed),
     recordDateProblem(outline),
     statusProblem(outline),
-    sharedNumberProblem(path, filed, records),
+    sharedNumberProblem(path, filed, records.paths),
+    ...revisionLinkProblems(path, outline, records.links),
   ].filter((violation) => violation !== undefined);
 }
 
@@ -167,7 +237,7 @@ function stepsProblems(kind: Kind, { prose }: Outline): readonly Violation[] {
   return [{ line: 1, message: `numbers no steps, which a ${kind} page lists as \`1.\` items` }];
 }
 
-function kindProblems(kind: Kind, doc: Doc, outline: Outline, records: readonly string[]): readonly Violation[] {
+function kindProblems(kind: Kind, doc: Doc, outline: Outline, records: Records): readonly Violation[] {
   if (kind === "adr") return adrProblems(doc.path, outline, records);
   if (kind === "changelog") return changelogProblems(outline);
   if (kind === "how-to" || kind === "tutorial") return stepsProblems(kind, outline);
@@ -182,7 +252,7 @@ function exactProblems(kind: Kind, expected: string, actual: string): readonly V
   return [{ line, message: `differs from ${templateFile(kind)}, which it holds word for word` }];
 }
 
-export function judge(kind: Kind, doc: Doc, records: readonly string[]): readonly Violation[] {
+export function judge(kind: Kind, doc: Doc, records: Records): readonly Violation[] {
   const template = TEMPLATES[kind];
   if (template.shape === "exact") return exactProblems(kind, template.text, doc.text);
   const frontMatter = frontMatterOf(doc.text).text;

package/src/docs/docs.ts

@@ -2,7 +2,7 @@
 import { Console, Effect } from "effect";
 import { ceilingFinding, entryFindings, isAgentFile, maintainingFinding } from "./doc-agents.ts";
 import { rootsOf, snapshotOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
-import { ADR_DIRECTORY, judge, placementOf, placementProblem, speaksToConsumers, type Placement } from "./doc-rules.ts";
+import { ADR_DIRECTORY, judge, placementOf, placementProblem, recordsOf, speaksToConsumers, type Placement, type Records } from "./doc-rules.ts";
 import { vanishedNames } from "./doc-names.ts";
 import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
 import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
@@ -40,7 +40,7 @@ const NAME = "docs";
 const USAGE = "usage: docs.ts <ref> | <base-ref> <head-ref>";
 const MARKDOWN = [":(glob)**/*.md"];
 
-function templateFindings(path: string, text: string, placement: Placement, records: readonly string[]): readonly Finding[] {
+function templateFindings(path: string, text: string, placement: Placement, records: Records): readonly Finding[] {
   const misplaced = placementProblem(placement);
   if (misplaced !== undefined) return [{ path, line: undefined, message: misplaced }];
   if (placement.type !== "judged") return [];
@@ -91,13 +91,13 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const renamedFrom = new Map(changes.flatMap((change) => (change.kind === "renamed" ? [[change.path, change.from] as const] : [])));
   const changed = yield* changedLines(base, head, MARKDOWN, root);
   const present = yield* pathsAt(head, MARKDOWN, root);
-  const records = present.filter((path) => path.startsWith(ADR_DIRECTORY));
   const proseDocs = present.flatMap((path) => {
     const reader = readerOf(path);
     return reader === undefined ? [] : [{ path, reader }];
   });
   const texts = yield* readTexts(root, head, [...new Set([...present.filter((path) => path.endsWith(".md")), ...proseDocs.map(({ path }) => path)])]);
   const text = (path: string): string => texts.get(path) ?? "";
+  const records = recordsOf(present.filter((path) => path.startsWith(ADR_DIRECTORY)).map((path) => ({ path, text: text(path) })));
   const judged = present.map((path) => ({ path, placement: placementOf(path, text(path)) })).filter(({ placement }) => placement.type !== "unjudged");
 
   const templated = judged.flatMap(({ path, placement }) => templateFindings(path, text(path), placement, records));

package/src/quality/lint-coverage.sh

@@ -1,14 +1,14 @@
 #!/bin/sh
-# lint-coverage: fail when oxlint silently skips a tracked TypeScript source,
+# lint-coverage: fail when oxlint silently skips a tracked TypeScript or Astro source,
 # or when tsconfig.json's program silently drops the ts-reset rules.
 set -eu
 
 tmp="$(mktemp -d)"
 trap 'rm -rf "$tmp"' EXIT INT TERM
 
-git ls-files -- '*.ts' '*.tsx' | LC_ALL=C sort > "$tmp/expected"
+git ls-files -- '*.ts' '*.tsx' '*.astro' | LC_ALL=C sort > "$tmp/expected"
 if ! [ -s "$tmp/expected" ]; then
-  echo "lint-coverage: no tracked .ts/.tsx files"
+  echo "lint-coverage: no tracked .ts/.tsx/.astro files"
   exit 0
 fi
 
@@ -18,7 +18,7 @@ if ! oxlint --debug=files > "$tmp/walk" 2> "$tmp/walk-error"; then
   cat "$tmp/walk" "$tmp/walk-error"
   exit 2
 fi
-grep -E '\.tsx?$' "$tmp/walk" | LC_ALL=C sort > "$tmp/walked" || true
+grep -E '[.]tsx?$|[.]astro$' "$tmp/walk" | LC_ALL=C sort > "$tmp/walked" || true
 
 expected_count="$(wc -l < "$tmp/expected" | tr -d ' ')"
 walked_count="$(grep -c . "$tmp/walked" || true)"
@@ -27,11 +27,16 @@ status=0
 comm -23 "$tmp/expected" "$tmp/walked" > "$tmp/missing"
 if [ -s "$tmp/missing" ]; then
   missing_count="$(wc -l < "$tmp/missing" | tr -d ' ')"
-  echo "lint-coverage: oxlint skips ${missing_count}/${expected_count} tracked .ts/.tsx files; missing:"
+  echo "lint-coverage: oxlint skips ${missing_count}/${expected_count} tracked .ts/.tsx/.astro files; missing:"
   cat "$tmp/missing"
   status=1
 else
-  echo "lint-coverage: ${walked_count}/${expected_count} tracked .ts/.tsx files"
+  echo "lint-coverage: ${walked_count}/${expected_count} tracked .ts/.tsx/.astro files"
+fi
+
+if ! grep -qE '[.]tsx?$' "$tmp/expected"; then
+  echo "lint-coverage: no tracked .ts/.tsx files, so no program to hold the ts-reset rules"
+  exit "$status"
 fi
 
 if ! [ -f tsconfig.json ]; then

package/src/testing/mutation-guard-plugin.js

@@ -0,0 +1,13 @@
+import { missingReportRefusal } from "./mutation-scope.js";
+
+export const GUARD_IGNORER = "checks-incremental-report-guard";
+
+// An ignorer is built before instrumentation from the resolved options, so a throw here stops the run before any mutant.
+function incrementalReportGuard(options) {
+  const refusal = missingReportRefusal(process.argv.slice(3), process.env.CI ?? "", options.incrementalFile);
+  if (refusal !== undefined) throw new Error(refusal);
+  return { shouldIgnore: () => undefined };
+}
+incrementalReportGuard.inject = ["options"];
+
+export const strykerPlugins = [{ kind: "Ignore", name: GUARD_IGNORER, factory: incrementalReportGuard }];

package/src/testing/mutation-scope.js

@@ -0,0 +1,27 @@
+import { existsSync } from "node:fs";
+
+const NON_RUNS = ["--help", "-h", "--version"];
+const MUTATE_FLAGS = ["--mutate", "-m"];
+
+function namesGlob(args) {
+  return args.some(
+    (arg, index) =>
+      (MUTATE_FLAGS.includes(arg) && (args[index + 1] ?? "") !== "") ||
+      (arg.startsWith("--mutate=") && arg !== "--mutate="),
+  );
+}
+
+function allowedAnyway(args, ci) {
+  return ci === "true" || args.some((arg) => NON_RUNS.includes(arg)) || namesGlob(args);
+}
+
+export function fullRunRefusal(args, ci) {
+  if (allowedAnyway(args, ci) || (args.includes("--incremental") && !args.includes("--force"))) return undefined;
+  return "refusing a full mutation run outside CI; start the same run in CI with `gh workflow run mutation`, or scope this run with `--mutate <glob>` or `--incremental`";
+}
+
+// Only the resolved options know the incrementalFile a consumer config sets, so this runs after config load.
+export function missingReportRefusal(args, ci, incrementalFile, reportExists = existsSync) {
+  if (allowedAnyway(args, ci) || reportExists(incrementalFile)) return undefined;
+  return `refusing a full mutation run outside CI: \`--incremental\` finds no report at ${incrementalFile} to reuse; scope this run with \`--mutate <glob>\`, or start the full baseline in CI with \`gh workflow run mutation\``;
+}

package/src/testing/mutation.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+import { Config, Effect, Schema } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { runMain } from "../core/main.ts";
+import { fullRunRefusal } from "./mutation-scope.js";
+
+export class MutationError extends Schema.TaggedError<MutationError>()("MutationError", {
+  message: Schema.String,
+}) {}
+
+const readCi = Config.String("CI").pipe(
+  Config.withDefault(""),
+  Effect.mapError((cause) => new MutationError({ message: `cannot read CI: ${cause.message}` })),
+);
+
+const runStryker = Effect.fn("runStryker")(function* (args: readonly string[]) {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const exitCode = yield* spawner.exitCode(
+    ChildProcess.make(process.execPath, ["x", "stryker", "run", ...args], {
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+    }),
+  );
+  return exitCode === ChildProcessSpawner.ExitCode(0);
+});
+
+const mutation = Effect.gen(function* () {
+  const args = process.argv.slice(2);
+  const refusal = fullRunRefusal(args, yield* readCi);
+  if (refusal !== undefined) return yield* new MutationError({ message: refusal });
+  return yield* runStryker(args);
+});
+
+if (import.meta.main) runMain("checks-mutation", mutation);

package/stryker.preset.js

@@ -1,6 +1,19 @@
+import { fileURLToPath } from "node:url";
+import { GUARD_IGNORER } from "./src/testing/mutation-guard-plugin.js";
+import { fullRunRefusal } from "./src/testing/mutation-scope.js";
+
+const [, , command, ...args] = process.argv;
+const refusal = command === "run" ? fullRunRefusal(args, process.env.CI ?? "") : undefined;
+if (refusal !== undefined) throw new Error(refusal);
+
 export default {
   packageManager: "npm",
-  plugins: ["@stryker-mutator/*", "@hughescr/stryker-bun-runner"],
+  plugins: [
+    "@stryker-mutator/*",
+    "@hughescr/stryker-bun-runner",
+    fileURLToPath(new URL("./src/testing/mutation-guard-plugin.js", import.meta.url)),
+  ],
+  ignorers: [GUARD_IGNORER],
   testRunner: "bun",
   bun: { timeout: 60000 },
   inPlace: true,