@skill-harness/core 0.6.0 → 0.7.0

package/dist/execution-trace.js

@@ -0,0 +1,299 @@
+import { createHash } from "node:crypto";
+import { EXECUTION_TRACE_VERSION } from "./capture-trace-types.js";
+import { redactArgs, redactText } from "./capture.js";
+/**
+ * Parse pi's `--mode json` event stream into an `ExecutionTraceV1`.
+ *
+ * Measured against pi 0.83.0; see `docs/pi-native-capture-design-2026-08-08.md`
+ * and the fixtures in `packages/adapters/test/fixtures/pi-json/`. Three findings
+ * from that spike are baked in here and each one is a bug if removed:
+ *
+ * 1. **Line-at-a-time, never buffered.** `message_update` re-sends the entire
+ *    accumulated message on every delta, so the stream is quadratic in output
+ *    length — a trivial three-tool-call run emitted 52 MB wrapping 12 KB of
+ *    terminal events. The parser consumes an iterable of lines and holds only
+ *    what it keeps.
+ * 2. **The final assistant message only.** pi's print mode — what the judge has
+ *    always been shown — emits exactly that. Concatenating every assistant text
+ *    block would add interim narration the transcript has never contained and
+ *    move verdicts on scenarios nobody edited.
+ * 3. **Correlate tool calls by `toolCallId`.** Batched calls execute
+ *    concurrently and their `end` events arrive in completion order.
+ */
+/** Events that carry no information a trace keeps, and are large. */
+const SKIPPED = new Set(["message_update", "tool_execution_update"]);
+/** `details` larger than this is dropped rather than persisted. */
+const MAX_DETAILS_CHARS = 2000;
+/**
+ * Build a trace from pi JSON lines.
+ *
+ * Malformed lines are counted, not thrown on: a single truncated line at the end
+ * of a killed process must not discard an otherwise complete trace. But a stream
+ * with NO terminal events at all is not a trace — `isComplete` says so, and the
+ * caller turns that into ERROR rather than a passing gate.
+ */
+export function parseTrace(lines, meta) {
+    const calls = new Map();
+    let issueCounter = 0;
+    let completionCounter = 0;
+    let malformedLines = 0;
+    let sawTerminal = false;
+    let finalText = "";
+    let lastAssistantText = "";
+    let cost = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(trimmed);
+        }
+        catch {
+            malformedLines++;
+            continue;
+        }
+        const type = ev.type;
+        if (typeof type !== "string" || SKIPPED.has(type))
+            continue;
+        if (type === "tool_execution_start") {
+            const id = str(ev.toolCallId);
+            if (!id)
+                continue;
+            calls.set(id, {
+                id,
+                name: str(ev.toolName) ?? "(unknown)",
+                args: redactArgs(ev.args, meta.homeDir),
+                issueIndex: issueCounter++,
+                completionIndex: -1, // filled in on `end`; -1 means it never completed
+                isError: false,
+                result: { bytes: 0, sha256: sha256("") },
+            });
+            continue;
+        }
+        if (type === "tool_execution_end") {
+            const id = str(ev.toolCallId);
+            if (!id)
+                continue;
+            const call = calls.get(id);
+            if (!call)
+                continue; // an end with no start is not evidence of a call
+            call.completionIndex = completionCounter++;
+            call.isError = ev.isError === true;
+            call.result = resultMeta(ev.result, meta.homeDir);
+            continue;
+        }
+        if (type === "message_end") {
+            sawTerminal = true;
+            const msg = ev.message;
+            if (msg?.role !== "assistant")
+                continue;
+            const text = assistantText(msg);
+            if (text) {
+                lastAssistantText = text;
+                // `stop` marks the model's closing message; a `toolUse` message is
+                // mid-flight narration and is deliberately not the transcript.
+                if (msg.stopReason === "stop")
+                    finalText = text;
+            }
+            const total = msg.usage?.cost?.total;
+            if (typeof total === "number")
+                cost = (cost ?? 0) + total;
+            continue;
+        }
+        if (type === "turn_end" || type === "agent_end" || type === "agent_settled") {
+            sawTerminal = true;
+            // Deliberately read NOTHING from these. They repeat the same assistant
+            // messages `message_end` already carried (`turn_end` and `agent_end` do;
+            // `agent_settled` carries no keys at all beyond `type`), and reading two
+            // sources would double the transcript and reintroduce thinking.
+            continue;
+        }
+    }
+    const trace = {
+        trace_version: EXECUTION_TRACE_VERSION,
+        pi_version: meta.piVersion,
+        subject: meta.subject,
+        scenario_id: meta.scenarioId,
+        mode: meta.mode,
+        rep: meta.rep,
+        turn: meta.turn,
+        // Fall back to the last assistant text when no message carried `stop` — a
+        // truncated or length-capped run still produced an answer, and losing it
+        // would silently turn a real reply into an empty transcript.
+        // Redacted: the model's own answer routinely quotes the paths it just read,
+        // and `smoke-real-pi.sh` asserts no `/home/` survives into a persisted trace
+        // — an assertion that used to pass only because the smoke model happened not
+        // to echo one.
+        final_text: redactText(finalText || lastAssistantText, meta.homeDir),
+        tool_calls: [...calls.values()].sort((a, b) => a.issueIndex - b.issueIndex),
+        // `null`, not `[]`: the stream says nothing about the filesystem. The runner
+        // overwrites this after observing the workspace. Defaulting to `[]` claimed
+        // "observed, nothing changed" for every trace ever parsed.
+        changed_paths: meta.changedPaths ? [...meta.changedPaths].sort() : null,
+        cost_usd: cost,
+    };
+    trace.trace_sha256 = traceSha256(trace);
+    return { trace, isComplete: sawTerminal, malformedLines };
+}
+/** Visible assistant text. Thinking is dropped here, and at every other reader. */
+function assistantText(msg) {
+    return (msg.content ?? [])
+        .filter((b) => b.type === "text" && typeof b.text === "string")
+        .map((b) => b.text)
+        .join("\n")
+        .trim();
+}
+/**
+ * Bounded metadata about a tool result. The body is never kept: results carry
+ * file contents, command output, and absolute paths (a failing `read` embeds the
+ * full path in its error string).
+ */
+function resultMeta(result, homeDir) {
+    const body = JSON.stringify(result?.content ?? result ?? null);
+    const meta = { bytes: Buffer.byteLength(body, "utf8"), sha256: sha256(body) };
+    const details = result?.details;
+    if (details && typeof details === "object" && !Array.isArray(details)) {
+        const encoded = JSON.stringify(details);
+        // Small `details` is the one channel an extension can expose deliberately.
+        // Large `details` is a result body wearing a different hat.
+        //
+        // Redacted like every other value that reaches disk. `TraceResultMeta` has
+        // always PROMISED this — "retained only when it is small and free of
+        // redaction hits" — while the code checked only the size, so a tool that put
+        // a token, a connection string or a home path in `details` wrote it verbatim
+        // into the trace artifact. `args` right beside it was redacted the whole time.
+        if (encoded.length <= MAX_DETAILS_CHARS)
+            meta.details = redactArgs(details, homeDir);
+    }
+    return meta;
+}
+function str(v) {
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/**
+ * Deterministic hash over the trace, excluding the hash field itself.
+ *
+ * Keys are emitted in a fixed order rather than whatever insertion produced, so
+ * the same execution always hashes the same — a digest that depends on key order
+ * would make `regate` report spurious drift.
+ */
+export function traceSha256(trace) {
+    const { trace_sha256: _omit, ...rest } = trace;
+    return sha256(stableStringify(rest));
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+/** Serialize a trace as the JSONL artifact saved beside a transcript. */
+export function serializeTrace(trace) {
+    return `${JSON.stringify(trace)}\n`;
+}
+/** Read a saved trace artifact back, for `regate`. Returns null when unusable. */
+export function deserializeTrace(text) {
+    const line = text.split("\n").find((l) => l.trim());
+    if (!line)
+        return null;
+    try {
+        const parsed = JSON.parse(line);
+        // A trace from a future version is refused rather than half-read: the whole
+        // point of the version field is that a reader can decline.
+        if (parsed.trace_version !== EXECUTION_TRACE_VERSION)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Collapse a scenario's per-turn traces into one view for gate evaluation.
+ *
+ * Assertions are written about the scenario ("it delegated to `plan` at least
+ * once"), not about turn 3 — a multi-turn scenario would otherwise need the
+ * author to know which turn a tool call landed in, which is a property of the
+ * model's choices, not of the test.
+ *
+ * Indices are renumbered across the whole scenario so `issueIndex` stays a total
+ * order. `completionIndex` is renumbered within the concatenation too: turns are
+ * strictly sequential (each is a separate `pi` invocation), so no completion in
+ * turn 2 can precede one in turn 1.
+ *
+ * Returns null for an empty list — "no turns produced evidence" must not look
+ * like "a run in which nothing happened".
+ */
+export function mergeTraces(traces) {
+    if (traces.length === 0)
+        return null;
+    if (traces.length === 1) {
+        // Compute the digest here rather than trusting the producer to have set it.
+        // `regate` identifies saved evidence by this hash, so a trace that arrived
+        // without one would be un-regatable — and an adapter is exactly the layer
+        // most likely to forget.
+        const only = traces[0];
+        return only.trace_sha256 ? only : { ...only, trace_sha256: traceSha256(only) };
+    }
+    const calls = [];
+    const changed = new Set();
+    let anyUnobserved = false;
+    let cost = null;
+    let completed = 0;
+    for (const t of traces) {
+        // Issue order and completion order are renumbered SEPARATELY. Assigning both
+        // from the same counter collapsed them, so every merged call got
+        // `completionIndex === issueIndex` — destroying the out-of-order completion
+        // data the parser records, and the persisted trace then described a
+        // concurrency ordering that did not happen.
+        const mergedCompletion = new Map([...t.tool_calls]
+            .filter((c) => c.completionIndex >= 0)
+            .sort((a, b) => a.completionIndex - b.completionIndex)
+            .map((c) => [c.id, completed++]));
+        for (const c of [...t.tool_calls].sort((a, b) => a.issueIndex - b.issueIndex)) {
+            calls.push({ ...c, issueIndex: calls.length, completionIndex: mergedCompletion.get(c.id) ?? -1 });
+        }
+        // A single unobserved turn makes the merged evidence unobserved: a scenario
+        // cannot claim "nothing changed" from turns it never looked at.
+        if (t.changed_paths === null)
+            anyUnobserved = true;
+        else
+            for (const p of t.changed_paths)
+                changed.add(p);
+        if (t.cost_usd !== null)
+            cost = (cost ?? 0) + t.cost_usd;
+    }
+    const last = traces[traces.length - 1];
+    const merged = {
+        ...last,
+        // The scenario's answer is its LAST turn's answer, matching how the
+        // transcript reads and how the judge is asked to grade it.
+        final_text: last.final_text,
+        tool_calls: calls,
+        changed_paths: anyUnobserved ? null : [...changed].sort(),
+        cost_usd: cost,
+    };
+    merged.trace_sha256 = traceSha256(merged);
+    return merged;
+}
+/** Split a raw stdout blob into lines. Prefer streaming; this is for saved blobs. */
+export function* lines(text) {
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === "\n") {
+            yield text.slice(start, i);
+            start = i + 1;
+        }
+    }
+    if (start < text.length)
+        yield text.slice(start);
+}
+//# sourceMappingURL=execution-trace.js.map

package/dist/index.d.ts

@@ -27,3 +27,11 @@ export * from "./regate.js";
 export * from "./downgrade.js";
 export * from "./canary.js";
 export * from "./stability.js";
+export * from "./capture-trace-types.js";
+export * from "./spec-write.js";
+export * from "./capture.js";
+export * from "./execution-trace.js";
+export * from "./trace-gates.js";
+export * from "./instruction-coverage.js";
+export * from "./affected.js";
+export * from "./adjudication.js";

package/dist/index.js

@@ -27,4 +27,12 @@ export * from "./regate.js";
 export * from "./downgrade.js";
 export * from "./canary.js";
 export * from "./stability.js";
+export * from "./capture-trace-types.js";
+export * from "./spec-write.js";
+export * from "./capture.js";
+export * from "./execution-trace.js";
+export * from "./trace-gates.js";
+export * from "./instruction-coverage.js";
+export * from "./affected.js";
+export * from "./adjudication.js";
 //# sourceMappingURL=index.js.map

package/dist/instruction-coverage.d.ts

@@ -0,0 +1,106 @@
+import type { Scenario } from "./spec.js";
+/**
+ * Which instructions have a test pointing at them.
+ *
+ * The unit is a Markdown heading section, because that is the unit skill authors
+ * already write in — no new syntax to learn, and no annotation step that gets
+ * skipped. The cost is that renaming a heading breaks a reference; that is
+ * reported as a broken reference rather than silently dropped, which is the only
+ * honest option (a silently-dropped reference reads as "not covered" and sends
+ * the author to write a test that already exists).
+ *
+ * **This measures declared linkage, not proof.** A section with a scenario
+ * pointing at it has *a test somebody associated with it* — not a guarantee the
+ * behavior is tested, still less tested well. Every surface here says "declared"
+ * for that reason. Overselling this number would make it worse than absent: an
+ * author who believes 100% coverage means 100% tested will stop looking.
+ */
+export interface Section {
+    /** GitHub-style slug, disambiguated on collision (`name`, `name-1`, …). */
+    slug: string;
+    /** Heading text as written. */
+    title: string;
+    /** Heading depth: 1 for `#`, 2 for `##`. Setext `===`/`---` map to 1/2. */
+    depth: number;
+    /** 1-based line of the heading itself. */
+    startLine: number;
+    /** 1-based last line of the section, inclusive — the line before the next heading. */
+    endLine: number;
+}
+/**
+ * GitHub-style anchor slug: lowercase, drop punctuation, spaces to hyphens.
+ *
+ * Matching GitHub matters because the reference an author writes
+ * (`SKILL.md#core-principle`) is the anchor they would use in a link, so it is
+ * the one they will guess.
+ */
+export declare function slugify(title: string): string;
+/**
+ * Extract heading sections from Markdown.
+ *
+ * Fenced code blocks are skipped: a shell comment (`# rebuild the bundle`) inside
+ * an example is not a section, and treating it as one both invents coverage
+ * targets and shifts every subsequent section's line range — which would then
+ * mis-map git hunks to the wrong section, silently selecting the wrong tests.
+ */
+export declare function parseSections(markdown: string): Section[];
+/** Section containing a 1-based line, or undefined for content before the first heading. */
+export declare function sectionAtLine(sections: Section[], line: number): Section | undefined;
+export interface CoversRef {
+    /** Raw reference as written in the spec. */
+    raw: string;
+    /** Path portion, relative to the spec dir. */
+    file: string;
+    /** Slug portion; undefined when the reference names a whole file. */
+    slug?: string;
+}
+/** Parse `SKILL.md#core-principle` / `../../agents/plan.md` into its parts. */
+export declare function parseCoversRef(raw: string): CoversRef;
+export interface SectionCoverage {
+    file: string;
+    section: Section;
+    /** Scenario ids that declare a reference to this section. */
+    scenarios: string[];
+    /** Capture ids parked against this section but not yet promoted. */
+    pendingCaptures: string[];
+}
+export interface BrokenRef {
+    scenarioId: string;
+    raw: string;
+    reason: "file-missing" | "section-missing";
+    /** Nearest slugs in that file, to make a rename obvious. */
+    didYouMean: string[];
+}
+export interface CoverageReport {
+    /** Every section of every referenced instruction file, covered or not. */
+    sections: SectionCoverage[];
+    covered: SectionCoverage[];
+    uncovered: SectionCoverage[];
+    broken: BrokenRef[];
+    /** Scenarios that declare no `covers` at all. */
+    unmapped: string[];
+    pct: number;
+}
+export interface CoverageOptions {
+    /** Dir that `covers` paths resolve against — the spec's own directory. */
+    specDir: string;
+    scenarios: Scenario[];
+    /** Instruction files to report on even if nothing references them. */
+    baseFiles?: string[];
+    /** capture id → covers refs, for parking a pending case against a section. */
+    pendingCaptures?: {
+        id: string;
+        covers: string[];
+    }[];
+}
+/**
+ * Build the coverage report.
+ *
+ * Free and offline — it reads Markdown and the spec, nothing else. That is
+ * deliberate: a coverage command that spends tokens would be run once.
+ */
+export declare function computeCoverage(opts: CoverageOptions): CoverageReport;
+/** Render the report for a terminal. `declared` wording is deliberate throughout. */
+export declare function formatCoverage(report: CoverageReport, skill: string): string;
+/** Path of `file` relative to `specDir`, normalized for comparison with `covers`. */
+export declare function relativeToSpec(specDir: string, file: string): string;

package/dist/instruction-coverage.js

@@ -0,0 +1,253 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, dirname, relative, isAbsolute } from "node:path";
+const FENCE = /^\s{0,3}(`{3,}|~{3,})/;
+const ATX = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
+const SETEXT_H1 = /^\s{0,3}=+\s*$/;
+const SETEXT_H2 = /^\s{0,3}-+\s*$/;
+/**
+ * GitHub-style anchor slug: lowercase, drop punctuation, spaces to hyphens.
+ *
+ * Matching GitHub matters because the reference an author writes
+ * (`SKILL.md#core-principle`) is the anchor they would use in a link, so it is
+ * the one they will guess.
+ */
+export function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[`*_~[\]()]/g, "")
+        .replace(/[^\p{L}\p{N}\s-]/gu, "")
+        .trim()
+        .replace(/\s+/g, "-");
+}
+/**
+ * Extract heading sections from Markdown.
+ *
+ * Fenced code blocks are skipped: a shell comment (`# rebuild the bundle`) inside
+ * an example is not a section, and treating it as one both invents coverage
+ * targets and shifts every subsequent section's line range — which would then
+ * mis-map git hunks to the wrong section, silently selecting the wrong tests.
+ */
+export function parseSections(markdown) {
+    const lines = markdown.split("\n");
+    const found = [];
+    const seen = new Map();
+    let fence = null;
+    // Skip YAML frontmatter. Every SKILL.md opens with it, and its closing `---`
+    // makes the line above look exactly like a Setext h2 underline — so without
+    // this, every skill gains a phantom section named after its own `description:`
+    // line, and it lands at the top where it is most likely to be "covered" by a
+    // careless whole-file reference.
+    const start = frontmatterEnd(lines);
+    const push = (title, depth, startLine) => {
+        const base = slugify(title);
+        if (base === "")
+            return; // an empty heading is not addressable
+        const n = seen.get(base) ?? 0;
+        seen.set(base, n + 1);
+        found.push({ slug: n === 0 ? base : `${base}-${n}`, title, depth, startLine });
+    };
+    for (let i = start; i < lines.length; i++) {
+        const line = lines[i];
+        const fenceMatch = FENCE.exec(line);
+        if (fenceMatch) {
+            const marker = fenceMatch[1][0];
+            if (fence === null)
+                fence = marker;
+            else if (fence === marker)
+                fence = null;
+            continue;
+        }
+        if (fence !== null)
+            continue;
+        const atx = ATX.exec(line);
+        if (atx) {
+            push(atx[2], atx[1].length, i + 1);
+            continue;
+        }
+        // Setext: the UNDERLINE marks the heading, whose text is the line above.
+        const prev = i > start ? lines[i - 1] : "";
+        if (prev.trim() !== "" && !ATX.test(prev)) {
+            if (SETEXT_H1.test(line))
+                push(prev.trim(), 1, i);
+            else if (SETEXT_H2.test(line) && /[^-\s]/.test(prev))
+                push(prev.trim(), 2, i);
+        }
+    }
+    return found.map((s, i) => ({
+        ...s,
+        endLine: i + 1 < found.length ? found[i + 1].startLine - 1 : lines.length,
+    }));
+}
+/**
+ * Index of the first line after YAML frontmatter, or 0 when there is none.
+ *
+ * Only a `---` on line 1 opens frontmatter — a `---` further down is a horizontal
+ * rule, and treating it as a delimiter would swallow the document.
+ */
+function frontmatterEnd(lines) {
+    if (lines[0]?.trim() !== "---")
+        return 0;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === "---")
+            return i + 1;
+    }
+    return 0; // unterminated: treat the whole file as content rather than losing it
+}
+/** Section containing a 1-based line, or undefined for content before the first heading. */
+export function sectionAtLine(sections, line) {
+    return sections.find((s) => line >= s.startLine && line <= s.endLine);
+}
+/** Parse `SKILL.md#core-principle` / `../../agents/plan.md` into its parts. */
+export function parseCoversRef(raw) {
+    const hash = raw.indexOf("#");
+    if (hash < 0)
+        return { raw, file: raw.trim() };
+    return { raw, file: raw.slice(0, hash).trim(), slug: raw.slice(hash + 1).trim() || undefined };
+}
+/**
+ * Build the coverage report.
+ *
+ * Free and offline — it reads Markdown and the spec, nothing else. That is
+ * deliberate: a coverage command that spends tokens would be run once.
+ */
+export function computeCoverage(opts) {
+    const fileSections = new Map();
+    const readSections = (file) => {
+        if (fileSections.has(file))
+            return fileSections.get(file);
+        const abs = isAbsolute(file) ? file : resolve(opts.specDir, file);
+        if (!existsSync(abs))
+            return null;
+        const sections = parseSections(readFileSync(abs, "utf8"));
+        fileSections.set(file, sections);
+        return sections;
+    };
+    for (const f of opts.baseFiles ?? [])
+        readSections(f);
+    const bySection = new Map();
+    const key = (file, slug) => `${file}#${slug}`;
+    const ensure = (file, section) => {
+        const k = key(file, section.slug);
+        let entry = bySection.get(k);
+        if (!entry) {
+            entry = { file, section, scenarios: [], pendingCaptures: [] };
+            bySection.set(k, entry);
+        }
+        return entry;
+    };
+    // Seed every section of every known file, so "uncovered" is a real list rather
+    // than only what someone happened to reference.
+    for (const [file, sections] of fileSections)
+        for (const s of sections)
+            ensure(file, s);
+    const broken = [];
+    const unmapped = [];
+    const attach = (id, refs, into) => {
+        for (const raw of refs) {
+            const ref = parseCoversRef(raw);
+            const sections = readSections(ref.file);
+            if (sections === null) {
+                broken.push({ scenarioId: id, raw, reason: "file-missing", didYouMean: [] });
+                continue;
+            }
+            for (const s of sections)
+                ensure(ref.file, s);
+            if (ref.slug === undefined) {
+                // A whole-file reference covers every section in it.
+                for (const s of sections)
+                    ensure(ref.file, s)[into].push(id);
+                continue;
+            }
+            const match = sections.find((s) => s.slug === ref.slug);
+            if (!match) {
+                broken.push({
+                    scenarioId: id,
+                    raw,
+                    reason: "section-missing",
+                    didYouMean: nearest(ref.slug, sections.map((s) => s.slug)),
+                });
+                continue;
+            }
+            ensure(ref.file, match)[into].push(id);
+        }
+    };
+    for (const s of opts.scenarios) {
+        if (!s.covers || s.covers.length === 0) {
+            unmapped.push(s.id);
+            continue;
+        }
+        attach(s.id, s.covers, "scenarios");
+    }
+    for (const c of opts.pendingCaptures ?? [])
+        attach(c.id, c.covers, "pendingCaptures");
+    const sections = [...bySection.values()].sort((a, b) => a.file.localeCompare(b.file) || a.section.startLine - b.section.startLine);
+    const covered = sections.filter((s) => s.scenarios.length > 0);
+    const uncovered = sections.filter((s) => s.scenarios.length === 0);
+    return {
+        sections,
+        covered,
+        uncovered,
+        broken,
+        unmapped,
+        pct: sections.length === 0 ? 0 : Math.round((covered.length / sections.length) * 100),
+    };
+}
+/**
+ * Closest existing slugs, so a broken reference names the likely rename.
+ *
+ * A renamed heading is the common cause of a broken reference, and
+ * "section-missing: core-principle" without a suggestion sends the author
+ * hunting through a file they just edited.
+ */
+function nearest(target, candidates, limit = 3) {
+    return candidates
+        .map((c) => ({ c, d: distance(target, c) }))
+        .filter(({ c, d }) => d <= Math.max(3, Math.floor(c.length / 2)))
+        .sort((a, b) => a.d - b.d)
+        .slice(0, limit)
+        .map(({ c }) => c);
+}
+function distance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let last = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, last + (a[i - 1] === b[j - 1] ? 0 : 1));
+            last = tmp;
+        }
+    }
+    return prev[b.length];
+}
+/** Render the report for a terminal. `declared` wording is deliberate throughout. */
+export function formatCoverage(report, skill) {
+    const out = [];
+    out.push(`${skill}: ${report.covered.length}/${report.sections.length} sections have a declared test (${report.pct}%)`);
+    out.push("");
+    if (report.uncovered.length) {
+        out.push("  no test declares coverage of:");
+        for (const s of report.uncovered)
+            out.push(`    ${s.file}#${s.section.slug}  (${s.section.title})`);
+        out.push("");
+    }
+    if (report.broken.length) {
+        out.push("  broken references:");
+        for (const b of report.broken) {
+            const hint = b.didYouMean.length ? ` — did you mean ${b.didYouMean.map((s) => `#${s}`).join(", ")}?` : "";
+            out.push(`    ${b.scenarioId}: ${b.raw} (${b.reason})${hint}`);
+        }
+        out.push("");
+    }
+    if (report.unmapped.length) {
+        out.push(`  scenarios with no \`covers\`: ${report.unmapped.join(", ")}`);
+        out.push("");
+    }
+    out.push("  `covers` records a declared link, not proof the behaviour is tested.");
+    return out.join("\n");
+}
+/** Path of `file` relative to `specDir`, normalized for comparison with `covers`. */
+export function relativeToSpec(specDir, file) {
+    return relative(specDir, isAbsolute(file) ? file : resolve(dirname(specDir), file)).split("\\").join("/");
+}
+//# sourceMappingURL=instruction-coverage.js.map