@heroiclands/package-build 22.9.1 → 22.10.0

package/sohl/item-fields.mjs

@@ -35,6 +35,7 @@
  * @module
  */
 
+import { isAddressTuple } from "../engine/address.mjs";
 import {
     AS_AUTHORED,
     BLANK_IS_DEFAULT,
@@ -143,14 +144,48 @@ const SKILL_APTITUDES = Object.freeze({
     read: (_raw, { fm }) => resolveSkillAptitudes(fm, noteContext(fm, "mystery")),
 });
 
+/* --------------------------------------------------------------------- */
+/*  The Address positions                                                 */
+/* --------------------------------------------------------------------- */
+
+/*
+ * An affiliation names other notes in four of its fields, and each of those
+ * values is an **Address** — written at whatever length says what it means —
+ * while the compiled Item holds the **Shortcode** the runtime resolves among
+ * one actor's items. `engine/address-fields.mjs` is the step between them, and
+ * these are the positions it reads.
+ *
+ * Each states two things, and they are not the same statement: `type` is the
+ * default an omitted `<type>` segment takes, and `accepts` is the set of types
+ * the field takes at all. They coincide at all four, which is the common case
+ * rather than the rule — an art slot defaults to `icon` and accepts `icon` or
+ * `image` — so each is written out rather than derived from the other.
+ */
+
+/** One place: an affiliation's seat. */
+const PLACE_VALUE = Object.freeze({ type: "place", accepts: Object.freeze(["place"]) });
+
+/** A list of places: the ones an affiliation holds sway over. */
+const PLACE_ITEMS = Object.freeze({ ...PLACE_VALUE, holds: "items" });
+
+/** A list of affiliations: the ones this affiliation answers to. */
+const AFFILIATION_ITEMS = Object.freeze({
+    type: "affiliation",
+    accepts: Object.freeze(["affiliation"]),
+    holds: "items",
+});
+
+/** A map keyed by affiliation: this one's standing toward each. */
+const AFFILIATION_KEYS = Object.freeze({ ...AFFILIATION_ITEMS, holds: "keys" });
+
 /** Standings toward other affiliations, validated against the closed list. */
 const RELATION = Object.freeze({
-    shape: "map of affiliation shortcode → standing",
+    shape: "map of affiliation address → standing",
     read: (_raw, { fm }) => resolveRelation(fm, noteContext(fm, "affiliation")),
 });
 
 /**
- * A list of references, each a bare shortcode.
+ * A list of references, each an address.
  *
  * Blank entries are dropped rather than emitted: a list that has been edited
  * down in a property editor keeps its empty rows, and an empty string is not a
@@ -158,15 +193,15 @@ const RELATION = Object.freeze({
  * value here — a sovereign polity is subordinate to nobody — rather than an
  * unset one.
  */
-const SHORTCODE_LIST = Object.freeze({
-    shape: "list of shortcodes",
+const ADDRESS_LIST = Object.freeze({
+    shape: "list of addresses",
     kind: "list",
     read: (raw) =>
         (Array.isArray(raw) ? raw
         : raw == null || raw === "" ? []
         : [raw]
         )
-            .map((entry) => String(entry ?? "").trim())
+            .map((entry) => (isAddressTuple(entry) ? entry : String(entry ?? "").trim()))
             .filter((entry) => entry !== ""),
 });
 
@@ -237,7 +272,8 @@ const GEAR_COMMON = Object.freeze([
         describe: "How many the stack holds. A compendium article ships one.",
     },
     {
-        name: "weight",
+        name: "data.weight",
+        legacyKey: "weight",
         to: "weightBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -245,7 +281,8 @@ const GEAR_COMMON = Object.freeze([
         describe: "Weight of one, in pounds.",
     },
     {
-        name: "value",
+        name: "data.value",
+        legacyKey: "value",
         to: "valueBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -253,7 +290,8 @@ const GEAR_COMMON = Object.freeze([
         describe: "Worth of one, in pence.",
     },
     {
-        name: "quality",
+        name: "data.quality",
+        legacyKey: "quality",
         to: "qualityBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -261,7 +299,8 @@ const GEAR_COMMON = Object.freeze([
         describe: "Craftsmanship, as a modifier to what the article does.",
     },
     {
-        name: "durability",
+        name: "data.durability",
+        legacyKey: "durability",
         to: "durabilityBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -293,6 +332,14 @@ const GEAR_COMMON = Object.freeze([
  * Every item type's frontmatter vocabulary, in the order the `system` block
  * emits it.
  *
+ * **A field whose shared source is a path into `data:` names both positions.**
+ * `name` is the source the content format's mapping tables state — `data.seat`,
+ * `data.weight` — and `legacyKey` is the key the system block still carries, which
+ * wins while a tree writes it. Naming only the source would move the in-block
+ * read to a key spelled `data.seat`, which nothing authors; naming only the key
+ * leaves the container the specification points at unread, and the field then
+ * compiles its default over an authored value with nothing said.
+ *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 export const ITEM_FIELDS = Object.freeze({
@@ -341,9 +388,11 @@ export const ITEM_FIELDS = Object.freeze({
         {
             // Plural because the field holds a map of many standings, one per
             // affiliation — the singular reads as a misnomer.
-            name: "relations",
+            name: "data.relations",
+            legacyKey: "relations",
             to: "relations",
             ...RELATION,
+            address: AFFILIATION_KEYS,
             default: {},
             describe: "How this society regards others: aligned, unaligned, rival or nemesis.",
         },
@@ -351,21 +400,25 @@ export const ITEM_FIELDS = Object.freeze({
             // The organisational relation: which bodies this one answers to.
             // A list, because an affiliation may sit under more than one at
             // once — an arcane tradition within an order, say.
-            name: "parents",
+            name: "data.parents",
+            legacyKey: "parents",
             to: "parents",
-            ...SHORTCODE_LIST,
+            ...ADDRESS_LIST,
+            address: AFFILIATION_ITEMS,
             default: [],
-            describe: "Affiliations this one is subordinate to, by shortcode.",
+            describe: "Affiliations this one is subordinate to, by address.",
         },
         {
             // Not `capital` or `headquarters`: each fits about half the eleven
             // subTypes, while a seat covers a polity, a guild, an order and a
             // faith alike.
-            name: "seat",
+            name: "data.seat",
+            legacyKey: "seat",
             to: "seat",
             ...BLANK_IS_NULL,
+            address: PLACE_VALUE,
             default: null,
-            describe: "Where the affiliation's authority sits, by place shortcode.",
+            describe: "Where the affiliation's authority sits, by place address.",
         },
         {
             // The geographic relation, kept apart from the organisational one
@@ -375,11 +428,13 @@ export const ITEM_FIELDS = Object.freeze({
             // mapping row states (`data.domains` → `system.domain`). The two
             // spellings are deliberate rather than a slip, so the declaration
             // carries both rather than either side guessing.
-            name: "domains",
+            name: "data.domains",
+            legacyKey: "domains",
             to: "domain",
-            ...SHORTCODE_LIST,
+            ...ADDRESS_LIST,
+            address: PLACE_ITEMS,
             default: [],
-            describe: "Places this affiliation holds sway over, by shortcode.",
+            describe: "Places this affiliation holds sway over, by address.",
         },
     ]),
 
@@ -418,14 +473,16 @@ export const ITEM_FIELDS = Object.freeze({
             describe: "How readily the host throws it off.",
         },
         {
-            name: "contagionIndex",
+            name: "data.contagionIndex",
+            legacyKey: "contagionIndex",
             to: "contagionIndexBase",
             ...NUMBER,
             default: 0,
             describe: "How readily it passes to someone else.",
         },
         {
-            name: "transmission",
+            name: "data.transmission",
+            legacyKey: "transmission",
             to: "transmission",
             ...AS_AUTHORED,
             default: "none",
@@ -440,7 +497,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Days from contracting to onset, rolled by the receiving actor. Unset means no incubation.",
         },
         {
-            name: "outcome",
+            name: "data.outcome",
+            legacyKey: "outcome",
             to: "outcome",
             ...BLANK_IS_DEFAULT,
             default: "cured",
@@ -464,7 +522,8 @@ export const ITEM_FIELDS = Object.freeze({
         // cannot be grepped, and each phase's prose differs anyway — which is
         // the whole content of the declaration.
         {
-            name: "onsetDurationFormula",
+            name: "data.onsetDurationFormula",
+            legacyKey: "onsetDurationFormula",
             to: "onsetDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -472,7 +531,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval from contracting the affliction to the start of onset. Omitted when unset, leaving no incubation.",
         },
         {
-            name: "onsetDurationBase",
+            name: "data.onsetDurationBase",
+            legacyKey: "onsetDurationBase",
             to: "onsetDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -480,7 +540,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "The onset interval in seconds, standing in for a roll of the formula. Omitted when unset.",
         },
         {
-            name: "healingCheckDurationFormula",
+            name: "data.healingCheckDurationFormula",
+            legacyKey: "healingCheckDurationFormula",
             to: "healingCheckDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -488,7 +549,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval between healing checks, once the affliction is symptomatic. Omitted when unset.",
         },
         {
-            name: "healingCheckDurationBase",
+            name: "data.healingCheckDurationBase",
+            legacyKey: "healingCheckDurationBase",
             to: "healingCheckDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -496,7 +558,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "The healing-check interval in seconds, standing in for a roll of the formula. Omitted when unset.",
         },
         {
-            name: "resolutionDurationFormula",
+            name: "data.resolutionDurationFormula",
+            legacyKey: "resolutionDurationFormula",
             to: "resolutionDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -504,7 +567,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval from onset to the affliction running its course. Omitted when unset.",
         },
         {
-            name: "resolutionDurationBase",
+            name: "data.resolutionDurationBase",
+            legacyKey: "resolutionDurationBase",
             to: "resolutionDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -711,7 +775,7 @@ export const ITEM_FIELDS = Object.freeze({
         {
             name: "assocSkillCode",
             to: "assocSkillCode",
-            ref: "skill",
+            code: "skill",
             ...BLANK_IS_NULL,
             default: null,
             describe: "Shortcode of the skill the mystery is tested against.",
@@ -719,7 +783,7 @@ export const ITEM_FIELDS = Object.freeze({
         {
             name: "assocAffiliationCode",
             to: "assocAffiliationCode",
-            ref: "affiliation",
+            code: "affiliation",
             ...BLANK_IS_NULL,
             default: null,
             describe:
@@ -733,14 +797,16 @@ export const ITEM_FIELDS = Object.freeze({
             describe: "The mystery's level before any modifier.",
         },
         {
-            name: "skillAptitudes",
+            name: "data.skillAptitudes",
+            legacyKey: "skillAptitudes",
             to: "skillAptitudes",
             ...SKILL_APTITUDES,
             default: {},
             describe: "Aptitude the mystery grants, per skill selector.",
         },
         {
-            name: "charges",
+            name: "data.charges",
+            legacyKey: "charges",
             to: "charges",
             ...CHARGES,
             default: { value: null, max: null },
@@ -760,7 +826,7 @@ export const ITEM_FIELDS = Object.freeze({
         {
             name: "assocSkillCode",
             to: "assocSkillCode",
-            ref: "skill",
+            code: "skill",
             ...AS_AUTHORED,
             default: "",
             describe: "Shortcode of the skill the ability is tested against.",
@@ -768,7 +834,7 @@ export const ITEM_FIELDS = Object.freeze({
         {
             name: "assocAffiliationCode",
             to: "assocAffiliationCode",
-            ref: "affiliation",
+            code: "affiliation",
             ...BLANK_IS_NULL,
             default: null,
             describe:
@@ -796,7 +862,8 @@ export const ITEM_FIELDS = Object.freeze({
             describe: "The ability's level before any modifier.",
         },
         {
-            name: "charges",
+            name: "data.charges",
+            legacyKey: "charges",
             to: "charges",
             ...CHARGES,
             default: { value: null, max: null },
@@ -884,7 +951,7 @@ export const ITEM_FIELDS = Object.freeze({
         {
             name: "parentSkillCode",
             to: "parentSkillCode",
-            ref: "skill",
+            code: "skill",
             ...AS_AUTHORED,
             default: "",
             describe: "Shortcode of the skill this one specialises, for a specialisation.",
@@ -959,7 +1026,8 @@ export const ITEM_FIELDS = Object.freeze({
         // `bloodLossAdvance*` is the one an author reaches for most: a trauma
         // that sets it bleeds, and one that leaves it unset does not.
         {
-            name: "healingCheckDurationFormula",
+            name: "data.healingCheckDurationFormula",
+            legacyKey: "healingCheckDurationFormula",
             to: "healingCheckDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -967,7 +1035,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval between healing checks. Omitted when unset, leaving the world's configured interval to apply.",
         },
         {
-            name: "healingCheckDurationBase",
+            name: "data.healingCheckDurationBase",
+            legacyKey: "healingCheckDurationBase",
             to: "healingCheckDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -975,7 +1044,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "The healing-check interval in seconds, standing in for a roll of the formula. Omitted when unset.",
         },
         {
-            name: "bloodLossAdvanceDurationFormula",
+            name: "data.bloodLossAdvanceDurationFormula",
+            legacyKey: "bloodLossAdvanceDurationFormula",
             to: "bloodLossAdvanceDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -983,7 +1053,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval between blood-loss advances. Omitted when unset, leaving the world's configured interval to apply.",
         },
         {
-            name: "bloodLossAdvanceDurationBase",
+            name: "data.bloodLossAdvanceDurationBase",
+            legacyKey: "bloodLossAdvanceDurationBase",
             to: "bloodLossAdvanceDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -991,7 +1062,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "The blood-loss interval in seconds. Setting it is what makes the wound bleed; omitted when unset, and the wound does not.",
         },
         {
-            name: "courseDurationFormula",
+            name: "data.courseDurationFormula",
+            legacyKey: "courseDurationFormula",
             to: "courseDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -999,7 +1071,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval between course tests, for a condition that runs one — shock, coma, infection. Omitted when unset.",
         },
         {
-            name: "courseDurationBase",
+            name: "data.courseDurationBase",
+            legacyKey: "courseDurationBase",
             to: "courseDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,

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

@@ -0,0 +1,90 @@
+/**
+ * An Address position, as a field declaration states it.
+ *
+ * @typedef {object} AddressPosition
+ * @property {string} type - The type an omitted `<type>` segment takes.
+ * @property {readonly string[]} accepts - Every type the position accepts.
+ * @property {"value"|"items"|"keys"} [holds] - Where the Addresses are.
+ *   Defaults to `value`.
+ */
+/**
+ * What a reduction could not do, for a caller to report.
+ *
+ * @typedef {object} AddressFinding
+ * @property {string} key - The field, named as an author writes it.
+ * @property {string} written - The authored value, so the caller can locate the
+ *   finding at the line carrying it rather than at the key.
+ * @property {string} message - One sentence, naming the fix.
+ */
+/**
+ * The declarations that state an Address position.
+ *
+ * @param {readonly object[]} fields - A field declaration.
+ * @returns {object[]} Only the fields carrying an `address` statement.
+ */
+export function addressFields(fields: readonly object[]): object[];
+/**
+ * Reduce every Address a compiled block holds to the Shortcode it names.
+ *
+ * The block is edited in place, as {@link
+ * module:engine/system-block.mergeSystemData} edits it: what the caller holds is
+ * the document being assembled, and a field the reduction cannot read is left
+ * exactly as authored — the findings stop the build, so nothing ships either
+ * way, and an untouched value is what a reader of the failing note sees.
+ *
+ * @param {object} emitted - The `system` block, already built.
+ * @param {readonly object[]} fields - The type's field declaration.
+ * @param {import("./address.mjs").AddressVocabulary & {package?: string}}
+ *   vocabulary - The tree's vocabularies and the package the values are written
+ *   in.
+ * @returns {AddressFinding[]} Every value that could not be reduced.
+ */
+export function reduceAddressFields(emitted: object, fields: readonly object[], vocabulary?: import("./address.mjs").AddressVocabulary & {
+    package?: string;
+}): AddressFinding[];
+/**
+ * How many values a position holds.
+ *
+ * - `value` — the field's value is one Address.
+ * - `items` — every element of a list is one.
+ * - `keys` — every **key** of a map is one, and the values are untouched.
+ *
+ * @type {readonly string[]}
+ */
+export const ADDRESS_FIELD_SHAPES: readonly string[];
+/**
+ * An Address position, as a field declaration states it.
+ */
+export type AddressPosition = {
+    /**
+     * - The type an omitted `<type>` segment takes.
+     */
+    type: string;
+    /**
+     * - Every type the position accepts.
+     */
+    accepts: readonly string[];
+    /**
+     * - Where the Addresses are.
+     * Defaults to `value`.
+     */
+    holds?: "keys" | "value" | "items" | undefined;
+};
+/**
+ * What a reduction could not do, for a caller to report.
+ */
+export type AddressFinding = {
+    /**
+     * - The field, named as an author writes it.
+     */
+    key: string;
+    /**
+     * - The authored value, so the caller can locate the
+     * finding at the line carrying it rather than at the key.
+     */
+    written: string;
+    /**
+     * - One sentence, naming the fix.
+     */
+    message: string;
+};

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

@@ -0,0 +1,34 @@
+/**
+ * Render typed properties at a generated-output boundary.
+ * @param {any} value - A tuple-bearing tree.
+ * @param {WeakMap<object, object>} [seen] - Shared containers in this output.
+ * @returns {any} A serializable tree containing full Addresses.
+ */
+export function encodeAddresses(value: any, seen?: WeakMap<object, object>): any;
+/**
+ * Clone mutable note state while retaining immutable Address identities.
+ * @param {any} value - Typed note state.
+ * @returns {any} An independent mutable container tree.
+ */
+export function cloneAddressState(value: any): any;
+/** Address-keyed properties hold typed entries rather than string object keys. */
+export class AddressEntries {
+    /** @param {Array<{target: object, value: unknown, sourceKey: string}>} entries - Typed entries and diagnostic source keys. */
+    constructor(entries: Array<{
+        target: object;
+        value: unknown;
+        sourceKey: string;
+    }>);
+    entries: {
+        target: object;
+        value: unknown;
+        sourceKey: string;
+    }[];
+}
+/** An Address and the section within its document. */
+export class AddressLink {
+    /** @param {object} target - Complete tuple. @param {string} anchor - Section slug. */
+    constructor(target: object, anchor: string);
+    target: object;
+    anchor: string;
+}