@heroiclands/package-build 22.7.0 → 22.9.0

package/engine/note-dates.mjs

@@ -0,0 +1,350 @@
+/*
+ * 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
+ */
+
+/**
+ * **A date on a note: one authored string, one grammar, one record.**
+ *
+ * ```text
+ * [~] [-] YYYY [/ MM [/ DD]] [ ERA ]
+ *
+ * ERA : (?:[a-z0-9]+-){0,3}[a-z0-9]+ . [a-z0-9]+
+ * ```
+ *
+ * - `~` — approximate. It marks the value and does not change what it parses
+ *   to, so a renderer can print `c. -2110` from the same number it sorts on.
+ *   It precedes the sign: `~-2500`, never `-~2500`.
+ * - `-` — before the epoch the year is counted from. There is no year zero, so
+ *   `-1` sits immediately before `1`.
+ * - `YYYY` — required.
+ * - `MM`, `DD` — optional, in that order.
+ * - `ERA` — a calendar's address plus `.<era shortcode>`, in the four address
+ *   forms {@link ERA_QUALIFIER_PATTERN} admits. Omitted, the date sits on the
+ *   canonical axis and is attributed to nobody.
+ *
+ * **Precision falls out of how much is written.** `-984` is a year, `689/6` a
+ * month, `689/6/19` a day. There is no precision vocabulary, so there is
+ * nothing to fall out of step with the value it describes.
+ *
+ * ## A trailing token is only ever an era
+ *
+ * It has exactly one shape and it always contains exactly one dot, so **a
+ * trailing token at all means the value needs the corpus, and no token means
+ * it is already on the axis** — which is readable off the string, before
+ * anything is resolved.
+ *
+ * ## The rule to copy: print `text`, order on `sort`, do arithmetic on `canonicalYear`
+ *
+ * Every parsed date carries all three, because neither the string nor the
+ * number is cheap to derive from the other at read time:
+ *
+ * ```yaml
+ * text: "689/6/19"   # authored, verbatim — what a page prints
+ * known: true        # what a query branches on
+ * era: null          # the reckoning named, or null for the canonical axis
+ * year: 689          # as authored, signed, within its own reckoning
+ * month: 6           # null where unwritten
+ * day: 19            # null where unwritten
+ * approximate: false # the `~`
+ * precision: day     # derived: day | month | year
+ * canonicalYear: 689 # signed — arithmetic
+ * sort: 689.0619     # total order across mixed precision — sorting
+ * ```
+ *
+ * `era` is `null` for a bare value and there is no substitute for it: the
+ * canonical axis is not a reckoning anybody keeps and has no address, so
+ * filling the field would state an identification that is not true.
+ *
+ * ## A number is written only where there is one to write
+ *
+ * A date naming an era carries the qualifier and **no `canonicalYear` and no
+ * `sort` keys at all** until the era is resolved against the corpus. They are
+ * absent rather than null, because a record carrying `known: true` beside a
+ * null year and a null sort is indistinguishable from the `unknown` record
+ * below — which is the one shape whose confusion is invisible in the output.
+ *
+ * ## `unknown` is a value, and it is unordered
+ *
+ * `"unknown"` says the thing happened and the date is not recorded. It parses
+ * to the same record with the year half empty — `known: false`, and **a null
+ * `canonicalYear` and a null `sort`**.
+ *
+ * Both shortcuts past that are silently wrong. Normalising it to `0` sorts the
+ * ancient dead into the year immediately before the epoch; treating it as a
+ * null year and letting a comparison default it sorts them into the present,
+ * beside the living. So anything that orders or filters on a date leaves an
+ * unknown one out of the ordering and reports it as its own group, and a range
+ * filter never matches it, because the record does not claim a year and a
+ * filter must not claim one for it.
+ *
+ * ## Absence is not a finding, and neither is a bare value
+ *
+ * An absent value is a fact about the subject rather than a gap, so parsing
+ * nothing yields nothing and reports nothing. A bare value is the canonical
+ * axis, always, and it is silent: an unattributed date is the honest form for
+ * a date an author is placing rather than a record somebody in the setting
+ * kept.
+ *
+ * @module
+ */
+
+import { ADDRESS_SEGMENT_PATTERN } from "./address-charset.mjs";
+import { calendarStructure, canonicalYear, dateSortKey, daysInMonth } from "./calendars.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/**
+ * The literal that says a thing happened and the date is not recorded.
+ *
+ * @type {string}
+ */
+export const UNKNOWN_DATE = "unknown";
+
+/**
+ * One address segment, read out of the charset addresses are already held to
+ * rather than restated — a second copy is one more thing to drift.
+ */
+const SEGMENT = ADDRESS_SEGMENT_PATTERN.source.replace(/^\^|\$$/g, "");
+
+/** The era qualifier's body, without anchors, for composing into the grammar. */
+const ERA = `(?:${SEGMENT}-){0,3}${SEGMENT}\\.${SEGMENT}`;
+
+/**
+ * What a date's trailing token may look like.
+ *
+ * A calendar note's address followed by `.<era shortcode>`. The `{0,3}`
+ * repetition is the four address forms exactly — bare `shortcode`,
+ * `type-shortcode`, `system-type-shortcode` and
+ * `package-system-type-shortcode` — so the hyphen separates an address's
+ * segments, the dot separates the address from the era, and the split needs no
+ * lookahead.
+ *
+ * @type {RegExp}
+ */
+export const ERA_QUALIFIER_PATTERN = new RegExp(`^${ERA}$`);
+
+/**
+ * The grammar, as one expression.
+ *
+ * @type {RegExp}
+ */
+export const NOTE_DATE_PATTERN = new RegExp(
+    `^(~)?\\s*(-?\\d+)(?:/(\\d+)(?:/(\\d+))?)?(?:\\s+(${ERA}))?$`,
+);
+
+/** A day written with no month — ungrammatical, and worth its own sentence. */
+const DAY_WITHOUT_MONTH_PATTERN = /^(?:~)?\s*-?\d+\/\/\d+(?:\s+\S+)?$/;
+
+/** A trailing token carrying a dot that the era grammar still refuses. */
+const MALFORMED_ERA_PATTERN = /^(?:~)?\s*-?\d+(?:\/\d+(?:\/\d+)?)?\s+\S*\.\S*$/;
+
+/** A trailing word with no dot, which names nothing now that an era is addressed. */
+const DOTLESS_TOKEN_PATTERN = /^(?:~)?\s*(-?\d+)((?:\/\d+(?:\/\d+)?)?)\s+[A-Za-z][A-Za-z0-9]*$/;
+
+/** The record an unknown date parses to — every field but `text` and `known` empty. */
+function unknownRecord() {
+    return {
+        text: UNKNOWN_DATE,
+        known: false,
+        era: null,
+        year: null,
+        month: null,
+        day: null,
+        approximate: false,
+        precision: null,
+        // Never 0 and never a defaulted null year: see the module docs.
+        canonicalYear: null,
+        sort: null,
+    };
+}
+
+/**
+ * Parse one authored date.
+ *
+ * Every field that holds a date — a birth, a death, an event's start and its
+ * end — parses through here, so there is one grammar to write, test, document
+ * and teach.
+ *
+ * Findings are returned rather than thrown, because a corpus pass wants every
+ * bad value in one run rather than the first. Each carries the `file` it was
+ * given and, where `raw` and `keyPath` locate the value, its line and column;
+ * a position that cannot be established honestly is dropped rather than
+ * defaulted, which is what keeps `file:line:column:` parseable.
+ *
+ * @param {unknown} value - The authored value. A number is what YAML hands
+ *   back for a bare year, so it is accepted and stringified.
+ * @param {object} [options]
+ * @param {{months?: readonly object[]|null}} [options.calendar] - The calendar
+ *   the value is written in, as its note declares it. Its ordered month list
+ *   bounds a written month and a written day, the day against the length of
+ *   the month it names. A calendar that declares no list bounds nothing.
+ * @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
+ *   permitted value here. It is not, in a field whose absence already says the
+ *   date is unrecorded.
+ * @param {string} [options.file] - The note, for the diagnostics.
+ * @param {string} [options.raw] - The note's full contents, to locate the value.
+ * @param {ReadonlyArray<string|number>} [options.keyPath] - Path to the key
+ *   within the frontmatter, for the same.
+ * @returns {{date: object|null, findings: object[]}} The record, or `null` when
+ *   the value is absent or refused, and every finding the value earned.
+ */
+export function parseNoteDate(value, options) {
+    const { calendar, field, allowUnknown = true, file, raw, keyPath } = options ?? {};
+    const findings = [];
+
+    // Absence is a fact about the subject, not a gap — nothing to parse and
+    // nothing to say about it.
+    if (value === null || value === undefined) return { date: null, findings };
+
+    const at = () => ({
+        ...(file === undefined ? {} : { file }),
+        ...(raw !== undefined && keyPath !== undefined ?
+            positionOfFrontmatterPath(raw, keyPath)
+        :   {}),
+    });
+    const authored = typeof value === "number" || typeof value === "string";
+    // A YAML scalar reaches here as a string or, for a bare year, as a number.
+    // Anything else is not a date, and the message shows what it was rather
+    // than an empty pair of backticks.
+    const text = authored ? String(value) : "";
+    const shown = authored ? text : JSON.stringify(value);
+    const subject = field ? `\`${field}: ${shown}\`` : `\`${shown}\``;
+    const refuse = (message) => {
+        findings.push({ ...at(), severity: "error", message });
+        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 match = NOTE_DATE_PATTERN.exec(trimmed);
+    if (!match) {
+        if (DAY_WITHOUT_MONTH_PATTERN.test(trimmed)) {
+            return refuse(
+                `${subject} writes a day with no month — a date is written to the ` +
+                    `year, to the month or to the day, and each level needs the one ` +
+                    `above it`,
+            );
+        }
+        if (MALFORMED_ERA_PATTERN.test(trimmed)) {
+            return refuse(
+                `${subject} — an era is written ` +
+                    `\`<calendar shortcode>.<era shortcode>\`, lowercase letters ` +
+                    `and digits only`,
+            );
+        }
+        if (DOTLESS_TOKEN_PATTERN.test(trimmed)) {
+            // The message an author who learned a retired spelling meets. No
+            // table says which direction that spelling counted, so it states
+            // the rule rather than guessing a concrete replacement.
+            return refuse(
+                `${subject} names no era — a reckoning is written ` +
+                    `\`<calendar shortcode>.<era shortcode>\`: a year before ` +
+                    `an era's epoch is written negative, and a year after it ` +
+                    `simply drops the token`,
+            );
+        }
+        return refuse(
+            `${subject} is not a date — write ` +
+                `\`[~][-]YYYY[/MM[/DD]] [<calendar shortcode>.<era shortcode>]\`: ` +
+                `a year, negative where it falls before the epoch it is counted ` +
+                `from, optionally a month and a day, and an era where the date is a ` +
+                `reckoning somebody kept`,
+        );
+    }
+
+    const [, tilde, yearText, monthText, dayText, era] = match;
+    const approximate = tilde === "~";
+    const year = Number(yearText);
+    const month = monthText === undefined ? null : Number(monthText);
+    const day = dayText === undefined ? null : Number(dayText);
+
+    // No year zero, in any reckoning: the years either side of an epoch are -1
+    // and 1. `-0` is the same year written the other way and is refused with it.
+    if (year === 0) {
+        return refuse(
+            `${subject} writes year 0, and no reckoning has one — the years either ` +
+                `side of an epoch are -1 and 1`,
+        );
+    }
+
+    const { months } = calendarStructure(calendar);
+    if (month !== null && month < 1) {
+        return refuse(`${subject} writes month ${month}, and a month is numbered from 1`);
+    }
+    // An upper bound is checked only where the calendar states its months.
+    // Twelve Gregorian months assumed here would refuse `667/2/30`, which is a
+    // correct date in a year of twelve thirty-day months.
+    if (month !== null && months !== null && month > months.length) {
+        return refuse(
+            `${subject} writes month ${month}, and the calendar it is written in ` +
+                `keeps ${months.length} months`,
+        );
+    }
+    if (day !== null && day < 1) {
+        return refuse(`${subject} writes day ${day}, and a day is numbered from 1`);
+    }
+    // Per month, because the months differ: a five-day month sits in the list
+    // wherever its people put it, and a bound taken from the longest month
+    // would accept a date that calendar has no day for.
+    const length = month !== null ? daysInMonth(calendar, month) : null;
+    if (day !== null && length !== null && day > length) {
+        const named = months?.[month - 1]?.name;
+        return refuse(
+            `${subject} writes day ${day}, and ${named ? `${named}` : `month ${month}`} ` +
+                `is ${length} days long`,
+        );
+    }
+
+    const precision =
+        day !== null ? "day"
+        : month !== null ? "month"
+        : "year";
+    if (approximate && precision === "day") {
+        findings.push({
+            ...at(),
+            severity: "warning",
+            message:
+                `${subject} marks a day approximate, which is nearly always a slip ` +
+                `— drop the \`~\`, or write the month or the year the date is ` +
+                `approximate to`,
+        });
+    }
+
+    const date = {
+        text,
+        known: true,
+        era: era ?? null,
+        year,
+        month,
+        day,
+        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) {
+        date.canonicalYear = canonicalYear(year);
+        date.sort = dateSortKey(date.canonicalYear, month, day);
+    }
+    return { date, findings };
+}

package/engine/note-vocabulary.mjs

@@ -85,6 +85,12 @@ import { currentType } from "./ids.mjs";
 // What a place is next to and reachable from — the two relation lists and
 // the checks that hold them to their closed sets and to each other.
 import { checkBorders, checkRoutes } from "./place-relations.mjs";
+import {
+    CALENDAR_FIELDS,
+    INVARIANT_FIELDS,
+    checkCalendarNote,
+    checkWorldFacts,
+} from "./calendar-notes.mjs";
 import { checkHeld } from "./holdings.mjs";
 import { checkCitedPopulations, checkPopulation } from "./populations.mjs";
 // What trade a settlement supports — the scale and the check that holds a
@@ -306,6 +312,22 @@ const CHARGES = Object.freeze([
     { name: "charges.max", ...NUM, describe: "Most charges it can hold; unset means no maximum." },
 ]);
 
+/**
+ * Everything `place` asks of a whole note.
+ *
+ * Two questions about one subject, and they are independent: who holds this
+ * land, and — where the note is a body rather than somewhere within one — what
+ * the body states about itself. A type declares one whole-note check, so the
+ * two are composed here rather than either being folded into the other.
+ *
+ * @param {object} note - The note.
+ * @param {object} [opts] - The lint's options, passed through unchanged.
+ * @returns {object[]} Findings from both.
+ */
+function checkPlace(note, opts) {
+    return [...checkHeld(note, opts), ...checkWorldFacts(note, opts)];
+}
+
 /* --------------------------------------------------------------------- */
 /*  The vocabulary                                                        */
 /* --------------------------------------------------------------------- */
@@ -586,8 +608,32 @@ export const NOTE_VOCABULARY = Object.freeze({
             },
             { name: "gender", ...TEXT, describe: "`male`, `female` or `other`." },
             { name: "species", ...LINK, describe: "The being's species, as a lore note." },
-            { name: "age", ...NUM, describe: "Age in years." },
-            { name: "birthday", ...TEXT, describe: "Date of birth, `YYYY/MM/DD`." },
+            {
+                name: "born",
+                ...TEXT,
+                describe:
+                    "When the being was born — a date, or `unknown` where the birth is " +
+                    "unrecorded. Absent, the being was never born.",
+            },
+            {
+                name: "died",
+                ...TEXT,
+                describe:
+                    "When the being died — a date, or `unknown` where the death is " +
+                    "unrecorded. Absent, the being is alive.",
+            },
+            // Ahead of `height` and behind the dates, because it opens the
+            // appearance clause: a composed row stands where its group's first
+            // field is declared, so the two dates read before the clause
+            // whether or not a note states an age.
+            {
+                name: "age",
+                ...TEXT,
+                describe:
+                    "Age in years, stated only to override what `born` says — `34`, or `~34` " +
+                    "for an estimate. Unstated beside a dated `born` it is computed; unstated " +
+                    "beside an unknown or absent `born` the age is unknown.",
+            },
             { name: "height", ...NUM, describe: "Height in metres." },
             { name: "weight", ...NUM, describe: "Weight in kilograms." },
             {
@@ -1020,16 +1066,27 @@ export const NOTE_VOCABULARY = Object.freeze({
             "bestiary",
             "gathering",
         ]),
-        // Nothing of its own: a lore note is prose, and what it *is* about is
-        // its subType. The specification declares an empty table for it, and
-        // the authored corpus writes no `data:` key on any of the 180.
-        data: Object.freeze([]),
+        // A lore note is prose, and what it *is* about is its subType — with
+        // one exception. A calendar is a division of the year, and a division
+        // is data; the check scopes the family to the subType that means it,
+        // because `DataFieldSpec` declares the keys a type accepts and not the
+        // subType that may write them.
+        check: checkCalendarNote,
+        data: CALENDAR_FIELDS,
     }),
 
     place: Object.freeze({
         stubbable: true,
-        subTypes: Object.freeze(["world", "region", "settlement", "site", "structure", "feature"]),
-        check: checkHeld,
+        subTypes: Object.freeze([
+            "world",
+            "region",
+            "settlement",
+            "site",
+            "structure",
+            "feature",
+            "celestial",
+        ]),
+        check: checkPlace,
         data: Object.freeze([
             {
                 name: "demonym",
@@ -1080,6 +1137,10 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "Journeys from this place's centre — where the destination lies, how " +
                     "it is travelled, and about how many days it takes.",
             },
+            // What a body states about itself: its size, its year, its moon.
+            // Legal on a `world` or a `celestial` and nowhere else, which the
+            // type's own check is what enforces.
+            ...INVARIANT_FIELDS,
         ]),
     }),
 

package/engine/pdf-render.mjs

@@ -1089,6 +1089,16 @@ export function renderBook({
         `#set text(font: "${escapeTypstString(serif)}", size: 9.6pt, fill: book-ink, lang: "en")`,
     );
     out.push("#set par(justify: true, leading: 0.55em, first-line-indent: 1.2em)");
+    // The first-line indent is what separates one paragraph of running prose
+    // from the next, and inside a list item the marker already does that. An
+    // item carrying more than one paragraph sets every one of them flush at the
+    // item's own text column, so the item reads as a single block hanging off
+    // its marker. Neither the marker column nor the gap after it is set here:
+    // Typst measures the widest marker in the list and aligns every body
+    // against it, which is what keeps a list of twelve aligned once `10.`
+    // becomes wider than `1.`.
+    out.push("#show list: set par(first-line-indent: 0em)");
+    out.push("#show enum: set par(first-line-indent: 0em)");
     // The mono face is a separate claim from the book face: a fenced block is
     // the one place the corpus is allowed box-drawing characters, and the
     // serif that sets the prose is not the font that carries them.

package/engine/retired-fields.mjs

@@ -57,7 +57,7 @@
  * by accident.
  *
  * **What `traits:` did.** It held a being's own description — gender,
- * species, age, birthday, height, weight, frame and `appearance.*` — at the
+ * species, age, birth date, height, weight, frame and `appearance.*` — at the
  * note's top level. The content format gives those a home: `data:`, the closed
  * container for a subject's type-specific facts, which `being` declares every
  * one of them in. Every note that carried one has been moved, across four
@@ -111,13 +111,21 @@
  * are needed, and separately: a note may have moved one and not the other, and
  * a single finding covering both would name the wrong line half the time.
  *
+ * **A `data:` field's retired spelling is written in `data:`**, and nowhere
+ * else. The container is closed, so a key in it is either one the type declares
+ * or one refused by name — which makes the retired spelling of a declared key
+ * an error the moment the replacement lands, unless the container check knows
+ * to read it as a rename. {@link declaresRetiredAlias} and
+ * {@link readAliasedField} therefore take `inData`, and search that one region
+ * rather than the block and the top level a system field is written in.
+ *
  * @module
  */
 
 import fs from "node:fs";
 
 import { positionInFrontmatter } from "./diagnostics.mjs";
-import { sohlField } from "./frontmatter.mjs";
+import { getFrontmatter, sohlField } from "./frontmatter.mjs";
 import { retiredTopLevelKey } from "./system-block.mjs";
 
 /**
@@ -355,8 +363,9 @@ export function traitsRetiredMessage(file) {
         "content format declares, where `being` declares every one of its " +
         "keys; at the top level it was passed through to the page unchecked, " +
         "so a misspelling became a theme parameter rather than a finding. " +
-        "`gender`, `species`, `age`, `birthday` and `appearance.*` move " +
-        "unchanged; three reshape — `traits.height.m` becomes `data.height` " +
+        "`gender`, `species`, `age` and `appearance.*` move unchanged; " +
+        "`traits.birthday` becomes `data.born`; three reshape — " +
+        "`traits.height.m` becomes `data.height` " +
         "(metres), `traits.weight.kg` becomes `data.weight` (kilograms), and " +
         "`traits.build.frame` becomes `data.frame`"
     );
@@ -451,11 +460,19 @@ export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel
  * read past. Only `affiliation` declares the field, so the alias is reported
  * there and the old spelling stays an ordinary unknown key everywhere else.
  *
+ * **`born`.** A birthday is a day that recurs; what a note records is the date
+ * somebody was born, once. The two read alike while every value belonged to a
+ * living person, and `born` is what the field has to be called beside `died`,
+ * which a being now also states. It is the first alias whose field lives in
+ * `data:` rather than in a system block, so the two readers below take
+ * `inData`.
+ *
  * @type {Readonly<Record<string, string>>}
  */
 export const RETIRED_FIELD_ALIASES = Object.freeze({
     templatePriority: "archetype",
     relations: "relation",
+    born: "birthday",
 });
 
 /**
@@ -558,11 +575,17 @@ export function retiredTopLevelMessage(field, file) {
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} current - The field's current name.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.inData=false] - Search the `data:` container
+ *   instead. A `data:` field has exactly one home, so its retired spelling has
+ *   exactly one too, and searching the block or the top level for it would
+ *   answer about a key the container check has already refused.
  * @returns {boolean} Whether the retired spelling is declared.
  */
-export function declaresRetiredAlias(fm, current) {
+export function declaresRetiredAlias(fm, current, { inData = false } = {}) {
     const retired = RETIRED_FIELD_ALIASES[current];
     if (!retired || !fm || typeof fm !== "object") return false;
+    if (inData) return Object.hasOwn(dataContainer(fm), retired);
     const block = fm.sohl;
     const inBlock =
         block &&
@@ -572,6 +595,21 @@ export function declaresRetiredAlias(fm, current) {
     return Boolean(inBlock) || Object.hasOwn(fm, retired);
 }
 
+/**
+ * A note's `data:` container, or an empty one where it authored none.
+ *
+ * The property editor writes an emptied map as `[]`, which means the same thing
+ * `{}` does — this note authors no entries — so both read as empty rather than
+ * as something to search.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {object} The container.
+ */
+function dataContainer(fm) {
+    const data = fm.data;
+    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+}
+
 /**
  * Read a field that has a retired spelling, the current name winning.
  *
@@ -587,11 +625,23 @@ export function declaresRetiredAlias(fm, current) {
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} current - The field's current name.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.inData=false] - Read the `data:` container instead,
+ *   which is where a `data:` field and its retired spelling are both written.
+ *   Dotted names resolve inside it, so `appearance.eye_color` reads the way it
+ *   is authored.
  * @returns {any} The value, or `undefined` when neither spelling carries one.
  */
-export function readAliasedField(fm, current) {
-    const value = sohlField(fm, current, undefined);
+export function readAliasedField(fm, current, { inData = false } = {}) {
+    const read =
+        inData ?
+            /** @param {string} key */ (key) =>
+                fm && typeof fm === "object" ?
+                    getFrontmatter(dataContainer(fm), key, undefined)
+                :   undefined
+        :   /** @param {string} key */ (key) => sohlField(fm, key, undefined);
+    const value = read(current);
     if (value !== undefined && value !== null && value !== "") return value;
     const retired = RETIRED_FIELD_ALIASES[current];
-    return retired ? sohlField(fm, retired, undefined) : undefined;
+    return retired ? read(retired) : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.7.0",
+    "version": "22.9.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",