probatio 0.0.1 → 0.0.3

package/README.md

@@ -5,7 +5,7 @@ Probatio (Latin: a testing, a proof) is a free, open-source testing toolkit buil
 it remembers what was fixed so agents with small context do not redo or undo work; and it finds
 the bugs a test suite would miss instead of asking anyone to read more tests.
 
-Status (2026-10-05): `mutate run` discovers the project suite and scores it. Python, JavaScript, and TypeScript narrow each mutant with a line map collected on the baseline. C does the same when the binary was built with LLVM 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` mutates the changed lines and uses that same map. `mutate tally` reads a finished run, names tests that killed nothing, and does not delete a test. The MCP server returns the same JSON as the CLI.
+Status (2026-10-05): `mutate run` discovers the project suite and scores it. Python, JavaScript, and TypeScript narrow each mutant with a line map collected on the baseline. C does the same when the binary was built with LLVM 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` mutates the changed lines and uses that same map. `mutate tally` reads a finished run, names tests that killed nothing, and does not delete a test. The MCP server speaks one JSON object per line and returns the same JSON as the CLI.
 
 Read in this order:
 
@@ -23,19 +23,19 @@ One JSON object on stdout. `schemaVersion`, `ok`, `summary`, `next`, `nextCall`.
 
 ```bash
 npx probatio mutate generate --package . --out .probatio/generate
-npx probatio mutate run --package . --patches .probatio/generate/mutants --out .probatio/runs --no-build
+npx probatio mutate run --package . --patches .probatio/generate/mutants --out .probatio/runs
 npx probatio mutate tally --out .probatio/runs
 ```
 
 `generate` writes operator mutants (conditions, `&&`/`||`, `===`/`!==`, boundaries, booleans, a dropped `!`). The same class is written for COBOL (`.cob`, `.cbl`), Rust, C, C++, Java, Go, Python, JavaScript, and C#. Strings and comments are not mutated. A COBOL `*>` comment and a fixed-format line whose column 7 is `*` or `/` are comments. Each patch is forward: apply it to introduce the bug, and the file says so. When mutants were written, `next` states the count, the suite command if one was discovered, and whether the first run collects a line map.
 
-`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.
+`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.
 
-Python, JavaScript, and TypeScript collect a line map on the baseline. C collects one when LLVM coverage was instrumented. A later mutant runs the tests that executed its line. A line no test executed is `no coverage`, not a survivor. Go, Java, Rust, and C# can take a test name. Without a line map they still run the suite you gave them. 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.
+Python, JavaScript, and TypeScript collect a line map on the baseline. C collects one when LLVM coverage was instrumented. Go and Maven/Java collect file, line, and the test names that hit that line. A later mutant runs only those tests (`go test -run`, Maven `-Dtest`). A line no test executed is `no coverage`, and the suite is not started. Rust and C# can take a test name and do not collect a line. 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.
 
-`tally` reads that run directory. It names tests that killed a mutant, tests that killed nothing, and one gap for each survivor and each uncovered line. `deletedTests` is 0. It does not delete a file.
+`tally` reads that run directory. The summary leads with the no-coverage count, then the survivors. It names tests that killed a mutant and tests that killed nothing. A gap is a survivor. An unseen line is not a gap and not a pass. A timeout is neither a kill nor a gap. `deletedTests` is 0. It does not delete a file.
 
 ## ledger
 

package/dist/cli.js

@@ -143,12 +143,7 @@ async function runCommand(flags) {
     if (direction !== "auto" && direction !== "forward" && direction !== "reverse") {
         throw new Error("--direction must be auto, forward, or reverse");
     }
-    const buildValues = flags.get("build");
-    const build = !buildValues || buildValues.length === 0
-        ? ["npm", "run", "build:mcp", "--silent"]
-        : buildValues[buildValues.length - 1] === false
-            ? null
-            : String(buildValues[buildValues.length - 1]).split(" ").filter(Boolean);
+    const build = buildCommand(flags);
     const report = await runMutants({
         packageDir,
         repoDir,
@@ -444,12 +439,7 @@ async function checkKillCommand(flags, id) {
     const patchDirs = texts(flags, "patches").map((dir) => path.resolve(dir));
     if (patchDirs.length === 0)
         throw new Error("--patches is required");
-    const buildValues = flags.get("build");
-    const build = !buildValues || buildValues.length === 0
-        ? null
-        : buildValues[buildValues.length - 1] === false
-            ? null
-            : String(buildValues[buildValues.length - 1]).split(" ").filter(Boolean);
+    const build = buildCommand(flags);
     return checkKill(id, {
         packageDir,
         repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
@@ -496,3 +486,14 @@ function finish(envelope, human) {
     process.stdout.write(render(envelope, human));
     process.exit(envelope.ok ? 0 : 1);
 }
+/** Omitted `--build` and `--no-build` both mean no build. `--build <cmd>` opts in. */
+function buildCommand(flags) {
+    const values = flags.get("build");
+    if (!values || values.length === 0)
+        return null;
+    const last = values[values.length - 1];
+    if (typeof last !== "string")
+        return null;
+    const parts = last.split(" ").filter(Boolean);
+    return parts.length > 0 ? parts : null;
+}

package/dist/mcp.js

@@ -1,35 +1,39 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 const here = path.dirname(fileURLToPath(import.meta.url));
-let buffer = Buffer.alloc(0);
+const version = readVersion();
+const tool = {
+    name: "probatio",
+    description: "Run one probatio command. argv is the CLI words and flags.",
+    inputSchema: {
+        type: "object",
+        properties: { argv: { type: "array", items: { type: "string" } } },
+        required: ["argv"],
+    },
+};
+let buffer = "";
+process.stdin.setEncoding("utf8");
 process.stdin.on("data", (chunk) => {
-    buffer = Buffer.concat([buffer, chunk]);
+    buffer += chunk;
     drain();
 });
-process.stdin.on("end", () => process.exit(0));
-function drain() {
-    for (;;) {
-        const headerEnd = buffer.indexOf("\r\n\r\n");
-        if (headerEnd === -1)
-            return;
-        const header = buffer.subarray(0, headerEnd).toString("utf8");
-        const match = header.match(/Content-Length:\s*(\d+)/i);
-        const start = headerEnd + 4;
-        if (!match) {
-            buffer = buffer.subarray(start);
+process.stdin.on("end", () => {
+    drain(true);
+    process.exit(0);
+});
+function drain(flush = false) {
+    const lines = buffer.split("\n");
+    buffer = flush ? "" : lines.pop() ?? "";
+    for (const line of lines) {
+        const text = line.replace(/\r$/, "").trim();
+        if (!text)
             continue;
-        }
-        const length = Number(match[1]);
-        if (buffer.length < start + length)
-            return;
-        const body = buffer.subarray(start, start + length).toString("utf8");
-        buffer = buffer.subarray(start + length);
         let message;
         try {
-            message = JSON.parse(body);
+            message = JSON.parse(text);
         }
         catch {
             continue;
@@ -49,29 +53,14 @@ function handle(message) {
             result: {
                 protocolVersion: "2024-11-05",
                 capabilities: { tools: {} },
-                serverInfo: { name: "probatio", version: "0.0.1" },
+                serverInfo: { name: "probatio", version },
+                tools: [tool],
             },
         });
         return;
     }
     if (message.method === "tools/list") {
-        send({
-            jsonrpc: "2.0",
-            id: message.id,
-            result: {
-                tools: [
-                    {
-                        name: "probatio",
-                        description: "Run one probatio command. argv is the CLI words and flags.",
-                        inputSchema: {
-                            type: "object",
-                            properties: { argv: { type: "array", items: { type: "string" } } },
-                            required: ["argv"],
-                        },
-                    },
-                ],
-            },
-        });
+        send({ jsonrpc: "2.0", id: message.id, result: { tools: [tool] } });
         return;
     }
     if (message.method === "tools/call") {
@@ -112,8 +101,16 @@ function cliCommand() {
     const tsx = path.resolve(here, "..", "node_modules", ".bin", "tsx");
     return { bin: tsx, args: [path.join(here, "cli.ts")] };
 }
+function readVersion() {
+    try {
+        const raw = JSON.parse(readFileSync(path.resolve(here, "..", "package.json"), "utf8"));
+        return typeof raw.version === "string" && raw.version.length > 0 ? raw.version : "0.0.1";
+    }
+    catch {
+        return "0.0.1";
+    }
+}
 function send(message) {
-    const payload = Buffer.from(JSON.stringify(message), "utf8");
-    process.stdout.write(`Content-Length: ${payload.length}\r\n\r\n`);
-    process.stdout.write(payload);
+    const line = JSON.stringify(message);
+    process.stdout.write(`${line}\n`);
 }

package/dist/mutate/go-coverage.js

@@ -0,0 +1,100 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/** Blocks in a Go cover profile whose count is above zero. */
+export function parseCoverProfile(text, modulePath) {
+    const hits = [];
+    const prefix = modulePath ? `${modulePath}/` : "";
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("mode:"))
+            continue;
+        const match = /^(.+):(\d+)\.\d+,(\d+)\.\d+\s+\d+\s+(\d+)$/.exec(line);
+        if (!match)
+            continue;
+        if (Number(match[4]) <= 0)
+            continue;
+        let file = match[1];
+        if (prefix && file.startsWith(prefix))
+            file = file.slice(prefix.length);
+        file = file.split("\\").join("/");
+        const start = Number(match[2]);
+        const end = Number(match[3]);
+        for (let number = start; number <= end; number++)
+            hits.push({ file, line: number });
+    }
+    return hits;
+}
+/**
+ * One compiled test binary per package, then one profile per test name.
+ * A stock cover profile does not name the test, so each test gets its own.
+ */
+export function writeGoCoverage(pkg, testNames, dest) {
+    const wanted = new Set(testNames.filter((name) => name.length > 0 && !name.includes("/")));
+    if (wanted.size === 0)
+        return { ok: false, detail: "go coverage: no test names" };
+    const mod = run("go", ["list", "-m"], pkg);
+    if (mod.status !== 0)
+        return { ok: false, detail: clip(mod.stderr || mod.stdout || mod.error?.message || "go list -m failed") };
+    const modulePath = mod.stdout.trim().split("\n")[0]?.trim() ?? "";
+    const listed = run("go", ["list", "-f", "{{.ImportPath}}\t{{.Dir}}\t{{len .TestGoFiles}}\t{{len .XTestGoFiles}}", "./..."], pkg);
+    if (listed.status !== 0)
+        return { ok: false, detail: clip(listed.stderr || listed.stdout || listed.error?.message || "go list failed") };
+    const work = path.join(path.dirname(dest), "go-cover");
+    mkdirSync(work, { recursive: true });
+    const files = {};
+    const packages = listed.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+    for (const row of packages) {
+        const [importPath, dir, testFiles, xTestFiles] = row.split("\t");
+        if (!importPath || !dir)
+            continue;
+        if (Number(testFiles ?? "0") + Number(xTestFiles ?? "0") <= 0)
+            continue;
+        const bin = path.join(work, `${safe(importPath)}.test`);
+        const compiled = run("go", ["test", "-c", "-covermode=set", "-o", bin, importPath], pkg);
+        if (compiled.status !== 0 || compiled.error)
+            continue;
+        const listedTests = run(bin, ["-test.list", "."], dir);
+        if (listedTests.status !== 0)
+            continue;
+        for (const name of listedTests.stdout.split("\n").map((item) => item.trim()).filter((item) => wanted.has(item))) {
+            const profile = path.join(work, `${safe(importPath)}-${safe(name)}.out`);
+            run(bin, ["-test.run", `^${escapeRegExp(name)}$`, "-test.coverprofile", profile], dir);
+            let text = "";
+            try {
+                text = readFileSync(profile, "utf8");
+            }
+            catch {
+                continue;
+            }
+            for (const hit of parseCoverProfile(text, modulePath))
+                addHit(files, hit.file, hit.line, name);
+        }
+    }
+    if (Object.keys(files).length === 0)
+        return { ok: false, detail: "go coverage: no covered lines" };
+    writeFileSync(dest, `${JSON.stringify({ files }, null, 2)}\n`);
+    return { ok: true, detail: `${Object.keys(files).length} files` };
+}
+function addHit(files, file, line, test) {
+    const lines = files[file] ?? {};
+    const key = String(line);
+    const names = lines[key] ?? [];
+    if (!names.includes(test))
+        names.push(test);
+    lines[key] = names;
+    files[file] = lines;
+}
+function safe(value) {
+    return value.replace(/[^A-Za-z0-9._-]+/g, "_");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function run(bin, args, cwd) {
+    return spawnSync(bin, args, { cwd, encoding: "utf8", timeout: 120_000 });
+}
+function clip(text) {
+    const line = text.trim().split("\n").find((item) => item.trim()) ?? "go coverage failed";
+    return line.slice(0, 240);
+}

package/dist/mutate/java-coverage.js

@@ -0,0 +1,217 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const JACOCO = "0.8.15";
+const ASM = "9.10.1";
+const RUNNER = fileURLToPath(new URL("./probatio-jacoco-run.java", import.meta.url));
+/**
+ * One JVM, one JaCoCo dump per Surefire test method.
+ * The default jacoco.exec file does not name the test.
+ */
+export function writeJavaCoverage(pkg, testNames, dest) {
+    const tests = testNames.map(junitMethod).filter((name) => name !== null);
+    if (tests.length === 0)
+        return { ok: false, detail: "java coverage: no class.method test names" };
+    const classDirs = findClassDirs(pkg);
+    if (classDirs.length === 0)
+        return { ok: false, detail: "java coverage: no target/classes" };
+    const work = path.join(path.dirname(dest), "java-cover");
+    mkdirSync(work, { recursive: true });
+    const jars = resolveJars(pkg, work);
+    if ("error" in jars)
+        return { ok: false, detail: jars.error };
+    const source = path.join(work, "ProbatioJacocoRun.java");
+    writeFileSync(source, readFileSync(RUNNER));
+    const compileCp = [jars.agent, jars.junit, jars.core, jars.asm, jars.asmCommons, jars.asmTree].join(path.delimiter);
+    const compiled = run(javaTool("javac"), ["-encoding", "UTF-8", "-cp", compileCp, "-d", work, source], pkg);
+    if (compiled.status !== 0)
+        return { ok: false, detail: clip(compiled.stderr || compiled.stdout || compiled.error?.message || "javac failed") };
+    const testsFile = path.join(work, "tests.txt");
+    writeFileSync(testsFile, `${tests.join("\n")}\n`);
+    const projectCp = buildClasspath(pkg, work);
+    if ("error" in projectCp)
+        return { ok: false, detail: projectCp.error };
+    // Surefire brings the platform launcher. A project's test classpath often has the Jupiter engine and not the launcher.
+    const launcher = platformLauncherJar(pkg, work, projectCp.cp);
+    if ("error" in launcher)
+        return { ok: false, detail: launcher.error };
+    // Our asm and JaCoCo must win over a project that still ships an older asm. That older reader rejects Java 27 class files.
+    const cp = [work, jars.core, jars.asm, jars.asmCommons, jars.asmTree, jars.junit, launcher.jar, ...classDirs, ...testClassDirs(pkg), projectCp.cp].filter(Boolean).join(path.delimiter);
+    const dump = path.join(work, "hits.txt");
+    const ran = run(javaTool("java"), [`-javaagent:${jars.agent}=output=none,excludes=ProbatioJacocoRun:org.junit.*:org.apiguardian.*:org.opentest4j.*`, "-cp", cp, "ProbatioJacocoRun", classDirs.join(path.delimiter), testsFile, dump, pkg], pkg, 900_000);
+    if (ran.error && ran.error.code === "ETIMEDOUT") {
+        return { ok: false, detail: "java coverage: timed out" };
+    }
+    if (ran.status !== 0 || !existsSync(dump)) {
+        return { ok: false, detail: clip(ran.stderr || ran.stdout || ran.error?.message || "java coverage runner failed") };
+    }
+    const files = hitsToMap(readFileSync(dump, "utf8"));
+    if (Object.keys(files).length === 0)
+        return { ok: false, detail: "java coverage: no covered lines" };
+    writeFileSync(dest, `${JSON.stringify({ files }, null, 2)}\n`);
+    return { ok: true, detail: `${Object.keys(files).length} files` };
+}
+export function hitsToMap(text) {
+    const files = {};
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (!line.startsWith("HIT "))
+            continue;
+        const parts = line.slice(4).split(" ");
+        if (parts.length < 3)
+            continue;
+        const test = parts.pop() ?? "";
+        const number = parts.pop() ?? "";
+        const file = parts.join(" ");
+        if (!file || !/^\d+$/.test(number) || !test)
+            continue;
+        const lines = files[file] ?? {};
+        const names = lines[number] ?? [];
+        if (!names.includes(test))
+            names.push(test);
+        lines[number] = names;
+        files[file] = lines;
+    }
+    return files;
+}
+function junitMethod(name) {
+    const leaf = name.split("::").pop() ?? name;
+    const dot = leaf.lastIndexOf(".");
+    if (dot <= 0 || dot === leaf.length - 1)
+        return null;
+    if (leaf.startsWith("maven-") || leaf === "javac")
+        return null;
+    return `${leaf.slice(0, dot)}#${leaf.slice(dot + 1)}`;
+}
+function findClassDirs(root) {
+    const found = [];
+    const walk = (dir, depth) => {
+        if (depth > 4)
+            return;
+        let entries = [];
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (name === "node_modules" || name === ".git" || name === "java-cover")
+                continue;
+            const full = path.join(dir, name);
+            if (name === "target") {
+                const classes = path.join(full, "classes");
+                if (existsSync(classes))
+                    found.push(classes);
+                continue;
+            }
+            if (name.startsWith("."))
+                continue;
+            walk(full, depth + 1);
+        }
+    };
+    walk(root, 0);
+    return found;
+}
+function testClassDirs(root) {
+    return findClassDirs(root).map((dir) => path.join(path.dirname(dir), "test-classes")).filter((dir) => existsSync(dir));
+}
+function resolveJars(pkg, work) {
+    const copies = [
+        [`org.jacoco:org.jacoco.agent:${JACOCO}:jar:runtime`, "agent.jar"],
+        [`org.jacoco:org.jacoco.core:${JACOCO}`, "core.jar"],
+        [`org.ow2.asm:asm:${ASM}`, "asm.jar"],
+        [`org.ow2.asm:asm-commons:${ASM}`, "asm-commons.jar"],
+        [`org.ow2.asm:asm-tree:${ASM}`, "asm-tree.jar"],
+        ["junit:junit:4.13.2", "junit.jar"],
+    ];
+    const paths = {};
+    for (const [artifact, name] of copies) {
+        const dest = path.join(work, name);
+        if (!existsSync(dest)) {
+            const before = new Set(readdirSync(work));
+            const copied = run("mvn", ["-B", "-q", "org.apache.maven.plugins:maven-dependency-plugin:3.6.1:copy", `-Dartifact=${artifact}`, `-DoutputDirectory=${work}`], pkg);
+            if (copied.status !== 0)
+                return { error: clip(copied.stderr || copied.stdout || copied.error?.message || `mvn copy ${artifact} failed`) };
+            const created = readdirSync(work).find((item) => !before.has(item) && item.endsWith(".jar"));
+            if (!created)
+                return { error: `java coverage: missing ${artifact}` };
+            writeFileSync(dest, readFileSync(path.join(work, created)));
+        }
+        paths[name] = dest;
+    }
+    return {
+        agent: paths["agent.jar"],
+        core: paths["core.jar"],
+        asm: paths["asm.jar"],
+        asmCommons: paths["asm-commons.jar"],
+        asmTree: paths["asm-tree.jar"],
+        junit: paths["junit.jar"],
+    };
+}
+/** Launcher jar matching the project's junit-platform-engine, or none when this suite is not Jupiter. */
+function platformLauncherJar(pkg, work, projectCp) {
+    const entries = projectCp.split(path.delimiter).filter(Boolean);
+    if (entries.some((item) => path.basename(item).startsWith("junit-platform-launcher")))
+        return { jar: "" };
+    const engine = entries.find((item) => path.basename(item).startsWith("junit-platform-engine-"));
+    if (!engine)
+        return { jar: "" };
+    const version = path.basename(engine).replace(/^junit-platform-engine-/, "").replace(/\.jar$/, "");
+    if (!version)
+        return { error: "java coverage: junit-platform-engine version missing" };
+    const dest = path.join(work, "launcher.jar");
+    if (!existsSync(dest)) {
+        const artifact = `org.junit.platform:junit-platform-launcher:${version}`;
+        const before = new Set(readdirSync(work));
+        const copied = run("mvn", ["-B", "-q", "org.apache.maven.plugins:maven-dependency-plugin:3.6.1:copy", `-Dartifact=${artifact}`, `-DoutputDirectory=${work}`], pkg);
+        if (copied.status !== 0)
+            return { error: clip(copied.stderr || copied.stdout || copied.error?.message || `mvn copy ${artifact} failed`) };
+        const created = readdirSync(work).find((item) => !before.has(item) && item.endsWith(".jar"));
+        if (!created)
+            return { error: `java coverage: missing ${artifact}` };
+        writeFileSync(dest, readFileSync(path.join(work, created)));
+    }
+    return { jar: dest };
+}
+function buildClasspath(pkg, work) {
+    const file = path.join(work, "classpath.txt");
+    const built = run("mvn", ["-B", "-q", "dependency:build-classpath", "-DincludeScope=test", `-Dmdep.outputFile=${file}`], pkg);
+    if (built.status !== 0)
+        return { error: clip(built.stderr || built.stdout || built.error?.message || "mvn classpath failed") };
+    try {
+        return { cp: readFileSync(file, "utf8").trim() };
+    }
+    catch {
+        return { error: "java coverage: classpath file missing" };
+    }
+}
+function javaTool(name) {
+    const home = process.env.JAVA_HOME;
+    if (home) {
+        const candidate = path.join(home, "bin", name);
+        if (existsSync(candidate) && toolWorks(candidate))
+            return candidate;
+    }
+    if (toolWorks(name))
+        return name;
+    for (const dir of ["/opt/homebrew/opt/openjdk/bin", "/usr/local/opt/openjdk/bin"]) {
+        const candidate = path.join(dir, name);
+        if (existsSync(candidate) && toolWorks(candidate))
+            return candidate;
+    }
+    return name;
+}
+function toolWorks(bin) {
+    const probed = spawnSync(bin, ["-version"], { encoding: "utf8" });
+    const text = `${probed.stdout ?? ""}${probed.stderr ?? ""}`;
+    return probed.status === 0 && !/Unable to locate a Java Runtime/i.test(text);
+}
+function run(bin, args, cwd, timeout = 180_000) {
+    return spawnSync(bin, args, { cwd, encoding: "utf8", timeout });
+}
+function clip(text) {
+    const line = text.trim().split("\n").find((item) => item.trim()) ?? "java coverage failed";
+    return line.slice(0, 240);
+}