@heroiclands/package-build 23.1.0 → 23.2.0

package/engine/retired-fields.mjs

@@ -1,631 +0,0 @@
-/*
- * 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
- */
-
-/**
- * Frontmatter fields a note may no longer declare.
- *
- * A retired field has exactly two possible fates, and only one of them is
- * honest. Left honoured, it keeps doing whatever it did — which is why it was
- * retired. Left *ignored*, it reads to its author as though it still works: the
- * note says one thing and the build does another, and nothing says so. So a
- * retired field is **refused**, naming the file and the line, and the message
- * says what to write instead rather than which value to correct.
- *
- * `package:` is retired the same way and is refused from `note-package.mjs`,
- * where the concept it belonged to still lives. `draft:`, the top-level
- * `aliases:`, `section:` and `traits:` have no such home — there is no
- * surviving concept any of them was part of — so they are refused here.
- *
- * **What `draft:` did.** It excluded a note from the compiled packs, from
- * the link manifest and from a consuming site build. Nothing reported the
- * consequence: `content-links.mjs`, `site-index.mjs` and `content-lint.mjs`
- * never read the field, so a link into a drafted note was indistinguishable
- * from a link to a note that does not exist, and the checkers could not say
- * which. The field's entire effect was to move a note from *published* to
- * *unresolvable*, silently — and it also suppressed real build failures, since
- * a note the compilers never reached could not fail on the defects it carried.
- *
- * **What `aliases:` did.** It fed the alias index, which is what a bare
- * `[[Alias]]` was looked up in. That form resolved to nothing anywhere in the
- * corpus, while the collision rule guarding it folded in every note's
- * `name.full` and so decided what a note could be named. The form and
- * the index are retired together, leaving the field with no reader at all.
- *
- * **What `section:` did.** It named the section a `collection` note
- * headed, under the `collection` landing rule — its only reader anywhere. That
- * rule is retired, a section being landed by the `README.md` in its directory,
- * so the field has none. No schema or vocabulary ever declared it either, and
- * nothing checks unrecognized top-level keys, so left in place it would be
- * silently ignored rather than reported.
- *
- * **`name.aliases` lists alternate names.** The note infobox shows them in
- * authored order. They do not create addresses or change link resolution.
- *
- * **What `traits:` did.** It held a being's own description — gender,
- * 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
- * repositories, and this is the third step of that retirement.
- *
- * Refusing it by name rather than as an unknown key is what names the home the
- * facts have: the finding says which `data:` key each one becomes, which an
- * author cannot read off a list of the keys the region declares.
- *
- * `sohl.traits` is a different field that shares the name — `projectilegear`
- * declares one, and the theme's gear sidebar reads it — so the refusal is
- * anchored at column 1 and never reaches inside a system block.
- *
- * **A field retired in favour of another is a third case.** `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, and
- * this module carries the **first**: both spellings are read, the current one
- * wins, and the retired one is *reported* rather than refused. See
- * {@link RETIRED_FIELD_ALIASES}.
- *
- * **The third step is deletion, and it needs no code.** `image`, a map's
- * background art, illustrates all three states: reported,
- * swept, then dropped from the
- * table. Removing the entry is the whole of it — with no alias, the spelling is
- * an ordinary unknown key in the `sohl:` block, which the frontmatter lint
- * already refuses as an error alongside the required field it failed to supply.
- * So nothing here *records* a finished retirement: the absence of an entry is
- * the record, and a retirement that needed a standing refusal would mean the
- * replacement never arrived. Do not keep a tombstone for one.
- *
- * **A retired *position* is the same case, and reads the same.** A field
- * whose shared source moved under `data:` is not renamed — `data.species` and
- * `hm3.species` are one field written in two places — but the retirement has
- * the identical shape: both are read, the one the note carries wins, and the
- * legacy in-block key is reported by {@link legacyKeyMessage} so the sweep has
- * something to count down. Which position a value came from is
- * {@link module:engine/system-block.resolveFieldValue}'s answer; this module
- * only says what an author is told about it.
- *
- * **A field has two retiring positions, not one.** The in-block key is
- * the obvious one; the other is the note's **top level**, because the sweep
- * did not
- * invent the facts `data:` holds — it gathered them from exactly there. So
- * `portrait:` beside `img:` is the pre-`data:` spelling of `data.portrait`,
- * read for the same reason and reported by {@link retiredTopLevelMessage}. Both
- * 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 { getFrontmatter, sohlField } from "./frontmatter.mjs";
-import { retiredTopLevelKey } from "./system-block.mjs";
-
-/**
- * What a note declaring `draft:` is told, in one place.
- *
- * Written once and shared by the compile-time refusal and the frontmatter lint,
- * because an author meets whichever of the two runs first and they should read
- * the same. It says what the field did and what to write instead, rather than
- * which value to correct: no value makes declaring it right.
- *
- * @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 draftRetiredMessage(file) {
-    return (
-        "`draft:` is a retired frontmatter field — delete it" +
-        (file ? ` — ${file}` : "") +
-        ". It excluded the note from the compiled packs, the link manifest " +
-        "and the site, and no checker reported the exclusion, so every " +
-        "wikilink into it read as a link to a note that does not exist. To " +
-        "mark a note as unfinished, tag it `#draft` instead: the note still " +
-        "compiles and publishes, a link into it renders marked, and a " +
-        "`FROM #draft` query still finds it"
-    );
-}
-
-/**
- * Refuse a note that declares `draft:` at all.
- *
- * Presence is the whole test. `draft: false` is as retired as `draft: true` —
- * it reads as "publish this note", which is what happens either way, and is
- * exactly the belief the message exists to correct.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
- *   could not be parsed.
- * @param {object} [options] - Options.
- * @param {string} [options.file] - The note's path, named in the message. Omit
- *   it where the caller emits through a diagnostic, which puts the locator at
- *   the start of the line already — repeating it prints the path twice.
- * @param {string} [options.absPath] - The note's file on disk, read only on the
- *   failing path to locate the offending line and column. The position rides on
- *   the thrown error as `position`, for a caller that emits a diagnostic.
- * @returns {void}
- * @throws {Error} When the note declares the field.
- */
-export function assertNoDraftField(fm, { file, absPath } = {}) {
-    if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "draft")) return;
-
-    const err = new Error(`${draftRetiredMessage(file)}.`);
-    // Where the field is, so the caller's diagnostic opens on the line that has
-    // to be deleted. Read here rather than carried through every walk: this is
-    // the failing path, and the build stops on it.
-    const position = locateFrontmatterKey(absPath, "draft");
-    if (position) err.position = position;
-    throw err;
-}
-
-/**
- * What a note declaring a top-level `aliases:` is told, in one place.
- *
- * Shared by the compile-time refusal and the frontmatter lint, because an
- * author meets whichever of the two runs first and they should read the same.
- * It says what the field fed and what to write instead, rather than which value
- * to correct: no value makes declaring it right.
- *
- * **What it did.** It was the authored half of the alias index — the
- * namespace a bare `[[Alias]]` was looked up in. Across the three content trees
- * not one bare link resolved through it, while the collision rule that kept it
- * unambiguous folded in every note's `name.full` and so dictated what a note
- * could be named. The form is retired, so the list has no reader.
- *
- * **`name.aliases` is a different field.** It lists alternate names in the
- * infobox and is deliberately unmentioned by this message. See
- * {@link assertNoAliasesField}.
- *
- * @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 aliasesRetiredMessage(file) {
-    return (
-        "`aliases:` is a retired frontmatter field — delete it" +
-        (file ? ` — ${file}` : "") +
-        ". It listed names the bare `[[Alias]]` form could cite, and that " +
-        "form is retired: every wikilink is now an address, written " +
-        "`[[type-shortcode|Text]]`. Nothing else ever read the list"
-    );
-}
-
-/**
- * Refuse a note that declares a top-level `aliases:`.
- *
- * Presence is the whole test. `aliases: []` is as retired as a populated one —
- * it reads as "this note claims no other names", a statement about a namespace
- * that no longer exists.
- *
- * **The nested `name.aliases` is deliberately not refused.** It is the note's
- * ordered alternate names and appears in the note infobox. It does not create
- * addresses or change how authored links resolve.
- *
- * That distinction is the reason this checks `Object.hasOwn(fm, "aliases")`
- * rather than resolving a dotted key: the top-level field is the whole subject,
- * and reaching into `name` at all is the thing being avoided.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
- *   could not be parsed.
- * @param {object} [options] - Options.
- * @param {string} [options.file] - The note's path, named in the message. Omit
- *   it where the caller emits through a diagnostic, which puts the locator at
- *   the start of the line already — repeating it prints the path twice.
- * @param {string} [options.absPath] - The note's file on disk, read only on the
- *   failing path to locate the offending line and column. The position rides on
- *   the thrown error as `position`, for a caller that emits a diagnostic.
- * @returns {void}
- * @throws {Error} When the note declares a top-level `aliases`.
- */
-export function assertNoAliasesField(fm, { file, absPath } = {}) {
-    if (!declaresRetiredAliasesField(fm)) return;
-
-    const err = new Error(`${aliasesRetiredMessage(file)}.`);
-    // Anchored at column 1: a permitted `name.aliases` writes the same key,
-    // indented, and a finding about the retired top-level field must never
-    // open on it.
-    const position = locateFrontmatterKey(absPath, "aliases", undefined, { topLevel: true });
-    if (position) err.position = position;
-    throw err;
-}
-
-/**
- * Whether a note declares the retired top-level `aliases:`.
- *
- * A nested `name.aliases` is **not** this field and never answers true here —
- * see {@link assertNoAliasesField} for why the two part company.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {boolean} Whether the retired field is declared.
- */
-export function declaresRetiredAliasesField(fm) {
-    return Boolean(fm) && typeof fm === "object" && Object.hasOwn(fm, "aliases");
-}
-
-/**
- * What a note declaring `section:` is told, in one place.
- *
- * Shared by the compile-time refusal and the frontmatter lint, because an
- * author meets whichever of the two runs first and they should read the same.
- * It names what lands a section now rather than a value to correct: no value
- * makes declaring the field right.
- *
- * **What it did.** It named the section a `collection` note headed,
- * under the `collection` landing rule — the only reader it ever had, in the
- * second branch of `landingOf` (`engine/content-address.mjs`). That rule went
- * first, and the whole mechanism went with it: a section is a Hugo
- * directory the note format does not carry, so no note lands one and a page
- * that introduces a type is an ordinary note addressed `doc-<type>`. Nothing
- * else read the field, and no schema or vocabulary declared it, so left in
- * place it would be ignored in silence — the note saying one thing and the
- * build doing another.
- *
- * @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 sectionRetiredMessage(file) {
-    return (
-        "`section:` is a retired frontmatter field — delete it" +
-        (file ? ` — ${file}` : "") +
-        ". It named the section a `collection` note headed, and both the rule " +
-        "and the sections it routed to are retired: a page that introduces " +
-        "the notes of a type is an ordinary note — `type: doc`, " +
-        "`subType: reference`, `shortcode: <type>` — addressed `doc-<type>`. " +
-        "Nothing else ever read the field"
-    );
-}
-
-/**
- * Refuse a note that declares `section:` at all.
- *
- * Presence is the whole test, as it is for `draft:` and `aliases:`: an empty
- * value reads as "this note heads a section and names none", a statement about
- * a rule that no longer exists.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
- *   could not be parsed.
- * @param {object} [options] - Options.
- * @param {string} [options.file] - The note's path, named in the message. Omit
- *   it where the caller emits through a diagnostic, which puts the locator at
- *   the start of the line already — repeating it prints the path twice.
- * @param {string} [options.absPath] - The note's file on disk, read only on the
- *   failing path to locate the offending line and column. The position rides on
- *   the thrown error as `position`, for a caller that emits a diagnostic.
- * @returns {void}
- * @throws {Error} When the note declares the field.
- */
-export function assertNoSectionField(fm, { file, absPath } = {}) {
-    if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "section")) return;
-
-    const err = new Error(`${sectionRetiredMessage(file)}.`);
-    // Anchored at column 1: a nested `section:` inside some other block is
-    // not this field — a finding about the top-level one must not open on it.
-    const position = locateFrontmatterKey(absPath, "section", undefined, { topLevel: true });
-    if (position) err.position = position;
-    throw err;
-}
-
-/**
- * What a note writing a top-level `traits:` block is told.
- *
- * The message states the **mapping**, not just the destination, because three
- * of the keys reshaped as well as moved: the block nested its measurements
- * where the format flattens them. A bare "write `data:` instead" would send an
- * author to author `data.height: {m: 1.78}`, which is a declared key holding an
- * undeclared shape.
- *
- * @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 traitsRetiredMessage(file) {
-    return (
-        "`traits:` is a retired frontmatter block — move it into `data:`" +
-        (file ? ` — ${file}` : "") +
-        ". A being's own description belongs in the closed container the " +
-        "content format declares, where `being` declares every one of its " +
-        "keys. " +
-        "`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`"
-    );
-}
-
-/**
- * Refuse a note that declares a top-level `traits:` block at all.
- *
- * Presence is the whole test, as it is for `draft:` and `aliases:`: an empty
- * `traits:` is still a note claiming a block that no longer exists.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
- *   could not be parsed.
- * @param {object} [options] - Options.
- * @param {string} [options.file] - The note's path, named in the message. Omit
- *   it where the caller emits through a diagnostic, which puts the locator at
- *   the start of the line already.
- * @param {string} [options.absPath] - The note's file on disk, read only on the
- *   failing path to locate the offending line and column. The position rides on
- *   the thrown error as `position`, for a caller that emits a diagnostic.
- * @returns {void}
- * @throws {Error} When the note declares the block.
- */
-export function assertNoTraitsField(fm, { file, absPath } = {}) {
-    if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "traits")) return;
-
-    const err = new Error(`${traitsRetiredMessage(file)}.`);
-    // Anchored at column 1. `sohl.traits` is a *different field that shares the
-    // name* — `projectilegear` declares one and the theme's gear sidebar reads
-    // it — so a finding about the top-level block must never open on it.
-    const position = locateFrontmatterKey(absPath, "traits", undefined, { topLevel: true });
-    if (position) err.position = position;
-    throw err;
-}
-
-/**
- * A frontmatter key's position in a note's file, or nothing.
- *
- * {@link positionInFrontmatter} answers the same question from the file's
- * *text*; this reads the file to ask it. Kept apart from either caller because
- * 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 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.
- * @param {object} [options] - Options, forwarded to
- *   {@link positionInFrontmatter}.
- * @param {boolean} [options.topLevel=false] - Require the key at column 1, so
- *   an identically named nested key cannot answer for 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, value = undefined, { topLevel = false } = {}) {
-    if (!absPath) return undefined;
-    let raw;
-    try {
-        raw = fs.readFileSync(absPath, "utf8");
-    } catch {
-        return undefined;
-    }
-    const at = positionInFrontmatter(raw, key, value, { topLevel });
-    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
- * `relation` is retired on an affiliation — which declares `relations` — and
- * remains an unknown key anywhere else.
- *
- * **`templatePriority`.** The number that decides which of several
- * competing templates the Create dialog offers was called `archetype`, and
- * `archetypes` — one letter apart — is a list of what *sort* a character is.
- * A priority and a taxonomy cannot be told apart by a plural `s`, so the
- * priority takes the name that says what it is. The specification already
- * called it `templatePriority` on two of its three sides.
- *
- * **`relations`.** The field holds a *map* of standings, one per
- * affiliation — its own description says so, and `resolveRelation` has always
- * read it that way. `relation` named the many as one, which every author had to
- * 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",
-});
-
-/**
- * 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`
-    );
-}
-
-/**
- * What a note writing a field at its **legacy in-block position** is told.
- *
- * The same three-step retirement `retiredAliasMessage` announces, applied to a
- * *position* rather than a spelling. A field whose shared source moved
- * under `data:` keeps reading the key its block still carries, that read wins,
- * and it is reported here so a sweep has something to count down — without it,
- * moving a field into `data:` would be a flag day across every repository that
- * authors it.
- *
- * It names the block, because the key is `hm3.species` and not `species`: an
- * author told to move "`species`" has two regions to guess between.
- *
- * @param {string} block - The system block the key was written in.
- * @param {{name?: string, legacyKey?: string}} field - The declaration, which
- *   names both positions.
- * @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 legacyKeyMessage(block, field, file) {
-    const legacy = `${block}.${field.legacyKey}`;
-    return (
-        `\`${legacy}:\` is the legacy position of the shared \`${field.name}:\` ` +
-        `— write it under \`data:\` instead` +
-        (file ? ` — ${file}` : "") +
-        `. Both are read and \`${legacy}\` wins, so the note compiles ` +
-        `identically either way; the in-block key is removed in a later release`
-    );
-}
-
-/**
- * What a note writing a field at the **top-level key `data:` gathered it off**
- * is told.
- *
- * {@link legacyKeyMessage}'s counterpart for the other retiring position.
- * `portrait:` beside `img:` is the bare spelling of `data.portrait`, and both
- * are read for the same reason both in-block spellings are: a package moves its
- * corpus when it is ready, not on a flag day.
- *
- * It says nothing about which value is emitted, because that is not what an
- * author needs from it. The value is the same either way; what the finding
- * counts is one more note still on the old position.
- *
- * @param {{name?: string}} field - The declaration, which names the current
- *   position; the retiring one is derived from it.
- * @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 retiredTopLevelMessage(field, file) {
-    const retiring = retiredTopLevelKey(field);
-    return (
-        `top-level \`${retiring}:\` is the pre-\`data:\` position of the shared ` +
-        `\`${field.name}:\` — move it under \`data:\` instead` +
-        (file ? ` — ${file}` : "") +
-        `. Both are read and \`${field.name}\` wins, so the note compiles ` +
-        `identically either way; the top-level key 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.
- * @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, { 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 &&
-        typeof block === "object" &&
-        !Array.isArray(block) &&
-        Object.hasOwn(block, retired);
-    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.
- *
- * 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: `relations:` cleared in an editor means the
- * note records no standings 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.
- * @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, { 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 ? read(retired) : undefined;
-}