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

package/dist/check.js

@@ -0,0 +1,378 @@
+import { createHash } from "node:crypto";
+import { GEN_CLOSE, claimBlocks, correctionLineOf, inlineGensOf, markersOf, sectionIdOf, splitPage } from "./page.js";
+import { coversKeysOf, releaseDistanceOf, repoOf, resolveRef } from "./tree.js";
+import { compareVersions, parseRun, uAgeFinding, vAgeFinding } from "./versions.js";
+import { GENRES, LEVELS, genreRow } from "./genre.js";
+import { parseCritKey } from "./acceptance.js";
+import { knobTableProblems } from "./knobs.js";
+export const PAGE_KINDS = Object.freeze(["concept", "reference", "howto", "upgrade"]);
+export const OWNER_REPOS = Object.freeze(["core", "server", "cli", "client-core"]);
+const PAGE_ID_PREFIXES = Object.freeze([...OWNER_REPOS, ...Object.keys(GENRES)]);
+const PAGE_ID = new RegExp(`^(?:${PAGE_ID_PREFIXES.join("|")})/[a-z0-9][a-z0-9./-]*$`);
+const RECOMPUTED_KINDS = Object.freeze(["export", "set", "contract", "src", "catalog"]);
+export const FRONTMATTER_KEYS = Object.freeze({
+    title: "one",
+    "page-id": "one",
+    audience: "many",
+    kind: "one",
+    "owner-repo": "one",
+    secondary: "one",
+    stable: "one",
+    feats: "many",
+    verified: "one",
+    anchor: "many",
+    falsified: "many",
+});
+const REQUIRED_KEYS = Object.freeze(["title", "page-id", "audience", "kind", "owner-repo", "stable", "feats", "verified"]);
+export function publicnessBans(workItemName, extra = []) {
+    return Object.freeze([
+        ...(workItemName === undefined ? [] : [["an internal work-item name", new RegExp(`(?<![A-Za-z0-9-])${workItemName.source}`, workItemName.flags.replace(/[gy]/g, ""))]]),
+        ["a board post number", /\[\d{4,5}\]/],
+        ["a ruling number", /\bC-R\d+/],
+        ["a neighbour repository's ticket", /\b(?:S|L|CC)-\d+\b/],
+        ["a defect-record number", /\bB-\d+\b/],
+        ["a ticket number in prose", /(?<![\w&])#\d{3,}\b/],
+        ["a design-record number", /\bdesign\/\d+/],
+        ["a decoded reference bundle", /\bcli\d{3}\.js\b/],
+        ["an internal repository's name", /(?<![\w@/-])sema-(?:internal|comms)(?:-[a-z]+)?\b/],
+        ["a review tool's name", /\bcodex\b/i],
+        ["a review round", /\bround \d+\b/i],
+        ["an internal narrative word", /裁定|帖|看板|派车/],
+        ...extra.map(([what, rx]) => [what, new RegExp(rx.source, rx.flags.replace(/[gy]/g, ""))]),
+    ]);
+}
+const sha = (s) => "sha256:" + createHash("sha256").update(s).digest("hex").slice(0, 16);
+const genKey = (g) => `gen:${g.name}${g.args.length ? ` ${g.args.join(" ")}` : ""}`;
+export const generatorOf = (tree, name) => (Object.hasOwn(tree.generators, name) ? tree.generators[name] : undefined);
+export function generate(gen, args) {
+    const g = gen.render(...args);
+    if (g === null || typeof g !== "object" || typeof g.text !== "string" || !Array.isArray(g.refs) || g.refs.some((r) => typeof r !== "string")) {
+        throw new Error("a generator answers `{ text, refs }` (a string and an array of refs)");
+    }
+    return g;
+}
+export function checkPage(tree, rel, text, { stamp = false } = {}) {
+    const findings = [];
+    const repo = repoOf(tree);
+    const row = genreRow(tree.genre);
+    const { fm, body, bodyLine, fmLines } = splitPage(text);
+    const at = (gate, line, message, fixed) => {
+        findings.push({ gate, page: rel, line, message, ...(fixed ? { fixed } : {}) });
+    };
+    if (fm === null) {
+        at("anchors", 1, "the page has no frontmatter (`---` … `---`)");
+        return { findings, digests: {}, coords: {}, levels: {} };
+    }
+    const fileLine = (bodyRelative) => bodyLine + bodyRelative - 1;
+    for (const l of fmLines) {
+        if (l.key === undefined) {
+            if (l.raw.trim() !== "")
+                at("anchors", l.line, `a frontmatter line that is not \`key: value\`: ${JSON.stringify(l.raw.slice(0, 60))}`);
+            continue;
+        }
+        if (!Object.hasOwn(FRONTMATTER_KEYS, l.key))
+            at("anchors", l.line, `unknown frontmatter key \`${l.key}\` (the keys are ${Object.keys(FRONTMATTER_KEYS).join(", ")})`);
+    }
+    for (const [k, card] of Object.entries(FRONTMATTER_KEYS))
+        if (card === "one" && (fm._list[k]?.length ?? 0) > 1)
+            at("anchors", 1, `\`${k}\` is given ${fm._list[k].length} times; it is one value`);
+    for (const k of REQUIRED_KEYS)
+        if (fm[k] === undefined || fm[k] === "")
+            at("anchors", 1, `frontmatter lacks \`${k}\``);
+    for (const a of fm._list.audience ?? [])
+        if (!row.audiences.includes(a))
+            at("anchors", 1, `audience \`${a}\` is not one of ${row.audiences.join(", ")}`);
+    if (fm.kind !== undefined && !PAGE_KINDS.includes(fm.kind))
+        at("anchors", 1, `kind \`${fm.kind}\` is not one of ${PAGE_KINDS.join(", ")}`);
+    const owner = fm["owner-repo"];
+    if (owner !== undefined) {
+        if (!OWNER_REPOS.includes(owner))
+            at("anchors", 1, `owner-repo \`${owner}\` is not one of ${OWNER_REPOS.join(", ")}`);
+        else if (owner !== repo.word)
+            at("anchors", 1, `owner-repo \`${owner}\` is not this repository (${repo.word}): a page's refs resolve in its owner's tree, and a page lives in that tree`);
+    }
+    if (fm.stable !== undefined && fm.stable !== "true" && fm.stable !== "false")
+        at("anchors", 1, `stable must be true or false, got \`${fm.stable}\``);
+    if (fm["page-id"] !== undefined && !PAGE_ID.test(fm["page-id"]))
+        at("anchors", 1, `page-id \`${fm["page-id"]}\` must read <${PAGE_ID_PREFIXES.join("|")}>/<path>`);
+    const feats = fm._list.feats ?? [];
+    for (const f of feats)
+        if (f !== "none" && !/^F-\d{3}$/.test(f))
+            at("anchors", 1, `feats \`${f}\` is not F-<nnn> or none`);
+    if (feats.includes("none") && feats.length > 1)
+        at("anchors", 1, "feats names `none` and a feature row: one or the other");
+    if (fm.verified !== undefined) {
+        const vm = /^(@?[a-z0-9][a-z0-9./_-]*)@(\d+\.\d+\.\d+) ([0-9a-f]{7,40})$/.exec(fm.verified);
+        if (!vm)
+            at("anchors", 1, "verified must read `<package>@<X.Y.Z> <commit sha>`");
+        else if (vm[1] !== repo.name)
+            at("anchors", 1, `verified names ${vm[1]}, not this repository's package ${repo.name}`);
+        else if (compareVersions(vm[2], repo.version) > 0)
+            at("anchors", 1, `verified names ${vm[2]}, a version this tree (${repo.version}) has not reached`);
+    }
+    const falsified = [];
+    for (const f of fm._list.falsified ?? []) {
+        const fmm = /^(W-\d+) (\S+) \d{4}-\d{2}-\d{2}$/.exec(f);
+        if (!fmm)
+            at("anchors", 1, `falsified must read \`W-<n> <section-id> <YYYY-MM-DD>\`, got ${JSON.stringify(f)}`);
+        else
+            falsified.push({ id: fmm[1], section: fmm[2] });
+    }
+    const stamped = Object.create(null);
+    for (const v of fm._list.anchor ?? []) {
+        const am = /^(.+) (sha256:[0-9a-f]{16})$/.exec(v);
+        if (am)
+            stamped[am[1]] = am[2];
+        else
+            at("anchors", 1, `anchor must read \`<ref> sha256:<16 hex>\`, got ${JSON.stringify(v.slice(0, 60))}`);
+    }
+    const stable = fm.stable === "true";
+    const { blocks, gens, fences, units, headings, problems } = claimBlocks(body);
+    for (const p of problems)
+        at("anchors", fileLine(p.line), p.message);
+    const refs = new Map();
+    const cite = (r, line) => {
+        refs.set(r, [...(refs.get(r) ?? []), line]);
+    };
+    const levels = Object.fromEntries(LEVELS.map((l) => [l, 0]));
+    const judgeMarker = (line, mk, hasGen) => {
+        levels[mk.level]++;
+        if (!row.levels.includes(mk.level)) {
+            at("anchors", line, `level \`${mk.level}\` is not a level of the ${tree.genre} genre (its levels are ${row.levels.join(", ")})`);
+            return;
+        }
+        if (mk.level === "I" && stable)
+            at("anchors", line, "an `I` sentence on a stable page");
+        if (mk.level === "G" && !hasGen && !mk.refs.some((r) => RECOMPUTED_KINDS.includes(r.split(":")[0])))
+            at("anchors", line, `a \`G\` marker cites none of ${RECOMPUTED_KINDS.join(" / ")}`);
+        if (mk.level === "P" && !mk.refs.some((r) => r.startsWith("pin:")))
+            at("anchors", line, "a `P` marker cites no `pin:`");
+        if (mk.level === "V" && !mk.refs.some((r) => r.startsWith("run:")))
+            at("anchors", line, "a `V` marker cites no `run:`");
+        const crits = mk.refs.filter((r) => r.startsWith("crit:")).length;
+        if (mk.level === "U" && crits !== 1)
+            at("anchors", line, `a \`U\` marker cites exactly one \`crit:\` ref, this one cites ${crits}`);
+        if (mk.level !== "U" && crits > 0)
+            at("anchors", line, `a \`crit:\` ref is a \`U\` marker's evidence, not a \`${mk.level}\` marker's`);
+        for (const r of mk.refs)
+            cite(r, line);
+    };
+    const sectionAt = (bodyRelative) => {
+        const h = headings.filter((x) => x.line < bodyRelative).at(-1);
+        return h === undefined ? undefined : sectionIdOf(h.text);
+    };
+    const correctionLines = [];
+    for (const b of blocks) {
+        const line = fileLine(b.line);
+        const { stripped, markers } = markersOf(b.text);
+        const correction = correctionLineOf(b.text);
+        if (correction)
+            correctionLines.push({ id: correction.correction, section: sectionAt(b.line), line });
+        if (markers.length === 0) {
+            at("anchors", line, `a claim block with no marker: ${JSON.stringify(b.text.slice(0, 70))}`);
+            continue;
+        }
+        const last = markers[markers.length - 1];
+        const tail = stripped.slice(last.index + last.length).replace(/\|?\s*$/, "").trim();
+        if (tail.length > 0)
+            at("anchors", line, `text after the last marker is vouched by nothing: ${JSON.stringify(b.text.slice(last.index + last.length).trim().slice(0, 60))}`);
+        const uMarkers = markers.filter((mk) => mk.level === "U").length;
+        if (uMarkers > 1)
+            at("anchors", line, `a claim block holds at most one \`U\` marker, this one holds ${uMarkers}`);
+        const hasGen = inlineGensOf(b.text).length > 0;
+        for (const mk of markers)
+            judgeMarker(line, mk, hasGen);
+    }
+    for (const f of fences) {
+        const line = fileLine(f.line);
+        if (f.unclosed)
+            at("anchors", line, "a code fence that never closes");
+        const { markers } = markersOf(f.info);
+        if (markers.length === 0)
+            at("anchors", line, "a code fence with no marker in its info string");
+        for (const mk of markers)
+            judgeMarker(line, mk, false);
+    }
+    const generated = new Map();
+    const coversKeys = coversKeysOf(tree.config);
+    for (const g of gens) {
+        const line = fileLine(g.line);
+        const gen = generatorOf(tree, g.name);
+        if (!gen) {
+            at("anchors", line, `unknown generator \`${g.name}\` (the generators are ${Object.keys(tree.generators).join(", ")})`);
+            continue;
+        }
+        if (!g.closed) {
+            at("anchors", line, `the generated region \`${g.name}\` never closes`);
+            continue;
+        }
+        let fresh;
+        try {
+            fresh = generate(gen, g.args);
+        }
+        catch (e) {
+            at("anchors", line, `the generator \`${g.name}\` cannot read its source: ${e.message}`);
+            continue;
+        }
+        generated.set(g, fresh);
+        if (markersOf(fresh.text).markers.length > 0)
+            at("anchors", line, `the generated region \`${g.name}\` spells a marker: a generator hands its evidence over as refs, never as marker text`);
+        if (/<!--|-->/.test(fresh.text))
+            at("anchors", line, `the generated region \`${g.name}\` spells a comment delimiter: its text cannot be told from its fences`);
+        for (const r of fresh.refs)
+            cite(r, line);
+        if (gen.covers) {
+            try {
+                for (const k of Object.keys(gen.covers(...g.args)))
+                    if (!coversKeys.includes(k))
+                        at("anchors", line, `the generator \`${g.name}\` covers \`${k}\`, the covers key of no source this repository declares (${coversKeys.join(", ") || "none"})`);
+            }
+            catch (e) {
+                at("anchors", line, `the generator \`${g.name}\` cannot say what it covers: ${e.message}`);
+            }
+        }
+        if (gen.rowFields) {
+            try {
+                const fields = gen.rowFields(...g.args);
+                if (!Array.isArray(fields) || fields.some((f) => typeof f !== "string"))
+                    throw new Error("it answers an array of knob field ids");
+                for (const p of knobTableProblems(g.name, fields, fresh.text))
+                    at("anchors", line, p);
+            }
+            catch (e) {
+                at("anchors", line, `the generator \`${g.name}\` cannot say which knob fields it renders: ${e.message}`);
+            }
+        }
+    }
+    const bans = publicnessBans(tree.config.readers?.workItemName, tree.config.bans);
+    const scan = (raw, line, where) => {
+        const textOf = raw.replace(/pin:[^\s#"]+#/g, "pin:#");
+        for (const [what, rx] of bans) {
+            const hit = rx.exec(textOf);
+            if (hit)
+                at("anchors", line, `${what} in ${where} (${JSON.stringify(hit[0])}): the published pages carry no identifier of the internal record`);
+        }
+    };
+    [`title: ${fm.title ?? ""}`, ...body.split("\n")].forEach((raw, i) => scan(raw, i === 0 ? 1 : fileLine(i), "the page text"));
+    for (const [g, fresh] of generated)
+        for (const r of fresh.refs)
+            scan(r, fileLine(g.line), `a ref the generated region \`${g.name}\` hands over`);
+    if (tree.correctionsDeclared) {
+        const records = tree.corrections() ?? [];
+        const pageId = fm["page-id"];
+        const held = new Map(records.map((r) => [r.id, r]));
+        for (const r of records) {
+            if (r.repo !== repo.word || r.pageId !== pageId)
+                continue;
+            if (r.status === "open") {
+                at("anchors", 1, `correction ${r.id} is open against this page (section \`${r.section}\`): the page fails until the correction is closed`, "fail");
+                continue;
+            }
+            if (!falsified.some((f) => f.id === r.id))
+                at("anchors", 1, `correction ${r.id} is closed and the page carries no \`falsified: ${r.id} ${r.section} <date>\` line`);
+            if (!correctionLines.some((c) => c.id === r.id && c.section === r.section))
+                at("anchors", 1, `correction ${r.id} is closed and no correction line under section \`${r.section}\` names it`);
+        }
+        for (const f of falsified) {
+            const r = held.get(f.id);
+            if (r === undefined)
+                at("anchors", 1, `falsified names ${f.id}, which the correction record does not hold`);
+            else if (r.repo !== repo.word || r.pageId !== pageId)
+                at("anchors", 1, `falsified names ${f.id}, a correction of ${r.repo} ${r.pageId}, not of this page`);
+            else if (r.section !== f.section)
+                at("anchors", 1, `falsified names ${f.id} under section \`${f.section}\`; the record names \`${r.section}\``);
+        }
+        for (const c of correctionLines) {
+            const r = held.get(c.id);
+            if (r === undefined)
+                at("anchors", c.line, `a correction line names ${c.id}, which the correction record does not hold`);
+            else if (r.repo !== repo.word || r.pageId !== pageId)
+                at("anchors", c.line, `a correction line names ${c.id}, a correction of ${r.repo} ${r.pageId}, not of this page`);
+        }
+    }
+    const digests = { text: sha(units.map((u) => `${u.kind}:${u.text}`).join("\n\n")) };
+    const coords = {};
+    for (const [ref, lines] of refs) {
+        const r = resolveRef(tree, ref);
+        if (r === undefined) {
+            at("anchors", lines[0], `\`${ref}\` does not resolve in this tree`);
+            continue;
+        }
+        if ("error" in r) {
+            at("anchors", lines[0], r.error, "fixed" in r ? r.fixed : undefined);
+            continue;
+        }
+        if (ref.startsWith("run:")) {
+            const age = vAgeFinding(parseRun(ref.slice(4)), repo);
+            if (age)
+                at("freshness", lines[0], age.message, age.fixed);
+            continue;
+        }
+        if (ref.startsWith("crit:")) {
+            const age = uAgeFinding(parseCritKey(ref.slice(5)).version, repo, releaseDistanceOf(tree));
+            if (age)
+                at("freshness", lines[0], age.message, age.fixed);
+        }
+        digests[ref] = sha(r.text);
+        if (r.file && r.line)
+            coords[ref] = `${r.file}:${r.line}`;
+    }
+    for (const [g, fresh] of generated) {
+        digests[genKey(g)] = sha(fresh.text);
+        if (!stamp && fresh.text !== g.content)
+            at("freshness", fileLine(g.line), `the generated region \`${genKey(g).slice(4)}\` differs from a fresh generation (the source moved, or the region was edited by hand)`);
+    }
+    if (!stamp) {
+        for (const [k, d] of Object.entries(digests)) {
+            if (!(k in stamped))
+                at("freshness", 1, `\`${k}\` has no stamped digest (the page changed after its stamp)`);
+            else if (stamped[k] !== d)
+                at("freshness", 1, `\`${k}\` changed since the stamp (${stamped[k]} → ${d})${k === "text" ? ": the page's own text was edited without a new stamp" : ""}`);
+        }
+        for (const k of Object.keys(stamped))
+            if (!(k in digests))
+                at("freshness", 1, `\`${k}\` is stamped but no longer cited`);
+    }
+    return { findings, digests, coords, levels };
+}
+export function regenerate(tree, text) {
+    const { body } = splitPage(text);
+    const bodyAt = text.length - body.length;
+    let out = text;
+    const gens = claimBlocks(body)
+        .gens.filter((g) => g.closed)
+        .sort((a, b) => b.span[0] - a.span[0]);
+    for (const g of gens) {
+        const gen = generatorOf(tree, g.name);
+        if (!gen)
+            continue;
+        let fresh;
+        try {
+            fresh = generate(gen, g.args).text;
+        }
+        catch {
+            continue;
+        }
+        const [from, to] = [bodyAt + g.span[0], bodyAt + g.span[1]];
+        const region = out.slice(from, to);
+        const open = region.slice(0, region.indexOf("-->") + 3);
+        out = out.slice(0, from) + (g.inline ? `${open}${fresh}${GEN_CLOSE}` : `${open}\n${fresh}\n${GEN_CLOSE}`) + out.slice(to);
+    }
+    return out;
+}
+export function stampPage(tree, rel, text, { commit }) {
+    const fresh = regenerate(tree, text);
+    const r = checkPage(tree, rel, fresh, { stamp: true });
+    const anchorsFindings = r.findings.filter((f) => f.gate === "anchors");
+    if (anchorsFindings.length > 0)
+        return { refused: anchorsFindings };
+    const repo = repoOf(tree);
+    const end = fresh.indexOf("\n---\n", 4);
+    const head = fresh
+        .slice(0, end)
+        .split("\n")
+        .filter((l) => !l.startsWith("anchor: "))
+        .map((l) => (l.startsWith("verified: ") ? `verified: ${repo.name}@${repo.version} ${commit}` : l));
+    const anchorLines = Object.entries(r.digests).map(([k, d]) => `anchor: ${k} ${d}`);
+    return { text: [...head, ...anchorLines].join("\n") + fresh.slice(end), anchors: anchorLines.length };
+}

package/dist/corrections.d.ts

@@ -0,0 +1,29 @@
+/** Where a correction-record checkout holds its records. */
+export declare const CORRECTIONS_DIR = "corrections";
+/** The name a repository declares the correction record under among its required sources. */
+export declare const CORRECTION_RECORD = "correction record";
+/** One correction: the page it names (repository word and page-id), the section, its state and dates. */
+export interface CorrectionRecord {
+    readonly id: string;
+    readonly repo: string;
+    readonly pageId: string;
+    readonly section: string;
+    readonly status: "open" | "closed";
+    readonly opened: string;
+    readonly closed?: string;
+    readonly file: string;
+}
+/**
+ * A record file read: its frontmatter holds `id` (the file's own `W-<n>`), `repo`, `page-id`, `section`, `status`
+ * (`open` or `closed`), `opened`, and `closed` exactly when the status is closed. A record that does not read this way
+ * throws: a gate never guesses a correction's state.
+ */
+export declare function parseCorrectionRecord(file: string, text: string): CorrectionRecord;
+/** How the records are read from a checkout named on the command line: undefined when none is named or it holds no record directory. */
+export type CorrectionRecordReader = (correctionsRoot: string | undefined) => readonly CorrectionRecord[] | undefined;
+/** The reader over `<checkout>/corrections/W-<n>.md`: a present, empty directory is a record with no correction. */
+export declare const correctionRecordAt: CorrectionRecordReader;
+/** The correction record as a required source: the repository names its reader. */
+export interface CorrectionRecordSource {
+    readonly records: CorrectionRecordReader;
+}

package/dist/corrections.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { splitPage } from "./page.js";
+export const CORRECTIONS_DIR = "corrections";
+export const CORRECTION_RECORD = "correction record";
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+export function parseCorrectionRecord(file, text) {
+    const { fm } = splitPage(text);
+    if (fm === null)
+        throw new Error(`${file}: a correction record has no frontmatter`);
+    const want = /(W-\d+)\.md$/.exec(file)?.[1];
+    const get = (k) => {
+        const v = fm[k];
+        if (typeof v !== "string" || v === "")
+            throw new Error(`${file}: a correction record lacks \`${k}\``);
+        return v;
+    };
+    const id = get("id");
+    if (id !== want)
+        throw new Error(`${file}: id \`${id}\` is not the file's own ${want ?? "W-<n>"}`);
+    const status = get("status");
+    if (status !== "open" && status !== "closed")
+        throw new Error(`${file}: status \`${status}\` is not open or closed`);
+    const opened = get("opened");
+    if (!DATE.test(opened))
+        throw new Error(`${file}: opened \`${opened}\` is not YYYY-MM-DD`);
+    const closed = fm.closed;
+    if (status === "closed" && (closed === undefined || !DATE.test(closed)))
+        throw new Error(`${file}: a closed correction names no \`closed: YYYY-MM-DD\``);
+    if (status === "open" && closed !== undefined)
+        throw new Error(`${file}: an open correction names a \`closed:\` date`);
+    return { id, repo: get("repo"), pageId: get("page-id"), section: get("section"), status, opened, ...(closed === undefined ? {} : { closed }), file };
+}
+export const correctionRecordAt = (correctionsRoot) => {
+    if (correctionsRoot === undefined)
+        return undefined;
+    const dir = join(correctionsRoot, CORRECTIONS_DIR);
+    if (!existsSync(dir))
+        return undefined;
+    return readdirSync(dir)
+        .filter((f) => /^W-\d+\.md$/.test(f))
+        .sort()
+        .map((f) => parseCorrectionRecord(`${CORRECTIONS_DIR}/${f}`, readFileSync(join(dir, f), "utf8")));
+};

package/dist/coverage.d.ts

@@ -0,0 +1,91 @@
+import { type Finding } from "./check.js";
+import { type CoverageSource, type WikiTree } from "./tree.js";
+/** Feature-row statuses that put a row in the required coverage set (`verified` is a shipped row after its acceptance run). */
+export declare const COVERED_FEAT_STATUSES: readonly string[];
+/** The feature rows a comms checkout holds, or why there are none to read. */
+export type FeatRows = {
+    readonly rows: ReadonlyArray<{
+        id: string;
+        status: string;
+    }>;
+} | {
+    readonly absent: readonly string[];
+} | {
+    readonly error: string;
+};
+/**
+ * The feature rows of the comms checkout, with their status for this repository. `commsRoot` names the checkout;
+ * otherwise the first of `candidates` that exists is read. `{ absent }` = no comms checkout at all (a release clone,
+ * a remote gate host); `{ error }` = a checkout without its rows.
+ */
+export declare function readFeatRows(repoWord: string, { commsRoot, candidates }?: {
+    commsRoot?: string;
+    candidates?: readonly string[];
+}): FeatRows;
+/** The root exports of the frozen export surface; a page cites one by `export:`, a region covers them under `exports`. */
+export declare function rootExportsSource(): CoverageSource;
+/** The root exports of the stable tier, cited and covered as the root exports are. */
+export declare function stableRootExportsSource(): CoverageSource;
+/** The live rows of the closed-set registry; cited by `set:`, covered under `sets`. */
+export declare function liveClosedSetsSource(): CoverageSource;
+/** The contract sentences of the registry; cited by `contract:`. */
+export declare function contractSentencesSource(): CoverageSource;
+/**
+ * The configuration catalog's keys. A `catalog:` ref vouches for one sentence about a knob; only a generated region
+ * renders the knob, so only a region (under `configKeys`) covers one.
+ */
+export declare function configurationKeysSource(): CoverageSource;
+/** One row of the coverage report: a source, how many of its items some page cites, and its size. */
+export interface CoverageReportRow {
+    readonly source: string;
+    readonly cited: number;
+    readonly size: number;
+}
+/**
+ * What the pages of a tree cite: the feature rows on their `feats:`, the ids cited through a ref of each kind (a
+ * marked sentence's `export:` / `set:` / `contract:` ref, and the refs a generated region hands over), and the ids a
+ * generated region renders in full under each `covers` key.
+ */
+export interface CitedByPages {
+    readonly feats: ReadonlySet<string>;
+    /** The ids cited through a ref of this kind. */
+    refs(kind: string): ReadonlySet<string>;
+    /** The ids a generated region covers under this key. */
+    covers(key: string): ReadonlySet<string>;
+    /** Whether `id` is cited for this source: by a ref of its kind, or covered under its key. */
+    isCited(source: Pick<CoverageSource, "refKind" | "coversKey">, id: string): boolean;
+}
+/**
+ * What the given pages cite — the one reading of "cited" every consumer shares: the coverage gate below counts its
+ * required and reported sources from it, and a repository's release tooling asks it whether a name a release moved is
+ * on a page. A page cites an item through a ref on a marked sentence, and a generated region covers what its generator
+ * says it renders in full (`covers`, never counted from the rendered text) and hands over the refs it renders. A source
+ * with no ref kind (the configuration keys) is covered only by a region. A region whose generator cannot read its
+ * source covers nothing (the anchors gate names it).
+ */
+export declare function citedByPages(tree: WikiTree, pages: ReadonlyArray<{
+    rel: string;
+    text: string;
+}>): CitedByPages;
+/** One required source as this run judged it: covered of size, or why it could not be read. */
+export interface RequiredSummaryRow {
+    readonly source: string;
+    readonly covered: number;
+    readonly size: number;
+    readonly unread?: string;
+}
+/**
+ * The coverage gate's judgment over parsed pages. Required (one finding per gap): the genre's own sources — for the
+ * wiki, every feature row shipped or verified for this repository is on some page's `feats:` — and every source the
+ * repository declares required. Reported only: the sources the repository declares reported, counted.
+ */
+export declare function coverageFindings(tree: WikiTree, pages: ReadonlyArray<{
+    rel: string;
+    text: string;
+}>, feats: FeatRows): {
+    findings: Finding[];
+    report: CoverageReportRow[];
+    required: RequiredSummaryRow[];
+};
+/** The required sources in one sentence: each with its coverage, so a requirement never disappears from the verdict. */
+export declare function requiredSummaryOf(rows: readonly RequiredSummaryRow[]): string;