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

package/dist/source.js

@@ -0,0 +1,193 @@
+import ts from "typescript";
+export function lineOf(sf, node) {
+    return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+}
+export function propertyNameOf(name) {
+    return name && (ts.isIdentifier(name) || ts.isStringLiteral(name)) ? name.text : undefined;
+}
+function membersOfDeclaration(node) {
+    if (ts.isInterfaceDeclaration(node) || ts.isClassDeclaration(node) || ts.isEnumDeclaration(node))
+        return node.members;
+    if (ts.isTypeAliasDeclaration(node) && ts.isTypeLiteralNode(node.type))
+        return node.type.members;
+    return [];
+}
+export function declarationOf(tree, rel, path) {
+    const sf = tree.sourceFile(rel);
+    const [head, ...rest] = path.split(".");
+    let found = [];
+    for (const st of sf.statements) {
+        if (ts.isVariableStatement(st)) {
+            if (st.declarationList.declarations.some((d) => ts.isIdentifier(d.name) && d.name.text === head))
+                found.push(st);
+            continue;
+        }
+        const named = ts.isFunctionDeclaration(st) || ts.isInterfaceDeclaration(st) || ts.isTypeAliasDeclaration(st) || ts.isClassDeclaration(st) || ts.isEnumDeclaration(st);
+        if (named && st.name?.text === head)
+            found.push(st);
+    }
+    for (const member of rest) {
+        const next = [];
+        for (const node of found)
+            for (const m of membersOfDeclaration(node))
+                if (propertyNameOf(m.name) === member)
+                    next.push(m);
+        found = next;
+    }
+    if (found.length === 0)
+        return undefined;
+    const printer = ts.createPrinter({ removeComments: true });
+    return { text: found.map((n) => printer.printNode(ts.EmitHint.Unspecified, n, sf)).join("\n"), line: lineOf(sf, found[0]), nodes: found, sf };
+}
+function runnerCallee(expr, sf) {
+    const plain = /^(describe|suite|it|test)((?:\.[A-Za-z]+)*)$/;
+    if (ts.isCallExpression(expr)) {
+        const inner = plain.exec(expr.expression.getText(sf));
+        if (!inner)
+            return undefined;
+        const mods = inner[2].split(".").filter(Boolean);
+        if (!["skipIf", "runIf", "each", "for"].includes(mods.at(-1) ?? ""))
+            return undefined;
+        return { head: inner[1], mods };
+    }
+    const m = plain.exec(expr.getText(sf));
+    if (!m)
+        return undefined;
+    const mods = m[2].split(".").filter(Boolean);
+    if (mods.includes("each") || mods.includes("for"))
+        return undefined;
+    return { head: m[1], mods };
+}
+const VOIDING_MODIFIERS = Object.freeze(["skip", "todo", "fails", "skipIf", "runIf"]);
+function optionModifiers(call) {
+    const out = [];
+    for (const a of call.arguments.slice(1)) {
+        if (!ts.isObjectLiteralExpression(a))
+            continue;
+        for (const p of a.properties) {
+            if (ts.isSpreadAssignment(p))
+                out.push("…spread");
+            const name = ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p) ? propertyNameOf(p.name) : undefined;
+            if (name === undefined || !VOIDING_MODIFIERS.includes(name))
+                continue;
+            if (ts.isPropertyAssignment(p) && p.initializer.kind === ts.SyntaxKind.FalseKeyword)
+                continue;
+            out.push(name);
+        }
+    }
+    return out;
+}
+export function pinOf(tree, rel, fragment) {
+    if (!tree.exists(rel))
+        return undefined;
+    const sf = tree.sourceFile(rel);
+    const hits = [];
+    const visit = (n, chain) => {
+        if (ts.isCallExpression(n)) {
+            const callee = runnerCallee(n.expression, sf);
+            const a = n.arguments[0];
+            const title = a && (ts.isStringLiteral(a) || ts.isNoSubstitutionTemplateLiteral(a)) ? a.text : null;
+            if (callee && title !== null) {
+                const voids = [...callee.mods.filter((m) => VOIDING_MODIFIERS.includes(m)), ...optionModifiers(n)];
+                const step = { label: `${callee.head}${callee.mods.map((m) => `.${m}`).join("")}(${JSON.stringify(title)})`, voids };
+                if (callee.head === "it" || callee.head === "test") {
+                    if (title.includes(fragment))
+                        hits.push({ n, chain: [...chain, step] });
+                    return;
+                }
+                ts.forEachChild(n, (c) => visit(c, [...chain, step]));
+                return;
+            }
+        }
+        ts.forEachChild(n, (c) => visit(c, chain));
+    };
+    visit(sf, []);
+    if (hits.length === 0)
+        return undefined;
+    if (hits.length > 1)
+        return { error: `the title fragment "${fragment}" names ${hits.length} tests in ${rel}; a pin names one` };
+    const { n, chain } = hits[0];
+    const voiding = chain.find((s) => s.voids.length > 0);
+    if (voiding)
+        return { error: `the pinned test may not run, or runs inverted (${voiding.label}: ${voiding.voids.join(", ")})` };
+    const printed = ts.createPrinter({ removeComments: true }).printNode(ts.EmitHint.Unspecified, n, sf);
+    return { text: `${chain.map((s) => s.label).join(" > ")}\n${printed}`, file: rel, line: lineOf(sf, n) };
+}
+export function literalTableReader(unwrap) {
+    return (files, rel, table) => {
+        const sf = files.sourceFile(rel);
+        for (const st of sf.statements) {
+            if (!ts.isVariableStatement(st))
+                continue;
+            for (const d of st.declarationList.declarations) {
+                if (!ts.isIdentifier(d.name) || d.name.text !== table || !d.initializer)
+                    continue;
+                const { init } = unwrap(d.initializer);
+                if (init === undefined || !ts.isObjectLiteralExpression(init))
+                    throw new Error(`${rel}: ${table} is not an object literal`);
+                const out = {};
+                for (const p of init.properties) {
+                    const key = ts.isPropertyAssignment(p) ? propertyNameOf(p.name) : undefined;
+                    if (key === undefined || !ts.isPropertyAssignment(p) || !ts.isStringLiteral(p.initializer))
+                        throw new Error(`${rel}: ${table} has an entry that is not a literal string pair (${p.getText(sf).slice(0, 60)})`);
+                    out[key] = p.initializer.text;
+                }
+                return out;
+            }
+        }
+        throw new Error(`${rel}: no top-level ${table}`);
+    };
+}
+export function literalKeyCatalog({ file, declaration }) {
+    return {
+        file,
+        knobs: (tree) => {
+            if (!tree.exists(file))
+                throw new Error(`the configuration catalog ${file} is not in this tree`);
+            const decl = declarationOf(tree, file, declaration);
+            if (decl === undefined)
+                throw new Error(`${file} declares no ${declaration}`);
+            const { sf } = decl;
+            const knobs = [];
+            const printer = ts.createPrinter({ removeComments: true });
+            const visit = (n) => {
+                if (ts.isObjectLiteralExpression(n)) {
+                    const props = new Map();
+                    for (const p of n.properties) {
+                        const name = ts.isPropertyAssignment(p) ? propertyNameOf(p.name) : undefined;
+                        if (ts.isPropertyAssignment(p) && name !== undefined)
+                            props.set(name, p.initializer);
+                        else if (ts.isShorthandPropertyAssignment(p) && p.name.text === "key")
+                            throw new Error(`${file}: a knob's key is not written as a literal (${p.getText(sf)})`);
+                    }
+                    const key = props.get("key");
+                    if (key !== undefined) {
+                        if (!ts.isStringLiteral(key))
+                            throw new Error(`${file}: a knob's key is not a string literal (${key.getText(sf)})`);
+                        const lit = (k) => {
+                            const v = props.get(k);
+                            return v === undefined ? undefined : ts.isStringLiteral(v) || ts.isNoSubstitutionTemplateLiteral(v) ? v.text : printer.printNode(ts.EmitHint.Unspecified, v, sf);
+                        };
+                        const recommended = props.get("recommended");
+                        knobs.push({
+                            key: key.text,
+                            kind: lit("kind"),
+                            unit: lit("unit"),
+                            recommended: recommended === undefined ? "—" : printer.printNode(ts.EmitHint.Unspecified, recommended, sf),
+                            precedence: lit("precedence"),
+                            text: printer.printNode(ts.EmitHint.Unspecified, n, sf),
+                            line: lineOf(sf, n),
+                        });
+                        return;
+                    }
+                }
+                ts.forEachChild(n, visit);
+            };
+            for (const node of decl.nodes)
+                visit(node);
+            if (knobs.length === 0)
+                throw new Error(`${file}: ${declaration} declares no knob with a literal key`);
+            return knobs;
+        },
+    };
+}

package/dist/tree.d.ts

@@ -0,0 +1,234 @@
+import ts from "typescript";
+import { type CatalogKnob, type CatalogReader, type Resolved, type TableValuesReader, type TreeFiles, type Unresolvable } from "./source.js";
+import { type Frontmatter } from "./page.js";
+import { type ReleaseDistance, type RepoIdentity, type Severity } from "./versions.js";
+import { type Genre, type GenreRow } from "./genre.js";
+import { type AcceptanceIndex, type AcceptanceIndexReader } from "./acceptance.js";
+import { type CorrectionRecord, type CorrectionRecordSource } from "./corrections.js";
+/** The ref kinds a page may cite. */
+export declare const REF_KINDS: readonly string[];
+/** A repository's frozen export surface: name → kind, name → tier. */
+export interface ExportSurface {
+    readonly exports: Record<string, string>;
+    readonly tiers: Record<string, string>;
+}
+/** One row of a repository's closed-set registry, as the gates and generators read it. */
+export interface ClosedSetRow {
+    readonly set: string;
+    readonly file: string;
+    readonly memberKind: string;
+    readonly memberSource: string;
+    readonly status: string;
+}
+/** One row of a repository's contract-sentence registry. */
+export interface ContractRow {
+    readonly id: string;
+    readonly file: string;
+}
+/** One contract tag found in a source file: its id, its sentences, its line. */
+export interface ContractTag {
+    readonly id: string;
+    readonly sentences: readonly string[];
+    readonly line: number;
+}
+/**
+ * How a repository reads a `pin:` ref: the one check whose title holds the fragment, its suite path and its call printed
+ * without comments as its text; undefined when no check holds it; an error when more than one does, or when the check
+ * might not run. The package's own reader is vitest's ({@link pinOf}); a repository whose tests are another form hands
+ * in its own, held to the same contract.
+ */
+export type PinReader = (files: TreeFiles, rel: string, fragment: string) => Resolved | Unresolvable | undefined;
+/**
+ * The repository's own readings, each optional: a repository configures the readers of the things it has. A ref whose
+ * kind needs a reader the repository does not configure is an anchors finding that says so; a reader that is configured
+ * reads exactly as it always has.
+ */
+export interface WikiReaders {
+    /** The frozen export surface (`export:` refs, the root-export coverage sources). */
+    readonly snapshot?: (files: TreeFiles) => ExportSurface;
+    /** The closed-set registry (`set:` refs, generators, the closed-set coverage source). */
+    readonly closedSets?: {
+        readonly rows: (files: TreeFiles) => readonly ClosedSetRow[];
+        /** The members a row names, read from its source file; undefined when the row names members its reader cannot read. */
+        readonly members: (sf: ts.SourceFile, row: ClosedSetRow) => readonly string[] | undefined;
+    };
+    /** The contract-sentence registry (`contract:` refs, the contract coverage source). */
+    readonly contracts?: {
+        readonly rows: (files: TreeFiles) => readonly ContractRow[];
+        readonly tags: (sf: ts.SourceFile, file: string) => readonly ContractTag[];
+    };
+    /** The configuration catalog (`catalog:` refs, the configuration-key coverage source). */
+    readonly catalog?: CatalogReader;
+    /** A literal table reader, for generators that render a table of the tree. */
+    readonly tableValues?: TableValuesReader;
+    /** The internal record's work-item name form: the published wiki never carries one. Its flags hold (`i` reads any case). */
+    readonly workItemName?: RegExp;
+    /** The `pin:` reader, when this repository's tests are not vitest. */
+    readonly pin?: PinReader;
+    /** The acceptance index (`crit:` refs), read from the checkout named by `--test <dir>`. */
+    readonly acceptanceIndex?: AcceptanceIndexReader;
+    /** A cell's criterion as its publisher states it now, by key; undefined when the publisher's record holds no such criterion. */
+    readonly criterionText?: (files: TreeFiles, key: {
+        readonly repo: string;
+        readonly version: string;
+        readonly cell: string;
+    }) => string | undefined;
+}
+/** The readers a generator is handed: it reads nothing itself, so a table on a page and the gate read the tree one way. */
+export interface GeneratorReaders {
+    setMembers(set: string): readonly string[] | undefined;
+    tableValues(file: string, table: string): Record<string, string>;
+    closedSetRows(): readonly ClosedSetRow[];
+    configKnobs(): CatalogKnob[];
+    /** The pages of the genre under check (its index page excluded), each with its path under the genre's directory. */
+    wikiPages(): Array<{
+        rel: string;
+        fm: Frontmatter;
+    }>;
+    /** The row of the genre under check. */
+    genre(): GenreRow;
+}
+/**
+ * What a generated region holds: its text, and the refs that text relies on. The refs join the page's own: each must
+ * resolve, is held to what a page never carries, has its digest stamped, and is counted by coverage.
+ */
+export interface Generated {
+    readonly text: string;
+    readonly refs: readonly string[];
+}
+/**
+ * One generator: `render(...args)` is its region; `covers(...args)`, when present, is what the region renders in full —
+ * items by the covers key of a declared coverage source, which the coverage gate counts as covered; `rowFields(...args)`,
+ * when present, says the region is a table of knobs and names the knob fields its columns render, in column order, out
+ * of the package's table of knob fields. A reading it cannot make throws.
+ */
+export interface Generator {
+    render(...args: string[]): Generated;
+    covers?(...args: string[]): Readonly<Record<string, readonly string[]>>;
+    rowFields?(...args: string[]): readonly string[];
+}
+/** A repository's generators, made over the readers the gate hands them. */
+export type GeneratorFactory = (read: GeneratorReaders) => Record<string, Generator>;
+/** One item of a coverage source: its id, and where it stands when it stands in a file. */
+export interface CoverageItem {
+    readonly id: string;
+    readonly file?: string;
+    readonly line?: number;
+}
+/**
+ * A coverage source: its items read from the tree (a reading that cannot be made throws), the ref kind a page cites an
+ * item by (`export:<name>`) when pages may, and the key a generator's `covers` names its items under when regions may.
+ */
+export interface CoverageSource {
+    items(tree: WikiTree): readonly CoverageItem[];
+    readonly refKind?: string;
+    readonly coversKey?: string;
+}
+/** A required source: a coverage source, or the correction record. */
+export type RequiredSource = CoverageSource | CorrectionRecordSource;
+/**
+ * What a gate entry runs against: the repository root and the genre, and the repository's profile.
+ *
+ * The gate holds every page directory it is pointed at — `docs/wiki` and `docs/manual` alike — to one rule set: the
+ * genre, and with it the directory, is chosen here, by the entry's configuration object, never by a page's own header,
+ * and the package opens no second interface for another genre.
+ *
+ * A source named in `required` or `reported` with no reader (`undefined`) cannot be judged: the gate exits 2 rather
+ * than leave the requirement out.
+ */
+export interface WikiGateConfig {
+    /** The repository root every path is relative to. */
+    readonly root: string;
+    /** The genre: its row of the genre table names the page directory under the root (`wiki` = `docs/wiki`). */
+    readonly genre: Genre;
+    /** This repository's package name, the version its releases carry, and the word its pages name it by; `package.json` when absent. */
+    readonly identity?: RepoIdentity & {
+        readonly word: string;
+    };
+    /** The version from which this repository's findings fail, per genre: the genre under check must be named. */
+    readonly redFrom: Readonly<Partial<Record<Genre, string>>>;
+    /** How many releases separate two of this repository's versions (a `U` sentence's age); minor versions when absent. */
+    readonly releaseDistance?: ReleaseDistance;
+    readonly readers?: WikiReaders;
+    readonly generators?: GeneratorFactory;
+    /** The sources this repository's pages must cover, by name, besides what the genre requires. */
+    readonly required?: Readonly<Record<string, RequiredSource | undefined>>;
+    /** The sources the coverage gate counts and reports, by name. */
+    readonly reported?: Readonly<Record<string, CoverageSource | undefined>>;
+    /** Forms this repository's pages never carry, besides the shared ones: `[what, pattern]`. */
+    readonly bans?: ReadonlyArray<readonly [string, RegExp]>;
+    /** Run before any judgment; a throw means the gate cannot judge (the inputs a repository's readers need are not readable). */
+    readonly preflight?: (tree: WikiTree) => void;
+}
+/** Where the trees outside this one sit: the acceptance index's checkout and the correction record's. */
+export interface TreeOptions {
+    /** Repo-relative path → text, standing in for files on disk — how a pin checks a page against a changed source. */
+    readonly overrides?: ReadonlyMap<string, string>;
+    readonly testRoot?: string;
+    readonly correctionsRoot?: string;
+}
+/** The tree: the configuration's files, readers and generators, read once each. */
+export interface WikiTree extends TreeFiles {
+    readonly config: WikiGateConfig;
+    readonly genre: Genre;
+    /** The genre's page directory. */
+    readonly wikiDir: string;
+    readonly overrides: ReadonlyMap<string, string>;
+    snapshot(): ExportSurface;
+    closedSetRows(): readonly ClosedSetRow[];
+    contractRows(): readonly ContractRow[];
+    packageJson(): {
+        name?: unknown;
+        version?: unknown;
+    };
+    configKnobs(): CatalogKnob[];
+    /** Every page file under the genre's directory (repo-relative, sorted); `notes/` directories hold annotation files, not pages. */
+    wikiPageFiles(): string[];
+    /** Every page file under the directory of every genre: a page-id is unique across a repository's genres. */
+    allPageFiles(): string[];
+    /** The acceptance index as this check reads it; undefined when no checkout is named or it holds no index. */
+    acceptanceIndex(): AcceptanceIndex | undefined;
+    /** Whether the correction record is among this repository's required sources. */
+    readonly correctionsDeclared: boolean;
+    /** The correction records; undefined when the record is not declared, or declared and not in this check. */
+    corrections(): readonly CorrectionRecord[] | undefined;
+    readonly readers: GeneratorReaders;
+    readonly generators: Record<string, Generator>;
+}
+/** The correction-record source among the required ones, if declared (its value may be undefined: declared without a reader). */
+export declare function correctionSourceOf(config: Pick<WikiGateConfig, "required">): {
+    declared: boolean;
+    source: CorrectionRecordSource | undefined;
+};
+/**
+ * The tree a page is checked against. `overrides` (repo-relative path → text) stands in for files on disk — how a pin
+ * checks a page against a changed source without writing one. A repository generator spelled like a generator the
+ * package holds is refused: one name, one generator.
+ */
+export declare function createTree(config: WikiGateConfig, { overrides, testRoot, correctionsRoot }?: TreeOptions): WikiTree;
+/** The declared coverage sources, required then reported, each with its name (a source declared without a reader is skipped). */
+export declare function coverageSourcesOf(config: Pick<WikiGateConfig, "required" | "reported">): Array<{
+    name: string;
+    source: CoverageSource;
+    required: boolean;
+}>;
+/** The keys a generator's `covers` may name: the covers key of a declared coverage source. */
+export declare function coversKeysOf(config: Pick<WikiGateConfig, "required" | "reported">): string[];
+/** This repository as the gate sees it: its package name, version, and the word its pages name it by in `owner-repo`. */
+export declare function repoOf(tree: Pick<WikiTree, "packageJson"> & {
+    readonly config?: Pick<WikiGateConfig, "identity">;
+}): RepoIdentity & {
+    word: string;
+};
+/** The distance this repository reads releases by. */
+export declare function releaseDistanceOf(tree: Pick<WikiTree, "config">): ReleaseDistance;
+/** A ref that reads as its kind but is no evidence: `fixed` is a severity no version moves. */
+export type RefRefusal = Unresolvable & {
+    readonly fixed?: Severity;
+};
+/**
+ * One reading per ref. Undefined = the ref does not resolve in this tree; `{ error, fixed? }` = it is malformed, names
+ * something that is not evidence, or needs a reader this repository does not configure; otherwise `{ text, file?, line? }`
+ * where `text` is what the freshness digest is taken of.
+ */
+export declare function resolveRef(tree: WikiTree, ref: string): Resolved | RefRefusal | undefined;

package/dist/tree.js

@@ -0,0 +1,240 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import ts from "typescript";
+import { declarationOf, pinOf } from "./source.js";
+import { splitPage } from "./page.js";
+import { minorReleaseDistance, parseRun } from "./versions.js";
+import { GENRES, genreRow } from "./genre.js";
+import { cellRefusal, keyReached, parseCritKey } from "./acceptance.js";
+import { CORRECTION_RECORD } from "./corrections.js";
+import { builtInGenerators } from "./generators.js";
+export const REF_KINDS = Object.freeze(["export", "set", "contract", "src", "pin", "catalog", "run", "crit"]);
+function noReader(what) {
+    return `this repository configures no ${what} reader`;
+}
+export function correctionSourceOf(config) {
+    const required = config.required ?? {};
+    if (!Object.hasOwn(required, CORRECTION_RECORD))
+        return { declared: false, source: undefined };
+    const v = required[CORRECTION_RECORD];
+    return { declared: true, source: v !== undefined && "records" in v ? v : undefined };
+}
+export function createTree(config, { overrides = new Map(), testRoot, correctionsRoot } = {}) {
+    const { root, genre } = config;
+    const wikiDir = genreRow(genre).dir;
+    const repoReaders = config.readers ?? {};
+    const texts = new Map();
+    const sources = new Map();
+    const once = new Map();
+    const memo = (key, f) => {
+        if (!once.has(key))
+            once.set(key, f());
+        return once.get(key);
+    };
+    const required = (reader, what) => {
+        if (reader === undefined)
+            throw new Error(noReader(what));
+        return reader;
+    };
+    const pagesUnder = (dir) => {
+        const out = new Set();
+        const walk = (rel) => {
+            const abs = join(root, rel);
+            if (!existsSync(abs))
+                return;
+            for (const e of readdirSync(abs, { withFileTypes: true })) {
+                const child = `${rel}/${e.name}`;
+                if (e.isDirectory()) {
+                    if (e.name !== "notes")
+                        walk(child);
+                }
+                else if (e.name.endsWith(".md"))
+                    out.add(child);
+            }
+        };
+        walk(dir);
+        for (const rel of overrides.keys())
+            if (rel.startsWith(`${dir}/`) && rel.endsWith(".md") && !rel.includes("/notes/"))
+                out.add(rel);
+        return [...out].sort();
+    };
+    const corrections = correctionSourceOf(config);
+    const tree = {
+        root,
+        config,
+        genre,
+        wikiDir,
+        overrides,
+        exists: (rel) => overrides.has(rel) || existsSync(join(root, rel)),
+        read: (rel) => {
+            if (overrides.has(rel))
+                return overrides.get(rel);
+            if (!texts.has(rel))
+                texts.set(rel, readFileSync(join(root, rel), "utf8"));
+            return texts.get(rel);
+        },
+        sourceFile: (rel) => {
+            if (!sources.has(rel))
+                sources.set(rel, ts.createSourceFile(rel, tree.read(rel), ts.ScriptTarget.ES2022, true));
+            return sources.get(rel);
+        },
+        snapshot: () => memo("snapshot", () => required(repoReaders.snapshot, "export-surface")(tree)),
+        closedSetRows: () => memo("closed", () => required(repoReaders.closedSets, "closed-set registry").rows(tree)),
+        contractRows: () => memo("contracts", () => required(repoReaders.contracts, "contract-sentence registry").rows(tree)),
+        packageJson: () => memo("package", () => JSON.parse(tree.read("package.json"))),
+        configKnobs: () => memo("knobs", () => required(repoReaders.catalog, "configuration catalog").knobs(tree)),
+        wikiPageFiles: () => memo("pages", () => pagesUnder(wikiDir)),
+        allPageFiles: () => memo("all-pages", () => Object.values(GENRES).flatMap((row) => pagesUnder(row.dir))),
+        acceptanceIndex: () => memo("acceptance", () => required(repoReaders.acceptanceIndex, "acceptance-index")(testRoot)),
+        correctionsDeclared: corrections.declared,
+        corrections: () => memo("corrections", () => (corrections.declared ? required(corrections.source, "correction-record").records(correctionsRoot) : undefined)),
+    };
+    tree.readers = readersOf(tree);
+    const own = (config.generators ?? (() => ({})))(tree.readers);
+    const builtIn = builtInGenerators(tree.readers);
+    for (const name of Object.keys(own))
+        if (Object.hasOwn(builtIn, name))
+            throw new Error(`the repository's generator \`${name}\` is spelled like the package's own: one name, one generator`);
+    tree.generators = Object.assign(Object.create(null), builtIn, own);
+    return tree;
+}
+export function coverageSourcesOf(config) {
+    const out = [];
+    for (const [name, v] of Object.entries(config.required ?? {}))
+        if (v !== undefined && "items" in v)
+            out.push({ name, source: v, required: true });
+    for (const [name, v] of Object.entries(config.reported ?? {}))
+        if (v !== undefined)
+            out.push({ name, source: v, required: false });
+    return out;
+}
+export function coversKeysOf(config) {
+    return [...new Set(coverageSourcesOf(config).flatMap(({ source }) => (source.coversKey === undefined ? [] : [source.coversKey])))];
+}
+export function repoOf(tree) {
+    const identity = tree.config?.identity;
+    if (identity !== undefined)
+        return { name: identity.name, version: identity.version, word: identity.word };
+    const pkg = tree.packageJson();
+    const word = String(pkg.name ?? "").replace(/^@sema-agent\//, "");
+    return { name: pkg.name, version: pkg.version, word };
+}
+export function releaseDistanceOf(tree) {
+    return tree.config.releaseDistance ?? minorReleaseDistance;
+}
+function readersOf(tree) {
+    const repoReaders = tree.config.readers ?? {};
+    return {
+        setMembers: (name) => {
+            const row = tree.closedSetRows().find((r) => r.set === name);
+            if (!row || !tree.exists(row.file))
+                return undefined;
+            return repoReaders.closedSets.members(tree.sourceFile(row.file), row) ?? undefined;
+        },
+        tableValues: (rel, table) => {
+            if (repoReaders.tableValues === undefined)
+                throw new Error(noReader("literal-table"));
+            return repoReaders.tableValues(tree, rel, table);
+        },
+        closedSetRows: () => tree.closedSetRows(),
+        configKnobs: () => tree.configKnobs(),
+        wikiPages: () => tree
+            .wikiPageFiles()
+            .filter((rel) => rel !== `${tree.wikiDir}/README.md`)
+            .map((rel) => ({ rel: rel.slice(tree.wikiDir.length + 1), fm: splitPage(tree.read(rel)).fm }))
+            .filter((p) => p.fm !== null && typeof p.fm["page-id"] === "string"),
+        genre: () => genreRow(tree.genre),
+    };
+}
+function missingReaderOf(tree, kind) {
+    const r = tree.config.readers ?? {};
+    if (kind === "export" && r.snapshot === undefined)
+        return "export-surface";
+    if (kind === "set" && r.closedSets === undefined)
+        return "closed-set registry";
+    if (kind === "contract" && r.contracts === undefined)
+        return "contract-sentence registry";
+    if (kind === "catalog" && r.catalog === undefined)
+        return "configuration catalog";
+    if (kind === "crit" && r.acceptanceIndex === undefined)
+        return "acceptance-index";
+    if (kind === "crit" && r.criterionText === undefined)
+        return "criterion-text";
+    return undefined;
+}
+export function resolveRef(tree, ref) {
+    const m = /^([a-z]+):(.+)$/.exec(ref);
+    if (!m)
+        return { error: `ref "${ref}" names no kind (one of ${REF_KINDS.join(", ")})` };
+    const kind = m[1];
+    const rest = m[2];
+    const missing = missingReaderOf(tree, kind);
+    if (missing !== undefined)
+        return { error: `\`${kind}:\` refs are not read here: ${noReader(missing)}` };
+    switch (kind) {
+        case "export": {
+            const s = tree.snapshot();
+            return Object.hasOwn(s.exports, rest) ? { text: `${rest}:${s.exports[rest]}:${s.tiers[rest]}` } : undefined;
+        }
+        case "set": {
+            const row = tree.closedSetRows().find((r) => r.set === rest);
+            if (!row)
+                return undefined;
+            const members = tree.readers.setMembers(rest);
+            return members === undefined ? { error: `the registry row of ${rest} names members its reader cannot read` } : { text: JSON.stringify(members), file: row.file };
+        }
+        case "contract": {
+            const row = tree.contractRows().find((r) => r.id === rest);
+            if (!row || !tree.exists(row.file))
+                return undefined;
+            const tag = tree.config.readers.contracts.tags(tree.sourceFile(row.file), row.file).find((t) => t.id === rest);
+            return tag ? { text: tag.sentences.join(" "), file: row.file, line: tag.line } : undefined;
+        }
+        case "src": {
+            const sm = /^([^#]+)#([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)$/.exec(rest);
+            if (!sm)
+                return { error: `src ref "${ref}" must read src:<file>#<Declaration>[.<member>…]` };
+            if (!tree.exists(sm[1]))
+                return undefined;
+            const d = declarationOf(tree, sm[1], sm[2]);
+            return d ? { text: d.text, file: sm[1], line: d.line } : undefined;
+        }
+        case "pin": {
+            const pm = /^([^#]+)#"(.+)"$/.exec(rest);
+            if (!pm)
+                return { error: `pin ref "${ref}" must read pin:<test file>#"<title fragment>"` };
+            return (tree.config.readers?.pin ?? pinOf)(tree, pm[1], pm[2]);
+        }
+        case "catalog": {
+            const knob = tree.configKnobs().find((k) => k.key === rest);
+            return knob ? { text: knob.text, file: tree.config.readers.catalog.file, line: knob.line } : undefined;
+        }
+        case "run":
+            return parseRun(rest) ? { text: rest } : { error: `run ref "${ref}" must read run:<who>@<package>@<X.Y.Z>@<YYYY-MM-DD>` };
+        case "crit":
+            return resolveCrit(tree, rest);
+        default:
+            return { error: `unknown ref kind "${kind}" (one of ${REF_KINDS.join(", ")})` };
+    }
+}
+function resolveCrit(tree, key) {
+    const refuse = (error) => ({ error, fixed: "fail" });
+    const k = parseCritKey(key);
+    if (k === undefined)
+        return refuse(`crit ref "crit:${key}" must read crit:<repo>@<X.Y.Z>:<cell> (G<n>[.<sub>] or G-<id>)`);
+    const repo = repoOf(tree);
+    if (k.repo !== repo.word)
+        return refuse(`crit:${key} is a cell of ${k.repo}, not of this repository (${repo.word}): not evidence for this page`);
+    if (!keyReached(k, repo.version))
+        return refuse(`crit:${key} names ${k.version}, a release this tree (${repo.version}) has not reached`);
+    const index = tree.acceptanceIndex();
+    if (index === undefined)
+        return { error: `crit:${key} cannot be judged: no acceptance index in this check (name its checkout with --test <dir>)` };
+    const refusal = cellRefusal(index, key);
+    if (refusal !== undefined)
+        return refuse(refusal);
+    const criterion = tree.config.readers.criterionText(tree, k);
+    if (criterion === undefined)
+        return refuse(`crit:${key}: the publisher's record states no such criterion`);
+    return { text: `${key}\n${index.cells.get(key).textSha}\n${criterion}` };
+}