@heroiclands/package-build 22.14.4 → 22.15.0

package/engine/calendar-artifacts.mjs

@@ -0,0 +1,153 @@
+/*
+ * 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>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/** Build the calendar files a content package ships to Foundry. */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { calendariaEnvelope, compileCalendars } from "./calendar-notes.mjs";
+import { formatDiagnostic, positionOfFrontmatterPath } from "./diagnostics.mjs";
+import { authoredFrontmatter, isNoteRecord, noteFile } from "./index-records.mjs";
+import { metadataFileName } from "./packages.mjs";
+
+// The import envelope requires an ISO instant. A fixed value keeps an export
+// reproducible from its source rather than stamping the build machine's clock.
+const EXPORT_EPOCH = "1970-01-01T00:00:00.000Z";
+
+/** @param {string} file @param {string} message @param {string} raw @param {string[]} keyPath */
+function failAt(file, message, raw, keyPath) {
+    const position = positionOfFrontmatterPath(raw, keyPath, { key: true });
+    const error = new Error(formatDiagnostic({ file, ...position, severity: "error", message }));
+    error.located = true;
+    throw error;
+}
+
+/** @param {string} file */
+function readIndex(file) {
+    const display = path.relative(process.cwd(), file) || file;
+    if (!fs.existsSync(file)) {
+        const error = new Error(
+            `${display}: error: content index is absent; run content-build content-index`,
+        );
+        error.located = true;
+        throw error;
+    }
+    const records = fs
+        .readFileSync(file, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line, index) => {
+            try {
+                return JSON.parse(line);
+            } catch (cause) {
+                const error = new Error(
+                    `${display}:${index + 1}: error: invalid content index record`,
+                    {
+                        cause,
+                    },
+                );
+                error.located = true;
+                throw error;
+            }
+        });
+    if (!records.some(isNoteRecord)) {
+        const error = new Error(`${display}: error: content index contains no notes`);
+        error.located = true;
+        throw error;
+    }
+    return records;
+}
+
+/**
+ * Emit calendar definitions and import envelopes from the package's index.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - Resolved content configuration.
+ * @param {string} opts.calendariaVersion - Version whose import format is targeted.
+ * @returns {{directory: string, calendars: number, files: number}}
+ */
+export function emitCalendarArtifacts({ config, calendariaVersion } = {}) {
+    if (!config) throw new Error("calendar emission requires a content configuration");
+    if (!/^\d+\.\d+\.\d+$/.test(calendariaVersion ?? "")) {
+        throw new Error("calendar emission requires a Calendaria version such as 1.4.2");
+    }
+
+    const root = config.rootDir;
+    const contentBase = path.resolve(root, config.paths.content);
+    const indexFile = path.resolve(
+        root,
+        config.paths.contentIndex,
+        metadataFileName(config.contentPackage),
+    );
+    const directory = path.resolve(root, "build/calendars");
+    const notes = readIndex(indexFile)
+        .filter(isNoteRecord)
+        .map((record) => ({
+            fm: authoredFrontmatter(record),
+            file: path.relative(root, noteFile(contentBase, record)),
+            rel: record.file.path,
+        }));
+    const calendars = notes.filter(
+        (note) =>
+            String(note.fm.type).toLowerCase() === "lore" &&
+            String(note.fm.subType).toLowerCase() === "calendar",
+    );
+    const names = new Map();
+    for (const note of calendars) {
+        const raw = fs.readFileSync(path.resolve(root, note.file), "utf8");
+        const shortcode = note.fm.shortcode;
+        if (typeof shortcode !== "string" || !/^[a-z0-9]+$/.test(shortcode)) {
+            failAt(
+                note.file,
+                "calendar shortcode must contain lowercase ASCII letters and digits",
+                raw,
+                ["shortcode"],
+            );
+        }
+        if (names.has(shortcode)) {
+            failAt(
+                note.file,
+                `calendar shortcode ${shortcode} also occurs in ${names.get(shortcode)}`,
+                raw,
+                ["shortcode"],
+            );
+        }
+        names.set(shortcode, note.file);
+    }
+
+    const compiled = compileCalendars({ notes }, { contentPackage: config.contentPackage });
+    if (compiled.calendars.length !== calendars.length) {
+        const note = calendars[0];
+        failAt(
+            note.file,
+            "calendar notes require a world note declaring data.year",
+            fs.readFileSync(path.resolve(root, note.file), "utf8"),
+            ["subType"],
+        );
+    }
+    const outputs = [];
+    for (let index = 0; index < calendars.length; index++) {
+        const shortcode = calendars[index].fm.shortcode;
+        const definition = compiled.calendars[index];
+        outputs.push([`${shortcode}.json`, definition]);
+        outputs.push([
+            `${shortcode}.calendaria.json`,
+            calendariaEnvelope(definition, {
+                version: calendariaVersion,
+                exportedAt: EXPORT_EPOCH,
+            }),
+        ]);
+    }
+
+    fs.rmSync(directory, { recursive: true, force: true });
+    fs.mkdirSync(directory, { recursive: true });
+    for (const [name, value] of outputs) {
+        fs.writeFileSync(path.join(directory, name), `${JSON.stringify(value, null, 2)}\n`);
+    }
+    return { directory, calendars: calendars.length, files: outputs.length };
+}

package/engine/calendar-notes.mjs

@@ -64,9 +64,10 @@
  * @module
  */
 
-import { dayOfYear, daysInYear } from "./calendars.mjs";
+import { dayOfYear, daysInYear, monthDayOfYear } from "./calendars.mjs";
 import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
 
 /** The `lore` subType whose notes are calendars. */
 export const CALENDAR_SUBTYPE = "calendar";
@@ -144,11 +145,10 @@ export const CALENDAR_FIELDS = Object.freeze([
     },
     {
         name: "eras",
-        shape: "list of `{ shortcode, name, abbreviation?, proclaimedBy?, start, end? }`",
+        shape: "list of `{ shortcode, name, marker?, abbreviation?, proclaimedBy?, start, end? }`",
         kind: "list",
         describe:
-            "The year-counts kept in this calendar. A date names one by writing " +
-            "`<calendar shortcode>.<era shortcode>`.",
+            "The year-counts kept in this calendar. A marker names one era and uses these months.",
     },
     {
         name: "dateFormats",
@@ -456,6 +456,7 @@ export function checkWorldFacts(note, { index } = {}) {
 
     if (written.includes("present")) {
         const { findings: dated } = parseNoteDate(dataOf(note).present, {
+            ...reckoningContext(index),
             field: "data.present",
             allowUnknown: false,
             file: note.file,
@@ -464,6 +465,18 @@ export function checkWorldFacts(note, { index } = {}) {
         });
         findings.push(...dated);
     }
+    if (written.includes("moon") && dataOf(note).moon?.newOn !== undefined) {
+        findings.push(
+            ...parseNoteDate(dataOf(note).moon.newOn, {
+                ...reckoningContext(index),
+                field: "data.moon.newOn",
+                allowUnknown: false,
+                file: note.file,
+                raw: note.raw,
+                keyPath: ["data", "moon", "newOn"],
+            }).findings,
+        );
+    }
 
     // The corpus questions, which need every note and so are asked only where
     // the caller handed one over.
@@ -558,8 +571,24 @@ export function checkCalendarNote(note, { index } = {}) {
         });
     }
 
+    if (written.includes("epoch")) {
+        findings.push(
+            ...parseNoteDate(dataOf(note).epoch, {
+                ...reckoningContext(index),
+                field: "data.epoch",
+                allowUnknown: false,
+                file: note.file,
+                raw: note.raw,
+                keyPath: ["data", "epoch"],
+            }).findings,
+        );
+    }
+
     findings.push(...checkMonthSum(note, index));
     findings.push(...checkEraShortcodes(note));
+    findings.push(
+        ...reckoningContext(index).findings.filter((finding) => finding.file === note.file),
+    );
     findings.push(...checkCalendarDateFormats(note));
     return findings;
 }
@@ -718,16 +747,18 @@ function seasonValues(seasons) {
 }
 
 /** The era rows, keyed by shortcode, with the addressing segments dropped. */
-function eraEntries(eras) {
+function eraEntries(eras, dateContext = {}) {
     const entries = {};
     for (const era of Array.isArray(eras) ? eras : []) {
         const shortcode = String(era?.shortcode ?? "");
         if (!shortcode) continue;
+        const start = parseNoteDate(era?.start, { ...dateContext, allowUnknown: false }).date;
+        const end = parseNoteDate(era?.end, { ...dateContext, allowUnknown: false }).date;
         entries[shortcode] = written({
             name: String(era?.name ?? ""),
             abbreviation: era?.abbreviation === undefined ? undefined : String(era.abbreviation),
-            start: era?.start === undefined ? undefined : String(era.start),
-            end: era?.end === undefined ? undefined : String(era.end),
+            start: era?.start === undefined ? undefined : String(start?.year ?? era.start),
+            end: era?.end === undefined ? undefined : String(end?.year ?? era.end),
         });
     }
     return entries;
@@ -746,15 +777,23 @@ function eraEntries(eras) {
  * @param {string} name - What the body is called.
  * @returns {object|null} The entry, keyed by the body's name, or `null`.
  */
-function moonEntries(moon, body, name) {
+function moonEntries(moon, body, name, months, dateContext = {}) {
     if (!moon || !name) return null;
-    const date = parseNoteDate(moon.newOn, { allowUnknown: false }).date;
+    const date = parseNoteDate(moon.newOn, { ...dateContext, allowUnknown: false }).date;
+    const calendarDay =
+        date?.canonicalDay && months.length ? monthDayOfYear(months, date.canonicalDay) : null;
     return {
         [name]: written({
             name,
             cycleLength: Number(moon.cycle),
             referenceDate:
-                date ? written({ year: date.year, month: date.month, day: date.day }) : undefined,
+                date ?
+                    written({
+                        year: date.canonicalYear ?? date.year,
+                        month: calendarDay?.month ?? date.month,
+                        day: calendarDay?.day ?? date.day,
+                    })
+                :   undefined,
             // A circular orbit is a cycle of exactly its length, every time.
             cycleVariance: String(body?.orbit ?? "") === "circular" ? 0 : undefined,
             phaseMode: "fixed",
@@ -781,15 +820,21 @@ function moonEntries(moon, body, name) {
  *   its own package.
  * @returns {object} The definition.
  */
-export function compileCalendar({ note, invariants, contentPackage }) {
+export function compileCalendar({ note, invariants, contentPackage, dateContext = {} }) {
     const data = dataOf(note);
     const year = invariants?.year ?? {};
     const months = Array.isArray(data.months) ? data.months : [];
-    const epoch = parseNoteDate(data.epoch, { allowUnknown: false }).date;
+    const epoch = parseNoteDate(data.epoch, { ...dateContext, allowUnknown: false }).date;
     const shortcode = String(note.fm?.shortcode ?? "");
     const name = String(note.fm?.name?.full ?? "");
     const description = String(note.fm?.description ?? "");
-    const moons = moonEntries(invariants?.moon, invariants?.body ?? null, invariants?.moonName);
+    const moons = moonEntries(
+        invariants?.moon,
+        invariants?.body ?? null,
+        invariants?.moonName,
+        months,
+        dateContext,
+    );
     const author = contentPackage ? String(contentPackage) : undefined;
 
     return written({
@@ -818,8 +863,10 @@ export function compileCalendar({ note, invariants, contentPackage }) {
         seasons: { values: seasonValues(data.seasons) },
         // How far into the year the world's zero falls. `1/1` is none.
         epochDayOffset:
-            epoch && months.length ? dayOfYear(months, epoch.month ?? 1, epoch.day ?? 1) - 1 : 0,
-        eras: eraEntries(data.eras),
+            epoch && months.length ?
+                (epoch.canonicalDay ?? dayOfYear(months, epoch.month ?? 1, epoch.day ?? 1)) - 1
+            :   0,
+        eras: eraEntries(data.eras, dateContext),
         dateFormats: data.dateFormats,
         moons: moons ?? undefined,
         metadata: written({
@@ -871,9 +918,10 @@ export function compileCalendars(index, { contentPackage } = {}) {
     const invariants = worldInvariants(index);
     if (!invariants.year) return { calendars: [], invariants };
     const calendars = [];
+    const dateContext = reckoningContext(index);
     for (const note of index?.notes ?? []) {
         if (typeOf(note) !== "lore" || subTypeOf(note) !== CALENDAR_SUBTYPE) continue;
-        calendars.push(compileCalendar({ note, invariants, contentPackage }));
+        calendars.push(compileCalendar({ note, invariants, contentPackage, dateContext }));
     }
     return { calendars, invariants };
 }

package/engine/calendars.mjs

@@ -126,6 +126,116 @@ export function dateSortKey(year, month, day) {
     return (year * 10000 + (month ?? 0) * 100 + (day ?? 0)) / 10000;
 }
 
+/**
+ * Days from an arbitrary canonical origin to a canonical year and day.
+ *
+ * Canonical years form a continuous integer line. Day one opens each year;
+ * calendar month divisions play no part in this count.
+ *
+ * @param {number} year - Canonical year.
+ * @param {number} day - Day of that year, starting at one.
+ * @param {number} originYear - Canonical year whose first day is offset zero.
+ * @param {number} daysPerYear - The world's authored year length.
+ * @returns {number} Signed whole-day offset.
+ */
+export function canonicalDayOffset(year, day, originYear, daysPerYear) {
+    if (
+        !Number.isSafeInteger(year) ||
+        !Number.isSafeInteger(originYear) ||
+        !Number.isSafeInteger(daysPerYear) ||
+        daysPerYear < 1 ||
+        !Number.isSafeInteger(day) ||
+        day < 1 ||
+        day > daysPerYear
+    ) {
+        throw new RangeError(
+            "a canonical date needs an integer year and a day in the world's year",
+        );
+    }
+    const offset = (year - originYear) * daysPerYear + day - 1;
+    if (!Number.isSafeInteger(offset))
+        throw new RangeError("canonical day offset exceeds integer range");
+    return offset;
+}
+
+/**
+ * The canonical year and day at a signed offset from an arbitrary origin.
+ * Flooring the division keeps the day within the year before the origin.
+ *
+ * @param {number} offset - Whole days from the origin.
+ * @param {number} originYear - Canonical year whose first day is offset zero.
+ * @param {number} daysPerYear - The world's authored year length.
+ * @returns {{year: number, day: number}} Canonical year and day.
+ */
+export function canonicalDateFromOffset(offset, originYear, daysPerYear) {
+    if (
+        !Number.isSafeInteger(offset) ||
+        !Number.isSafeInteger(originYear) ||
+        !Number.isSafeInteger(daysPerYear) ||
+        daysPerYear < 1
+    ) {
+        throw new RangeError("a canonical offset needs integer days, origin year, and year length");
+    }
+    const years = Math.floor(offset / daysPerYear);
+    const year = originYear + years;
+    if (!Number.isSafeInteger(year)) throw new RangeError("canonical year exceeds integer range");
+    return { year, day: offset - years * daysPerYear + 1 };
+}
+
+/**
+ * Print a calendar-neutral date as `<year>.<day>[:HHMMSS]`.
+ *
+ * @param {{year: number, day: number, seconds?: number}} date - Canonical date.
+ * @param {number} daysPerYear - The world's authored year length.
+ * @returns {string} The canonical spelling.
+ */
+export function formatCanonicalDate(date, daysPerYear) {
+    canonicalDayOffset(date?.year, date?.day, date?.year, daysPerYear);
+    if (date.seconds === undefined) return `${date.year}.${date.day}`;
+    if (!Number.isSafeInteger(date.seconds) || date.seconds < 0 || date.seconds >= 86400) {
+        throw new RangeError("canonical time is a whole second within one day");
+    }
+    const hour = String(Math.floor(date.seconds / 3600)).padStart(2, "0");
+    const minute = String(Math.floor((date.seconds % 3600) / 60)).padStart(2, "0");
+    const second = String(date.seconds % 60).padStart(2, "0");
+    return `${date.year}.${date.day}:${hour}${minute}${second}`;
+}
+
+/**
+ * Read the calendar-neutral `<year>.<day>[:HHMMSS]` spelling.
+ *
+ * This is distinct from an authored month date such as `720/6`; no calendar
+ * month list is consulted to read a canonical day of year.
+ *
+ * @param {unknown} value - Canonical date text.
+ * @param {number} daysPerYear - The world's authored year length.
+ * @returns {{year: number, day: number, seconds?: number}|null} The date, or
+ *   `null` when the spelling or a component is invalid.
+ */
+export function parseCanonicalDate(value, daysPerYear) {
+    if (typeof value !== "string") return null;
+    const match = /^(-?\d+)\.(\d+)(?::(\d{2})(\d{2})(\d{2}))?$/.exec(value);
+    if (!match) return null;
+    const year = Number(match[1]);
+    const day = Number(match[2]);
+    if (
+        !Number.isSafeInteger(year) ||
+        !Number.isSafeInteger(day) ||
+        !Number.isSafeInteger(daysPerYear) ||
+        daysPerYear < 1 ||
+        day < 1 ||
+        day > daysPerYear
+    ) {
+        return null;
+    }
+    if (match[3] === undefined) return { year, day };
+    const hour = Number(match[3]);
+    const minute = Number(match[4]);
+    const second = Number(match[5]);
+    if (hour > 23 || minute > 59 || second > 59) return null;
+    return { year, day, seconds: hour * 3600 + minute * 60 + second };
+}
+
 /**
  * One month of a calendar, as the note declares it.
  *
@@ -213,6 +323,25 @@ export function dayOfYear(months, month, day) {
     return monthStarts(months)[month - 1] + day - 1;
 }
 
+/**
+ * Recover a calendar's month and day from an ordinal day of its year.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @param {number} ordinal - Day of year, starting at one.
+ * @returns {{month: number, day: number}|null} The named day, or `null` outside the year.
+ */
+export function monthDayOfYear(months, ordinal) {
+    if (!Number.isSafeInteger(ordinal) || ordinal < 1) return null;
+    let remaining = ordinal;
+    for (let position = 0; position < months.length; position++) {
+        const length = Number(months[position]?.days);
+        if (!Number.isSafeInteger(length) || length < 1) return null;
+        if (remaining <= length) return { month: position + 1, day: remaining };
+        remaining -= length;
+    }
+    return null;
+}
+
 /**
  * How far into its cycle a moon is on a given day.
  *

package/engine/content-index.mjs

@@ -151,6 +151,7 @@ import { isDraftNote } from "./note-vocabulary.mjs";
 // an unknown one — filled in against the package's own declared present before
 // a record is built, so the index carries it without the note being written to.
 import { applyComputedBeingAge, presentAmongFrontmatters } from "./being-age.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
 
 export {
     authoredFrontmatter,
@@ -692,10 +693,11 @@ export function collectContentIndex(
     // this same walk states one — the whole tree is already in memory, so no
     // second read is needed to answer a question about all of it.
     const present = presentAmongFrontmatters(notes.map((n) => n.frontmatter));
+    const dates = reckoningContext({ notes: notes.map((n) => n.frontmatter) });
 
     for (const { frontmatter, body, bodyLine, absPath } of notes) {
         const fm = frontmatter ?? {};
-        applyComputedBeingAge(fm, present);
+        applyComputedBeingAge(fm, present, dates);
         const relPath = path.relative(contentBase, absPath);
         try {
             records.push(