@ultimat3/cli 22.15.0 → 24.0.0

package/src/coverage-floor.ts

@@ -0,0 +1,334 @@
+// The coverage floor an app states in `x.verify.json`, what the unit suite measured against the
+// app's WHOLE source tree, and the findings where the two disagree. A finding of the `unit` step,
+// never a step of its own: the step list is as stable as an error code.
+
+// why: Bun ships no synchronous existence check and no path-join primitive; the fix a
+// below-floor finding carries depends on whether the test beside the worst file exists.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { CoverageMap } from './coverage-lcov';
+import { percent } from './coverage-lcov';
+import { appSourceFiles, hasExecutableCode, readSource, unloadedWeight } from './coverage-source';
+import { msg } from './messages';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+
+/** The `x.verify.json` key. */
+export const COVERAGE_FIELD = 'coverage';
+
+/**
+ * Lines and functions, the framework's own code and every app's — one bar. **A floor, not the
+ * goal**: coverage measures execution, not validation, and a test added to raise it is proven by
+ * mutation (break the source, watch it go red, restore). A covered branch whose test cannot fail
+ * is worse than an uncovered one.
+ */
+export const COVERAGE_BAR = 95;
+
+/** How far above a floor under the bar the tree may measure before the floor has to rise. */
+export const FLOOR_SLACK = 1.5;
+
+/** How many files a below-floor finding names. */
+export const LOSS_LIMIT = 10;
+
+const FLOOR_FILE = 'x.verify.json';
+
+export interface CoverageExclude {
+  /** Relative to the app root. */
+  readonly glob: string;
+  /** Why a unit test cannot execute it — a browser-only mount, a container entry point. */
+  readonly why: string;
+}
+
+export interface CoverageFloor {
+  readonly lines: number;
+  readonly funcs: number;
+  /** Required while either number is under `COVERAGE_BAR`: what is uncovered, who closes it. */
+  readonly why?: string;
+  readonly exclude: readonly CoverageExclude[];
+}
+
+const isPercent = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 100;
+
+const isText = (value: unknown): value is string =>
+  typeof value === 'string' && value.trim().length > 0;
+
+/**
+ * `coverage` out of `x.verify.json`, or the reasons it is not a floor. A number that is not a
+ * percentage is refused rather than read as zero — `measured < NaN` is false for every reading,
+ * so a typo would stop the floor enforcing and report green. An `exclude` entry with no `why` is
+ * refused too, and DROPPED: it excludes nothing until it says what it is for.
+ */
+export function readCoverageFloor(payload: Record<string, unknown> | undefined): {
+  coverage?: CoverageFloor;
+  problems: readonly string[];
+} {
+  const raw = payload?.[COVERAGE_FIELD];
+  if (raw === undefined) return { problems: [] };
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return { problems: [`"${COVERAGE_FIELD}" is not an object of { "lines", "funcs" }`] };
+  }
+  const record = raw as Record<string, unknown>;
+  const problems: string[] = [];
+  for (const key of ['lines', 'funcs'] as const) {
+    if (!isPercent(record[key])) {
+      problems.push(
+        `"${COVERAGE_FIELD}.${key}" is ${JSON.stringify(record[key])}, which is not a percentage from 0 to 100`,
+      );
+    }
+  }
+  if (record['why'] !== undefined && !isText(record['why'])) {
+    problems.push(`"${COVERAGE_FIELD}.why" is not a sentence`);
+  }
+  const exclude: CoverageExclude[] = [];
+  const list = record['exclude'];
+  if (list !== undefined && !Array.isArray(list)) {
+    problems.push(`"${COVERAGE_FIELD}.exclude" is not a list of { "glob", "why" }`);
+  }
+  for (const entry of Array.isArray(list) ? (list as unknown[]) : []) {
+    const one =
+      typeof entry === 'object' && entry !== null ? (entry as Record<string, unknown>) : {};
+    if (!isText(one['glob'])) {
+      problems.push(`"${COVERAGE_FIELD}.exclude" holds an entry with no "glob"`);
+    } else if (!isText(one['why'])) {
+      problems.push(
+        `"${COVERAGE_FIELD}.exclude" excludes ${one['glob']} with no "why" — say why a unit test cannot execute it`,
+      );
+    } else exclude.push({ glob: one['glob'], why: one['why'] });
+  }
+  if (!isPercent(record['lines']) || !isPercent(record['funcs'])) return { problems };
+  return {
+    coverage: {
+      lines: record['lines'],
+      funcs: record['funcs'],
+      ...(isText(record['why']) ? { why: record['why'] } : {}),
+      exclude,
+    },
+    problems,
+  };
+}
+
+/** One source file's share of the gap. */
+export interface FileLoss {
+  readonly file: string;
+  /** Lines that could have run and did not. */
+  readonly uncovered: number;
+  readonly lines: number;
+  /** No unit test loaded it at all: it counts at 0%, weighed off its source. */
+  readonly unloaded: boolean;
+}
+
+export interface CoverageMeasure {
+  readonly lines: number;
+  readonly funcs: number;
+  readonly linesHit: number;
+  readonly linesFound: number;
+  readonly funcsHit: number;
+  readonly funcsFound: number;
+  /** Source files counted, loaded or not. */
+  readonly files: number;
+  /** Worst first: most uncovered lines, then by path. */
+  readonly losses: readonly FileLoss[];
+}
+
+/**
+ * The suite's coverage of the app's WHOLE source tree. `coverage` is keyed by path relative to
+ * `root`; a record for anything else — a framework package, `node_modules`, a test — is not the
+ * app's source and is dropped. A source file with executable code and no record counts at 0%.
+ */
+export async function measureCoverage(
+  root: string,
+  coverage: CoverageMap,
+  floor: CoverageFloor | undefined,
+): Promise<CoverageMeasure> {
+  const sources = appSourceFiles(root, floor?.exclude.map((entry) => entry.glob) ?? []);
+  let linesHit = 0;
+  let linesFound = 0;
+  let funcsHit = 0;
+  let funcsFound = 0;
+  let files = 0;
+  const losses: FileLoss[] = [];
+  for (const file of sources) {
+    const loaded = Object.hasOwn(coverage, file) ? coverage[file] : undefined;
+    if (loaded !== undefined) {
+      const found = loaded.hit.length + loaded.miss.length;
+      linesHit += loaded.hit.length;
+      linesFound += found;
+      funcsHit += Math.min(loaded.funcsHit, loaded.funcsFound);
+      funcsFound += loaded.funcsFound;
+      files += 1;
+      if (loaded.miss.length > 0) {
+        losses.push({ file, uncovered: loaded.miss.length, lines: found, unloaded: false });
+      }
+      continue;
+    }
+    const source = await readSource(root, file);
+    // A barrel or a types-only module emits nothing, so Bun writes no record for it when it IS
+    // loaded: absent is correct, and it weighs nothing.
+    if (source === undefined || !hasExecutableCode(source)) continue;
+    const weight = unloadedWeight(source);
+    linesFound += weight.lines;
+    funcsFound += weight.funcs;
+    files += 1;
+    losses.push({ file, uncovered: weight.lines, lines: weight.lines, unloaded: true });
+  }
+  losses.sort((a, b) => b.uncovered - a.uncovered || (a.file < b.file ? -1 : 1));
+  return {
+    lines: percent(linesHit, linesFound),
+    funcs: percent(funcsHit, funcsFound),
+    linesHit,
+    linesFound,
+    funcsHit,
+    funcsFound,
+    files,
+    losses,
+  };
+}
+
+/** One decimal, rounded DOWN: a printed number never claims more than was measured. */
+const shown = (value: number): string => (Math.floor(value * 10) / 10).toFixed(1);
+
+/**
+ * The floor a measured number supports: the bar once it clears it, the whole number under it
+ * below — up to a point of room, so one uncovered line in an unrelated file is not a red gate,
+ * and less than `FLOOR_SLACK`, so the floor it writes is never stale the moment it is written.
+ */
+const floorFor = (measured: number): number =>
+  measured >= COVERAGE_BAR ? COVERAGE_BAR : Math.floor(measured);
+
+const WHY_PLACEHOLDER = '<what is uncovered and who closes it>';
+
+/** The `"coverage": { … }` text for a measured tree — what an author pastes. */
+export function floorLine(measure: Pick<CoverageMeasure, 'lines' | 'funcs'>): string {
+  const lines = floorFor(measure.lines);
+  const funcs = floorFor(measure.funcs);
+  const why = lines < COVERAGE_BAR || funcs < COVERAGE_BAR ? `, "why": "${WHY_PLACEHOLDER}"` : '';
+  return `"${COVERAGE_FIELD}": { "lines": ${String(lines)}, "funcs": ${String(funcs)}${why} }`;
+}
+
+/**
+ * `foo.ts` → `foo.test.ts`, and `page.tsx` → `page.test.ts`: where the test that covers a file
+ * lives. Always `.ts` — every generator writes it so, and a test holds no JSX: the registry leak
+ * guard's loader covers `.test.ts` only, so a `.test.tsx` this named would also be unguarded.
+ */
+export const testPathOf = (file: string): string => file.replace(/\.tsx?$/, '.test.ts');
+
+export interface JudgeOptions {
+  /** Whether `path` (relative to the app root) exists — decides which fix a below-floor gets. */
+  readonly exists: (path: string) => boolean;
+}
+
+/**
+ * The findings a measurement earns against the stated floor — none is the only pass.
+ *
+ * | State | Finding |
+ * |---|---|
+ * | no floor stated | `X_COVERAGE_FLOOR_UNSTATED`, carrying the line to add |
+ * | a floor under the bar with no `why` | `X_COVERAGE_FLOOR_UNSTATED` |
+ * | measured under the floor | `X_COVERAGE_BELOW_FLOOR`, naming the files that lose the most |
+ * | a floor under the bar, and the tree `FLOOR_SLACK` points over it | `X_COVERAGE_FLOOR_STALE` |
+ *
+ * The last row is what makes the floor only rise, and it needs no history to do it: a floor may
+ * sit under the bar only while it is what the tree measures.
+ */
+export function coverageFindings(
+  measure: CoverageMeasure,
+  floor: CoverageFloor | undefined,
+  options: JudgeOptions,
+): readonly Finding[] {
+  const measured = `${shown(measure.lines)}% of lines and ${shown(measure.funcs)}% of functions`;
+  if (floor === undefined) {
+    return [
+      {
+        code: 'X_COVERAGE_FLOOR_UNSTATED',
+        cause: `${FLOOR_FILE} states no coverage floor; the unit suite covers ${measured} of this app's own source (${String(measure.files)} files, one no test loads counted at 0%)`,
+        fix: `edit ${FLOOR_FILE} — add ${floorLine(measure)}`,
+        docs: ERROR_DOCS_URL,
+        at: FLOOR_FILE,
+      },
+    ];
+  }
+  const findings: Finding[] = [];
+  const stated = `${shown(floor.lines)}% / ${shown(floor.funcs)}%`;
+  const underBar = floor.lines < COVERAGE_BAR || floor.funcs < COVERAGE_BAR;
+  if (underBar && floor.why === undefined) {
+    findings.push({
+      code: 'X_COVERAGE_FLOOR_UNSTATED',
+      cause: `${FLOOR_FILE} states a coverage floor of ${stated}, under the ${String(COVERAGE_BAR)}% bar, and no reason for it`,
+      fix: `edit ${FLOOR_FILE} — add "why": "${WHY_PLACEHOLDER}" inside "${COVERAGE_FIELD}", or raise both numbers to ${String(COVERAGE_BAR)}`,
+      docs: ERROR_DOCS_URL,
+      at: FLOOR_FILE,
+    });
+  }
+  if (measure.lines < floor.lines || measure.funcs < floor.funcs) {
+    const worst = measure.losses.slice(0, LOSS_LIMIT);
+    const named = worst
+      .map((loss) =>
+        loss.unloaded
+          ? `${loss.file} (no unit test loads it: ${String(loss.lines)} lines)`
+          : `${loss.file} (${String(loss.uncovered)} of ${String(loss.lines)} lines)`,
+      )
+      .join(', ');
+    const first = worst[0];
+    const test = first === undefined ? undefined : testPathOf(first.file);
+    findings.push({
+      code: 'X_COVERAGE_BELOW_FLOOR',
+      cause: `the unit suite covers ${measured} of this app's own source, under the floor of ${stated} in ${FLOOR_FILE}${named === '' ? '' : ` — losing the most lines: ${named}`}`,
+      fix:
+        test === undefined
+          ? 'x verify --only unit --json'
+          : options.exists(test)
+            ? // Quoted: a route directory is `[id]`, which a shell reads as a glob.
+              `bun test --coverage ${quoteArg(test)}`
+            : `edit ${test} — no test sits beside ${first?.file ?? test}; write one that fails when the source is broken, then: bun test --coverage ${quoteArg(test)}`,
+      docs: ERROR_DOCS_URL,
+      ...(first === undefined ? {} : { at: first.file }),
+    });
+  }
+  const risen = (['lines', 'funcs'] as const).filter(
+    (key) => floor[key] < COVERAGE_BAR && measure[key] >= floor[key] + FLOOR_SLACK,
+  );
+  if (risen.length > 0) {
+    const lines = Math.max(floor.lines, floorFor(measure.lines));
+    const funcs = Math.max(floor.funcs, floorFor(measure.funcs));
+    const cleared = lines >= COVERAGE_BAR && funcs >= COVERAGE_BAR;
+    findings.push({
+      code: 'X_COVERAGE_FLOOR_STALE',
+      cause: `the unit suite now covers ${measured}, more than ${String(FLOOR_SLACK)} points over the floor of ${stated} in ${FLOOR_FILE} — the floor only rises`,
+      fix: `edit ${FLOOR_FILE} — set "lines": ${String(lines)} and "funcs": ${String(funcs)} inside "${COVERAGE_FIELD}"${cleared ? ', and delete its "why"' : ''}`,
+      docs: ERROR_DOCS_URL,
+      at: FLOOR_FILE,
+    });
+  }
+  return findings;
+}
+
+export interface CoverageVerdict {
+  readonly measure: CoverageMeasure;
+  readonly findings: readonly Finding[];
+  /** One line for the step's `output`: the numbers, and the floor they were held to. */
+  readonly output: string;
+}
+
+/** Measure `coverage` against the app at `root` and judge it against `floor` — the whole check. */
+export async function judgeCoverage(
+  root: string,
+  coverage: CoverageMap,
+  floor: CoverageFloor | undefined,
+): Promise<CoverageVerdict> {
+  const measure = await measureCoverage(root, coverage, floor);
+  return {
+    measure,
+    findings: coverageFindings(measure, floor, {
+      exists: (path) => existsSync(join(root, path)),
+    }),
+    output: msg('cli.verify.coverage', {
+      lines: shown(measure.lines),
+      funcs: shown(measure.funcs),
+      files: measure.files,
+      floor: floor === undefined ? 'unstated' : `${shown(floor.lines)}% / ${shown(floor.funcs)}%`,
+    }),
+  };
+}

package/src/coverage-lcov.ts

@@ -0,0 +1,193 @@
+// The one lcov reader: what `bun test --coverage --coverage-reporter=lcov` wrote, as per-file
+// facts, and how the facts of several test processes add up. `scripts/coverage-gate.ts` (the
+// framework's packages) and `coverage-floor.ts` (an app) both read through it.
+
+/** One `SF:` record, as written: its own totals and every `DA:` line. */
+export interface LcovRecord {
+  /** The `SF:` path, verbatim — Bun writes it relative to the directory the run started in. */
+  readonly file: string;
+  /** `LF` / `LH` / `FNF` / `FNH`. Bun's lcov carries no `FN:` lines, so functions are counts only. */
+  readonly linesFound: number;
+  readonly linesHit: number;
+  readonly funcsFound: number;
+  readonly funcsHit: number;
+  /** line → hits. */
+  readonly lines: ReadonlyMap<number, number>;
+}
+
+export function parseLcov(text: string): readonly LcovRecord[] {
+  const records: LcovRecord[] = [];
+  let file: string | undefined;
+  let lf = 0;
+  let lh = 0;
+  let fnf = 0;
+  let fnh = 0;
+  let lines = new Map<number, number>();
+  for (const line of text.split('\n')) {
+    if (line.startsWith('SF:')) {
+      file = line.slice(3);
+      lf = 0;
+      lh = 0;
+      fnf = 0;
+      fnh = 0;
+      lines = new Map();
+    } else if (file === undefined) {
+      // Before the first record (`TN:`), or between two.
+    } else if (line.startsWith('DA:')) {
+      const comma = line.indexOf(',');
+      const at = Number(line.slice(3, comma));
+      const hits = Number(line.slice(comma + 1));
+      if (comma > 3 && Number.isSafeInteger(at) && Number.isFinite(hits)) lines.set(at, hits);
+    } else if (line.startsWith('LF:')) lf = Number(line.slice(3));
+    else if (line.startsWith('LH:')) lh = Number(line.slice(3));
+    else if (line.startsWith('FNF:')) fnf = Number(line.slice(4));
+    else if (line.startsWith('FNH:')) fnh = Number(line.slice(4));
+    else if (line === 'end_of_record') {
+      records.push({
+        file,
+        linesFound: lf,
+        linesHit: lh,
+        funcsFound: fnf,
+        funcsHit: fnh,
+        lines,
+      });
+      file = undefined;
+    }
+  }
+  return records;
+}
+
+/** One source file's coverage: which lines ran, which could have and did not, and its functions. */
+export interface FileCoverage {
+  readonly hit: readonly number[];
+  readonly miss: readonly number[];
+  readonly funcsFound: number;
+  readonly funcsHit: number;
+}
+
+export const fileCoverageOf = (record: LcovRecord): FileCoverage => {
+  const hit: number[] = [];
+  const miss: number[] = [];
+  for (const [line, hits] of record.lines) (hits > 0 ? hit : miss).push(line);
+  return { hit, miss, funcsFound: record.funcsFound, funcsHit: record.funcsHit };
+};
+
+/**
+ * One file's coverage across several test PROCESSES.
+ *
+ * A line is covered when any process ran it. It is uncovered only when EVERY process that loaded
+ * the file lists it as unrun — because Bun lists a function nothing called in that process by its
+ * whole line range, comments and blank lines included, and lists a function that ran by its
+ * executable lines alone. A union therefore counts the comments of every function one process
+ * called and another merely loaded, and the number moves with how the files were dealt:
+ * `examples/dummy` read 59.9% at four workers, 65.0% at two and 65.5% in one process, same tree
+ * (measured 2026-10-01, Bun 1.4.0, whose own `--parallel` merge is that union). This rule read
+ * 65.90% for 2, 4 and 8 processes and for contiguous chunks — and is exactly what Bun reports for
+ * one `--isolate` process.
+ *
+ * Functions have no identity in Bun's lcov, only two counts, so they cannot be unioned: the file
+ * takes the best any one process reached. That is a lower bound, and the reason the processes are
+ * cut along directories (`verify-coverage-run.ts`) — the tests beside a file run together.
+ */
+export function mergeFileCoverage(parts: readonly FileCoverage[]): FileCoverage {
+  if (parts.length === 1) return parts[0] as FileCoverage;
+  const hit = new Set<number>();
+  for (const part of parts) for (const line of part.hit) hit.add(line);
+  const missIn = parts.map((part) => new Set(part.miss));
+  const miss = [...(missIn[0] ?? [])].filter(
+    (line) => !hit.has(line) && missIn.every((set) => set.has(line)),
+  );
+  return {
+    hit: [...hit].sort((a, b) => a - b),
+    miss: miss.sort((a, b) => a - b),
+    funcsFound: Math.max(0, ...parts.map((part) => part.funcsFound)),
+    funcsHit: Math.max(0, ...parts.map((part) => part.funcsHit)),
+  };
+}
+
+/** file → coverage. A plain record so it survives `--json` between a shard and `x verify merge`. */
+export type CoverageMap = Readonly<Record<string, FileCoverage>>;
+
+/** Several processes' (or several shards') maps as one, file by file. */
+export function mergeCoverage(maps: readonly CoverageMap[]): CoverageMap {
+  const byFile = new Map<string, FileCoverage[]>();
+  for (const map of maps) {
+    for (const [file, coverage] of Object.entries(map)) {
+      const list = byFile.get(file) ?? [];
+      list.push(coverage);
+      byFile.set(file, list);
+    }
+  }
+  return Object.fromEntries(
+    [...byFile]
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([file, parts]) => [file, mergeFileCoverage(parts)]),
+  );
+}
+
+/** `hit / found` as a percentage to two decimals; nothing found is 0, never a pass over nothing. */
+export const percent = (hit: number, found: number): number =>
+  found === 0 ? 0 : Math.round((hit / found) * 10_000) / 100;
+
+/** `[1,2,3,7]` → `"1-3,7"`: a shard's facts ride in its `--json` document, so they are kept small. */
+export function encodeLines(lines: readonly number[]): string {
+  const sorted = [...lines].sort((a, b) => a - b);
+  const runs: string[] = [];
+  let start: number | undefined;
+  let last = 0;
+  const flush = (): void => {
+    if (start !== undefined) runs.push(start === last ? String(start) : `${start}-${last}`);
+  };
+  for (const line of sorted) {
+    if (start !== undefined && line === last + 1) {
+      last = line;
+      continue;
+    }
+    flush();
+    start = line;
+    last = line;
+  }
+  flush();
+  return runs.join(',');
+}
+
+/** The inverse of `encodeLines`; a run that does not parse is no lines, never a throw. */
+export function decodeLines(text: string): readonly number[] {
+  const lines: number[] = [];
+  for (const run of text.split(',')) {
+    const match = /^(\d+)(?:-(\d+))?$/.exec(run);
+    if (match === null) continue;
+    const from = Number(match[1]);
+    const to = match[2] === undefined ? from : Number(match[2]);
+    for (let line = from; line <= to && line - from < 1_000_000; line += 1) lines.push(line);
+  }
+  return lines;
+}
+
+/** A file's facts as they cross `--json`: hit runs, miss runs, `[funcsFound, funcsHit]`. */
+export type CoverageWire = Readonly<
+  Record<string, { readonly h: string; readonly m: string; readonly f: readonly [number, number] }>
+>;
+
+export const encodeCoverage = (map: CoverageMap): CoverageWire =>
+  Object.fromEntries(
+    Object.entries(map).map(([file, one]) => [
+      file,
+      { h: encodeLines(one.hit), m: encodeLines(one.miss), f: [one.funcsFound, one.funcsHit] },
+    ]),
+  );
+
+/** A part's `data.coverage.<step>` back into a map, or nothing when it is not one. */
+export function decodeCoverage(value: unknown): CoverageMap | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+  const out = new Map<string, FileCoverage>();
+  for (const [file, raw] of Object.entries(value)) {
+    if (typeof raw !== 'object' || raw === null) return undefined;
+    const { h, m, f } = raw as { h?: unknown; m?: unknown; f?: unknown };
+    if (typeof h !== 'string' || typeof m !== 'string' || !Array.isArray(f)) return undefined;
+    const [found, hit] = f as unknown[];
+    if (typeof found !== 'number' || typeof hit !== 'number') return undefined;
+    out.set(file, { hit: decodeLines(h), miss: decodeLines(m), funcsFound: found, funcsHit: hit });
+  }
+  return Object.fromEntries(out);
+}

package/src/coverage-source.ts

@@ -0,0 +1,136 @@
+// What counts as an app's OWN source for the coverage floor, and what a file no test loaded
+// weighs. Bun writes an lcov record only for a file something imported, so a module nothing
+// reaches is absent from both halves of the fraction — and makes the number BETTER.
+
+// why: Bun ships no path-joining primitive; `join` builds the host path to each source file.
+import { join } from 'node:path';
+import { maskLiterals, stripComments } from '@ultimat3/core';
+
+/** A test file, whatever its suite: `*.test.ts`, `*.contract.test.tsx`, … */
+export const TEST_FILE = /\.test\.[cm]?[jt]sx?$/;
+
+/** Index just past the balanced `{ … }` that starts at or after `from`. */
+function skipBalanced(text: string, from: number): number {
+  let depth = 0;
+  for (let i = from; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === '{') depth += 1;
+    else if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) return i + 1;
+    }
+  }
+  return text.length;
+}
+
+/**
+ * Index just past the `;` that ends a `type` alias — the first one at nesting depth zero.
+ *
+ * Depth matters and a naive scan gets it wrong: `type _A = Assert<[FactKeysOf<{ a: 1 }>] extends
+ * [Actor] ? true : false>;` contains a `{ … }` whose closing brace is NOT the end of the
+ * declaration, and matching braces there leaves `, ] extends [Actor] … >;` behind, which then
+ * reads as executable code.
+ */
+function endOfTypeAlias(text: string, from: number): number {
+  let depth = 0;
+  for (let i = from; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === '{' || ch === '[' || ch === '(' || ch === '<') depth += 1;
+    else if (ch === '}' || ch === ']' || ch === ')' || ch === '>') depth -= 1;
+    else if (ch === ';' && depth <= 0) return i + 1;
+  }
+  return text.length;
+}
+
+/**
+ * Whether a file emits anything at RUNTIME, as opposed to a barrel or a types-only module.
+ *
+ * Load-bearing, not cosmetic: bun writes an lcov record only for a file that produced executable
+ * code, so a pure barrel and a types-only module are legitimately absent — while a real module
+ * nothing imported is absent for the opposite reason and must be reported.
+ * `packages/core/src/type-pins.ts` says it of itself: "This module emits nothing and exports
+ * nothing anybody imports."
+ *
+ * A regex cannot decide this. `metrics-types.ts` contains `(() => number)` in a TYPE position, so
+ * scanning for `=>` calls a types-only file executable. Hence a scanner: strip comments and
+ * re-export statements, then remove `interface` blocks by brace matching and `type` aliases to
+ * their depth-zero `;`, and ask whether anything is left.
+ *
+ * `declare module` and `declare global` are removed the same way, and for the same reason the
+ * `declare const` line exists: an ambient block emits nothing at runtime, so bun writes no lcov
+ * record for a file built only from one. Their bodies go with them — an augmentation's members
+ * are declarations whatever they look like. Without this, `matcher-surface.ts` (a
+ * `declare module 'bun:test'` and nothing else) read as executable and was reported as a real
+ * module no test imports, which is the opposite of what it is.
+ */
+export function hasExecutableCode(source: string): boolean {
+  let text = source
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^[ \t]*\/\/.*$/gm, '')
+    .replace(/^[ \t]*(?:import|export)\b[^;]*?from\s*'[^']*';[ \t]*$/gm, '')
+    .replace(/^[ \t]*import\s+type\b[^;]*;[ \t]*$/gm, '')
+    // `declare const x: T;` is ambient — it emits nothing, and `type-pins.ts` files are built
+    // almost entirely from them.
+    .replace(/^[ \t]*declare\s+(?:const|let|var|function|class)\b[^;]*;[ \t]*$/gm, '');
+
+  // Ambient blocks first: their bodies hold `interface` members that the loop below would strip
+  // individually, leaving a bare `declare module '…' { }` shell behind that reads as code.
+  for (;;) {
+    const ambient = /(?:^|\n)[ \t]*declare\s+(?:module\s+'[^']*'|global)\s*\{/.exec(text);
+    if (ambient === null) break;
+    const start = ambient.index + (ambient[0].startsWith('\n') ? 1 : 0);
+    text = text.slice(0, start) + text.slice(skipBalanced(text, text.indexOf('{', start)));
+  }
+
+  for (;;) {
+    const found = /(?:^|\n)[ \t]*(?:export\s+)?(?:declare\s+)?(interface|type)\s/.exec(text);
+    if (found === null) break;
+    const start = found.index + (found[0].startsWith('\n') ? 1 : 0);
+    const end =
+      found[1] === 'interface'
+        ? skipBalanced(text, text.indexOf('{', start))
+        : endOfTypeAlias(text, start);
+    text = text.slice(0, start) + text.slice(end);
+  }
+  return text.replace(/\s/g, '') !== '';
+}
+
+/**
+ * What a file with NO lcov record weighs, read off its source because nothing else knows: its
+ * non-blank, non-comment lines, and one function per `function` keyword or arrow (at least one —
+ * it has executable code, or it would not be asked). An estimate, deliberately on the heavy side
+ * of what Bun reports for a loaded file (1.34x over `examples/dummy`'s loaded sources,
+ * 2026-10-01): the only way to make it exact is to load the file from a test, which is the fix.
+ */
+export function unloadedWeight(source: string): { readonly lines: number; readonly funcs: number } {
+  const stripped = stripComments(source);
+  const lines = stripped.split('\n').filter((line) => line.trim() !== '').length;
+  const funcs = (maskLiterals(stripped).match(/\bfunction\b|=>/g) ?? []).length;
+  return { lines: Math.max(1, lines), funcs: Math.max(1, funcs) };
+}
+
+/** Never an app's own source, wherever it sits. */
+const NOT_SOURCE = /(?:^|\/)(?:node_modules|dist|build|\.x)\//;
+
+/**
+ * Every `.ts` / `.tsx` under the app's `apps/` and `packages/` that is its own source: not a
+ * test, not a declaration file, not installed or built output, and not excluded by `exclude`
+ * (globs relative to the app root). Sorted, so two runs of one tree read one list.
+ */
+export function appSourceFiles(root: string, exclude: readonly string[] = []): readonly string[] {
+  const globs = exclude.map((pattern) => new Bun.Glob(pattern));
+  const files: string[] = [];
+  for (const rel of new Bun.Glob('{apps,packages}/**/*.{ts,tsx}').scanSync({ cwd: root })) {
+    const path = rel.split('\\').join('/');
+    if (NOT_SOURCE.test(path) || TEST_FILE.test(path) || path.endsWith('.d.ts')) continue;
+    if (globs.some((glob) => glob.match(path))) continue;
+    files.push(path);
+  }
+  return files.sort();
+}
+
+/** The source text of `rel` under `root`, or nothing when it cannot be read. */
+export const readSource = (root: string, rel: string): Promise<string | undefined> =>
+  Bun.file(join(root, rel))
+    .text()
+    .catch(() => undefined);