@specific.dev/spectest 0.127.0 → 0.129.0

package/src/coverage/rust.rs

@@ -0,0 +1,102 @@
+// Copy to your test build as spectest-coverage.rs and include behind a coverage
+// feature. Call start()? at the beginning of main in EACH instrumented binary.
+// No Spectest service, compiler or network connection is needed at runtime.
+use std::{ffi::CString, fs, io::{self, BufRead, Read, Write}, os::unix::net::UnixListener,
+    path::PathBuf, process::Command, sync::{Mutex, OnceLock}, time::{SystemTime, UNIX_EPOCH}};
+
+unsafe extern "C" {
+    fn __llvm_profile_get_size_for_buffer() -> u64;
+    fn __llvm_profile_write_buffer(buffer: *mut u8) -> i32;
+    fn __llvm_profile_set_filename(filename: *const std::ffi::c_char);
+    fn atexit(callback: extern "C" fn()) -> i32;
+}
+
+struct Collector { dir: PathBuf, id: String, socket: PathBuf, binary: PathBuf, lock: Mutex<()> }
+static COLLECTOR: OnceLock<Collector> = OnceLock::new();
+
+fn failure(error: impl std::fmt::Display) {
+    if let Some(c) = COLLECTOR.get() {
+        let _ = fs::write(c.dir.join(format!("rust-error-{}.txt", c.id)), error.to_string());
+    }
+}
+
+fn tool(name: &str, default: &str, args: &[&std::ffi::OsStr]) -> io::Result<Vec<u8>> {
+    let output = Command::new(std::env::var_os(name).unwrap_or_else(|| default.into())).args(args).output()?;
+    if !output.status.success() {
+        return Err(io::Error::other(format!("{default}: {}", String::from_utf8_lossy(&output.stderr))));
+    }
+    Ok(output.stdout)
+}
+
+fn capture() -> io::Result<()> {
+    let c = COLLECTOR.get().expect("coverage initialized");
+    let _guard = c.lock.lock().map_err(|_| io::Error::other("coverage lock poisoned"))?;
+    let raw = c.dir.join(format!(".rust/{}.profraw", c.id));
+    let data = c.dir.join(format!(".rust/{}.profdata", c.id));
+    // A buffer snapshot overwrites this process's profile. write_file() with
+    // merge patterns would repeatedly add its inherited counters to itself.
+    let mut buffer = vec![0u8; unsafe { __llvm_profile_get_size_for_buffer() } as usize];
+    if unsafe { __llvm_profile_write_buffer(buffer.as_mut_ptr()) } != 0 {
+        return Err(io::Error::other("LLVM could not snapshot counters"));
+    }
+    fs::write(&raw, buffer)?;
+    tool("SPECTEST_LLVM_PROFDATA", "llvm-profdata", &["merge".as_ref(), "-sparse".as_ref(), raw.as_os_str(), "-o".as_ref(), data.as_os_str()])?;
+    let ignore = std::env::var("SPECTEST_RUST_IGNORE").unwrap_or_else(|_| "(/rustc/|/\\.cargo/registry/|/spectest-coverage\\.rs$)".into());
+    let report = tool("SPECTEST_LLVM_COV", "llvm-cov", &["export".as_ref(), "-format=lcov".as_ref(), "-instr-profile".as_ref(), data.as_os_str(),
+        c.binary.as_os_str(), format!("-ignore-filename-regex={ignore}").as_ref()])?;
+    if !report.starts_with(b"SF:") && !report.starts_with(b"TN:") {
+        return Err(io::Error::other("LLVM exported no LCOV source records"));
+    }
+    let mut report = String::from_utf8(report).map_err(io::Error::other)?;
+    if let Ok(root) = std::env::var("SPECTEST_RUST_BUILD_ROOT") {
+        let prefix = format!("SF:{}/", root.trim_end_matches('/'));
+        report = report.lines().map(|line| match line.strip_prefix(&prefix) {
+            Some(relative) => format!("SF:{relative}\n"), None => format!("{line}\n"),
+        }).collect();
+    }
+    let temporary = c.dir.join(format!(".rust/{}.lcov.tmp", c.id));
+    fs::write(&temporary, report)?;
+    fs::rename(temporary, c.dir.join(format!("rust-{}.lcov", c.id)))?;
+    Ok(())
+}
+
+extern "C" fn finish() {
+    if let Err(error) = capture() { failure(error); }
+    if let Some(c) = COLLECTOR.get() { let _ = fs::remove_file(&c.socket); }
+}
+
+/// Disabled when SPECTEST_COVERAGE_DIR is absent. Requires Unix and LLVM
+/// instrumentation at link time; gate this module behind your coverage build.
+pub fn start() -> io::Result<()> {
+    let Some(dir) = std::env::var_os("SPECTEST_COVERAGE_DIR") else { return Ok(()); };
+    if COLLECTOR.get().is_some() { return Ok(()); }
+    let dir = PathBuf::from(dir);
+    fs::create_dir_all(dir.join(".rust"))?;
+    let nonce = SystemTime::now().duration_since(UNIX_EPOCH).map_err(io::Error::other)?.as_nanos();
+    let id = format!("{:x}-{nonce:x}", std::process::id());
+    let socket = dir.join(format!(".rust-ctl-{id}"));
+    let listener = UnixListener::bind(&socket)?;
+    let binary = std::env::current_exe()?;
+    let exit_path = CString::new(dir.join(format!(".rust/{id}.exit.profraw")).as_os_str().as_encoded_bytes())?;
+    // The profiler may retain the filename until process exit.
+    unsafe { __llvm_profile_set_filename(exit_path.into_raw()); }
+    COLLECTOR.set(Collector { dir, id, socket, binary, lock: Mutex::new(()) }).map_err(|_| io::Error::other("coverage already initialized"))?;
+    if unsafe { atexit(finish) } != 0 { return Err(io::Error::other("could not register coverage exit handler")); }
+    // Establish a report before readiness; an uninstrumented/mismatched build
+    // must fail before it can supply an apparently empty baseline.
+    if let Err(error) = capture() { failure(&error); return Err(error); }
+    std::thread::Builder::new().name("spectest-coverage".into()).spawn(move || {
+        for connection in listener.incoming() {
+            let mut stream = match connection { Ok(stream) => stream, Err(error) => { failure(error); break; } };
+            let _ = stream.set_read_timeout(Some(std::time::Duration::from_secs(5)));
+            let mut request = String::new();
+            let result = io::BufReader::new(&stream).take(32).read_line(&mut request)
+                .and_then(|_| if request == "dump\n" { capture() } else { Err(io::Error::other("invalid coverage request")) });
+            match result {
+                Ok(()) => { let _ = stream.write_all(b"ok\n"); }
+                Err(error) => { failure(&error); let _ = writeln!(stream, "error {error}"); }
+            }
+        }
+    })?;
+    Ok(())
+}

package/src/coverage-bun.test.ts

@@ -0,0 +1,103 @@
+import { expect, test } from "bun:test";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { bun, applyCoverageAdapters, NODE_COVERAGE_HOOK } from "./coverage";
+import { readCoverageDir, encodeCoverageBundle } from "./harness/coverage";
+
+async function checked(args: string[], cwd: string, env?: Record<string, string | undefined>) {
+  const child = Bun.spawn(args, { cwd, env: { ...process.env, ...env }, stdout: "pipe", stderr: "pipe" });
+  const [code, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+  if (code) throw new Error(`${args.join(" ")}: ${stderr}`);
+  return stdout;
+}
+
+test("Bun native coverage preserves bundle maps, captures exit, and rejects unmappable runtime transpilation", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bun-cov-"));
+  const reports = path.join(root, "reports");
+  await fs.mkdir(reports);
+  try {
+    await fs.writeFile(path.join(root, "hook.cjs"), NODE_COVERAGE_HOOK);
+    await fs.writeFile(path.join(root, "app.ts"), `export function choice(x: boolean) {\n if(x) return 'left';\n return 'right';\n}\nconsole.log(choice(true));\n`);
+    await checked([process.execPath, "build", "--target=bun", "--sourcemap=external", "--outdir=dist", "app.ts"], root);
+    const env = { BUN_OPTIONS: `--preload ${root}/hook.cjs`, SPECTEST_COVERAGE_DIR: reports, SPECTEST_COVERAGE_RUNTIME: "bun" };
+    expect(await checked([process.execPath, "dist/app.js"], root, env)).toContain("left");
+    const adapter = bun();
+    const context = { service: "bun", reportDir: reports, signal: AbortSignal.timeout(5000), exec: async () => ({ stdout: "", stderr: "" }),
+      writeReport: (name: string, content: string) => fs.writeFile(path.join(reports, name), content) };
+    await adapter.capture!(context);
+    const capture = await readCoverageDir("bun", reports);
+    expect(capture.error).toBeUndefined();
+    const scripts = capture.reports.filter(r => r.name.startsWith("scripts/")).map(r => JSON.parse(r.content).spectestScript);
+    expect(scripts).toHaveLength(1);
+    expect(scripts[0].sourceMap.data.sources.join()).toContain("app.ts");
+    expect(scripts[0].sourceMap.data.sourcesContent).toBeUndefined();
+    const dump = capture.reports.find(r => r.name.startsWith("node-"))!;
+    expect(JSON.parse(dump.content).result[0].functions.length).toBeGreaterThan(0);
+    await adapter.capture!(context);
+    expect((await readCoverageDir("bun", reports)).reports.some(r => r.name.startsWith("node-"))).toBe(false);
+    await checked([process.execPath, "app.ts"], root, env);
+    expect((await readCoverageDir("bun", reports)).error).toContain("neither");
+    const config = applyCoverageAdapters("cli", { image: "oven/bun", env: { BUN_OPTIONS: "--smol" }, coverage: { adapters: [adapter] } });
+    expect(config.env.BUN_OPTIONS).toContain("--smol --preload");
+  } finally { await fs.rm(root, { recursive: true, force: true }); }
+}, 20000);
+
+test("Bun live captures reset execution counts between calls", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bun-live-"));
+  let child: ReturnType<typeof Bun.spawn> | undefined;
+  try {
+    await fs.mkdir(path.join(root, "reports"));
+    await fs.writeFile(path.join(root, "hook.cjs"), NODE_COVERAGE_HOOK);
+    await fs.writeFile(path.join(root, "server.ts"), `import { createInterface } from 'node:readline';\nfunction left() {\n return 41;\n}\nfunction right() {\n return 42;\n}\ncreateInterface({input:process.stdin}).on('line', line => console.log(line === 'left' ? left() : right()));\nconsole.log('ready');\n`);
+    await checked([process.execPath, "build", "--target=bun", "--sourcemap=external", "--outdir=dist", "server.ts"], root);
+    child = Bun.spawn([process.execPath, "dist/server.js"], { cwd: root, stdin: "pipe", stdout: "pipe", stderr: "pipe", env: {
+      ...process.env, BUN_OPTIONS: `--preload ${root}/hook.cjs`, SPECTEST_COVERAGE_DIR: `${root}/reports`, SPECTEST_COVERAGE_RUNTIME: "bun",
+    } });
+    const reader = (child.stdout as ReadableStream<Uint8Array>).getReader();
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain("ready");
+    const ctx = { service: "live", reportDir: `${root}/reports`, signal: AbortSignal.timeout(5000), exec: async () => ({ stdout: "", stderr: "" }),
+      writeReport: (name: string, content: string) => fs.writeFile(path.join(root, "reports", name), content) };
+    const adapter = bun();
+    await adapter.capture!(ctx);
+    const setup = await readCoverageDir("live", ctx.reportDir);
+    const compiled = await fs.readFile(path.join(root, "dist/server.js"), "utf8");
+    const descriptor = JSON.parse(setup.reports.find(r => r.name.startsWith("scripts/"))!.content).spectestScript;
+    for (const name of ["left", "right"]) {
+      const start = compiled.indexOf(`function ${name}(`);
+      const range = descriptor.functions.find((f: [string, number, number]) => f[1] === start);
+      expect(range).toBeDefined();
+      expect(compiled[range[2] - 1]).toBe("}");
+    }
+    (child.stdin as { write(value: string): void }).write("left\n");
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain("41");
+    await adapter.capture!(ctx);
+    const first = await readCoverageDir("live", ctx.reportDir);
+    if (process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE) {
+      const output = path.join(process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE, "bun");
+      await fs.mkdir(output, { recursive: true });
+      await fs.writeFile(path.join(output, "setup.json.gz"), encodeCoverageBundle("__setup__", [{ ...setup, root }]));
+      await fs.writeFile(path.join(output, "left.json.gz"), encodeCoverageBundle("left", [{ ...first, root }]));
+      await fs.writeFile(path.join(output, "tree.txt"), "server.ts\n");
+      await fs.writeFile(path.join(output, "lines.json"), JSON.stringify({ "server.ts": 9 }));
+    }
+    expect(first.error).toBeUndefined();
+    const functions = first.reports.filter(r => r.name.startsWith("node-")).flatMap(r => JSON.parse(r.content).result.flatMap((s: any) => s.functions));
+    expect(functions.length).toBeGreaterThan(0);
+    await adapter.capture!(ctx);
+    const idle = await readCoverageDir("live", ctx.reportDir);
+    // No executed application ranges survive an idle take.
+    const idleFunctions = idle.reports.filter(r => r.name.startsWith("node-")).flatMap(r => JSON.parse(r.content).result.flatMap((s: any) => s.functions));
+    expect(idleFunctions).toHaveLength(0);
+    (child.stdin as { write(value: string): void }).write("right\n");
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain("42");
+    await adapter.capture!(ctx);
+    const right = await readCoverageDir("live", ctx.reportDir);
+    expect(right.error).toBeUndefined();
+    if (process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE) {
+      await fs.writeFile(path.join(process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE, "bun/right.json.gz"), encodeCoverageBundle("right", [{ ...right, root }]));
+    }
+    (child.stdin as { end(): void }).end();
+    await child.exited;
+  } finally { child?.kill(); await fs.rm(root, { recursive: true, force: true }); }
+}, 20000);

package/src/coverage-bun.ts

@@ -0,0 +1,40 @@
+import { appendEnvFlag, node, NODE_COVERAGE_HOOK, NODE_COVERAGE_HOOK_PATH, type CoverageAdapter, type NodeCoverageOptions } from "./coverage.js";
+import { access } from "node:fs/promises";
+import path from "node:path";
+
+/** Bun's native precise profiler, for `bun build --target=bun` bundles.
+ * Keep external or inline source maps with the bundle. Raw TS/JS requiring
+ * runtime transpilation is rejected because Bun cannot supply its compiled
+ * source through the in-process inspector. */
+export interface BunCoverageOptions extends NodeCoverageOptions {
+  /** Only for idle command containers where no Bun process has run yet. */
+  allowEmpty?: boolean;
+}
+
+export function bun(options: BunCoverageOptions = {}): CoverageAdapter {
+  const adapter = node(options);
+  return {
+    ...adapter,
+    name: "bun",
+    configure(service, info) {
+      const configured = adapter.configure!(service, info);
+      const env = appendEnvFlag(service.env, "BUN_OPTIONS", `--preload ${NODE_COVERAGE_HOOK_PATH}`);
+      return { ...configured, env: {
+        ...configured.env, BUN_OPTIONS: env.BUN_OPTIONS,
+        // The Node adapter also contributes metadata for generated bundles.
+        NODE_OPTIONS: service.env?.NODE_OPTIONS ?? "",
+        SPECTEST_COVERAGE_RUNTIME: "bun",
+      }, files: [...(service.files ?? []), { path: NODE_COVERAGE_HOOK_PATH, content: NODE_COVERAGE_HOOK }] };
+    },
+    inventory: ctx => adapter.inventory!({ ...ctx, exec: command => ctx.exec(
+      command.replace(/\| node -/g, "| env BUN_OPTIONS= SPECTEST_COVERAGE_DIR= bun run -"),
+    ) }),
+    async capture(ctx) {
+      if (!options.allowEmpty) {
+        try { await access(path.join(ctx.reportDir, ".attached-bun")); }
+        catch { throw new Error("Bun coverage hook never attached; use a supported Bun runtime and preserve BUN_OPTIONS"); }
+      }
+      await adapter.capture!(ctx);
+    },
+  };
+}

package/src/coverage-rust.test.ts

@@ -0,0 +1,74 @@
+import { expect, test } from "bun:test";
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+import { rust } from "./coverage-rust";
+import { captureCoverageTarget } from "./harness/coverage-target";
+import { encodeCoverageBundle } from "./harness/coverage";
+
+async function run(args: string[], cwd?: string) {
+  const child = Bun.spawn(args, { cwd, stdout: "pipe", stderr: "pipe" });
+  const [code, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+  if (code) throw new Error(`${args[0]}: ${stderr}`);
+  return stdout.trim();
+}
+
+const installedTools = (() => {
+  try {
+    const sysroot = execFileSync("rustc", ["--print", "sysroot"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    const host = execFileSync("rustc", ["-vV"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).match(/^host: (.+)$/m)![1];
+    const tools = path.join(sysroot, "lib/rustlib", host, "bin");
+    return existsSync(path.join(tools, "llvm-cov")) && existsSync(path.join(tools, "llvm-profdata")) ? tools : undefined;
+  } catch { return undefined; }
+})();
+test.skipIf(!installedTools)("Rust real LLVM reports capture live and exited processes, subtract baseline, and fail on lost processes", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rust-cov-"));
+  let child: ReturnType<typeof Bun.spawn> | undefined;
+  try {
+    const tools = installedTools!;
+    await fs.access(path.join(tools, "llvm-cov"));
+    await fs.mkdir(path.join(root, "reports"));
+    await fs.copyFile(new URL("./coverage/rust.rs", import.meta.url), path.join(root, "spectest-coverage.rs"));
+    await fs.writeFile(path.join(root, "main.rs"), `#[path="spectest-coverage.rs"] mod coverage;\nuse std::io::{self, BufRead, Write};\nfn choose(left: bool) -> u32 {\n if left { 41 } else { 42 }\n}\nfn main() {\n coverage::start().unwrap();\n println!("ready");\n io::stdout().flush().unwrap();\n for line in io::stdin().lock().lines() {\n  println!("{}",choose(line.unwrap()=="left"));\n  io::stdout().flush().unwrap();\n }\n}\n`);
+    await run(["rustc", "--edition=2024", "-C", "instrument-coverage", "-C", "opt-level=0", "main.rs", "-o", "server"], root);
+    const env = { ...process.env, SPECTEST_COVERAGE_DIR: `${root}/reports`, SPECTEST_LLVM_COV: `${tools}/llvm-cov`, SPECTEST_LLVM_PROFDATA: `${tools}/llvm-profdata` };
+    const launch = () => Bun.spawn([`${root}/server`], { cwd: root, env, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+    child = launch();
+    let reader = (child.stdout as ReadableStream<Uint8Array>).getReader();
+    const ready = new TextDecoder().decode((await reader.read()).value);
+    if (!ready.includes("ready")) throw new Error(await new Response(child.stderr).text());
+    const context = { service: "rust", reportDir: `${root}/reports`, signal: AbortSignal.timeout(10000),
+      exec: async () => ({ stdout: "", stderr: "" }), writeReport: async () => {}, projectFiles: async () => [], readProjectFile: async () => null };
+    const capture = (baseline = false) => captureCoverageTarget({ context, coverage: { adapters: [rust()] }, root, baseline });
+    const setup = await capture(true);
+    expect(setup.error).toBeUndefined();
+    (child.stdin as { write(value: string): void }).write("left\n");
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain("41");
+    const changed = await capture();
+    if (process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE) {
+      const output = path.join(process.env.SPECTEST_RUNTIME_COVERAGE_EVIDENCE, "rust");
+      await fs.mkdir(output, { recursive: true });
+      await fs.writeFile(path.join(output, "setup.json.gz"), encodeCoverageBundle("__setup__", [setup]));
+      await fs.writeFile(path.join(output, "left.json.gz"), encodeCoverageBundle("left", [changed]));
+      await fs.writeFile(path.join(output, "tree.txt"), "main.rs\n");
+      await fs.writeFile(path.join(output, "lines.json"), JSON.stringify({ "main.rs": 14 }));
+    }
+    expect(changed.error).toBeUndefined();
+    expect(changed.reports.map(r => r.content).join()).toMatch(/DA:4,[1-9]/);
+    const idle = await capture();
+    expect(idle.error).toBeUndefined();
+    expect(idle.reports.map(r => r.content).join()).toBe("TN:\n");
+    (child.stdin as { end(): void }).end();
+    expect(await child.exited).toBe(0);
+    expect((await capture()).error).toBeUndefined();
+    // A new process has a unique profile, even if the old PID is reused.
+    child = launch();
+    reader = (child.stdout as ReadableStream<Uint8Array>).getReader();
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain("ready");
+    child.kill("SIGKILL");
+    await child.exited;
+    expect((await capture()).error).toContain("without a final report");
+  } finally { child?.kill(); await fs.rm(root, { recursive: true, force: true }); }
+}, 30000);

package/src/coverage-rust.ts

@@ -0,0 +1,79 @@
+import { promises as fs, readFileSync } from "node:fs";
+import path from "node:path";
+import { connect } from "node:net";
+import type { CoverageAdapter, CoverageSourceOptions } from "./coverage.js";
+
+export interface RustCoverageOptions extends CoverageSourceOptions {
+  /** Only for idle command containers where no Rust process has run yet. */
+  allowEmpty?: boolean;
+  /** Compiler workspace directory, when different from the runtime workdir.
+   * Exact SF paths below it are made repository-relative before archiving. */
+  buildRoot?: string;
+  /** Matching rustup llvm-tools-preview executables, in the runtime image. */
+  llvmCov?: string;
+  llvmProfdata?: string;
+  /** LLVM filename regex for external/generated sources, not application code. */
+  ignoreFilenameRegex?: string;
+}
+
+/** Source for a test-build-only module, copied as spectest-coverage.rs. The
+ * application links only this std-only helper, never the JavaScript SDK. */
+export function rustHelperSource(): string {
+  return readFileSync(new URL("./coverage/rust.rs", import.meta.url), "utf8");
+}
+
+/** Flush a socket-backed collector. A dead process without a final flush is
+ * incomplete coverage, never an empty successful report. */
+export async function flushCoverageSockets(dir: string, prefix: string, signal: AbortSignal): Promise<number> {
+  const names = (await fs.readdir(dir)).filter(name => name.startsWith(prefix));
+  for (const name of names) {
+    signal.throwIfAborted();
+    await new Promise<void>((resolve, reject) => {
+      const socket = connect(path.join(dir, name), () => socket.end("dump\n"));
+      let reply = "";
+      const abort = () => socket.destroy(new Error(`coverage flush aborted: ${name}`));
+      signal.addEventListener("abort", abort, { once: true });
+      socket.setTimeout(55_000, () => socket.destroy(new Error(`coverage flush timed out: ${name}`)));
+      socket.on("data", chunk => { reply += chunk; if (reply.length > 8192) socket.destroy(new Error("oversized coverage reply")); });
+      socket.on("error", error => reject(new Error(`coverage process ${name} exited without a final report or could not be reached: ${error.message}`)));
+      socket.on("close", () => {
+        signal.removeEventListener("abort", abort);
+        if (reply.trim() === "ok") resolve();
+        else reject(new Error(`coverage process ${name} did not flush: ${reply.trim() || "process exited without a final report"}`));
+      });
+    });
+  }
+  return names.length;
+}
+
+/** Requires instrumented binaries calling the shipped coverage/rust.rs helper.
+ * The helper exports cumulative per-process LCOV before exit and on request;
+ * no compiler tools or binaries need to be copied out of terminated pods. */
+export function rust(options: RustCoverageOptions = {}): CoverageAdapter {
+  const { sourceRoot, excludeSources, llvmCov, llvmProfdata, ignoreFilenameRegex, buildRoot } = options;
+  if (buildRoot !== undefined && (!buildRoot.startsWith("/") || buildRoot === "/" || /[\0\r\n]/.test(buildRoot) || buildRoot.split("/").includes(".."))) throw new Error("Rust buildRoot must be an absolute compiler workspace directory");
+  for (const value of [llvmCov, llvmProfdata, ignoreFilenameRegex]) {
+    if (value !== undefined && (!value || /[\0\r\n]/.test(value))) throw new Error("invalid Rust coverage option");
+  }
+  return {
+    name: "rust", reports: "cumulative",
+    sourceOptions: { ...(sourceRoot !== undefined ? { sourceRoot } : {}), ...(excludeSources ? { excludeSources } : {}) },
+    ownsReport: name => /^rust-.*\.lcov$/.test(name),
+    configure: service => ({ ...service, env: { ...service.env,
+      SPECTEST_COVERAGE_DIR: "/spectest/coverage",
+      ...(buildRoot ? { SPECTEST_RUST_BUILD_ROOT: buildRoot } : {}),
+      ...(llvmCov ? { SPECTEST_LLVM_COV: llvmCov } : {}),
+      ...(llvmProfdata ? { SPECTEST_LLVM_PROFDATA: llvmProfdata } : {}),
+      ...(ignoreFilenameRegex ? { SPECTEST_RUST_IGNORE: ignoreFilenameRegex } : {}),
+    } }),
+    async capture(ctx) {
+      await flushCoverageSockets(ctx.reportDir, ".rust-ctl-", ctx.signal);
+      const names = await fs.readdir(ctx.reportDir);
+      if (names.some(name => name.startsWith("rust-error-"))) throw new Error("Rust coverage helper failed; inspect rust-error report");
+      if (!names.some(name => /^rust-.*\.lcov$/.test(name))) {
+        if (options.allowEmpty) { await ctx.writeReport("rust-empty.lcov", "TN:\n"); return; }
+        throw new Error("no Rust coverage reports: build with -C instrument-coverage and call spectest_coverage::start() before application work");
+      }
+    },
+  };
+}

package/src/coverage.test.ts

@@ -540,7 +540,7 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     const names = await dumpsIn(dir);
     expect(names.length).toBe(2);
     const byThread = new Map<string, Dump>();
-    for (const n of names) byThread.set(n.split("-")[2]!, await readDump(dir, n));
+    for (const n of names) byThread.set(n.split("-")[3]!, await readDump(dir, n));
     const recs = await records(dir);
     expect(recs.size).toBe(1); // one script, one record, whichever thread came first
     const rec = recs.get(`file://${path.join(dir, "threads.js")}`)!;
@@ -600,14 +600,14 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     expect(out.trim().split("\n")).toEqual(["npm:@s/b@2.0.0", "npm:a@1.0.0", "npm:c@3.0.0", "npm:d@4.0.0", "npm:e", "npm:f@6.0.0"]);
   });
 
-  test("a stale socket left by a killed process is removed at capture", async () => {
+  test("a killed covered process makes capture incomplete instead of silently losing execution", async () => {
     const dir = await scratch();
     const server = await start(dir, "server.js", 1);
     server.kill("SIGKILL");
     await new Promise<void>((r) => server.on("exit", () => r()));
     expect((await socketsIn(dir)).length).toBe(1); // SIGKILL: no exit handler, socket left behind
-    await node().capture!(fakeCtx(dir));
-    expect((await socketsIn(dir)).length).toBe(0);
+    await expect(node().capture!(fakeCtx(dir))).rejects.toThrow("without a final report");
+    expect((await socketsIn(dir)).length).toBe(1);
   });
 
   test("no process and no dump: an empty report is written, once", async () => {

package/src/coverage.ts

@@ -36,6 +36,8 @@ import { harvestAllBrowserCoverage, takeBrowserCoverageReport } from "./browser-
 import { COVERAGE_CONTAINER_DIR, type CoverageReportsMode } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR, type CoverageReportsMode };
 export { next, type NextCoverageOptions } from "./coverage-next.js";
+export { bun, type BunCoverageOptions } from "./coverage-bun.js";
+export { rust, rustHelperSource, type RustCoverageOptions } from "./coverage-rust.js";
 
 /** Where `node()` mounts its hook inside the container. */
 export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
@@ -44,7 +46,7 @@ export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
 export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
 
 /** Prefix of the per-process sockets the node hook answers on, relative
- *  to the coverage dir: `.ctl-<pid>`. */
+ *  to the coverage dir: `.ctl-<pid>-<nonce>`. */
 export const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
 
 
@@ -150,6 +152,10 @@ export interface CoverageAdapter {
   load?(ctx: CoverageLoadContext): void | Promise<void>;
   /** Make the report appear in the directory. A throw fails the test. */
   capture?(ctx: CoverageCaptureContext): void | Promise<void>;
+  /** Component-owned containers (for example k3s pods). Their reports retain
+   * their own source roots and counter baselines, rather than the outer
+   * service's filesystem identity. Internal: ordinary adapters use capture. */
+  collect?(ctx: CoverageInventoryContext & CoverageCaptureContext, baseline: boolean): Promise<import("./harness/coverage.js").ServiceCoverageCapture[]>;
   /**
    * Project paths (gitignore-style patterns, project-relative) whose
    * changes this adapter's **inventory** accounts for — a package
@@ -245,7 +251,7 @@ export function validateCoverage(service: string, cov: unknown): void {
         ((a as CoverageAdapter).explains === undefined ||
           (Array.isArray((a as CoverageAdapter).explains) &&
             ((a as CoverageAdapter).explains as unknown[]).every((e) => typeof e === "string"))) &&
-        ["configure", "load", "capture", "inventory", "ownsReport"].every(
+        ["configure", "load", "capture", "collect", "inventory", "ownsReport"].every(
           (k) =>
             (a as Record<string, unknown>)[k] === undefined ||
             typeof (a as Record<string, unknown>)[k] === "function",
@@ -398,7 +404,7 @@ export const NODE_COVERAGE_DUMP_PREFIX = "node-";
  *   without `--enable-source-maps`. For a bundled CLI that was 12 MB per
  *   invocation, inside the test's own time, parsed again at capture.
  * - **Takes** on request — the main thread binds a Unix socket
- *   `.ctl-<pid>` in the coverage directory and takes on `dump\n`; every
+ *   `.ctl-<pid>-<nonce>` in the coverage directory and takes on `dump\n`; every
  *   process binds its own (the first node process is often a wrapper,
  *   `pnpm exec`, `tsx`, `npm run`) — and in every thread's `exit`
  *   handler, which is how a short-lived CLI and a worker thread report.
@@ -448,6 +454,7 @@ export const NODE_COVERAGE_HOOK = `"use strict";
 (function () {
   const dir = process.env[${JSON.stringify(NODE_COVERAGE_DIR_ENV)}];
   if (!dir) return;
+  const bunRuntime = !!process.versions.bun && process.env.SPECTEST_COVERAGE_RUNTIME === "bun";
   let inspector, fs, path, crypto, url, wt, net;
   try {
     inspector = require("node:inspector");
@@ -468,19 +475,46 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   }
   // An in-process session answers before post() returns.
   function post(method, params) {
+    // Bun's callback API queues a microtask, including during process exit.
+    // Its synchronous return API is necessary for short-lived commands.
+    if (bunRuntime) return session.post(method, params || {});
     let out = null;
     session.post(method, params || {}, function (err, res) {
       out = err ? null : res;
     });
     return out;
   }
-  if (post("Profiler.enable") === null) return;
-  post("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
+  fs.mkdirSync(dir, { recursive: true });
+  function fail(error) {
+    fs.writeFileSync(path.join(dir, "coverage-error-" + process.pid + ".txt"), String(error));
+  }
+  try {
+    if (post("Profiler.enable") === null) throw new Error("coverage profiler unavailable");
+    if (!post("Profiler.startPreciseCoverage", { callCount: true, detailed: true })) throw new Error("precise coverage unavailable");
+    if (bunRuntime && (!process.versions.bun || !wt.isMainThread)) throw new Error("Bun coverage requires a supported main-thread runtime");
+  } catch (error) { fail(error); throw error; }
+  let bunRangeAdjustment = 0;
+  if (bunRuntime) {
+    // Bun releases have exposed both JSC-inclusive and V8-exclusive range
+    // ends. Probe the actual runtime before app code loads: interpreting an
+    // inclusive closing brace as exclusive attributes its source-map token
+    // to startup, making untouched function bodies appear boot-executed.
+    const probe = "let x=0;\\nfunction spectestCoverageProbe(){return 1;}\\nspectestCoverageProbe();\\n//# sourceURL=spectest-coverage-probe";
+    eval(probe);
+    const measured = post("Profiler.takePreciseCoverage");
+    const script = measured && measured.result.find(s => s.url === "spectest-coverage-probe");
+    const fn = script && script.functions.find(f => f.ranges[0].startOffset === probe.indexOf("function"));
+    if (!fn) { const error = new Error("Bun precise coverage capability probe failed"); fail(error); throw error; }
+    bunRangeAdjustment = probe.indexOf("}") + 1 - fn.ranges[0].endOffset;
+    if (bunRangeAdjustment !== 0 && bunRangeAdjustment !== 1) {
+      const error = new Error("unsupported Bun coverage range semantics"); fail(error); throw error;
+    }
+  }
 
   // Attach before app scripts execute. Enabling only at capture loses the
   // source of collected vm contexts (e.g. Temporal workflow bundles).
   // Bound V8's collected-script cache; live sources remain owned by V8.
-  post("Debugger.enable", { maxScriptsCacheSize: 16 * 1024 * 1024 });
+  if (!bunRuntime) post("Debugger.enable", { maxScriptsCacheSize: 16 * 1024 * 1024 });
 
   const GENERATED = new Map();
   try {
@@ -499,6 +533,10 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   // can be reused by another process, vm context, or compilation.
   const known = new Map();
   let seq = 0;
+  const processToken = process.pid + "-" + crypto.randomBytes(6).toString("hex");
+  const liveMarker = path.join(dir, ".live-" + processToken + "-" + wt.threadId);
+  fs.writeFileSync(liveMarker, "");
+  fs.writeFileSync(path.join(dir, ".attached-" + (bunRuntime ? "bun" : "node")), "");
 
   function isApp(u) {
     return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF;
@@ -674,6 +712,12 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     const kept = [];
     const units = new Set();
     for (const s of res.result) {
+      if (bunRuntime && bunRangeAdjustment && Array.isArray(s.functions)) {
+        const length = Math.max(...s.functions.flatMap(f => f.ranges.map(r => r.endOffset)));
+        for (const f of s.functions) for (const range of f.ranges) {
+          if (range.endOffset < length) range.endOffset += bunRangeAdjustment;
+        }
+      }
       if (!Array.isArray(s.functions) || !s.functions.some(ran)) continue;
       if (isApp(s.url)) kept.push(s);
       else if (isDep(s.url)) {
@@ -695,7 +739,18 @@ export const NODE_COVERAGE_HOOK = `"use strict";
         fs.mkdirSync(MARKERS, { recursive: true });
       } catch (e) {}
       for (const s of fresh) {
-        const r = post("Debugger.getScriptSource", { scriptId: s.scriptId });
+        let r;
+        if (bunRuntime) {
+          // Bun does not expose getScriptSource through the in-process API.
+          // Accept only precompiled, untranspiled bundles, never guess that
+          // disk TypeScript offsets describe executed JavaScript.
+          const source = fs.readFileSync(url.fileURLToPath(s.url), "utf8");
+          const extent = Math.max(...s.functions.flatMap(f => f.ranges.map(r => r.endOffset)));
+          if (!source.startsWith("// @bun\\n") || source.length !== extent) {
+            throw new Error("Bun coverage needs an unchanged bun build --target=bun bundle with source maps: " + s.url);
+          }
+          r = { scriptSource: source };
+        } else r = post("Debugger.getScriptSource", { scriptId: s.scriptId });
         try {
           const source = r && r.scriptSource;
           if (GENERATED.has(s.url) && typeof source === "string") {
@@ -737,12 +792,12 @@ export const NODE_COVERAGE_HOOK = `"use strict";
         };
       }),
     };
-    const name = ${JSON.stringify(NODE_COVERAGE_DUMP_PREFIX)} + process.pid + "-" + wt.threadId + "-" + Date.now() + "-" + seq++ + ".json";
+    const name = ${JSON.stringify(NODE_COVERAGE_DUMP_PREFIX)} + processToken + "-" + wt.threadId + "-" + Date.now() + "-" + seq++ + ".json";
     writeAtomic(path.join(dir, name), JSON.stringify(doc));
   }
 
   if (wt.isMainThread) {
-    const SOCK = path.join(dir, ${JSON.stringify(NODE_COVERAGE_SOCKET_PREFIX)} + process.pid);
+    const SOCK = path.join(dir, ${JSON.stringify(NODE_COVERAGE_SOCKET_PREFIX)} + processToken);
     const server = net.createServer(function (conn) {
       let buf = "";
       conn.on("data", function (chunk) {
@@ -754,6 +809,7 @@ export const NODE_COVERAGE_HOOK = `"use strict";
           take();
           reply = "ok\\n";
         } catch (err) {
+          fail(err);
           reply = "error " + (err && err.message ? err.message : String(err)) + "\\n";
         }
         conn.end(reply);
@@ -774,7 +830,8 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   process.on("exit", function () {
     try {
       take();
-    } catch (e) {}
+      fs.unlinkSync(liveMarker);
+    } catch (e) { fail(e); }
   });
 })();
 `;
@@ -992,9 +1049,9 @@ export function node(options: NodeCoverageOptions = {}): CoverageAdapter {
 
 /**
  * Ask every node process that holds a hook socket in `dir` for a dump.
- * A socket nobody answers (its process died without unlinking — SIGKILL,
- * OOM) is removed. Returns how many processes answered; a process that
- * answered with an error throws.
+ * An unanswered socket with a live marker means the process died without
+ * a final report and fails collection. Stale sockets without live markers
+ * are removed. Returns how many processes answered; error replies throw.
  */
 export async function dumpAllNodeProcesses(dir: string, signal: AbortSignal): Promise<number> {
   const fs = await import("node:fs/promises");
@@ -1029,6 +1086,10 @@ export async function dumpAllNodeProcesses(dir: string, signal: AbortSignal): Pr
       });
     });
     if (reply === null) {
+      const pid = name.slice(NODE_COVERAGE_SOCKET_PREFIX.length);
+      if ((await fs.readdir(dir)).some(marker => marker.startsWith(".live-" + pid + "-"))) {
+        throw new Error(`coverage process ${name} exited without a final report`);
+      }
       // Nobody home: the process is gone. Clean up so the next capture
       // does not knock again.
       await fs.unlink(sock).catch(() => {});