@heroiclands/package-build 25.5.5 → 25.6.1

package/docs/reference/theme-pages.md

@@ -218,6 +218,7 @@ something to show:
 | Within            | `within`         | a place                                                | the places whose `data.parents` names it, a paragraph to each kind of place                  |
 | Governed by       | `governedby`     | a place                                                | the affiliation its `data.government` names, with that affiliation's kind                    |
 | Governed places   | `governedplaces` | an affiliation                                         | the places whose `data.government` names it, a paragraph to each kind of place               |
+| Office holders    | `officeholders`  | an affiliation                                         | each office a living being holds, one line each, with its holders                            |
 | Chronology        | `chronology`     | a place                                                | the [event views](format-details.md#event-views)                                             |
 | Events            | `events`         | a being, an affiliation or a people                    | the event views                                                                              |
 | Accounts          | `accounts`       | an affiliation, a place or a people                    | the event views                                                                              |

package/engine/content-format.yaml

@@ -96,6 +96,7 @@ types:
             - durability
             - made
             - lost
+            - unique
         subTypes: []
     armorlocation:
         data:
@@ -114,6 +115,7 @@ types:
             - durability
             - made
             - lost
+            - unique
             - quantity
             - potency
             - strength
@@ -130,6 +132,7 @@ types:
             - durability
             - made
             - lost
+            - unique
             - capacity
         subTypes: []
     miscgear:
@@ -141,6 +144,7 @@ types:
             - durability
             - made
             - lost
+            - unique
             - quantity
         subTypes: []
     mystery:
@@ -189,6 +193,7 @@ types:
             - durability
             - made
             - lost
+            - unique
             - quantity
         subTypes:
             - none
@@ -268,6 +273,7 @@ types:
             - durability
             - made
             - lost
+            - unique
         subTypes: []
     lore:
         data:
@@ -323,6 +329,7 @@ types:
             - culture
             - population
             - government
+            - settlements
             - market
             - borders
             - routes
@@ -343,10 +350,12 @@ types:
         subTypes:
             - world
             - region
+            - district
             - settlement
             - site
             - structure
             - feature
+            - route
             - celestial
     scenario:
         data:
@@ -355,7 +364,6 @@ types:
             - cast
             - factions
             - follows
-            - status
             - party.size
             - party.archetypes
         subTypes:
@@ -740,12 +748,6 @@ vocabularies:
         - "4"
         - "5"
         - "6"
-    holdingModel:
-        - held
-        - endowed
-        - registered
-        - kin
-        - polis
     bearing:
         - N
         - NE

package/engine/content-html.mjs

@@ -64,7 +64,8 @@ import { positionInBody, splitFrontmatter } from "./diagnostics.mjs";
  * markdown's own angle brackets out of it: an autolink is `<https://…>`, and
  * `https` is followed by `:` rather than whitespace or `>`, so the pattern
  * stops. A comparison written in prose — `a < b` — has no name after the
- * bracket at all.
+ * bracket at all. A doubled `<<` opens a quotation, so its second bracket
+ * never starts an HTML tag.
  *
  * Attributes are consumed as "anything but a bracket", deliberately loosely: a
  * finding names the tag, and a pattern that tried to parse attribute syntax
@@ -73,7 +74,7 @@ import { positionInBody, splitFrontmatter } from "./diagnostics.mjs";
  *
  * @type {RegExp}
  */
-export const HTML_TAG = /<\/?[A-Za-z][A-Za-z0-9-]*(?:\s[^<>]*)?\/?>/g;
+export const HTML_TAG = /(?<!<)<\/?[A-Za-z][A-Za-z0-9-]*(?:\s[^<>]*)?\/?>/g;
 
 /**
  * What a note carrying raw HTML is told.

package/engine/content-index.mjs

@@ -141,6 +141,8 @@ import { EXPRESSION, renderMarkdownExpressions } from "./markdown-expressions.mj
 import { scanFigures } from "./content-figures.mjs";
 import { eventNoteIndex } from "./event-fields.mjs";
 import { derivedSections } from "./derived-sections.mjs";
+import { officeBodyKey, officeHolders } from "./office-holders.mjs";
+import { inheritDistrictGovernments } from "./holdings.mjs";
 // One reader for a note's anchors, shared with the link checker and with the
 // builds that emit a link. Re-exported because this is where callers
 // have always addressed it.
@@ -1311,6 +1313,8 @@ export function collectContentIndex(
         parsed,
     });
     resolveCultures(records, { contentPackage, contentBase, foreignRecord, problems, parsed });
+    // A district stating no government falls under its parent's.
+    inheritDistrictGovernments(records, { foreignRecord });
     const cultureNotes = records
         .filter((record) => isNoteRecord(record) && record.type === "lore")
         .map((record) => ({
@@ -1333,6 +1337,24 @@ export function collectContentIndex(
     for (const [note, inherited] of inheritance.values)
         if (Object.keys(inherited).length) note.fm.data = { ...note.fm.data, ...inherited };
 
+    // An office's holders are the living beings naming it, read once every
+    // being is recorded. A public body lists only public beings, as its page
+    // does.
+    phase("index office holders");
+    const publicHolders = officeHolders(records.filter((record) => !isGmNote(record)));
+    const allHolders = officeHolders(records);
+    for (const record of records) {
+        if (!isNoteRecord(record) || record.type !== "affiliation") continue;
+        const held = (isGmNote(record) ? allHolders : publicHolders).get(officeBodyKey(record));
+        if (!held) continue;
+        record.officeHolders = [...held].map(([office, holders]) => ({
+            office,
+            holders: holders.map((being) =>
+                readCanonicalKey(canonicalKey(being.package, "note", "being", being.shortcode)),
+            ),
+        }));
+    }
+
     // Automatic lexical sections require only the recorded frontmatter. Their
     // published anchors and journal targets therefore use the same pure body
     // projection as the surfaces, without making the index emitter async.
@@ -1924,6 +1946,7 @@ export function emitContentIndex({ contentBase, outDir, config, publication } =
                 record.data?.events?.length,
         ) ||
             derivedSections(notes, {
+                rawOf: (file) => parsed.get(file)?.raw,
                 fileOf: (record) => noteFile(tree, record),
                 config: resolved,
                 foreignIndex: loadForeignIndexes(resolved, [contentPackage]).index,

package/engine/content-links.mjs

@@ -56,6 +56,7 @@ import { readWikilink } from "./wikilink-syntax.mjs";
 import { encodeAddresses } from "./address-values.mjs";
 import fs from "node:fs";
 import { cultureRecordProblems, cultureInheritedFields } from "./culture-parents.mjs";
+import { governmentInherited } from "./holdings.mjs";
 import path from "node:path";
 
 import { matchAllOutsideCode } from "./code-fences.mjs";
@@ -248,6 +249,13 @@ export function buildLinkIndex(
         if (typeof record.languageCode === "string") note.languageCode = record.languageCode;
         const hierarchyProblems = cultureRecordProblems(record);
         note.inheritedCultureFields = cultureInheritedFields(record);
+        // A district's government taken from its parent is the parent's
+        // authored value, checked where it is written, not here.
+        if (governmentInherited(record))
+            note.inheritedCultureFields = new Set([
+                ...(note.inheritedCultureFields ?? []),
+                "government",
+            ]);
         if (hierarchyProblems)
             note.reportedCultureParents = new Set(
                 hierarchyProblems

package/engine/content-render.mjs

@@ -40,11 +40,11 @@
  *
  * A note reaches {@link Renderer#render} with its index-dependent constructs
  * already resolved by {@link module:engine/content-expand.expandContent}.
+ * Valid authored page breaks are omitted before these stages.
+ *
  * {@link Renderer#prepare} then writes the constructs markdown-it has no
  * syntax for as HTML between blank lines, in this order:
  *
- * Valid authored page breaks are omitted before these stages.
- *
  * 1. **Marked text** — a run's language, face and mapping, from the
  *    configuration's script notes.
  * 2. **Captioned items** — each figure's wrapper and label. Its number, kind

package/engine/content-tables.mjs

@@ -14,6 +14,7 @@
 import { FENCE_LINE } from "./code-fences.mjs";
 import { PAGE_LIST_LANGUAGE } from "./page-lists.mjs";
 import { appendGeneratedSections } from "./generated-sections.mjs";
+import { insertDeclaredSections } from "./declared-sections.mjs";
 import { insertLexicalSections } from "./lexical-sections.mjs";
 
 /**
@@ -129,8 +130,8 @@ export function expandContentTables(markdown, { source = "", sqlTables, pageList
                 source,
                 directive: block.join("\n"),
                 reason: failure,
-                line: i,
-                column: indent.length + 1,
+                line: prepared?.line ?? i,
+                column: prepared?.column ?? indent.length + 1,
             });
             block.forEach((value, offset) => emit(value, i + offset));
             i = close;
@@ -149,11 +150,17 @@ export function expandContentTables(markdown, { source = "", sqlTables, pageList
         if (close + 1 < lines.length && lines[close + 1].trim()) emit("", i, true);
         i = close;
     }
+    const declared = insertDeclaredSections(out.join("\n"), sqlTables?.declared, {
+        authored,
+        lineMap,
+        generatedFrom,
+        syntax: sqlTables?.syntax,
+    });
     return {
-        ...insertLexicalSections(out.join("\n"), sqlTables?.lexical, {
+        ...insertLexicalSections(declared.markdown, sqlTables?.lexical, {
             authored,
-            lineMap,
-            generatedFrom,
+            lineMap: declared.lineMap,
+            generatedFrom: declared.generatedFrom,
             syntax: sqlTables?.syntax,
         }),
         errors,

package/engine/culture-reach.mjs

@@ -345,6 +345,9 @@ export function noteTerms(index, note, entry) {
  * in a tree that describes peoples. Its ranks and offices then have no
  * culture associations for term queries.
  *
+ * The note's `data.culture` is the culture the content index resolved for it:
+ * its own, else the one its `data.parents` chain agrees on.
+ *
  * @param {object} note - An `affiliation` note.
  * @param {{index?: object}} [context]
  * @returns {object[]} One warning, at the note's `type`, or none.

package/engine/declared-sections.mjs

@@ -0,0 +1,100 @@
+/*
+ * 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
+ */
+/** Place declared content in its authored section, or create that section. */
+import { scanHeadingAttributes } from "./heading-attributes.mjs";
+import { scanBlocks } from "./content-blocks.mjs";
+
+/** Authored headings, excluding literal examples and named containers. */
+export function declaredHeadings(markdown, syntax) {
+    const blocks = (syntax ? syntax(markdown).blocks : scanBlocks(markdown)).blocks;
+    return scanHeadingAttributes(markdown).headings.filter(
+        (heading) =>
+            !blocks.some(
+                (block) => heading.line - 1 >= block.start && heading.line - 1 <= block.end,
+            ),
+    );
+}
+
+/**
+ * Insert indexed content at its heading while preserving subsequent source lines.
+ * @param {string} markdown - Expanded body.
+ * @param {Array<{slug:string,heading:string,markdown:string}>} [sections] - Declared content.
+ * @param {{authored?:string,lineMap?:object[],generatedFrom?:number,syntax?:Function}} [context] - Captured source mappings.
+ * @returns {{markdown:string,lineMap:object[],generatedFrom?:number}} Expanded body and locations.
+ */
+export function insertDeclaredSections(
+    markdown,
+    sections = [],
+    { authored = markdown, lineMap, generatedFrom, syntax } = {},
+) {
+    const lines = String(markdown ?? "").split("\n");
+    const locations = lineMap ? [...lineMap] : lines.map((_, line) => ({ line, generated: false }));
+    if (!sections.length)
+        return {
+            markdown: lines.join("\n"),
+            lineMap: locations,
+            ...(generatedFrom === undefined ? {} : { generatedFrom }),
+        };
+    const headings = declaredHeadings(authored, syntax)
+        .map((heading) => ({
+            ...heading,
+            sourceLine: heading.line - 1,
+            line: locations.findIndex(
+                (location, at) =>
+                    location.line === heading.line - 1 &&
+                    !location.generated &&
+                    (generatedFrom === undefined || at < generatedFrom),
+            ),
+        }))
+        .filter((h) => h.line >= 0);
+    const edits = [];
+    for (const section of sections) {
+        const own = headings.find((h) => h.id === section.slug || h.text === section.heading);
+        const next = own && headings.find((h) => h.line > own.line && h.level <= own.level);
+        const at = next?.line ?? generatedFrom ?? lines.length;
+        if (own && !own.id) {
+            const line = lines[own.line].replace(/\s*#*\s*$/, "");
+            lines[own.line] =
+                /\{[^{}]*\}$/.test(line) ?
+                    line.replace(/\}$/, ` #${section.slug}}`)
+                :   line + ` {#${section.slug}}`;
+        }
+        edits.push({
+            at,
+            source: own?.sourceLine ?? Math.max(0, String(authored).split("\n").length - 1),
+            lines: [
+                "",
+                ...(own ?
+                    section.markdown
+                :   `# ${section.heading} {#${section.slug}}\n\n${section.markdown}`
+                ).split("\n"),
+                "",
+            ],
+        });
+    }
+    for (const edit of edits.sort((a, b) => b.at - a.at)) {
+        lines.splice(edit.at, 0, ...edit.lines);
+        locations.splice(
+            edit.at,
+            0,
+            ...edit.lines.map(() => ({ line: edit.source, generated: true })),
+        );
+        if (generatedFrom !== undefined && edit.at <= generatedFrom)
+            generatedFrom += edit.lines.length;
+    }
+    return {
+        markdown: lines.join("\n"),
+        lineMap: locations,
+        ...(generatedFrom === undefined ? {} : { generatedFrom }),
+    };
+}

package/engine/derived-sections.mjs

@@ -21,10 +21,12 @@
  * | Within            | `within`         | a place              | the places whose `parents` names it, grouped by kind         |
  * | Governed by       | `governedby`     | a place              | the affiliation its `data.government` names                  |
  * | Governed places   | `governedplaces` | an affiliation       | the places naming it as government, grouped by kind          |
+ * | Office holders    | `officeholders`  | an affiliation       | each declared office's living holders, from the beings' own `office` |
  * | In song and story | `insongandstory` | any note             | the works naming it, or one of its events, in `subjects`     |
  * | From here         | `fromhere`       | a place on a border or a route | the map from it, as an image                       |
  *
- * The lists are the derivations {@link module:engine/holdings} and
+ * The lists are the derivations {@link module:engine/holdings},
+ * {@link module:engine/office-holders} and
  * {@link module:engine/literature-works} make, over this package's records and
  * every fetched index. An entry naming a note that publishes a page is a
  * wikilink with an empty label, so each surface resolves it its own way and
@@ -39,6 +41,7 @@
  */
 
 import fs from "node:fs";
+import { assertSettlementRecords, settlementMarkdown } from "./settlement-tables.mjs";
 import path from "node:path";
 
 import {
@@ -52,6 +55,8 @@ import { isNoteRecord } from "./index-records.mjs";
 import { foreignWorksNodes, worksNode, worksPages } from "./literature-works.mjs";
 import { buildMaps, relatedPlaces } from "./map-build.mjs";
 import { mapWorld } from "./map-places.mjs";
+import { officeBodyKey, officeHolders } from "./office-holders.mjs";
+import { renderAddress } from "./address.mjs";
 import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
 
 /**
@@ -65,10 +70,12 @@ import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
 export const PLACE_KIND_LABELS = Object.freeze({
     world: "Worlds",
     region: "Regions",
+    district: "Districts",
     settlement: "Settlements",
     site: "Sites",
     structure: "Structures",
     feature: "Features",
+    route: "Routes",
     celestial: "Celestial places",
 });
 
@@ -166,6 +173,22 @@ function section(slug, content) {
     return `${sectionHeading(slug)}\n\n${content}\n`;
 }
 
+/**
+ * A body's offices, one line each, with the beings holding each.
+ *
+ * @param {Map<string, object[]>} held - Office → its holders' records.
+ * @returns {string} Markdown.
+ */
+function officeLines(held) {
+    const holder = (record) =>
+        record.address ?
+            `[[${renderAddress({ ...record.address.canonical, system: "note" })}|]]`
+        :   plain(titleOf(record));
+    return [...held]
+        .map(([office, holders]) => `- **${plain(office)}:** ${holders.map(holder).join(", ")}`)
+        .join("\n");
+}
+
 /**
  * The note's name, as the derivations title an entry.
  *
@@ -257,12 +280,18 @@ export function drawMapsFrom(records, { outDir, foreignIndex = new Map(), config
  *   prepared results are keyed.
  * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes.
  * @param {object} [opts.config] - The resolved configuration.
+ * @param {(file:string)=>string|undefined} [opts.rawOf] - Captured source locators.
+ * @param {object[]} [opts.all=records] - Complete records for settlement validation.
  * @param {string} [opts.only] - One note file to give sections to; absent,
  *   every note.
  * @returns {Map<string, Map<string, string>>} Note file to its sections, each
  *   keyed by its slug, for every note given at least one.
  */
-export function derivedSections(records, { fileOf, foreignIndex = new Map(), config, only }) {
+export function derivedSections(
+    records,
+    { fileOf, foreignIndex = new Map(), config, only, rawOf, all = records },
+) {
+    assertSettlementRecords(all, { fileOf, foreignIndex, rawOf });
     const notes = records.filter((record) => isNoteRecord(record) && record.shortcode);
     const pages = notes.filter((record) => record.address);
     const nodeOf = (record) => ({
@@ -286,6 +315,7 @@ export function derivedSections(records, { fileOf, foreignIndex = new Map(), con
         { types: new Set(Object.keys(NOTE_VOCABULARY)) },
     );
     const mapped = new Set(placesWithMaps(notes, { foreignIndex, config }));
+    const offices = officeHolders(notes);
 
     const out = new Map();
     for (const record of pages) {
@@ -297,6 +327,8 @@ export function derivedSections(records, { fileOf, foreignIndex = new Map(), con
             if (content && !authoredSection(record, slug))
                 sections.set(slug, section(slug, content));
         };
+        const settlements = settlementMarkdown(record);
+        if (settlements) sections.set("settlements", section("settlements", settlements));
         if (lists.contains?.length) add("within", groupedPlaces(lists.contains));
         if (lists.governed_by?.length)
             add(
@@ -305,6 +337,8 @@ export function derivedSections(records, { fileOf, foreignIndex = new Map(), con
             );
         if (lists.governed_places?.length)
             add("governedplaces", groupedPlaces(lists.governed_places));
+        const held = record.type === "affiliation" && offices.get(officeBodyKey(record));
+        if (held) add("officeholders", officeLines(held));
         const written = works.get(key)?.works ?? [];
         if (written.length)
             add(

package/engine/dictionary-rows.mjs

@@ -49,6 +49,7 @@
  */
 
 import { pluralOf, pluralByRule } from "./word-inflections.mjs";
+import { standingOffices } from "./standings.mjs";
 export { pluralOf, pluralByRule } from "./word-inflections.mjs";
 import { createHash } from "node:crypto";
 import { parseAddress, renderAddress } from "./address.mjs";
@@ -393,7 +394,7 @@ export function dictionaryAndTermRows(records, all = records) {
                     :   [];
                 add("office", title, isMap(office) ? office.description : office, [
                     ...holders,
-                    ...membersOf(body, (standing) => standing.office === title),
+                    ...membersOf(body, (standing) => standingOffices(standing).includes(title)),
                 ]);
             }
         governance.set(body, rows);

package/engine/encoding-template.mjs

@@ -21,6 +21,12 @@ const scalar = (value) =>
     !/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value);
 const base = (value) => value.normalize("NFD").replace(/\p{M}/gu, "");
 const slug = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Each diaeresis vowel and the plain vowel whose mapping writes it. */
+const DIAERESIS_VOWELS = Object.freeze(
+    Object.fromEntries(
+        [..."aeiouAEIOU"].map((plain) => [(plain + "\u0308").normalize("NFC"), plain]),
+    ),
+);
 const codeName = /^[A-Za-z0-9_]+$/;
 
 /**
@@ -339,12 +345,27 @@ export function templateProgram(data, options, fault) {
         ]),
     ];
     if (!Array.isArray(accepts)) fault("accepts", "accepts must be a list of characters or ranges");
+    // A diaeresis vowel no source names is written with its plain vowel's rows,
+    // and decoding restores it by rule.
+    const named = [...mappings.map(([from]) => from), ...contextual.map((r) => r.from)];
+    const derived =
+        rules.diaeresis?.allowed === true ?
+            Object.fromEntries(
+                Object.entries(DIAERESIS_VOWELS).filter(
+                    ([letter, plain]) =>
+                        named.includes(plain) &&
+                        !named.some((from) => from.includes(letter)) &&
+                        !separators.some((row) => row.from.includes(letter)),
+                ),
+            )
+        :   undefined;
     return {
         definition: {
             name: "encoding-note",
             fonts: [data.font],
             accepts: [
                 ...accepts,
+                ...Object.keys(derived ?? {}),
                 ...STANDARD_ROWS.flatMap((r) => [...(Array.isArray(r) ? r[0] : r.from)]),
             ],
             separator: " ",
@@ -366,6 +387,13 @@ export function templateProgram(data, options, fault) {
                 maxVowelGroup: Math.max(0, ...vowelGroups.map((group) => [...group].length)),
                 stress,
                 diaeresis: rules.diaeresis?.allowed === false,
+                apart:
+                    derived ?
+                        Object.freeze({
+                            letters: Object.freeze(derived),
+                            groups: Object.freeze(vowelGroups),
+                        })
+                    :   undefined,
                 grave: rules["grave-accent"]?.allowed === false,
             }),
         },

package/engine/encoding-terms.mjs

@@ -89,18 +89,26 @@ export const ENCODING_RULE_FIELDS = Object.freeze([
             describe: "The complete authored group inventory.",
         },
     ]),
-    ...["diaeresis", "grave-accent"].map((name) =>
-        block(name, `Whether ${name} mappings are allowed.`, [
-            {
-                name: "allowed",
-                kind: "boolean",
-                shape: "true or false",
-                required: true,
-                describe:
-                    "False forbids the accent; true permits explicitly mapped and accepted characters.",
-            },
-        ]),
-    ),
+    block("diaeresis", "Whether diaeresis vowels are allowed, and how they are written.", [
+        {
+            name: "allowed",
+            kind: "boolean",
+            shape: "true or false",
+            required: true,
+            describe:
+                "False forbids the diaeresis; true derives plain-vowel mappings and restores splits where a declared group's native mapping distinguishes joined and separate vowels. Exact conversion refuses an unrecoverable derived group split; canonical conversion keeps its conventional reading.",
+        },
+    ]),
+    block("grave-accent", "Whether grave-accent mappings are allowed.", [
+        {
+            name: "allowed",
+            kind: "boolean",
+            shape: "true or false",
+            required: true,
+            describe:
+                "False forbids the accent; true permits explicitly mapped and accepted characters.",
+        },
+    ]),
     {
         name: "contextual-mappings",
         kind: "list",