@heroiclands/package-build 19.0.0 → 20.2.0

package/engine/frontmatter-lint.mjs

@@ -121,24 +121,152 @@ export const UNIVERSAL_KEYS = Object.freeze(
  * The system blocks a build checks, and what each accepts beyond the shared
  * vocabulary.
  *
- * One entry, because one system is what every existing tree declares — and the
- * default is a *declaration*, not a hard-coded assumption: a build that ships
- * content for two systems passes both, and each block is then checked against
- * its own vocabulary rather than against the other's (#58). A block nothing
- * declares is not checked, because nothing can say what it may carry, and
- * inventing a rule for it would report a correct tree red.
- *
- * `fieldVocabulary` says the note type's own declared field names are keys of
- * this block. True for `sohl` and untrue in general: those names come from the
- * `itemBuilders` registry that this system declares, and a second system's
- * notes write a second system's fields.
- *
- * @type {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>}
+ * One entry, because one system is what every existing tree declares — and it
+ * is a *fallback*, not the rule. {@link systemBlocksFor} derives the map from
+ * the configuration, which is what makes the block a package actually ships for
+ * the block that gets checked; this is what a caller holding no configuration
+ * gets, which in practice is a unit test.
+ *
+ * A block nothing declares is not checked, because nothing can say what it may
+ * carry, and inventing a rule for it would report a correct tree red.
+ *
+ * Three ways a block may state its vocabulary, and a spec declares at most one:
+ *
+ * - `known` — an explicit list of keys, for a caller stating them outright.
+ * - `fieldVocabulary` — the note type's own declared field names, as the
+ *   caller's `schemas` state them, are keys of this block. That holds for the
+ *   **one** system a single-registry tree ships for, where `schemas` *is* that
+ *   system's vocabulary, and in general holds for no other.
+ * - `fields` — type → that system's own declared fields, from the registry the
+ *   system declares. What a second system's block is checked against, because a
+ *   second system's notes write a second system's fields and the note-type
+ *   schemas describe somebody else's.
+ *
+ * @type {Readonly<Record<string, SystemBlockSpec>>}
  */
 export const DEFAULT_SYSTEM_BLOCKS = Object.freeze({
     sohl: Object.freeze({ fieldVocabulary: true }),
 });
 
+/**
+ * What one system block accepts beyond the keys every block carries.
+ *
+ * @typedef {object} SystemBlockSpec
+ * @property {readonly string[]} [known] - Keys stated outright.
+ * @property {boolean} [fieldVocabulary] - Whether the note type's declared field
+ *   names, as the caller's `schemas` state them, are keys of this block.
+ * @property {Readonly<Record<string, readonly object[]>>} [fields] - Type → this
+ *   system's own declared fields. A type it does not name is a type this system
+ *   says nothing about, and its block is left unchecked on such a note rather
+ *   than reported wholesale.
+ */
+
+/**
+ * Every system a configuration says its tree carries (#58).
+ *
+ * **Which systems a package ships for is already declared**, in three places
+ * that answer different questions, so this reads all three rather than asking a
+ * new one:
+ *
+ * - `systems:` (#48) declares them without requiring one, which is how a
+ *   package ships for several;
+ * - a **pack's** `system:` is the same statement made per pack, and it is the
+ *   one some trees make: `harn-ensemble` declares an `actors-sohl` and an
+ *   `actors-hm3` and nothing else about either system. It is already
+ *   authoritative elsewhere — `eligibleFor` fails a note for want of the block
+ *   a pack's `system:` names — so a lint that did not read it would refuse a
+ *   note at compile for a block it never checked;
+ * - `stats.systemId` is the package-wide answer where there is one, and it has
+ *   already absorbed every way of spelling that: a system package is its own
+ *   system, and a module takes `requiresSystem`, its lone `systems:` entry, or
+ *   its lone system relationship.
+ *
+ * A package naming a system in none of them is system-agnostic on purpose — its
+ * packs are core document types carrying no system data — so it carries no
+ * system block and naming one would invent it.
+ *
+ * @param {object} [config] - A resolved configuration from `defineConfig`.
+ * @returns {string[]} The system ids, deduplicated, in declared order.
+ */
+export function declaredSystems(config) {
+    const out = [];
+    for (const system of Object.keys(config?.systems ?? {})) {
+        if (!out.includes(system)) out.push(system);
+    }
+    for (const pack of config?.packs ?? []) {
+        const system = pack?.system;
+        if (typeof system === "string" && system && !out.includes(system)) out.push(system);
+    }
+    if (out.length) return out;
+    const packageWide = config?.stats?.systemId;
+    return typeof packageWide === "string" && packageWide ? [packageWide] : [];
+}
+
+/**
+ * The system blocks a configuration says its tree carries, and what each
+ * accepts (#58).
+ *
+ * The lint checks the blocks its caller names, and for as long as there was one
+ * system the only caller named none — so every tree took the `sohl:` of
+ * {@link DEFAULT_SYSTEM_BLOCKS}, a constant, in a module whose whole discipline
+ * is that it states no vocabulary of its own. That is wrong in both directions
+ * the moment a second system exists, and the second direction is the worse:
+ *
+ * - a package shipping for `hm3` had its `hm3:` block **never looked at**, so
+ *   every key in it was discarded at compile without a word — the silent-drop
+ *   family this check exists to close;
+ * - and the block that *was* checked was named after a system that package does
+ *   not ship for, so the one finding it could make was about nothing.
+ *
+ * **A block's vocabulary has two sources, and a system may have both.**
+ *
+ * - The **note schemas** the caller hands in as `schemas`. Those belong to one
+ *   system — the CLI imports `sohl/note-schemas.mjs` — and `schemaSystem` is the
+ *   caller naming which, because only the caller knows. It is the only source
+ *   that reaches a type no item registry declares, which is to say `being`: the
+ *   2,512 notes `harn-ensemble` is made of, and the reason this is not an
+ *   optional refinement.
+ * - The system's **own registry**, `itemFieldsBySystem`, keyed by system and
+ *   until now read by nothing. This is what a *second* system's block is held
+ *   to, since the note schemas describe its neighbour.
+ *
+ * A system with neither is left out: nothing can state what its block may
+ * carry, and holding it to an empty vocabulary would report every key in a
+ * correct tree. **That is a check that does not run**, which is
+ * indistinguishable from one that passed, so the caller says it out loud —
+ * {@link declaredSystems} is the other half of that comparison. `harn-ensemble`
+ * is the tree it names: two systems, and an `itemBuilders` registry for
+ * neither, so its `hm3:` block is unchecked until it declares one.
+ *
+ * An earlier draft of this took the note schemas for a system's vocabulary only
+ * where the package declared **one** system, on the reasoning that with several
+ * there is nothing to say which one they describe. There is: the caller, which
+ * chose them. The guess cost `harn-ensemble` its whole `sohl:` check — two
+ * systems declared, so the fallback never fired — which is the coverage this
+ * change exists to widen rather than narrow.
+ *
+ * @param {object} [config] - A resolved configuration from `defineConfig`.
+ * @param {object} [options] - Options.
+ * @param {string} [options.schemaSystem] - The system whose vocabulary the
+ *   caller's `schemas` state. There are two systems, not an open set, so this is
+ *   one word from the caller rather than a mechanism.
+ * @returns {Readonly<Record<string, SystemBlockSpec>>} The blocks to check, in
+ *   declared order. A system nothing states the vocabulary of is absent.
+ */
+export function systemBlocksFor(config, { schemaSystem } = {}) {
+    const byName = config?.itemFieldsBySystem ?? {};
+    /** @type {Record<string, SystemBlockSpec>} */
+    const blocks = {};
+    for (const system of declaredSystems(config)) {
+        /** @type {SystemBlockSpec} */
+        const spec = {};
+        if (system === schemaSystem) spec.fieldVocabulary = true;
+        if (byName[system]) spec.fields = byName[system];
+        if (Object.keys(spec).length) blocks[system] = Object.freeze(spec);
+    }
+    return Object.freeze(blocks);
+}
+
 /**
  * Edit distance, capped — enough to answer "did you mean".
  *
@@ -591,30 +719,114 @@ function checkTags(note, { type }) {
  * note in any tree writes `img: ""` on a being; a check keyed on `img` alone
  * would have called that tree clean (#218).
  *
- * @type {readonly string[]}
+ * **Each carries where it is authored**, because the two no longer agree. The
+ * specification puts an actor's portrait under `data:` and leaves its token art
+ * at the note's top level, so `portrait` has a third position to read and `img`
+ * does not — and a check that read only the two they share would pass a
+ * `data.portrait: ""` it could not see (#332).
+ *
+ * @type {readonly {key: string, inData: boolean}[]}
+ */
+const ART_FIELDS = Object.freeze([
+    Object.freeze({ key: "img", inData: false }),
+    Object.freeze({ key: "portrait", inData: true }),
+]);
+
+/**
+ * The in-block keys a type's own declarations claim for a *different* quantity.
+ *
+ * {@link module:engine/field-spec.FieldSpec.topLevelMeans} read from the other
+ * side. That property says the note's top-level key of a field's name means
+ * something else, and `resolveFieldValue` honours it by refusing to read the
+ * shared position *for that field*. The statement is symmetric: if the two
+ * positions hold unrelated quantities, then the **block** position is not the
+ * note-level field either, and a check about the note-level field must not read
+ * it.
+ *
+ * `affiliation`'s `title` is the case that named this. A note's top-level
+ * `title` is its page heading, which the site emitter publishes as
+ * `fm.title ?? name`; `sohl.title` is the style of address an office carries —
+ * "Ajaw", "Warden". Twenty-eight `sohl-kethira-basic` affiliations author
+ * `sohl.title: ""` — an office with no style of address, which is ordinary —
+ * and every one of them was reported as publishing a page with no heading. None
+ * of them does; their pages take `name.full` exactly as intended (#312).
+ *
+ * Keyed on the **in-block** key — `legacyKey` where a field declares one, and
+ * its first segment where that is dotted — because that is the position a note
+ * authors, and so the position a note-level check would otherwise read.
+ *
+ * @param {readonly object[]|null|undefined} schema - The type's declarations.
+ * @returns {Set<string>} The in-block keys that are not the note-level field of
+ *   the same name.
  */
-const ART_FIELDS = Object.freeze(["img", "portrait"]);
+/**
+ * The keys a field declaration is authored at **inside a system block**.
+ *
+ * The first segment of each field's in-block key: `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 on
+ * the name instead would report `sohl.species` as a property no `being` has,
+ * against exactly the notes the sweep has not reached yet.
+ *
+ * Written once and read twice: the note type's own declaration answers for the
+ * system whose vocabulary the caller's `schemas` are, and a second system's
+ * registry answers for its block (#58). Two derivations of one thing would be
+ * free to disagree about which position a note authors.
+ *
+ * @param {readonly object[]|null|undefined} schema - A type's declarations.
+ * @returns {Set<string>} The in-block keys.
+ */
+function inBlockKeys(schema) {
+    return new Set(authoredFields(schema ?? []).map((f) => legacyKeyOf(f).split(".")[0]));
+}
+
+function collidingBlockKeys(schema) {
+    const keys = new Set();
+    if (!Array.isArray(schema)) return keys;
+    for (const field of authoredFields(schema)) {
+        if (field.topLevelMeans === undefined) continue;
+        keys.add(String(legacyKeyOf(field)).split(".")[0]);
+    }
+    return keys;
+}
 
 /**
- * Read a shared top-level field the way the compiler reads one: the `sohl:`
- * block first, then the note's top level.
+ * Read a shared field the way the compiler reads one: the `sohl:` block first,
+ * then `data:` where the field lives there, then the note's top level.
+ *
+ * The same order {@link module:engine/system-block.resolveFieldValue} uses,
+ * restated here rather than imported so this module stays a leaf the linter can
+ * load without a resolved build configuration. Unlike that resolver it
+ * distinguishes the two empties — an authored `""` comes back as `""` and an
+ * authored `null` as `null` — which is the whole point of the caller below
+ * (#218).
  *
- * The same order {@link module:engine/helpers.sohlField} uses, restated here
- * rather than imported so this module stays a leaf the linter can load without
- * a resolved build configuration. Unlike `sohlField` it distinguishes the two
- * empties — an authored `""` comes back as `""` and an authored `null` as
- * `null` — which is the whole point of the caller below (#218).
+ * **`blockCollides` drops the first position**, where the note's type declares
+ * a system field of that name meaning something else — the resolver's
+ * `topLevelMeans` exemption, applied from the note-level side (#312). See
+ * {@link collidingBlockKeys}. The caller decides per key rather than this
+ * function deciding for itself, because this module knows no type's vocabulary:
+ * the declarations arrive from the caller, as `schemas` and `vocabulary` do.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} key - The field name.
- * @returns {any} The authored value, or `undefined` where neither position
- *   declares one.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.inData=false] - Whether the field's shared source
+ *   is `data.<key>` rather than the top-level key.
+ * @param {boolean} [options.blockCollides=false] - Whether `sohl.<key>` is a
+ *   system field that merely shares this name, and so answers for nothing here.
+ * @returns {any} The authored value, or `undefined` where no position declares
+ *   one.
  */
-function authoredValue(fm, key) {
-    const block = fm?.sohl;
+function authoredValue(fm, key, { inData = false, blockCollides = false } = {}) {
+    const block = blockCollides ? undefined : fm?.sohl;
     if (block && typeof block === "object" && !Array.isArray(block) && Object.hasOwn(block, key)) {
         return block[key];
     }
+    const data = inData ? fm?.data : undefined;
+    if (data && typeof data === "object" && !Array.isArray(data) && Object.hasOwn(data, key)) {
+        return data[key];
+    }
     return fm && Object.hasOwn(fm, key) ? fm[key] : undefined;
 }
 
@@ -709,9 +921,17 @@ function checkEmbeddedShortcodes(note, blockName) {
  *   note against whatever its type declares and knows no type names of its
  *   own. Its absence skips the `data:` and `subType` checks rather than
  *   reporting every key as unknown.
- * @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 {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]
+ *   What art a note of one type reaches its document through — the passes' own
+ *   declaration, asked through `engine/generate.mjs`'s `emittedArtFor`.
+ *   Supplied by the caller like `schemas`, so this module states no list of
+ *   iconless types of its own; absent it, an inert `img:` goes unreported
+ *   rather than every note's being (#349).
+ * @param {Readonly<Record<string, SystemBlockSpec>>} [opts.systems]
+ *   The system blocks to check, and what each accepts. Supplied by the caller
+ *   for the same reason `schemas` is — a build derives them from its
+ *   configuration through {@link systemBlocksFor}, and this module states no
+ *   system name of its own. See {@link DEFAULT_SYSTEM_BLOCKS} for the fallback.
  * @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
@@ -720,13 +940,21 @@ function checkEmbeddedShortcodes(note, blockName) {
  */
 export function lintNote(
     note,
-    { schemas, index, vocabulary, packs, systems = DEFAULT_SYSTEM_BLOCKS },
+    { schemas, index, vocabulary, packs, emittedArt, systems = DEFAULT_SYSTEM_BLOCKS },
 ) {
     const findings = [];
     const fm = note.fm ?? {};
     const type = String(fm.type ?? "");
     const raw = () => note.raw ?? "";
     const at = (key, literal) => positionInFrontmatter(raw(), key, literal ?? undefined);
+    /**
+     * The in-block keys this note's own type claims for something other than
+     * the note-level field of that name, which every note-level check below
+     * reads past (#312). Resolved once: the type is fixed for the note, and
+     * each check would otherwise ask the same question of the same
+     * declarations.
+     */
+    const blockCollisions = collidingBlockKeys(schemas?.[currentType(type)]);
 
     // The retired top-level fields, checked before the type: a note may carry
     // one whatever its type is, and each finding stands on its own. Reported
@@ -797,15 +1025,23 @@ export function lintNote(
     // optional strings, and it is not — it belongs to `resolveImg`, and `title`
     // never goes through it.
     //
-    // It once had a sharper reason, recorded here because it was load-bearing
-    // and is now false: a note's top-level `title` was simultaneously the shared
-    // source for an `affiliation` item's `system.title`, so asking an author for
-    // `title: null` would have compiled the literal string `"null"` into the
-    // document. That collision is gone — the field declares `topLevelMeans` and
-    // the top-level key is no longer a source for it — so `title: null` is now
-    // 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.
+    // It once had a sharper reason: a note's top-level `title` was
+    // simultaneously the shared source for an `affiliation` item's
+    // `system.title`, so asking an author for `title: null` would have compiled
+    // the literal string `"null"` into the document. The field declares
+    // `topLevelMeans` now, so the top-level key is no longer a source for it and
+    // `title: null` is harmless. `title: ""` is warned about on its own account
+    // below, as the *page's* heading rather than as an art path.
+    //
+    // **The collision itself did not go away, and this was where that was
+    // misread.** `topLevelMeans` settles which position the *emitted field*
+    // reads; it says nothing about which position a *check* reads, and
+    // `authoredValue` went on resolving through the block regardless — so an
+    // office with no style of address answered for its note's heading, in
+    // twenty-eight `sohl-kethira-basic` affiliations (#312). Hence
+    // `blockCollisions`: a note-level check reads past a block key its type
+    // claims for something else.
+
     // 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
@@ -829,8 +1065,70 @@ export function lintNote(
         });
     }
 
-    for (const key of ART_FIELDS) {
-        if (authoredValue(fm, key) !== "") continue;
+    // An art field a note's own type never emits (#349). `img` is a *shared
+    // top-level* field — `BLOCK_DOCUMENT_PROPERTIES` maps it onto
+    // `document.img`, so it is legal on every note whatever the type — and a
+    // note whose document has no such property authors it, validates, compiles,
+    // and loses the value with nothing said. `Parrot` in `sohl-thalorna` had
+    // declared `img: images/mystery/parrot.webp` since long before the art rule
+    // was written and compiled `img: null`, exactly as a note declaring nothing
+    // does. The author's only evidence was the absence of an icon somewhere
+    // they were probably not looking.
+    //
+    // **Which types those are is not stated here.** It is asked of the passes,
+    // through the `emittedArt` the caller supplies — a note's type routes to a
+    // document, a document to the pass that compiles it, and the pass declares
+    // its own art. A list of iconless types kept in the linter would be a list
+    // free to drift from what is actually emitted, which is the defect rather
+    // than the check. Absent the option no claim is made, on the pattern
+    // `index` and `vocabulary` set.
+    //
+    // **Only an authored value, never `null`.** `null` is the blessed spelling
+    // for "this note names no art" (#218), and on a type with no art that is a
+    // true and harmless thing to say — it compiles identically to writing
+    // nothing. Twenty-six `sohl-thalorna` place notes are in exactly that
+    // state, and telling each of them to delete a key that already means
+    // nothing would bury the fifty-seven that name a path they believe ships.
+    //
+    // A **warning**, as the `package:` and retired-alias sweeps are: the note
+    // compiles correctly and the value is merely inert. Nor is it certainly
+    // unwanted — a note's top level is the generated page's front matter as
+    // well, so a template may read there what no document carries, which is a
+    // judgement only the tree's author can make.
+    const emitted = emittedArt ? emittedArt(currentType(type)) : null;
+    /** The art fields this note's type reaches nothing through. */
+    const inertArt = new Set(
+        emitted ? ART_FIELDS.filter(({ key }) => !emitted.art.includes(key)).map((f) => f.key) : [],
+    );
+    for (const { key, inData } of ART_FIELDS) {
+        if (!inertArt.has(key)) continue;
+        const authored = authoredValue(fm, key, {
+            inData,
+            blockCollides: blockCollisions.has(key),
+        });
+        if (typeof authored !== "string") continue;
+        findings.push({
+            file: note.file,
+            ...at(key),
+            severity: "warning",
+            message:
+                `\`${key}:\` reaches no document from a \`${type}\` note — ` +
+                (emitted?.document ?
+                    `it compiles into a ${emitted.document}, which carries no artwork`
+                :   "it compiles into a page rather than a compendium document") +
+                ", so the path is dropped. Delete the key, or move the art onto " +
+                "the note whose document is meant to show it; keep it only where " +
+                "a page template reads it as a parameter",
+        });
+    }
+
+    for (const { key, inData } of ART_FIELDS) {
+        // Reported above, and the distinction this draws does not exist there:
+        // where nothing is emitted, `""` and `null` are equally inert and the
+        // note has no default art to lose.
+        if (inertArt.has(key)) continue;
+        if (authoredValue(fm, key, { inData, blockCollides: blockCollisions.has(key) }) !== "")
+            continue;
         findings.push({
             file: note.file,
             ...at(key),
@@ -852,7 +1150,13 @@ export function lintNote(
     //
     // 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") === "") {
+    //
+    // **The emitter reads `fm.title`, so this reads the note level.** On an
+    // `affiliation` `sohl.title` is the office's style of address, which the
+    // heading has nothing to do with — and `blockCollisions` is what keeps the
+    // two apart (#312). On every other type nothing claims the block key, so the
+    // resolution is the unchanged one.
+    if (authoredValue(fm, "title", { blockCollides: blockCollisions.has("title") }) === "") {
         findings.push({
             file: note.file,
             ...at("title"),
@@ -1016,15 +1320,8 @@ export function lintNote(
     }
 
     const fields = authoredFields(schema);
-    /**
-     * 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 keys this type's own declaration is authored at inside a block. */
+    const declared = inBlockKeys(schema);
 
     // 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
@@ -1056,16 +1353,33 @@ export function lintNote(
     // Every declared system's block, each against its own vocabulary (#58). A
     // block carries the shared keys any system's does — `system`, `type`,
     // `img`, `effects`, `flags`, `pack` — plus whatever that system declares:
-    // for `sohl`, the note type's own field names, which are still the position
-    // the corpus authors them at until #126 moves them.
+    // the note type's own field names for the system those schemas describe,
+    // and a second system's own registry for its block. Which systems arrive
+    // here is the configuration's answer, not this module's; see
+    // {@link systemBlocksFor}.
     for (const [blockName, spec] of Object.entries(systems ?? {})) {
         // Two embedded items denoting one entity (#228). Per block, because
         // `items` is a block key and a second system's actor carries its own.
+        // Before the `continue` below, because it is a statement about the
+        // block's *shape* and holds whether or not this system declares a
+        // vocabulary for the note's type.
         findings.push(...checkEmbeddedShortcodes(note, blockName));
+        // A block is checked only where its system speaks about this type. A
+        // type a system's registry does not name is a type it says nothing
+        // about — SoHL's `mysticalability` is not an HM3 type at all — and
+        // holding the block to an empty vocabulary would report every key in
+        // it, which is the correct tree reported red.
+        //
+        // `fieldVocabulary` reaches types no registry declares, `being` above
+        // all, so a spec carrying it always speaks. Only a spec whose *sole*
+        // statement is `fields` can fall silent here.
+        const own = spec?.fields;
+        if (own && !own[type] && !spec?.fieldVocabulary && !spec?.known) continue;
         const accepted = new Set([
             ...UNIVERSAL_KEYS,
             ...(spec?.known ?? []),
             ...(spec?.fieldVocabulary ? declared : []),
+            ...(own ? inBlockKeys(own[type]) : []),
         ]);
         for (const key of unknownBlockKeys(fm, blockName, { known: accepted })) {
             // Reported above, with what to write instead — a retired spelling
@@ -1194,14 +1508,20 @@ export function lintNote(
  * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
  *   it declares (#128); see {@link lintNote}.
  * @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<Record<string, SystemBlockSpec>>} [opts.systems]
+ *   The system blocks to check; see {@link lintNote} and
+ *   {@link systemBlocksFor}.
  * @param {readonly string[]} [opts.packs] - The declared pack names; see
  *   {@link lintNote}.
+ * @param {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]
+ *   What art a type reaches its document through; see {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index, { schemas, vocabulary, packs, references = true, systems }) {
+export function lintFrontmatter(
+    index,
+    { schemas, vocabulary, packs, emittedArt, references = true, systems },
+) {
     const findings = [];
     const notes = [...index.notes].sort((a, b) =>
         a.file < b.file ? -1
@@ -1214,6 +1534,7 @@ export function lintFrontmatter(index, { schemas, vocabulary, packs, references
                 schemas,
                 vocabulary,
                 packs,
+                emittedArt,
                 index: references ? index : undefined,
                 ...(systems ? { systems } : {}),
             }),

package/engine/frontmatter.mjs

@@ -301,13 +301,15 @@ export function parseValueDesc(raw) {
 }
 
 /**
- * The compendium folder a note names, and how it named it.
+ * The compendium folder a note names.
  *
- * 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).
+ * **There is one spelling.** `packFolder:` is a folder note's **address**
+ * (`folder-poisonsandtoxins`), resolved through the address index the whole
+ * build shares. The `folder:` Foundry-id spelling this function once read
+ * beside it, and the per-pack `*-folders.yaml` that id was resolved against,
+ * are retired together (#260) — a note declaring `folder:` is refused by
+ * {@link module:engine/folder-notes.assertNoDeclaredFolder} rather than
+ * reaching here, so there is no second source for a value to come from.
  *
  * **`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
@@ -318,13 +320,11 @@ export function parseValueDesc(raw) {
  * 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.
+ *   whether it is a folder note's address. `isAddress` is always `true` and is
+ *   kept so a caller reads the same shape it always did; it distinguished the
+ *   two spellings, and there is only one left to be.
  */
 export function folderField(fm) {
     const asAddress = sohlField(fm, "packFolder", null);