@heroiclands/package-build 22.20.0 → 22.22.0

package/engine/note-vocabulary.mjs

@@ -12,30 +12,32 @@
  */
 
 /**
- * The **closed** half of a note's frontmatter: the `data:` container, and the
- * `subType` each note type declares.
- *
- * A note's frontmatter has three regions, and only one of them is open. The
- * **top level** describes the note as a published artefact, every key of it is
- * copied into the generated web page, and an unrecognised key there is a Hugo
- * or theme parameter this build has no standing to refuse. The **system
- * blocks** describe the subject as one system's documents. Between them sits
- * `data:` — the type-specific facts about the subject itself, system-agnostic,
- * and closed.
- *
- * Closed is the whole point. Those facts previously sat at the top level, where
- * the pass-through rule applied to them too, so a misspelled `wieght` became a
- * theme parameter rather than a finding — indistinguishable, from the outside,
- * from a weapon that simply weighs nothing. Under `data:` the same misspelling
- * is an error naming the note and the key it was probably meant to be.
- *
- * **`subType` rides along, and stays at the top level.** It is not a `data:`
- * key: a note's `(type, subType)` is what each system's map reads to derive a
- * document type, so it describes the note rather than the subject. But it is
- * the other per-type vocabulary the format closes, it is enumerated in the same
- * `### type:` section of the specification that enumerates the `data:` keys,
- * and keeping the two together means one entry per type rather than two
- * registries free to disagree about which types exist.
+ * The **closed vocabularies** of a note's frontmatter: the top-level keys, the
+ * `data:` container, and the `subType` each note type declares.
+ *
+ * A note's frontmatter has three regions and every one of them is closed. The
+ * **top level** describes the note as a published artefact and is a fixed list
+ * — {@link NOTE_TOP_LEVEL_FIELDS} — so a key it does not name is a finding at
+ * its own line rather than a value copied into the generated page. The
+ * **system blocks** describe the subject as one system's documents, and are
+ * checked against the published schema. Between them sits `data:` — the
+ * type-specific facts about the subject itself, system-agnostic.
+ *
+ * Closed is the whole point, and the failure it answers is a misspelling. A
+ * region that passes an unrecognised key through cannot tell `wieght` from a
+ * weapon that weighs nothing: the note says one thing, the build does another,
+ * and nothing says so. Under a closed vocabulary the same misspelling is an
+ * error naming the note and the key it was probably meant to be.
+ *
+ * **`subType` is a top-level key with a per-type vocabulary**, which is why it
+ * is declared twice over: once in {@link NOTE_TOP_LEVEL_FIELDS} as a key the
+ * region accepts, and once per type below as the closed set of values that type
+ * takes. It is not a `data:` key — a note's `(type, subType)` is what each
+ * system's map reads to derive a document type, so it describes the note rather
+ * than the subject — but its values are enumerated in the same `### type:`
+ * section of the specification that enumerates the `data:` keys, and keeping
+ * the two together means one entry per type rather than two registries free to
+ * disagree about which types exist.
  *
  * **This is note-format knowledge, so it lives in `engine/`.** `data:` holds
  * what is true of the *thing* — a weapon's weight, an affliction's
@@ -79,6 +81,9 @@
 // is how a disagreement between the three arises.
 import { ART_SLOTS } from "./art-slots.mjs";
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
+// The system registry, so the top-level block keys below are the systems this
+// toolchain recognises rather than a second list of them.
+import { SYSTEM_IDS } from "./systems.mjs";
 // The retirement window for a renamed type, read rather than restated: a
 // vocabulary that answered only to the current spelling would report every key
 // of an unswept note as unknown.
@@ -97,7 +102,10 @@ import {
 // question, asked the way `checkPlace` and `checkCalendarNote` are.
 import { checkBeingAge } from "./being-age.mjs";
 import { checkSocialTies } from "./social-ties.mjs";
+import { checkStandings } from "./standings.mjs";
+import { STANDING_BODY_TYPES } from "./standing-terms.mjs";
 import { checkDatedOffices } from "./office-holders.mjs";
+import { checkRankLadder } from "./rank-ladder.mjs";
 import { checkCalendarChoice } from "./calendar-choice.mjs";
 import { checkCultureChoice } from "./culture-choice.mjs";
 import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
@@ -128,12 +136,20 @@ import { positionOfFrontmatterPath } from "./diagnostics.mjs";
  * @typedef {object} DataFieldSpec
  * @property {string} name - The key under `data:`, dotted for a nested one
  *   (`charges.value`).
- * @property {"string"|"number"|"boolean"|"list"|"map"|"scalar-or-map"|"address"|"shortcode"} [kind] -
+ * @property {"string"|"number"|"boolean"|"list"|"map"|"list-or-map"|"scalar-or-map"|"address"|"shortcode"} [kind] -
  *   The value's shape, for the lint. Absent means no claim is made about the
  *   value — which is the honest answer wherever the specification's stated
  *   shape and the shape notes are authored in today disagree.
  * @property {"address"|"shortcode"} [entryKind] - Type of each list or pack-map value.
- * @property {"address"|"shortcode"} [keyKind] - Type of each map key.
+ * @property {"address"|"shortcode"} [keyKind] - 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.
+ * @property {boolean} [standings] - 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}.
+ * @property {boolean} [roster] - The map names posts, each with a description,
+ *   so each takes a row labelled and anchored by the post's own name.
  * @property {"subType"} [keySelector] - An alternative `subType:<skill-subtype>` key.
  * @property {readonly string[]} [accepts] - Allowed Address types, separate from `ref`.
  * @property {string} [shape] - Human-readable shape, for a finding and for
@@ -208,12 +224,45 @@ const TEXT = Object.freeze({ shape: "string", kind: "string" });
 /** A list. */
 const LIST = Object.freeze({ shape: "list", kind: "list" });
 
+/**
+ * One value, or several.
+ *
+ * The two are the same fact at different lengths rather than two different
+ * facts, so a single value means a list of one and a consumer reads one shape.
+ * That is what separates this from `list-or-map`, whose halves say different
+ * things.
+ */
+const TEXT_OR_LIST = Object.freeze({ shape: "string or list", kind: "string-or-list" });
+
 /** A single Address. */
 const LINK = Object.freeze({ shape: "an Address", kind: "address" });
 
 /** A list of Addresses. */
 const LINKS = Object.freeze({ shape: "list of Addresses", kind: "list", entryKind: "address" });
 
+/**
+ * A being's memberships, and the standing it holds in each.
+ *
+ * A map keyed by the body's Address, whose entry is that membership's `rank`
+ * and `office` — the pair a flat list of bodies cannot state, because it has
+ * nowhere to say which body a standing is held in.
+ *
+ * **`list-or-map` is the sweep's shape**, and it says which half each
+ * declaration describes: `entryKind` the list's entries, `keyKind` the map's
+ * keys. A tree still writing the list form keeps the check it had, and the map
+ * form earns the two the body can answer — see {@link module:engine/standings}.
+ */
+const STANDINGS = Object.freeze({
+    shape: "a standing map keyed by Address, or a list of Addresses",
+    kind: "list-or-map",
+    entryKind: "address",
+    keyKind: "address",
+    standings: true,
+    ref: "affiliation",
+    accepts: STANDING_BODY_TYPES,
+    check: checkStandings,
+});
+
 /**
  * A single Address, or one per pack.
  *
@@ -270,6 +319,101 @@ const TOKEN_ICON = Object.freeze({
     describe: "What a token on the canvas wears — an `icon` address; unset, it follows `icon`.",
 });
 
+/**
+ * One top-level frontmatter key.
+ *
+ * Narrower than a {@link DataFieldSpec}: the top level is a fixed list rather
+ * than a per-type vocabulary, nothing there is keyed by pack or resolved as an
+ * Address, and the value's shape is checked by whatever owns the region the key
+ * opens — `name`, `tags` and each system block each have their own check.
+ *
+ * @typedef {object} TopLevelFieldSpec
+ * @property {string} name - The key, as a note writes it.
+ * @property {boolean} [system] - The key opens a game system's block, so it is
+ *   one of {@link module:engine/systems.SYSTEM_IDS} rather than a fixed key.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+
+/**
+ * **The top-level vocabulary**, in the order a formatted note writes it.
+ *
+ * The region describes the note as a published artefact: what it is called,
+ * what kind of thing it is about, how it is classified, and which of the other
+ * two regions it opens. Everything else a note states is a fact about the
+ * subject, which belongs under `data:`, or a fact about one system's document,
+ * which belongs inside that system's block.
+ *
+ * **Closed, like the other two regions.** A key this list does not name is a
+ * finding at its own line, because a region that passed one through would turn
+ * a misspelling into a value nothing reads — `title` beside `name`, or `pack`
+ * where `data.pack` was meant.
+ *
+ * **The system blocks are derived from the system registry**, so recognising a
+ * further system is a change to {@link module:engine/systems.SYSTEM_IDS} and to
+ * nothing else. They sort by name after the fixed keys: a block is the largest
+ * thing a note writes, every one of them belongs at the end, and a rule a
+ * reader can restate in one sentence is worth more than a hand-kept order.
+ *
+ * Five readers derive from this one list — the frontmatter lint's accepted set,
+ * the message it prints, the formatter's key order, the content-format check,
+ * and the author-facing reference — so none of them can fall behind the others.
+ *
+ * @type {readonly TopLevelFieldSpec[]}
+ */
+export const NOTE_TOP_LEVEL_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "shortcode",
+        describe: "The note's own address segment, unique within its type.",
+    }),
+    Object.freeze({
+        name: "name",
+        describe: "The display names — a required `full`, and any `aliases`.",
+    }),
+    Object.freeze({
+        name: "type",
+        describe: "What the note is about, which decides its vocabulary and its document.",
+    }),
+    Object.freeze({
+        name: "subType",
+        describe: "The type's own genre, where it declares one.",
+    }),
+    Object.freeze({
+        name: "description",
+        describe: "The short page summary.",
+    }),
+    Object.freeze({
+        name: "tags",
+        describe: "Draft state, GM routing, and the descriptive labels a page list reads.",
+    }),
+    Object.freeze({
+        name: "data",
+        describe: "The facts about the subject itself, shared by every system.",
+    }),
+    ...[...SYSTEM_IDS].sort().map((system) =>
+        Object.freeze({
+            name: system,
+            system: true,
+            describe:
+                `What the \`${system}\` system makes of the subject — its ` +
+                `document's mechanics, routing and art.`,
+        }),
+    ),
+]);
+
+/**
+ * The top-level keys, in formatted order.
+ *
+ * @type {readonly string[]}
+ */
+export const NOTE_TOP_LEVEL_KEYS = Object.freeze(NOTE_TOP_LEVEL_FIELDS.map((field) => field.name));
+
+/**
+ * Membership test for the top-level vocabulary.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const NOTE_TOP_LEVEL_KEY_SET = Object.freeze(new Set(NOTE_TOP_LEVEL_KEYS));
+
 /**
  * The `data:` keys **every** note type accepts, whatever it is.
  *
@@ -415,7 +559,7 @@ function checkPlacePurpose(note) {
             },
         ];
     if (hasTag(note.fm, value)) return [];
-    const tags = note.fm?.tags ?? note.fm?.tag;
+    const tags = note.fm?.tags;
     return [
         {
             ...at(),
@@ -449,15 +593,17 @@ export const GM_TAG = "gm";
 /**
  * The tags that **classify** a note, grouped by what they classify.
  *
- * `tags:` lives at the open top level and most tags belong there: a theme, a
- * region, a working state is the author's own and this build has no opinion
- * about it. A classifying tag is different, because something queries it — a
+ * `tags:` holds an open vocabulary of *values*, and most tags belong there: a
+ * theme, a region, a working state is the author's own and this build has no
+ * opinion about it. A classifying tag is different, because something queries
+ * it — a
  * settlement tagged `village` appears in the list of villages and an untagged
  * one does not, so `vilage` does not merely look wrong, it removes the note from
  * an index while the index still renders a table that looks complete.
  *
  * **This list is not a closed set.** An unrecognised tag is legal, because the
- * region is open; what is reported is a **near miss** — a tag close enough to a
+ * values are the author's; what is reported is a **near miss** — a tag close
+ * enough to a
  * declared one to be a typo of it.
  *
  * **Each group names the types it applies to**, and that scope is what makes the
@@ -629,14 +775,12 @@ export function exclusiveTagGroups(type, groups = DECLARED_TAGS) {
  * The spelling of the tag *itself* still is — a near miss is a near miss, and
  * the frontmatter lint is what reports it; nothing here guesses.
  *
- * Reads `tags` and the singular `tag` spelling.
- *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} tag - The tag to look for, in its declared spelling.
  * @returns {boolean} Whether the note carries it.
  */
 export function hasTag(fm, tag) {
-    const raw = fm?.tags ?? fm?.tag;
+    const raw = fm?.tags;
     if (raw == null) return false;
     const wanted = String(tag).toLowerCase();
     for (const entry of Array.isArray(raw) ? raw : [raw]) {
@@ -725,7 +869,8 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ref: "lore",
                 accepts: ["lore"],
                 describe:
-                    "Lore concerning this being, such as the standing it holds or the law it lives under.",
+                    "Lore concerning this being — the law it lives under, the customs it is " +
+                    "subject to, the traditions it was raised in.",
             },
             {
                 name: "culture",
@@ -744,10 +889,11 @@ export const NOTE_VOCABULARY = Object.freeze({
             },
             {
                 name: "affiliations",
-                ...LINKS,
-                ref: "affiliation",
-                accepts: ["affiliation"],
-                describe: "Affiliations the being belongs to — traditions, polities, and the rest.",
+                ...STANDINGS,
+                describe:
+                    "Bodies the being belongs to, keyed by Address, each entry holding the " +
+                    "standing it holds there — `rank`, required, a level on that body's own " +
+                    "ladder, and `office`, optional, a post that body names.",
             },
             {
                 name: "socialTies",
@@ -759,7 +905,14 @@ export const NOTE_VOCABULARY = Object.freeze({
                 check: checkSocialTies,
                 describe: `Defining ties directed from this being to others: ${SOCIAL_TIES.map(({ term, meaning }) => `\`${term}\` (${meaning})`).join("; ")}`,
             },
-            { name: "gender", ...TEXT, describe: "`male`, `female` or `other`." },
+            {
+                name: "gender",
+                ...TEXT,
+                describe:
+                    "One of `male`, `female`, `nonbinary`, `none` or `other`. " +
+                    "`none` says the being has no gender; an absent field says its " +
+                    "gender is unrecorded.",
+            },
             {
                 name: "species",
                 ...LINK,
@@ -827,12 +980,19 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "frame",
                 ...TEXT,
-                describe: "Relative frame — `scant`, `light`, `medium`, `large` or `massive`.",
+                describe:
+                    "Relative frame — one of `scant`, `light`, `medium`, `heavy` or `massive`.",
             },
             { name: "appearance.eye_color", ...TEXT, describe: "Eye colour." },
             { name: "appearance.hair_color", ...TEXT, describe: "Hair colour." },
             { name: "appearance.skin_color", ...TEXT, describe: "Skin colour." },
-            { name: "appearance.complexion", ...TEXT, describe: "Complexion." },
+            {
+                name: "appearance.complexion",
+                ...TEXT_OR_LIST,
+                describe:
+                    "The skin's condition — one value, or several, because a face " +
+                    "carries more than one at once. A single value means a list of one.",
+            },
             {
                 name: "appearance.extra_features",
                 ...LIST,
@@ -896,11 +1056,25 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "governance.ranks",
                 ...LIST,
+                // A rung is `{level, title, description}` with an optional
+                // `lore`. The shape check sees a list and stops there, so the
+                // rungs inside it are checked here — a ladder is what a being's
+                // `rank` indexes into, and an incomplete rung resolves to a
+                // standing with no name.
+                check: checkRankLadder,
+                // Each rung takes a row of its own, labelled and anchored by
+                // its title, ordered by level — the ladder's parallel to
+                // `governance.offices`' `roster`.
+                ranks: true,
                 describe: "The ladder of ranks the body confers — level, title, description.",
             },
             {
                 name: "governance.offices",
                 ...ANY,
+                // A map of named posts: each takes a row of its own, labelled
+                // by the post and anchored by it, so the description a body
+                // declares is a destination a being's `office` can link to.
+                roster: true,
                 check: checkDatedOffices,
                 describe: "Named offices, each with a description and optional dated holders.",
             },