@avi2dg/checks 0.50.1 → 0.52.0

package/src/delivery/runner-policy.ts

@@ -0,0 +1,385 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { runsMutation, within, type Run } from "./mutation-job.ts";
+import { isRecord, names, workflowJobs, workflowTitle, type Workflow } from "./workflow-references.ts";
+
+export type RunnerConfig = {
+  readonly mutation: readonly string[] | undefined;
+  readonly selfHosted: readonly (readonly string[])[];
+};
+
+export type RunnerPolicy = {
+  readonly visibility: "private" | "public" | "unknown";
+  readonly runners: RunnerConfig;
+  readonly scripts: ReadonlyMap<string, string>;
+  readonly files?: ReadonlyMap<string, string>;
+};
+
+export type RunnerFault = {
+  readonly location: string;
+  readonly fault: string;
+};
+
+export class RunnerPolicyError extends Schema.TaggedError<RunnerPolicyError>()("RunnerPolicyError", {
+  message: Schema.String,
+}) {}
+
+const Runners = Schema.Struct({
+  mutationRunner: Schema.optional(Schema.NonEmptyArray(Schema.NonEmptyString)),
+  selfHostedRunners: Schema.optional(Schema.Array(Schema.NonEmptyArray(Schema.NonEmptyString))),
+});
+const Manifest = Schema.Struct({
+  checks: Schema.optional(Runners),
+});
+// GitHub expressions match context and property names without regard to case.
+const OVERRIDE_ACCESS = String.raw`vars\s*(?:\.\s*CI_RUNS_ON\b|\[\s*'CI_RUNS_ON'\s*\])`;
+const RUNNER_OVERRIDE = new RegExp(String.raw`\b${OVERRIDE_ACCESS}`, "i");
+const HOSTED_OVERRIDE = new RegExp(String.raw`^\$\{\{\s*${OVERRIDE_ACCESS}\s*\|\|\s*'ubuntu-latest'\s*\}\}$`, "i");
+const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
+
+function sameLabels(runsOn: unknown, labels: readonly string[]): boolean {
+  const named = Array.isArray(runsOn) ? names(runsOn) : undefined;
+  return named?.length === labels.length && labels.every((label) => named.includes(label));
+}
+
+function readsOverride(runsOn: unknown): boolean {
+  if (typeof runsOn === "string") return RUNNER_OVERRIDE.test(runsOn);
+  const values = isRecord(runsOn) ? Object.values(runsOn) : Array.isArray(runsOn) ? runsOn : [];
+  return values.some(readsOverride);
+}
+
+function forkReachable(workflow: Workflow): boolean {
+  const on = isRecord(workflow.document) ? workflow.document["on"] : undefined;
+  const events = isRecord(on) ? Object.keys(on) : (names(on) ?? []);
+  return events.some((event) => {
+    const name = event.toLowerCase();
+    return name === "pull_request" || name === "pull_request_target" || name === "pull_request_review" || name === "pull_request_review_comment" || name === "issue_comment";
+  });
+}
+
+// An exact match would let a differently cased label slip past the refusal.
+function namesSelfHosted(runsOn: unknown): boolean {
+  if (typeof runsOn === "string") return runsOn.trim().toLowerCase() === "self-hosted";
+  if (Array.isArray(runsOn)) return runsOn.some((label) => typeof label === "string" && label.toLowerCase() === "self-hosted");
+  if (isRecord(runsOn)) {
+    const labels = runsOn["labels"];
+    return Array.isArray(labels) && labels.some((label) => typeof label === "string" && label.toLowerCase() === "self-hosted");
+  }
+  return false;
+}
+
+function mutationFault(runsOn: unknown, labels: readonly string[] | undefined, visibility: RunnerPolicy["visibility"], reachable: boolean): string | undefined {
+  const pin = labels === undefined ? undefined : `[${labels.join(", ")}]`;
+  if (readsOverride(runsOn)) {
+    if (visibility === "public" && reachable) {
+      return "a mutation job reads CI_RUNS_ON, so an override moves its mutation runs; set runs-on: ubuntu-latest";
+    }
+    return pin === undefined
+      ? "a mutation job reads CI_RUNS_ON, so an override moves its mutation runs; declare the mutation runner labels in package.json checks.mutationRunner"
+      : `a mutation job reads CI_RUNS_ON, so an override moves its mutation runs off ${pin}; set runs-on: ${pin}`;
+  }
+  if (visibility !== "private") return undefined;
+  if (labels === undefined) {
+    return "a mutation job in a private repository names no checks.mutationRunner in package.json; declare the mutation runner labels there";
+  }
+  return sameLabels(runsOn, labels) ? undefined : `a mutation job in a private repository runs off ${pin}; set runs-on: ${pin}`;
+}
+
+function otherFault(runsOn: unknown, runners: RunnerConfig, visibility: RunnerPolicy["visibility"]): string | undefined {
+  const hosted = typeof runsOn === "string" && HOSTED_OVERRIDE.test(runsOn.trim());
+  if (hosted || runners.selfHosted.some((allowed) => sameLabels(runsOn, allowed))) return undefined;
+  if (visibility !== "private" && !readsOverride(runsOn)) return undefined;
+  return `the job is not on a hosted runner CI_RUNS_ON can override; set runs-on: ${HOSTED_DEFAULT}`;
+}
+
+function declaredLabels(labels: readonly string[], runners: RunnerConfig): boolean {
+  const declared = runners.mutation === undefined ? runners.selfHosted : [runners.mutation, ...runners.selfHosted];
+  const wanted = labels.map((label) => label.toLowerCase());
+  return wanted.length > 0 && declared.some((allowed) => wanted.every((label) => allowed.some((candidate) => candidate.toLowerCase() === label)));
+}
+
+function matrixKey(expression: string): string | undefined {
+  const match = /^\$\{\{\s*matrix\s*\.\s*([\w-]+)\s*\}\}$/i.exec(expression.trim());
+  return match?.[1]?.toLowerCase();
+}
+
+type Scalar = string | number | boolean;
+
+type Combo = Map<string, unknown>;
+
+type Terms = readonly (readonly [string, unknown])[];
+
+function scalarList(value: unknown): readonly Scalar[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const kept = value.filter((entry): entry is Scalar => typeof entry === "string" || typeof entry === "number" || typeof entry === "boolean");
+  return kept.length === value.length ? kept : undefined;
+}
+
+function matrixAxes(matrix: Readonly<Record<string, unknown>>): readonly (readonly [string, readonly Scalar[]])[] | undefined {
+  const axes: (readonly [string, readonly Scalar[]])[] = [];
+  for (const [name, axis] of Object.entries(matrix)) {
+    const lowered = name.toLowerCase();
+    if (lowered === "include" || lowered === "exclude") continue;
+    const values = scalarList(axis);
+    if (values === undefined) return undefined;
+    axes.push([lowered, values]);
+  }
+  return axes;
+}
+
+function expandCombos(axes: readonly (readonly [string, readonly Scalar[]])[]): Combo[] | undefined {
+  let combos: Combo[] = [new Map()];
+  for (const [name, axis] of axes) {
+    const next: Combo[] = [];
+    for (const combo of combos) {
+      for (const value of axis) next.push(new Map(combo).set(name, value));
+    }
+    combos = next;
+    if (combos.length > 512) return undefined;
+  }
+  return combos;
+}
+
+function exclusionBlocks(excluded: unknown): readonly Terms[] | undefined {
+  if (excluded === undefined) return [];
+  if (!Array.isArray(excluded)) return undefined;
+  const blocks: Terms[] = [];
+  for (const candidate of excluded) {
+    if (!isRecord(candidate)) return undefined;
+    const terms: (readonly [string, unknown])[] = [];
+    let usable = true;
+    for (const [name, value] of Object.entries(candidate)) {
+      if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+        usable = false;
+        break;
+      }
+      terms.push([name.toLowerCase(), value]);
+    }
+    if (usable) blocks.push(terms);
+  }
+  return blocks;
+}
+
+function withoutExcluded(combos: readonly Combo[], blocks: readonly Terms[]): Combo[] {
+  return combos.filter((combo) => !blocks.some((terms) => terms.every(([name, value]) => combo.get(name) === value)));
+}
+
+function includeEntries(candidate: Readonly<Record<string, unknown>>): Terms | undefined {
+  const entries: (readonly [string, unknown])[] = [];
+  for (const [name, value] of Object.entries(candidate)) {
+    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") return undefined;
+    entries.push([name.toLowerCase(), value]);
+  }
+  return entries;
+}
+
+function mergeEntries(originals: readonly Combo[], axisNames: ReadonlySet<string>, entries: Terms, appended: Combo[]): void {
+  const matches = originals.filter((combo) => entries.every(([name, value]) => !axisNames.has(name) || combo.get(name) === value));
+  if (matches.length === 0) appended.push(new Map(entries));
+  else for (const combo of matches) for (const [name, value] of entries) combo.set(name, value);
+}
+
+function applyInclude(originals: readonly Combo[], axisNames: ReadonlySet<string>, extra: unknown): readonly Combo[] | undefined {
+  const appended: Combo[] = [];
+  if (!Array.isArray(extra)) return appended;
+  for (const candidate of extra) {
+    if (!isRecord(candidate)) return undefined;
+    const entries = includeEntries(candidate);
+    if (entries === undefined) return undefined;
+    mergeEntries(originals, axisNames, entries, appended);
+  }
+  return appended;
+}
+
+function runnerValues(combos: readonly Combo[], appended: readonly Combo[], key: string): readonly string[] | undefined {
+  const used = new Set<string>();
+  for (const combo of [...combos, ...appended]) {
+    const value = combo.get(key);
+    if (value === undefined) continue;
+    if (typeof value !== "string") return undefined;
+    used.add(value);
+  }
+  return used.size > 0 ? [...used] : undefined;
+}
+
+function matrixValues(job: Readonly<Record<string, unknown>>, key: string): readonly string[] | undefined {
+  const strategy = job["strategy"];
+  if (!isRecord(strategy)) return undefined;
+  const matrix = strategy["matrix"];
+  if (!isRecord(matrix)) return undefined;
+  if (key === "include" || key === "exclude") return undefined;
+  const axes = matrixAxes(matrix);
+  if (axes === undefined) return undefined;
+  const combos = expandCombos(axes);
+  if (combos === undefined) return undefined;
+  const blocks = exclusionBlocks(matrix["exclude"]);
+  if (blocks === undefined) return undefined;
+  const kept = withoutExcluded(combos, blocks);
+  const appended = applyInclude(axes.length === 0 ? [] : kept, new Set(axes.map(([name]) => name)), matrix["include"]);
+  if (appended === undefined) return undefined;
+  return runnerValues(kept, appended, key);
+}
+
+function hasInterpolation(value: string): boolean {
+  return value.includes("${{");
+}
+
+function mentionedSelfHosted(value: unknown): boolean {
+  if (typeof value === "string") return /self-hosted/i.test(value);
+  if (Array.isArray(value)) return value.some(mentionedSelfHosted);
+  if (isRecord(value)) return Object.values(value).some(mentionedSelfHosted);
+  return false;
+}
+
+function plainLabels(value: unknown): readonly string[] | undefined {
+  if (typeof value === "string") return hasInterpolation(value) ? undefined : [value];
+  if (!Array.isArray(value) || !value.every((entry): entry is string => typeof entry === "string")) return undefined;
+  return value.some(hasInterpolation) ? undefined : value;
+}
+
+function matrixRefusal(
+  job: Readonly<Record<string, unknown>>,
+  shown: string,
+  key: string,
+  runners: RunnerConfig,
+  selfHosted: string,
+  unresolvable: (shown: string) => string,
+): string | undefined {
+  const values = matrixValues(job, key);
+  if (values === undefined) return unresolvable(shown);
+  for (const value of values) {
+    if (hasInterpolation(value)) return mentionedSelfHosted(value) ? selfHosted : unresolvable(shown);
+    if (value.toLowerCase() === "self-hosted" || declaredLabels([value], runners)) return selfHosted;
+  }
+  return undefined;
+}
+
+function stringFault(
+  job: Readonly<Record<string, unknown>>,
+  runsOn: string,
+  runners: RunnerConfig,
+  selfHosted: string,
+  unresolvable: (shown: string) => string,
+): string | undefined {
+  const trimmed = runsOn.trim();
+  const key = matrixKey(trimmed);
+  if (key !== undefined) return matrixRefusal(job, trimmed, key, runners, selfHosted, unresolvable);
+  if (hasInterpolation(trimmed)) return mentionedSelfHosted(trimmed) ? selfHosted : unresolvable(trimmed);
+  return declaredLabels([trimmed], runners) ? selfHosted : undefined;
+}
+
+function arrayFault(runsOn: unknown, runners: RunnerConfig, selfHosted: string, unresolvable: (shown: string) => string): string | undefined {
+  const labels = plainLabels(runsOn);
+  if (labels === undefined) return mentionedSelfHosted(runsOn) ? selfHosted : unresolvable("its runs-on expression");
+  return declaredLabels(labels, runners) ? selfHosted : undefined;
+}
+
+function scalarLabelsFault(runsOn: unknown, runners: RunnerConfig, selfHosted: string, unresolvable: (shown: string) => string): string | undefined {
+  const labels = plainLabels(runsOn);
+  if (labels === undefined) return unresolvable("its runs-on expression");
+  return labels.some((label) => label.toLowerCase() === "self-hosted") || declaredLabels(labels, runners) ? selfHosted : undefined;
+}
+
+function recordFault(
+  runsOn: Readonly<Record<string, unknown>>,
+  runners: RunnerConfig,
+  selfHosted: string,
+  unresolvable: (shown: string) => string,
+): string | undefined {
+  if (runsOn["group"] === undefined) return scalarLabelsFault(runsOn["labels"], runners, selfHosted, unresolvable);
+  const labels = plainLabels(runsOn["labels"]);
+  if (labels !== undefined && (labels.some((label) => label.toLowerCase() === "self-hosted") || declaredLabels(labels, runners))) return selfHosted;
+  const group = typeof runsOn["group"] === "string" ? runsOn["group"].trim() : "a runner group";
+  return "a public repository runs a fork-reachable job on runner group " + group + ", which cannot be shown to be hosted before the run; set runs-on: ubuntu-latest";
+}
+
+function publicFault(job: Readonly<Record<string, unknown>>, runsOn: unknown, runners: RunnerConfig): string | undefined {
+  const selfHosted = "a public repository runs a fork-reachable job on self-hosted labels, so a fork pull request would run its code there; set runs-on: ubuntu-latest";
+  const unresolvable = (shown: string) =>
+    "a public repository runs a fork-reachable job on " + shown + ", which cannot be shown to be a hosted runner before the run; set runs-on: ubuntu-latest";
+  if (namesSelfHosted(runsOn)) return selfHosted;
+  if (typeof runsOn === "string") return stringFault(job, runsOn, runners, selfHosted, unresolvable);
+  if (Array.isArray(runsOn)) return arrayFault(runsOn, runners, selfHosted, unresolvable);
+  if (isRecord(runsOn)) return recordFault(runsOn, runners, selfHosted, unresolvable);
+  return unresolvable("its runs-on expression");
+}
+
+function calledWorkflow(job: Readonly<Record<string, unknown>>): string | undefined {
+  const uses = job["uses"];
+  return typeof uses === "string" && uses.startsWith("./.github/workflows/") ? uses.slice(2) : undefined;
+}
+
+function watchedWorkflows(workflow: Workflow): readonly string[] {
+  const on = isRecord(workflow.document) ? workflow.document["on"] : undefined;
+  const watched = isRecord(on) ? on["workflow_run"] : undefined;
+  return isRecord(watched) ? (names(watched["workflows"]) ?? []) : [];
+}
+
+function runnerFault(job: Readonly<Record<string, unknown>>, runsOn: unknown, mutation: boolean, policy: RunnerPolicy, reachable: boolean): string | undefined {
+  if (policy.visibility === "public" && reachable) {
+    const fault = publicFault(job, runsOn, policy.runners);
+    if (fault !== undefined) return fault;
+  }
+  return mutation ? mutationFault(runsOn, policy.runners.mutation, policy.visibility, reachable) : otherFault(runsOn, policy.runners, policy.visibility);
+}
+
+function stepDirectory(value: unknown, inherited: string | undefined): string | undefined {
+  if (value === undefined) return inherited;
+  return typeof value === "string" ? within("", value) : undefined;
+}
+
+function defaultDirectory(node: unknown, inherited: string | undefined): string | undefined {
+  const defaults = isRecord(node) ? node["defaults"] : undefined;
+  const run = isRecord(defaults) ? defaults["run"] : undefined;
+  return stepDirectory(isRecord(run) ? run["working-directory"] : undefined, inherited);
+}
+
+export function jobRuns(workflow: Workflow, job: Readonly<Record<string, unknown>>): readonly Run[] {
+  const dir = defaultDirectory(job, defaultDirectory(workflow.document, ""));
+  const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+  return steps.flatMap((step: unknown) => (isRecord(step) && typeof step["run"] === "string" ? [{ script: step["run"], dir: stepDirectory(step["working-directory"], dir) }] : []));
+}
+
+export function findRunnerFaults(policy: RunnerPolicy, workflows: readonly Workflow[]): readonly RunnerFault[] {
+  const reachable = new Map(workflows.map((workflow) => [workflow.path, forkReachable(workflow)] as const));
+  const titleOf = new Map(workflows.map((workflow) => [workflow.path, workflowTitle(workflow.document) ?? workflow.path] as const));
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const workflow of workflows) {
+      if (reachable.get(workflow.path) === true) continue;
+      const called = workflows.some(
+        (other) => reachable.get(other.path) === true && workflowJobs(other).some(([, job]) => calledWorkflow(job) === workflow.path),
+      );
+      const watched = watchedWorkflows(workflow).some((parent) =>
+        workflows.some((other) => reachable.get(other.path) === true && titleOf.get(other.path) === parent),
+      );
+      if (called || watched) {
+        reachable.set(workflow.path, true);
+        changed = true;
+      }
+    }
+  }
+  return workflows.flatMap((workflow) =>
+    workflowJobs(workflow).flatMap(([id, job]) => {
+      if (job["runs-on"] === undefined) return [];
+      const mutation = jobRuns(workflow, job).some((run) => runsMutation(run, policy.scripts, (file) => policy.files?.get(file)));
+      const fault = runnerFault(job, job["runs-on"], mutation, policy, reachable.get(workflow.path) ?? forkReachable(workflow));
+      return fault === undefined ? [] : [{ location: workflow.path + " job " + id, fault }];
+    }),
+  );
+}
+
+export function formatRunnerReport(faults: readonly RunnerFault[]): string {
+  return [`ci-wiring: ${faults.length} job(s) run on the wrong runner:`, ...faults.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
+}
+
+export const readRunnerConfig = Effect.fn("readRunnerConfig")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const file = (yield* Path.Path).join(root, "package.json");
+  if (!(yield* fs.exists(file))) return { mutation: undefined, selfHosted: [] } satisfies RunnerConfig;
+  const { checks } = yield* fs.readFileString(file).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(Manifest))),
+    Effect.mapError((cause) => new RunnerPolicyError({ message: `cannot read ${file}: ${cause.message}` })),
+  );
+  return { mutation: checks?.mutationRunner, selfHosted: checks?.selfHostedRunners ?? [] } satisfies RunnerConfig;
+});

package/src/delivery/workflow-references.ts

@@ -232,7 +232,7 @@ export function locate(path: string, lines: readonly string[]): Locator {
   };
 }
 
-function workflowTitle(document: unknown): string | undefined {
+export function workflowTitle(document: unknown): string | undefined {
   return isRecord(document) && typeof document["name"] === "string" ? document["name"] : undefined;
 }
 

package/src/docs/doc-templates.ts

@@ -53,7 +53,7 @@ const RELATED_TOPICS = fixed("Related topics", optional("there is no other page
   "- [<page title>](<path to the page>)",
 ]);
 
-const BEFORE_YOU_BEGIN = fixed("Before you begin", REQUIRED, ["- <each prerequisite, with the version it is tested on>"]);
+const BEFORE_YOU_BEGIN = fixed("Before you begin", REQUIRED, ["- <each prerequisite, naming the file that pins its version rather than the version>"]);
 
 const STEPS = ["To <do the task>:", "", "1. <step>", "1. <step>"];
 

package/src/docs/doc-versions.ts

@@ -0,0 +1,137 @@
+import { Effect, Option, Schema } from "effect";
+import { git } from "../core/git.ts";
+import { PACKAGE_MANIFEST } from "./doc-references.ts";
+import { scanMarkdown, type MarkdownLine } from "./prose-matchers.ts";
+
+type Pin = { readonly name: string | undefined; readonly version: string; readonly holder: string };
+
+const BUN_VERSION = ".bun-version";
+
+const Group = Schema.optionalKey(Schema.Record(Schema.String, Schema.String));
+const Manifest = Schema.Struct({
+  version: Schema.optionalKey(Schema.String),
+  packageManager: Schema.optionalKey(Schema.String),
+  engines: Group,
+  dependencies: Group,
+  devDependencies: Group,
+  peerDependencies: Group,
+  optionalDependencies: Group,
+});
+const decodeManifest = Schema.decodeUnknownOption(Schema.fromJsonString(Manifest));
+const NO_MANIFEST: typeof Manifest.Type = {};
+
+const VERSION = /\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/;
+const ONE_VERSION = new RegExp(String.raw`^[\^~=v]?(${VERSION.source})$`);
+const VERSIONS = new RegExp(VERSION.source, "g");
+
+function namedPins(group: Readonly<Record<string, string>> | undefined): readonly Pin[] {
+  return Object.entries(group ?? {}).flatMap(([name, range]) => {
+    const version = ONE_VERSION.exec(range.trim())?.[1];
+    return version === undefined ? [] : [{ name, version, holder: PACKAGE_MANIFEST }];
+  });
+}
+
+function barePins(value: string | undefined, holder: string): readonly Pin[] {
+  return [...(value ?? "").matchAll(VERSIONS)].map(([version]) => ({ name: undefined, version, holder }));
+}
+
+export function pinsOf(manifest: string, bunVersion: string): readonly Pin[] {
+  const { version, packageManager, engines = {}, dependencies, devDependencies, peerDependencies, optionalDependencies } = Option.getOrElse(
+    decodeManifest(manifest),
+    () => NO_MANIFEST,
+  );
+  const pins = [
+    ...[dependencies, devDependencies, peerDependencies, optionalDependencies].flatMap(namedPins),
+    ...[version, packageManager, ...Object.values(engines)].flatMap((value) => barePins(value, PACKAGE_MANIFEST)),
+    ...barePins(bunVersion, BUN_VERSION),
+  ];
+  return pins.filter((pin, index) => pins.findIndex((other) => other.name === pin.name && other.version === pin.version) === index);
+}
+
+function escaped(text: string): string {
+  return text.replaceAll(/[.*+?^${}()|[\]\\/]/g, String.raw`\$&`);
+}
+
+// A longer version that only opens with the pin, as 1.2.30 or 1.2.3-beta, is another version.
+const VERSION_END = String.raw`(?![\w-]|\.\d)`;
+
+function patternOf({ name, version }: Pin): RegExp {
+  const written =
+    name === undefined ? String.raw`(?<![\w.+-])v?${escaped(version)}` : String.raw`(?<![\w@/.-])${escaped(name)}@[\^~]?${escaped(version)}`;
+  return new RegExp(written + VERSION_END, "g");
+}
+
+const GENERATED_OPEN = /^\s*<!-- generated ([\w-]+):/;
+const GENERATED_CLOSE = /^\s*<!-- end generated ([\w-]+) -->/;
+
+function handWritten(lines: readonly MarkdownLine[]): readonly MarkdownLine[] {
+  const exempt = new Set<number>();
+  let at = 0;
+  while (at < lines.length) {
+    const opening = lines[at]?.kind === "code" ? null : GENERATED_OPEN.exec(lines[at]?.raw ?? "");
+    if (opening === null) {
+      at += 1;
+      continue;
+    }
+    const closeAt = lines.findIndex(
+      (line, index) => index > at && line.kind !== "code" && GENERATED_CLOSE.exec(line.raw)?.[1] === opening[1],
+    );
+    if (closeAt < 0) {
+      at += 1;
+      continue;
+    }
+    for (let index = at; index <= closeAt; index += 1) exempt.add(index);
+    at = closeAt + 1;
+  }
+  return lines.filter((_, index) => !exempt.has(index));
+}
+
+type Copy = { readonly at: number; readonly end: number; readonly pin: Pin; readonly written: string };
+
+function namePresent(raw: string, name: string): boolean {
+  return new RegExp(String.raw`(?<![\w@/.-])${escaped(name)}(?![\w/.-])`, "i").test(raw);
+}
+
+function barePatternFor(version: string): RegExp {
+  return new RegExp(String.raw`(?<![\w.+-])v?${escaped(version)}` + VERSION_END, "g");
+}
+
+// A bare pin inside a named copy, as 1.2.3 in zod@1.2.3, is the same copy.
+function copiesIn(raw: string, pins: readonly Pin[]): readonly Copy[] {
+  const found: Copy[] = [];
+  for (const pin of pins) {
+    for (const match of raw.matchAll(patternOf(pin))) {
+      const at = match.index;
+      found.push({ at, end: at + match[0].length, pin, written: match[0] });
+    }
+    if (pin.name !== undefined && namePresent(raw, pin.name)) {
+      for (const match of raw.matchAll(barePatternFor(pin.version))) {
+        const at = match.index;
+        found.push({ at, end: at + match[0].length, pin, written: match[0] });
+      }
+    }
+  }
+  const installed = found.filter((copy) => copy.written.includes("@"));
+  return found
+    .filter((copy) => copy.written.includes("@") || !installed.some(({ at, end }) => copy.at >= at && copy.end <= end))
+    .toSorted((a, b) => a.at - b.at);
+}
+
+export function versionFindings(text: string, pins: readonly Pin[], within?: ReadonlySet<number>): readonly { readonly line: number; readonly message: string }[] {
+  if (pins.length === 0) return [];
+  return handWritten(scanMarkdown(text))
+    .filter(({ line }) => within === undefined || within.has(line))
+    .flatMap(({ line, raw }) =>
+      copiesIn(raw, pins).map(({ written, pin }) => ({
+        line,
+        message: `carries \`${written}\`, a version ${pin.holder} pins. Name ${pin.holder} instead, or let a build write the line between generated markers`,
+      })),
+    );
+}
+
+const readAt = (root: string, head: string, path: string) =>
+  git(["show", `${head}:${path}`], root).pipe(Effect.catchTag("GitFailure", () => Effect.succeed("")));
+
+export const pinsAt = Effect.fn("pinsAt")(function* (root: string, head: string) {
+  return pinsOf(yield* readAt(root, head, PACKAGE_MANIFEST), yield* readAt(root, head, BUN_VERSION));
+});

package/src/docs/docs.ts

@@ -4,6 +4,7 @@ import { ceilingFinding, entryFindings, isAgentFile, maintainingFinding } from "
 import { rootsOf, snapshotOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, recordsOf, speaksToConsumers, type Placement, type Records } from "./doc-rules.ts";
 import { vanishedNames } from "./doc-names.ts";
+import { pinsAt, versionFindings } from "./doc-versions.ts";
 import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
 import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
@@ -107,6 +108,10 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const prose = edited.flatMap(({ path, reader }) =>
     proseFindings(text(path), reader, changed.get(path)).map(({ line, message }) => ({ path, line, message })),
   );
+  const pins = yield* pinsAt(root, head);
+  const versions = edited.flatMap(({ path }) =>
+    versionFindings(text(path), pins, changed.get(path)).map(({ line, message }) => ({ path, line, message })),
+  );
   const sentenceAdvisory = edited
     .flatMap(({ path }) => longSentences(text(path), changed.get(path)).map(({ line, message }) => ({ path, line, message })))
     .toSorted(inPathOrder);
@@ -132,6 +137,7 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
     findings: [
       ...templated.filter((finding) => touched.has(finding.path)),
       ...prose,
+      ...versions,
       ...references.failing,
       ...vanished,
       ...shapes,
@@ -153,6 +159,7 @@ export function report({ held, edited, named, agents, findings, advisory, senten
       ? [
           `${NAME}: ${held.length} doc file(s) the range touches hold to their templates`,
           `${NAME}: ${edited.lines} line(s) the range adds or edits in ${edited.docs} living doc(s) or agent file(s) hold to the prose rules`,
+          `${NAME}: no line the range adds or edits copies a version package.json or .bun-version pins`,
           `${NAME}: the range breaks no path, link or command the ${named} living doc(s) or agent file(s) name`,
           `${NAME}: the ${agents} agent file(s) hold to the ceiling, and every entry names a tracked path, a link or a command`,
         ]

package/src/testing/mutation-baseline-full.ts

@@ -0,0 +1,68 @@
+import { Clock, Config, Console, Effect, FileSystem, Option, Schema } from "effect";
+import { ChildProcessSpawner } from "effect/process";
+import { collect } from "../core/git.ts";
+import { withoutStale } from "./mutation-baseline-saved.ts";
+import { STRYKER_CONFIGS, stalenessSince } from "./mutation-scope.ts";
+
+export class BaselineFailure extends Schema.TaggedError<BaselineFailure>()("BaselineFailure", {
+  message: Schema.String,
+}) {}
+
+export const gh = Effect.fn("gh")(function* (args: readonly string[]) {
+  const failed = (reason: string): BaselineFailure => new BaselineFailure({ message: `gh ${args.join(" ")}: ${reason.trim()}` });
+  const { stdout, stderr, exitCode } = yield* collect("gh", args).pipe(Effect.mapError((cause) => failed(cause.message)));
+  if (exitCode !== ChildProcessSpawner.ExitCode(0)) return yield* failed(stderr);
+  return stdout;
+});
+
+const FULL_CONFIGS = [...STRYKER_CONFIGS, "stryker.preset.js", "bun.lock", ".bun-version"];
+
+const REFRESH_DAYS = 28;
+const DAY_MS = 86_400_000;
+
+const refreshWindow = (time: number): number => Math.floor(time / (REFRESH_DAYS * DAY_MS));
+
+// Each full run reuses what the run before it restored, so a cap on the restored run's age alone caps nothing.
+// Windows fixed from the epoch cap the whole chain: every state in a window was built from runs in that window.
+export function inRefreshWindow(createdAt: string, now: number): boolean {
+  return refreshWindow(Date.parse(createdAt)) === refreshWindow(now);
+}
+
+export type FullRun = { readonly databaseId: number; readonly createdAt: string };
+
+const decodeHeadSha = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ headSha: Schema.String })));
+
+const viewedHead = Effect.fn("viewedHead")(function* (run: number) {
+  return (yield* gh(["run", "view", String(run), "--json", "headSha"]).pipe(Effect.flatMap(decodeHeadSha))).headSha;
+});
+
+export const pruneFullState = Effect.fn("pruneFullState")(function* (run: FullRun, state: string) {
+  const fs = yield* FileSystem.FileSystem;
+  if (!(yield* fs.exists(state))) return;
+  const override = yield* Config.Int("CHECKS_MUTATION_BASELINE_NOW_MS").pipe(Config.option);
+  let now = yield* Clock.currentTimeMillis;
+  if (Option.isSome(override)) now = override.value;
+  if (!inRefreshWindow(run.createdAt, now)) {
+    yield* fs.remove(state);
+    yield* Console.log(`mutation-baseline: dropped the restored full state, run ${run.databaseId} started before the current ${REFRESH_DAYS}-day refresh window`);
+    return;
+  }
+  const base = yield* viewedHead(run.databaseId);
+  const { paths, preload, stale, config } = yield* stalenessSince(base, "HEAD");
+  const changed = [...paths].filter((path) => FULL_CONFIGS.includes(path) || config.has(path)).toSorted();
+  if (changed.length > 0 || preload !== undefined) {
+    yield* fs.remove(state);
+    yield* Console.log(`mutation-baseline: dropped the restored full state, ${preload ?? changed.join(" ")} changed since run ${run.databaseId}`);
+    return;
+  }
+  const text = yield* fs.readFileString(state);
+  const stateJson: unknown = yield* Effect.try({
+    try: (): unknown => JSON.parse(text),
+    catch: () => new BaselineFailure({ message: `${state} is not a Stryker incremental state with its test files` }),
+  });
+  const stripped = withoutStale(stateJson, { tests: new Set(stale), sources: paths });
+  if (stripped.tests.length === 0 && stripped.sources.length === 0) return;
+  yield* fs.writeFileString(state, JSON.stringify(stripped.state));
+  const dropped = [...stripped.tests, ...stripped.sources.map((source) => `${source} results`)].join(" ");
+  yield* Console.log(`mutation-baseline: dropped ${dropped} from the restored full state`);
+});