@heroiclands/package-build 22.20.0 → 22.22.0

package/engine/markdown-expressions.mjs

@@ -7,8 +7,182 @@ import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
 import { formatDateInCalendar, parseNoteDate } from "./note-dates.mjs";
 import { numberWords, numberDigits } from "./number-words.mjs";
 
-// Hugo shortcodes begin `{{<` or `{{%` and stay in the source for Hugo.
-const EXPRESSION = /(?<![\\{])\{\{(?![{<%])([^{}\n]+)\}\}(?!\})/g;
+/**
+ * An inline expression, as an author writes one.
+ *
+ * Hugo shortcodes begin `{{<` or `{{%` and stay in the source for Hugo.
+ *
+ * Exported because a renderer that meets one has met a body this pass never ran
+ * over, and has to be able to say so.
+ *
+ * @type {RegExp}
+ */
+export const EXPRESSION = /(?<![\\{])\{\{(?![{<%])([^{}\n]+)\}\}(?!\})/g;
+
+/**
+ * Every helper an expression may call, with the parameters it takes.
+ *
+ * **This is the one list.** The engine registers from it and the authoring
+ * document is checked against it, so a helper added here is a helper the
+ * document must describe, and a helper the document describes but the engine
+ * does not register fails the same test.
+ *
+ * `make` receives the render's context — the prepared SQL results and the date
+ * rules — and returns the function Handlebars calls. A helper that needs
+ * neither ignores it.
+ */
+const HELPERS = Object.freeze([
+    Object.freeze({
+        name: "eq",
+        params: "a b",
+        summary: 'True when both are the same value. Compares exactly, so 1 and "1" differ.',
+        make: () => (left, right) => left === right,
+    }),
+    Object.freeze({
+        name: "gt",
+        params: "a b",
+        summary: "True when a is greater than b. Both must be finite numbers.",
+        make: () => numericCompare("gt", (a, b) => a > b),
+    }),
+    Object.freeze({
+        name: "gte",
+        params: "a b",
+        summary: "True when a is greater than or equal to b. Both must be finite numbers.",
+        make: () => numericCompare("gte", (a, b) => a >= b),
+    }),
+    Object.freeze({
+        name: "lt",
+        params: "a b",
+        summary: "True when a is less than b. Both must be finite numbers.",
+        make: () => numericCompare("lt", (a, b) => a < b),
+    }),
+    Object.freeze({
+        name: "lte",
+        params: "a b",
+        summary: "True when a is less than or equal to b. Both must be finite numbers.",
+        make: () => numericCompare("lte", (a, b) => a <= b),
+    }),
+    Object.freeze({
+        name: "not",
+        params: "value",
+        summary: "True when the value is false, zero, empty or absent.",
+        make: () => (value) => !value,
+    }),
+    Object.freeze({
+        name: "and",
+        params: "value …",
+        summary: "True when every value given is true. Takes two or more.",
+        make:
+            () =>
+            (...args) =>
+                args.slice(0, -1).every(Boolean),
+    }),
+    Object.freeze({
+        name: "or",
+        params: "value …",
+        summary: "True when any value given is true. Takes two or more.",
+        make:
+            () =>
+            (...args) =>
+                args.slice(0, -1).some(Boolean),
+    }),
+    Object.freeze({
+        name: "words",
+        params: "number",
+        summary:
+            "The number spelled out for running prose — `1200` becomes one thousand two hundred. " +
+            "Whole numbers only; a decimal is a finding, and `digits` takes one.",
+        make: () => (value) => numberWords(value),
+    }),
+    Object.freeze({
+        name: "digits",
+        params: "number",
+        summary:
+            "The number as a grouped numeral — `1200` becomes 1,200, and a fractional part is kept.",
+        make: () => (value) => numberDigits(value),
+    }),
+    Object.freeze({
+        name: "sql",
+        params: '"query"',
+        summary:
+            "The single value a query returns, for use inside a sentence. The query is a quoted " +
+            "string, the same SQL a table fence takes.",
+        make:
+            ({ sqlResults }) =>
+            (query) => {
+                if (typeof query !== "string" || !query.trim())
+                    throw new TypeError("sql needs a nonempty query string");
+                const result = sqlResults?.get(query);
+                if (!result)
+                    throw new RangeError(`SQL expression has no prepared result: ${query}`);
+                if (result.error) throw new RangeError(`SQL expression failed: ${result.error}`);
+                return result.value;
+            },
+    }),
+    Object.freeze({
+        name: "dateformat",
+        params: 'calendar date ["format"]',
+        summary:
+            "A date written in a calendar. The calendar is an Address or its shortcode, the date " +
+            "is the value a note carries, and the optional third argument names an output pattern.",
+        make:
+            ({ dates }) =>
+            (calendar, authored, formatOrOptions) => {
+                if (
+                    !(typeof calendar === "string" || isAddressTuple(calendar)) ||
+                    !["string", "number"].includes(typeof authored)
+                )
+                    throw new TypeError("dateformat needs a calendar Address and a date");
+                const parsed = parseNoteDate(authored, { ...dates, allowUnknown: false });
+                const error = parsed.findings.find((item) => item.severity === "error");
+                if (error || !parsed.date)
+                    throw new RangeError(error?.message ?? "date does not resolve");
+                const printable = formatDateInCalendar(
+                    parsed.date,
+                    isAddressTuple(calendar) ? renderAddress(calendar) : calendar,
+                    dates,
+                    typeof formatOrOptions === "string" ? formatOrOptions : undefined,
+                );
+                if (!printable)
+                    throw new RangeError(`date cannot be printed in calendar ${calendar}`);
+                return printable.prose ?? printable.text;
+            },
+    }),
+]);
+
+/**
+ * A comparison of two numbers, which refuses anything else.
+ *
+ * Four helpers differ only in the comparison, and a value that is not a finite
+ * number is a finding rather than a silent `false`.
+ *
+ * @param {string} name - The helper's name, for the message.
+ * @param {(a: number, b: number) => boolean} compare - The comparison.
+ * @returns {(left: unknown, right: unknown) => boolean} The helper.
+ */
+function numericCompare(name, compare) {
+    return (left, right) => {
+        const finite = (value) =>
+            typeof value === "bigint" || (typeof value === "number" && Number.isFinite(value));
+        if (!finite(left) || !finite(right))
+            throw new TypeError(`${name} needs two finite numbers`);
+        return compare(left, right);
+    };
+}
+
+/**
+ * Each helper's parameters and what it does, keyed by name.
+ *
+ * The authoring document describes this surface, and a test holds the two
+ * together. A consumer reads it to list what an expression may call.
+ *
+ * @type {Readonly<Record<string, Readonly<{params: string, summary: string}>>>}
+ */
+export const EXPRESSION_HELPERS = Object.freeze(
+    Object.fromEntries(
+        HELPERS.map(({ name, params, summary }) => [name, Object.freeze({ params, summary })]),
+    ),
+);
 
 /** Find SQL helper calls, including calls nested inside Boolean expressions. */
 export function sqlQueriesInMarkdown(body, fm = {}) {
@@ -47,57 +221,8 @@ export function renderMarkdownExpressions(
 ) {
     const findings = [];
     const engine = Handlebars.create();
-    const numeric = (name, left, right) => {
-        if (
-            !["number", "bigint"].includes(typeof left) ||
-            !["number", "bigint"].includes(typeof right) ||
-            (typeof left === "number" && !Number.isFinite(left)) ||
-            (typeof right === "number" && !Number.isFinite(right))
-        )
-            throw new TypeError(`${name} needs two finite numbers`);
-    };
-    for (const [name, compare] of Object.entries({
-        gt: (a, b) => a > b,
-        gte: (a, b) => a >= b,
-        lt: (a, b) => a < b,
-        lte: (a, b) => a <= b,
-    }))
-        engine.registerHelper(name, (left, right) => {
-            numeric(name, left, right);
-            return compare(left, right);
-        });
-    engine.registerHelper("eq", (left, right) => left === right);
-    engine.registerHelper("not", (value) => !value);
-    engine.registerHelper("and", (...args) => args.slice(0, -1).every(Boolean));
-    engine.registerHelper("or", (...args) => args.slice(0, -1).some(Boolean));
-    engine.registerHelper("words", (value) => numberWords(value));
-    engine.registerHelper("digits", (value) => numberDigits(value));
-    engine.registerHelper("sql", (query) => {
-        if (typeof query !== "string" || !query.trim())
-            throw new TypeError("sql needs a nonempty query string");
-        const result = sqlResults?.get(query);
-        if (!result) throw new RangeError(`SQL expression has no prepared result: ${query}`);
-        if (result.error) throw new RangeError(`SQL expression failed: ${result.error}`);
-        return result.value;
-    });
-    engine.registerHelper("dateformat", (calendar, authored, formatOrOptions) => {
-        if (
-            !(typeof calendar === "string" || isAddressTuple(calendar)) ||
-            !["string", "number"].includes(typeof authored)
-        )
-            throw new TypeError("dateformat needs a calendar Address and a date");
-        const parsed = parseNoteDate(authored, { ...dates, allowUnknown: false });
-        const error = parsed.findings.find((item) => item.severity === "error");
-        if (error || !parsed.date) throw new RangeError(error?.message ?? "date does not resolve");
-        const printable = formatDateInCalendar(
-            parsed.date,
-            isAddressTuple(calendar) ? renderAddress(calendar) : calendar,
-            dates,
-            typeof formatOrOptions === "string" ? formatOrOptions : undefined,
-        );
-        if (!printable) throw new RangeError(`date cannot be printed in calendar ${calendar}`);
-        return printable.prose ?? printable.text;
-    });
+    for (const helper of HELPERS)
+        engine.registerHelper(helper.name, helper.make({ sqlResults, dates }));
     const markdown = replaceOutsideCode(body, EXPRESSION, (source, _inside, offset) => {
         try {
             return engine.compile(source, { strict: true })(fm ?? {});

package/engine/note-addresses.mjs

@@ -62,8 +62,12 @@ export const STRUCTURED_ADDRESSES = Object.freeze([
 export function addressPositions(fm, context = {}) {
     const out = [];
     for (const field of dataFields(fm.type) ?? []) {
+        // A field that admits both a list and a map declares both halves, and
+        // which one a note wrote is not knowable from the declaration — so the
+        // position says "either" and the conversion reads the value's shape.
         const shape =
             field.kind === "address" ? "value"
+            : field.kind === "list-or-map" ? "keys-or-list"
             : field.keyKind === "address" ? "keys"
             : field.entryKind === "address" ? field.kind
             : undefined;
@@ -197,7 +201,7 @@ export function decodeNoteAddresses(fm, context) {
                 `\`${path.join(".")}\` ${description}: ${JSON.stringify(value)}`,
             );
             error.keyPath = path;
-            error.addressKey = position.shape === "keys";
+            error.addressKey = position.shape === "keys" || position.shape === "keys-or-list";
             throw error;
         };
         const read = (value, path) => {
@@ -217,7 +221,16 @@ export function decodeNoteAddresses(fm, context) {
         };
         const convert = (value, path) => {
             if (value == null || value === "") return value;
-            if (position.shape === "keys") {
+            // Whichever of the two shapes the note wrote, read as that one. An
+            // empty list is the property editor's emptied map and converts to
+            // nothing either way.
+            const shape =
+                position.shape === "keys-or-list" ?
+                    Array.isArray(value) && value.length ?
+                        "list"
+                    :   "keys"
+                :   position.shape;
+            if (shape === "keys") {
                 if (value instanceof AddressEntries) return value;
                 if (Array.isArray(value) && value.length === 0) return value;
                 if (typeof value !== "object" || Array.isArray(value))
@@ -230,15 +243,11 @@ export function decodeNoteAddresses(fm, context) {
                     })),
                 );
             }
-            if (position.shape === "list") {
+            if (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 (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");

package/engine/note-dates.mjs

@@ -117,6 +117,39 @@ function unknownRecord() {
     };
 }
 
+/**
+ * Whether a number-valued date may have lost a trailing zero off its day.
+ *
+ * YAML reads an unquoted `<year>.<day>` as a float, and a float carries no
+ * trailing zero: `born: 667.130` and `born: 667.13` both arrive as `667.13`.
+ * The authored digits are unrecoverable by then, so the question a reader needs
+ * answered is whether a longer day was *possible* — and it was exactly when the
+ * value with one more zero on the end still names a day the world's year holds.
+ *
+ * One zero settles it. A second only makes the day ten times longer again, so a
+ * value whose single-zero expansion already falls outside the year has no
+ * reading but the one it was handed.
+ *
+ * **The world's year length is what makes the question answerable**, so a tree
+ * whose notes declare none gets no claim either way — the same rule the upper
+ * bound on a day follows. Refusing every float there would red a whole corpus
+ * over a test nothing could evaluate.
+ *
+ * @param {number} value - The authored value, as YAML parsed it.
+ * @param {number|undefined} daysPerYear - The world's year length.
+ * @returns {boolean} True when the authored day is ambiguous.
+ */
+function dayCouldHaveLostAZero(value, daysPerYear) {
+    if (Number.isInteger(value)) return false;
+    const fraction = String(Math.abs(value)).split(".")[1] ?? "";
+    // An exponent-form string carries no day at all.
+    if (!/^\d+$/.test(fraction)) return false;
+    const tenfold = Number(`${fraction}0`);
+    if (!Number.isSafeInteger(tenfold)) return false;
+    if (!Number.isSafeInteger(daysPerYear) || daysPerYear < 1) return false;
+    return tenfold <= daysPerYear;
+}
+
 /**
  * Parse one authored date.
  *
@@ -194,6 +227,22 @@ export function parseNoteDate(value, options) {
         return { date: null, findings };
     };
 
+    // An unquoted `<year>.<day>` reaches here as a float, and YAML has already
+    // dropped a trailing zero off the day: `667.13` and `667.130` arrive as one
+    // value, so nothing downstream can tell day 13 from day 130. Refused where
+    // the lost zero would still name a day inside the world's year, and read as
+    // written where no such day exists — `675.281` cannot have been `675.2810`.
+    if (typeof value === "number" && dayCouldHaveLostAZero(value, daysPerYear)) {
+        const grown = `${text}0`;
+        return refuse(
+            `${subject} is a number, and a day's trailing zero is lost before a date ` +
+                `is read — \`${text}\` and \`${grown}\` reach this check as one value. ` +
+                `Quote a canonical date that states a day, \`"${text}"\` or ` +
+                `\`"${grown}"\`, so the digits the note states are the digits the ` +
+                `build reads`,
+        );
+    }
+
     const resolveEra = (parsed, reckoning, label) => {
         if (parsed.year < 1) return refuse(`${subject} needs a positive year in ${label}`);
         if (!Number.isSafeInteger(daysPerYear) || daysPerYear < 1)

package/engine/note-frontmatter.mjs

@@ -7,22 +7,13 @@
 
 import YAML from "yaml";
 
-/** The complete ordered top-level vocabulary for addressed content notes. */
-export const NOTE_TOP_LEVEL_KEYS = Object.freeze([
-    "shortcode",
-    "name",
-    "type",
-    "subType",
-    "description",
-    "tags",
-    "data",
-    "hm3",
-    "sohl",
-    "dnd5e",
-]);
-
-/** Membership test for the top-level vocabulary. */
-export const NOTE_TOP_LEVEL_KEY_SET = new Set(NOTE_TOP_LEVEL_KEYS);
+// The top-level vocabulary itself is declared beside the other two closed
+// regions, so the lint, the formatter and the reference read one list.
+export {
+    NOTE_TOP_LEVEL_FIELDS,
+    NOTE_TOP_LEVEL_KEYS,
+    NOTE_TOP_LEVEL_KEY_SET,
+} from "./note-vocabulary.mjs";
 
 /** The name properties every note accepts, in display order. */
 export const NOTE_NAME_KEYS = Object.freeze(["full", "aliases"]);