@heroiclands/package-build 23.0.0 → 23.1.1

package/engine/near-miss.mjs

@@ -0,0 +1,90 @@
+/*
+ * 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
+ */
+
+/**
+ * The near miss a closed vocabulary names when it refuses a key: the declared
+ * key an unknown one was most likely meant to be, and the declared list as an
+ * English sentence.
+ *
+ * Shared by every closed region — the top level, `data:`, a system block, and
+ * the inner keys of a `data:` field — so a misspelling is answered the same
+ * way at every depth.
+ *
+ * @module
+ */
+
+/**
+ * Edit distance, capped — enough to answer "did you mean".
+ *
+ * A misspelled property is the failure class this check exists for, and a
+ * finding that names the key the author *meant* turns a hunt through the
+ * reference into a one-character fix.
+ *
+ * @param {string} a - One string.
+ * @param {string} b - The other.
+ * @returns {number} The Levenshtein distance.
+ */
+export function distance(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let prev = Array.from({ length: cols }, (_, j) => j);
+    for (let i = 1; i < rows; i += 1) {
+        const row = [i];
+        for (let j = 1; j < cols; j += 1) {
+            row[j] = Math.min(
+                prev[j] + 1,
+                row[j - 1] + 1,
+                prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+            );
+        }
+        prev = row;
+    }
+    return prev[cols - 1];
+}
+
+/**
+ * A closed vocabulary as an English list, for the message that names it.
+ *
+ * Written from the declaration rather than spelled into the message, so a key
+ * the vocabulary gains cannot go unmentioned by the finding that refuses its
+ * neighbours.
+ *
+ * @param {readonly string[]} keys - The declared keys, in declared order.
+ * @returns {string} `"a, b, or c"`.
+ */
+export function listed(keys) {
+    if (keys.length < 2) return keys.join("");
+    return `${keys.slice(0, -1).join(", ")}, or ${keys[keys.length - 1]}`;
+}
+
+/**
+ * The declared key an unknown one was most likely meant to be.
+ *
+ * @param {string} key - The unknown key.
+ * @param {Iterable<string>} candidates - The declared keys.
+ * @returns {string|undefined} The nearest, when it is near enough to suggest.
+ */
+export function nearest(key, candidates) {
+    let best;
+    let bestAt = Infinity;
+    for (const candidate of candidates) {
+        const d = distance(key.toLowerCase(), candidate.toLowerCase());
+        if (d < bestAt) {
+            bestAt = d;
+            best = candidate;
+        }
+    }
+    // A third of the key's length, so a suggestion is a plausible typo rather
+    // than the least-bad of a list of unrelated words.
+    return bestAt <= Math.max(1, Math.floor(key.length / 3)) ? best : undefined;
+}

package/engine/note-addresses.mjs

@@ -12,15 +12,25 @@ import {
     parseAddress,
     renderAddress,
     acceptsType,
+    hasAnchor,
     readCanonicalKey,
+    splitAnchor,
 } 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 { EVENT_ADDRESS_POSITIONS } from "./note-events.mjs";
 
-import { AddressEntries, AddressLink } from "./address-values.mjs";
-export { AddressEntries, encodeAddresses, cloneAddressState } from "./address-values.mjs";
+import { AddressEntries, AddressLink, readPublishedAddresses } from "./address-values.mjs";
+export {
+    AddressEntries,
+    encodeAddresses,
+    cloneAddressState,
+    publishAddresses,
+    readPublishedAddresses,
+    flattenPublishedAddresses,
+} from "./address-values.mjs";
 
 /** Structured positions whose Address is nested inside a declared container. */
 export const STRUCTURED_ADDRESSES = Object.freeze([
@@ -77,12 +87,24 @@ export function addressPositions(fm, context = {}) {
                 shape,
                 type: field.ref,
                 accepts: field.accepts,
+                ...(field.anchors ? { anchors: field.anchors } : {}),
                 ...(ASSET_TYPE_NAMES.has(field.ref) || field.ref === "folder" ?
                     { system: "none" }
                 :   {}),
             });
     }
     out.push(...STRUCTURED_ADDRESSES.filter((p) => !p.noteType || p.noteType === fm.type));
+    // An event's Addresses, on every type that carries events. Read leniently:
+    // a value that is no accepted Address stays as written, for the event
+    // check to refuse at its own key with the message its key earns, rather
+    // than taking the whole note out of the index.
+    if ((dataFields(fm.type) ?? []).some((field) => field.name === "events"))
+        for (const position of EVENT_ADDRESS_POSITIONS)
+            out.push({
+                ...position,
+                path: ["data", "events", "*", ...position.path],
+                lenient: true,
+            });
     for (const system of new Set([
         ...SHIPPED_SYSTEMS,
         ...Object.keys(context.systemBlocks ?? {}),
@@ -206,7 +228,27 @@ export function decodeNoteAddresses(fm, context) {
         };
         const read = (value, path) => {
             if (value == null || value === "") return value;
-            const tuple = parseAddress(value, defaults, {
+            if (value instanceof AddressLink) {
+                if (!position.anchors)
+                    fail(
+                        value,
+                        path,
+                        "takes no anchor — it names a whole note, so write the Address without `#…`",
+                    );
+                return value;
+            }
+            // An anchor is admitted only where the position declares the kinds
+            // it takes; the anchor's existence and kind are a resolution
+            // question, asked where the index is.
+            const anchored = hasAnchor(value);
+            if (anchored && !position.anchors)
+                fail(
+                    value,
+                    path,
+                    "takes no anchor — it names a whole note, so write the Address without `#…`",
+                );
+            const { address: written, anchor } = anchored ? splitAnchor(value) : { address: value };
+            const tuple = parseAddress(written, defaults, {
                 declared: true,
                 legacyShortcodeCase: position.legacyShortcodeCase,
             });
@@ -217,7 +259,13 @@ export function decodeNoteAddresses(fm, context) {
                     path,
                     `must name a ${position.accepts.join(" or ")} Address, but names ${tuple.type}`,
                 );
-            return tuple;
+            return anchored ?
+                    new AddressLink(
+                        tuple,
+                        anchor,
+                        position.anchors.length === 1 ? position.anchors[0] : null,
+                    )
+                :   tuple;
         };
         const convert = (value, path) => {
             if (value == null || value === "") return value;
@@ -258,12 +306,24 @@ export function decodeNoteAddresses(fm, context) {
             }
             return read(value, path);
         };
+        // A lenient position keeps a value it cannot read, as written.
+        const settle = (value, path) => {
+            if (!position.lenient) return convert(value, path);
+            try {
+                return convert(value, path);
+            } catch {
+                return value;
+            }
+        };
         // 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");
+                if (!Array.isArray(owner)) {
+                    if (position.lenient) return 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;
@@ -271,7 +331,7 @@ export function decodeNoteAddresses(fm, context) {
             const copy = Array.isArray(owner) ? [...owner] : { ...owner };
             copy[key] =
                 offset === path.length - 1 ?
-                    convert(owner[key], [...actual, key])
+                    settle(owner[key], [...actual, key])
                 :   visit(owner[key], path, offset + 1, [...actual, key]);
             return copy;
         };
@@ -312,11 +372,18 @@ export function noteAddressContext(config) {
 
 /**
  * Decode Address properties contributed by an index record.
+ *
+ * A record read from a published index writes every Address as
+ * `{ address, anchor, anchorKind }`; each becomes a tuple, or an
+ * {@link AddressLink} where it carries an anchor, before the declared
+ * positions are read.
+ *
  * @param {object} record - The record.
  * @param {object} context - Builder defaults.
  * @returns {object} The typed record.
  */
 export function decodeIndexAddresses(record, context) {
+    Object.assign(record, readPublishedAddresses(record));
     decodeNoteAddresses(record, context);
     const canonical = (value, keyPath) => {
         const target = readCanonicalKey(value);
@@ -335,19 +402,8 @@ export function decodeIndexAddresses(record, context) {
     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: "note",
-                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);
+        if (anchor.link != null && !(anchor.link instanceof AddressLink))
+            throw new Error(`Index anchor link is not an Address: ${JSON.stringify(anchor.link)}`);
     }
     return record;
 }

package/engine/note-dates.mjs

@@ -955,11 +955,13 @@ function resolveEventEntry(entry, context) {
 
 /** Normalize a note's declared dates for indexes and generated pages. */
 export function resolvedDateFields(fm, context) {
-    if (fm?.type === "lore") {
-        const events = Array.isArray(fm.data?.events) ? fm.data.events : [];
-        const resolved = events.map((entry) => resolveEventEntry(entry, context));
+    // A note carrying `data.events` — a lore, place or affiliation note — is
+    // dated by them.
+    if (Array.isArray(fm?.data?.events)) {
+        const resolved = fm.data.events.map((entry) => resolveEventEntry(entry, context));
         return resolved.length ? { events: resolved } : {};
     }
+    if (fm?.type === "lore") return {};
     const fields =
         fm?.type === "being" ?
             [

package/engine/note-event-terms.mjs

@@ -0,0 +1,364 @@
+/*
+ * 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
+ */
+
+/**
+ * The **terms of an event**: the closed value lists an event entry draws on,
+ * and the declaration of every key an entry and each map inside it take.
+ *
+ * A leaf module, importing nothing. The note vocabulary reads
+ * {@link EVENT_ENTRY} as it loads, so the frontmatter lint's inner-key check
+ * closes every key of an entry the way it closes every other `data:` field's;
+ * {@link module:engine/note-events} walks the same declaration for what the
+ * values mean — closed lists, Addresses, identity and order — and reaches the
+ * vocabulary through the Address reader.
+ *
+ * An entry is declared in the inner-key vocabulary of
+ * {@link module:engine/data-keys} — `fields`, `entries`, `kind`, `shape`,
+ * `required`, `describe` — with four properties of its own that the event
+ * check reads:
+ *
+ * - `oneOf` — `{name, values}`: the value is one of `values`, a closed list the
+ *   format reference states as the vocabulary table `name`;
+ * - `ref`, `accepts`, `anchors`, `single`, `eventOrLore`, `calendar` on an
+ *   Address: its default type, its accepted types, the anchor kinds it may
+ *   name, and whether it must name exactly one event, an event or a `lore`
+ *   note, or a calendar note;
+ * - `own` — the key's value is judged by the event check's own code (`id`,
+ *   `when`, `until`, `recurs`) rather than by the walker.
+ *
+ * @module
+ */
+
+/** What an event is, grouped for reading and closed for validation. */
+export const EVENT_KINDS = Object.freeze([
+    // peoples
+    "arrival",
+    "departure",
+    "migration",
+    "contact",
+    "displacement",
+    // polities
+    "founding",
+    "charter",
+    "accession",
+    "secession",
+    "conquest",
+    "treaty",
+    "dissolution",
+    // conflict
+    "battle",
+    "war",
+    "siege",
+    "revolt",
+    // ruin
+    "fall",
+    "catastrophe",
+    "plague",
+    "famine",
+    // works
+    "raising",
+    "ruin",
+    "making",
+    "loss",
+    "discovery",
+    // institutions and belief
+    "schism",
+    "law",
+    "council",
+    // persons
+    "birth",
+    "death",
+]);
+
+/** How far an event's history reaches. Set by hand. */
+export const EVENT_DEPTHS = Object.freeze(["world", "region", "local"]);
+
+/** What the world's evidence supports about an event. */
+export const EVENT_STANDINGS = Object.freeze([
+    "attested",
+    "single-source",
+    "reconstructed",
+    "disputed",
+    "legendary",
+]);
+
+/** Whether a place that felt an event knows what caused it. */
+export const REACH_KNOWLEDGE = Object.freeze(["named", "misattributed", "unlinked"]);
+
+/** What a participant was to an event. */
+export const PARTICIPANT_ROLES = Object.freeze([
+    "actor",
+    "victim",
+    "instrument",
+    "witness",
+    "founder",
+    "ruler",
+    "author",
+    "signatory",
+]);
+
+/** How a later event follows from an earlier one. */
+export const FOLLOWS_HOW = Object.freeze(["caused", "enabled", "ended", "answered"]);
+
+/** How far an account agrees with the event's summary. */
+export const ACCOUNT_AGREES = Object.freeze(["full", "partly", "disputes", "denies", "silent"]);
+
+/**
+ * Every closed list, by the name of the vocabulary table the format reference
+ * and `engine/content-format.yaml` state it under. `eventKind` is not `kind`
+ * because the infobox's row kinds already hold that name.
+ */
+export const EVENT_VOCABULARIES = Object.freeze({
+    eventKind: EVENT_KINDS,
+    depth: EVENT_DEPTHS,
+    standing: EVENT_STANDINGS,
+    knowledge: REACH_KNOWLEDGE,
+    role: PARTICIPANT_ROLES,
+    followsHow: FOLLOWS_HOW,
+    agrees: ACCOUNT_AGREES,
+});
+
+/** A key holding text, stated with something in it. */
+const text = (name, describe, required = false) =>
+    Object.freeze({ name, kind: "string", shape: "a string", required, describe });
+
+/** A key holding one value of a closed list. */
+const oneOf = (name, vocabulary, describe, required = false) =>
+    Object.freeze({
+        name,
+        kind: "string",
+        shape: `one \`${vocabulary}\` value`,
+        oneOf: Object.freeze({ name: vocabulary, values: EVENT_VOCABULARIES[vocabulary] }),
+        required,
+        describe,
+    });
+
+/** A key holding one Address, with what it may name. */
+const address = (name, shape, describe, extra = {}, required = false) =>
+    Object.freeze({ name, kind: "address", shape, required, describe, ...extra });
+
+/** A key holding a list of maps, each closed to `fields`. */
+const listOf = (name, shape, describe, fields) =>
+    Object.freeze({
+        name,
+        kind: "list",
+        shape,
+        entries: Object.freeze({
+            kind: "map",
+            shape: `a map — ${shape.replace(/\[\]$/, "")}`,
+            fields,
+        }),
+        describe,
+    });
+
+/** An Address naming a place; a bare shortcode is read as one. */
+const PLACE = Object.freeze({ ref: "place", accepts: Object.freeze(["place"]) });
+
+/**
+ * One event entry, as an inner-key declaration: every key it takes, and every
+ * key of each map nested in it.
+ *
+ * @type {Readonly<{kind: "map", shape: string, fields: readonly object[]}>}
+ */
+export const EVENT_ENTRY = Object.freeze({
+    kind: "map",
+    shape: "an event — a map of the keys below",
+    fields: Object.freeze([
+        Object.freeze({
+            name: "id",
+            kind: "shortcode",
+            shape: "an address segment",
+            own: true,
+            describe: "The event's name within its note — lowercase letters and digits.",
+        }),
+        oneOf("kind", "eventKind", "What sort of thing happened."),
+        oneOf("depth", "depth", "How far the event's history reaches."),
+        Object.freeze({
+            name: "when",
+            kind: "date",
+            shape: 'a date, or `"0.<day>"`',
+            required: true,
+            own: true,
+            describe: "When it happened, or the anchor and first instance of an event that recurs.",
+        }),
+        Object.freeze({
+            name: "until",
+            kind: "date",
+            shape: "a date",
+            own: true,
+            describe: "When a continuous event ended, or where a recurring series stopped.",
+        }),
+        Object.freeze({
+            name: "recurs",
+            kind: "map",
+            shape: "`{ every }` or `{ on }`",
+            own: true,
+            fields: Object.freeze([
+                Object.freeze({
+                    name: "every",
+                    kind: "integer",
+                    shape: "a whole number of years, 1 or more",
+                    describe: "A period counted on the canonical axis from `when`.",
+                }),
+                Object.freeze({
+                    name: "on",
+                    kind: "list",
+                    shape: "a list of dates, strictly increasing, each later than `when`",
+                    entries: Object.freeze({ kind: "date", shape: "a date" }),
+                    describe: "Recorded occurrences beyond the first, in place of a period.",
+                }),
+            ]),
+            describe: "How further occurrences are found; absent for an event that happened once.",
+        }),
+        text("summary", "What happened, stated plainly.", true),
+        oneOf("standing", "standing", "What the world's evidence supports."),
+        listOf(
+            "names",
+            "`{ name, by, gloss? }[]`",
+            "The event's names in the world, each with who uses it.",
+            [
+                text("name", "One name the event goes by in the world.", true),
+                address(
+                    "by",
+                    "an Address naming an `affiliation`, `lore`, `place`, `being` or `skill` note",
+                    "Who uses that name — a people, a polity, a faith, a place, a tongue.",
+                    { accepts: Object.freeze(["affiliation", "lore", "place", "being", "skill"]) },
+                    true,
+                ),
+                text("gloss", "What the name means, or how it is used."),
+            ],
+        ),
+        Object.freeze({
+            name: "where",
+            kind: "map",
+            shape: "`{ locus?, reach? }`",
+            fields: Object.freeze([
+                Object.freeze({
+                    name: "locus",
+                    kind: "list",
+                    shape: "a list of Addresses, each defaulting to `place`",
+                    entries: Object.freeze({ kind: "address", shape: "a place Address", ...PLACE }),
+                    describe: "Where the event physically happened; each resolves to a place.",
+                }),
+                listOf(
+                    "reach",
+                    "`{ place, how, knowledge, attributedTo? }[]`",
+                    "Where the event was felt, and whether each place knows why.",
+                    [
+                        address(
+                            "place",
+                            "an Address, defaulting to `place`",
+                            "A place where the event was felt.",
+                            PLACE,
+                            true,
+                        ),
+                        text(
+                            "how",
+                            "One clause: a consequence someone in that place could notice.",
+                            true,
+                        ),
+                        oneOf(
+                            "knowledge",
+                            "knowledge",
+                            "Whether that place connects what it felt to this event.",
+                            true,
+                        ),
+                        address(
+                            "attributedTo",
+                            "an Address, defaulting to `lore`, naming an event or a `lore` note",
+                            "Only beside `knowledge: misattributed` — the cause that place names instead.",
+                            { ref: "lore", anchors: Object.freeze(["event"]), eventOrLore: true },
+                        ),
+                    ],
+                ),
+            ]),
+            describe: "Where it happened, and where it was felt.",
+        }),
+        listOf("who", "`{ ref, role }[]`", "Who took part, and as what.", [
+            address(
+                "ref",
+                "an Address naming a `being`, `affiliation` or `lore` note",
+                "A participant — a being, a people, an affiliation.",
+                { accepts: Object.freeze(["being", "affiliation", "lore"]) },
+                true,
+            ),
+            oneOf("role", "role", "What the participant was to the event.", true),
+        ]),
+        listOf(
+            "follows",
+            "`{ event, how, note? }[]`",
+            "The earlier events this one follows from.",
+            [
+                address(
+                    "event",
+                    "an Address, defaulting to `lore`, anchored to an `event` where its note holds several",
+                    "The earlier event; it resolves to exactly one event.",
+                    { ref: "lore", anchors: Object.freeze(["event"]), single: true },
+                    true,
+                ),
+                oneOf("how", "followsHow", "How this event follows from it.", true),
+                text("note", "One clause saying what connects the two."),
+            ],
+        ),
+        listOf(
+            "accounts",
+            "`{ by, says, agrees, withholds? }[]`",
+            "What each people, polity, faith or place says about it.",
+            [
+                address(
+                    "by",
+                    "an Address naming an `affiliation`, `lore`, `place` or `being` note",
+                    "Who holds the account.",
+                    { accepts: Object.freeze(["affiliation", "lore", "place", "being"]) },
+                    true,
+                ),
+                text("says", "What they say happened, in their terms.", true),
+                oneOf("agrees", "agrees", "How far their account agrees with `summary`.", true),
+                text("withholds", "What they decline to say."),
+            ],
+        ),
+        Object.freeze({
+            name: "unresolved",
+            kind: "list",
+            shape: "a list of strings",
+            entries: Object.freeze({ kind: "string", shape: "a string" }),
+            describe: "What the world itself has not settled.",
+        }),
+        Object.freeze({
+            name: "sources",
+            kind: "list",
+            shape: "a list of Addresses",
+            entries: Object.freeze({ kind: "address", shape: "an Address, written with its type" }),
+            describe: "The notes that state or support the event; each resolves.",
+        }),
+        Object.freeze({
+            name: "stated",
+            kind: "map",
+            shape: "`{ calendar, text }`",
+            fields: Object.freeze([
+                address(
+                    "calendar",
+                    "an Address, or a lore shortcode",
+                    "The calendar that tradition reckons in — a `lore` note with `subType: calendar`.",
+                    { ref: "lore", accepts: Object.freeze(["lore"]), calendar: true },
+                    true,
+                ),
+                text("text", "The date as that tradition writes it.", true),
+            ]),
+            describe: "The date as one tradition writes it in its own reckoning.",
+        }),
+    ]),
+});
+
+/** Every key an event entry admits, in the order the reference documents them. */
+export const EVENT_ENTRY_KEYS = Object.freeze(EVENT_ENTRY.fields.map((field) => field.name));