@event4u/agent-config 9.22.0 → 9.23.0

package/src/scripts/_lib/gate_ledger.ts

@@ -0,0 +1,295 @@
+/**
+ * Completeness accounting — "planned work reaches exactly one terminal outcome".
+ *
+ * WHY THIS EXISTS. `_lib/scan_scope.ts` closed one half of the false-green
+ * class: a gate whose *root* is dead now fails instead of printing a green
+ * checkmark over zero files. It cannot close the other half. A gate with a live
+ * root that enumerates 300 targets, `continue`s past 280 of them on assorted
+ * unwritten conditions, and checks 20, still exits 0 — and its output is
+ * indistinguishable from a gate that checked all 300. Absence of findings and
+ * absence of scanning look alike, which is the exact failure this repository
+ * has recorded four separate times from its own history.
+ *
+ * The ledger makes the per-target accounting explicit and mechanical:
+ *
+ * 1. The gate **plans** every target it intends to consider.
+ * 2. Every planned target must reach exactly ONE terminal outcome —
+ *    {@link GateLedger.complete}, {@link GateLedger.fail},
+ *    {@link GateLedger.skip}, or {@link GateLedger.outOfScope}.
+ * 3. {@link GateLedger.finalize} throws when any planned target reached none.
+ *
+ * A planned target with no terminal outcome is a silent `continue` — the defect
+ * this module exists to catch. Naming it costs one call at the top of the loop
+ * body and one at each exit.
+ *
+ * **Why skip reasons are a closed union rather than a free string.** Every gate
+ * in this tree already skips targets, and every one of them explains itself in
+ * prose that no reader can aggregate: "excluded dir", "too big", "binary?",
+ * "(no creds)". A closed vocabulary makes the skips countable and comparable
+ * across the estate, and — the load-bearing part — makes an unlisted reason a
+ * *typecheck* failure rather than a code review someone has to notice. Adding a
+ * genuinely new reason is a visible one-line diff to {@link SKIP_REASON_MESSAGE},
+ * which is the review surface a free string never gets.
+ *
+ * Scope note: this is deliberately not a scan-root guard. Use
+ * {@link import('./scan_scope.js').assertScanned} for the root, and this for
+ * the items under it. The two are complementary and a gate wants both.
+ */
+import process from 'node:process';
+
+/**
+ * The closed vocabulary of reasons a planned target may go unchecked.
+ *
+ * Seeded from the reasons this repository's own gates already emit in prose, so
+ * the first adopters translate rather than invent. Every code carries a
+ * one-sentence message in {@link SKIP_REASON_MESSAGE}; a code without one does
+ * not typecheck, because the record type is keyed on this union.
+ */
+export type GateSkipReason =
+    | 'excluded_directory'
+    | 'size_limit'
+    | 'binary_content'
+    | 'missing_credentials'
+    | 'rules_unavailable'
+    | 'manifest_absent'
+    | 'no_applicable_files'
+    | 'disabled_by_configuration'
+    | 'generated_artifact'
+    | 'dead_scan_root'
+    | 'declared_exemption'
+    | 'not_applicable_kind';
+
+/**
+ * One sentence per skip code, printed verbatim in the ledger's own output.
+ *
+ * The sentence is the audit surface: a reader who sees `size_limit ×41` in a
+ * gate's report should be able to decide, without opening the gate, whether 41
+ * unchecked targets is expected.
+ */
+export const SKIP_REASON_MESSAGE: Record<GateSkipReason, string> = {
+    excluded_directory: 'the target sits under a directory this gate deliberately does not walk',
+    size_limit: 'the target exceeds the size ceiling this gate reads within',
+    binary_content: 'the target is not decodable text, so the check does not apply to it',
+    missing_credentials: 'the check needs a credential that is not present in this environment',
+    rules_unavailable: 'the rule or policy corpus this check compares against could not be loaded',
+    manifest_absent: 'the manifest that declares what to check for this target does not exist',
+    no_applicable_files: 'the target resolved to zero files the check applies to',
+    disabled_by_configuration: 'a setting in this repository turns this check off for the target',
+    generated_artifact: 'the target is generated output whose source is checked instead',
+    dead_scan_root: 'the root this target was enumerated from no longer exists',
+    declared_exemption: 'the target carries an explicit, reviewable exemption from this check',
+    not_applicable_kind: 'the target is a kind of artifact this check does not apply to',
+};
+
+/** Terminal outcomes a planned target can reach. Exactly one, exactly once. */
+export type GateOutcomeKind = 'completed' | 'failed' | 'skipped' | 'out_of_scope';
+
+/** What {@link GateLedger.finalize} returns once every planned target is accounted for. */
+export interface GateLedgerTally {
+    planned: number;
+    completed: number;
+    skipped: number;
+    failed: number;
+    out_of_scope: number;
+    /** Planned targets that reached no terminal outcome. Non-zero means `finalize` threw. */
+    unaccounted: number;
+    /** Skip counts per code, for the report line and for downstream auditing. */
+    skips_by_reason: Partial<Record<GateSkipReason, number>>;
+}
+
+/** Raised when planned work did not reach a terminal outcome. */
+export class UnaccountedTargetsError extends Error {
+    readonly gate: string;
+    readonly targets: readonly string[];
+
+    constructor(gate: string, targets: readonly string[]) {
+        const shown = targets.slice(0, 20);
+        const more = targets.length - shown.length;
+        super(
+            `${gate}: ${String(targets.length)} planned target(s) reached no terminal outcome — ` +
+                'the gate enumerated them and then neither checked, failed, skipped, nor ' +
+                'excluded them, so its green result covers less than it appears to. ' +
+                `Unaccounted: ${shown.join(', ')}${more > 0 ? ` … and ${String(more)} more` : ''}`,
+        );
+        this.name = 'UnaccountedTargetsError';
+        this.gate = gate;
+        this.targets = targets;
+    }
+}
+
+/**
+ * Raised when the ledger is used incorrectly.
+ *
+ * A double terminal outcome, or an outcome for a target that was never planned,
+ * means the accounting itself is wrong — and an accounting bug that passes
+ * quietly would restore exactly the blind spot this module removes. So these
+ * throw rather than warn.
+ */
+export class LedgerUsageError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'LedgerUsageError';
+    }
+}
+
+interface Resolution {
+    kind: GateOutcomeKind;
+    reason: string;
+}
+
+/**
+ * Per-target completeness ledger for one gate run.
+ *
+ * ```ts
+ * const ledger = new GateLedger('lint_example');
+ * ledger.plan(files);
+ * for (const file of files) {
+ *     if (isGenerated(file)) { ledger.outOfScope(file, 'generated_artifact'); continue; }
+ *     if (tooBig(file)) { ledger.skip(file, 'size_limit'); continue; }
+ *     const finding = check(file);
+ *     if (finding) ledger.fail(file, finding); else ledger.complete(file);
+ * }
+ * ledger.report();          // throws if anything was left unaccounted
+ * ```
+ */
+export class GateLedger {
+    readonly gate: string;
+    /** Insertion-ordered so the unaccounted list reads in enumeration order. */
+    private readonly planned = new Map<string, Resolution | undefined>();
+
+    constructor(gate: string) {
+        this.gate = gate;
+    }
+
+    /** Declare one or more targets this run intends to consider. */
+    plan(target: string | readonly string[]): void {
+        const targets = typeof target === 'string' ? [target] : target;
+        for (const t of targets) {
+            if (this.planned.has(t)) {
+                throw new LedgerUsageError(
+                    `${this.gate}: target planned twice: ${t}. A duplicate plan makes the ` +
+                        'denominator wrong in the direction that hides work.',
+                );
+            }
+            this.planned.set(t, undefined);
+        }
+    }
+
+    /** The target was checked and satisfied the gate. */
+    complete(target: string): void {
+        this.resolve(target, { kind: 'completed', reason: '' });
+    }
+
+    /** The target was checked and violated the gate. `reason` is the finding text. */
+    fail(target: string, reason: string): void {
+        this.resolve(target, { kind: 'failed', reason });
+    }
+
+    /** The target was NOT checked; `reason` names why, from the closed vocabulary. */
+    skip(target: string, reason: GateSkipReason): void {
+        this.resolve(target, { kind: 'skipped', reason });
+    }
+
+    /** The target does not belong to this gate's corpus; `reason` names why. */
+    outOfScope(target: string, reason: GateSkipReason): void {
+        this.resolve(target, { kind: 'out_of_scope', reason });
+    }
+
+    private resolve(target: string, resolution: Resolution): void {
+        if (!this.planned.has(target)) {
+            throw new LedgerUsageError(
+                `${this.gate}: ${resolution.kind} recorded for an unplanned target: ${target}. ` +
+                    'Every target reaching an outcome must first be planned, or the ' +
+                    'denominator understates the work.',
+            );
+        }
+        const existing = this.planned.get(target);
+        if (existing !== undefined) {
+            throw new LedgerUsageError(
+                `${this.gate}: target resolved twice (${existing.kind} then ${resolution.kind}): ${target}.`,
+            );
+        }
+        this.planned.set(target, resolution);
+    }
+
+    /** Planned targets that have not yet reached a terminal outcome, in enumeration order. */
+    unaccountedTargets(): string[] {
+        const out: string[] = [];
+        for (const [target, resolution] of this.planned) {
+            if (resolution === undefined) {
+                out.push(target);
+            }
+        }
+        return out;
+    }
+
+    /**
+     * Close the ledger and return the tally.
+     *
+     * @throws {UnaccountedTargetsError} when any planned target reached no outcome.
+     */
+    finalize(): GateLedgerTally {
+        const unaccounted = this.unaccountedTargets();
+        if (unaccounted.length > 0) {
+            throw new UnaccountedTargetsError(this.gate, unaccounted);
+        }
+        const tally: GateLedgerTally = {
+            planned: this.planned.size,
+            completed: 0,
+            skipped: 0,
+            failed: 0,
+            out_of_scope: 0,
+            unaccounted: 0,
+            skips_by_reason: {},
+        };
+        for (const resolution of this.planned.values()) {
+            if (resolution === undefined) {
+                continue;
+            }
+            if (resolution.kind === 'completed') {
+                tally.completed += 1;
+            } else if (resolution.kind === 'failed') {
+                tally.failed += 1;
+            } else {
+                if (resolution.kind === 'skipped') {
+                    tally.skipped += 1;
+                } else {
+                    tally.out_of_scope += 1;
+                }
+                const code = resolution.reason as GateSkipReason;
+                tally.skips_by_reason[code] = (tally.skips_by_reason[code] ?? 0) + 1;
+            }
+        }
+        return tally;
+    }
+
+    /**
+     * Finalize and print the denominator on the success path.
+     *
+     * The line goes to stdout unconditionally, exactly as
+     * {@link import('./scan_scope.js').reportScanned} does and for the same
+     * recorded reason: CI passes `--quiet`, and a count only visible without it
+     * is not a count. It is deliberately NOT the `scanned: <N>` line
+     * `check_gate_coverage` parses — that stays the single machine-read
+     * coverage signal, and this is the human-auditable completeness breakdown
+     * beside it.
+     *
+     * @throws {UnaccountedTargetsError} via {@link finalize}.
+     */
+    report(write: (chunk: string) => unknown = process.stdout.write.bind(process.stdout)): GateLedgerTally {
+        const tally = this.finalize();
+        const checked = tally.completed + tally.failed;
+        const parts = [
+            `scanned=${String(checked)}`,
+            `planned=${String(tally.planned)}`,
+            `skipped=${String(tally.skipped + tally.out_of_scope)}`,
+        ];
+        write(`${this.gate} ledger: ${parts.join(' ')}\n`);
+        const codes = Object.keys(tally.skips_by_reason).sort() as GateSkipReason[];
+        for (const code of codes) {
+            const n = tally.skips_by_reason[code] ?? 0;
+            write(`  ${code} ×${String(n)} — ${SKIP_REASON_MESSAGE[code]}\n`);
+        }
+        return tally;
+    }
+}

package/src/scripts/_lib/gate_result.ts

@@ -0,0 +1,101 @@
+/**
+ * Estate-level result handling — telling "found violations" from "broke".
+ *
+ * A gate exits non-zero for two structurally different reasons, and the exit
+ * code alone cannot separate them:
+ *
+ * - **verdict** — it ran, inspected its corpus, and found violations. The
+ *   estate is being measured correctly; something in the tree is wrong.
+ * - **estate-invalidating** — it could not measure at all: the scan root is
+ *   dead, planned targets went unaccounted, the ratchet's base ref is
+ *   unreachable, the ledger was mis-used. Nothing was certified, and a report
+ *   built from this run is not a report.
+ *
+ * Conflating them costs in both directions. Treated as a verdict, an
+ * invalidated run sends a contributor hunting for a violation that does not
+ * exist. Treated as a crash, a real violation gets triaged as flakiness. This
+ * repository has recorded three traps of the second kind — estate invalidation
+ * misreported as a per-gate red.
+ *
+ * The classification reads the failure's own error name, which the structural
+ * errors already carry, rather than pattern-matching prose. A gate that throws
+ * something else is `crashed`: unknown, non-green, and reported as itself.
+ *
+ * **Gaming risk.** Nothing here can be gamed by a passing gate — the module
+ * only ever downgrades confidence. The real risk is the opposite: a future
+ * error class that IS estate-invalidating but is not listed below reads as a
+ * plain crash. Mitigated by keying on the shared `_lib` error names and by the
+ * fixture that pins each one; the residual is that a new structural error must
+ * be added here deliberately.
+ */
+
+/**
+ * Error names that mean the measurement is void, not that the tree is dirty.
+ *
+ * Sourced from the shared gate primitives: `scan_scope`, `gate_ledger`, and
+ * `ratchet_base_ref`.
+ */
+export const ESTATE_INVALIDATING_ERRORS: readonly string[] = [
+    'DeadScopeError',
+    'UnaccountedTargetsError',
+    'LedgerUsageError',
+    'BaseRefUnavailableError',
+    'ProbeOverflowError',
+];
+
+export type GateOutcome = 'clean' | 'violations' | 'crashed' | 'estate_invalid';
+
+export interface GateRunSignal {
+    /** Process exit code, or `null` when the gate never produced one. */
+    exitCode: number | null;
+    /** Combined stdout + stderr, used only to spot a named structural error. */
+    output: string;
+    /** True when the runner itself could not execute the gate. */
+    spawnFailed?: boolean;
+}
+
+/** True when `output` names one of the structural error classes. */
+export function namesEstateInvalidatingError(output: string): boolean {
+    return ESTATE_INVALIDATING_ERRORS.some((name) => output.includes(name));
+}
+
+/**
+ * Classify one gate run.
+ *
+ * Fail-closed on a null exit code: a gate that produced no verdict was not run,
+ * and a gate that was not run is not a passing gate.
+ */
+export function classifyGateRun(signal: GateRunSignal): GateOutcome {
+    if (signal.spawnFailed === true || signal.exitCode === null) {
+        return 'crashed';
+    }
+    if (namesEstateInvalidatingError(signal.output)) {
+        return 'estate_invalid';
+    }
+    return signal.exitCode === 0 ? 'clean' : 'violations';
+}
+
+/** True when this outcome must never contribute to a green aggregate. */
+export function blocksGreenAggregate(outcome: GateOutcome): boolean {
+    return outcome !== 'clean';
+}
+
+/**
+ * One-line explanation, so the estate report says WHICH kind of failure it is.
+ */
+export function describeOutcome(id: string, outcome: GateOutcome): string {
+    switch (outcome) {
+        case 'clean':
+            return `${id}: clean`;
+        case 'violations':
+            return `${id}: found violations — the measurement is sound, the tree is not`;
+        case 'estate_invalid':
+            return (
+                `${id}: ESTATE INVALID — it could not measure (dead scope, unaccounted targets, ` +
+                'unreachable base ref, or ledger misuse). Nothing was certified by this run, so ' +
+                'no report built on it is a report'
+            );
+        case 'crashed':
+            return `${id}: crashed with no verdict — not run, therefore not passing`;
+    }
+}

package/src/scripts/_lib/gate_self_test.ts

@@ -0,0 +1,129 @@
+/**
+ * Self-test harness — a gate proving, on demand, that its rejections fire.
+ *
+ * WHY. Every gate in this tree has fixtures in `tests/`, and those fixtures run
+ * in CI on the test job. That leaves one gap: nothing proves the gate binary a
+ * contributor actually invokes still rejects anything. A gate whose detection
+ * silently stopped matching — a regex that no longer fires, a scan root that
+ * moved, a suppression that widened — passes its unit tests against imported
+ * functions while the CLI it ships reports clean forever.
+ *
+ * `--self-test` closes that: the gate builds known-bad fixtures in a temporary
+ * directory and invokes ITSELF against them, asserting each rejection fires.
+ *
+ * **The floor is the load-bearing part.** A self-test is itself a checker, so a
+ * truncated case list must fail rather than print success — otherwise deleting
+ * cases is the cheapest way to a green self-test. {@link runSelfTest} refuses
+ * to pass below its declared minimum, and the minimum is a constant in the
+ * gate's own source where a reviewer sees it change.
+ *
+ * **Gaming risk.** The obvious degenerate pass is a case whose `expect` is
+ * `accept` and whose fixture is empty — it asserts nothing and still counts
+ * toward the floor. Mitigated by requiring at least one `reject` case and by
+ * counting reject cases separately in the floor check; the residual is that no
+ * harness can judge whether a fixture is *representative*, which stays a human
+ * read at review time.
+ */
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import process from 'node:process';
+
+/**
+ * Invoke a gate's real CLI against a fixture.
+ *
+ * Deliberately shells out rather than calling `main()` in-process: the thing
+ * under test is the binary a contributor runs, including its argv parsing and
+ * its entry guard. An in-process call would skip exactly the layers that have
+ * silently no-opped in this repository before.
+ */
+export function runGateCli(
+    repoRoot: string,
+    scriptRelPath: string,
+    args: readonly string[],
+    cwd: string,
+): number {
+    const tsx = path.join(
+        repoRoot,
+        'node_modules',
+        '.bin',
+        process.platform === 'win32' ? 'tsx.cmd' : 'tsx',
+    );
+    const res = spawnSync(tsx, [path.join(repoRoot, scriptRelPath), ...args], {
+        cwd,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+        // The child must not recurse into its own self-test.
+        env: { ...process.env, GATE_SELF_TEST_CHILD: '1' },
+    });
+    return res.status ?? 1;
+}
+
+export interface SelfTestCase {
+    /** Short description, printed per case. */
+    name: string;
+    /** `reject` — the gate must fail on this fixture. `accept` — it must pass. */
+    expect: 'reject' | 'accept';
+    /** Runs the fixture and returns the gate's exit code. */
+    run: () => number;
+}
+
+export interface SelfTestOptions {
+    gate: string;
+    cases: readonly SelfTestCase[];
+    /** Minimum total cases. Below this, the run FAILS regardless of results. */
+    minCases: number;
+    /** Minimum `reject` cases. A suite that only proves passes proves nothing. */
+    minRejectCases?: number;
+    write?: (chunk: string) => unknown;
+}
+
+/**
+ * Run a gate's self-test suite.
+ *
+ * @returns process exit code — 0 when every case behaved and the floor held.
+ */
+export function runSelfTest(opts: SelfTestOptions): number {
+    const write = opts.write ?? process.stdout.write.bind(process.stdout);
+    const minReject = opts.minRejectCases ?? 1;
+    const rejectCases = opts.cases.filter((c) => c.expect === 'reject').length;
+
+    if (opts.cases.length < opts.minCases || rejectCases < minReject) {
+        write(
+            `❌  ${opts.gate} --self-test: ${String(opts.cases.length)} case(s) ` +
+                `(${String(rejectCases)} rejecting) is below the declared floor of ` +
+                `${String(opts.minCases)} (${String(minReject)} rejecting). A truncated self-test ` +
+                'must fail rather than print success — deleting cases is otherwise the cheapest ' +
+                'route to a green one.\n',
+        );
+        return 1;
+    }
+
+    let failed = 0;
+    for (const testCase of opts.cases) {
+        let exit: number;
+        try {
+            exit = testCase.run();
+        } catch (e) {
+            write(`❌  ${opts.gate} --self-test: ${testCase.name} — threw: ${String(e)}\n`);
+            failed += 1;
+            continue;
+        }
+        const behaved = testCase.expect === 'reject' ? exit !== 0 : exit === 0;
+        if (behaved) {
+            write(`✅  ${testCase.name} (expected ${testCase.expect}, exit ${String(exit)})\n`);
+        } else {
+            write(
+                `❌  ${testCase.name}: expected the gate to ${testCase.expect} this fixture, ` +
+                    `got exit ${String(exit)}. The gate's detection has stopped firing on a case ` +
+                    'it is supposed to catch.\n',
+            );
+            failed += 1;
+        }
+    }
+
+    write(
+        `\n${opts.gate} --self-test: ${String(opts.cases.length - failed)}/${String(opts.cases.length)} ` +
+            `case(s) behaved (${String(rejectCases)} rejecting, floor ${String(opts.minCases)})\n`,
+    );
+    return failed > 0 ? 1 : 0;
+}

package/src/scripts/_lib/measured_render.ts

@@ -0,0 +1,97 @@
+/**
+ * Render-only-measured — a category with no measurement is never a number.
+ *
+ * WHY. The recorded failure: the always-budget report printed a share for a
+ * dimension it counted **zero** artefacts in. `0 / 0` became `0.0%`, and `0.0%`
+ * reads as a measurement that came back low — the most confident possible way
+ * to say nothing. Nobody looking at the page could tell the difference between
+ * "we measured this and it is at zero" and "we never measured this at all".
+ *
+ * The invariant is one line: **an unmeasured category renders as absent or
+ * explicitly "not measured", never as a zero and never as a computed share.**
+ * A zero is a claim; absence of measurement is not.
+ *
+ * The second half is the gap list. A coverage number published alone invites
+ * the reader to assume the remainder is small and boring. Naming the
+ * un-measured artefacts beside the covered count costs one line and removes the
+ * assumption — see {@link renderCoverage}.
+ *
+ * **Gaming risk.** A generator can still bypass this module and interpolate its
+ * own `${(n/d*100).toFixed(1)}%`. Nothing here can stop that; the mitigation is
+ * the paired test assertion (a generator handed an unmeasured dimension must
+ * emit no percentage) plus review. The residual is a generator that neither
+ * imports this nor carries that test, which is why the invariant is written
+ * into the authoring guideline rather than only into this file.
+ */
+
+/** How an unmeasured category is spelled. Exported so tests can pin it. */
+export const NOT_MEASURED = 'not measured';
+
+export interface ShareOptions {
+    /** Decimal places for a real share. Default 1. */
+    precision?: number;
+    /**
+     * Set false when the dimension was not measured at all, even though a
+     * denominator happens to be available. A denominator alone does not prove
+     * the measurement ran.
+     */
+    measured?: boolean;
+}
+
+/**
+ * A percentage, or {@link NOT_MEASURED} when there is nothing to divide.
+ *
+ * Never returns `0.0%` for an empty denominator — that is the whole point.
+ */
+export function renderShare(numerator: number, denominator: number, opts: ShareOptions = {}): string {
+    if (opts.measured === false || denominator <= 0 || !Number.isFinite(denominator)) {
+        return NOT_MEASURED;
+    }
+    if (!Number.isFinite(numerator)) {
+        return NOT_MEASURED;
+    }
+    return `${((numerator / denominator) * 100).toFixed(opts.precision ?? 1)}%`;
+}
+
+/** A count, or {@link NOT_MEASURED} when the category was never measured. */
+export function renderCount(value: number | null | undefined, measured = true): string {
+    if (!measured || value === null || value === undefined || !Number.isFinite(value)) {
+        return NOT_MEASURED;
+    }
+    return String(value);
+}
+
+export interface CoverageLine {
+    label: string;
+    covered: number;
+    total: number;
+    /** The un-covered artefacts, named. Empty array means genuinely none. */
+    gaps: readonly string[];
+    /** Cap on how many gap names are printed inline. Default 8. */
+    maxGaps?: number;
+}
+
+/**
+ * A coverage number WITH its gap list.
+ *
+ * The gap list is not optional formatting. A coverage number published alone
+ * lets the reader assume the remainder is small and boring; naming it removes
+ * the assumption at the cost of one line. When the count is capped for length,
+ * the true remainder is still stated — a silently truncated gap list reads as
+ * "covered everything" exactly like the number it was meant to qualify.
+ */
+export function renderCoverage(line: CoverageLine): string {
+    const share = renderShare(line.covered, line.total);
+    const head = `${line.label}: ${String(line.covered)}/${String(line.total)} (${share})`;
+    if (line.total <= 0) {
+        return `${line.label}: ${NOT_MEASURED} — the population is empty, so there is no coverage to report`;
+    }
+    if (line.gaps.length === 0) {
+        return `${head} — no gaps`;
+    }
+    const cap = line.maxGaps ?? 8;
+    const shown = line.gaps.slice(0, cap);
+    const more = line.gaps.length - shown.length;
+    const tail = more > 0 ? `, … and ${String(more)} more` : '';
+    return `${head} — not covered: ${shown.join(', ')}${tail}`;
+}