probatio 0.1.0 → 0.1.3

package/README.md

@@ -1,21 +1,38 @@
 # Probatio
 
-Probatio (Latin: a testing, a proof) is a free testing toolkit under the MIT license, built for AI agents
-(Claude, Grok, ChatGPT, others), working alone or as swarms. Every claim it makes is checkable.
-It remembers what was fixed so agents with small context do not redo or undo work, and it shows
-which tests already touch a change.
+[![npm version](https://img.shields.io/npm/v/probatio)](https://www.npmjs.com/package/probatio)
 
-Status (2026-10-06): `mutate run` discovers the project suite and scores it. Node, pytest, C (when the binary was built with LLVM coverage), Go, Maven/Java, Rust, and C# collect a line map on the baseline. A line no test executes is `no coverage`, and the suite is not started. A line that runs only in a child process the map cannot see is `no coverage`. A suite with no line map, a baseline of 5 seconds or more, and more than 30 mutants stops before the first mutant. `verify-change` names the tests the line map ran. `ran` stays the direct-importer list. `mutate tally` does not delete a test. A kill is an assertion the suite already had. A sealed miss means the suite did not see the bug. The kill count is not a merge gate. On Commons CSV (Apache-2.0, commit `2c83a308`), two sealed runs agreed: with the new test file hidden, `CSVFormatTest.testFormatThrowsNullPointerException` failed on the reverted printer. `deletedTests` stayed 0. That older JUnit platform did not write a line map, so the first pass was the whole suite and confirm reran the older test. Auspex, markupsafe, and a hand-planted fixture are not that result. The package version in this repository is 0.1.0. The copy on npm is 0.0.5. The BugsInPy search row is still open, and the rows that apply only when a sealed run misses do not apply, because this catch held. The MCP server speaks one JSON object per line and returns the same JSON as the CLI.
+Probatio scores a test suite by the bugs it already catches. A kill is an assertion the suite had. The kill count is not a merge gate.
 
-Read in this order:
+Node 22.6 or newer:
 
-1. `HANDOFF.md` — why, the evidence from Auspex, the design, and the lessons that cost time.
-2. `FOR-GROK.md` — the builder brief: build order with acceptance tests, the agent contract,
-   memory for agents, anti-gaming, swarm protocol, traps.
-3. `seed/` — code copied from the Auspex experiment to start from (Auspex paths inside).
+```bash
+npm install probatio
+```
+
+```bash
+npx probatio mutate generate --package . --out .probatio/generate
+npx probatio mutate run --package . --patches .probatio/generate/mutants --out .probatio/runs
+npx probatio mutate tally --out .probatio/runs
+```
 
-Roles: Grok builds most of it; Claude refines and finishes. Grok keeps `NOTES-FOR-CLAUDE.md` here
-(decisions, guesses, shortcuts with file:line, acceptance output actually run).
+Each command prints one JSON object and exits 0 only when `ok` is true.
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "summary": "0 no coverage, 0 survived, 1 killed, 0 flaky, 0 timed out, 0 errored, of 1 finished.",
+  "next": "No survivor in this batch.",
+  "nextCall": { "argv": ["mutate", "tally", "--out", ".probatio/runs"] }
+}
+```
+
+Agents changing this repo should read [AGENTS.md](AGENTS.md). The MCP server is `probatio mcp`. Snippets are in the MCP section below. People building Probatio should read [docs/builders.md](docs/builders.md). Small suites live in [examples/](examples/).
+
+## Status
+
+Status (2026-10-06): `mutate run` discovers the project suite and scores it. Node, pytest, C (when the binary was built with LLVM coverage), Go, Maven/Java, Rust, C#, and Mocha collect a line map on the baseline. Mocha's map comes from its own root hooks. Loading the node:test collector under Mocha does not name Mocha tests. A line no test executes is `no coverage`, and the suite is not started. A plain Node script can write the lines it ran, and the parent test that reads that dump stores them under its own name. A child the parent does not read stays `no coverage`, and the suite is not started. A suite with no line map, a baseline of 5 seconds or more, and more than 30 mutants stops before the first mutant. `verify-change` names the tests the line map ran. It scores `src/`, a `lib/` file when the package tests import `lib/`, and a Go file beside `go.mod`. Tests, docs, `dist/`, and `node_modules` stay unseen. `ran` stays the direct-importer list. Covered mutants of one Node file run one after another inside the suite process that is already running. `--workers` stays 1. A Node test that sets its own `timeout` keeps that time when `--test-timeout-ms` is shorter. A mutant that crashes or leaves that process dirty ends it, and the next mutant starts clean. An uncovered line still does not start the suite. `mutate tally` does not delete a test. A kill is an assertion the suite already had. A sealed miss means the suite did not see the bug. The kill count is not a merge gate. On Commons CSV (Apache-2.0, commit `2c83a308`), two sealed runs agreed: with the new test file hidden, `CSVFormatTest.testFormatThrowsNullPointerException` failed on the reverted printer. `deletedTests` stayed 0. That older JUnit platform did not write a line map, so the first pass was the whole suite and confirm reran the older test. Auspex, markupsafe, and a hand-planted fixture are not that result. The package version in this repository is 0.1.3. npm latest is 0.1.2 (`29301bc`). The BugsInPy search row is still open, and the rows that apply only when a sealed run misses do not apply, because this catch held. The MCP server speaks one JSON object per line and returns the same JSON as the CLI.
 
 ## mutate
 
@@ -31,7 +48,7 @@ npx probatio mutate tally --out .probatio/runs
 
 `run` discovers the suite: `run_tests.sh`, Cargo, Go, Swift, Maven, dotnet, pytest, unittest, node:test, Mocha, then `make test` when COBOL tests sit under that Makefile. An unknown layout stops and asks for `--suite-command`. It does not compile one file and call that the suite. `make test` that would curl or wget a missing file stops, and nothing is fetched. A worktree that has no `node_modules` uses the main checkout's. Omitting `--build` runs no build. Pass `--build` with a command when the suite needs one first.
 
-Node, pytest, Go, Maven/Java, Rust, and C# collect a line map on the baseline. C collects one when LLVM coverage was instrumented. The map stores the file, the line, and the test names that hit that line. A later mutant runs only those tests (`go test -run`, Maven `-Dtest`, `cargo test`, `dotnet test --filter`). A line no test executed is `no coverage`, and the suite is not started. A child process the map cannot see is `no coverage`. A baseline of 5 seconds or more, with no line map and more than 30 mutants still pending, stops before the first mutant. `next` names that baseline and tells you to narrow `--src` or pass a smaller patch directory. A one-file C, C++, Java, COBOL, or assembly launcher is not a suite discovery returns.
+Node, pytest, Go, Maven/Java, Rust, C#, and Mocha collect a line map on the baseline. C collects one when LLVM coverage was instrumented. Mocha writes its own `{ files }` record from root hooks, keyed by the Mocha title. The node:test collector is a different file and does not name Mocha tests. The map stores the file, the line, and the test names that hit that line. A later mutant runs only those tests (`go test -run`, Maven `-Dtest`, `cargo test`, `dotnet test --filter`, Mocha `--grep`). A line no test executed is `no coverage`, and the suite is not started. A plain Node script can leave a nameless list of the lines it ran. The parent test that reads that list stores them under its own name. A child the parent does not read stays `no coverage`. Covered mutants of one Node file are applied one after another in the suite process already running, and the line map is reset between them. `--workers` stays 1. A crash or a process left dirty ends that process. The next mutant starts clean. A baseline of 5 seconds or more, with no line map and more than 30 mutants still pending, stops before the first mutant. `next` names that baseline and tells you to narrow `--src` or pass a smaller patch directory. A one-file C, C++, Java, COBOL, or assembly launcher is not a suite discovery returns.
 
 The mutant timeout is the baseline duration times 5, and at least 20 seconds, capped by `--suite-timeout-ms`. A timeout is not a kill. `--budget-ms` stops mutant work after the baseline. The first mutant still runs, except for that no-line-map stop. A kill is the test that failed, or a compiler token when the mutant did not build. Confirm is on by default and reruns the failing names. Pytest names that `-k` cannot express are passed as node ids. A usage error, including pytest exit 4, is not a kill. `verify-change` does not confirm a second time. Add `--affected` to limit the file list to tests that can see the change. The default, once a line map exists, runs the tests on the changed line.
 
@@ -81,4 +98,23 @@ Lists the tests that can see the diff, runs mutants on the changed lines, and re
 
 An item is `.probatio/queue/<id>.json`. `queue claim` renames it to `claimed/<agent>-<id>.json` with a lease. `queue reap` moves an expired lease back. `check-kill <id>` runs the tests that directly import the mutated file and confirms the killing test again. It is done only when that mutant dies and that suite is still green. `verify-change` is the edit-sized run: it uses the line map and does not confirm a second time.
 
-The MCP server speaks stdio JSON-RPC. Its one tool runs the CLI and returns that command's JSON.
+## MCP
+
+`probatio mcp` and the `probatio-mcp` bin speak stdio JSON-RPC, one JSON object per line. The tool name is `probatio`. `argv` is the CLI words. `ping` returns `{}`. An unknown method returns JSON-RPC `-32601` with the same id.
+
+```json
+{
+  "mcpServers": {
+    "probatio": {
+      "command": "probatio",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+That block is the Claude, Cursor, and Grok shape. The tool runs the CLI and returns that command's JSON. `nextCall.argv` keeps absolute paths so a later spawn does not have to expand `~`.
+
+`mutate generate` reads the commit (`HEAD` unless you pass `--commit`). `--working-tree` reads the checkout on disk and says so. `mutate run` scores the commit either way.
+
+`verify-change` does not score uncommitted edits when `--base` and `--commit` are the same. A clean empty diff says `No diff-scoped mutant.`

package/dist/cli.js

@@ -10,65 +10,82 @@ import { appendFinding, chooseSealed, fixGap, guardAllows, lineHash, loadState,
 import { git } from "./mutate/patch.js";
 import { generateMutants } from "./mutate/generate.js";
 import { runMutants } from "./mutate/run.js";
-import { LABEL_LEAK_SUMMARY, labelLeaked, readSealedLabel } from "./mutate/sealed.js";
+import { LABEL_LEAK_SUMMARY, labelLeaked, readSealedLabel, sealedTreeLeaked } from "./mutate/sealed.js";
 import { generateNext } from "./mutate/suite-decision.js";
 import { discoverSuite } from "./mutate/suites.js";
 import { tallyRun } from "./mutate/tally.js";
 import { checkKill } from "./swarm/check-kill.js";
 import { claimItem, reapClaims, seedQueue } from "./swarm/queue.js";
 import { verifyChange } from "./verify/change.js";
-const parsed = parseArgs(process.argv.slice(2));
-const [group, action] = parsed.command;
-try {
-    if (group === "mutate" && action === "generate")
-        finish(await generateCommand(parsed.flags), parsed.human);
-    if (group === "mutate" && action === "run")
-        finish(await runCommand(parsed.flags), parsed.human);
-    if (group === "mutate" && action === "sealed")
-        finish(await sealedCommand(parsed.flags), parsed.human);
-    if (group === "mutate" && action === "tally")
-        finish(tallyCommand(parsed.flags), parsed.human);
-    if (group === "ledger" && action === "build")
-        finish(await ledgerCommand(parsed.flags), parsed.human);
-    if (group === "matrix" && action === "report")
-        finish(matrixCommand(parsed.flags), parsed.human);
-    if (group === "golden" && action === "check")
-        finish(goldenCommand(parsed.flags), parsed.human);
-    if (group === "gap" && action === "fix")
-        finish(gapFixCommand(parsed.flags), parsed.human);
-    if (group === "gap" && action === "revert")
-        finish(gapRevertCommand(parsed.flags), parsed.human);
-    if (group === "guard" && action === "check")
-        finish(guardCommand(parsed.flags), parsed.human);
-    if (group === "findings" && action === "add")
-        finish(findingsCommand(parsed.flags), parsed.human);
-    if (group === "status")
-        finish(statusCommand(parsed.flags), parsed.human);
-    if (group === "seal")
-        finish(sealCommand(parsed.flags), parsed.human);
-    if (group === "queue" && action === "seed")
-        finish(queueSeedCommand(parsed.flags), parsed.human);
-    if (group === "queue" && action === "claim")
-        finish(queueClaimCommand(parsed.flags), parsed.human);
-    if (group === "queue" && action === "reap")
-        finish(queueReapCommand(parsed.flags), parsed.human);
-    if (group === "check-kill")
-        finish(await checkKillCommand(parsed.flags, action), parsed.human);
-    if (group === "verify-change")
-        finish(await verifyCommand(parsed.flags), parsed.human);
-    finish(usage(false, "Use mutate, ledger, matrix, golden, gap, guard, findings, status, queue, check-kill, or verify-change."), parsed.human);
-}
-catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    finish({
+import { nodeTooOld } from "./node-version.js";
+const tooOld = nodeTooOld(process.versions.node);
+if (tooOld) {
+    process.stdout.write(`${JSON.stringify({
         schemaVersion: SCHEMA_VERSION,
         ok: false,
-        command: `${group ?? "mutate"}.${action ?? "help"}`,
-        summary: message,
-        next: "Fix the command and run it again.",
+        command: "mutate.help",
+        summary: tooOld,
+        next: "Install Node 22.6 or newer and run the command again.",
         nextCall: null,
-    }, parsed.human);
+    })}\n`);
+    process.exit(1);
 }
+const parsed = parseArgs(process.argv.slice(2));
+const [group, action] = parsed.command;
+if (group === "mcp" && !action) {
+    await import("./mcp.js");
+}
+else
+    try {
+        if (group === "mutate" && action === "generate")
+            finish(await generateCommand(parsed.flags), parsed.human);
+        if (group === "mutate" && action === "run")
+            finish(await runCommand(parsed.flags), parsed.human);
+        if (group === "mutate" && action === "sealed")
+            finish(await sealedCommand(parsed.flags), parsed.human);
+        if (group === "mutate" && action === "tally")
+            finish(tallyCommand(parsed.flags), parsed.human);
+        if (group === "ledger" && action === "build")
+            finish(await ledgerCommand(parsed.flags), parsed.human);
+        if (group === "matrix" && action === "report")
+            finish(matrixCommand(parsed.flags), parsed.human);
+        if (group === "golden" && action === "check")
+            finish(goldenCommand(parsed.flags), parsed.human);
+        if (group === "gap" && action === "fix")
+            finish(gapFixCommand(parsed.flags), parsed.human);
+        if (group === "gap" && action === "revert")
+            finish(gapRevertCommand(parsed.flags), parsed.human);
+        if (group === "guard" && action === "check")
+            finish(guardCommand(parsed.flags), parsed.human);
+        if (group === "findings" && action === "add")
+            finish(findingsCommand(parsed.flags), parsed.human);
+        if (group === "status")
+            finish(statusCommand(parsed.flags), parsed.human);
+        if (group === "seal")
+            finish(sealCommand(parsed.flags), parsed.human);
+        if (group === "queue" && action === "seed")
+            finish(queueSeedCommand(parsed.flags), parsed.human);
+        if (group === "queue" && action === "claim")
+            finish(queueClaimCommand(parsed.flags), parsed.human);
+        if (group === "queue" && action === "reap")
+            finish(queueReapCommand(parsed.flags), parsed.human);
+        if (group === "check-kill")
+            finish(await checkKillCommand(parsed.flags, action), parsed.human);
+        if (group === "verify-change")
+            finish(await verifyCommand(parsed.flags), parsed.human);
+        finish(usage(false, "Use mutate, ledger, matrix, golden, gap, guard, findings, status, queue, check-kill, or verify-change."), parsed.human);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        finish({
+            schemaVersion: SCHEMA_VERSION,
+            ok: false,
+            command: `${group ?? "mutate"}.${action ?? "help"}`,
+            summary: message,
+            next: "Fix the command and run it again.",
+            nextCall: null,
+        }, parsed.human);
+    }
 function usage(ok, summary) {
     return {
         schemaVersion: SCHEMA_VERSION,
@@ -93,7 +110,19 @@ async function generateCommand(flags) {
         maxMutants: int(flags, "max-mutants") ?? null,
         maxMinutes: int(flags, "max-minutes") ?? null,
         skipFiles: texts(flags, "skip-file"),
+        commit: text(flags, "commit") ?? "HEAD",
+        workingTree: bool(flags, "working-tree", false),
     });
+    if (result.error) {
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            ok: false,
+            command: "mutate.generate",
+            summary: result.error,
+            next: "Commit the file, or pass --working-tree to mutate the checkout on disk. mutate run scores the commit.",
+            nextCall: null,
+        };
+    }
     if (result.violations.length > 0) {
         const first = result.violations[0];
         return {
@@ -117,9 +146,14 @@ async function generateCommand(flags) {
         summary: stopped
             ? `Stopped by the time budget after ${result.filesVisited} files. ${result.mutants.length} mutants written.`
             : `${result.mutants.length} mutants in ${result.filesVisited} files. No string-literal mutant.`,
-        next: stopped
-            ? "Narrow --src or raise --max-minutes, then run the same command."
-            : generateNext(result.mutants.length, suite ? { kind: suite.kind, command: suite.command } : null),
+        next: [
+            stopped
+                ? "Narrow --src or raise --max-minutes, then run the same command."
+                : generateNext(result.mutants.length, suite ? { kind: suite.kind, command: suite.command } : null),
+            result.source === "working-tree"
+                ? "These patches match the working tree. mutate run scores the commit, so commit the files before mutate run."
+                : "",
+        ].filter((line) => line.length > 0).join(" "),
         nextCall: result.mutants.length === 0
             ? null
             : { argv: ["mutate", "run", "--package", packageDir, "--patches", patches, "--out", path.join(outDir, "runs")] },
@@ -133,6 +167,19 @@ async function generateCommand(flags) {
     };
 }
 async function runCommand(flags, hide = null) {
+    const hidden = hide ?? texts(flags, "hide");
+    const escaped = hidden.find((rel) => rel.split(/[\\/]/).includes(".."));
+    if (escaped) {
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            ok: false,
+            command: "mutate.run",
+            summary: `--hide stays inside the package. Refused ${escaped}.`,
+            next: "Pass a relative path with no .. segment.",
+            nextCall: null,
+            killed: 0,
+        };
+    }
     const onlyNames = texts(flags, "only-test");
     if (onlyNames.some((id) => id === "::command" || id.endsWith("::command"))) {
         return {
@@ -234,9 +281,10 @@ function tallyCommand(flags) {
 async function sealedCommand(flags) {
     const label = readSealedLabel(path.resolve(requireText(flags, "label")));
     const hide = texts(flags, "hide");
+    const outDir = path.resolve(requireText(flags, "out"));
     const report = await runCommand(flags, hide);
     const body = JSON.stringify(report);
-    if (!labelLeaked(body, label))
+    if (!labelLeaked(body, label) && !sealedTreeLeaked(outDir, label))
         return report;
     return {
         schemaVersion: SCHEMA_VERSION,

package/dist/contract.js

@@ -1,18 +1,20 @@
 import { homedir } from "node:os";
 export const SCHEMA_VERSION = 1;
 /** Replace the home directory so a result never carries a user's name or home path. */
-export function scrub(value, home = homedir()) {
+export function scrub(value, home = homedir(), keepPaths = false) {
     if (typeof value === "string") {
-        if (!home || !value.includes(home))
+        if (keepPaths || !home || !value.includes(home))
             return value;
         return value.split(home).join("~");
     }
     if (Array.isArray(value))
-        return value.map((item) => scrub(item, home));
+        return value.map((item) => scrub(item, home, keepPaths));
     if (value && typeof value === "object") {
         const out = {};
-        for (const [key, item] of Object.entries(value))
-            out[key] = scrub(item, home);
+        for (const [key, item] of Object.entries(value)) {
+            // nextCall.argv is executed. A tilde is not expanded by spawn or by MCP.
+            out[key] = scrub(item, home, keepPaths || key === "nextCall");
+        }
         return out;
     }
     return value;

package/dist/mcp.js

@@ -3,6 +3,19 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { nodeTooOld } from "./node-version.js";
+const tooOld = nodeTooOld(process.versions.node);
+if (tooOld) {
+    process.stdout.write(`${JSON.stringify({
+        schemaVersion: 1,
+        ok: false,
+        command: "mcp",
+        summary: tooOld,
+        next: "Install Node 22.6 or newer and run the command again.",
+        nextCall: null,
+    })}\n`);
+    process.exit(1);
+}
 const here = path.dirname(fileURLToPath(import.meta.url));
 const version = readVersion();
 const tool = {
@@ -63,6 +76,10 @@ function handle(message) {
         send({ jsonrpc: "2.0", id: message.id, result: { tools: [tool] } });
         return;
     }
+    if (message.method === "ping") {
+        send({ jsonrpc: "2.0", id: message.id, result: {} });
+        return;
+    }
     if (message.method === "tools/call") {
         const argv = message.params?.arguments?.argv;
         if (!Array.isArray(argv) || argv.some((item) => typeof item !== "string")) {
@@ -92,7 +109,13 @@ function handle(message) {
                 isError: envelope.ok !== true,
             },
         });
+        return;
     }
+    send({
+        jsonrpc: "2.0",
+        id: message.id,
+        error: { code: -32601, message: `method not found: ${message.method}` },
+    });
 }
 function cliCommand() {
     const compiled = path.join(here, "cli.js");

package/dist/mutate/child-lines.mjs

@@ -0,0 +1,34 @@
+// Nameless line dump for a plain script. This is not a node:test process and it
+// does not write a coverage shard. The parent test's afterEach reads the dump.
+import { randomBytes } from "node:crypto"
+import { mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { openLineSampler } from "./precise-lines.mjs"
+
+const mapPath = process.env.PROBATIO_COVERAGE_MAP
+if (mapPath) {
+  let sampler = null
+  try {
+    sampler = await openLineSampler((rel) => rel.endsWith("child-lines.mjs") || rel.endsWith("precise-lines.mjs"))
+  } catch (err) {
+    writeFileSync(`${mapPath}.error`, `${err instanceof Error ? err.message : String(err)}\n`)
+  }
+  if (sampler) {
+    let wrote = false
+    const dump = () => {
+      if (wrote) return
+      wrote = true
+      sampler.positiveLines().then((hits) => {
+        const dir = `${mapPath}.children`
+        mkdirSync(dir, { recursive: true })
+        writeFileSync(
+          path.join(dir, `${process.pid}-${randomBytes(4).toString("hex")}.json`),
+          JSON.stringify({ hits }),
+        )
+      }).catch((err) => {
+        writeFileSync(`${mapPath}.error`, `${err instanceof Error ? err.message : String(err)}\n`)
+      })
+    }
+    process.on("beforeExit", dump)
+  }
+}

package/dist/mutate/coverage-map.js

@@ -104,17 +104,10 @@ export function writeLlvmCoverage(pkg, profileDir, binary, dest) {
         return { ok: false, detail: "no profraw" };
     if (!binary)
         return { ok: false, detail: "no instrumented binary" };
-    const llvmCov = findTool("llvm-cov");
-    const llvmProf = findTool("llvm-profdata");
-    if (!llvmCov || !llvmProf)
-        return { ok: false, detail: `llvm tool missing (${llvmCov ? "llvm-profdata" : "llvm-cov"})` };
     const merged = path.join(profileDir, "baseline.profdata");
-    const merge = spawnSync(llvmProf, ["merge", "-sparse", "-o", merged, ...raws], { encoding: "utf8" });
-    if (merge.status !== 0)
-        return { ok: false, detail: (merge.stderr || merge.stdout || "llvm-profdata failed").trim() };
-    const exported = spawnSync(llvmCov, ["export", binary, `-instr-profile=${merged}`], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
-    if (exported.status !== 0)
-        return { ok: false, detail: (exported.stderr || exported.stdout || "llvm-cov failed").trim() };
+    const exported = exportLlvmProfile(binary, raws, merged);
+    if (!exported.ok)
+        return exported;
     const map = llvmExportToMap(exported.stdout, pkg);
     if (!map)
         return { ok: false, detail: "llvm-cov export was not a coverage map" };
@@ -159,14 +152,78 @@ function llvmExportToMap(stdout, pkg) {
         return null;
     return { files };
 }
-function findTool(name) {
+/**
+ * clang and rustc write different profraw versions. Each pair is one LLVM install.
+ * The first pair that can merge the profile wins.
+ */
+export function llvmToolsPresent() {
+    return llvmToolPairs().length > 0;
+}
+export function exportLlvmProfile(binary, raws, merged) {
+    const pairs = llvmToolPairs();
+    if (pairs.length === 0)
+        return { ok: false, detail: "llvm tool missing (llvm-cov)" };
+    let detail = "llvm-profdata failed";
+    for (const { cov, prof } of pairs) {
+        const merge = spawnSync(prof, ["merge", "-sparse", "-o", merged, ...raws], { encoding: "utf8" });
+        if (merge.status !== 0) {
+            detail = (merge.stderr || merge.stdout || "llvm-profdata failed").trim();
+            continue;
+        }
+        const exported = spawnSync(cov, ["export", binary, `-instr-profile=${merged}`], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+        if (exported.status !== 0) {
+            detail = (exported.stderr || exported.stdout || "llvm-cov failed").trim();
+            continue;
+        }
+        return { ok: true, stdout: exported.stdout };
+    }
+    return { ok: false, detail };
+}
+function llvmToolPairs() {
+    const covs = toolCandidates("llvm-cov");
+    const profs = toolCandidates("llvm-profdata");
+    const pairs = [];
+    const seen = new Set();
+    for (const cov of covs) {
+        const prof = profs.find((item) => path.dirname(item) === path.dirname(cov));
+        if (!prof)
+            continue;
+        const key = `${cov}\0${prof}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        pairs.push({ cov, prof });
+    }
+    return pairs;
+}
+function toolCandidates(name) {
+    const out = [];
+    const add = (file) => {
+        if (!file || out.includes(file) || !existsSync(file))
+            return;
+        out.push(file);
+    };
     const fromXcrun = spawnSync("xcrun", ["--find", name], { encoding: "utf8" });
-    const xcrunPath = fromXcrun.stdout?.trim() ?? "";
-    if (fromXcrun.status === 0 && xcrunPath && existsSync(xcrunPath))
-        return xcrunPath;
+    if (fromXcrun.status === 0)
+        add((fromXcrun.stdout ?? "").trim());
     const which = spawnSync("sh", ["-c", `command -v ${name}`], { encoding: "utf8" });
-    const found = which.stdout?.trim() ?? "";
-    if (which.status === 0 && found)
-        return found;
-    return null;
+    if (which.status === 0)
+        add((which.stdout ?? "").trim());
+    const rustc = spawnSync("rustc", ["--print", "sysroot"], { encoding: "utf8" });
+    if (rustc.status === 0) {
+        const root = path.join(rustc.stdout.trim(), "lib", "rustlib");
+        if (existsSync(root)) {
+            for (const host of readdirSync(root))
+                add(path.join(root, host, "bin", name));
+        }
+    }
+    const usr = "/usr/lib";
+    if (existsSync(usr)) {
+        for (const dir of readdirSync(usr)) {
+            if (dir.startsWith("llvm-"))
+                add(path.join(usr, dir, "bin", name));
+        }
+    }
+    add(path.join("/usr/bin", name));
+    return out;
 }

package/dist/mutate/generate.js

@@ -8,8 +8,9 @@ export function generateMutants(options) {
     const started = Date.now();
     const limit = options.maxMinutes;
     const over = () => limit != null && Date.now() - started >= limit * 60_000;
+    const sourceDefault = options.workingTree ? "working-tree" : "commit";
     if (over())
-        return { mutants: [], violations: [], filesVisited: 0, budgetHit: true };
+        return { mutants: [], violations: [], filesVisited: 0, budgetHit: true, source: sourceDefault };
     const srcRoot = path.resolve(options.packageDir, options.srcDir);
     const walked = walkSources(srcRoot, over);
     const files = walked.files.filter((file) => !options.skipFiles.includes(path.basename(file)));
@@ -18,13 +19,18 @@ export function generateMutants(options) {
     const chosen = [];
     let filesVisited = 0;
     let budgetHit = walked.stopped;
+    let source = sourceDefault;
     for (const file of files) {
         if (over()) {
             budgetHit = true;
             break;
         }
         filesVisited += 1;
-        const text = readFileSync(file, "utf8");
+        const loaded = fileText(options.packageDir, file, options);
+        if ("error" in loaded)
+            return { mutants: [], violations: [], filesVisited, budgetHit, source: "commit", error: loaded.error };
+        source = loaded.source;
+        const text = loaded.text;
         const rel = posix(path.relative(options.packageDir, file));
         const found = findInSource(rel, text);
         violations.push(...found.violations);
@@ -34,7 +40,7 @@ export function generateMutants(options) {
             chosen.push({ rel, text, point });
     }
     if (violations.length > 0)
-        return { mutants: [], violations, filesVisited, budgetHit };
+        return { mutants: [], violations, filesVisited, budgetHit, source };
     const capped = options.maxMutants === null ? chosen : chosen.slice(0, options.maxMutants);
     const packageReal = real(options.packageDir);
     const patchRoot = gitRoot(packageReal);
@@ -55,7 +61,22 @@ export function generateMutants(options) {
         mutants.push({ id, file: item.rel, line: item.point.line, op: item.point.op, patch });
     }
     writeFileSync(path.join(mutantsDir, "mutants.json"), `${JSON.stringify({ schemaVersion: 1, seed: options.seed, mutants }, null, 2)}\n`);
-    return { mutants, violations, filesVisited, budgetHit };
+    return { mutants, violations, filesVisited, budgetHit, source };
+}
+function fileText(packageDir, absFile, options) {
+    if (options.workingTree)
+        return { text: readFileSync(absFile, "utf8"), source: "working-tree" };
+    const root = gitRoot(packageDir);
+    if (!root)
+        return { text: readFileSync(absFile, "utf8"), source: "working-tree" };
+    const rel = posix(path.relative(root, real(absFile)));
+    const commit = options.commit && options.commit.length > 0 ? options.commit : "HEAD";
+    const shown = spawnSync("git", ["-C", root, "show", `${commit}:${rel}`], { encoding: "utf8" });
+    if (shown.status !== 0) {
+        const shownRel = posix(path.relative(packageDir, absFile));
+        return { error: `${shownRel} is not in ${commit}. Pass --working-tree to read the checkout.` };
+    }
+    return { text: shown.stdout, source: "commit" };
 }
 function walkSources(dir, over) {
     if (!statExists(dir))

package/dist/mutate/mocha-coverage.cjs

@@ -0,0 +1,71 @@
+// Mocha root hooks. This file is not node-coverage.mjs. Mocha does not run
+// node:test afterEach/after, so that collector records no Mocha title.
+// These hooks key inspector hits by the current Mocha title and write { files }.
+const { mkdirSync, writeFileSync } = require("node:fs")
+const path = require("node:path")
+
+const mapPath = process.env.PROBATIO_COVERAGE_MAP
+if (mapPath) {
+  /** @type {Map<string, Map<number, Set<string>>>} */
+  const byFile = new Map()
+  /** @type {Array<{ file: string, line: number }>} */
+  let prelude = []
+  /** @type {{ positiveLines: () => Promise<Array<{ file: string, line: number }>> } | null} */
+  let sampler = null
+
+  function add(hits, name) {
+    if (!name) return
+    for (const hit of hits) {
+      let lines = byFile.get(hit.file)
+      if (!lines) {
+        lines = new Map()
+        byFile.set(hit.file, lines)
+      }
+      let names = lines.get(hit.line)
+      if (!names) {
+        names = new Set()
+        lines.set(hit.line, names)
+      }
+      names.add(name)
+    }
+  }
+
+  function titleOf(test) {
+    if (!test) return ""
+    if (typeof test.fullTitle === "function") return test.fullTitle()
+    return typeof test.title === "string" ? test.title : ""
+  }
+
+  exports.mochaHooks = {
+    async beforeAll() {
+      try {
+        const opened = await import("./precise-lines.mjs")
+        sampler = await opened.openLineSampler((rel) => rel.endsWith("mocha-coverage.cjs") || rel.endsWith("precise-lines.mjs") || rel.endsWith("node-coverage.mjs"))
+        prelude = await sampler.positiveLines()
+      } catch (err) {
+        writeFileSync(`${mapPath}.error`, `${err instanceof Error ? err.message : String(err)}\n`)
+      }
+    },
+    async afterEach() {
+      if (!sampler) return
+      const title = titleOf(this.currentTest)
+      try {
+        add(prelude, title)
+        add(await sampler.positiveLines(), title)
+      } catch (err) {
+        writeFileSync(`${mapPath}.error`, `${err instanceof Error ? err.message : String(err)}\n`)
+      }
+    },
+    afterAll() {
+      if (byFile.size === 0) return
+      const files = {}
+      for (const [file, lines] of byFile) {
+        const bucket = {}
+        for (const [line, names] of lines) bucket[String(line)] = [...names].sort()
+        files[file] = bucket
+      }
+      mkdirSync(path.dirname(mapPath), { recursive: true })
+      writeFileSync(mapPath, `${JSON.stringify({ files }, null, 2)}\n`)
+    },
+  }
+}