@heroiclands/package-build 22.11.0 → 22.12.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @heroiclands/package-build
 
+## 22.12.0
+
+### Minor Changes
+
+- **References:** An Address in note data that names no local or declared dependency target now reports an error; missing artwork keeps its fallback warning.
+
 ## 22.11.0
 
 ### Minor Changes

package/CONTENT.md

@@ -1249,6 +1249,12 @@ somewhere other than where they were made, or not at all:
   reference answered by a vendored manifest lands exactly as it would in a
   wikilink. `--no-references` turns this one off for a tree whose cross-package
   references it cannot see.
+- **Dead Address reference** — an Address-valued `data:` field naming no local
+  note, asset or entry in a declared dependency index. The finding names the
+  field and the complete Address it names. A short form means this package;
+  another package requires the full Address. `--no-references` also turns off
+  this target check. Art slots report unresolved art through their own fallback
+  warning.
 
 **A schema says what a note may _write_, not what the compiler emits.** Those
 are different, and the difference is the whole calibration of the check: a note

package/docs/content-format.md

@@ -1315,6 +1315,12 @@ Address-keyed relation maps hold typed targets and standing values. Only generat
 output serializes these properties to Address strings. Runtime Shortcodes,
 Foundry UUIDs, file paths and URLs keep their own representations.
 
+An Address-valued `data:` field must name a target in this package or a declared
+dependency index. `content-build lint` reports a missing target as an error at
+the value or map key that names it. A stub counts as a target for data even
+though it publishes no page. Art slots use their own missing-art warning and
+document fallback.
+
 #### An omitted segment defaults from where the link is written
 
 It is **not** a wildcard and resolution is not a search. Every short form expands
@@ -3015,9 +3021,7 @@ If `sohl` is present, this becomes an `affliction` item.
 | `subType`                          | `system.subType`                     | NA    |
 | `data.transmission`                | `system.transmission`                | NA    |
 | `data.outcome`                     | `system.outcome`                     | NA    |
-| `data.healingRate`                 | `system.healingRateBase`             | NA    |
 | `data.contagionIndex`              | `system.contagionIndexBase`          | NA    |
-| `data.outcomeTraumas`              | `system.outcomeTraumas`              | NA    |
 | `data.onsetDurationFormula`        | `system.onsetDurationFormula`        | NA    |
 | `data.onsetDurationBase`           | `system.onsetDurationBase`           | NA    |
 | `data.healingCheckDurationFormula` | `system.healingCheckDurationFormula` | NA    |
@@ -3055,6 +3059,10 @@ that writes one fails the build. They are world times, and `0` is a valid one,
 so there is no blank a note could write either; leave them out and the data
 model's `null` stands.
 
+`data.healingRate` and `data.outcomeTraumas` are page data. SoHL reads an
+affliction’s base healing rate from `sohl.healingRateBase`. Its item declaration
+does not read `data.outcomeTraumas`.
+
 ### type: armorgear
 
 Note: `data.quantity` may not be specified. Quantity is always 1.
@@ -3129,7 +3137,9 @@ if a `sohl` property is present, a SoHL item of type "concoctiongear" will be cr
 | `data.value`      | `system.valueBase`      | NA    |
 | `data.quality`    | `system.qualityBase`    | NA    |
 | `data.durability` | `system.durabilityBase` | NA    |
-| `data.quantity`   | `system.quantity`       | NA    |
+
+`data.quantity` is page data for a concoction. SoHL sets `system.quantity` to
+`1` for each compendium item.
 
 ### type: containergear
 
@@ -3142,19 +3152,21 @@ Note: `data.quantity` may not be specified; quantity is always set to 1.
 | `value`            | `number` | Gear value                                 |
 | `quality`          | `number` | Gear quality                               |
 | `durability`       | `number` | Gear durability                            |
-| `capacity`         | `number` | Container capacity (in lbs)                |
+| `capacity`         | `number` | HM3 container capacity (in lbs)            |
 
 if a `sohl` property is present, a SoHL item of type "containergear" will be created.
 
 if a `hm3` property is present, an HM3 item of type "containergear" will be created.
 
-| shared source     | → sohl                   | → hm3                 |
-| ----------------- | ------------------------ | --------------------- |
-| `data.weight`     | `system.weightBase`      | `system.weight`       |
-| `data.value`      | `system.valueBase`       | `system.value`        |
-| `data.quality`    | `system.qualityBase`     | NA                    |
-| `data.durability` | `system.durabilityBase`  | NA                    |
-| `data.capacity`   | `system.maxCapacityBase` | `system.capacity.max` |
+| shared source     | → sohl                  | → hm3                 |
+| ----------------- | ----------------------- | --------------------- |
+| `data.weight`     | `system.weightBase`     | `system.weight`       |
+| `data.value`      | `system.valueBase`      | `system.value`        |
+| `data.quality`    | `system.qualityBase`    | NA                    |
+| `data.durability` | `system.durabilityBase` | NA                    |
+| `data.capacity`   | NA                      | `system.capacity.max` |
+
+SoHL reads a container’s capacity in pounds from `sohl.maxCapacity`.
 
 ### type: miscgear
 
@@ -3165,7 +3177,7 @@ if a `hm3` property is present, an HM3 item of type "containergear" will be crea
 | `value`            | `number` | Gear value                                 |
 | `quality`          | `number` | Gear quality                               |
 | `durability`       | `number` | Gear durability                            |
-| `quantity`         | `number` | Gear quantity (default: 1)                 |
+| `quantity`         | `number` | HM3 gear quantity (default: 1)             |
 
 if a `sohl` property is present, a SoHL item of type "miscgear" will be created.
 
@@ -3177,7 +3189,9 @@ if a `hm3` property is present, an HM3 item of type "miscgear" will be created.
 | `data.value`      | `system.valueBase`      | `system.value`    |
 | `data.quality`    | `system.qualityBase`    | NA                |
 | `data.durability` | `system.durabilityBase` | NA                |
-| `data.quantity`   | `system.quantity`       | `system.quantity` |
+| `data.quantity`   | NA                      | `system.quantity` |
+
+SoHL sets `system.quantity` to `1` for each compendium item.
 
 ### type: mystery
 
@@ -3213,10 +3227,12 @@ if a `sohl` property is present, a SoHL item of type "mystery" will be created.
 | --------------------- | ----------------------- | ----- |
 | `subType`             | `system.subType`        | NA    |
 | `data.skillAptitudes` | `system.skillAptitudes` | NA    |
-| `data.level`          | `system.levelBase`      | NA    |
 | `data.charges.value`  | `system.charges.value`  | NA    |
 | `data.charges.max`    | `system.charges.max`    | NA    |
 
+`data.level` is page data for a mystery. SoHL reads the item’s level from
+`sohl.levelBase`.
+
 ### type: mysticalability
 
 **subType**:
@@ -3250,13 +3266,15 @@ If an `hm3` property is present, an HM3 item is created, and `hm3.type` states w
 `sohl.system` as shortcodes and have no shared source; `data.assocSkill` and
 `data.assocAffiliation` name the same two notes as Addresses, for the page.
 
-| shared source        | → sohl                    | → hm3         |
-| -------------------- | ------------------------- | ------------- |
-| `subType`            | `system.subType`          | **see above** |
-| `data.masteryLevel`  | `system.masteryLevelBase` | NA            |
-| `data.level`         | `system.levelBase`        | NA            |
-| `data.charges.value` | `system.charges.value`    | NA            |
-| `data.charges.max`   | `system.charges.max`      | NA            |
+| shared source        | → sohl                 | → hm3         |
+| -------------------- | ---------------------- | ------------- |
+| `subType`            | `system.subType`       | **see above** |
+| `data.charges.value` | `system.charges.value` | NA            |
+| `data.charges.max`   | `system.charges.max`   | NA            |
+
+`data.masteryLevel` and `data.level` are page data for an ability. SoHL reads
+the item’s base mastery and level from `sohl.masteryLevelBase` and
+`sohl.levelBase`.
 
 ### type: projectilegear
 
@@ -3276,7 +3294,7 @@ If an `hm3` property is present, an HM3 item is created, and `hm3.type` states w
 | `value`            | `number` | Gear value                                 |
 | `quality`          | `number` | Gear quality                               |
 | `durability`       | `number` | Gear durability                            |
-| `quantity`         | `number` | Gear quantity (default: 1)                 |
+| `quantity`         | `number` | HM3 gear quantity (default: 1)             |
 
 if a `sohl` property is present, a SoHL item of type "projectilegear" will be created.
 
@@ -3293,7 +3311,9 @@ HM3 side while remaining distinct on the SoHL side.
 | `data.value`      | `system.valueBase`      | `system.value`    |
 | `data.quality`    | `system.qualityBase`    | NA                |
 | `data.durability` | `system.durabilityBase` | NA                |
-| `data.quantity`   | `system.quantity`       | `system.quantity` |
+| `data.quantity`   | NA                      | `system.quantity` |
+
+SoHL sets `system.quantity` to `1` for each compendium item.
 
 ### type: skill
 
@@ -3313,7 +3333,7 @@ HM3 side while remaining distinct on the SoHL side.
 | `data` property    | Values    | Description                                |
 | ------------------ | --------- | ------------------------------------------ |
 | `templatePriority` | `number`  | Template priority, _null_ = not a template |
-| `masteryLevel`     | `number`  | Mastery Level                              |
+| `masteryLevel`     | `number`  | HM3 mastery level                          |
 | `parentSkill`      | `Address` | Parent skill this skill specializes        |
 
 if a `sohl` property is present, a SoHL item of type "skill" will be created.
@@ -3326,10 +3346,12 @@ Note: `hm3.system.type` (skill types) use the values "Craft", "Physical", "Commu
 skill this one specializes, and has no shared source; `data.parentSkill` names that
 skill as an Address, for the page.
 
-| shared source       | → sohl                    | → hm3                 |
-| ------------------- | ------------------------- | --------------------- |
-| `subType`           | `system.subType`          | See notes above       |
-| `data.masteryLevel` | `system.masteryLevelBase` | `system.masteryLevel` |
+| shared source       | → sohl           | → hm3                 |
+| ------------------- | ---------------- | --------------------- |
+| `subType`           | `system.subType` | See notes above       |
+| `data.masteryLevel` | NA               | `system.masteryLevel` |
+
+SoHL reads a skill’s base mastery from `sohl.masteryLevelBase`.
 
 ### type: trauma
 

package/engine/frontmatter-lint.mjs

@@ -68,7 +68,7 @@ import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.
 import { pathnameProblem } from "./pathnames.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES, RENAMED_TYPES, currentType, renamedTypeMessage } from "./ids.mjs";
-import { parseAddress, acceptsType } from "./address.mjs";
+import { parseAddress, acceptsType, renderAddress } from "./address.mjs";
 import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
 import { isAddressSegment } from "./address-charset.mjs";
 // The one place the "every pack not named" key is spelled. Imported rather
@@ -421,7 +421,7 @@ function dataBlock(fm) {
  *   was loaded to recognise it would be worse than not checking.
  * @returns {object[]} Findings.
  */
-function checkDataContainer(note, { type, fields, packs, addressContext }) {
+function checkDataContainer(note, { type, fields, packs, addressContext, index }) {
     const findings = [];
     const { present, entries, malformed } = dataBlock(note.fm ?? {});
     if (!present) return findings;
@@ -504,7 +504,7 @@ function checkDataContainer(note, { type, fields, packs, addressContext }) {
             });
             continue;
         }
-        findings.push(...checkDataReferences(note, field, value, segments, addressContext));
+        findings.push(...checkDataReferences(note, field, value, segments, addressContext, index));
         // A `scalar-or-map` written in its map form is checked entry by entry,
         // because that is the correction an author has to make: one key's
         // value, not the whole map. Quoting the map back would name every
@@ -521,15 +521,16 @@ function checkDataContainer(note, { type, fields, packs, addressContext }) {
 }
 
 /**
- * Validate typed entries without resolving their targets.
+ * Validate typed entries and resolve declared non-art Address targets.
  * @param {object} note - The authored note.
  * @param {object} field - Its data field declaration.
  * @param {unknown} value - The field value.
  * @param {string[]} segments - The field's path under `data`.
  * @param {object} context - The builder's Address context.
+ * @param {object} [index] - The local and declared dependency Address index.
  * @returns {object[]} Located findings.
  */
-function checkDataReferences(note, field, value, segments, context) {
+function checkDataReferences(note, field, value, segments, context, index) {
     const checks = [];
     if (field.kind === "address") checks.push({ value, path: [], kind: "address" });
     if (field.entryKind) {
@@ -573,10 +574,16 @@ function checkDataReferences(note, field, value, segments, context) {
         let reason;
         if (!matchesKind(check.value, check.kind, defaults))
             reason = `should be ${check.kind === "address" ? "an Address" : "a Shortcode"}`;
-        else if (check.kind === "address" && accepted) {
+        else if (check.kind === "address") {
             const tuple = parseAddress(check.value, defaults, { declared: true });
-            if (!acceptsType(tuple, accepted))
+            if (accepted && !acceptsType(tuple, accepted))
                 reason = `accepts ${accepted.join(" or ")}, not ${tuple.type}`;
+            else if (
+                index?.addressHit &&
+                !ART_SLOTS.some((slot) => slot.key === field.name) &&
+                !index.addressHit(renderAddress(tuple))
+            )
+                reason = `names ${renderAddress(tuple)}, which does not resolve in this package or its declared dependencies`;
         }
         if (!reason) continue;
         const path = ["data", ...segments, ...check.path];
@@ -1519,6 +1526,7 @@ export function lintNote(
                 fields,
                 packs,
                 addressContext: referenceContext,
+                index,
             }),
         );
         findings.push(...checkSubType(note, { type, entry }));

package/engine/holdings.mjs

@@ -124,15 +124,12 @@ export const HELD_SUBTYPES = Object.freeze(["settlement", "site", "structure"]);
  * 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
+ * **The holdings graph has package-blind Shortcode identity.** `places` and
+ * `affiliations` merge local and fetched notes into one shortcode space; the
+ * first declaration wins. A fetched place attaches to a local parent with
+ * the same shortcode, and a fetched affiliation can name both local and
+ * fetched domains. The authored entries remain Addresses; this graph uses
+ * their shortcode projection for containment and tenure. 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.
@@ -321,6 +318,7 @@ export function holdingsPages(nodes) {
         // Read through the one reader, so a caller handing in what a note
         // wrote — an address, a wikilink, a repeat — is read as `holdingsNode`
         // reads it.
+        // Shortcode identity: the first node of each type owns this graph key.
         by.set(shortcode, {
             ...node,
             shortcode,

package/engine/map-places.mjs

@@ -108,15 +108,14 @@ const PLACE_TYPES = Object.freeze(new Set(["place"]));
  * 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
+ * **The map graph has package-blind Shortcode identity.** `world.places`
+ * merges local and fetched places by shortcode, with local declarations
+ * taking precedence. A fetched place attaches to the local containment tree
+ * by its parent's shortcode. The authored parent remains an Address; the map
+ * uses its shortcode projection for containment, layout, and DOT nodes. 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.
+ * package's own root.
  *
  * @param {unknown} parent - One `parents` entry.
  * @returns {string} Its shortcode, or `""` for an entry that names nothing.
@@ -193,6 +192,7 @@ export function placesFromRecords(records, { contentBase, base }) {
             // lint's finding.
             if (places.has(shortcode)) continue;
             const data = record.data && typeof record.data === "object" ? record.data : {};
+            // Shortcode identity: local places claim the map node first.
             places.set(shortcode, {
                 shortcode,
                 name,
@@ -243,6 +243,7 @@ function addForeignPlaces(world, foreignIndex) {
         if (entry?.type !== "place") continue;
         const shortcode = readCanonicalKey(canonical)?.shortcode?.toLowerCase() ?? "";
         if (!shortcode || world.places.has(shortcode)) continue;
+        // Shortcode identity: fetched places fill only unclaimed map nodes.
         world.places.set(shortcode, {
             shortcode,
             name: String(entry.name ?? shortcode),

package/engine/populations.mjs

@@ -242,8 +242,10 @@ export function foreignNode(canonical, entry) {
 /**
  * The corpus a link index describes.
  *
- * A shortcode is declared once per type and the first declaration wins, so a
- * local note shadows a dependency's the way the link resolver answers.
+ * Population containment and tenure use the same package-blind Shortcode
+ * identity as holdings and maps. Each type has one node per shortcode, with
+ * local notes taking precedence over fetched entries. A fetched place can
+ * attach to local geography, while its authored `parents` remains an Address.
  *
  * @param {object} index - The link index.
  * @returns {Corpus} The corpus.
@@ -263,6 +265,7 @@ function corpusOf(index) {
         if (!node) return;
         const by = node.type === "place" ? places : affiliations;
         if (by.has(node.shortcode)) return;
+        // Shortcode identity: the first node of each type owns this graph key.
         by.set(node.shortcode, node);
         // Not a canonical Address: package-blind by design, so a local place
         // shadows a foreign one of the same type and shortcode. `/` keeps that

package/package.json

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