@heroiclands/package-build 23.3.0 → 23.3.1

package/engine/literature-notes.mjs

@@ -13,13 +13,17 @@
 
 /**
  * A work a people tells, sings or writes: the `literature` lore subType and the
- * three optional facts only such a note may state about itself. Whose work it
- * is, `data.culture`, is a field every lore note but a culture note may state,
+ * optional facts only such a note may state about itself. Whose work it is,
+ * `data.culture`, is a field every lore note but a culture note may state,
  * declared in `culture-choice.mjs`.
  *
+ * `data.language` is shared with the `culture` subType: a work names the
+ * tongue it is composed in, and a culture names the tongue its people speak,
+ * whose name lists `package-build npc new` draws from.
+ *
  * `DataFieldSpec` declares the keys a type accepts, not the subType that may
- * write them, so {@link checkLiteratureNote} scopes these keys to `literature`
- * the way the calendar check scopes its own to `calendar`.
+ * write them, so {@link checkLiteratureNote} scopes these keys to the subTypes
+ * that mean them, the way the calendar check scopes its own to `calendar`.
  *
  * @module
  */
@@ -30,6 +34,9 @@ import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 /** The `lore` subType whose notes are works of literature. */
 export const LITERATURE_SUBTYPE = "literature";
 
+/** The `lore` subTypes that may name a language. */
+export const LANGUAGE_SUBTYPES = Object.freeze([LITERATURE_SUBTYPE, "culture"]);
+
 /**
  * Require `data.language` to address a `skill` note whose subType is
  * `language`.
@@ -67,7 +74,27 @@ export function checkLanguageChoice(note, { index } = {}) {
 }
 
 /**
- * The fields only a `literature` note may state. Every one is optional.
+ * `data.language`: the tongue a work is composed in, or the tongue a culture's
+ * people speak. Optional on both.
+ *
+ * @type {object}
+ */
+export const LANGUAGE_FIELD = Object.freeze({
+    name: "language",
+    shape: "an Address",
+    kind: "address",
+    ref: "skill",
+    accepts: Object.freeze(["skill"]),
+    check: checkLanguageChoice,
+    describe:
+        "The tongue the work is composed in, or on a culture note the tongue its people " +
+        "speak, as a language skill note. `package-build npc new` draws a culture's names " +
+        "from its language's `data.names`. A `literature` or `culture` note only.",
+});
+
+/**
+ * The fields only a `literature` note may state, beside the shared
+ * {@link LANGUAGE_FIELD}. Every one is optional.
  *
  * @type {ReadonlyArray<object>}
  */
@@ -90,39 +117,47 @@ export const LITERATURE_FIELDS = Object.freeze([
             "The beings, places, gods and other notes the work concerns, and each " +
             "event it concerns, named as `place-ironfells#sack`.",
     },
-    {
-        name: "language",
-        shape: "an Address",
-        kind: "address",
-        ref: "skill",
-        accepts: ["skill"],
-        check: checkLanguageChoice,
-        describe: "The tongue the work is composed in, as a language skill note.",
-    },
 ]);
 
 const LITERATURE_KEYS = Object.freeze(LITERATURE_FIELDS.map((field) => field.name));
 
 /**
- * Refuse a literature field on a lore note of any other subType.
+ * Refuse a literature field on a lore note of any other subType, and
+ * `data.language` on a lore note that is neither a work nor a culture.
  *
  * @param {object} note
- * @returns {object[]} One error per literature key written off `literature`.
+ * @returns {object[]} One error per key written off the subTypes that take it.
  */
 export function checkLiteratureNote(note) {
     const type = String(note?.type ?? note?.fm?.type ?? "").toLowerCase();
     const subType = String(note?.fm?.subType ?? "").toLowerCase();
-    if (type !== "lore" || subType === LITERATURE_SUBTYPE) return [];
+    if (type !== "lore") return [];
     const data = note?.fm?.data;
     if (!data || typeof data !== "object" || Array.isArray(data)) return [];
-    return LITERATURE_KEYS.filter((key) => data[key] !== undefined && data[key] !== null).map(
-        (key) => ({
-            file: note.file,
-            ...positionOfFrontmatterPath(note.raw ?? "", ["data", key], { key: true }),
-            severity: "error",
-            message:
-                `\`data.${key}\` describes a work of literature, and this note's ` +
-                `\`subType\` is not \`literature\``,
-        }),
-    );
+    const stated = (key) => data[key] !== undefined && data[key] !== null;
+    const finding = (key, message) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(note.raw ?? "", ["data", key], { key: true }),
+        severity: "error",
+        message,
+    });
+    const findings = [];
+    if (subType !== LITERATURE_SUBTYPE)
+        for (const key of LITERATURE_KEYS.filter(stated))
+            findings.push(
+                finding(
+                    key,
+                    `\`data.${key}\` describes a work of literature, and this note's ` +
+                        `\`subType\` is not \`literature\``,
+                ),
+            );
+    if (!LANGUAGE_SUBTYPES.includes(subType) && stated(LANGUAGE_FIELD.name))
+        findings.push(
+            finding(
+                LANGUAGE_FIELD.name,
+                "`data.language` names the tongue of a work of literature or of a culture, " +
+                    "and this note's `subType` is neither `literature` nor `culture`",
+            ),
+        );
+    return findings;
 }

package/engine/note-vocabulary.mjs

@@ -111,7 +111,13 @@ import { checkNoteEvents } from "./note-events.mjs";
 import { AFFILIATION_STANDINGS } from "../sohl/affiliation-standings.mjs";
 import { EVENT_ENTRY } from "./note-event-terms.mjs";
 import { CULTURE_FIELD, checkCultureSubType } from "./culture-choice.mjs";
-import { LITERATURE_FIELDS, checkLiteratureNote } from "./literature-notes.mjs";
+import {
+    checkAppearanceProfile,
+    profileLookKeys,
+    requiredHeightGenders,
+} from "./appearance-profile.mjs";
+import { LANGUAGE_FIELD, LITERATURE_FIELDS, checkLiteratureNote } from "./literature-notes.mjs";
+import { checkLanguageNames, requiredGivenGenders } from "./language-names.mjs";
 import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
@@ -429,6 +435,155 @@ function lookField(name, what) {
     };
 }
 
+/**
+ * A culture's `data.appearanceProfile`: weighted words for each being-look
+ * field but `gender`, and height ranges keyed by gender. Its keys and the words
+ * each takes are read from {@link BEING_LOOK_VOCABULARY}; what a profile means
+ * and how `package-build npc new` draws from it is in `appearance-profile.mjs`.
+ *
+ * @type {DataFieldSpec}
+ */
+const APPEARANCE_PROFILE_FIELD = Object.freeze({
+    name: "appearanceProfile",
+    kind: "map",
+    shape: "an appearance profile",
+    check: (note) => checkAppearanceProfile(note, BEING_LOOK_VOCABULARY),
+    describe:
+        "What this culture's people look like, for `package-build npc new`: " +
+        `${wordList(profileLookKeys(BEING_LOOK_VOCABULARY)).replace(/ or (?!.* or )/, " and ")} ` +
+        "each map words of that field's vocabulary to positive weights, and `height` maps a " +
+        "gender to a `{min, max}` range, " +
+        `${wordList([...requiredHeightGenders()]).replace(" or ", " and ")} required. A culture ` +
+        "note only. See [appearance profiles](format-details.md#appearance-profiles).",
+    fields: Object.freeze([
+        ...profileLookKeys(BEING_LOOK_VOCABULARY).map((key) =>
+            Object.freeze({
+                name: key,
+                kind: "map",
+                shape: "a map of words to weights",
+                required: true,
+                describe: `Weighted \`${key}\` words; a word left out is never drawn.`,
+                values: Object.freeze({
+                    kind: "number",
+                    shape: "a positive weight",
+                    describe: "The word's weight against the others in its map.",
+                }),
+            }),
+        ),
+        Object.freeze({
+            name: "height",
+            kind: "map",
+            shape: "a map of genders to height ranges",
+            required: true,
+            describe:
+                "Height ranges keyed by gender; a gender with no range draws from the span " +
+                "of every range stated.",
+            values: Object.freeze({
+                kind: "map",
+                shape: "a height range",
+                describe: "The shortest and tallest height drawn.",
+                fields: Object.freeze([
+                    Object.freeze({
+                        name: "min",
+                        kind: "string",
+                        required: true,
+                        shape: "a height in metres or feet and inches",
+                        describe: "The shortest height drawn.",
+                    }),
+                    Object.freeze({
+                        name: "max",
+                        kind: "string",
+                        required: true,
+                        shape: "a height in metres or feet and inches",
+                        describe: "The tallest height drawn.",
+                    }),
+                ]),
+            }),
+        }),
+    ]),
+});
+
+/**
+ * A language's `data.names`: the pattern its speakers' names are built by and
+ * the lists each part is drawn from. Its keys beyond `pattern` and `given` are
+ * named by the language, so the map declares no closed inner keys and
+ * {@link checkLanguageNames} checks the whole of it; what the lists mean and
+ * how `package-build npc new` draws from them is in `language-names.mjs`.
+ *
+ * @type {DataFieldSpec}
+ */
+const NAMES_FIELD = Object.freeze({
+    name: "names",
+    kind: "map",
+    shape: "a language's name lists",
+    check: (note) => checkLanguageNames(note, BEING_LOOK_VOCABULARY),
+    describe:
+        "How this language's speakers are named, for `package-build npc new`: `pattern` " +
+        'builds a name from placeholders such as "{given} {clan}" and literal text, `given` ' +
+        "maps a gender to a list of given names, " +
+        `${wordList([...requiredGivenGenders()]).replace(" or ", " and ")} required, and ` +
+        "every other key is a list of names a placeholder of the same name draws from. A " +
+        "language skill note only. See [name lists](format-details.md#name-lists).",
+    fields: Object.freeze([
+        Object.freeze({
+            name: "pattern",
+            kind: "string-list-or-map",
+            required: true,
+            shape: 'a pattern such as "{given} {clan}", a list of them, or a map of genders to either',
+            describe:
+                "How a name is built: each `{list}` placeholder is filled from the list of " +
+                "that name, `{given.<gender>}` from that gender's given names, and the text " +
+                "around them is written as it stands. A list states every form a name may " +
+                "take; a map keyed by gender states each gender's forms, and a gender with " +
+                "none takes every pattern stated.",
+            entries: Object.freeze({
+                kind: "string",
+                shape: "a pattern",
+                describe: "One form a name may take.",
+            }),
+            values: Object.freeze({
+                kind: "string-or-list",
+                shape: "a pattern or a list of them",
+                describe: "The forms a name of that gender may take.",
+                entries: Object.freeze({
+                    kind: "string",
+                    shape: "a pattern",
+                    describe: "One form a name of that gender may take.",
+                }),
+            }),
+        }),
+        Object.freeze({
+            name: "given",
+            kind: "map",
+            required: true,
+            shape: "a map of genders to lists of names",
+            describe:
+                "Given names by gender word. A gender with no list draws from every given " +
+                "list together.",
+            values: Object.freeze({
+                kind: "list",
+                shape: "a list of names",
+                describe: "The given names of one gender.",
+                entries: Object.freeze({
+                    kind: "string",
+                    shape: "a name",
+                    describe: "One name, as written.",
+                }),
+            }),
+        }),
+    ]),
+    values: Object.freeze({
+        kind: "list",
+        shape: "a list of names",
+        describe: "A list a placeholder of the same name draws from, such as `clan` or `family`.",
+        entries: Object.freeze({
+            kind: "string",
+            shape: "a name",
+            describe: "One name, as written.",
+        }),
+    }),
+});
+
 /** A list. */
 const LIST = Object.freeze({ shape: "list", kind: "list" });
 
@@ -1659,6 +1814,7 @@ export const NOTE_VOCABULARY = Object.freeze({
                 accepts: ["skill"],
                 describe: "The skill this one specialises.",
             },
+            NAMES_FIELD,
         ]),
     }),
 
@@ -1833,7 +1989,8 @@ export const NOTE_VOCABULARY = Object.freeze({
         // A lore note is prose, and what it *is* about is its subType — with
         // two exceptions. A calendar is a division of the year, and a division
         // is data; a work of literature states in what tongue it is and what it
-        // concerns. The checks scope each family to the subType that means it,
+        // concerns, and a culture what tongue it speaks and what its people look
+        // like. The checks scope each family to the subType that means it,
         // because `DataFieldSpec` declares the keys a type accepts and not the
         // subType that may write them. Any lore note may name the people it
         // belongs to; a culture note names only itself.
@@ -1852,7 +2009,9 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "culture, and states the field only as itself.",
             },
             ...LITERATURE_FIELDS,
+            LANGUAGE_FIELD,
             EVENTS_FIELD,
+            APPEARANCE_PROFILE_FIELD,
         ]),
     }),