@heroiclands/package-build 9.0.0 → 10.0.1

package/engine/helpers.mjs

@@ -39,6 +39,8 @@ import { contentPackage, foundryPackageId } from "./content-package.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
 import { loadForeignManifests, PACKAGE_BASE } from "./kb-manifest.mjs";
 import { buildWikilinkIndex, convertWikilinks } from "./wikilinks.mjs";
+// The alias sources every index shares (#131).
+import { aliasesOf } from "./alias-index.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { emitDiagnostic, positionInBody } from "./diagnostics.mjs";
 // The pure `sohl:` frontmatter readers live in a leaf module so the item-type
@@ -147,8 +149,8 @@ export function* walkMarkdownTree(
 
 /**
  * Resolve the required `sohl.archetype` frontmatter for an Item/Actor entry
- * (see the archetype contract, #604 — `flags.sohl.docArchetype`). The property
- * is a nullable number that authors must state explicitly:
+ * (the archetype contract, #604). The property is a nullable number that
+ * authors must state explicitly:
  *   - a number → the document is an archetype of that priority.
  *   - `null`   → the document is not an archetype.
  *   - absent   → an authoring error (throws), so "not an archetype" is never
@@ -182,30 +184,29 @@ export function resolveArchetype(fm, label) {
 }
 
 /**
- * Merge the required `sohl.archetype` frontmatter into a document's `flags`,
- * returning a new object (the input is never mutated). A numeric archetype
- * seeds `flags.sohl.docArchetype`; `null` omits the flag (and clears any stale
- * `docArchetype` while preserving sibling `sohl` flags); an absent value
- * throws. See {@link resolveArchetype}.
- *
- * @param {object} fm              Parsed frontmatter.
- * @param {object} [flags]         The entry's existing flags (e.g. `fm.flags`).
- * @param {string} label           Human-readable context for error messages.
- * @returns {object}               The flags object with the archetype applied.
+ * The value a document's `system.archetype` carries, from the required
+ * `sohl.archetype` frontmatter (#126, sohl#1780).
+ *
+ * A **schema field**, so the tri-state is written out in full rather than
+ * expressed by a key's presence: a number is an archetype at that priority,
+ * and `null` is not an archetype. This is where {@link resolveArchetype}'s
+ * `undefined` becomes the field's `null` — an emitted `undefined` would be
+ * dropped by `JSON.stringify`, leaving the compiled document with no
+ * `archetype` at all and the tri-state readable as two.
+ *
+ * **`0` is an archetype.** It is the priority SoHL's own archetypes ship at,
+ * and it is falsy, so this returns it unchanged and every caller must ask
+ * `typeof v === "number"` rather than testing truthiness.
+ *
+ * @param {object} fm      Parsed frontmatter.
+ * @param {string} label   Human-readable context for error messages.
+ * @returns {number|null}  The archetype priority, or `null` for a document
+ *   that is not an archetype.
  * @throws {Error} When `sohl.archetype` is absent or invalid.
  */
-export function withArchetypeFlag(fm, flags, label) {
+export function systemArchetype(fm, label) {
     const archetype = resolveArchetype(fm, label);
-    const out = { ...(flags || {}) };
-    const sohl = { ...(out.sohl || {}) };
-    if (archetype === undefined) {
-        delete sohl.docArchetype;
-    } else {
-        sohl.docArchetype = archetype;
-    }
-    if (Object.keys(sohl).length > 0) out.sohl = sohl;
-    else delete out.sohl;
-    return out;
+    return archetype === undefined ? null : archetype;
 }
 
 /**
@@ -449,12 +450,10 @@ export function buildContentLinkIndex(contentBase, router = packRouter()) {
             docPack: router.resolveOrNull(fm, "JournalEntry"),
             shortcode: fm.shortcode ?? null,
             name: fm.name?.full ?? base,
-            aliases: [
-                ...(Array.isArray(fm.aliases) ? fm.aliases : []),
-                ...(fm.name?.full ? [fm.name.full] : []),
-                ...(Array.isArray(fm.name?.aliases) ? fm.name.aliases : []),
-                base,
-            ].filter(Boolean),
+            // The shared alias sources (#131): `aliases`, `name.aliases` and
+            // `name.full`, and deliberately not the filename — see
+            // {@link aliasesOf} for what that admitted and why it went.
+            aliases: aliasesOf(fm),
         });
     }
     // Packages this build links *into* but does not publish. Their manifests
@@ -567,6 +566,19 @@ export function convertNoteWikilinks(
                     `as [[type-shortcode|Text]].`,
             );
         }
+        // The author wrote a pipe, so they meant an address — and this target
+        // is not one. Its own message, because the correction is its own: a
+        // note *name* has to become an address, which is not the same job as
+        // fixing a shortcode that resolves nowhere (#131).
+        if (u.reason === "not-an-address") {
+            fail(
+                u,
+                `wikilink ${u.link} in "${name}" is written as an address — ` +
+                    `the "|" says so — but "${u.target}" is not one. Write ` +
+                    `[[type-shortcode|Text]], or drop the "|" to name it as ` +
+                    `an alias within this note's own type.`,
+            );
+        }
         // A qualified address resolving nowhere is a typo, now that every
         // linkable package is either built here or vendored (#1499) — so it
         // fails the note rather than degrading to text. A bare alias stays a

package/engine/ids.mjs

@@ -51,7 +51,18 @@ export function makeId(namespace, value) {
  *
  * @type {ReadonlySet<string>}
  */
-export const MAP_TYPES = Object.freeze(new Set(["battlemap", "localmap", "regionalmap"]));
+export const MAP_TYPES = Object.freeze(new Set(["map"]));
+
+/**
+ * The map subTypes, which differ only in the canvas defaults derived for them.
+ *
+ * They were three *types* until #174, which cost three entries in the pack
+ * router, three in the claims set and three in every consumer's section config
+ * — for one idea that the specification had always described as one type.
+ *
+ * @type {readonly string[]}
+ */
+export const MAP_SUBTYPES = Object.freeze(["battlemap", "localmap", "regionalmap"]);
 
 /**
  * Content type → the pack its documents compile into, and the document type
@@ -95,6 +106,13 @@ export const PACK_BY_TYPE = Object.freeze({
 export const RETIRED_TYPES = Object.freeze({
     character: "being",
     creature: "being",
+    // The three map spellings, retired in favour of the single `map` whose
+    // subType they became (#174). Recorded rather than deleted for the same
+    // reason as the two above: an unnamed type falls through to the open item
+    // set, so a note or link left on one would be routed to the items pack.
+    battlemap: "map",
+    localmap: "map",
+    regionalmap: "map",
 });
 
 /**

package/engine/index.mjs

@@ -36,6 +36,9 @@
 /** Deterministic document ids, the conventional pack map, and compendium UUIDs. */
 export * as ids from "./ids.mjs";
 
+/** The per-system frontmatter block, and the declared shared→system mapping. */
+export * as systemBlock from "./system-block.mjs";
+
 /** Fenced-code detection, so a rewrite never edits a code block. */
 export * as codeFences from "./code-fences.mjs";
 
@@ -51,6 +54,9 @@ export * as packConfig from "./pack-config.mjs";
 /** Which pack of a document type a note's document lands in (#1566). */
 export * as packRouter from "./pack-router.mjs";
 
+/** Which note types a configuration compiles, and the notes nothing claims (#146). */
+export * as noteClaims from "./note-claims.mjs";
+
 /** The content package a build compiles, and the Foundry package it ships in. */
 export * as contentPackage from "./content-package.mjs";
 
@@ -66,6 +72,9 @@ export * as homepage from "./homepage.mjs";
 /** The note types the engine itself declares, whatever a consumer registers. */
 export * as noteSchemas from "./note-schemas.mjs";
 
+/** The closed frontmatter regions: the `data:` container and each type's `subType`. */
+export * as noteVocabulary from "./note-vocabulary.mjs";
+
 /** The shipped Foundry manifest: locating it, reading it, guarding its id. */
 
 /** The URL a content note is published at — the one web-address rule. */
@@ -104,6 +113,9 @@ export * as helpers from "./helpers.mjs";
 /** The consumer's resolved item-type registry: the whitelist and its builders. */
 export * as itemRegistry from "./item-registry.mjs";
 
+/** The per-system note-type → document-subtype map, and looking a note up in it. */
+export * as documentSubtypes from "./document-subtypes.mjs";
+
 /** Which types carry documentation of their own, and where it is addressed. */
 export * as itemDocs from "./item-docs.mjs";
 
@@ -113,6 +125,9 @@ export * as wikilinks from "./wikilinks.mjs";
 /** What a `[[…]]` is, before either resolver decides where it points. */
 export * as wikilinkSyntax from "./wikilink-syntax.mjs";
 
+/** The alias namespace: what a note may be called, and who may claim a name. */
+export * as aliasIndex from "./alias-index.mjs";
+
 /** The address index a site build resolves its wikilinks against. */
 export * as siteIndex from "./site-index.mjs";
 

package/engine/item-registry.mjs

@@ -18,7 +18,11 @@
  * Both are read from the one resolved configuration, so they are literally the
  * same object's keys and values: a type cannot be whitelisted for compilation
  * without the builder that compiles it, which is the guarantee #1504 exists
- * for. The Item compiler dispatches through {@link itemBuilder}, so the table a
+ * for. Where a consumer declares **several** registries, one per system (#58),
+ * the vocabulary is their union and every lookup below takes the system that is
+ * asking — a type both systems declare has two builders, and answering with one
+ * of them because it was declared first is the silent-wrong-output failure this
+ * package spends its time removing. The Item compiler dispatches through {@link itemBuilder}, so the table a
  * consumer configured is the table its notes compile with — the whitelist and
  * the dispatch used to come from different places, and a consumer supplying its
  * own registry got the types it asked for and the builders it did not (#1563).
@@ -60,6 +64,43 @@ export function itemTypes() {
     return loadPackConfig().itemTypes;
 }
 
+/**
+ * Look one type up in the table a system declared, or in the flat one.
+ *
+ * The flat table is the union with the first declaring registry winning, which
+ * is the right answer for every single-system build and no answer at all where
+ * two systems declare the type. So a contested type without a system **throws**
+ * rather than resolving: the alternative is a document built by one system's
+ * builder and stamped with another's, which is exactly the shape of defect the
+ * document-subtype map exists to stop (#79).
+ *
+ * @param {string} what - What is being looked up, for the message.
+ * @param {"itemBuilders"|"itemArt"|"itemFields"} table - Which table.
+ * @param {string} type - The item type.
+ * @param {string} [system] - The system asking, where a build has more than one.
+ * @returns {any} The entry, or `undefined`.
+ * @throws {Error} When several systems declare the type and none is named.
+ */
+function lookup(what, table, type, system) {
+    const config = loadPackConfig();
+    if (system !== undefined) {
+        const perSystem = /** @type {Record<string, Record<string, unknown>>} */ (
+            config[`${table}BySystem`]
+        );
+        // A consumer declaring one, system-less registry keeps answering for
+        // every system: it *is* the only vocabulary in the build.
+        if (Object.keys(perSystem).length) return perSystem[system]?.[type];
+    } else if (config.itemTypesBySeveralSystems.has(type)) {
+        throw new Error(
+            `More than one declared registry defines the item type "${type}", so ` +
+                `the ${what} of a "${type}" depends on which system is asking. ` +
+                `Name the system at the call site, or stop declaring the type ` +
+                `twice.`,
+        );
+    }
+    return /** @type {Record<string, unknown>} */ (config[table])[type];
+}
+
 /**
  * The builder the consuming repository registered for an item type.
  *
@@ -68,11 +109,16 @@ export function itemTypes() {
  * failing as an anonymous `is not a function` (#1504).
  *
  * @param {string} type - The note's `type` frontmatter.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry. Omitted, a type only one registry declares still
+ *   resolves; a contested one throws rather than picking a side.
  * @returns {(fm: object) => object} The builder for that type.
  * @throws {Error} When the configuration registers no builder for `type`.
  */
-export function itemBuilder(type) {
-    const builder = /** @type {Record<string, Function>} */ (loadPackConfig().itemBuilders)[type];
+export function itemBuilder(type, system) {
+    const builder = /** @type {Function|undefined} */ (
+        lookup("builder", "itemBuilders", type, system)
+    );
     if (typeof builder !== "function") {
         throw new Error(
             `No builder registered for item type "${type}" — add one to the ` +
@@ -83,6 +129,25 @@ export function itemBuilder(type) {
     return /** @type {(fm: object) => object} */ (builder);
 }
 
+/**
+ * The frontmatter fields a type's registry entry declares, if any.
+ *
+ * Sparse by design: a type whose entry declares none compiles normally and is
+ * simply undocumented (#22). What reads it is the `system`-block passthrough,
+ * which has to know which paths a declared field already writes before it
+ * writes the rest (#58).
+ *
+ * @param {string} type - The item type.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry.
+ * @returns {readonly object[]|undefined} The declaration, or `undefined`.
+ */
+export function itemFields(type, system) {
+    return /** @type {readonly object[]|undefined} */ (
+        lookup("field declaration", "itemFields", type, system)
+    );
+}
+
 /**
  * The default art for an item type — the image a note of that type is given
  * when it carries no `img:` of its own.
@@ -106,11 +171,13 @@ export function itemBuilder(type) {
  * One spelling, one meaning, wherever it is written.
  *
  * @param {string} type - the item type.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry.
  * @returns {string} The default image path for that type.
  * @throws {Error} When the type's registry entry pairs no `img`.
  */
-export function itemArt(type) {
-    const art = /** @type {Record<string, string|undefined>} */ (loadPackConfig().itemArt)[type];
+export function itemArt(type, system) {
+    const art = /** @type {string|undefined} */ (lookup("default art", "itemArt", type, system));
     if (!art) {
         throw new Error(
             `No default art for item type "${type}" — the note carries no ` +

package/engine/kb-manifest.mjs

@@ -90,18 +90,47 @@ export function canonicalKey(pkg, type, shortcode) {
 }
 
 /**
- * Reads a canonical key back into its parts.
+ * How many segments a canonical key has, and therefore how many the reader
+ * below counts.
+ *
+ * Named rather than written as a literal because it is the *grammar*, not an
+ * implementation detail of one function: it is the number a change to the
+ * address form would move, and the thing a reader of that change has to find.
  *
- * Unambiguous because no package, type or shortcode contains a hyphen — types
- * are bare words and shortcodes are `^[A-Za-z0-9]+$` (#1397).
+ * @type {number}
+ */
+export const CANONICAL_KEY_SEGMENTS = 3;
+
+/**
+ * Reads a canonical key back into its parts.
  *
- * @param {string} key - A canonical key.
- * @returns {{package: string, type: string, shortcode: string}|null} The parts,
- *   or `null` when the key is not in canonical form.
+ * Parsing is plain positional counting: split on the separator, require
+ * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
+ * **The charset rule is what makes that sound** — every segment is
+ * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
+ * so the hyphen is purely a separator and the count alone determines every
+ * field. That is enforced at each of the three sources rather than assumed of
+ * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
+ * `defineConfig` (#59), and types are bare words. Were any of them free to
+ * carry a hyphen, no amount of counting would recover the fields and the reader
+ * would need a vocabulary to match against instead.
+ *
+ * **Nothing to read and nothing readable are different answers.** A key that
+ * cannot be canonical — `harn-adventures-skill-melee`, four segments — yields
+ * `null`, while an absent or blank input yields `undefined`. Both are falsy, so
+ * every call site (all of which test the result for truthiness) is unaffected;
+ * the distinction is there so a caller reporting "this key is unreadable" can
+ * tell that it has a key to report about.
+ *
+ * @param {unknown} key - A canonical key, or nothing.
+ * @returns {{package: string, type: string, shortcode: string}|null|undefined}
+ *   The parts; `null` when there is a string that is not in canonical form;
+ *   `undefined` when there is no key at all.
  */
 export function readCanonicalKey(key) {
+    if (key == null || key === "") return undefined;
     const parts = String(key).split("-");
-    if (parts.length !== 3) return null;
+    if (parts.length !== CANONICAL_KEY_SEGMENTS) return null;
     const [pkg, type, shortcode] = parts;
     if (!pkg || !type || !shortcode) return null;
     return { package: pkg, type, shortcode };

package/engine/map-notes.mjs

@@ -51,11 +51,14 @@
 
 import crypto from "crypto";
 
-import { compendiumUuid, makeId, MAP_TYPES } from "./ids.mjs";
+import { compendiumUuid, makeId, MAP_SUBTYPES, MAP_TYPES } from "./ids.mjs";
 // The curated region-event vocabulary is shared verbatim with the runtime
 // bridge (`SohlRegionTriggerBehavior`), so an event this build accepts is
 // exactly one the bridge forwards.
 import { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS } from "./region-events.mjs";
+// A map's background art is `img`, as every other note type's art is; `image`
+// is the retired spelling, still read through the retirement window (#142).
+import { readAliasedField } from "./retired-fields.mjs";
 
 /* -------------------------------------------------------------------- */
 /*  Note types and their canvas profiles                                */
@@ -63,7 +66,7 @@ import { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS } from "./region-events.m
 
 // The set itself lives in `ids.mjs`, a leaf both this module and the
 // doc-carrying type set in `item-docs.mjs` can depend on without a cycle.
-export { MAP_TYPES };
+export { MAP_SUBTYPES, MAP_TYPES };
 
 /**
  * Whether a content note's type compiles into a Scene.
@@ -76,7 +79,7 @@ export function isMapType(type) {
 }
 
 /**
- * Per-type canvas defaults, emitted **explicitly** on every scene.
+ * Per-subtype canvas defaults, emitted **explicitly** on every scene.
  *
  * This is not a convenience. `grid.type`, `grid.distance` and `grid.units` all
  * declare `initial: () => game.system.grid.*`, and there is no `game` at build
@@ -86,7 +89,7 @@ export function isMapType(type) {
  *
  * @type {Readonly<Record<string, object>>}
  */
-export const MAP_TYPE_PROFILES = Object.freeze({
+export const MAP_SUBTYPE_PROFILES = Object.freeze({
     battlemap: Object.freeze({
         grid: { type: 1 /* SQUARE */, distance: 5, units: "ft" },
         tokenVision: true,
@@ -108,18 +111,23 @@ export const MAP_TYPE_PROFILES = Object.freeze({
 });
 
 /**
- * The canvas profile for a map type.
+ * The canvas profile for a map subType.
  *
- * @param {string} type - The note's `type`.
- * @returns {object} The profile from {@link MAP_TYPE_PROFILES}.
- * @throws {Error} When the type is not a map type — the build's fail-fast
- *   contract, so a typo never ships a scene with Foundry's own defaults.
+ * Keyed on the subType rather than the type since #174: every map note is
+ * `type: map`, and which canvas it derives is the one thing the three
+ * spellings ever decided.
+ *
+ * @param {string} subType - The note's `subType`.
+ * @returns {object} The profile from {@link MAP_SUBTYPE_PROFILES}.
+ * @throws {Error} When the subType is not a map subType — the build's
+ *   fail-fast contract, so a typo never ships a scene with Foundry's own
+ *   defaults.
  */
-export function mapProfile(type) {
-    const profile = MAP_TYPE_PROFILES[String(type)];
+export function mapProfile(subType) {
+    const profile = MAP_SUBTYPE_PROFILES[String(subType)];
     if (!profile) {
         throw new Error(
-            `unknown map type "${type}" — expected one of ${[...MAP_TYPES].join(", ")}`,
+            `unknown map subtype "${subType}" — expected one of ${MAP_SUBTYPES.join(", ")}`,
         );
     }
     return profile;
@@ -879,7 +887,7 @@ export function buildScene(fm, ctx) {
     const sohl = fm.sohl ?? {};
     const sceneId = fm.id;
     if (!sceneId) throw new Error("a map note needs an `id`");
-    const profile = mapProfile(fm.type);
+    const profile = mapProfile(fm.subType);
 
     const dimensions = sohl.dimensions;
     if (
@@ -896,7 +904,11 @@ export function buildScene(fm, ctx) {
                 "match the art",
         );
     }
-    if (!sohl.image) throw new Error("a map note needs an `image`");
+    // Read from the note rather than from its `sohl:` block: art is not
+    // system-specific, so `img` is authored at the top level like every other
+    // type's, and `sohlField` honours the block for anything already there.
+    const img = readAliasedField(fm, "img");
+    if (!img) throw new Error("a map note needs an `img`");
 
     const warn = (message) => {
         if (ctx.warnings) ctx.warnings.push(message);
@@ -921,7 +933,7 @@ export function buildScene(fm, ctx) {
         tokenVision: profile.tokenVision,
         fog: { mode: profile.fog.mode },
         initialLevel: DEFAULT_LEVEL_ID,
-        levels: [buildLevel(sohl, sceneId)],
+        levels: [buildLevel(sohl, sceneId, img)],
         drawings: [],
         tokens: [],
         lights: buildLights(sohl, geom, inner),
@@ -957,7 +969,7 @@ export function buildScene(fm, ctx) {
 }
 
 /**
- * Synthesise the scene's single embedded Level from `image:` / `overlay:`.
+ * Synthesise the scene's single embedded Level from `img:` / `overlay:`.
  *
  * Authors never write `levels:`. A scene must ship at least one Level — the
  * client-side `_preCreate` net that would create one does not run for offline
@@ -967,16 +979,20 @@ export function buildScene(fm, ctx) {
  *
  * @param {object} sohl - The note's `sohl:` block.
  * @param {string} sceneId - The owning scene's `_id`.
+ * @param {string} [img] - The background art, already resolved from the note.
+ *   Passed by {@link buildScene}, which reads it from the note rather than from
+ *   the block; defaults to whichever spelling the block itself carries, so a
+ *   direct two-argument call still works (#142).
  * @returns {object} The Level document, keyed for the pack.
  */
-export function buildLevel(sohl, sceneId) {
+export function buildLevel(sohl, sceneId, img = readAliasedField({ sohl }, "img")) {
     const level = {
         _id: DEFAULT_LEVEL_ID,
         name: sohl.levelName ?? "Ground",
         elevation: { bottom: 0, top: 20 },
         background: {
             color: sohl.backgroundColor ?? "#999999",
-            src: sohl.image,
+            src: img,
         },
         foreground: { src: sohl.overlay ?? null },
         sort: 0,