@sema-agent/wiki-gate 0.0.0-stage → 7.67.0

package/dist/page.js

@@ -0,0 +1,175 @@
+const MARKER = /\{\{([GUPVI])((?:\s+(?:"[^"]*"|[^\s{}])+)*)\s*\}\}/g;
+const GEN_OPEN_LINE = /^<!-- wiki:gen ([a-z][a-z-]*)((?: [^ <>]+)*) -->$/;
+const GEN_OPEN_ANY = /<!-- wiki:gen /;
+const GEN_INLINE = /<!-- wiki:gen ([a-z][a-z-]*)((?: [^ <>]+)*) -->([\s\S]*?)<!-- \/wiki:gen -->/g;
+export const GEN_CLOSE = "<!-- /wiki:gen -->";
+const INLINE_CODE = /`[^`\n]*`/g;
+export function splitPage(text) {
+    const m = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(text);
+    if (!m)
+        return { fm: null, body: text, bodyLine: 1, fmLines: [] };
+    const fm = Object.assign(Object.create(null), { _list: Object.create(null) });
+    const fmLines = [];
+    m[1].split("\n").forEach((line, i) => {
+        const kv = /^([a-z][a-z-]*):[ \t]*(.*)$/.exec(line);
+        fmLines.push({ line: i + 2, key: kv?.[1], value: kv?.[2], raw: line });
+        if (!kv)
+            return;
+        (fm._list[kv[1]] ??= []).push(kv[2]);
+        fm[kv[1]] ??= kv[2];
+    });
+    return { fm, body: m[2], bodyLine: m[1].split("\n").length + 3, fmLines };
+}
+export function claimBlocks(body) {
+    const lines = body.split("\n");
+    const starts = [];
+    for (let i = 0, at = 0; i < lines.length; at += lines[i].length + 1, i++)
+        starts.push(at);
+    const blocks = [];
+    const gens = [];
+    const fences = [];
+    const units = [];
+    const headings = [];
+    const problems = [];
+    let cur = [];
+    let inFence = null;
+    const flush = (end) => {
+        if (cur.length) {
+            const b = { line: end - cur.length + 1, text: cur.join("\n") };
+            blocks.push(b);
+            units.push({ kind: "block", text: replaceInlineGens(b.text, (m) => `<gen ${m[1]}${m[2]}>`) });
+        }
+        cur = [];
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const L = lines[i];
+        const n = i + 1;
+        if (inFence) {
+            if (/^```\s*$/.test(L)) {
+                fences.push(inFence);
+                units.push({ kind: "fence", text: `${inFence.lang} ${inFence.info}\n${inFence.body.join("\n")}` });
+                inFence = null;
+            }
+            else
+                inFence.body.push(L);
+            continue;
+        }
+        const f = /^```(\S*)\s*(.*)$/.exec(L);
+        if (f) {
+            flush(n - 1);
+            inFence = { line: n, lang: f[1], info: f[2], body: [] };
+            continue;
+        }
+        const g = GEN_OPEN_LINE.exec(L);
+        if (g) {
+            flush(n - 1);
+            let j = i + 1;
+            const content = [];
+            while (j < lines.length && lines[j] !== GEN_CLOSE)
+                content.push(lines[j++]);
+            const closed = j < lines.length;
+            gens.push({ line: n, name: g[1], args: g[2].trim().split(" ").filter(Boolean), content: content.join("\n"), inline: false, closed, span: [starts[i], closed ? starts[j] + GEN_CLOSE.length : body.length] });
+            i = j;
+            continue;
+        }
+        if (GEN_OPEN_ANY.test(maskCode(L)) && !maskCode(L).includes(GEN_CLOSE))
+            problems.push({ line: n, message: "a generated region opens inside a line and does not close on it (a region of its own starts on a line holding only its opening comment)" });
+        if (/^\s*$/.test(L)) {
+            flush(n - 1);
+            continue;
+        }
+        if (/^#{1,6} /.test(L)) {
+            flush(n - 1);
+            units.push({ kind: "heading", text: L });
+            headings.push({ line: n, text: L });
+            continue;
+        }
+        if (/^\|[\s:|-]+\|\s*$/.test(L))
+            continue;
+        if (/^<!--(?:(?!-->)[\s\S])*-->\s*$/.test(L) && !GEN_OPEN_ANY.test(L)) {
+            flush(n - 1);
+            continue;
+        }
+        if (/^\|/.test(L) && /^\|[\s:|-]+\|\s*$/.test(lines[i + 1] ?? "")) {
+            flush(n - 1);
+            units.push({ kind: "header", text: L });
+            continue;
+        }
+        if (/^\s*([-*]|\d+\.)\s/.test(L) || /^\|/.test(L)) {
+            flush(n - 1);
+            cur.push(L);
+            flush(n);
+            continue;
+        }
+        cur.push(L);
+    }
+    flush(lines.length);
+    if (inFence)
+        fences.push({ ...inFence, unclosed: true });
+    for (const b of blocks) {
+        for (const g of inlineGensOf(b.text)) {
+            const at = starts[b.line - 1] + g.index;
+            gens.push({ line: b.line, name: g.m[1], args: g.m[2].trim().split(" ").filter(Boolean), content: g.m[3], inline: true, closed: true, span: [at, at + g.length] });
+        }
+    }
+    return { blocks, gens, fences, units, headings, problems };
+}
+function maskCode(text) {
+    return text.replace(INLINE_CODE, (s) => "x".repeat(s.length));
+}
+function maskQuote(view, text) {
+    const c = correctionLineOf(text);
+    return c ? view.slice(0, c.quoteSpan[0]) + "x".repeat(c.quoteSpan[1] - c.quoteSpan[0]) + view.slice(c.quoteSpan[1]) : view;
+}
+export function inlineGensOf(text) {
+    const out = [];
+    for (const v of maskQuote(maskCode(text), text).matchAll(GEN_INLINE))
+        out.push({ index: v.index, length: v[0].length, m: new RegExp(GEN_INLINE.source).exec(text.slice(v.index, v.index + v[0].length)) });
+    return out;
+}
+function replaceInlineGens(text, f) {
+    let out = "";
+    let at = 0;
+    for (const g of inlineGensOf(text)) {
+        out += text.slice(at, g.index) + f(g.m);
+        at = g.index + g.length;
+    }
+    return out + text.slice(at);
+}
+function refTokens(refText) {
+    return [...refText.matchAll(/(?:[^\s"]+"[^"]*"[^\s"]*|[^\s"]+)/g)].map((m) => m[0]);
+}
+const CORRECTION_LINE = /^((?:[-*]|\d+\.)\s+)?"([\s\S]*?)" — corrected by (W-\d+) on (\d{4}-\d{2}-\d{2}) at (\d+\.\d+\.\d+): /;
+export function correctionLineOf(text) {
+    const m = CORRECTION_LINE.exec(text);
+    if (!m)
+        return undefined;
+    const open = (m[1] ?? "").length;
+    return { correction: m[3], date: m[4], version: m[5], quoted: m[2], quoteSpan: [open, open + m[2].length + 2] };
+}
+export function sectionIdOf(heading) {
+    return heading
+        .replace(/^#{1,6}\s+/, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export function markersOf(text) {
+    const view = maskQuote(maskCode(text), text).replace(GEN_INLINE, (s) => "x".repeat(s.length));
+    const markers = [...view.matchAll(MARKER)].map((v) => ({ level: v[1], refs: refTokens(text.slice(v.index + 3, v.index + v[0].length - 2)), index: v.index, length: v[0].length }));
+    return { stripped: view.trimEnd(), markers };
+}
+export function citationsOf(text) {
+    const { fm, body } = splitPage(text);
+    const { blocks, gens, fences } = claimBlocks(body);
+    const refs = new Set();
+    for (const b of blocks)
+        for (const mk of markersOf(b.text).markers)
+            for (const r of mk.refs)
+                refs.add(r);
+    for (const f of fences)
+        for (const mk of markersOf(f.info).markers)
+            for (const r of mk.refs)
+                refs.add(r);
+    return { feats: fm?._list.feats ?? [], refs: [...refs], gens };
+}

package/dist/run.d.ts

@@ -0,0 +1,81 @@
+import { type Finding } from "./check.js";
+import { type CoverageReportRow, type RequiredSummaryRow } from "./coverage.js";
+import { type WikiGateConfig } from "./tree.js";
+import { type Severity } from "./versions.js";
+/** A finding with the severity this run judged it at. */
+export type JudgedFinding = Finding & {
+    readonly severity: Severity;
+};
+/** The verdict of a gate run: how many failures and warnings, the exit code, and the line that always speaks. */
+export interface Verdict {
+    readonly judged: JudgedFinding[];
+    readonly failures: number;
+    readonly warnings: number;
+    readonly exit: 0 | 1;
+    readonly line: string;
+}
+/**
+ * A run's verdict. `redFrom` is the version this repository's findings fail from, for the genre under check; `notes`
+ * are what the line says besides the counts (the required sources, the correction record, the acceptance index).
+ */
+export declare function verdictOf(gate: string, findings: readonly Finding[], { version, strict, pages, redFrom, notes }: {
+    version: string;
+    strict?: boolean;
+    pages: number;
+    redFrom: string;
+    notes?: readonly string[];
+}): Verdict;
+/** How one gate entry runs: strict or not, which pages (repo-relative; every page when absent), where the other checkouts are. */
+export interface GateOptions {
+    readonly strict?: boolean;
+    readonly pages?: readonly string[];
+    /** The comms checkout the coverage gate reads feature rows from. */
+    readonly commsRoot?: string;
+    /** Where to look for a comms checkout when `commsRoot` is not named, in order. */
+    readonly commsCandidates?: readonly string[];
+    /** The acceptance-index checkout `crit:` refs are read in. */
+    readonly testRoot?: string;
+    /** The correction-record checkout. */
+    readonly correctionsRoot?: string;
+}
+/** A gate entry's answer: a verdict and the coverage report — or exit 2 and the reason it could not judge. */
+export type GateResult = (Verdict & {
+    readonly report: CoverageReportRow[];
+    readonly required: RequiredSummaryRow[];
+    readonly pages: number;
+}) | {
+    readonly exit: 2;
+    readonly couldNotJudge: string;
+};
+/** The anchors gate: page shape, every claim marked, every ref resolves, nothing internal, no open correction. */
+export declare function wikiAnchors(config: WikiGateConfig, opts?: GateOptions): GateResult;
+/** The freshness gate: every stamped digest and every generated region against the tree now. */
+export declare function wikiFreshness(config: WikiGateConfig, opts?: GateOptions): GateResult;
+/** The coverage gate: every required source covered; the reported sources counted. */
+export declare function wikiCoverage(config: WikiGateConfig, opts?: GateOptions): GateResult;
+/** What the command-line runner reads besides the configuration. */
+export interface WikiGateCommandLine {
+    readonly argv: readonly string[];
+    /** The directory page arguments are relative to (the process's own when absent). */
+    readonly cwd?: string;
+    /** How the usage line names the command. */
+    readonly invocation?: string;
+    /** Where to look for a comms checkout when `--comms` is not given, in order. */
+    readonly commsCandidates?: () => readonly string[];
+    /** The commit a stamp vouches for: the repository's head. */
+    readonly headCommit?: () => string;
+}
+/**
+ * The command line over the entries and the stamp:
+ *
+ *   anchors   [--strict] [--test <dir>] [--corrections <dir>] [<page.md> …]
+ *   freshness [--strict] [--test <dir>] [--corrections <dir>] [<page.md> …]
+ *   coverage  [--strict] [--comms <dir>] [--test <dir>] [--corrections <dir>] [--report]
+ *   stamp [--test <dir>] [--corrections <dir>] <page.md> …
+ *
+ * `--report` prints the coverage report as a table (source, cited, size, cited %) in place of the plain `report:` lines.
+ * An option a command does not take is refused by name (exit 2), so a misspelled `--strcit` cannot pass as a lenient run.
+ * Exit 0 = no failure (warnings are printed), 1 = at least one failure, 2 = cannot judge. Every run prints a verdict
+ * line: a gate that judged nothing must not look like a green one.
+ */
+export declare function runWikiGate(config: WikiGateConfig, cli: WikiGateCommandLine): number;

package/dist/run.js

@@ -0,0 +1,231 @@
+import { statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { checkPage, stampPage } from "./check.js";
+import { coverageFindings, readFeatRows, requiredSummaryOf } from "./coverage.js";
+import { splitPage } from "./page.js";
+import { correctionSourceOf, createTree, repoOf } from "./tree.js";
+import { compareVersions, severityOf } from "./versions.js";
+import { CORRECTION_RECORD } from "./corrections.js";
+export function verdictOf(gate, findings, { version, strict = false, pages, redFrom, notes = [] }) {
+    const judged = findings.map((f) => ({ ...f, severity: severityOf(f, { version, strict, redFrom }) }));
+    const failures = judged.filter((f) => f.severity === "fail").length;
+    const warnings = judged.length - failures;
+    const period = strict ? "strict: no version grace, a finding's own severity holds" : compareVersions(version, redFrom) >= 0 ? `findings fail (this tree is ${version}, failing since ${redFrom})` : `warning period: findings fail from ${redFrom}, this tree is ${version}`;
+    const line = `wiki-${gate}: ${pages} page(s), ${failures} failure(s), ${warnings} warning(s) — ${period}${notes.map((n) => ` · ${n}`).join("")}`;
+    return { judged, failures, warnings, exit: failures > 0 ? 1 : 0, line };
+}
+function isFile(abs) {
+    try {
+        return statSync(abs).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function prepared(config, opts) {
+    try {
+        const tree = createTree(config, { testRoot: opts.testRoot, correctionsRoot: opts.correctionsRoot });
+        const repo = repoOf(tree);
+        const redFrom = config.redFrom?.[config.genre];
+        if (redFrom === undefined)
+            throw new Error(`the configuration names no red-from version for the ${config.genre} genre`);
+        compareVersions(repo.version, redFrom);
+        for (const [which, sources] of [["required", config.required], ["reported", config.reported]]) {
+            for (const [name, v] of Object.entries(sources ?? {}))
+                if (v === undefined)
+                    throw new Error(`the ${which} source \`${name}\` is declared and this repository configures no reader for it`);
+        }
+        const corrections = correctionSourceOf(config);
+        if (corrections.declared && corrections.source === undefined)
+            throw new Error(`the required source \`${CORRECTION_RECORD}\` is not a correction-record reader`);
+        config.preflight?.(tree);
+        const notes = [];
+        if (!corrections.declared)
+            notes.push("corrections: not declared");
+        else {
+            const records = tree.corrections();
+            if (records === undefined)
+                throw new Error("the correction record is a required source and is not in this check (name its checkout with --corrections <dir>)");
+            notes.push(`corrections: ${records.length} record(s), ${records.filter((r) => r.status === "open").length} open`);
+        }
+        if (config.readers?.acceptanceIndex !== undefined) {
+            const index = tree.acceptanceIndex();
+            notes.push(index === undefined ? "acceptance index: not in this check" : `acceptance index at ${index.commit}`);
+        }
+        return { tree, repo, redFrom, notes };
+    }
+    catch (e) {
+        return { couldNotJudge: e.message };
+    }
+}
+function pageIdTwins(tree) {
+    const byId = new Map();
+    for (const rel of tree.allPageFiles()) {
+        const id = splitPage(tree.read(rel)).fm?.["page-id"];
+        if (id !== undefined)
+            byId.set(id, [...(byId.get(id) ?? []), rel]);
+    }
+    return byId;
+}
+function runGate(gate, config, opts) {
+    const ready = prepared(config, opts);
+    if ("couldNotJudge" in ready)
+        return { exit: 2, couldNotJudge: ready.couldNotJudge };
+    const { tree, repo, redFrom, notes } = ready;
+    const strict = opts.strict ?? false;
+    const pages = opts.pages === undefined || opts.pages.length === 0 ? tree.wikiPageFiles() : [...opts.pages];
+    const notFiles = pages.filter((p) => !isFile(join(config.root, p)));
+    if (pages.length === 0 || notFiles.length > 0)
+        return { exit: 2, couldNotJudge: pages.length === 0 ? `no page under ${tree.wikiDir}` : `not a page file: ${notFiles.join(", ")}` };
+    try {
+        let findings = [];
+        const report = [];
+        const required = [];
+        if (gate === "coverage") {
+            const all = tree.wikiPageFiles().map((rel) => ({ rel, text: tree.read(rel) }));
+            const r = coverageFindings(tree, all, readFeatRows(repo.word, { commsRoot: opts.commsRoot, candidates: opts.commsCandidates }));
+            findings = r.findings;
+            report.push(...r.report);
+            required.push(...r.required);
+            notes.unshift(requiredSummaryOf(r.required));
+        }
+        else {
+            const twins = gate === "anchors" ? pageIdTwins(tree) : new Map();
+            for (const rel of pages) {
+                const text = tree.read(rel);
+                findings.push(...checkPage(tree, rel, text).findings.filter((f) => f.gate === gate));
+                const id = splitPage(text).fm?.["page-id"];
+                const others = id === undefined ? [] : (twins.get(id) ?? []).filter((p) => p !== rel);
+                if (others.length > 0)
+                    findings.push({ gate: "anchors", page: rel, line: 1, message: `page-id \`${id}\` is also the id of ${others.join(", ")}: a page-id is unique across a repository's genres` });
+            }
+        }
+        return { ...verdictOf(gate, findings, { version: repo.version, strict, pages: pages.length, redFrom, notes }), report, required, pages: pages.length };
+    }
+    catch (e) {
+        return { exit: 2, couldNotJudge: e.message };
+    }
+}
+export function wikiAnchors(config, opts = {}) {
+    return runGate("anchors", config, opts);
+}
+export function wikiFreshness(config, opts = {}) {
+    return runGate("freshness", config, opts);
+}
+export function wikiCoverage(config, opts = {}) {
+    return runGate("coverage", config, opts);
+}
+const GATES = Object.freeze({ anchors: wikiAnchors, freshness: wikiFreshness, coverage: wikiCoverage });
+const VALUED_FLAGS = Object.freeze(["--comms", "--test", "--corrections"]);
+const OPTIONS = Object.freeze({
+    anchors: ["--strict", "--test", "--corrections"],
+    freshness: ["--strict", "--test", "--corrections"],
+    coverage: ["--strict", "--comms", "--test", "--corrections", "--report"],
+    stamp: ["--test", "--corrections"],
+});
+function coverageTable(rows) {
+    const out = ["| source | cited | size | cited % |", "|---|---|---|---|"];
+    for (const row of rows)
+        out.push(`| ${row.source} | ${row.cited} | ${row.size} | ${row.size === 0 ? "—" : `${((100 * row.cited) / row.size).toFixed(1)}%`} |`);
+    return out;
+}
+export function runWikiGate(config, cli) {
+    const [cmd, ...rest] = cli.argv;
+    const usage = `usage: ${cli.invocation ?? "wiki-gate"} anchors|freshness|coverage [--strict] [--comms <dir>] [--test <dir>] [--corrections <dir>] [--report] [<page.md> …] | stamp <page.md> …`;
+    if (cmd === undefined || !Object.hasOwn(OPTIONS, cmd)) {
+        console.error(usage);
+        return 2;
+    }
+    const taken = OPTIONS[cmd];
+    const flags = new Set();
+    const values = new Map();
+    const args = [];
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (!a.startsWith("--")) {
+            args.push(a);
+            continue;
+        }
+        if (!taken.includes(a)) {
+            console.error(`wiki-${cmd}: unknown option ${a} — \`${cmd}\` takes ${taken.join(", ")}\n${usage}`);
+            return 2;
+        }
+        if (VALUED_FLAGS.includes(a)) {
+            const v = rest[++i];
+            if (v === undefined || v.startsWith("--")) {
+                console.error(`wiki-${cmd}: ${a} needs a directory\n${usage}`);
+                return 2;
+            }
+            values.set(a, v);
+            continue;
+        }
+        flags.add(a);
+    }
+    const strict = flags.has("--strict");
+    const cwd = cli.cwd ?? process.cwd();
+    const pages = args.map((a) => relative(config.root, isAbsolute(a) ? a : resolve(cwd, a)).split("\\").join("/"));
+    const at = (flag) => {
+        const v = values.get(flag);
+        return v === undefined ? undefined : resolve(cwd, v);
+    };
+    const where = { testRoot: at("--test"), correctionsRoot: at("--corrections") };
+    if (cmd === "stamp")
+        return runStamp(config, cli, pages, where);
+    const commsRoot = at("--comms");
+    const commsCandidates = cmd === "coverage" && !commsRoot ? cli.commsCandidates?.() : undefined;
+    const r = GATES[cmd](config, { strict, pages, commsRoot, commsCandidates, ...where });
+    if ("couldNotJudge" in r) {
+        console.error(`wiki-${cmd} COULD NOT JUDGE (exit 2): ${r.couldNotJudge}`);
+        return 2;
+    }
+    for (const f of r.judged)
+        console.log(`${f.severity === "fail" ? "FAIL" : "WARN"} ${f.page}${f.line ? `:${f.line}` : ""}: ${f.message}`);
+    if (flags.has("--report"))
+        for (const line of coverageTable(r.report))
+            console.log(line);
+    else
+        for (const row of r.report)
+            console.log(`report: ${row.source} cited ${row.cited} / ${row.size}`);
+    console.log(r.line);
+    return r.exit;
+}
+function runStamp(config, cli, pages, where) {
+    const ready = prepared(config, where);
+    if ("couldNotJudge" in ready) {
+        console.error(`wiki-stamp COULD NOT JUDGE (exit 2): ${ready.couldNotJudge}`);
+        return 2;
+    }
+    const { tree, repo, notes } = ready;
+    const listed = pages.length === 0 ? tree.wikiPageFiles() : pages;
+    const notFiles = listed.filter((p) => !isFile(join(config.root, p)));
+    if (listed.length === 0 || notFiles.length > 0) {
+        console.error(`wiki-stamp COULD NOT JUDGE (exit 2): ${listed.length === 0 ? `no page under ${tree.wikiDir}` : `not a page file: ${notFiles.join(", ")}`}`);
+        return 2;
+    }
+    if (pages.length === 0) {
+        console.error("wiki-stamp: name the page(s) to stamp — a stamp re-vouches sentences somebody re-read, never the whole wiki at once");
+        return 2;
+    }
+    try {
+        if (cli.headCommit === undefined)
+            throw new Error("the command line names no head commit for a stamp to vouch for");
+        const commit = cli.headCommit();
+        let refused = 0;
+        for (const rel of pages) {
+            const r = stampPage(tree, rel, tree.read(rel), { commit });
+            if ("refused" in r) {
+                refused++;
+                for (const f of r.refused)
+                    console.error(`REFUSED ${f.page}:${f.line}: ${f.message}`);
+                continue;
+            }
+            writeFileSync(join(config.root, rel), r.text);
+            console.log(`stamped ${rel}: ${r.anchors} anchor line(s), verified ${repo.name}@${repo.version} ${commit}${notes.map((n) => ` · ${n}`).join("")}`);
+        }
+        return refused > 0 ? 1 : 0;
+    }
+    catch (e) {
+        console.error(`wiki-stamp COULD NOT JUDGE (exit 2): ${e.message}`);
+        return 2;
+    }
+}

package/dist/source.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The by-name readers of TypeScript source: a declaration, a pinned test, a literal table, a literal-key catalog. Each
+ * reads through the tree's file access ({@link TreeFiles}), so a page checked against a changed source (an override)
+ * reads the changed text.
+ */
+import ts from "typescript";
+/** The file access every reader goes through: repository-relative paths, overrides first. */
+export interface TreeFiles {
+    /** The repository root the paths are relative to. */
+    readonly root: string;
+    exists(rel: string): boolean;
+    read(rel: string): string;
+    sourceFile(rel: string): ts.SourceFile;
+}
+/** What a ref resolves to: the text its digest is taken of, and where it stands. */
+export interface Resolved {
+    readonly text: string;
+    readonly file?: string;
+    readonly line?: number;
+}
+/** A ref that is malformed, or names something that is not evidence. */
+export interface Unresolvable {
+    readonly error: string;
+}
+export declare function lineOf(sf: ts.SourceFile, node: ts.Node): number;
+/** A property or member name as written, quoted or not (`key` and `"key"` name the same thing); undefined when computed. */
+export declare function propertyNameOf(name: ts.Node | undefined): string | undefined;
+/** A declaration read by name: its text without comments, its first line, its nodes, its source file. */
+export interface DeclarationReading {
+    readonly text: string;
+    readonly line: number;
+    readonly nodes: readonly ts.Node[];
+    readonly sf: ts.SourceFile;
+}
+/**
+ * The declaration `path` (`Name` or `Name.member…`) of a source file, found by name — never by line — and printed with
+ * every comment removed: a declaration's JSDoc, and its members', is not evidence. All declarations of the name are
+ * read (overloads, a merged interface). Undefined when the name is not declared at the top level.
+ */
+export declare function declarationOf(tree: Pick<TreeFiles, "sourceFile">, rel: string, path: string): DeclarationReading | undefined;
+/**
+ * The one test whose title contains `fragment`, its suite path, and its call printed without comments. A fragment that
+ * names no test is undefined; one that names more than one, or a test that a `skip` / `todo` / `fails` / conditional on
+ * itself or any enclosing suite may keep from running, is an error.
+ */
+export declare function pinOf(tree: Pick<TreeFiles, "exists" | "sourceFile">, rel: string, fragment: string): Resolved | Unresolvable | undefined;
+/** How a repository unwraps a table's initializer (`as const`, `satisfies`, `Object.freeze(…)`) to the literal under it. */
+export type InitializerUnwrap = (initializer: ts.Expression) => {
+    init: ts.Expression | undefined;
+};
+/** A reader of a top-level `const` object table: string keys to string values. */
+export type TableValuesReader = (files: TreeFiles, rel: string, table: string) => Record<string, string>;
+/**
+ * The table reader over a repository's own unwrap rule: a top-level `const` object table read literally, string keys to
+ * string values. Anything not literal throws.
+ */
+export declare function literalTableReader(unwrap: InitializerUnwrap): TableValuesReader;
+/** One knob of a configuration catalog, as the coverage gate and the generators read it. */
+export interface CatalogKnob {
+    readonly key: string;
+    readonly kind: string | undefined;
+    readonly unit: string | undefined;
+    readonly recommended: string;
+    readonly precedence: string | undefined;
+    /** The knob's object literal printed without comments: what a `catalog:` ref's digest is taken of. */
+    readonly text: string;
+    readonly line: number;
+}
+/** A repository's configuration catalog: the file it is declared in, and its knobs read from the tree. */
+export interface CatalogReader {
+    readonly file: string;
+    knobs(files: TreeFiles): CatalogKnob[];
+}
+/**
+ * The catalog reader for a catalog written as object literals: every object literal under `declaration` in `file` that
+ * carries a literal `key` is one knob, read literally. A key not written as a literal, and a catalog with no such knob,
+ * throw.
+ */
+export declare function literalKeyCatalog({ file, declaration }: {
+    readonly file: string;
+    readonly declaration: string;
+}): CatalogReader;