Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
21.8 KB
Raw Blame
#!/usr/bin/env bun
/**
 * scripts/merge-lcov.ts — merge per-lane bun lcov.info files into one
 * artifact pair: a regenerated merged lcov + a JSON summary for the
 * coverage gates (containment sprint).
 *
 * Usage:
 *   bun scripts/merge-lcov.ts --out-lcov <path> --out-json <path> \
 *     [--manifest-expect <lane,lane,...>] [--sha <commit>] <dir-or-file>...
 *
 * Behavior:
 *   - Recursively finds every lcov.info under the input dirs (a file input
 *     is used directly). Only LOADED files appear in bun's lcov output; a
 *     src file that never appears was never imported by any test. Any
 *     lcov.info under a `coverage-merged` path segment is skipped: report-
 *     job re-runs download the prior run's merged artifact via the
 *     `coverage-*` glob, and re-merging it would double every hit count.
 *   - Parses SF/DA/FN/FNDA/LF/LH/TN/end_of_record. Unknown record types
 *     (e.g. BRDA) warn to stderr and are SKIPPED — never passed through.
 *   - A malformed/truncated lcov.info warns, is skipped WHOLE, and marks
 *     the summary degraded — the merge never aborts on bad lane data.
 *   - SF normalization: absolute paths become repo-relative POSIX paths
 *     (repo root = process.cwd(); any absolute prefix ending in the repo
 *     directory name is also stripped), then deduped/merged.
 *   - Merge math: DA hits summed per file:line; FNDA hits summed per
 *     function name. All output records are REGENERATED from parsed data
 *     (fresh FN/FNDA/FNF/FNH/LF/LH). bun/JSC omits function names, so
 *     function records are informational only — line records are the only
 *     gate input (summary carries functionCoverage: 'informational').
 *   - Lane manifests: each lane dir may contain lane-manifest.json
 *     {lane, sha, lcovCount, complete}. With --manifest-expect, a
 *     missing/incomplete manifest for an expected lane marks degraded.
 *     Duplicate lane identities, a SHA other than --sha (default HEAD),
 *     or an lcovCount unlike the files under that manifest also degrade.
 *     A manifest whose lane name contains 'shard' with lcovCount != 1
 *     marks degraded: the shard lane runs ONE bun process via xargs -x;
 *     a second bun process reusing the coverage dir would have OVERWRITTEN
 *     lcov.info, so any other count means the xargs-batching tripwire
 *     fired and line data was silently lost.
 *   - JSON metrics count src/ files ONLY (test/, scripts/, node_modules
 *     records are kept in the merged out-lcov but excluded from
 *     totals/dirs/files). neverLoaded lists src/**\/*.ts files (non-test,
 *     non-generated, non-*.d.ts) absent from the merged data — a COUNT +
 *     sorted list, deliberately NEVER a fake all-files percentage
 *     (physical lines != executable lines).
 *   - lineHits (EXTENSION KEY, consumed by scripts/coverage-diff-gate.ts):
 *     per-src-file per-line merged DA hits, so the gates read ONE JSON
 *     artifact and never re-parse lcov text.
 *
 * Env:
 *   COVERAGE_CORPUS  names the corpus ('prCorpus'|'fullCorpus'; default
 *                    'unknown').
 *   GENERATED_AT     overrides the generatedAt timestamp (fixture-locked
 *                    tests).
 *
 * Exit codes: 0 success (including degraded — degraded is DATA, carried in
 * the summary for the gates to downgrade on); 2 usage/IO error.
 */

import {
  existsSync,
  mkdirSync,
  readFileSync,
  readdirSync,
  statSync,
  writeFileSync,
} from "node:fs";
import { dirname, join, resolve, sep } from "node:path";
import { spawnSync } from "node:child_process";

// ---------------------------------------------------------------------------
// Parsing
// ---------------------------------------------------------------------------

export interface LcovFileRecord {
  sf: string;
  /** [line, hits] pairs, in file order (may repeat lines across records). */
  da: Array<[number, number]>;
  /** [line, name] pairs. */
  fn: Array<[number, string]>;
  /** [hits, name] pairs. */
  fnda: Array<[number, string]>;
}

export interface ParseResult {
  records: LcovFileRecord[];
  warnings: string[];
  /** True when the file is malformed/truncated; caller must skip it whole. */
  malformed: boolean;
}

/** Record types we parse but do not carry through (they are recomputed). */
const KNOWN_RECOMPUTED = new Set(["TN", "FNF", "FNH", "LF", "LH"]);

/**
 * Parse one lcov.info text. Never throws. On any malformed/truncated
 * structure, returns malformed:true — the caller drops the whole file.
 */
export function parseLcovText(text: string): ParseResult {
  const warnings: string[] = [];
  const warnedTypes = new Set<string>();
  const records: LcovFileRecord[] = [];
  let current: LcovFileRecord | null = null;

  const fail = (msg: string): ParseResult => {
    warnings.push(msg);
    return { records: [], warnings, malformed: true };
  };

  const lines = text.split("\n");
  for (let i = 0; i < lines.length; i++) {
    const raw = lines[i] ?? "";
    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
    if (line.trim() === "") continue;

    if (line === "end_of_record") {
      if (!current) return fail(`line ${i + 1}: end_of_record without SF`);
      records.push(current);
      current = null;
      continue;
    }

    const colon = line.indexOf(":");
    if (colon < 0) return fail(`line ${i + 1}: unparseable line ${JSON.stringify(line)}`);
    const type = line.slice(0, colon);
    const rest = line.slice(colon + 1);

    if (type === "SF") {
      if (current) return fail(`line ${i + 1}: SF while previous record open (missing end_of_record)`);
      if (rest.trim() === "") return fail(`line ${i + 1}: SF with empty path`);
      current = { sf: rest.trim(), da: [], fn: [], fnda: [] };
      continue;
    }
    if (KNOWN_RECOMPUTED.has(type)) continue; // parsed + ignored; regenerated on output
    if (type === "DA") {
      if (!current) return fail(`line ${i + 1}: DA outside an SF record`);
      const parts = rest.split(",");
      const ln = Number(parts[0]);
      const hits = Number(parts[1]);
      if (!Number.isFinite(ln) || !Number.isFinite(hits)) {
        return fail(`line ${i + 1}: malformed DA record ${JSON.stringify(line)}`);
      }
      current.da.push([ln, hits]);
      continue;
    }
    if (type === "FN") {
      if (!current) return fail(`line ${i + 1}: FN outside an SF record`);
      const comma = rest.indexOf(",");
      const ln = Number(comma < 0 ? rest : rest.slice(0, comma));
      const name = comma < 0 ? "" : rest.slice(comma + 1);
      if (!Number.isFinite(ln)) return fail(`line ${i + 1}: malformed FN record`);
      current.fn.push([ln, name]);
      continue;
    }
    if (type === "FNDA") {
      if (!current) return fail(`line ${i + 1}: FNDA outside an SF record`);
      const comma = rest.indexOf(",");
      const hits = Number(comma < 0 ? rest : rest.slice(0, comma));
      const name = comma < 0 ? "" : rest.slice(comma + 1);
      if (!Number.isFinite(hits)) return fail(`line ${i + 1}: malformed FNDA record`);
      current.fnda.push([hits, name]);
      continue;
    }
    // Unknown record type: warn once per type per file, skip (no pass-through).
    if (!warnedTypes.has(type)) {
      warnedTypes.add(type);
      warnings.push(`unknown lcov record type ${JSON.stringify(type)} — skipped`);
    }
  }
  if (current) return fail("truncated file: SF record without end_of_record");
  return { records, warnings, malformed: false };
}

// ---------------------------------------------------------------------------
// SF normalization
// ---------------------------------------------------------------------------

/**
 * Normalize an SF path to repo-relative POSIX. Repo root = repoRootAbs
 * (process.cwd() in production). Also strips any absolute prefix ending in
 * the repo directory name (CI checkouts live under a different absolute
 * root than the machine that reads the artifact).
 */
export function normalizeSf(sfRaw: string, repoRootAbs: string): string {
  let p = sfRaw.replace(/\\/g, "/");
  const root = repoRootAbs.replace(/\\/g, "/").replace(/\/+$/, "");
  if (p === root) return "";
  if (p.startsWith(root + "/")) p = p.slice(root.length + 1);
  else if (p.startsWith("/") || /^[A-Za-z]:\//.test(p)) {
    const repoDirName = root.slice(root.lastIndexOf("/") + 1);
    const marker = "/" + repoDirName + "/";
    const idx = p.lastIndexOf(marker);
    if (idx >= 0) p = p.slice(idx + marker.length);
    // else: absolute path outside any recognizable repo prefix — keep as-is;
    // it will not match src/ and stays out of the JSON metrics.
  }
  while (p.startsWith("./")) p = p.slice(2);
  return p;
}

// ---------------------------------------------------------------------------
// Merging
// ---------------------------------------------------------------------------

export interface MergedFile {
  /** line -> summed hits */
  da: Map<number, number>;
  /** function name -> first (lowest) line seen */
  fnLine: Map<string, number>;
  /** function name -> summed hits */
  fnda: Map<string, number>;
}

export type Merged = Map<string, MergedFile>;

export function mergeRecord(merged: Merged, sfNormalized: string, rec: LcovFileRecord): void {
  let f = merged.get(sfNormalized);
  if (!f) {
    f = { da: new Map(), fnLine: new Map(), fnda: new Map() };
    merged.set(sfNormalized, f);
  }
  for (const [line, hits] of rec.da) f.da.set(line, (f.da.get(line) ?? 0) + hits);
  for (const [line, name] of rec.fn) {
    const prev = f.fnLine.get(name);
    if (prev === undefined || line < prev) f.fnLine.set(name, line);
  }
  for (const [hits, name] of rec.fnda) f.fnda.set(name, (f.fnda.get(name) ?? 0) + hits);
}

/** Regenerate a merged lcov text from parsed data (fresh counters). */
export function emitLcov(merged: Merged): string {
  const out: string[] = [];
  const files = [...merged.keys()].sort();
  for (const file of files) {
    const f = merged.get(file)!;
    out.push("TN:");
    out.push(`SF:${file}`);
    const fnEntries = [...f.fnLine.entries()].sort((a, b) => a[1] - b[1] || (a[0] < b[0] ? -1 : 1));
    for (const [name, line] of fnEntries) out.push(`FN:${line},${name}`);
    const fndaEntries = [...f.fnda.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
    for (const [name, hits] of fndaEntries) out.push(`FNDA:${hits},${name}`);
    out.push(`FNF:${f.fnLine.size}`);
    out.push(`FNH:${[...f.fnda.values()].filter((h) => h > 0).length}`);
    const daLines = [...f.da.keys()].sort((a, b) => a - b);
    for (const line of daLines) out.push(`DA:${line},${f.da.get(line)!}`);
    out.push(`LF:${f.da.size}`);
    out.push(`LH:${[...f.da.values()].filter((h) => h > 0).length}`);
    out.push("end_of_record");
  }
  return out.join("\n") + (out.length > 0 ? "\n" : "");
}

// ---------------------------------------------------------------------------
// src/ inventory for neverLoaded
// ---------------------------------------------------------------------------

/**
 * All gate-relevant source files on disk: src/**\/*.ts, excluding *.test.ts,
 * *.generated.ts, *.d.ts. Repo-relative POSIX, sorted.
 */
export function listSrcTsFiles(repoRootAbs: string): string[] {
  const srcAbs = join(repoRootAbs, "src");
  if (!existsSync(srcAbs)) return [];
  const out: string[] = [];
  const walk = (dirAbs: string, relFromSrc: string): void => {
    for (const ent of readdirSync(dirAbs, { withFileTypes: true })) {
      const rel = relFromSrc ? `${relFromSrc}/${ent.name}` : ent.name;
      if (ent.isDirectory()) {
        if (ent.name === "node_modules") continue;
        walk(join(dirAbs, ent.name), rel);
      } else if (
        ent.name.endsWith(".ts") &&
        !ent.name.endsWith(".test.ts") &&
        !ent.name.endsWith(".generated.ts") &&
        !ent.name.endsWith(".d.ts")
      ) {
        out.push(`src/${rel}`);
      }
    }
  };
  walk(srcAbs, "");
  return out.sort();
}

// ---------------------------------------------------------------------------
// Summary
// ---------------------------------------------------------------------------

export interface CovTriple {
  lines: number;
  covered: number;
  pct: number;
}

export function pctOf(covered: number, lines: number): number {
  if (lines === 0) return 0;
  return Math.round((covered / lines) * 10000) / 100;
}

/** Top-level src dir bucket: src/core/x/y.ts -> 'src/core'; src/cli.ts -> 'src'. */
export function topLevelSrcDir(file: string): string {
  const parts = file.split("/");
  return parts.length >= 3 ? `${parts[0]}/${parts[1]}` : parts[0]!;
}

// ---------------------------------------------------------------------------
// Lane manifests
// ---------------------------------------------------------------------------

export interface LaneManifest {
  lane: string;
  sha?: string;
  lcovCount?: number;
  complete?: boolean;
}

// ---------------------------------------------------------------------------
// main
// ---------------------------------------------------------------------------

function warn(msg: string): void {
  process.stderr.write(`merge-lcov: warning: ${msg}\n`);
}

function usage(msg: string): never {
  process.stderr.write(`merge-lcov: ${msg}\n`);
  process.stderr.write(
    "usage: bun scripts/merge-lcov.ts --out-lcov <path> --out-json <path> [--manifest-expect <lane,lane,...>] [--sha <expected-commit>] <dir-or-file>...\n",
  );
  process.exit(2);
}

/**
 * Self-merge guard: the CI report job downloads coverage artifacts via the
 * `coverage-*` glob, and on a re-run the PRIOR report job's own
 * `coverage-merged` artifact matches that glob too. Re-merging our own merged
 * output into itself would double every hit count, so any lcov.info whose
 * path contains a `coverage-merged` segment is skipped.
 */
export function isMergedArtifactPath(p: string): boolean {
  return p.split(/[\\/]/).includes("coverage-merged");
}

function walkForInputs(dirAbs: string, lcovFiles: string[], manifestFiles: string[]): void {
  for (const ent of readdirSync(dirAbs, { withFileTypes: true })) {
    const p = join(dirAbs, ent.name);
    if (ent.isDirectory()) {
      if (ent.name === "node_modules") continue;
      walkForInputs(p, lcovFiles, manifestFiles);
    } else if (ent.name === "lcov.info") {
      if (isMergedArtifactPath(p)) {
        // Expected on report-job re-runs — skipped, NOT degraded.
        warn(`skipping ${p}: under a coverage-merged path segment (self-merge guard)`);
        continue;
      }
      lcovFiles.push(p);
    } else if (ent.name === "lane-manifest.json") {
      manifestFiles.push(p);
    }
  }
}

function main(): void {
  const argv = process.argv.slice(2);
  let outLcov = "";
  let outJson = "";
  let manifestExpect: string[] = [];
  let expectedSha = "";
  const inputs: string[] = [];
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i]!;
    if (a === "--out-lcov") outLcov = argv[++i] ?? "";
    else if (a === "--out-json") outJson = argv[++i] ?? "";
    else if (a === "--sha") {
      expectedSha = argv[++i] ?? "";
      if (!expectedSha || expectedSha.startsWith("--")) usage("--sha requires a commit");
    }
    else if (a === "--manifest-expect") {
      manifestExpect = (argv[++i] ?? "")
        .split(",")
        .map((s) => s.trim())
        .filter(Boolean);
    } else if (a.startsWith("--")) usage(`unknown flag: ${a}`);
    else inputs.push(a);
  }
  if (!outLcov || !outJson) usage("--out-lcov and --out-json are required");
  if (inputs.length === 0) usage("at least one <dir-or-file> input is required");

  let degraded = false;
  const lcovFiles: string[] = [];
  const manifestFiles: string[] = [];
  for (const input of inputs) {
    if (!existsSync(input)) {
      warn(`input path not found: ${input} — marking degraded`);
      degraded = true;
      continue;
    }
    const st = statSync(input);
    if (st.isFile()) {
      if (isMergedArtifactPath(input)) {
        warn(`skipping ${input}: under a coverage-merged path segment (self-merge guard)`);
        continue;
      }
      lcovFiles.push(input);
    } else {
      walkForInputs(input, lcovFiles, manifestFiles);
    }
  }

  // --- lane manifests ---
  if (!expectedSha && manifestFiles.length > 0) {
    const git = spawnSync("git", ["rev-parse", "HEAD"], { encoding: "utf8" });
    if (git.status === 0) expectedSha = git.stdout.trim();
    if (!expectedSha) {
      warn("cannot resolve expected commit — pass --sha; marking degraded");
      degraded = true;
    }
  }
  const manifests: Array<LaneManifest & { root: string; valid: boolean }> = [];
  for (const mf of manifestFiles) {
    try {
      const parsed = JSON.parse(readFileSync(mf, "utf8")) as Partial<LaneManifest>;
      if (typeof parsed.lane !== "string" || parsed.lane === "") {
        warn(`manifest ${mf} has no lane name — marking degraded`);
        degraded = true;
        continue;
      }
      manifests.push({
        lane: parsed.lane,
        sha: typeof parsed.sha === "string" ? parsed.sha : undefined,
        lcovCount: typeof parsed.lcovCount === "number" ? parsed.lcovCount : undefined,
        complete: parsed.complete === true,
        root: resolve(dirname(mf)),
        valid: true,
      });
    } catch {
      warn(`manifest ${mf} is not valid JSON — marking degraded`);
      degraded = true;
    }
  }
  for (const m of manifests) {
    const invalidate = (reason: string) => {
      warn(`lane '${m.lane}' ${reason} — marking degraded`);
      m.valid = false;
      degraded = true;
    };
    if (!expectedSha || m.sha !== expectedSha) {
      invalidate(`has sha=${m.sha ?? "missing"}, expected ${expectedSha || "unavailable"}`);
    }
    if (manifests.filter(other => other.lane === m.lane).length !== 1) {
      invalidate("has duplicate manifests");
    }
    const actualCount = new Set(lcovFiles.filter(file => resolve(file).startsWith(m.root + sep)).map(file => resolve(file))).size;
    if (!Number.isInteger(m.lcovCount) || m.lcovCount! < 0 || m.lcovCount !== actualCount) {
      invalidate(`has lcovCount=${m.lcovCount ?? "missing"}, actual=${actualCount}`);
    }
    // xargs-batching tripwire: a shard lane must have written EXACTLY ONE
    // lcov.info (one bun process). Anything else means data was overwritten
    // or never written.
    if (m.lane.includes("shard") && m.lcovCount !== 1) {
      warn(`shard lane '${m.lane}' has lcovCount=${m.lcovCount ?? "missing"} (expected 1) — marking degraded`);
      m.valid = false;
      degraded = true;
    }
  }
  for (const expected of manifestExpect) {
    const m = manifests.find((x) => x.lane === expected);
    if (!m) {
      warn(`expected lane '${expected}' has no lane-manifest.json — marking degraded`);
      degraded = true;
    } else if (m.complete !== true) {
      warn(`expected lane '${expected}' manifest is not complete — marking degraded`);
      degraded = true;
    }
  }

  // --- parse + merge ---
  const repoRoot = process.cwd();
  const merged: Merged = new Map();
  let parsedFiles = 0;
  for (const lf of lcovFiles) {
    let text: string;
    try {
      text = readFileSync(lf, "utf8");
    } catch (err) {
      warn(`cannot read ${lf}: ${String(err)} — skipped, marking degraded`);
      degraded = true;
      continue;
    }
    const res = parseLcovText(text);
    for (const w of res.warnings) warn(`${lf}: ${w}`);
    if (res.malformed) {
      warn(`${lf}: malformed/truncated — file skipped whole, marking degraded`);
      degraded = true;
      continue;
    }
    parsedFiles++;
    for (const rec of res.records) {
      const sf = normalizeSf(rec.sf, repoRoot);
      if (sf === "") continue;
      mergeRecord(merged, sf, rec);
    }
  }
  if (parsedFiles === 0) warn("no lcov.info data merged (zero parseable inputs)");

  // --- JSON metrics: src/ files only ---
  const srcFiles = [...merged.keys()].filter((f) => f.startsWith("src/")).sort();
  const files: Record<string, CovTriple> = {};
  const dirAgg = new Map<string, { lines: number; covered: number }>();
  const lineHits: Record<string, Record<string, number>> = {};
  let totalLines = 0;
  let totalCovered = 0;
  for (const f of srcFiles) {
    const m = merged.get(f)!;
    const lines = m.da.size;
    const covered = [...m.da.values()].filter((h) => h > 0).length;
    files[f] = { lines, covered, pct: pctOf(covered, lines) };
    totalLines += lines;
    totalCovered += covered;
    const dir = topLevelSrcDir(f);
    const agg = dirAgg.get(dir) ?? { lines: 0, covered: 0 };
    agg.lines += lines;
    agg.covered += covered;
    dirAgg.set(dir, agg);
    const hits: Record<string, number> = {};
    for (const line of [...m.da.keys()].sort((a, b) => a - b)) hits[String(line)] = m.da.get(line)!;
    lineHits[f] = hits;
  }
  const dirs: Record<string, CovTriple> = {};
  for (const dir of [...dirAgg.keys()].sort()) {
    const agg = dirAgg.get(dir)!;
    dirs[dir] = { lines: agg.lines, covered: agg.covered, pct: pctOf(agg.covered, agg.lines) };
  }

  const loaded = new Set(srcFiles);
  const neverLoadedFiles = listSrcTsFiles(repoRoot).filter((f) => !loaded.has(f));

  const summary = {
    generatedAt: process.env.GENERATED_AT || new Date().toISOString(),
    corpus: process.env.COVERAGE_CORPUS || "unknown",
    lanes: {
      expected: manifestExpect,
      complete: manifests
        .filter((m) => m.complete === true && m.valid)
        .map((m) => m.lane)
        .sort(),
    },
    degraded,
    total: { lines: totalLines, covered: totalCovered, pct: pctOf(totalCovered, totalLines) },
    dirs,
    files,
    functionCoverage: "informational" as const,
    neverLoaded: { count: neverLoadedFiles.length, files: neverLoadedFiles },
    lineHits,
  };

  try {
    mkdirSync(dirname(outLcov), { recursive: true });
    mkdirSync(dirname(outJson), { recursive: true });
    writeFileSync(outLcov, emitLcov(merged), "utf8");
    writeFileSync(outJson, JSON.stringify(summary, null, 2) + "\n", "utf8");
  } catch (err) {
    process.stderr.write(`merge-lcov: cannot write outputs: ${String(err)}\n`);
    process.exit(2);
  }

  process.stderr.write(
    `merge-lcov: merged ${lcovFiles.length} lcov file(s) (${parsedFiles} parseable) → ` +
      `${srcFiles.length} src file(s), total ${summary.total.pct}% ` +
      `(${totalCovered}/${totalLines} lines), degraded=${degraded}\n`,
  );
}

if (import.meta.main) main();