lazycodex-ai 5.1.54 → 5.1.55

package/packages/shared-skills/skills/programming/scripts/typescript/check-test-junk-rules.ts

@@ -0,0 +1,140 @@
+import { extname } from "node:path"
+
+export type RuleId =
+  | "source-grep"
+  | "prose-pin"
+  | "fixed-sleep"
+  | "focused"
+  | "skipped"
+  | "self-compare"
+  | "lower-bound"
+
+export type Language = "typescript" | "python" | "rust" | "go"
+
+export type ReadKind = "prose" | "source"
+
+export type LineRule = {
+  readonly rule: RuleId
+  readonly languages: readonly Language[]
+  readonly pattern: RegExp
+  readonly message: string
+}
+
+export const RULE_IDS: readonly RuleId[] = [
+  "source-grep",
+  "prose-pin",
+  "fixed-sleep",
+  "focused",
+  "skipped",
+  "self-compare",
+  "lower-bound",
+]
+
+export function languageOf(file: string): Language | undefined {
+  switch (extname(file)) {
+    case ".ts":
+    case ".tsx":
+    case ".mts":
+    case ".cts":
+    case ".js":
+    case ".jsx":
+    case ".mjs":
+    case ".cjs":
+      return "typescript"
+    case ".py":
+      return "python"
+    case ".rs":
+      return "rust"
+    case ".go":
+      return "go"
+    default:
+      return undefined
+  }
+}
+
+const SLEEP_MESSAGE = "fixed sleep: wait on the event or state change, not on the clock"
+const SKIP_MESSAGE = "skipped test: fix the test or delete it with its proof; never park it"
+const LOWER_BOUND_MESSAGE = "lower bound on a cardinality: removing one item stays green; pin the exact set"
+
+export const LINE_RULES: readonly LineRule[] = [
+  {
+    rule: "fixed-sleep",
+    languages: ["typescript"],
+    pattern: /\bsetTimeout\s*\(\s*(resolve|res|r|done|cb)\s*,\s*[1-9]|\bawait\s+(Bun\.)?sleep\s*\(\s*[1-9]|new Promise\s*\(\s*\(?\s*\w*\s*\)?\s*=>\s*setTimeout\s*\(\s*\w+\s*,\s*[1-9]/,
+    message: SLEEP_MESSAGE,
+  },
+  { rule: "fixed-sleep", languages: ["python"], pattern: /\btime\.sleep\s*\(|\bawait\s+(asyncio|anyio|trio)\.sleep\s*\(\s*[0-9]/, message: SLEEP_MESSAGE },
+  { rule: "fixed-sleep", languages: ["rust"], pattern: /\bthread::sleep\s*\(|\btokio::time::sleep\s*\(/, message: SLEEP_MESSAGE },
+  { rule: "fixed-sleep", languages: ["go"], pattern: /\btime\.Sleep\s*\(/, message: SLEEP_MESSAGE },
+  {
+    rule: "focused",
+    languages: ["typescript"],
+    pattern: /\b(test|it|describe)\.only\s*\(/,
+    message: "focused test: the rest of the suite is skipped silently",
+  },
+  { rule: "skipped", languages: ["typescript"], pattern: /\b(test|it|describe)\.skip\s*\(|\b(xit|xdescribe|xtest)\s*\(/, message: SKIP_MESSAGE },
+  { rule: "skipped", languages: ["python"], pattern: /@pytest\.mark\.skip\b|\bpytest\.skip\s*\(|\bunittest\.skip\b/, message: SKIP_MESSAGE },
+  { rule: "skipped", languages: ["rust"], pattern: /#\[ignore\b/, message: SKIP_MESSAGE },
+  { rule: "skipped", languages: ["go"], pattern: /\bt\.Skip(f|Now)?\s*\(/, message: SKIP_MESSAGE },
+  {
+    rule: "lower-bound",
+    languages: ["typescript"],
+    pattern: /\.(length|size|count)\s*\)\s*\.(toBeGreaterThan\s*\(\s*[1-9]|toBeGreaterThanOrEqual\s*\(\s*([2-9]|\d{2,}))/,
+    message: LOWER_BOUND_MESSAGE,
+  },
+  {
+    rule: "lower-bound",
+    languages: ["python"],
+    pattern: /\bassert\s+len\s*\(.+\)\s*(>\s*[1-9]|>=\s*([2-9]|\d{2,}))/,
+    message: LOWER_BOUND_MESSAGE,
+  },
+]
+
+export const SELF_COMPARE: Readonly<Record<Language, RegExp>> = {
+  typescript: /\bexpect\s*\(\s*([^()]+?)\s*\)\s*\.(toBe|toEqual|toStrictEqual)\s*\(\s*\1\s*\)/,
+  python: /\bassert\s+([A-Za-z_][\w.]*)\s*==\s*\1\s*(#|$)/,
+  rust: /\bassert_eq!\s*\(\s*([^,()]+?)\s*,\s*\1\s*\)/,
+  go: /\b(Equal|Exactly)\s*\(\s*t\s*,\s*([^,()]+?)\s*,\s*\2\s*\)/,
+}
+
+const SOURCE_EXTENSIONS = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|py|rs|go)$/
+const PROSE_EXTENSIONS = /\.(md|mdc|txt|prompt)$/
+const READ_ASSIGNMENT = /\b(?:const|let|var)\s+(\w+)\s*=\s*(?:await\s+)?(?:\w+\.)?(?:readFileSync|readFile|readTextSync|Bun\.file|open|read_text|read)\s*\(([^\n]*)$/
+const PYTHON_READ_ASSIGNMENT = /^\s*(\w+)\s*=\s*(?:\w+\.)?(?:open|Path|read_text)\s*\(([^\n]*)$/
+const STRING_LITERAL = /["'`]([^"'`]+)["'`]/g
+
+function readKindOf(callArguments: string): ReadKind | undefined {
+  for (const literal of callArguments.matchAll(STRING_LITERAL)) {
+    const value = literal[1] ?? ""
+    if (PROSE_EXTENSIONS.test(value)) return "prose"
+    if (SOURCE_EXTENSIONS.test(value)) return "source"
+  }
+  return undefined
+}
+
+export function collectReadVariables(lines: readonly string[], language: Language): ReadonlyMap<string, ReadKind> {
+  const variables = new Map<string, ReadKind>()
+  const pattern = language === "python" ? PYTHON_READ_ASSIGNMENT : READ_ASSIGNMENT
+  for (const line of lines) {
+    const match = pattern.exec(line)
+    if (match === null) continue
+    const kind = readKindOf(match[2] ?? "")
+    if (kind !== undefined && match[1] !== undefined) variables.set(match[1], kind)
+  }
+  return variables
+}
+
+export function greppedVariable(line: string, language: Language): string | undefined {
+  if (language === "python") {
+    return /\bassert\s+(?:not\s+)?["'][^"']*["']\s+(?:not\s+)?in\s+(\w+)/.exec(line)?.[1]
+  }
+  return (
+    /\bexpect\s*\(\s*(\w+)\s*\)\s*(?:\.not)?\.(?:toContain|toMatch|toMatchSnapshot|toMatchInlineSnapshot|toInclude|toStartWith|toEndWith)\s*\(/.exec(line)?.[1] ??
+    /\bexpect\s*\(\s*(\w+)\.(?:includes|match|indexOf|search)\s*\(/.exec(line)?.[1]
+  )
+}
+
+export const READ_RULE_MESSAGES: Readonly<Record<ReadKind, { readonly rule: RuleId; readonly message: string }>> = {
+  prose: { rule: "prose-pin", message: "wording of a prompt/skill/doc is pinned; assert a machine-consumed value or write no test" },
+  source: { rule: "source-grep", message: "a source file is grepped as text; drive the module and assert behavior" },
+}

package/packages/shared-skills/skills/programming/scripts/typescript/check-test-junk.test.ts

@@ -0,0 +1,125 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test"
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import type { Finding, RuleId } from "./check-test-junk"
+
+const script = join(import.meta.dir, "check-test-junk.ts")
+let root = ""
+
+async function run(args: readonly string[]): Promise<{ readonly code: number; readonly findings: readonly Finding[] }> {
+  const child = Bun.spawn([process.execPath, script, "--json", ...args], { cwd: root, stdout: "pipe", stderr: "pipe" })
+  const [stdout, code] = await Promise.all([new Response(child.stdout).text(), child.exited])
+  const parsed: { readonly findings: readonly Finding[] } = JSON.parse(stdout)
+  return { code, findings: parsed.findings }
+}
+
+const JUNK_TS = `import { readFileSync } from "node:fs"
+test("source grep", () => {
+  const source = readFileSync("src/parser.ts", "utf8")
+  expect(source).toContain("export function parse")
+})
+test("prose pin", () => {
+  const skill = readFileSync("SKILL.md", "utf8")
+  expect(skill).toContain("You are a senior engineer")
+})
+test("sleeps", async () => {
+  await new Promise((resolve) => setTimeout(resolve, 500))
+})
+test.only("focused", () => {})
+it.skip("parked", () => {})
+test("self compare", () => {
+  expect(config.prompt).toEqual(config.prompt)
+})
+test("lower bound", () => {
+  expect(masked.length).toBeGreaterThanOrEqual(3)
+})
+test("opted out", async () => {
+  await new Promise((resolve) => setTimeout(resolve, 50)) // test-junk-ok: fixed-sleep debounce window is the behavior under test
+})
+`
+
+const CLEAN_TS = `import { readFileSync } from "node:fs"
+test("parses a date when the input has a timezone", () => {
+  expect(parse("2026-01-01T00:00:00Z")).toEqual({ year: 2026 })
+})
+test("the packaged skill equals its source", () => {
+  const source = readFileSync("skills/x/SKILL.md", "utf8")
+  const packaged = readFileSync("dist/skills/x/SKILL.md", "utf8")
+  expect(packaged).toBe(source)
+})
+test("the bundle keeps the runtime entry", () => {
+  const bundle = readFileSync("dist/index.js", "utf8")
+  expect(bundle.length).toBeGreaterThan(0)
+  expect(parseExports(bundle)).toEqual(["main"])
+})
+test("yields one tick before asserting", async () => {
+  await new Promise((resolve) => setTimeout(resolve, 0))
+  expect(flushed).toBe(true)
+})
+`
+
+const JUNK_PY = `import time
+def test_sleeps():
+    time.sleep(1)
+def test_lower():
+    assert len(items) >= 2
+def test_lower_nested():
+    assert len(select(items)) > 1
+def test_prose():
+    body = Path("SKILL.md").read_text()
+    assert "You are" in body
+`
+
+const JUNK_GO = `func TestSleeps(t *testing.T) {
+\ttime.Sleep(100 * time.Millisecond)
+\tt.Skip("flaky")
+}
+`
+
+describe("#given test files with mechanically detectable junk", () => {
+  beforeAll(() => {
+    root = mkdtempSync(join(process.env.RUN_TMP ?? tmpdir(), "check-test-junk-"))
+    mkdirSync(join(root, "src"), { recursive: true })
+    writeFileSync(join(root, "src", "junk.test.ts"), JUNK_TS)
+    writeFileSync(join(root, "src", "clean.test.ts"), CLEAN_TS)
+    writeFileSync(join(root, "src", "test_junk.py"), JUNK_PY)
+    writeFileSync(join(root, "src", "junk_test.go"), JUNK_GO)
+    writeFileSync(join(root, "src", "parser.ts"), "export const parse = () => readFileSync('x.ts')\n")
+  })
+
+  afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+  test("#when the TypeScript fixture is scanned #then every class is reported at its line and the opted-out line is not", async () => {
+    const { code, findings } = await run(["src/junk.test.ts"])
+    const byRule = new Map<RuleId, number[]>()
+    for (const finding of findings) byRule.set(finding.rule, [...(byRule.get(finding.rule) ?? []), finding.line])
+    expect(code).toBe(1)
+    expect(byRule.get("source-grep")).toEqual([4])
+    expect(byRule.get("prose-pin")).toEqual([8])
+    expect(byRule.get("fixed-sleep")).toEqual([11])
+    expect(byRule.get("focused")).toEqual([13])
+    expect(byRule.get("skipped")).toEqual([14])
+    expect(byRule.get("self-compare")).toEqual([16])
+    expect(byRule.get("lower-bound")).toEqual([19])
+  })
+
+  test("#when Python and Go fixtures are scanned #then their sleep, skip and lower-bound forms are reported", async () => {
+    const { findings } = await run(["src/test_junk.py", "src/junk_test.go"])
+    expect(findings.map((finding) => [finding.file.split("/").at(-1), finding.line, finding.rule])).toEqual([
+      ["test_junk.py", 3, "fixed-sleep"],
+      ["test_junk.py", 5, "lower-bound"],
+      ["test_junk.py", 7, "lower-bound"],
+      ["test_junk.py", 10, "prose-pin"],
+      ["junk_test.go", 2, "fixed-sleep"],
+      ["junk_test.go", 3, "skipped"],
+    ])
+  })
+
+  test("#when a clean test file and a production file are scanned #then nothing is reported and the exit code is 0", async () => {
+    const { code, findings } = await run(["src/clean.test.ts", "src/parser.ts"])
+    expect(findings).toEqual([])
+    expect(code).toBe(0)
+  })
+})

package/packages/shared-skills/skills/programming/scripts/typescript/check-test-junk.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env bun
+/**
+ * Flag test files for the junk classes a regex can see (the rest need a reader):
+ *
+ *   source-grep    - a value read from a source file (.ts/.js/.py/.rs/.go/...) is grepped
+ *                    (toContain / toMatch / includes / `in`); byte equality between two reads is not flagged
+ *   prose-pin      - a value read from a prompt/skill/markdown file has its wording pinned
+ *                    (toContain / not.toContain / toMatch / toMatchSnapshot / `in`)
+ *   fixed-sleep    - setTimeout-as-wait, sleep(N), time.sleep, thread::sleep, time.Sleep
+ *   focused        - test.only / it.only / describe.only (a focused test silently skips the suite)
+ *   skipped        - .skip / xit / xdescribe / @pytest.mark.skip / #[ignore] / t.Skip
+ *   self-compare   - expect(x).toBe(x) / assert x == x / assert_eq!(x, x)
+ *   lower-bound    - toBeGreaterThan(N>=1) / toBeGreaterThanOrEqual(N>=2) on a length/size/count
+ *                    (removing one item stays green; a plain non-empty check is not flagged)
+ *
+ * Opt out per line with a trailing comment naming the rule and the reason:
+ *   // test-junk-ok: fixed-sleep debounce window is the behavior under test
+ *
+ * Usage:
+ *   bun run scripts/typescript/check-test-junk.ts [--json] <file-or-dir>...
+ *
+ * Exit codes: 0 no findings, 1 findings, 2 input error.
+ * Each class is explained in references/testing/junk-classes.md; a finding here is a candidate
+ * to prove with references/testing/README.md "test your test", not an automatic deletion.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { basename, extname, join } from "node:path"
+import process from "node:process"
+
+import {
+  collectReadVariables,
+  greppedVariable,
+  languageOf,
+  LINE_RULES,
+  READ_RULE_MESSAGES,
+  RULE_IDS,
+  SELF_COMPARE,
+  type RuleId,
+} from "./check-test-junk-rules"
+
+export type { RuleId } from "./check-test-junk-rules"
+
+export type Finding = {
+  readonly file: string
+  readonly line: number
+  readonly rule: RuleId
+  readonly message: string
+}
+
+const EXCLUDED_DIRS: ReadonlySet<string> = new Set([".git", "node_modules", "dist", "build", "target", "__pycache__", ".venv", "vendor"])
+
+const TEST_FILE_PATTERNS: readonly RegExp[] = [
+  /\.(test|spec)\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/,
+  /_test\.go$/,
+  /(^|\/)test_[^/]*\.py$/,
+  /(^|\/)[^/]*_test\.py$/,
+  /\.rs$/,
+]
+
+const OPT_OUT = /test-junk-ok:\s*([a-z-]+)/
+
+function isTestFile(file: string): boolean {
+  if (!TEST_FILE_PATTERNS.some((pattern) => pattern.test(file))) return false
+  // Rust unit tests live inside source files; only files declaring a test module count.
+  return extname(file) !== ".rs" || /#\[cfg\(test\)\]|#\[test\]/.test(readFileSync(file, "utf8"))
+}
+
+function* walk(root: string): Generator<string> {
+  if (statSync(root).isFile()) {
+    yield root
+    return
+  }
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!EXCLUDED_DIRS.has(entry.name)) yield* walk(join(root, entry.name))
+    } else if (entry.isFile()) {
+      yield join(root, entry.name)
+    }
+  }
+}
+
+function optedOut(line: string, rule: RuleId): boolean {
+  const match = OPT_OUT.exec(line)
+  return match !== null && match[1] === rule
+}
+
+function scanFile(file: string): readonly Finding[] {
+  const language = languageOf(file)
+  if (language === undefined) return []
+  const lines = readFileSync(file, "utf8").split("\n")
+  const readVariables = collectReadVariables(lines, language)
+  const findings: Finding[] = []
+  const report = (line: number, rule: RuleId, message: string): void => {
+    if (!optedOut(lines[line - 1] ?? "", rule)) findings.push({ file, line, rule, message })
+  }
+
+  lines.forEach((source, index) => {
+    const line = index + 1
+    for (const rule of LINE_RULES) {
+      if (rule.languages.includes(language) && rule.pattern.test(source)) report(line, rule.rule, rule.message)
+    }
+    if (SELF_COMPARE[language].test(source)) {
+      report(line, "self-compare", "the expected value is the value under test; derive it from the input")
+    }
+    const grepped = greppedVariable(source, language)
+    const kind = grepped === undefined ? undefined : readVariables.get(grepped)
+    if (kind !== undefined) report(line, READ_RULE_MESSAGES[kind].rule, READ_RULE_MESSAGES[kind].message)
+  })
+  return findings
+}
+
+function scan(paths: readonly string[]): readonly Finding[] {
+  const findings: Finding[] = []
+  for (const root of paths) {
+    for (const file of walk(root)) {
+      if (isTestFile(file)) findings.push(...scanFile(file))
+    }
+  }
+  return findings
+}
+
+function main(argv: readonly string[]): number {
+  const json = argv.includes("--json")
+  const paths = argv.filter((arg) => arg !== "--json")
+  if (paths.length === 0) {
+    console.error(`usage: ${basename(import.meta.path)} [--json] <file-or-dir>...`)
+    return 2
+  }
+  for (const path of paths) {
+    try {
+      statSync(path)
+    } catch {
+      console.error(`error: ${path} does not exist`)
+      return 2
+    }
+  }
+  const findings = scan(paths)
+  if (json) {
+    console.log(JSON.stringify({ findings, rules: RULE_IDS }, null, 2))
+  } else {
+    for (const finding of findings) console.log(`${finding.file}:${finding.line} ${finding.rule} ${finding.message}`)
+    console.log(findings.length === 0 ? "check-test-junk: no findings" : `check-test-junk: ${findings.length} finding(s)`)
+  }
+  return findings.length === 0 ? 0 : 1
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)))

package/packages/shared-skills/skills/programming/scripts/typescript/mutation-proof.test.ts

@@ -0,0 +1,43 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { MutationError, runMutation } from "./mutation-proof"
+
+let root = ""
+const OWNER = "export const add = (a: number, b: number): number => a + b\n"
+
+describe("#given a production owner and a test that exercises it", () => {
+  beforeAll(() => {
+    root = mkdtempSync(join(process.env.RUN_TMP ?? tmpdir(), "mutation-proof-"))
+    writeFileSync(join(root, "owner.ts"), OWNER)
+    writeFileSync(
+      join(root, "owner.test.ts"),
+      'import { expect, test } from "bun:test"\nimport { add } from "./owner"\ntest("adds", () => { expect(add(1, 2)).toBe(3) })\n',
+    )
+  })
+
+  afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+  test("#when the owner is broken #then the test goes red and the owner is restored byte for byte", async () => {
+    const result = await runMutation({
+      cwd: root,
+      file: "owner.ts",
+      find: "a + b",
+      replace: "a - b",
+      tests: [{ label: "candidate", command: [process.execPath, "test", "owner.test.ts"] }],
+    })
+    expect(result.outcomes.map((outcome) => [outcome.label, outcome.verdict])).toEqual([["candidate", "red"]])
+    expect(result.restoredSha256).toBe(result.originalSha256)
+    expect(readFileSync(join(root, "owner.ts"), "utf8")).toBe(OWNER)
+  })
+
+  test("#when the find text is not unique or empty #then it refuses before touching the file", async () => {
+    for (const [find, kind] of [["a", "FIND_NOT_UNIQUE"], ["", "FIND_EMPTY"]] as const) {
+      const attempt = runMutation({ cwd: root, file: "owner.ts", find, replace: "x", tests: [] })
+      await expect(attempt).rejects.toMatchObject({ kind })
+    }
+    expect(readFileSync(join(root, "owner.ts"), "utf8")).toBe(OWNER)
+  })
+})

package/packages/shared-skills/skills/programming/scripts/typescript/mutation-proof.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env bun
+/**
+ * Prove that a test can fail: apply one exact-match edit to a production file, run each test
+ * command against the mutated owner, then restore the original bytes and verify their hash.
+ *
+ * Usage:
+ *   bun run scripts/typescript/mutation-proof.ts --file <path> --find <text> --replace <text> \
+ *     --test '<label>=<argv...>' [--test ...] [--cwd <dir>] [--json]
+ *
+ *   --test takes "label=command words"; the command is split on spaces and quoting is not
+ *   supported, so select a test by a pattern without spaces or run the whole file.
+ *
+ * Verdicts per test: red (exit != 0, the test caught the mutation) or green (exit 0, it did not).
+ * The owner is restored on success, on a thrown error, and on SIGINT/SIGTERM.
+ * Exit codes: 0 ran and restored, 1 the find text is empty or did not match exactly once or the
+ * restore hash differed (the file was still restored), 2 usage, 130/143 interrupted and restored.
+ * Read references/testing/junk-classes.md "Proof rule" for how to read a candidate/keeper pair.
+ */
+
+import { createHash } from "node:crypto"
+import { readFileSync, writeFileSync } from "node:fs"
+import { resolve } from "node:path"
+import process from "node:process"
+import { parseArgs } from "node:util"
+
+export type MutationTest = { readonly label: string; readonly command: readonly string[] }
+
+export type MutationOutcome = {
+  readonly label: string
+  readonly command: readonly string[]
+  readonly exitCode: number
+  readonly verdict: "red" | "green"
+  readonly outputTail: string
+}
+
+export type MutationResult = {
+  readonly file: string
+  readonly find: string
+  readonly replace: string
+  readonly originalSha256: string
+  readonly restoredSha256: string
+  readonly outcomes: readonly MutationOutcome[]
+}
+
+export class MutationError extends Error {
+  constructor(
+    readonly kind: "FIND_EMPTY" | "FIND_NOT_UNIQUE" | "RESTORE_MISMATCH",
+    message: string,
+  ) {
+    super(message)
+    this.name = "MutationError"
+  }
+}
+
+const sha256 = (bytes: Uint8Array): string => createHash("sha256").update(bytes).digest("hex")
+
+async function runCaptured(command: readonly string[], cwd: string): Promise<{ readonly exitCode: number; readonly outputTail: string }> {
+  const child = Bun.spawn([...command], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  const lines = `${stdout}${stderr}`.trimEnd().split("\n")
+  return { exitCode, outputTail: lines.slice(-30).join("\n") }
+}
+
+export async function runMutation(options: {
+  readonly cwd: string
+  readonly file: string
+  readonly find: string
+  readonly replace: string
+  readonly tests: readonly MutationTest[]
+}): Promise<MutationResult> {
+  if (options.find.length === 0) throw new MutationError("FIND_EMPTY", `${options.file}: find text is empty`)
+  const full = resolve(options.cwd, options.file)
+  const original = readFileSync(full)
+  const text = original.toString("utf8")
+  const occurrences = text.split(options.find).length - 1
+  if (occurrences !== 1) {
+    throw new MutationError("FIND_NOT_UNIQUE", `${options.file}: find matched ${occurrences} times (need exactly 1)`)
+  }
+  const originalSha256 = sha256(original)
+  const outcomes: MutationOutcome[] = []
+  const restoreOnSignal = (signal: NodeJS.Signals): void => {
+    writeFileSync(full, original)
+    process.exit(signal === "SIGINT" ? 130 : 143)
+  }
+  process.on("SIGINT", restoreOnSignal)
+  process.on("SIGTERM", restoreOnSignal)
+  try {
+    writeFileSync(full, text.replace(options.find, () => options.replace))
+    for (const test of options.tests) {
+      const run = await runCaptured(test.command, options.cwd)
+      outcomes.push({
+        label: test.label,
+        command: test.command,
+        exitCode: run.exitCode,
+        verdict: run.exitCode === 0 ? "green" : "red",
+        outputTail: run.outputTail,
+      })
+    }
+  } finally {
+    writeFileSync(full, original)
+    process.off("SIGINT", restoreOnSignal)
+    process.off("SIGTERM", restoreOnSignal)
+  }
+  const restoredSha256 = sha256(readFileSync(full))
+  if (restoredSha256 !== originalSha256) {
+    throw new MutationError("RESTORE_MISMATCH", `${options.file} not restored byte for byte`)
+  }
+  return { file: options.file, find: options.find, replace: options.replace, originalSha256, restoredSha256, outcomes }
+}
+
+function parseTest(spec: string): MutationTest | undefined {
+  const separator = spec.indexOf("=")
+  if (separator <= 0) return undefined
+  const label = spec.slice(0, separator)
+  const command = spec
+    .slice(separator + 1)
+    .split(" ")
+    .filter((word) => word.length > 0)
+  return command.length === 0 ? undefined : { label, command }
+}
+
+function usage(): number {
+  console.error(
+    "usage: mutation-proof.ts --file <path> --find <text> --replace <text> --test '<label>=<argv...>' [--test ...] [--cwd <dir>] [--json]",
+  )
+  return 2
+}
+
+async function main(argv: readonly string[]): Promise<number> {
+  const { values } = parseArgs({
+    args: [...argv],
+    options: {
+      file: { type: "string" },
+      find: { type: "string" },
+      replace: { type: "string" },
+      test: { type: "string", multiple: true },
+      cwd: { type: "string", default: process.cwd() },
+      json: { type: "boolean", default: false },
+    },
+    strict: true,
+  })
+  if (values.file === undefined || values.find === undefined || values.replace === undefined || values.test === undefined) {
+    return usage()
+  }
+  const tests: MutationTest[] = []
+  for (const spec of values.test) {
+    const parsed = parseTest(spec)
+    if (parsed === undefined) return usage()
+    tests.push(parsed)
+  }
+  try {
+    const result = await runMutation({
+      cwd: values.cwd ?? process.cwd(),
+      file: values.file,
+      find: values.find,
+      replace: values.replace,
+      tests,
+    })
+    if (values.json) {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      for (const outcome of result.outcomes) console.log(`${outcome.label}: ${outcome.verdict} (exit ${outcome.exitCode})`)
+      console.log(`restored ${result.file} (sha256 ${result.restoredSha256.slice(0, 12)})`)
+    }
+    return 0
+  } catch (error) {
+    if (error instanceof MutationError) {
+      console.error(`mutation-proof: ${error.kind}: ${error.message}`)
+      return 1
+    }
+    throw error
+  }
+}
+
+if (import.meta.main) process.exit(await main(process.argv.slice(2)))