@heroiclands/package-build 6.1.0 → 8.0.0

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.1.0",
+    "version": "8.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/item-fields.mjs

@@ -311,11 +311,6 @@ export const ITEM_FIELDS = Object.freeze({
             value: false,
             describe: "Whether it is currently dormant. Play state.",
         },
-        {
-            to: "isTreated",
-            value: false,
-            describe: "Whether it has been treated. Play state.",
-        },
         {
             name: "levelBase",
             to: "levelBase",
@@ -633,22 +628,6 @@ export const ITEM_FIELDS = Object.freeze({
             required: true,
             describe: "What kind of projectile it is.",
         },
-        {
-            name: "impact.overrideDice",
-            to: "impactBase.overrideDice",
-            shape: "boolean",
-            read: (raw, { fm }) => Boolean(raw ?? impactDie(fm) > 0),
-            describe:
-                "Whether the projectile's dice replace the launching weapon's. Defaults to true when the projectile declares a die.",
-        },
-        {
-            name: "impact.overrideModifier",
-            to: "impactBase.overrideModifier",
-            shape: "boolean",
-            read: (raw) => Boolean(raw ?? false),
-            describe:
-                "Whether the projectile's modifier replaces the launching weapon's.",
-        },
         {
             to: "impactBase.numDice",
             value: (fm) => (impactDie(fm) > 0 ? 1 : 0),
@@ -781,20 +760,6 @@ export const ITEM_FIELDS = Object.freeze({
             describe:
                 "How the injury was inflicted. Unset on a descriptive condition.",
         },
-        {
-            name: "isTreated",
-            to: "isTreated",
-            ...BOOLEAN,
-            default: false,
-            describe: "Whether it has been treated.",
-        },
-        {
-            name: "isBleeding",
-            to: "isBleeding",
-            ...BOOLEAN,
-            default: false,
-            describe: "Whether it is bleeding.",
-        },
         {
             name: "bodyLocationCode",
             to: "bodyLocationCode",

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

package/types/content-config.d.mts

@@ -131,6 +131,20 @@ export const DEFAULT_ADDRESS_SCHEME: Readonly<{
  * @satisfies {readonly SiteMode[]}
  */
 export const SITE_MODES: readonly ["homepage", "content"];
+/**
+ * How the loader hands {@link defineConfig} the system version it resolved.
+ *
+ * A **Symbol**, deliberately. `stats.systemVersion` is refused from an authored
+ * configuration (#48), but the value still has to reach here from the loader —
+ * which is the half that may do I/O, and which reads a system package's version
+ * out of the adjacent `package.json`. A string key would be a second spelling of
+ * the refused one, forgeable from YAML and reachable by `rejectUnknownKeys`; a
+ * symbol key cannot be written in YAML at all and does not appear in
+ * `Object.keys`, so the refusal has no back door.
+ *
+ * @type {symbol}
+ */
+export const DERIVED_SYSTEM_VERSION: symbol;
 /**
  * How much of a package reaches the web.
  *

package/types/engine/base-compiler.d.mts

@@ -92,7 +92,7 @@ export class BasePackCompiler {
      * @param {boolean} [options.routingReporter] - Whether this pass reports a
      *   note of its type that routes nowhere.
      */
-    constructor({ contentBase, dest, folderResolver, packName, docType, router, routingReporter, }?: {
+    constructor({ contentBase, dest, folderResolver, packName, packSystem, docType, router, routingReporter, }?: {
         contentBase: string;
         dest: string;
         folderResolver?: ((path: string | null) => string | null) | undefined;
@@ -153,6 +153,22 @@ export class BasePackCompiler {
      * @type {number}
      */
     unresolvedLinks: number;
+    packSystem: any;
+    /**
+     * The `_stats` block every entry this pass emits is stamped with (#48).
+     *
+     * Per pack rather than per package, because a module may ship the same
+     * content for two systems — `harn-ensemble` has an `actors-hm3` pack and an
+     * `actors-sohl` pack — and those documents were built against different
+     * system versions. A single global block stamped both identically.
+     *
+     * Memoised on the instance: one pass, one pack, one system, so the block is
+     * constant for the life of the compiler. The previous module-level memo
+     * could not be, because it was shared across passes for different packs.
+     *
+     * @returns {object} The block, built once per compiler.
+     */
+    get stats(): object;
     /**
      * Whether this pass's pack is the one a claimed note belongs in.
      *
@@ -326,6 +342,7 @@ export class BasePackCompiler {
         bodyLine: number | undefined;
         bodyColumn: number | undefined;
     } | undefined;
+    #private;
 }
 /**
  * The tallies one pass accumulates while walking the tree.

package/types/engine/content-links.d.mts

@@ -46,9 +46,17 @@ export function buildLinkIndex(contentBase: string, { manifestDir, skipDirectori
  *   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.

package/types/engine/diagnostics.d.mts

@@ -169,12 +169,44 @@ export function positionOfLiteral(text: string, needle: string, occurrence?: num
  * 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: string, keyPath: ReadonlyArray<string | number>): {
+export function positionOfYamlPath(text: string, keyPath: ReadonlyArray<string | number>, { key }?: {
+    key?: boolean | undefined;
+}): {
     line?: number;
     column?: number;
 };
+/**
+ * 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: string): Array<string | number>;

package/types/engine/foreign-catalog.d.mts

@@ -23,6 +23,15 @@ export function itemCatalogRelationships(config: object): Array<{
  * @returns {string} The directory.
  */
 export function catalogDir(config: object, id: string, version: string): string;
+/**
+ * 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: object, id: string, version: string): string;
 /**
  * Write an unzipped archive's entries under `dest`.
  *
@@ -101,3 +110,9 @@ export function fetchAllCatalogs(config: object): Promise<number>;
  * @returns {string[]} Every cached dependency's item directories.
  */
 export function foreignItemCatalogDirs(config: object): string[];
+/**
+ * The file a system publishes its `system` field sets as (#60).
+ *
+ * @type {string}
+ */
+export const SCHEMA_ARTIFACT_FILE: string;

package/types/engine/generate.d.mts

@@ -13,8 +13,9 @@
  * @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?: object): string[];
 /**

package/types/engine/helpers.d.mts

@@ -19,7 +19,7 @@ export function parseMarkdownFile(filePath: any): {
 } | {
     frontmatter: any;
     body: string;
-    description: any;
+    description: string;
     bodyLine: number;
     bodyColumn: number;
 };
@@ -56,7 +56,7 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
     absPath: string;
     frontmatter: any;
     body: string;
-    description: any;
+    description: string;
     bodyLine: number;
     bodyColumn: number;
 }, void, unknown>;
@@ -190,6 +190,32 @@ export function buildStats(systemVersion?: string, config?: {
         packageManifest: string;
     };
 }): object;
+/**
+ * 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: string | null | undefined, config?: object): object;
 /**
  * The `_stats` block every compiler stamps on an entry it emits, built once.
  *
@@ -342,7 +368,7 @@ export function folderFilename(name: any, id: any): string;
  * pack, `"JournalEntry"` for the journals pack.
  */
 export function writeFolderDocs(folders: any, stats: any, destDir: any, documentType: any): void;
-export const md: any;
+export const md: import("markdown-it").MarkdownIt;
 export { slugify } from "./content-slug.mjs";
 export { makeId } from "./ids.mjs";
 export { getFrontmatter, sohlField, resolveCharges, resolveSkillAptitudes, resolveRelation, requireSubType, parseValueDesc } from "./frontmatter.mjs";

package/types/engine/journals.d.mts

@@ -93,15 +93,21 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   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({ id, name, markdown, leadName, folder, flags, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, }: {
     id: string;
     name: string;
     markdown: string;
     leadName?: string | undefined;
     folder?: string | null | undefined;
     flags?: object | undefined;
+    stats?: object | undefined;
 }): object;
 export class Journals extends BasePackCompiler {
     /**

package/types/engine/pack-config.d.mts

@@ -14,6 +14,28 @@
  *   {@link CONFIG_FILENAMES}.
  */
 export function findConfigFile(from: string): string | undefined;
+/**
+ * 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: unknown, configPath?: string): unknown;
 /**
  * Turn a parsed YAML configuration into the frozen one the engine reads.
  *

package/types/engine/prose-lint.d.mts

@@ -36,8 +36,16 @@ export function checkFormatting(root: string, opts?: {
  *
  * {@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]