@heroiclands/package-build 22.9.1 → 22.10.0

package/hm3/actors.mjs

@@ -26,13 +26,9 @@
  * the note says which, by writing `hm3.type`. An absent one is an error naming
  * the note, never a default.
  *
- * **What is emitted, and what is deliberately not.** Four rows of the content
- * format's `being` mapping table give HM3 a destination — `data.portrait` →
- * `system.bioImage`, `data.species`, `data.gender`, `data.occupation`, and
- * `data.templatePriority` → `flags.hm3.templatePriority` — and every one of
- * them is *declared as that source* rather than as the bare key the corpus
- * writes, so the specification's mapping is executable rather than
- * aspirational. Plus the two anchored prose sections: `{#appearance}` is HM3's
+ * Shared gender, occupation and template priority map to HM3's native fields.
+ * Native species text is independent of the lore Address in `data.species`.
+ * The anchored prose section `{#appearance}` supplies HM3's
  * `description` and `{#dossier}` its
  * `biography`. Everything else an HM3 actor carries — the thirteen abilities,
  * the sunsign, `move`, `fatigue`, `shockIndex`, a creature's `loadRating` — has
@@ -70,31 +66,19 @@ import {
 import { blockField, blockProperty, mergeSystemData } from "../engine/system-block.mjs";
 
 /**
- * The shared `data:` facts every HM3 actor takes, whatever its subtype.
+ * Native HM3 facts shared by its actor subtypes.
  *
- * Declared rather than read by hand, so a value resolves by the same order
- * every other declared field does — `hm3.system.<to>` first, then the in-block
- * position, then the shared source, then the default — and so the
- * author-facing reference can be generated from the same statement the compiler
- * obeys.
- *
- * **Both positions, named separately.** The specification maps
- * `data.species` onto `system.species`, and every HM3 note in the corpus writes
- * `hm3.species`. Until the sweep those are two live positions for one
- * field, so the declaration names both: `name` is the shared source, `legacyKey`
- * the key the block still carries, and the block wins while it is there. Naming
- * only one of them is what made the row unreadable — a plain `species` could
- * not see `data.species`, and a dotted `data.species` could not see the 2,512
- * notes that carry `hm3.species`, each yielding `""` in silence.
+ * Species is native text. The note's lore Address in `data.species` is
+ * independent and supplies no native value.
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
 const ACTOR_FIELDS = Object.freeze([
     {
-        name: "data.species",
-        legacyKey: "species",
+        name: "species",
         to: "species",
         ...STRING,
+        topLevelMeans: "The shared species is a lore Address, independent of native species text.",
         default: "",
         describe: "The kind of creature this is.",
     },

package/hm3/item-fields.mjs

@@ -76,7 +76,8 @@ import { AS_AUTHORED, NUMBER } from "../engine/field-spec.mjs";
  */
 const GEAR_COMMON = Object.freeze([
     {
-        name: "weight",
+        name: "data.weight",
+        legacyKey: "weight",
         to: "weight",
         ...AS_AUTHORED,
         kind: "number",
@@ -84,7 +85,8 @@ const GEAR_COMMON = Object.freeze([
         describe: "Weight of one, in pounds.",
     },
     {
-        name: "value",
+        name: "data.value",
+        legacyKey: "value",
         to: "value",
         ...AS_AUTHORED,
         kind: "number",
@@ -104,7 +106,8 @@ const GEAR_COMMON = Object.freeze([
  * @type {import("../engine/field-spec.mjs").FieldSpec}
  */
 const QUANTITY = Object.freeze({
-    name: "quantity",
+    name: "data.quantity",
+    legacyKey: "quantity",
     to: "quantity",
     ...NUMBER,
     default: 1,
@@ -124,6 +127,11 @@ const QUANTITY = Object.freeze({
  * a registry is addressed by what a note calls itself. What the document is
  * called is the map's answer, and only the map's.
  *
+ * Each field names both of its authored positions, as
+ * {@link module:hm3/actors} does and for the same reason: `name` is the shared
+ * source the content format's mapping tables state, and `legacyKey` is the key
+ * the `hm3:` block still carries.
+ *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 export const HM3_ITEM_FIELDS = Object.freeze({
@@ -139,7 +147,8 @@ export const HM3_ITEM_FIELDS = Object.freeze({
     containergear: Object.freeze([
         ...GEAR_COMMON,
         {
-            name: "capacity",
+            name: "data.capacity",
+            legacyKey: "capacity",
             to: "capacity.max",
             ...NUMBER,
             default: 0,
@@ -161,7 +170,8 @@ export const HM3_ITEM_FIELDS = Object.freeze({
     // through, and only the mastery level is declared here.
     skill: Object.freeze([
         {
-            name: "masteryLevel",
+            name: "data.masteryLevel",
+            legacyKey: "masteryLevel",
             to: "masteryLevel",
             ...NUMBER,
             default: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.9.1",
+    "version": "22.10.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",

package/sohl/infobox.mjs

@@ -51,6 +51,8 @@
  * @module
  */
 
+import { parseAddress, isAddressTuple, completeAddress } from "../engine/address.mjs";
+import { contentPackage } from "../engine/content-package.mjs";
 import {
     DURATION_LABELS,
     GEAR_UNITS,
@@ -63,6 +65,8 @@ import {
 import { currentType } from "../engine/ids.mjs";
 import { subTypes } from "../engine/note-vocabulary.mjs";
 import { systemBlock, systemData } from "../engine/system-block.mjs";
+import { readCanonicalKey } from "../engine/content-address.mjs";
+import { readQualifier } from "../engine/address.mjs";
 import { NOTE_SCHEMAS } from "./note-schemas.mjs";
 import { GEAR_TYPE_TO_KEY } from "./being-info.mjs";
 
@@ -174,15 +178,45 @@ function isMapping(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+/**
+ * Every content type `model:` may name — the note vocabulary this system
+ * declares, engine types included.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const MODEL_TYPES = new Set(Object.keys(NOTE_SCHEMAS));
+
+/**
+ * The `(type, shortcode)` an entry's `model:` names, or `undefined`.
+ *
+ * `model` is an Address, read by the same grammar every wikilink is —
+ * `type-shortcode` within this package, `package-system-type-shortcode` to
+ * name a dependency's catalogue. This decode answers neither of the two
+ * questions {@link module:engine/address} asks about the package: a runtime
+ * lookup among one actor's embedded items resolves by `(type, shortcode)`
+ * alone, where packages do not exist, so a fully qualified `model` is read for
+ * its last two segments exactly as a bare one is.
+ *
+ * @param {unknown} model - The authored value.
+ * @returns {{type: string, shortcode: string}|undefined} What it names.
+ */
+function modelAddress(model) {
+    const target = parseAddress(
+        model,
+        { package: contentPackage(), system: "sohl", types: MODEL_TYPES },
+        { declared: true, legacyShortcodeCase: true },
+    );
+    return target.reason ? undefined : target;
+}
+
 /**
  * What one entry of `sohl.items` names.
  *
  * An entry addresses its item three ways and every tree uses all three: a
- * `model` address whose last two hyphen-separated segments are always
- * `<type>-<shortcode>`, explicit `type` / `shortcode` keys, or a locally
- * authored item stating its type with the shortcode inside its own `system`
- * block. One decode covers all of them, so nothing downstream has to know
- * which form a note happened to use.
+ * `model` address, explicit `type` / `shortcode` keys, or a locally authored
+ * item stating its type with the shortcode inside its own `system` block. One
+ * decode covers all of them, so nothing downstream has to know which form a
+ * note happened to use.
  *
  * @param {object} entry - One `sohl.items` entry.
  * @returns {{type: string, shortcode: string, name: string, system: object}|undefined}
@@ -190,19 +224,21 @@ function isMapping(value) {
  */
 export function decodeItem(entry) {
     if (!isMapping(entry)) return undefined;
+    const address = entry.model ? modelAddress(entry.model) : undefined;
     let type = typeof entry.type === "string" ? entry.type : "";
     let shortcode = typeof entry.shortcode === "string" ? entry.shortcode : "";
-    if (!type && typeof entry.model === "string") {
-        const segments = entry.model.split("-");
-        if (segments.length >= 2) {
-            type = segments[segments.length - 2];
-            if (!shortcode) shortcode = segments[segments.length - 1];
+    if (!type) {
+        const named = address;
+        if (named) {
+            type = named.type;
+            if (!shortcode) shortcode = named.shortcode;
         }
     }
     const system = isMapping(entry.system) ? entry.system : {};
     if (!shortcode && typeof system.shortcode === "string") shortcode = system.shortcode;
     if (!type) return undefined;
     return {
+        ...(address ? { address } : {}),
         type: currentType(type),
         shortcode,
         name: typeof entry.name === "string" ? entry.name : "",
@@ -222,6 +258,32 @@ function itemsOf(fm, block) {
     return (Array.isArray(declared) ? declared : []).map(decodeItem).filter(Boolean);
 }
 
+/**
+ * A model's documentation presentation, with its native name as plain text
+ * when no documentation is published. The model keeps its native identity.
+ * @param {object} item - Decoded native item.
+ * @param {Function} resolve - The medium's reference resolver.
+ * @param {string} block - The native system.
+ * @returns {object|undefined} Documentation links and display metadata.
+ */
+function itemPresentation(item, resolve, block) {
+    if (!item.shortcode) return undefined;
+    if (!item.address)
+        return resolve?.(item.shortcode, { kind: "shortcode", type: item.type, system: block });
+    const documentation = completeAddress({ ...item.address, system: "none" });
+    const found = resolve?.(documentation, { type: documentation.type });
+    const native =
+        !found?.name || !found?.subType ? resolve?.(item.address, { type: item.type }) : undefined;
+    if (!found && !native) return undefined;
+    return {
+        name: found?.name ?? native?.name,
+        subType: found?.subType ?? native?.subType,
+        address: documentation,
+        ...(found?.url ? { url: found.url } : {}),
+        ...(found?.uuid ? { uuid: found.uuid } : {}),
+    };
+}
+
 /**
  * One item as a value a renderer can draw: its name, and a link where the
  * index reached it.
@@ -229,10 +291,11 @@ function itemsOf(fm, block) {
  * @param {object} item - A decoded item.
  * @param {(ref: unknown, hint?: object) => object|undefined} resolve - The
  *   medium's resolver.
- * @returns {{text: string, url?: string, uuid?: string, address?: string}} The value.
+ * @param {string} block - The native system.
+ * @returns {{text: string, url?: string, uuid?: string, address?: import("../engine/address.mjs").AddressTuple}} The value.
  */
-function itemValue(item, resolve) {
-    const found = item.shortcode ? resolve?.(item.shortcode, { type: item.type }) : undefined;
+function itemValue(item, resolve, block) {
+    const found = itemPresentation(item, resolve, block);
     const value = { text: item.name || found?.name || humanizeValue(item.shortcode) };
     if (found?.url) value.url = found.url;
     if (found?.uuid) value.uuid = found.uuid;
@@ -277,9 +340,9 @@ export function beingSections(fm, { block, resolve }) {
         if (item.type !== "skill") continue;
         const mastery = item.system.masteryLevelBase;
         if (!hasValue(mastery)) continue;
-        const found = item.shortcode ? resolve?.(item.shortcode, { type: "skill" }) : undefined;
+        const found = itemPresentation(item, resolve, block);
         const family = item.system.subType ?? found?.subType;
-        const value = itemValue(item, resolve);
+        const value = itemValue(item, resolve, block);
         const entry = { ...value, text: `${value.text} ${mastery}` };
         if (family && families.has(family)) families.get(family).push(entry);
         else unplaced.push(entry);
@@ -298,7 +361,7 @@ export function beingSections(fm, { block, resolve }) {
     const mystical = [];
     for (const item of items) {
         if (item.type !== "mysticalability") continue;
-        mystical.push(itemValue(item, resolve));
+        mystical.push(itemValue(item, resolve, block));
     }
     if (mystical.length) {
         sections.push({
@@ -313,7 +376,7 @@ export function beingSections(fm, { block, resolve }) {
     for (const item of items) {
         const key = GEAR_TYPE_TO_KEY[item.type];
         if (!key) continue;
-        gear.get(key).push(itemValue(item, resolve));
+        gear.get(key).push(itemValue(item, resolve, block));
     }
     const gearGroups = [];
     for (const [key, entries] of gear) {