@heroiclands/package-build 22.9.1 → 22.10.0

package/engine/note-addresses.mjs

@@ -0,0 +1,310 @@
+/*
+ * 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>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { systemBlocksFor } from "./system-vocabulary.mjs";
+import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
+import {
+    isAddressTuple,
+    parseAddress,
+    renderAddress,
+    acceptsType,
+    readCanonicalKey,
+} from "./address.mjs";
+import { NOTE_VOCABULARY, dataFields } from "./note-vocabulary.mjs";
+import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
+import { ART_SLOTS } from "./art-slots.mjs";
+import { SHIPPED_SYSTEMS } from "./subtype-registry.mjs";
+
+import { AddressEntries, AddressLink } from "./address-values.mjs";
+export { AddressEntries, encodeAddresses, cloneAddressState } from "./address-values.mjs";
+
+/** Structured positions whose Address is nested inside a declared container. */
+export const STRUCTURED_ADDRESSES = Object.freeze([
+    { path: ["packFolder"], shape: "scalar-or-map", type: "folder", accepts: ["folder"] },
+    {
+        noteType: "affiliation",
+        path: ["data", "governance", "ranks", "*", "lore"],
+        shape: "value",
+        type: "lore",
+        accepts: ["lore"],
+    },
+    {
+        noteType: "place",
+        path: ["data", "borders", "*", "to"],
+        shape: "value",
+        type: "place",
+        accepts: ["place"],
+    },
+    {
+        noteType: "place",
+        path: ["data", "routes", "*", "to"],
+        shape: "value",
+        type: "place",
+        accepts: ["place"],
+    },
+]);
+
+/**
+ * All declared Address positions of a note, including embedded notes.
+ * @param {object} fm - The note.
+ * @returns {object[]} Position descriptors with container shape and defaults.
+ */
+export function addressPositions(fm, context = {}) {
+    const out = [];
+    for (const field of dataFields(fm.type) ?? []) {
+        const shape =
+            field.kind === "address" ? "value"
+            : field.keyKind === "address" ? "keys"
+            : field.entryKind === "address" ? field.kind
+            : undefined;
+        if (shape)
+            out.push({
+                path: ["data", ...field.name.split(".")],
+                shape,
+                type: field.ref,
+                accepts: field.accepts,
+            });
+    }
+    out.push(...STRUCTURED_ADDRESSES.filter((p) => !p.noteType || p.noteType === fm.type));
+    for (const system of new Set([
+        ...SHIPPED_SYSTEMS,
+        ...Object.keys(context.systemBlocks ?? {}),
+    ])) {
+        out.push({
+            path: [system, "packFolder"],
+            shape: "scalar-or-map",
+            type: "folder",
+            accepts: ["folder"],
+            system,
+        });
+        out.push({
+            path: [system, "items", "*", "model"],
+            shape: "value",
+            system,
+            legacyShortcodeCase: true,
+        });
+        for (const slot of ART_SLOTS)
+            out.push({
+                path: [system, "items", "*", "data", slot.key],
+                shape: "value",
+                type: slot.type,
+                accepts: slot.accepts,
+                system,
+            });
+        const spec = context.systemBlocks?.[system];
+        for (const [index, entry] of (Array.isArray(fm[system]?.items) ?
+            fm[system].items
+        :   []
+        ).entries()) {
+            const model =
+                entry?.model == null ?
+                    null
+                :   parseAddress(
+                        entry.model,
+                        {
+                            ...context,
+                            system,
+                            types: new Set([...Object.keys(NOTE_VOCABULARY), ...ASSET_TYPE_NAMES]),
+                        },
+                        { declared: true, legacyShortcodeCase: true },
+                    );
+            const type = model && !model.reason ? model.type : entry?.type;
+            for (const field of spec?.fields?.[type] ?? []) {
+                if (!field.address) continue;
+                out.push({
+                    path: [system, "items", index, "system", ...field.to.split(".")],
+                    shape:
+                        field.address.holds === "items" ? "list" : (field.address.holds ?? "value"),
+                    type: field.address.type,
+                    accepts: field.address.accepts,
+                    system,
+                });
+            }
+        }
+        const fields = [
+            ...(spec?.fields?.[fm.type] ?? []),
+            ...(spec?.fieldVocabulary ? (context.schemas?.[fm.type]?.fields ?? []) : []),
+        ];
+        for (const field of fields) {
+            if (!field.address) continue;
+            const position = {
+                shape: field.address.holds === "items" ? "list" : (field.address.holds ?? "value"),
+                type: field.address.type,
+                accepts: field.address.accepts,
+                system,
+            };
+            out.push({ ...position, path: [system, "system", ...field.to.split(".")] });
+            out.push({
+                ...position,
+                path: [system, ...(field.legacyKey ?? field.name).split(".")],
+            });
+            if (field.name?.startsWith("data.") && field.topLevelMeans === undefined)
+                out.push({ ...position, system: "none", path: field.name.slice(5).split(".") });
+        }
+    }
+    for (const position of [...out]) {
+        const last = position.path.at(-1);
+        const retired = RETIRED_FIELD_ALIASES[last];
+        if (retired) out.push({ ...position, path: [...position.path.slice(0, -1), retired] });
+    }
+    return out;
+}
+
+/**
+ * Decode declared properties at the note boundary. Raw mappings cannot impersonate tuples.
+ * @param {object} fm - Parsed YAML or an index record.
+ * @param {object} context - The builder's package and known types.
+ * @returns {object} The same note carrying typed Address properties.
+ */
+export function decodeNoteAddresses(fm, context) {
+    if (!fm || typeof fm !== "object") return fm;
+    const types = new Set([
+        ...Object.keys(NOTE_VOCABULARY),
+        ...ASSET_TYPE_NAMES,
+        ...(context.types ?? []),
+    ]);
+    for (const position of addressPositions(fm, context)) {
+        const defaults = {
+            ...context,
+            types,
+            system: position.system ?? context.system ?? "none",
+            type: position.type,
+        };
+        const fail = (value, path, description) => {
+            const error = new Error(
+                `\`${path.join(".")}\` ${description}: ${JSON.stringify(value)}`,
+            );
+            error.keyPath = path;
+            error.addressKey = position.shape === "keys";
+            throw error;
+        };
+        const read = (value, path) => {
+            if (value == null || value === "") return value;
+            const tuple = parseAddress(value, defaults, {
+                declared: true,
+                legacyShortcodeCase: position.legacyShortcodeCase,
+            });
+            if (tuple.reason) fail(value, path, "is not an accepted Address");
+            if (position.accepts && !acceptsType(tuple, position.accepts))
+                fail(
+                    value,
+                    path,
+                    `must name a ${position.accepts.join(" or ")} Address, but names ${tuple.type}`,
+                );
+            return tuple;
+        };
+        const convert = (value, path) => {
+            if (value == null || value === "") return value;
+            if (position.shape === "keys") {
+                if (value instanceof AddressEntries) return value;
+                if (Array.isArray(value) && value.length === 0) return value;
+                if (typeof value !== "object" || Array.isArray(value))
+                    fail(value, path, "must be an Address-keyed map");
+                return new AddressEntries(
+                    Object.entries(value).map(([key, v]) => ({
+                        target: read(key, [...path, key]),
+                        value: v,
+                        sourceKey: key,
+                    })),
+                );
+            }
+            if (position.shape === "list") {
+                if (!Array.isArray(value)) fail(value, path, "must be a list of Addresses");
+                return value.map((v, i) => read(v, [...path, i]));
+            }
+            if (
+                position.shape === "scalar-or-map" &&
+                typeof value === "object" &&
+                !isAddressTuple(value)
+            ) {
+                if (Array.isArray(value)) {
+                    if (!value.length) return value;
+                    fail(value, path, "must be an Address or pack map");
+                }
+                return Object.fromEntries(
+                    Object.entries(value).map(([key, v]) => [key, read(v, [...path, key])]),
+                );
+            }
+            return read(value, path);
+        };
+        // Copy each traversed owner so YAML aliases retain their own read context.
+        const visit = (owner, path, offset = 0, actual = []) => {
+            if (owner == null || owner === "") return owner;
+            const key = path[offset];
+            if (key === "*") {
+                if (!Array.isArray(owner)) fail(owner, actual, "must be a list of entries");
+                return owner.map((value, i) => visit(value, path, offset + 1, [...actual, i]));
+            }
+            if (typeof owner !== "object") return owner;
+            if (!Object.hasOwn(owner, key)) return owner;
+            const copy = Array.isArray(owner) ? [...owner] : { ...owner };
+            copy[key] =
+                offset === path.length - 1 ?
+                    convert(owner[key], [...actual, key])
+                :   visit(owner[key], path, offset + 1, [...actual, key]);
+            return copy;
+        };
+        const decoded = visit(fm, position.path);
+        Object.assign(fm, decoded);
+    }
+    return fm;
+}
+
+/**
+ * Read context supplied by the package configuration.
+ * @param {object} config - Resolved package configuration.
+ * @returns {object} Builder defaults and system declarations.
+ */
+export function noteAddressContext(config) {
+    return {
+        package: config.contentPackage,
+        system: "none",
+        systemBlocks: systemBlocksFor(config),
+    };
+}
+
+/**
+ * Decode Address properties contributed by an index record.
+ * @param {object} record - The record.
+ * @param {object} context - Builder defaults.
+ * @returns {object} The typed record.
+ */
+export function decodeIndexAddresses(record, context) {
+    decodeNoteAddresses(record, context);
+    const canonical = (value, keyPath) => {
+        const target = readCanonicalKey(value);
+        if (!isAddressTuple(target)) {
+            const error = new Error(
+                `Index ${keyPath.join(".")} is not a complete Address: ${JSON.stringify(value)}`,
+            );
+            error.keyPath = keyPath;
+            throw error;
+        }
+        return target;
+    };
+    for (const key of ["documentation", "documents"]) {
+        if (record[key] != null) record[key] = canonical(record[key], [key]);
+    }
+    if (record.address?.canonical != null)
+        record.address.canonical = canonical(record.address.canonical, ["address", "canonical"]);
+    for (const anchor of record.anchors ?? []) {
+        if (!anchor.link || anchor.link instanceof AddressLink) continue;
+        const [written, section] = anchor.link.split("#");
+        const target = parseAddress(
+            written,
+            {
+                ...context,
+                system: "none",
+                types: new Set([...Object.keys(NOTE_VOCABULARY), ...ASSET_TYPE_NAMES]),
+            },
+            { declared: true },
+        );
+        if (target.reason) throw new Error(`Index anchor link is not an Address: ${anchor.link}`);
+        anchor.link = new AddressLink(target, section);
+    }
+    return record;
+}

package/engine/note-vocabulary.mjs

@@ -77,6 +77,7 @@
 
 // The one charset, read rather than restated. A second spelling of the pattern
 // is how a disagreement between the three arises.
+import { ART_SLOTS } from "./art-slots.mjs";
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
 // The retirement window for a renamed type, read rather than restated: a
 // vocabulary that answered only to the current spelling would report every key
@@ -114,20 +115,25 @@ import { MARKET_CLASSES, checkMarket } from "./market-class.mjs";
  * @typedef {object} DataFieldSpec
  * @property {string} name - The key under `data:`, dotted for a nested one
  *   (`charges.value`).
- * @property {"string"|"number"|"boolean"|"list"|"map"|"scalar-or-map"} [kind] -
+ * @property {"string"|"number"|"boolean"|"list"|"map"|"scalar-or-map"|"address"|"shortcode"} [kind] -
  *   The value's shape, for the lint. Absent means no claim is made about the
  *   value — which is the honest answer wherever the specification's stated
  *   shape and the shape notes are authored in today disagree.
+ * @property {"address"|"shortcode"} [entryKind] - Type of each list or pack-map value.
+ * @property {"address"|"shortcode"} [keyKind] - Type of each map key.
+ * @property {"subType"} [keySelector] - An alternative `subType:<skill-subtype>` key.
+ * @property {readonly string[]} [accepts] - Allowed Address types, separate from `ref`.
  * @property {string} [shape] - Human-readable shape, for a finding and for
  *   documentation.
  * @property {string} [entryShape] - For a `scalar-or-map` field, what one
  *   entry of the map is. A finding names the entry at fault rather than
  *   quoting the whole map back, so the string an author has to correct is the
  *   one the message holds.
- * @property {string} [ref] - The type a bare value takes. An art slot declares
+ * @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
- *   separator states its own address.
+ *   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.
  *   `"pack"` means each is a pack this package declares, so a key naming none
  *   is a finding of its own: it addresses a hierarchy nothing will ever read.
@@ -189,14 +195,14 @@ const TEXT = Object.freeze({ shape: "string", kind: "string" });
 /** A list. */
 const LIST = Object.freeze({ shape: "list", kind: "list" });
 
-/** A single wikilink, which is a string until it is resolved. */
-const LINK = Object.freeze({ shape: "a wikilink", kind: "string" });
+/** A single Address. */
+const LINK = Object.freeze({ shape: "an Address", kind: "address" });
 
-/** A list of wikilinks. */
-const LINKS = Object.freeze({ shape: "list of wikilinks", kind: "list" });
+/** A list of Addresses. */
+const LINKS = Object.freeze({ shape: "list of Addresses", kind: "list", entryKind: "address" });
 
 /**
- * A single wikilink, or one per pack.
+ * A single Address, or one per pack.
  *
  * The map form is not a convenience spelling of the scalar: it says something
  * the scalar cannot, that the answer *differs by pack*. A folder's `parent` is
@@ -209,9 +215,10 @@ const LINKS = Object.freeze({ shape: "list of wikilinks", kind: "list" });
  * specification prescribes was a finding and no note using it was not.
  */
 const LINK_BY_PACK = Object.freeze({
-    shape: "a wikilink, or a map of wikilinks keyed by pack",
+    shape: "an Address, or a map of Addresses keyed by pack",
+    entryKind: "address",
     kind: "scalar-or-map",
-    entryShape: "a wikilink",
+    entryShape: "an Address",
     keys: "pack",
 });
 
@@ -246,6 +253,7 @@ const TOKEN_ICON = Object.freeze({
     name: "tokenIcon",
     ...LINK,
     ref: "icon",
+    accepts: ART_SLOTS.find((slot) => slot.key === "tokenIcon").accepts,
     describe: "What a token on the canvas wears — an `icon` address; unset, it follows `icon`.",
 });
 
@@ -273,12 +281,14 @@ export const SHARED_DATA_FIELDS = Object.freeze([
         name: "icon",
         ...LINK,
         ref: "icon",
+        accepts: ART_SLOTS.find((slot) => slot.key === "icon").accepts,
         describe: "The document's profile art — an `icon` address, resolved into `img`.",
     }),
     Object.freeze({
         name: "banner",
         ...LINK,
         ref: "image",
+        accepts: ART_SLOTS.find((slot) => slot.key === "banner").accepts,
         describe: "The page's hero image — an `image` address. Reaches no compiled document.",
     }),
 ]);
@@ -599,22 +609,44 @@ export const NOTE_VOCABULARY = Object.freeze({
             TEMPLATE_PRIORITY,
             { name: "archetypes", ...LIST, describe: "Archetypal behaviours the being fits." },
             { name: "occupation", ...TEXT, describe: "What the being does for a living." },
-            { name: "stations", ...LINKS, describe: "Stations the being holds." },
+            {
+                name: "stations",
+                ...LINKS,
+                ref: "lore",
+                accepts: ["lore"],
+                describe: "Stations the being holds.",
+            },
             {
                 name: "lore",
                 ...LINKS,
+                ref: "lore",
+                accepts: ["lore"],
                 describe:
                     "Lore concerning this being — the people it is of, the standing it " +
                     "holds, the law it lives under.",
             },
-            { name: "homes", ...LINKS, describe: "Places the being calls home." },
+            {
+                name: "homes",
+                ...LINKS,
+                ref: "place",
+                accepts: ["place"],
+                describe: "Places the being calls home.",
+            },
             {
                 name: "affiliations",
                 ...LINKS,
+                ref: "affiliation",
+                accepts: ["affiliation"],
                 describe: "Affiliations the being belongs to — traditions, polities, and the rest.",
             },
             { name: "gender", ...TEXT, describe: "`male`, `female` or `other`." },
-            { name: "species", ...LINK, describe: "The being's species, as a lore note." },
+            {
+                name: "species",
+                ...LINK,
+                ref: "lore",
+                accepts: ["lore"],
+                describe: "The being's species, as a lore note.",
+            },
             {
                 name: "born",
                 ...TEXT,
@@ -732,27 +764,54 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "commonSkills",
                 ...LINKS,
+                ref: "skill",
+                accepts: ["skill"],
                 describe: "Skills common among members — languages first among them.",
             },
-            { name: "seat", ...LINK, describe: "Where the affiliation's authority sits." },
-            { name: "domains", ...LINKS, describe: "Places over which it holds sway." },
+            {
+                name: "seat",
+                ...LINK,
+                ref: "place",
+                accepts: ["place"],
+                describe: "Where the affiliation's authority sits.",
+            },
+            {
+                name: "domains",
+                ...LINKS,
+                ref: "place",
+                accepts: ["place"],
+                describe: "Places over which it holds sway.",
+            },
             { name: "population", ...NUM, describe: "How many people it counts." },
             {
                 name: "economy",
                 ...LINKS,
+                accepts: ["affiliation", "lore"],
                 describe: "What its economic life runs on — currencies, banking bodies, goods.",
             },
             {
                 name: "lore",
                 ...LINKS,
+                ref: "lore",
+                accepts: ["lore"],
                 describe:
                     "Lore concerning it — the peoples it draws on, the god a faith " +
                     "venerates, its law, its calendar.",
             },
-            { name: "parents", ...LINKS, describe: "Affiliations it is subordinate to." },
+            {
+                name: "parents",
+                ...LINKS,
+                ref: "affiliation",
+                accepts: ["affiliation"],
+                describe: "Affiliations it is subordinate to.",
+            },
             {
                 name: "relations",
-                ...ANY,
+                kind: "map",
+                keyKind: "address",
+                ref: "affiliation",
+                accepts: ["affiliation"],
+                shape: "a map keyed by Address",
                 describe: "Standing with other affiliations — aligned, unaligned, rival, nemesis.",
             },
         ]),
@@ -862,15 +921,26 @@ export const NOTE_VOCABULARY = Object.freeze({
         subTypes: Object.freeze(["boon", "boost", "fate", "grace", "birthsign", "other", "piety"]),
         data: Object.freeze([
             TEMPLATE_PRIORITY,
-            { name: "assocSkill", ...LINK, describe: "The skill it is associated with." },
+            {
+                name: "assocSkill",
+                ...LINK,
+                ref: "skill",
+                accepts: ["skill"],
+                describe: "The skill it is associated with.",
+            },
             {
                 name: "assocAffiliation",
                 ...LINK,
+                ref: "affiliation",
+                accepts: ["affiliation"],
                 describe: "The affiliation it is associated with.",
             },
             {
                 name: "skillAptitudes",
-                ...ANY,
+                kind: "map",
+                keyKind: "shortcode",
+                keySelector: "subType",
+                shape: "a map keyed by Shortcode or subType selector",
                 describe:
                     "Bonuses and penalties, each naming a skill or a `subType:<skill-subtype>`.",
             },
@@ -895,10 +965,18 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
         data: Object.freeze([
             TEMPLATE_PRIORITY,
-            { name: "assocSkill", ...LINK, describe: "The skill it is associated with." },
+            {
+                name: "assocSkill",
+                ...LINK,
+                ref: "skill",
+                accepts: ["skill"],
+                describe: "The skill it is associated with.",
+            },
             {
                 name: "assocAffiliation",
                 ...LINK,
+                ref: "affiliation",
+                accepts: ["affiliation"],
                 describe: "The affiliation it is associated with.",
             },
             { name: "masteryLevel", ...NUM, describe: "Mastery before any modifier." },
@@ -930,7 +1008,13 @@ export const NOTE_VOCABULARY = Object.freeze({
         data: Object.freeze([
             TEMPLATE_PRIORITY,
             { name: "masteryLevel", ...NUM, describe: "Mastery before any modifier." },
-            { name: "parentSkill", ...LINK, describe: "The skill this one specialises." },
+            {
+                name: "parentSkill",
+                ...LINK,
+                ref: "skill",
+                accepts: ["skill"],
+                describe: "The skill this one specialises.",
+            },
         ]),
     }),
 
@@ -1024,6 +1108,8 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "parent",
                 ...LINK_BY_PACK,
+                ref: "folder",
+                accepts: ["folder"],
                 describe:
                     "The folder this one sits in, as an address — or one " +
                     "address per pack, keyed by pack name with `default` for " +
@@ -1110,6 +1196,8 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "lore",
                 ...LINKS,
+                ref: "lore",
+                accepts: ["lore"],
                 describe:
                     "Lore concerning this place — its peoples, its law, its calendar, " +
                     "its history.",
@@ -1117,6 +1205,8 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "parents",
                 ...LINKS,
+                ref: "place",
+                accepts: ["place"],
                 describe: "Enclosing places this one sits within.",
             },
             {
@@ -1162,13 +1252,39 @@ export const NOTE_VOCABULARY = Object.freeze({
         stubbable: true,
         subTypes: Object.freeze(["campaign", "adventure", "encounter"]),
         data: Object.freeze([
-            { name: "parents", ...LINKS, describe: "Scenarios this one sits within." },
-            { name: "locations", ...LINKS, describe: "Places the scenario takes place in." },
-            { name: "cast", ...LINKS, describe: "Beings who appear in it." },
-            { name: "factions", ...LINKS, describe: "Affiliations with a stake in it." },
+            {
+                name: "parents",
+                ...LINKS,
+                ref: "scenario",
+                accepts: ["scenario"],
+                describe: "Scenarios this one sits within.",
+            },
+            {
+                name: "locations",
+                ...LINKS,
+                ref: "place",
+                accepts: ["place"],
+                describe: "Places the scenario takes place in.",
+            },
+            {
+                name: "cast",
+                ...LINKS,
+                ref: "being",
+                accepts: ["being"],
+                describe: "Beings who appear in it.",
+            },
+            {
+                name: "factions",
+                ...LINKS,
+                ref: "affiliation",
+                accepts: ["affiliation"],
+                describe: "Affiliations with a stake in it.",
+            },
             {
                 name: "follows",
                 ...LINKS,
+                ref: "scenario",
+                accepts: ["scenario"],
                 describe: "Scenarios that should be played before this one.",
             },
             {
@@ -1203,6 +1319,7 @@ export const NOTE_VOCABULARY = Object.freeze({
                 name: "bgImage",
                 ...LINK,
                 ref: "image",
+                accepts: ART_SLOTS.find((slot) => slot.key === "bgImage").accepts,
                 describe: "The map's background art — an `image` address.",
             },
             {
@@ -1240,7 +1357,9 @@ export const NOTE_VOCABULARY = Object.freeze({
             },
             {
                 name: "place",
-                ...TEXT,
+                ...LINK,
+                ref: "place",
+                accepts: ["place"],
                 describe:
                     "The place this map depicts. Named here and not on the place, " +
                     "because a place has several maps and a map depicts one place.",

package/engine/pdf-build.mjs

@@ -379,7 +379,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         scheme,
     };
     const collected = collectContentPages(contentBase, ctx);
-    const gates = siteGates(collected.pages, collected, { config: resolved });
+    const gates = siteGates(collected.pages, collected, { config: resolved, records });
     if (gatesFailed(gates)) {
         for (const [name, list] of Object.entries(gates)) {
             if (!Array.isArray(list)) continue;