@avi2dg/checks 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 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

@@ -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/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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.29.0",
+  "version": "0.30.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",

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/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,