@heroiclands/package-build 6.1.0 → 8.0.0

package/engine/diagnostics.mjs

@@ -289,12 +289,25 @@ export function positionOfLiteral(text, needle, occurrence = 1) {
  * resolves to nothing — yields `{}`, so a caller spreads the result and the
  * position is dropped rather than guessed.
  *
+ * **`key: true` addresses the declaration rather than the value.** A finding
+ * about a *value* — this pack name is not in `packs[]` — belongs on the value,
+ * which is the default. A finding that names a **field** — `\`site.sections.x\`
+ * is not a recognized option` — sends the reader to look for that field, so the
+ * position should be the field's own, and in a flow mapping
+ * (`{ title: X, banner: Y }`) the two are different columns on one line. The
+ * key's node is found through the same parse, so this stays one locator rather
+ * than a second one free to disagree with it.
+ *
  * @param {string} text - The document's contents.
  * @param {ReadonlyArray<string|number>} keyPath - Path to the node: map keys as
  *   strings, sequence entries as numbers.
+ * @param {object} [opts]
+ * @param {boolean} [opts.key=false] - Report where the last segment is
+ *   *declared* rather than where its value sits. Ignored for a sequence entry,
+ *   which has no key.
  * @returns {{line?: number, column?: number}} Spreadable position fields.
  */
-export function positionOfYamlPath(text, keyPath) {
+export function positionOfYamlPath(text, keyPath, { key = false } = {}) {
     if (typeof text !== "string" || !text) return {};
     if (!Array.isArray(keyPath) || keyPath.length === 0) return {};
 
@@ -305,6 +318,19 @@ export function positionOfYamlPath(text, keyPath) {
         // `keepScalar` returns the Scalar node rather than its value, which is
         // the only form carrying a range.
         node = doc.getIn(keyPath, true);
+        if (key && node !== undefined) {
+            const last = keyPath[keyPath.length - 1];
+            const parent =
+                keyPath.length === 1 ?
+                    doc.contents
+                :   doc.getIn(keyPath.slice(0, -1), true);
+            const pair = parent?.items?.find?.(
+                (item) =>
+                    item?.key != null &&
+                    String(item.key.value) === String(last),
+            );
+            if (pair?.key?.range) node = pair.key;
+        }
     } catch {
         return {};
     }
@@ -314,3 +340,37 @@ export function positionOfYamlPath(text, keyPath) {
     const { line, col } = counter.linePos(start);
     return { line, column: col };
 }
+
+/**
+ * The YAML key path a **dotted field path** addresses.
+ *
+ * Configuration checks report the offending key as the path a reader would
+ * write it — `packs[1].name`, `site.sections.affliction.title` — because that
+ * is what the message has to say. {@link positionOfYamlPath} addresses a node
+ * by segments instead, so this is the one translation between them: `.`
+ * separates map keys, and a bracketed suffix is a sequence index.
+ *
+ * A path this cannot parse yields `[]`, which {@link positionOfYamlPath} in
+ * turn resolves to no position — dropped rather than guessed, as everything
+ * else here is.
+ *
+ * @param {string} field - The dotted path, as a diagnostic spells it.
+ * @returns {Array<string|number>} Its segments, sequence indices as numbers.
+ */
+export function yamlKeyPath(field) {
+    if (typeof field !== "string" || field === "") return [];
+    /** @type {Array<string|number>} */
+    const segments = [];
+    for (const segment of field.split(".")) {
+        const parsed = /^([^[\]]*)((?:\[\d+\])*)$/.exec(segment);
+        // Anything else is not a path this understands — a key holding a `[`,
+        // or a dot inside a key. Refuse the whole path rather than resolve
+        // part of it to a node that is not the one named.
+        if (!parsed) return [];
+        if (parsed[1] !== "") segments.push(parsed[1]);
+        for (const index of parsed[2].matchAll(/\[(\d+)\]/g)) {
+            segments.push(Number(index[1]));
+        }
+    }
+    return segments;
+}

package/engine/foreign-catalog.mjs

@@ -97,6 +97,51 @@ export function catalogDir(config, id, version) {
  */
 const itemsDir = (dir) => path.join(dir, "items");
 
+/**
+ * The file a system publishes its `system` field sets as (#60).
+ *
+ * @type {string}
+ */
+export const SCHEMA_ARTIFACT_FILE = "schema.json";
+
+/**
+ * Where a cached dependency's published schema sits, if it shipped one.
+ *
+ * @param {object} config - The resolved configuration.
+ * @param {string} id - The dependency's package id.
+ * @param {string} version - Its resolved version.
+ * @returns {string} The path, whether or not it exists.
+ */
+export function cachedSchemaPath(config, id, version) {
+    return path.join(catalogDir(config, id, version), SCHEMA_ARTIFACT_FILE);
+}
+
+/**
+ * Keep the dependency's published schema beside its extracted items.
+ *
+ * **Copied to one known place rather than read from where it landed.** The two
+ * fetch paths leave the unpacked archive in different states — a download
+ * unzips into `<cache>/package/` and keeps it, while `--from` unzips into a
+ * temporary directory and deletes it — so a reader that went looking in the
+ * unpacked tree would find the schema for one and not the other, which is the
+ * kind of difference that shows up as an unexplained skipped check.
+ *
+ * Absent is not an error: a system that has not adopted the artifact yet is
+ * simply unchecked, and saying so is {@link module:engine/schema-check}'s job
+ * rather than the fetch's.
+ *
+ * @param {string} root - The unpacked package root.
+ * @param {string} dir - The dependency's cache directory.
+ * @returns {boolean} Whether one was published.
+ */
+function cacheSchemaArtifact(root, dir) {
+    const src = path.join(root, SCHEMA_ARTIFACT_FILE);
+    if (!fs.existsSync(src)) return false;
+    fs.mkdirSync(dir, { recursive: true });
+    fs.copyFileSync(src, path.join(dir, SCHEMA_ARTIFACT_FILE));
+    return true;
+}
+
 /**
  * Whether a dependency's cache is present and complete.
  *
@@ -288,6 +333,7 @@ export async function fetchCatalog(config, rel) {
     await downloadAndUnzip(download, raw);
 
     await extractItemPacks(rel.id, version, manifest, raw, dir);
+    cacheSchemaArtifact(raw, dir);
     return dir;
 }
 
@@ -385,6 +431,7 @@ export async function fetchCatalogFromPath(config, rel, source) {
         const dir = catalogDir(config, rel.id, version);
         fs.rmSync(dir, { recursive: true, force: true });
         await extractItemPacks(rel.id, version, manifest, root, dir);
+        cacheSchemaArtifact(root, dir);
         log.info(`${rel.id}@${version}: cached from ${source}`);
         return dir;
     } finally {

package/engine/generate.mjs

@@ -49,7 +49,7 @@ import { Actors } from "../sohl/actors.mjs";
 import { Macros } from "./macros.mjs";
 import { Scenes } from "./scenes.mjs";
 import {
-    buildStats,
+    statsForPack,
     loadFolders,
     buildFolderResolver,
     writeFolderDocs,
@@ -102,8 +102,9 @@ export const packJsonDir = (name, config = loadPackConfig()) =>
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
  * @returns {string[]} Each Item pack's JSON directory. Empty when the
- *   repository ships no items at all — the actors pass, which is the only
- *   caller that needs one, refuses that itself.
+ *   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()) {
     return config.packs
@@ -246,7 +247,7 @@ export function unsatisfiedPassDependencies(running, config) {
  *     count (0 on success) and the number of entries it wrote.
  */
 async function generatePack(
-    { name, type, folders, companions },
+    { name, type, folders, companions, system },
     config,
     router,
     routingReporter,
@@ -290,7 +291,9 @@ async function generatePack(
         companionDests[companion.name] = companionDest;
     }
 
-    writeFolderDocs(folderList, buildStats(undefined, config), dest, type);
+    // A folder document belongs to the pack it is written into, so it carries
+    // that pack's system rather than the package-wide one (#48).
+    writeFolderDocs(folderList, statsForPack(system, config), dest, type);
 
     const pack = new packClass({
         contentBase,
@@ -311,6 +314,8 @@ async function generatePack(
         foreignSourceDirs: foreignItemCatalogDirs(config),
         folderResolver: resolver,
         packName: name,
+        // Which system this pack's documents are stamped for (#48).
+        packSystem: system ?? null,
         docType: type,
         router,
         routingReporter,

package/engine/helpers.mjs

@@ -335,6 +335,44 @@ export function buildStats(
     };
 }
 
+/**
+ * The `_stats` block for one pack, stamped with the system that pack is for
+ * (#48).
+ *
+ * **`systemId` travels with `systemVersion`.** They are one decision, so where
+ * one is omitted both are. Stamping a per-pack version against a package-wide
+ * id would emit `systemId: sohl, systemVersion: 1.6.3` on HM3 documents — a
+ * *plausible lie*, which is worse than the missing value #43 fixed, because
+ * nothing about it looks wrong.
+ *
+ * Resolution, in order:
+ *
+ * 1. The pack's own `system:`, looked up in the `systems:` block. That is the
+ *    case a module shipping for two systems needs, and the one no
+ *    package-wide value could express.
+ * 2. Failing that, the package-wide `stats` — a package whose packs are all for
+ *    one system, which is every package that worked before this existed.
+ *
+ * A pack naming a system is validated against `systems:` at configuration time,
+ * so an unresolvable name never reaches here.
+ *
+ * @param {string|null|undefined} packSystem - The pack's declared `system:`.
+ * @param {object} [config] - The resolved configuration.
+ * @returns {object} The `_stats` block for that pack.
+ */
+export function statsForPack(packSystem, config = loadPackConfig()) {
+    const declared = packSystem ? config.systems?.[packSystem] : null;
+    if (!declared) return buildStats(undefined, config);
+    return {
+        systemId: packSystem,
+        systemVersion: declared.compatibility.verified,
+        coreVersion: supportedCoreVersion(config),
+        createdTime: 0,
+        modifiedTime: 0,
+        lastModifiedBy: config.stats.lastModifiedBy,
+    };
+}
+
 /** Memoised {@link defaultStats}. */
 let cachedDefaultStats;
 

package/engine/journals.mjs

@@ -230,6 +230,11 @@ export function buildPages(rawPages, entryId, noteName) {
  *   heading; see {@link splitPages}.
  * @param {string|null} [params.folder] - The folder id, or `null`.
  * @param {object} [params.flags] - Document flags.
+ * @param {object} [params.stats] - The `_stats` block to stamp. Passed by the
+ *   caller because it is a property of the *pack* being written, not of the
+ *   entry: a module may ship the same content for two systems, and each pack's
+ *   documents record the system version they were built against (#48). A
+ *   caller with no pack in hand gets the package-wide block.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
 export function buildJournalEntry({
@@ -239,6 +244,7 @@ export function buildJournalEntry({
     leadName,
     folder = null,
     flags,
+    stats = defaultStats(),
 }) {
     const rawPages = splitPages(markdown, leadName);
     const pages = buildPages(rawPages, id, name);
@@ -250,7 +256,7 @@ export function buildJournalEntry({
         ownership: { default: 0 },
         flags: flags || {},
         _id: id,
-        _stats: defaultStats(),
+        _stats: stats,
         _key: `!journal!${id}`,
     };
 }
@@ -347,6 +353,7 @@ export class Journals extends BasePackCompiler {
             leadName: ownsDoc ? name : undefined,
             folder,
             flags: fm.flags,
+            stats: this.stats,
         });
     }
 

package/engine/macros.mjs

@@ -322,6 +322,8 @@ export class Macros extends BasePackCompiler {
         return buildMacroEntry(fm, {
             command: macroCommand(body, name),
             folder: this.folderResolver(sohlField(fm, "folder", null)),
+            // This pack's system, not the package-wide one (#48).
+            stats: this.stats,
         });
     }
 

package/engine/pack-config.mjs

@@ -80,7 +80,12 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import YAML from "yaml";
 
-import { defineConfig } from "../content-config.mjs";
+import { defineConfig, DERIVED_SYSTEM_VERSION } from "../content-config.mjs";
+import {
+    formatDiagnostic,
+    positionOfYamlPath,
+    yamlKeyPath,
+} from "./diagnostics.mjs";
 
 /** The stem every consuming repository declares its build under. */
 export const CONFIG_BASENAME = "package-build.config";
@@ -276,6 +281,33 @@ function shippedSystemVersion(rootDir, input) {
         input.relationships ?? {}
     ).systems;
 
+    // The `systems:` block declares without requiring (#48), so it is consulted
+    // first: a package that has adopted it needs no relationship, and one that
+    // ships for two systems could not express itself through a relationship at
+    // all. `requiresSystem` names the package-wide default when there is one;
+    // otherwise a single declared system is unambiguous. With several and no
+    // gate, there is no package-wide answer — each pack carries its own, and
+    // {@link statsForPack} is what reads it.
+    const systemsBlock =
+        /** @type {Record<string, {compatibility?: {verified?: string}}>} */ (
+            input.systems ?? {}
+        );
+    const systemIds = Object.keys(systemsBlock);
+    if (systemIds.length) {
+        const chosen =
+            typeof input.requiresSystem === "string" ? input.requiresSystem
+            : systemIds.length === 1 ? systemIds[0]
+            : null;
+        if (chosen) {
+            const verified = systemsBlock[chosen]?.compatibility?.verified;
+            if (typeof verified === "string" && verified.length)
+                return verified;
+        }
+        // Several declared and none required: the package-wide value is
+        // deliberately absent rather than one of them picked arbitrarily.
+        return null;
+    }
+
     // A module that names neither a system nor a relationship with one is
     // system-agnostic on purpose: its packs are core document types carrying no
     // system data, and it installs under any system. There is no version to
@@ -314,6 +346,95 @@ function shippedSystemVersion(rootDir, input) {
     return verified;
 }
 
+/**
+ * Where in the configuration file a dotted field path was written.
+ *
+ * Only a YAML configuration has text to resolve a path against. An `.mjs` one
+ * is deliberately not searched: JavaScript source fed to a YAML parser is not
+ * an error — it parses as *something*, and a path could resolve to a line that
+ * has nothing to do with the key. A position that is wrong is worse than none,
+ * so the extension decides.
+ *
+ * A path that names a key the file never declared — a missing required one —
+ * has no node of its own. The position then names the **mapping it belongs
+ * in**, one level up and no further: that entry is a real node, and it is the
+ * one the reader has to edit. Walking further would drift away from the key
+ * with each step, so a top-level key that is simply absent gets no position at
+ * all.
+ *
+ * @param {string} configPath - Absolute path of the configuration file.
+ * @param {string} field - The dotted path the diagnostic names.
+ * @returns {{line?: number, column?: number}} Spreadable position fields,
+ *   empty when nothing can be established honestly.
+ */
+function positionInConfig(configPath, field) {
+    if (!/\.ya?ml$/i.test(configPath)) return {};
+
+    let text;
+    try {
+        text = fs.readFileSync(configPath, "utf8");
+    } catch {
+        return {};
+    }
+
+    const keyPath = yamlKeyPath(field);
+    if (keyPath.length === 0) return {};
+
+    const declared = positionOfYamlPath(text, keyPath, { key: true });
+    if (declared.line !== undefined) return declared;
+    if (keyPath.length === 1) return {};
+    return positionOfYamlPath(text, keyPath.slice(0, -1), { key: true });
+}
+
+/**
+ * Attach the position of the key a configuration error names.
+ *
+ * Eighty-one checks across `content-config.mjs` and `config.mjs` report through
+ * one `fail()`, which knows the offending key's dotted path and nothing
+ * about where it was written. Locating one of them and not the rest would be
+ * worse than locating none — a reader would learn that some configuration
+ * errors carry a position and could not predict which — so the path rides on
+ * the error and every one of them is located here, at the boundary that knows
+ * which file was read (#95).
+ *
+ * The message keeps its body and gains the `file:line:column: error: ` prefix
+ * every other finding in this build already uses, so nothing a reader has today
+ * is lost. `located` marks it done, so an error crossing two boundaries is
+ * decorated once; the fields are also left on the error, for a caller that
+ * wants to re-render it.
+ *
+ * @param {unknown} err - What was thrown.
+ * @param {string} [configPath] - The configuration file that was read.
+ * @returns {unknown} The same error, decorated when it named a field.
+ */
+export function locateConfigError(err, configPath) {
+    const failure =
+        /** @type {{field?: unknown, located?: boolean, message?: string, file?: string, line?: number, column?: number}} */ (
+            err
+        );
+    if (!(err instanceof Error)) return err;
+    if (
+        failure.located ||
+        typeof failure.field !== "string" ||
+        !failure.field
+    ) {
+        return err;
+    }
+    if (!configPath) return err;
+
+    const at = {
+        file: configPath,
+        ...positionInConfig(configPath, failure.field),
+    };
+    Object.assign(failure, at, { located: true });
+    failure.message = formatDiagnostic({
+        ...at,
+        severity: "error",
+        message: /** @type {string} */ (failure.message),
+    });
+    return err;
+}
+
 /**
  * Turn a parsed YAML configuration into the frozen one the engine reads.
  *
@@ -400,23 +521,28 @@ export function configFromData(data, configPath) {
     const stats = input.stats;
     if (stats !== null && typeof stats === "object" && !Array.isArray(stats)) {
         const declared = /** @type {Record<string, unknown>} */ (stats);
-        if (declared.systemVersion !== undefined) {
-            throw new Error(
-                `package-build: ${configPath} declares ` +
-                    `\`stats.systemVersion\`, which a data configuration may ` +
-                    `not: a system derives it from the \`version\` of the ` +
-                    `\`package.json\` beside it, and a module from the ` +
-                    `\`compatibility.verified\` of the system it declares a ` +
-                    `relationship with. Remove the key.`,
-            );
-        }
+        // `stats.systemId` and `stats.systemVersion` are both refused by
+        // `defineConfig`, which reports them with a locator — so nothing is
+        // rejected here. This half only supplies the value the validator cannot
+        // compute: resolving a system package's version means reading the
+        // adjacent `package.json`, and `defineConfig` performs no I/O.
+        //
+        // Passed under a symbol so the channel is not a second, forgeable
+        // spelling of the key that was just refused (see
+        // {@link DERIVED_SYSTEM_VERSION}).
         input.stats = {
             ...declared,
-            systemVersion: shippedSystemVersion(rootDir, input),
+            [DERIVED_SYSTEM_VERSION]: shippedSystemVersion(rootDir, input),
         };
     }
 
-    return defineConfig(/** @type {never} */ (input));
+    try {
+        return defineConfig(/** @type {never} */ (input));
+    } catch (err) {
+        // Every `fail()` in the validator names a key and knows nothing about
+        // the file; this is where the two meet.
+        throw locateConfigError(err, configPath);
+    }
 }
 
 /**
@@ -432,6 +558,10 @@ function loadCodeConfig(configPath) {
     try {
         module = require(configPath);
     } catch (err) {
+        // A code configuration calls `defineConfig` itself, so its rejections
+        // arrive here. There is no YAML to locate into, but the file is known —
+        // `locateConfigError` names it and drops the line.
+        locateConfigError(err, configPath);
         if (
             /** @type {{ code?: string }} */ (err)?.code ===
             "ERR_REQUIRE_ASYNC_MODULE"

package/engine/prose-lint.mjs

@@ -240,8 +240,16 @@ function toDiagnostic(directory, result) {
  *
  * {@link MARKDOWNLINT_CONFIG} is passed as markdownlint's `optionsDefault`,
  * which is precisely the "shipped default, consumer overrides" behaviour the
- * command promises: a `.markdownlint-cli2.jsonc` found in the tree replaces it,
- * and a repository with none gets these rules.
+ * command promises: a repository with no configuration of its own gets these
+ * rules, and a `.markdownlint-cli2.jsonc` found in the tree overrides them.
+ *
+ * The override is **key by key, and each key wholesale** — which is not the same
+ * as "replaces it", and the difference is the one worth stating. A consumer file
+ * declaring only `ignores` keeps this rule set intact, including `default: false`
+ * and every per-rule option; but its `ignores` *replaces*
+ * {@link MARKDOWN_IGNORES} rather than extending it, so such a file must restate
+ * every shared entry it still wants. Omitting `CHANGELOG.md` there silently
+ * starts linting a generated file.
  *
  * @param {string} root - Repository to lint.
  * @param {object} [opts]

package/engine/scenes.mjs

@@ -414,7 +414,7 @@ export class Scenes extends BasePackCompiler {
             packageId: foundryPackageId(),
             name,
             folder,
-            stats: defaultStats(),
+            stats: this.stats,
             journalEntryId: entryId,
             // A map note's prose is a derived JournalEntry: it lands in the
             // default JournalEntry pack, not in whichever Scene pack the map
@@ -521,7 +521,7 @@ export class Scenes extends BasePackCompiler {
             sort: 0,
             flags: {},
             _id: id,
-            _stats: defaultStats(),
+            _stats: this.stats,
             _key: `!adventures!${id}`,
         };
     }