Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
// merge-lcov.test.ts — behavioral, fixture-locked tests for
// scripts/merge-lcov.ts (containment-sprint coverage machinery).
//
// Fixtures are inline synthetic lcov strings written into tmp lane dirs;
// the script runs as a subprocess from the repo root (SF normalization and
// the neverLoaded scan resolve against process.cwd()).
import { afterAll, beforeAll, describe, expect, it } from "bun:test";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { basename, join } from "node:path";
import { isMergedArtifactPath, normalizeSf, parseLcovText } from "../../scripts/merge-lcov.ts";
const REPO_ROOT = join(import.meta.dir, "..", "..");
const HEAD_SHA = Bun.spawnSync(['git', 'rev-parse', 'HEAD'], { cwd: REPO_ROOT }).stdout.toString().trim();
interface RunResult {
code: number;
stdout: string;
stderr: string;
}
function runMerge(args: string[], env: Record<string, string> = {}): RunResult {
const res = Bun.spawnSync(["bun", join(REPO_ROOT, "scripts", "merge-lcov.ts"), ...args], {
cwd: REPO_ROOT,
env: { ...process.env, GENERATED_AT: "2026-08-15T00:00:00.000Z", ...env },
stdout: "pipe",
stderr: "pipe",
});
return { code: res.exitCode, stdout: res.stdout.toString(), stderr: res.stderr.toString() };
}
let tmp: string;
beforeAll(() => {
tmp = mkdtempSync(join(tmpdir(), "merge-lcov-test-"));
});
afterAll(() => {
rmSync(tmp, { recursive: true, force: true });
});
function laneDir(name: string, lcovText: string, manifest?: object): string {
const dir = join(tmp, name);
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, "lcov.info"), lcovText, "utf8");
if (manifest) writeFileSync(join(dir, "lane-manifest.json"), JSON.stringify(manifest), "utf8");
return dir;
}
function outPaths(name: string): { lcov: string; json: string } {
return { lcov: join(tmp, `${name}.lcov.info`), json: join(tmp, `${name}.json`) };
}
interface SummaryShape {
generatedAt: string;
corpus: string;
lanes: { expected: string[]; complete: string[] };
degraded: boolean;
total: { lines: number; covered: number; pct: number };
dirs: Record<string, { lines: number; covered: number; pct: number }>;
files: Record<string, { lines: number; covered: number; pct: number }>;
functionCoverage: string;
neverLoaded: { count: number; files: string[] };
lineHits: Record<string, Record<string, number>>;
}
function readSummary(path: string): SummaryShape {
return JSON.parse(readFileSync(path, "utf8")) as SummaryShape;
}
const LANE_A = [
"TN:",
"SF:src/fixture-cov-a.ts",
"FN:1,alpha",
"FNDA:2,alpha",
"DA:1,1",
"DA:2,0",
"DA:3,5",
"LF:3",
"LH:2",
"end_of_record",
"",
].join("\n");
const LANE_B = [
"TN:",
"SF:src/fixture-cov-a.ts",
"FN:1,alpha",
"FNDA:3,alpha",
"DA:1,2",
"DA:2,0",
"DA:4,7",
"end_of_record",
"",
].join("\n");
describe("merge: DA summing across lanes", () => {
it("sums per-line hits, unions lines, regenerates counters", () => {
const a = laneDir("sum-a", LANE_A);
const b = laneDir("sum-b", LANE_B);
const out = outPaths("sum");
const res = runMerge(["--out-lcov", out.lcov, "--out-json", out.json, a, b]);
expect(res.code).toBe(0);
const lcov = readFileSync(out.lcov, "utf8");
expect(lcov).toContain("SF:src/fixture-cov-a.ts");
expect(lcov).toContain("DA:1,3"); // 1 + 2
expect(lcov).toContain("DA:2,0"); // 0 + 0
expect(lcov).toContain("DA:3,5"); // lane A only
expect(lcov).toContain("DA:4,7"); // lane B only
expect(lcov).toContain("FNDA:5,alpha"); // 2 + 3 summed per function name
expect(lcov).toContain("FNF:1");
expect(lcov).toContain("FNH:1");
expect(lcov).toContain("LF:4");
expect(lcov).toContain("LH:3");
const json = readSummary(out.json);
expect(json.files["src/fixture-cov-a.ts"]).toEqual({ lines: 4, covered: 3, pct: 75 });
expect(json.lineHits["src/fixture-cov-a.ts"]).toEqual({ "1": 3, "2": 0, "3": 5, "4": 7 });
expect(json.degraded).toBe(false);
expect(json.functionCoverage).toBe("informational");
expect(json.generatedAt).toBe("2026-08-15T00:00:00.000Z");
});
it("honors COVERAGE_CORPUS and defaults to 'unknown'", () => {
const a = laneDir("corpus-a", LANE_A);
const out = outPaths("corpus");
runMerge(["--out-lcov", out.lcov, "--out-json", out.json, a], { COVERAGE_CORPUS: "prCorpus" });
expect(readSummary(out.json).corpus).toBe("prCorpus");
const out2 = outPaths("corpus2");
const res = Bun.spawnSync(
["bun", join(REPO_ROOT, "scripts", "merge-lcov.ts"), "--out-lcov", out2.lcov, "--out-json", out2.json, a],
{
cwd: REPO_ROOT,
env: { ...process.env, COVERAGE_CORPUS: "", GENERATED_AT: "2026-08-15T00:00:00.000Z" },
stdout: "pipe",
stderr: "pipe",
},
);
expect(res.exitCode).toBe(0);
expect(readSummary(out2.json).corpus).toBe("unknown");
});
});
describe("merge: SF normalization", () => {
it("merges absolute, repo-relative, and foreign-checkout-prefix SF paths into one record", () => {
const abs = [
`SF:${REPO_ROOT}/src/fixture-cov-n.ts`,
"DA:1,1",
"end_of_record",
"",
].join("\n");
const rel = ["SF:src/fixture-cov-n.ts", "DA:1,1", "DA:2,4", "end_of_record", ""].join("\n");
const foreign = [
`SF:/ci/runner/work/${basename(REPO_ROOT)}/src/fixture-cov-n.ts`,
"DA:1,1",
"end_of_record",
"",
].join("\n");
const a = laneDir("norm-a", abs);
const b = laneDir("norm-b", rel);
const c = laneDir("norm-c", foreign);
const out = outPaths("norm");
const res = runMerge(["--out-lcov", out.lcov, "--out-json", out.json, a, b, c]);
expect(res.code).toBe(0);
const json = readSummary(out.json);
expect(Object.keys(json.files)).toEqual(["src/fixture-cov-n.ts"]);
// 1+1+1 on line 1, 4 on line 2 — all three spellings merged.
expect(json.lineHits["src/fixture-cov-n.ts"]).toEqual({ "1": 3, "2": 4 });
const lcov = readFileSync(out.lcov, "utf8");
expect(lcov.match(/^SF:/gm)?.length).toBe(1);
});
it("normalizeSf unit: strips cwd, strips any prefix ending in the repo dir name, keeps relatives", () => {
expect(normalizeSf(`${REPO_ROOT}/src/a.ts`, REPO_ROOT)).toBe("src/a.ts");
expect(normalizeSf(`/ci/work/${basename(REPO_ROOT)}/src/a.ts`, REPO_ROOT)).toBe("src/a.ts");
expect(normalizeSf("src/a.ts", REPO_ROOT)).toBe("src/a.ts");
expect(normalizeSf("./src/a.ts", REPO_ROOT)).toBe("src/a.ts");
expect(normalizeSf("/somewhere/else/src/a.ts", REPO_ROOT)).toBe("/somewhere/else/src/a.ts");
});
});
describe("merge: malformed input handling", () => {
it("skips a malformed lcov file whole and marks degraded, keeping the good lane", () => {
const good = laneDir("mal-good", LANE_A);
const bad = laneDir("mal-bad", "DA:1,1\n"); // DA outside any SF record
const out = outPaths("mal");
const res = runMerge(["--out-lcov", out.lcov, "--out-json", out.json, good, bad]);
expect(res.code).toBe(0); // never aborts
expect(res.stderr).toContain("malformed");
const json = readSummary(out.json);
expect(json.degraded).toBe(true);
expect(json.files["src/fixture-cov-a.ts"]).toEqual({ lines: 3, covered: 2, pct: 66.67 });
});
it("treats a truncated file (SF without end_of_record) as malformed", () => {
const bad = laneDir("trunc-bad", "SF:src/fixture-trunc.ts\nDA:1,1\n");
const out = outPaths("trunc");
const res = runMerge(["--out-lcov", out.lcov, "--out-json", out.json, bad]);
expect(res.code).toBe(0);
const json = readSummary(out.json);
expect(json.degraded).toBe(true);
expect(json.files["src/fixture-trunc.ts"]).toBeUndefined(); // whole file skipped
});
it("parseLcovText unit: unknown record types warn and are skipped without malforming", () => {
const res = parseLcovText("SF:src/x.ts\nBRDA:1,0,0,1\nDA:1,1\nend_of_record\n");
expect(res.malformed).toBe(false);
expect(res.warnings.some((w) => w.includes("BRDA"))).toBe(true);
expect(res.records[0]?.da).toEqual([[1, 1]]);
});
it("parseLcovText unit: non-numeric DA is malformed", () => {
const res = parseLcovText("SF:src/x.ts\nDA:one,1\nend_of_record\n");
expect(res.malformed).toBe(true);
expect(res.records).toEqual([]);
});
});
describe("merge: lane manifests", () => {
const GOOD_MANIFEST = { lane: "shard-1", sha: HEAD_SHA, lcovCount: 1, complete: true };
it("complete expected lanes → not degraded; lanes.complete lists them", () => {
const a = laneDir("man-ok", LANE_A, GOOD_MANIFEST);
const out = outPaths("man-ok");
const res = runMerge(["--out-lcov", out.lcov, "--out-json", out.json, "--manifest-expect", "shard-1", a]);
expect(res.code).toBe(0);
const json = readSummary(out.json);
expect(json.degraded).toBe(false);
expect(json.lanes.expected).toEqual(["shard-1"]);
expect(json.lanes.complete).toEqual(["shard-1"]);
});
it("missing manifest for an expected lane → degraded", () => {
const a = laneDir("man-miss", LANE_A, GOOD_MANIFEST);
const out = outPaths("man-miss");
const res = runMerge([
"--out-lcov", out.lcov, "--out-json", out.json,
"--manifest-expect", "shard-1,serial", a,
]);
expect(res.code).toBe(0);
expect(res.stderr).toContain("serial");
const json = readSummary(out.json);
expect(json.degraded).toBe(true);
expect(json.lanes.expected).toEqual(["shard-1", "serial"]);
expect(json.lanes.complete).toEqual(["shard-1"]);
});
it("incomplete manifest for an expected lane → degraded", () => {
const a = laneDir("man-inc", LANE_A, { ...GOOD_MANIFEST, complete: false });
const out = outPaths("man-inc");
runMerge(["--out-lcov", out.lcov, "--out-json", out.json, "--manifest-expect", "shard-1", a]);
const json = readSummary(out.json);
expect(json.degraded).toBe(true);
expect(json.lanes.complete).toEqual([]);
});
it("shard manifest with lcovCount != 1 → degraded (xargs-batching tripwire)", () => {
const a = laneDir("man-two", LANE_A, { ...GOOD_MANIFEST, lcovCount: 2 });
const out = outPaths("man-two");
const res = runMerge(["--out-lcov", out.lcov, "--out-json", out.json, "--manifest-expect", "shard-1", a]);
expect(res.stderr).toContain("lcovCount=2");
expect(readSummary(out.json).degraded).toBe(true);
});
it("non-shard lane may carry many lcov files without tripping the tripwire", () => {
const a = laneDir("man-serial", LANE_A, { lane: "serial", sha: HEAD_SHA, lcovCount: 2, complete: true });
mkdirSync(join(a, 'second'));
writeFileSync(join(a, 'second/lcov.info'), LANE_B);
const out = outPaths("man-serial");
runMerge(["--out-lcov", out.lcov, "--out-json", out.json, "--manifest-expect", "serial", a]);
expect(readSummary(out.json).degraded).toBe(false);
});
it('requires every serial shard and accepts their independent multi-file counts', () => {
const dirs = Array.from({ length: 4 }, (_, i) => {
const dir = laneDir(`serial-matrix-${i}`, LANE_A, { lane: `serial-${i + 1}`, sha: HEAD_SHA, lcovCount: 2, complete: true });
mkdirSync(join(dir, 'second'));
writeFileSync(join(dir, 'second/lcov.info'), LANE_B);
return dir;
});
const out = outPaths('serial-matrix');
const args = ['--out-lcov', out.lcov, '--out-json', out.json, '--manifest-expect', 'serial-1,serial-2,serial-3,serial-4'];
expect(runMerge([...args, ...dirs]).code).toBe(0);
expect(readSummary(out.json).degraded).toBe(false);
runMerge([...args, ...dirs.slice(0, 3)]);
expect(readSummary(out.json).degraded).toBe(true);
});
it('requires all four nightly E2E identities with their independent multi-process LCOV counts', () => {
const dirs = Array.from({ length: 4 }, (_, i) => {
const dir = laneDir(`nightly-e2e-${i}`, LANE_A, { lane: `e2e-${i + 1}`, sha: HEAD_SHA, lcovCount: 2, complete: true });
mkdirSync(join(dir, 'second'));
writeFileSync(join(dir, 'second/lcov.info'), LANE_B);
return dir;
});
const out = outPaths('nightly-e2e');
const args = ['--out-lcov', out.lcov, '--out-json', out.json, '--manifest-expect', 'e2e-1,e2e-2,e2e-3,e2e-4'];
runMerge([...args, ...dirs]);
expect(readSummary(out.json).degraded).toBe(false);
expect(readSummary(out.json).lanes.complete).toEqual(['e2e-1', 'e2e-2', 'e2e-3', 'e2e-4']);
for (let absent = 0; absent < 4; absent++) {
runMerge([...args, ...dirs.filter((_, index) => index !== absent)]);
expect(readSummary(out.json).degraded).toBe(true);
}
rmSync(join(dirs[3], 'second/lcov.info'));
runMerge([...args, ...dirs]);
expect(readSummary(out.json).degraded).toBe(true);
expect(readSummary(out.json).lanes.complete).not.toContain('e2e-4');
});
it.each([
['missing count', { lcovCount: undefined }],
['wrong count', { lcovCount: 2 }],
['negative count', { lcovCount: -1 }],
['fractional count', { lcovCount: 1.5 }],
['wrong SHA', { sha: 'other-commit' }],
['missing SHA', { sha: undefined }],
])('%s cannot report complete coverage', (name, changes) => {
const a = laneDir(`metadata-${name}`, LANE_A, { ...GOOD_MANIFEST, lane: 'serial-1', ...changes });
const out = outPaths(`metadata-${name}`);
const result = runMerge(['--out-lcov', out.lcov, '--out-json', out.json, '--manifest-expect', 'serial-1', a]);
expect(result.code).toBe(0); // advisory degradation, never a test-result verdict
expect(readSummary(out.json).degraded).toBe(true);
expect(readSummary(out.json).lanes.complete).toEqual([]);
});
it('a missing LCOV file invalidates the lane count', () => {
const a = laneDir('missing-lcov', LANE_A, { ...GOOD_MANIFEST, lane: 'serial-1' });
rmSync(join(a, 'lcov.info'));
const out = outPaths('missing-lcov');
runMerge(['--out-lcov', out.lcov, '--out-json', out.json, '--manifest-expect', 'serial-1', a]);
expect(readSummary(out.json).degraded).toBe(true);
});
it('duplicate lane identities cannot satisfy the expected lane', () => {
const a = laneDir('duplicate-a', LANE_A, GOOD_MANIFEST);
const b = laneDir('duplicate-b', LANE_B, GOOD_MANIFEST);
const out = outPaths('duplicate');
const result = runMerge(['--out-lcov', out.lcov, '--out-json', out.json, '--manifest-expect', 'shard-1', a, b]);
expect(result.stderr).toContain('duplicate manifests');
expect(readSummary(out.json).degraded).toBe(true);
expect(readSummary(out.json).lanes.complete).toEqual([]);
});
it('--sha validates historical artifacts independently of the checkout', () => {
const a = laneDir('historical', LANE_A, { ...GOOD_MANIFEST, sha: 'historical-commit' });
const out = outPaths('historical');
runMerge(['--out-lcov', out.lcov, '--out-json', out.json, '--sha', 'historical-commit', '--manifest-expect', 'shard-1', a]);
expect(readSummary(out.json).degraded).toBe(false);
});
});
describe("merge: JSON metrics scope + hand-computed totals", () => {
const LANE_C = [
"SF:src/fixture-tot-one.ts",
"DA:1,1",
"DA:2,0",
"end_of_record",
"SF:src/core/fixture-tot-two.ts",
"DA:10,3",
"DA:11,1",
"DA:12,0",
"end_of_record",
"SF:test/fixture-tot.test.ts",
"DA:1,1",
"end_of_record",
"SF:scripts/fixture-tot-tool.ts",
"DA:1,1",
"end_of_record",
"",
].join("\n");
it("totals/dirs/files count src/ only; out-lcov keeps every record", () => {
const c = laneDir("tot-c", LANE_C);
const out = outPaths("tot");
const res = runMerge(["--out-lcov", out.lcov, "--out-json", out.json, c]);
expect(res.code).toBe(0);
const json = readSummary(out.json);
// Hand-computed: src lines 2+3=5, covered 1+2=3 → 60%.
expect(json.total).toEqual({ lines: 5, covered: 3, pct: 60 });
expect(json.dirs["src"]).toEqual({ lines: 2, covered: 1, pct: 50 });
expect(json.dirs["src/core"]).toEqual({ lines: 3, covered: 2, pct: 66.67 });
expect(Object.keys(json.files).sort()).toEqual([
"src/core/fixture-tot-two.ts",
"src/fixture-tot-one.ts",
]);
expect(json.lineHits["test/fixture-tot.test.ts"]).toBeUndefined();
// Non-src records stay in the merged lcov artifact.
const lcov = readFileSync(out.lcov, "utf8");
expect(lcov).toContain("SF:test/fixture-tot.test.ts");
expect(lcov).toContain("SF:scripts/fixture-tot-tool.ts");
});
it("neverLoaded inventories real src files absent from the data — count + sorted list, no percentage", () => {
const c = laneDir("never-c", LANE_C);
const out = outPaths("never");
runMerge(["--out-lcov", out.lcov, "--out-json", out.json, c]);
const json = readSummary(out.json);
// The fixture files are "loaded" (present in data); every real src file is not.
expect(json.neverLoaded.count).toBe(json.neverLoaded.files.length);
expect(json.neverLoaded.files).toContain("src/cli.ts");
expect(json.neverLoaded.files).not.toContain("src/fixture-tot-one.ts");
const sorted = [...json.neverLoaded.files].sort();
expect(json.neverLoaded.files).toEqual(sorted);
expect(json.neverLoaded.files.every((f) => !f.endsWith(".test.ts") && !f.endsWith(".d.ts"))).toBe(true);
});
});
describe("merge: self-merge guard (coverage-merged exclusion)", () => {
it("skips lcov.info under a coverage-merged path segment without degrading", () => {
// CI report-job re-runs download the PRIOR run's own coverage-merged
// artifact via the coverage-* glob; re-merging it would double every hit
// count. The guard drops it while keeping real lanes.
laneDir("selfmerge/lane-a", LANE_A);
laneDir(
"selfmerge/coverage-merged",
["SF:src/fixture-prior-merged.ts", "DA:1,100", "end_of_record", ""].join("\n"),
);
const out = outPaths("selfmerge");
const res = runMerge(["--out-lcov", out.lcov, "--out-json", out.json, join(tmp, "selfmerge")]);
expect(res.code).toBe(0);
expect(res.stderr).toContain("self-merge guard");
const json = readSummary(out.json);
expect(json.files["src/fixture-prior-merged.ts"]).toBeUndefined(); // prior artifact dropped
expect(json.files["src/fixture-cov-a.ts"]).toEqual({ lines: 3, covered: 2, pct: 66.67 }); // real lane kept
expect(json.degraded).toBe(false); // expected on re-runs, not data loss
});
it("skips a direct lcov.info FILE input under a coverage-merged segment", () => {
laneDir("selfmerge-direct/coverage-merged", LANE_A);
const a = laneDir("selfmerge-direct/lane-a", LANE_A);
const out = outPaths("selfmerge-direct");
const res = runMerge([
"--out-lcov", out.lcov, "--out-json", out.json,
join(tmp, "selfmerge-direct", "coverage-merged", "lcov.info"),
a,
]);
expect(res.code).toBe(0);
expect(res.stderr).toContain("self-merge guard");
// Only the real lane merged: hits are lane-A's alone, not doubled.
expect(readSummary(out.json).lineHits["src/fixture-cov-a.ts"]).toEqual({ "1": 1, "2": 0, "3": 5 });
});
it("isMergedArtifactPath unit: matches a path SEGMENT, not a substring", () => {
expect(isMergedArtifactPath("/dl/coverage-merged/lcov.info")).toBe(true);
expect(isMergedArtifactPath("dl/coverage-merged/nested/lcov.info")).toBe(true);
expect(isMergedArtifactPath("/dl/coverage-merged-old/lcov.info")).toBe(false);
expect(isMergedArtifactPath("/dl/coverage-shard1/lcov.info")).toBe(false);
});
});
describe("merge: CLI contract", () => {
it("missing required args → exit 2", () => {
const res = runMerge(["--out-lcov", join(tmp, "x.lcov")]);
expect(res.code).toBe(2);
expect(res.stderr).toContain("usage");
});
it("nonexistent input path warns and marks degraded, never aborts", () => {
const a = laneDir("ghost-a", LANE_A);
const out = outPaths("ghost");
const res = runMerge(["--out-lcov", out.lcov, "--out-json", out.json, a, join(tmp, "does-not-exist")]);
expect(res.code).toBe(0);
expect(res.stderr).toContain("not found");
expect(readSummary(out.json).degraded).toBe(true);
});
});