@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/mutate-report.ts

@@ -0,0 +1,96 @@
+/** The two reports of `repo mutate`: Stryker's json report in, a shard's own report out and read back. */
+import { z } from "zod";
+import { KILLED_STATUSES, SURVIVOR_STATUSES } from "./mutate.constants.ts";
+
+/** A mutant no test killed. */
+type Survivor = { line: number; column: number; mutator: string; status: "Survived" | "NoCoverage" };
+/** One file's mutants: how many tests killed and the ones that lived. */
+export type FileScore = { killed: number; survivors: Survivor[] };
+/** What one shard run writes: the commit it mutated, which shard of how many, and its files' scores. */
+export type ShardReport = { head: string; shard: { index: number; total: number }; files: Record<string, FileScore> };
+
+function buildSchemas() {
+  const stryker = z.object({
+    files: z.record(
+      z.string(),
+      z.object({
+        mutants: z.array(
+          z.object({
+            status: z.string(),
+            mutatorName: z.string(),
+            location: z.object({ start: z.object({ line: z.number(), column: z.number() }) }),
+          }),
+        ),
+      }),
+    ),
+  });
+  const survivor = z.object({
+    line: z.number(),
+    column: z.number(),
+    mutator: z.string(),
+    status: z.enum(["Survived", "NoCoverage"]),
+  });
+  const report = z.object({
+    head: z.string(),
+    shard: z.object({ index: z.number().int().min(1), total: z.number().int().min(1) }),
+    files: z.record(z.string(), z.object({ killed: z.number(), survivors: z.array(survivor) })),
+  });
+  return { stryker, report };
+}
+
+const schemas = /* @__PURE__ */ buildSchemas();
+
+export type Parsed<T> = { ok: true; value: T } | { ok: false; reason: string };
+
+const reasonOf = (error: z.ZodError): string =>
+  error.issues.map((issue) => `${issue.path.join(".") || "report"}: ${issue.message}`).join("; ");
+
+type Mutant = z.output<typeof schemas.stryker>["files"][string]["mutants"][number];
+
+function survivorOf(mutant: Mutant): Survivor[] {
+  if (!SURVIVOR_STATUSES.includes(mutant.status)) return [];
+  const { line, column } = mutant.location.start;
+  return [
+    {
+      line,
+      column,
+      mutator: mutant.mutatorName,
+      status: mutant.status /* SURVIVOR_STATUSES lists exactly the two statuses */ as Survivor["status"],
+    },
+  ];
+}
+
+/** Stryker's report as per-file scores: Killed and Timeout kill, Survived and NoCoverage survive, the rest is left out. */
+export function fromStryker(raw: unknown): Parsed<Record<string, FileScore>> {
+  const parsed = schemas.stryker.safeParse(raw);
+  if (!parsed.success) return { ok: false, reason: reasonOf(parsed.error) };
+  const files = Object.entries(parsed.data.files).map(([file, { mutants }]): [string, FileScore] => [
+    file,
+    {
+      killed: mutants.filter((mutant) => KILLED_STATUSES.includes(mutant.status)).length,
+      survivors: mutants.flatMap(survivorOf),
+    },
+  ]);
+  return { ok: true, value: Object.fromEntries(files) };
+}
+
+/** JSON text as a value, or why it is no JSON. */
+export function parseJson(text: string): Parsed<unknown> {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch (error) {
+    return { ok: false, reason: String(error) };
+  }
+}
+
+/** A shard report read from JSON text. */
+export function parseReport(text: string): Parsed<ShardReport> {
+  const json = parseJson(text);
+  if (!json.ok) return json;
+  const parsed = schemas.report.safeParse(json.value);
+  return parsed.success ? { ok: true, value: parsed.data } : { ok: false, reason: reasonOf(parsed.error) };
+}
+
+/** The survivors of every file of a report. */
+export const survivorCount = (files: Record<string, FileScore>): number =>
+  Object.values(files).reduce((sum, file) => sum + file.survivors.length, 0);

package/cli/mutate-run.ts

@@ -0,0 +1,128 @@
+/** One `repo mutate` run in a throwaway clone of HEAD: clone, install, Stryker, its report; the clone is always removed. */
+import path from "node:path";
+import { z } from "zod";
+import type { Captured } from "./scripts/lint.ts";
+import {
+  BUN_FLAGS,
+  CLONE_DIR,
+  CONFIG_NAME,
+  INSTALL_ARGS,
+  INSTALL_COMMAND,
+  INSTALL_HINT,
+  INSTALLED_DIR,
+  JSON_INDENT,
+  MANIFEST,
+  NEWLINE,
+  RAW_REPORT_NAME,
+  SHORT_SHA,
+  STRYKER_BIN_NAME,
+  STRYKER_CORE,
+  STRYKER_OPTIONS,
+  STRYKER_RUNNER,
+  STRYKER_RUN,
+  TEMP_PREFIX,
+} from "./mutate.constants.ts";
+import type { Shard } from "./mutate-args.ts";
+import type { MutateDeps } from "./mutate-deps.ts";
+import { splitShards } from "./mutate-files.ts";
+import { fromStryker, parseJson, type ShardReport } from "./mutate-report.ts";
+
+/** What a run mutates: the root, the commit, every selected file and the shard of them this run takes. */
+export type Plan = { root: string; sha: string; files: string[]; shard: Shard };
+
+function buildBinSchema() {
+  return z.object({ bin: z.union([z.string(), z.record(z.string(), z.string())]) });
+}
+
+const binSchema = /* @__PURE__ */ buildBinSchema();
+
+/** A failed command's own words: its stderr, else its stdout. */
+const detail = (run: Captured): string => run.stderr.trim() || run.stdout.trim();
+
+/** Prints a refusal and returns null, the failure every step answers with. */
+function refuse(deps: MutateDeps, line: string, extra = ""): null {
+  deps.err(`repo mutate: ${line}${NEWLINE}${extra}`);
+  return null;
+}
+
+/** Clones the root shared, then detaches the clone to the commit; false after saying why when git fails. */
+function checkout(clone: string, plan: Plan, deps: MutateDeps): boolean {
+  const cloned = deps.git(plan.root, ["clone", "-q", "--shared", plan.root, clone]);
+  const detach = ["-C", clone, "checkout", "-q", "--detach", plan.sha];
+  const last = cloned.code === 0 ? deps.git(plan.root, detach) : cloned;
+  if (last.code === 0) return true;
+  const what = cloned.code === 0 ? `check out ${plan.sha.slice(0, SHORT_SHA)} in the clone` : `clone ${plan.root}`;
+  refuse(deps, `could not ${what}: ${detail(last)}`);
+  return false;
+}
+
+/** The path of Stryker's bin in the clone, or null after printing the install line when the tool is not installed. */
+function strykerBin(clone: string, deps: MutateDeps): string | null {
+  const modules = path.join(clone, INSTALLED_DIR);
+  const core = deps.fs.read(path.join(modules, STRYKER_CORE, MANIFEST));
+  const runner = deps.fs.read(path.join(modules, STRYKER_RUNNER, MANIFEST));
+  const manifest = core === null || runner === null ? null : parseJson(core);
+  const parsed = manifest?.ok === true ? binSchema.safeParse(manifest.value) : null;
+  const bin = parsed?.success ? parsed.data.bin : undefined;
+  const relative = typeof bin === "string" ? bin : bin?.[STRYKER_BIN_NAME];
+  if (relative === undefined) return refuse(deps, `install the mutation tool first: ${INSTALL_HINT}`);
+  return path.join(modules, STRYKER_CORE, relative);
+}
+
+/** The Stryker config for `files`, written beside the clone with its raw report path. */
+function configOf(files: string[], rawReport: string): string {
+  const config = { ...STRYKER_OPTIONS, mutate: files, jsonReporter: { fileName: rawReport } };
+  return JSON.stringify(config, null, JSON_INDENT);
+}
+
+function lineCounts(clone: string, files: string[], deps: MutateDeps): Map<string, number> {
+  const count = (file: string) => (deps.fs.read(path.join(clone, file)) ?? "").split(NEWLINE).length;
+  return new Map(files.map((file) => [file, count(file)]));
+}
+
+/** Stryker over `files` in the clone: its per-file scores, or null after printing why it gave none. */
+function stryker(base: string, run: { files: string[]; bin: string }, deps: MutateDeps): ShardReport["files"] | null {
+  const { files, bin } = run;
+  const clone = path.join(base, CLONE_DIR);
+  const config = path.join(base, CONFIG_NAME);
+  const raw = path.join(base, RAW_REPORT_NAME);
+  deps.fs.write(config, configOf(files, raw));
+  const ran = deps.run([...BUN_FLAGS, deps.preload, bin, STRYKER_RUN, config], clone);
+  if (ran.code !== 0) {
+    return refuse(deps, "the tests failed before any mutant ran; fix them first", ran.stdout + ran.stderr);
+  }
+  const text = deps.fs.read(raw);
+  if (text === null) return refuse(deps, "Stryker wrote no readable report: the report file is missing");
+  const json = parseJson(text);
+  const scores = json.ok ? fromStryker(json.value) : json;
+  return scores.ok ? scores.value : refuse(deps, `Stryker wrote no readable report: ${scores.reason}`);
+}
+
+/** A finished run: the shard's report and how many files it took. */
+export type Ran = { report: ShardReport; files: number };
+
+function mutateIn(base: string, plan: Plan, deps: MutateDeps): Ran | null {
+  const clone = path.join(base, CLONE_DIR);
+  if (!checkout(clone, plan, deps)) return null;
+  const mine = splitShards(plan.files, lineCounts(clone, plan.files, deps), plan.shard);
+  const ran = (files: ShardReport["files"]): Ran => ({
+    report: { head: plan.sha, shard: plan.shard, files },
+    files: mine.length,
+  });
+  if (mine.length === 0) return ran({});
+  const installed = deps.run([...INSTALL_ARGS], clone);
+  if (installed.code !== 0) return refuse(deps, `${INSTALL_COMMAND} failed in the clone: ${detail(installed)}`);
+  const bin = strykerBin(clone, deps);
+  const scores = bin === null ? null : stryker(base, { files: mine, bin }, deps);
+  return scores === null ? null : ran(scores);
+}
+
+/** The shard's scores from a run in a fresh clone under the OS temp dir, removed whether the run ends or throws. */
+export function runInClone(plan: Plan, deps: MutateDeps): Ran | null {
+  const base = deps.fs.mkdtemp(TEMP_PREFIX);
+  try {
+    return mutateIn(base, plan, deps);
+  } finally {
+    deps.fs.rm(base);
+  }
+}

package/cli/mutate-shards.ts

@@ -0,0 +1,64 @@
+/** The shard reports in a dir: read, and judged to be one complete run. */
+import path from "node:path";
+import type { MutateDeps } from "./mutate-deps.ts";
+import { parseReport, type ShardReport } from "./mutate-report.ts";
+import { JSON_SUFFIX, SHORT_SHA } from "./mutate.constants.ts";
+
+/** `a and b`, `a, b and c`: two items or more. */
+function listOf(items: readonly string[]): string {
+  const last = items.length - 1;
+  return `${items.slice(0, last).join(", ")} and ${items[last]}`;
+}
+
+const unique = <T>(items: readonly T[]): T[] => [...new Set(items)];
+export const shortOf = (head: string): string => head.slice(0, SHORT_SHA);
+
+type Check = (dir: string, reports: ShardReport[]) => string | null;
+
+const mixedHeads: Check = (dir, reports) => {
+  const heads = unique(reports.map((report) => shortOf(report.head)));
+  return heads.length > 1 ? `${dir} holds shards of ${listOf(heads)}; use one run's reports` : null;
+};
+
+const mixedTotals: Check = (dir, reports) => {
+  const totals = unique(reports.map((report) => report.shard.total));
+  return totals.length > 1 ? `${dir} mixes runs of ${listOf(totals.map(String))} shards; use one run's reports` : null;
+};
+
+const repeated: Check = (dir, reports) => {
+  const seen = reports.map((report) => report.shard.index);
+  const twice = seen.find((index, at) => seen.indexOf(index) !== at);
+  return twice === undefined ? null : `${dir} holds shard ${twice} twice; use one run's reports`;
+};
+
+const missing: Check = (dir, reports) => {
+  const total = reports.reduce((_, report) => report.shard.total, 0);
+  const seen = reports.map((report) => report.shard.index);
+  const absent = Array.from({ length: total }, (_, at) => at + 1).filter((index) => !seen.includes(index));
+  if (absent.length === 0) return null;
+  const noun = absent.length > 1 ? "shards" : "shard";
+  return `${dir} is missing ${noun} ${absent.join(", ")} of ${total}; download every shard's report first`;
+};
+
+const CHECKS: readonly Check[] = [mixedHeads, mixedTotals, repeated, missing];
+
+/** The reports in `dir` when they are one complete run; else the line that says what is wrong with them. */
+export function loadShards(dir: string, deps: MutateDeps): ShardReport[] | string {
+  const full = path.resolve(deps.cwd, dir);
+  const names = (deps.fs.list(full) ?? []).filter((name) => name.endsWith(JSON_SUFFIX)).toSorted();
+  if (names.length === 0) {
+    const hint = `repo mutate --shard i/n --report ${dir}/mutation-i${JSON_SUFFIX}`;
+    return `${dir} holds no mutation report; run \`${hint}\` first`;
+  }
+  const reports: ShardReport[] = [];
+  for (const name of names) {
+    const parsed = parseReport(deps.fs.read(path.join(full, name)) ?? "");
+    if (!parsed.ok) return `${path.join(dir, name)} is not a mutation report: ${parsed.reason}`;
+    reports.push(parsed.value);
+  }
+  for (const check of CHECKS) {
+    const problem = check(dir, reports);
+    if (problem !== null) return problem;
+  }
+  return reports;
+}

package/cli/mutate.constants.ts

@@ -0,0 +1,67 @@
+/** The names `repo mutate` and its report share. */
+
+/** Prefix of the temp dir holding a run's clone, Stryker config and raw report. */
+export const TEMP_PREFIX = "workerstack-mutate-";
+/** The clone's dir inside the temp dir, so the config and the raw report stay outside it. */
+export const CLONE_DIR = "repo";
+export const CONFIG_NAME = "stryker.json";
+export const RAW_REPORT_NAME = "stryker-report.json";
+/** Where an unsharded run writes its report, relative to the repo root. */
+export const DEFAULT_REPORT = ".tmp/repo/mutation/report.json";
+/** The spaces a written JSON file is indented with. */
+export const JSON_INDENT = 2;
+export const OK = 0;
+export const FAILED = 1;
+export const SHORT_SHA = 7;
+/** The words a flag and its value take. */
+export const FLAG_WORDS = 2;
+export const FIRST_SHARD = 1;
+export const NEWLINE = "\n";
+export const JSON_SUFFIX = ".json";
+
+export const CHECK_COMMAND = "check";
+export const SHARD_FLAG = "--shard";
+export const REPORT_FLAG = "--report";
+export const WRITE_FLAG = "--write";
+export const FLAG_PREFIX = "--";
+export const ASSIGN = "=";
+export const SHARD_PATTERN: RegExp = /^(\d+)\/(\d+)$/;
+
+/** The package manifests of the mutation tool, read from the clone's install. */
+export const STRYKER_CORE = "@stryker-mutator/core";
+export const STRYKER_RUNNER = "@stryker-mutator/vitest-runner";
+export const MANIFEST = "package.json";
+/** The dir `bun install` fills. */
+export const INSTALLED_DIR = "node_modules";
+export const INSTALL_HINT: string = `bun add -d ${STRYKER_CORE}@10.1.1 ${STRYKER_RUNNER}@10.1.1`;
+export const INSTALL_ARGS: readonly string[] = ["install", "--frozen-lockfile"];
+export const INSTALL_COMMAND = "bun install --frozen-lockfile";
+/** The bun flags that run Stryker's node bin under bun with the preload. */
+export const BUN_FLAGS: readonly string[] = ["--bun", "--preload"];
+export const STRYKER_BIN_NAME = "stryker";
+export const STRYKER_RUN = "run";
+
+/** The globs a mutated file must not match, with the tests (`*.test.*`, `*.spec.*`) and declaration files. */
+export const EXCLUDED: readonly RegExp[] = [/\.(test|spec)\.[cm]?[jt]sx?$/, /(^|\/)fixtures\//, /\.d\.ts$/];
+
+/** The Stryker options this repo needs; see plan 55's Context for why each is set. */
+export const STRYKER_OPTIONS = {
+  testRunner: "vitest",
+  reporters: ["json"],
+  coverageAnalysis: "perTest",
+  inPlace: true,
+  disableTypeChecks: false,
+  ignoreStatic: true,
+  vitest: { pool: "forks" },
+} as const;
+
+/** Stryker statuses that count as a kill, a survivor, and the rest, which no score counts. */
+export const KILLED_STATUSES: readonly string[] = ["Killed", "Timeout"];
+export const SURVIVOR_STATUSES: readonly string[] = ["Survived", "NoCoverage"];
+
+/** The package a file belongs to when no workspace package dir holds it. */
+export const ROOT_PACKAGE = ".";
+export const PERCENT = 100;
+export const PERCENT_DIGITS = 2;
+export const SEPARATOR = "; ";
+export const ARROW = "→";

package/cli/mutate.test.ts

@@ -0,0 +1,182 @@
+import { expect, it } from "vitest";
+import path from "node:path";
+import { BASE, CLONE, OUT, ROOT, SHA, fakes, rawReport, sim } from "./fixtures/mutate-fakes.ts";
+import { runMutate } from "./mutate.ts";
+
+const SHARD = ["--shard", "1/2", "--report", OUT];
+const INSTALL =
+  "repo mutate: install the mutation tool first: bun add -d @stryker-mutator/core@10.1.1 @stryker-mutator/vitest-runner@10.1.1\n";
+
+it("clones HEAD shared, detaches to its sha, installs frozen, runs Stryker there and removes the clone", async () => {
+  const f = fakes();
+  expect(await runMutate(SHARD, f.deps)).toBe(0);
+  const git = f.calls.filter((c) => c.startsWith("git"));
+  expect(git).toEqual([
+    "git rev-parse HEAD",
+    "git status --porcelain",
+    "git ls-tree -r --name-only HEAD",
+    `git clone -q --shared ${ROOT} ${CLONE}`,
+    `git -C ${CLONE} checkout -q --detach ${SHA}`,
+  ]);
+  const order = f.calls.map((c) => c.split(" ")[0] + (c.includes("install") ? " install" : ""));
+  expect(order.slice(-3)).toEqual(["bun install", "bun", "rm"]);
+  expect(f.calls).toContain(`bun install --frozen-lockfile @${CLONE}`);
+  expect(f.calls.at(-1)).toBe(`rm ${BASE}`);
+  expect(f.calls.filter((c) => c.startsWith("mkdtemp"))).toEqual(["mkdtemp workerstack-mutate-"]);
+});
+
+it("runs the bin the clone's package names under bun with the preload, config outside the clone", async () => {
+  const f = fakes();
+  await runMutate(SHARD, f.deps);
+  const run = f.calls.find((c) => c.includes("stryker.js"));
+  const bin = path.join(CLONE, "node_modules/@stryker-mutator/core/bin/stryker.js");
+  expect(run).toBe(
+    `bun --bun --preload /pkg/cli/stryker-preload.ts ${bin} run ${path.join(BASE, "stryker.json")} @${CLONE}`,
+  );
+});
+
+it("writes a Stryker config with the shard's files and the options this repo needs", async () => {
+  const f = fakes();
+  let config: unknown;
+  const write = f.deps.fs.write;
+  f.deps.fs.write = (file, text) => {
+    if (file.endsWith("stryker.json")) config = JSON.parse(text);
+    write(file, text);
+  };
+  await runMutate(SHARD, f.deps);
+  expect(config).toEqual({
+    testRunner: "vitest",
+    mutate: ["src/a.ts"],
+    reporters: ["json"],
+    coverageAnalysis: "perTest",
+    inPlace: true,
+    disableTypeChecks: false,
+    ignoreStatic: true,
+    vitest: { pool: "forks" },
+    jsonReporter: { fileName: path.join(BASE, "stryker-report.json") },
+  });
+});
+
+it("removes the clone when Stryker fails, when git fails and when a step throws", async () => {
+  const failed = fakes(sim({ stryker: { code: 1, output: "x", report: {} } }));
+  expect(await runMutate(SHARD, failed.deps)).toBe(1);
+  expect(failed.calls.at(-1)).toBe(`rm ${BASE}`);
+  const cloneFails = fakes(sim({ gitFails: "clone" }));
+  expect(await runMutate(SHARD, cloneFails.deps)).toBe(1);
+  expect(cloneFails.err.join("")).toBe(`repo mutate: could not clone ${ROOT}: boom\n`);
+  expect(cloneFails.calls.at(-1)).toBe(`rm ${BASE}`);
+  const thrown = fakes();
+  thrown.deps.run = () => {
+    throw new Error("spawn died");
+  };
+  await expect(runMutate(SHARD, thrown.deps)).rejects.toThrow("spawn died");
+  expect(thrown.calls.at(-1)).toBe(`rm ${BASE}`);
+});
+
+it("names a failed detach and a failed install, and removes the clone", async () => {
+  const detach = fakes(sim({ gitFails: "--detach" }));
+  expect(await runMutate(SHARD, detach.deps)).toBe(1);
+  expect(detach.err.join("")).toBe(`repo mutate: could not check out ${SHA.slice(0, 7)} in the clone: boom\n`);
+  const install = fakes(sim({ installFails: true }));
+  expect(await runMutate(SHARD, install.deps)).toBe(1);
+  expect(install.err.join("")).toBe("repo mutate: bun install --frozen-lockfile failed in the clone: lock\n");
+  expect(install.calls.at(-1)).toBe(`rm ${BASE}`);
+});
+
+it("shards the tracked matches by lines, writes the shard report and prints its line", async () => {
+  const f = fakes();
+  expect(await runMutate(["--shard", "2/2", "--report", OUT], f.deps)).toBe(0);
+  expect(f.out.join("")).toBe(`mutate: HEAD ${SHA.slice(0, 7)}\nmutate: 1 file, shard 2/2, 0 survivors in ${OUT}\n`);
+  expect(JSON.parse(f.files.get(OUT) ?? "")).toEqual({
+    head: SHA,
+    shard: { index: 2, total: 2 },
+    files: { "src/b.ts": { killed: 1, survivors: [] } },
+  });
+});
+
+it("counts Survived and NoCoverage as survivors, Timeout as killed, and leaves out the rest", async () => {
+  const report = rawReport({
+    "src/a.ts": ["Killed", "Timeout", "Survived", "NoCoverage", "CompileError", "Ignored"],
+  });
+  const f = fakes(sim({ stryker: { code: 0, output: "", report } }));
+  await runMutate(["--shard", "1/2", "--report", OUT], f.deps);
+  expect(JSON.parse(f.files.get(OUT) ?? "")).toMatchObject({
+    files: {
+      "src/a.ts": {
+        killed: 2,
+        survivors: [
+          { line: 3, column: 2, mutator: "ArithmeticOperator", status: "Survived" },
+          { line: 4, column: 2, mutator: "ArithmeticOperator", status: "NoCoverage" },
+        ],
+      },
+    },
+  });
+  expect(f.out.join("")).toContain(`2 survivors in ${OUT}`);
+});
+
+it("writes an empty report for a shard past the files without installing or running Stryker", async () => {
+  const f = fakes(sim({ tracked: ["src/a.ts"] }));
+  expect(await runMutate(["--shard", "2/2", "--report", OUT], f.deps)).toBe(0);
+  expect(f.calls.some((c) => c.startsWith("bun"))).toBe(false);
+  expect(JSON.parse(f.files.get(OUT) ?? "")).toMatchObject({ shard: { index: 2, total: 2 }, files: {} });
+  expect(f.out.join("")).toContain("0 files, shard 2/2, 0 survivors");
+});
+
+it("refuses a report Stryker did not write, naming why", async () => {
+  const f = fakes(sim({ stryker: { code: 0, output: "", report: { files: 3 } } }));
+  expect(await runMutate(SHARD, f.deps)).toBe(1);
+  expect(f.err.join("")).toMatch(/^repo mutate: Stryker wrote no readable report: .+\n$/);
+  const none = fakes();
+  none.deps.run = () => ({ code: 0, stdout: "", stderr: "" });
+  expect(await runMutate(SHARD, none.deps)).toBe(1);
+  expect(none.err.join("")).toContain("Stryker wrote no readable report: the report file is missing");
+});
+
+it("notes that uncommitted changes are not mutated, only when there are some", async () => {
+  const dirty = fakes(sim({ dirty: true }));
+  await runMutate(SHARD, dirty.deps);
+  expect(dirty.out[0]).toBe(`mutate: HEAD ${SHA.slice(0, 7)} (uncommitted changes are not mutated)\n`);
+  const clean = fakes();
+  await runMutate(SHARD, clean.deps);
+  expect(clean.out[0]).toBe(`mutate: HEAD ${SHA.slice(0, 7)}\n`);
+});
+
+it("prints the install line when the clone has no Stryker", async () => {
+  const f = fakes(sim({ installed: false }));
+  expect(await runMutate(SHARD, f.deps)).toBe(1);
+  expect(f.err.join("")).toBe(INSTALL);
+  expect(f.calls.at(-1)).toBe(`rm ${BASE}`);
+});
+
+it("prints Stryker's lines under the failed dry run", async () => {
+  const f = fakes(sim({ stryker: { code: 1, output: "FAIL src/a.test.ts > adds\n", report: {} } }));
+  expect(await runMutate(SHARD, f.deps)).toBe(1);
+  expect(f.err.join("")).toBe(
+    "repo mutate: the tests failed before any mutant ran; fix them first\nFAIL src/a.test.ts > adds\n",
+  );
+});
+
+it("names the glob when no tracked file matches, before any clone", async () => {
+  const f = fakes(sim({ tracked: ["docs/x.ts"] }));
+  expect(await runMutate(SHARD, f.deps)).toBe(1);
+  expect(f.err.join("")).toBe(
+    "repo mutate: no tracked file matches coverage.mutate (src/**/*.ts); set coverage.mutate in workerstack.config.ts\n",
+  );
+  expect(f.calls.some((c) => c.includes("clone") || c.startsWith("mkdtemp"))).toBe(false);
+});
+
+it("refuses a bad --shard before touching git, and prints the config's errors", async () => {
+  const bad = fakes();
+  expect(await runMutate(["--shard", "9/8"], bad.deps)).toBe(1);
+  expect(bad.err.join("")).toBe("repo mutate: --shard takes i/n with 1 <= i <= n, such as 2/8\n");
+  expect(bad.calls).toEqual([]);
+  const noConfig = fakes(sim({ config: ["workerstack.config.ts: no default export"] }));
+  expect(await runMutate(SHARD, noConfig.deps)).toBe(1);
+  expect(noConfig.err.join("")).toBe("repo mutate: workerstack.config.ts: no default export\n");
+});
+
+it("says so when the directory is no git repository", async () => {
+  const f = fakes(sim({ gitFails: "rev-parse" }));
+  expect(await runMutate(SHARD, f.deps)).toBe(1);
+  expect(f.err.join("")).toBe(`repo mutate: ${ROOT} has no commit to mutate: boom\n`);
+});

package/cli/mutate.ts

@@ -0,0 +1,64 @@
+/**
+ * `repo mutate`: runs StrykerJS under bun, in place, in a throwaway `git clone --shared` of HEAD so no mutant can touch
+ * the checkout, over the tracked files matching `coverage.mutate` or shard `i/n` of them, and writes a report of every
+ * file's kills and survivors. A whole run holds each package to its floor in `coverage.mutationFloors`; a shard checks
+ * none, and `check <dir>` merges a run's shard reports and does. A typed path is relative to the current directory; the default report is under the repo root.
+ */
+import path from "node:path";
+import { parseArgs, type Shard } from "./mutate-args.ts";
+import { checkReports } from "./check-reports.ts";
+import { fail, type MutateConfig, type MutateDeps } from "./mutate-deps.ts";
+import { selectFiles } from "./mutate-files.ts";
+import { judgeRun, plural } from "./mutate-floors.ts";
+import { realDeps } from "./mutate-real-deps.ts";
+import { survivorCount } from "./mutate-report.ts";
+import { runInClone } from "./mutate-run.ts";
+import { DEFAULT_REPORT, FAILED, JSON_INDENT, NEWLINE, OK, SHORT_SHA } from "./mutate.constants.ts";
+
+const NOTE = "(uncommitted changes are not mutated)";
+const whole = (shard: Shard): boolean => shard.total === 1;
+
+/** The commit to mutate and the tracked files to mutate in it, after saying the commit; or the failing exit code. */
+function target(config: MutateConfig, deps: MutateDeps): { sha: string; files: string[] } | number {
+  const head = deps.git(config.root, ["rev-parse", "HEAD"]);
+  if (head.code !== 0) return fail(deps, `${config.root} has no commit to mutate: ${head.stderr.trim()}`);
+  const sha = head.stdout.trim();
+  const dirty = deps.git(config.root, ["status", "--porcelain"]).stdout.trim() !== "";
+  deps.out(`mutate: HEAD ${sha.slice(0, SHORT_SHA)}${dirty ? ` ${NOTE}` : ""}${NEWLINE}`);
+  const tracked = deps.git(config.root, ["ls-tree", "-r", "--name-only", "HEAD"]).stdout.split(NEWLINE);
+  const files = selectFiles(tracked, config.mutate);
+  if (files.length > 0) return { sha, files };
+  const globs = config.mutate.join(", ");
+  return fail(deps, `no tracked file matches coverage.mutate (${globs}); set coverage.mutate in workerstack.config.ts`);
+}
+
+async function runShard(shard: Shard, typed: string | undefined, deps: MutateDeps): Promise<number> {
+  const config = await deps.config(deps.cwd);
+  if (Array.isArray(config)) return fail(deps, ...config);
+  const found = target(config, deps);
+  if (typeof found === "number") return found;
+  if (whole(shard)) deps.out(`mutate: ${plural(found.files.length, "file")}, shard 1/1${NEWLINE}`);
+  const report = typed ?? DEFAULT_REPORT;
+  const reportFile = typed === undefined ? path.join(config.root, report) : path.resolve(deps.cwd, report);
+  const ran = runInClone({ root: config.root, sha: found.sha, files: found.files, shard }, deps);
+  if (ran === null) return FAILED;
+  const json = `${JSON.stringify(ran.report, null, JSON_INDENT)}${NEWLINE}`;
+  deps.fs.write(reportFile, json);
+  if (whole(shard)) return judgeRun({ report: ran.report, config, shown: report }, deps);
+  const files = plural(ran.files, "file");
+  const survivors = plural(survivorCount(ran.report.files), "survivor");
+  deps.out(`mutate: ${files}, shard ${shard.index}/${shard.total}, ${survivors} in ${report}${NEWLINE}`);
+  return OK;
+}
+
+/** `repo mutate` with its collaborators injected; the exit code. */
+export function runMutate(argv: string[], deps: MutateDeps): Promise<number> {
+  const args = parseArgs(argv);
+  if (args.kind === "error") return Promise.resolve(fail(deps, args.line));
+  return args.kind === "check" ? checkReports(args.dir, args.write, deps) : runShard(args.shard, args.report, deps);
+}
+
+/** The registry entry: `repo mutate` in the current directory. */
+export function main(argv: string[]): Promise<number> {
+  return runMutate(argv, realDeps(process.cwd()));
+}

package/cli/nested-vitest-flags.ts

@@ -0,0 +1,8 @@
+/**
+ * Passed to every vitest that repo spawns inside a project. Vitest 5 keeps transformed modules in the workspace
+ * root's `.vitest-cache` and, at start, wipes the whole directory when the project's lockfile hash differs from the
+ * one recorded there (`ensureCacheIntegrity` in vitest's `cli-api` chunk). A project that links the packages of the
+ * run that spawned it shares that directory, so the nested run would delete entries the outer run is still reading
+ * and fail it with ENOENT at import.
+ */
+export const NESTED_VITEST_FLAGS: readonly string[] = ["--fsModuleCache=false"];

package/cli/nightly-config.constants.ts

@@ -0,0 +1,14 @@
+/** The limits and texts of the `nightly` config section. */
+
+export const MIN_SHARDS = 1;
+export const MAX_SHARDS = 32;
+/** A secret name: upper-case letters, digits and underscores, not starting with a digit. */
+export const SECRET_NAME: RegExp = /^[A-Z_][A-Z0-9_]*$/;
+/** Names GitHub reserves for itself. */
+export const RESERVED_PREFIX = "GITHUB_";
+export const SHARDS_ERROR: string = `must be a whole number from ${MIN_SHARDS} to ${MAX_SHARDS}`;
+export const SECRET_ERROR: string = `must be a secret name like CLOUDFLARE_API_TOKEN, not starting with ${RESERVED_PREFIX}`;
+export const SECRETS_ERROR = "must be a list of secret names";
+export const SECTION_ERROR = "must be an object like { shards: 8, secrets: [...] }";
+/** The repeat count that reads as "twice". */
+export const TWICE = 2;