@heroiclands/package-build 8.1.0 → 10.0.0

package/engine/pack-config.mjs

@@ -81,11 +81,7 @@ import { createRequire } from "node:module";
 import YAML from "yaml";
 
 import { defineConfig, DERIVED_SYSTEM_VERSION } from "../content-config.mjs";
-import {
-    formatDiagnostic,
-    positionOfYamlPath,
-    yamlKeyPath,
-} from "./diagnostics.mjs";
+import { formatDiagnostic, positionOfYamlPath, yamlKeyPath } from "./diagnostics.mjs";
 
 /** The stem every consuming repository declares its build under. */
 export const CONFIG_BASENAME = "package-build.config";
@@ -130,9 +126,9 @@ export const CONFIG_FILENAMES = Object.freeze([
 export function findConfigFile(from) {
     let dir = path.resolve(from);
     for (;;) {
-        const found = CONFIG_FILENAMES.map((name) =>
-            path.join(dir, name),
-        ).filter((candidate) => fs.existsSync(candidate));
+        const found = CONFIG_FILENAMES.map((name) => path.join(dir, name)).filter((candidate) =>
+            fs.existsSync(candidate),
+        );
         if (found.length > 1) {
             throw new Error(
                 `package-build: ${dir} holds more than one configuration ` +
@@ -275,11 +271,9 @@ function shippedSystemVersion(rootDir, input) {
         return pkg.version;
     }
 
-    const systemId = /** @type {Record<string, unknown>} */ (input.stats ?? {})
-        .systemId;
-    const declaredSystems = /** @type {Record<string, unknown>} */ (
-        input.relationships ?? {}
-    ).systems;
+    const systemId = /** @type {Record<string, unknown>} */ (input.stats ?? {}).systemId;
+    const declaredSystems = /** @type {Record<string, unknown>} */ (input.relationships ?? {})
+        .systems;
 
     // The `systems:` block declares without requiring (#48), so it is consulted
     // first: a package that has adopted it needs no relationship, and one that
@@ -288,10 +282,9 @@ function shippedSystemVersion(rootDir, input) {
     // otherwise a single declared system is unambiguous. With several and no
     // gate, there is no package-wide answer — each pack carries its own, and
     // {@link statsForPack} is what reads it.
-    const systemsBlock =
-        /** @type {Record<string, {compatibility?: {verified?: string}}>} */ (
-            input.systems ?? {}
-        );
+    const systemsBlock = /** @type {Record<string, {compatibility?: {verified?: string}}>} */ (
+        input.systems ?? {}
+    );
     const systemIds = Object.keys(systemsBlock);
     if (systemIds.length) {
         const chosen =
@@ -300,8 +293,7 @@ function shippedSystemVersion(rootDir, input) {
             : null;
         if (chosen) {
             const verified = systemsBlock[chosen]?.compatibility?.verified;
-            if (typeof verified === "string" && verified.length)
-                return verified;
+            if (typeof verified === "string" && verified.length) return verified;
         }
         // Several declared and none required: the package-wide value is
         // deliberately absent rather than one of them picked arbitrarily.
@@ -323,11 +315,9 @@ function shippedSystemVersion(rootDir, input) {
 
     const systems =
         /** @type {{id?: string, compatibility?: {verified?: string}}[]} */ (
-            /** @type {Record<string, unknown>} */ (input.relationships ?? {})
-                .systems
+            /** @type {Record<string, unknown>} */ (input.relationships ?? {}).systems
         ) ?? [];
-    const relationship =
-        systems.find((entry) => entry?.id === systemId) ?? systems[0];
+    const relationship = systems.find((entry) => entry?.id === systemId) ?? systems[0];
     const verified = relationship?.compatibility?.verified;
 
     if (typeof verified !== "string" || verified.length === 0) {
@@ -413,11 +403,7 @@ export function locateConfigError(err, configPath) {
             err
         );
     if (!(err instanceof Error)) return err;
-    if (
-        failure.located ||
-        typeof failure.field !== "string" ||
-        !failure.field
-    ) {
+    if (failure.located || typeof failure.field !== "string" || !failure.field) {
         return err;
     }
     if (!configPath) return err;
@@ -445,9 +431,10 @@ export function locateConfigError(err, configPath) {
  * - **`rootDir`** is the configuration's own directory, always. A data file
  *   cannot write `import.meta.dirname`, and any absolute path it wrote instead
  *   would be one machine's — so authoring it is rejected rather than honoured.
- * - **`itemBuilders`** is a *name* (`sohl`), resolved against the built-in
- *   registries. A registry of a consumer's own is code, and code goes in an
- *   `.mjs` configuration.
+ * - **`itemBuilders`** is a *name* (`sohl`) — or a list of names, for a tree
+ *   feeding more than one system (#58) — resolved against the built-in
+ *   registries. A registry's name is the system it belongs to. A registry of a
+ *   consumer's own is code, and code goes in an `.mjs` configuration.
  * - **`stats.systemVersion`** is derived from the adjacent `package.json` when
  *   the configuration does not state it. Stating it is still allowed: a
  *   repository shipping content *for* another package (a module declaring
@@ -496,26 +483,42 @@ export function configFromData(data, configPath) {
     input.foundryPackage = foundryPackageId(rootDir);
 
     if (input.itemBuilders !== undefined) {
-        const named = input.itemBuilders;
+        const declared = input.itemBuilders;
         const known = Object.keys(ITEM_BUILDER_REGISTRIES).join(", ");
-        if (typeof named !== "string") {
-            throw new Error(
-                `package-build: ${configPath} must name its \`itemBuilders\` ` +
-                    `registry as a string — the registry is code, and data ` +
-                    `cannot carry it. Known registries: ${known}; a registry ` +
-                    `of your own goes in ${CONFIG_BASENAME}.mjs.`,
-            );
-        }
-        const load = ITEM_BUILDER_REGISTRIES[named];
-        if (!load) {
-            throw new Error(
-                `package-build: ${configPath} names the \`itemBuilders\` ` +
-                    `registry "${named}", which this package does not ship. ` +
-                    `Known registries: ${known}. To supply your own, declare ` +
-                    `it in ${CONFIG_BASENAME}.mjs.`,
-            );
-        }
-        input.itemBuilders = load();
+        // One name or several. A repository feeding two systems needs both
+        // vocabularies, and one registry can only carry one (#58); the scalar
+        // form every existing configuration uses is the one-element case and
+        // means exactly what it always did.
+        const names = Array.isArray(declared) ? declared : [declared];
+        const resolved = names.map((named, index) => {
+            const where = Array.isArray(declared) ? `itemBuilders[${index}]` : "itemBuilders";
+            if (typeof named !== "string") {
+                throw new Error(
+                    `package-build: ${configPath} must name its \`${where}\` ` +
+                        `registry as a string — the registry is code, and data ` +
+                        `cannot carry it. Known registries: ${known}; a registry ` +
+                        `of your own goes in ${CONFIG_BASENAME}.mjs.`,
+                );
+            }
+            const load = ITEM_BUILDER_REGISTRIES[named];
+            if (!load) {
+                throw new Error(
+                    `package-build: ${configPath} names the \`${where}\` ` +
+                        `registry "${named}", which this package does not ship. ` +
+                        `Known registries: ${known}. To supply your own, declare ` +
+                        `it in ${CONFIG_BASENAME}.mjs.`,
+                );
+            }
+            // A shipped registry's *name* is the system it belongs to, which is
+            // what lets a data configuration declare a set without carrying the
+            // system id a second time.
+            return { system: named, builders: load() };
+        });
+        // The scalar form stays the flat, system-less registry it has always
+        // resolved to. Wrapping it as a one-entry set would be tidier and would
+        // change what every existing configuration means — `itemBuildersBySystem`
+        // would gain an entry the consumer never declared.
+        input.itemBuilders = Array.isArray(declared) ? resolved : resolved[0].builders;
     }
 
     const stats = input.stats;
@@ -562,10 +565,7 @@ function loadCodeConfig(configPath) {
         // arrive here. There is no YAML to locate into, but the file is known —
         // `locateConfigError` names it and drops the line.
         locateConfigError(err, configPath);
-        if (
-            /** @type {{ code?: string }} */ (err)?.code ===
-            "ERR_REQUIRE_ASYNC_MODULE"
-        ) {
+        if (/** @type {{ code?: string }} */ (err)?.code === "ERR_REQUIRE_ASYNC_MODULE") {
             throw new Error(
                 `package-build: ${configPath} (or something it imports) uses ` +
                     `top-level await, which the configuration cannot: it is ` +
@@ -603,8 +603,7 @@ export function loadPackConfig() {
     if (loaded) return loaded;
 
     const explicit = process.env.PACKAGE_BUILD_CONFIG;
-    const configPath =
-        explicit ? path.resolve(explicit) : findConfigFile(import.meta.dirname);
+    const configPath = explicit ? path.resolve(explicit) : findConfigFile(import.meta.dirname);
 
     if (!configPath || !fs.existsSync(configPath)) {
         throw new Error(
@@ -621,10 +620,7 @@ export function loadPackConfig() {
     loaded =
         configPath.endsWith(".mjs") ?
             loadCodeConfig(configPath)
-        :   configFromData(
-                YAML.parse(fs.readFileSync(configPath, "utf8")),
-                configPath,
-            );
+        :   configFromData(YAML.parse(fs.readFileSync(configPath, "utf8")), configPath);
     loadedFrom = configPath;
     return loaded;
 }

package/engine/pack-router.mjs

@@ -47,12 +47,18 @@
  * - A note's **derived** documents are routed by the default of *their* type,
  *   not by the note's declaration: an item note's prose compiles into a
  *   JournalEntry, and `pack:` names where the *item* goes.
+ * - A note feeding **more than one system** declares `pack:` inside the block
+ *   that differs (#58). `pack` needed no new mechanism for that: it is an
+ *   ordinary shared property, so `<system>.pack` overrides the top-level one
+ *   for that system's document and leaves it standing for every other. A note
+ *   wanting one pack for both says it once at the top.
  *
  * @module
  */
 
 import { packForType } from "./ids.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
+import { blockProperty } from "./system-block.mjs";
 
 /**
  * A note that cannot be routed to a pack. Thrown rather than returned so no
@@ -84,8 +90,8 @@ export const PACK_FIELD = "pack";
  *
  * @param {readonly object[]} packs - The resolved `packs` list from
  *   `defineConfig`.
- * @returns {{resolve: (fm: object, docType: string) => string,
- *   resolveOrNull: (fm: object, docType: string) => string|undefined,
+ * @returns {{resolve: (fm: object, docType: string, system?: string) => string,
+ *   resolveOrNull: (fm: object, docType: string, system?: string) => string|undefined,
  *   packsOfType: (docType: string) => string[],
  *   defaultOf: (docType: string) => string|undefined}} The router.
  */
@@ -117,19 +123,22 @@ export function createPackRouter(packs) {
     }
 
     /** @param {object} fm */
-    const noteLabel = (fm) =>
-        fm?.name?.full ?? fm?.shortcode ?? fm?.id ?? "a note";
+    const noteLabel = (fm) => fm?.name?.full ?? fm?.shortcode ?? fm?.id ?? "a note";
 
     /**
      * The pack one pass should write this note's document to.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {string} docType - The document type the calling pass writes.
+     * @param {string} [system] - The system whose document is being routed. Its
+     *   block's `pack:` wins over the shared one; without it only the shared
+     *   declaration is read, which is every single-system build.
      * @returns {string} The pack name.
      * @throws {PackRoutingError} When the note routes nowhere.
      */
-    function resolve(fm, docType) {
-        const declared = fm?.[PACK_FIELD];
+    function resolve(fm, docType, system) {
+        const declared =
+            system === undefined ? fm?.[PACK_FIELD] : blockProperty(fm, system, PACK_FIELD);
         // The declaration names where the note's *own* document goes. A pass
         // writing a document derived from it — an item's prose becoming a
         // JournalEntry — is not what the author was addressing.
@@ -190,11 +199,12 @@ export function createPackRouter(packs) {
          *
          * @param {object} fm - The note's frontmatter.
          * @param {string} docType - The document type being addressed.
+         * @param {string} [system] - The system whose document is addressed.
          * @returns {string|undefined} The pack name, or `undefined`.
          */
-        resolveOrNull(fm, docType) {
+        resolveOrNull(fm, docType, system) {
             try {
-                return resolve(fm, docType);
+                return resolve(fm, docType, system);
             } catch {
                 return undefined;
             }

package/engine/prose-config.mjs

@@ -46,7 +46,25 @@
  * @type {Readonly<object>}
  */
 export const PRETTIER_BASE = Object.freeze({
-    printWidth: 80,
+    // 100, not the conventional 80. The usual argument for 80 is reading
+    // measure, and it does not apply here: `proseWrap` is left at Prettier's
+    // default of `preserve`, so authored prose is never reflowed at all — the
+    // notes in these trees run to a p90 of 378 characters a line and are
+    // untouched by this number. What it actually governs is TypeScript and the
+    // YAML of a note's frontmatter, and both were measurably cramped at 80.
+    //
+    // Measured before changing it, across a third of the SoHL source: at 80,
+    // Prettier *fails* to honour the limit on 1,399 lines — long string
+    // literals, `@src/…` specifiers, generic signatures — so those lines are
+    // over-width anyway and their surroundings were broken up for nothing. At
+    // 100 that falls to 75, and the file is 4.9% shorter. Past 100 the returns
+    // flatten (120 buys another 2.6%).
+    //
+    // The same knee appears in content: an item entry written in flow style —
+    // `{ shortcode: X, type: skill, name: …, system: { … } }` — typically lands
+    // in the low 90s, so 90.8% of 318,030 entries fit on one line at 80 and
+    // 95.3% at 100, with almost nothing gained in between.
+    printWidth: 100,
     tabWidth: 4,
     useTabs: false,
     semi: true,
@@ -113,9 +131,7 @@ export const PRETTIER_CONFIG = Object.freeze({
  *   `overrides`: passing that inline is what silently did nothing (#76).
  */
 export function sharedPrettierOptionsFor(file) {
-    return /\.md$/i.test(file) ?
-            { ...PRETTIER_BASE, ...PRETTIER_MARKDOWN }
-        :   { ...PRETTIER_BASE };
+    return /\.md$/i.test(file) ? { ...PRETTIER_BASE, ...PRETTIER_MARKDOWN } : { ...PRETTIER_BASE };
 }
 
 /**

package/engine/prose-lint.mjs

@@ -61,6 +61,23 @@ const NEVER_WALK = Object.freeze(new Set([".git", "node_modules"]));
  */
 const IGNORE_FILES = Object.freeze([".gitignore", ".prettierignore"]);
 
+/**
+ * How many times `--write` will format one file looking for a fixpoint.
+ *
+ * `format` is *assumed* idempotent and is not guaranteed to be: a single pass
+ * can leave text the next pass would still change, and a `--write` run that
+ * takes one pass then reports success has called such a file formatted while
+ * `prettier --check` still rejects it (#125). Formatting to a fixpoint removes
+ * the assumption — the file lands on the value repeated formatting converges
+ * to, whatever it took to get there.
+ *
+ * Three, not "until it stops": a file that oscillates would loop forever, and
+ * the cap turns that into a report. Three is enough for the case this is for
+ * (one pass short) with a pass to spare, and costs nothing on a tree that is
+ * already formatted, where the first pass converges immediately.
+ */
+const MAX_FORMAT_PASSES = 3;
+
 /**
  * Every file under a root, minus the directories nothing should walk.
  *
@@ -106,28 +123,27 @@ function walkFiles(root) {
  * @param {readonly string[]} [opts.paths] - Files or directories to check
  *   instead of the whole root.
  * @param {boolean} [opts.write=false] - Rewrite unformatted files in place
- *   rather than reporting them.
+ *   rather than reporting them. Each file is formatted to a fixpoint (up to
+ *   {@link MAX_FORMAT_PASSES} passes), so a written tree is one a second run
+ *   leaves alone; a file that will not converge is reported and left unchanged
+ *   (#125).
  * @param {object} [opts.prettier] - The Prettier module, for tests.
  * @returns {Promise<{findings: Array<{file: string, severity: string,
  *   message: string}>, checked: number, written: string[]}>} The findings, how
- *   many files were considered, and what was rewritten.
+ *   many files were considered, and what was rewritten. `--write` reports
+ *   findings too — a file it cannot parse, or cannot format to a fixpoint.
  */
 export async function checkFormatting(root, opts = {}) {
     const { paths, write = false } = opts;
     const prettier = opts.prettier ?? (await import("prettier"));
     const base = path.resolve(root);
-    const ignorePath = IGNORE_FILES.map((name) => path.join(base, name)).filter(
-        (file) => fs.existsSync(file),
+    const ignorePath = IGNORE_FILES.map((name) => path.join(base, name)).filter((file) =>
+        fs.existsSync(file),
     );
 
-    const roots =
-        paths?.length ?
-            paths.map((entry) => path.resolve(base, entry))
-        :   [base];
+    const roots = paths?.length ? paths.map((entry) => path.resolve(base, entry)) : [base];
     const candidates = roots.flatMap((entry) =>
-        fs.existsSync(entry) && fs.statSync(entry).isDirectory() ?
-            walkFiles(entry)
-        :   [entry],
+        fs.existsSync(entry) && fs.statSync(entry).isDirectory() ? walkFiles(entry) : [entry],
     );
 
     const findings = [];
@@ -160,7 +176,38 @@ export async function checkFormatting(root, opts = {}) {
         // every other one.
         try {
             if (write) {
-                const formatted = await prettier.format(source, options);
+                // Format to a fixpoint rather than once, so what lands on disk
+                // is what a second run would have produced (#125).
+                let formatted = source;
+                let converged = false;
+                for (let pass = 0; pass < MAX_FORMAT_PASSES; pass += 1) {
+                    const next = await prettier.format(formatted, options);
+                    if (next === formatted) {
+                        converged = true;
+                        break;
+                    }
+                    formatted = next;
+                }
+
+                if (!converged) {
+                    // Nothing is written. A formatting the command cannot
+                    // reproduce is not one to commit to disk — writing it
+                    // would make `--write` churn the file on every run — and a
+                    // file that never settles is a defect somewhere that has
+                    // to be named rather than absorbed.
+                    findings.push({
+                        file,
+                        severity: "error",
+                        // No line or column: the verdict is about the whole
+                        // file, and #17's rule is to drop a field rather than
+                        // invent one.
+                        message:
+                            `did not converge after ${MAX_FORMAT_PASSES} formatting passes; ` +
+                            "left unchanged",
+                    });
+                    continue;
+                }
+
                 if (formatted !== source) {
                     fs.writeFileSync(file, formatted);
                     written.push(file);
@@ -175,8 +222,7 @@ export async function checkFormatting(root, opts = {}) {
                     // No line or column: Prettier's answer is about the whole
                     // file, and #17's rule is to drop a field rather than
                     // invent one.
-                    message:
-                        "is not formatted; run `content-build format --write` to fix it",
+                    message: "is not formatted; run `content-build format --write` to fix it",
                 });
             }
         } catch (err) {
@@ -189,9 +235,7 @@ export async function checkFormatting(root, opts = {}) {
             const loc = err?.loc?.start ?? err?.loc;
             findings.push({
                 file,
-                ...(Number.isFinite(loc?.line) ?
-                    { line: loc.line, column: loc.column }
-                :   {}),
+                ...(Number.isFinite(loc?.line) ? { line: loc.line, column: loc.column } : {}),
                 severity: "error",
                 message: `cannot be parsed: ${String(err?.message ?? err).split("\n")[0]}`,
             });

package/engine/region-events.mjs

@@ -54,9 +54,7 @@ export const REGION_EVENT_TO_TRIGGER = Object.freeze({
  *
  * @type {readonly string[]}
  */
-export const CURATED_REGION_EVENTS = Object.freeze(
-    Object.keys(REGION_EVENT_TO_TRIGGER),
-);
+export const CURATED_REGION_EVENTS = Object.freeze(Object.keys(REGION_EVENT_TO_TRIGGER));
 
 /**
  * Region events SoHL deliberately does **not** forward: the continuous

package/engine/retired-fields.mjs

@@ -34,12 +34,24 @@
  * *unresolvable*, silently — and it also suppressed real build failures, since
  * a note the compilers never reached could not fail on the defects it carried.
  *
+ * **A field retired in favour of another is a third case (#142).** `draft:` and
+ * `package:` were retired outright: nothing replaced them, so no value made
+ * writing one right and refusal was the only honest answer. A *renamed* field
+ * has a replacement, and the two spellings mean the same thing — so the note
+ * still compiles, correctly, and refusing it would fail a build over a document
+ * that is not wrong. Those retire in the three steps `package:` took (#56), and
+ * this module carries the **first**: both spellings are read, the current one
+ * wins, and the retired one is *reported* rather than refused. The sweep and
+ * the refusal come later, once no tree writes it. See
+ * {@link RETIRED_FIELD_ALIASES}.
+ *
  * @module
  */
 
 import fs from "node:fs";
 
 import { positionInFrontmatter } from "./diagnostics.mjs";
+import { sohlField } from "./frontmatter.mjs";
 
 /**
  * What a note declaring `draft:` is told, in one place.
@@ -105,12 +117,15 @@ export function assertNoDraftField(fm, { file, absPath } = {}) {
  * both refusals need it and a second copy is a second thing to keep correct.
  *
  * @param {string|undefined} absPath - The note's file.
- * @param {string} key - The top-level frontmatter key.
+ * @param {string} key - The frontmatter key.
+ * @param {string} [value] - When given, prefer the occurrence whose line also
+ *   carries this text — so a finding about one entry of a block opens on that
+ *   entry rather than on the key that introduces it.
  * @returns {{line?: number, column?: number}|undefined} Spreadable position
  *   fields, dropped rather than guessed when the file cannot be read or the key
  *   cannot be found — as `formatDiagnostic` requires.
  */
-export function locateFrontmatterKey(absPath, key) {
+export function locateFrontmatterKey(absPath, key, value = undefined) {
     if (!absPath) return undefined;
     let raw;
     try {
@@ -118,6 +133,105 @@ export function locateFrontmatterKey(absPath, key) {
     } catch {
         return undefined;
     }
-    const at = positionInFrontmatter(raw, key);
+    const at = positionInFrontmatter(raw, key, value);
     return at.line === undefined ? undefined : at;
 }
+
+/* -------------------------------------------------------------------- */
+/*  Retired *in favour of another field*                                 */
+/* -------------------------------------------------------------------- */
+
+/**
+ * The current field name a retired spelling was renamed to.
+ *
+ * Keyed by the **current** name, because that is what a type's schema declares
+ * and what every reader asks for; the value is the spelling still honoured.
+ * The table is therefore scoped by the schema without saying so twice: an alias
+ * applies to a note only where that note's type declares the current field, so
+ * `image` is retired on a map — which declares `img` — and remains an unknown
+ * key anywhere else.
+ *
+ * **`img` (#142).** Every note type names its artwork `img`, at the note's top
+ * level, and resolves it the same way. A map alone named its background art
+ * `image` and read it out of the `sohl:` block — two spellings for one idea,
+ * with nothing to reconcile them, and a specification that had to hedge rather
+ * than state a rule. Art is not system-specific: a Scene is a core Foundry
+ * document and HM3 would want the identical one, so the field belongs beside
+ * every other note's `img`, not inside a system block.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const RETIRED_FIELD_ALIASES = Object.freeze({ img: "image" });
+
+/**
+ * What a note writing a renamed field is told, in one place.
+ *
+ * Shared by the compile-time report and the frontmatter lint, because an author
+ * meets whichever runs first and they should read the same. It names the key to
+ * write rather than a value to correct — no value makes the retired spelling
+ * right — and it says the note compiles either way, so a reader knows this is a
+ * rename to schedule rather than a build to unbreak.
+ *
+ * @param {string} retired - The spelling the note used.
+ * @param {string} current - What to write instead.
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function retiredAliasMessage(retired, current, file) {
+    return (
+        `\`${retired}:\` is a retired frontmatter field — write \`${current}:\` ` +
+        `instead` +
+        (file ? ` — ${file}` : "") +
+        `. Both are read and \`${current}\` wins, so the note compiles ` +
+        `identically either way; \`${retired}\` is removed in a later release`
+    );
+}
+
+/**
+ * Whether a note writes the retired spelling of a field, wherever it put it.
+ *
+ * Both regions are searched, because {@link sohlField} reads both: a note that
+ * moved the key to the top level without renaming it has done half the
+ * migration, and should be told so rather than passing in silence.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} current - The field's current name.
+ * @returns {boolean} Whether the retired spelling is declared.
+ */
+export function declaresRetiredAlias(fm, current) {
+    const retired = RETIRED_FIELD_ALIASES[current];
+    if (!retired || !fm || typeof fm !== "object") return false;
+    const block = fm.sohl;
+    const inBlock =
+        block &&
+        typeof block === "object" &&
+        !Array.isArray(block) &&
+        Object.hasOwn(block, retired);
+    return Boolean(inBlock) || Object.hasOwn(fm, retired);
+}
+
+/**
+ * Read a field that has a retired spelling, the current name winning.
+ *
+ * This is the whole of the retirement window's behaviour, in one function, so
+ * the compiler and the linter cannot disagree about which value a note carries.
+ * Resolution within each spelling is {@link sohlField}'s — the `sohl:` block
+ * first, then the note's top level — so a renamed field keeps working wherever
+ * it was already written while the canonical home is the top level.
+ *
+ * A blank value counts as absent: `img:` cleared in an editor means the note
+ * names no art there, and falling through to the retired spelling is what an
+ * author part-way through the rename means by it.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} current - The field's current name.
+ * @returns {any} The value, or `undefined` when neither spelling carries one.
+ */
+export function readAliasedField(fm, current) {
+    const value = sohlField(fm, current, undefined);
+    if (value !== undefined && value !== null && value !== "") return value;
+    const retired = RETIRED_FIELD_ALIASES[current];
+    return retired ? sohlField(fm, retired, undefined) : undefined;
+}