@heroiclands/package-build 22.21.0 → 22.23.0

package/engine/journals.mjs

@@ -51,16 +51,20 @@
 
 import log from "loglevel";
 
+import path from "node:path";
+
 import {
     sohlField,
     makeId,
     resolveName,
+    resolveImg,
     defaultStats,
     renderFoundryMarkdown,
     md,
     folderField,
 } from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
+import { scanBlocks } from "./content-blocks.mjs";
 import { anchorPageId, resolveReference } from "./wikilinks.mjs";
 import { infoboxesToHtml, linkToUuid } from "./infobox-render.mjs";
 import { noteInfoboxes } from "./infobox-registry.mjs";
@@ -69,16 +73,50 @@ import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { JOURNAL_TYPES } from "./ids.mjs";
 import { journalHasContent } from "./note-state.mjs";
 import { draftNoticeFor } from "./draft-notice.mjs";
-import { scanCaptions } from "./content-captions.mjs";
+import { scanFigures } from "./content-figures.mjs";
 import { separateFootnotes } from "./content-footnotes.mjs";
+import { WITHHELD_CLASS, pageOpenings } from "./heading-attributes.mjs";
+import { imagesIn } from "./content-images.mjs";
+import { IMAGE_EXTENSIONS } from "./asset-types.mjs";
+import { pathnameRoles } from "./art-fields.mjs";
+
+/**
+ * `CONST.DOCUMENT_OWNERSHIP_LEVELS.NONE` — the default ownership a withheld
+ * page states. A GM reads every document whatever it says; everyone else reads
+ * this one not at all.
+ */
+const WITHHELD_OWNERSHIP = 0;
+
+/**
+ * Every line a named block's own markup occupies, from its `:::name` opener
+ * to its closing `:::` inclusive.
+ *
+ * Read from {@link module:engine/content-blocks.scanBlocks}'s own ranges
+ * rather than restated here, so a figure cannot disagree with the blocks pass
+ * about what counts as a named block or where one ends. `scanBlocks` already
+ * recognises every name in its registry, carrying an attribute block or not,
+ * and already tracks a nested construct's own closer by depth rather than by
+ * a flag a bare `:::` clears regardless of whose closer it is.
+ *
+ * @param {string} markdown - A note's body, as {@link splitPages} receives it.
+ * @returns {Set<number>} 0-based line indices inside a named block.
+ */
+function namedBlockLines(markdown) {
+    const lines = new Set();
+    for (const { start, end } of scanBlocks(markdown).blocks) {
+        for (let i = start; i <= end; i++) lines.add(i);
+    }
+    return lines;
+}
 
 /**
  * Splits a markdown body into pages by top-level H1 headings. Fenced
- * code blocks are respected so `# foo` inside ``` blocks doesn't trigger
- * a split. Content before the first H1 (if non-empty) becomes a leading
- * page. Each H1 yields a page whose name is the heading
+ * code blocks are respected so `# foo` inside ``` or ~~~ blocks doesn't
+ * trigger a split. Content before the first H1 (if non-empty) becomes a
+ * leading page. Each H1 yields a page whose name is the heading
  * text (with any `{#anchor-id}` suffix stripped out and surfaced as
- * `anchorSlug`).
+ * `anchorSlug`). The classes the heading declares come along as `classes`, so
+ * a surface that honours one has it without reading the suffix again.
  *
  * `leadName` names that leading page. A journal note's is "Introduction",
  * because it introduces the pages that follow. An item doc's is the item — a
@@ -86,26 +124,32 @@ import { separateFootnotes } from "./content-footnotes.mjs";
  * calling that page "Introduction" would label the description as a preamble to
  * nothing.
  *
+ * A figure fence carries its own record along onto the page it starts, as
+ * `figure` — `null` for a page a heading started. {@link buildPages} reads it
+ * to build the `image` or `text` page a fence begins; nothing else sets it.
+ *
  * @param {string} body - Markdown body to split.
  * @param {string} [leadName] - Name of the page before the first heading.
+ * @param {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares, so a figure page's
+ *   name reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
- *   markdown: string}>} Pages in document order.
+ *   classes: string[], figure: object|null, markdown: string}>} Pages in
+ *   document order.
  */
-export function splitPages(body, leadName = "Introduction") {
+export function splitPages(body, leadName = "Introduction", resolveRole) {
     const { markdown, definitions } = separateFootnotes(body);
     const lines = markdown.split("\n");
-    const captions = scanCaptions(markdown).captions;
-    const captionStarts = new Map(captions.map((caption) => [caption.line - 1, caption]));
-    const captionedHeadings = new Set(
-        captions
-            .filter((caption) => /^\s*#{1,6}\s/.test(lines[caption.blockStart] ?? ""))
-            .map((caption) => caption.blockStart),
+    const figureStarts = new Map(
+        scanFigures(markdown, { resolveRole }).figures.map((figure) => [figure.line - 1, figure]),
     );
+    const blockLines = namedBlockLines(markdown);
+    const openings = pageOpenings(markdown, blockLines);
     const pages = [];
     const beforeFirstH1 = [];
     let current = null;
-    let inCodeBlock = false;
-    let inSecret = false;
+    let codeFence = null;
 
     const closeCurrent = () => {
         if (!current) return;
@@ -113,43 +157,61 @@ export function splitPages(body, leadName = "Introduction") {
             name: current.name,
             anchorSlug: current.anchorSlug,
             level: current.level,
+            classes: current.classes,
+            figure: current.figure ?? null,
             markdown: current.lines.join("\n").trim(),
         });
         current = null;
     };
 
     for (const [lineIndex, line] of lines.entries()) {
-        if (line.trim().startsWith("```")) {
-            inCodeBlock = !inCodeBlock;
+        // A fence's closer must carry the same character as its opener and
+        // be at least as long — a longer fence is what lets a fenced example
+        // carry a shorter fence of its own as literal content, same as
+        // {@link module:engine/content-blocks.scanBlocks} and
+        // {@link module:engine/content-figures.scanFigures} track it.
+        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (codeFence) {
+            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length) {
+                codeFence = null;
+            }
+        } else if (fence) {
+            codeFence = fence[1];
         }
-        if (!inCodeBlock && /^:::secret[ \t]*$/.test(line)) inSecret = true;
-        else if (!inCodeBlock && /^:::[ \t]*$/.test(line)) inSecret = false;
+        const inCodeBlock = codeFence !== null;
 
         // An H1 starts a page, as does any heading carrying an `{#slug}`
         // anchor: a Foundry UUID can only address a page, so a linkable
         // section has to be one.
-        const headingMatch =
-            !inCodeBlock && !inSecret ? line.match(/^\s*(#{1,6})\s+(.+?)\s*#*\s*$/) : null;
-        const rawHeading = headingMatch?.[2]?.trim();
-        const anchorMatch = rawHeading?.match(/^(.*?)\s*\{#([^}]+)\}\s*$/);
-        const startsPage = headingMatch && (headingMatch[1].length === 1 || anchorMatch);
-        const caption = !inCodeBlock && !inSecret ? captionStarts.get(lineIndex) : null;
-        if (caption) {
+        // {@link module:engine/heading-attributes.parseHeadingLine} is the one
+        // reading of that rule — `scanBlocks` and `scanFigures` refuse such a
+        // heading written where it cannot become a page, from the same
+        // function, so none of them can disagree about what starts one. The
+        // lines it claims here are collected by `pageOpenings`, which also
+        // skips a fence and a named block. A figure fence opens a page of its
+        // own, named for the figure's label.
+        const opening = openings.get(lineIndex);
+        const figure =
+            !inCodeBlock && !blockLines.has(lineIndex) ? figureStarts.get(lineIndex) : null;
+        if (figure) {
             closeCurrent();
             current = {
-                name: caption.label,
-                anchorSlug: caption.id,
+                name: figure.label,
+                anchorSlug: figure.id || null,
                 level: 1,
+                classes: [],
+                figure,
                 lines: [line],
             };
             continue;
         }
-        if (startsPage && !captionedHeadings.has(lineIndex)) {
+        if (opening) {
             closeCurrent();
             current = {
-                name: (anchorMatch ? anchorMatch[1] : rawHeading).trim(),
-                anchorSlug: anchorMatch?.[2]?.trim() || null,
-                level: headingMatch[1].length,
+                name: opening.text,
+                anchorSlug: opening.id || null,
+                level: opening.level,
+                classes: opening.classes,
                 lines: [],
             };
             continue;
@@ -169,6 +231,8 @@ export function splitPages(body, leadName = "Introduction") {
             name: leadName,
             anchorSlug: null,
             level: 1,
+            classes: [],
+            figure: null,
             markdown: intro,
         });
     }
@@ -267,19 +331,169 @@ export function journalPageId(entryId, page) {
         :   makeId("journal-page", `${entryId}:${page.name}`);
 }
 
+/**
+ * Whether a caption carries markup an `image` page's `caption` field cannot
+ * hold.
+ *
+ * `image.caption` is a `StringField`; `text.content` is an `HTMLField`.
+ * Parsed as inline Markdown, plain prose tokenises as `text` alone, wrapping
+ * at most on a `softbreak` — anything else (emphasis, a code span, a link, an
+ * inline image) is a token an image page has nowhere to render.
+ *
+ * @param {string} caption - The figure's raw caption markdown.
+ * @returns {boolean} Whether the caption needs a `text` page.
+ */
+function captionCarriesMarkup(caption) {
+    if (!caption) return false;
+    const [inline] = md.parseInline(caption, {});
+    return (inline?.children ?? []).some(
+        (token) => token.type !== "text" && token.type !== "softbreak",
+    );
+}
+
+/**
+ * The one picture a `figure`-kind fence holds, when it holds exactly one and
+ * nothing else — the shape an `image` page can draw on its own. A grouped
+ * fence, two pictures or more, keeps the `text` page a single `src` cannot
+ * hold, and an embed that resolves to a sound rather than a picture does too,
+ * there being no audio page type.
+ *
+ * By the time a journal note's markdown reaches this pass, an embed has
+ * already been rewritten into the ordinary `![alt](src)` image every surface
+ * renders ({@link module:engine/content-embeds}), so the file this needs is
+ * already sitting in the fence's own contents rather than behind an address
+ * this pass would have to resolve a second time.
+ *
+ * @param {object} figure - The figure record, `kind` already derived.
+ * @param {object} page - From {@link splitPages}; `page.markdown` starts on
+ *   the figure's own opening line, so `figure`'s line-based offsets translate
+ *   into it directly.
+ * @returns {string|null} The picture's `src`, or `null`.
+ */
+function soleFigurePicture(figure, page) {
+    if (figure.kind !== "figure" && figure.kind !== "map") return null;
+    const offset = figure.line - 1;
+    const lines = page.markdown.split("\n");
+    const contents = lines.slice(figure.bodyStart - offset, figure.bodyEnd - offset).join("\n");
+    const images = imagesIn(contents);
+    if (images.length !== 1) return null;
+    const extension = path.extname(images[0].src).toLowerCase();
+    return IMAGE_EXTENSIONS.includes(extension) ? images[0].src : null;
+}
+
+/**
+ * Whether a figure fence is the whole of the page {@link splitPages} gave it.
+ *
+ * A figure always starts a page of its own, but nothing closes one: trailing
+ * prose before the next heading or figure stays on it, exactly as it would
+ * behind an ordinary heading. An `image` page holds a `src` and a caption and
+ * nowhere else to put that prose, so it is refused the type and kept a `text`
+ * page, where the prose renders after the figure's own div as it always has.
+ *
+ * @param {object} figure - The figure record.
+ * @param {object} page - From {@link splitPages}.
+ * @returns {boolean} Whether nothing follows the fence's closing `:::`.
+ */
+function figureIsWholePage(figure, page) {
+    const offset = figure.line - 1;
+    const after = page.markdown
+        .split("\n")
+        .slice(figure.close - offset + 1)
+        .join("\n");
+    return after.trim() === "";
+}
+
+/**
+ * The fields particular to the Foundry page a `:::figure` fence begins.
+ *
+ * A fence holding exactly one picture, captioned with no inline markup, and
+ * standing alone on its page becomes a page of type `image`: `src` the
+ * picture, `image.caption` the caption text, the page named for the figure's
+ * own number. Every other fence — grouped, an audio embed, a caption
+ * `image.caption` cannot hold, or one trailing prose keeps company with —
+ * becomes a page of type `text`.
+ *
+ * The `text` page's content is rendered and then relabeled. The render sees
+ * only this one fence — {@link scanFigures}, called again inside
+ * {@link module:engine/content-figures.renderFigureBlocks} on this page's own
+ * markdown, recounts it as the first of its kind regardless of its true,
+ * note-wide number. The fence is the whole of the figure on this page, so its
+ * label paragraph is the one element to correct, to the number the note-wide
+ * scan in {@link buildJournalEntry} already assigned.
+ *
+ * @param {object} figure - The figure record from {@link scanFigures},
+ *   carried onto the page by {@link splitPages}.
+ * @param {object} page - From {@link splitPages}.
+ * @param {string} pageId - The page's `_id`, threaded into footnote anchors.
+ * @param {Map<string, number>} footnoteNumbers - Shared across the note.
+ * @param {(address: string) => string|undefined} [resolveRole] - See
+ *   {@link splitPages}.
+ * @returns {{name: string, type: "image", src: string, image: {caption?: string}}
+ *   |{name: string, type: "text", text: {format: number, content: string}}}
+ */
+function buildFigurePageFields(figure, page, pageId, footnoteNumbers, resolveRole) {
+    const picture = soleFigurePicture(figure, page);
+    if (picture && figureIsWholePage(figure, page) && !captionCarriesMarkup(figure.caption)) {
+        let src = picture;
+        try {
+            src = resolveImg(picture) ?? picture;
+        } catch {
+            // Left as the authored pathname — the same fallback an inline
+            // image's own render takes when no configuration resolves it.
+        }
+        return {
+            name: figure.label,
+            type: "image",
+            src,
+            image: figure.hasCaption ? { caption: figure.caption } : {},
+        };
+    }
+    const label =
+        figure.hasCaption ? `${figure.label}: ${md.renderInline(figure.caption)}` : figure.label;
+    const content = renderFoundryMarkdown(
+        page.markdown,
+        undefined,
+        footnoteNumbers,
+        pageId,
+        resolveRole,
+    );
+    return {
+        name: figure.label,
+        type: "text",
+        text: {
+            format: 1,
+            content: content.replace(
+                /<p class="content-figure-label">[\s\S]*?<\/p>/,
+                () => `<p class="content-figure-label">${label}</p>`,
+            ),
+        },
+    };
+}
+
 /**
  * Compile split pages into JournalEntryPage documents.
  *
  * @param {Array<object>} rawPages - From {@link splitPages}.
  * @param {string} entryId - The owning JournalEntry's `_id`.
  * @param {string} noteName - The note, for error messages.
+ * A page whose heading carries `.secret` is given to the GM alone, by the one
+ * ownership value Foundry reads as "nobody but a GM". Every other page states
+ * no ownership and inherits the journal's. A figure-started page states none
+ * either: {@link scanFigures} validates a figure's classes against its own
+ * closed vocabulary, which carries no `.secret`.
+ *
+ * @param {Array<object>} figures - From {@link scanFigures}, numbered across
+ *   the whole note. Read by a page a heading started; a page a figure started
+ *   carries its own figure already, from {@link splitPages}.
+ * @param {(address: string) => string|undefined} [resolveRole] - See
+ *   {@link splitPages}.
  * @returns {Array<{_id: string, name: string, type: string,
  *   title: {show: boolean, level: number},
- *   text: {format: number, content: string}, _key: string}>} The page
- *   documents, in order.
+ *   text: {format: number, content: string}, _key: string,
+ *   ownership?: {default: number}}>} The page documents, in order.
  * @throws {Error} When the note has no content at all, or repeats an anchor.
  */
-export function buildPages(rawPages, entryId, noteName, captions) {
+export function buildPages(rawPages, entryId, noteName, figures, resolveRole) {
     if (rawPages.length === 0) {
         throw new Error(
             `note "${noteName}" has no Introduction content and no H1 headings — nothing to compile`,
@@ -296,18 +510,32 @@ export function buildPages(rawPages, entryId, noteName, captions) {
     }
     return rawPages.map((page) => {
         const pageId = journalPageId(entryId, page);
+        const withheld = (page.classes ?? []).includes(WITHHELD_CLASS);
+        const fields =
+            page.figure ?
+                buildFigurePageFields(page.figure, page, pageId, footnoteNumbers, resolveRole)
+            :   {
+                    name: page.name,
+                    type: "text",
+                    text: {
+                        format: 1,
+                        content:
+                            page.markdown ?
+                                renderFoundryMarkdown(
+                                    page.markdown,
+                                    figures,
+                                    footnoteNumbers,
+                                    pageId,
+                                    resolveRole,
+                                )
+                            :   "",
+                    },
+                };
         return {
             _id: pageId,
-            name: page.name,
-            type: "text",
+            ...fields,
             title: { show: true, level: page.level ?? 1 },
-            text: {
-                format: 1,
-                content:
-                    page.markdown ?
-                        renderFoundryMarkdown(page.markdown, captions, footnoteNumbers, pageId)
-                    :   "",
-            },
+            ...(withheld ? { ownership: { default: WITHHELD_OWNERSHIP } } : {}),
             _key: `!journal.pages!${entryId}.${pageId}`,
         };
     });
@@ -329,7 +557,6 @@ export function buildPages(rawPages, entryId, noteName, captions) {
  * @param {string} [params.leadName] - Name for the page before the first
  *   heading; see {@link splitPages}.
  * @param {string|null} [params.folder] - The folder id, or `null`.
- * @param {object} [params.flags] - Document flags.
  * @param {object} [params.stats] - The `_stats` block to stamp. Passed by the
  *   caller because it is a property of the *pack* being written, not of the
  *   entry: a module may ship the same content for two systems, and each pack's
@@ -344,6 +571,10 @@ export function buildPages(rawPages, entryId, noteName, captions) {
  *   module:engine/draft-notice}. It leads the first authored page,
  *   because a reader deciding whether to rely on the entry has to be told
  *   before they read it rather than after.
+ * @param {(address: string) => string|undefined} [params.resolveRole] - From
+ *   a picture's address to the role its asset declares, so a figure page's
+ *   name reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
 export function buildJournalEntry({
@@ -352,13 +583,19 @@ export function buildJournalEntry({
     markdown,
     leadName,
     folder = null,
-    flags,
     stats = defaultStats(),
     infoboxes = [],
     notice = "",
+    resolveRole,
 }) {
-    const rawPages = splitPages(markdown, leadName);
-    const pages = buildPages(rawPages, id, name, scanCaptions(markdown).captions);
+    const rawPages = splitPages(markdown, leadName, resolveRole);
+    const pages = buildPages(
+        rawPages,
+        id,
+        name,
+        scanFigures(markdown, { resolveRole }).figures,
+        resolveRole,
+    );
     for (const box of infoboxes) {
         const pageId = makeId("journal-infobox-page", `${id}:${box.id}`);
         pages.push({
@@ -379,7 +616,7 @@ export function buildJournalEntry({
         folder,
         sort: 0,
         ownership: { default: 0 },
-        flags: flags || {},
+        flags: {},
         _id: id,
         _stats: stats,
         _key: `!journal!${id}`,
@@ -521,12 +758,20 @@ export class Journals extends BasePackCompiler {
             // by the pack list this build is being driven by.
             router: this.router,
             dates: reckoningContext(this.linkIndex),
+            contentPackage: this.linkIndex?.contentPackage,
         });
 
+        // The markdown this pass reads has already had its embeds rewritten
+        // into ordinary images, each `src` the pathname `pathnameRoles` keys
+        // its roles by — so a `:::figure` of a map names itself `Map 1` here
+        // exactly as the website and the book name the same picture.
+        const roles = pathnameRoles(this.linkIndex);
+
         return buildJournalEntry({
             id,
             name,
             markdown,
+            resolveRole: (pathname) => roles.get(pathname),
             infoboxes: boxes.map((box) => ({
                 id: box.id,
                 name: `${
@@ -546,7 +791,6 @@ export class Journals extends BasePackCompiler {
             // "Introduction" — see {@link splitPages}.
             leadName: ownsDoc ? name : undefined,
             folder,
-            flags: fm.flags,
             stats: this.stats,
         });
     }