@heroiclands/package-build 22.9.1 → 22.10.0

package/engine/holdings.mjs

@@ -43,7 +43,19 @@
  * @module
  */
 
+import { isAddressTuple } from "./address.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
+import { parseAddress } from "./address.mjs";
+import { readCanonicalKey } from "./content-address.mjs";
+
+/**
+ * The one type a `parents` or `domains` entry may name — the default
+ * {@link module:engine/address.parseAddress} fills in when the segment is
+ * omitted, and the whole of what this position accepts.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const PLACE_TYPES = Object.freeze(new Set(["place"]));
 
 /**
  * The keys this module writes, and which a note cannot author: `contains`
@@ -103,22 +115,39 @@ export const HELD_SUBTYPES = Object.freeze(["settlement", "site", "structure"]);
 /**
  * The shortcode a `parents` or `domains` entry names, lower case.
  *
- * An entry is written as a bare shortcode, as an address, or as a wikilink
- * carrying either; the shortcode is the last segment of the address in every
- * case, because a segment carries no separator.
+ * **A `parents` or `domains` entry is an Address** — the specification types
+ * both `Address[]`, targeting `place` — read at whatever length says what it
+ * means, `place` the default and the whole of the accepted set. Frontmatter
+ * never holds a Wikilink, so no bracket, `|` or `#` is stripped here; a
+ * qualified form is read structurally by {@link readCanonicalKey} for its
+ * literal four segments, since this position asks neither its package nor its
+ * system, only the shortcode {@link module:engine/address} would resolve it
+ * to anyway.
+ *
+ * **The match this shortcode feeds is deliberately package-blind.** `places`
+ * and `affiliations` merge this package's own notes with every fetched
+ * dependency's into one shortcode space, first declaration wins — the way a
+ * dependency's generic geography attaches to whatever a consumer calls the
+ * same shortcode, which is the point of _A dependency's places and
+ * affiliations take part_ above. Comparing the full Address instead would
+ * ask an entry's package to agree with the citing note's, and a fetched
+ * entry's own `parents` or `domains` is written in *its* package while the
+ * blend it takes part in is *this* one's — see
+ * `tests/site-holdings.test.ts`'s `empire.domains: ["mill", "abroad"]`, where
+ * `mill` is local and `abroad` is the dependency's own, both bare, both
+ * correct only because neither package is asked.
  *
  * @param {unknown} value - One entry.
  * @returns {string} Its shortcode, or `""` for an entry that names nothing.
  */
 function namedShortcode(value) {
-    const text = String(value ?? "")
-        .trim()
-        .replace(/^\[\[/, "")
-        .replace(/\]\]$/, "")
-        .split("|")[0]
-        .split("#")[0]
-        .trim();
-    return text.split("-").pop()?.toLowerCase() ?? "";
+    if (isAddressTuple(value)) return value.shortcode.toLowerCase();
+    const text = String(value ?? "").trim();
+    if (!text) return "";
+    const qualified = readCanonicalKey(text);
+    if (qualified) return qualified.shortcode.toLowerCase();
+    const read = parseAddress(text, { type: "place", types: PLACE_TYPES });
+    return read.reason ? "" : read.shortcode.toLowerCase();
 }
 
 /**
@@ -244,7 +273,7 @@ export function foreignHoldingsNodes(foreignIndex) {
     for (const [canonical, entry] of foreignIndex) {
         const type = String(entry?.type ?? "");
         if (type !== "place" && type !== "affiliation") continue;
-        const shortcode = canonical.split("-").pop()?.toLowerCase() ?? "";
+        const shortcode = readCanonicalKey(canonical)?.shortcode?.toLowerCase() ?? "";
         if (!shortcode) continue;
         out.push({
             shortcode,

package/engine/index-records.mjs

@@ -32,6 +32,7 @@
  */
 
 import path from "node:path";
+import { isAddressTuple } from "./address.mjs";
 
 /**
  * The keys the content index adds to a record, which a note therefore may not
@@ -72,6 +73,7 @@ export const DERIVED_KEYS = Object.freeze([
  * @returns {unknown} The value with every plain object's keys in sorted order.
  */
 export function sortKeysDeep(value) {
+    if (isAddressTuple(value)) return value;
     if (Array.isArray(value)) return value.map(sortKeysDeep);
     if (value === null || typeof value !== "object") return value;
     // A Date or any other exotic object would lose itself in a rebuild from

package/engine/infobox-render.mjs

@@ -34,6 +34,7 @@
  * @module
  */
 
+import { encodeAddresses } from "./address-values.mjs";
 import { sectionHolds } from "./infobox.mjs";
 import { escapeTypst, escapeTypstString } from "./pdf-render.mjs";
 
@@ -227,7 +228,7 @@ export function sectionHasContent(section) {
  */
 export function linkToTypst(value, links, labelFor) {
     const text = escapeTypst(value?.text ?? "");
-    const anchor = value?.address ? links?.get(value.address) : undefined;
+    const anchor = value?.address ? links?.get(encodeAddresses(value.address)) : undefined;
     if (anchor) return `#link(<${labelFor(anchor)}>)[${text}]`;
     if (value?.url) return `#link("${escapeTypstString(value.url)}")[${text}]`;
     return text;

package/engine/infobox.mjs

@@ -112,11 +112,13 @@
  * @module
  */
 
+import { isAddressTuple, renderAddress } from "./address.mjs";
 import { getFrontmatter } from "./frontmatter.mjs";
 import { currentType } from "./ids.mjs";
 import { NOTE_VOCABULARY, dataFields } from "./note-vocabulary.mjs";
 import { readAliasedField } from "./retired-fields.mjs";
 import { subtypeRow } from "./document-subtypes.mjs";
+import { authoredKey } from "./system-block.mjs";
 
 /**
  * How a section arranges what it holds.
@@ -326,13 +328,20 @@ export const NOTE_FIELD_PRESENTATION = Object.freeze({
  * `<type>.<field>` wins over the bare name, so a spelling two types use for two
  * quantities can be said differently on each without splitting the overlay.
  *
+ * **Keyed by the key an author writes, not by the path a declaration names.**
+ * One fact has two declarations — the note vocabulary's `weight` and an item
+ * field's `data.weight` — and the overlay says what a *reader* is shown, which
+ * is one word either way. So the container is dropped before the lookup, and
+ * `GEAR_UNITS` answers for both sides with one entry.
+ *
  * @param {Readonly<Record<string, object>>} presentation - The overlay.
  * @param {string|undefined} type - The note's type.
  * @param {string} name - The field's declared name.
  * @returns {object} The entry, or an empty one.
  */
 export function overlayFor(presentation, type, name) {
-    return presentation?.[`${currentType(type)}.${name}`] ?? presentation?.[name] ?? {};
+    const key = authoredKey(name);
+    return presentation?.[`${currentType(type)}.${key}`] ?? presentation?.[key] ?? {};
 }
 
 /** What a composed group's row is called. @type {Readonly<Record<string, string>>} */
@@ -418,6 +427,7 @@ export function isUnsetSentinel(value) {
  * @returns {boolean} Whether to emit it.
  */
 export function hasValue(value) {
+    if (isAddressTuple(value)) return true;
     if (value == null) return false;
     if (typeof value === "string") return value.trim() !== "" && !isUnsetSentinel(value);
     if (Array.isArray(value)) return value.some((entry) => hasValue(entry));
@@ -454,6 +464,7 @@ export function humanizeFieldName(name) {
  * @returns {string} The text.
  */
 export function humanizeValue(value) {
+    if (isAddressTuple(value)) value = value.shortcode;
     return String(value ?? "")
         .replace(/[_-]+/g, " ")
         .trim();
@@ -472,6 +483,7 @@ export function humanizeValue(value) {
  * @returns {string} The text.
  */
 export function presentValue(value) {
+    if (isAddressTuple(value)) value = value.shortcode;
     const text = humanizeValue(value);
     if (!/^[a-z][a-z0-9_-]*$/.test(String(value ?? ""))) return text;
     return text.replace(/\b[a-z]/g, (letter) => letter.toUpperCase());
@@ -507,8 +519,12 @@ export function hasRenderableValue(kind, value) {
  * @returns {string} One of {@link INFOBOX_VALUE_KINDS}.
  */
 export function valueKindOf(field, value) {
-    if (field?.shape === "a wikilink") return "link";
-    if (field?.shape === "list of wikilinks") return "links";
+    if (field?.kind === "address" || field?.shape === "a wikilink") return "link";
+    if (
+        (field?.kind === "list" && field?.entryKind === "address") ||
+        field?.shape === "list of wikilinks"
+    )
+        return "links";
     if (field?.kind === "number") return "number";
     if (field?.kind === "list") return "list";
     if (field?.kind === "string") return "text";
@@ -814,19 +830,23 @@ export function systemRowsSection(
 ) {
     const rows = [];
     for (const field of fields ?? []) {
-        if (!field?.name || taken.has(field.name)) continue;
+        // Asked on the authored key: the note box records what it showed by the
+        // key a note writes, and a field whose shared source is a path into
+        // `data:` names the container as well — so comparing the declared names
+        // would put one fact on two surfaces.
+        if (!field?.name || taken.has(authoredKey(field.name))) continue;
         const overlay = overlayFor(presentation, fm?.type, field.name);
         if (overlay.withheld) continue;
         const { value: raw, from } = resolveField(field, fm, { block });
         if (from === "default" || from === "value") continue;
         if (isDeclaredDefault(field, raw)) continue;
         if (!hasValue(raw)) continue;
-        const declaredKind = field.ref ? "link" : valueKindOf(field, raw);
+        const declaredKind = field.code ? "link" : valueKindOf(field, raw);
         const built = rowValue(
             declaredKind,
             raw,
             resolve,
-            field.ref ? { type: field.ref } : undefined,
+            field.code ? { kind: "shortcode", type: field.code, system: block } : undefined,
         );
         if (!hasRenderableValue(declaredKind, built)) continue;
         const { kind, value } = applyUnit(declaredKind, built, overlay.unit);

package/engine/item-compiler.mjs

@@ -355,6 +355,11 @@ export class SystemItemCompiler extends BasePackCompiler {
             block: system,
             claimed: claimedPaths(itemFields(type, system)),
         });
+        // Every field whose authored value is an Address and whose emitted value
+        // is a Shortcode, reduced once the block is whole — so a value the field
+        // read and one authored straight at the destination go through the same
+        // step.
+        this.reduceEmittedAddresses(built, itemFields(type, system));
         this.reportUndeclaredSystemData(fm, system, "Item", subType);
         // And what *this* pass wrote on its own initiative, which no field
         // declaration states and so no other check can see. Read off the

package/engine/item-docs.mjs

@@ -43,8 +43,6 @@
  */
 
 import { compendiumUuid, makeId, pageUuid } from "./ids.mjs";
-import { loadPackConfig } from "./pack-config.mjs";
-import { currentType } from "./ids.mjs";
 import { itemTypes } from "./item-registry.mjs";
 import { packRouter } from "./pack-router.mjs";
 
@@ -61,50 +59,15 @@ import { packRouter } from "./pack-router.mjs";
 export { itemTypes };
 
 /**
- * Every content type whose **prose compiles into a JournalEntry of its own**,
- * addressed by the virtual `doc<type>` qualifier.
+ * The doc-carrying types, under the names the compilers hold them by.
  *
- * Every item type, every actor type, every map type, plus `macro` — a macro
- * note's body documents the script the note also compiles into a Macro, which
- * is the same shape as an item and its description: one note, two documents,
- * the prose living in the journals pack.
- *
- * **One set, read by the compiler and the emitter alike.** The journals pass
- * decides what to compile from it, and the link manifest decides what to
- * publish a `doc<type>` entry for. Held apart, the two drift into a manifest
- * that asserts documentation nothing compiled — or a compiled entry no
- * consumer can address. It is composed exactly once, in `defineConfig`, and
- * read from there — never recomposed at a call site.
- *
- * `doc` notes are absent, for the reason that applies to them alone: a `doc`
- * note's single document *is* its prose, so there is no second document for a
- * `doc<type>` address to name.
- *
- * An accessor rather than a hoisted constant, so that importing this module
- * needs no configuration (#2).
- *
- * @returns {ReadonlySet<string>} The configured doc-carrying types.
- */
-export function docEntryTypes() {
-    return loadPackConfig().docEntryTypes;
-}
-
-/**
- * Whether a content note's type is one whose prose becomes a JournalEntry of
- * its own.
- *
- * @param {string} type - The note's `type` frontmatter.
- * @returns {boolean} True for an item type, an actor type, a map type and
- *   `macro`; false for `doc`.
+ * The set is what decides whether `doc<type>` is a legal type segment, so it is
+ * stated in `engine/address.mjs` beside the grammar that reads one and read from
+ * there by the journals pass and the link manifest — one set, so an authored
+ * `doc<type>` address and the entry it names cannot disagree about which types
+ * have one.
  */
-export function hasDocEntry(type) {
-    // Through {@link currentType}, because the set is derived from the item
-    // registry's keys and those are the *current* spelling of a note type. A
-    // note still on a renamed one carries its documentation journal exactly as
-    // before — this is the one lookup between an item compiling and its prose
-    // silently compiling into nothing.
-    return docEntryTypes().has(String(currentType(type)));
-}
+export { docEntryTypes, hasDocEntry } from "./address.mjs";
 
 /**
  * The id of the JournalEntry a note's prose compiles into — an item's, or a

package/engine/map-dot.mjs

@@ -31,6 +31,7 @@
  * @module
  */
 
+import { isAddressTuple, renderAddress } from "./address.mjs";
 import { subtreeOf } from "./map-places.mjs";
 
 /* --------------------------------------------------------------------- */
@@ -200,6 +201,7 @@ const LEGEND = Object.freeze([
  * @returns {string} Quoted and escaped, newlines folded to spaces.
  */
 export function dotString(value) {
+    if (isAddressTuple(value)) value = renderAddress(value);
     return (
         '"' +
         String(value ?? "")

package/engine/map-notes.mjs

@@ -59,6 +59,11 @@ import { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS } from "./region-events.m
 // A map's background art is `img`, as every other note type's art is. `image`,
 // the spelling a map alone once used, is retired and gone.
 import { sohlField } from "./frontmatter.mjs";
+// `bgImage` is one of the four declared art slots, so its accepted set comes
+// from there rather than being restated: the overlay, a tile's texture and an
+// ambient sound's `audio` are map-specific address fields, not slots, and take
+// no set beyond their own type.
+import { artSlot } from "./art-fields.mjs";
 
 /* -------------------------------------------------------------------- */
 /*  Note types and their canvas profiles                                */
@@ -908,7 +913,7 @@ export function buildScene(fm, ctx) {
     // A Scene has no `img`, so a map's background is its own slot, authored
     // under `data:` with the other art. It is an `image` address like every
     // other art reference, and the record it resolves to carries the path.
-    const img = ctx.art(fm.data?.bgImage, "bgImage", "image");
+    const img = ctx.art(fm.data?.bgImage, "bgImage", "image", artSlot("bgImage")?.accepts);
     if (!img) throw new Error("a map note needs a `bgImage`");
 
     const warn = (message) => {
@@ -984,7 +989,7 @@ export function buildScene(fm, ctx) {
  *   `bgImage` address by {@link buildScene}. Passed rather than resolved here,
  *   because an address is answered by the compile's index and this function
  *   takes none.
- * @param {(value: unknown, key: string, type: string) => string|null} [art] -
+ * @param {(value: unknown, key: string, type: string, accepts?: Iterable<string>) => string|null} [art] -
  *   The art resolver, for the foreground overlay. Omitted, a note naming one
  *   gets no overlay rather than a path nothing serves.
  * @returns {object} The Level document, keyed for the pack.

package/engine/map-places.mjs

@@ -39,7 +39,17 @@ import { indexRecordsFor, isNoteRecord } from "./content-index.mjs";
 import { noteFile } from "./index-records.mjs";
 import { cachedIndexPath, loadForeignIndexes } from "./metadata-index.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
-import { resolvePackageUrl } from "./content-address.mjs";
+import { parseAddress, isAddressTuple } from "./address.mjs";
+import { readCanonicalKey, resolvePackageUrl } from "./content-address.mjs";
+
+/**
+ * The one type a `parents` entry may name — the default
+ * {@link module:engine/address.parseAddress} fills in when the segment is
+ * omitted, and the whole of what this position accepts.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const PLACE_TYPES = Object.freeze(new Set(["place"]));
 
 /**
  * A place as the map reads it, from either source.
@@ -89,17 +99,36 @@ import { resolvePackageUrl } from "./content-address.mjs";
  */
 
 /**
- * The shortcode a `parents` entry names, lower case: the last segment of
- * either a bare shortcode or an address.
+ * The shortcode a `parents` entry names, lower case.
+ *
+ * **A `parents` entry is an Address** — the specification types it
+ * `Address[]`, and the description ("enclosing places") is what makes `place`
+ * its default and its only accepted type. A qualified form is read
+ * structurally by {@link readCanonicalKey} for its literal four segments,
+ * since this position asks neither its package nor its system, only the
+ * shortcode {@link module:engine/address} would resolve it to anyway.
+ *
+ * **The match this shortcode feeds is deliberately package-blind.**
+ * `world.places` merges this package's own places with every fetched
+ * dependency's into one shortcode space, the way a dependency's place
+ * attaches to the local containment tree it is drawn beside — see
+ * `tests/map.test.ts`'s _loads a dependency's places beside the package's
+ * own_, where a fetched place's bare `parents: ["world"]` reaches this
+ * package's own root. Comparing the full Address instead would ask the
+ * dependency's own package to agree with this one's, which the feature is
+ * built to cross.
  *
  * @param {unknown} parent - One `parents` entry.
- * @returns {string} Its shortcode.
+ * @returns {string} Its shortcode, or `""` for an entry that names nothing.
  */
 function parentShortcode(parent) {
-    return String(parent ?? "")
-        .split("-")
-        .pop()
-        .toLowerCase();
+    if (isAddressTuple(parent)) return parent.shortcode.toLowerCase();
+    const text = String(parent ?? "").trim();
+    if (!text) return "";
+    const qualified = readCanonicalKey(text);
+    if (qualified) return qualified.shortcode.toLowerCase();
+    const read = parseAddress(text, { type: "place", types: PLACE_TYPES });
+    return read.reason ? "" : read.shortcode.toLowerCase();
 }
 
 /**
@@ -127,7 +156,10 @@ function relationList(value) {
     if (!Array.isArray(value)) return [];
     return value
         .filter((e) => e && typeof e === "object" && !Array.isArray(e))
-        .map((e) => ({ ...e, to: String(e.to ?? "").toLowerCase() }));
+        .map((e) => ({
+            ...e,
+            to: isAddressTuple(e.to) ? e.to.shortcode : String(e.to ?? "").toLowerCase(),
+        }));
 }
 
 /**
@@ -209,7 +241,7 @@ export function placesFromRecords(records, { contentBase, base }) {
 function addForeignPlaces(world, foreignIndex) {
     for (const [canonical, entry] of foreignIndex) {
         if (entry?.type !== "place") continue;
-        const shortcode = canonical.split("-").pop()?.toLowerCase() ?? "";
+        const shortcode = readCanonicalKey(canonical)?.shortcode?.toLowerCase() ?? "";
         if (!shortcode || world.places.has(shortcode)) continue;
         world.places.set(shortcode, {
             shortcode,

package/engine/metadata-index.mjs

@@ -39,6 +39,11 @@
  * @module
  */
 
+import { buildReferenceTargets } from "./reference-targets.mjs";
+
+import { completeAddress, renderAddress } from "./address.mjs";
+
+import { decodeIndexAddresses, noteAddressContext, encodeAddresses } from "./note-addresses.mjs";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -330,6 +335,7 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
     const index = new Map();
     const packages = new Set();
     const stale = [];
+    const referenceRecords = [];
 
     /**
      * Fold one package's records into the index.
@@ -338,7 +344,7 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
      * @param {Array<Record<string, any>>} records - Its index records.
      * @returns {void}
      */
-    const ingest = (pkg, records) => {
+    const ingest = (pkg, records, sourceFile) => {
         // A base is only needed to resolve a page *URL*, so a pack-only
         // dependency — Foundry addresses and no site, which `kethira` is by
         // licensing rather than by accident — needs none. Demanding one would
@@ -351,8 +357,20 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
         const base = bases?.[pkg];
         const web = typeof base === "string" && base.length > 0;
 
-        for (const record of records) {
-            const key = record?.address?.canonical;
+        const pageAliases = [];
+        for (const [recordIndex, record] of records.entries()) {
+            try {
+                decodeIndexAddresses(record, noteAddressContext(config));
+            } catch (error) {
+                error.file = sourceFile;
+                const lines = sourceFile ? fs.readFileSync(sourceFile, "utf8").split("\n") : [];
+                let nonempty = -1;
+                const line = lines.findIndex((text) => text.trim() && ++nonempty === recordIndex);
+                error.position = line >= 0 ? { line: line + 1 } : {};
+                throw error;
+            }
+            referenceRecords.push(record);
+            const key = encodeAddresses(record?.address?.canonical);
             if (!key) continue;
             const parts = readCanonicalKey(key);
             if (!parts) continue;
@@ -398,7 +416,44 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 domains: record.data?.domains ?? undefined,
                 package: pkg,
             });
+            const entry = index.get(key);
+            for (const [system, published] of Object.entries(record.foundry ?? {})) {
+                const identity = completeAddress({
+                    package: record.package,
+                    system,
+                    type: record.type,
+                    shortcode: record.shortcode,
+                });
+                const publishedKey = renderAddress(identity);
+                if (!index.has(publishedKey))
+                    index.set(publishedKey, {
+                        ...entry,
+                        uuid: published.uuid,
+                        anchors: published.anchors,
+                        type: identity.type,
+                    });
+            }
+            if (entry.url) {
+                const identity = completeAddress({
+                    package: record.package,
+                    system: "none",
+                    type: record.type,
+                    shortcode: record.shortcode,
+                });
+                if (identity.type !== record.type)
+                    pageAliases.push([
+                        renderAddress(identity),
+                        {
+                            ...entry,
+                            uuid: undefined,
+                            anchors: undefined,
+                            doc: undefined,
+                            type: identity.type,
+                        },
+                    ]);
+            }
         }
+        for (const [key, entry] of pageAliases) if (!index.has(key)) index.set(key, entry);
         packages.add(pkg);
     };
 
@@ -424,10 +479,10 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
         }
         const pkg = records[0]?.package ?? packageOfCache(file);
         if (local.has(pkg)) continue;
-        ingest(pkg, records);
+        ingest(pkg, records, file);
     }
 
-    return { index, packages, stale };
+    return { index, references: buildReferenceTargets(referenceRecords, index), packages, stale };
 }
 
 /**