@heroiclands/package-build 22.20.0 → 22.21.0

package/engine/svg-theme.mjs

@@ -45,7 +45,7 @@ const INK_LIGHT = "#211d16";
 const INK_DARK = "#ece3cf";
 
 /**
- * The shapes a theme rule may repaint.
+ * The shapes a fill rule may repaint.
  *
  * Explicitly black, or black by default for want of a `fill`. A shape painted
  * some other colour is deliberate — a white highlight in a two-tone badge — and
@@ -53,7 +53,7 @@ const INK_DARK = "#ece3cf";
  *
  * @type {string}
  */
-const SELECTOR = [
+const FILL_SELECTOR = [
     '[fill="#000"]',
     '[fill="#000000"]',
     '[fill="black"]',
@@ -67,10 +67,21 @@ const SELECTOR = [
     "g:not([fill])",
 ].join(",");
 
+/**
+ * The shapes a stroke rule may repaint.
+ *
+ * Explicitly black only — SVG's default stroke is `none`, so there is no
+ * want-of-a-`stroke` case to opt in the way a want-of-a-`fill` case is. A
+ * broad match would paint an outline onto a shape that has none.
+ *
+ * @type {string}
+ */
+const STROKE_SELECTOR = ['[stroke="#000"]', '[stroke="#000000"]', '[stroke="black"]'].join(",");
+
 /** @type {string} */
 const STYLE =
-    `<style>${SELECTOR}{fill:${INK_LIGHT}}` +
-    `@media(prefers-color-scheme:dark){${SELECTOR}{fill:${INK_DARK}}}</style>`;
+    `<style>${FILL_SELECTOR}{fill:${INK_LIGHT}}${STROKE_SELECTOR}{stroke:${INK_LIGHT}}` +
+    `@media(prefers-color-scheme:dark){${FILL_SELECTOR}{fill:${INK_DARK}}${STROKE_SELECTOR}{stroke:${INK_DARK}}}</style>`;
 
 /**
  * Every `style="…"` attribute, capturing its declarations.

package/engine/wikilinks.mjs

@@ -583,7 +583,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index, cap
  * @param {object} index - From {@link buildWikilinkIndex}.
  * @param {unknown} ref - The reference, as authored.
  * @param {object} [hint] - `{type}`, where the caller knows what it expects.
- * @returns {{name?: string, uuid?: string, address?: import("./address.mjs").AddressTuple, subType?: string}|undefined}
+ * @returns {{name?: string, uuid?: string, address?: import("./address.mjs").AddressTuple, subType?: string, standings?: object}|undefined}
  *   The target, or `undefined` where nothing answers.
  */
 export function resolveReference(index, ref, hint) {
@@ -611,6 +611,7 @@ export function resolveReference(index, ref, hint) {
         return {
             name: published.name,
             subType: published.subType,
+            ...(published.standings ? { standings: published.standings } : {}),
             ...(published.uuid ? { uuid: published.uuid } : {}),
             address: tuple,
         };
@@ -638,6 +639,7 @@ export function resolveReference(index, ref, hint) {
         return {
             name: local.name,
             subType: local.subType,
+            ...(local.standings ? { standings: local.standings } : {}),
             ...(uuid ? { uuid } : {}),
             address: tuple,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.20.0",
+    "version": "22.21.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/actors.mjs

@@ -29,16 +29,19 @@
  * `ACTOR_VAULT_TYPE = "being"` here and emitted `type: "being"` several hundred
  * lines below, which made the two vocabularies agree by coincidence.
  *
- * It was two content types — `character` and `creature` — which compiled to the
- * same `being` with no branch anywhere between them; they were retired in
- * retired, and are reported by `assertTypeNotRetired` in
- * `engine/ids.mjs`.
- *
  * Attributes (`sohl.attributes` map) become embedded attribute items with
  * `scoreBase` set from the map value. Each entry in `sohl.items` is similarly
  * resolved by `(type, shortcode)` and deep-merged with the entry's other
  * properties. `sohl.skills` is ignored.
  *
+ * **A membership is derived, never authored here.** `data.affiliations` names
+ * the bodies a being belongs to and the standing it holds in each, and each
+ * entry becomes one embedded affiliation item: the entry's `rank` is that
+ * item's `system.level` and its `office` is `system.office`. A standing is a
+ * fact about the setting rather than about one system — it does not become true
+ * because SoHL is installed — so the system block states none of it, and a
+ * sheet and a page cannot come to disagree.
+ *
  * Not a standalone script — exports the `Actors` compiler class, imported and
  * driven by `engine/generate.mjs`. Must run after the items passes, since it
  * reads their generated JSON trees.
@@ -58,6 +61,10 @@ import { SOHL_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 // verbatim, and `sohl.img` / `sohl.effects` / `sohl.flags` overriding their
 // shared top-level forms for this system alone.
 import { blockProperty, mergeSystemData } from "../engine/system-block.mjs";
+// A being's memberships and the standing it holds in each, read from the one
+// place they are authored. The rank *is* the affiliation item's `level`, so
+// there is nothing to map and nowhere for a second authoring to disagree.
+import { readStandings } from "../engine/standings.mjs";
 
 /**
  * The system this pass compiles for — the block its notes write.
@@ -256,10 +263,59 @@ export class Actors extends SystemActorCompiler {
             });
         }
 
+        for (const embedded of this.buildMemberships(itemsMap, actorId, fm, ctx)) {
+            items.push(embedded);
+        }
+
         this.openUnopenedSkills(items, ctx);
         return items;
     }
 
+    /**
+     * One embedded affiliation item per body the being belongs to.
+     *
+     * The body's own compiled item is the model, so a membership carries
+     * whatever that body declares — its subtype, its common skills, its
+     * standings toward others — and the being adds only what is true of *this*
+     * membership: the rung it stands on and the post it holds.
+     *
+     * A being naming a body that compiles to no item is a finding rather than a
+     * silently dropped membership: the note says the being belongs somewhere,
+     * and a sheet that shows nothing says it does not.
+     *
+     * @param {Map<string, object>} itemsMap - The predefined-item catalogue.
+     * @param {string} actorId - The owning actor's id.
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} ctx - Diagnostic context.
+     * @returns {object[]} The embedded items, in the order the note names them.
+     */
+    buildMemberships(itemsMap, actorId, fm, ctx) {
+        const { entries } = readStandings(fm?.data?.affiliations);
+        const items = [];
+        for (const { body, standing } of entries) {
+            const shortcode = body?.shortcode;
+            if (!shortcode) continue;
+            const level = Number(standing?.rank);
+            const office = typeof standing?.office === "string" ? standing.office.trim() : "";
+            const system = {
+                ...(Number.isFinite(level) ? { level } : {}),
+                ...(office ? { office } : {}),
+            };
+            const embedded = this.resolveEmbedded(
+                itemsMap,
+                actorId,
+                "affiliation",
+                shortcode,
+                Object.keys(system).length ? { system } : {},
+                `affiliations:${shortcode}`,
+                ctx,
+                { fmKey: "affiliations", modelPackage: body.package ?? null },
+            );
+            if (embedded) items.push(embedded);
+        }
+        return items;
+    }
+
     /**
      * Bake each unopened skill's opening mastery level into the document.
      *

package/types/engine/note-vocabulary.d.mts

@@ -296,15 +296,29 @@ export type DataFieldSpec = {
      * value — which is the honest answer wherever the specification's stated
      * shape and the shape notes are authored in today disagree.
      */
-    kind?: "string" | "number" | "boolean" | "map" | "address" | "list" | "shortcode" | "scalar-or-map" | undefined;
+    kind?: "string" | "number" | "boolean" | "map" | "address" | "list" | "shortcode" | "list-or-map" | "scalar-or-map" | undefined;
     /**
      * - Type of each list or pack-map value.
      */
     entryKind?: "address" | "shortcode" | undefined;
     /**
-     * - Type of each map key.
+     * - Type of each map key. On a
+     * `list-or-map` field it describes the map form alone, and `entryKind` the
+     * list form alone: reading both of one value would check a map's entries as
+     * if they were its keys.
      */
     keyKind?: "address" | "shortcode" | undefined;
+    /**
+     * - The map's entries are standings held in the
+     * body each is keyed by, so a row names the two together — see
+     * {@link module :engine/standings}.
+     */
+    standings?: boolean | undefined;
+    /**
+     * - The map names posts, each with a description,
+     * so each takes a row labelled and anchored by the post's own name.
+     */
+    roster?: boolean | undefined;
     /**
      * - An alternative `subType:<skill-subtype>` key.
      */

package/types/engine/standing-terms.d.mts

@@ -0,0 +1,16 @@
+/**
+ * The note type a standing is held in.
+ *
+ * A standing is always held in a body: the entry is keyed by that body's
+ * Address, which is what lets the rung and the post be checked against what
+ * the body itself declares.
+ */
+export const STANDING_BODY_TYPES: readonly string[];
+/**
+ * The two keys one standing carries.
+ *
+ * `rank` is the level on the body's own `governance.ranks` ladder, as a number.
+ * `office` is a key of its `governance.offices` map, as a string. Both are
+ * optional — a membership with neither is the ordinary shape.
+ */
+export const STANDING_KEYS: readonly string[];

package/types/engine/standings.d.mts

@@ -0,0 +1,129 @@
+/**
+ * The standings a being authored, in one shape whichever shape it wrote.
+ *
+ * The list form names bodies and no standings; the map form names both. Three
+ * spellings reach here and every reader downstream takes the same entries, so
+ * none of them asks which it was handed:
+ *
+ * - an **{@link AddressEntries}** — the map after the note boundary decoded its
+ *   keys into typed Addresses, which is the shape every compile sees;
+ * - a **plain map**, which is the shape a checker reading raw YAML sees;
+ * - a **list**, which names bodies and says nothing about standing in them.
+ *
+ * An emptied map arrives from the property editor as `[]` and means what `{}`
+ * means — this being authors no membership — so both read as no entries.
+ *
+ * Each entry carries `body` for a message and `sourceKey` for a position: the
+ * authored key is what a reader has to find in the file, and the decoded
+ * Address is what a finding should name.
+ *
+ * @param {unknown} value - The authored `data.affiliations`.
+ * @returns {{form: "absent"|"list"|"map"|"malformed",
+ *   entries: Array<{body: unknown, sourceKey: string|number, standing: unknown}>}}
+ *   The form it was written in, and its entries.
+ */
+export function readStandings(value: unknown): {
+    form: "absent" | "list" | "map" | "malformed";
+    entries: Array<{
+        body: unknown;
+        sourceKey: string | number;
+        standing: unknown;
+    }>;
+};
+/**
+ * The rungs an affiliation's ladder declares, as level → title.
+ *
+ * A rung states its own `level`, so the ladder is read by that number rather
+ * than by its position in the list: a body may write its rungs in any order,
+ * and several start at zero.
+ *
+ * @param {unknown} ranks - An affiliation's `data.governance.ranks`.
+ * @returns {Map<number, string>} Level → the title that level is called.
+ */
+export function rankLadder(ranks: unknown): Map<number, string>;
+/**
+ * The offices an affiliation names, as key → description.
+ *
+ * An office is authored either as a bare description or as a `{description,
+ * holders}` map, and a reader of the post's name wants the same string from
+ * both.
+ *
+ * @param {unknown} offices - An affiliation's `data.governance.offices`.
+ * @returns {Map<string, string>} Office key → its description.
+ */
+export function officeRoster(offices: unknown): Map<string, string>;
+/**
+ * The anchor an office's row is addressed by.
+ *
+ * Declared once, because the row that carries the anchor and the link that
+ * reaches it are drawn by different passes: two spellings of the same
+ * derivation is a link into a page that offers no such destination.
+ *
+ * An office whose name reduces to nothing URL-safe has no anchor, and the
+ * caller is the one that can say what to do without one.
+ *
+ * @param {string} office - The office's key, as the body wrote it.
+ * @returns {string} The anchor, or `""` where the name carries nothing.
+ */
+export function officeAnchor(office: string): string;
+/**
+ * What an affiliation lends to a reference to it.
+ *
+ * A reference's value answers what was found as well as where it is — the same
+ * reason a target's `subType` travels with it. A standing is read on the
+ * *being*, and what it is called is declared on the *body*, so the ladder and
+ * the office roster ride along to the one place that needs them.
+ *
+ * Nothing rides for a note that declares neither.
+ *
+ * @param {object} fm - The affiliation note's frontmatter.
+ * @returns {{ranks?: Record<string, string>, offices?: Record<string, string>}|undefined}
+ *   What a reference carries, or nothing.
+ */
+export function standingsDigest(fm: object): {
+    ranks?: Record<string, string>;
+    offices?: Record<string, string>;
+} | undefined;
+/**
+ * How a standing reads beside the body that confers it.
+ *
+ * The office leads, because it is the more particular of the two: a reader
+ * meeting "War Chief" has been told the rung as well. The body closes the
+ * phrase, which is the whole point of keying the entry by it — a standing with
+ * no body named is the lossy form.
+ *
+ * No article is supplied. One body's name reads with a "the" in front of it and
+ * the next does not, and inventing one is this build editing the corpus.
+ *
+ * @param {object} standing - `{rank, office}`, either or both absent.
+ * @param {string} body - What the body is called.
+ * @param {{ranks?: Record<string, string>}} [digest] - The body's ladder.
+ * @returns {string} The phrase, or the body's name where no standing is held.
+ */
+export function standingPhrase(standing: object, body: string, digest?: {
+    ranks?: Record<string, string>;
+}): string;
+/**
+ * Validate a being's memberships and the standing it holds in each.
+ *
+ * Four questions, and the last two are what keying the entry by its body buys:
+ *
+ * 1. the value is a map keyed by Address (or the list this window still takes);
+ * 2. every key names an affiliation that resolves, once;
+ * 3. a `rank` is a level the named body's `governance.ranks` declares;
+ * 4. an `office` is a key of that body's `governance.offices`.
+ *
+ * Both of the last two are read from the named body's own frontmatter as the
+ * lint runs, so a renamed rung or a renamed post fails on every being pointing
+ * at it rather than on a list somebody has to remember to edit.
+ *
+ * @param {object} note - The note.
+ * @param {{index?: object}} [options] - The lint's options.
+ * @returns {object[]} Located findings.
+ */
+export function checkStandings(note: object, { index }?: {
+    index?: object;
+}): object[];
+import { STANDING_BODY_TYPES } from "./standing-terms.mjs";
+import { STANDING_KEYS } from "./standing-terms.mjs";
+export { STANDING_BODY_TYPES, STANDING_KEYS };

package/types/engine/wikilinks.d.mts

@@ -133,7 +133,7 @@ export function convertWikilinks(markdown: string, { type, id, pack, docPack, in
  * @param {object} index - From {@link buildWikilinkIndex}.
  * @param {unknown} ref - The reference, as authored.
  * @param {object} [hint] - `{type}`, where the caller knows what it expects.
- * @returns {{name?: string, uuid?: string, address?: import("./address.mjs").AddressTuple, subType?: string}|undefined}
+ * @returns {{name?: string, uuid?: string, address?: import("./address.mjs").AddressTuple, subType?: string, standings?: object}|undefined}
  *   The target, or `undefined` where nothing answers.
  */
 export function resolveReference(index: object, ref: unknown, hint?: object): {
@@ -141,6 +141,7 @@ export function resolveReference(index: object, ref: unknown, hint?: object): {
     uuid?: string;
     address?: import("./address.mjs").AddressTuple;
     subType?: string;
+    standings?: object;
 } | undefined;
 import { ITEM_PACK } from "./ids.mjs";
 import { PACK_BY_TYPE } from "./ids.mjs";

package/types/sohl/actors.d.mts

@@ -21,6 +21,25 @@ export class Actors extends SystemActorCompiler {
      * entry plus one per `sohl.items` entry. `sohl.skills` is ignored.
      */
     buildEmbeddedItems(itemsMap: any, actorId: any, fm: any, ctx: any): object[];
+    /**
+     * One embedded affiliation item per body the being belongs to.
+     *
+     * The body's own compiled item is the model, so a membership carries
+     * whatever that body declares — its subtype, its common skills, its
+     * standings toward others — and the being adds only what is true of *this*
+     * membership: the rung it stands on and the post it holds.
+     *
+     * A being naming a body that compiles to no item is a finding rather than a
+     * silently dropped membership: the note says the being belongs somewhere,
+     * and a sheet that shows nothing says it does not.
+     *
+     * @param {Map<string, object>} itemsMap - The predefined-item catalogue.
+     * @param {string} actorId - The owning actor's id.
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} ctx - Diagnostic context.
+     * @returns {object[]} The embedded items, in the order the note names them.
+     */
+    buildMemberships(itemsMap: Map<string, object>, actorId: string, fm: object, ctx: string): object[];
     /**
      * Bake each unopened skill's opening mastery level into the document.
      *