@docsworth/cli 0.2.0 → 0.3.0

package/dist/core/config.d.ts

@@ -19,7 +19,9 @@ declare const MirrorSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "kind">;
 export declare const ConfigSchema: z.ZodObject<{
     format: z.ZodDefault<z.ZodLiteral<1>>;
-    knowledge_root: z.ZodDefault<z.ZodString>;
+    knowledge_root: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    static_dirs: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+    site_url: z.ZodOptional<z.ZodString>;
     github: z.ZodObject<{
         org: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
         repo: z.ZodOptional<z.ZodString>;
@@ -40,6 +42,9 @@ export declare const ConfigSchema: z.ZodObject<{
     skills: z.ZodDefault<z.ZodObject<{
         out_dir: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
+    frontmatter: z.ZodDefault<z.ZodObject<{
+        extra_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     mirror: z.ZodDefault<z.ZodObject<{
         out_dir: z.ZodDefault<z.ZodString>;
         sources: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/core/config.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, posix } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
 import { UserError } from "./errors.js";
@@ -26,9 +26,47 @@ const MirrorSourceSchema = z.discriminatedUnion("kind", [
         acl: z.string().default("internal"),
     }),
 ]);
+/**
+ * A directory in the repo, in one spelling: `knowledge/`, `./knowledge` and `knowledge//` are
+ * `knowledge`, since paths join to it and a trailing slash would double. It's named relative to
+ * the repo, which redaction and CODEOWNERS paths are built on: the repo itself (`.`, or `/`,
+ * which a join makes the same), a directory above it, an absolute path and a Windows separator
+ * are refused. So are git's own directory (a ref named `x.md` is a file adopt would write) and
+ * Docsworth's state.
+ */
+function repoDir(what) {
+    return z
+        .string()
+        .transform((s) => posix.normalize(s).replace(/(.)\/+$/, "$1"))
+        .refine((s) => s !== "." && s !== ".." && !s.startsWith("../") && !s.startsWith("/") && !/^[A-Za-z]:/.test(s) && !s.includes("\\"), `${what} is a directory in the repo, named relative to it: not the repo itself (.), not above it (..), not absolute; such as \`knowledge\``)
+        .refine((s) => !s.split("/").some((seg) => seg.toLowerCase() === ".git") && !/^\.knowledge(\/|$)/i.test(s), `${what} can't be in git's own directory (.git) or Docsworth's (.knowledge)`);
+}
 export const ConfigSchema = z.object({
     format: z.literal(1).default(1),
-    knowledge_root: z.string().default("knowledge"),
+    knowledge_root: repoDir("the knowledge root").default("knowledge"),
+    /**
+     * Directories a docs site serves at its root (Docusaurus's `static/`): lint reads a
+     * root-relative attachment link (`/img/x.png`) from them too.
+     */
+    static_dirs: z.array(repoDir("a static directory")).default([]),
+    /**
+     * Where the team's docs site serves the pages, as `https://docs.example.com/docs/`.
+     * Redaction reads a link to a URL under it as the route it names.
+     */
+    site_url: z
+        .string()
+        .url()
+        .superRefine((u, ctx) => {
+        // `.url()` has reported a value that isn't one; this runs all the same.
+        const at = URL.canParse(u) ? new URL(u) : undefined;
+        if (!at)
+            return;
+        if (at.protocol !== "https:" && at.protocol !== "http:")
+            ctx.addIssue({ code: "custom", message: "site_url must be an http or https URL" });
+        else if (at.username || at.password || at.search || at.hash)
+            ctx.addIssue({ code: "custom", message: "site_url is an origin and a path, with no credentials, query or fragment" });
+    })
+        .optional(),
     github: z.object({
         /** Team owners resolve to @<org>/<team>. Required even for local-only repos. */
         org: z.string().min(1).transform((s) => s.toLowerCase()),
@@ -69,6 +107,12 @@ export const ConfigSchema = z.object({
         .refine((a) => !a.required || a.enabled, { message: "audit_log.required needs audit_log.enabled: true (otherwise nothing is audited)" })
         .default({ enabled: false, include_queries: false, required: false, retention_days: 365 }),
     skills: z.object({ out_dir: z.string().default("skills") }).default({ out_dir: "skills" }),
+    /** Keys a site generator keeps in frontmatter (Docusaurus's `sidebar_position`, say): lint doesn't warn on them. */
+    frontmatter: z
+        .object({ extra_fields: z.array(z.string().min(1)).default([]) })
+        // `extra_field:` must fail, not quietly leave every key warned on.
+        .strict()
+        .default({ extra_fields: [] }),
     mirror: z
         .object({
         out_dir: z.string().default(".knowledge/mirror"),

package/dist/core/edits.d.ts

@@ -0,0 +1,13 @@
+export interface Edit {
+    /** Start offset in the original text. */
+    start: number;
+    /** End offset (exclusive) in the original text. */
+    end: number;
+    insert: string;
+}
+/**
+ * `text` with each edit applied at its original offsets, rebuilt in one pass after sorting the
+ * edits (O(E log E) plus the text, not once per edit). Edits must not overlap; ones at the same
+ * offset apply in the order given.
+ */
+export declare function applyEdits(text: string, edits: readonly Edit[]): string;

package/dist/core/edits.js

@@ -0,0 +1,20 @@
+// Replacing ranges of a text by their original offsets: every rewrite `adopt` and `verify`
+// make goes through here, so one edit never shifts another's place.
+/**
+ * `text` with each edit applied at its original offsets, rebuilt in one pass after sorting the
+ * edits (O(E log E) plus the text, not once per edit). Edits must not overlap; ones at the same
+ * offset apply in the order given.
+ */
+export function applyEdits(text, edits) {
+    const sorted = edits.map((e, i) => ({ e, i })).sort((a, b) => a.e.start - b.e.start || a.e.end - b.e.end || a.i - b.i);
+    const parts = [];
+    let at = 0;
+    for (const { e } of sorted) {
+        if (e.start < at)
+            throw new Error(`edits overlap at offset ${e.start}`);
+        parts.push(text.slice(at, e.start), e.insert);
+        at = e.end;
+    }
+    parts.push(text.slice(at));
+    return parts.join("");
+}

package/dist/core/frontmatter.d.ts

@@ -13,5 +13,17 @@ export declare const FRONTMATTER_MAX: number;
  * isn't a plain number/bool/null stays a string, so dates round-trip exactly.
  */
 export declare function splitFrontmatter(text: string): SplitDoc;
+export interface FrontmatterSpan {
+    /** Where the YAML starts: just after the opening `---` line. */
+    start: number;
+    /** Where it ends, before the closing `---` line's own line break. */
+    end: number;
+    /** Where the body starts, after the closing `---` line. */
+    bodyStart: number;
+    /** The opening line's line ending. */
+    eol: "\n" | "\r\n";
+}
+/** Where a page's frontmatter sits in `text`, by offset; null without a terminated block. */
+export declare function frontmatterSpan(text: string): FrontmatterSpan | null;
 /** Serialize frontmatter + body back to a markdown file (used by writes and promote). */
 export declare function joinFrontmatter(yaml: string, body: string): string;

package/dist/core/frontmatter.js

@@ -10,15 +10,13 @@ const CLOSE = /\r?\n---[ \t]*(\r?\n|$)/;
  * isn't a plain number/bool/null stays a string, so dates round-trip exactly.
  */
 export function splitFrontmatter(text) {
-    const open = OPEN.exec(text);
-    if (!open)
+    if (!OPEN.test(text))
         return { data: null, body: text, error: "missing frontmatter block" };
-    const rest = text.slice(open[0].length);
-    const close = CLOSE.exec(rest);
-    if (!close)
+    const span = frontmatterSpan(text);
+    if (!span)
         return { data: null, body: text, error: "unterminated frontmatter block" };
-    const yamlSrc = rest.slice(0, close.index);
-    const body = rest.slice(close.index + close[0].length);
+    const yamlSrc = text.slice(span.start, span.end);
+    const body = text.slice(span.bodyStart);
     // A page's frontmatter is a few hundred bytes; YAML parsing slows past linear on
     // hostile input (64 KB of `}&`: 650 ms, paid on every reload).
     if (Buffer.byteLength(yamlSrc, "utf8") > FRONTMATTER_MAX)
@@ -34,6 +32,17 @@ export function splitFrontmatter(text) {
         return { data: null, body, error: `invalid YAML: ${err.message.split("\n")[0]}` };
     }
 }
+/** Where a page's frontmatter sits in `text`, by offset; null without a terminated block. */
+export function frontmatterSpan(text) {
+    const open = OPEN.exec(text);
+    if (!open)
+        return null;
+    const start = open[0].length;
+    const close = CLOSE.exec(text.slice(start));
+    if (!close)
+        return null;
+    return { start, end: start + close.index, bodyStart: start + close.index + close[0].length, eol: open[0].length === 5 ? "\r\n" : "\n" };
+}
 /** Serialize frontmatter + body back to a markdown file (used by writes and promote). */
 export function joinFrontmatter(yaml, body) {
     return `---\n${yaml.trimEnd()}\n---\n${body.startsWith("\n") ? body : `\n${body}`}`;

package/dist/core/gfm.d.ts

@@ -0,0 +1,13 @@
+import { Node } from "commonmark";
+/**
+ * commonmark.js's tree for `markdown`, with GFM tables as tables (see above). The placeholder
+ * is never a link or an image, whatever a page writes around it: a definition for it, a
+ * `(target)` or `[label]` right after the link redaction replaced, or a link around it. A
+ * link or image labelled "restricted page" becomes the placeholder's text, and one whose
+ * label holds the placeholder becomes its label's text.
+ */
+export declare function parseGfm(markdown: string): Node;
+/** The text and code inside `node`: a link's or image's label, as the reader sees it. */
+export declare function textIn(node: Node): string;
+/** A table cell (`th` or `td`) in a tree from `parseGfm`; its children are the cell's content. */
+export declare function isTableCell(node: Node): boolean;

package/dist/core/gfm.js

@@ -0,0 +1,244 @@
+// GFM tables on commonmark.js: the parse the web app renders pages from
+// (packages/ui/src/markdown.ts), and search's text snippets read (`plainText` in
+// search.ts), so a snippet holds exactly the words the page shows.
+import { Node, Parser } from "commonmark";
+/**
+ * Whether a line, indented as it was, starts a block of its own: CommonMark's own grammar,
+ * by parsing the line alone. A table row is a paragraph; a list item, indented code or an
+ * HTML tag isn't, and in GFM it ends the table.
+ */
+function startsBlock(line, indent) {
+    const first = new Parser().parse(" ".repeat(indent) + line).firstChild;
+    return first !== null && first.type !== "paragraph";
+}
+/** A row's cells: outer pipes optional, `\|` is a pipe inside a cell (in code too, as GFM). */
+function cellsOf(line) {
+    let s = line.trim();
+    if (s.startsWith("|"))
+        s = s.slice(1);
+    if (s.endsWith("|") && !s.endsWith("\\|"))
+        s = s.slice(0, -1);
+    return s.split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, "|"));
+}
+/** The alignments a delimiter row (`| :--- | ---: |`) sets, or null if the line isn't one. */
+function delimiterRow(line) {
+    if (!line.includes("|"))
+        return null;
+    const cells = cellsOf(line);
+    if (!cells.every((c) => /^:?-+:?$/.test(c)))
+        return null;
+    return cells.map((c) => (c.startsWith(":") ? (c.endsWith(":") ? "center" : "left") : c.endsWith(":") ? "right" : null));
+}
+/** A node that renders as the given fixed tags around its children. Blocks get their own line. */
+function custom(type, onEnter, onExit) {
+    const n = new Node(type);
+    n.onEnter = onEnter;
+    n.onExit = onExit;
+    return n;
+}
+/**
+ * Replace `block` (a paragraph, or a setext heading with its `underline`) with the table its
+ * text holds, if it holds one. `info[i]` is what line i was.
+ */
+function rebuildTable(block, text, info, underline, budget, inlines, blocks) {
+    const lines = text.replace(/\n$/, "").split("\n");
+    const endsTable = (i) => info[i]?.lazy || startsBlock(lines[i], info[i]?.indent ?? 0);
+    for (let h = 0; h + 1 < lines.length; h++) {
+        if (info[h]?.lazy || info[h + 1]?.lazy)
+            continue;
+        const align = delimiterRow(lines[h + 1]);
+        if (!align || cellsOf(lines[h]).length !== align.length)
+            continue;
+        let end = h + 2;
+        while (end < lines.length && !endsTable(end))
+            end++;
+        const setext = block.type === "heading";
+        const rule = setext && /^-{3,}$/.test(underline);
+        const early = end < lines.length;
+        const bodyLines = [...lines.slice(h + 2, end), ...(setext && !rule && !early ? [underline] : [])];
+        // Padding a short row costs no input, so a table's cells could outgrow the page by far
+        // (800 header cells and 800 one-cell rows). A table past the page's budget stays text.
+        const cells = align.length * (1 + bodyLines.length);
+        if (cells > budget.cells)
+            return;
+        budget.cells -= cells;
+        const row = (line, tag) => {
+            const tr = custom("custom_block", "<tr>", "</tr>");
+            const cells = cellsOf(line);
+            align.forEach((a, i) => {
+                const cell = custom("custom_inline", a ? `<${tag} class="dw-align-${a}">` : `<${tag}>`, `</${tag}>`);
+                const content = inlines(cells[i] ?? "");
+                while (content.firstChild)
+                    cell.appendChild(content.firstChild);
+                tr.appendChild(cell);
+            });
+            return tr;
+        };
+        const table = custom("custom_block", '<div class="dw-table-scroll"><table>', "</table></div>");
+        const head = custom("custom_block", "<thead>", "</thead>");
+        head.appendChild(row(lines[h], "th"));
+        table.appendChild(head);
+        if (bodyLines.length > 0) {
+            const body = custom("custom_block", "<tbody>", "</tbody>");
+            for (const line of bodyLines)
+                body.appendChild(row(line, "td"));
+            table.appendChild(body);
+        }
+        if (h > 0)
+            block.insertBefore(inlines(lines.slice(0, h).join("\n")));
+        block.insertBefore(table);
+        if (early) {
+            // The lines after the table, indented as they were, read as blocks again.
+            const rest = blocks(lines.slice(end).map((line, i) => " ".repeat(info[end + i]?.indent ?? 0) + line).join("\n"));
+            while (rest.firstChild)
+                block.insertBefore(rest.firstChild);
+        }
+        if (rule)
+            block.insertBefore(new Node("thematic_break"));
+        else if (setext && early)
+            block.insertBefore(inlines(underline));
+        block.unlink();
+        return;
+    }
+}
+/**
+ * commonmark.js's tree, with GFM tables as tables. `refmap`: link definitions from the page
+ * this text was cut from (the blocks after a table), which its own may add to. `budget.left`:
+ * how many more characters may be parsed again after tables, for the whole page. Tables chained
+ * in one paragraph (each ended by a line that can't interrupt it) re-parse ever shorter tails,
+ * which is quadratic, and nests a parse per table; page text is untrusted, so past eight
+ * times the page's length, or 16 tables deep, the tail is read as plain CommonMark instead
+ * (its tables as text). Real pages chain a table or two.
+ */
+function parse(markdown, refmap, budget = { left: 8 * markdown.length, cells: markdown.length }, depth = 0) {
+    const parser = new Parser();
+    const internals = parser;
+    const inline = internals.inlineParser;
+    const { addLine, processInlines } = internals;
+    if (typeof inline?.parse !== "function" || typeof addLine !== "function" || typeof processInlines !== "function")
+        return parser.parse(markdown);
+    internals.processInlines = function (block) {
+        // The tail's own definitions win: GitHub links a label defined again after a table to
+        // that later definition.
+        this.refmap = { ...refmap, ...this.refmap };
+        processInlines.call(this, block);
+    };
+    // Each line a paragraph is given: whether it came lazily (its containers unmatched), and its
+    // indent. Keyed by the paragraph's sourcepos array: commonmark.js updates it in place, and a
+    // setext heading made from the paragraph is given the same array.
+    const lineInfo = new WeakMap();
+    internals.addLine = function () {
+        const key = this.tip.sourcepos;
+        if (this.tip.type === "paragraph" && key) {
+            let lines = lineInfo.get(key);
+            if (!lines)
+                lineInfo.set(key, (lines = []));
+            lines.push({ lazy: !this.allClosed, indent: this.indent });
+        }
+        addLine.call(this);
+    };
+    // The placeholder is never a link definition: redacted, `[term](page.md): word` reads
+    // `[restricted page]: word`, which CommonMark would take as one and drop from the page.
+    const { parseReference } = inline;
+    if (typeof parseReference === "function")
+        inline.parseReference = (s, refmap) => (PLACEHOLDER_DEFINITION.test(s) ? 0 : parseReference.call(inline, s, refmap));
+    const parseInlines = inline.parse.bind(inline);
+    const raw = new Map();
+    inline.parse = (block) => {
+        const text = block._string_content;
+        if ((block.type === "paragraph" || block.type === "heading") && text?.includes("|"))
+            raw.set(block, text);
+        parseInlines(block);
+    };
+    const doc = parser.parse(markdown);
+    const inlines = (text) => {
+        const p = new Node("paragraph");
+        p._string_content = text;
+        parseInlines(p);
+        return p;
+    };
+    const source = markdown.split(/\r\n|\n|\r/);
+    for (const [block, text] of raw) {
+        // Reference definitions are taken from the front of a paragraph: its last lines are the text's.
+        const lines = text.replace(/\n$/, "").split("\n").length;
+        // A setext heading ends on its underline's line, at the underline's last character.
+        const [endLine = 0, endCol = 0] = block.sourcepos?.[1] ?? [];
+        const underline = block.type === "heading" ? (/([=-]+)\s*$/.exec(source[endLine - 1]?.slice(0, endCol) ?? "")?.[1] ?? "") : "";
+        const blocks = (rest) => {
+            if (rest.length > budget.left || depth >= 16)
+                return new Parser().parse(rest);
+            budget.left -= rest.length;
+            return parse(rest, internals.refmap, budget, depth + 1);
+        };
+        rebuildTable(block, text, ((block.sourcepos && lineInfo.get(block.sourcepos)) || []).slice(-lines), underline, budget, inlines, blocks);
+    }
+    return doc;
+}
+/**
+ * `[restricted page]` (`RESTRICTED`, src/core/acl.ts): the placeholder redaction leaves for a
+ * link to a page the caller can't see. Not imported: acl.ts would bring its dependencies into
+ * the web app.
+ */
+const PLACEHOLDER = "[restricted page]";
+const MAX_NESTING = 32;
+const PLACEHOLDER_DEFINITION = /^\[\s*restricted\s+page\s*\]:/i;
+/**
+ * commonmark.js's tree for `markdown`, with GFM tables as tables (see above). The placeholder
+ * is never a link or an image, whatever a page writes around it: a definition for it, a
+ * `(target)` or `[label]` right after the link redaction replaced, or a link around it. A
+ * link or image labelled "restricted page" becomes the placeholder's text, and one whose
+ * label holds the placeholder becomes its label's text.
+ */
+export function parseGfm(markdown) {
+    const doc = parse(markdown);
+    // Links and images nested deeper than MAX_NESTING are read as their text. Each check below
+    // walks what's inside a link, so unbounded nesting would make it quadratic (page text is
+    // untrusted); 32 levels is far past anything a page means.
+    const deep = [];
+    let nesting = 0;
+    const outer = doc.walker();
+    for (let e = outer.next(); e; e = outer.next()) {
+        if (e.node.type !== "link" && e.node.type !== "image")
+            continue;
+        if (!e.entering)
+            nesting--;
+        else if (++nesting > MAX_NESTING)
+            deep.push(e.node);
+    }
+    for (const n of deep) {
+        while (n.firstChild)
+            n.insertBefore(n.firstChild);
+        n.unlink();
+    }
+    // Innermost first: a link is judged by its label once what's inside it is replaced, so an
+    // image inside a link that becomes the placeholder takes the link's target away too.
+    const links = [];
+    const walker = doc.walker();
+    for (let e = walker.next(); e; e = walker.next())
+        if (!e.entering && (e.node.type === "link" || e.node.type === "image"))
+            links.push(e.node);
+    for (const n of links) {
+        const label = textIn(n).replace(/\s+/g, " ").trim();
+        const literal = `[${label.toLowerCase()}]` === PLACEHOLDER ? PLACEHOLDER : label.toLowerCase().includes(PLACEHOLDER) ? label : null;
+        if (literal === null)
+            continue;
+        const text = new Node("text");
+        text.literal = literal;
+        n.insertBefore(text);
+        n.unlink();
+    }
+    return doc;
+}
+/** The text and code inside `node`: a link's or image's label, as the reader sees it. */
+export function textIn(node) {
+    let out = "";
+    const walker = node.walker();
+    for (let e = walker.next(); e; e = walker.next())
+        if (e.entering && (e.node.type === "text" || e.node.type === "code"))
+            out += e.node.literal ?? "";
+    return out;
+}
+/** A table cell (`th` or `td`) in a tree from `parseGfm`; its children are the cell's content. */
+export function isTableCell(node) {
+    return node.type === "custom_inline" && /^<t[hd][\s>]/.test(node.onEnter ?? "");
+}

package/dist/core/links.d.ts

@@ -0,0 +1,82 @@
+/** Every link and image destination in `body`, in order, as commonmark.js parses it. */
+export declare function pageLinks(body: string): string[];
+export interface LinkSpan {
+    /** The destination as CommonMark reads it (escapes and entities applied, percent-encoded). */
+    dest: string;
+    /** The destination as written, `<` `>` aside: `start`/`end` delimit it in the body. */
+    raw: string;
+    start: number;
+    end: number;
+    /** Written in angle brackets (`<…>`), which stay outside start/end. */
+    angle: boolean;
+}
+/**
+ * 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 declare function linkSpans(body: string, nonce?: () => string): LinkSpan[];
+/** A destination as written, read by CommonMark: escapes and entities applied, encoded. */
+export declare function readDestination(raw: string, angle: boolean): string;
+/** A destination that leaves the page's files: a scheme, `//`, or an in-page `#`. */
+export declare const EXTERNAL: RegExp;
+/** A destination's path: no query or fragment, still percent-encoded (`resolveLink` decodes it once). */
+export declare function linkPath(dest: string): string;
+/** A path from `linkPath`, decoded: to show, and to match against file names. */
+export declare function shownPath(path: string): string;
+export type LinkFault = "missing" | "directory" | "extensionless" | "route";
+/**
+ * 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 declare function linkFault(repoRoot: string, knowledgeRoot: string, fromPath: string, path: string, opts?: {
+    /** The pages a slug or an id puts at a route (`siteRoute`), by route. */
+    aliases?: (route: string) => string[];
+    /** Directories a docs site serves at its root (config `static_dirs`). */
+    staticDirs?: readonly string[];
+}): {
+    target: string;
+    fault: LinkFault | null;
+    underRoot: boolean;
+    pages?: string[];
+};
+/**
+ * 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 declare function routePages(repoRoot: string, rootDir: string, route: string): string[];
+/** A file or directory name as Docusaurus routes it: its number prefix removed. */
+export declare function unprefixed(name: string): string;
+/** Docusaurus's category index: `index`, `README`, or a file named after its directory. */
+export declare function isCategoryIndex(stem: string, dir: string | undefined): boolean;
+/**
+ * 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 declare function fileRoute(under: string): string;
+/** The one route a docs site serves a page at: its `siteRoute`, else its `fileRoute`. */
+export declare function pageRoute(under: string, slug: unknown, id: unknown): string;
+/**
+ * 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 declare function siteRoute(under: string, slug: unknown, id: unknown): string | null;
+/**
+ * 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 declare function servedFrom(repoRoot: string, dir: string, target: string): boolean;
+/** A path a static directory can serve: a file with an extension, never a page (`.md`), which lives under the knowledge root. */
+export declare function isAttachment(path: string): boolean;