@heroiclands/package-build 17.1.0 → 18.0.0

package/engine/frontmatter-lint.mjs

@@ -55,8 +55,9 @@
  * @module
  */
 
-import { authoredFields } from "./field-spec.mjs";
+import { authoredFields, readsLegacyKey } from "./field-spec.mjs";
 import {
+    legacyKeyOf,
     resolveFieldValue,
     systemBlock,
     SYSTEM_BLOCK_KEYS,
@@ -64,8 +65,12 @@ import {
 } from "./system-block.mjs";
 import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
-import { RETIRED_TYPES } from "./ids.mjs";
+import { RETIRED_TYPES, RENAMED_TYPES, currentType, renamedTypeMessage } from "./ids.mjs";
 import { isAddressSegment } from "./address-charset.mjs";
+// The one place the "every pack not named" key is spelled. Imported rather
+// than repeated, because a linter holding its own copy of what the compiler
+// reads is exactly the disagreement #288 was.
+import { DEFAULT_PARENT } from "./folder-notes.mjs";
 import { declaredTags, subTypeCharsetMessage, typeCharsetMessage } from "./note-vocabulary.mjs";
 import {
     RETIRED_FIELD_ALIASES,
@@ -73,9 +78,11 @@ import {
     aliasesRetiredMessage,
     declaresRetiredAliasesField,
     draftRetiredMessage,
+    legacyKeyMessage,
     readAliasedField,
     retiredAliasMessage,
     sectionRetiredMessage,
+    traitsRetiredMessage,
 } from "./retired-fields.mjs";
 
 /**
@@ -106,7 +113,9 @@ import {
  *
  * @type {ReadonlySet<string>}
  */
-export const UNIVERSAL_KEYS = Object.freeze(new Set(["folder", "pack", "archetype", "kbcat"]));
+export const UNIVERSAL_KEYS = Object.freeze(
+    new Set(["folder", "packFolder", "pack", "archetype", "templatePriority", "kbcat"]),
+);
 
 /**
  * The system blocks a build checks, and what each accepts beyond the shared
@@ -215,11 +224,33 @@ export function matchesKind(value, kind) {
                 (typeof value === "object" && value !== null && !Array.isArray(value)) ||
                 (Array.isArray(value) && value.length === 0)
             );
+        case "scalar-or-map":
+            // A scalar, or a map of them. The map's *entries* are checked
+            // separately, by the caller that can name the key at fault; all
+            // this answers is whether the value has one of the two shapes the
+            // field admits. A list has neither.
+            return matchesKind(value, "string") || matchesKind(value, "map");
         default:
             return true;
     }
 }
 
+/**
+ * The entries of a `scalar-or-map` value written in its map form, or `null`
+ * where it was written as the scalar.
+ *
+ * The empty-list spelling of an emptied map ({@link matchesKind}) has no
+ * entries, so it reads the same as `{}` here too.
+ *
+ * @param {unknown} value - The authored value.
+ * @returns {Record<string, unknown>|null} Its entries, or `null` for a scalar.
+ */
+function mapEntries(value) {
+    if (Array.isArray(value)) return value.length === 0 ? {} : null;
+    if (typeof value !== "object" || value === null) return null;
+    return /** @type {Record<string, unknown>} */ (value);
+}
+
 /**
  * The `data:` container a note authored.
  *
@@ -260,9 +291,14 @@ function dataBlock(fm) {
  * @param {object} opts
  * @param {string} opts.type - The note's type, for the message.
  * @param {readonly object[]} opts.fields - The type's `data:` declaration.
+ * @param {readonly string[]} [opts.packs] - The pack names this package
+ *   declares, against which a `keys: "pack"` map's keys are checked. Absent,
+ *   no claim is made about them: a caller that cannot see the configuration
+ *   knows no pack names, and reporting every key as unknown because nothing
+ *   was loaded to recognise it would be worse than not checking.
  * @returns {object[]} Findings.
  */
-function checkDataContainer(note, { type, fields }) {
+function checkDataContainer(note, { type, fields, packs }) {
     const findings = [];
     const { present, entries, malformed } = dataBlock(note.fm ?? {});
     if (!present) return findings;
@@ -306,13 +342,91 @@ function checkDataContainer(note, { type, fields }) {
             value = value && typeof value === "object" ? value[segment] : undefined;
         }
         if (value === undefined || value === null) continue;
-        if (matchesKind(value, field.kind)) continue;
+        if (!matchesKind(value, field.kind)) {
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(raw, ["data", ...segments]),
+                severity: "error",
+                message:
+                    `\`data.${field.name}\` should be ${field.shape ?? field.kind}, ` +
+                    `but reads ${JSON.stringify(value)}`,
+            });
+            continue;
+        }
+        // A `scalar-or-map` written in its map form is checked entry by entry,
+        // because that is the correction an author has to make: one key's
+        // value, not the whole map. Quoting the map back would name every
+        // entry that is right alongside the one that is not.
+        const written = field.kind === "scalar-or-map" ? mapEntries(value) : null;
+        if (written) {
+            findings.push(
+                ...checkKeyedMap(note, { field, segments, entries: written, raw, packs }),
+            );
+        }
+    }
+
+    return findings;
+}
+
+/**
+ * Check one `scalar-or-map` field written in its map form, entry by entry.
+ *
+ * Two separate statements are checked, and they fail independently: whether a
+ * key names something — a pack, for `keys: "pack"` — and whether the value
+ * under it has the shape one entry is declared to have. A key nobody declares
+ * is not a harmless surplus: the compiler asks the map for the pack it is
+ * compiling and takes `default` when there is no such key, so a mistyped
+ * `journal:` silently files the folder wherever the default puts it, which is
+ * exactly the hierarchy the author wrote the key to override.
+ *
+ * @param {object} note - The note.
+ * @param {object} opts
+ * @param {object} opts.field - The field's declaration.
+ * @param {readonly string[]} opts.segments - Its path under `data:`.
+ * @param {Record<string, unknown>} opts.entries - The map's entries.
+ * @param {string} opts.raw - The note's raw text, for positions.
+ * @param {readonly string[]} [opts.packs] - The declared pack names, if known.
+ * @returns {object[]} Findings, one per offending entry.
+ */
+function checkKeyedMap(note, { field, segments, entries, raw, packs }) {
+    const findings = [];
+    const known = field.keys === "pack" && packs?.length ? new Set(packs) : undefined;
+
+    for (const [key, value] of Object.entries(entries)) {
+        const path = ["data", ...segments, key];
+        const named = `data.${field.name}.${key}`;
+
+        // `default` is the map's own key for "every pack not named", not a
+        // pack — spelled out rather than left as an absent key, so a map
+        // stating only exceptions still reads as a complete answer (#276).
+        if (known && key !== DEFAULT_PARENT && !known.has(key)) {
+            const guess = nearest(key, known);
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(raw, path, { key: true }),
+                severity: "error",
+                message:
+                    `"${key}" is not a pack this package declares, so ` +
+                    `\`${named}\` states a hierarchy nothing reads` +
+                    (guess ? `. Did you mean "${guess}"?` : ""),
+            });
+            continue;
+        }
+
+        // An explicit `~` under a key is a statement, not an omission: it says
+        // "at the root there", which is different from saying nothing.
+        if (value === undefined || value === null) continue;
+        if (matchesKind(value, "string")) continue;
         findings.push({
             file: note.file,
-            ...positionOfFrontmatterPath(raw, ["data", ...segments]),
+            // On the key, not the value: an entry whose value is itself a map
+            // begins on the *next* line, so pointing at the value lands a
+            // reader inside the thing that is wrong rather than on the entry
+            // the message names.
+            ...positionOfFrontmatterPath(raw, path, { key: true }),
             severity: "error",
             message:
-                `\`data.${field.name}\` should be ${field.shape ?? field.kind}, ` +
+                `\`${named}\` should be ${field.entryShape ?? "a scalar"}, ` +
                 `but reads ${JSON.stringify(value)}`,
         });
     }
@@ -554,7 +668,7 @@ function checkEmbeddedShortcodes(note, blockName) {
             :   entry.shortcode;
         if (!type || !key) return;
 
-        const address = `${type}${key}`;
+        const address = `${type}/${key}`;
         const first = claimed.get(address);
         if (first === undefined) {
             claimed.set(address, index);
@@ -598,9 +712,16 @@ function checkEmbeddedShortcodes(note, blockName) {
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check, and what each accepts. See
  *   {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {readonly string[]} [opts.packs] - The pack names this package
+ *   declares, for a `data:` field whose map is keyed by pack. Supplied by the
+ *   caller like `schemas` and `vocabulary`, and absent it no claim is made
+ *   about those keys.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_SYSTEM_BLOCKS }) {
+export function lintNote(
+    note,
+    { schemas, index, vocabulary, packs, systems = DEFAULT_SYSTEM_BLOCKS },
+) {
     const findings = [];
     const fm = note.fm ?? {};
     const type = String(fm.type ?? "");
@@ -657,6 +778,29 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
     // harmless. Whether `title: ""` deserves a warning of its own is a separate
     // question about the *page's* heading, still open on #218, and not settled
     // by extending an art-path check to it.
+    // The template priority is a *shared source* — the specification states it
+    // once for every type, as it does `pack` — so its retirement is reported
+    // here rather than by the per-type loop below, which only reaches a field
+    // some type's vocabulary declares (#266).
+    if (declaresRetiredAlias(fm, "templatePriority")) {
+        findings.push({
+            file: note.file,
+            ...at(RETIRED_FIELD_ALIASES.templatePriority),
+            // An error, unlike the other retired alias. `archetype` is not
+            // a field of its own — it is `templatePriority` under its prior
+            // name, and both sit one letter from `archetypes`, which means
+            // something else entirely. A tree still on it is one where a
+            // priority and a taxonomy are told apart by a plural `s`, which
+            // is worth stopping rather than mentioning. This reds every
+            // tree until each is swept; that is the point.
+            severity: "error",
+            message: retiredAliasMessage(
+                RETIRED_FIELD_ALIASES.templatePriority,
+                "templatePriority",
+            ),
+        });
+    }
+
     for (const key of ART_FIELDS) {
         if (authoredValue(fm, key) !== "") continue;
         findings.push({
@@ -670,6 +814,29 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
                 "meant to have no image",
         });
     }
+    // `title: ""` publishes a blank heading (#218). The rule the art fields
+    // follow — `null` falls back, `""` is blank on purpose — reads the same way
+    // here, and for a *page heading* the deliberate blank is almost never what
+    // anyone wants: the emitter is `fm.title ?? name`, so `""` survives, the
+    // page publishes with no name, and it sorts to the front of its section
+    // landing ahead of every named page. Fifteen notes in `sohl-thalorna` are
+    // in exactly that state.
+    //
+    // A warning rather than an error: the value is legal under the rule, and a
+    // note that genuinely wants no heading may keep it — it just has to mean it.
+    if (authoredValue(fm, "title") === "") {
+        findings.push({
+            file: note.file,
+            ...at("title"),
+            severity: "warning",
+            message:
+                '`title: ""` publishes a page with no heading, which sorts to ' +
+                "the front of its section ahead of every named page. Write " +
+                "`title: null` to fall back to `name.full`, or give the page a " +
+                'heading; keep `""` only where the blank is meant',
+        });
+    }
+
     if (Object.hasOwn(fm, "draft")) {
         findings.push({
             file: note.file,
@@ -689,6 +856,18 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
             message: sectionRetiredMessage(),
         });
     }
+    // Anchored at column 1 for the same reason `section` is, and with more at
+    // stake: `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 retired top-level block must never open on it (#291).
+    if (Object.hasOwn(fm, "traits")) {
+        findings.push({
+            file: note.file,
+            ...positionInFrontmatter(raw(), "traits", undefined, { topLevel: true }),
+            severity: "error",
+            message: traitsRetiredMessage(),
+        });
+    }
     // Only the top-level `aliases` is retired. `name.aliases` writes the same
     // key indented under `name:` and is **permitted** — reserved and unread —
     // so both the test and the locator are anchored at column 1 (#180).
@@ -753,7 +932,27 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
         return findings;
     }
 
-    const schema = schemas[type];
+    // A **renamed** type is the opposite case, and the opposite answer: the
+    // note compiles into exactly the document it always did, so refusing it
+    // would fail a build over a note that is not wrong. It is reported, and
+    // every lookup below reads the current spelling (#78).
+    const renamedTo = RENAMED_TYPES[type];
+    if (renamedTo) {
+        findings.push({
+            file: note.file,
+            ...at("type", type),
+            // A warning, for the reason the retired *field* alias below is one:
+            // the sweep is the content trees' work and the refusal comes after
+            // it, as `package:`'s did (#56).
+            severity: "warning",
+            message: renamedTypeMessage(type, renamedTo),
+        });
+    }
+    // What every type-keyed table is keyed by. The authored spelling is still
+    // what a message quotes — it is what the reader has in front of them.
+    const current = currentType(type);
+
+    const schema = schemas[current];
     if (!schema) {
         findings.push({
             file: note.file,
@@ -771,15 +970,22 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
     // one this type may write. Skipped entirely when the caller declares no
     // vocabulary — reporting every key as unknown because nothing was loaded
     // to recognise it would be worse than not checking.
-    const entry = vocabulary?.[type];
+    const entry = vocabulary?.[current];
     if (entry) {
-        findings.push(...checkDataContainer(note, { type, fields: entry.data ?? [] }));
+        findings.push(...checkDataContainer(note, { type, fields: entry.data ?? [], packs }));
         findings.push(...checkSubType(note, { type, entry }));
     }
 
     const fields = authoredFields(schema);
-    /** First segment of each declared name — `impact.die` is authored as `impact`. */
-    const declared = new Set(fields.map((f) => f.name.split(".")[0]));
+    /**
+     * First segment of the key each field is authored at **inside the block** —
+     * `impact.die` is authored as `impact`, and a field whose shared source
+     * moved under `data:` is authored at the `legacyKey` it declares rather
+     * than at its dotted name (#305). Keying this on the name would report
+     * `sohl.species` as a property no `being` has, against exactly the notes
+     * the sweep has not reached yet.
+     */
+    const declared = new Set(fields.map((f) => legacyKeyOf(f).split(".")[0]));
 
     // The retired spelling of a field this type declares → what to write now.
     // Built from the type's own vocabulary, so a renamed field is retired
@@ -865,11 +1071,28 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
                 from = "block";
             }
         }
+        // The sweep's progress signal (#305). A **warning**, for the reason a
+        // retired spelling is one: the note compiles to the correct document,
+        // so failing a build over it would red a tree that has done nothing
+        // wrong yet. The refusal comes once no tree writes the position.
+        if (readsLegacyKey(field, from)) {
+            findings.push({
+                file: note.file,
+                ...at(legacyKeyOf(field)),
+                severity: "warning",
+                message: legacyKeyMessage("sohl", field),
+            });
+        }
         const absent = from === "default" || value === undefined || value === null;
         // Where the field belongs, as a message names it: a shared field is not
         // under `sohl:`, so telling an author to write `sohl.img` would send
-        // them to the wrong region.
-        const label = field.shared ? `\`${field.name}\`` : `\`sohl.${field.name}\``;
+        // them to the wrong region. Nor is a field whose shared source is a
+        // path into `data:` — `sohl.data.species` is a region that does not
+        // exist, and the home of that field is the container it names (#305).
+        const label =
+            field.shared || (field.name.includes(".") && field.legacyKey !== undefined) ?
+                `\`${field.name}\``
+            :   `\`sohl.${field.name}\``;
 
         if (field.required && absent) {
             findings.push({
@@ -896,7 +1119,7 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
 
         // A reference names another note by shortcode. Resolved through the
         // link index's own resolver, so a cross-package reference answered by a
-        // vendored manifest lands exactly as the same address in a wikilink
+        // fetched index lands exactly as the same address in a wikilink
         // would — rather than through a second, subtly different rule.
         //
         // **As an address, always** — which is now the only namespace there
@@ -914,7 +1137,7 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
                     severity: "error",
                     message:
                         `${label} names ${field.ref} ` +
-                        `"${value}", and no note or vendored manifest declares it`,
+                        `"${value}", and no note or fetched index declares it`,
                 });
             }
         }
@@ -934,10 +1157,12 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
  * @param {boolean} [opts.references=true] - Whether to check references.
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {readonly string[]} [opts.packs] - The declared pack names; see
+ *   {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index, { schemas, vocabulary, references = true, systems }) {
+export function lintFrontmatter(index, { schemas, vocabulary, packs, references = true, systems }) {
     const findings = [];
     const notes = [...index.notes].sort((a, b) =>
         a.file < b.file ? -1
@@ -949,6 +1174,7 @@ export function lintFrontmatter(index, { schemas, vocabulary, references = true,
             ...lintNote(note, {
                 schemas,
                 vocabulary,
+                packs,
                 index: references ? index : undefined,
                 ...(systems ? { systems } : {}),
             }),

package/engine/frontmatter.mjs

@@ -64,6 +64,46 @@ export function sohlField(fm, key, defaultValue = undefined) {
     return getFrontmatter(fm, key, defaultValue);
 }
 
+/**
+ * Read a `sohl:` field, seeing the **destination** position as well (#126).
+ *
+ * Five declarations resolve their value by re-reading the note rather than by
+ * taking the one {@link module:engine/system-block.resolveFieldValue} handed
+ * them — `subType`, `charges`, a mystery's `skillAptitudes`, an affiliation's
+ * `relations` and a projectile's impact die — because each validates a *shape
+ * spread over several keys* rather than coercing one scalar.
+ *
+ * That was equivalent while every note authored inside the block, and stopped
+ * being so once a note may author at `sohl.system.<to>` instead: {@link
+ * sohlField} sees `sohl.<key>` and the top level, never inside `sohl.system`.
+ * So those five read as unset and shipped their empty value — a missing
+ * `subType` is a thrown build error, and the other four ship empty in silence,
+ * which is the failure class the passthrough exists to prevent.
+ *
+ * The **destination wins**, matching every other field's resolution order.
+ *
+ * `legacyKey` is for the one pair whose two positions are spelled differently:
+ * a projectile authors `impact.die` and stores `impactBase.die`, so the reader
+ * has to be told both. It is the same split `FieldSpec.name`/`legacyKey` makes
+ * (#305), for the same reason — one name cannot key two positions.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} to - The key at the destination, dotted for a nested one.
+ * @param {any} [defaultValue] - What an unauthored field reads as.
+ * @param {object} [options] - Options.
+ * @param {string} [options.legacyKey] - The key the block still carries, when
+ *   it is not spelled `to`. Defaults to `to`.
+ * @returns {any} The value.
+ */
+export function sohlSystemField(fm, to, defaultValue = undefined, { legacyKey = to } = {}) {
+    const system = fm?.sohl?.system;
+    if (system && typeof system === "object" && !Array.isArray(system)) {
+        const found = getFrontmatter(system, to, undefined);
+        if (found !== undefined) return found;
+    }
+    return sohlField(fm, legacyKey, defaultValue);
+}
+
 /**
  * Read a frontmatter property that is authored as a **map**, returning its
  * entries — or `null` when the note authors none.
@@ -81,12 +121,12 @@ export function sohlField(fm, key, defaultValue = undefined) {
  * silent data loss these readers exist to prevent.
  *
  * @param {object} fm - The item frontmatter.
- * @param {string} key - The property name, read via {@link sohlField}.
+ * @param {string} key - The property name, read via {@link sohlSystemField}.
  * @returns {[string, unknown][] | null} The property's entries — empty when the
  *   note authors none — or `null` when the value is not a map.
  */
 function readMapEntries(fm, key) {
-    const raw = sohlField(fm, key, undefined);
+    const raw = sohlSystemField(fm, key, undefined);
     if (raw == null) return [];
     if (Array.isArray(raw)) return raw.length === 0 ? [] : null;
     if (typeof raw !== "object") return null;
@@ -115,11 +155,11 @@ export function resolveCharges(fm) {
         const num = Number(raw);
         return Number.isFinite(num) ? Math.trunc(num) : null;
     };
-    const max = toCount(sohlField(fm, "charges.max", null));
+    const max = toCount(sohlSystemField(fm, "charges.max", null));
     // A blank maximum means "does not use charges" — a stray current count
     // cannot outlive it, since the logic layer disables both modifiers.
     return {
-        value: max === null ? null : toCount(sohlField(fm, "charges.value", null)),
+        value: max === null ? null : toCount(sohlSystemField(fm, "charges.value", null)),
         max,
     };
 }
@@ -182,16 +222,24 @@ export function resolveSkillAptitudes(fm, ctx = "item") {
  * @throws {Error} When the map is malformed or names an unknown standing.
  */
 export function resolveRelation(fm, ctx = "item") {
-    const entries = readMapEntries(fm, "relation");
+    // `relations` is the field's name; `relation` is the retired spelling, read
+    // underneath it so a tree converts on its own schedule (SoHL#1781). The
+    // current name wins wherever a note writes both, and the lint reports the
+    // old one through {@link RETIRED_FIELD_ALIASES}.
+    // Probed at the destination too: a note that has moved to
+    // `sohl.system.relations` carries the current spelling, and a probe that
+    // could not see it would fall through to the retired one and read `{}`.
+    const key = sohlSystemField(fm, "relations", undefined) == null ? "relation" : "relations";
+    const entries = readMapEntries(fm, key);
     if (entries === null) {
-        throw new Error(`${ctx}: relation must be a map of shortcode → standing`);
+        throw new Error(`${ctx}: ${key} must be a map of shortcode → standing`);
     }
     const out = {};
     for (const [code, value] of entries) {
         const standing = String(value);
         if (!AFFILIATION_STANDINGS.includes(standing)) {
             throw new Error(
-                `${ctx}: relation["${code}"] must be one of ${AFFILIATION_STANDINGS.join(", ")}, got "${value}"`,
+                `${ctx}: ${key}["${code}"] must be one of ${AFFILIATION_STANDINGS.join(", ")}, got "${value}"`,
             );
         }
         out[code] = standing;
@@ -216,7 +264,7 @@ export function resolveRelation(fm, ctx = "item") {
  * @throws {Error} When `subType` is missing or blank.
  */
 export function requireSubType(fm, ctx) {
-    const subType = sohlField(fm, "subType", undefined);
+    const subType = sohlSystemField(fm, "subType", undefined);
     if (subType == null || subType === "") {
         const label = ctx || fm?.title || fm?.name || "item";
         throw new Error(
@@ -251,3 +299,35 @@ export function parseValueDesc(raw) {
         return { label: String(entry), maxValue: 0 };
     });
 }
+
+/**
+ * The compendium folder a note names, and how it named it.
+ *
+ * Two spellings, deliberately not merged into one value: `packFolder:` is a
+ * folder note's **address** (`folder-poisonsandtoxins`) and `folder:` is a
+ * Foundry **id** (`ONXsqZAIZr2qzxTb`). Which one a value is cannot be told from
+ * the string — both are alphanumeric — so the field it was written in is what
+ * says, and that answer is carried rather than re-derived (#251).
+ *
+ * **`packFolder` was a path for one release** (`Possessions/Misc_Gear/Cooking`)
+ * and is an address now (#255). A path encoded the hierarchy *in the value*, so
+ * reparenting a folder made every note naming it wrong — a structural edit
+ * became a corpus-wide rewrite. An address is stable under reparenting, which
+ * is exactly why a note is addressed by `(type, shortcode)` and never by
+ * `file.path`. The path form is **removed rather than deprecated**: it had no
+ * authors to migrate, which is the whole reason the change was cheap enough to
+ * make.
+ *
+ * `packFolder` wins where both are present. Nothing about `folder` changes: a
+ * note that names one is read, resolved and emitted exactly as before, until
+ * #260 retires it.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {{value: string|null, isAddress: boolean}} The authored value, and
+ *   whether it is a folder note's address.
+ */
+export function folderField(fm) {
+    const asAddress = sohlField(fm, "packFolder", null);
+    if (asAddress != null && asAddress !== "") return { value: asAddress, isAddress: true };
+    return { value: sohlField(fm, "folder", null), isAddress: false };
+}