@heroiclands/package-build 23.0.0 → 23.1.1

package/engine/note-vocabulary.mjs

@@ -91,6 +91,7 @@ import { currentType } from "./ids.mjs";
 // What a place is next to and reachable from — the two relation lists and
 // the checks that hold them to their closed sets and to each other.
 import { checkBorders, checkRoutes } from "./place-relations.mjs";
+import { BORDER_FIELDS, ROUTE_FIELDS } from "./place-relation-terms.mjs";
 import {
     CALENDAR_FIELDS,
     INVARIANT_FIELDS,
@@ -103,11 +104,20 @@ import {
 import { checkBeingAge } from "./being-age.mjs";
 import { checkSocialTies } from "./social-ties.mjs";
 import { checkStandings } from "./standings.mjs";
-import { STANDING_BODY_TYPES } from "./standing-terms.mjs";
+import {
+    OFFICE_FIELDS,
+    RUNG_FIELDS,
+    STANDING_BODY_TYPES,
+    STANDING_FIELDS,
+} from "./standing-terms.mjs";
 import { checkDatedOffices } from "./office-holders.mjs";
 import { checkAffiliationRankFloor, checkRankLadder } from "./rank-ladder.mjs";
 import { checkCalendarChoice } from "./calendar-choice.mjs";
-import { checkLoreEvents } from "./lore-events.mjs";
+import { checkNoteEvents } from "./note-events.mjs";
+// The closed set of standings one body holds toward another, read from the one
+// list the compiled Item is held to, so the lint and the compile cannot differ.
+import { AFFILIATION_STANDINGS } from "../sohl/affiliation-standings.mjs";
+import { EVENT_ENTRY } from "./note-event-terms.mjs";
 import { checkCultureChoice } from "./culture-choice.mjs";
 import { LITERATURE_FIELDS, checkLiteratureNote } from "./literature-notes.mjs";
 import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
@@ -154,6 +164,10 @@ import { positionOfFrontmatterPath } from "./diagnostics.mjs";
  *   so each takes a row labelled and anchored by the post's own name.
  * @property {"subType"} [keySelector] - An alternative `subType:<skill-subtype>` key.
  * @property {readonly string[]} [accepts] - Allowed Address types, separate from `ref`.
+ * @property {readonly ("prose"|"event")[]} [anchors] - The anchor kinds an
+ *   Address here may name with `#<anchor>`. Absent, an anchor is refused.
+ * @property {boolean} [single] - The Address names exactly one event: an
+ *   anchor of kind `event`, or a note holding one event and no more.
  * @property {string} [nullText] - Infobox text for an explicitly authored null with a declared meaning.
  * @property {string} [shape] - Human-readable shape, for a finding and for
  *   documentation.
@@ -162,8 +176,7 @@ import { positionOfFrontmatterPath } from "./diagnostics.mjs";
  *   quoting the whole map back, so the string an author has to correct is the
  *   one the message holds.
  * @property {string} [ref] - The Address's default type, an art slot declares
- *   one — `icon` for `icon` and `tokenIcon`, `image` for `bgImage` and
- *   `banner` — so `icon: anvil` names `icon-anvil` while a value carrying the
+ *   one — `icon` for `icon` and `tokenIcon`, `image` for `banner` — so `icon: anvil` names `icon-anvil` while a value carrying the
  *   separator states its own address. Distinct from a `FieldSpec`'s `code`
  *   ({@link module:engine/field-spec}), which names a **Shortcode** instead.
  * @property {"pack"} [keys] - For a `scalar-or-map` field, what its keys name.
@@ -176,6 +189,13 @@ import { positionOfFrontmatterPath } from "./diagnostics.mjs";
  *   it, and the linter calls whatever it is handed. A place's `borders` and
  *   `routes` carry one, because what they state is checked against the note
  *   at the other end.
+ * @property {readonly import("./data-keys.mjs").InnerKeySpec[]} [fields] - The
+ *   keys of a value that is a map, closed to them — see
+ *   {@link module:engine/data-keys}.
+ * @property {object} [entries] - What one entry of a list value is, where the
+ *   entries are not Addresses (`entryKind` says that).
+ * @property {object} [values] - What the value under each key of a keyed map
+ *   is, where the keys are data rather than declared names.
  * @property {string} describe - One line, for the author-facing reference.
  */
 
@@ -226,6 +246,13 @@ const TEXT = Object.freeze({ shape: "string", kind: "string" });
 /** A list. */
 const LIST = Object.freeze({ shape: "list", kind: "list" });
 
+/** A list of strings. */
+const TEXT_LIST = Object.freeze({
+    shape: "list of strings",
+    kind: "list",
+    entries: Object.freeze({ kind: "string", shape: "a string" }),
+});
+
 /**
  * One value, or several.
  *
@@ -234,7 +261,11 @@ const LIST = Object.freeze({ shape: "list", kind: "list" });
  * That is what separates this from `list-or-map`, whose halves say different
  * things.
  */
-const TEXT_OR_LIST = Object.freeze({ shape: "string or list", kind: "string-or-list" });
+const TEXT_OR_LIST = Object.freeze({
+    shape: "string or list",
+    kind: "string-or-list",
+    entries: Object.freeze({ kind: "string", shape: "a string" }),
+});
 
 /** A single Address. */
 const LINK = Object.freeze({ shape: "an Address", kind: "address" });
@@ -259,6 +290,11 @@ const STANDINGS = Object.freeze({
     kind: "list-or-map",
     entryKind: "address",
     keyKind: "address",
+    values: Object.freeze({
+        kind: "map",
+        shape: "a map — `{ rank, office? }`",
+        fields: STANDING_FIELDS,
+    }),
     standings: true,
     ref: "affiliation",
     accepts: STANDING_BODY_TYPES,
@@ -321,6 +357,29 @@ const TOKEN_ICON = Object.freeze({
     describe: "What a token on the canvas wears — an `icon` address; unset, it follows `icon`.",
 });
 
+/**
+ * What happened to or at a subject — the `events` key, declared once and spread
+ * into every type that carries events, so the schema cannot differ between
+ * them. The entry's own schema and its check live in
+ * {@link module:engine/note-events}.
+ *
+ * Declared here rather than in that module because its imports reach back to
+ * this one: a function declaration is bound before either module runs, and an
+ * object is not.
+ *
+ * @type {DataFieldSpec}
+ */
+export const EVENTS_FIELD = Object.freeze({
+    name: "events",
+    kind: "list",
+    shape: "list of event entries",
+    entries: EVENT_ENTRY,
+    check: checkNoteEvents,
+    describe:
+        "What happened to or at this subject — each entry one dated, attributed event: " +
+        "a founding, a war, a fall, or an occasion that recurs.",
+});
+
 /**
  * One top-level frontmatter key.
  *
@@ -455,9 +514,24 @@ export const SHARED_DATA_FIELDS = Object.freeze([
     }),
     Object.freeze({
         name: "harnworld",
-        shape: "map",
+        shape: "`{ realm?, ritual? }`",
         kind: "map",
-        describe: "HârnWorld source details shared by every system.",
+        fields: Object.freeze([
+            Object.freeze({
+                name: "realm",
+                kind: "string",
+                shape: "a string",
+                describe: "The HârnWorld realm the subject belongs to.",
+            }),
+            Object.freeze({
+                name: "ritual",
+                kind: "list",
+                shape: "list of strings",
+                entries: Object.freeze({ kind: "string", shape: "a string" }),
+                describe: "The HârnWorld religions the subject observes.",
+            }),
+        ]),
+        describe: "HârnWorld source details shared by every system — `realm` and `ritual`.",
     }),
     Object.freeze({
         name: "icon",
@@ -478,7 +552,20 @@ export const SHARED_DATA_FIELDS = Object.freeze([
 ]);
 
 /**
- * The four gear values every carried thing declares.
+ * An Address naming one event: `place-ironfells#sack`, or a note holding
+ * exactly one event, with a bare shortcode read as a `lore` note.
+ */
+const EVENT_ADDRESS = Object.freeze({
+    kind: "address",
+    ref: "lore",
+    anchors: Object.freeze(["event"]),
+    single: true,
+    shape: "an Address of one event",
+});
+
+/**
+ * The values every carried thing declares: the four a game reads, and the two
+ * events of its history.
  *
  * @type {readonly DataFieldSpec[]}
  */
@@ -487,6 +574,20 @@ const GEAR = Object.freeze([
     { name: "value", ...NUM, describe: "What the thing is worth." },
     { name: "quality", ...NUM, describe: "How well it is made." },
     { name: "durability", ...NUM, describe: "How much wear it takes before it fails." },
+    {
+        name: "made",
+        ...EVENT_ADDRESS,
+        describe:
+            "The event in which the thing was made — `lore-forging`, or one event of a " +
+            "note as `place-ironfells#raising`.",
+    },
+    {
+        name: "lost",
+        ...EVENT_ADDRESS,
+        describe:
+            "The event in which the thing was lost — `lore-flood`, or one event of a note " +
+            "as `place-ironfells#sack`.",
+    },
 ]);
 
 /** Gear that is counted rather than carried singly. */
@@ -855,10 +956,9 @@ export const NOTE_VOCABULARY = Object.freeze({
         // package's declared present compute — see `engine/being-age.mjs`.
         check: checkBeingAge,
         data: Object.freeze([
-            { name: "social", shape: "map", kind: "map", describe: "The being's social profile." },
             TOKEN_ICON,
             TEMPLATE_PRIORITY,
-            { name: "archetypes", ...LIST, describe: "Archetypal behaviours the being fits." },
+            { name: "archetypes", ...TEXT_LIST, describe: "Archetypal behaviours the being fits." },
             { name: "occupation", ...TEXT, describe: "What the being does for a living." },
             {
                 name: "stations",
@@ -906,6 +1006,10 @@ export const NOTE_VOCABULARY = Object.freeze({
                 accepts: SOCIAL_TIE_TARGET_TYPES,
                 terms: SOCIAL_TIES,
                 shape: "a map keyed by Address",
+                values: Object.freeze({
+                    kind: "string",
+                    shape: `a tie — ${SOCIAL_TIES.map(({ term }) => term).join(", ")}`,
+                }),
                 check: checkSocialTies,
                 describe: `Defining ties directed from this being to others: ${SOCIAL_TIES.map(({ term, meaning }) => `\`${term}\` (${meaning})`).join("; ")}`,
             },
@@ -999,7 +1103,7 @@ export const NOTE_VOCABULARY = Object.freeze({
             },
             {
                 name: "appearance.extra_features",
-                ...LIST,
+                ...TEXT_LIST,
                 describe: "Anything else a stranger would notice.",
             },
         ]),
@@ -1031,6 +1135,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
         data: Object.freeze([
             TEMPLATE_PRIORITY,
+            EVENTS_FIELD,
             {
                 name: "demonym",
                 ...TEXT,
@@ -1061,6 +1166,12 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "governance.ranks",
                 ...LIST,
+                shape: "list of `{ level, title, description, lore? }`",
+                entries: Object.freeze({
+                    kind: "map",
+                    shape: "a map — `{ level, title, description, lore? }`",
+                    fields: RUNG_FIELDS,
+                }),
                 // A rung is `{level, title, description}` with an optional
                 // `lore`. The shape check sees a list and stops there, so the
                 // rungs inside it are checked here — a ladder is what a being's
@@ -1075,7 +1186,13 @@ export const NOTE_VOCABULARY = Object.freeze({
             },
             {
                 name: "governance.offices",
-                ...ANY,
+                kind: "map",
+                shape: "a map of named offices",
+                values: Object.freeze({
+                    kind: "scalar-or-map",
+                    shape: "a description, or `{ description, holders }`",
+                    fields: OFFICE_FIELDS,
+                }),
                 // A map of named posts: each takes a row of its own, labelled
                 // by the post and anchored by it, so the description a body
                 // declares is a destination a being's `office` can link to.
@@ -1120,6 +1237,11 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ref: "affiliation",
                 accepts: ["affiliation"],
                 shape: "a map keyed by Address",
+                values: Object.freeze({
+                    kind: "string",
+                    allowed: AFFILIATION_STANDINGS,
+                    shape: `a standing — ${AFFILIATION_STANDINGS.join(", ")}`,
+                }),
                 describe: "Standing with other affiliations — aligned, unaligned, rival, nemesis.",
             },
         ]),
@@ -1249,6 +1371,7 @@ export const NOTE_VOCABULARY = Object.freeze({
                 keyKind: "shortcode",
                 keySelector: "subType",
                 shape: "a map keyed by Shortcode or subType selector",
+                values: Object.freeze({ kind: "number", shape: "a number" }),
                 describe:
                     "Bonuses and penalties, each naming a skill or a `subType:<skill-subtype>`.",
             },
@@ -1492,19 +1615,7 @@ export const NOTE_VOCABULARY = Object.freeze({
             ...checkCalendarNote(note, context),
             ...checkLiteratureNote(note),
         ],
-        data: Object.freeze([
-            ...CALENDAR_FIELDS,
-            ...LITERATURE_FIELDS,
-            {
-                name: "events",
-                kind: "list",
-                shape: "list of `{ when, until?, recurs? }`",
-                check: checkLoreEvents,
-                describe:
-                    "This note's dated occurrences — a founding once, an anniversary " +
-                    "that recurs, or a list of recorded happenings.",
-            },
-        ]),
+        data: Object.freeze([...CALENDAR_FIELDS, ...LITERATURE_FIELDS, EVENTS_FIELD]),
     }),
 
     place: Object.freeze({
@@ -1520,6 +1631,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
         check: checkPlace,
         data: Object.freeze([
+            EVENTS_FIELD,
             {
                 name: "calendar",
                 ...LINK,
@@ -1586,6 +1698,11 @@ export const NOTE_VOCABULARY = Object.freeze({
                 name: "borders",
                 ...LIST,
                 shape: "list of `{ to, bearing }` entries",
+                entries: Object.freeze({
+                    kind: "map",
+                    shape: "a map — `{ to, bearing }`",
+                    fields: BORDER_FIELDS,
+                }),
                 check: checkBorders,
                 describe:
                     "Places sharing a frontier with this one — each the other's shortcode " +
@@ -1595,6 +1712,11 @@ export const NOTE_VOCABULARY = Object.freeze({
                 name: "routes",
                 ...LIST,
                 shape: "list of `{ to, bearing, mode, days, terrain?, leagues? }` entries",
+                entries: Object.freeze({
+                    kind: "map",
+                    shape: "a map — `{ to, bearing, mode, days, terrain?, leagues? }`",
+                    fields: ROUTE_FIELDS,
+                }),
                 check: checkRoutes,
                 describe:
                     "Journeys from this place's centre — where the destination lies, how " +
@@ -1658,7 +1780,7 @@ export const NOTE_VOCABULARY = Object.freeze({
             },
             {
                 name: "party.archetypes",
-                ...LIST,
+                ...TEXT_LIST,
                 describe: "Archetypes the scenario is written for.",
             },
         ]),
@@ -1668,66 +1790,52 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     map: Object.freeze({
         stubbable: true,
-        // The subType classifies the map; `data.scene` carries its canvas.
+        // The subType classifies the map; `data.scene` is its Foundry Scene.
         subTypes: Object.freeze(["battlemap", "localmap", "regionalmap", "totm"]),
         data: Object.freeze([
             {
                 name: "scene",
-                ...ANY,
-                describe: "A Foundry Scene export with all its authored fields.",
+                kind: "map",
+                shape: "an object — a Foundry Scene document as exported",
+                describe:
+                    "The Foundry Scene as exported, passed through unchanged apart " +
+                    "from `data.fixup` and its pins marked `#anchor`. Nothing inside it is checked; " +
+                    "the book prints its levels' background images.",
             },
             {
                 name: "fixup",
                 ...LIST,
+                shape: "list of `{ path, type, value }`",
+                entries: Object.freeze({
+                    kind: "map",
+                    shape: "a map — `{ path, type, value }`",
+                    fields: Object.freeze([
+                        Object.freeze({
+                            name: "path",
+                            kind: "string",
+                            required: true,
+                            shape: "a property path into `data.scene`",
+                            describe: "The exported field to replace, from `data.scene`.",
+                        }),
+                        Object.freeze({
+                            name: "type",
+                            kind: "string",
+                            required: true,
+                            allowed: Object.freeze(["address"]),
+                            shape: "`address`",
+                            describe: "What `value` is: `address`.",
+                        }),
+                        Object.freeze({
+                            name: "value",
+                            kind: "address",
+                            required: true,
+                            shape: "an asset Address",
+                            describe: "The asset Address whose path replaces the exported one.",
+                        }),
+                    ]),
+                }),
                 describe: "Asset address replacements in an exported Scene.",
             },
-            // A Scene has no `img`, so the shared art key reaches nothing here:
-            // a map's background is its own slot, and an `image` address.
-            {
-                name: "bgImage",
-                ...LINK,
-                ref: "image",
-                accepts: ART_SLOTS.find((slot) => slot.key === "bgImage").accepts,
-                describe: "The map's background art — an `image` address.",
-            },
-            {
-                name: "scale",
-                ...ANY,
-                describe: "Regional map distance per grid unit: {distance, unit}.",
-            },
-            {
-                name: "dimensions",
-                ...LIST,
-                describe: "`[width, height]` in whole pixels — the art's own size.",
-            },
-            {
-                name: "pxPerGrid",
-                ...NUM,
-                describe: "Whole pixels per grid square; must match the art.",
-            },
-            { name: "navName", ...TEXT, describe: "Short name for the navigation bar." },
-            { name: "levelName", ...TEXT, describe: "Name of the embedded level." },
-            {
-                name: "backgroundColor",
-                ...TEXT,
-                describe: "Colour shown where the art does not reach.",
-            },
-            { name: "overlay", ...TEXT, describe: "Path to the foreground art." },
-            // Geometry carries no `kind`. The specification lists each
-            // as a sequence while the notes authoring them today write
-            // a map keyed by name, and a lint has no business picking
-            // the winner of a disagreement the format has not settled.
-            { name: "walls", ...ANY, describe: "Wall segments." },
-            { name: "doors", ...ANY, describe: "Doors." },
-            { name: "lights", ...ANY, describe: "Light sources." },
-            { name: "tiles", ...ANY, describe: "Tiles." },
-            { name: "sounds", ...ANY, describe: "Ambient sounds." },
-            { name: "regions", ...ANY, describe: "Regions and their behaviours." },
-            {
-                name: "notes",
-                ...ANY,
-                describe: "Map pins, each a grid location and an anchor in this note's own body.",
-            },
             {
                 name: "place",
                 ...LINK,
@@ -1867,15 +1975,3 @@ export function subTypes(type, vocabulary = NOTE_VOCABULARY) {
     if (!entry || !Object.hasOwn(entry, "subTypes")) return undefined;
     return entry.subTypes;
 }
-
-/**
- * Accepted migration input with no canonical field or emitted value.
- *
- * Legacy affiliation domains are ignored. They never supply a government.
- * @param {string} type - The note type.
- * @param {string} key - An authored data key.
- * @returns {boolean} Whether the obsolete key is accepted during migration.
- */
-export function isLegacyDataField(type, key) {
-    return currentType(type) === "affiliation" && key === "domains";
-}

package/engine/office-holders.mjs

@@ -1,4 +1,13 @@
 /*
+ * 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
  */
 
@@ -7,8 +16,10 @@ import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 
-const OFFICE_KEYS = new Set(["description", "holders"]);
-const HOLDER_KEYS = new Set(["being", "start", "end", "contested"]);
+import { HOLDER_FIELDS, OFFICE_FIELDS } from "./standing-terms.mjs";
+
+export { HOLDER_FIELDS, OFFICE_FIELDS };
+
 const mapping = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
 /**
@@ -26,65 +37,20 @@ export function checkDatedOffices(note, { index } = {}) {
         severity: "error",
         message,
     });
-    if (!mapping(offices))
-        return [
-            at(
-                ["data", "governance", "offices"],
-                "data.governance.offices must be a map of named offices",
-            ),
-        ];
+    // The roster's shape — a map of offices, each a description or a map of
+    // `OFFICE_FIELDS`, each holder a map of `HOLDER_FIELDS` — is the inner-key
+    // check's. What is checked here is what the holders and their dates mean.
+    if (!mapping(offices)) return [];
 
     const dates = reckoningContext(index);
     for (const [office, value] of Object.entries(offices)) {
         const base = ["data", "governance", "offices", office];
-        if (typeof value === "string") continue;
-        if (!mapping(value)) {
-            findings.push(
-                at(base, `office ${office} must be a description or a {description, holders} map`),
-            );
-            continue;
-        }
-        for (const key of Object.keys(value))
-            if (!OFFICE_KEYS.has(key))
-                findings.push(
-                    at(
-                        [...base, key],
-                        `office ${office} has unknown key ${key}; use description or holders`,
-                    ),
-                );
-        if (typeof value.description !== "string")
-            findings.push(
-                at([...base, "description"], `office ${office} needs a string description`),
-            );
-        if (!Array.isArray(value.holders)) {
-            findings.push(at([...base, "holders"], `office ${office} needs a holders list`));
-            continue;
-        }
+        if (!mapping(value) || !Array.isArray(value.holders)) continue;
         const terms = [];
         value.holders.forEach((row, position) => {
             const rowPath = [...base, "holders", position];
-            if (!mapping(row)) {
-                findings.push(at(rowPath, `office ${office} holder must be a map`));
-                return;
-            }
-            for (const key of Object.keys(row))
-                if (!HOLDER_KEYS.has(key))
-                    findings.push(
-                        at([...rowPath, key], `office ${office} holder has unknown key ${key}`),
-                    );
-            if (row.contested !== undefined && typeof row.contested !== "boolean")
-                findings.push(
-                    at(
-                        [...rowPath, "contested"],
-                        `office ${office} contested must be true or false`,
-                    ),
-                );
-
-            if (typeof row.being !== "string" || !row.being.trim()) {
-                findings.push(
-                    at([...rowPath, "being"], `office ${office} holder needs a being Address`),
-                );
-            } else {
+            if (!mapping(row)) return;
+            if (typeof row.being === "string" && row.being.trim()) {
                 const tuple = parseAddress(row.being, {
                     package: index?.contentPackage,
                     system: "note",

package/engine/packagebuild-index.mjs

@@ -50,6 +50,7 @@ import { fileURLToPath } from "node:url";
 import { collectAssetRecords } from "./asset-index.mjs";
 import { recordPath, sortKeysDeep } from "./index-records.mjs";
 import { PACKAGEBUILD_PACKAGE, metadataFileName } from "./packages.mjs";
+import { decodeIndexAddresses, publishAddresses } from "./note-addresses.mjs";
 
 /**
  * This package's own root, wherever it is installed.
@@ -117,7 +118,21 @@ export function packageBuildRecords(assetsBase = PACKAGEBUILD_ASSETS) {
  */
 export function emitPackageBuildIndex({ assetsBase, file = PACKAGEBUILD_INDEX_FILE } = {}) {
     const records = packageBuildRecords(assetsBase);
-    const text = records.length ? `${records.map((r) => JSON.stringify(r)).join("\n")}\n` : "";
+    // Written the way every published index is: each Address an object.
+    const text =
+        records.length ?
+            `${records
+                .map((record) =>
+                    JSON.stringify(
+                        sortKeysDeep(
+                            publishAddresses(
+                                decodeIndexAddresses(record, { package: PACKAGEBUILD_PACKAGE }),
+                            ),
+                        ),
+                    ),
+                )
+                .join("\n")}\n`
+        :   "";
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, text);
     return { file, assets: records.length, bytes: Buffer.byteLength(text) };