@heroiclands/package-build 22.22.0 → 22.24.0

package/engine/lore-events.mjs

@@ -0,0 +1,197 @@
+/*
+ * 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
+ */
+
+/**
+ * Validate a `lore` note's `data.events` list, entry by entry.
+ *
+ * `data.events` is declared `kind: "list"` with a prose `shape`, the way
+ * `data.eras` already is (`engine/calendar-notes.mjs`), and checked by its own
+ * walker rather than by the generic `data:` container check, which only knows
+ * that the value is an array. Every finding here is positioned at
+ * `["data", "events", position, ...]`, so it lands on the entry that carries
+ * the fault rather than on the note.
+ *
+ * @module
+ */
+
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+import { parseNoteDate } from "./note-dates.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
+
+/** Whether a value is a plain map — not `null`, not an array. */
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Validate one `lore` note's `data.events`.
+ *
+ * Registered as the `events` field's own `check` in `note-vocabulary.mjs`, so
+ * it runs on every `lore` note regardless of `subType` — an occasion is not a
+ * calendar fact, and nothing here is scoped to `subType: calendar`.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {{index?: object}} [options]
+ * @returns {object[]} Findings, each positioned at the entry that earned it.
+ */
+export function checkLoreEvents(note, { index } = {}) {
+    const events = note.fm?.data?.events;
+    if (!Array.isArray(events)) return [];
+
+    const findings = [];
+    const dates = reckoningContext(index);
+    const at = (path, message) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(note.raw ?? "", path),
+        severity: "error",
+        message,
+    });
+
+    events.forEach((entry, position) => {
+        const row = mapping(entry) ? entry : {};
+        const base = ["data", "events", position];
+
+        const when = parseNoteDate(row.when, {
+            ...dates,
+            allowUnknown: true,
+            allowZeroYear: true,
+            field: "when",
+            file: note.file,
+            raw: note.raw,
+            keyPath: [...base, "when"],
+        });
+        findings.push(...when.findings);
+
+        const until = parseNoteDate(row.until, {
+            ...dates,
+            allowUnknown: false,
+            field: "until",
+            file: note.file,
+            raw: note.raw,
+            keyPath: [...base, "until"],
+        });
+        findings.push(...until.findings);
+
+        const recurs = row.recurs;
+        if (recurs === undefined || recurs === null) return;
+
+        if (row.when === undefined || row.when === null) {
+            findings.push(
+                at(
+                    [...base, "recurs"],
+                    "`recurs` needs a `when` of its own — a recurrence counts from the anchor it names",
+                ),
+            );
+            return;
+        }
+        if (when.date?.known && when.date.year === 0) {
+            findings.push(
+                at(
+                    [...base, "recurs"],
+                    "`recurs` is refused beside a `when` of year 0 — that date already recurs " +
+                        "on that day every year, and `every` above 1 cannot be counted without " +
+                        "an anchor year",
+                ),
+            );
+            return;
+        }
+        if (!mapping(recurs)) {
+            findings.push(at([...base, "recurs"], "`recurs` is a map of `every` or `on`"));
+            return;
+        }
+
+        const hasEvery = Object.hasOwn(recurs, "every");
+        const hasOn = Object.hasOwn(recurs, "on");
+        if (hasEvery && hasOn) {
+            findings.push(
+                at(
+                    [...base, "recurs"],
+                    "`recurs` declares exactly one of `every` or `on`, not both — a period " +
+                        "with exceptions is written as an enumeration",
+                ),
+            );
+            return;
+        }
+        if (!hasEvery && !hasOn) {
+            findings.push(
+                at(
+                    [...base, "recurs"],
+                    "`recurs` needs `every` or `on` — its absence is what says the occasion " +
+                        "happened once",
+                ),
+            );
+            return;
+        }
+
+        if (hasEvery) {
+            const { every } = recurs;
+            if (!(Number.isInteger(every) && every >= 1)) {
+                findings.push(
+                    at(
+                        [...base, "recurs", "every"],
+                        `\`recurs.every\` needs a whole number of years, 1 or more, but reads ` +
+                            `${JSON.stringify(every)}`,
+                    ),
+                );
+            }
+            return;
+        }
+
+        if (row.until !== undefined && row.until !== null) {
+            findings.push(
+                at(
+                    [...base, "until"],
+                    "`until` is refused beside `recurs.on` — the enumeration states its own " +
+                        "last entry",
+                ),
+            );
+        }
+
+        const onList = recurs.on;
+        if (!Array.isArray(onList) || onList.length === 0) {
+            findings.push(at([...base, "recurs", "on"], "`recurs.on` needs a list of dates"));
+            return;
+        }
+
+        let previous = when.date?.known ? when.date : null;
+        onList.forEach((onRaw, onPosition) => {
+            const onPath = [...base, "recurs", "on", onPosition];
+            const onParsed = parseNoteDate(onRaw, {
+                ...dates,
+                allowUnknown: false,
+                field: "recurs.on",
+                file: note.file,
+                raw: note.raw,
+                keyPath: onPath,
+            });
+            findings.push(...onParsed.findings);
+            const onDate = onParsed.date;
+            if (onDate?.known && previous?.known) {
+                if (onDate.sort <= previous.sort) {
+                    findings.push(
+                        at(
+                            onPath,
+                            onPosition === 0 ?
+                                "`recurs.on` entry is at or before `when`, so it is not a " +
+                                    "later occurrence"
+                            :   "`recurs.on` entries are not strictly increasing",
+                        ),
+                    );
+                }
+            }
+            if (onDate?.known) previous = onDate;
+        });
+    });
+
+    return findings;
+}

package/engine/markdown-expressions.mjs

@@ -6,6 +6,8 @@ import { isAddressTuple, renderAddress } from "./address.mjs";
 import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
 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";
 
 /**
  * An inline expression, as an author writes one.
@@ -148,8 +150,164 @@ const HELPERS = Object.freeze([
                 return printable.prose ?? printable.text;
             },
     }),
+    Object.freeze({
+        name: "ref",
+        params: 'address [form="number"|"full"|"title"]',
+        summary:
+            'A link to a `:::figure` fence, by its anchor — `"#thorn"` on this note, ' +
+            '`"note-address#thorn"` on another. `form` is `number` (the default, and ' +
+            'admitted explicitly), rendering "Figure 13"; `full`, the number and the ' +
+            "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.",
+        make:
+            ({ figures }) =>
+            (address, options) => {
+                const hash = options?.hash ?? {};
+                const form = Object.hasOwn(hash, "form") ? hash.form : "number";
+                const formFault = refFormFault(form);
+                if (formFault) throw new RangeError(formFault);
+                if (typeof address !== "string" || !address.trim())
+                    throw new TypeError("ref needs an address naming a figure's anchor");
+                const { parsed, figure, crossNote, noteFound, url } = refFigure(address, figures);
+                if (!figure)
+                    throw new RangeError(refNotFoundFault(address, parsed, crossNote, noteFound));
+                if (form !== "number" && !figure.hasCaption)
+                    throw new RangeError(refNoCaptionFault(form, parsed));
+                return renderRef(figure, parsed, form, { url, link: figures?.link });
+            },
+    }),
 ]);
 
+/** The closed set of forms a figure reference may render as; `number` is the default. */
+const REF_FORMS = Object.freeze(["number", "full", "title"]);
+
+/**
+ * Whether a `ref` helper's `form` is one of {@link REF_FORMS}.
+ * @param {unknown} form - The resolved value, quoted or not.
+ * @returns {string|null} A finding message, or `null` when the form is valid.
+ */
+function refFormFault(form) {
+    return REF_FORMS.includes(form) ? null : `ref's form must be one of ${REF_FORMS.join(", ")}`;
+}
+
+/**
+ * The figure a `ref` address names, read through the wikilink grammar's own
+ * address parsing rather than a second parser.
+ *
+ * A same-page address reads `figures.get`. A cross-note address reads
+ * `figures.note`, which resolves the written address exactly as a wikilink
+ * does and hands back the target's own figures and its own address — a build
+ * that resolves no cross-note reference simply omits `note`, and every
+ * cross-note address is then refused alike.
+ *
+ * @param {string} address - `"#thorn"` or `"note-address#thorn"`.
+ * @param {{get: (id: string) => object|undefined,
+ *   note?: (address: string) => {url: string|null,
+ *   figures: Map<string, object>}|undefined, link?: Function}} [figures] -
+ *   This note's figures, and how to reach another note's.
+ * @returns {{parsed: object, figure: object|null, crossNote: boolean,
+ *   noteFound: boolean, url: string|null}} The parsed address, the figure it
+ *   names (`null` when none matches), whether the address names another
+ *   note, whether that note was found at all, and the target's own address
+ *   (`null` for a same-page reference).
+ */
+function refFigure(address, figures) {
+    const parsed = parseWikilink(address);
+    if (isSamePage(parsed)) {
+        return {
+            parsed,
+            figure: figures?.get(parsed.anchor) ?? null,
+            crossNote: false,
+            noteFound: true,
+            url: null,
+        };
+    }
+    const note = figures?.note?.(parsed.target);
+    if (!note) return { parsed, figure: null, crossNote: true, noteFound: false, url: null };
+    return {
+        parsed,
+        figure: note.figures.get(parsed.anchor) ?? null,
+        crossNote: true,
+        noteFound: true,
+        url: note.url ?? null,
+    };
+}
+
+/** The message for a `ref` address naming no figure, same-note or across notes. */
+function refNotFoundFault(address, parsed, crossNote, noteFound) {
+    if (!crossNote) return `ref "${address}" names no figure for anchor "#${parsed.anchor}"`;
+    if (!noteFound)
+        return `ref "${address}" addresses "${parsed.target}", which names no note this build resolves`;
+    return `ref "${address}" names no figure for anchor "#${parsed.anchor}" in "${parsed.target}"`;
+}
+
+/** The message for a `full` or `title` reference to a figure with no caption. */
+function refNoCaptionFault(form, parsed) {
+    return `ref form="${form}" needs a caption, and figure "#${parsed.anchor}" has none`;
+}
+
+/**
+ * A figure caption's markdown, with every link flattened to its label text.
+ *
+ * `ref` renders as a link, so a link nested inside the label it wraps would be
+ * a second anchor — invalid HTML, and unreadable in Typst. Emphasis and an
+ * icon embed nest inside an anchor legally, and are left as written.
+ *
+ * @param {string} caption - The figure's raw caption markdown.
+ * @returns {string} The caption, every link reduced to its label.
+ */
+function flattenCaptionLinks(caption) {
+    return String(caption ?? "")
+        .replace(WIKILINK, (_all, inner) => {
+            const link = parseWikilink(inner);
+            return authoredLabel(link) ?? link.inner;
+        })
+        .replace(/\[([^\]\n]*)\]\([^)\n]*\)/g, "$1");
+}
+
+/** A `ref` call's label text, for the form it was asked to render. */
+function refLabel(figure, form) {
+    if (form === "number") return figure.label;
+    const title = flattenCaptionLinks(figure.caption);
+    return form === "title" ? title : `${figure.label}: ${title}`;
+}
+
+/**
+ * The default rendering of a `ref` call — a Markdown link to the figure's
+ * anchor, on the target's own address when the reference crosses notes.
+ *
+ * @param {{anchor: string, url: string|null}} target - The anchor, and the
+ *   target note's own address (`null` for a same-page reference).
+ * @param {string} label - The link's text.
+ * @returns {string} `[label](url#anchor)`, `url` empty for a same-page link.
+ */
+function defaultRefLink({ anchor, url }, label) {
+    return `[${label}](${url ?? ""}#${slugify(anchor)})`;
+}
+
+/**
+ * A `ref` call's rendered Markdown, always a link to the figure's anchor.
+ *
+ * `link`, when the surface supplies one, replaces the default Markdown link
+ * — the one override this build needs is Foundry, which addresses a figure
+ * through its own wikilink conversion rather than through an anchor fragment
+ * a journal page cannot resolve.
+ *
+ * @param {object} figure - The figure record.
+ * @param {object} parsed - The parsed `ref` address.
+ * @param {string} form - One of {@link REF_FORMS}.
+ * @param {{url: string|null, link?: (target: {anchor: string, url: string|null},
+ *   label: string) => string}} context - The target's own address, and the
+ *   surface's own link renderer.
+ */
+function renderRef(figure, parsed, form, { url, link } = {}) {
+    const label = refLabel(figure, form);
+    const render = link ?? defaultRefLink;
+    return render({ anchor: parsed.anchor, url }, label);
+}
+
 /**
  * A comparison of two numbers, which refuses anything else.
  *
@@ -210,29 +368,121 @@ export function sqlQueriesInMarkdown(body, fm = {}) {
     return queries;
 }
 
+/**
+ * A `ref` call's fault, told from its AST node rather than its rendered
+ * result. **Only the AST tells a quoted `"full"` from an unquoted `full`** —
+ * Handlebars resolves the unquoted form against the render context before a
+ * helper ever sees it, so by the time `ref` runs the two are the same value
+ * and the distinction is gone.
+ *
+ * @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}.
+ * @returns {string|null} A finding message, or `null` when the call is sound.
+ */
+function refCallFault(node, figures) {
+    const pair = node.hash?.pairs?.find((entry) => entry.key === "form");
+    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";
+    const formFault = refFormFault(form);
+    if (formFault) return formFault;
+    const addressParam = node.params?.[0];
+    const address = addressParam?.type === "StringLiteral" ? addressParam.value : null;
+    // Not a literal address: left to the render pass, which reports whatever
+    // the resolved value turns out to be.
+    if (typeof address !== "string" || !address.trim()) return null;
+    const { parsed, figure, crossNote, noteFound } = refFigure(address, figures);
+    if (!figure) return refNotFoundFault(address, parsed, crossNote, noteFound);
+    if (form !== "number" && !figure.hasCaption) return refNoCaptionFault(form, parsed);
+    return null;
+}
+
+/**
+ * Every `ref` call's fault in a body, reachable without rendering a thing —
+ * walked from the same parsed AST {@link sqlQueriesInMarkdown} walks, since a
+ * `ref` call can sit nested inside a Boolean helper exactly as a `sql` one
+ * can.
+ *
+ * @param {string} body
+ * @param {object} [figures] - This note's figures, and how to reach another
+ *   note's — see {@link refFigure}.
+ * @returns {Array<{offset: number, message: string}>} One entry per faulty
+ *   `{{...}}` expression, `offset` into `body`.
+ */
+function refFaults(body, figures) {
+    const faults = [];
+    for (const match of matchAllOutsideCode(body, EXPRESSION)) {
+        let program;
+        try {
+            program = Handlebars.parse(match[0]).body;
+        } catch {
+            continue; // The render pass reports the malformed expression itself.
+        }
+        const visit = (node) => {
+            if (!node || typeof node !== "object") return;
+            if (node.path?.original === "ref") {
+                const message = refCallFault(node, figures);
+                if (message) faults.push({ offset: match.index, message });
+            }
+            for (const parameter of node.params ?? []) visit(parameter);
+        };
+        for (const node of program) visit(node);
+    }
+    return faults;
+}
+
+/** Where an offset into `body` sits, in the file's own line and column. */
+function positionAt(body, offset, bodyLine) {
+    const before = String(body).slice(0, offset);
+    const lines = before.split("\n");
+    return { line: bodyLine + lines.length - 1, column: lines.at(-1).length + 1 };
+}
+
 /**
  * Expand scalar frontmatter references and registered functions in Markdown prose.
  * @param {string} body
- * @param {{fm?: object, dates?: object, sqlResults?: Map<string, object>, file?: string, bodyLine?: number}} [options]
+ * @param {{fm?: object, dates?: object, sqlResults?: Map<string, object>,
+ *   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] -
+ *   `figures` is the `ref` helper's own view of the corpus: `get` reads this
+ *   note's `:::figure` fences 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.
  */
 export function renderMarkdownExpressions(
     body,
-    { fm, dates, sqlResults, file, bodyLine = 1 } = {},
+    { fm, dates, sqlResults, figures, file, bodyLine = 1 } = {},
 ) {
     const findings = [];
     const engine = Handlebars.create();
     for (const helper of HELPERS)
-        engine.registerHelper(helper.name, helper.make({ sqlResults, dates }));
+        engine.registerHelper(helper.name, helper.make({ sqlResults, dates, figures }));
+    const staticFaults = new Map(refFaults(body, figures).map((f) => [f.offset, f.message]));
     const markdown = replaceOutsideCode(body, EXPRESSION, (source, _inside, offset) => {
+        const fault = staticFaults.get(offset);
+        if (fault) {
+            const { line, column } = positionAt(body, offset, bodyLine);
+            findings.push({
+                ...(file ? { file } : {}),
+                line,
+                column,
+                severity: "error",
+                message: `Markdown expression ${source} failed: ${fault}`,
+            });
+            return source;
+        }
         try {
             return engine.compile(source, { strict: true })(fm ?? {});
         } catch (error) {
-            const before = String(body).slice(0, offset);
-            const lines = before.split("\n");
+            const { line, column } = positionAt(body, offset, bodyLine);
             findings.push({
                 ...(file ? { file } : {}),
-                line: bodyLine + lines.length - 1,
-                column: lines.at(-1).length + 1,
+                line,
+                column,
                 severity: "error",
                 message: `Markdown expression ${source} failed: ${error.message}`,
             });