@heroiclands/package-build 22.20.0 → 22.22.0

package/engine/anchored-sections.mjs

@@ -15,8 +15,8 @@
  * **Anchored body sections** — the `# Heading {#anchor}` convention, and how a
  * compiler pulls one section out of a note's prose.
  *
- * The content format gives three anchors a document meaning: `{#appearance}`,
- * `{#dossier}` and `{#spoilers}`. *Which field* each lands in is a system's
+ * The content format gives two anchors a document meaning: `{#appearance}` and
+ * `{#dossier}`. *Which field* each lands in is a system's
  * business — SoHL writes the first to an actor's `appearance`, HM3 to an
  * actor's and an item's `description` — but *finding* it is not, so the
  * extraction lives here where every compiler reaches it.
@@ -30,6 +30,8 @@
  */
 
 import { renderFoundryMarkdown } from "./helpers.mjs";
+import { collectAnchors } from "./anchors.mjs";
+import { splitHeadingAttributes } from "./heading-attributes.mjs";
 
 /**
  * Extract the body of an H1 section whose heading carries the explicit
@@ -39,6 +41,11 @@ import { renderFoundryMarkdown } from "./helpers.mjs";
  * heading exists. Fenced code blocks are respected so `# foo` inside
  * ``` blocks does not trigger a match.
  *
+ * An anchor declared on a lower heading is found by {@link collectAnchors}
+ * but not by the `#\s+` match below, so it extracts as absent rather than as
+ * wrong — {@link misplacedAnchorSection} is the check a caller runs first to
+ * tell the two apart.
+ *
  * @param {string} body - The note body.
  * @param {string} anchorId - The anchor to find.
  * @returns {string} The section's markdown, or "".
@@ -57,8 +64,7 @@ export function extractAnchorSection(body, anchorId) {
         }
         const h1Match = !inCodeBlock ? line.match(/^\s*#\s+(.+?)\s*#*\s*$/) : null;
         if (h1Match) {
-            const anchor = h1Match[1].match(/\{#([^}]+)\}\s*$/);
-            const id = anchor?.[1]?.trim().toLowerCase() || null;
+            const id = splitHeadingAttributes(h1Match[1]).id.toLowerCase() || null;
             if (capturing) break;
             if (id === wanted) {
                 capturing = true;
@@ -81,3 +87,28 @@ export function renderSection(body, anchorId) {
     const slice = extractAnchorSection(body, anchorId);
     return slice ? renderFoundryMarkdown(slice) : "";
 }
+
+/**
+ * Where an `{#appearance}` or `{#dossier}` anchor sits on a heading below the
+ * top level, which {@link extractAnchorSection} cannot read.
+ *
+ * {@link module:engine/anchors.collectAnchors} finds the anchor at any
+ * level, because a lower heading legitimately starts a journal page. It does
+ * not feed an actor field: an H1-only extractor reads nothing from one, and a
+ * caller that trusts the empty result as "no such section" rather than
+ * "found, but unreadable" compiles a blank field with nothing to say why.
+ *
+ * @param {string} body - The note body.
+ * @param {string} anchorId - The anchor to check, case-insensitively.
+ * @param {number} [bodyLine=1] - The 1-based file line the body starts on.
+ * @returns {{line: number}|null} The misplaced anchor's line, or `null` when
+ *   it is absent or already on an H1.
+ */
+export function misplacedAnchorSection(body, anchorId, bodyLine = 1) {
+    const wanted = String(anchorId).toLowerCase();
+    const found = collectAnchors(body, bodyLine).find(
+        (anchor) => anchor.slug.toLowerCase() === wanted,
+    );
+    if (!found || found.level === 1) return null;
+    return { line: found.line };
+}

package/engine/anchors.mjs

@@ -22,23 +22,16 @@
  * anchors does this note declare?" had two answers and they disagreed on
  * `{#CalendarFormat}`.
  *
+ * The suffix itself is read by {@link module:engine/heading-attributes}, which
+ * {@link module:engine/journals.splitPages} also reads it through — so the index
+ * cannot name an anchor the pages do not carry.
+ *
  * @module
  */
 
 import { scanCaptions } from "./content-captions.mjs";
+import { HEADING_LINE, splitHeadingAttributes } from "./heading-attributes.mjs";
 
-/**
- * A heading, and the `{#slug}` anchor it declares.
- *
- * Kept identical to the pair {@link splitPages} matches, because the two must
- * agree about what an anchor is: that pass decides which sections become
- * addressable journal pages, and an index naming an anchor it does not produce
- * would advertise a link that resolves nowhere. `tests/content-index.test.ts`
- * asserts the two find the same anchors, so drift fails the suite rather than
- * shipping.
- */
-const HEADING = /^\s*(#{1,6})\s+(.+?)\s*#*\s*$/;
-const ANCHOR = /^(.*?)\s*\{#([^}]+)\}\s*$/;
 /**
  * The `{#slug}` and `:::caption {#slug}` anchors a note declares.
  *
@@ -66,16 +59,13 @@ export function collectAnchors(body, bodyLine = 1) {
         }
         if (inCodeBlock) continue;
 
-        const heading = HEADING.exec(lines[i]);
+        const heading = HEADING_LINE.exec(lines[i]);
         if (!heading) continue;
-        const anchor = ANCHOR.exec(heading[2].trim());
-        if (!anchor) continue;
-
-        const slug = anchor[2].trim();
-        if (!slug) continue;
+        const attributes = splitHeadingAttributes(heading[2]);
+        if (!attributes.id) continue;
         anchors.push({
-            slug,
-            name: anchor[1].trim(),
+            slug: attributes.id,
+            name: attributes.text,
             level: heading[1].length,
             line: bodyLine + i,
         });

package/engine/base-compiler.mjs

@@ -62,9 +62,10 @@
  */
 
 import { authoredFrontmatter } from "./index-records.mjs";
-import { renderSecretBlocks } from "./content-secrets.mjs";
-import { scanAdmonitions } from "./content-admonitions.mjs";
+import { scanBlocks } from "./content-blocks.mjs";
+import { scanHeadingAttributes, withheldSections } from "./heading-attributes.mjs";
 import { scanCaptions } from "./content-captions.mjs";
+import { footnoteFindings } from "./content-footnotes.mjs";
 import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
 import { isGmNote } from "./note-vocabulary.mjs";
 import { cloneAddressState } from "./address-values.mjs";
@@ -614,6 +615,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,37 +655,70 @@ 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,
+            });
+        }
+        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 = {
+        for (const captionError of scanCaptions(tabulated).errors) {
+            findings.push({
+                message: captionError.message,
                 line:
                     (bodyLine ?? 1) +
                     (lineMap[captionError.line - 1]?.line ?? captionError.line - 1),
                 column: captionError.column,
-            };
-            throw error;
+            });
         }
         const expressions = renderMarkdownExpressions(tabulated, {
             fm,
@@ -665,12 +727,10 @@ export class BasePackCompiler {
             file: absPath,
             bodyLine,
         });
-        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 +1297,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

@@ -325,7 +325,6 @@ export class Bundles extends BasePackCompiler {
             // it compiles into already has somewhere to put the prose.
             description: markdown.trim() ? renderFoundryMarkdown(markdown) : "",
             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)