voyage/lib/util/test-census.mjs

// lib/util/test-census.mjs
// Census of the test suite: split top-level test() declarations into
// "behavior" tests vs "doc-consistency pins" (string/existence assertions that
// pin documentation against a source-of-truth). Makes the cited test count
// honest — a prose-pin is not the same coverage as a behavior test, so a single
// conflated total oversells behavior coverage.
// Devil's-advocate audit §Top changes #8 (S19).
//
// Metric: top-level `test(` declarations (static, deterministic, in-process).
// This is distinct from node:test's runtime total, which additionally counts
// subtests; the runtime total is therefore ≥ this declaration count.

import { readFileSync, readdirSync } from 'node:fs';
import { join } from 'node:path';

// Files whose tests are documentation pins, not behavior coverage. Kept as a
// regex (not a single filename) so a future split-out (e.g. prose-pins.test.mjs)
// is bucketed correctly without editing this module.
export const PIN_FILE_RE = /(doc-consistency|prose-pins)\.test\.mjs$/;

function walk(dir) {
  const out = [];
  for (const e of readdirSync(dir, { withFileTypes: true })) {
    const p = join(dir, e.name);
    if (e.isDirectory()) out.push(...walk(p));
    else if (e.isFile() && e.name.endsWith('.test.mjs')) out.push(p);
  }
  return out;
}

function countTests(file) {
  return (readFileSync(file, 'utf-8').match(/^\s*test\(/gm) || []).length;
}

// Returns { behavior, docPins, total, byFile } for all *.test.mjs under
// testsRoot. behavior + docPins === total by construction.
export function censusTests(testsRoot) {
  const files = walk(testsRoot).sort();
  const byFile = {};
  let behavior = 0;
  let docPins = 0;
  for (const f of files) {
    const n = countTests(f);
    byFile[f] = n;
    if (PIN_FILE_RE.test(f)) docPins += n;
    else behavior += n;
  }
  return { behavior, docPins, total: behavior + docPins, byFile };
}