@heroiclands/package-build 9.0.0 → 10.0.1

package/engine/frontmatter-lint.mjs

@@ -56,10 +56,18 @@
  */
 
 import { authoredFields } from "./field-spec.mjs";
-import { positionInFrontmatter } from "./diagnostics.mjs";
+import { resolveFieldValue, SYSTEM_BLOCK_KEYS, unknownBlockKeys } from "./system-block.mjs";
+import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
-import { draftRetiredMessage } from "./retired-fields.mjs";
+import { declaredTags } from "./note-vocabulary.mjs";
+import {
+    RETIRED_FIELD_ALIASES,
+    declaresRetiredAlias,
+    draftRetiredMessage,
+    readAliasedField,
+    retiredAliasMessage,
+} from "./retired-fields.mjs";
 
 /**
  * `sohl:` keys every type accepts, whatever its schema says.
@@ -91,6 +99,28 @@ import { draftRetiredMessage } from "./retired-fields.mjs";
  */
 export const UNIVERSAL_KEYS = Object.freeze(new Set(["folder", "pack", "archetype", "kbcat"]));
 
+/**
+ * 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}>>}
+ */
+export const DEFAULT_SYSTEM_BLOCKS = Object.freeze({
+    sohl: Object.freeze({ fieldVocabulary: true }),
+});
+
 /**
  * Edit distance, capped — enough to answer "did you mean".
  *
@@ -182,14 +212,208 @@ export function matchesKind(value, kind) {
 }
 
 /**
- * The `sohl:` block a note authored, or an empty one.
+ * The `data:` container a note authored.
+ *
+ * An emptied map arrives from the property editor as `[]` and means the same
+ * thing `{}` does — this note authors no entries (#8) — so both read as an
+ * empty container rather than as a malformed one.
  *
  * @param {object} fm - The note's frontmatter.
- * @returns {object} The block.
+ * @returns {{present: boolean, entries: object, malformed: boolean}} What was
+ *   authored, and whether it is a container at all.
+ */
+function dataBlock(fm) {
+    if (!Object.hasOwn(fm ?? {}, "data")) {
+        return { present: false, entries: {}, malformed: false };
+    }
+    const value = fm.data;
+    if (value == null || (Array.isArray(value) && value.length === 0)) {
+        return { present: true, entries: {}, malformed: false };
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return { present: true, entries: {}, malformed: true };
+    }
+    return { present: true, entries: value, malformed: false };
+}
+
+/**
+ * Check a note's `data:` container against the closed vocabulary its type
+ * declares (#128).
+ *
+ * Unlike the top level, which is passed through to the published page and so
+ * cannot be refused, `data:` holds the type-specific facts about the subject
+ * and every key of it is declared. An unrecognised key is therefore a finding
+ * naming the note, with the key it was most likely meant to be — the same
+ * capped edit distance {@link nearest} applies to a `sohl:` key, drawn from
+ * this type's own vocabulary rather than from every type's.
+ *
+ * @param {object} note - The note.
+ * @param {object} opts
+ * @param {string} opts.type - The note's type, for the message.
+ * @param {readonly object[]} opts.fields - The type's `data:` declaration.
+ * @returns {object[]} Findings.
+ */
+function checkDataContainer(note, { type, fields }) {
+    const findings = [];
+    const { present, entries, malformed } = dataBlock(note.fm ?? {});
+    if (!present) return findings;
+
+    const raw = note.raw ?? "";
+    if (malformed) {
+        findings.push({
+            file: note.file,
+            ...positionOfFrontmatterPath(raw, ["data"], { key: true }),
+            severity: "error",
+            message:
+                "`data:` must be a map of the note's own type-specific " +
+                `properties, but reads ${JSON.stringify(note.fm.data)}`,
+        });
+        return findings;
+    }
+
+    /** First segment of each declared name — `charges.value` is authored as `charges`. */
+    const declared = new Set(fields.map((f) => f.name.split(".")[0]));
+
+    for (const key of Object.keys(entries)) {
+        if (declared.has(key)) continue;
+        const guess = nearest(key, declared);
+        findings.push({
+            file: note.file,
+            ...positionOfFrontmatterPath(raw, ["data", key], { key: true }),
+            severity: "error",
+            message:
+                `"${key}" is not a \`data:\` property declared by ${type}; ` +
+                `the container is closed, so unlike a top-level key it is ` +
+                `not passed through to the page` +
+                (guess ? `. Did you mean "${guess}"?` : ""),
+        });
+    }
+
+    for (const field of fields) {
+        if (!field.kind) continue;
+        const segments = field.name.split(".");
+        let value = entries;
+        for (const segment of segments) {
+            value = value && typeof value === "object" ? value[segment] : undefined;
+        }
+        if (value === undefined || value === null) continue;
+        if (matchesKind(value, field.kind)) continue;
+        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)}`,
+        });
+    }
+
+    return findings;
+}
+
+/**
+ * Check a note's top-level `subType` against the values its type declares
+ * (#128).
+ *
+ * `subType` stays at the top level — it is what each system's map reads to
+ * derive a document type, so it describes the note rather than the subject —
+ * but it is not open like the rest of that region: a type either declares a
+ * `subType` or does not, and a type that does declares its values.
+ *
+ * @param {object} note - The note.
+ * @param {object} opts
+ * @param {string} opts.type - The note's type, for the message.
+ * @param {object} opts.entry - The type's vocabulary entry.
+ * @returns {object[]} Findings.
  */
-function sohlBlock(fm) {
-    const block = fm?.sohl;
-    return block && typeof block === "object" && !Array.isArray(block) ? block : {};
+function checkSubType(note, { type, entry }) {
+    const fm = note.fm ?? {};
+    if (!Object.hasOwn(fm, "subType") || fm.subType == null || fm.subType === "") return [];
+
+    const value = String(fm.subType);
+    const at = positionInFrontmatter(note.raw ?? "", "subType");
+
+    if (!Object.hasOwn(entry, "subTypes")) {
+        return [
+            {
+                file: note.file,
+                ...at,
+                severity: "error",
+                message:
+                    `\`subType\` is not a property declared by ${type}; it ` +
+                    `declares no subtypes, so nothing reads this value`,
+            },
+        ];
+    }
+
+    const values = entry.subTypes;
+    // `null` is "declared, values not yet enumerated" — presence is legal and
+    // the value is nobody's to check yet.
+    if (values == null || values.includes(value)) return [];
+
+    const guess = nearest(value, values);
+    return [
+        {
+            file: note.file,
+            ...at,
+            severity: "error",
+            message:
+                `\`subType\` "${value}" is not one of the subtypes ` +
+                `${type} declares (${values.join(", ")})` +
+                (guess ? `. Did you mean "${guess}"?` : ""),
+        },
+    ];
+}
+
+/**
+ * Check a note's `tags` for near misses against the tags that classify (#172).
+ *
+ * `tags:` is top-level and the top level is open, so an unrecognised tag is
+ * **not** a finding: a theme, a region or a working state is the author's own
+ * vocabulary and this build has no standing to refuse it.
+ *
+ * **Distance alone is not enough either**, which the corpus settles rather than
+ * argues: `azravan` on a faith, `barter` on an economy note and `secret` on
+ * three lore notes are all within a typo's distance of `caravan`, `border` and
+ * `sacred`, and not one is a mistake. Checked against every declared tag at
+ * once, the rule was wrong on every note it touched.
+ *
+ * **The scope is what makes it sound.** Each group names the types it applies
+ * to, so a place's kinds are only ever checked on a place, and the eight
+ * findings above become none while a settlement tagged `vilage` is still
+ * caught.
+ *
+ * @param {object} note - The note.
+ * @param {object} opts
+ * @param {readonly string[]} opts.tags - Every declared tag, flattened.
+ * @returns {object[]} Findings.
+ */
+function checkTags(note, { type }) {
+    const authored = (note.fm ?? {}).tags;
+    if (!Array.isArray(authored)) return [];
+
+    const tags = declaredTags(type);
+    if (!tags.length) return [];
+    const declared = new Set(tags);
+    const findings = [];
+    for (const raw of authored) {
+        if (typeof raw !== "string" || !raw.trim()) continue;
+        const value = raw.trim();
+        if (declared.has(value)) continue;
+        const guess = nearest(value, tags);
+        if (!guess) continue;
+        findings.push({
+            file: note.file,
+            ...positionInFrontmatter(note.raw ?? "", "tags"),
+            severity: "error",
+            message:
+                `tag "${value}" is not declared, and is a near miss for the declared ` +
+                `tag "${guess}". A classifying tag is queried, so a misspelt one drops ` +
+                `this note out of an index without failing anything. Write "${guess}", ` +
+                `or rename the tag so it is plainly the author's own`,
+        });
+    }
+    return findings;
 }
 
 /**
@@ -200,9 +424,18 @@ function sohlBlock(fm) {
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
  * @param {object} [opts.index] - The link index, for the reference check. Its
  *   absence skips that check rather than reporting every reference as dead.
+ * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
+ *   it declares, as `engine/note-vocabulary.mjs` states them (#128). Supplied
+ *   by the caller for the same reason `schemas` is: this module validates a
+ *   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}.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note, { schemas, index }) {
+export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_SYSTEM_BLOCKS }) {
     const findings = [];
     const fm = note.fm ?? {};
     const type = String(fm.type ?? "");
@@ -239,6 +472,11 @@ export function lintNote(note, { schemas, index }) {
     // fields above because it is the same kind of statement — a top-level key
     // this note may not write — and, like them, it must survive the two early
     // returns below: the finding stands whatever else the type is.
+    // Tags are checked here for the same reason: a classifying tag is not a
+    // type's property — `draft` belongs to any note and `village` to a place —
+    // so the finding must survive the early returns below.
+    findings.push(...checkTags(note, { type }));
+
     for (const { key, message } of checkHomepageAddressFields(fm)) {
         findings.push({
             file: note.file,
@@ -275,42 +513,114 @@ export function lintNote(note, { schemas, index }) {
         return findings;
     }
 
+    // The closed frontmatter regions (#128), checked beside the `sohl:` block
+    // because they are the same statement about the same note: this key is not
+    // 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];
+    if (entry) {
+        findings.push(...checkDataContainer(note, { type, fields: entry.data ?? [] }));
+        findings.push(...checkSubType(note, { type, entry }));
+    }
+
     const fields = authoredFields(schema);
-    const block = sohlBlock(fm);
     /** First segment of each declared name — `impact.die` is authored as `impact`. */
     const declared = new Set(fields.map((f) => f.name.split(".")[0]));
 
-    for (const key of Object.keys(block)) {
-        if (declared.has(key) || UNIVERSAL_KEYS.has(key)) continue;
-        const guess = nearest(key, declared);
+    // 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
+    // exactly where its replacement exists and the old name stays an unknown
+    // key everywhere else (#142).
+    const renamed = new Map();
+    for (const name of declared) {
+        const retired = RETIRED_FIELD_ALIASES[name];
+        if (retired) renamed.set(retired, name);
+    }
+    for (const [retired, current] of renamed) {
+        // `declaresRetiredAlias` searches both regions, because both are read:
+        // a note that moved the key to the top level without renaming it has
+        // done half the migration. It is the same predicate the compile-time
+        // report asks, so the two cannot disagree about what a note declares.
+        if (!declaresRetiredAlias(fm, current)) continue;
         findings.push({
             file: note.file,
-            ...at(key),
-            severity: "error",
-            message:
-                `"${key}" is not a property of a ${type}; it is discarded at ` +
-                `compile with no warning` +
-                (guess ? `. Did you mean "${guess}"?` : ""),
+            ...at(retired),
+            // A warning, not an error: 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 after the sweep, as
+            // `package:`'s did (#56).
+            severity: "warning",
+            message: retiredAliasMessage(retired, current),
         });
     }
 
+    // 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.
+    for (const [blockName, spec] of Object.entries(systems ?? {})) {
+        const accepted = new Set([
+            ...UNIVERSAL_KEYS,
+            ...(spec?.known ?? []),
+            ...(spec?.fieldVocabulary ? declared : []),
+        ]);
+        for (const key of unknownBlockKeys(fm, blockName, { known: accepted })) {
+            // Reported above, with what to write instead — a retired spelling
+            // is a rename to schedule, not a key nobody recognises. Only where
+            // the block's vocabulary is this type's: the alias renames *this*
+            // system's field, and another system's like-spelled key is not it.
+            if (spec?.fieldVocabulary && renamed.has(key)) continue;
+            const guess = nearest(key, [...accepted, ...SYSTEM_BLOCK_KEYS]);
+            findings.push({
+                file: note.file,
+                ...at(key),
+                severity: "error",
+                message:
+                    `"${key}" is not a property of a ${type}` +
+                    (blockName === "sohl" ? "" : ` under \`${blockName}\``) +
+                    `; it is discarded at compile with no warning` +
+                    (guess ? `. Did you mean "${guess}"?` : ""),
+            });
+        }
+    }
+
     for (const field of fields) {
         // Only top-level names are read here: a nested one (`impact.die`) is
         // reached through its parent, and reporting the parent twice — once as
         // itself and once as its child — helps nobody.
-        const [head, ...rest] = field.name.split(".");
-        let value = block[head];
-        for (const segment of rest) {
-            value = value && typeof value === "object" ? value[segment] : undefined;
+        const [head] = field.name.split(".");
+        // Resolved exactly as the compiler resolves it (#58): the system path
+        // first, then the block, then the declared shared source. A lint that
+        // read only one of the three would report a note's own field as missing
+        // the moment it moved to another of them. A **shared** field needs
+        // nothing extra here — the note's top level *is* the third step — so
+        // `shared` says only where the field's home is, for the message below.
+        let { value, from } = resolveFieldValue(field, fm, { block: "sohl" });
+        // A **renamed** field may still be written under its retired spelling,
+        // which that order knows nothing about. It resolves through the reader
+        // the compiler uses, so the lint cannot disagree with the build about
+        // which value a note carries (#142).
+        if ((from === "default" || value == null) && RETIRED_FIELD_ALIASES[field.name]) {
+            const aliased = readAliasedField(fm, field.name);
+            if (aliased !== undefined) {
+                value = aliased;
+                from = "block";
+            }
         }
-        const absent = value === undefined || value === null;
+        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}\``;
 
         if (field.required && absent) {
             findings.push({
                 file: note.file,
                 ...at("type", type),
                 severity: "error",
-                message: `a ${type} must declare \`sohl.${field.name}\` — ${field.describe}`,
+                message: `a ${type} must declare ${label} — ${field.describe}`,
             });
             continue;
         }
@@ -322,7 +632,7 @@ export function lintNote(note, { schemas, index }) {
                 ...at(head),
                 severity: "error",
                 message:
-                    `\`sohl.${field.name}\` should be ${field.shape ?? field.kind}, ` +
+                    `${label} should be ${field.shape ?? field.kind}, ` +
                     `but reads ${JSON.stringify(value)}`,
             });
             continue;
@@ -332,15 +642,22 @@ export function lintNote(note, { schemas, index }) {
         // link index's own resolver, so a cross-package reference answered by a
         // vendored manifest lands exactly as the same address in a wikilink
         // would — rather than through a second, subtly different rule.
+        //
+        // **As an address, always.** The resolver's third argument chooses the
+        // namespace and has no fallback (#144): omitted, it reads the target as
+        // an *alias*, and `type-shortcode` is never an alias, so every value a
+        // `ref:` field carries was reported unresolvable (#176). A frontmatter
+        // reference is a bare address by construction — there is no pipe to
+        // read intent from, and the field supplies the type — so it says so.
         if (field.ref && index && typeof value === "string" && value) {
             const target = `${field.ref}-${value}`;
-            if (!index.resolve(note, target) && !index.manifestHit(target)) {
+            if (!index.resolve(note, target, true) && !index.manifestHit(target)) {
                 findings.push({
                     file: note.file,
                     ...at(head, value),
                     severity: "error",
                     message:
-                        `\`sohl.${field.name}\` names ${field.ref} ` +
+                        `${label} names ${field.ref} ` +
                         `"${value}", and no note or vendored manifest declares it`,
                 });
             }
@@ -356,11 +673,15 @@ export function lintNote(note, { schemas, index }) {
  * @param {object} index - From `buildLinkIndex`.
  * @param {object} opts
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
+ * @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}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index, { schemas, references = true }) {
+export function lintFrontmatter(index, { schemas, vocabulary, references = true, systems }) {
     const findings = [];
     const notes = [...index.notes].sort((a, b) =>
         a.file < b.file ? -1
@@ -371,7 +692,9 @@ export function lintFrontmatter(index, { schemas, references = true }) {
         findings.push(
             ...lintNote(note, {
                 schemas,
+                vocabulary,
                 index: references ? index : undefined,
+                ...(systems ? { systems } : {}),
             }),
         );
     }

package/engine/generate.mjs

@@ -53,6 +53,7 @@ import { countContentNotes } from "./content-tree.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { routerFor } from "./pack-router.mjs";
+import { unclaimedNoteFindings } from "./note-claims.mjs";
 
 /**
  * The compiler class for each Foundry document type a pack may hold.
@@ -94,16 +95,30 @@ export const packJsonDir = (name, config = loadPackConfig()) =>
  * order among packs of one type — and every one of them is written before the
  * actors pass that reads them.
  *
+ * **Scoped to one system when the caller has one (#58).** A being addresses an
+ * item by `(type, shortcode)`, and that address is unique within one system and
+ * not across two: `skill:sword` is an HM3 skill *and* a SoHL skill, with
+ * different data models behind them. The reference itself is unambiguous — it
+ * sits inside a system block, so position says which it means — but the
+ * resolver has to know which catalogue it is searching, or it resolves the pair
+ * by whichever pack was read first. So an Actor pass reads the Item packs of
+ * **its own** system plus the system-neutral ones, which belong to every
+ * system. Asking for no system reads them all, which is every single-system
+ * build and the behaviour this always had.
+ *
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
+ * @param {string|null} [system] - The system whose catalogue is wanted. Omitted
+ *   or `null`, every Item pack is read.
  * @returns {string[]} Each Item pack's JSON directory. Empty when the
  *   repository ships no items at all, which is a legitimate package: the actors
  *   pass accepts an empty list and reports an item it cannot resolve per
  *   `(type, shortcode)` instead, naming the being (#49).
  */
-export function itemPackJsonDirs(config = loadPackConfig()) {
+export function itemPackJsonDirs(config = loadPackConfig(), system = null) {
     return config.packs
         .filter((pack) => pack.type === "Item")
+        .filter((pack) => system == null || !pack.system || pack.system === system)
         .map((pack) => packJsonDir(pack.name, config));
 }
 
@@ -296,7 +311,9 @@ async function generatePack(
         // the Item packs, so the dependency is stated rather than assumed
         // (#1508) — and it is every Item pack, since a repository may ship more
         // than one (#1566).
-        itemsSourceDirs: itemPackJsonDirs(config),
+        // Scoped to this pack's system, so a being resolves `(type, shortcode)`
+        // against its own system's catalogue and the neutral one (#58).
+        itemsSourceDirs: itemPackJsonDirs(config, system ?? null),
         // The catalogue of a package this repository depends on but does
         // not contain, for a repository that authors beings without
         // holding the items they are assembled from. Cache-only: a cold
@@ -381,6 +398,17 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
         return 1;
     }
     log.info(`Content tree: ${noteCount} note(s) at ${contentBase}`);
+
+    // A note whose `type:` no configured pack claims compiles into nothing, and
+    // used to say nothing (#146) — no pass got far enough to reject it, so the
+    // silence had no owner. Asked once, of the whole configuration, because
+    // that is the only place it can be answered: a per-pass check would report
+    // every type a system deliberately does not map, which is exactly the
+    // silence #79 requires. Independent of `only`, since it is a fact about the
+    // configured pack list rather than about which passes this run executes.
+    const unclaimed = unclaimedNoteFindings(config);
+    for (const finding of unclaimed) emitDiagnostic(finding);
+
     fs.mkdirSync(config.paths.packJson, { recursive: true });
 
     // A companion pack has no pass of its own — naming it selects the pass that
@@ -419,10 +447,10 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
         for (const message of unsatisfied) {
             emitDiagnostic({ severity: "error", message });
         }
-        return unsatisfied.length;
+        return unsatisfied.length + unclaimed.length;
     }
 
-    let totalErrors = 0;
+    let totalErrors = unclaimed.length;
     const passes = [];
     for (const pack of ordered) {
         const { errors, compiled } = await generatePack(