@heroiclands/package-build 25.6.2 → 25.7.0

package/engine/cdn-publish.mjs

@@ -15,14 +15,17 @@
  * `package-build cdn publish` — every picture a package has, on the CDN, and
  * the art the package leaves out as a named asset set.
  *
+ * Internal publication uses the same plan with an atlas rsync writer and public
+ * HTTPS reads. Cloudflare publication keeps the S3-compatible transport.
+ *
  * **The layout is the deployed one.** Each icon and image is uploaded flat, as
- * `icons/<basename>` or `images/<basename>`, under `<site.assets>/<package>/`
- * — the address {@link module:engine/pathnames.resolvePathname} gives the
- * website for the same file, so the site and the CDN agree by construction.
+ * `icons/<basename>` or `images/<basename>`, under the selected CDN's package
+ * root. Cloudflare uses `site.assets`; internal uses `INTERNAL_CDN_HOST`.
+ * Select the same CDN origin for site builds that consume these pictures.
  * Shipped and excluded pictures both go up: the website shows all of them.
  *
- * **The bucket is served at `site.assets`.** An object's key is its path below
- * that URL, `<package>/images/<basename>`, so the key and the public address
+ * **Each destination preserves object keys.** An object's key is its path below
+ * the selected CDN origin, `<package>/images/<basename>`, so the key and the public address
  * differ only by the host.
  *
  * **The bytes are the staged bytes.** The repository's `assetTransform` runs
@@ -56,6 +59,9 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import os from "node:os";
+import { execFile } from "node:child_process";
+import { promisify, stripVTControlCharacters } from "node:util";
 
 import { AwsClient } from "aws4fetch";
 
@@ -278,7 +284,7 @@ export function s3Store({ endpoint, bucket, accessKeyId, secretAccessKey, fetch:
 export function publicStore(host, fetchImpl) {
     const base = host.replace(/\/+$/, "");
     const get = (key, method) =>
-        (fetchImpl ?? fetch)(`${base}/${key}`, {
+        (fetchImpl ?? fetch)(`${base}/${key.split("/").map(encodeURIComponent).join("/")}`, {
             method,
             headers: method === "HEAD" ? IDENTITY : undefined,
         });
@@ -300,6 +306,156 @@ export function publicStore(host, fetchImpl) {
     };
 }
 
+/** The internal CDN's public origin. Reads never require SSH credentials. */
+export const INTERNAL_CDN_HOST = "https://cdn.internal.heroiclands.org";
+
+/** The manual operator's ordinary SSH account on atlas. */
+export const INTERNAL_CDN_DESTINATION = "atlas:/srv/preview/cdn";
+
+/**
+ * Refuse traversal, absolute paths and control characters before touching a store.
+ *
+ * @param {string} key - A planned relative object key.
+ * @returns {void}
+ */
+function validateCdnKey(key) {
+    if (
+        typeof key !== "string" ||
+        !/^[\x20-\x7e]+$/.test(key) ||
+        key.includes("\\") ||
+        key.split("/").some((part) => !part || part === "." || part === "..")
+    ) {
+        throw new Error("unsafe CDN key: expected a printable relative path without traversal");
+    }
+}
+
+/**
+ * Retain the last actionable receiver diagnostic without commands or key material.
+ *
+ * @param {unknown} stderr - Child-process stderr, never the whole error message.
+ * @returns {string} Bounded, terminal-safe diagnostic text, or an empty string.
+ */
+function transferDiagnostic(stderr) {
+    if (typeof stderr !== "string" && !Buffer.isBuffer(stderr)) return "";
+    const text = stripVTControlCharacters(String(stderr).slice(-8192))
+        .replace(
+            /-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?(?:-----END [^-]*PRIVATE KEY-----|$)/g,
+            "",
+        )
+        .replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, "");
+    let fallback = "";
+    for (const raw of text.split("\n").reverse()) {
+        const line = raw
+            .trim()
+            .replace(/^(?:\/[^\s/]+)*\/(rrsync|rsync|ssh)(?=(?: error)?: )/i, "$1");
+        if (/command failed|command:|\brsync\s+--|\bssh\s+-/i.test(line)) continue;
+        const known = line.match(
+            /Host key verification failed\.|Permission denied(?: \([A-Za-z0-9, -]{1,80}\))?\.?|REMOTE HOST IDENTIFICATION HAS CHANGED|Connection refused|Connection timed out|Could not resolve hostname/i,
+        );
+        if (known) return known[0];
+        if (!/^(?:r?rsync|ssh)(?: error)?: /i.test(line)) continue;
+        const context = line
+            .replace(/(["'])[^"']*\1/g, "[redacted]")
+            .replace(/(?:\/|[A-Za-z]:[\\/])[^\s,;)]+/g, "[path]")
+            .replace(/[A-Za-z0-9+/=]{48,}/g, "[redacted]")
+            .slice(0, 240);
+        if (/^rrsync(?: error)?: /i.test(line)) return context;
+        fallback ||= context;
+    }
+    return fallback;
+}
+
+/**
+ * Report an operation and its structured failure code, excluding error argv/message.
+ *
+ * @param {unknown} error - A filesystem or child-process error.
+ * @param {string} operation - The operation being attempted.
+ * @returns {string} The operator-facing failure.
+ */
+function internalFailure(error, operation) {
+    const details = error && typeof error === "object" ? /** @type {any} */ (error) : {};
+    const code =
+        Number.isInteger(details.code) && details.code >= 0 && details.code <= 255 ?
+            `exit ${details.code}`
+        : typeof details.code === "string" && Object.hasOwn(os.constants.errno, details.code) ?
+            `code ${details.code}`
+        : typeof details.signal === "string" && /^SIG[A-Z0-9]{1,12}$/.test(details.signal) ?
+            `signal ${details.signal}`
+        :   "";
+    const context = operation === "rsync transfer" ? transferDiagnostic(details.stderr) : "";
+    const action =
+        operation === "rsync transfer" ? "rsync transfer failed" : `could not ${operation}`;
+    return `internal CDN ${action}${code ? `; ${code}` : ""}${context ? `: ${context}` : ""}`;
+}
+
+/**
+ * Internal storage: HTTPS reads and rsync writes of the planned bytes only.
+ *
+ * The default uses the operator's normal atlas account. An explicitly configured
+ * SSH alias may select the forced-rrsync account with a relative `cdn` destination.
+ * SSH configuration and its agent supply keys; no remote shell is requested.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.destination] - `host:/srv/preview/cdn` or `alias:cdn`.
+ * @param {typeof fetch} [opts.fetch] - The fetch to use for public reads.
+ * @param {(args: string[]) => Promise<unknown>} [opts.transfer] - Run rsync.
+ * @returns {CdnStore} The store.
+ */
+export function internalStore({
+    destination = INTERNAL_CDN_DESTINATION,
+    fetch: fetchImpl,
+    transfer = (args) => promisify(execFile)("rsync", args),
+} = {}) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*:(?:\/srv\/preview\/)?cdn\/?$/.test(destination)) {
+        throw new Error(
+            "invalid internal CDN destination: use an SSH host alias followed by :/srv/preview/cdn or :cdn",
+        );
+    }
+    const target = `${destination.replace(/\/+$/, "")}/`;
+    const reader = publicStore(INTERNAL_CDN_HOST, fetchImpl);
+    return {
+        ...reader,
+        describe: `${destination} (${INTERNAL_CDN_HOST})`,
+        async write(key, body) {
+            validateCdnKey(key);
+            let scratch;
+            let operation = "create temporary directory";
+            let failure;
+            try {
+                scratch = fs.mkdtempSync(path.join(os.tmpdir(), "package-build-cdn-"));
+                const file = path.join(scratch, ...key.split("/"));
+                operation = "create staged directories";
+                fs.mkdirSync(path.dirname(file), { recursive: true });
+                operation = "write staged file";
+                fs.writeFileSync(file, body);
+                operation = "rsync transfer";
+                await transfer([
+                    "--recursive",
+                    "--relative",
+                    "--ignore-times",
+                    "--chmod=D755,F644",
+                    "--omit-dir-times",
+                    "--rsh=ssh -o BatchMode=yes -o StrictHostKeyChecking=yes",
+                    "--",
+                    `${scratch}/./${key}`,
+                    target,
+                ]);
+            } catch (error) {
+                failure = internalFailure(error, operation);
+            } finally {
+                if (scratch) {
+                    try {
+                        fs.rmSync(scratch, { recursive: true, force: true });
+                    } catch (error) {
+                        failure ??= internalFailure(error, "remove temporary directory");
+                    }
+                }
+            }
+            if (failure) throw new Error(failure);
+        },
+    };
+}
+
 /**
  * One picture to publish.
  *
@@ -444,6 +600,8 @@ async function pooled(items, limit, work) {
  *   planned size once the run ends — or would be, in a dry run.
  */
 export async function publishToCdn(plan, { store, dryRun = false, log = () => {} }) {
+    for (const upload of plan.uploads) validateCdnKey(upload.key);
+    validateCdnKey(plan.set?.key);
     if (!dryRun && !store.write) {
         throw new Error(`the store (${store.describe}) is read-only, so it can only be dry-run`);
     }

package/engine/content-index.mjs

@@ -1108,6 +1108,13 @@ export function resolveCultures(
  * @param {Iterable<string>} [options.nameTypes] - Additional bare name kinds from configured type declarations.
  * @param {ReturnType<typeof import("./content-timings.mjs").createContentTimings>} [options.timings] -
  *   Invocation stage accounting, which records each phase of the derivation.
+ * @param {NoteDerivationCache} [options.cache] - Earlier work to answer from:
+ *   each note's parse, and the records derived from one note alone, which
+ *   depend on that note and on the context the tree gives every note (the
+ *   setting date and calendars, the addresses the notes declare, the asset
+ *   records, the address context and the configured kinds). Not consulted
+ *   for the records when `syntax` is given. Every pass that reads the whole
+ *   tree runs whatever the cache holds.
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
@@ -1131,6 +1138,7 @@ export function collectContentIndex(
         syntax,
         nameTypes,
         timings,
+        cache,
     },
 ) {
     // Each phase runs until the next begins; the caller's stage closes the last.
@@ -1142,8 +1150,9 @@ export function collectContentIndex(
     phase("index read");
     const records = [];
     // Passed through rather than defaulted away: an absent scope is the
-    // caller's omission, and `walkMarkdownTree` says so.
-    const walkOpts = { skipDirectories, sources, ...(sources ? { renderDescription: false } : {}) };
+    // caller's omission, and `walkMarkdownTree` says so. No record reads a
+    // note's rendered description, so none is rendered.
+    const walkOpts = { skipDirectories, sources, renderDescription: false, parse: cache?.parse };
 
     // A package may ship assets and no notes at all, in which case there is no
     // tree to walk and the index is its asset records. The caller decides
@@ -1202,6 +1211,29 @@ export function collectContentIndex(
         parsedNotes,
         contentPackage,
     );
+    // Everything the tree gives each note's own records, so a cached note's
+    // records are reused only where none of it moved.
+    const noteContext =
+        cache && !syntax ?
+            cache.context({
+                dates,
+                assetRecords,
+                declared: parsedNotes
+                    .map(({ frontmatter: fm }) => `${fm?.type}\0${fm?.shortcode}`)
+                    .sort(),
+                addressContext: Object.entries(addressContext ?? { package: contentPackage })
+                    .filter(([, value]) => typeof value !== "function")
+                    .sort(([a], [b]) =>
+                        a < b ? -1
+                        : a > b ? 1
+                        : 0,
+                    ),
+                contentPackage,
+                languages,
+                manifest,
+                nameTypes: nameTypes ? [...nameTypes] : undefined,
+            })
+        :   undefined;
 
     // Each recorded note with its body, for the words its prose cites.
     phase("index notes");
@@ -1220,23 +1252,25 @@ export function collectContentIndex(
         applyComputedBeingAge(fm, present, dates);
         const relPath = path.relative(contentBase, absPath);
         try {
-            const made = indexRecordsForNote({
-                frontmatter: fm,
-                relPath,
-                absPath,
-                raw,
-                contentPackage,
-                body,
-                bodyLine,
-                bodyColumn,
-                nameTypes,
-                manifest,
-                addressContext: decodeContext,
-                dateContext: dates,
-                resolveRole,
-                syntax,
-                runContext: { languages },
-            });
+            const derive = () =>
+                indexRecordsForNote({
+                    frontmatter: fm,
+                    relPath,
+                    absPath,
+                    raw,
+                    contentPackage,
+                    body,
+                    bodyLine,
+                    bodyColumn,
+                    nameTypes,
+                    manifest,
+                    addressContext: decodeContext,
+                    dateContext: dates,
+                    resolveRole,
+                    syntax,
+                    runContext: { languages },
+                });
+            const made = cache ? cache.records(absPath, noteContext, derive) : derive();
             records.push(...made);
             bodies.push({ record: made[0], body });
         } catch (err) {
@@ -1533,6 +1567,8 @@ function dependencyAddresses(config) {
  * @param {Map<string, object>} [opts.foreignIndex] - Captured dependency address view.
  * @param {ReturnType<typeof import("./content-timings.mjs").createContentTimings>} [opts.timings] -
  *   Invocation stage accounting.
+ * @param {NoteDerivationCache} [opts.cache] - Earlier parses and per-note
+ *   records to answer from; see {@link collectContentIndex}.
  * @returns {object[]} One record per note, plus one per documentation entry.
  */
 export function indexRecordsFor({
@@ -1547,6 +1583,7 @@ export function indexRecordsFor({
     nameTypes,
     foreignIndex,
     timings,
+    cache,
 } = {}) {
     const resolved = config ?? loadPackConfig();
     const tree = contentBase ?? resolved.paths.content;
@@ -1582,6 +1619,7 @@ export function indexRecordsFor({
         syntax,
         nameTypes: nameTypes ?? resolved.itemTypes,
         timings,
+        cache,
     });
 }
 
@@ -1802,6 +1840,20 @@ export async function prepareContentIndex({ contentBase, config, session } = {})
     };
 }
 
+/**
+ * Earlier derivation work {@link collectContentIndex} may answer from, such as
+ * {@link module:engine/note-cache.noteTree}'s store.
+ * @typedef {object} NoteDerivationCache
+ * @property {typeof import("./helpers.mjs").parseMarkdownFile} [parse] - Reads
+ *   one note, as {@link module:engine/helpers.parseMarkdownFile} does.
+ * @property {(value: unknown) => string|undefined} context - A key for the
+ *   context the tree gives each note's records, or nothing when it has none.
+ * @property {(absPath: string, context: string|undefined, derive: () => object[]) => object[]} records -
+ *   The records one note derives: the stored ones when that note's text and
+ *   the context are unchanged, else `derive()`'s. Either is the caller's to
+ *   change.
+ */
+
 /**
  * A captured source context, consumed without mutation by the synchronous emitter.
  * @typedef {object} PreparedContentIndex

package/engine/content-spans.mjs

@@ -23,6 +23,23 @@ import { parseExtensionAttributes, refusedAttributes } from "./extension-attribu
 import { inlineText } from "./name-markup.mjs";
 import { cartoucheProblems, glyphProblems } from "./content-glyphs.mjs";
 
+/**
+ * Whether the text before `at` ends in `@` and one or more ASCII letters, as
+ * a language tag does.
+ *
+ * Read backwards from `at`, so each bracket costs its own tag's length rather
+ * than the length of everything before it.
+ *
+ * @param {string} text - The source.
+ * @param {number} at - The offset of the bracket.
+ * @returns {boolean} Whether a tag ends there.
+ */
+function followsLanguageTag(text, at) {
+    let start = at;
+    while (start > 0 && /[A-Za-z]/.test(text[start - 1])) start--;
+    return start < at && text[start - 1] === "@";
+}
+
 /** Add bracket spans after recognized Markdown links and footnotes.
  * @param {import("markdown-it")} md - Markdown parser to extend.
  * @param {object} [options] - Surface presentation.
@@ -65,7 +82,7 @@ export function spanMarkdownPlugin(md, { spoilers = false, source = false, verse
             // adjacent closing brackets without parsing every label twice.
             (state.src[start + 1] === "[" &&
                 state.src[state.src.indexOf("]", start + 2) + 1] === "]") ||
-            /@[A-Za-z]+$/.test(state.src.slice(0, start)) ||
+            followsLanguageTag(state.src, start) ||
             state.src[start + 1] === "^" ||
             ["!", "]"].includes(state.src[start - 1]) ||
             (state.src[start - 1] === "[" && state.linkLevel === 0)

package/engine/content-styles.mjs

@@ -25,6 +25,7 @@
  */
 
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 
 import { baseStylesheetSource } from "./base-styles.mjs";
 
@@ -89,3 +90,87 @@ export function highlightRules(scope) {
 export function siteCodeStylesheet(scope = ".single-body") {
     return `${scope} :is(pre, code) {\n    color-scheme: dark;\n}\n\n${highlightRules(scope)}`;
 }
+
+/** The stretches of the site theme's stylesheet that style a page body. */
+const NOTE_BODY_RULES = /\/\* note-body \*\/([^]*?)\/\* \/note-body \*\//g;
+
+/**
+ * The page-wide rules the site theme writes for the whole document, and the
+ * selector each is given for a body shown on its own: the reset, the root
+ * size the theme's `rem` lengths are measured against, the body's text and
+ * the ordinary link. `keep` names the declarations that carry over; a rule
+ * without one carries over whole.
+ */
+const PAGE_RULES = Object.freeze([
+    {
+        from: "*, *::before, *::after",
+        to: ".single-content, .single-content *, .single-content *::before, .single-content *::after",
+    },
+    { from: "html", to: ":root", keep: ["font-size"] },
+    {
+        from: "body",
+        to: ".single-content",
+        keep: [
+            "font-family",
+            "font-weight",
+            "line-height",
+            "color",
+            "background",
+            "-webkit-font-smoothing",
+        ],
+    },
+    { from: "a", to: ".single-content a" },
+    { from: "a:hover", to: ".single-content a:hover" },
+]);
+
+/**
+ * One page-wide rule of the theme, given the selector a body shown on its own
+ * takes.
+ *
+ * @param {string} css - The theme's stylesheet.
+ * @param {{from: string, to: string, keep?: readonly string[]}} rule - Which
+ *   rule, and how it carries over.
+ * @returns {string} The rule.
+ * @throws {Error} When the stylesheet has no such rule.
+ */
+function scopedPageRule(css, { from, to, keep }) {
+    const escaped = from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const found = new RegExp(`^${escaped} \\{([^}]*)\\}`, "m").exec(css);
+    if (!found) throw new Error(`the site stylesheet has no \`${from}\` rule for a page body`);
+    const declarations = found[1]
+        .split(";")
+        .map((declaration) => declaration.trim())
+        .filter(Boolean)
+        .filter((declaration) => !keep || keep.includes(declaration.split(":")[0].trim()));
+    return `${to} {\n${declarations.map((declaration) => `  ${declaration};`).join("\n")}\n}`;
+}
+
+/**
+ * The CSS the site theme applies to a page body: its custom properties, the
+ * body's text, named blocks, figures, verse, footnotes, unresolved and draft
+ * links, cartouches, glyphs, alerts, spoilers, dictionary lists and faces,
+ * then the highlighted-code rules a site links as `css/code.css`.
+ *
+ * Read from the theme's own stylesheet, the stretches it marks `note-body`,
+ * so a rule changed there changes here. The rules are scoped as the theme
+ * scopes them: the body sits in a `.single-body` inside a `.single-content`.
+ * The theme's page-wide rules for the reset, the body's typography and the
+ * ordinary link come first, scoped to `.single-content`, so a body set in that
+ * wrapper reads as the page does whatever the host's own styles; the one
+ * exception is the root font size, set on `:root`, since every length the
+ * theme writes in `rem` is measured against it.
+ *
+ * @returns {string} The stylesheet.
+ * @throws {Error} When the theme's stylesheet marks no body rules, or lacks
+ *   one of the page-wide rules.
+ */
+export function noteBodyStylesheet() {
+    const css = fs.readFileSync(
+        fileURLToPath(new URL("../site-theme/static/css/style.css", import.meta.url)),
+        "utf8",
+    );
+    const rules = [...css.matchAll(NOTE_BODY_RULES)].map((match) => match[1].trim());
+    if (!rules.length) throw new Error("the site stylesheet marks no rules for a page body");
+    const page = PAGE_RULES.map((rule) => scopedPageRule(css, rule));
+    return `${[...page, ...rules].join("\n\n")}\n\n${siteCodeStylesheet()}`;
+}

package/engine/derived-sections.mjs

@@ -58,6 +58,7 @@ import { mapWorld } from "./map-places.mjs";
 import { officeBodyKey, officeHolders } from "./office-holders.mjs";
 import { renderAddress } from "./address.mjs";
 import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { outsideOnly } from "./prepared-only.mjs";
 
 /**
  * The heading each kind of place is grouped under, in the order the place
@@ -282,8 +283,8 @@ export function drawMapsFrom(records, { outDir, foreignIndex = new Map(), config
  * @param {object} [opts.config] - The resolved configuration.
  * @param {(file:string)=>string|undefined} [opts.rawOf] - Captured source locators.
  * @param {object[]} [opts.all=records] - Complete records for settlement validation.
- * @param {string} [opts.only] - One note file to give sections to; absent,
- *   every note.
+ * @param {string|Set<string>} [opts.only] - The note file, or files, to give
+ *   sections to; absent, every note.
  * @returns {Map<string, Map<string, string>>} Note file to its sections, each
  *   keyed by its slug, for every note given at least one.
  */
@@ -319,7 +320,7 @@ export function derivedSections(
 
     const out = new Map();
     for (const record of pages) {
-        if (only !== undefined && fileOf(record) !== only) continue;
+        if (outsideOnly(only, fileOf(record))) continue;
         const key = record.address.canonical;
         const lists = holdings.get(key) ?? {};
         const sections = new Map();

package/engine/event-views.mjs

@@ -42,6 +42,7 @@
 import { ownDocumentSystem, renderAddress } from "./address.mjs";
 import { authoredSection, sectionHeading } from "./generated-sections.mjs";
 import { calendarAddress } from "./reckoning-markers.mjs";
+import { outsideOnly } from "./prepared-only.mjs";
 
 /** A literal SQL string. */
 const literal = (text) => `'${String(text).replace(/'/g, "''")}'`;
@@ -428,8 +429,9 @@ function section(view, query) {
  * @param {Iterable<object>} records - The content-index records.
  * @param {(record: object) => string} fileOf - A record's note file, as the
  *   prepared results are keyed.
- * @param {string} [only] - One note file to give views to, every note's being
- *   read for them; absent, every note is given its views.
+ * @param {string|Set<string>} [only] - The note file, or files, to give views
+ *   to, every note's being read for them; absent, every note is given its
+ *   views.
  * @returns {Promise<Map<string, Map<string, string>>>} Note file to its views,
  *   each keyed by its slug, for every note given at least one.
  */
@@ -448,7 +450,7 @@ export async function eventViewSections(db, records, fileOf, only) {
         const selves = [];
         for (const record of all) {
             if (!record?.address || record.documents || !record.shortcode) continue;
-            if (only !== undefined && fileOf(record) !== only) continue;
+            if (outsideOnly(only, fileOf(record))) continue;
             if (!view.applies(record) || authoredSection(record, view.slug)) continue;
             const self = selfForms(record);
             if (view.query(self, shape)) selves.push(self);
@@ -460,7 +462,7 @@ export async function eventViewSections(db, records, fileOf, only) {
     }
     for (const record of all) {
         if (!record?.address || record.documents || !record.shortcode) continue;
-        if (only !== undefined && fileOf(record) !== only) continue;
+        if (outsideOnly(only, fileOf(record))) continue;
         const self = selfForms(record);
         const sections = new Map();
         for (const view of EVENT_VIEWS) {

package/engine/helpers.mjs

@@ -356,6 +356,9 @@ export function assertSuppliedCorpus(records, who) {
  * @param {Map<string, {raw: string}>} [opts.sources] - Selected sources in walk order.
  *   Supplied, the walk parses these strings instead of reading the filesystem.
  * @param {boolean} [opts.renderDescription=true] - Render each body's description.
+ * @param {typeof parseMarkdownFile} [opts.parse] - What reads one file, called
+ *   as {@link parseMarkdownFile} is; a caller holding earlier parses answers
+ *   from them.
  * @yields {{frontmatter: object|null, body: string, description: string,
  *   file: string, absPath: string, bodyLine?: number, bodyColumn?: number}}
  *   One entry per `.md` file found.
@@ -364,7 +367,13 @@ export function assertSuppliedCorpus(records, who) {
  */
 export function* walkMarkdownTree(
     rootDir,
-    { skipDirectories, addressContext, sources, renderDescription = true } = {},
+    {
+        skipDirectories,
+        addressContext,
+        sources,
+        renderDescription = true,
+        parse = parseMarkdownFile,
+    } = {},
 ) {
     // Stated by the caller, never resolved here. A default here
     // — `loadPackConfig().skipDirectories` — read whichever configuration
@@ -381,7 +390,7 @@ export function* walkMarkdownTree(
     if (sources) {
         for (const [absPath, source] of sources) {
             yield {
-                ...parseMarkdownFile(absPath, {
+                ...parse(absPath, {
                     addressContext,
                     raw: source.raw,
                     renderDescription,
@@ -392,6 +401,27 @@ export function* walkMarkdownTree(
         }
         return;
     }
+    for (const absPath of walkMarkdownFiles(rootDir, { skipDirectories })) {
+        yield {
+            ...parse(absPath, { addressContext, renderDescription }),
+            file: path.basename(absPath),
+            absPath,
+        };
+    }
+}
+
+/**
+ * Recursively yields the path of every `.md` file under `rootDir`, in the
+ * order {@link walkMarkdownTree} reads them, without reading any.
+ *
+ * @param {string} rootDir - Root of the tree to walk.
+ * @param {{skipDirectories: readonly string[]}} opts - Directory names to
+ *   ignore wherever they appear; required, as for {@link walkMarkdownTree}.
+ * @yields {string} Each file's absolute path.
+ * @throws {Error} When `skipDirectories` is not stated.
+ */
+export function* walkMarkdownFiles(rootDir, { skipDirectories } = {}) {
+    assertStatedScope(skipDirectories, "walkMarkdownFiles");
     if (!fs.existsSync(rootDir)) return;
     const stack = [rootDir];
     while (stack.length > 0) {
@@ -408,13 +438,7 @@ export function* walkMarkdownTree(
             if (entry.isDirectory()) {
                 if (skipDirectories.includes(entry.name)) continue;
                 stack.push(absPath);
-            } else if (entry.isFile() && entry.name.endsWith(".md")) {
-                yield {
-                    ...parseMarkdownFile(absPath, { addressContext, renderDescription }),
-                    file: entry.name,
-                    absPath,
-                };
-            }
+            } else if (entry.isFile() && entry.name.endsWith(".md")) yield absPath;
         }
     }
 }

package/engine/index.mjs

@@ -212,6 +212,7 @@ export * as packagebuildIndex from "./packagebuild-index.mjs";
 
 /** Publishing a content tree as a website: the pass, and its integrity gates. */
 export * as siteBuild from "./site-build.mjs";
+export * as sitePage from "./site-page.mjs";
 
 /** In-memory page rendering for an editor preview. */
 export * as sitePreview from "./site-preview.mjs";