@heroiclands/package-build 22.10.0 → 22.11.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @heroiclands/package-build
 
+## 22.11.0
+
+### Minor Changes
+
+- **Affiliations:** SoHL common skills link to their exact native Items; authors declare them in the SoHL block, and shared declarations receive an error.
+
 ## 22.10.0
 
 ### Minor Changes

package/CONTENT.md

@@ -1444,6 +1444,27 @@ segment, and returns a complete tuple or a reason. This mode leaves package
 membership to resolution. The lint receives the builder's package separately
 from target lookup, including when reference resolution is disabled.
 
+An affiliation authors native SoHL skill references at
+`sohl.system.commonSkills`:
+
+```yaml
+sohl:
+  system:
+    commonSkills:
+      - herb
+      - sohl-sohl-skill-law
+```
+
+The first Address names this content package's SoHL skill; the second names a
+skill in the declared SoHL dependency. The content index retains their complete
+Addresses. Foundry compilation resolves each exact native skill Item in the
+local or declared dependency index and writes its published Item UUID to the
+affiliation's `system.commonSkills` array. The producer's module ID and pack
+come from that index. An unresolved target or a target without a native Item
+UUID is a located error. The shared `data:` container has no `commonSkills`
+property. Infoboxes use a skill's published documentation journal when it has
+one and show its known name as plain text otherwise.
+
 **There is deliberately no third rule** requiring every note to repeat its own
 `type-shortcode` address in `aliases:`. It would serve one reader — Obsidian, so
 `[[type-shortcode]]` resolves in the editor — and no build reads it: both

package/docs/api.md

@@ -1369,6 +1369,7 @@ Which of SoHL's facts a note's summary panel carries, and how they group. Read o
 | `SOHL_FIELD_PRESENTATION` | `const SOHL_FIELD_PRESENTATION` | —                     | looking up what one of SoHL's fields is called, or why it carries no row            |
 | `PROTECTION_FIELDS`       | `const PROTECTION_FIELDS`       | —                     | reading the declarations of the aspects armour is rated against, in the order shown |
 | `UNSTATED`                | `const UNSTATED`                | —                     | naming what a strike mode shows where a value was not stated                        |
+| `affiliationSections`     | `affiliationSections(fm, ctx)`  | `object[]`            | building an affiliation's box with skill documentation links                        |
 | `armorSections`           | `armorSections(fm, ctx)`        | `object[]`            | building armour's box, protection included                                          |
 | `beingSections`           | `beingSections(fm, ctx)`        | `object[]`            | building a being's attributes, skills, mystical abilities and equipment             |
 | `decodeItem`              | `decodeItem(entry)`             | `object \| undefined` | reading what one `sohl.items` entry names, whichever form it was written in         |

package/docs/commands.md

@@ -1445,7 +1445,7 @@ declaration that compiles it. Otherwise 0.
 $ content-build content-format fields --fields sohl --coverage
 […] 13 type(s) compared against sohl's declarations (56 field pair(s)).
 […] 12 type(s) the format declares are out of reach — no `itemBuilders` entry covers them: being, homepage, vehicle, armorlocation, lore, map, place, scenario, doc, macro, bundle, folder.
-[…] affiliation: format only [commonSkills, demonym, economy, epithet, governance, lore, population, symbol, templatePriority], declaration only [level, office, society, subType, title]
+[…] affiliation: format only [demonym, economy, epithet, governance, lore, population, symbol, templatePriority], declaration only [commonSkills, level, office, society, subType, title]
 ```
 
 **SEE ALSO**

package/docs/content-format.md

@@ -495,6 +495,12 @@ reduction happens at build time, and two things are errors naming the note: an
 Address whose type the field does not accept, and two Addresses that reduce to one
 shortcode, which the field cannot hold both of.
 
+**A SoHL skill Address becomes a native Item UUID.** An affiliation's
+`sohl.system.commonSkills` names skills in its own package or a declared
+dependency. Its `system.commonSkills` contains the exact published Item UUIDs,
+including each foreign module's own pack name. Native skill lookup uses those
+UUIDs; the journal, website and book use documentation links for presentation.
+
 **A `Code` suffix marks a different thing.** `system.assocSkillCode`,
 `system.assocAffiliationCode` and `system.parentSkillCode` hold a `Shortcode` at
 both ends — each is authored as one, under `<system>.system`, and emitted verbatim
@@ -2844,7 +2850,6 @@ rank names the standing, and the standing says.
 | `governance.summary` | `string`                 | summary of the governance situation                                                            |
 | `governance.ranks`   | `Rank[]`                 | The ranks available to members of the affiliation                                              |
 | `governance.offices` | `Map<name, description>` | Official offices in the affiliation                                                            |
-| `commonSkills`       | `Address[]`              | Common skills among members (languages, etc.)                                                  |
 | `seat`               | `Address`                | Where the affiliation's authority sits                                                         |
 | `domains`            | `Address[]`              | Places over which this affiliation holds sway                                                  |
 | `population`         | `number`                 | Number of people in the affiliation (precision 2 significant digits).                          |
@@ -2926,6 +2931,27 @@ If `sohl` is present, this becomes an `affiliation` item.
 | `data.parents`   | `system.parents`   | NA    |
 | `data.relations` | `system.relations` | NA    |
 
+An affiliation writes SoHL common skills under `sohl.system.commonSkills` as a
+list of skill Addresses. An abbreviated value names a skill in the authoring
+package; a skill in the SoHL system package uses its complete Address:
+
+```yaml
+sohl:
+  system:
+    commonSkills:
+      - herb
+      - sohl-sohl-skill-law
+```
+
+The compiled SoHL Item stores the exact published Item UUIDs in
+`system.commonSkills`. An empty or absent list emits `[]`. A foreign target must
+come from a declared `relationships.systems` or `relationships.requires` content
+index. Each UUID uses the module and pack named by that target's published index;
+a missing skill Item or Item UUID is an error at the authored Address. The
+content index retains complete Addresses. Journal, web and book infoboxes link
+to a skill's published documentation journal when one exists and otherwise show
+its name as plain text.
+
 `governance` reaches no system field. Ranks and offices are the note's and the
 web page's — SoHL's affiliation item has nowhere to put them, and inventing a
 mapping for a field no schema declares is the drift these tables exist to catch.
@@ -3903,7 +3929,7 @@ because they were true of something else, and each removal has a home to go to.
 
 **`languages` is a fact about a polity.** A place's languages change when its
 ruler changes, which is what makes them the ruler's property — and
-`affiliation.commonSkills` already holds them. The authored corpus agrees: of 206
+`sohl.system.commonSkills` holds them. The authored corpus agrees: of 206
 places carrying `languages`, 190 were settlements and 16 were regions, and not one
 was a site, a structure or a feature. A ruin has no language.
 

package/engine/address-fields.mjs

@@ -12,16 +12,18 @@
  */
 
 /**
- * **An authored Address, an emitted Shortcode.**
+ * **An authored Address, an emitted native reference.**
  *
  * A declared field may hold an Address where the document it compiles into
- * holds a **Shortcode**. An affiliation's `seat` is the worked case: the note
+ * holds a **Shortcode** or a published Item UUID. An affiliation's `seat` is a Shortcode case: the note
  * names a place at whatever length says what it means — `tashal`,
  * `place-tashal`, `none-place-tashal`, `kethira-none-place-tashal` — and the
  * compiled Item carries `tashal`, which is what the runtime resolves among the
  * items one actor holds, where packages do not exist.
  *
- * So the builder resolves the one into the other, and this module is that step.
+ * The `emit: "uuid"` declaration resolves an exact native target from the
+ * local or declared dependency index. The target supplies its published UUID.
+ * This module performs both conversions at the Foundry output boundary.
  * Storing the written form instead would store a value plus a context that does
  * not travel with it: a four-segment string reaches a runtime that looks up one
  * segment and returns nothing, silently.
@@ -70,10 +72,8 @@
  *
  * ## What this module does not do
  *
- * It resolves nothing against the index: the shortcode is a segment of the
- * Address, so reducing one needs the grammar and the position's declarations
- * and nothing else. Whether the target exists is a separate question, asked
- * where the index is.
+ * Shortcode output needs only the Address grammar. UUID output requires the
+ * exact target in the published index and accepts only Item UUIDs.
  *
  * A failure is a **finding**, never a diagnostic: the caller owns the file and
  * the severity, and locates the finding at the value inside the note.
@@ -107,6 +107,7 @@ export const ADDRESS_FIELD_SHAPES = Object.freeze(["value", "items", "keys"]);
  * @property {readonly string[]} accepts - Every type the position accepts.
  * @property {"value"|"items"|"keys"} [holds] - Where the Addresses are.
  *   Defaults to `value`.
+ * @property {"uuid"} [emit] - Resolve each exact target to its published Item UUID.
  */
 
 /**
@@ -171,7 +172,7 @@ function reduceOne(value, field, vocabulary, findings) {
     // Two keys, or two list entries, reducing to one emitted shortcode: the
     // Address each of them named, by the shortcode all of them land on.
     const seen = new Map();
-    const read = (written) => readOne(written, field, defaults, seen, findings, shape);
+    const read = (written) => readOne(written, field, defaults, seen, findings, shape, vocabulary);
 
     if (shape === "keys") {
         if (!isMapping(value)) return undefined;
@@ -212,8 +213,15 @@ function reduceOne(value, field, vocabulary, findings) {
  * @returns {string|undefined} The shortcode, or `undefined` when nothing is
  *   emitted for this value.
  */
-function readOne(written, field, defaults, seen, findings, shape) {
+function readOne(written, field, defaults, seen, findings, shape, vocabulary) {
     const key = findingKey(field);
+    // An embedded Item may inherit an already compiled reference from its model.
+    if (
+        field.address.emit === "uuid" &&
+        typeof written === "string" &&
+        /^Compendium\.[^.]+\.[^.]+\.Item\.[^.]+$/.test(written)
+    )
+        return written;
     const value =
         isAddressTuple(written) ? renderAddress(written)
         : typeof written === "string" ? written
@@ -231,6 +239,20 @@ function readOne(written, field, defaults, seen, findings, shape) {
     }
 
     const address = renderAddress(tuple);
+    if (field.address.emit === "uuid") {
+        const target =
+            tuple.package === vocabulary.package ?
+                vocabulary.referenceTargets?.get(address)
+            :   vocabulary.foreignReferences?.get(address);
+        const uuid = target?.uuid;
+        if (!uuid || !/^Compendium\.[^.]+\.[^.]+\.Item\.[^.]+$/.test(uuid)) {
+            report(
+                `\`${key}\` names \`${address}\`, but its exact native Item has no published Item UUID`,
+            );
+            return undefined;
+        }
+        return uuid;
+    }
     const code = tuple.shortcode;
     const first = seen.get(code);
     if (first && first.address !== address) {

package/engine/base-compiler.mjs

@@ -717,6 +717,8 @@ export class BasePackCompiler {
             types: this.linkIndex?.types,
             packages: this.linkIndex?.packages,
             noIndexPackages: this.linkIndex?.noIndexPackages,
+            referenceTargets: this.linkIndex?.referenceTargets,
+            foreignReferences: this.linkIndex?.foreignReferences,
         });
         for (const finding of findings) {
             this.errorCount++;

package/engine/field-spec.mjs

@@ -148,8 +148,9 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   being's own body structure, not a note, so it declares none. Distinct
  *   from a `DataFieldSpec`'s `ref` ({@link module:engine/note-vocabulary}),
  *   which names an **Address** instead.
- * @property {import("./address-fields.mjs").AddressPosition} [address] - **The
- *   authored value is an Address and the emitted one is its Shortcode.** The
+ * @property {import("./address-fields.mjs").AddressPosition} [address] - The
+ *   authored value is an Address. The emitted value is its Shortcode, or the
+ *   exact published Item UUID when `emit: "uuid"` is declared. The
  *   statement carries the default type an omitted `<type>` segment takes, the
  *   set of types the position accepts — two separate things, which coincide at
  *   most positions — and where the Addresses sit: the value itself, every

package/engine/frontmatter-lint.mjs

@@ -476,10 +476,12 @@ function checkDataContainer(note, { type, fields, packs, addressContext }) {
             ...positionOfFrontmatterPath(raw, ["data", key], { key: true }),
             severity: "error",
             message:
-                `"${key}" is not a \`data:\` property declared by ${type}; ` +
-                `the container is closed, so unlike a top-level key it is ` +
-                `not passed through to the page` +
-                (guess ? `. Did you mean "${guess}"?` : ""),
+                type === "affiliation" && key === "commonSkills" ?
+                    "`data.commonSkills` is not an affiliation field; write skill Addresses at `sohl.system.commonSkills`"
+                :   `"${key}" is not a \`data:\` property declared by ${type}; ` +
+                    `the container is closed, so unlike a top-level key it is ` +
+                    `not passed through to the page` +
+                    (guess ? `. Did you mean "${guess}"?` : ""),
         });
     }
 

package/engine/note-addresses.mjs

@@ -5,7 +5,7 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
-import { systemBlocksFor } from "./system-vocabulary.mjs";
+import { declaredSystems, systemBlocksFor } from "./system-vocabulary.mjs";
 import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
 import {
     isAddressTuple,
@@ -260,10 +260,25 @@ export function decodeNoteAddresses(fm, context) {
  * @returns {object} Builder defaults and system declarations.
  */
 export function noteAddressContext(config) {
+    const systemBlocks = { ...systemBlocksFor(config) };
+    // A module with one declared system uses its flat Item registry for that
+    // system's Address positions, including fields stored in its content index.
+    const systems = new Set([
+        ...declaredSystems(config),
+        ...(config.relationships?.systems ?? []).map((relationship) => relationship.id),
+    ]);
+    if (
+        systems.size === 1 &&
+        config.itemFields &&
+        Object.keys(config.itemFieldsBySystem ?? {}).length === 0
+    ) {
+        const [system] = systems;
+        systemBlocks[system] = { ...systemBlocks[system], fields: config.itemFields };
+    }
     return {
         package: config.contentPackage,
         system: "none",
-        systemBlocks: systemBlocksFor(config),
+        systemBlocks,
     };
 }
 

package/engine/note-vocabulary.mjs

@@ -761,13 +761,6 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...ANY,
                 describe: "The named offices it appoints, each with what the office does.",
             },
-            {
-                name: "commonSkills",
-                ...LINKS,
-                ref: "skill",
-                accepts: ["skill"],
-                describe: "Skills common among members — languages first among them.",
-            },
             {
                 name: "seat",
                 ...LINK,

package/package.json

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

@@ -543,6 +543,36 @@ function genericSections(fm, type, ctx) {
     return systemRowsSection(fm, NOTE_SCHEMAS[type], ctx);
 }
 
+/** An affiliation presents skill documentation while retaining native Item identity. */
+export function affiliationSections(fm, ctx) {
+    const field = NOTE_SCHEMAS.affiliation.find((entry) => entry.to === "commonSkills");
+    const sections = systemRowsSection(
+        fm,
+        NOTE_SCHEMAS.affiliation.filter((entry) => entry !== field),
+        ctx,
+    );
+    const { value } = ctx.resolveField(field, fm, { block: ctx.block });
+    if (!Array.isArray(value) || value.length === 0) return sections;
+    const entries = value.map((skill) => {
+        const native = ctx.resolve?.(skill, { type: "skill", system: "sohl" });
+        const docAddress =
+            isAddressTuple(skill) ? completeAddress({ ...skill, system: "none" }) : undefined;
+        const doc = docAddress ? ctx.resolve?.(docAddress, { type: docAddress.type }) : undefined;
+        return {
+            text: doc?.name || native?.name || humanizeValue(skill),
+            ...(doc?.url ? { url: doc.url } : {}),
+            ...(doc?.uuid ? { uuid: doc.uuid } : {}),
+            ...(docAddress && (doc?.url || doc?.uuid) ? { address: docAddress } : {}),
+        };
+    });
+    sections.push({
+        id: "commonskills",
+        layout: "rows",
+        rows: [{ label: "Common skills", kind: "links", value: entries }],
+    });
+    return sections;
+}
+
 /**
  * SoHL's infobox declaration.
  *
@@ -555,6 +585,7 @@ export const SOHL_INFOBOX = defineInfobox({
     presentation: SOHL_FIELD_PRESENTATION,
     sections: {
         being: beingSections,
+        affiliation: affiliationSections,
         armorgear: armorSections,
         weapongear: weaponSections,
         projectilegear: projectileSections,

package/sohl/item-fields.mjs

@@ -178,6 +178,14 @@ const AFFILIATION_ITEMS = Object.freeze({
 /** A map keyed by affiliation: this one's standing toward each. */
 const AFFILIATION_KEYS = Object.freeze({ ...AFFILIATION_ITEMS, holds: "keys" });
 
+/** Native skill references retain the published Item UUID. */
+const SKILL_UUID_ITEMS = Object.freeze({
+    type: "skill",
+    accepts: Object.freeze(["skill"]),
+    holds: "items",
+    emit: "uuid",
+});
+
 /** Standings toward other affiliations, validated against the closed list. */
 const RELATION = Object.freeze({
     shape: "map of affiliation address → standing",
@@ -385,6 +393,15 @@ export const ITEM_FIELDS = Object.freeze({
             default: 0,
             describe: "Standing within the society.",
         },
+        {
+            name: "commonSkills",
+            to: "commonSkills",
+            ...ADDRESS_LIST,
+            address: SKILL_UUID_ITEMS,
+            default: [],
+            topLevelMeans: "Common skills belong to the SoHL affiliation item.",
+            describe: "Native SoHL skill Items common among members, by address.",
+        },
         {
             // Plural because the field holds a map of many standings, one per
             // affiliation — the singular reads as a misnomer.

package/types/engine/address-fields.d.mts

@@ -6,6 +6,7 @@
  * @property {readonly string[]} accepts - Every type the position accepts.
  * @property {"value"|"items"|"keys"} [holds] - Where the Addresses are.
  *   Defaults to `value`.
+ * @property {"uuid"} [emit] - Resolve each exact target to its published Item UUID.
  */
 /**
  * What a reduction could not do, for a caller to report.
@@ -69,6 +70,10 @@ export type AddressPosition = {
      * Defaults to `value`.
      */
     holds?: "keys" | "value" | "items" | undefined;
+    /**
+     * - Resolve each exact target to its published Item UUID.
+     */
+    emit?: "uuid" | undefined;
 };
 /**
  * What a reduction could not do, for a caller to report.

package/types/engine/field-spec.d.mts

@@ -277,8 +277,9 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   being's own body structure, not a note, so it declares none. Distinct
  *   from a `DataFieldSpec`'s `ref` ({@link module:engine/note-vocabulary}),
  *   which names an **Address** instead.
- * @property {import("./address-fields.mjs").AddressPosition} [address] - **The
- *   authored value is an Address and the emitted one is its Shortcode.** The
+ * @property {import("./address-fields.mjs").AddressPosition} [address] - The
+ *   authored value is an Address. The emitted value is its Shortcode, or the
+ *   exact published Item UUID when `emit: "uuid"` is declared. The
  *   statement carries the default type an omitted `<type>` segment takes, the
  *   set of types the position accepts — two separate things, which coincide at
  *   most positions — and where the Addresses sit: the value itself, every
@@ -553,8 +554,9 @@ export type FieldSpec = {
      */
     code?: string | undefined;
     /**
-     * - **The
-     * authored value is an Address and the emitted one is its Shortcode.** The
+     * - The
+     * authored value is an Address. The emitted value is its Shortcode, or the
+     * exact published Item UUID when `emit: "uuid"` is declared. The
      * statement carries the default type an omitted `<type>` segment takes, the
      * set of types the position accepts — two separate things, which coincide at
      * most positions — and where the Addresses sit: the value itself, every

package/types/sohl/infobox.d.mts

@@ -82,6 +82,8 @@ export function projectileSections(fm: object, ctx: object): object[];
  * @returns {[string, object][]} Mode name → the mode.
  */
 export function strikeModes(declared: unknown): [string, object][];
+/** An affiliation presents skill documentation while retaining native Item identity. */
+export function affiliationSections(fm: any, ctx: any): object[];
 /** What this system's box is called. @type {string} */
 export const SOHL_INFOBOX_TITLE: string;
 /**