@heroiclands/package-build 23.13.0 → 24.0.0

package/engine/asset-shipping.mjs

@@ -272,8 +272,11 @@ export function assetsManifest(staged, stageDir) {
  *
  * The pictures are written beside whatever a `packageBuild.assets` row already
  * put under `icons/` and `images/`; nothing there is removed. A picture whose
- * deployed path is already a file in the stage is a finding, and no picture is
- * written. Clearing an earlier run's pictures is the stage reset's work.
+ * deployed path already holds a file with the bytes it would stage — after the
+ * transform, when there is one — is its own earlier output and is skipped, so
+ * staging twice into one directory is quiet. A file there with other bytes is a
+ * finding, and no picture is written. Clearing an earlier run's pictures is the
+ * stage reset's work.
  *
  * @param {object} opts - Options.
  * @param {string} opts.assetsBase - The package's asset directory, the roots'
@@ -309,13 +312,22 @@ export function stagePackageAssets({
     if (findings.length) return { staged: [], excluded: [], findings, manifest: null };
 
     const { staged, excluded } = selectStagedAssets(records, shippingLicenses);
-    const planned = staged.map((record) => ({
-        record,
-        from: path.join(assetsBase, ...record.asset.path.split("/")),
-        to: path.join(stageDir, .../** @type {string} */ (deployedAssetPath(record)).split("/")),
-    }));
-    for (const { record, from, to } of planned) {
+    const planned = staged.map((record) => {
+        const from = path.join(assetsBase, ...record.asset.path.split("/"));
+        return {
+            record,
+            from,
+            transformed: transform ? transform(from) : null,
+            to: path.join(
+                stageDir,
+                .../** @type {string} */ (deployedAssetPath(record)).split("/"),
+            ),
+        };
+    });
+    for (const { record, from, to, transformed } of planned) {
         if (!fs.existsSync(to)) continue;
+        const bytes = transformed != null ? transformed : fs.readFileSync(from);
+        if (Buffer.from(fs.readFileSync(to)).equals(Buffer.from(bytes))) continue;
         findings.push({
             file: to,
             severity: "error",
@@ -326,9 +338,9 @@ export function stagePackageAssets({
         });
     }
     if (findings.length) return { staged: [], excluded: [], findings, manifest: null };
-    for (const { from, to } of planned) {
+    for (const { from, to, transformed } of planned) {
+        if (fs.existsSync(to)) continue;
         fs.mkdirSync(path.dirname(to), { recursive: true });
-        const transformed = transform ? transform(from) : null;
         if (transformed != null) fs.writeFileSync(to, transformed);
         else fs.copyFileSync(from, to);
     }

package/engine/base-compiler.mjs

@@ -68,10 +68,10 @@ import { scanSpans } from "./content-spans.mjs";
 import { scanBlocks } from "./content-blocks.mjs";
 import { scanRuns } from "./content-scripts.mjs";
 import { scanHeadingAttributes, withheldSections } from "./heading-attributes.mjs";
-import { scanFigures } from "./content-figures.mjs";
 import { footnoteFindings } from "./content-footnotes.mjs";
 import { checkImages } from "./content-images.mjs";
-import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
+import { embedRole } from "./content-embeds.mjs";
+import { expandContent } from "./content-expand.mjs";
 import { eventNoteIndex } from "./event-fields.mjs";
 import { isGmNote } from "./note-vocabulary.mjs";
 import { cloneAddressState } from "./address-values.mjs";
@@ -84,8 +84,6 @@ import {
     makeFilename,
     resolveImg,
     resolveName,
-    convertNoteWikilinks,
-    expandNoteTables,
     statsForPack,
 } from "./helpers.mjs";
 // The record accessors only — see `engine/index-records.mjs` for why they live
@@ -131,25 +129,6 @@ import { annotateAssetReferences, assetReferenceLookup } from "./asset-reference
  *   about. Counted as errors, never as skips.
  */
 
-/**
- * A `ref` call's Foundry rendering: a same-page wikilink rather than a
- * Markdown link, so the wikilink pass that runs after expressions render
- * addresses it exactly as an authored `[[#anchor|Text]]` is — by the
- * JournalEntryPage the figure's own fence became, whether that page holds
- * only the figure or carries it alongside other prose. A Markdown link's
- * `#anchor` fragment resolves nowhere in Foundry, which addresses a page by
- * UUID and an anchor within a page by that page's own anchor; this is why the
- * two surfaces do not share a renderer.
- *
- * @param {{anchor: string}} target - The figure's own anchor.
- * @param {string} label - The link's text, which may itself carry Markdown.
- * @returns {string} `[[#anchor|label]]`, with a literal `|` in the label
- *   escaped so it cannot be read as the wikilink's own separator.
- */
-function foundryRefLink({ anchor }, label) {
-    return `[[#${anchor}|${label.replace(/\|/g, "\\|")}]]`;
-}
-
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
  *
@@ -670,8 +649,9 @@ export class BasePackCompiler {
     /**
      * The body {@link BasePackCompiler#buildEntry} receives.
      *
-     * Generated tables expand before wikilinks are converted, so a cell a
-     * table emits is resolved along with the authored links.
+     * The body is expanded by {@link module:engine/content-expand.expandContent}
+     * for Foundry: generated tables expand before wikilinks are converted, so
+     * a cell a table emits is resolved along with the authored links.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {string} body - The note body, as authored.
@@ -686,6 +666,14 @@ export class BasePackCompiler {
         // it made — `errors` or `findings`, never just the first — so nothing
         // here re-scans; it only stops taking `[0]`.
         const findings = [];
+        const bodyLine = this.currentNote?.bodyLine ?? 1;
+        const bodyColumn = this.currentNote?.bodyColumn ?? 1;
+        // A finding's body position, in the file. The parser trims the body,
+        // so only its first line is offset by the column the body starts at.
+        const inFile = ({ line, column }) => ({
+            line: bodyLine + line - 1,
+            column: line === 1 && column !== undefined ? bodyColumn + column - 1 : column,
+        });
         const syntax = this.corpus?.syntax;
         const scanned = syntax?.(body);
         for (const secretError of [
@@ -695,41 +683,27 @@ export class BasePackCompiler {
             ...scanRuns(body, this.corpus?.runs, syntax).errors,
             ...markupAnchorFindings(body, syntax),
         ]) {
-            findings.push({
-                message: secretError.message,
-                line: (this.currentNote?.bodyLine ?? 1) + secretError.line - 1,
-                column:
-                    secretError.line === 1 ?
-                        (this.currentNote?.bodyColumn ?? 1)
-                    :   secretError.column,
-            });
+            findings.push({ message: secretError.message, ...inFile(secretError) });
         }
         // A heading's attribute block, and a `.secret` written where no surface
         // can honour it. Read off the body as authored, before the tables
         // expand, because a heading is a heading whatever a pass does with the
         // prose under it — so a pass that converts nothing reports these too.
         for (const headingError of [
-            ...scanHeadingAttributes(body, this.currentNote?.bodyLine ?? 1).errors,
-            ...withheldSections(body, this.currentNote?.bodyLine ?? 1).errors,
+            ...scanHeadingAttributes(body, bodyLine).errors,
+            ...withheldSections(body, bodyLine).errors,
         ]) {
             findings.push({
                 message: headingError.message,
                 line: headingError.line,
                 column:
-                    headingError.line === (this.currentNote?.bodyLine ?? 1) ?
-                        (this.currentNote?.bodyColumn ?? 1) + headingError.column - 1
+                    headingError.line === bodyLine ?
+                        bodyColumn + headingError.column - 1
                     :   headingError.column,
             });
         }
         for (const footnoteError of footnoteFindings(body)) {
-            findings.push({
-                message: footnoteError.message,
-                line: (this.currentNote?.bodyLine ?? 1) + footnoteError.line - 1,
-                column:
-                    footnoteError.line === 1 ?
-                        (this.currentNote?.bodyColumn ?? 1)
-                    :   footnoteError.column,
-            });
+            findings.push({ message: footnoteError.message, ...inFile(footnoteError) });
         }
         // An image sharing its paragraph with other text, a bad address or a
         // title with nowhere to draw it — the same findings `lint` reports,
@@ -737,10 +711,7 @@ export class BasePackCompiler {
         // already names rather than rendering the directive as though it were
         // absent. `checkImages` already resolves `bodyLine` and `bodyColumn`
         // internally, so its findings need no further adjustment.
-        for (const imageError of checkImages(body, "", {
-            bodyLine: this.currentNote?.bodyLine ?? 1,
-            bodyColumn: this.currentNote?.bodyColumn ?? 1,
-        })) {
+        for (const imageError of checkImages(body, "", { bodyLine, bodyColumn })) {
             findings.push({
                 message: imageError.message,
                 line: imageError.line,
@@ -752,69 +723,56 @@ export class BasePackCompiler {
             return body;
         }
         const name = resolveName(fm);
-        const { absPath, bodyLine, bodyColumn } = this.currentNote ?? {};
-        const { markdown: tabulated, lineMap } = expandNoteTables(body, {
-            name,
-            bodyLine,
-            sqlTables: absPath ? this.sqlTables?.get(absPath) : undefined,
-            pageLists: absPath ? this.sqlTables?.pageLists?.get(absPath) : undefined,
+        // The note's own position, unset where the caller supplied none, so a
+        // link finding drops the field rather than guessing it.
+        const { absPath, bodyLine: noteLine, bodyColumn: noteColumn } = this.currentNote ?? {};
+        // A `ref`'s cross-note resolution is the web's alone: a journal
+        // addresses a page by UUID, which this pass has none of for another
+        // note.
+        const expanded = expandContent(body, {
+            target: "foundry",
+            index: this.linkIndex,
+            note: { fm, file: absPath, source: name, bodyLine: noteLine, bodyColumn: noteColumn },
+            prepared: {
+                sqlTables: absPath ? this.sqlTables?.get(absPath) : undefined,
+                pageLists: absPath ? this.sqlTables?.pageLists?.get(absPath) : undefined,
+                inline: absPath ? this.sqlTables?.inline?.get(absPath) : undefined,
+            },
+            events: this.eventNotes(),
+            // A `ref` to a map reads the number the map's own page carries.
+            resolveRole: (address) => embedRole(this.linkIndex, address),
+            links: {
+                // A `[[#slug]]` self-link addresses the source note, which has
+                // no entry in the index — so where its own documents landed
+                // has to travel with it.
+                pack: this.router?.resolveOrNull(fm, packForType(fm.type).docType),
+                docPack: this.router?.resolveOrNull(fm, "JournalEntry"),
+            },
         });
-        const figureScan = scanFigures(tabulated);
-        for (const captionError of figureScan.errors) {
+        // A table the preparation could not answer fails the note on its own,
+        // at the table's line.
+        const { tables } = expanded.findings;
+        if (tables.length) {
+            const err = new Error(tables.map((e) => `content table — ${e.reason}`).join("; "));
+            if (noteLine !== undefined && tables[0].line !== undefined)
+                err.position = { line: noteLine + tables[0].line };
+            throw err;
+        }
+        const { lineMap } = expanded;
+        for (const captionError of expanded.findings.captions) {
+            const authored = lineMap[captionError.line - 1]?.line ?? captionError.line - 1;
             findings.push({
                 message: captionError.message,
-                line:
-                    (bodyLine ?? 1) +
-                    (lineMap[captionError.line - 1]?.line ?? captionError.line - 1),
-                column: captionError.column,
+                ...inFile({ line: authored + 1, column: captionError.column }),
             });
         }
-        // What the `ref` expression helper needs: this note's own figures, by
-        // id, and how a reference renders — a same-page wikilink rather than
-        // a Markdown link, so the wikilink pass below addresses it exactly as
-        // an authored `[[#anchor|Text]]` is, by the page the figure's own
-        // fence became. Cross-note resolution is omitted: a journal addresses
-        // a page by UUID, which this pass has none of for another note.
-        const figuresById = new Map(
-            figureScan.figures
-                .filter((figure) => figure.id)
-                .map((figure) => [
-                    figure.id,
-                    { label: figure.label, caption: figure.caption, hasCaption: figure.hasCaption },
-                ]),
-        );
-        const expressions = renderMarkdownExpressions(tabulated, {
-            fm,
-            dates: reckoningContext(this.linkIndex),
-            sqlResults: absPath ? this.sqlTables?.inline?.get(absPath) : undefined,
-            file: absPath,
-            bodyLine,
-            figures: { get: (id) => figuresById.get(id), link: foundryRefLink },
-            events: this.eventNotes(),
-        });
-        for (const finding of expressions.findings) {
+        for (const finding of expanded.findings.expressions) {
             findings.push({ message: finding.message, line: finding.line, column: finding.column });
         }
         this.reportConvertBodyFindings(findings);
-        const { markdown, unresolved } = convertNoteWikilinks(expressions.markdown, {
-            type: fm.type,
-            id: fm.id,
-            // Where this note is, so a link that resolves nowhere is reported
-            // at a position an author can open rather than by note name.
-            file: absPath,
-            bodyLine,
-            bodyColumn,
-            lineMap,
-            // A `[[#slug]]` self-link addresses the source note, which has no
-            // entry in the index — so where its own documents landed has to
-            // travel with it.
-            pack: this.router?.resolveOrNull(fm, packForType(fm.type).docType),
-            docPack: this.router?.resolveOrNull(fm, "JournalEntry"),
-            index: this.linkIndex,
-            name,
-        });
-        this.unresolvedLinks += unresolved.length;
-        return markdown;
+        if (expanded.linkError) throw expanded.linkError;
+        this.unresolvedLinks += expanded.unresolved.length;
+        return expanded.markdown;
     }
 
     /**

package/engine/changelog-lint.mjs

@@ -553,7 +553,7 @@ function checkTooManyBullets(bullets) {
             severity: "error",
             message:
                 `changelog-check/too-many-bullets ${bullets.length} top-level bullets is an ` +
-                `itemized log, not a release note — one to six, so a reader sees the shape ` +
+                `itemized log, not a release note — at most ${MAX_TOP_BULLETS}, so a reader sees the shape ` +
                 "of the release at a glance",
         },
     ];

package/engine/content-address.mjs

@@ -140,7 +140,7 @@ export function addressSlug(fm) {
  * composing a URL prepends where the package is served (`/<package>/`); a
  * consumer composing a manifest entry measures against that same base. Nothing
  * else is prepended: `prefix` says where the content tree *mounts inside the
- * package* — the Hugo directory its pages are written under — and an address is
+ * package* — where its pages sit in the source tree — and an address is
  * `(type, shortcode)`, a package-wide identity that takes no mount, so `sohl`
  * publishes `/sohl/affliction-aconite/` from a file written under `kb/`. The
  * `type-` half is what keeps that flat namespace clear of the package's fixed

package/engine/content-alerts.mjs

@@ -136,9 +136,13 @@ export function scanAlerts(source) {
 }
 /** Render alert wrappers while preserving ordinary Markdown and note footnotes.
  * @param {string} source - Authored Markdown.
- * @param {"web"|"foundry"} [target="web"] - Publishing surface.
+ * @param {"web"|"foundry"|"preview"} [target="web"] - Publishing surface: the
+ *   preview draws the icon as an inline drawing, since a buffer has no icon font.
+ * @param {object} [options]
+ * @param {(markdown: string) => string} [options.renderInline] - How a title
+ *   is rendered; omitted, a title is plain inline Markdown.
  */
-export function renderAlerts(source, target = "web") {
+export function renderAlerts(source, target = "web", { renderInline } = {}) {
     const { blocks, errors } = scanAlerts(source),
         lines = String(source ?? "").split("\n"),
         output = [];
@@ -163,9 +167,9 @@ export function renderAlerts(source, target = "web") {
         output.push(
             "",
             `<aside ${attrs.join(" ")}>`,
-            `<header class="alert-title">${definition.icon} ${titleParser.renderInline(block.title)}</header>`,
+            `<header class="alert-title">${target === "preview" ? definition.svg : definition.icon} ${(renderInline ?? titleParser.renderInline.bind(titleParser))(block.title)}</header>`,
             "",
-            renderAlerts(block.body, target).markdown,
+            renderAlerts(block.body, target, { renderInline }).markdown,
             "",
             "</aside>",
             "",

package/engine/content-blocks.mjs

@@ -38,7 +38,7 @@
  * **A block's body is left as Markdown, not pre-rendered.** The wrapper is
  * written with a blank line after the opening tag and before the closing one,
  * which is what lets the surrounding renderer — Foundry's single parse of the
- * whole page, or Hugo's of the whole site page — read the body as part of its
+ * whole page, or the site renderer's of the whole page — read the body as part of its
  * own document rather than as an isolated fragment. A fragment rendered on its
  * own has no access to the note's footnote definitions, which live at the top
  * level outside every block, so a reference inside one would fall through as
@@ -163,8 +163,8 @@ export function scanBlocks(source) {
                 parsed.problems.push("block attributes need {…} braces");
             else parsed = parseExtensionAttributes(raw.trim().slice(1, -1));
         }
-        for (const message of [...parsed.problems, ...refusedAttributes(parsed.values)])
-            errors.push({ ...at, message });
+        const problems = [...parsed.problems, ...refusedAttributes(parsed.values)];
+        for (const message of problems) errors.push({ ...at, message });
         const attributes = { ...parsed.values };
         let title = BLOCK_NAMES[name] ?? "";
         if (name !== "div" && Object.hasOwn(attributes, "title")) {
@@ -178,7 +178,7 @@ export function scanBlocks(source) {
             id: parsed.id,
             classes: parsed.classes,
             attributes,
-            rejected: parsed.problems.length > 0 || refusedAttributes(parsed.values).length > 0,
+            rejected: problems.length > 0,
             indent: /^ */.exec(line)[0],
         });
     }
@@ -237,7 +237,8 @@ function attributeText(block, target, classes) {
  * Render named blocks for one publishing surface.
  *
  * `foundry` emits a `<section>` whose heading is its first line; `web` emits a
- * `<details>` the reader opens. Neither carries an inline `style`.
+ * `<details>` the reader opens, and `preview` the same without the search
+ * marker. None carries an inline `style`.
  *
  * The body is left as Markdown between the wrapper's tags, each separated from
  * its tag by a blank line — see the module docs for why that is what lets the
@@ -247,10 +248,13 @@ function attributeText(block, target, classes) {
  * A finding does not stop the well-formed blocks around it from rendering.
  *
  * @param {string} source - Markdown containing named blocks.
- * @param {"foundry"|"web"} target - Publishing surface.
+ * @param {"foundry"|"web"|"preview"} target - Publishing surface.
+ * @param {object} [options]
+ * @param {(markdown: string) => string} [options.renderInline] - How a title
+ *   is rendered; omitted, a title is plain inline Markdown.
  * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
  */
-export function renderBlocks(source, target) {
+export function renderBlocks(source, target, { renderInline } = {}) {
     const { errors } = scanBlocks(source);
     source = renderVerse(source).markdown;
     const renderedBlocks = scanBlocks(source).blocks;
@@ -268,14 +272,14 @@ export function renderBlocks(source, target) {
         // at every depth, never a rendered fragment.
         const held =
             BLOCK_CONTAINERS.includes(block.name) ?
-                renderBlocks(block.body, target).markdown
+                renderBlocks(block.body, target, { renderInline }).markdown
             :   block.body;
         if (block.name === "div") {
             output.push("", `<div ${attributes}>`, "", held, "", "</div>", "");
             cursor = block.end + 1;
             continue;
         }
-        const title = titleParser.renderInline(block.title);
+        const title = (renderInline ?? titleParser.renderInline.bind(titleParser))(block.title);
         if (target === "foundry") {
             output.push(
                 "",
@@ -287,6 +291,16 @@ export function renderBlocks(source, target) {
                 "</section>",
                 "",
             );
+        } else if (target === "preview") {
+            output.push(
+                "",
+                `<details ${attributes}><summary>${title}</summary>`,
+                "",
+                held,
+                "",
+                "</details>",
+                "",
+            );
         } else {
             output.push(
                 "",
@@ -314,7 +328,8 @@ export function renderBlocks(source, target) {
  *
  * **A spoiler, not access control.** The section is in the published page, so a
  * reader who opens the element or reads the source reads it. Foundry is the one
- * surface that withholds anything.
+ * surface that withholds anything. The disclosure is kept out of the site's
+ * search index, as a `secret` block is, so no result quotes it.
  *
  * @param {string} source - A page's Markdown, headings intact.
  * @returns {string} The same Markdown, each withheld section inside a
@@ -335,7 +350,7 @@ export function renderWithheldSections(source) {
         ];
         output.push(
             "",
-            `<details class="${escapeAttribute(classes.join(" "))}">`,
+            `<details class="${escapeAttribute(classes.join(" "))}" data-pagefind-ignore>`,
             `<summary class="${escapeAttribute(WITHHELD_CLASS)}">${BLOCK_NAMES[WITHHELD_CLASS]}</summary>`,
             "",
             ...lines.slice(section.start, section.end),

package/engine/content-embeds.mjs

@@ -35,7 +35,7 @@
  *
  * **That is why the rewrite is a source-text pass rather than a markdown-it
  * inline rule.** Two of the four readers have no render pass to put a token in:
- * the website is handed *markdown* for Hugo to render, and the link checker
+ * the website's renderer is handed *markdown*, and the link checker
  * parses nothing at all. A third, the book, reads its staging list out of the
  * source text before it tokenises. A token would therefore serve one reader and
  * leave the other three needing the grammar a second time, which is the drift