@heroiclands/package-build 22.21.0 → 22.23.0

package/engine/note-dates.mjs

@@ -25,6 +25,14 @@
  * neutral and resolved named dates. A neutral year retains `precision: "year"`
  * and has no `canonicalDay`; day one is used only to calculate its bounds.
  *
+ * **Year 0 means any year**, and is accepted only where a caller passes
+ * `allowZeroYear` — a `lore` event's `when`. `when: "0.5"` is the fifth day of
+ * the year, in every year: the value carries `year: 0` and a `canonicalDay`,
+ * but no `canonicalYear` and no `sort`, since it names no point on the axis
+ * and cannot date its own note. Every other field keeps the ordinary
+ * refusal, and a bare `0` with no day is refused everywhere — any year with
+ * no day names nothing.
+ *
  * @module
  */
 
@@ -117,6 +125,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.
  *
@@ -166,6 +207,10 @@ export function parseNoteDate(value, options) {
         daysPerYear,
         field,
         allowUnknown = true,
+        // Narrows the year-0 refusal for exactly one caller: an `events`
+        // entry's `when`, where year 0 means "this day, every year" rather
+        // than a point on the axis. Every other field keeps the refusal.
+        allowZeroYear = false,
         file,
         raw,
         keyPath,
@@ -194,6 +239,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)
@@ -282,7 +343,14 @@ export function parseNoteDate(value, options) {
             return refuse(`${subject} cannot resolve its calendar date: ${err.message}`);
         }
     }
-    if (/^-?0+\.\d+(?::\d{6})?$/.test(unmarked))
+    // Negative zero (`-0.<day>`) is refused unconditionally — it is the same
+    // year as bare `0` written the other way, and `allowZeroYear` means only
+    // "any year", never "any year, backwards". A bare positive `0.<day>` is
+    // refused everywhere except the one caller that passes `allowZeroYear`.
+    if (
+        /^-0+\.\d+(?::\d{6})?$/.test(unmarked) ||
+        (!allowZeroYear && /^0+\.\d+(?::\d{6})?$/.test(unmarked))
+    )
         return refuse(
             `${subject} writes year 0, and no reckoning has one — the years either ` +
                 `side of an epoch are -1 and 1`,
@@ -294,6 +362,28 @@ export function parseNoteDate(value, options) {
         );
     if (unmarked.includes(".")) {
         const canonical = parseCanonicalDate(unmarked, daysPerYear ?? Number.MAX_SAFE_INTEGER);
+        if (canonical && canonical.year === 0) {
+            // Year 0 means "this day, every year" — it names no point on the
+            // axis, so it carries no `canonicalYear` and no `sort`: nothing
+            // orders it and it cannot date its note, the same silence
+            // `unknown` keeps for the fields that carry no axis position.
+            return {
+                date: {
+                    text,
+                    known: true,
+                    era: null,
+                    year: 0,
+                    month: null,
+                    day: canonical.day,
+                    approximate: approximateInput,
+                    precision: "day",
+                    canonicalDay: canonical.day,
+                    spanDays: 1,
+                    ...(canonical.seconds === undefined ? {} : { seconds: canonical.seconds }),
+                },
+                findings,
+            };
+        }
         if (canonical) {
             return {
                 date: {
@@ -606,19 +696,276 @@ export function formatNoteDate(date, era, daysPerYear, formatName) {
     return { era, year, month, day, text, prose };
 }
 
+/**
+ * The occurrences of one recurring series overlapping a bound.
+ *
+ * **No materialized occurrence list.** An annual series anchored centuries
+ * back has thousands of occurrences to the present, and the only questions a
+ * build asks are "is this year one of them" and "which is next" — so an
+ * omitted bound answers with a single occurrence rather than every one a live
+ * series could have:
+ *
+ * - `to` omitted: the first occurrence at or after `from` (default, the
+ *   anchor's own year) — "next".
+ * - `from` omitted, `to` given: the last occurrence at or before `to` —
+ *   "the greatest occurrence at or before `until`".
+ * - Both given: every occurrence between them, inclusive — a membership
+ *   probe is `from === to`.
+ *
+ * **The lower bound is not optional.** A candidate year before the anchor's
+ * own year is never an occurrence, however a bare modulo would read it: `%`
+ * takes the sign of its dividend in both JavaScript and SQL, so a year
+ * exactly one period before the anchor would otherwise match. `k` is clamped
+ * at zero rather than left to run negative.
+ *
+ * **The period advances the canonical year, never the era-relative year.**
+ * `date.canonicalYear` is already on the continuous axis `canonicalYear`
+ * builds — era year `-1` sits immediately before era year `1`, but canonical
+ * year `0` is an ordinary integer between them — so stepping by whole
+ * multiples of `every` on `canonicalYear` crosses an epoch with no special
+ * case. Counting in era-relative years instead would need a correction at
+ * every crossing and silently loses one year each time it is forgotten.
+ *
+ * **Precision, approximation and the day of year carry through untouched.**
+ * Every occurrence is the anchor's own record with only `canonicalYear`
+ * advanced, so a day-precision anchor's `canonicalDay` — including one inside
+ * a short intercalary month — names the same day of every occurrence, and an
+ * approximate anchor's occurrences are approximate too.
+ *
+ * @param {object} date - The anchor's resolved record
+ *   ({@link parseNoteDate}), carrying a real `canonicalYear`. A year-0 "any
+ *   year" anchor carries none and has no series through this function — its
+ *   `recurs` is refused, and its own next occurrence is computed directly
+ *   from the day of year alone.
+ * @param {{every?: number, on?: object[]}} [recurs] - The declared
+ *   recurrence: a whole-year period, or an enumeration of further resolved
+ *   date records (each already carrying its own `canonicalYear`). Neither
+ *   admits the other.
+ * @param {object} [bounds]
+ * @param {number} [bounds.from] - The lower bound, inclusive, as a canonical
+ *   year.
+ * @param {number} [bounds.to] - The upper bound, inclusive, as a canonical
+ *   year.
+ * @returns {object[]} Occurrence records, in increasing order.
+ */
+export function occurrencesOf(date, recurs, { from, to } = {}) {
+    if (!date?.known || !Number.isSafeInteger(date.canonicalYear)) return [];
+    const anchor = date.canonicalYear;
+
+    if (Array.isArray(recurs?.on)) {
+        if (from === undefined && to === undefined) return [date];
+        const series = [date, ...recurs.on]
+            .filter((occ) => occ?.known && Number.isSafeInteger(occ.canonicalYear))
+            .sort((a, b) => a.canonicalYear - b.canonicalYear);
+        const inRange = series.filter(
+            (occ) =>
+                (from === undefined || occ.canonicalYear >= from) &&
+                (to === undefined || occ.canonicalYear <= to),
+        );
+        if (from === undefined) return inRange.slice(-1);
+        if (to === undefined) return inRange.slice(0, 1);
+        return inRange;
+    }
+
+    const every = recurs?.every;
+    if (!Number.isSafeInteger(every) || every < 1) {
+        const solo = (from === undefined || anchor >= from) && (to === undefined || anchor <= to);
+        return solo ? [date] : [];
+    }
+
+    const lowestK = from === undefined ? 0 : Math.max(0, Math.ceil((from - anchor) / every));
+    if (to === undefined) return [{ ...date, canonicalYear: anchor + lowestK * every }];
+
+    const highestK = Math.floor((to - anchor) / every);
+    if (highestK < lowestK) return [];
+    if (from === undefined) return [{ ...date, canonicalYear: anchor + highestK * every }];
+
+    const out = [];
+    for (let k = lowestK; k <= highestK; k += 1)
+        out.push({ ...date, canonicalYear: anchor + k * every });
+    return out;
+}
+
+/** A resolved date's printed form, in the era its own value selects. */
+function withMarkerProse(date, context) {
+    const era =
+        date.marker ? context?.markers?.get(date.marker)
+        : date.qualifier ? context?.eras?.get(date.qualifier)
+        : null;
+    const printable = formatNoteDate(date, era, context?.daysPerYear);
+    return { ...date, prose: printable?.prose ?? null };
+}
+
+/**
+ * A resolved date's printed form, re-selecting the era that covers its own
+ * position rather than keeping whatever era its anchor was authored in.
+ *
+ * `when`/`until`/`on` are checked exactly as `born`/`died` are: an
+ * era-qualified value carries a `marker` or a `qualifier`, which names the
+ * calendar as well as the era, and a bare canonical value carries neither and
+ * prints bare. What is new here is that a *generated* occurrence keeps the
+ * anchor's marker or qualifier — advancing the year only — so that calendar's
+ * **whole** era list is swept through {@link eraCovering} for the
+ * occurrence's own position, rather than assuming it stays in the era the
+ * anchor was in. A later occurrence may therefore print in a different era
+ * than its anchor, or print bare where no count was proclaimed for that year;
+ * neither is a finding, since nobody authored the occurrence.
+ *
+ * @param {object} date - The resolved date, generated or authored.
+ * @param {object} [context] - As {@link resolvedDateFields} reads it.
+ * @returns {object} The date, carrying `prose`.
+ */
+function withSweptEraProse(date, context, { generated = false } = {}) {
+    if (!date?.known) return { ...date, prose: null };
+    const anchorEra =
+        date.marker ? context?.markers?.get(date.marker)
+        : date.qualifier ? context?.eras?.get(date.qualifier)
+        : null;
+    let era = null;
+    if (anchorEra?.calendarShortcode) {
+        try {
+            const calendarRows = calendarEras(anchorEra.calendarShortcode, context);
+            era = eraCovering(date, calendarRows, context?.daysPerYear);
+        } catch {
+            // Ambiguous or overlapping eras are a corpus defect reported
+            // where the eras themselves are declared; an occurrence prints
+            // bare rather than failing a build over a note that authored
+            // nothing wrong.
+            era = null;
+        }
+    }
+    const printable = formatNoteDate(date, era, context?.daysPerYear);
+    return {
+        ...date,
+        prose: printable?.prose ?? null,
+        // `formatNoteDate`'s own bare `text` echoes `date.text` — the
+        // anchor's authored spelling, which a *generated* occurrence has
+        // outgrown. Only a generated occurrence with no era to print in
+        // needs a text of its own, built from its own canonical year.
+        ...(generated && !era ?
+            {
+                text:
+                    (date.approximate ? "~" : "") +
+                    (date.precision === "day" && Number.isSafeInteger(date.canonicalDay) ?
+                        `${eraYear(date.canonicalYear)}.${date.canonicalDay}`
+                    :   String(eraYear(date.canonicalYear))),
+            }
+        :   {}),
+    };
+}
+
+/** The package's declared present, resolved to a date record, or `null`. */
+function resolvedPresent(context) {
+    if (context?.present === undefined || context?.present === null) return null;
+    const date = parseNoteDate(context.present, { ...context, allowUnknown: false }).date;
+    return date?.known ? date : null;
+}
+
+/**
+ * One `data.events` entry, resolved: its own `when`, `until`, `recurs` and
+ * `next`.
+ *
+ * `recurs.first` and `recurs.last` are canonical years rather than the
+ * fractional `sort` a day-precision date carries, because `every` counts
+ * whole years — a SQL fence testing membership with
+ * `(year - recurs.first) % recurs.every = 0 AND year >= recurs.first` reads
+ * them as the plain integers they are.
+ *
+ * @param {unknown} entry - The authored `{ when, until?, recurs? }`.
+ * @param {object} [context] - As {@link resolvedDateFields} reads it.
+ * @returns {object} The resolved entry; a key is present only where the note
+ *   authored or the build computed something for it.
+ */
+function resolveEventEntry(entry, context) {
+    const row = entry && typeof entry === "object" && !Array.isArray(entry) ? entry : {};
+    const out = {};
+
+    const when = parseNoteDate(row.when, {
+        ...context,
+        allowUnknown: true,
+        allowZeroYear: true,
+    }).date;
+    if (when?.known) out.when = withSweptEraProse(when, context);
+
+    const until = parseNoteDate(row.until, { ...context, allowUnknown: false }).date;
+    if (until?.known) out.until = withSweptEraProse(until, context);
+
+    if (!when?.known) return out;
+
+    // Year 0: an annual day-of-year marker, recurring by construction. Its
+    // own next occurrence is computed directly from the day of year rather
+    // than through `occurrencesOf`, which needs a real anchor year — and it
+    // carries no `recurs` record, since the entry is already annual.
+    if (when.year === 0) {
+        const present = resolvedPresent(context);
+        if (present && Number.isSafeInteger(when.canonicalDay)) {
+            const dueThisYear =
+                !Number.isSafeInteger(present.canonicalDay) ||
+                present.canonicalDay <= when.canonicalDay;
+            const year = dueThisYear ? present.canonicalYear : present.canonicalYear + 1;
+            if (!out.until || year <= out.until.canonicalYear) {
+                out.next = withSweptEraProse({ ...when, canonicalYear: year }, context, {
+                    generated: true,
+                });
+            }
+        }
+        return out;
+    }
+
+    const recurs = row.recurs;
+    if (!recurs || typeof recurs !== "object" || Array.isArray(recurs)) return out;
+
+    const recursOut = {};
+    let series;
+    // An enumeration is bounded by construction — its own last entry — so
+    // `last` is never null for `on`; a period is live unless `until` bounds
+    // it, so `last` is null exactly where there is no `until` to bound it.
+    if (Number.isInteger(recurs.every) && recurs.every >= 1) {
+        recursOut.every = recurs.every;
+        series = { every: recurs.every };
+        recursOut.last =
+            out.until ?
+                (occurrencesOf(when, series, { to: out.until.canonicalYear }).at(-1)
+                    ?.canonicalYear ?? null)
+            :   null;
+    } else if (Array.isArray(recurs.on)) {
+        const onDates = recurs.on
+            .map((raw) => parseNoteDate(raw, { ...context, allowUnknown: false }).date)
+            .filter((parsedOn) => parsedOn?.known);
+        recursOut.on = onDates.map((onDate) => withSweptEraProse(onDate, context));
+        series = { on: onDates };
+        recursOut.last =
+            onDates.length ? onDates[onDates.length - 1].canonicalYear : when.canonicalYear;
+    } else {
+        return out;
+    }
+
+    recursOut.first = when.canonicalYear;
+    out.recurs = recursOut;
+
+    const present = resolvedPresent(context);
+    if (present?.known) {
+        const candidate = occurrencesOf(when, series, { from: present.canonicalYear })[0];
+        if (candidate && (!out.until || candidate.canonicalYear <= out.until.canonicalYear)) {
+            out.next = withSweptEraProse(candidate, context, { generated: true });
+        }
+    }
+    return out;
+}
+
 /** 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));
+        return resolved.length ? { events: resolved } : {};
+    }
     const fields =
         fm?.type === "being" ?
             [
                 ["born", fm.data?.born],
                 ["died", fm.data?.died],
             ]
-        : fm?.type === "lore" ?
-            [
-                ["when", fm.data?.event?.when],
-                ["until", fm.data?.event?.until],
-            ]
         :   [];
     const out = {};
     for (const [key, value] of fields) {
@@ -628,12 +975,7 @@ export function resolvedDateFields(fm, context) {
             allowUnknown: key === "born" || key === "died",
         });
         if (parsed.date && !parsed.findings.some((finding) => finding.severity === "error")) {
-            const era =
-                parsed.date.marker ? context?.markers?.get(parsed.date.marker)
-                : parsed.date.qualifier ? context?.eras?.get(parsed.date.qualifier)
-                : null;
-            const printable = formatNoteDate(parsed.date, era, context?.daysPerYear);
-            out[key] = { ...parsed.date, prose: printable?.prose ?? null };
+            out[key] = withMarkerProse(parsed.date, context);
         }
     }
     return out;

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"]);