@heroiclands/package-build 22.28.0 → 23.1.0

package/engine/generated-sections.mjs

@@ -0,0 +1,223 @@
+/*
+ * 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
+ */
+
+/**
+ * A note's **generated sections**: the H1 sections the build appends after
+ * everything the author wrote, each under a fixed anchor.
+ *
+ * Two families share the one mechanism. The derived lists —
+ * {@link module:engine/derived-sections} — say where a place sits, who governs
+ * it, what it governs, which works concern the note and what the map from a
+ * place shows. The event views — {@link module:engine/event-views} — list the
+ * events concerning a note. Each section is Markdown an author could have
+ * written, so the website, the Foundry journal and the book receive one text
+ * and set it as they set an authored section: Foundry starts a page at the
+ * heading, the website a section in its table of contents, the book a section
+ * of the entry.
+ *
+ * Three rules hold for every section:
+ *
+ * - **An author's own anchor replaces it.** A note whose body declares a prose
+ *   anchor with the section's slug keeps its own section and is given no
+ *   generated one.
+ * - **A section with nothing to show is not generated.**
+ * - **Sections follow the author's text in the order of
+ *   {@link GENERATED_SECTIONS}.**
+ *
+ * This module is a leaf: it holds the order, the join and the boundary, and
+ * imports nothing, so the table expansion every surface runs can read it
+ * without reaching the derivations.
+ *
+ * @module
+ */
+
+/**
+ * Every generated section, in the order it follows the author's text: where a
+ * place sits and who governs it, then what happened, then what was written
+ * about it, then the map.
+ *
+ * @type {ReadonlyArray<Readonly<{slug: string, heading: string}>>}
+ */
+export const GENERATED_SECTIONS = Object.freeze(
+    [
+        { slug: "within", heading: "Within" },
+        { slug: "governedby", heading: "Governed by" },
+        { slug: "governedplaces", heading: "Governed places" },
+        { slug: "chronology", heading: "Chronology" },
+        { slug: "events", heading: "Events" },
+        { slug: "accounts", heading: "Accounts" },
+        { slug: "followed", heading: "What followed" },
+        { slug: "insongandstory", heading: "In song and story" },
+        { slug: "fromhere", heading: "From here" },
+    ].map((section) => Object.freeze(section)),
+);
+
+/**
+ * The directory, inside a package's own pathname space, that holds the
+ * drawings the build makes. A generated section names a drawing as
+ * `generated/<name>`, and each surface serves it from where it drew it: the
+ * website inlines it, the Foundry compile stages it into the module under
+ * `assets/generated/`, and the book draws it beside its Typst source. An
+ * authored image is never addressed here.
+ *
+ * @type {string}
+ */
+export const GENERATED_DRAWING_DIR = "generated";
+
+/**
+ * The pathname a generated section names the map from a place by.
+ *
+ * @param {string} shortcode - The place.
+ * @returns {string} `generated/from-<shortcode>.svg`.
+ */
+export function fromHereSource(shortcode) {
+    return `${GENERATED_DRAWING_DIR}/${fromHereFile(shortcode)}`;
+}
+
+/**
+ * The file the map from a place is drawn into, wherever a surface draws it.
+ *
+ * @param {string} shortcode - The place.
+ * @returns {string} `from-<shortcode>.svg`.
+ */
+export function fromHereFile(shortcode) {
+    return `from-${String(shortcode).toLowerCase()}.svg`;
+}
+
+/**
+ * The drawing an image pathname names, when it names one the build makes.
+ *
+ * @param {string} src - An image's address, as the Markdown carries it.
+ * @returns {string|null} The drawn file's name, or `null` for any other image.
+ */
+export function generatedDrawing(src) {
+    const match = /^generated\/(from-[a-z0-9_-]+\.svg)$/.exec(String(src ?? "").trim());
+    return match ? match[1] : null;
+}
+
+/**
+ * Whether an authored image addresses the directory the build's drawings use.
+ *
+ * @param {string} src - The address, exactly as authored.
+ * @returns {string} The problem, as a finding's sentence, or `""`.
+ */
+export function generatedDirectoryProblem(src) {
+    const s = String(src ?? "").trim();
+    if (s === GENERATED_DRAWING_DIR || s.startsWith(`${GENERATED_DRAWING_DIR}/`)) {
+        return (
+            `\`${s}\` is under \`${GENERATED_DRAWING_DIR}/\`, which holds the drawings ` +
+            "the build makes for its generated sections — address an authored image " +
+            "anywhere else in the package"
+        );
+    }
+    return "";
+}
+
+/**
+ * Whether a note's own body declares a prose anchor with this slug.
+ *
+ * @param {object} record - The note's index record, whose `anchors` were read
+ *   from the authored body.
+ * @param {string} slug - The section's anchor.
+ * @returns {boolean} Whether the author has written the section.
+ */
+export function authoredSection(record, slug) {
+    return (record?.anchors ?? []).some(
+        (anchor) => anchor?.kind === "prose" && anchor.slug === slug,
+    );
+}
+
+/**
+ * The heading line of one generated section, with its anchor.
+ *
+ * @param {string} slug - One of {@link GENERATED_SECTIONS}.
+ * @returns {string} `# <Heading> {#<slug>}`.
+ */
+export function sectionHeading(slug) {
+    const section = GENERATED_SECTIONS.find((one) => one.slug === slug);
+    if (!section) throw new Error(`no generated section is named "${slug}"`);
+    return `# ${section.heading} {#${section.slug}}`;
+}
+
+/**
+ * One note's sections, joined in {@link GENERATED_SECTIONS} order.
+ *
+ * @param {Iterable<Map<string, string>|undefined>} parts - Each a map of slug
+ *   to that section's Markdown, heading included.
+ * @returns {string} The sections, or `""` when there are none.
+ */
+export function joinSections(parts) {
+    const bySlug = new Map();
+    for (const part of parts) for (const [slug, text] of part ?? []) bySlug.set(slug, text);
+    return GENERATED_SECTIONS.filter((section) => bySlug.has(section.slug))
+        .map((section) => bySlug.get(section.slug).replace(/\s+$/, "") + "\n")
+        .join("\n");
+}
+
+/**
+ * A note's body with its generated sections after it — the one way the two
+ * are joined, so the pass that answers their fences and every pass that
+ * expands them read the same text.
+ *
+ * @param {string} body - The authored body.
+ * @param {string|undefined} sections - Its sections, from {@link joinSections}.
+ * @returns {string} The body the surfaces receive.
+ */
+export function appendGeneratedSections(body, sections) {
+    if (!sections) return body;
+    return `${String(body ?? "").replace(/\s+$/, "")}\n\n${sections}`;
+}
+
+/**
+ * The line a surface inserts where a note's generated sections begin, when it
+ * treats them differently from the author's text. Private-use characters, so
+ * no pass between the expansion and the split reads it as markup, and no
+ * output carries it: {@link splitGenerated} removes it.
+ *
+ * @type {string}
+ */
+export const GENERATED_BOUNDARY = "generated-sections";
+
+/**
+ * Mark where a note's generated sections begin.
+ *
+ * @param {string} markdown - The expanded body.
+ * @param {number|undefined} from - The 0-based line the sections start on,
+ *   from {@link module:engine/content-tables.expandContentTables}.
+ * @returns {string} The body, with {@link GENERATED_BOUNDARY} on its own line
+ *   before the sections; unchanged where there are none.
+ */
+export function markGenerated(markdown, from) {
+    if (from === undefined || from < 0) return markdown;
+    const lines = String(markdown).split("\n");
+    if (from > lines.length) return markdown;
+    lines.splice(from, 0, GENERATED_BOUNDARY);
+    return lines.join("\n");
+}
+
+/**
+ * Split a body at its {@link GENERATED_BOUNDARY}.
+ *
+ * @param {string} markdown - A body {@link markGenerated} marked.
+ * @returns {{authored: string, generated: string}} The author's text, and the
+ *   generated sections after it — `""` when there are none.
+ */
+export function splitGenerated(markdown) {
+    const lines = String(markdown ?? "").split("\n");
+    const at = lines.indexOf(GENERATED_BOUNDARY);
+    if (at < 0) return { authored: String(markdown ?? ""), generated: "" };
+    return {
+        authored: lines.slice(0, at).join("\n"),
+        generated: lines.slice(at + 1).join("\n"),
+    };
+}

package/engine/heading-attributes.mjs

@@ -305,9 +305,11 @@ export function withheldSections(source, bodyLine = 1) {
         sections.push({ start: index, end: starts[at + 1] ?? lines.length, heading });
     }
     // A heading that opens no page is not among the openings at all, so the
-    // class is looked for again across every heading the body states.
+    // class is looked for again across every heading the body states. The
+    // openings are keyed by body line index and a heading carries its file
+    // line, so the body's first line is subtracted to compare the two.
     for (const heading of scanHeadingAttributes(source, bodyLine).headings) {
-        if (openings.has(heading.line - 1)) continue;
+        if (openings.has(heading.line - bodyLine)) continue;
         if (!heading.classes.includes(WITHHELD_CLASS)) continue;
         errors.push({
             line: heading.line,

package/engine/helpers.mjs

@@ -920,7 +920,18 @@ export function buildContentLinkIndex(
             // discarded here — the walk yields the body and nothing read it.
             // Read from the record rather than from a second reading of the
             // note's headings — the one-anchor-reader rule.
-            anchors: new Set((record.anchors ?? []).map((anchor) => anchor.slug)),
+            anchors: new Set(
+                (record.anchors ?? [])
+                    .filter((anchor) => anchor.kind === "prose")
+                    .map((anchor) => anchor.slug),
+            ),
+            // The note's event ids, which a wikilink may not name: a link to
+            // one is refused with its own message rather than as unknown.
+            eventAnchors: new Set(
+                (record.anchors ?? [])
+                    .filter((anchor) => anchor.kind === "event")
+                    .map((anchor) => anchor.slug),
+            ),
             anchorUuids: record.foundry?.note?.anchors,
             docAnchorUuids: documentation?.foundry?.note?.anchors,
         });

package/engine/holdings.mjs

@@ -14,32 +14,17 @@
 /**
  * Derive containment and government lists from place facts. Geography comes
  * only from `data.parents`; government comes only from `data.government`.
- * Affiliation domains never supply government, and neither graph expands
- * through geographic or affiliation ancestors. Government identity preserves the Address package, type and shortcode.
+ * Neither graph expands through geographic or affiliation ancestors. Government identity preserves the Address package, type and shortcode.
  * Its system normalizes to `note` because Item and journal documents share one page.
- * Historical holdings API names remain for callers migrating their imports.
+ * The lists become a note's generated **Within**, **Governed by** and
+ * **Governed places** sections — see {@link module:engine/derived-sections}.
  * @module
  */
 import { isAddressTuple, ownDocumentSystem, parseAddress, renderAddress } from "./address.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { readCanonicalKey } from "./content-address.mjs";
 
-/** Derived keys, including retired keys removed from generated pages.
- * @type {readonly string[]}
- */
-export const HOLDINGS_KEYS = Object.freeze([
-    "contains",
-    "governed_by",
-    "governed_places",
-    "held_by",
-    "holdings",
-]);
-/** @deprecated Government advisories apply to every inhabited place subtype.
- * @type {readonly string[]}
- */
-export const HELD_SUBTYPES = Object.freeze(["settlement", "site", "structure"]);
-
-/** @typedef {{title:string,url?:string,type:string,subType?:string}} HoldingsEntry */
+/** @typedef {{title:string,url?:string,address:string,type:string,subType?:string}} HoldingsEntry */
 /**
  * @typedef {object} HoldingsNode
  * @property {string} shortcode
@@ -56,7 +41,7 @@ export const HELD_SUBTYPES = Object.freeze(["settlement", "site", "structure"]);
  */
 /** @typedef {{contains?:HoldingsEntry[],governed_by?:HoldingsEntry[],governed_places?:HoldingsEntry[]}} Holdings */
 
-/** Historical shortcode projection for callers that explicitly need one.
+/** The shortcodes a `parents` value names, bare or qualified.
  * @param {unknown} value
  * @returns {string[]}
  */
@@ -124,6 +109,7 @@ function entryOf(node) {
     return {
         title: node.title,
         ...(listed(node) ? { url: node.url } : {}),
+        address: ownKey(node),
         type: node.type,
         ...(node.subType === undefined ? {} : { subType: node.subType }),
     };
@@ -138,10 +124,13 @@ function bySubTypeThenTitle(a, b) {
 
 /** Read local facts without converting government omission into anarchy.
  * @param {object} fm
- * @param {{title:string,url?:string,package?:string,system?:string,governmentSystem?:string}} page
+ * @param {{title:string,url?:string,package?:string,system?:string,canonical?:string,governmentSystem?:string}} page
  * @returns {HoldingsNode|null}
  */
-export function holdingsNode(fm, { title, url, package: pkg, system, governmentSystem }) {
+export function holdingsNode(
+    fm,
+    { title, url, package: pkg, system, canonical, governmentSystem },
+) {
     const type = String(fm?.type ?? "");
     if (type !== "place" && type !== "affiliation") return null;
     const shortcode = String(fm?.shortcode ?? "").toLowerCase();
@@ -155,6 +144,7 @@ export function holdingsNode(fm, { title, url, package: pkg, system, governmentS
         url,
         ...(pkg ? { package: pkg } : {}),
         ...(system ? { system } : {}),
+        ...(canonical ? { canonical } : {}),
         ...(governmentSystem ? { governmentSystem } : {}),
         parents:
             type === "place" ?
@@ -294,14 +284,3 @@ export function checkGovernment(note) {
         },
     ];
 }
-
-/**
- * The historical API name for the government advisory. Tenure is no longer checked.
- * @deprecated Use checkGovernment.
- * @param {object} note - The place note.
- * @param {object} [_opts] - Historical options, no longer needed.
- * @returns {object[]} Government advisory findings.
- */
-export function checkHeld(note, _opts = {}) {
-    return checkGovernment(note);
-}

package/engine/ids.mjs

@@ -40,25 +40,31 @@ export function makeId(namespace, value) {
 }
 
 /**
- * Every content type that compiles into a Foundry `Scene` — a **map note**.
- * The three differ only in derived canvas defaults, which is the map
- * compiler's business; everything else treats them alike.
+ * Every content type that compiles into a Foundry `Scene` — a **map note**,
+ * which carries its Scene as exported from Foundry.
  *
- * Declared in this leaf module because several passes that must not depend on
- * the map compiler need it: the pack router below, and the doc-carrying type
- * set in `item-docs.mjs` (a map note's prose becomes a JournalEntry, exactly as
- * an item's or a macro's does).
+ * Declared in this leaf module because several passes need it: the pack router
+ * below, the scenes pass, and the doc-carrying type set in `item-docs.mjs` (a
+ * map note's prose becomes a JournalEntry, exactly as an item's or a macro's
+ * does).
  *
  * @type {ReadonlySet<string>}
  */
 export const MAP_TYPES = Object.freeze(new Set(["map"]));
 
 /**
- * The map subTypes, which differ only in the canvas defaults derived for them.
+ * Whether a content note's type compiles into a Scene.
  *
- * As three *types* they would cost three entries in the pack
- * router, three in the claims set and three in every consumer's section config
- * — for one idea that the specification had always described as one type.
+ * @param {string} [type] - The note's `type` frontmatter.
+ * @returns {boolean} True for a map type.
+ */
+export function isMapType(type) {
+    return MAP_TYPES.has(String(type));
+}
+
+/**
+ * The map subTypes. A subType says what kind of map a note is; every one
+ * carries its Scene as exported from Foundry.
  *
  * @type {readonly string[]}
  */

package/engine/index.mjs

@@ -280,8 +280,8 @@ export * as journals from "./journals.mjs";
 /** The Macro compiler. */
 export * as macros from "./macros.mjs";
 
-/** The map-note schema a Scene is authored in. */
-export * as mapNotes from "./map-notes.mjs";
+/** An exported Scene's compile: its fixups, keys and anchored pins. */
+export * as exportedScene from "./exported-scene.mjs";
 
 /** The Scene and Adventure compiler. */
 export * as scenes from "./scenes.mjs";
@@ -303,8 +303,8 @@ export * as compendiums from "./compendiums.mjs";
 
 // The region-event vocabulary stays flat as well as namespaced: the Foundry
 // runtime imports these three by name through
-// `@heroiclands/package-build/engine/region-events`, and they were part of this
-// barrel's surface before the pipeline arrived.
+// `@heroiclands/package-build/engine/region-events`, and this barrel carries
+// them by name too.
 export {
     CURATED_REGION_EVENTS,
     EXCLUDED_REGION_EVENTS,

package/engine/infobox-render.mjs

@@ -116,12 +116,17 @@ function valueToHtml(row, link) {
 /**
  * One entry of a `runin` group or a `list` section as HTML.
  *
+ * An entry's optional `lead` is plain text set before it, so a line such as a
+ * membership — `War Chief, Hárár (5), of Vrystwald Tribes` — links the body's
+ * name and nothing else.
+ *
  * @param {object} entry - The entry.
  * @param {(value: object) => string} link - How this medium draws a link.
  * @returns {string} HTML.
  */
 function entryToHtml(entry, link) {
-    return entry?.url || entry?.address ? link(entry) : escapeHtml(entry?.text);
+    const lead = entry?.lead ? escapeHtml(entry.lead) : "";
+    return lead + (entry?.url || entry?.address ? link(entry) : escapeHtml(entry?.text));
 }
 
 /**
@@ -265,6 +270,19 @@ function valueToTypst(row, link) {
     }
 }
 
+/**
+ * One entry of a `runin` group or a `list` section as Typst: its `lead` as
+ * plain text, then the entry, linked where the book can reach it.
+ *
+ * @param {object} entry - The entry.
+ * @param {(value: object) => string} link - How the book draws a link.
+ * @returns {string} Typst markup.
+ */
+function entryToTypst(entry, link) {
+    const lead = entry?.lead ? escapeTypst(entry.lead) : "";
+    return lead + (entry?.url || entry?.address ? link(entry) : escapeTypst(entry?.text));
+}
+
 /**
  * One section as Typst, whole and unbreakable.
  *
@@ -306,16 +324,13 @@ function sectionToTypst(section, link, lead = "") {
     } else if (section.layout === "runin") {
         for (const group of section.groups ?? []) {
             const entries = (group.entries ?? [])
-                .map((entry) =>
-                    entry?.url || entry?.address ? link(entry) : escapeTypst(entry?.text),
-                )
+                .map((entry) => entryToTypst(entry, link))
                 .join(", ");
             body.push(`#infobox-runin("${escapeTypstString(group.label ?? "")}")[${entries}]`);
         }
     } else {
         for (const entry of section.entries ?? []) {
-            const text = entry?.url || entry?.address ? link(entry) : escapeTypst(entry?.text);
-            body.push(`#infobox-runin("")[${text}]`);
+            body.push(`#infobox-runin("")[${entryToTypst(entry, link)}]`);
         }
     }