@heroiclands/package-build 22.21.0 → 22.23.0

package/engine/base-compiler.mjs

@@ -62,9 +62,11 @@
  */
 
 import { authoredFrontmatter } from "./index-records.mjs";
-import { renderSecretBlocks } from "./content-secrets.mjs";
-import { scanAdmonitions } from "./content-admonitions.mjs";
-import { scanCaptions } from "./content-captions.mjs";
+import { scanBlocks } from "./content-blocks.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 { isGmNote } from "./note-vocabulary.mjs";
 import { cloneAddressState } from "./address-values.mjs";
@@ -124,6 +126,25 @@ import { reckoningContext } from "./reckoning-markers.mjs";
  *   says nothing 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.
  *
@@ -614,6 +635,34 @@ export class BasePackCompiler {
         this.unresolvedLinks = 0;
     }
 
+    /**
+     * Report every finding {@link BasePackCompiler#convertBody} collected
+     * across its passes, and decline the note if there were any.
+     *
+     * Reported directly, one `noteError` per finding, rather than thrown as a
+     * single wrapped message: the site build and the book report the same way,
+     * each finding at its own line, and a note with three problems meets all
+     * three in the run that found them instead of one per rebuild. The thrown
+     * sentinel carries `alreadyReported` so the compile loop's generic catch
+     * does not add a fourth, vaguer line on top of the three already said.
+     *
+     * @param {readonly {message: string, line?: number, column?: number}[]} findings
+     * @throws {Error} When `findings` is non-empty, after reporting all of them.
+     */
+    reportConvertBodyFindings(findings) {
+        for (const finding of findings) {
+            this.errorCount++;
+            this.noteError(finding.message, { line: finding.line, column: finding.column });
+        }
+        if (findings.length) {
+            const error = new Error(
+                `${findings.length} finding(s) in the note body, each reported above`,
+            );
+            error.alreadyReported = true;
+            throw error;
+        }
+    }
+
     /**
      * The body {@link BasePackCompiler#buildEntry} receives.
      *
@@ -626,51 +675,114 @@ export class BasePackCompiler {
      *   that does not convert.
      */
     convertBody(fm, body) {
-        const secretError =
-            renderSecretBlocks(body, "book").errors[0] ?? scanAdmonitions(body).errors[0];
-        if (secretError) {
-            const error = new Error(secretError.message);
-            error.position = {
+        // Every pass's own findings are collected before any of them is
+        // reported, so a note with a malformed block *and* a malformed
+        // caption *and* a bad expression surfaces all three in one run
+        // instead of one per rebuild. Each pass already returns every finding
+        // it made — `errors` or `findings`, never just the first — so nothing
+        // here re-scans; it only stops taking `[0]`.
+        const findings = [];
+        for (const secretError of scanBlocks(body).errors) {
+            findings.push({
+                message: secretError.message,
                 line: (this.currentNote?.bodyLine ?? 1) + secretError.line - 1,
                 column:
                     secretError.line === 1 ?
                         (this.currentNote?.bodyColumn ?? 1)
                     :   secretError.column,
-            };
-            throw error;
+            });
+        }
+        // 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,
+        ]) {
+            findings.push({
+                message: headingError.message,
+                line: headingError.line,
+                column:
+                    headingError.line === (this.currentNote?.bodyLine ?? 1) ?
+                        (this.currentNote?.bodyColumn ?? 1) + 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,
+            });
+        }
+        // An image sharing its paragraph with other text, a bad address or a
+        // title with nowhere to draw it — the same findings `lint` reports,
+        // asked here too so a build run on its own refuses what the lint
+        // 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,
+        })) {
+            findings.push({
+                message: imageError.message,
+                line: imageError.line,
+                column: imageError.column,
+            });
+        }
+        if (!this.constructor.convertsWikilinks) {
+            this.reportConvertBodyFindings(findings);
+            return body;
         }
-        if (!this.constructor.convertsWikilinks) 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,
         });
-        const captionError = scanCaptions(tabulated).errors[0];
-        if (captionError) {
-            const error = new Error(captionError.message);
-            error.position = {
+        const figureScan = scanFigures(tabulated);
+        for (const captionError of figureScan.errors) {
+            findings.push({
+                message: captionError.message,
                 line:
                     (bodyLine ?? 1) +
                     (lineMap[captionError.line - 1]?.line ?? captionError.line - 1),
                 column: captionError.column,
-            };
-            throw error;
+            });
         }
+        // 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 },
         });
-        if (expressions.findings.length) {
-            const finding = expressions.findings[0];
-            const error = new Error(finding.message);
-            error.position = { line: finding.line, column: finding.column };
-            throw error;
+        for (const finding of expressions.findings) {
+            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,
@@ -1237,6 +1349,11 @@ export class BasePackCompiler {
                 stats.compiled++;
                 this.onCompiled(fm, doc);
             } catch (err) {
+                // `convertBody` already reported every finding it collected,
+                // one `noteError` each, before throwing this sentinel — so the
+                // generic wrap below would only restate "failed to compile" on
+                // top of findings an author has already been told about.
+                if (err.alreadyReported) continue;
                 this.errorCount++;
                 const repeatedAnchor = err.message.match(
                     /declares the anchor \{#([^}]+)\} on more than one heading/,

package/engine/base-styles.mjs

@@ -0,0 +1,149 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The **base stylesheet** every package ships, and where it lands.
+ *
+ * Compiled content relies on a handful of rules to be legible — a definition
+ * list is the whole of it today — and five packages need them. Four of those
+ * have no stylesheet at all, so writing the rules by hand means one edit and
+ * four new files, each with a configuration entry, each free to diverge from
+ * the first time one of them is touched. This repository already ships
+ * configuration to consumers and already generates the manifest that declares
+ * a package's `styles`, so it can ship the sheet the same way: one file,
+ * staged into every package, corrected in one place.
+ *
+ * A package keeps its own stylesheet for its own needs. The base sheet carries
+ * only what all of them share.
+ *
+ * Everything here is pure but for {@link baseStylesheetSource}, which resolves
+ * a path against this module's own location.
+ *
+ * @module
+ */
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Where the shipped sheet lands inside the staged package.
+ *
+ * Under `styles/` beside a package's own sheet, and named for the toolchain so
+ * nothing a repository writes can collide with it. The path is relative to the
+ * staged package root, which is what both the stage entry and the manifest's
+ * `styles` are addressed in.
+ *
+ * @type {string}
+ */
+export const BASE_STYLESHEET_DEST = "styles/package-build-base.css";
+
+/**
+ * The cascade layer the sheet loads into, per package kind.
+ *
+ * Foundry declares its layer order in `css/foundry2.css`, ending
+ * `… layouts, system, modules, exceptions` — the eighth and ninth being, by its
+ * own comments, default game system styles and default module styles. That is
+ * what this sheet is, so it takes the layer its kind is given and is therefore
+ * the weakest thing a package can load:
+ *
+ * - **An unlayered package sheet beats it**, because an unlayered rule beats
+ *   every layered one whatever its specificity.
+ * - **A package sheet naming any other layer beats it too**, because a layer
+ *   Foundry's order does not mention is appended after the ones it does.
+ *
+ * So a package overrides the base sheet from its own, whichever way it declares
+ * one, and the override needs no `!important` and no specificity contest.
+ *
+ * @param {"system"|"module"} artifact - Which artifact is shipped.
+ * @returns {string} The layer name.
+ */
+export function baseStyleLayer(artifact) {
+    return artifact === "system" ? "system" : "modules";
+}
+
+/**
+ * The manifest `styles` entry for the base sheet.
+ *
+ * Foundry's `styles` is an array of `{layer?, src}`, and a bare string is
+ * migrated into that shape on read, so the object form is written directly.
+ *
+ * @param {"system"|"module"} artifact - Which artifact is shipped.
+ * @returns {{src: string, layer: string}} The entry.
+ */
+export function baseStyleEntry(artifact) {
+    return { src: BASE_STYLESHEET_DEST, layer: baseStyleLayer(artifact) };
+}
+
+/**
+ * The absolute path of the sheet as installed, so the stage can copy it.
+ *
+ * Resolved against this module rather than against the consumer's working
+ * directory, because the file belongs to this package and arrives through
+ * `node_modules`.
+ *
+ * @returns {string} Absolute path of the shipped stylesheet.
+ */
+export function baseStylesheetSource() {
+    return path.resolve(
+        fileURLToPath(new URL("../assets/styles", import.meta.url)),
+        "content-base.css",
+    );
+}
+
+/**
+ * The `[source, destination]` pair that stages the sheet.
+ *
+ * The destination is relative, in the same spelling the repository's own asset
+ * table uses, so the caller resolves both against the repository root exactly
+ * as it resolves every other entry.
+ *
+ * @param {string} stageDir - The configured stage directory, relative to the
+ *   repository root.
+ * @returns {[string, string]} The pair, for `stageAssets`.
+ */
+export function baseStyleStageEntry(stageDir) {
+    return [baseStylesheetSource(), path.join(stageDir, BASE_STYLESHEET_DEST)];
+}
+
+/**
+ * The manifest's `styles`, with the base sheet named first.
+ *
+ * **First rather than last**, because `styles` is load order: a package's own
+ * sheet has to be read after the base one for an override written at equal
+ * specificity in an equal layer to take. The cascade layer makes the override
+ * work anyway, and the order makes it work for the right reason.
+ *
+ * A declared entry addressing the same file is not duplicated — a repository
+ * that named the staged path itself gets one entry, keeping whatever layer it
+ * chose, so declaring it is a way of placing it rather than an error.
+ *
+ * @param {object} options
+ * @param {unknown} [options.declared] - The declared `styles`, whatever shape
+ *   it was written in; anything that is not a list is returned untouched.
+ * @param {"system"|"module"} options.artifact - Which artifact is shipped.
+ * @param {boolean} [options.enabled] - Whether the package takes the base
+ *   sheet. `false` returns the declared list unchanged.
+ * @returns {unknown} The `styles` to emit, or `undefined` when there is
+ *   nothing to emit at all.
+ */
+export function withBaseStyle({ declared, artifact, enabled = true }) {
+    if (!enabled) return declared;
+    const list =
+        Array.isArray(declared) ? declared
+        : declared === undefined ? []
+        : declared;
+    if (!Array.isArray(list)) return list;
+    const names = (entry) => (typeof entry === "string" ? entry : entry?.src);
+    if (list.some((entry) => names(entry) === BASE_STYLESHEET_DEST)) return list;
+    return [baseStyleEntry(artifact), ...list];
+}

package/engine/bundles.mjs

@@ -75,6 +75,7 @@ import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { folderField, renderFoundryMarkdown, resolveName } from "./helpers.mjs";
 import { packForType } from "./ids.mjs";
 import { readQualifier } from "./wikilinks.mjs";
+import { pathnameRoles } from "./art-fields.mjs";
 
 /**
  * Load every compiled document a bundle may hold, keyed `<docType>/<id>`.
@@ -311,6 +312,12 @@ export class Bundles extends BasePackCompiler {
             contents.push({ docType: member.docType, document });
         }
 
+        // 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 buildAdventure({
             id: fm.id,
             name,
@@ -323,9 +330,13 @@ export class Bundles extends BasePackCompiler {
             // Foundry renders on the import card. That is why a bundle earns no
             // separate documentation journal the way an item does: the document
             // it compiles into already has somewhere to put the prose.
-            description: markdown.trim() ? renderFoundryMarkdown(markdown) : "",
+            description:
+                markdown.trim() ?
+                    renderFoundryMarkdown(markdown, undefined, undefined, undefined, (pathname) =>
+                        roles.get(pathname),
+                    )
+                :   "",
             folder: this.folderResolver(authoredFolder, { isAddress: folderIsAddress }),
-            flags: fm.flags,
             stats: this.stats,
             contents,
         });

package/engine/compendiums.mjs

@@ -191,7 +191,14 @@ function cleanPackEntry(
 
     if (data.effects) data.effects.forEach((i) => cleanPackEntry(i, { clearSourceId: false }));
     if (data.items) data.items.forEach((i) => cleanPackEntry(i, { clearSourceId: false }));
-    if (data.pages) data.pages.forEach((i) => cleanPackEntry(i, { ownership: -1 }));
+    // A page's own stated default survives, because a page compiled as GM-only
+    // says so here and nowhere else; the per-user grants beside it do not, which
+    // is what the reset is for. `-1` is `INHERIT`, the value a page that says
+    // nothing takes.
+    if (data.pages)
+        data.pages.forEach((page) =>
+            cleanPackEntry(page, { ownership: page.ownership?.default ?? -1 }),
+        );
     if (data.system?.description) data.system.description = cleanString(data.system.description);
     if (data.system?.biography) data.system.biography = cleanString(data.system.biography);
     if (data.system?.textReference)