@cudoment/cudoc 0.4.0 → 0.6.0

package/dist/node/storage.js

@@ -23,7 +23,14 @@ export function safePath(root, relative) {
         throw new Error(`cudoc: path escapes document root: ${relative}`);
     return target;
 }
-export function sourceFiles(root, extensions = [".md", ".mdx"]) {
+/**
+ * Every file under `root` with one of the extensions, sorted, as absolute
+ * paths. Dot entries and `node_modules` are always skipped; `exclude` is asked
+ * about each remaining entry's POSIX path relative to `root`, and a directory
+ * it excludes is not entered, so a symlink inside one is never seen.
+ */
+export function sourceFiles(root, extensions = [".md", ".mdx"], options = {}) {
+    const base = path.resolve(root);
     const walk = (dir) => fs
         .readdirSync(dir, { withFileTypes: true })
         .sort((a, b) => a.name.localeCompare(b.name, "en"))
@@ -31,6 +38,8 @@ export function sourceFiles(root, extensions = [".md", ".mdx"]) {
         if (entry.name.startsWith(".") || entry.name === "node_modules")
             return [];
         const file = path.join(dir, entry.name);
+        if (options.exclude?.(posix(path.relative(base, file))))
+            return [];
         if (entry.isSymbolicLink())
             throw new Error(`cudoc: symlink in source tree: ${file}`);
         if (entry.isDirectory())
@@ -39,31 +48,225 @@ export function sourceFiles(root, extensions = [".md", ".mdx"]) {
             ? [file]
             : [];
     });
-    return walk(path.resolve(root));
+    return walk(base);
 }
 export function writeJson(file, value) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify(value));
 }
-/** Only replace directories bearing our ownership marker. Never delete arbitrary output. */
-export function publishDirectory(inputRoot, outputRoot, build) {
+/**
+ * Creates the lock already holding this process's id, or fails with `EEXIST`.
+ *
+ * The id is written to a file of this process's own and linked into place:
+ * `link` fails when the lock exists, as an exclusive open does, and no other
+ * process ever reads the lock before the id is in it. A file system without
+ * hard links gets the exclusive open instead, and the id right after it.
+ */
+function createLock(lock) {
+    const pending = `${lock}.${process.pid}-${crypto.randomUUID()}`;
+    fs.writeFileSync(pending, String(process.pid));
+    try {
+        fs.linkSync(pending, lock);
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw error;
+        const fd = fs.openSync(lock, "wx");
+        try {
+            fs.writeSync(fd, String(process.pid));
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    finally {
+        fs.rmSync(pending, { force: true });
+    }
+}
+/** The process id a lock file names, or `NaN` when it names none. */
+const holderOf = (lock) => {
+    try {
+        return Number.parseInt(fs.readFileSync(lock, "utf8"), 10);
+    }
+    catch {
+        return Number.NaN;
+    }
+};
+const busy = (output, holder) => new Error(`cudoc: ${output} is being written by process ${holder}; wait for it to finish`);
+/**
+ * Takes the lock beside an output directory, holding this process's id, and
+ * then recovers what a killed build left there.
+ *
+ * A lock whose process is gone was left by a build that was killed. A lock
+ * held by a live process is a build still running, which is reported by name
+ * rather than as `EEXIST`. A stale lock is claimed by renaming it, which only
+ * one process can do to that file, and the lock is then taken again before
+ * anything else is touched. A process that found the same stale lock but
+ * renames after another has already taken the lock over finds a live id in
+ * what it moved, puts it back and reports that build instead of taking the
+ * lock from it; one that finds the stale lock already gone tries the lock
+ * again, and gets either the lock or the name of the process that did.
+ *
+ * The staging directory and the backup a killed build was working with are
+ * recovered only by the process holding the lock. A running build's own
+ * directories exist only while it holds the lock, so whatever recovery finds
+ * belongs to no build, and a process that lost the lock cannot remove the
+ * staging directory of the one that won it. The one window left is between
+ * reading a dead id and renaming: a rename that moves a lock another process
+ * took over in that moment is put back, but a third process can create the
+ * lock while it is away. Closing that would need a rename conditioned on the
+ * file's identity, which the file system does not offer.
+ */
+function acquireLock(lock, output) {
+    for (;;) {
+        try {
+            createLock(lock);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const holder = holderOf(lock);
+        if (Number.isInteger(holder) && holder > 0 && processAlive(holder))
+            throw busy(output, holder);
+        const claimed = `${lock}.stale-${process.pid}-${crypto.randomUUID()}`;
+        try {
+            fs.renameSync(lock, claimed);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            // Another process claimed the stale lock first. Whoever takes the lock
+            // next recovers the leftovers; this one touches nothing until then.
+            continue;
+        }
+        const moved = holderOf(claimed);
+        if (moved !== holder &&
+            Number.isInteger(moved) &&
+            moved > 0 &&
+            processAlive(moved)) {
+            try {
+                fs.linkSync(claimed, lock);
+            }
+            catch {
+                // A lock is back in place already; the one moved here is not needed.
+            }
+            fs.rmSync(claimed, { force: true });
+            throw busy(output, moved);
+        }
+        fs.rmSync(claimed, { force: true });
+    }
+    // A leftover that cannot be moved or removed ends this publication, and
+    // the lock goes with it, so the next one in this process can try again.
+    try {
+        recoverLeftovers(output);
+    }
+    catch (error) {
+        fs.rmSync(lock, { force: true });
+        throw error;
+    }
+}
+const OWNER_MARKER = ".cudoc-output";
+const OWNER_TEXT = "cudoc\n";
+/**
+ * Whether `dir` is a directory cudoc wrote: a real directory, not a link to
+ * one, holding the ownership marker with exactly cudoc's text. Replacing an
+ * output and recovering a killed build's leftovers both ask this, so nothing
+ * is moved or removed on a weaker test than the one that guards the output.
+ */
+function ownedDirectory(dir) {
+    try {
+        if (!fs.lstatSync(dir).isDirectory())
+            return false;
+        const marker = path.join(dir, OWNER_MARKER);
+        return (fs.lstatSync(marker).isFile() &&
+            fs.readFileSync(marker, "utf8") === OWNER_TEXT);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Removes a directory `ownedDirectory` accepts, its marker last. A removal
+ * that stops partway, a process killed or a file that cannot go, leaves a
+ * directory that is still owned, which the next recovery finishes.
+ */
+function removeOwned(dir) {
+    if (!fs.existsSync(dir))
+        return;
+    for (const entry of fs.readdirSync(dir))
+        if (entry !== OWNER_MARKER)
+            fs.rmSync(path.join(dir, entry), { recursive: true, force: true });
+    fs.rmSync(dir, { recursive: true, force: true });
+}
+const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** The staging prefix; `mkdtempSync` appends six letters or digits to it. */
+const STAGING = ".cudoc-staging-";
+/**
+ * Puts back the backup and removes the staging directory a killed build left
+ * beside `output`. Called only with the lock held, so nothing found here is a
+ * running build's.
+ *
+ * Only the names this module gives are considered, `<output>.previous-<uuid>`
+ * for a backup and `<output>.cudoc-staging-` and the six letters or digits
+ * `mkdtemp` appends for a staging directory, and only when the directory is
+ * owned, so a copy of an output someone made by hand under another name is
+ * never touched.
+ */
+function recoverLeftovers(output) {
+    const dir = path.dirname(output);
+    const name = escape(path.basename(output));
+    const backup = new RegExp(`^${name}\\.previous-${UUID}$`);
+    const staging = new RegExp(`^${name}${escape(STAGING)}[A-Za-z0-9]{6}$`);
+    for (const entry of fs.readdirSync(dir)) {
+        const leftover = path.join(dir, entry);
+        if (backup.test(entry) && ownedDirectory(leftover)) {
+            if (!fs.existsSync(output))
+                fs.renameSync(leftover, output);
+            else
+                removeOwned(leftover);
+        }
+        else if (staging.test(entry) && ownedDirectory(leftover))
+            removeOwned(leftover);
+    }
+}
+/** Whether a process id names a running process this user can see. */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: it exists but belongs to someone else, which still means running.
+        return error.code === "EPERM";
+    }
+}
+export function publishDirectory(inputRoots, outputRoot, build) {
     if (fs.existsSync(outputRoot) && fs.lstatSync(outputRoot).isSymbolicLink())
         throw new Error("cudoc: output directory must not be a symlink");
-    const input = realPath(inputRoot), output = realPath(outputRoot);
-    if (contained(input, output) || contained(output, input))
-        throw new Error("cudoc: input and output directories overlap");
+    const output = realPath(outputRoot);
+    for (const inputRoot of [inputRoots].flat()) {
+        const input = realPath(inputRoot);
+        if (contained(input, output) || contained(output, input))
+            throw new Error("cudoc: input and output directories overlap");
+    }
     fs.mkdirSync(path.dirname(output), { recursive: true });
-    const owner = path.join(output, ".cudoc-output");
-    if (fs.existsSync(output) &&
-        (!fs.existsSync(owner) || fs.readFileSync(owner, "utf8") !== "cudoc\n"))
+    if (fs.existsSync(output) && !ownedDirectory(output))
         throw new Error(`cudoc: refusing to replace unowned directory: ${output}`);
     const lock = `${output}.lock`;
-    const fd = fs.openSync(lock, "wx");
-    const staging = fs.mkdtempSync(`${output}.tmp-`);
-    const backup = `${output}.previous-${crypto.randomUUID()}`;
+    acquireLock(lock, output);
+    let staging;
     try {
-        fs.writeFileSync(path.join(staging, ".cudoc-output"), "cudoc\n");
-        build(staging);
+        staging = fs.mkdtempSync(`${output}${STAGING}`);
+    }
+    catch (error) {
+        fs.unlinkSync(lock);
+        throw error;
+    }
+    const backup = `${output}.previous-${crypto.randomUUID()}`;
+    const commit = () => {
         if (fs.existsSync(output))
             fs.renameSync(output, backup);
         try {
@@ -74,12 +277,31 @@ export function publishDirectory(inputRoot, outputRoot, build) {
                 fs.renameSync(backup, output);
             throw error;
         }
-        fs.rmSync(backup, { recursive: true, force: true });
-    }
-    finally {
-        fs.rmSync(staging, { recursive: true, force: true });
-        fs.closeSync(fd);
+        removeOwned(backup);
+    };
+    const cleanup = () => {
+        removeOwned(staging);
         fs.unlinkSync(lock);
+    };
+    let result;
+    try {
+        fs.writeFileSync(path.join(staging, OWNER_MARKER), OWNER_TEXT);
+        result = build(staging);
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+    const pending = result;
+    if (typeof pending?.then !== "function") {
+        try {
+            commit();
+        }
+        finally {
+            cleanup();
+        }
+        return;
     }
+    return pending.then(commit).finally(cleanup);
 }
 //# sourceMappingURL=storage.js.map

package/dist/node/storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/node/storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,MAAM,MAAM,aAAa,CAAA;AAEhC,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,EAAE,CACpC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACzD,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACvE,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,MAAc;IACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAC5C,OAAO,CACL,QAAQ,KAAK,EAAE;QACf,CAAC,QAAQ,KAAK,IAAI;YAChB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;YACrC,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAC9B,CAAA;AACH,CAAC;AACD,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACrC,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAA;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAA;AAC7E,CAAC;AACD,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,QAAgB;IACrD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;IAC3C,IACE,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QAE7B,MAAM,IAAI,KAAK,CAAC,sCAAsC,QAAQ,EAAE,CAAC,CAAA;IACnE,OAAO,MAAM,CAAA;AACf,CAAC;AACD,MAAM,UAAU,WAAW,CACzB,IAAY,EACZ,UAAU,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC;IAE5B,MAAM,IAAI,GAAG,CAAC,GAAW,EAAY,EAAE,CACrC,EAAE;SACC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SACzC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;SAClD,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QACjB,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc;YAC7D,OAAO,EAAE,CAAA;QACX,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QACvC,IAAI,KAAK,CAAC,cAAc,EAAE;YACxB,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,EAAE,CAAC,CAAA;QAC3D,IAAI,KAAK,CAAC,WAAW,EAAE;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAA;QAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;YAC1D,CAAC,CAAC,CAAC,IAAI,CAAC;YACR,CAAC,CAAC,EAAE,CAAA;IACR,CAAC,CAAC,CAAA;IACN,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;AACjC,CAAC;AACD,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAc;IACpD,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACrD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;AAC/C,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,UAAkB,EAClB,KAAgC;IAEhC,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,cAAc,EAAE;QACxE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;IAClE,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,EAC/B,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAA;IAC/B,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IAChE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACvD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IAChD,IACE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;QACrB,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,SAAS,CAAC;QAEvE,MAAM,IAAI,KAAK,CAAC,iDAAiD,MAAM,EAAE,CAAC,CAAA;IAC5E,MAAM,IAAI,GAAG,GAAG,MAAM,OAAO,CAAA;IAC7B,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAClC,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,CAAA;IAChD,MAAM,MAAM,GAAG,GAAG,MAAM,aAAa,MAAM,CAAC,UAAU,EAAE,EAAE,CAAA;IAC1D,IAAI,CAAC;QACH,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,SAAS,CAAC,CAAA;QAChE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACxD,IAAI,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;YACxD,MAAM,KAAK,CAAA;QACb,CAAC;QACD,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IACrD,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QACpD,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAA;QAChB,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC;AACH,CAAC"}
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/node/storage.ts"],"names":[],"mappings":"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"}

package/dist/node/watch.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Collection that repeats as sources change.
+ *
+ * A pass is what the CLI's `collect` does once: build the library, then
+ * prepare the embeds. Here every pass after the first hands the previous
+ * library and the previous preparation back in, so only the documents whose
+ * text changed compile again and only the blocks that read a changed document
+ * resolve again. The watcher runs a pass when a file under any root changes,
+ * after a short quiet period, and keeps the last good result when a pass
+ * fails, so a half-typed document is an error message rather than a broken
+ * library.
+ */
+import type { CompiledDocument } from "../markdown.js";
+import { type BuildDocumentsOptions, type Library } from "./library.js";
+import { type PreparedEmbeds } from "./prepare-embeds.js";
+/**
+ * A collection configuration as a config file exports it: the build options,
+ * where the compiler may return its result synchronously or as a promise.
+ */
+export type CollectConfig = Omit<BuildDocumentsOptions, "compiler"> & {
+    compiler?: (...parameters: Parameters<NonNullable<BuildDocumentsOptions["compiler"]>>) => CompiledDocument | Promise<CompiledDocument>;
+};
+/** What one pass produced and how much of it was new. */
+export type CollectionPass = {
+    library: Library;
+    prepared: PreparedEmbeds;
+    documentCount: number;
+    /** Ids of the documents this pass compiled. Every document on a full pass. */
+    compiled: string[];
+    /** Documents taken from the previous library unchanged. */
+    reused: number;
+    /** Embed blocks in the library, and how many were taken from the previous preparation. */
+    blocks: number;
+    reusedBlocks: number;
+    outDir: string;
+    /** Wall-clock milliseconds the pass took. */
+    elapsed: number;
+};
+export type CollectionState = {
+    library?: Library;
+    prepared?: PreparedEmbeds;
+};
+/**
+ * The library and preparation already in `outDir`, when they load and are
+ * worth reusing, so a watcher's first pass compiles only what changed since
+ * the last run. Anything unreadable or incompatible means starting fresh.
+ */
+export declare function previousCollection(outDir?: string): CollectionState;
+/**
+ * One pass: collect, then prepare, then publish both at once. With
+ * `previous`, an unchanged document is not compiled and an unaffected block
+ * is not resolved; the published files are complete either way. Nothing is
+ * written until every embed has resolved, so a pass that fails leaves the
+ * previous library and its prepared embeds in place, still matching.
+ */
+export declare function collectDocuments(config: CollectConfig, previous?: CollectionState): Promise<CollectionPass>;
+export type WatchOptions = {
+    /** Quiet time after the last change before a pass starts, in milliseconds. Default 150. */
+    debounce?: number;
+    /** The result of every pass, the first included. */
+    onPass?: (pass: CollectionPass) => void;
+    /**
+     * A failed pass, or a watcher the system stopped. The watcher keeps the last
+     * good result and keeps running. Default: print the error to stderr.
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * Whether the first pass may start from what `outDir` already holds.
+     * Default true.
+     */
+    reuseOutput?: boolean;
+};
+export type CollectionWatcher = {
+    /** Resolves when the first pass has finished, whether it succeeded or failed. */
+    ready: Promise<void>;
+    /** Stops watching. A pass in progress finishes. */
+    close(): void;
+};
+/**
+ * Collects once, then again whenever a `.md` or `.mdx` file under any root is
+ * created, changed, renamed or deleted. Changes that arrive while a pass runs
+ * start another pass when it finishes, so the output always reflects the
+ * latest files.
+ */
+export declare function watchDocuments(config: CollectConfig, options?: WatchOptions): CollectionWatcher;
+//# sourceMappingURL=watch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/node/watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,OAAO,EACb,MAAM,cAAc,CAAA;AAErB,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGxE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,qBAAqB,EAAE,UAAU,CAAC,GAAG;IACpE,QAAQ,CAAC,EAAE,CACT,GAAG,UAAU,EAAE,UAAU,CAAC,WAAW,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC,KACtE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAClD,CAAA;AAED,yDAAyD;AACzD,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;IACxB,aAAa,EAAE,MAAM,CAAA;IACrB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAA;IACd,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B,CAAA;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,SAAqB,GAC1B,eAAe,CAkBjB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,aAAa,EACrB,QAAQ,GAAE,eAAoB,GAC7B,OAAO,CAAC,cAAc,CAAC,CAmCzB;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAA;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,iFAAiF;IACjF,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACpB,mDAAmD;IACnD,KAAK,IAAI,IAAI,CAAA;CACd,CAAA;AA0BD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,YAAiB,GACzB,iBAAiB,CA2DnB"}

package/dist/node/watch.js

@@ -0,0 +1,174 @@
+/**
+ * Collection that repeats as sources change.
+ *
+ * A pass is what the CLI's `collect` does once: build the library, then
+ * prepare the embeds. Here every pass after the first hands the previous
+ * library and the previous preparation back in, so only the documents whose
+ * text changed compile again and only the blocks that read a changed document
+ * resolve again. The watcher runs a pass when a file under any root changes,
+ * after a short quiet period, and keeps the last good result when a pass
+ * fails, so a half-typed document is an error message rather than a broken
+ * library.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { loadLibrary, resolveRoots, } from "./library.js";
+import { collectLibrary, collectLibraryAsync } from "./collect.js";
+import { prepareEmbeds } from "./prepare-embeds.js";
+import { publishDirectory } from "./storage.js";
+/**
+ * The library and preparation already in `outDir`, when they load and are
+ * worth reusing, so a watcher's first pass compiles only what changed since
+ * the last run. Anything unreadable or incompatible means starting fresh.
+ */
+export function previousCollection(outDir = ".cudoc/documents") {
+    const state = {};
+    try {
+        if (fs.existsSync(path.join(outDir, "manifest.json")))
+            state.library = loadLibrary(outDir);
+    }
+    catch {
+        return {};
+    }
+    try {
+        const file = path.join(outDir, "embeds.json");
+        if (state.library && fs.existsSync(file)) {
+            const prepared = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (prepared?.schemaVersion === 2)
+                state.prepared = prepared;
+        }
+    }
+    catch {
+        delete state.prepared;
+    }
+    return state;
+}
+/**
+ * One pass: collect, then prepare, then publish both at once. With
+ * `previous`, an unchanged document is not compiled and an unaffected block
+ * is not resolved; the published files are complete either way. Nothing is
+ * written until every embed has resolved, so a pass that fails leaves the
+ * previous library and its prepared embeds in place, still matching.
+ */
+export async function collectDocuments(config, previous = {}) {
+    const started = Date.now();
+    const { compiler, ...rest } = config;
+    const options = { ...rest, previous: previous.library };
+    const collection = compiler
+        ? await collectLibraryAsync({
+            ...options,
+            compiler: async (...parameters) => compiler(...parameters),
+        })
+        : collectLibrary(options);
+    const { library, outDir } = collection;
+    // Assigned by the publication below, which throws if preparation fails.
+    let prepared;
+    await publishDirectory(collection.inputs, outDir, async (staging) => {
+        collection.write(staging);
+        prepared = await prepareEmbeds(library, staging, {
+            previous: previous.prepared,
+        });
+    });
+    const keys = Object.keys(prepared.blocks);
+    return {
+        library,
+        prepared,
+        documentCount: library.documents.length,
+        compiled: library.incremental?.compiled ??
+            library.documents.map((document) => document.id),
+        reused: library.incremental?.reused.length ?? 0,
+        blocks: keys.length,
+        reusedBlocks: keys.filter((key) => previous.prepared?.blocks[key] === prepared.blocks[key]).length,
+        outDir,
+        elapsed: Date.now() - started,
+    };
+}
+/**
+ * Whether a change may alter what collection reads: a Markdown file, a
+ * directory, or an entry that is gone, which may have been a directory
+ * renamed, moved or deleted with its documents inside. A name alone cannot
+ * tell `v1.5/` from a file, so what is still there is looked at. Dot entries
+ * and `node_modules` are never collected, so changes under them are ignored.
+ */
+const isSource = (root, filename) => {
+    if (filename === null)
+        return true;
+    const segments = String(filename).split(/[\\/]/);
+    if (segments.some((segment) => segment.startsWith(".") || segment === "node_modules"))
+        return false;
+    if (/\.mdx?$/i.test(segments[segments.length - 1] ?? ""))
+        return true;
+    try {
+        return fs.statSync(path.join(root, String(filename))).isDirectory();
+    }
+    catch {
+        return true;
+    }
+};
+/**
+ * Collects once, then again whenever a `.md` or `.mdx` file under any root is
+ * created, changed, renamed or deleted. Changes that arrive while a pass runs
+ * start another pass when it finishes, so the output always reflects the
+ * latest files.
+ */
+export function watchDocuments(config, options = {}) {
+    const debounce = options.debounce ?? 150;
+    const report = options.onError ?? ((error) => console.error(error));
+    const roots = resolveRoots(config);
+    let state = options.reuseOutput === false ? {} : previousCollection(config.outDir);
+    let running;
+    let pending = false;
+    let timer;
+    let closed = false;
+    const pass = async () => {
+        try {
+            const result = await collectDocuments(config, state);
+            state = { library: result.library, prepared: result.prepared };
+            options.onPass?.(result);
+        }
+        catch (error) {
+            report(error);
+        }
+    };
+    const run = () => {
+        if (running) {
+            pending = true;
+            return running;
+        }
+        running = pass().then(async () => {
+            running = undefined;
+            if (pending && !closed) {
+                pending = false;
+                await run();
+            }
+        });
+        return running;
+    };
+    const schedule = (root, filename) => {
+        if (closed || !isSource(root, filename))
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            void run();
+        }, debounce);
+    };
+    const watchers = roots.map((root) => 
+    // A watcher the system gives up on — too many watched files, a root
+    // deleted — emits an error; without a listener that ends the process.
+    fs
+        .watch(root.dir, { recursive: true }, (_event, filename) => schedule(root.dir, filename))
+        .on("error", (error) => report(error)));
+    return {
+        ready: run(),
+        close() {
+            closed = true;
+            if (timer)
+                clearTimeout(timer);
+            for (const watcher of watchers)
+                watcher.close();
+        },
+    };
+}
+//# sourceMappingURL=watch.js.map

package/dist/node/watch.js.map

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

package/dist/paged.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What the paginated output formats have to agree on.
+ *
+ * A PDF is printed by a browser and a `.docx` is assembled by a writer that
+ * never sees CSS, so the only thing keeping the two in step is a shared
+ * definition rather than two implementations that happen to match. This module
+ * is browser-safe and holds no I/O.
+ */
+import type { Position } from "unist";
+import type { DocumentNode } from "./document.js";
+/** The info string an author writes on a fence to force a page break. */
+export declare const PAGE_BREAK_FENCE = "cudoc-pagebreak";
+/** `data.cudoc.kind` on the node the fence normalizes to. */
+export declare const PAGE_BREAK_KIND = "pageBreak";
+/** The class the printed stylesheets key their `break-after` rule off. */
+export declare const PAGE_BREAK_CLASS = "cudoc-page-break";
+/**
+ * Whether a node is an authored page break.
+ *
+ * A writer must test this **before** any generic `thematicBreak` handling: the
+ * break is carried on a `thematicBreak` because that is a childless flow node
+ * which can never swallow content, so a handler that dispatches on `type` alone
+ * turns an authored page break into a horizontal rule.
+ */
+export declare const isPageBreak: (node: DocumentNode) => boolean;
+/**
+ * The node an authored break becomes.
+ *
+ * `hidden` gives it the user agent's `display: none`, so a host stylesheet
+ * cudoc does not own cannot give the empty element a margin on the primary
+ * site. The printed stylesheet turns it back on and breaks after it.
+ */
+export declare const pageBreakNode: (position?: Position) => DocumentNode;
+//# sourceMappingURL=paged.d.ts.map

package/dist/paged.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paged.d.ts","sourceRoot":"","sources":["../src/paged.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,oBAAoB,CAAA;AAEjD,6DAA6D;AAC7D,eAAO,MAAM,eAAe,cAAc,CAAA;AAE1C,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,qBAAqB,CAAA;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,YAAY,KAAG,OACL,CAAA;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,WAAW,QAAQ,KAAG,YAYlD,CAAA"}