@heroiclands/package-build 6.1.0 → 8.0.0

package/CONTENT.md

@@ -155,7 +155,9 @@ the file sits in, fills the optional halves with their defaults
 manifest switches off and `publish.site` at its `homepage` floor),
 derives `assetRoot`, `packDirectories`, `itemTypes` and `docEntryTypes`, and
 freezes the result. A malformed configuration throws a `TypeError` naming the
-offending field, so it fails at load rather than as an empty pack much later.
+offending field — and the line and column it was written on, in the
+[located form](#diagnostics) — so it fails at load rather than as an empty pack
+much later.
 
 **Four values are derived rather than authored**, because each is something a
 file can be asked for rather than told:
@@ -1160,6 +1162,24 @@ Two rules keep it that way, both in `engine/diagnostics.mjs`:
   meaningless, `file: …` when only the note is known. Nothing defaults to
   `1:1`, which would send a reader to the frontmatter every time.
 
+**A configuration error is located the same way.** Every check in
+`content-config.mjs` and `config.mjs` reports through one `fail()`, naming the
+offending key's dotted path — a good description and a bad locator, in a file
+that runs to hundreds of lines with sibling entries flow-mapped onto one. The
+path now rides on the error, and the loader that read the file resolves it
+against the YAML, so all of them come out located:
+
+```text
+package-build.config.yaml:382:64: error: package-build config: `site.sections.being.descrption` is not a recognized option (expected one of: title, banner).
+```
+
+The same two rules apply. A key the file never declares — a required one that is
+simply missing — has no node of its own, so the position names the **mapping it
+belongs in** and no further out; a missing _top-level_ key has nothing above it
+but the document, and an `.mjs` configuration has no YAML to resolve a path
+against at all. Both report `package-build.config.yaml: error: …`, the file
+without a line, rather than a line that would be wrong.
+
 Establishing a position at all takes three corrections, applied only where they
 hold — see `positionInBody`. A body offset is not a file line until the
 frontmatter's lines are added (`bodyLine`); the trim that strips the body can

package/bin/content-build.mjs

@@ -73,6 +73,12 @@ import {
 import { renderItemFieldReference } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
+import {
+    compareFields,
+    resolveSchemaArtifact,
+    undeclaredMessage,
+    unemittedMessage,
+} from "../engine/schema-check.mjs";
 // The one vocabulary, loaded whole. Every content project authors the full type
 // set — an adventure module ships skills, beings and magic swords — so no
 // consumer gets a subset (#19, #20).
@@ -156,6 +162,25 @@ prefix.apply(log, {
     },
 });
 
+/**
+ * Report a command's failure.
+ *
+ * A configuration error carries its own `file:line:column: error: ` locator
+ * (#95), and `loglevel`'s `[timestamp] [ERROR]:` prefix occupies exactly the
+ * position a parser reads the path from — so a located failure is printed
+ * unprefixed, as `emitDiagnostic` prints every other finding. Everything else
+ * is ordinary prose and keeps the log line it always had.
+ *
+ * @param {unknown} err - What was thrown.
+ * @returns {void}
+ */
+function reportFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/** @type {{located?: boolean}} */ (err)?.located)
+        console.error(message);
+    else log.error(message);
+}
+
 const argv = yargs(hideBin(process.argv))
     .command(packageCommand())
     .command(depsCommand())
@@ -303,7 +328,7 @@ function docsCommand() {
                     process.stdout.write(page);
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -367,9 +392,79 @@ function lintCommand() {
                     references: argv.references,
                 });
 
+                // What the builders emit, against what the receiving system
+                // declares (#60). Reported here rather than at compile: it is
+                // a property of the *declarations*, not of any one note, so it
+                // is the same answer for every document and belongs where a
+                // reader is already being told about the vocabulary.
+                const schema = resolveSchemaArtifact(config);
+                const schemaFindings = [];
+                if (!schema && config.stats?.systemId) {
+                    // Said out loud, because a check that quietly does nothing
+                    // is indistinguishable from one that passed — and this
+                    // whole issue exists because a defect went unnoticed for a
+                    // release. A system before its first schema build, or a
+                    // module pinning a version released before the artifact
+                    // existed, lands here.
+                    log.info(
+                        `No published schema for ${config.stats.systemId}` +
+                            `@${config.stats.systemVersion ?? "?"}, so emitted ` +
+                            `\`system\` fields are unchecked. A system ` +
+                            `generates its own; a module gets one from ` +
+                            `\`content-build deps fetch\`.`,
+                    );
+                }
+                const fieldSpecs = config.itemFields ?? {};
+                const comparable = Object.keys(fieldSpecs).length > 0;
+                if (schema && !comparable) {
+                    // A schema, and nothing to compare it against. The emitted
+                    // side of this check is the `fields:` of `itemBuilders`, so
+                    // a package whose compendium content is committed JSON
+                    // rather than built from field declarations has an empty
+                    // one — and every field the system declares would be
+                    // reported as unemitted. That is hundreds of findings whose
+                    // only content is that this package does not build
+                    // documents this way, which is not news and not a defect.
+                    //
+                    // Said out loud rather than skipped in silence, for the
+                    // same reason the absent-schema case is: a check that
+                    // quietly does nothing reads exactly like one that passed.
+                    log.info(
+                        `Read ${config.stats?.systemId ?? "the system"}'s ` +
+                            `schema, but this package declares no ` +
+                            `\`itemBuilders\` field specifications — so there ` +
+                            `is nothing to compare it against and the ` +
+                            `emitted-versus-declared check does not apply.`,
+                    );
+                }
+                if (schema && comparable) {
+                    const { undeclared, unemitted } = compareFields({
+                        builders: fieldSpecs,
+                        artifact: schema.artifact,
+                    });
+                    for (const f of undeclared) {
+                        schemaFindings.push({
+                            file: schema.source,
+                            severity: "error",
+                            message: undeclaredMessage(f),
+                        });
+                    }
+                    for (const f of unemitted) {
+                        // Advisory: a field the system fills at runtime, or one
+                        // added ahead of the content that will use it, is not a
+                        // defect.
+                        emitDiagnostic({
+                            file: schema.source,
+                            severity: "warning",
+                            message: unemittedMessage(f),
+                        });
+                    }
+                }
+
                 const findings = [
                     ...addresses.findings,
                     ...frontmatter.findings,
+                    ...schemaFindings,
                 ];
                 for (const finding of findings) emitDiagnostic(finding);
                 if (findings.length) {
@@ -385,7 +480,7 @@ function lintCommand() {
                     );
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -466,7 +561,7 @@ function formatCommand() {
                     log.info(`Formatting is clean (${checked} file(s)).`);
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -515,7 +610,7 @@ function markdownCommand() {
                     log.info("Markdown is clean.");
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -663,7 +758,7 @@ function linksCommand() {
                     );
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -739,7 +834,7 @@ function manifestCommand() {
                     });
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -868,7 +963,7 @@ function siteCommand() {
                         `landing(s) to ${path.relative(process.cwd(), s.out)}`,
                 );
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -962,7 +1057,7 @@ function reachabilityCommand() {
                     );
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -1052,7 +1147,7 @@ function depsCommand() {
                 if (count)
                     log.info(`Fetched ${count} dependency catalogue(s).`);
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -1262,7 +1357,7 @@ function packageCommand() {
                         });
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },

package/bin/package-build.mjs

@@ -80,6 +80,8 @@ import { hideBin } from "yargs/helpers";
 import { loadPackageBuildConfig } from "../config.mjs";
 import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
+import { buildSchemaArtifact } from "../engine/schema-extract.mjs";
+import { SCHEMA_ARTIFACT_FILE } from "../engine/foreign-catalog.mjs";
 import { validateLangSource } from "../lang.mjs";
 import {
     analyzeCoverage,
@@ -135,7 +137,14 @@ function ownVersion() {
  */
 function die(err) {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`package-build: ${message}`);
+    // A located diagnostic already starts with `file:line:column:`, which is
+    // exactly the position a parser reads the path from — prefixing it would
+    // yield a filename no editor can open (#95).
+    console.error(
+        /** @type {{located?: boolean}} */ (err)?.located ? message : (
+            `package-build: ${message}`
+        ),
+    );
     process.exit(1);
 }
 
@@ -305,6 +314,109 @@ function assetsCommand() {
     };
 }
 
+/**
+ * Format generated text the way the repository formats everything else.
+ *
+ * Not cosmetic. A generated file that Prettier would reformat leaves
+ * `lint:format` and the generator's own `--check` each demanding what the other
+ * forbids, and the repository cannot be made green. Resolving the config from
+ * the *output path* is what makes one implementation here serve repositories
+ * with different Prettier settings.
+ *
+ * Imported on use, as `prose-lint.mjs` does, so that commands which never
+ * format do not pay to load it.
+ *
+ * @param {string} text - The unformatted content.
+ * @param {string} filepath - Where it will be written.
+ * @returns {Promise<string>} The formatted content.
+ */
+async function formatGenerated(text, filepath) {
+    const prettier = await import("prettier");
+    const config = await prettier.resolveConfig(filepath);
+    return prettier.format(text, { ...config, filepath });
+}
+
+/**
+ * `schema` — publish this package's DataModel field sets as `schema.json`.
+ *
+ * The producing half of the check `content-build lint` runs: Foundry discards
+ * an unknown `system` key at construction and says nothing, so a content build
+ * needs to know what a document will actually receive (#60). It cannot ask a
+ * running Foundry, and it cannot read `defineSchema()` from a sibling checkout,
+ * so the system publishes the field sets as data — the same shape the link
+ * manifest already uses for addresses.
+ *
+ * `--check` fails when the committed copy disagrees with what the source would
+ * produce now, because a generated file nothing checks drifts from its
+ * generator silently — and this one is read by other repositories.
+ *
+ * @returns {object} The yargs command module.
+ */
+function schemaCommand() {
+    return {
+        command: "schema",
+        describe: "Publish this package's DataModel field sets as schema.json",
+        builder: (y) =>
+            y.option("check", {
+                type: "boolean",
+                default: false,
+                describe:
+                    "Fail when the committed schema.json is out of date " +
+                    "rather than rewriting it",
+            }),
+        handler: handler(async (argv) => {
+            const config = loadPackageBuildConfig();
+            if (!config.schema.length) {
+                console.log(
+                    "package-build: no `packageBuild.schema` declared; " +
+                        "nothing to publish.",
+                );
+                return;
+            }
+
+            const pkg = readPackageJson(config);
+            const artifact = buildSchemaArtifact({
+                rootDir: config.rootDir,
+                registries: config.schema,
+                packageId: config.packageId,
+                version: pkg.version,
+            });
+
+            const out = path.join(config.rootDir, SCHEMA_ARTIFACT_FILE);
+            const text = await formatGenerated(JSON.stringify(artifact), out);
+            const counts = Object.entries(artifact.documents)
+                .map(
+                    ([kind, subtypes]) =>
+                        `${Object.keys(subtypes).length} ${kind}`,
+                )
+                .join(", ");
+
+            if (argv.check) {
+                const current =
+                    fs.existsSync(out) ? fs.readFileSync(out, "utf8") : null;
+                if (current !== text) {
+                    die(
+                        `${SCHEMA_ARTIFACT_FILE} does not match what this ` +
+                            `package's data models would produce — regenerate ` +
+                            `it with \`package-build schema\`.`,
+                    );
+                }
+                console.log(
+                    `✅ ${SCHEMA_ARTIFACT_FILE} is up to date ` +
+                        `(${counts} subtypes).`,
+                );
+                return;
+            }
+
+            fs.writeFileSync(out, text, "utf8");
+            console.log(
+                `✅ Wrote ${SCHEMA_ARTIFACT_FILE} for ${artifact.system} ` +
+                    `${artifact.systemVersion} (${counts} subtypes).`,
+            );
+        }),
+    };
+}
+
 /**
  * `manifest` — generate `system.json` / `module.json` into the build stage.
  *
@@ -920,6 +1032,7 @@ yargs(hideBin(process.argv))
     .command(cleanCommand())
     .command(assetsCommand())
     .command(manifestCommand())
+    .command(schemaCommand())
     .command(langCommand())
     .command(bundleCommand())
     .command(releaseCommand())

package/config.mjs

@@ -59,7 +59,11 @@
  */
 
 import path from "node:path";
-import { loadPackConfig } from "./engine/pack-config.mjs";
+import {
+    loadPackConfig,
+    locateConfigError,
+    packConfigPath,
+} from "./engine/pack-config.mjs";
 
 /** Keys the reserved section may declare. */
 const SECTION_KEYS = [
@@ -68,6 +72,7 @@ const SECTION_KEYS = [
     "assetTransform",
     "manifest",
     "manifestFlags",
+    "schema",
     "clean",
     "lang",
     "deploy",
@@ -145,12 +150,21 @@ const ARTIFACT_OF_KIND = Object.freeze({
 });
 
 /**
+ * Reject a configured value, naming the key it was written under.
+ *
+ * The dotted path rides on the error as `field` as well as appearing in the
+ * message, so {@link loadPackageBuildConfig} — the half that knows which file
+ * was read — can resolve it to a line and column (#95). This half stays pure.
+ *
  * @param {string} where - Dotted path of the offending key.
  * @param {string} problem - What is wrong with it.
  * @returns {never}
  */
 function fail(where, problem) {
-    throw new TypeError(`package-build config: \`${where}\` ${problem}.`);
+    throw Object.assign(
+        new TypeError(`package-build config: \`${where}\` ${problem}.`),
+        { field: where },
+    );
 }
 
 /**
@@ -214,6 +228,41 @@ function normalizeAsset(value, index) {
     });
 }
 
+/**
+ * Validate the DataModel registries `package-build schema` reads.
+ *
+ * Each entry names a file and the binding in it that maps subtype to DataModel
+ * class. Two keys rather than a convention because the two repositories that
+ * declare this disagree on both: one keeps `ITEM_DM_DEF` and `ACTOR_DM_DEF` in
+ * a single configuration module, the other keeps `itemModels` and `actorModels`
+ * in a file apiece. Neither layout is more correct, and guessing between them
+ * would fail by reading nothing rather than by complaining.
+ *
+ * The document type is the key, so a package that models only Items simply says
+ * so — there is no empty `Actor` entry to write.
+ *
+ * @param {unknown} value - The `schema` block, or `undefined`.
+ * @returns {Readonly<object[]>} Registry entries; empty when absent.
+ */
+function normalizeSchema(value) {
+    if (value === undefined) return Object.freeze([]);
+    if (!isMapping(value)) fail("packageBuild.schema", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+
+    const entries = Object.entries(input).map(([documentType, entry]) => {
+        const where = `packageBuild.schema.${documentType}`;
+        if (!isMapping(entry)) fail(where, "must be a mapping");
+        const row = /** @type {Record<string, unknown>} */ (entry);
+        rejectUnknownKeys(row, ["from", "registry"], `${where}.`);
+        return Object.freeze({
+            documentType,
+            from: requireNonEmptyString(row.from, `${where}.from`),
+            registry: requireNonEmptyString(row.registry, `${where}.registry`),
+        });
+    });
+    return Object.freeze(entries);
+}
+
 /**
  * Validate the manifest specification.
  *
@@ -682,6 +731,7 @@ export function resolvePackageBuildConfig(shared) {
                     "packageBuild.release.artifact",
                 ),
         assets: Object.freeze(assets),
+        schema: normalizeSchema(section.schema),
         assetTransform:
             section.assetTransform === undefined ?
                 null
@@ -842,5 +892,14 @@ export function resolvePackageBuildConfig(shared) {
  *   declares something malformed.
  */
 export function loadPackageBuildConfig() {
-    return resolvePackageBuildConfig(loadPackConfig());
+    const shared = loadPackConfig();
+    try {
+        return resolvePackageBuildConfig(shared);
+    } catch (err) {
+        // The pure half names the offending key and nothing else; this half
+        // knows the file it was read from, so the position is attached here
+        // (#95) — the same boundary `configFromData` is for the rest of the
+        // configuration.
+        throw locateConfigError(err, packConfigPath());
+    }
 }