@heroiclands/package-build 25.5.5 → 25.6.1

package/engine/encoding.mjs

@@ -470,7 +470,11 @@ function checkGroupCase(enc, groups, text, at, bound) {
  * @param {string} text
  * @param {{font?: string, verse?: boolean, start?: number, end?: number}} [options]
  */
-function encodeRawPieces(enc, text, { font, verse = false, start = 0, end = text.length } = {}) {
+function encodeRawPieces(
+    enc,
+    text,
+    { font, verse = false, start = 0, end = text.length, stops = [] } = {},
+) {
     const groups = tiers(enc, font);
     if (typeof text !== "string") throw new EncodingError("Text must be a string");
     if (
@@ -485,9 +489,13 @@ function encodeRawPieces(enc, text, { font, verse = false, start = 0, end = text
         });
     const bound = end;
     const out = [];
-    let at = start;
+    let at = start,
+        stop = 0;
     while (at < bound) {
         const first = firstAt(text, at);
+        while (stop < stops.length && stops[stop] <= at) stop++;
+        // A row never spans the start of a diaeresis vowel written by its plain vowel.
+        const limit = Math.min(bound, stops[stop] ?? bound);
         if (first === OPEN) {
             const close = span(text.slice(0, bound), at, OPEN, CLOSE);
             out.push(
@@ -545,7 +553,7 @@ function encodeRawPieces(enc, text, { font, verse = false, start = 0, end = text
             continue;
         }
         if (!enc.template) checkGroupCase(enc, groups, text, at, bound);
-        const row = enc.accepted.has(first) ? rowAt(enc, groups, text, at, bound) : null;
+        const row = enc.accepted.has(first) ? rowAt(enc, groups, text, at, limit) : null;
         if (!row)
             refused(
                 enc,
@@ -688,7 +696,13 @@ function sourceDetails(enc, text, options) {
                     pointSlice(normalized.slice(0, bound), at, enc.template.maxVowelGroup)
                 :   "";
             const lower = lookahead.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
-            const group = enc.template?.vowelGroups.find((value) => lower.startsWith(value));
+            const group = enc.template?.vowelGroups.find(
+                (value) =>
+                    lower.startsWith(value) &&
+                    [...lookahead]
+                        .slice(1, [...value].length)
+                        .every((letter) => !/[\u0308\u0300]/u.test(letter.normalize("NFD"))),
+            );
             if (group) {
                 let cursor = at;
                 for (let i = 0; i < [...group].length; i++) {
@@ -713,7 +727,16 @@ function sourceDetails(enc, text, options) {
             });
         throw error;
     }
-    return projection;
+    const letters = enc.template?.apart?.letters;
+    if (!letters) return { ...projection, folded: normalized, stops: [] };
+    const stops = [];
+    let folded = "";
+    for (let at = 0; at < normalized.length; at++) {
+        const plain = at >= begin && at < bound ? letters[normalized[at]] : undefined;
+        if (plain) stops.push(at);
+        folded += plain ?? normalized[at];
+    }
+    return { ...projection, folded, stops };
 }
 
 /**
@@ -736,16 +759,49 @@ export function validateSource(enc, text, options = {}) {
  */
 export function encodePieces(enc, text, options = {}) {
     if (!enc?.template) return encodeRawPieces(enc, text, options);
-    const { normalized, sourceAt, begin, bound } = sourceDetails(enc, text, options);
+    const { normalized, folded, stops, sourceAt, begin, bound } = sourceDetails(enc, text, options);
     try {
-        return encodeRawPieces(enc, normalized, { ...options, start: begin, end: bound }).map(
-            (one) => ({
-                ...one,
-                from: text.slice(sourceAt[one.start], sourceAt[one.end]),
-                start: sourceAt[one.start],
-                end: sourceAt[one.end],
-            }),
-        );
+        const pieces = encodeRawPieces(enc, folded, {
+            ...options,
+            start: begin,
+            end: bound,
+            stops,
+        });
+        if (enc.roundTrip === "exact" && stops.length) {
+            const native = pieces.map((one) => one.to).join("");
+            const decoded = decodeTemplatePieces(enc, native, options);
+            let nativeAt = 0;
+            for (const one of pieces) {
+                const expected = normalized.slice(one.start, one.end);
+                const marked = stops.find(
+                    (at) =>
+                        at >= one.start &&
+                        at < one.end &&
+                        splitsDeclaredGroup(enc, normalized, at, begin, bound),
+                );
+                if (
+                    marked !== undefined &&
+                    !decoded.some(
+                        (step) =>
+                            step.start === nativeAt &&
+                            step.end === nativeAt + one.to.length &&
+                            step.from === expected,
+                    )
+                )
+                    textError(
+                        folded,
+                        marked,
+                        "The encoding cannot distinguish this diaeresis split in an exact round trip",
+                    );
+                nativeAt += one.to.length;
+            }
+        }
+        return pieces.map((one) => ({
+            ...one,
+            from: text.slice(sourceAt[one.start], sourceAt[one.end]),
+            start: sourceAt[one.start],
+            end: sourceAt[one.end],
+        }));
     } catch (error) {
         if (error instanceof EncodingError && error.offset !== undefined)
             throw new EncodingError(error.message, {
@@ -845,6 +901,12 @@ function decodeRawText(enc, text, { font } = {}) {
  */
 export function decodeText(enc, text, options = {}) {
     if (!enc?.template) return decodeRawText(enc, text, options);
+    return decodeTemplatePieces(enc, text, options)
+        .map((one) => one.from)
+        .join("");
+}
+
+function decodeTemplatePieces(enc, text, options = {}) {
     const readings = tiers(enc, options.font)[0].readings;
     if (typeof text !== "string") throw new EncodingError("Text must be a string");
     if (!templateReaders.has(enc)) {
@@ -905,7 +967,7 @@ export function decodeText(enc, text, options = {}) {
                 failedContext = Math.min(failedContext, at);
                 continue;
             }
-            paths.set(at, { from: row.from, next });
+            paths.set(at, { from: row.from, row, next });
         }
     }
     if (!paths.has(0)) {
@@ -950,8 +1012,76 @@ export function decodeText(enc, text, options = {}) {
     const out = [];
     for (let at = 0; at < text.length;) {
         const step = paths.get(at);
-        out.push(step.from);
+        out.push({ from: step.from, row: step.row, start: at, end: step.next });
         at = step.next;
     }
-    return out.join("");
+    const apart = enc.template.apart;
+    if (!apart) return out;
+    return restoreDiaeresis(enc, out, options);
+}
+
+/** Restore only joins contradicted by the selected native row boundaries. */
+function restoreDiaeresis(enc, pieces, options) {
+    const text = pieces.map((one) => one.from).join("");
+    const letters = [];
+    let offset = 0;
+    for (const [part, piece] of pieces.entries()) {
+        for (const char of piece.from) {
+            letters.push({ char, part, offset, literal: !piece.row });
+            offset += char.length;
+        }
+    }
+    const groups = tiers(enc, options.font);
+    for (let i = 0; i < letters.length; i++) {
+        if (letters[i].literal) continue;
+        const group = enc.template.apart.groups.find((value) => {
+            const span = [...value];
+            if (
+                !span.every((char, k) => {
+                    const letter = letters[i + k];
+                    return (
+                        letter &&
+                        !letter.literal &&
+                        letter.char.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase() ===
+                            char &&
+                        (k === 0 || letter.char.normalize("NFD").length === 1)
+                    );
+                })
+            )
+                return false;
+            const row = rowAt(enc, groups, text, letters[i].offset);
+            return row && row.from.toLowerCase() === value;
+        });
+        if (!group) continue;
+        const end = i + [...group].length;
+        let boundary = i + 1;
+        while (boundary < end && letters[boundary].part === letters[i].part) boundary++;
+        if (boundary === end) {
+            i = end - 1;
+            continue;
+        }
+        const letter = letters[boundary];
+        const marked = (letter.char + "\u0308").normalize("NFC");
+        if (enc.template.apart.letters[marked]) {
+            letter.char = marked;
+            i = boundary - 1;
+        }
+    }
+    const output = pieces.map((piece) => ({ ...piece, from: "" }));
+    for (const letter of letters) output[letter.part].from += letter.char;
+    return output;
+}
+
+/** Whether a derived mark actually splits one of this note's declared groups. */
+function splitsDeclaredGroup(enc, text, at, begin, bound) {
+    for (const group of enc.template.apart.groups) {
+        const count = [...group].length;
+        // The supported diaeresis letters are one NFC UTF-16 unit each.
+        for (let start = Math.max(begin, at - count + 1); start < at; start++) {
+            const span = pointSlice(text.slice(0, bound), start, count);
+            if (start + span.length <= at) continue;
+            if (span.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase() === group) return true;
+        }
+    }
+    return false;
 }

package/engine/generated-sections.mjs

@@ -57,9 +57,11 @@ export const CHRONOLOGY_SLUG = "chronology";
  */
 export const GENERATED_SECTIONS = Object.freeze(
     [
+        { slug: "settlements", heading: "Settlements" },
         { slug: "within", heading: "Within" },
         { slug: "governedby", heading: "Governed by" },
         { slug: "governedplaces", heading: "Governed places" },
+        { slug: "officeholders", heading: "Office holders" },
         { slug: CHRONOLOGY_SLUG, heading: "Chronology" },
         { slug: "events", heading: "Events" },
         { slug: "accounts", heading: "Accounts" },

package/engine/holdings.mjs

@@ -14,7 +14,9 @@
 /**
  * Derive containment and government lists from place facts. Geography comes
  * only from `data.parents`; government comes only from `data.government`.
- * Neither graph expands through geographic or affiliation ancestors. Government identity preserves the Address package, type and shortcode.
+ * Neither graph expands through affiliation ancestors, and government expands
+ * through geographic ones only for a district stating none, which the content
+ * index resolves before these lists read it. Government identity preserves the Address package, type and shortcode.
  * Its system normalizes to `note` because Item and journal documents share one page.
  * The lists become a note's generated **Within**, **Governed by** and
  * **Governed places** sections — see {@link module:engine/derived-sections}.
@@ -255,6 +257,106 @@ export function holdingsPages(nodes, { governmentNodes = [] } = {}) {
     return lists;
 }
 
+/* --------------------------------------------------------------------- */
+/*  A district's government                                               */
+/* --------------------------------------------------------------------- */
+
+/** Districts whose government the index supplied from a parent. */
+const inheritedGovernment = new WeakSet();
+
+/**
+ * Whether a record's `data.government` came from a parent rather than its own
+ * note.
+ *
+ * @param {object} record - An index record.
+ * @returns {boolean} True for a district that inherited its government.
+ */
+export function governmentInherited(record) {
+    return inheritedGovernment.has(record);
+}
+
+/**
+ * Give each district that states no government its parent's.
+ *
+ * A `place/district` falls under the government of the place it stands
+ * within. One stating no `data.government` key takes the value of its nearest
+ * parent that states the key, walking `data.parents` breadth first, in the
+ * order written, through any parent that states none, and never visiting a
+ * place twice. An explicit value on the district, `null` (complete anarchy)
+ * included, is its own and is kept; a parent's explicit `null` is inherited as
+ * anarchy. Every reader of the index — the Governed by and Governed places
+ * sections, the "missing government" advisory, a consumer of the published
+ * index — then reads the effective government at `data.government`.
+ *
+ * @param {object[]} records - Content-index records, edited in place.
+ * @param {object} [opts]
+ * @param {(key: string) => object|undefined} [opts.foreignRecord] - A fetched
+ *   index's record by canonical Address, for a parent in a dependency.
+ * @returns {void}
+ */
+export function inheritDistrictGovernments(records, { foreignRecord } = {}) {
+    const keyOf = (pkg, shortcode) =>
+        renderAddress({
+            package: String(pkg ?? "local"),
+            system: "note",
+            type: "place",
+            shortcode: String(shortcode).toLowerCase(),
+        });
+    const places = new Map();
+    for (const record of records) {
+        if (record?.type !== "place" || record.documents || !record.shortcode) continue;
+        const key = keyOf(record.package, record.shortcode);
+        if (!places.has(key)) places.set(key, record);
+    }
+    const parentKeys = (record) => {
+        const parents = record?.data?.parents ?? record?.parents;
+        const list =
+            Array.isArray(parents) ? parents
+            : parents == null ? []
+            : [parents];
+        return list
+            .map((value) => {
+                if (isAddressTuple(value)) return keyOf(value.package, value.shortcode);
+                const tuple =
+                    readCanonicalKey(String(value ?? "")) ??
+                    parseAddress(value, {
+                        package: record.package ?? "local",
+                        system: "note",
+                        type: "place",
+                        types: new Set(["place"]),
+                    });
+                return isAddressTuple(tuple) ? keyOf(tuple.package, tuple.shortcode) : "";
+            })
+            .filter(Boolean);
+    };
+    const stated = (record) => {
+        const data = record?.data && typeof record.data === "object" ? record.data : record;
+        return data && Object.hasOwn(data, "government") && !inheritedGovernment.has(record) ?
+                { value: data.government }
+            :   undefined;
+    };
+    for (const district of places.values()) {
+        if (district.subType !== "district") continue;
+        const data = district.data && typeof district.data === "object" ? district.data : {};
+        if (Object.hasOwn(data, "government")) continue;
+        const seen = new Set([keyOf(district.package, district.shortcode)]);
+        const queue = parentKeys(district);
+        let found;
+        while (queue.length && !found) {
+            const key = queue.shift();
+            if (seen.has(key)) continue;
+            seen.add(key);
+            const parent = places.get(key) ?? foreignRecord?.(key);
+            if (!parent) continue;
+            found = stated(parent);
+            if (!found) queue.push(...parentKeys(parent));
+        }
+        if (!found) continue;
+        district.data = { ...data, government: found.value };
+        inheritedGovernment.add(district);
+    }
+}
+
 /* --------------------------------------------------------------------- */
 /*  The lint                                                              */
 /* --------------------------------------------------------------------- */
@@ -264,8 +366,10 @@ export function holdingsPages(nodes, { governmentNodes = [] } = {}) {
  * Missing, null or zero population establishes no inhabited population.
  * Property presence distinguishes omitted government from explicit null,
  * which means complete anarchy. Non-null values are validated by the declared
- * affiliation reference field. Neither geographic containment nor tenure
- * supplies this fact, and the rule is independent of place subtype.
+ * affiliation reference field. Tenure never supplies this fact, and
+ * containment supplies it only to a district, which the content index gives
+ * its nearest parent's government (see {@link inheritDistrictGovernments}), so
+ * a district under a governed place is never advised.
  *
  * @param {object} note - The note with parsed frontmatter and raw source.
  * @returns {object[]} Located warning findings.

package/engine/index-records.mjs

@@ -42,7 +42,8 @@ import { isAddressTuple } from "./address.mjs";
  * since a note declaring its own is a hard error — and it matches what
  * the content-table expander puts on the same field, so a query reads the same
  * value from either. `file` namespaces the note's place in the tree, again
- * matching the expander's `file.*`.
+ * matching the expander's `file.*`. `officeHolders` lists, on a body, the
+ * living beings whose own standing names each of its offices.
  *
  * Both are checked rather than assumed: `folder` is real frontmatter on most
  * notes, so the neighbouring names are close enough to a real key that a silent
@@ -68,6 +69,7 @@ export const DERIVED_KEYS = Object.freeze([
     "citations",
     "names",
     "runs",
+    "officeHolders",
 ]);
 
 /**

package/engine/index.mjs

@@ -103,7 +103,7 @@ export * as populations from "./populations.mjs";
 /** What trade a settlement supports: the six-step market scale, and the check that holds a value to it. */
 export * as marketClass from "./market-class.mjs";
 
-/** A region's settlements table: the holding models, the columns, and the check that holds a table to them. */
+/** A region's settlements table: its rows, the columns, and the check that holds a table to them. */
 export * as settlementTables from "./settlement-tables.mjs";
 
 /** The places a map is drawn from, read from the content index, and what `parents` says about them. */

package/engine/language-data.mjs

@@ -1071,7 +1071,6 @@ export function checkLanguageData(note, { index, types } = {}) {
     for (const kind of SCOPE_KINDS) {
         listOf(scope[kind]).forEach((value, i) => {
             const path = ["data", "scope", kind, i];
-            if (kind === "paths") return;
             if (kind === "types") {
                 if (types && typeof value === "string" && !types.includes(value))
                     findings.push(finding(path, "error", `\`${value}\` is not a note type`));

package/engine/language-rows.mjs

@@ -413,14 +413,12 @@ export function inScope(record, address, scope) {
         const wanted = values(kind);
         return strings(list).some((one) => wanted.has(one));
     };
-    const file = typeof record.file?.path === "string" ? record.file.path : "";
     return (
         values("addresses").has(address) ||
         any("folders", data.packFolder) ||
         any("cultures", data.culture) ||
         any("lore", data.lore) ||
-        any("parents", data.parents) ||
-        strings(scope.paths).some((prefix) => file.startsWith(prefix))
+        any("parents", data.parents)
     );
 }
 

package/engine/language-terms.mjs

@@ -152,8 +152,12 @@ export const JOIN_MEETINGS = Object.freeze(["C+C", "V+C", "V+V"]);
  */
 export const JOIN_RULES = Object.freeze(["merge", "insert", "drop", "double"]);
 
-/** What a written mark says of its letter. */
-export const MARK_KINDS = Object.freeze(["stress", "length", "apart"]);
+/**
+ * What a written mark says of its letter: `stress` falls on it, `length` holds
+ * it longer, `apart` says it apart from its neighbour, `quality` changes
+ * which vowel is said, and `tone` marks a rising or falling pitch.
+ */
+export const MARK_KINDS = Object.freeze(["stress", "length", "apart", "quality", "tone"]);
 
 /** How many of a mark a word may carry: `one` at most, or `any` number. */
 export const MARK_LIMITS = Object.freeze(["one", "any"]);
@@ -320,13 +324,6 @@ export const SCOPE_FIELDS = Object.freeze([
         entries: Object.freeze({ kind: "address", shape: "an Address" }),
         describe: "These notes themselves.",
     }),
-    Object.freeze({
-        name: "paths",
-        kind: "list",
-        shape: "a list of content paths",
-        entries: Object.freeze({ kind: "string", shape: "a path such as `Regions/Aelwyth/`" }),
-        describe: "Every note whose file sits below one of these paths of the content tree.",
-    }),
     Object.freeze({
         name: "types",
         kind: "list",
@@ -1926,7 +1923,7 @@ export const LANGUAGE_DATA_FIELDS = Object.freeze([
     Object.freeze({
         name: "scope",
         kind: "map",
-        shape: "a map — `{ folders?, cultures?, lore?, parents?, addresses?, paths?, types?, skip? }`",
+        shape: "a map — `{ folders?, cultures?, lore?, parents?, addresses?, types?, skip? }`",
         fields: SCOPE_FIELDS,
         describe: "The notes the register covers. A language skill note only.",
     }),

package/engine/map-dot.mjs

@@ -131,6 +131,26 @@ export const STYLE = Object.freeze({
         penwidth: 2.0,
         extraStyle: "rounded",
     },
+    district: {
+        shape: "box",
+        fill: "#C5E1A5",
+        border: DEFAULT_BORDER,
+        fontsize: 9,
+        width: 0.8,
+        height: 0.4,
+        penwidth: 1.0,
+        extraStyle: "rounded,dashed",
+    },
+    route: {
+        shape: "parallelogram",
+        fill: "#FFE082",
+        border: DEFAULT_BORDER,
+        fontsize: 9,
+        width: 0.9,
+        height: 0.4,
+        penwidth: 1.0,
+        extraStyle: "",
+    },
     settlement: {
         shape: "ellipse",
         fill: "#A5D6A7",
@@ -187,10 +207,12 @@ export const STYLE = Object.freeze({
 const LEGEND = Object.freeze([
     ["world", "the root note"],
     ["region", "continent, region, sub-region"],
+    ["district", "quarter, ward, shire"],
     ["settlement", "city, town, village"],
     ["site", "ruin, landmark, dungeon, wonder"],
     ["feature", "river, mountain range, sea"],
     ["structure", "a single building"],
+    ["route", "road, pass, sea lane"],
     ["polity", "affiliation, dashed edge to its region"],
 ]);
 

package/engine/markdown-blocks.mjs

@@ -25,35 +25,50 @@
  */
 
 import MarkdownIt from "markdown-it";
+import footnotePlugin from "markdown-it-footnote";
 import { verseDivPlugin } from "./verse-regions.mjs";
 
 /** The renderer's block grammar, with inline parsing and its passes switched off. */
 const parser = new MarkdownIt({ html: true }).use(verseDivPlugin);
-parser.core.ruler.disable(["inline", "linkify", "replacements", "smartquotes", "text_join"]);
+const footnoteParser = new MarkdownIt({ html: true }).use(footnotePlugin).use(verseDivPlugin);
+for (const projection of [parser, footnoteParser])
+    projection.core.ruler.disable([
+        "inline",
+        "linkify",
+        "replacements",
+        "smartquotes",
+        "text_join",
+    ]);
+// Keep definition containers and their original maps in place for scanners.
+footnoteParser.core.ruler.disable("footnote_tail");
 
 /** How many recent sources keep their tokens. */
 const RECENT = 16;
 
 /** @type {Map<string, import("markdown-it").Token[]>} */
 const recent = new Map();
+const recentFootnotes = new Map();
 
 /**
  * The block tokens of a Markdown source. The array is shared between callers
  * and must not be modified; an `inline` token carries no `children`.
  *
  * @param {unknown} source - Markdown.
+ * @param {object} [options] - Optional block projection.
+ * @param {boolean} [options.footnotes=false] - Include footnote definition containers.
  * @returns {readonly import("markdown-it").Token[]} The block tokens, in order.
  */
-export function blockTokens(source) {
+export function blockTokens(source, { footnotes = false } = {}) {
     const text = String(source ?? "");
-    const hit = recent.get(text);
+    const cache = footnotes ? recentFootnotes : recent;
+    const hit = cache.get(text);
     if (hit) {
-        recent.delete(text);
-        recent.set(text, hit);
+        cache.delete(text);
+        cache.set(text, hit);
         return hit;
     }
-    const tokens = parser.parse(text, { verseSource: text });
-    recent.set(text, tokens);
-    if (recent.size > RECENT) recent.delete(recent.keys().next().value);
+    const tokens = (footnotes ? footnoteParser : parser).parse(text, { verseSource: text });
+    cache.set(text, tokens);
+    if (cache.size > RECENT) cache.delete(cache.keys().next().value);
     return tokens;
 }

package/engine/metadata-index.mjs

@@ -507,6 +507,7 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                     }
                 :   {}),
                 population: record.data?.population ?? undefined,
+                market: record.data?.market ?? undefined,
                 ...(Object.hasOwn(record.data ?? {}, "government") ?
                     { government: record.data.government }
                 :   {}),

package/engine/note-addresses.mjs

@@ -43,6 +43,22 @@ export {
 
 /** Structured positions whose Address is nested inside a declared container. */
 export const STRUCTURED_ADDRESSES = Object.freeze([
+    {
+        noteType: "place",
+        path: ["data", "settlements", "rows", "*", "place"],
+        shape: "value",
+        type: "place",
+        accepts: ["place"],
+        lenient: true,
+    },
+    {
+        noteType: "place",
+        path: ["data", "settlements", "rows", "*", "heldBy"],
+        shape: "value",
+        type: "affiliation",
+        accepts: ["affiliation", "being"],
+        lenient: true,
+    },
     { path: ["data", "seeAlso", "*", "address"], shape: "value", lenient: true },
     {
         path: ["packFolder"],