@cudoment/cudoc 0.4.0 → 0.6.0

package/dist/node/command.js

@@ -0,0 +1,116 @@
+/**
+ * The `cudoc` command line as a function: arguments in, exit code out. The
+ * installed binary (`cli.ts`) runs it with the process's own streams; a test
+ * calls it directly. It is not a package entry point.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadLibrary } from "./library.js";
+import { generateDataset } from "./dataset.js";
+import { checkReferences } from "./check.js";
+import { formatCheckResult } from "./report.js";
+import { collectDocuments, watchDocuments } from "./watch.js";
+export const USAGE = "Usage: cudoc <collect|check|dataset> --config config.mjs [--watch] [--format text|json] [--strict]";
+/**
+ * What the process prints for a failure. cudoc's own errors describe the
+ * document and are printed as they read; anything else keeps its stack, since
+ * it is a fault rather than a finding.
+ */
+export const describeError = (value) => {
+    if (!(value instanceof Error) ||
+        !(/^cudoc[\w-]*: /.test(value.message) || value.message === USAGE))
+        return value;
+    // A finding may wrap what caused it, a parser's message for instance. A
+    // cause the message already repeats, as a block's names its resolver's,
+    // adds nothing.
+    let text = value.message;
+    for (let cause = value.cause; cause !== undefined; cause = cause instanceof Error ? cause.cause : undefined) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        if (!text.includes(reason.replace(/^cudoc[\w-]*: /, "")))
+            text += `\n  caused by: ${reason}`;
+    }
+    return text;
+};
+const processOutput = {
+    out: (text) => console.log(text),
+    error: (value) => console.error(describeError(value)),
+};
+/**
+ * Runs one command. Resolves with the exit code; a `collect --watch` resolves
+ * after its first pass and keeps watching until the process is signalled.
+ */
+export async function runCommand(argv, io = processOutput) {
+    try {
+        const [command] = argv;
+        const flags = new Set(argv.filter((value) => value.startsWith("--")));
+        const configIndex = argv.indexOf("--config");
+        const formatIndex = argv.indexOf("--format");
+        const format = formatIndex === -1 ? "text" : argv[formatIndex + 1];
+        if (!["collect", "check", "dataset"].includes(command ?? "") ||
+            configIndex === -1 ||
+            !argv[configIndex + 1] ||
+            (format !== "text" && format !== "json"))
+            throw new Error(USAGE);
+        const configPath = argv[configIndex + 1];
+        const config = configPath.endsWith(".json")
+            ? JSON.parse(fs.readFileSync(configPath, "utf8"))
+            : (await import(pathToFileURL(path.resolve(configPath)).href)).default;
+        if (command === "dataset") {
+            io.out(JSON.stringify(generateDataset(config)));
+            return 0;
+        }
+        if (command === "check") {
+            // Checking reads the library the last collection published, which is
+            // the one the host build renders from, and writes nothing. It needs no
+            // compiler: a host's collector script keeps that, not this config.
+            const outDir = config.outDir ?? ".cudoc/documents";
+            if (!fs.existsSync(path.join(outDir, "manifest.json")))
+                throw new Error(`cudoc: no collected library in ${outDir}; collect documents before checking them`);
+            const library = loadLibrary(outDir, undefined, config.roots ?? config.sourceRoot);
+            // A stored library keeps no functions: a table column that names an
+            // extractor is checked with the one the same configuration registers.
+            if (config.extractors)
+                library.extractors = config.extractors;
+            const result = checkReferences(library, config.check ?? {});
+            io.out(format === "json"
+                ? JSON.stringify(result, null, 2)
+                : formatCheckResult(result));
+            const blocking = result.issues.filter((issue) => issue.severity === "error" || flags.has("--strict"));
+            return blocking.length ? 1 : 0;
+        }
+        if (flags.has("--watch")) {
+            // The first pass starts from whatever the output directory holds, and
+            // every pass reports what it compiled; a failed pass is a message and
+            // the last good output stays in place.
+            const watcher = watchDocuments(config, {
+                onPass: ({ documentCount, compiled, reused, blocks, reusedBlocks, outDir, elapsed, }) => io.out(JSON.stringify({
+                    documentCount,
+                    compiled,
+                    reused,
+                    blocks,
+                    reusedBlocks,
+                    outDir,
+                    elapsed,
+                })),
+                onError: (error) => io.error(error),
+            });
+            const stop = () => {
+                watcher.close();
+                process.exit(0);
+            };
+            process.on("SIGINT", stop);
+            process.on("SIGTERM", stop);
+            await watcher.ready;
+            return 0;
+        }
+        const { documentCount, outDir } = await collectDocuments(config);
+        io.out(JSON.stringify({ documentCount, outDir }));
+        return 0;
+    }
+    catch (error) {
+        io.error(error);
+        return 1;
+    }
+}
+//# sourceMappingURL=command.js.map

package/dist/node/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/node/command.ts"],"names":[],"mappings":"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"}

package/dist/node/dataset.d.ts

@@ -2,12 +2,25 @@ import { type ProjectionOptions } from "../dataset.js";
 export type DatasetOptions = ProjectionOptions & {
     inputDir: string;
     outDir: string;
+    /**
+     * The collected library the ASTs came from. Its roots tell the generator
+     * where a document's scope segment starts, and its private documents are
+     * left out. Without it, the scope is the first path segment and nothing is
+     * private.
+     */
+    library?: string;
     documents?: string[];
     scopes?: string[];
     projectionId?: string;
     requireVersion?: boolean;
 };
-export declare function generateDataset({ inputDir, outDir, documents, scopes, projectionId, requireVersion, ...projection }: DatasetOptions): {
+/**
+ * The segment that names a document's scope: the first one after the longest
+ * root base that prefixes the id, so `docs/ko/guide` under base `docs` and
+ * `terms/ko/token` under base `terms` both belong to `ko`.
+ */
+export declare const scopeOf: (id: string, bases: readonly string[]) => string;
+export declare function generateDataset({ inputDir, outDir, library, documents, scopes, projectionId, requireVersion, ...projection }: DatasetOptions): {
     schemaVersion: string;
     documentCount: number;
     documents: {

package/dist/node/dataset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../../src/node/dataset.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAUlE,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AACD,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,MAAM,EACN,SAAS,EACT,MAAM,EACN,YAAuB,EACvB,cAAqB,EACrB,GAAG,UAAU,EACd,EAAE,cAAc;;;;YAiBK,MAAM;cAAQ,MAAM;oBAAc,MAAM;;EA+B7D"}
+{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../../src/node/dataset.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAWlE,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AAyBD;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAAI,IAAI,MAAM,EAAE,OAAO,SAAS,MAAM,EAAE,KAAG,MAM9D,CAAA;AAED,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,MAAM,EACN,OAAO,EACP,SAAS,EACT,MAAM,EACN,YAAuB,EACvB,cAAqB,EACrB,GAAG,UAAU,EACd,EAAE,cAAc;;;;YA8BK,MAAM;cAAQ,MAAM;oBAAc,MAAM;;EAiC7D"}

package/dist/node/dataset.js

@@ -2,19 +2,56 @@ import fs from "node:fs";
 import path from "node:path";
 import { validateAstContract } from "../internal/core/ast/validate.js";
 import { projectAst } from "../dataset.js";
+import { LIBRARY_SCHEMA_VERSION } from "./library.js";
 import { hash, sourceFiles, publishDirectory, safePath, posix, writeJson, } from "./storage.js";
-export function generateDataset({ inputDir, outDir, documents, scopes, projectionId = "custom", requireVersion = true, ...projection }) {
+/** What the generator reads from a library manifest, when it is given one. */
+const readLibraryFacts = (library) => {
+    const manifest = JSON.parse(fs.readFileSync(path.join(library, "manifest.json"), "utf8"));
+    if (manifest.schemaVersion !== LIBRARY_SCHEMA_VERSION ||
+        !Array.isArray(manifest.roots) ||
+        !Array.isArray(manifest.documents))
+        throw new Error("cudoc: incompatible document manifest; rebuild documents");
+    return {
+        bases: manifest.roots.map((root) => root.base),
+        privateIds: new Set(manifest.documents
+            .filter((doc) => doc.private)
+            .map((doc) => doc.id)),
+    };
+};
+/**
+ * The segment that names a document's scope: the first one after the longest
+ * root base that prefixes the id, so `docs/ko/guide` under base `docs` and
+ * `terms/ko/token` under base `terms` both belong to `ko`.
+ */
+export const scopeOf = (id, bases) => {
+    const base = [...bases]
+        .filter((candidate) => !candidate || id.startsWith(`${candidate}/`))
+        .sort((a, b) => b.length - a.length)[0];
+    const rest = base ? id.slice(base.length + 1) : id;
+    return rest.split("/")[0];
+};
+export function generateDataset({ inputDir, outDir, library, documents, scopes, projectionId = "custom", requireVersion = true, ...projection }) {
+    const facts = library
+        ? readLibraryFacts(library)
+        : { bases: [""], privateIds: new Set() };
+    // A library's own `manifest.json`, or a `meta.json` beside the documents,
+    // sits at the top of the input; a document of that name deeper down is
+    // still a document.
     const entries = sourceFiles(inputDir, [".json"])
-        .filter((file) => !["manifest.json", "meta.json"].includes(path.basename(file)))
+        .filter((file) => !["manifest.json", "meta.json"].includes(posix(path.relative(inputDir, file))))
         .map((file) => ({
         file,
         id: posix(path.relative(inputDir, file)).replace(/\.json$/, ""),
     }))
+        .filter((entry) => !facts.privateIds.has(entry.id))
         .filter((entry) => (!documents || documents.includes(entry.id)) &&
-        (!scopes || scopes.includes(entry.id.split("/")[0])));
-    for (const id of documents ?? [])
+        (!scopes || scopes.includes(scopeOf(entry.id, facts.bases))));
+    for (const id of documents ?? []) {
+        if (facts.privateIds.has(id))
+            throw new Error(`cudoc: dataset document is private: ${id}`);
         if (!entries.some((e) => e.id === id))
             throw new Error(`cudoc: dataset document missing: ${id}`);
+    }
     const inputs = [];
     publishDirectory(inputDir, outDir, (staging) => {
         for (const { file, id } of entries) {
@@ -38,7 +75,9 @@ export function generateDataset({ inputDir, outDir, documents, scopes, projectio
             projectionId,
             projection,
             documentCount: inputs.length,
-            scopes: scopes ?? [...new Set(entries.map((e) => e.id.split("/")[0]))],
+            scopes: scopes ?? [
+                ...new Set(entries.map((e) => scopeOf(e.id, facts.bases))),
+            ],
             documents: inputs,
         });
     });

package/dist/node/dataset.js.map

@@ -1 +1 @@
-{"version":3,"file":"dataset.js","sourceRoot":"","sources":["../../src/node/dataset.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dataset.js","sourceRoot":"","sources":["../../src/node/dataset.ts"],"names":[],"mappings":"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"}

package/dist/node/glob.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The small glob dialect collection options use to name files.
+ *
+ * Patterns are matched against a document's library path — its root base
+ * followed by its path under the root directory, in POSIX form — so one
+ * vocabulary serves `exclude`, `private` and any later option that names
+ * documents. The dialect is deliberately small: `*` and `?` within a segment,
+ * `**` for any number of segments, and a pattern without `/` matching a file
+ * or directory name anywhere. There are no brace sets, character classes or
+ * negations, because a mistyped pattern that silently matches nothing is
+ * worse than a pattern an author has to spell out.
+ */
+/**
+ * Compiles one pattern. A trailing `**` also matches the directory itself, so
+ * a walker can prune `drafts/**` at `drafts` instead of visiting every file
+ * beneath it.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+/** A predicate over library paths for a list of patterns; empty lists match nothing. */
+export declare function globMatcher(patterns: readonly string[] | undefined, option: string): (libraryPath: string) => boolean;
+//# sourceMappingURL=glob.d.ts.map

package/dist/node/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/node/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA2BpD;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CACzB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACvC,MAAM,EAAE,MAAM,GACb,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAUlC"}

package/dist/node/glob.js

@@ -0,0 +1,61 @@
+/**
+ * The small glob dialect collection options use to name files.
+ *
+ * Patterns are matched against a document's library path — its root base
+ * followed by its path under the root directory, in POSIX form — so one
+ * vocabulary serves `exclude`, `private` and any later option that names
+ * documents. The dialect is deliberately small: `*` and `?` within a segment,
+ * `**` for any number of segments, and a pattern without `/` matching a file
+ * or directory name anywhere. There are no brace sets, character classes or
+ * negations, because a mistyped pattern that silently matches nothing is
+ * worse than a pattern an author has to spell out.
+ */
+const escape = (value) => value.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+const segment = (value) => escape(value).replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
+/**
+ * Compiles one pattern. A trailing `**` also matches the directory itself, so
+ * a walker can prune `drafts/**` at `drafts` instead of visiting every file
+ * beneath it.
+ */
+export function globToRegExp(pattern) {
+    if (typeof pattern !== "string" || !pattern.trim())
+        throw new Error("cudoc: a glob pattern must be a non-empty string");
+    const segments = pattern
+        .replace(/\\/g, "/")
+        .replace(/^\.?\//, "")
+        .split("/")
+        .filter((part) => part !== "" && part !== ".");
+    if (!segments.length || segments.includes(".."))
+        throw new Error(`cudoc: invalid glob pattern: ${pattern}`);
+    if (segments.length === 1 && segments[0] !== "**")
+        return new RegExp(`(?:^|/)${segment(segments[0])}$`);
+    let source = "^";
+    let separator = false;
+    segments.forEach((part, index) => {
+        const last = index === segments.length - 1;
+        if (part === "**") {
+            if (index === 0)
+                source += last ? ".*" : "(?:.*/)?";
+            else
+                source += last ? "(?:/.*)?" : "/(?:.*/)?";
+            separator = false;
+            return;
+        }
+        if (separator)
+            source += "/";
+        source += segment(part);
+        separator = true;
+    });
+    return new RegExp(`${source}$`);
+}
+/** A predicate over library paths for a list of patterns; empty lists match nothing. */
+export function globMatcher(patterns, option) {
+    if (patterns === undefined)
+        return () => false;
+    if (!Array.isArray(patterns) ||
+        patterns.some((pattern) => typeof pattern !== "string"))
+        throw new Error(`cudoc: ${option} must be an array of glob patterns`);
+    const expressions = patterns.map(globToRegExp);
+    return (libraryPath) => expressions.some((expression) => expression.test(libraryPath));
+}
+//# sourceMappingURL=glob.js.map

package/dist/node/glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../../src/node/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAA;AAE5E,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,EAAE,CAChC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAE9D;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;QAChD,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAA;IACrE,MAAM,QAAQ,GAAG,OAAO;SACrB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG,CAAC,CAAA;IAChD,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,gCAAgC,OAAO,EAAE,CAAC,CAAA;IAC5D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI;QAC/C,OAAO,IAAI,MAAM,CAAC,UAAU,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,GAAG,CAAC,CAAA;IACvD,IAAI,MAAM,GAAG,GAAG,CAAA;IAChB,IAAI,SAAS,GAAG,KAAK,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC/B,MAAM,IAAI,GAAG,KAAK,KAAK,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAA;QAC1C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,IAAI,KAAK,KAAK,CAAC;gBAAE,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAA;;gBAC9C,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAA;YAC9C,SAAS,GAAG,KAAK,CAAA;YACjB,OAAM;QACR,CAAC;QACD,IAAI,SAAS;YAAE,MAAM,IAAI,GAAG,CAAA;QAC5B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;QACvB,SAAS,GAAG,IAAI,CAAA;IAClB,CAAC,CAAC,CAAA;IACF,OAAO,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,CAAA;AACjC,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,WAAW,CACzB,QAAuC,EACvC,MAAc;IAEd,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,GAAG,EAAE,CAAC,KAAK,CAAA;IAC9C,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC;QAEvD,MAAM,IAAI,KAAK,CAAC,UAAU,MAAM,oCAAoC,CAAC,CAAA;IACvE,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;IAC9C,OAAO,CAAC,WAAW,EAAE,EAAE,CACrB,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAA;AAClE,CAAC"}

package/dist/node/library.d.ts

@@ -1,6 +1,11 @@
 import type { Root } from "mdast";
-import { type CompiledDocument } from "../markdown.js";
+import type { CompiledDocument } from "../markdown.js";
 import type { DocumentOptions } from "../document.js";
+import type { TableExtractor } from "./resolve-embed.js";
+import { type ResolvedRoot, type SourceRoot } from "./roots.js";
+export type { SourceRoot, ResolvedRoot } from "./roots.js";
+export { resolveRoots, documentIdOf, libraryPathOf, sourceFileOf, } from "./roots.js";
+export { LIBRARY_SCHEMA_VERSION } from "./collect.js";
 export type SourceSnapshot = {
     text: string;
     hash: string;
@@ -14,11 +19,19 @@ export type SourceSnapshot = {
 };
 export type StoredDocument = {
     id: string;
+    /** The library path with its extension: the root base, then the path under the root. */
     sourcePath: string;
     route: string;
     tree: Root;
     source: SourceSnapshot;
     frontmatter: Record<string, unknown>;
+    /**
+     * Set when a `private` pattern matched the document. It is collected and
+     * checked like any other, and left out of exports and datasets.
+     */
+    private?: true;
+    /** Local names the document's own `import` statements bind, when it has any. */
+    imports?: string[];
 };
 export type DocumentCompiler = (source: string, context: {
     id: string;
@@ -30,12 +43,41 @@ export type Library = {
     documents: StoredDocument[];
     options: DocumentOptions;
     configuration: string;
-    sourceRoot?: string;
+    /** Where the documents were read from. Runtime only; a loaded library has it when the caller supplies roots. */
+    roots?: ResolvedRoot[];
+    /** The base of every root, in root order, as the manifest records them. */
+    bases?: string[];
+    /** Cell extractors an embed table may name. Runtime only; their versions are in the configuration. */
+    extractors?: Record<string, TableExtractor>;
     compiler?: DocumentCompiler;
     asyncCompiler?: AsyncDocumentCompiler;
+    /** What an incremental build did. Runtime only; present when `previous` was given. */
+    incremental?: {
+        compiled: string[];
+        reused: string[];
+    };
 };
 export type BuildDocumentsOptions = DocumentOptions & {
-    sourceRoot: string;
+    /** One directory at the top of the library: shorthand for `roots: [{ dir }]`. */
+    sourceRoot?: string;
+    /** Directories to collect, each under its own base. Exactly one of `sourceRoot` and `roots` is given. */
+    roots?: SourceRoot[];
+    /**
+     * Glob patterns, matched against library paths, for files and directories
+     * that are not documents at all: drafts, agent notes, work folders.
+     */
+    exclude?: string[];
+    /**
+     * Glob patterns, matched against library paths, for documents that are
+     * collected and checked but never exported or put in a dataset.
+     */
+    private?: string[];
+    /**
+     * Functions an embed table's `{ extractor }` column may name. Each carries
+     * a `version` that enters the library configuration, so prepared embeds go
+     * stale when an extractor's output changes.
+     */
+    extractors?: Record<string, TableExtractor>;
     outDir?: string;
     routeBase?: string;
     routeSuffix?: string;
@@ -45,12 +87,40 @@ export type BuildDocumentsOptions = DocumentOptions & {
     compiler?: DocumentCompiler;
     /** Identifies external compiler/plugins/configuration for persisted metadata. */
     compilerId?: string;
+    /**
+     * A library collected earlier. A document whose source text is unchanged
+     * is taken from it instead of compiled again, as long as the configuration
+     * hash is the same; a document that is new, changed or collected under a
+     * different configuration compiles as usual. The publication is complete
+     * either way.
+     */
+    previous?: Library;
 };
+/**
+ * Compiles every document and publishes the library to `outDir`, replacing
+ * what was there in one step. Prepared embeds are not part of it: a separate
+ * `prepareEmbeds` adds `embeds.json`, and `collectDocuments` does both into
+ * one publication.
+ */
+export declare function buildDocuments(options: BuildDocumentsOptions): Library;
 /** Collect async framework compilers before publishing or resolving any embeds. */
 export declare function buildDocumentsAsync(options: Omit<BuildDocumentsOptions, "compiler"> & {
     compiler: AsyncDocumentCompiler;
 }): Promise<Library>;
-export declare function snapshotSource(text: string, tree: Root, format: "md" | "mdx"): SourceSnapshot;
-export declare function buildDocuments({ sourceRoot, outDir, compiler, compilerId, routeBase, routeSuffix, routes, ...options }: BuildDocumentsOptions): Library;
-export declare function loadLibrary(outDir?: string, compiler?: DocumentCompiler, sourceRoot?: string): Library;
+export type LoadLibraryOptions = {
+    /**
+     * Keep the loaded documents in memory and reuse them while `manifest.json`
+     * is byte-for-byte unchanged. For a server that renders from the library on
+     * every request; a one-off build has nothing to gain. The documents are
+     * shared between calls, so treat them as read-only.
+     */
+    cache?: boolean;
+};
+/**
+ * Reads a published library back. `roots` restores where the documents live
+ * on disk, which replacement and asset resolution need; a single directory is
+ * the shorthand for one root at the top. The bases given have to be the ones
+ * the library was collected with, because ids were derived from them.
+ */
+export declare function loadLibrary(outDir?: string, compiler?: DocumentCompiler, roots?: string | SourceRoot[], options?: LoadLibraryOptions): Library;
 //# sourceMappingURL=library.d.ts.map

package/dist/node/library.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library.d.ts","sourceRoot":"","sources":["../../src/node/library.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"library.d.ts","sourceRoot":"","sources":["../../src/node/library.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AACjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAGxD,OAAO,EAAgB,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAO7E,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAErD,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,IAAI,GAAG,KAAK,CAAA;IACpB,QAAQ,EAAE,MAAM,CACd,MAAM,EACN;QACE,KAAK,EAAE,MAAM,CAAA;QACb,GAAG,EAAE,MAAM,CAAA;QACX,MAAM,EAAE,MAAM,CAAA;QACd,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;KACjC,CACF,CAAA;CACF,CAAA;AACD,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,cAAc,CAAA;IACtB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB,CAAA;AACD,MAAM,MAAM,gBAAgB,GAAG,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,KAChE,gBAAgB,CAAA;AACrB,MAAM,MAAM,qBAAqB,GAAG,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,KACrC,OAAO,CAAC,gBAAgB,CAAC,CAAA;AAC9B,MAAM,MAAM,OAAO,GAAG;IACpB,SAAS,EAAE,cAAc,EAAE,CAAA;IAC3B,OAAO,EAAE,eAAe,CAAA;IACxB,aAAa,EAAE,MAAM,CAAA;IACrB,gHAAgH;IAChH,KAAK,CAAC,EAAE,YAAY,EAAE,CAAA;IACtB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,sGAAsG;IACtG,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IAC3C,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,aAAa,CAAC,EAAE,qBAAqB,CAAA;IACrC,sFAAsF;IACtF,WAAW,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CACvD,CAAA;AACD,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG;IACpD,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yGAAyG;IACzG,KAAK,CAAC,EAAE,UAAU,EAAE,CAAA;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAItE;AAED,mFAAmF;AACnF,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,IAAI,CAAC,qBAAqB,EAAE,UAAU,CAAC,GAAG;IACjD,QAAQ,EAAE,qBAAqB,CAAA;CAChC,GACA,OAAO,CAAC,OAAO,CAAC,CAIlB;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,MAAM,SAAqB,EAC3B,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,EAC7B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAgET"}