@heroiclands/package-build 23.1.0 → 23.2.0

package/engine/content-links.mjs

@@ -27,9 +27,8 @@
  *    written target expands to exactly one canonical address, from the
  *    position's own defaults — the package it omits is always this one — so a
  *    lookup finds one entry or none. There is no candidate set to disambiguate.
- * 3. **An unlabelled link.** `[[x]]` addresses nothing: the alias namespace it
- *    once named is retired, and a shortcode is an address rather than
- *    prose, so the link has neither a resolvable target nor text to show. The
+ * 3. **An unlabelled link.** `[[x]]` addresses nothing: a shortcode is an address
+ *    rather than prose, so the link has neither a resolvable target nor text to show. The
  *    correction is always `[[type-shortcode|Text]]`.
  * 4. **A wikilink authored in frontmatter.** Both builds walk a note's *body*
  *    and copy frontmatter through verbatim, so a link written in a
@@ -47,7 +46,7 @@
  * **What this deliberately does not do.** Corpus reachability — "every rules
  * document is reachable from the book's root" — is a statement about what one
  * package publishes, not about the note format, so it belongs with the
- * publishing it describes; so does a retired hostname. Both are served by the
+ * publishing it describes; so does a withdrawn hostname. Both are served by the
  * link graph returned here rather than implemented here.
  *
  * @module
@@ -90,7 +89,6 @@ import {
 import { loadForeignIndexes, noContentIndexPackages } from "./metadata-index.mjs";
 import { frontmatterWikilinks, slugify } from "./web-wikilinks.mjs";
 import { homepageAddresses, isHomepage } from "./homepage.mjs";
-import { RETIRED_TYPES } from "./ids.mjs";
 import { parseWikilink, WIKILINK } from "./wikilink-syntax.mjs";
 import { readQualifier } from "./wikilinks.mjs";
 
@@ -120,8 +118,8 @@ export function anchorsOf(body) {
  * Read a content tree into the index a link resolves against.
  *
  * **The corpus comes from the content index, not from a walk of this module's
- * own**. Every pass used to answer "which files are the content?" for
- * itself and throw the answer away; this one now reads
+ * own**. Passes do not each answer "which files are the content?" for
+ * themselves; this one reads
  * {@link module:engine/content-index.indexRecordsFor}, which is the same
  * derivation the published artifact and the compilers are driven from. So a
  * note the index records is a note the link check sees, and the addresses and
@@ -167,8 +165,9 @@ export function buildLinkIndex(
     const frontmatterLinks = [];
 
     // The one package every note in this tree belongs to. Taken from the
-    // configuration this build resolved — never from a note (`package:` is
-    // retired, so there is no second source an address could disagree with)
+    // configuration this build resolved — never from a note (a note
+    // declares no package, so there is no second source an address could
+    // disagree with)
     // and never from the ambient one, which is a different configuration
     // whenever a test injects one, `PACKAGE_BUILD_CONFIG` names one, or the
     // command runs from a worktree.
@@ -379,6 +378,8 @@ export function buildLinkIndex(
                 target: u.target,
                 reason: u.reason,
                 ...(u.type ? { type: u.type } : {}),
+                ...(u.shortcode ? { shortcode: u.shortcode } : {}),
+                ...(u.declared ? { declared: u.declared } : {}),
             })),
             ...problems.map((problem) => ({
                 text: problem.link,
@@ -786,8 +787,6 @@ function readAddress(url, packages) {
  * **What is checkable, stated plainly.** Only an address into this site is, and
  * only against facts this build already holds:
  *
- * - A **retired content type** in the path. The engine knows the retired names
- *   and what replaced it, so this is a fact rather than a guess.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
  *   fetched index names. Every one of them has a better form to write, which
  *   is why every one is reported — including a bare `/<package>/`, which names
@@ -890,30 +889,6 @@ export function auditHomepageLinks(index) {
                             `relocation does not leave this page behind`,
                 );
             }
-
-            // The retired-type rule reads the path *inside* the package, so an
-            // address that named one is fixed the same way wherever it was
-            // written.
-            const inPackage = prefix ? segments.slice(1) : segments;
-            for (const [i, segment] of inPackage.entries()) {
-                // `hasOwn`, not a plain lookup: a path segment spelled
-                // `constructor` would otherwise inherit a truthy answer from
-                // `Object.prototype` and be reported as retired.
-                if (!Object.hasOwn(RETIRED_TYPES, segment)) continue;
-                const replacement = RETIRED_TYPES[segment];
-                const fixed = [...inPackage];
-                fixed[i] = replacement;
-                report(
-                    field,
-                    url,
-                    url,
-                    occurrence,
-                    `address "${url}" names content type "${segment}", ` +
-                        `retired in favour of "${replacement}" — both ` +
-                        `compiled to the same document, so the fix is ` +
-                        `mechanical: "${fixed.join("/")}/"`,
-                );
-            }
         }
     }
 
@@ -1015,6 +990,25 @@ export function auditLinks(index) {
                 deadAddresses.push({ ...at, reason: "not-an-address" });
                 continue;
             }
+            // A capital in the shortcode is refused, never lowercased. The
+            // lowercase spelling is looked up only to name it in the finding.
+            const cased = readQualifier(target, index.types, index.packages, index.noIndexPackages);
+            if (cased?.reason === "shortcode-not-lowercase") {
+                const lower = `${target.slice(0, -cased.shortcode.length)}${cased.lowercase.shortcode}`;
+                const declared =
+                    index.resolveAddress(lower) ?? index.stubAt?.(lower) ?? manifestHit(lower);
+                deadAddresses.push({
+                    ...at,
+                    reason: "shortcode-not-lowercase",
+                    shortcode: cased.shortcode,
+                    ...(declared ? { declared: cased.lowercase.shortcode } : {}),
+                });
+                continue;
+            }
+            if (cased?.reason === "not-lowercase") {
+                deadAddresses.push({ ...at, reason: "not-lowercase" });
+                continue;
+            }
             const resolved = index.resolveAddress(target);
             if (resolved) {
                 if ((isGmNote(resolved.fm) || resolved.gm) && !isGmNote(note.fm)) {

package/engine/content-lint.mjs

@@ -44,13 +44,12 @@
  * **There is deliberately no third rule** requiring every note to repeat its
  * own `type-shortcode` address in a top-level `aliases:` list. It would serve
  * no build reader: both resolvers parse the hyphen
- * qualifier themselves. The field is retired, refused from
- * `retired-fields.mjs`.
+ * qualifier themselves.
  *
  * **What is deliberately absent.** Corpus reachability — "every Rules document
  * is reachable from the book's root" — is a statement about what one package
  * publishes, not about the note format, and belongs with the publishing it
- * describes. So do retired hostnames.
+ * describes. So do withdrawn hostnames.
  *
  * @module
  */

package/engine/content-poetry.mjs

@@ -1,4 +1,15 @@
-/* SPDX-License-Identifier: GPL-3.0-or-later */
+/*
+ * 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
+ */
 
 /** The authored verse lines, excluding stanza separators. */
 export function verseLines(body) {

package/engine/content-slug.mjs

@@ -19,25 +19,13 @@
  * address, `type-shortcode`, derived in `engine/content-address.mjs` and
  * touching no display string at all.
  *
- * It is not the other way round: a `contentSlug` here that
- * derived a page's URL from `name.full`, abbreviating it through a table of 200
- * words so the result stayed short, and a `findSlugCollisions` to catch the two
- * notes that would then claim one URL. Its own header justified the readability
- * cost with a rename-survival story — *"every change appends to the legacy-URL
- * map, which emits a redirect"* — and no such map was ever written, in this
- * package or in any consumer. So a rename silently 404'd every existing link,
- * a display string was load-bearing, and a uniqueness check was needed to keep
- * it correct. An address has none of those properties, so all three went.
- *
- * What is left is the normalisation the rest of the build still needs, in the
- * two places it was always right for:
+ * The normalisation applies in two places:
  *
  * - **heading anchors**, where an author writes the matching key by hand — a map
  *   note pins `locations.stair-foot` at a heading called *Stair Foot*;
  * - **pack filenames**, read back only by the unpacker.
  *
- * Neither is abbreviated, and neither ever was: abbreviation existed solely to
- * shorten a name-derived URL, so it left with it.
+ * Neither is abbreviated.
  *
  * What the rule does, and why:
  *

package/engine/content-spans.mjs

@@ -1,4 +1,16 @@
-/* SPDX-License-Identifier: GPL-3.0-or-later */
+/*
+ * 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
+ */
+
 import MarkdownIt from "markdown-it";
 import { alertMarkdownPlugin } from "./content-alerts.mjs";
 import { slugify } from "./content-slug.mjs";

package/engine/content-tables.mjs

@@ -1,4 +1,15 @@
-/* SPDX-License-Identifier: GPL-3.0-or-later */
+/*
+ * 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
+ */
 
 import { FENCE_LINE } from "./code-fences.mjs";
 import { PAGE_LIST_LANGUAGE } from "./page-lists.mjs";

package/engine/culture-choice.mjs

@@ -1,32 +1,229 @@
-/* SPDX-License-Identifier: GPL-3.0-or-later */
+/*
+ * 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
+ */
+
+/**
+ * `data.culture`: the people a note belongs to, named as a `lore` note of
+ * `subType: culture`.
+ *
+ * One declaration serves every type that takes the field. Where a type's
+ * subtypes differ on it — a setting guide requires it, other `doc` genres
+ * refuse it, and a culture note names only itself — {@link checkCultureSubType}
+ * scopes it, because
+ * `DataFieldSpec` declares the keys a type accepts and not the subType that may
+ * write them.
+ *
+ * @module
+ */
+
+import {
+    canonicalKey,
+    isAddressTuple,
+    ownDocumentSystem,
+    parseAddress,
+    renderAddress,
+} from "./address.mjs";
+import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/** The `lore` subType a culture names, and the one whose culture is itself. */
+const CULTURE_SUBTYPE = "culture";
+
+/** The `doc` subType that requires a culture; every other `doc` subType refuses it. */
+const SETTING_GUIDE_SUBTYPE = "settingguide";
+
+/**
+ * The Address a `data.culture` value names, read against the defaults of the
+ * position it is written in.
+ *
+ * @param {unknown} value - The value as written, or an already decoded tuple.
+ * @param {object} [index] - The link index, for the package and vocabularies.
+ * @returns {object} The tuple, or the parser's problem.
+ */
+function cultureAddress(value, index) {
+    return parseAddress(value, {
+        package: index?.contentPackage,
+        system: "note",
+        type: "lore",
+        types: index?.types,
+        packages: index?.packages,
+    });
+}
 
-import { isAddressTuple, parseAddress, renderAddress } from "./address.mjs";
-import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+/**
+ * Whether a `data.culture` value names the note that carries it.
+ *
+ * The comparison is between canonical Addresses, so a culture note's shortcode,
+ * any longer form of its Address and a decoded tuple all name it alike. A note
+ * with no shortcode has no Address to compare against and names nothing.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {unknown} value - The `data.culture` value, as written or decoded.
+ * @param {object} [index] - The package and vocabularies a written value is
+ *   read against, and the package the note's own Address is in.
+ * @returns {boolean} Whether the value is the note's own Address.
+ */
+export function cultureNamesItself(fm, value, index) {
+    const shortcode = fm?.shortcode;
+    const type = String(fm?.type ?? "").toLowerCase();
+    if (typeof shortcode !== "string" || !shortcode.trim() || !type) return false;
+    if (value === undefined || value === null) return false;
+    const tuple = cultureAddress(value, index);
+    if (tuple.reason) return false;
+    return (
+        renderAddress(tuple) ===
+        canonicalKey(index?.contentPackage, ownDocumentSystem(type), type, shortcode.trim())
+    );
+}
 
 /**
- * Require a being's primary culture to address a culture lore note.
+ * Whether a note is a `lore` note of `subType: culture`.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @returns {boolean} Whether it is a culture note.
+ */
+function isCultureNote(note) {
+    return (
+        String(note?.type ?? note?.fm?.type ?? "").toLowerCase() === "lore" &&
+        String(note?.fm?.subType ?? "").toLowerCase() === CULTURE_SUBTYPE
+    );
+}
+
+/**
+ * Require a note's `data.culture` to address a culture lore note.
+ *
+ * A value that is not a `lore` Address, or names nothing, is left to the
+ * reference check, which reports it in its own terms. A culture note's own
+ * value is {@link checkCultureSubType}'s to judge, since it names only the note
+ * itself.
+ *
  * @param {object} note
  * @param {{index?: object}} [options]
+ * @returns {object[]} One error at the value when it names lore of another subType.
  */
 export function checkCultureChoice(note, { index } = {}) {
     const value = note.fm?.data?.culture;
     if (value === undefined || value === null || !index?.addressHit) return [];
-    const tuple = parseAddress(value, {
-        package: index.contentPackage,
-        system: "note",
-        type: "lore",
-        types: index.types,
-        packages: index.packages,
-    });
+    if (isCultureNote(note)) return [];
+    const tuple = cultureAddress(value, index);
     if (tuple.reason || tuple.type !== "lore") return [];
     const target = index.addressHit(renderAddress(tuple));
-    if (!target || (target.fm ?? target).subType === "culture") return [];
+    if (!target || (target.fm ?? target).subType === CULTURE_SUBTYPE) return [];
+    const type = String(note.type ?? note.fm?.type ?? "note");
+    const article = /^[aeiou]/i.test(type) ? "an" : "a";
     return [
         {
             file: note.file,
             ...positionOfFrontmatterPath(note.raw ?? "", ["data", "culture"]),
             severity: "error",
-            message: `data.culture ${isAddressTuple(value) ? renderAddress(value) : value} names lore whose subType is not culture`,
+            message:
+                `data.culture ${isAddressTuple(value) ? renderAddress(value) : value} names lore ` +
+                `whose subType is not culture; ${article} ${type}'s culture is a culture lore note`,
         },
     ];
 }
+
+/**
+ * The `data.culture` field, declared once and spread into each type that takes
+ * it. A type gives its own `describe` where the field means something narrower
+ * there.
+ *
+ * @type {Readonly<object>}
+ */
+export const CULTURE_FIELD = Object.freeze({
+    name: "culture",
+    shape: "an Address",
+    kind: "address",
+    ref: "lore",
+    accepts: Object.freeze(["lore"]),
+    check: checkCultureChoice,
+    describe: "The people this note belongs to, as a culture lore note.",
+});
+
+/**
+ * Scope `data.culture` to the subtypes that take it.
+ *
+ * A `doc` of `subType: settingguide` introduces one culture's setting and must
+ * name it; a missing value is an error at the `subType:` line. Every other `doc`
+ * subType refuses a written value, as an error at the key.
+ *
+ * A `lore` note of `subType: culture` is itself the culture. It may omit the
+ * field or name itself, in any form the Address parser reads; a value naming any
+ * other Address is an error at the value. A note with no shortcode has no
+ * Address to compare against, and the shortcode check reports it.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {{index?: object}} [options] - The link index, for the package and
+ *   vocabularies a written value is read against.
+ * @returns {object[]} Findings.
+ */
+export function checkCultureSubType(note, { index } = {}) {
+    const type = String(note?.type ?? note?.fm?.type ?? "").toLowerCase();
+    const subType = String(note?.fm?.subType ?? "").toLowerCase();
+    const data = note?.fm?.data;
+    const written =
+        data !== null &&
+        typeof data === "object" &&
+        !Array.isArray(data) &&
+        data.culture !== undefined &&
+        data.culture !== null;
+    const atKey = (message) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(note.raw ?? "", ["data", "culture"], { key: true }),
+        severity: "error",
+        message,
+    });
+
+    if (type === "doc") {
+        if (subType === SETTING_GUIDE_SUBTYPE) {
+            if (written) return [];
+            return [
+                {
+                    file: note.file,
+                    ...positionInFrontmatter(note.raw ?? "", "subType", undefined, {
+                        topLevel: true,
+                    }),
+                    severity: "error",
+                    message:
+                        "a setting guide introduces one culture, so this note must state " +
+                        "`data.culture`, naming a culture lore note",
+                },
+            ];
+        }
+        if (!written) return [];
+        return [
+            atKey(
+                `\`data.culture\` is stated by a setting guide, and this note's \`subType\` ` +
+                    `is not \`${SETTING_GUIDE_SUBTYPE}\``,
+            ),
+        ];
+    }
+
+    if (type === "lore" && subType === CULTURE_SUBTYPE && written) {
+        const shortcode = note.fm?.shortcode;
+        if (typeof shortcode !== "string" || !shortcode.trim()) return [];
+        const value = data.culture;
+        if (cultureAddress(value, index).reason) return [];
+        if (cultureNamesItself({ ...note.fm, type }, value, index)) return [];
+        return [
+            {
+                file: note.file,
+                ...positionOfFrontmatterPath(note.raw ?? "", ["data", "culture"]),
+                severity: "error",
+                message:
+                    `data.culture ${isAddressTuple(value) ? renderAddress(value) : value} ` +
+                    `names another note; a culture note's data.culture names the note itself`,
+            },
+        ];
+    }
+
+    return [];
+}

package/engine/data-keys.mjs

@@ -57,7 +57,7 @@ import { nearest } from "./near-miss.mjs";
  * @property {string} name - The key as an author writes it.
  * @property {string} [kind] - Its value's shape: `string`, `date`, `number`,
  *   `integer`, `boolean`, `address`, `list`, `map`, `scalar-or-map`,
- *   `list-or-map` or `string-or-list` — see {@link fitsKind}. Absent, the check
+ *   or `string-or-list` — see {@link fitsKind}. Absent, the check
  *   makes no claim about the value.
  * @property {readonly string[]} [allowed] - The closed set a present value is
  *   one of, where the key takes a fixed word.
@@ -143,8 +143,6 @@ export function fitsKind(value, kind) {
             );
         case "scalar-or-map":
             return isScalar(value) || fitsKind(value, "map");
-        case "list-or-map":
-            return Array.isArray(value) || fitsKind(value, "map");
         case "string-or-list":
             return isScalar(value) || Array.isArray(value);
         default:
@@ -287,21 +285,25 @@ export function checkDataKeys(note, fields) {
             );
             return;
         }
-        if (spec.allowed && !spec.allowed.includes(value)) {
-            const guess = typeof value === "string" ? nearest(value, spec.allowed) : undefined;
-            findings.push(
-                finding(
-                    path,
-                    `\`${pathLabel(path)}\` should be ${spec.allowed.map((word) => `\`${word}\``).join(" or ")}, ` +
-                        `but reads ${JSON.stringify(value)}` +
-                        (guess ? `. Did you mean "${guess}"?` : ""),
-                ),
-            );
-            return;
-        }
+        if (!inAllowed(spec, value, path)) return;
         walk(spec, value, path);
     };
 
+    /** Whether a present value is in the spec's closed set, if it has one; else a finding. */
+    const inAllowed = (spec, value, path) => {
+        if (!spec.allowed || spec.allowed.includes(value)) return true;
+        const guess = typeof value === "string" ? nearest(value, spec.allowed) : undefined;
+        findings.push(
+            finding(
+                path,
+                `\`${pathLabel(path)}\` should be ${spec.allowed.map((word) => `\`${word}\``).join(" or ")}, ` +
+                    `but reads ${JSON.stringify(value)}` +
+                    (guess ? `. Did you mean "${guess}"?` : ""),
+            ),
+        );
+        return false;
+    };
+
     /** Close one map to its declared keys, and walk each that is present. */
     const closeMap = (inner, value, path) => {
         const names = inner.map((spec) => spec.name);
@@ -341,7 +343,8 @@ export function checkDataKeys(note, fields) {
         // A dotted group's own shape is checked here: the container check
         // reads its members' leaves and has nothing to say about the group.
         if (spec.grouped) visit(spec, value, path);
-        else if (fitsKind(value, spec.kind)) walk(spec, value, path);
+        else if (fitsKind(value, spec.kind) && inAllowed(spec, value, path))
+            walk(spec, value, path);
     }
     return findings;
 }

package/engine/date-conversion.mjs

@@ -1,4 +1,15 @@
-/* SPDX-License-Identifier: GPL-3.0-or-later */
+/*
+ * 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
+ */
 
 import { eraYear, formatCanonicalDate, parseCanonicalDate } from "./calendars.mjs";
 import { addressedCalendarDate } from "./calendar-human.mjs";

package/engine/declaration-check.mjs

@@ -1,4 +1,13 @@
 /*
+ * 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
  */
 

package/engine/derived-fields.mjs

@@ -15,16 +15,16 @@
  * `system` keys a note may **never** author, because the *compiler* writes them
  * from the note itself.
  *
- * The third of three refusals that read alike and state different facts:
+ * The companion of `runtime-only-fields.mjs`, and the two state different
+ * facts:
  *
  * | module | refuses a field | because |
  * | --- | --- | --- |
- * | `retired-fields.mjs` | a note may no longer declare | it has been withdrawn |
  * | `runtime-only-fields.mjs` | a note never could | the *document* writes it in play |
  * | this one | a note never could | the *compiler* writes it, from the note |
  *
- * The distinction between the last two is where the value comes from, and it
- * decides what an author is told. A runtime-only field has no compile-time
+ * The distinction is where the value comes from, and it decides what an author
+ * is told. A runtime-only field has no compile-time
  * value at all, so the fix is to delete the key. A derived one **does** have a
  * compile-time value — it is already being written, from somewhere else in the
  * same note — so the fix is to move the content to wherever the compiler reads
@@ -54,7 +54,7 @@
  */
 
 import { getFrontmatter } from "./frontmatter.mjs";
-import { locateFrontmatterKey } from "./retired-fields.mjs";
+import { locateFrontmatterKey } from "./diagnostics.mjs";
 import { SYSTEM_DATA_KEY, systemData } from "./system-block.mjs";
 
 /**
@@ -88,8 +88,7 @@ export function derivedMessage(key, from, file) {
 /**
  * The derived keys a note actually writes, in declaration order.
  *
- * **Presence is the whole test**, as it is for a retired or a runtime-only
- * field: an authored empty string is as much a claim on the key as prose is,
+ * **Presence is the whole test**, as it is for a runtime-only field: an authored empty string is as much a claim on the key as prose is,
  * and it is the same belief the message exists to correct. So the question is
  * whether the path resolves to anything at all, never whether the value is a
  * usable one.

package/engine/diagnostics.mjs

@@ -42,6 +42,7 @@
  *   which would send a reader to the frontmatter every time.
  */
 
+import fs from "node:fs";
 import path from "node:path";
 import YAML, { LineCounter } from "yaml";
 
@@ -183,10 +184,8 @@ export function positionInBody(body, offset, { bodyLine = 1, bodyColumn = 1, lin
  * The key match tolerates leading whitespace by default, so a nested key of the
  * same name answers when no top-level one is present — which is usually what a
  * reader wants, the key being unique in nearly every note. Pass `topLevel` where
- * it is not: `aliases` is both a retired top-level field and a **permitted**
- * `name.aliases`, and a finding about the first must never open on the
- * second, which would tell an author to delete a field they are allowed to
- * write.
+ * it is not: a finding about a top-level key must never open on a nested key
+ * of the same name.
  *
  * @param {string} raw - The file's full contents, frontmatter included.
  * @param {string} key - The top-level frontmatter key.
@@ -235,6 +234,37 @@ export function positionInFrontmatter(raw, key, value = undefined, { topLevel =
     };
 }
 
+/**
+ * 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.
+ *
+ * @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;
+}
+
 /** Escape a literal for use inside a `RegExp`. */
 function escape(literal) {
     return String(literal).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");