@heroiclands/package-build 25.5.5 → 25.6.1

package/engine/note-vocabulary.mjs

@@ -104,6 +104,8 @@ import {
     STANDING_FIELDS,
 } from "./standing-terms.mjs";
 import { checkDatedOffices } from "./office-holders.mjs";
+import { checkUniqueItem } from "./unique-items.mjs";
+import { checkPlaceKind } from "./place-kinds.mjs";
 import { checkAffiliationRankFloor, checkRankLadder } from "./rank-ladder.mjs";
 import { checkCalendarChoice } from "./calendar-choice.mjs";
 import { checkNoteEvents } from "./note-events.mjs";
@@ -160,6 +162,7 @@ import { checkCitedPopulations, checkPopulation } from "./populations.mjs";
 import { MARKET_CLASSES, checkMarket } from "./market-class.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkSettlementTables } from "./settlement-tables.mjs";
+import { SETTLEMENTS_FIELD } from "./settlement-terms.mjs";
 import { checkConceptList, checkCoreFlag } from "./core-vocabulary.mjs";
 import { METRE_KINDS, checkMetresField } from "./metre-declaration.mjs";
 import { checkLanguageEmphasis, checkScriptField } from "./script-emphasis.mjs";
@@ -1251,8 +1254,8 @@ const EVENT_ADDRESS = Object.freeze({
 });
 
 /**
- * The values every carried thing declares: the four a game reads, and the two
- * events of its history.
+ * The values every carried thing declares: the four a game reads, the two
+ * events of its history, and whether it is the only one of its kind.
  *
  * @type {readonly DataFieldSpec[]}
  */
@@ -1275,6 +1278,15 @@ const GEAR = Object.freeze([
             "The event in which the thing was lost — `lore-flood`, or one event of a note " +
             "as `place-ironfells#sack`.",
     },
+    {
+        name: "unique",
+        kind: "boolean",
+        shape: "`true` or `false`",
+        check: checkUniqueItem,
+        describe:
+            "`true` for a one-of-a-kind item, such as a named weapon; its note links the " +
+            "places and beings involved. Absent, the item is common.",
+    },
 ]);
 
 /** Gear that is counted rather than carried singly. */
@@ -1304,7 +1316,7 @@ const CHARGES = Object.freeze([
  * Three questions about one subject, and they are independent: who governs
  * this inhabited place, what the body states about itself where the note is a
  * body rather than somewhere within one, and whether a region's settlements
- * table agrees with its holding model and the notes it links. A type declares
+ * table agrees with the notes it links. A type declares
  * one whole-note check, so the three are composed here rather than any being
  * folded into another.
  *
@@ -1317,6 +1329,7 @@ function checkPlace(note, opts) {
         ...checkGovernment(note),
         ...checkWorldFacts(note, opts),
         ...checkSettlementTables(note, opts),
+        ...checkPlaceKind(note, opts),
     ];
 }
 
@@ -2497,10 +2510,12 @@ export const NOTE_VOCABULARY = Object.freeze({
         subTypes: Object.freeze([
             "world",
             "region",
+            "district",
             "settlement",
             "site",
             "structure",
             "feature",
+            "route",
             "celestial",
         ]),
         check: checkPlace,
@@ -2556,6 +2571,7 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "Explicit null means complete anarchy. " +
                     "A positive population with no government key produces an advisory.",
             },
+            SETTLEMENTS_FIELD,
             {
                 name: "market",
                 ...NUM,
@@ -2638,11 +2654,6 @@ export const NOTE_VOCABULARY = Object.freeze({
                 accepts: ["scenario"],
                 describe: "Scenarios that should be played before this one.",
             },
-            {
-                name: "status",
-                ...TEXT,
-                describe: "`draft`, `playtested` or `published`.",
-            },
             {
                 name: "party.size",
                 ...TEXT,

package/engine/office-holders.mjs

@@ -17,9 +17,85 @@ import { parseNoteDate } from "./note-dates.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 
 import { HOLDER_FIELDS, OFFICE_FIELDS } from "./standing-terms.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+import { isAddressTuple } from "./address.mjs";
+import { officeRoster, readStandings, standingOffices } from "./standings.mjs";
 
 export { HOLDER_FIELDS, OFFICE_FIELDS };
 
+/**
+ * A note's identity across its systems: `package-type-shortcode`, lowercased.
+ *
+ * A body's Item and its journal carry one page, and a being names the body by
+ * its `note` Address, so the system is left out.
+ *
+ * @param {{package?: string, type?: string, shortcode?: string}} tuple
+ * @returns {string} The key, or `""` where a part is missing.
+ */
+export function officeBodyKey(tuple) {
+    const parts = [tuple?.package, tuple?.type, tuple?.shortcode].map((part) =>
+        String(part ?? "").toLowerCase(),
+    );
+    return parts.every(Boolean) ? parts.join("-") : "";
+}
+
+/**
+ * Each body's offices with the living beings that hold them.
+ *
+ * Nothing is authored on the office for this: a being states the post it holds
+ * in its own `data.affiliations.<body>.office`, and this collects, for every
+ * office in a body's `governance.offices`, each being naming it. A being whose
+ * `data.died` is set holds nothing, so a former holder drops out and a vacant
+ * office lists no one. A post the body does not declare is the standing check's
+ * finding and is listed nowhere.
+ *
+ * Offices keep the body's declared order; holders are ordered by name.
+ *
+ * @param {object[]} records - Content-index records; only note records are
+ *   read.
+ * @returns {Map<string, Map<string, object[]>>} Body identity
+ *   (`package-type-shortcode`) → office → the holding beings' records, for every
+ *   body with at least one held office.
+ */
+export function officeHolders(records) {
+    const notes = records.filter((record) => isNoteRecord(record) && record.shortcode);
+    /** Body identity → office → holding beings. */
+    const named = new Map();
+    for (const record of notes) {
+        if (record.type !== "being" || record.data?.died != null) continue;
+        for (const { body, standing } of readStandings(record.data?.affiliations).entries) {
+            const key = isAddressTuple(body) ? officeBodyKey(body) : "";
+            if (!key || !mapping(standing)) continue;
+            const offices = named.get(key) ?? new Map();
+            for (const office of standingOffices(standing)) {
+                const holders = offices.get(office) ?? [];
+                if (!holders.includes(record)) holders.push(record);
+                offices.set(office, holders);
+            }
+            named.set(key, offices);
+        }
+    }
+    const nameOf = (record) => String(record.name?.full ?? record.shortcode);
+    const out = new Map();
+    for (const record of notes) {
+        if (record.type !== "affiliation") continue;
+        const key = officeBodyKey(record);
+        const claims = named.get(key);
+        if (!claims) continue;
+        const held = new Map();
+        for (const office of officeRoster(record.data?.governance?.offices).keys()) {
+            const holders = claims.get(office);
+            if (holders?.length)
+                held.set(
+                    office,
+                    holders.toSorted((a, b) => nameOf(a).localeCompare(nameOf(b), "en")),
+                );
+        }
+        if (held.size) out.set(key, held);
+    }
+    return out;
+}
+
 const mapping = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
 /**

package/engine/page-breaks.mjs

@@ -19,7 +19,7 @@ import { parseExtensionAttributes, refusedAttributes } from "./extension-attribu
 
 /** A standalone attributed break, including Markdown container prefixes. */
 const BREAK_LINE =
-    /^(?:[ \t]*(?:>[ \t]?|(?:[-+*]|\d{1,9}[.)])[ \t]+))*[ \t]*(---|\*\*\*|___)[ \t]+(\{[^\r\n]*\})[ \t]*$/;
+    /^(?<prefix>(?:[ \t]*(?:>[ \t]?|(?:[-+*]|\d{1,9}[.)])[ \t]+|\[\^[^\]\s]+\]:[ \t]*))*[ \t]*)(?<marker>---|\*\*\*|___)[ \t]+(?<attributes>\{[^\r\n]*\})[ \t]*$/;
 const PLACEMENT = "a page break stands between blocks at the top level of a note";
 
 /**
@@ -35,8 +35,13 @@ export function scanPageBreaks(source) {
     if (!lines.some((line) => BREAK_LINE.test(line))) return { breaks: [], errors: [] };
     const literal = new Set();
     const nested = new Set();
-    for (const token of blockTokens(text)) {
+    let footnoteDepth = 0;
+    for (const token of blockTokens(text, { footnotes: true })) {
+        if (token.type === "footnote_reference_open") footnoteDepth++;
+        if (token.type === "footnote_reference_close") footnoteDepth--;
         if (!token.map) continue;
+        if (footnoteDepth)
+            for (let line = token.map[0]; line < token.map[1]; line++) nested.add(line);
         const target =
             ["fence", "code_block", "html_block", "verse_div"].includes(token.type) ? literal
             : ["blockquote_open", "list_item_open"].includes(token.type) ? nested
@@ -51,10 +56,11 @@ export function scanPageBreaks(source) {
         if (literal.has(i)) continue;
         const match = BREAK_LINE.exec(lines[i]);
         if (!match) continue;
-        const parsed = parseExtensionAttributes(match[2].slice(1, -1));
-        if (match[1] !== "---" && !parsed.classes.includes("page-break")) continue;
-        const column = lines[i].indexOf(match[1]) + 1;
-        const attributeColumn = lines[i].indexOf("{") + 1;
+        const { prefix, marker, attributes } = match.groups;
+        const parsed = parseExtensionAttributes(attributes.slice(1, -1));
+        if (marker !== "---" && !parsed.classes.includes("page-break")) continue;
+        const column = prefix.length + 1;
+        const attributeColumn = lines[i].lastIndexOf(attributes) + 1;
         const at = (message) => ({ line: i + 1, column: attributeColumn, message });
         const problems = [...parsed.problems, ...refusedAttributes(parsed.values)];
         if (
@@ -68,7 +74,7 @@ export function scanPageBreaks(source) {
         if (parsed.id) problems.push("a page break does not accept an id");
         if (Object.keys(parsed.values).length)
             problems.push("a page break does not accept attributes");
-        if (match[1] !== "---")
+        if (marker !== "---")
             errors.push({ line: i + 1, column, message: "only --- accepts {.page-break}" });
         if (
             nested.has(i) ||
@@ -77,7 +83,7 @@ export function scanPageBreaks(source) {
         )
             errors.push({ line: i + 1, column, message: PLACEMENT });
         errors.push(...problems.map(at));
-        if (match[1] === "---" && !problems.length && !errors.some((error) => error.line === i + 1))
+        if (marker === "---" && !problems.length && !errors.some((error) => error.line === i + 1))
             breaks.push({ line: i + 1, column });
     }
     return { breaks, errors };
@@ -94,6 +100,28 @@ export function omitPageBreaks(source) {
     return lines.join("\n");
 }
 
+/**
+ * Preserve refused markers as literal Markdown before the book slices blocks.
+ * A slice must not make a marker eligible by discarding its original neighbour.
+ * Findings are collected from the original source before this rewrite.
+ * @param {string} source - Complete Markdown body, before splitting containers.
+ * @returns {string} Markdown with invalid markers escaped for literal rendering.
+ */
+export function escapeInvalidPageBreaks(source) {
+    const text = String(source ?? "");
+    const refused = new Set(scanPageBreaks(text).errors.map((error) => error.line));
+    if (!refused.size) return text;
+    return text
+        .split("\n")
+        .map((line, i) => {
+            if (!refused.has(i + 1)) return line;
+            const match = BREAK_LINE.exec(line.replace(/\r$/, ""));
+            const prefix = match.groups.prefix;
+            return `${prefix}\\${line.slice(prefix.length)}`;
+        })
+        .join("\n");
+}
+
 /**
  * Produce the book's page-break token, leaving ordinary thematic breaks alone.
  * @param {import("markdown-it")} md - The book parser.

package/engine/pdf-render.mjs

@@ -62,7 +62,7 @@
  * @module
  */
 
-import { scanPageBreaks } from "./page-breaks.mjs";
+import { escapeInvalidPageBreaks, scanPageBreaks } from "./page-breaks.mjs";
 import { createRenderer } from "./content-render.mjs";
 import { bookDraftNoticePreamble } from "./draft-notice.mjs";
 import { ICON_PATTERN, ICON_SIZES } from "./content-icons.mjs";
@@ -360,7 +360,7 @@ function reportUnrenderable(source, definitions, opts, original) {
         }
     }
     for (const error of [
-        ...scanPageBreaks(source).errors,
+        ...scanPageBreaks(original).errors,
         ...scanSpans(source).errors,
         ...scanRuns(source, opts.runs).errors,
         ...markupAnchorFindings(source),
@@ -522,7 +522,8 @@ export function markdownToTypst(markdown, opts = {}) {
             renderRuns(markingSource, opts.runs, undefined, { target: "book" })
         );
     const markedFootnotes = marked && definitions ? separateFootnotes(marked.markdown) : undefined;
-    const source = markedFootnotes?.markdown ?? marked?.markdown ?? authored;
+    const markedSource = markedFootnotes?.markdown ?? marked?.markdown ?? authored;
+    const source = opts.nested ? markedSource : escapeInvalidPageBreaks(markedSource);
     if (markedFootnotes) definitions = markedFootnotes.definitions;
     if (marked) {
         sharedOptions.footnoteDefinitions = definitions;

package/engine/place-kinds.mjs

@@ -0,0 +1,106 @@
+/*
+ * 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
+ */
+
+/**
+ * **What a district and a route require of their notes.**
+ *
+ * A `place/district` is a recognised division of a larger place, usually
+ * administrative: a city's quarter, a town's ward, a kingdom's shire. It always
+ * stands within a `place/settlement` or a `place/region`, named in
+ * `data.parents`. It may name its own governing affiliation in
+ * `data.government`; without one it falls under its parent's government.
+ *
+ * A `place/route` is a road, a pass or a sea lane, and the journeys it carries
+ * are its `data.routes`.
+ *
+ * @module
+ */
+
+import { isAddressTuple, parseAddress, renderAddress } from "./address.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/** The place kinds a district may stand within. */
+export const DISTRICT_PARENT_KINDS = Object.freeze(["settlement", "region"]);
+
+/**
+ * The place one `parents` entry names, as the lint's index holds it.
+ *
+ * @param {unknown} value - The authored entry.
+ * @param {object} [index] - The lint's address index.
+ * @returns {{resolved: boolean, fm?: object}} Whether it resolves, and its
+ *   frontmatter where it does.
+ */
+function parentOf(value, index) {
+    const tuple =
+        isAddressTuple(value) ? value : (
+            parseAddress(value, {
+                package: index?.contentPackage,
+                system: "note",
+                type: "place",
+                types: index?.types,
+                packages: index?.packages,
+            })
+        );
+    if (!isAddressTuple(tuple) || !index?.addressHit) return { resolved: false };
+    const hit = index.addressHit(renderAddress({ ...tuple, system: "note" }));
+    return hit ? { resolved: true, fm: hit.fm ?? hit } : { resolved: false };
+}
+
+/**
+ * Check a district's parent and a route's journeys.
+ *
+ * A district naming no parent is reported at its `subType`; one whose parents
+ * all resolve and none is a settlement or a region is reported at `parents`.
+ * A parent that does not resolve is the Address check's finding, so a district
+ * whose only parents are unresolved earns nothing more here. A route stating no
+ * `data.routes` entry is reported at its `subType`.
+ *
+ * @param {object} note - The note: `file`, `raw` and parsed `fm`.
+ * @param {{index?: object}} [options] - The lint's options.
+ * @returns {object[]} Located findings.
+ */
+export function checkPlaceKind(note, { index } = {}) {
+    const subType = note.fm?.subType;
+    const at = (path, key) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(note.raw ?? "", path, key ? { key: true } : undefined),
+        severity: "error",
+    });
+    if (subType === "district") {
+        const parents = note.fm?.data?.parents;
+        const list =
+            Array.isArray(parents) ? parents
+            : parents == null ? []
+            : [parents];
+        const message =
+            "a district stands within a settlement or a region; name one in `data.parents`";
+        if (!list.length) return [{ ...at(["subType"]), message }];
+        const found = list.map((value) => parentOf(value, index));
+        if (found.some((one) => !one.resolved)) return [];
+        if (found.some((one) => DISTRICT_PARENT_KINDS.includes(one.fm?.subType))) return [];
+        return [{ ...at(["data", "parents"], true), message }];
+    }
+    if (subType === "route") {
+        const routes = note.fm?.data?.routes;
+        if (Array.isArray(routes) && routes.length) return [];
+        return [
+            {
+                ...at(["subType"]),
+                message:
+                    "a route carries its journeys in `data.routes`; state at least one, " +
+                    "each `{ to, bearing, mode, days }`",
+            },
+        ];
+    }
+    return [];
+}