@heroiclands/package-build 6.0.0 → 7.0.0

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

package/engine/site-build.mjs

@@ -65,6 +65,7 @@ import { loadPackConfig } from "./pack-config.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
 import {
     HOMEPAGE_DESTINATION,
+    checkHomepageCount,
     homepageFrontmatter,
     homepageTitle,
     isHomepage,
@@ -269,9 +270,9 @@ export function collectTreePages(tree, ctx) {
  * packages ship under is a property of the code path rather than of a
  * configuration that happens to be empty (#55).
  *
- * Returned as a list rather than as the one note there should be. Requiring
- * exactly one is #52's, and it is a separate decision — this reports what it
- * found so a count is visible either way.
+ * Returned as a list rather than as the one note there should be, because the
+ * count is what {@link checkHomepageCount} judges (#52) — this walk reports
+ * what it found, and {@link buildSite} decides whether that is one.
  *
  * @param {string} contentBase - Absolute path to the content tree.
  * @param {object} ctx - `{ skipDirectories }`.
@@ -345,6 +346,10 @@ export function writeHomepages(outRoot, pages, config) {
  */
 export function siteGates(pages, findings, { manifestDir }) {
     const out = {
+        // Always empty here: the homepage count is decided in `buildSite`
+        // before the content walk, and a failing count returns without ever
+        // reaching these gates (#52). Present so every caller reads one shape.
+        homepages: [],
         frontmatterLinks: findings.fmLinkFindings ?? [],
         slugErrors: findings.slugFindings ?? [],
         collisions: [],
@@ -403,6 +408,7 @@ export function siteGates(pages, findings, { manifestDir }) {
  */
 export function emptyGates() {
     return {
+        homepages: [],
         frontmatterLinks: [],
         slugErrors: [],
         collisions: [],
@@ -418,6 +424,7 @@ export function emptyGates() {
 /** Whether any gate produced a finding. */
 export function gatesFailed(gates) {
     return Boolean(
+        gates.homepages.length ||
         gates.frontmatterLinks.length ||
         gates.slugErrors.length ||
         gates.collisions.length ||
@@ -455,6 +462,39 @@ export function tableUniverse(pages) {
     return byPackage;
 }
 
+/**
+ * The front matter a section's landing states about itself.
+ *
+ * The section metadata a configuration resolved, ready to be written or merged
+ * onto a page. Two things happen here and nothing else does:
+ *
+ * - **`title` leads.** It is the one key every landing has carried since the
+ *   first one, and a landing whose block opened with `banner:` would be a
+ *   gratuitous diff on every consumer's tree.
+ * - **An absent value is left off**, not written as `undefined` — which is not
+ *   a value YAML can carry, and would abort the serializer.
+ *
+ * Everything else the section declared is passed through. That is the point of
+ * the function: before #91 both writers transcribed `title` and `banner` by
+ * name, so the vocabulary lived in three places — the schema that admits a key
+ * and the two writers that copy it — and a key added to the schema alone
+ * validated cleanly and then reached no page. The *schema* is the bound worth
+ * keeping (see `normalizeSectionMeta`, which refuses a key it does not know and
+ * names it); a second, silent bound in the writers is not.
+ *
+ * @param {object} meta - A resolved `site.sections` / `site.readmeSections`
+ *   entry.
+ * @returns {object} Its front matter, `title` first.
+ */
+export function sectionFrontmatter(meta) {
+    const data = { title: meta.title };
+    for (const [key, value] of Object.entries(meta)) {
+        if (key === "title" || value === undefined) continue;
+        data[key] = value;
+    }
+    return data;
+}
+
 /**
  * The frontmatter a page publishes with.
  *
@@ -494,12 +534,11 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
         if (decorate) decorate(data, page);
         if (isReadme) {
             const meta = readmeSections[sec];
-            if (meta) {
-                data.title = meta.title;
-                // Guarded: a title-only entry would otherwise emit
-                // `banner: undefined`, which the YAML serializer rejects.
-                if (meta.banner) data.banner = meta.banner;
-            }
+            // What the section says about itself wins over what its README
+            // happens to carry — the landing has to match the card linking to
+            // it. Assigned rather than transcribed key by key, so a section's
+            // vocabulary is decided in one place (#91).
+            if (meta) Object.assign(data, sectionFrontmatter(meta));
         }
     } else {
         // A tree's own landing describes the *mount*, and nothing beneath it. A
@@ -509,7 +548,7 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
         const isSectionRoot = path.posix.dirname(page.rel) === ".";
         const meta = isReadme && isSectionRoot ? readmeSections[sec] : null;
         data = { ...fm, title: meta?.title ?? fm.title ?? name };
-        if (meta?.banner) data.banner = meta.banner;
+        if (meta) Object.assign(data, sectionFrontmatter(meta));
     }
     delete data.aliases;
     return data;
@@ -660,15 +699,11 @@ export function writeSectionLandings(
     for (const [sec, meta] of Object.entries(sections)) {
         const dir = path.join(outRoot, sec);
         fs.mkdirSync(dir, { recursive: true });
-        // A section may have no hero: the images are CDN assets and not every
-        // section has one. An explicit `banner: undefined` is not a value YAML
-        // can carry, so the key is left off entirely.
+        // Whatever the section declared, not a list of keys named here — see
+        // {@link sectionFrontmatter} for why the two lists were one too many.
         fs.writeFileSync(
             path.join(dir, "_index.md"),
-            matter.stringify("", {
-                title: meta.title,
-                ...(meta.banner ? { banner: meta.banner } : {}),
-            }),
+            matter.stringify("", sectionFrontmatter(meta)),
         );
         written += 1;
     }
@@ -848,12 +883,32 @@ export function buildSite({ config, outRoot } = {}) {
         scheme,
     };
 
+    const homepages = collectHomepages(resolved.paths.content, ctx).pages;
+
+    // Exactly one homepage, and checked here — before the output tree is
+    // cleared and before either mode branches (#52). Before the clear, because
+    // a gate that fired after it would have destroyed a good site to report a
+    // bad tree. Before the branch, because the requirement does not vary by
+    // mode: `publish.site` chooses whether the *content* surfaces are
+    // published, and the homepage is the floor beneath both.
+    const homepageFindings = checkHomepageCount(homepages, {
+        contentBase: resolved.paths.content,
+        contentPackage: resolved.contentPackage,
+    });
+    if (homepageFindings.length) {
+        return {
+            gates: { ...emptyGates(), homepages: homepageFindings },
+            manifests: null,
+            tableErrors: [],
+            wikiErrors: [],
+            stats: null,
+        };
+    }
+
     // The whole tree is a build artifact, regenerated every run: a page whose
     // note was deleted or renamed would otherwise linger and keep publishing.
     fs.rmSync(outBase, { recursive: true, force: true });
 
-    const homepages = collectHomepages(resolved.paths.content, ctx).pages;
-
     // Homepage-only stops here, and stopping is the point: nothing below reads
     // the content tree for pages, so `sohl-kethira-basic` and `harn-adventures`
     // cannot publish one whatever else their `site:` block declares (#55).

package/engine/web-wikilinks.mjs

@@ -46,7 +46,12 @@ import { slugify } from "./content-slug.mjs";
 // Re-exported so a site build keeps one import path for the whole of link
 // resolution: the same rule that names a page also names an anchor within it.
 export { slugify };
-import { WIKILINK, isSamePage, parseWikilink } from "./wikilink-syntax.mjs";
+import {
+    authoredLabel,
+    WIKILINK,
+    isSamePage,
+    parseWikilink,
+} from "./wikilink-syntax.mjs";
 
 /** KB heading/anchor slug: lowercase, non-alphanumerics to single hyphens. */
 
@@ -240,10 +245,14 @@ export function resolveWebWikilinks(body, ctx) {
     // inline span is source text, not a link (#1505).
     return replaceOutsideCode(body, WIKILINK, (_m, rawInner) => {
         const { target, anchor, display } = parseWikilink(rawInner);
+        // An empty label is not a label: `[[x|]]` addresses the target and
+        // shows its name, so `""` falls through to the same place `null` does
+        // (#113). One reading, from {@link authoredLabel}.
+        const label = authoredLabel({ display });
 
         // `[[#section-slug|Text]]` — a section of this same page.
         if (isSamePage({ target, anchor })) {
-            return `[${display ?? anchor}](#${slugify(anchor)})`;
+            return `[${label ?? anchor}](#${slugify(anchor)})`;
         }
 
         const key = target.toLowerCase();
@@ -272,7 +281,7 @@ export function resolveWebWikilinks(body, ctx) {
             // (#1398), and a hyphen inside a note *name* ("Grukar-ahk") is not
             // one, which is why the rule is the packs' own (#1409).
             const text =
-                display ??
+                label ??
                 (isAddress(target, ctx.contentTypes) ? hit.name : target);
             // A pack-only package publishes Foundry addresses and no pages
             // (#1516), so its entries carry no `path` and resolve to no URL.
@@ -325,6 +334,6 @@ export function resolveWebWikilinks(body, ctx) {
                 reason: "broken type/shortcode",
             });
         }
-        return unresolvedLink(display ?? target, target);
+        return unresolvedLink(label ?? target, target);
     });
 }

package/engine/wikilink-syntax.mjs

@@ -91,6 +91,31 @@ export function parseWikilink(rawInner) {
     return { inner: inner.trim(), target, anchor, display, labelled };
 }
 
+/**
+ * The label an author actually supplied, or `null` when they supplied none.
+ *
+ * **An empty label is not a label.** `[[x|]]` is deliberately writable — it
+ * means "address this target, and show the target's own name" — so `display:
+ * ""` has to read as *absent* everywhere a fallback is chosen, exactly as
+ * `display: null` does. The two are still distinguishable through
+ * {@link ParsedWikilink.labelled}, which is the thing that genuinely differs
+ * and which #1409 depends on.
+ *
+ * Stated here because the two resolvers had already drawn the line in two
+ * places and drawn it differently: the packs tested falsiness and were right,
+ * the web tested `??` — which falls through on `null` only — and emitted
+ * `[](/url/)`, a link with no clickable text, through every build (#113). That
+ * is the same drift this module exists to prevent, in the case its own
+ * {@link ParsedWikilink} docstring calls out. One reading, one place.
+ *
+ * @param {{display: string|null}} parsed - A parsed wikilink, or anything
+ *   carrying its `display`.
+ * @returns {string|null} The label, or `null` when there is none to show.
+ */
+export function authoredLabel({ display }) {
+    return display ? display : null;
+}
+
 /**
  * Whether a parsed link addresses a section of the page it is written on.
  *

package/engine/wikilinks.mjs

@@ -93,7 +93,7 @@ import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 // The syntax lives in `./wikilink-syntax.mjs`, so the web resolver and this
 // one cannot disagree about what counts as a link.
-import { WIKILINK, parseWikilink } from "./wikilink-syntax.mjs";
+import { authoredLabel, WIKILINK, parseWikilink } from "./wikilink-syntax.mjs";
 
 export { ITEM_PACK, PACK_BY_TYPE, packForType };
 
@@ -498,8 +498,11 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
             const { labelled } = parsed;
             let target = parsed.target;
             // An unlabelled link shows its interior verbatim, anchor included;
-            // a labelled one shows its label.
-            let text = labelled ? (parsed.display ?? "") : parsed.inner;
+            // a labelled one shows its label. An *empty* label is not a label
+            // — `[[x|]]` means "show the target's name" — and that reading
+            // comes from {@link authoredLabel} so the web resolver cannot draw
+            // the line somewhere else (#113).
+            let text = labelled ? (authoredLabel(parsed) ?? "") : parsed.inner;
             const slug = parsed.anchor || null;
 
             // Resolve the document: same-page (empty target), type-shortcode, or alias.

package/manifest.mjs

@@ -430,8 +430,43 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
         ...releaseUrls({ repoUrl, version: packageJson.version, artifact }),
     };
     if (config.compatibility) derived.compatibility = config.compatibility;
-    if (config.relationships && Object.keys(config.relationships).length) {
-        derived.relationships = publishedRelationships(config.relationships);
+
+    // `requiresSystem` is the gate half of the declare/require split (#48). It
+    // emits the `relationships.systems` entry Foundry's `supportsSystem` reads,
+    // reusing the `systems:` declaration rather than restating it — a second
+    // transcription is free to disagree with what it copied, which is how
+    // `stats.systemVersion` came to sit at `0.6.0` for four releases.
+    //
+    // Declaring a system emits nothing on its own. That is the point: a module
+    // shipping content for two systems names both under `systems:`, stamps each
+    // pack accordingly, and stays loadable everywhere because it requires
+    // neither.
+    const relationships = { ...(config.relationships ?? {}) };
+    if (config.requiresSystem) {
+        const declaredSystem = config.systems?.[config.requiresSystem];
+        const entry = {
+            id: config.requiresSystem,
+            type: "system",
+            ...(declaredSystem?.manifest ?
+                { manifest: declaredSystem.manifest }
+            :   {}),
+            ...(declaredSystem?.compatibility ?
+                {
+                    compatibility: Object.fromEntries(
+                        Object.entries(declaredSystem.compatibility).filter(
+                            ([, v]) => v != null,
+                        ),
+                    ),
+                }
+            :   {}),
+        };
+        // An explicit `relationships.systems` still wins, so a repository
+        // mid-migration is never told two different things about itself.
+        relationships.systems =
+            relationships.systems?.length ? relationships.systems : [entry];
+    }
+    if (Object.keys(relationships).length) {
+        derived.relationships = publishedRelationships(relationships);
     }
 
     const merged = { ...declared, ...derived };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "6.0.0",
+    "version": "7.0.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -122,12 +122,12 @@
         "classic-level": "^3.0.0",
         "dotenv": "^17.2.3",
         "fflate": "^0.8.3",
-        "glob": "^11.0.3",
+        "glob": "^13.0.6",
         "gray-matter": "^4.0.3",
         "handlebars": "^4.7.9",
         "loglevel": "^1.9.2",
         "loglevel-plugin-prefix": "^0.8.4",
-        "markdown-it": "^14.1.0",
+        "markdown-it": "^15.0.0",
         "markdownlint-cli2": "^0.23.2",
         "prettier": "^3.9.6",
         "ssh2-sftp-client": "^12.1.1",
@@ -148,7 +148,9 @@
         "build:types": "tsc -p tsconfig.dts.json",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
+        "lint": "npm run format:check && npm run lint:markdown",
         "lint:markdown": "node bin/content-build.mjs markdown",
+        "lint:markdown:fix": "node bin/content-build.mjs markdown --fix",
         "changeset": "changeset",
         "changeset:check": "changeset status --since=origin/main",
         "changeset:version": "changeset version && npm install --package-lock-only",

package/sohl/actors.mjs

@@ -327,20 +327,33 @@ export class Actors extends BasePackCompiler {
     itemsSourceDirs;
     foreignSourceDirs;
 
-    constructor({ itemsSourceDirs, foreignSourceDirs = [], ...options }) {
+    constructor({ itemsSourceDirs = [], foreignSourceDirs = [], ...options }) {
         super(options);
         // Where the items passes wrote their JSON. Stated by the caller rather
         // than assumed to be this pack's sibling: the packs' locations are
         // configuration, and a consumer may put them anywhere (#1508). Every
         // Item pack, because a repository may ship more than one (#1566).
-        if (!itemsSourceDirs?.length) {
-            throw new Error(
-                "Actors compiler requires `itemsSourceDirs` — the generated JSON " +
-                    "of every Item pack, which each being's embedded items are " +
-                    "resolved against. Declare at least one pack of type " +
-                    '"Item" in package-build.config.yaml.',
-            );
-        }
+        //
+        // **Optional, and empty is a legitimate package (#49).** This used to
+        // throw unless at least one Item pack was declared, which asked a
+        // package to declare the very thing it may exist not to have. An Item
+        // pack is system-bound by construction — Foundry requires `system` on
+        // Item packs — so a deliberately system-agnostic module could satisfy
+        // the guard only by naming a system. `harn-ensemble` is the case:
+        // 2,512 beings whose embedded items address the `sohl` and `hm3`
+        // catalogues, and five affiliation notes of its own.
+        //
+        // The guard also did not test what it claimed. It counted *declared
+        // directories*, not resolvable items, so an empty Item pack satisfied
+        // it while a being naming a missing item still failed later. The
+        // condition actually cared about is checked where it can be reported
+        // precisely: {@link Actors#resolveEmbedded} already errors per
+        // unresolved `(type, shortcode)`, naming the being. A package whose
+        // beings embed nothing, or whose every address resolves against a
+        // dependency catalogue through `foreignSourceDirs`, now compiles with
+        // no Item pack at all — and one that is genuinely missing an item
+        // still fails, saying which item and which actor rather than which
+        // pack is absent.
         Object.defineProperty(this, "itemsSourceDirs", {
             value: Object.freeze([...itemsSourceDirs]),
             writable: false,
@@ -641,7 +654,7 @@ export class Actors extends BasePackCompiler {
             // `sohl.archetype` (required nullable number) drives
             // `flags.sohl.docArchetype` (#640 / archetype contract #604).
             flags: withArchetypeFlag(fm, fm.flags, ctx),
-            _stats: defaultStats(),
+            _stats: this.stats,
             _key: `!actors!${id}`,
         };
     }

package/sohl/items.mjs

@@ -167,7 +167,7 @@ export class Items extends BasePackCompiler {
             // `sohl.archetype` (required nullable number) drives
             // `flags.sohl.docArchetype` (#640 / archetype contract #604).
             flags: withArchetypeFlag(fm, fm.flags, `item "${name}"`),
-            _stats: defaultStats(),
+            _stats: this.stats,
             ownership: { default: 0 },
             folder,
             _key: `!items!${id}`,