@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/docs/decision-record.js

@@ -0,0 +1,135 @@
+// The grammar of one decision record: how its file name numbers it, where its status is stated and
+// which records it supersedes. `docs check` reads records with it and `work decide` writes them with
+// it, so a record one accepts is a record the other can number and mark superseded.
+import { posix } from 'node:path';
+import { parseDocument } from 'yaml';
+import { resolveLinkTarget, walkMarkdownProse } from './markdown.js';
+// Dated names (2026-09-<slug>.md) order by date and carry no number to collide.
+const DATED = /^(?:19|20)\d{2}-\d{2}(?:-\d{2})?(?=[-_.])/;
+const NUMBERED = /^(\d+)(?=[-_. ])/;
+const STATUS_LINE = /^(\s*(?:[-*]\s+)?(?:\*\*|__)?status(?:\*\*|__)?\s*:\s*(?:\*\*|__)?\s*)(.*)$/i;
+const STATUS_HEADING = /^#{1,6}\s+status\s*$/i;
+const FRONT_MATTER_STATUS = /^(status\s*:\s*)/i;
+const KEYWORD = /\b(supersedes|superseded\s+by)\b/gi;
+// A link (rewritten to [[target]]), a file name, `ADR-12`, `#12`, or a zero-padded `of 0012`; a bare
+// number counts only right after the keyword, so a year later in the sentence is not read as a record.
+const REFERENCE = /\[\[([^\]]+)\]\]|(?:\b(?:adr|decision|record)s?[-\s]?#?|#|\b(?:of|in)\s+(?=0))(\d{1,5})\b|([\w./-]+\.md)\b/gi;
+/** Whether a record file is named by date, and so carries no number. */
+export const isDatedRecordName = (name) => DATED.test(name);
+/** The digits a record file is numbered by, or undefined for a dated or unnumbered name. */
+export function recordNumber(name) {
+    return DATED.test(name) ? undefined : NUMBERED.exec(name)?.[1];
+}
+/** The first word of a status, lowercased: `accepted` for "**Accepted** (2026-01-02)". */
+export function leadingWord(value) {
+    return value.replace(/[*_`[\]]/g, '').trim().split(/[\s,.;:()]/, 1)[0].toLowerCase();
+}
+// A link becomes [[target]] so its target survives as one token; code spans keep their text.
+function referenceText(prose) {
+    return prose.replace(/\[([^\]]*)\]\(([^)\s]*)[^)]*\)/g, (_match, _label, target) => ` [[${target}]] `).replace(/`/g, ' ');
+}
+function referencesIn(line, text, record) {
+    const found = [];
+    const keywords = [...text.matchAll(KEYWORD)];
+    keywords.forEach((keyword, position) => {
+        const start = keyword.index + keyword[0].length;
+        // The clause the keyword governs: up to the next keyword, a semicolon or a sentence end.
+        const end = Math.min(keywords[position + 1]?.index ?? text.length, ...[/;/, /\.(?:\s|$)/].map(pattern => { const at = text.slice(start).search(pattern); return at === -1 ? text.length : start + at; }));
+        const clause = text.slice(start, end);
+        const outgoing = keyword[1].toLowerCase() === 'supersedes';
+        // "Supersedes 0012" names the whole record; "supersedes the cache clause of 0012" only a part.
+        // A number that runs on into a name (`2026-09-cache.md`, `0012-x.md`) is a file name, read below.
+        const bare = /^\s*:?\s*(\d{1,5})\b(?![-.]\w)/.exec(clause);
+        const leading = /^\s*:?\s*(?:\[\[|(?:adr|decision|record)s?\b|#|[\w./-]+\.md\b)/i.test(clause) || bare !== null;
+        // "Supersedes 0012 (ADR-0012)" names one record twice; it is one reference.
+        const add = (reference, text) => {
+            if (!found.some(row => row.number === reference.number && row.file === reference.file))
+                found.push({ line, text, full: outgoing && leading, ...reference });
+        };
+        if (bare)
+            add({ number: Number(bare[1]) }, bare[1]);
+        for (const match of clause.matchAll(REFERENCE)) {
+            const target = match[1] ?? match[3];
+            if (target !== undefined) {
+                const file = resolveLinkTarget(posix.dirname(record), target);
+                if (file?.endsWith('.md'))
+                    add({ file }, target);
+            }
+            else
+                add({ number: Number(match[2]) }, match[0].trim());
+        }
+    });
+    return found;
+}
+/** A record's status and supersedes references, or why it cannot be read. `name` is its path inside the records' directory. */
+export function parseDecisionRecord(name, body) {
+    let walked;
+    try {
+        walked = walkMarkdownProse(body);
+    }
+    catch (error) {
+        return { unreadable: error.message };
+    }
+    const rows = body.split(/\r?\n/);
+    let status;
+    const supersedes = [];
+    if (rows[0] === '---') {
+        const end = rows.indexOf('---', 1);
+        const front = rows.slice(1, end === -1 ? 1 : end);
+        const parsed = parseDocument(front.join('\n'));
+        if (parsed.errors.length > 0)
+            return { unreadable: `its front matter is not valid YAML (${parsed.errors[0].message.split('\n', 1)[0]})` };
+        const data = parsed.toJS();
+        if (data && typeof data === 'object') {
+            if (typeof data.status === 'string') {
+                // Counted from the opening `---`; 0 where the field is not written on a line of its own.
+                const at = front.findIndex(row => FRONT_MATTER_STATUS.test(row));
+                status = { line: at === -1 ? 0 : at + 2, value: data.status, form: 'front-matter' };
+            }
+            for (const [field, text] of [['supersedes', 'Supersedes'], ['superseded_by', 'Superseded by']]) {
+                for (const value of [data[field]].flat()) {
+                    if (typeof value === 'string' || typeof value === 'number') {
+                        supersedes.push(...referencesIn(rows.findIndex(row => row.startsWith(`${field}:`)) + 1, `${text} ${value}`, name));
+                    }
+                }
+            }
+        }
+    }
+    walked.lines.forEach((row, position) => {
+        const prose = row.prose;
+        if (status === undefined) {
+            const line = STATUS_LINE.exec(prose);
+            if (line && line[2].trim() !== '')
+                status = { line: row.line, value: line[2], form: 'line' };
+            else if (STATUS_HEADING.test(prose)) {
+                const next = walked.lines.slice(position + 1).find(candidate => candidate.prose.trim() !== '');
+                if (next && !/^#/.test(next.prose))
+                    status = { line: next.line, value: next.prose, form: 'heading' };
+            }
+        }
+        supersedes.push(...referencesIn(row.line, referenceText(prose), name));
+    });
+    return { ...status ? { status } : {}, supersedes };
+}
+/**
+ * The record's text with its status set to `status`, where `parseDecisionRecord` finds it and in the
+ * same form; undefined when the record states no status, or states it on a line this cannot rewrite
+ * in place (one an HTML comment shares).
+ */
+export function withStatus(text, status) {
+    const parsed = parseDecisionRecord('', text);
+    if ('unreadable' in parsed || parsed.status === undefined)
+        return undefined;
+    const rows = text.split('\n');
+    const index = parsed.status.line - 1;
+    const row = rows[index];
+    if (row === undefined)
+        return undefined;
+    const ending = row.endsWith('\r') ? '\r' : '';
+    const raw = ending ? row.slice(0, -1) : row;
+    const prefix = parsed.status.form === 'heading' ? '' : (parsed.status.form === 'line' ? STATUS_LINE : FRONT_MATTER_STATUS).exec(raw)?.[1];
+    if (prefix === undefined)
+        return undefined;
+    rows[index] = `${prefix}${status}${ending}`;
+    return rows.join('\n');
+}

package/dist/docs/decisions.d.ts

@@ -0,0 +1,16 @@
+import { type Diagnostic } from '../environment/contract.js';
+interface DecisionRecordSet {
+    /** Prefixed onto every reported path: '' in the cockpit's own repository, `<slug>:` in a sibling. */
+    readonly repository: string;
+    /** The records' directory, relative to the repository root. */
+    readonly directory: string;
+    /** Each Markdown file directly inside the directory, by file name. */
+    readonly files: ReadonlyMap<string, string>;
+    readonly index?: Readonly<{
+        path: string;
+        body: string;
+    }>;
+}
+/** Every integrity finding in one decision-record set. Index and template files are not records. */
+export declare function inspectDecisionRecords(set: DecisionRecordSet): Diagnostic[];
+export {};

package/dist/docs/decisions.js

@@ -0,0 +1,103 @@
+// The integrity of a decision-record set: numbering, the index, statuses and supersedes links.
+// Decision records drift in ways nothing else notices: concurrent branches each take the next
+// free number, a record lands without an index line, and a record superseded in full keeps
+// reading "Accepted" because only the newer one was edited.
+import { posix } from 'node:path';
+import { ENVIRONMENT_CODES } from '../environment/contract.js';
+import { leadingWord, parseDecisionRecord, recordNumber } from './decision-record.js';
+import { resolveLinkTarget, walkMarkdownProse } from './markdown.js';
+const DECISION_STATUSES = ['proposed', 'accepted', 'superseded', 'deprecated', 'rejected'];
+const numberOf = (name) => { const digits = recordNumber(name); return digits === undefined ? undefined : Number(digits); };
+/** Every integrity finding in one decision-record set. Index and template files are not records. */
+export function inspectDecisionRecords(set) {
+    const findings = [];
+    const at = (name, line) => `${set.repository}${posix.join(set.directory, name)}${line ? `:${line}` : ''}`;
+    const indexName = set.index && posix.dirname(set.index.path) === set.directory ? posix.basename(set.index.path) : undefined;
+    // A README or index page lists the records, and a template is the shape of one; neither decides anything.
+    const names = [...set.files.keys()].filter(name => name !== indexName && !/^(?:readme|index)\.md$/i.test(name) && !/template/i.test(name)).sort();
+    const records = new Map();
+    for (const name of names) {
+        const parsed = parseDecisionRecord(name, set.files.get(name));
+        if ('unreadable' in parsed) {
+            findings.push({ severity: 'error', code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+                message: `decision record ${at(name)} could not be read: ${parsed.unreadable}`, target: at(name),
+                fix: 'correct the record so it parses as Markdown with optional YAML front matter, then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+            continue;
+        }
+        records.set(name, parsed);
+    }
+    const byNumber = new Map();
+    for (const name of names) {
+        const number = numberOf(name);
+        if (number !== undefined)
+            byNumber.set(number, [...byNumber.get(number) ?? [], name]);
+    }
+    for (const [number, shared] of byNumber) {
+        if (shared.length < 2)
+            continue;
+        // Not "_DUPLICATE": the CLI reads that suffix as a repeated option and prints a usage hint.
+        findings.push({ severity: 'error', code: 'DECISION_NUMBER_REUSED', target: at(shared[1]),
+            message: `decision records ${shared.map(name => at(name)).join(' and ')} share number ${number}`,
+            fix: 'renumber the later record to the next free number, then update the index and every supersedes line that cites it' });
+    }
+    for (const [name, record] of records) {
+        const status = record.status === undefined ? undefined : leadingWord(record.status.value);
+        if (!DECISION_STATUSES.some(known => known === status)) {
+            findings.push({ severity: 'error', code: 'DECISION_STATUS_MISSING', target: at(name, record.status?.line),
+                message: record.status === undefined ? `decision record ${at(name)} states no status`
+                    : `decision record ${at(name)} has status "${record.status.value.trim()}", which starts with none of ${DECISION_STATUSES.join(', ')}`,
+                fix: `give the record a status line such as "Status: Accepted", or status: accepted in its front matter, starting with one of ${DECISION_STATUSES.join(', ')}` });
+        }
+        for (const reference of record.supersedes) {
+            const target = reference.file !== undefined
+                ? posix.dirname(reference.file) === '.' && records.has(reference.file) ? reference.file : undefined
+                : names.find(candidate => numberOf(candidate) === reference.number);
+            if (target === undefined) {
+                findings.push({ severity: 'error', code: 'DECISION_LINK_UNRESOLVED', target: at(name, reference.line),
+                    message: `decision record ${at(name, reference.line)} cites ${reference.text}, which names no record in ${set.repository}${set.directory}`,
+                    fix: 'correct the number or link to name an existing record, or restore the record it names' });
+                continue;
+            }
+            const superseded = records.get(target)?.status;
+            // Only an accepted record replaces another; a proposed or rejected one leaves it standing.
+            if (reference.full && ['accepted', 'superseded', 'deprecated'].includes(status ?? '') && superseded && leadingWord(superseded.value) === 'accepted') {
+                findings.push({ severity: 'error', code: 'DECISION_SUPERSEDED_STALE', target: at(target, superseded.line),
+                    message: `decision record ${at(target)} still has status "${superseded.value.trim()}", but ${at(name, reference.line)} supersedes it`,
+                    fix: `change the superseded record's status to "Superseded by" the newer record; if only part of it is replaced, say which part in the newer record's supersedes line, such as "supersedes the retry clause of ${target}"` });
+            }
+        }
+    }
+    if (set.index) {
+        let links;
+        try {
+            links = walkMarkdownProse(set.index.body).links;
+        }
+        catch (error) {
+            findings.push({ severity: 'error', code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+                message: `decision index ${set.repository}${set.index.path} could not be read: ${error.message}`, target: `${set.repository}${set.index.path}`,
+                fix: 'close the HTML comment the message names, then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+            return findings;
+        }
+        const linked = new Set();
+        for (const link of links) {
+            const resolved = resolveLinkTarget(posix.dirname(set.index.path), link.target);
+            if (resolved === undefined || !resolved.endsWith('.md') || posix.dirname(resolved) !== set.directory)
+                continue;
+            const name = posix.basename(resolved);
+            linked.add(name);
+            if (!set.files.has(name)) {
+                findings.push({ severity: 'error', code: 'DECISION_INDEX_ENTRY_MISSING', target: `${set.repository}${set.index.path}:${link.line}`,
+                    message: `decision index ${set.repository}${set.index.path}:${link.line} links ${link.target}, which does not exist`,
+                    fix: 'correct the link to the record\'s current file name, or remove the entry if the record was deleted on purpose' });
+            }
+        }
+        for (const name of names) {
+            if (linked.has(name))
+                continue;
+            findings.push({ severity: 'error', code: 'DECISION_UNINDEXED', target: at(name),
+                message: `decision record ${at(name)} is not linked from ${set.repository}${set.index.path}`,
+                fix: 'add a line linking the record to the decision index' });
+        }
+    }
+    return findings;
+}

package/dist/docs/markdown.d.ts

@@ -0,0 +1,36 @@
+interface ProseLine {
+    readonly line: number;
+    readonly prose: string;
+    readonly comments: readonly string[];
+}
+interface MarkdownLink {
+    readonly line: number;
+    readonly label: string;
+    readonly target: string;
+    readonly index: number;
+    readonly end: number;
+}
+export interface WalkedMarkdown {
+    readonly lines: readonly ProseLine[];
+    readonly fences: readonly Readonly<{
+        line: number;
+        info: string;
+    }>[];
+    /** Each line inside a fenced block, with the info string of its fence. */
+    readonly fencedLines: readonly Readonly<{
+        line: number;
+        info: string;
+        text: string;
+    }>[];
+    readonly links: readonly MarkdownLink[];
+}
+/** The visible prose of a page, line by line: fenced code and front matter removed, HTML comments lifted out. */
+export declare function walkMarkdownProse(body: string): WalkedMarkdown;
+/**
+ * The repository path a link target or cited path names, resolved against `base`, the directory it
+ * is relative to ('' for the repository root): its fragment, query, `:line[:column]` suffix and
+ * trailing slashes dropped, and its percent escapes decoded. Undefined for an empty, absolute or
+ * external (`scheme:`) target. The result may still climb out with `../`; the caller decides.
+ */
+export declare function resolveLinkTarget(base: string, target: string): string | undefined;
+export {};

package/dist/docs/markdown.js

@@ -0,0 +1,88 @@
+// The Markdown reading shared by the repository's own docs lint and `cockpit docs check`: one walker,
+// so both agree on what counts as prose, code and a link.
+import { posix } from 'node:path';
+/** The visible prose of a page, line by line: fenced code and front matter removed, HTML comments lifted out. */
+export function walkMarkdownProse(body) {
+    const lines = [];
+    const fences = [];
+    const fencedLines = [];
+    const links = [];
+    const rows = body.split(/\r?\n/);
+    let fence;
+    const start = rows[0] === '---' ? rows.indexOf('---', 1) + 1 : 0;
+    let comment;
+    for (let index = start; index < rows.length; index += 1) {
+        const number = index + 1;
+        let text = rows[index];
+        const marker = /^\s*(`{3,}|~{3,})(.*)$/.exec(text);
+        if (fence !== undefined) {
+            if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && marker[2].trim() === '')
+                fence = undefined;
+            else
+                fencedLines.push({ line: number, info: fences.at(-1).info, text });
+            continue;
+        }
+        if (marker && comment === undefined) {
+            fence = marker[1];
+            fences.push({ line: number, info: marker[2].trim() });
+            continue;
+        }
+        const comments = [];
+        let prose = '';
+        while (text !== '') {
+            if (comment) {
+                const close = text.indexOf('-->');
+                comment.text += ` ${close === -1 ? text : text.slice(0, close)}`;
+                if (close === -1) {
+                    text = '';
+                    break;
+                }
+                text = text.slice(close + 3);
+                const owner = lines.find(row => row.line === comment.line);
+                const done = comment.text.trim().replace(/\s+/g, ' ');
+                if (owner)
+                    owner.comments.push(done);
+                else
+                    comments.push(done);
+                comment = undefined;
+                continue;
+            }
+            const open = text.indexOf('<!--');
+            if (open === -1) {
+                prose += text;
+                break;
+            }
+            prose += text.slice(0, open);
+            comment = { line: number, text: '' };
+            text = text.slice(open + 4);
+        }
+        lines.push({ line: number, prose, comments });
+        const visible = prose.replace(/`+[^`]*`+/g, span => ' '.repeat(span.length));
+        for (const match of visible.matchAll(/\[([^\]]*)\]\(([^)\s]*)[^)]*\)/g)) {
+            links.push({ line: number, label: match[1], target: match[2], index: match.index, end: match.index + match[0].length });
+        }
+    }
+    if (comment)
+        throw new Error(`HTML comment opened on line ${comment.line} is not closed`);
+    return { lines, fences, fencedLines, links };
+}
+/**
+ * The repository path a link target or cited path names, resolved against `base`, the directory it
+ * is relative to ('' for the repository root): its fragment, query, `:line[:column]` suffix and
+ * trailing slashes dropped, and its percent escapes decoded. Undefined for an empty, absolute or
+ * external (`scheme:`) target. The result may still climb out with `../`; the caller decides.
+ */
+export function resolveLinkTarget(base, target) {
+    let value = target.split(/[#?]/, 1)[0].replace(/:\d+(?::\d+)?$/, '').replace(/\/+$/, '');
+    // A `%` that starts no valid escape is part of the file name, as CommonMark reads it.
+    try {
+        value = decodeURI(value);
+    }
+    catch (error) {
+        if (!(error instanceof URIError))
+            throw error;
+    }
+    if (value === '' || value.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(value))
+        return undefined;
+    return posix.normalize(posix.join(base, value));
+}

package/dist/docs/references.d.ts

@@ -0,0 +1,32 @@
+import type { Diagnostic } from '../environment/contract.js';
+import { type WalkedMarkdown } from './markdown.js';
+interface RepositoryHistory {
+    /** Each path a commit deleted or renamed away, newest first, mapped to its new name for a rename. */
+    readonly removed: ReadonlyMap<string, string | undefined>;
+    /** Every make target any version of a Makefile defined. */
+    readonly targets: ReadonlySet<string>;
+}
+export interface LivingDocument {
+    readonly path: string;
+    readonly walked: WalkedMarkdown;
+}
+/** `git log --format= --name-status -z -M --diff-filter=DR` output, newest commit first. */
+export declare function parseRemovedPaths(output: string): Map<string, string | undefined>;
+/** The targets the given Makefile lines define, including .PHONY names; special and pattern targets are skipped. */
+export declare function makeTargets(lines: Iterable<string>): Set<string>;
+/** The targets ever defined, from `git log -p` over the Makefiles: every line was added once. */
+export declare function historicalMakeTargets(patch: string): Set<string>;
+/**
+ * The stale references in the given documents. `files` are the repository's files now; a cited
+ * directory counts as present while any file is under it.
+ */
+export declare function staleReferences(input: Readonly<{
+    repository: string;
+    documents: readonly LivingDocument[];
+    files: ReadonlySet<string>;
+    targets: ReadonlySet<string>;
+    history: RepositoryHistory;
+    /** Whether the path is on disk; an ignored file is absent from `files` but not removed. */
+    present: (path: string) => boolean;
+}>): Diagnostic[];
+export {};

package/dist/docs/references.js

@@ -0,0 +1,148 @@
+// Stale references in living documents: a path or `make` target a document cites that the
+// repository once had and has since removed. Keying on history is the whole precision story: a
+// backlog full of proposals ("add `make park`") names things that never existed, and those are
+// left alone, while `make publish` after its target was deleted is exactly the rot to report. No
+// allowlist is needed, and a link that never resolved is a link checker's business.
+import { posix } from 'node:path';
+import { resolveLinkTarget } from './markdown.js';
+/** `git log --format= --name-status -z -M --diff-filter=DR` output, newest commit first. */
+export function parseRemovedPaths(output) {
+    const removed = new Map();
+    const tokens = output.split('\0').filter(token => token !== '');
+    for (let index = 0; index < tokens.length;) {
+        const status = tokens[index++];
+        if (status === 'D') {
+            const path = tokens[index++];
+            if (!removed.has(path))
+                removed.set(path, undefined);
+        }
+        else if (/^R\d*$/.test(status)) {
+            const from = tokens[index++];
+            const to = tokens[index++];
+            if (!removed.has(from))
+                removed.set(from, to);
+        }
+        else
+            throw new Error(`unexpected git name-status record ${JSON.stringify(status)}`);
+    }
+    return removed;
+}
+const RULE = /^([^\s:#=$][^:#=$]*?)\s*::?(?!=)/;
+/** The targets the given Makefile lines define, including .PHONY names; special and pattern targets are skipped. */
+export function makeTargets(lines) {
+    const targets = new Set();
+    for (const line of lines) {
+        const phony = /^\.PHONY\s*:(.*)$/.exec(line);
+        const names = phony ? phony[1] : RULE.exec(line)?.[1];
+        for (const name of names?.trim().split(/\s+/) ?? []) {
+            if (name !== '' && !name.startsWith('.') && !name.includes('%'))
+                targets.add(name);
+        }
+    }
+    return targets;
+}
+/** The targets ever defined, from `git log -p` over the Makefiles: every line was added once. */
+export function historicalMakeTargets(patch) {
+    return makeTargets(patch.split('\n').filter(line => /^[+-]/.test(line) && !/^(?:\+\+\+|---) /.test(line)).map(line => line.slice(1)));
+}
+const SHELL_FENCES = new Set(['', 'sh', 'bash', 'shell', 'zsh', 'console', 'terminal', 'shell-session']);
+const PATH_SPAN = /^[A-Za-z0-9._@+~-][A-Za-z0-9._@+~/-]*$/;
+// `make a b` cites a and b; `make -C dir x` or `make -f other.mk x` cites another Makefile, so not x.
+function citedTargets(text) {
+    const targets = [];
+    for (const match of text.matchAll(/(?:^|[\s;&|(`$])make((?:[ \t]+[^\s;&|)`]+)*)/g)) {
+        const words = match[1].trim().split(/\s+/).filter(Boolean);
+        if (words.some(word => /^-(?:C|f)|^--(?:directory|file|makefile)\b/.test(word)))
+            continue;
+        for (const word of words) {
+            if (word.startsWith('-') || word.includes('='))
+                continue;
+            if (!/^[A-Za-z0-9_][A-Za-z0-9._/-]*$/.test(word))
+                break;
+            targets.push(word);
+        }
+    }
+    return targets;
+}
+function citedPath(document, raw, relativeToDocument) {
+    const value = raw.trim().replace(/^<|>$/g, '');
+    const relative = relativeToDocument || value.startsWith('./') || value.startsWith('../');
+    const resolved = resolveLinkTarget(relative ? posix.dirname(document) : '', value);
+    return resolved === undefined || resolved === '.' || resolved.startsWith('../') ? undefined : resolved;
+}
+// Every directory above the given files: `a/b/c.md` contributes `a` and `a/b`.
+const ancestors = (files) => new Set([...files].flatMap(file => file.split('/').slice(0, -1).map((_, index, parts) => parts.slice(0, index + 1).join('/'))));
+/**
+ * The stale references in the given documents. `files` are the repository's files now; a cited
+ * directory counts as present while any file is under it.
+ */
+export function staleReferences(input) {
+    const findings = [];
+    const directories = ancestors(input.files);
+    const exists = (path) => input.files.has(path) || directories.has(path);
+    const removedDirectories = ancestors(input.history.removed.keys());
+    // Follow renames to where the content lives now; a chain that ends in a deletion is a removal.
+    const successor = (path) => {
+        const seen = new Set();
+        let current = path;
+        while (input.history.removed.has(current) && !seen.has(current)) {
+            seen.add(current);
+            const next = input.history.removed.get(current);
+            if (next === undefined)
+                return undefined;
+            if (exists(next))
+                return next;
+            current = next;
+        }
+        return undefined;
+    };
+    for (const document of input.documents) {
+        const reported = new Set();
+        const start = findings.length;
+        const where = (line) => `${input.repository}${document.path}:${line}`;
+        const cite = (line, path) => {
+            if (path === undefined || exists(path) || !input.history.removed.has(path) && !removedDirectories.has(path) || input.present(path))
+                return;
+            const key = `${line}\0${path}`;
+            if (reported.has(key))
+                return;
+            reported.add(key);
+            const renamed = successor(path);
+            findings.push({ severity: 'error', code: 'DOCS_REFERENCE_REMOVED', target: where(line),
+                message: renamed === undefined
+                    ? `${where(line)} cites ${path}, which the repository history removed`
+                    : `${where(line)} cites ${path}, which the repository history renamed to ${renamed}`,
+                fix: 'cite the path that replaced it (a rename is named in the message), or rewrite or delete the sentence if what it described is gone; then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+        };
+        const citeTargets = (line, text) => {
+            for (const target of citedTargets(text)) {
+                const key = `${line}\0make ${target}`;
+                if (input.targets.has(target) || !input.history.targets.has(target) || reported.has(key))
+                    continue;
+                reported.add(key);
+                findings.push({ severity: 'error', code: 'DOCS_TARGET_REMOVED', target: where(line),
+                    message: `${where(line)} runs make ${target}, a target the Makefiles once defined and no longer do`,
+                    fix: 'cite the target or command that replaced it, or rewrite or delete the sentence if the step is gone; then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+            }
+        };
+        for (const row of document.walked.lines) {
+            for (const span of row.prose.matchAll(/(`+)([^`]+)\1/g)) {
+                const value = span[2].trim();
+                if (PATH_SPAN.test(value))
+                    cite(row.line, citedPath(document.path, value, false));
+                else
+                    citeTargets(row.line, value);
+            }
+        }
+        for (const link of document.walked.links)
+            cite(link.line, citedPath(document.path, link.target, true));
+        for (const row of document.walked.fencedLines) {
+            if (SHELL_FENCES.has(row.info.split(/\s+/, 1)[0].toLowerCase()))
+                citeTargets(row.line, row.text.replace(/^\s*[$%>#]\s+/, ''));
+        }
+        // Spans, links and fences are read in separate passes; the report follows the document.
+        const line = (finding) => Number(finding.target.slice(finding.target.lastIndexOf(':') + 1));
+        findings.splice(start, findings.length - start, ...findings.slice(start).sort((left, right) => line(left) - line(right)));
+    }
+    return findings;
+}

package/dist/emit.d.ts

@@ -0,0 +1,22 @@
+import type { CockpitConfig } from './schema.js';
+import type { DocumentedSibling, Gap } from './registry-resolve/registry.js';
+/**
+ * Render a config as `cockpit.toml`.
+ *
+ * The round trip this closes is the acceptance test for the whole schema: a registry read
+ * out of an existing harness, emitted here, and parsed back must mean the same thing. Until
+ * this existed the "round trip" stopped at an in-memory object, which proves the parser
+ * agrees with itself and nothing else.
+ */
+export declare function emitToml(config: CockpitConfig): string;
+/**
+ * Render the gaps a registry draft could not answer, as commented TOML.
+ *
+ * Deliberately emitted as comments rather than placeholder values: a placeholder is a value,
+ * and a value is indistinguishable from an answer the moment the file is read by anything
+ * other than the person who generated it. A blocking gap keeps the config invalid on
+ * purpose, so the schema refuses it until a human writes the real answer.
+ */
+export declare function emitGaps(gaps: readonly Gap[]): string;
+/** The sibling rows as the schema wants them, dropping fields the source did not carry. */
+export declare function toSiblingRows(siblings: readonly DocumentedSibling[]): Record<string, unknown>[];

package/dist/emit.js

@@ -0,0 +1,43 @@
+import { stringify } from 'smol-toml';
+/**
+ * Render a config as `cockpit.toml`.
+ *
+ * The round trip this closes is the acceptance test for the whole schema: a registry read
+ * out of an existing harness, emitted here, and parsed back must mean the same thing. Until
+ * this existed the "round trip" stopped at an in-memory object, which proves the parser
+ * agrees with itself and nothing else.
+ */
+export function emitToml(config) {
+    return stringify(config);
+}
+/**
+ * Render the gaps a registry draft could not answer, as commented TOML.
+ *
+ * Deliberately emitted as comments rather than placeholder values: a placeholder is a value,
+ * and a value is indistinguishable from an answer the moment the file is read by anything
+ * other than the person who generated it. A blocking gap keeps the config invalid on
+ * purpose, so the schema refuses it until a human writes the real answer.
+ */
+export function emitGaps(gaps) {
+    if (gaps.length === 0)
+        return '';
+    const lines = ['# Gaps — cockpit could not read these from its sources.', '#'];
+    for (const g of gaps) {
+        const mark = g.blocking ? 'REQUIRED' : 'optional';
+        lines.push(`# [${mark}] ${g.slug}.${g.field}: ${g.why}`);
+    }
+    return lines.join('\n') + '\n';
+}
+/** The sibling rows as the schema wants them, dropping fields the source did not carry. */
+export function toSiblingRows(siblings) {
+    return siblings.map((s) => ({
+        slug: s.slug,
+        dir: s.dir,
+        ...(s.remote ? { remote: s.remote } : {}),
+        ...(s.branch ? { branch: s.branch } : {}),
+        mount: s.mount.value,
+        acquire: s.acquire.value,
+        var: s.var,
+        purpose: s.purpose,
+    }));
+}

package/dist/entrypoint-kinds.d.ts

@@ -0,0 +1,3 @@
+export declare const ENTRYPOINT_KINDS: readonly ["entrypoint", "origin", "callback_url", "advertised_listener", "cors_origin", "public_base_url"];
+export type EntrypointKind = (typeof ENTRYPOINT_KINDS)[number];
+export declare function isEntrypointKind(value: unknown): value is EntrypointKind;

package/dist/entrypoint-kinds.js

@@ -0,0 +1,11 @@
+export const ENTRYPOINT_KINDS = Object.freeze([
+    'entrypoint',
+    'origin',
+    'callback_url',
+    'advertised_listener',
+    'cors_origin',
+    'public_base_url',
+]);
+export function isEntrypointKind(value) {
+    return typeof value === 'string' && ENTRYPOINT_KINDS.includes(value);
+}