@heroiclands/package-build 22.28.0 → 23.1.0

package/engine/markdown-expressions.mjs

@@ -8,6 +8,7 @@ import { formatDateInCalendar, parseNoteDate } from "./note-dates.mjs";
 import { numberWords, numberDigits } from "./number-words.mjs";
 import { slugify } from "./content-slug.mjs";
 import { WIKILINK, authoredLabel, isSamePage, parseWikilink } from "./wikilink-syntax.mjs";
+import { EVENT_REFERENCE_FIELDS, eventFieldText } from "./event-fields.mjs";
 
 /**
  * An inline expression, as an author writes one.
@@ -152,7 +153,9 @@ const HELPERS = Object.freeze([
     }),
     Object.freeze({
         name: "ref",
-        params: 'address [form="number"|"full"|"title"]',
+        params:
+            'address [form="number"|"full"|"title"] ' +
+            '| address field="when"|"until"|"kind"|"summary"|"name"',
         summary:
             'A link to a captioned item, by its anchor — `"#thorn"` on this note, ' +
             '`"note-address#thorn"` on another. `form` is `number` (the default, and ' +
@@ -160,11 +163,21 @@ const HELPERS = Object.freeze([
             "caption; or `title`, the caption alone. Always renders as a link to the " +
             "figure, and a link inside the caption contributes only its label text. " +
             "The number rendered is the one the figure carries on the surface doing " +
-            "the rendering, whichever note names it.",
+            "the rendering, whichever note names it. With `field` in place of `form`, " +
+            'the address names an event — `"place-ironfells#sack"`, `"#sack"` on this ' +
+            'note, or `"lore-founding"` for a note holding one event — and the reference ' +
+            "prints that event's `when`, `until`, `kind`, `summary` or `name` as plain " +
+            "text, never a link; a date prints as the note format prints any date.",
         make:
-            ({ figures }) =>
+            ({ figures, events, fm, dates }) =>
             (address, options) => {
                 const hash = options?.hash ?? {};
+                if (Object.hasOwn(hash, "field")) {
+                    if (Object.hasOwn(hash, "form")) throw new RangeError(REF_BOTH_FAULT);
+                    const result = eventReference(address, hash.field, { events, fm, dates });
+                    if (result.problem) throw new RangeError(result.problem);
+                    return result.text;
+                }
                 const form = Object.hasOwn(hash, "form") ? hash.form : "number";
                 const formFault = refFormFault(form);
                 if (formFault) throw new RangeError(formFault);
@@ -184,6 +197,74 @@ const HELPERS = Object.freeze([
     }),
 ]);
 
+/** What a reference writing both `form` and `field` is told. */
+const REF_BOTH_FAULT = "ref takes form= for a figure or field= for an event, not both";
+
+/**
+ * The text one event reference prints, or why it prints nothing.
+ *
+ * The address is read through the wikilink grammar, as a figure reference's
+ * is: `"#sack"` names an event of this note, `"place-ironfells#sack"` one of
+ * another, and `"lore-founding"` a note holding exactly one event. The anchor
+ * must be one the note declares, and an `event` one.
+ *
+ * @param {unknown} address - The reference's address.
+ * @param {unknown} field - The field to print, one of {@link EVENT_REFERENCE_FIELDS}.
+ * @param {{events?: {note: (written: string) => object|undefined,
+ *   own?: (fm: object) => object|undefined}, fm?: object,
+ *   dates?: object}} context - Every note's events, this note's frontmatter,
+ *   and the reckoning context.
+ * @returns {{text: string}|{problem: string}} The text, with any link reduced to
+ *   its label, or the finding's message.
+ */
+function eventReference(address, field, { events, fm, dates } = {}) {
+    if (!EVENT_REFERENCE_FIELDS.includes(field))
+        return { problem: `ref's field must be one of ${EVENT_REFERENCE_FIELDS.join(", ")}` };
+    if (typeof address !== "string" || !address.trim())
+        return { problem: "ref needs an address naming an event" };
+    if (!events?.note)
+        return { problem: `ref "${address}" names an event, and this build resolves none` };
+    const parsed = parseWikilink(address);
+    const same = isSamePage(parsed);
+    const note = same ? events.own?.(fm) : events.note(parsed.target);
+    if (!note)
+        return {
+            problem:
+                same ?
+                    `ref "${address}" names an event of this note, which this build does not resolve`
+                :   `ref "${address}" addresses "${parsed.target}", which names no note this build resolves`,
+        };
+    let event;
+    if (parsed.anchor) {
+        const anchor = note.anchors.find((one) => one?.slug === parsed.anchor);
+        event = note.events.find((one) => one.id === parsed.anchor);
+        if (anchor && anchor.kind !== "event")
+            return {
+                problem:
+                    `ref "${address}" names "#${parsed.anchor}", a ${anchor.kind ?? "prose"} ` +
+                    "anchor — field= reads an event",
+            };
+        if (!event)
+            return {
+                problem: `ref "${address}" names no anchor "#${parsed.anchor}" in "${note.target}"`,
+            };
+    } else {
+        if (note.events.length !== 1)
+            return {
+                problem:
+                    note.events.length === 0 ?
+                        `ref "${address}" names "${note.target}", which holds no events`
+                    :   `ref "${address}" names "${note.target}", which holds ` +
+                        `${note.events.length} events — name one as "${parsed.target}#<id>"`,
+            };
+        event = note.events[0];
+    }
+    const value = eventFieldText(event, field, dates);
+    if (value.missing)
+        return { problem: `ref "${address}" field="${field}": that event states no ${field}` };
+    return { text: flattenCaptionLinks(value.text) };
+}
+
 /** The closed set of forms a figure reference may render as; `number` is the default. */
 const REF_FORMS = Object.freeze(["number", "full", "title"]);
 
@@ -382,10 +463,25 @@ export function sqlQueriesInMarkdown(body, fm = {}) {
  * @param {object} node - A `MustacheStatement`/`SubExpression` AST node.
  * @param {object} [figures] - This note's figures, and how to reach another
  *   note's — see {@link refFigure}.
+ * @param {object} [eventContext] - What an event reference reads — see
+ *   {@link eventReference}.
  * @returns {string|null} A finding message, or `null` when the call is sound.
  */
-function refCallFault(node, figures) {
+function refCallFault(node, figures, eventContext) {
     const pair = node.hash?.pairs?.find((entry) => entry.key === "form");
+    const fieldPair = node.hash?.pairs?.find((entry) => entry.key === "field");
+    if (fieldPair) {
+        if (fieldPair.value.type !== "StringLiteral")
+            return (
+                "ref's field must be a quoted string — one of " + EVENT_REFERENCE_FIELDS.join(", ")
+            );
+        if (pair) return REF_BOTH_FAULT;
+        const addressParam = node.params?.[0];
+        if (addressParam?.type !== "StringLiteral") return null;
+        return (
+            eventReference(addressParam.value, fieldPair.value.value, eventContext).problem ?? null
+        );
+    }
     if (pair && pair.value.type !== "StringLiteral")
         return `ref's form must be a quoted string — one of ${REF_FORMS.join(", ")}`;
     const form = pair ? pair.value.value : "number";
@@ -413,10 +509,12 @@ function refCallFault(node, figures) {
  * @param {string} body
  * @param {object} [figures] - This note's figures, and how to reach another
  *   note's — see {@link refFigure}.
+ * @param {object} [eventContext] - What an event reference reads — see
+ *   {@link eventReference}.
  * @returns {Array<{offset: number, message: string}>} One entry per faulty
  *   `{{...}}` expression, `offset` into `body`.
  */
-function refFaults(body, figures) {
+function refFaults(body, figures, eventContext) {
     const faults = [];
     for (const match of matchAllOutsideCode(body, EXPRESSION)) {
         let program;
@@ -428,7 +526,7 @@ function refFaults(body, figures) {
         const visit = (node) => {
             if (!node || typeof node !== "object") return;
             if (node.path?.original === "ref") {
-                const message = refCallFault(node, figures);
+                const message = refCallFault(node, figures, eventContext);
                 if (message) faults.push({ offset: match.index, message });
             }
             for (const parameter of node.params ?? []) visit(parameter);
@@ -452,22 +550,29 @@ function positionAt(body, offset, bodyLine) {
  *   figures?: {get: (id: string) => {label: string, caption: string,
  *   hasCaption: boolean}|undefined, note?: (address: string) =>
  *   {url: string|null, figures: Map<string, object>}|undefined,
- *   link?: Function}, file?: string, bodyLine?: number}} [options] -
+ *   link?: Function}, events?: {note: (written: string) => object|undefined,
+ *   own?: (fm: object) => object|undefined},
+ *   file?: string, bodyLine?: number}} [options] -
  *   `figures` is the `ref` helper's own view of the corpus: `get` reads this
  *   note's captioned items by id, and `note` resolves another note's the
  *   way a wikilink would — omitted, a cross-note address is refused rather
  *   than looked up. `link` overrides how a resolved reference renders; the
- *   default is a Markdown link to the target's own anchor.
+ *   default is a Markdown link to the target's own anchor. `events` is what an
+ *   event reference reads: every note's events by Address, from
+ *   {@link module:engine/event-fields.eventNoteIndex}; omitted, an event
+ *   reference is refused.
  */
 export function renderMarkdownExpressions(
     body,
-    { fm, dates, sqlResults, figures, file, bodyLine = 1 } = {},
+    { fm, dates, sqlResults, figures, events, file, bodyLine = 1 } = {},
 ) {
     const findings = [];
     const engine = Handlebars.create();
     for (const helper of HELPERS)
-        engine.registerHelper(helper.name, helper.make({ sqlResults, dates, figures }));
-    const staticFaults = new Map(refFaults(body, figures).map((f) => [f.offset, f.message]));
+        engine.registerHelper(helper.name, helper.make({ sqlResults, dates, figures, events, fm }));
+    const staticFaults = new Map(
+        refFaults(body, figures, { events, fm, dates }).map((f) => [f.offset, f.message]),
+    );
     const markdown = replaceOutsideCode(body, EXPRESSION, (source, _inside, offset) => {
         const fault = staticFaults.get(offset);
         if (fault) {

package/engine/metadata-index.mjs

@@ -307,6 +307,27 @@ function newestIndex(dirs) {
     return path.join(dir, entries[0]);
 }
 
+/**
+ * A published record's events, each with its `id`, the dates the publishing
+ * package resolved for it, and the entry as published, which an inline
+ * reference to one of its fields reads.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {Array<{id?: string, when?: object, until?: object, entry: object}>|undefined}
+ *   In entry order, or `undefined` for a note with none.
+ */
+function publishedEvents(record) {
+    const events = record.data?.events;
+    if (!Array.isArray(events) || events.length === 0) return undefined;
+    const resolved = record.resolvedDates?.events ?? [];
+    return events.map((entry, position) => ({
+        ...(typeof entry?.id === "string" ? { id: entry.id } : {}),
+        ...(resolved[position]?.when ? { when: resolved[position].when } : {}),
+        ...(resolved[position]?.until ? { until: resolved[position].until } : {}),
+        entry,
+    }));
+}
+
 /**
  * Resolve every foreign address this build can cite, from the fetched indexes.
  *
@@ -437,6 +458,19 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 ...(Object.hasOwn(record.data ?? {}, "government") ?
                     { government: record.data.government }
                 :   {}),
+                // Every anchor the note declares, with its kind, and each of its
+                // events with its id and resolved date, so a consumer's
+                // `follows` edge into this package is resolved and ordered here.
+                noteAnchors: record.anchors ?? undefined,
+                events: publishedEvents(record),
+                // What a work of literature concerns and what kind of work it
+                // is, so a consumer's subject pages list a dependency's works.
+                ...(parts.type === "lore" && record.subType === "literature" ?
+                    {
+                        subjects: record.data?.subjects ?? undefined,
+                        form: record.data?.form ?? undefined,
+                    }
+                :   {}),
                 package: pkg,
             });
             const entry = index.get(key);

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" ?
             [