@docsworth/cli 0.2.0 → 0.3.0

package/dist/core/links.js

@@ -0,0 +1,345 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join, posix, sep } from "node:path";
+import { Parser } from "commonmark";
+import { applyEdits } from "./edits.js";
+import { resolveLink } from "./repo.js";
+// A page's links as CommonMark reads them (docs/format-spec.md, "Links"), for lint and for
+// adopt's rewriting.
+// commonmark.js decides: no link in code or HTML, destinations with nested parentheses,
+// link text with nested brackets, reference links through the definitions they use.
+/** Every link and image destination in `body`, in order, as commonmark.js parses it. */
+export function pageLinks(body) {
+    return destinations(new Parser().parse(body));
+}
+function destinations(doc) {
+    return linksIn(doc).map((l) => l.dest);
+}
+/** Each link and image in `doc`, in order: its destination, and what else tells it apart (kind, title, text). */
+function linksIn(doc) {
+    const out = [];
+    const walker = doc.walker();
+    for (let e = walker.next(); e; e = walker.next()) {
+        if (!e.entering || (e.node.type !== "link" && e.node.type !== "image"))
+            continue;
+        // Its own text, not its subtree's: nested images would make that quadratic.
+        let text = "";
+        for (let c = e.node.firstChild; c; c = c.next)
+            if (c.type === "text" || c.type === "code")
+                text += c.literal ?? "";
+        out.push({ dest: e.node.destination ?? "", rest: `${e.node.type}\0${e.node.title ?? ""}\0${text}` });
+    }
+    return out;
+}
+/**
+ * Where each link's destination is written in `body`, for rewriting it in place. A liberal
+ * scanner proposes candidates (after every `](`, and after a definition's `]:`); then
+ * commonmark.js confirms them, all at once. Each candidate gets a token of its own written
+ * just before it, the body is parsed once, and a candidate counts only if some link's or
+ * image's destination is its token followed by what CommonMark reads the candidate as.
+ * Text is only added, never taken away, so the page parses as it did: whatever CommonMark
+ * doesn't link (code, HTML, a definition no link uses) is left out by its own rules, and
+ * candidates may overlap.
+ */
+export function linkSpans(body, nonce = randomNonce) {
+    const byStart = new Map();
+    for (const c of [...inlineCandidates(body), ...definitionCandidates(body)])
+        if (!byStart.has(c.start))
+            byStart.set(c.start, c);
+    const candidates = [...byStart.values()].sort((a, b) => a.start - b.start);
+    if (!candidates.length)
+        return [];
+    // Tokens no destination the page already has could be mistaken for: absent from its text and
+    // from what CommonMark reads (an entity can spell one).
+    const original = linksIn(new Parser().parse(body));
+    const prefix = markerPrefix(body, original.map((l) => l.dest), nonce);
+    if (prefix === null)
+        return [];
+    const tokens = candidates.map((_, i) => `${prefix}${i}x`);
+    const marked = applyEdits(body, candidates.map((c, i) => ({ start: c.start, end: c.start, insert: tokens[i] })));
+    // A token takes no text away, but it can make a link: the line under a bare label (`[d]:`
+    // then `<div>`, or `---`) reads as its destination once a token starts it. So each link in
+    // the tokened page must use up one of the page's own, the same but for the token (its
+    // destination, kind, title and text); a candidate whose token makes one more is out.
+    const own = new Map();
+    const key = (dest, rest) => `${dest}\0${rest}`;
+    for (const l of original)
+        own.set(key(l.dest, l.rest), (own.get(key(l.dest, l.rest)) ?? 0) + 1);
+    const tokenAt = new RegExp(`^${prefix}(\\d+)x`);
+    const anyToken = new RegExp(`${prefix}\\d+x`, "g");
+    const seen = new Map(); // candidate → the destination its token led
+    const made = new Set();
+    for (const l of linksIn(new Parser().parse(marked))) {
+        const m = tokenAt.exec(l.dest);
+        const dest = m ? l.dest.slice(m[0].length) : l.dest;
+        const k = key(dest, l.rest.replace(anyToken, ""));
+        const left = own.get(k) ?? 0;
+        if (left > 0)
+            own.set(k, left - 1);
+        if (!m)
+            continue;
+        const i = Number(m[1]);
+        if (left === 0)
+            made.add(i);
+        seen.set(i, dest);
+    }
+    const spans = candidates.flatMap((c, i) => {
+        const dest = readDestination(c.raw, c.angle);
+        return seen.get(i) === dest && !made.has(i) ? [{ ...c, dest }] : [];
+    });
+    return nonOverlapping(spans);
+}
+const randomNonce = () => `dw${randomBytes(8).toString("hex")}m`;
+/** A random marker prefix the page holds nowhere, in its text or its destinations; null after eight tries. */
+function markerPrefix(body, already, nonce) {
+    for (let tries = 0; tries < 8; tries++) {
+        const prefix = nonce();
+        if (!body.includes(prefix) && !already.some((d) => d.includes(prefix)))
+            return prefix;
+    }
+    return null; // with 64 random bits a try, only a page built against a fixed nonce gets here
+}
+// Nested parentheses a destination may hold. CommonMark lets an implementation set a limit (at
+// least 3); commonmark.js sets none, but without one each `](` on a run of them scanned on through
+// every later `(`: 64 KB of `](` took 1.7 s. A deeper real destination is only unlocated, and
+// lint judges it.
+const MAX_PARENS = 32;
+/** A destination at `at` (whitespace before it skipped), read as CommonMark reads one. */
+function scanDestination(body, at) {
+    let i = at;
+    while (body[i] === " " || body[i] === "\t")
+        i++;
+    if (body[i] === "\r" && body[i + 1] === "\n")
+        i++;
+    if (body[i] === "\n") {
+        i++;
+        while (body[i] === " " || body[i] === "\t")
+            i++;
+    }
+    if (body[i] === "<") {
+        let j = i + 1;
+        while (j < body.length && body[j] !== ">" && body[j] !== "\n" && body[j] !== "<")
+            j += body[j] === "\\" ? 2 : 1;
+        return body[j] === ">" ? { raw: body.slice(i + 1, j), start: i + 1, end: j, angle: true } : null;
+    }
+    let depth = 0;
+    let j = i;
+    for (; j < body.length; j++) {
+        const c = body[j];
+        if (c === "\\" && j + 1 < body.length) {
+            j++;
+            continue;
+        }
+        if (c <= " " || c === "\x7f")
+            break;
+        if (c === "(" && ++depth > MAX_PARENS)
+            return null;
+        else if (c === ")") {
+            if (depth === 0)
+                break;
+            depth--;
+        }
+    }
+    return j > i && depth === 0 ? { raw: body.slice(i, j), start: i, end: j, angle: false } : null;
+}
+function inlineCandidates(body) {
+    const out = [];
+    for (let i = body.indexOf("]("); i >= 0; i = body.indexOf("](", i + 2)) {
+        const c = scanDestination(body, i + 2);
+        if (c)
+            out.push(c);
+    }
+    return out;
+}
+// A definition's label and colon, after any container markers: `>`, list items' bullets and
+// numbers, and indentation.
+const DEFINITION = /^(?:[ \t]*(?:>|(?:[-+*]|\d{1,9}[.)])(?=[ \t])))*[ \t]*\[(?:[^\]\\\n]|\\.){1,999}\]:/gm;
+function definitionCandidates(body) {
+    const out = [];
+    for (const m of body.matchAll(DEFINITION)) {
+        const c = scanDestination(body, m.index + m[0].length);
+        if (c)
+            out.push(c);
+    }
+    return out;
+}
+function nonOverlapping(cs) {
+    const sorted = [...cs].sort((a, b) => a.start - b.start);
+    const out = [];
+    for (const c of sorted)
+        if (!out.length || c.start >= out[out.length - 1].end)
+            out.push(c);
+    return out;
+}
+/** A destination as written, read by CommonMark: escapes and entities applied, encoded. */
+export function readDestination(raw, angle) {
+    const link = new Parser().parse(`[x](${angle ? `<${raw}>` : raw})`).firstChild?.firstChild;
+    return link?.type === "link" ? (link.destination ?? raw) : raw;
+}
+/** A destination that leaves the page's files: a scheme, `//`, or an in-page `#`. */
+export const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+/** A destination's path: no query or fragment, still percent-encoded (`resolveLink` decodes it once). */
+export function linkPath(dest) {
+    return dest.split(/[?#]/)[0];
+}
+/** A path from `linkPath`, decoded: to show, and to match against file names. */
+export function shownPath(path) {
+    try {
+        return decodeURI(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * How lint judges a link's path (from `linkPath`) on the page at `fromPath`: `missing` when it
+ * resolves to nothing in the repo; under the knowledge root, `directory` or `extensionless`
+ * when it names no page or attachment (R8b), since redaction couldn't tell which page it
+ * means; otherwise null.
+ */
+export function linkFault(repoRoot, knowledgeRoot, fromPath, path, opts = {}) {
+    const aliases = opts.aliases ?? (() => []);
+    const target = resolveLink(fromPath, path);
+    const abs = join(repoRoot, target);
+    const rootDir = posix.normalize(knowledgeRoot).replace(/\/+$/, "");
+    const underRoot = target === rootDir || target.startsWith(`${rootDir}/`);
+    if (target.startsWith("..") || !existsSync(abs)) {
+        // A root-relative attachment (`/img/x.png`) a docs site serves from a static directory. A page
+        // isn't one: pages are under the knowledge root.
+        const served = path.startsWith("/") && isAttachment(target) && (opts.staticDirs ?? []).some((d) => servedFrom(repoRoot, d, target));
+        return { target, fault: served ? null : "missing", underRoot };
+    }
+    if (!underRoot) {
+        // A root-relative route that names a directory or an extensionless file of the repo's, and,
+        // read from the knowledge root as a docs site serves it, a page: redaction can't tell which.
+        if (path.startsWith("/") && (statSync(abs).isDirectory() || posix.extname(target).length <= 1)) {
+            const routes = [target, ...(target === "docs" || target.startsWith("docs/") ? [target.slice("docs/".length)] : [])];
+            const pages = [...new Set([...routePages(repoRoot, rootDir, target), ...routes.flatMap(aliases)])].sort();
+            if (pages.length)
+                return { target, fault: "route", underRoot, pages };
+        }
+        return { target, fault: null, underRoot };
+    }
+    // A directory first: one can be named `guide.md`.
+    if (statSync(abs).isDirectory())
+        return { target, fault: "directory", underRoot };
+    // `notes.` has no extension: extname gives a bare dot.
+    return { target, fault: target.endsWith(".md") || posix.extname(target).length > 1 ? null : "extensionless", underRoot };
+}
+/**
+ * The page files under the knowledge root a root-relative route names on a docs site, with or
+ * without a leading `docs/`: each segment a directory or, last, a page, by its name or without
+ * its number prefix (`02-ops` is `ops`); a directory serves its category index. Lint fails a
+ * route this finds that also names a file of the repo's, and adopt lists one only a number prefix
+ * reaches. Dot-directories are skipped, as the loader skips them.
+ */
+export function routePages(repoRoot, rootDir, route) {
+    const named = (name, seg) => name === seg || unprefixed(name) === seg;
+    const list = (dir) => {
+        try {
+            return readdirSync(join(repoRoot, dir), { withFileTypes: true }).filter((e) => !e.name.startsWith(".") || e.isFile());
+        }
+        catch {
+            return [];
+        }
+    };
+    const out = new Set();
+    const routes = [route, ...(route === "docs" || route.startsWith("docs/") ? [route.slice("docs".length)] : [])];
+    for (const r of routes) {
+        const segs = r.split("/").filter(Boolean);
+        let dirs = [rootDir];
+        segs.forEach((seg, i) => {
+            const next = [];
+            for (const d of dirs)
+                for (const e of list(d)) {
+                    if (e.isDirectory() && named(e.name, seg))
+                        next.push(posix.join(d, e.name));
+                    if (i === segs.length - 1 && e.isFile() && e.name.endsWith(".md") && named(e.name.slice(0, -3), seg))
+                        out.add(posix.join(d, e.name));
+                }
+            dirs = next;
+        });
+        for (const d of dirs)
+            for (const e of list(d))
+                if (e.isFile() && e.name.endsWith(".md") && isCategoryIndex(e.name.slice(0, -3), d === rootDir ? undefined : posix.basename(d)))
+                    out.add(posix.join(d, e.name));
+    }
+    return [...out].sort();
+}
+// Docusaurus's default number-prefix parser (plugin-content-docs, numberPrefix.ts): `01-intro`
+// is `intro`, while a date's or version's digits (`2021-01-01-notes`, `1.0-x`) stay.
+const IGNORED_PREFIX = /^\d+[-_.]\d+/;
+const NUMBER_PREFIX = /^\d+\s*[-_.]+\s*([^-_.\s].*)$/;
+/** A file or directory name as Docusaurus routes it: its number prefix removed. */
+export function unprefixed(name) {
+    if (IGNORED_PREFIX.test(name))
+        return name;
+    return NUMBER_PREFIX.exec(name)?.[1] ?? name;
+}
+/** Docusaurus's category index: `index`, `README`, or a file named after its directory. */
+export function isCategoryIndex(stem, dir) {
+    // By the names as written, as Docusaurus compares them: `04-other/other.md` isn't one (a
+    // real build served it at `…/other/other`, 2026-11-13).
+    return ["index", "readme", dir?.toLowerCase()].includes(stem.toLowerCase());
+}
+/**
+ * Where a page's file puts it on a Docusaurus site, as a route without a leading slash: its
+ * path under the knowledge root without number prefixes, a category index at its directory.
+ */
+export function fileRoute(under) {
+    const parts = under.split("/");
+    const stem = parts.pop().replace(/\.md$/, "");
+    const index = isCategoryIndex(stem, parts.at(-1));
+    return posix.join(...parts.map(unprefixed), index ? "" : unprefixed(stem)).replace(/^\.$/, "");
+}
+/** The one route a docs site serves a page at: its `siteRoute`, else its `fileRoute`. */
+export function pageRoute(under, slug, id) {
+    return siteRoute(under, slug, id) ?? fileRoute(under);
+}
+/**
+ * Where a page's own `slug`, or an `id` other than its file name, puts it on a Docusaurus site,
+ * as a route without a leading slash; null when that's where its file is. `under` is its path
+ * under the knowledge root. (A category index routes by its directory whatever its id.)
+ */
+export function siteRoute(under, slug, id) {
+    const parts = under.split("/");
+    const stem = parts.pop().replace(/\.md$/, "");
+    const dirs = parts.map(unprefixed);
+    const index = isCategoryIndex(stem, parts.at(-1));
+    const file = fileRoute(under);
+    let route;
+    if (typeof slug === "string")
+        route = slug.startsWith("/") ? slug : posix.join(...dirs, slug);
+    else if (typeof id === "string" && !index && id !== unprefixed(stem))
+        route = posix.join(...dirs, id);
+    else
+        return null;
+    route = posix.normalize(route).replace(/^\/+|\/+$/g, "").replace(/^\.$/, "");
+    return route === file ? null : route;
+}
+/**
+ * Whether `target` is a file inside static directory `dir`, by real path: a path that climbs out
+ * (`/../../package.json`), a link in it that leads out, or a directory that is itself a link out
+ * of the repo, is nothing the site serves there.
+ */
+export function servedFrom(repoRoot, dir, target) {
+    // A path that climbs (`/../static/a.png`, or `/x/../../static/a.png` once normalized) names what
+    // a browser would make of it, at the site's root: never this file, even when climbing out and
+    // back in lands on it.
+    const path = posix.normalize(target);
+    if (path === ".." || path.startsWith("../"))
+        return false;
+    try {
+        const repo = realpathSync(repoRoot);
+        const base = realpathSync(join(repoRoot, dir));
+        const file = realpathSync(join(base, path));
+        return base.startsWith(`${repo}${sep}`) && file.startsWith(`${base}${sep}`) && statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** A path a static directory can serve: a file with an extension, never a page (`.md`), which lives under the knowledge root. */
+export function isAttachment(path) {
+    return !path.endsWith(".md") && posix.extname(path).length > 1;
+}

package/dist/core/lint.d.ts

@@ -1,4 +1,4 @@
-import { type Repo } from "./repo.js";
+import type { Repo } from "./repo.js";
 export type Severity = "error" | "warning";
 export interface Diagnostic {
     severity: Severity;
@@ -12,6 +12,5 @@ export interface LintResult {
     warnings: number;
     pages: number;
 }
-/** Lint a loaded knowledge repo. Errors fail CI; warnings never do (e.g. overdue pages). */
 export declare function lintRepo(repo: Repo, now: Date): LintResult;
 export declare function formatDiagnostics(result: LintResult): string;

package/dist/core/lint.js

@@ -4,16 +4,26 @@ import { join, posix } from "node:path";
 import { matchRule } from "./codeowners.js";
 import { CONFIG_PATH } from "./config.js";
 import { pageStatus } from "./gate.js";
-import { resolveLink } from "./repo.js";
+import { EXTERNAL, linkFault, linkPath, pageLinks, shownPath, siteRoute } from "./links.js";
+import { printable } from "./printable.js";
 // Directories whose pages must be a given type; elsewhere any type is fine.
 const DIR_TYPES = { runbooks: "runbook", decisions: "adr", services: "service" };
 const ADR_FILENAME = /^ADR-\d{4}-[a-z0-9-]+\.md$/;
 /** Lint a loaded knowledge repo. Errors fail CI; warnings never do (e.g. overdue pages). */
+// Links as CommonMark reads them (R8: none in code or HTML, reference links through their
+// definitions), relative ones only, as written apart from encoding, without query or fragment.
+function lintedLinks(body) {
+    return pageLinks(body)
+        .filter((d) => d && !EXTERNAL.test(d))
+        .map(linkPath)
+        .filter(Boolean);
+}
 export function lintRepo(repo, now) {
     const out = [];
     const err = (path, rule, message) => out.push({ severity: "error", path, rule, message });
     const warn = (path, rule, message) => out.push({ severity: "warning", path, rule, message });
     const root = repo.config.knowledge_root;
+    const extraFields = new Set(repo.config.frontmatter.extra_fields);
     // Repo-level structure.
     if (!repo.codeowners.path)
         err("CODEOWNERS", "codeowners-missing", "no CODEOWNERS file (.github/, root or docs/)");
@@ -82,20 +92,43 @@ export function lintRepo(repo, now) {
         else
             seen.set(p.id, p.path);
     }
+    // The routes pages' slugs and ids give them, once, when a link first needs them.
+    let aliasMap;
+    const aliases = (route) => {
+        if (!aliasMap) {
+            aliasMap = new Map();
+            for (const p of repo.pages) {
+                const r = siteRoute(p.path.slice(root.length + 1), p.slug, p.id);
+                if (r !== null)
+                    aliasMap.set(r, [...(aliasMap.get(r) ?? []), p.path]);
+            }
+        }
+        return aliasMap.get(route) ?? [];
+    };
     for (const page of repo.pages) {
         const status = pageStatus(page, repo, now);
         if (status.ownership_problem)
             err(page.path, "ownership", status.ownership_problem);
-        for (const link of page.links) {
-            const target = resolveLink(page.path, link);
-            if (target.startsWith("..") || !existsSync(join(repo.root, target)))
+        for (const path of lintedLinks(page.body)) {
+            // Under the knowledge root a link names a page or an attachment. A directory or a file
+            // with no extension names no page redaction could recognize (a Docusaurus route, say).
+            const { target, fault, pages } = linkFault(repo.root, root, page.path, path, { aliases, staticDirs: repo.config.static_dirs });
+            const link = shownPath(path);
+            if (fault === "missing")
                 err(page.path, "broken-link", `link to \`${link}\` does not resolve (${target})`);
+            else if (fault === "directory")
+                err(page.path, "broken-link", `link to \`${link}\` names a directory, not a page; link the page (\`${link.replace(/\/+$/, "")}/….md\`)`);
+            else if (fault === "extensionless")
+                err(page.path, "broken-link", `link to \`${link}\` names a file with no extension, not a page; link a page (\`.md\`) or an attachment`);
+            else if (fault === "route")
+                err(page.path, "broken-link", `link to \`${link}\` names ${target}, outside the knowledge root, and on a docs site the page ${pages.join(" or ")}: link the one you mean, with its extension`);
         }
         for (const id of page.supersedes ?? [])
             if (!seen.has(id))
                 warn(page.path, "supersedes-unknown", `supersedes \`${id}\`, which is not a page in this repo`);
         for (const f of page.unknownFields)
-            warn(page.path, "unknown-field", `unknown frontmatter field \`${f}\``);
+            if (!extraFields.has(f))
+                warn(page.path, "unknown-field", `unknown frontmatter field \`${f}\``);
         const dir = page.path.slice(root.length + 1).split("/")[0] ?? "";
         const wantType = DIR_TYPES[dir];
         if (wantType && page.type !== wantType)
@@ -109,7 +142,8 @@ export function lintRepo(repo, now) {
     return { diagnostics: out, errors, warnings: out.length - errors, pages: repo.pages.length + repo.invalid.length };
 }
 export function formatDiagnostics(result) {
-    const lines = result.diagnostics.map((d) => `${d.path}: ${d.severity} [${d.rule}] ${d.message}`);
+    // Paths and messages quote what pages hold: printed escaped, one diagnostic to a line.
+    const lines = result.diagnostics.map((d) => `${printable(d.path)}: ${d.severity} [${d.rule}] ${printable(d.message)}`);
     lines.push(`${result.pages} pages, ${result.errors} errors, ${result.warnings} warnings`);
     return lines.join("\n");
 }

package/dist/core/mcp/server.js

@@ -87,6 +87,7 @@ export function createMcpServer(service, opts = {}) {
             applies_to: z.string().optional().describe("Only pages that apply to this, e.g. `service:payments`"),
             include_stale: z.boolean().optional().describe("Also return non-citable pages inline, labeled with `gate`"),
             limit: z.number().int().min(1).max(25).optional(),
+            snippets: z.enum(["markdown", "text"]).optional().describe("`text`: snippets as a reader sees the page, without markup. Default `markdown`"),
         },
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, (args) => after(run(() => service.search(args)))));
@@ -162,11 +163,19 @@ export function createMcpServer(service, opts = {}) {
     if (opts.surface === "http") {
         const view = { readOnlyHint: true, openWorldHint: false };
         registered.set("ui_capabilities", server.registerTool("ui_capabilities", { title: "Capabilities", description: "For the Docsworth web app: who is served, in which mode, and whether writes would work.", inputSchema: {}, annotations: view }, () => after(run(() => service.uiCapabilities()))));
-        registered.set("ui_overview", server.registerTool("ui_overview", { title: "Overview", description: "For the Docsworth web app: counts of the caller's visible pages, by team, with what is due soon and what is stale.", inputSchema: {}, annotations: view }, () => after(run(() => service.uiOverview()))));
+        registered.set("ui_overview", server.registerTool("ui_overview", {
+            title: "Overview",
+            description: "For the Docsworth web app: counts of the caller's visible pages, by team, with what is due soon and what is stale.",
+            inputSchema: { list_limit: z.number().int().min(1).max(1000).optional().describe("At most this many of each list: the most pressing first") },
+            annotations: view,
+        }, (args) => after(run(() => service.uiOverview(args)))));
         registered.set("ui_graph", server.registerTool("ui_graph", {
             title: "Link graph",
             description: "For the Docsworth web app: the caller's visible pages and the links between them, or one team's.",
-            inputSchema: { owner_team: z.string().optional().describe("Only this team's pages") },
+            inputSchema: {
+                owner_team: z.string().optional().describe("Only this team's pages"),
+                max_nodes: z.number().int().min(1).max(500).optional().describe("At most this many pages: the most-linked ones"),
+            },
             annotations: view,
         }, (args) => after(run(() => service.uiGraph(args)))));
         registered.set("ui_page", server.registerTool("ui_page", {

package/dist/core/printable.d.ts

@@ -0,0 +1,4 @@
+/** `text` with control and bidirectional characters written as escapes (`\x1b`, `\u202e`). */
+export declare function printable(text: string): string;
+/** `value` as JSON, every such character a `\u` escape: JSON.stringify leaves C1 and bidirectional ones as they are. */
+export declare function printableJson(value: unknown): string;

package/dist/core/printable.js

@@ -0,0 +1,16 @@
+// Text a page holds, made safe to print on a terminal: a decoded link, a frontmatter value or a
+// file name could carry escape sequences that clear or spoof a report, line breaks that fake
+// another line, or bidirectional overrides that reorder it.
+// C0 and C1 controls, Unicode's Bidi_Control set, and its line and paragraph separators.
+const UNPRINTABLE = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+// The same but C0, which JSON.stringify escapes inside strings and uses outside them (a newline).
+const UNPRINTABLE_IN_JSON = /[\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+const hex = (c, width) => c.charCodeAt(0).toString(16).padStart(width, "0");
+/** `text` with control and bidirectional characters written as escapes (`\x1b`, `\u202e`). */
+export function printable(text) {
+    return text.replace(UNPRINTABLE, (c) => (c.charCodeAt(0) < 0x100 ? `\\x${hex(c, 2)}` : `\\u${hex(c, 4)}`));
+}
+/** `value` as JSON, every such character a `\u` escape: JSON.stringify leaves C1 and bidirectional ones as they are. */
+export function printableJson(value) {
+    return JSON.stringify(value, null, 2).replace(UNPRINTABLE_IN_JSON, (c) => `\\u${hex(c, 4)}`);
+}

package/dist/core/references.d.ts

@@ -29,6 +29,21 @@ export interface PageNames {
     depth: number;
     /** The knowledge repo's URL prefixes on GitHub (`github.com/acme/knowledge/`), if it's there. */
     repoUrls: string[];
+    /** Each page's one route on a docs site (`pageRoute`) → whether it's hidden (hidden wins a shared route). */
+    routes: Map<string, boolean>;
+    /** Hidden pages' paths under the root without `.md`: a link by a file's stem (`sec/1.0-release`). */
+    stems: Set<string>;
+    /** For each loaded page's repo path, the directories its URL reads a relative link from. */
+    urlDirs: Map<string, string[]>;
+    /** `site_url`'s host (port included), path prefix (no trailing slash), host name, and where that name starts a token's URL. */
+    site?: {
+        host: string;
+        prefix: string;
+        name: string;
+        at: RegExp;
+    };
+    /** Whether a repo path, as written (not folded), is a file or directory in the repo. */
+    exists: (repoPath: string) => boolean;
     /** The same, folded as rendered text (`foldRendered`), for the rendered view. */
     rendered?: PageNames;
 }
@@ -37,11 +52,31 @@ export declare function pageNames(repo: Repo, hidden: (page: Page) => boolean):
  * Whether a link destination, as written on page `from`, leads to a hidden page: one
  * that resolves to it, or a URL that ends with its path. A path under the knowledge root
  * that is no loaded page fails closed: a page that didn't load has no trustworthy ACL.
- * `html` for an attribute in raw HTML, where backslash escapes don't apply.
+ * `html` for an attribute in raw HTML, where backslash escapes don't apply. `links`, the
+ * text's CommonMark links (`linkPaths`): a route naming nothing fails closed only where it's
+ * one of them (or an attribute's), not where only the liberal reading finds it (`[^1]: The
+ * note`, `[term]: word`); a hidden page's route hides it wherever it stands.
  */
-export declare function destinationHides(dest: string, from: string, names: PageNames, html?: boolean): boolean;
+export declare function destinationHides(dest: string, from: string, names: PageNames, html?: boolean, links?: ReadonlySet<string>): boolean;
+/** The paths of `text`'s links and images, as commonmark.js parses them (`commonmarkPath`). */
+export declare function linkPaths(text: string): Set<string>;
+/**
+ * CommonMark's link definitions in `text`, the first for each label (keyed as `normalLabel`
+ * keys a label) → its destination; undefined where commonmark.js doesn't say.
+ */
+export declare function definitionsIn(text: string): Map<string, string> | undefined;
+/**
+ * The lines of `text` holding a reference to one of `labels` (definitions that go): left, a
+ * reference shows its label as text, in whatever container (code review, round 1: `> [HSM]`
+ * over `> [HSM]: …`), or before a `:` (`[ref]:` that can't start a definition is one).
+ * Matched as CommonMark matches labels (case, runs of space, and space inside the brackets
+ * aside), anywhere on a line.
+ */
+export declare function labelLines(text: string, labels: Iterable<string>): Set<number>;
+/** A label as CommonMark compares labels: runs of space one space, case folded as Unicode folds it (`ß` is `SS`: code review, round 2). */
+export declare const normalLabel: (s: string) => string;
 /** The lines of `text`, on page `from`, that name a hidden page: see the module comment. */
-export declare function namingLines(text: string, from: string, names: PageNames, depth?: number, inherited?: string[]): Set<number>;
+export declare function namingLines(text: string, from: string, names: PageNames, depth?: number, inherited?: string[], liberal?: boolean, gone?: Set<string>): Set<number>;
 /**
  * The lines of `text` where `find`, run over each view the sweep reads (as prose and
  * joined, with and without CommonMark's escapes, and as rendered), reports a span. For