@heroiclands/package-build 22.15.1 → 22.16.0

package/engine/note-dates.mjs

@@ -15,21 +15,19 @@
  * Parse authored note dates into records used by content checks and renderers.
  *
  * A neutral day is `<year>.<day>[:HHMMSS]`, where `day` is an ordinal within
- * the world's year. A marked date is `<marker>(<year>[/<month>[/<day>]])`.
- * The marker selects one era and its calendar's ordered month list; the era's
- * start places its year one on the neutral timeline. A bare year is year
- * precision, and `unknown` is unordered. The parser also accepts unmarked
- * slash dates and addressed era qualifiers.
+ * the world's year. A named date is `datefrom <calendar> <date>`; its calendar
+ * and era resolve the value on the neutral timeline. Either form accepts a
+ * leading `~` for approximation. `unknown` is unordered.
  *
  * `text` keeps the authored spelling. `canonicalYear` and `sort` are set for
- * neutral and resolved marked dates. A marked date also carries
- * `canonicalDay`, the ordinal day within its neutral year. An addressed era
- * qualifier carries no resolved year until a caller supplies its era facts.
+ * neutral and resolved named dates. Resolved dates also carry `canonicalDay`,
+ * the ordinal day within the neutral year.
  *
  * @module
  */
 
 import { ADDRESS_SEGMENT_PATTERN } from "./address-charset.mjs";
+import { addressedCalendarDate } from "./calendar-human.mjs";
 import {
     calendarStructure,
     canonicalDateFromOffset,
@@ -38,6 +36,8 @@ import {
     dateSortKey,
     dayOfYear,
     daysInMonth,
+    eraYear,
+    monthDayOfYear,
     parseCanonicalDate,
 } from "./calendars.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
@@ -78,9 +78,12 @@ export const ERA_QUALIFIER_PATTERN = new RegExp(`^${ERA}$`);
  * @type {RegExp}
  */
 export const NOTE_DATE_PATTERN = new RegExp(
-    `^(~)?\\s*(-?\\d+)(?:/(\\d+)(?:/(\\d+))?)?(?:\\s+(${ERA}))?$`,
+    `^(~)?\\s*(-?\\d+)(?:/(\\d+)(?:/(\\d+)(?::(\\d{6}))?)?)?(?:\\s+(${ERA}))?$`,
 );
 
+/** A calendar conversion written as a frontmatter date value. */
+export const DATEFROM_PATTERN = /^datefrom\s+(\S+)\s+(.+)$/;
+
 /** A day written with no month — ungrammatical, and worth its own sentence. */
 const DAY_WITHOUT_MONTH_PATTERN = /^(?:~)?\s*-?\d+\/\/\d+(?:\s+\S+)?$/;
 
@@ -129,8 +132,12 @@ function unknownRecord() {
  *   the month it names. A calendar that declares no list bounds nothing.
  * @param {Map<string, object>} [options.markers] - Resolved era markers from
  *   the corpus, each carrying its calendar and canonical start.
+ * @param {Map<string, object>} [options.eras] - Resolved calendar eras, keyed
+ *   by their addressed qualifier.
+ * @param {boolean} [options.ignoreEraBounds=false] - Parse a calendar row's
+ *   own boundary in a referenced era without applying that era's note span.
  * @param {number} [options.daysPerYear] - The world's year length, required for
- *   canonical days and marked dates.
+ *   canonical days and named dates.
  * @param {string} [options.field] - The key that carried it, named in every
  *   message. Omitted, a message names the value alone.
  * @param {boolean} [options.allowUnknown=true] - Whether `"unknown"` is a
@@ -147,6 +154,8 @@ export function parseNoteDate(value, options) {
     const {
         calendar,
         markers,
+        eras,
+        ignoreEraBounds = false,
         daysPerYear,
         field,
         allowUnknown = true,
@@ -178,71 +187,109 @@ export function parseNoteDate(value, options) {
         return { date: null, findings };
     };
 
-    if (text.trim() === UNKNOWN_DATE) {
-        if (allowUnknown) return { date: unknownRecord(), findings };
-        return refuse(
-            `${subject} — \`${UNKNOWN_DATE}\` records that something happened and ` +
-                `the date is not known, which only a field whose absence means it ` +
-                `never happened has any use for. \`${field ?? "this field"}\` is not ` +
-                `one, so leave it out instead`,
-        );
-    }
-
-    const trimmed = text.trim();
-    const marked = /^([A-Z][A-Z0-9]*)\((.*)\)$/.exec(trimmed);
-    if (marked) {
-        const [, marker, payload] = marked;
-        const reckoning = markers?.get(marker);
-        if (!reckoning) return refuse(`${subject} names unknown reckoning marker ${marker}`);
+    const resolveEra = (parsed, reckoning, label) => {
+        if (!ignoreEraBounds && parsed.year < 0 && reckoning.firstEra === false)
+            return refuse(
+                `${subject} counts backward from ${label}, but only the first era of a calendar may do so`,
+            );
         if (!Number.isSafeInteger(daysPerYear) || daysPerYear < 1)
-            return refuse(`${subject} needs the world's year length to resolve ${marker}`);
-        const parsed = parseNoteDate(payload, {
-            calendar: reckoning.calendar,
-            field,
-            allowUnknown: false,
-            file,
-            raw,
-            keyPath,
-        });
-        if (parsed.findings.some((finding) => finding.severity === "error") || !parsed.date)
-            return { date: null, findings: parsed.findings };
-        if (!parsed.date.known)
-            return refuse(`${subject} wraps an unknown date; write \`unknown\` by itself`);
-        if (parsed.date.era !== null)
+            return refuse(`${subject} needs the world's year length to resolve ${label}`);
+        const { months } = calendarStructure(reckoning.calendar);
+        if (!months) return refuse(`${subject} names ${label}, whose calendar declares no months`);
+        if (parsed.month !== null && parsed.month > months.length)
             return refuse(
-                `${subject} names two reckonings; the payload of ${marker} is a calendar date`,
+                `${subject} writes month ${parsed.month}, and ${label} keeps ${months.length} months`,
             );
-        if (parsed.date.canonicalDay !== undefined)
+        const length = parsed.month === null ? null : daysInMonth(reckoning.calendar, parsed.month);
+        if (parsed.day !== null && length !== null && parsed.day > length)
             return refuse(
-                `${subject} puts a canonical day inside ${marker}; write its calendar month and day`,
+                `${subject} writes day ${parsed.day}, and month ${parsed.month} is ${length} days long`,
             );
-        const { months } = calendarStructure(reckoning.calendar);
-        if (!months) return refuse(`${subject} names ${marker}, whose calendar declares no months`);
-        const ordinal = dayOfYear(months, parsed.date.month ?? 1, parsed.date.day ?? 1);
+        const ordinal = dayOfYear(months, parsed.month ?? 1, parsed.day ?? 1);
         const start = canonicalDayOffset(reckoning.epochYear, reckoning.epochDay, 1, daysPerYear);
-        const yearOffset = parsed.date.year > 0 ? parsed.date.year - 1 : parsed.date.year;
+        const yearOffset = parsed.year > 0 ? parsed.year - 1 : parsed.year;
         const offset = start + yearOffset * daysPerYear + ordinal - 1;
         if (!Number.isSafeInteger(offset))
             return refuse(`${subject} lies outside the supported canonical day range`);
-        if (reckoning.endOffset !== undefined && offset > reckoning.endOffset)
-            return refuse(`${subject} lies after the end of reckoning marker ${marker}`);
+        const spanDays =
+            parsed.precision === "year" ? daysPerYear
+            : parsed.precision === "month" ? length
+            : 1;
+        if (
+            !ignoreEraBounds &&
+            reckoning.endOffset !== undefined &&
+            offset + spanDays - 1 > reckoning.endOffset
+        )
+            return refuse(`${subject} lies after the end of ${label}`);
         const canonical = canonicalDateFromOffset(offset, 1, daysPerYear);
         return {
             date: {
-                ...parsed.date,
+                ...parsed,
                 text,
                 era: reckoning.era,
-                marker,
+                qualifier: reckoning.qualifier,
                 canonicalYear: canonical.year,
                 canonicalDay: canonical.day,
-                sort: canonical.year + (canonical.day - 1) / daysPerYear,
+                spanDays,
+                sort:
+                    canonical.year +
+                    (canonical.day - 1 + (parsed.seconds ?? 0) / 86400) / daysPerYear,
             },
-            findings: parsed.findings,
+            findings,
         };
+    };
+
+    if (text.trim() === UNKNOWN_DATE) {
+        if (allowUnknown) return { date: unknownRecord(), findings };
+        return refuse(
+            `${subject} — \`${UNKNOWN_DATE}\` records that something happened and ` +
+                `the date is not known, which only a field whose absence means it ` +
+                `never happened has any use for. \`${field ?? "this field"}\` is not ` +
+                `one, so leave it out instead`,
+        );
     }
 
-    if (trimmed.includes(".")) {
-        const canonical = parseCanonicalDate(trimmed, daysPerYear);
+    const trimmed = text.trim();
+    const approximateInput = trimmed.startsWith("~");
+    const unmarked = approximateInput ? trimmed.slice(1).trim() : trimmed;
+    const conversion = DATEFROM_PATTERN.exec(unmarked);
+    if (conversion) {
+        try {
+            const [, reference, human] = conversion;
+            const addressed = addressedCalendarDate(
+                human.trim(),
+                calendarEras(reference, { eras }),
+            );
+            if (!addressed) return refuse(`${subject} needs a named calendar date`);
+            const parsed = parseNoteDate(`${approximateInput ? "~" : ""}${addressed}`, {
+                markers,
+                eras,
+                daysPerYear,
+                ignoreEraBounds,
+                allowUnknown: false,
+                file,
+                raw,
+                keyPath,
+            });
+            if (!parsed.date || parsed.findings.some((item) => item.severity === "error"))
+                return parsed;
+            return { date: { ...parsed.date, text }, findings: parsed.findings };
+        } catch (err) {
+            return refuse(`${subject} cannot resolve its calendar date: ${err.message}`);
+        }
+    }
+    if (/^-?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`,
+        );
+    if (field && !/^-?\d+\.\d+(?::\d{6})?$/.test(unmarked))
+        return refuse(
+            `${subject} is not a frontmatter date — write ` +
+                "`<year>.<day>[:HHMMSS]` or `datefrom <calendar> <date>`",
+        );
+    if (unmarked.includes(".")) {
+        const canonical = parseCanonicalDate(unmarked, daysPerYear ?? Number.MAX_SAFE_INTEGER);
         if (canonical) {
             return {
                 date: {
@@ -252,14 +299,17 @@ export function parseNoteDate(value, options) {
                     year: canonical.year,
                     month: null,
                     day: canonical.day,
-                    approximate: false,
+                    approximate: approximateInput,
                     precision: "day",
                     canonicalYear: canonical.year,
                     canonicalDay: canonical.day,
+                    spanDays: 1,
                     ...(canonical.seconds === undefined ? {} : { seconds: canonical.seconds }),
                     sort:
-                        canonical.year +
-                        (canonical.day - 1 + (canonical.seconds ?? 0) / 86400) / daysPerYear,
+                        Number.isSafeInteger(daysPerYear) ?
+                            canonical.year +
+                            (canonical.day - 1 + (canonical.seconds ?? 0) / 86400) / daysPerYear
+                        :   null,
                 },
                 findings,
             };
@@ -299,15 +349,21 @@ export function parseNoteDate(value, options) {
         return refuse(
             `${subject} is not a date — write ` +
                 `\`<year>.<day>[:HHMMSS]\` or ` +
-                `\`<marker>(<year>[/<month>[/<day>]])\``,
+                `\`datefrom <calendar> <date>\``,
         );
     }
 
-    const [, tilde, yearText, monthText, dayText, era] = match;
+    const [, tilde, yearText, monthText, dayText, timeText, era] = match;
     const approximate = tilde === "~";
     const year = Number(yearText);
     const month = monthText === undefined ? null : Number(monthText);
     const day = dayText === undefined ? null : Number(dayText);
+    const seconds =
+        timeText === undefined ? undefined : (
+            Number(timeText.slice(0, 2)) * 3600 +
+            Number(timeText.slice(2, 4)) * 60 +
+            Number(timeText.slice(4, 6))
+        );
     if (
         !Number.isSafeInteger(year) ||
         (month !== null && !Number.isSafeInteger(month)) ||
@@ -325,6 +381,13 @@ export function parseNoteDate(value, options) {
                 `side of an epoch are -1 and 1`,
         );
     }
+    if (
+        timeText !== undefined &&
+        (Number(timeText.slice(0, 2)) > 23 ||
+            Number(timeText.slice(2, 4)) > 59 ||
+            Number(timeText.slice(4, 6)) > 59)
+    )
+        return refuse(`${subject} needs a 24-hour time in HHMMSS form`);
 
     const { months } = calendarStructure(calendar);
     if (month !== null && month < 1) {
@@ -376,15 +439,174 @@ export function parseNoteDate(value, options) {
         year,
         month,
         day,
+        ...(seconds === undefined ? {} : { seconds }),
         approximate,
         precision,
     };
     // A named era's epoch is a fact the corpus states, so the numbers derived
     // from it are written by the pass that resolves it and are absent until
     // then. A bare value is already on the axis.
+    if (era !== undefined && eras) {
+        const reckoning = eras.get(era);
+        if (reckoning?.ambiguous)
+            return refuse(
+                `${subject} names ambiguous calendar era ${era}; qualify its package and system`,
+            );
+        if (!reckoning) return refuse(`${subject} names unknown calendar era ${era}`);
+        return resolveEra(date, reckoning, `calendar era ${era}`);
+    }
     if (era === undefined) {
         date.canonicalYear = canonicalYear(year);
-        date.sort = dateSortKey(date.canonicalYear, month, day);
+        if (precision === "year" && Number.isSafeInteger(daysPerYear)) date.spanDays = daysPerYear;
+        date.sort =
+            dateSortKey(date.canonicalYear, month, day) +
+            (seconds ?? 0) / 86400 / (daysPerYear ?? 1);
     }
     return { date, findings };
 }
+
+/** Select the single era covering the full precision of a resolved date. */
+export function eraCovering(date, eraRows, daysPerYear) {
+    if (
+        !date?.known ||
+        !Number.isSafeInteger(date.canonicalYear) ||
+        !Number.isSafeInteger(daysPerYear) ||
+        !Number.isSafeInteger(date.spanDays)
+    )
+        return null;
+    const start = canonicalDayOffset(date.canonicalYear, date.canonicalDay ?? 1, 1, daysPerYear);
+    const end = start + date.spanDays - 1;
+    const matches = [...new Set(eraRows ?? [])].filter(
+        (era) =>
+            Number.isSafeInteger(era?.startOffset) &&
+            (era.firstEra === true || era.startOffset <= start) &&
+            (era.endOffset === undefined || end <= era.endOffset),
+    );
+    if (matches.length > 1)
+        throw new RangeError(
+            `date is covered by overlapping eras ${matches.map((era) => era.era).join(", ")}`,
+        );
+    return matches[0] ?? null;
+}
+
+/** Resolve a calendar or one of its eras from an Address or shortcode. */
+export function calendarEras(reference, context) {
+    const name = String(reference ?? "");
+    const rows = [...new Set(context?.eras?.values() ?? [])].filter(
+        (era) => era && !era.ambiguous && era.era,
+    );
+    const explicit = context?.eras?.get(name);
+    if (explicit?.ambiguous) throw new RangeError(`calendar era ${name} is ambiguous`);
+    if (explicit?.era) return [explicit];
+    const calendars = new Map();
+    for (const era of rows) {
+        const full = era.qualifier.slice(0, -(era.era.split(".").at(-1).length + 1));
+        const short = era.calendarShortcode;
+        if ([full, short, `lore-${short}`, `note-lore-${short}`].includes(name)) {
+            const list = calendars.get(full) ?? [];
+            list.push(era);
+            calendars.set(full, list);
+        }
+    }
+    if (calendars.size === 0) throw new RangeError(`calendar ${name} does not resolve`);
+    if (calendars.size > 1)
+        throw new RangeError(`calendar ${name} is ambiguous; use its full Address`);
+    return [...calendars.values()][0];
+}
+
+/** Print a resolved date using the era active in one addressed calendar. */
+export function formatDateInCalendar(date, reference, context) {
+    const eras = calendarEras(reference, context);
+    const chosen = eraCovering(date, eras, context?.daysPerYear);
+    const name = String(reference ?? "");
+    if (context?.eras?.get(name)?.era && chosen === null)
+        throw new RangeError(`date falls outside calendar era ${name}`);
+    return formatNoteDate(date, chosen, context?.daysPerYear);
+}
+
+/** Print a resolved date in one era, retaining its authored precision. */
+export function formatNoteDate(date, era, daysPerYear) {
+    if (!date?.known || !Number.isSafeInteger(date.canonicalYear)) return null;
+    if (!era) return { era: null, year: eraYear(date.canonicalYear), text: date.text, prose: null };
+    if (!Number.isSafeInteger(daysPerYear) || !Number.isSafeInteger(date.spanDays)) return null;
+    const target = era;
+    const start = canonicalDayOffset(date.canonicalYear, date.canonicalDay ?? 1, 1, daysPerYear);
+    if (start < target.startOffset && target.firstEra !== true) return null;
+    if (target.endOffset !== undefined && start + date.spanDays - 1 > target.endOffset) return null;
+    const epoch =
+        target.startOffset ??
+        canonicalDayOffset(target.epochYear, target.epochDay ?? 1, 1, daysPerYear);
+    const delta = start - epoch;
+    const cycle = Math.floor(delta / daysPerYear);
+    const year = cycle >= 0 ? cycle + 1 : cycle;
+    if (Math.floor((delta + date.spanDays - 1) / daysPerYear) !== cycle) return null;
+
+    let month = null;
+    let day = null;
+    if (date.precision !== "year") {
+        const months = calendarStructure(target.calendar).months;
+        if (!months) return null;
+        const ordinal = (((delta % daysPerYear) + daysPerYear) % daysPerYear) + 1;
+        const named = monthDayOfYear(months, ordinal);
+        if (!named) return null;
+        month = named.month;
+        if (date.precision === "month") {
+            if (named.day !== 1 || date.spanDays !== daysInMonth(target.calendar, month))
+                return null;
+        } else day = named.day;
+    }
+    const clock =
+        date.seconds === undefined ?
+            ""
+        :   ` ${String(Math.floor(date.seconds / 3600)).padStart(2, "0")}:` +
+            `${String(Math.floor(date.seconds / 60) % 60).padStart(2, "0")}:` +
+            `${String(date.seconds % 60).padStart(2, "0")}`;
+    const monthName =
+        month === null ? null : calendarStructure(target.calendar).months?.[month - 1]?.name;
+    const eraName =
+        target.abbreviation || target.marker || target.name || target.era.split(".").at(-1);
+    const text = `${date.approximate ? "~" : ""}${day === null ? "" : `${day} `}${monthName ? `${monthName} ` : ""}${year} ${eraName}${clock}`;
+    const digits = `${Math.abs(year)}${month === null ? "" : `/${month}`}${day === null ? "" : `/${day}${clock.replaceAll(":", "").replace(/^ /, ":")}`}`;
+    const label =
+        typeof target.label === "string" ?
+            target.label
+        :   target.label?.[year < 0 ? "before" : "after"];
+    const prose =
+        typeof label === "string" && label.includes("{date}") ?
+            label.replace("{date}", `${date.approximate ? "~" : ""}${digits}`)
+        :   null;
+    return { era, year, month, day, text, prose };
+}
+
+/** Normalize a note's declared dates for indexes and generated pages. */
+export function resolvedDateFields(fm, context) {
+    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) {
+        if (value === undefined || value === null) continue;
+        const parsed = parseNoteDate(value, {
+            ...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 };
+        }
+    }
+    return out;
+}

package/engine/note-package.mjs

@@ -43,12 +43,8 @@
  * carries. There is no value that makes writing it correct, so the diagnostic
  * says what to write instead rather than which value to change.
  *
- * **One `package` survives, and it is synthesised.** A `dataview` table scopes
- * itself with `WHERE … and package = "<pkg>"`, and that clause resolves against
- * frontmatter like any other field. {@link searchableFrontmatter} supplies the
- * derived value to the search so the 45 authored clauses across `sohl` and
- * `thalorna` keep matching. It is a *search* value, never an authored one, and
- * it is never written back to a note.
+ * SQL queries can refer to the configured package. Search readers receive that
+ * derived value without adding a field to authored frontmatter.
  *
  * @module
  */
@@ -57,26 +53,10 @@ import { contentPackage } from "./content-package.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 
 /**
- * A note's frontmatter as a generated table searches it — its package present,
- * though no note declares one.
- *
- * A `dataview` query resolves `package` out of frontmatter like any other
- * field, so a collection note that scopes itself with `WHERE … and package =
- * "sohl"` would match nothing now that the field is gone, and would render an
- * **empty table** in silence. Supplying the derived value here is what kept the
- * sweep mechanical rather than a trap — and a query that never mentions
- * `package` is unaffected either way.
- *
- * The frontmatter is copied rather than written into: it is the note's own
- * parsed object, shared with every other reader, and the derived package is a
- * property of *this search*, not of the note.
- *
+ * A copy of frontmatter carrying the configured package for query evaluation.
  * @param {object|null|undefined} fm - Parsed frontmatter.
- * @param {string} [configured] - The package this build compiles. Defaults to
- *   the configured `contentPackage`; passed explicitly by callers that already
- *   carry it in a context object, so a caller's configuration drives every read.
- * @returns {object|null|undefined} A shallow copy carrying the derived package,
- *   or whatever was passed when it is not frontmatter at all.
+ * @param {string} [configured] - The package this build compiles.
+ * @returns {object|null|undefined} Frontmatter with a derived package value.
  */
 export function searchableFrontmatter(fm, configured) {
     if (!fm || typeof fm !== "object") return fm;

package/engine/note-state.mjs

@@ -225,7 +225,8 @@ export function placeholderBody(body) {
  *
  * Fence blocks, headings, thematic breaks and HTML comments are dropped, and a
  * wikilink counts as the one word it renders — `[[affiliation-meivor|Mëivōr]]`
- * is a word, not three. What is left is split on whitespace.
+ * is a word, not three. A dash, slash, or ellipsis between words separates
+ * them even without surrounding spaces.
  *
  * @param {string|null|undefined} body - The note body.
  * @returns {number} The word count.
@@ -238,5 +239,8 @@ export function bodyWordCount(body) {
         .split("\n")
         .filter((line) => !STRUCTURE_LINE.test(line.trim()))
         .join(" ");
-    return text.split(/\s+/).filter((word) => /[\p{L}\p{N}]/u.test(word)).length;
+    return text
+        .replace(/(?<=[\p{L}\p{N}])(?:[—–/…]|\.\.\.)(?=[\p{L}\p{N}])/gu, " ")
+        .split(/\s+/)
+        .filter((word) => /[\p{L}\p{N}]/u.test(word)).length;
 }