@heroiclands/package-build 22.19.0 → 22.21.0

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

@@ -244,6 +244,24 @@ export const DECLARED_TAGS: Readonly<{
         tags: readonly string[];
     }>;
 }>;
+/** The case-sensitive archetypes and their author-facing meanings. */
+export const BEING_ARCHETYPES: Readonly<{
+    warrior: "Can hold a line and win a fight.";
+    skirmisher: "Fights light — ambush, missile, mobility.";
+    infiltrator: "Gets in unseen — locks, stealth, disguise.";
+    mage: "Commands arcane practice.";
+    cleric: "Commands religious practice and standing.";
+    healer: "Treats wounds and illness.";
+    scholar: "Reads, researches, and knows things.";
+    courtier: "Navigates rank, negotiation, and intrigue.";
+    woodsman: "Travels and survives wild country.";
+    mariner: "Handles boats and blue water.";
+    artisan: "Builds, repairs, and appraises craft work.";
+    trader: "Moves goods, values them, and knows markets.";
+    commoner: "Fits no more specific archetype; handles ordinary work and daily life.";
+    entertainer: "Performs for an audience through acting, music, comedy, or similar arts.";
+    guildsperson: "Has professional training, standing, or connections that open doors.";
+}>;
 /**
  * Every note type this toolchain compiles, and the closed vocabulary it
  * declares.
@@ -278,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/retired-fields.d.mts

@@ -49,10 +49,8 @@ export function assertNoDraftField(fm: object | null | undefined, { file, absPat
  * unambiguous folded in every note's `name.full` and so dictated what a note
  * could be named. The form is retired, so the list has no reader.
  *
- * **`name.aliases` is a different field and is not retired.** It fed the same
- * index, but unlike the top-level list it is being kept — reserved, unread,
- * and deliberately unmentioned by this message, which would otherwise tell an
- * author to delete a field they are allowed to write. See
+ * **`name.aliases` is a different field.** It lists alternate names in the
+ * infobox and is deliberately unmentioned by this message. See
  * {@link assertNoAliasesField}.
  *
  * @param {string} [file] - The note's path, named in the message. Omit it where
@@ -68,13 +66,9 @@ export function aliasesRetiredMessage(file?: string): string;
  * it reads as "this note claims no other names", a statement about a namespace
  * that no longer exists.
  *
- * **The nested `name.aliases` is deliberately not refused.** Both spellings fed
- * the retired alias index, and both lost their reader with it, but only the
- * top-level one is retired: `name.aliases` is **reserved**, held for a use that
- * does not exist yet. So it is neither refused nor read — no index consults it,
- * no rule validates its contents, nothing derives from it, and nothing emits
- * it. It rides in the note as inert data, and a note carrying one compiles,
- * resolves and emits exactly as if it were absent.
+ * **The nested `name.aliases` is deliberately not refused.** It is the note's
+ * ordered alternate names and appears in the note infobox. It does not create
+ * addresses or change how authored links resolve.
  *
  * That distinction is the reason this checks `Object.hasOwn(fm, "aliases")`
  * rather than resolving a dotted key: the top-level field is the whole subject,

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.
      *