@avi2dg/checks 0.43.0 → 0.44.0

package/src/testing/flake.ts

@@ -3,12 +3,15 @@ import { Config, Console, Effect, FileSystem, Option, Path, Random, Schema } fro
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { runMain, Usage } from "../core/main.ts";
 import { NAME_SEPARATOR, parseReport, ReportError, reporterArgs, type TestResult } from "./test-report.ts";
+import { scriptOptions } from "./test.ts";
 
 export type Run = {
   readonly seed: number;
   readonly passed: boolean;
   readonly tests: number;
   readonly failed: readonly TestResult[];
+  readonly crashedFiles: readonly string[];
+  readonly assignment: readonly (readonly string[])[];
 };
 
 export type Failure = {
@@ -18,20 +21,33 @@ export type Failure = {
   readonly seeds: readonly number[];
 };
 
-export type RunRecord = Omit<Run, "failed"> & { readonly failed: readonly string[] };
+export type RunRecord = Omit<Run, "failed" | "crashedFiles" | "assignment"> & { readonly failed: readonly string[] };
+
+export type FailingWorker = { readonly seed: number; readonly files: readonly string[] };
+
+export type Replay = FailingWorker & { readonly command: string };
 
 export type FlakeRecord = {
   readonly runs: readonly RunRecord[];
   readonly failures: readonly Failure[];
   readonly outsideTests: readonly number[];
+  readonly parallel?: { readonly workers: number; readonly replays: readonly Replay[] };
 };
 
+export class ManifestError extends Schema.TaggedError<ManifestError>()("ManifestError", {
+  message: Schema.String,
+}) {}
+
 type Plan = { readonly seeds: readonly number[] } | { readonly runs: number };
 
 const NAME = "checks-flake";
 const USAGE = `usage: ${NAME} [--runs <count> | --seed <seed>...] [--report <file>]`;
 const DEFAULT_RUNS = 10;
 const MAX_SEED = 2 ** 32 - 1;
+const WORKER_LOG = "CHECKS_FLAKE_WORKER_LOG";
+const PRELOAD = "flake-preload.ts";
+const SHELL_SAFE = /^[\w./-]+$/;
+const SILENT = { stdin: "ignore", stdout: "ignore", stderr: "ignore" } as const;
 
 const wholeBetween = (minimum: number, maximum: number) =>
   Schema.decodeUnknownEffect(Schema.NumberFromString.check(Schema.isInt(), Schema.isBetween({ minimum, maximum })));
@@ -60,23 +76,63 @@ const parseArgs = Effect.fnUntraced(function* (args: readonly string[]) {
   return { plan, report };
 });
 
+const Manifest = Schema.fromJsonString(Schema.Struct({ scripts: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)) }));
+const decodeManifest = Schema.decodeUnknownEffect(Manifest);
+const decodeWorkerLine = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Struct({ worker: Schema.Int, file: Schema.String })),
+);
+
+const workersOf = Effect.fn("workersOf")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const file = (yield* Path.Path).join(root, "package.json");
+  if (!(yield* fs.exists(file))) return undefined;
+  const { scripts } = yield* fs.readFileString(file).pipe(
+    Effect.flatMap(decodeManifest),
+    Effect.mapError((cause) => new ManifestError({ message: `cannot read ${file}: ${cause.message}` })),
+  );
+  return scriptOptions(scripts?.["test"])?.workers;
+});
+
+const assignmentOf = Effect.fn("assignmentOf")(function* (log: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  if (!(yield* fs.exists(log))) return [];
+  const byWorker = new Map<number, string[]>();
+  for (const line of (yield* fs.readFileString(log)).split("\n").filter((entry) => entry !== "")) {
+    const { worker, file } = yield* decodeWorkerLine(line).pipe(
+      Effect.mapError((cause) => new ReportError({ message: `the worker log is malformed: ${cause.message}` })),
+    );
+    byWorker.set(worker, [...(byWorker.get(worker) ?? []), path.relative(process.cwd(), file)]);
+  }
+  return [...byWorker.values()];
+});
+
 const seedsOf = (plan: Plan) =>
   "seeds" in plan ? Effect.succeed(plan.seeds) : Effect.replicateEffect(Random.nextIntBetween(0, MAX_SEED), plan.runs);
 
-const runOnce = Effect.fn("runOnce")(function* (seed: number, outfile: string) {
-  const fs = yield* FileSystem.FileSystem;
+const spawnSuite = Effect.fn("spawnSuite")(function* (seed: number, outfile: string, workers: number | undefined, log: string) {
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-  const args = ["test", "--randomize", `--seed=${seed}`, ...reporterArgs(outfile)];
-  const exitCode = yield* spawner.exitCode(
-    ChildProcess.make(process.execPath, args, { stdin: "ignore", stdout: "ignore", stderr: "ignore" }),
+  const args = ["test", "--randomize", `--seed=${seed}`];
+  if (workers === undefined) return yield* spawner.exitCode(ChildProcess.make(process.execPath, [...args, ...reporterArgs(outfile)], SILENT));
+  const preload = (yield* Path.Path).join(import.meta.dir, PRELOAD);
+  const parallelArgs = [`--parallel=${workers}`, "--preload", preload, ...reporterArgs(outfile)];
+  return yield* spawner.exitCode(
+    ChildProcess.make(process.execPath, [...args, ...parallelArgs], { ...SILENT, env: { [WORKER_LOG]: log }, extendEnv: true }),
   );
-  const passed = exitCode === ChildProcessSpawner.ExitCode(0);
+});
+
+const runOnce = Effect.fn("runOnce")(function* (seed: number, outfile: string, workers: number | undefined) {
+  const fs = yield* FileSystem.FileSystem;
+  const log = `${outfile}.workers`;
+  const passed = (yield* spawnSuite(seed, outfile, workers, log)) === ChildProcessSpawner.ExitCode(0);
+  const assignment = yield* assignmentOf(log);
   if (!(yield* fs.exists(outfile))) {
     if (passed) return yield* new ReportError({ message: `bun test passed with seed ${seed} but wrote no report` });
-    return { seed, passed, tests: 0, failed: [] } satisfies Run;
+    return { seed, passed, tests: 0, failed: [], crashedFiles: [], assignment } satisfies Run;
   }
-  const { results } = yield* parseReport(yield* fs.readFileString(outfile));
-  return { seed, passed, tests: results.length, failed: results.filter((result) => result.outcome === "failed") } satisfies Run;
+  const { results, crashedFiles } = yield* parseReport(yield* fs.readFileString(outfile));
+  const failed = results.filter((result) => result.outcome === "failed");
+  return { seed, passed, tests: results.length, failed, crashedFiles, assignment } satisfies Run;
 });
 
 function outcomeOf(run: Run): string {
@@ -88,7 +144,16 @@ function nameOf(result: TestResult): string {
   return `${result.file}${NAME_SEPARATOR}${result.name}`;
 }
 
-export function recordOf(runs: readonly Run[]): FlakeRecord {
+export function failingWorkersOf(run: Run): readonly FailingWorker[] {
+  if (run.passed) return [];
+  const failing = new Set([...run.failed.map((result) => result.file), ...run.crashedFiles]);
+  return run.assignment.flatMap((files) => {
+    const last = files.findLastIndex((file) => failing.has(file));
+    return last === -1 ? [] : [{ seed: run.seed, files: files.slice(0, last + 1) }];
+  });
+}
+
+export function recordOf(runs: readonly Run[], parallel?: FlakeRecord["parallel"]): FlakeRecord {
   const failures = new Map<string, { file: string; test: string; line: number; seeds: number[] }>();
   for (const run of runs) {
     const failing = new Map(run.failed.map((result) => [nameOf(result), result]));
@@ -102,9 +167,63 @@ export function recordOf(runs: readonly Run[]): FlakeRecord {
     runs: runs.map(({ seed, passed, tests, failed }) => ({ seed, passed, tests, failed: failed.map(nameOf) })),
     failures: [...failures.values()].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line),
     outsideTests: runs.filter((run) => !run.passed && run.failed.length === 0).map((run) => run.seed),
+    ...(parallel === undefined ? {} : { parallel }),
   };
 }
 
+function shellWord(file: string): string {
+  const word = `./${file}`;
+  return SHELL_SAFE.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
+}
+
+function replayFlags(seed: number): readonly string[] {
+  return ["--isolate", "--randomize", `--seed=${seed}`];
+}
+
+export function replayCommand(seed: number, listed: readonly string[]): string {
+  return ["bun test", ...replayFlags(seed), ...listed.map(shellWord)].join(" ");
+}
+
+function probeFile(log: string, slot: number): string {
+  return `import { test } from "bun:test";\nimport { appendFileSync } from "node:fs";\nappendFileSync(${JSON.stringify(log)}, "${slot}\\n");\ntest("probe", () => {});\n`;
+}
+
+// Bun shuffles the listed files too, by a permutation of their positions that the seed and their count fix.
+const replayOf = Effect.fn("replayOf")(function* (worker: FailingWorker, dir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const probe = yield* fs.makeTempDirectory({ directory: dir, prefix: "replay-" });
+  const log = path.join(probe, "order");
+  const slots = worker.files.map((_, slot) => `./${slot}.test.ts`);
+  yield* Effect.forEach(slots, (name, slot) => fs.writeFileString(path.join(probe, name), probeFile(log, slot)));
+  yield* spawner.exitCode(ChildProcess.make(process.execPath, ["test", ...replayFlags(worker.seed), ...slots], { ...SILENT, cwd: probe }));
+  const ran = (yield* fs.readFileString(log)).split("\n").filter((entry) => entry !== "").map(Number);
+  const listed = slots.map((_, slot) => worker.files[ran.indexOf(slot)]);
+  if (ran.length !== slots.length || !listed.every((file): file is string => file !== undefined)) {
+    return yield* new ReportError({ message: `bun ran the replay probe for seed ${worker.seed} in the order ${ran.join(", ")}` });
+  }
+  return { ...worker, command: replayCommand(worker.seed, listed) } satisfies Replay;
+});
+
+function replayLines({ workers, replays }: NonNullable<FlakeRecord["parallel"]>): readonly string[] {
+  const lines =
+    replays.length === 0
+      ? []
+      : [
+          "",
+          "Reproduce a failing run with the files its failing worker ran, listed so the seed runs them in that order:",
+          "",
+          ...replays.map((replay) => `- seed ${replay.seed}: \`${replay.command}\``),
+        ];
+  if (workers === 1) return lines;
+  return [
+    ...lines,
+    "",
+    `Rerunning a seed with bun test --randomize --seed=<seed> --parallel=${workers} reproduces a failing run only some of the time, because which worker takes each file is a race.`,
+  ];
+}
+
 function cell(text: string): string {
   return text.replaceAll("|", "\\|");
 }
@@ -112,8 +231,9 @@ function cell(text: string): string {
 export function summary(record: FlakeRecord): string {
   const total = record.runs.length;
   const failedRuns = record.runs.filter((run) => !run.passed).length;
-  if (failedRuns === 0) return `${NAME}: ${total} run(s) passed, with seeds ${record.runs.map((run) => run.seed).join(", ")}`;
-  const lines = [`${NAME}: ${failedRuns} of ${total} run(s) failed, ${record.failures.length} test(s) failing in them`];
+  const on = record.parallel === undefined ? "" : ` on ${record.parallel.workers} worker(s)`;
+  if (failedRuns === 0) return `${NAME}: ${total} run(s) passed${on}, with seeds ${record.runs.map((run) => run.seed).join(", ")}`;
+  const lines = [`${NAME}: ${failedRuns} of ${total} run(s) failed${on}, ${record.failures.length} test(s) failing in them`];
   if (record.failures.length > 0) {
     lines.push("", "| Test | Failed | Seeds |", "| --- | --- | --- |");
     for (const failure of record.failures) {
@@ -124,7 +244,8 @@ export function summary(record: FlakeRecord): string {
   if (record.outsideTests.length > 0) {
     lines.push("", `${record.outsideTests.length} run(s) failed outside any test, with seeds ${record.outsideTests.join(", ")}`);
   }
-  lines.push("", "Reproduce a failing run with bun test --randomize --seed=<seed>.");
+  if (record.parallel === undefined) lines.push("", "Reproduce a failing run with bun test --randomize --seed=<seed>.");
+  else lines.push(...replayLines(record.parallel));
   return lines.join("\n");
 }
 
@@ -133,14 +254,19 @@ const flake = Effect.gen(function* () {
   const path = yield* Path.Path;
   const { plan, report } = yield* parseArgs(process.argv.slice(2));
   const seeds = yield* seedsOf(plan);
+  const workers = yield* workersOf(process.cwd());
   const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-flake-" });
 
   const runs = yield* Effect.forEach(seeds, (seed, index) =>
-    runOnce(seed, path.join(dir, `${index}.xml`)).pipe(
+    runOnce(seed, path.join(dir, `${index}.xml`), workers).pipe(
       Effect.tap((run) => Console.log(`${NAME}: run ${index + 1} of ${seeds.length}, seed ${seed}: ${outcomeOf(run)}`)),
     ),
   );
-  const record = recordOf(runs);
+  const parallel =
+    workers === undefined
+      ? undefined
+      : { workers, replays: yield* Effect.forEach(runs.flatMap(failingWorkersOf), (worker) => replayOf(worker, dir)) };
+  const record = recordOf(runs, parallel);
   const text = summary(record);
   yield* Console.log(text);
 

package/src/testing/{mutation-scope.js → mutation-refusal.ts}

@@ -1,9 +1,7 @@
-import { existsSync } from "node:fs";
+const NON_RUNS: readonly string[] = ["--help", "-h", "--version"];
+const MUTATE_FLAGS: readonly string[] = ["--mutate", "-m"];
 
-const NON_RUNS = ["--help", "-h", "--version"];
-const MUTATE_FLAGS = ["--mutate", "-m"];
-
-function namesGlob(args) {
+function namesGlob(args: readonly string[]): boolean {
   return args.some(
     (arg, index) =>
       (MUTATE_FLAGS.includes(arg) && (args[index + 1] ?? "") !== "") ||
@@ -11,17 +9,21 @@ function namesGlob(args) {
   );
 }
 
-function allowedAnyway(args, ci) {
+function allowedAnyway(args: readonly string[], ci: string): boolean {
   return ci === "true" || args.some((arg) => NON_RUNS.includes(arg)) || namesGlob(args);
 }
 
-export function fullRunRefusal(args, ci) {
+export function fullRunRefusal(args: readonly string[], ci: string): string | undefined {
   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) {
+export function missingReportRefusal(
+  args: readonly string[],
+  ci: string,
+  incrementalFile: string,
+  reportExists: (path: string) => boolean,
+): string | undefined {
   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-scope.ts

@@ -0,0 +1,354 @@
+#!/usr/bin/env bun
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { escape, minimatch } from "minimatch";
+import { changedPaths, git, pathsAt, rangeEnds, type Change } from "../core/git.ts";
+import { runMain, Usage } from "../core/main.ts";
+
+const NAME = "mutation-scope";
+const USAGE = "usage: mutation-scope.ts <base> [full-baseline-report]";
+const TEST_TREE = "tests/";
+const UNIT_TESTS = "tests/unit/";
+const FIXTURES = "tests/fixtures/";
+const TEST_FILE = /\.test\.tsx?$/;
+const READ_FILE = /\.tsx?$/;
+const BUNFIG = "bunfig.toml";
+const MUTATION_RANGE = /:\d+(?::\d+)?-\d+(?::\d+)?$/;
+const IMPORTED_EXTENSIONS = [".tsx", ".ts", ".mts", ".mjs", ".js"];
+
+export const STRYKER_DEFAULT_MUTATE = [
+  "{src,lib}/**/!(*.+(s|S)pec|*.+(t|T)est).+(cjs|mjs|js|ts|mts|cts|jsx|tsx|html|vue|svelte)",
+  "!{src,lib}/**/__tests__/**/*.+(cjs|mjs|js|ts|mts|cts|jsx|tsx|html|vue|svelte)",
+];
+
+// Stryker loads the first of these that exists, in this order.
+const STRYKER_CONFIGS = ["", "."].flatMap((dot) =>
+  [".conf", ".config"].flatMap((kind) => ["json", "js", "mjs", "cjs"].map((extension) => `${dot}stryker${kind}.${extension}`)),
+);
+
+export class ScopeError extends Schema.TaggedError<ScopeError>()("ScopeError", {
+  message: Schema.String,
+}) {}
+
+const StrykerConfig = Schema.Struct({ mutate: Schema.optionalKey(Schema.Array(Schema.String)) });
+const decodeJsonConfig = Schema.decodeUnknownEffect(Schema.fromJsonString(StrykerConfig));
+const decodeConfigModule = Schema.decodeUnknownEffect(Schema.Struct({ default: StrykerConfig }));
+
+const BaselineSchema = Schema.Struct({
+  files: Schema.Record(
+    Schema.String,
+    Schema.Struct({
+      mutants: Schema.Array(
+        Schema.Struct({
+          coveredBy: Schema.optionalKey(Schema.Array(Schema.String)),
+          killedBy: Schema.optionalKey(Schema.Array(Schema.String)),
+        }),
+      ),
+    }),
+  ),
+  testFiles: Schema.Record(
+    Schema.String,
+    Schema.Struct({ source: Schema.optionalKey(Schema.String), tests: Schema.Array(Schema.Struct({ id: Schema.String })) }),
+  ),
+});
+
+export type Baseline = typeof BaselineSchema.Type;
+
+const decodeBaseline = Schema.decodeUnknownEffect(Schema.fromJsonString(BaselineSchema));
+
+const decodeBunfig = Schema.decodeUnknownEffect(
+  Schema.Struct({
+    test: Schema.optionalKey(Schema.Struct({ preload: Schema.optionalKey(Schema.Union([Schema.String, Schema.Array(Schema.String)])) })),
+  }),
+);
+
+export type MutationScope = { readonly scope: readonly string[]; readonly staleTests: readonly string[] };
+
+export type Picked = {
+  readonly scope: ReadonlySet<string>;
+  readonly tests: ReadonlySet<string>;
+  readonly touched: ReadonlySet<string>;
+  readonly paths: ReadonlySet<string>;
+};
+
+const isUnitTest = (path: string): boolean => path.startsWith(UNIT_TESTS) && TEST_FILE.test(path);
+
+const absolute = (root: string, path: string): string => `/${resolved(path.startsWith("/") ? "" : root, path)}`;
+
+// --mutate replaces the config's globs, so the scope applies the negated ones itself, resolving each against root as Stryker does.
+export function mutatedBy(patterns: readonly string[], root: string): (file: string) => boolean {
+  const rules = patterns.map((pattern) => {
+    const negated = pattern.startsWith("!");
+    return { glob: absolute(root, negated ? pattern.slice(1) : pattern), mutated: !negated };
+  });
+  return (file) => rules.reduce((mutated, rule) => (minimatch(absolute(root, file), rule.glob) ? rule.mutated : mutated), false);
+}
+
+function scopedNames(change: Change, mutated: (file: string) => boolean): readonly string[] {
+  if (change.kind === "deleted") return [];
+  if (change.kind === "renamed" && mutated(change.from) && mutated(change.path)) return [change.from, change.path];
+  return mutated(change.path) ? [change.path] : [];
+}
+
+const pathsOf = (change: Change): readonly string[] => (change.kind === "renamed" ? [change.from, change.path] : [change.path]);
+
+export function pickFromDiff(changes: readonly Change[], mutated: (file: string) => boolean): Picked {
+  const paths = changes.flatMap(pathsOf);
+  return {
+    scope: new Set(changes.flatMap((change) => scopedNames(change, mutated))),
+    tests: new Set(paths.filter(isUnitTest)),
+    touched: new Set(paths.filter((path) => path.startsWith(TEST_TREE))),
+    paths: new Set(paths),
+  };
+}
+
+const IMPORT = /(?:from|import)[ \t]*\(?[ \t]*["'](\.[^"']*)["']/g;
+const LISTED_SEGMENTS = /["'`][ \t]*,[ \t]*["'`]/g;
+const DIRECTORY_ENDS = ['"', "'", "`", '/"', "/'", "/`", "/${"];
+
+type Needle = { readonly text: string; readonly kind: "file" | "directory"; readonly fixture: string };
+
+function resolved(directory: string, spec: string): string {
+  const parts: string[] = [];
+  for (const part of `${directory}/${spec}`.split("/")) {
+    if (part === "..") parts.pop();
+    else if (part !== "." && part !== "") parts.push(part);
+  }
+  return parts.join("/");
+}
+
+// Bun takes the file a specifier names, then one with an extension added, and only then the directory's index.
+function importedFile(path: string, files: ReadonlySet<string>): string | undefined {
+  const bare = path.replace(/\.m?js$/, "");
+  const tried = [path, ...IMPORTED_EXTENSIONS.map((extension) => bare + extension), ...IMPORTED_EXTENSIONS.map((extension) => `${path}/index${extension}`)];
+  return tried.find((file) => files.has(file));
+}
+
+function fixtureNeedles(changed: readonly string[]): readonly Needle[] {
+  const needles = new Map<string, Needle>();
+  for (const fixture of changed.filter((path) => path.startsWith(FIXTURES))) {
+    const text = fixture.slice(TEST_TREE.length);
+    needles.set(text, { text, kind: "file", fixture });
+    for (let end = text.lastIndexOf("/"); end > 0; end = text.lastIndexOf("/", end - 1)) {
+      const directory = text.slice(0, end);
+      if (!needles.has(directory)) needles.set(directory, { text: directory, kind: "directory", fixture });
+    }
+  }
+  return [...needles.values()];
+}
+
+function mentions(line: string, { text, kind }: Needle): boolean {
+  if (kind === "file") return line.includes(text);
+  return DIRECTORY_ENDS.some((end) => line.includes(text + end));
+}
+
+type Edge = { readonly importer: string; readonly imported: string };
+
+function importsOf(file: string, text: string, files: ReadonlySet<string>): readonly string[] {
+  const directory = file.slice(0, Math.max(file.lastIndexOf("/"), 0));
+  return [...text.matchAll(IMPORT)].flatMap(([, spec = ""]) => importedFile(resolved(directory, spec), files) ?? []);
+}
+
+const edgesOf = (file: string, text: string, files: ReadonlySet<string>): readonly Edge[] =>
+  importsOf(file, text, files).map((imported) => ({ importer: file, imported }));
+
+function fixtureNamedIn(text: string, needles: readonly Needle[]): string | undefined {
+  if (needles.length === 0) return undefined;
+  for (const line of text.split("\n")) {
+    const joined = line.replaceAll(LISTED_SEGMENTS, "/");
+    const needle = needles.find((each) => mentions(joined, each));
+    if (needle !== undefined) return needle.fixture;
+  }
+  return undefined;
+}
+
+function spread(reached: Map<string, string>, edges: readonly Edge[]): void {
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const { importer, imported } of edges) {
+      const via = reached.get(imported);
+      if (via === undefined || reached.has(importer)) continue;
+      reached.set(importer, via);
+      grew = true;
+    }
+  }
+}
+
+// Maps each file that reads a changed path, through an import or the fixture's path, to that changed path.
+export function readersOf(sources: ReadonlyMap<string, string>, changed: readonly string[]): Map<string, string> {
+  const reached = new Map(changed.map((path) => [path, path]));
+  const needles = fixtureNeedles(changed);
+  for (const [file, text] of sources) {
+    const fixture = reached.has(file) ? undefined : fixtureNamedIn(text, needles);
+    if (fixture !== undefined) reached.set(file, fixture);
+  }
+  const files = new Set([...sources.keys(), ...changed]);
+  spread(reached, [...sources].flatMap(([file, text]) => edgesOf(file, text, files)));
+  return new Map([...reached].filter(([file, via]) => file !== via));
+}
+
+// Names what every unit test loads that the pull request changes: the preload list, a preload, or a file a preload imports.
+export function preloadChange(
+  changed: ReadonlySet<string>,
+  preloads: { readonly atBase: readonly string[]; readonly atHead: readonly string[] },
+  loaded: ReadonlySet<string>,
+): string | undefined {
+  if (preloads.atBase.join("\n") !== preloads.atHead.join("\n")) return `the [test] preload list in ${BUNFIG}`;
+  return [...preloads.atBase, ...loaded].find((path) => changed.has(path));
+}
+
+// Stryker leaves coveredBy empty on a static mutant, so only killedBy names its tests, and all of them only from a run without bail.
+export function coveringTests(baseline: Baseline, tests: ReadonlySet<string>, mutated: (file: string) => boolean): Map<string, readonly string[]> {
+  const owners = new Map(Object.entries(baseline.testFiles).flatMap(([file, { tests: listed }]) => listed.map(({ id }) => [id, file] as const)));
+  const covering = new Map<string, readonly string[]>();
+  for (const [source, { mutants }] of Object.entries(baseline.files)) {
+    if (!mutated(source)) continue;
+    const owning = mutants.flatMap(({ coveredBy = [], killedBy = [] }) => [...coveredBy, ...killedBy].map((id) => owners.get(id) ?? ""));
+    const changed = [...new Set(owning)].filter((file) => tests.has(file)).toSorted();
+    if (changed.length > 0) covering.set(source, changed);
+  }
+  return covering;
+}
+
+// Stryker reads each --mutate entry as a glob whose backslashes are separators, and the incremental state keys each test by its literal path.
+export function envLines({ scope, staleTests }: MutationScope): string {
+  const globs = scope.toSorted().map((file) => escape(file, { windowsPathsNoEscape: true, magicalBraces: true }));
+  return [`SCOPE=${globs.join(",")}`, `STALE_TESTS=${staleTests.toSorted().join(",")}`].join("\n");
+}
+
+export const parseArgs = Effect.fnUntraced(function* (argv: readonly string[]): Effect.fn.Return<{ readonly base: string; readonly baseline: string | undefined }, Usage> {
+  const [base, baseline, ...extra] = argv;
+  if (base === undefined || base.startsWith("-") || baseline?.startsWith("-") === true || extra.length > 0) return yield* new Usage({ message: USAGE });
+  return { base, baseline };
+});
+
+const loadConfig = Effect.fn("loadConfig")(function* (file: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const refused = (reason: string) => () => new ScopeError({ message: `${file} ${reason}` });
+  if (file.endsWith(".json")) {
+    return yield* fs.readFileString(file).pipe(Effect.flatMap(decodeJsonConfig), Effect.mapError(refused("is not a Stryker config whose mutate is a list of globs")));
+  }
+  const url = yield* path.toFileUrl(path.resolve(file)).pipe(Effect.mapError(refused("cannot be addressed")));
+  const loaded = yield* Effect.tryPromise({
+    try: (): Promise<unknown> => import(url.href),
+    catch: (cause) => new ScopeError({ message: `cannot load ${file}: ${String(cause)}` }),
+  });
+  const { default: config } = yield* decodeConfigModule(loaded).pipe(Effect.mapError(refused("exports no Stryker config whose mutate is a list of globs")));
+  return config;
+});
+
+const configuredMutate = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  for (const file of STRYKER_CONFIGS) {
+    if (yield* fs.exists(file)) return (yield* loadConfig(file)).mutate ?? STRYKER_DEFAULT_MUTATE;
+  }
+  return STRYKER_DEFAULT_MUTATE;
+});
+
+const mutatePatterns = Effect.gen(function* () {
+  const patterns = yield* configuredMutate;
+  const ranged = patterns.filter((pattern) => MUTATION_RANGE.test(pattern));
+  if (ranged.length > 0) {
+    return yield* new ScopeError({ message: `the Stryker mutate entries ${ranged.join(" ")} name a mutation range, which a scope of whole files cannot keep` });
+  }
+  return patterns;
+});
+
+const preloadsAt = Effect.fn("preloadsAt")(function* (rev: string, paths: ReadonlySet<string>) {
+  if (!paths.has(BUNFIG)) return [];
+  const text = yield* git(["show", `${rev}:${BUNFIG}`]);
+  const unparsed = () => new ScopeError({ message: `${BUNFIG} at ${rev} does not parse as TOML whose [test] preload is a path or a list of paths` });
+  const bunfig = yield* Effect.try({ try: (): unknown => Bun.TOML.parse(text), catch: unparsed }).pipe(Effect.flatMap(decodeBunfig), Effect.mapError(unparsed));
+  const preload = bunfig.test?.preload ?? [];
+  return (typeof preload === "string" ? [preload] : preload).map((entry) => resolved("", entry));
+});
+
+const loadedByPreloads = Effect.fn("loadedByPreloads")(function* (rev: string, preloads: readonly string[], paths: ReadonlySet<string>) {
+  const loaded = new Set<string>();
+  for (let next = preloads.flatMap((preload) => importedFile(preload, paths) ?? []); next.length > 0; ) {
+    for (const file of next) loaded.add(file);
+    const read = (file: string) => git(["show", `${rev}:${file}`]).pipe(Effect.map((text) => importsOf(file, text, paths)));
+    const imported = (yield* Effect.forEach(next, read, { concurrency: 16 })).flat();
+    next = [...new Set(imported)].filter((file) => !loaded.has(file));
+  }
+  return loaded;
+});
+
+const readTestTree = Effect.fn("readTestTree")(function* (paths: Iterable<string>) {
+  const fs = yield* FileSystem.FileSystem;
+  const files = [...paths].filter((path) => path.startsWith(TEST_TREE) && READ_FILE.test(path));
+  const read = (file: string) => fs.readFileString(file).pipe(Effect.map((text) => [file, text] as const));
+  return new Map(yield* Effect.forEach(files, read, { concurrency: 16 }));
+});
+
+const loadBaseline = Effect.fn("loadBaseline")(function* (report: string | undefined, tests: ReadonlySet<string>) {
+  const fs = yield* FileSystem.FileSystem;
+  if (report === undefined || !(yield* fs.exists(report))) {
+    const where = report === undefined ? "" : ` at ${report}`;
+    return yield* new ScopeError({ message: `${[...tests].toSorted().join(",")} changed, but no baseline report${where} says which sources they cover` });
+  }
+  const unparsed = (cause: { readonly message: string }) => new ScopeError({ message: `${report} is not a Stryker mutation report with its test files: ${cause.message}` });
+  return yield* fs.readFileString(report).pipe(Effect.flatMap(decodeBaseline), Effect.mapError(unparsed));
+});
+
+type Snapshots = { readonly base: string; readonly head: string; readonly atBase: ReadonlySet<string>; readonly atHead: ReadonlySet<string> };
+
+// Every unit test loads each preload, so a change to one makes every unit test read it.
+const unitReaders = Effect.fn("unitReaders")(function* (picked: Picked, { base, head, atBase, atHead }: Snapshots) {
+  const preloads = { atBase: yield* preloadsAt(base, atBase), atHead: yield* preloadsAt(head, atHead) };
+  const everyTestReads = preloadChange(picked.paths, preloads, yield* loadedByPreloads(head, preloads.atHead, atHead));
+  if (everyTestReads !== undefined) {
+    yield* Console.error(`${NAME}: every unit test reads ${everyTestReads}`);
+    return [...atHead].filter((test) => isUnitTest(test) && !picked.tests.has(test)).map((test) => [test, everyTestReads] as const);
+  }
+  if (picked.touched.size === 0) return [];
+  const readers = [...readersOf(yield* readTestTree(atHead), [...picked.touched])].filter(([reader]) => isUnitTest(reader));
+  for (const [reader, via] of readers) yield* Console.error(`${NAME}: ${reader} reads ${via}`);
+  return readers;
+});
+
+// An absent coverage edge holds only for a test whose merge-base source is the one the report ran.
+const staleIn = Effect.fn("staleIn")(function* (baseline: Baseline, tests: readonly string[], base: string) {
+  const recorded = new Map(Object.entries(baseline.testFiles).map(([file, { source }]) => [file, source]));
+  const atBase = yield* Effect.forEach(tests, (test) => git(["show", `${base}:${test}`]), { concurrency: 16 });
+  return tests.filter((test, index) => recorded.get(test) !== atBase[index]).toSorted();
+});
+
+// Stryker reports no source without mutants, so a source the report lacks may be newer than it and enters.
+const enteringSources = Effect.fn("enteringSources")(function* (
+  report: string | undefined,
+  tests: ReadonlySet<string>,
+  mutated: (file: string) => boolean,
+  { base, atBase, atHead }: Snapshots,
+  scoped: ReadonlySet<string>,
+) {
+  if (tests.size === 0) return [];
+  const baseline = yield* loadBaseline(report, tests);
+  const eligible = (source: string): boolean => mutated(source) && !scoped.has(source) && atHead.has(source);
+  const candidates = [...atHead].filter(eligible).toSorted();
+  const stale = yield* staleIn(baseline, [...tests].filter((test) => atBase.has(test)), base);
+  if (stale.length > 0) {
+    yield* Console.error(`${NAME}: the baseline report did not run ${stale.join(" ")} as the merge base holds it, so every mutated source enters`);
+    return candidates;
+  }
+  const entering = [...coveringTests(baseline, tests, mutated)].filter(([source]) => eligible(source));
+  for (const [source, via] of entering) yield* Console.error(`${NAME}: ${source} enters through ${via.join(" ")}`);
+  const unknown = candidates.filter((source) => !Object.hasOwn(baseline.files, source));
+  if (unknown.length > 0) yield* Console.error(`${NAME}: ${unknown.join(" ")} enter, as the baseline report holds no mutant of them`);
+  return [...entering.map(([source]) => source), ...unknown];
+});
+
+const selectScope = Effect.gen(function* () {
+  const { base, baseline } = yield* parseArgs(process.argv.slice(2));
+  const range = yield* rangeEnds(base, "HEAD");
+  const mutated = mutatedBy(yield* mutatePatterns, (yield* Path.Path).resolve("."));
+  const snapshots: Snapshots = { ...range, atBase: new Set(yield* pathsAt(range.base, [])), atHead: new Set(yield* pathsAt(range.head, [])) };
+  const picked = pickFromDiff(yield* changedPaths(range.base, range.head, []), mutated);
+  const readers = (yield* unitReaders(picked, snapshots)).map(([reader]) => reader);
+  const tests = new Set([...picked.tests, ...readers]);
+  const entering = yield* enteringSources(baseline, tests, mutated, snapshots, picked.scope);
+  yield* Console.log(envLines({ scope: [...picked.scope, ...entering], staleTests: readers }));
+  return true;
+});
+
+if (import.meta.main) runMain(NAME, selectScope);

package/src/testing/mutation.ts

@@ -2,7 +2,7 @@
 import { Config, Effect, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { runMain } from "../core/main.ts";
-import { fullRunRefusal } from "./mutation-scope.js";
+import { fullRunRefusal } from "./mutation-refusal.ts";
 
 export class MutationError extends Schema.TaggedError<MutationError>()("MutationError", {
   message: Schema.String,