@heroiclands/package-build 6.1.0 → 7.0.0

package/engine/content-links.mjs

@@ -58,6 +58,7 @@ import {
     canonicalKey,
     loadForeignManifests,
     manifestsComplete,
+    PACKAGE_BASE,
     readCanonicalKey,
 } from "./kb-manifest.mjs";
 import { frontmatterWikilinks, slugify } from "./web-wikilinks.mjs";
@@ -336,6 +337,74 @@ export function buildLinkIndex(
  */
 const SITE_HOST = /^(?:[a-z0-9-]+\.)*heroiclands\.org$/i;
 
+/**
+ * Every package landing this build can name, as `package` → base (#87).
+ *
+ * **A landing needs no manifest, and that is what makes it work.** The link
+ * manifest indexes content notes, and a homepage is deliberately not one — it
+ * compiles to no document and is entered in no manifest. The reading that
+ * follows from this, and that left a hardcoded URL as the only authored form,
+ * is that a landing therefore cannot be addressed. It does not follow: a
+ * landing's address is not a *note's* address but the **package's**, and
+ * {@link PACKAGE_BASE} already records where each package is served. That is a
+ * frozen constant vendored into every repository, so consulting it walks no
+ * tree, reads no manifest and builds no index — which is precisely why the
+ * mechanism survives `homepage` mode, where the licensing fence means none of
+ * those exist.
+ *
+ * The roster is consulted **for landings only**. Widening the package set the
+ * other rules read would make them offer manifest-based advice about packages
+ * no manifest is vendored for.
+ *
+ * @param {string} ownPackage - The package this build publishes.
+ * @param {Iterable<string>} manifestPackages - Packages a vendored manifest
+ *   names, which are addressable whether or not the roster lists them.
+ * @returns {Map<string, string>} Package to base, each base slash-terminated.
+ */
+function landingBases(ownPackage, manifestPackages) {
+    const bases = new Map();
+    // Convention first, roster second, so a package the roster relocates is
+    // recorded at the relocated base rather than the default one.
+    for (const pkg of [ownPackage, ...manifestPackages]) {
+        if (pkg) bases.set(pkg, `/${pkg}/`);
+    }
+    for (const [pkg, base] of Object.entries(PACKAGE_BASE)) {
+        if (typeof base === "string" && base.endsWith("/")) {
+            bases.set(pkg, base);
+        }
+    }
+    return bases;
+}
+
+/**
+ * The package whose landing an address names, or `null`.
+ *
+ * Matches the whole path, not a prefix: `/sohl/` is the landing, `/sohl/kb/`
+ * is a page inside the package and belongs to the manifest rules instead.
+ *
+ * @param {string} url - The authored address.
+ * @param {Map<string, string>} bases - From {@link landingBases}.
+ * @returns {{pkg: string, base: string}|null} The package and its base.
+ */
+function landingTarget(url, bases) {
+    const value = String(url ?? "").trim();
+    if (!value || !/^[a-z][a-z0-9+.-]*:/i.test(value)) return null;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    } catch {
+        return null;
+    }
+    if (!/^https?:$/.test(parsed.protocol)) return null;
+    if (!SITE_HOST.test(parsed.hostname)) return null;
+    const pathname =
+        parsed.pathname.endsWith("/") ? parsed.pathname : `${parsed.pathname}/`;
+    for (const [pkg, base] of bases) {
+        if (pathname === base) return { pkg, base };
+    }
+    return null;
+}
+
 /**
  * How an authored address resolves, or `null` for one nothing here can judge.
  *
@@ -400,9 +469,17 @@ function readAddress(url, packages) {
  *   and what replaced it, so this is a fact rather than a guess — and it is
  *   exactly the SoHL defect.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
- *   vendored manifest names. Both have a better form to write, which is why they
- *   are reported; a bare `/<package>/` is left alone, because a package
- *   homepage is in no manifest and there is nothing better to write.
+ *   vendored manifest names. Every one of them has a better form to write, which
+ *   is why every one is reported — including a bare `/<package>/`, which names
+ *   another package's landing (#87).
+ *
+ *   That last case was exempt until the better form was identified, on the
+ *   reasoning that a landing is in no link manifest so nothing could resolve it.
+ *   True, and beside the point: it does not need resolving. A landing's address
+ *   *is* its package prefix, so `/<package>/` is the absolute URL with the host
+ *   struck off — host-free, emitted verbatim, and needing no index, which is
+ *   what lets it hold in homepage-only mode where the tree is never walked. The
+ *   form was already accepted here; nothing had ever named it as the one to use.
  * - A **root-relative `url:`**, which the theme's `relURL` prefixes a second
  *   time. `href:` means "already resolved, use verbatim", so the same leading
  *   slash is correct there and is not reported.
@@ -424,6 +501,7 @@ function readAddress(url, packages) {
 export function auditHomepageLinks(index) {
     const findings = [];
     const packages = new Set([index.contentPackage, ...index.packages]);
+    const bases = landingBases(index.contentPackage, index.packages);
 
     for (const note of index.notes) {
         if (!isHomepage(note.fm)) continue;
@@ -467,28 +545,43 @@ export function auditHomepageLinks(index) {
             if (!address) continue;
             const { shape, segments, prefix } = address;
 
-            if (shape === "absolute" && prefix) {
-                // A bare `/<package>/` is a package's homepage, which is in no
-                // link manifest and has no relative form from another package.
-                // A finding with no fix is noise.
+            // Landings first, and by the roster rather than by the manifest
+            // package set: a landing is addressable in a repository that
+            // vendors no manifest at all, which is the case the fence creates
+            // and the case this rule exists for (#87).
+            const landing = landingTarget(url, bases);
+            if (landing) {
+                report(
+                    field,
+                    url,
+                    url,
+                    occurrence,
+                    `hardcoded absolute URL to ` +
+                        (landing.pkg === index.contentPackage ?
+                            `this package's own landing`
+                        :   `package "${landing.pkg}"'s landing`) +
+                        ` — write "${landing.base}", which names no host, is ` +
+                        `emitted verbatim, and resolves through the package ` +
+                        `roster rather than through an index, so it holds ` +
+                        `where no content tree is walked`,
+                );
+            } else if (shape === "absolute" && prefix) {
                 const rest = segments.slice(1).join("/");
-                if (rest) {
-                    report(
-                        field,
-                        url,
-                        url,
-                        occurrence,
-                        prefix === index.contentPackage ?
-                            `hardcoded absolute URL into this package's own ` +
-                                `address — write the package-relative ` +
-                                `"${rest}/", which the landing resolves ` +
-                                `against the site so the page follows the mount`
-                        :   `hardcoded absolute URL into package "${prefix}" ` +
-                                `— resolve it through that package's link ` +
-                                `manifest, whose entries carry the address, so a ` +
-                                `relocation does not leave this page behind`,
-                    );
-                }
+                report(
+                    field,
+                    url,
+                    url,
+                    occurrence,
+                    prefix === index.contentPackage ?
+                        `hardcoded absolute URL into this package's own ` +
+                            `address — write the package-relative ` +
+                            `"${rest}/", which the landing resolves ` +
+                            `against the site so the page follows the mount`
+                    :   `hardcoded absolute URL into package "${prefix}" ` +
+                            `— resolve it through that package's link ` +
+                            `manifest, whose entries carry the address, so a ` +
+                            `relocation does not leave this page behind`,
+                );
             } else if (shape === "rooted" && kind === "url") {
                 const rest =
                     prefix ? segments.slice(1).join("/") : segments.join("/");
@@ -497,9 +590,21 @@ export function auditHomepageLinks(index) {
                     url,
                     url,
                     occurrence,
-                    `url "${url}" is root-relative, but a landing's url: is ` +
-                        `resolved against the site — write "${rest}/", or ` +
-                        `href: for an address that is already resolved`,
+                    // A `url:` is package-relative by construction, so it
+                    // cannot address anything outside this package at all —
+                    // there is no relative spelling of another package's root.
+                    // `href:` is the field for an address already resolved.
+                    !rest ?
+                        `url "${url}" addresses ` +
+                            (prefix ?
+                                `package "${prefix}"'s landing`
+                            :   `the site root`) +
+                            `, but a landing's url: is package-relative and ` +
+                            `cannot leave this package — write ` +
+                            `href: "${url}", which is used verbatim`
+                    :   `url "${url}" is root-relative, but a landing's url: ` +
+                            `is resolved against the site — write "${rest}/", ` +
+                            `or href: for an address that is already resolved`,
                 );
             }
 

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/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}`,
         };
     }