@heroiclands/package-build 8.1.0 → 10.0.0

package/engine/scene-levels.mjs

@@ -87,9 +87,7 @@ const LEVEL_SPLITTING_CLI = "3.0.3";
  */
 export function compendiumCliVersion() {
     try {
-        return createRequire(import.meta.url)(
-            "@foundryvtt/foundryvtt-cli/package.json",
-        ).version;
+        return createRequire(import.meta.url)("@foundryvtt/foundryvtt-cli/package.json").version;
     } catch {
         return undefined;
     }
@@ -128,8 +126,7 @@ function levelIdOf(entry) {
  * @returns {string} A phrase naming the entry, never `[object Object]`.
  */
 function describeEntry(entry, index) {
-    if (isInlineLevel(entry))
-        return `\`levels[${index}]\` is ${describeShape(entry)}`;
+    if (isInlineLevel(entry)) return `\`levels[${index}]\` is ${describeShape(entry)}`;
     return `\`levels[${index}]\` is ${JSON.stringify(entry) ?? String(entry)}`;
 }
 
@@ -234,15 +231,11 @@ function describeRemedy(cliVersion) {
  * @returns {string} One report covering every affected scene.
  */
 function describeWholesaleLoss(declaring, cliVersion) {
-    const inline = declaring.some(([, scene]) =>
-        declaredLevels(scene).some(isInlineLevel),
-    );
+    const inline = declaring.some(([, scene]) => declaredLevels(scene).some(isInlineLevel));
     const list = declaring
         .map(([sceneId, scene]) => {
             const entries = declaredLevels(scene)
-                .map((entry) =>
-                    isInlineLevel(entry) ? describeShape(entry) : `"${entry}"`,
-                )
+                .map((entry) => (isInlineLevel(entry) ? describeShape(entry) : `"${entry}"`))
                 .join(", ");
             return `${nameScene(sceneId, scene)} → ${entries}`;
         })
@@ -329,9 +322,7 @@ export function checkSceneLevels(records, { cliVersion } = {}) {
     // No scene in the pack has a Level record: one fact about the compile,
     // which saying per scene would bury. Scenes declaring nothing are not
     // covered by it, so they are still judged individually below.
-    const declaring = scenes.filter(
-        ([, scene]) => declaredLevels(scene).length,
-    );
+    const declaring = scenes.filter(([, scene]) => declaredLevels(scene).length);
     const wholesale = levelKeys.size === 0 && declaring.length > 0;
     if (wholesale) problems.push(describeWholesaleLoss(declaring, cliVersion));
 
@@ -357,9 +348,7 @@ export function checkSceneLevels(records, { cliVersion } = {}) {
                         `${LEVEL_SPLITTING_CLI} writes.`,
                 );
             } else if (!id) {
-                broken.push(
-                    `${where}: ${describeEntry(entry, index)}, not a Level id.`,
-                );
+                broken.push(`${where}: ${describeEntry(entry, index)}, not a Level id.`);
             } else if (!levelKeys.has(`${sceneId}.${id}`)) {
                 broken.push(
                     `${where} lists level "${id}", but no record exists at ` +
@@ -372,16 +361,13 @@ export function checkSceneLevels(records, { cliVersion } = {}) {
         // A broken entry is already reported above; only the declaration
         // itself is judged here, so nothing is reported twice.
         if (broken.length) problems.push(...broken);
-        else
-            problems.push(...checkDeclaredLevels(scene ?? {}, declared, where));
+        else problems.push(...checkDeclaredLevels(scene ?? {}, declared, where));
     }
 
     for (const adventure of adventures) {
         const inline = Array.isArray(adventure?.scenes) ? adventure.scenes : [];
         for (const scene of inline) {
-            const levelIds = declaredLevels(scene).map(
-                (level) => levelIdOf(level) ?? level,
-            );
+            const levelIds = declaredLevels(scene).map((level) => levelIdOf(level) ?? level);
             const where =
                 `Adventure "${adventure?.name ?? adventure?._id}" scene ` +
                 `"${scene?.name ?? scene?._id}"`;

package/engine/scenes.mjs

@@ -51,25 +51,21 @@ import fs from "fs";
 import path from "path";
 import log from "loglevel";
 
-import {
-    walkMarkdownTree,
-    sohlField,
-    resolveName,
-    slugify,
-    defaultStats,
-} from "./helpers.mjs";
+import { walkMarkdownTree, sohlField, resolveName, slugify, defaultStats } from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
 import { buildJournalEntry, splitPages, journalPageId } from "./journals.mjs";
 import { compendiumUuid, makeId, packForType } from "./ids.mjs";
 import { packRouter } from "./pack-router.mjs";
 import { foundryPackageId } from "./content-package.mjs";
 import { itemDocEntryId } from "./item-docs.mjs";
+import { behaviorDocId, buildScene, isMapType, regionDocId } from "./map-notes.mjs";
 import {
-    behaviorDocId,
-    buildScene,
-    isMapType,
-    regionDocId,
-} from "./map-notes.mjs";
+    RETIRED_FIELD_ALIASES,
+    declaresRetiredAlias,
+    locateFrontmatterKey,
+    readAliasedField,
+    retiredAliasMessage,
+} from "./retired-fields.mjs";
 
 /**
  * Every SoHL action name this build knows about, for the `action:` warning on a
@@ -158,9 +154,7 @@ export class Scenes extends BasePackCompiler {
     }) {
         super({ contentBase, dest, folderResolver });
         if (!companionDests.adventures) {
-            throw new Error(
-                "Scenes compiler requires an `adventures` companion destination",
-            );
+            throw new Error("Scenes compiler requires an `adventures` companion destination");
         }
         Object.defineProperty(this, "adventureDir", {
             value: companionDests.adventures,
@@ -188,30 +182,21 @@ export class Scenes extends BasePackCompiler {
     #collect() {
         const maps = [];
         const effectsByAddress = new Map();
-        for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(
-            this.contentBase,
-        )) {
+        for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(this.contentBase)) {
             // No retired-field test: this pass's own walk — the shared compile
             // loop — is where a note still declaring `package:` (#56) or
             // `draft:` (#69) is reported, once. Repeating either check here
             // would double the diagnostic or throw past it. A refused note is
             // indexed and then never compiled, so it reaches no document.
             if (!fm || !fm.id) continue;
-            if (
-                fm.shortcode &&
-                Array.isArray(fm.effects) &&
-                fm.effects.length
-            ) {
+            if (fm.shortcode && Array.isArray(fm.effects) && fm.effects.length) {
                 effectsByAddress.set(`${fm.type}-${fm.shortcode}`, {
                     id: fm.id,
                     type: fm.type,
                     // Where the owning item landed, so a region behaviour's
                     // effect reference addresses the right pack when a
                     // repository ships several of one type (#1566).
-                    pack: packRouter().resolveOrNull(
-                        fm,
-                        packForType(fm.type).docType,
-                    ),
+                    pack: packRouter().resolveOrNull(fm, packForType(fm.type).docType),
                     effects: fm.effects,
                 });
             }
@@ -239,17 +224,13 @@ export class Scenes extends BasePackCompiler {
                 throw new Error(`Map note missing shortcode: ${absPath}`);
             }
             if (index.has(fm.shortcode)) {
-                throw new Error(
-                    `Two map notes share the shortcode "${fm.shortcode}"`,
-                );
+                throw new Error(`Two map notes share the shortcode "${fm.shortcode}"`);
             }
             const regions = new Map();
             for (const [key, spec] of Object.entries(fm.sohl?.regions ?? {})) {
                 const id = regionDocId(fm.id, key, spec?._id);
                 const behaviors = new Map();
-                for (const [bKey, bSpec] of Object.entries(
-                    spec?.behaviors ?? {},
-                )) {
+                for (const [bKey, bSpec] of Object.entries(spec?.behaviors ?? {})) {
                     behaviors.set(bKey, behaviorDocId(id, bKey, bSpec?._id));
                 }
                 regions.set(key, { id, behaviors });
@@ -283,9 +264,7 @@ export class Scenes extends BasePackCompiler {
             const mapKey = addr.map ?? selfShortcode;
             const target = index.get(mapKey);
             if (!target) {
-                throw new Error(
-                    `${label}: no map note has the shortcode "${mapKey}"`,
-                );
+                throw new Error(`${label}: no map note has the shortcode "${mapKey}"`);
             }
             const region = target.regions.get(addr.region);
             if (!region) {
@@ -305,9 +284,7 @@ export class Scenes extends BasePackCompiler {
             resolveBehaviorRef: (addr, label) => {
                 const { target, region } = lookupRegion(addr, label);
                 if (!addr.behavior) {
-                    throw new Error(
-                        `${label}: a behaviour reference is {map, region, behavior}`,
-                    );
+                    throw new Error(`${label}: a behaviour reference is {map, region, behavior}`);
                 }
                 const behaviorId = region.behaviors.get(addr.behavior);
                 if (!behaviorId) {
@@ -317,8 +294,7 @@ export class Scenes extends BasePackCompiler {
                     );
                 }
                 return (
-                    `Scene.${target.sceneId}.Region.${region.id}` +
-                    `.RegionBehavior.${behaviorId}`
+                    `Scene.${target.sceneId}.Region.${region.id}` + `.RegionBehavior.${behaviorId}`
                 );
             },
             resolveEffectRef: (addr, label) => {
@@ -409,6 +385,17 @@ export class Scenes extends BasePackCompiler {
         // pass has to read the other's output.
         const entryId = hasBody ? itemDocEntryId(fm.id) : undefined;
         const folder = this.folderResolver(sohlField(fm, "folder", null));
+        // The retired spelling of the background art, reported where an author
+        // meets it soonest — every consumer runs the compile, and not every
+        // one runs the lint (#142). Located by reading the note back, which is
+        // what the other retired-field reports do: this is the one path that
+        // needs the position, so it is paid for only here.
+        if (declaresRetiredAlias(fm, "img")) {
+            this.noteWarn(
+                retiredAliasMessage(RETIRED_FIELD_ALIASES.img, "img"),
+                locateFrontmatterKey(this.currentNote?.absPath, RETIRED_FIELD_ALIASES.img),
+            );
+        }
         const warnings = [];
         const scene = buildScene(fm, {
             packageId: foundryPackageId(),
@@ -420,8 +407,7 @@ export class Scenes extends BasePackCompiler {
             // default JournalEntry pack, not in whichever Scene pack the map
             // itself was routed to (#1566).
             journalPack: packRouter().defaultOf("JournalEntry"),
-            pageIds:
-                hasBody ? this.#pageIds(markdown, entryId, name) : new Map(),
+            pageIds: hasBody ? this.#pageIds(markdown, entryId, name) : new Map(),
             knownActions: this.knownActions,
             warnings,
             ...this.#resolvers(this.index, this.effectsByAddress, fm.shortcode),
@@ -455,7 +441,7 @@ export class Scenes extends BasePackCompiler {
             this.places.set(placeKey, {
                 key: placeKey,
                 name: sohlField(fm, "placeName", null) || name,
-                img: sohlField(fm, "image", null),
+                img: readAliasedField(fm, "img") ?? null,
                 pinned: false,
                 scenes: [],
                 journal: [],
@@ -489,9 +475,7 @@ export class Scenes extends BasePackCompiler {
 
     /** @inheritdoc */
     reportCompiled(stats) {
-        log.info(
-            `Compiled ${stats.compiled} scene(s) and ${this.adventureCount} adventure(s)`,
-        );
+        log.info(`Compiled ${stats.compiled} scene(s) and ${this.adventureCount} adventure(s)`);
     }
 
     /**

package/engine/schema-check.mjs

@@ -32,10 +32,20 @@
  * documents' `system` keys against `defineSchema()` **by hand**, which is how
  * the next one would have to be found too.
  *
- * **The emitted half needs no compilation and no parsing.** A builder *is* its
+ * **The declared half of the emission is statically known.** A builder *is* its
  * field list — {@link module:engine/field-spec} makes `buildFromFields` the only
- * statement of the mapping — so every `system` path a type can emit is
- * `field.to`, known statically. Nothing here compiles a document to find out.
+ * statement of the mapping — so every `system` path a *declared field* emits is
+ * `field.to`. {@link compareFields} needs no compilation to read that.
+ *
+ * **The rest of the emission is only observable.** A compiler writes keys of
+ * its own alongside the declared fields — `shortcode`, `actionDefs`, `notes`,
+ * `docHtml`, and since #126 `archetype` — and those appear in neither set
+ * {@link compareFields} compares, so nothing compared them at all (#155). They
+ * cannot be listed here without the list going stale the next time a compiler
+ * grows a key, so they are read off the `system` object the compiler produced:
+ * {@link compareEmittedSystem} takes the assembled block and asks what the
+ * schema does not declare. That is the same question, against the same schema,
+ * with the emitted set *observed* rather than derived.
  *
  * **The declared half is the consumer's, and arrives as data.** `defineSchema()`
  * lives in the target system's `src/`, so the system publishes its field sets as
@@ -56,6 +66,8 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { cachedSchemaPath, SCHEMA_ARTIFACT_FILE } from "./foreign-catalog.mjs";
+import { loadPackConfig } from "./pack-config.mjs";
+import { systemData, systemDataPaths, undeclaredPaths } from "./system-block.mjs";
 
 /**
  * The artifact version this module reads.
@@ -239,6 +251,186 @@ export function compareFields({
     return { undeclared, unemitted, skipped };
 }
 
+/**
+ * One `system` key a compiled document carries that its subtype does not
+ * declare.
+ *
+ * @typedef {object} EmissionFinding
+ * @property {string} type - The content type whose note produced the document.
+ * @property {string} subtype - The document subtype it compiled into.
+ * @property {string} documentType - `Item`, `Actor`, …
+ * @property {string} field - The undeclared path, dotted.
+ * @property {string} systemVersion - The version checked against.
+ * @property {"builder"|"compiler"} origin - What wrote it. See
+ *   {@link emittedUndeclaredMessage}.
+ */
+
+/**
+ * Whether a value is a mapping this walk descends into. Arrays are leaves: a
+ * schema declares an `ArrayField` as one path and says nothing about its
+ * indices.
+ *
+ * @param {unknown} value - The emitted value.
+ * @returns {boolean} Whether to walk into it.
+ */
+function isMapping(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Every declared path that has at least one declared path beneath it.
+ *
+ * The artifact does not describe every subtree it declares. A discriminated
+ * `TypedSchemaField` — SoHL's `strikeMode` — is published as the single path
+ * `strikeMode`, because its sub-schema is chosen by a discriminator at runtime
+ * and there is no one field list to publish; the compiled document stores it
+ * flat as `{ type, name, … }` all the same. Walking into it against a schema
+ * that says nothing about its contents reported all ten of a combat technique's
+ * stored keys as undeclared — ten findings, every one wrong, about a document
+ * that is correct.
+ *
+ * So a container is descended into only where the artifact actually enumerates
+ * something beneath it. That is the same stance {@link declaredFields} takes on
+ * a subtype the artifact does not name: what is not described is not checked,
+ * rather than guessed at.
+ *
+ * @param {ReadonlySet<string>} declared - Every path the subtype declares.
+ * @returns {Set<string>} The paths whose subtree the artifact describes.
+ */
+function enumeratedContainers(declared) {
+    const out = new Set();
+    for (const declaredPath of declared) {
+        const parts = declaredPath.split(".");
+        for (let i = 1; i < parts.length; i++) out.add(parts.slice(0, i).join("."));
+    }
+    return out;
+}
+
+/**
+ * The paths in a compiled `system` block that the subtype does not declare.
+ *
+ * {@link module:engine/system-block.undeclaredPaths} answers this for *authored*
+ * data, where every path came from a human and every container is one a human
+ * typed. An emitted block is different in one way that matters: it contains
+ * whole subtrees the artifact declares as a single path and describes no
+ * further — see {@link enumeratedContainers} — so the walk stops there instead
+ * of reporting their contents.
+ *
+ * Reported at the shallowest undeclared path, as its sibling is: everything
+ * beneath an undeclared container is undeclared by construction, and listing it
+ * all buries the one key that is the problem.
+ *
+ * @param {Record<string, unknown>} data - The emitted `system` block.
+ * @param {ReadonlySet<string>} declared - Every path the subtype declares.
+ * @param {ReadonlySet<string>} enumerated - From {@link enumeratedContainers}.
+ * @param {string} [prefix] - Internal: the path so far.
+ * @returns {string[]} The undeclared paths, shallowest-first.
+ */
+function undeclaredEmittedPaths(data, declared, enumerated, prefix = "") {
+    const out = [];
+    if (!isMapping(data)) return out;
+    for (const [key, value] of Object.entries(data)) {
+        const emittedPath = prefix ? `${prefix}.${key}` : key;
+        if (!declared.has(emittedPath)) {
+            out.push(emittedPath);
+            continue;
+        }
+        if (!isMapping(value) || !Object.keys(value).length) continue;
+        if (!enumerated.has(emittedPath)) continue;
+        out.push(
+            ...undeclaredEmittedPaths(
+                /** @type {Record<string, unknown>} */ (value),
+                declared,
+                enumerated,
+                emittedPath,
+            ),
+        );
+    }
+    return out;
+}
+
+/**
+ * What a **compiled document** carries in `system`, against what the receiving
+ * subtype declares (#155).
+ *
+ * The third of the three checks, and the only one whose emitted set is
+ * *observed*. {@link compareFields} reads the `itemBuilders` declarations and
+ * {@link checkAuthoredSystemData} reads a note's `<system>.system`; between them
+ * they miss every key a compiler writes on its own initiative, which is not a
+ * residue — it is `shortcode`, `actionDefs`, `notes`, `docHtml` and `archetype`.
+ *
+ * **The keys come from the object the compiler built, after a JSON round trip.**
+ * That is exactly what the pack file receives, so a key whose value is
+ * `undefined` — dropped by `JSON.stringify`, never written, nothing for Foundry
+ * to discard — is correctly not a finding. Reading the assembled block is also
+ * the only derivation that cannot go stale: a compiler that grows a key is
+ * checked on the next build without anyone remembering to add it to a list.
+ *
+ * **Authored paths are left alone.** A note's own `<system>.system` is reported
+ * by {@link checkAuthoredSystemData}, which can point at the line the author
+ * wrote; reporting it again here would be the same defect twice, once without a
+ * position.
+ *
+ * **A subtree the artifact does not describe is not checked**, rather than
+ * reported wholesale — see {@link enumeratedContainers} for the
+ * `TypedSchemaField` case that makes the distinction load-bearing.
+ *
+ * @param {object} opts
+ * @param {object} opts.system - The `system` block the compiler assembled.
+ * @param {SchemaArtifact} opts.artifact - The receiving system's schemas.
+ * @param {string} opts.documentType - `Item`, `Actor`, …
+ * @param {string} opts.subtype - The document subtype being emitted.
+ * @param {string} opts.type - The content type whose note produced it, for the
+ *   message.
+ * @param {readonly {to?: string}[]} [opts.fields] - The type's field
+ *   declaration, which decides a finding's {@link EmissionFinding.origin}.
+ * @param {ReadonlySet<string>} [opts.authored] - Paths the note authored, left
+ *   to the note-side check.
+ * @returns {EmissionFinding[]} One per undeclared path, shallowest-first.
+ */
+export function compareEmittedSystem({
+    system,
+    artifact,
+    documentType,
+    subtype,
+    type,
+    fields,
+    authored = new Set(),
+}) {
+    if (artifact?.version !== SCHEMA_ARTIFACT_VERSION) {
+        throw new Error(
+            `package-build: schema artifact version ${artifact?.version ?? "(absent)"}, ` +
+                `expected ${SCHEMA_ARTIFACT_VERSION}. A schema read under the wrong ` +
+                `shape would report confidently in both directions, so the check ` +
+                `stops rather than resolving anyway.`,
+        );
+    }
+
+    const declared = declaredFields(artifact, documentType, subtype);
+    // Not a finding, for the same reason `compareFields` skips one: a subtype
+    // the artifact says nothing about is a routing question (#79), not a field
+    // one, and guessing at it would report every key on the document.
+    if (!declared) return [];
+
+    // What the pack file receives. `undefined` is gone after this, which is the
+    // point: a key that never reaches the JSON is not an emitted key.
+    const emitted = JSON.parse(JSON.stringify(system ?? {}));
+    const byField = emittedFields(fields ?? []);
+
+    return undeclaredEmittedPaths(emitted, declared.all, enumeratedContainers(declared.all))
+        .filter((field) => !authored.has(field))
+        .map((field) => ({
+            type,
+            subtype,
+            documentType,
+            field,
+            systemVersion: artifact.systemVersion,
+            origin: /** @type {"builder"|"compiler"} */ (
+                byField.has(field) ? "builder" : "compiler"
+            ),
+        }));
+}
+
 /**
  * The published schema this build should check itself against, or `null`.
  *
@@ -277,10 +469,7 @@ export function resolveSchemaArtifact(config) {
     });
 
     // The system checking itself, against the schema its own build published.
-    if (
-        config.packageKind === "systems" &&
-        config.foundryPackage === systemId
-    ) {
+    if (config.packageKind === "systems" && config.foundryPackage === systemId) {
         const own = path.join(config.rootDir, SCHEMA_ARTIFACT_FILE);
         return fs.existsSync(own) ? read(own) : null;
     }
@@ -330,3 +519,155 @@ export function unemittedMessage(finding) {
         `field's initial value rather than an authored one`
     );
 }
+
+/**
+ * What an author is told about an emitted key the target system does not
+ * define — in the terms of whoever can actually fix it.
+ *
+ * The failure is identical in both cases and the remedies are not, which is
+ * why the two are told apart at all:
+ *
+ * | origin | who writes it | what fixes it |
+ * | --- | --- | --- |
+ * | `builder` | a `fields:` entry in this repository's `itemBuilders` | change the field's `to`, or get the system to declare it |
+ * | `compiler` | this package, on every document of the subtype | **nothing here** — the system must declare it, or this package must be pinned to a build that does not write it |
+ *
+ * A `compiler` finding is the one worth spelling out, because the obvious first
+ * move — go and look for the field in `itemBuilders` — leads nowhere: there is
+ * no declaration to correct. It means the build is running ahead of the system
+ * it compiles for, and the version named in the message is what says so.
+ *
+ * @param {EmissionFinding} finding - One entry from
+ *   {@link compareEmittedSystem}.
+ * @returns {string} The message.
+ */
+export function emittedUndeclaredMessage(finding) {
+    if (finding.origin === "builder") return undeclaredMessage(finding);
+    return (
+        `the compiler writes \`system.${finding.field}\` into every ` +
+        `${finding.documentType} of subtype "${finding.subtype}", and no field ` +
+        `declaration names it — ${finding.documentType} subtype ` +
+        `"${finding.subtype}" does not define it at ${finding.systemVersion}, and ` +
+        `Foundry discards an unknown \`system\` key when the document is ` +
+        `constructed, without a warning, so the value is lost at load while the ` +
+        `build reports success. No \`itemBuilders\` change fixes this: declare ` +
+        `the field in the receiving system, or hold this package at a build that ` +
+        `does not write it`
+    );
+}
+
+/** One resolved schema artifact per resolved configuration. */
+const artifacts = new WeakMap();
+
+/**
+ * {@link resolveSchemaArtifact}, read once per configuration.
+ *
+ * The per-note check below runs thousands of times in a build and the artifact
+ * never changes inside one, so reading and parsing it per note would be a
+ * megabyte of JSON per hundred documents for an answer that is already known.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {{artifact: SchemaArtifact, source: string}|null} The schema.
+ */
+function schemaFor(config) {
+    if (!artifacts.has(config)) artifacts.set(config, resolveSchemaArtifact(config));
+    return artifacts.get(config);
+}
+
+/**
+ * What a note authors under `<system>.system`, against what the receiving
+ * subtype declares (#58).
+ *
+ * The **note-side** half of the check `compareFields` performs on the
+ * declarations. A field list is checked once for the whole build because it is
+ * the same for every document; an authored `system` block is a property of one
+ * note, so it is checked where that note is compiled and reported against that
+ * note's file.
+ *
+ * It is the same failure either way, and the reason both halves exist: Foundry
+ * discards an unknown `system` key at construction and says nothing, so a
+ * mistyped path is lost at load while the build reports success.
+ *
+ * **Silent where there is nothing to check against.** A module pinning a system
+ * version released before the artifact existed, or a subtype the artifact does
+ * not name, produces no findings — the same stance `compareFields` takes, where
+ * an unknown subtype is a routing question rather than a field one. The
+ * whole-build check in `content-build lint` is where a missing artifact is said
+ * out loud, once, instead of per note.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} opts
+ * @param {string} opts.block - The system block to read, e.g. `"sohl"`.
+ * @param {string} opts.documentType - `Item`, `Actor`, …
+ * @param {string} opts.subType - The document subtype the note compiles into.
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @returns {{path: string, message: string}[]} One finding per undeclared path,
+ *   shallowest-first.
+ */
+export function checkAuthoredSystemData(
+    fm,
+    { block, documentType, subType, config = loadPackConfig() },
+) {
+    const data = systemData(fm, block);
+    if (!Object.keys(data).length) return [];
+
+    const schema = schemaFor(config);
+    if (!schema) return [];
+    const declared = declaredFields(schema.artifact, documentType, subType);
+    if (!declared) return [];
+
+    return undeclaredPaths(data, declared.all).map((path) => ({
+        path,
+        message:
+            `\`${block}.system.${path}\` is not a field ${documentType} subtype ` +
+            `"${subType}" declares at ${schema.artifact.systemVersion} — Foundry ` +
+            `discards an unknown \`system\` key when the document is constructed, ` +
+            `without a warning, so the value is lost at load while the build ` +
+            `reports success`,
+    }));
+}
+
+/**
+ * The `system` block a compiler just assembled, against what the receiving
+ * subtype declares (#155).
+ *
+ * The build-time face of {@link compareEmittedSystem}: it resolves the schema
+ * the way every other check here does — the system's own committed artifact, or
+ * the cached one from the release a module pins — and attaches the message a
+ * reader sees.
+ *
+ * **Silent where there is nothing to check against**, exactly as its two
+ * siblings are: a module pinning a system version released before the artifact
+ * existed, or a subtype the artifact does not name, produces no findings.
+ * `content-build lint` is where a missing artifact is said out loud, once.
+ *
+ * @param {object} system - The `system` block the compiler produced.
+ * @param {object} opts
+ * @param {object} opts.fm - The note's frontmatter, for the authored paths this
+ *   check leaves to {@link checkAuthoredSystemData}.
+ * @param {string} opts.block - The system block to read, e.g. `"sohl"`.
+ * @param {string} opts.documentType - `Item`, `Actor`, …
+ * @param {string} opts.subType - The document subtype the note compiles into.
+ * @param {string} opts.type - The note's content type, for the message.
+ * @param {readonly {to?: string}[]} [opts.fields] - The type's field
+ *   declaration, which decides each finding's origin.
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @returns {(EmissionFinding & {message: string})[]} One per undeclared path.
+ */
+export function checkEmittedSystemData(
+    system,
+    { fm, block, documentType, subType, type, fields, config = loadPackConfig() },
+) {
+    const schema = schemaFor(config);
+    if (!schema) return [];
+
+    return compareEmittedSystem({
+        system,
+        artifact: schema.artifact,
+        documentType,
+        subtype: subType,
+        type,
+        fields,
+        authored: new Set(systemDataPaths(systemData(fm, block))),
+    }).map((finding) => ({ ...finding, message: emittedUndeclaredMessage(finding) }));
+}