@heroiclands/package-build 8.1.0 → 10.0.0

package/engine/base-compiler.mjs

@@ -79,6 +79,9 @@ import { emitDiagnostic } from "./diagnostics.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
 import { assertNoDraftField } from "./retired-fields.mjs";
 import { assertTypeNotRetired, packForType } from "./ids.mjs";
+import { carriesSystemBlock } from "./system-block.mjs";
+import { checkAuthoredSystemData, checkEmittedSystemData } from "./schema-check.mjs";
+import { locateFrontmatterKey } from "./retired-fields.mjs";
 
 /**
  * The tallies one pass accumulates while walking the tree.
@@ -93,8 +96,9 @@ import { assertTypeNotRetired, packForType } from "./ids.mjs";
  * @property {number} compiled - Notes that became a document.
  * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
  * @property {number} skippedOther - Notes this pass does not claim.
- * @property {number} declined - Notes refused because they declare a retired
- *   frontmatter field. Counted as errors, never as skips.
+ * @property {number} declined - Notes this pack **refused** — one declaring a
+ *   retired frontmatter field, or one routed to a system pack whose system it
+ *   says nothing about (#58). Counted as errors, never as skips.
  */
 
 /**
@@ -167,6 +171,26 @@ export class BasePackCompiler {
      */
     static readsPackOutputOf = Object.freeze([]);
 
+    /**
+     * Whether this pass's document **is** a system's data, and therefore takes
+     * only notes that carry that system's block (#58).
+     *
+     * A pack may declare a `system:` — `harn-ensemble` ships an `actors-hm3`
+     * and an `actors-sohl` from one tree — and the note-side half of that is
+     * the block named after the system. A note carrying no such block has
+     * nothing to say about it, so compiling it there would emit a **hollow
+     * document**: a subtype, and none of the fields the subtype exists for.
+     *
+     * False by default, because most passes write documents that are not
+     * system data at all. A JournalEntry of prose is the same document under
+     * either system, and a journals pack that declared one must not turn every
+     * doc note in the tree into a finding. The Item and Actor passes say so;
+     * anything else that genuinely writes a system's data says so too.
+     *
+     * @type {boolean}
+     */
+    static requiresSystemBlock = false;
+
     /** @type {string} */
     contentBase;
     /** @type {string} */
@@ -176,6 +200,19 @@ export class BasePackCompiler {
     /** @type {number} */
     errorCount = 0;
 
+    /**
+     * Emitted-`system` findings, one per `documentType|subtype|field` (#155).
+     *
+     * A key the compiler writes is on **every** document of a subtype, so
+     * reporting it where it is found would print the same sentence 3,126 times
+     * and bury the one that is not systemic. Collected here instead and flushed
+     * once at the end of the pass, keyed so the class of defect is reported
+     * once and the first document carrying it names a file a reader can open.
+     *
+     * @type {Map<string, {message: string, file: string|undefined}>}
+     */
+    emittedFindings = new Map();
+
     /**
      * The pack this pass writes, and the Foundry document type it holds.
      *
@@ -244,9 +281,7 @@ export class BasePackCompiler {
         routingReporter = false,
     } = {}) {
         if (!contentBase) {
-            throw new Error(
-                `${this.constructor.name} compiler requires \`contentBase\``,
-            );
+            throw new Error(`${this.constructor.name} compiler requires \`contentBase\``);
         }
         if (!fs.existsSync(contentBase)) {
             throw new Error(`Content tree not found at ${contentBase}`);
@@ -302,7 +337,36 @@ export class BasePackCompiler {
      */
     routesHere(fm) {
         if (!this.router || !this.packName || !this.docType) return true;
-        return this.router.resolve(fm, this.docType) === this.packName;
+        return (
+            this.router.resolve(fm, this.docType, this.packSystem ?? undefined) === this.packName
+        );
+    }
+
+    /**
+     * Whether a claimed, routed note may become this pack's document at all.
+     *
+     * The pack-eligibility gate, and it fails rather than skipping: a note that
+     * routed *here* and carries nothing for this pack's system is an authoring
+     * mistake with a hollow document at the end of it, not a note that belongs
+     * to another pass. Skipping it quietly is how a whole tree compiles to
+     * documents nobody can use — the failure mode #1502 and #56 are both
+     * instances of.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {boolean} True when the note may be compiled here.
+     * @throws {Error} When this pack's system is absent from the note. The
+     *   error carries a `position` where the note's own file can be read.
+     */
+    eligibleFor(fm) {
+        if (!this.constructor.requiresSystemBlock || !this.packSystem) return true;
+        if (carriesSystemBlock(fm, this.packSystem)) return true;
+        const label = fm?.name?.full ?? fm?.shortcode ?? fm?.id ?? "this note";
+        throw new Error(
+            `${label} carries no \`${this.packSystem}:\` block, so it has no ` +
+                `${this.packSystem} data to compile — but it routes to pack ` +
+                `"${this.packName}", which declares \`system: ${this.packSystem}\`. ` +
+                `Add the block, or route the note to a pack of another system.`,
+        );
     }
 
     /**
@@ -358,10 +422,7 @@ export class BasePackCompiler {
      */
     async prepare() {
         if (this.constructor.convertsWikilinks) {
-            this.linkIndex = buildContentLinkIndex(
-                this.contentBase,
-                this.router,
-            );
+            this.linkIndex = buildContentLinkIndex(this.contentBase, this.router);
             this.contentDocs = collectContentDocs(this.contentBase);
         }
         this.unresolvedLinks = 0;
@@ -447,6 +508,113 @@ export class BasePackCompiler {
         });
     }
 
+    /**
+     * Report every `<system>.system` key the receiving subtype does not declare
+     * (#58).
+     *
+     * An **error**, not a warning: Foundry drops an unknown `system` key at
+     * construction without a word, so the alternative is a document shipped
+     * with a field the author wrote and nobody will ever see. Each finding is
+     * located at the offending key where the file can be read, so it points at
+     * a line rather than at a note.
+     *
+     * Silent where nothing can answer — no published schema, or a subtype the
+     * artifact does not name. `content-build lint` says that out loud once for
+     * the whole build rather than once per note.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} block - The system block to read.
+     * @param {string} documentType - `Item`, `Actor`, …
+     * @param {string} subType - The subtype this note compiles into.
+     * @returns {number} How many findings were reported.
+     */
+    reportUndeclaredSystemData(fm, block, documentType, subType) {
+        const absPath = this.currentNote?.absPath;
+        const findings = checkAuthoredSystemData(fm, { block, documentType, subType });
+        for (const finding of findings) {
+            this.errorCount++;
+            const leaf = finding.path.split(".").pop();
+            this.noteError(finding.message, locateFrontmatterKey(absPath, leaf));
+        }
+        return findings.length;
+    }
+
+    /**
+     * Record every `system` key the *compiled document* carries that the
+     * receiving subtype does not declare (#155).
+     *
+     * The sibling of {@link BasePackCompiler#reportUndeclaredSystemData}, and
+     * the half that sees what no declaration states. A compiler writes keys of
+     * its own alongside the declared fields — `shortcode`, `actionDefs`,
+     * `notes`, `docHtml`, `archetype` — and neither the field-declaration check
+     * nor the authored-`system` check can see them, so until this nothing
+     * compared them at all. Foundry's discard is the same silent one either
+     * way.
+     *
+     * Called with the block **after** the builder, the authored merge and any
+     * conditional fields have all written into it, so what is checked is what
+     * the pack file receives.
+     *
+     * Recorded rather than reported: see {@link BasePackCompiler#emittedFindings}
+     * for why, and {@link BasePackCompiler#reportEmittedFindings} for where they
+     * come out.
+     *
+     * @param {object} system - The `system` block just assembled.
+     * @param {object} opts
+     * @param {object} opts.fm - The note's frontmatter.
+     * @param {string} opts.block - The system block the note writes.
+     * @param {string} opts.documentType - `Item`, `Actor`, …
+     * @param {string} opts.subType - The subtype this note compiles into.
+     * @param {string} opts.type - The note's content type.
+     * @param {readonly {to?: string}[]} [opts.fields] - The type's field
+     *   declaration, which tells a builder emission from a compiler one.
+     * @param {object} [opts.config] - The resolved build configuration.
+     * @returns {number} How many findings were new to this pass.
+     */
+    reportEmittedSystemData(system, { fm, block, documentType, subType, type, fields, config }) {
+        const findings = checkEmittedSystemData(system, {
+            fm,
+            block,
+            documentType,
+            subType,
+            type,
+            fields,
+            ...(config ? { config } : {}),
+        });
+        let added = 0;
+        for (const finding of findings) {
+            const key = `${finding.documentType}|${finding.subtype}|${finding.field}`;
+            if (this.emittedFindings.has(key)) continue;
+            this.emittedFindings.set(key, {
+                message: finding.message,
+                file: this.currentNote?.absPath,
+            });
+            added++;
+        }
+        return added;
+    }
+
+    /**
+     * Emit the collected emitted-`system` findings, once each.
+     *
+     * An **error**, for the reason #60 made its sibling one: the value is gone
+     * at load and the build says nothing, and severity that varied by *which
+     * part of the build wrote the key* would make the less fixable half the
+     * quieter one. What varies is the message, which says whose fix it is —
+     * see {@link module:engine/schema-check.emittedUndeclaredMessage}.
+     *
+     * @returns {number} How many were reported.
+     */
+    reportEmittedFindings() {
+        const found = this.emittedFindings;
+        this.emittedFindings = new Map();
+        for (const finding of found.values()) {
+            this.errorCount++;
+            emitDiagnostic({ file: finding.file, severity: "error", message: finding.message });
+        }
+        return found.size;
+    }
+
     /**
      * One note → one document. **Required.**
      *
@@ -457,9 +625,7 @@ export class BasePackCompiler {
      */
     // eslint-disable-next-line no-unused-vars
     buildEntry(fm, markdown) {
-        throw new Error(
-            `${this.constructor.name} must implement buildEntry(fm, markdown)`,
-        );
+        throw new Error(`${this.constructor.name} must implement buildEntry(fm, markdown)`);
     }
 
     /**
@@ -526,9 +692,7 @@ export class BasePackCompiler {
      */
     reportCompiled(stats) {
         const label = this.constructor.label;
-        log.info(
-            `Compiled ${stats.compiled} ${label}${stats.compiled === 1 ? "" : "s"}`,
-        );
+        log.info(`Compiled ${stats.compiled} ${label}${stats.compiled === 1 ? "" : "s"}`);
     }
 
     /**
@@ -538,9 +702,7 @@ export class BasePackCompiler {
      * @param {PassStats} stats - The pass's tallies.
      */
     reportDetail(stats) {
-        log.debug(
-            `Skipped ${stats.skippedOther} file(s) this pack does not claim`,
-        );
+        log.debug(`Skipped ${stats.skippedOther} file(s) this pack does not claim`);
     }
 
     /**
@@ -563,8 +725,8 @@ export class BasePackCompiler {
             // them in the skipped tally is the defect (#56). Each one has
             // already been named individually as a diagnostic.
             log.error(
-                `Declined ${stats.declined} note(s) declaring a retired ` +
-                    `frontmatter field`,
+                `Declined ${stats.declined} note(s) — each named above, with ` +
+                    `the reason this pack would not compile it`,
             );
         }
         this.reportDetail(stats);
@@ -588,13 +750,9 @@ export class BasePackCompiler {
         const label = this.constructor.label;
         const Label = label.charAt(0).toUpperCase() + label.slice(1);
 
-        for (const {
-            frontmatter: fm,
-            body,
-            absPath,
-            bodyLine,
-            bodyColumn,
-        } of walkMarkdownTree(this.contentBase)) {
+        for (const { frontmatter: fm, body, absPath, bodyLine, bodyColumn } of walkMarkdownTree(
+            this.contentBase,
+        )) {
             // Which note this pass is on, so anything it calls can report a
             // position without every method having to be handed one (#17).
             this.currentNote = { absPath, bodyLine, bodyColumn };
@@ -660,14 +818,24 @@ export class BasePackCompiler {
                 }
                 continue;
             }
+            // Whether this pack's system is one the note speaks for. Checked
+            // after routing — a note bound for another pack is none of this
+            // pass's business — and before `skipNote`, so a pass's own
+            // rejection rules never run on a note it may not compile.
+            try {
+                this.eligibleFor(fm);
+            } catch (err) {
+                stats.declined++;
+                this.errorCount++;
+                this.noteError(err.message, err.position);
+                continue;
+            }
             if (this.skipNote(fm, body)) {
                 stats.skippedOther++;
                 continue;
             }
 
-            log.debug(
-                `Processing ${this.noteLabel(fm)}: ${resolveName(fm)} (${absPath})`,
-            );
+            log.debug(`Processing ${this.noteLabel(fm)}: ${resolveName(fm)} (${absPath})`);
             try {
                 const doc = this.compileNote(fm, this.convertBody(fm, body));
                 stats.compiled++;
@@ -686,6 +854,10 @@ export class BasePackCompiler {
 
         this.compiledCount = stats.compiled;
         await this.finish(stats);
+        // After `finish`, because a pass that writes documents there (the
+        // scenes pass bundles an Adventure) has emitted them by now; before
+        // `report`, so the pass's summary counts them.
+        this.reportEmittedFindings();
         this.report(stats);
     }
 }

package/engine/code-fences.mjs

@@ -111,9 +111,7 @@ export function codeRegions(markdown, { spans = true } = {}) {
         const fence = FENCE_LINE.exec(line);
         if (fence) {
             const marker = fence[2];
-            const closer = new RegExp(
-                `^[ \\t]*${marker[0]}{${marker.length},}[ \\t]*$`,
-            );
+            const closer = new RegExp(`^[ \\t]*${marker[0]}{${marker.length},}[ \\t]*$`);
             let close = i + 1;
             while (close < lines.length && !closer.test(lines[close])) close++;
             // An unclosed fence runs to the end of the document.
@@ -225,9 +223,7 @@ function inside(regions, offset) {
  */
 function offsetOf(args) {
     const last = args[args.length - 1];
-    return typeof last === "string" ?
-            args[args.length - 2]
-        :   args[args.length - 3];
+    return typeof last === "string" ? args[args.length - 2] : args[args.length - 3];
 }
 
 /**
@@ -263,9 +259,7 @@ export function replaceOutsideCode(markdown, pattern, replacer, options) {
 export function matchAllOutsideCode(markdown, pattern, options) {
     const src = String(markdown ?? "");
     const regions = codeRegions(src, options);
-    return [...src.matchAll(pattern)].filter(
-        (match) => !inside(regions, match.index),
-    );
+    return [...src.matchAll(pattern)].filter((match) => !inside(regions, match.index));
 }
 
 /**
@@ -304,8 +298,5 @@ export function protectCode(body, transform) {
         last = region.end;
     }
     masked += src.slice(last);
-    return transform(masked).replace(
-        /\u0000(\d+)\u0000/g,
-        (_m, i) => stash[Number(i)],
-    );
+    return transform(masked).replace(/\u0000(\d+)\u0000/g, (_m, i) => stash[Number(i)]);
 }

package/engine/compendiums.mjs

@@ -87,17 +87,13 @@ export async function compilePacks({
     stageDest = config.paths.stage,
     packName,
 } = {}) {
-    const packNames = sourcePacks.filter(
-        (name) => !packName || name === packName,
-    );
+    const packNames = sourcePacks.filter((name) => !packName || name === packName);
 
     // A prebuilt pack's JSON is checked in rather than generated, so it is
     // compiled from where it lives. Anything else comes from the build-only
     // intermediate the generation pass writes.
     const prebuiltDirs = new Map(
-        config.packs
-            .filter((pack) => pack.prebuilt)
-            .map((pack) => [pack.name, pack.prebuilt]),
+        config.packs.filter((pack) => pack.prebuilt).map((pack) => [pack.name, pack.prebuilt]),
     );
     const needsGeneration = packNames.some((name) => !prebuiltDirs.has(name));
 
@@ -185,8 +181,7 @@ function cleanPackEntry(
     }
     delete data.flags?.importSource;
     delete data.flags?.exportSource;
-    if (data._stats?.lastModifiedBy)
-        data._stats.lastModifiedBy = lastModifiedBy;
+    if (data._stats?.lastModifiedBy) data._stats.lastModifiedBy = lastModifiedBy;
 
     // Remove empty entries in flags
     if (!data.flags) data.flags = {};
@@ -194,18 +189,11 @@ function cleanPackEntry(
         if (Object.keys(contents).length === 0) delete data.flags[key];
     });
 
-    if (data.effects)
-        data.effects.forEach((i) =>
-            cleanPackEntry(i, { clearSourceId: false }),
-        );
-    if (data.items)
-        data.items.forEach((i) => cleanPackEntry(i, { clearSourceId: false }));
-    if (data.pages)
-        data.pages.forEach((i) => cleanPackEntry(i, { ownership: -1 }));
-    if (data.system?.description)
-        data.system.description = cleanString(data.system.description);
-    if (data.system?.biography)
-        data.system.biography = cleanString(data.system.biography);
+    if (data.effects) data.effects.forEach((i) => cleanPackEntry(i, { clearSourceId: false }));
+    if (data.items) data.items.forEach((i) => cleanPackEntry(i, { clearSourceId: false }));
+    if (data.pages) data.pages.forEach((i) => cleanPackEntry(i, { ownership: -1 }));
+    if (data.system?.description) data.system.description = cleanString(data.system.description);
+    if (data.system?.biography) data.system.biography = cleanString(data.system.biography);
     if (data.system?.textReference)
         data.system.textReference = cleanString(data.system.textReference);
     if (data.system?.notes) data.system.notes = cleanString(data.system.notes);
@@ -249,10 +237,7 @@ export async function cleanPacks({
 
     const folders = fs
         .readdirSync(packDest, { withFileTypes: true })
-        .filter(
-            (file) =>
-                file.isDirectory() && (!packName || packName === file.name),
-        );
+        .filter((file) => file.isDirectory() && (!packName || packName === file.name));
 
     /**
      * Walk through directories to find JSON files.
@@ -273,9 +258,7 @@ export async function cleanPacks({
             const json = JSON.parse(await readFile(src, { encoding: "utf8" }));
             if (entryName && entryName !== json.name.toLowerCase()) continue;
             if (!json._id || !json._key) {
-                log.info(
-                    `Failed to clean \x1b[31m${src}\x1b[0m, must have _id and _key.`,
-                );
+                log.info(`Failed to clean \x1b[31m${src}\x1b[0m, must have _id and _key.`);
                 continue;
             }
             cleanPackEntry(json);
@@ -351,21 +334,14 @@ export async function unpackPacks({
         await extractPack(src, dest, {
             log: true,
             transformEntry: (entry) => {
-                if (entryName && entryName !== entry.name.toLowerCase())
-                    return false;
+                if (entryName && entryName !== entry.name.toLowerCase()) return false;
                 cleanPackEntry(entry);
             },
             transformName: (entry) => {
                 if (entry._id in folders)
-                    return path.join(
-                        "folder_",
-                        folders[entry._id].path,
-                        ".json",
-                    );
+                    return path.join("folder_", folders[entry._id].path, ".json");
                 const outputName = slugify(entry.name);
-                const parent =
-                    containers[entry.system?.container] ??
-                    folders[entry.folder];
+                const parent = containers[entry.system?.container] ?? folders[entry.folder];
                 return path.join(parent?.path ?? "", `${outputName}.json`);
             },
         });

package/engine/content-address.mjs

@@ -38,14 +38,14 @@ export const KB_PREFIX = "kb/";
  * The URL section a note routes to.
  *
  * A `doc` is narrative content whose only identity is its subtype label, so it
- * routes by `category`; every other type names its own section.
+ * routes by `subType`; every other type names its own section.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string|undefined} The section, or `undefined` when the note has
- *   none — a `doc` with no category has no address and is not published.
+ *   none — a `doc` with no subtype has no address and is not published.
  */
 export function sectionOf(fm) {
-    return fm.type === "doc" ? fm.category : fm.type;
+    return fm.type === "doc" ? fm.subType : fm.type;
 }
 
 /**
@@ -80,14 +80,12 @@ export function contentAddress(fm, name, isReadme) {
  */
 function landingOf(fm, isReadme, landing) {
     if (landing === "readme") {
-        return isReadme ?
-                { landing: true, segment: sectionOf(fm) }
-            :   { landing: false };
+        return isReadme ? { landing: true, segment: sectionOf(fm) } : { landing: false };
     }
     // `collection`. The section is authored rather than derived: it is the
     // identity of the section being introduced, and the note's own title
     // ("Creatures") is presentation, which would slug to something else.
-    if (fm.type === "doc" && fm.category === "collection") {
+    if (fm.type === "doc" && fm.subType === "collection") {
         return { landing: true, segment: fm.section || fm.slug };
     }
     return { landing: false };
@@ -127,9 +125,7 @@ export function packageAddress(fm, name, { isReadme = false, scheme } = {}) {
     const land = landingOf(fm, isReadme, landing);
     if (land.landing) {
         if (typeof land.segment !== "string" || !land.segment) {
-            throw new Error(
-                `landing note declares no section, so it lands nowhere`,
-            );
+            throw new Error(`landing note declares no section, so it lands nowhere`);
         }
         return `${prefix}${land.segment}/`;
     }