@heroiclands/package-build 23.3.0 → 23.3.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @heroiclands/package-build
 
+## 23.3.1
+
+### Patch Changes
+
+**New npcs**
+
+- `package-build npc new` writes a complete npc note from a culture and a gender, filling every other field, an Appearance paragraph and a name; the same spec always gives the same person, and `--seed` draws another.
+- Give any field yourself, inline or from a JSON or YAML file, including the name and the Appearance and Dossier text, and it is written exactly as you gave it.
+- A culture describes its people in `data.appearanceProfile`, with weighted eye, hair and skin colours, complexions, frames and height ranges, and names the tongue they speak in `data.language`.
+- A language skill note lists its speakers' names in `data.names`: one or several patterns such as `{given} {clan}` or `{given} {given.male}sen`, by gender where forms differ, and the lists they draw on; a name you give must fit one.
+- `package-build lint` checks a profile's words, weights and ranges, and a language's pattern and lists.
+
 ## 23.3.0
 
 ### Minor Changes

package/bin/content-commands.mjs

@@ -31,6 +31,7 @@
  *   npx package-build map [--tree] [--from <shortcode>] [--chart <shortcode>] [--travel] [--out <dir>]
  *   npx package-build reachability <dir> [file] [--index <shortcode>]
  *   npx package-build addresses diff --from <zip|dir> [--strict]
+ *   npx package-build npc new (--spec <json> | --specfile <path>) [--seed <text>] [--out <path>]
  *
  * In a consuming repository, wrapped as npm scripts — SoHL spells them:
  *   npm run build:compiledb                // → … package compile (all packs)
@@ -112,7 +113,12 @@ import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-
 import { prepareTreeSqlTables } from "../engine/sql-tables.mjs";
 // The one place a link finding is worded, shared with both builds.
 import { linkFindingMessage } from "../engine/wikilink-syntax.mjs";
-import { emitDiagnostic, positionOfLiteral } from "../engine/diagnostics.mjs";
+import {
+    emitDiagnostic,
+    positionOfFrontmatterPath,
+    positionOfLiteral,
+    positionOfYamlPath,
+} from "../engine/diagnostics.mjs";
 import { reportFindings } from "./report.mjs";
 import {
     readItemAddresses,
@@ -127,6 +133,14 @@ import { CHART_HORIZON_DAYS } from "../engine/map-layout.mjs";
 import { GRAPHVIZ_ENGINES } from "../engine/map-graphviz.mjs";
 import { loadMapWorld } from "../engine/map-places.mjs";
 import { encodeAddresses } from "../engine/address-values.mjs";
+import YAML from "yaml";
+import { worldInvariants } from "../engine/calendar-notes.mjs";
+import { reckoningContext } from "../engine/reckoning-markers.mjs";
+import { BEING_LOOK_VOCABULARY } from "../engine/note-vocabulary.mjs";
+import { profileFindings } from "../engine/appearance-profile.mjs";
+import { namesFindings } from "../engine/language-names.mjs";
+import { parseAddress, renderAddress } from "../engine/address.mjs";
+import { cultureKey, generateNpc, npcDefaults, npcSpecProblems } from "../engine/npc-generate.mjs";
 
 /**
  * The packs `unpack` extracts.
@@ -241,7 +255,8 @@ export function registerContentCommands(cli) {
         )
         .command(withIndexPreflight(mapCommand()))
         .command(withIndexPreflight(reachabilityCommand()))
-        .command(addressesCommand());
+        .command(addressesCommand())
+        .command(withIndexPreflight(npcCommand()));
 }
 
 /** Optional sentence findings and note-level readability reports. */
@@ -490,6 +505,12 @@ function docsCommand() {
                 type: "string",
                 default: "docs",
             });
+            yargs.option("seed", {
+                describe:
+                    "Text that seeds generation beside the spec, to draw a different person " +
+                    "from the same spec.",
+                type: "string",
+            });
             yargs.option("out", {
                 describe: "Write to this file instead of the configured location.",
                 type: "string",
@@ -1555,6 +1576,12 @@ function contentIndexCommand() {
                 describe: "Content tree to read. Defaults to the configured contentBase.",
                 type: "string",
             });
+            yargs.option("seed", {
+                describe:
+                    "Text that seeds generation beside the spec, to draw a different person " +
+                    "from the same spec.",
+                type: "string",
+            });
             yargs.option("out", {
                 describe:
                     "Directory to write into. Defaults to the configured " +
@@ -2515,3 +2542,267 @@ function packageCommand() {
         },
     };
 }
+
+/**
+ * Read an `npc new` spec from `--spec` or `--specfile`.
+ *
+ * @param {{spec?: string, specfile?: string}} argv
+ * @returns {{spec: unknown, file?: string, text?: string}} The spec as parsed,
+ *   and the file and text it was read from where it came from a file.
+ */
+function readNpcSpec(argv) {
+    if (argv.spec !== undefined) {
+        try {
+            return { spec: JSON.parse(argv.spec) };
+        } catch (err) {
+            throw new Error(`\`--spec\` is not JSON: ${err.message}`);
+        }
+    }
+    const file = argv.specfile;
+    const ext = path.extname(file).toLowerCase();
+    if (![".json", ".yaml", ".yml"].includes(ext))
+        throw new Error(`\`--specfile\` ${file} must be a .json, .yaml or .yml file`);
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    } catch (err) {
+        throw new Error(`\`--specfile\` ${file} cannot be read: ${err.message}`);
+    }
+    try {
+        return { spec: ext === ".json" ? JSON.parse(text) : YAML.parse(text), file, text };
+    } catch (err) {
+        throw Object.assign(new Error(`${file}: error: ${err.message.split("\n")[0]}`), {
+            located: true,
+        });
+    }
+}
+
+/**
+ * An error located at a note, or at one key of its frontmatter where the note
+ * states it.
+ *
+ * @param {{file?: string, raw?: string}} note - Where the note is.
+ * @param {Array<string|number>} keyPath - The frontmatter key at fault, or the
+ *   map a missing key belongs in.
+ * @param {string} message - What is wrong.
+ * @returns {Error} The error, for `reportFailure` to print as a diagnostic.
+ */
+function noteError(note, keyPath, message) {
+    if (!note.file) return new Error(message);
+    return Object.assign(new Error(message), {
+        file: note.file,
+        keyPath,
+        position: positionOfFrontmatterPath(note.raw ?? "", keyPath, { key: true }),
+    });
+}
+
+/**
+ * `npc new`: resolve the spec's culture through the content tree, then the
+ * culture's appearance profile, its language and the language's name lists,
+ * and write the note. A missing link at any step is an error naming the note
+ * to fix.
+ *
+ * @param {object} config - The resolved pack configuration.
+ * @param {{spec?: string, specfile?: string, seed?: string, out?: string}} argv
+ */
+function newNpc(config, argv) {
+    const { spec, file: specFile, text: specText } = readNpcSpec(argv);
+    const problems = npcSpecProblems(spec);
+    if (problems.length) throw new Error(`npc new: ${problems.join("; ")}`);
+    if (argv.out && fs.existsSync(argv.out))
+        throw new Error(`${argv.out} already exists, and \`npc new\` never overwrites a note`);
+
+    const root = config.paths.content;
+    const records = indexRecordsFor({
+        contentBase: root,
+        config,
+        skipDirectories: config.skipDirectories,
+        problems: [],
+    });
+    const index = buildLinkIndex(root, {
+        config,
+        records,
+        skipDirectories: config.skipDirectories,
+    });
+    const located = (hit) => ({
+        file: hit.file ? path.relative(process.cwd(), hit.file) : undefined,
+        raw: hit.raw,
+    });
+
+    const written = spec.data.culture;
+    const key = cultureKey(written, index);
+    const hit = key ? index.addressHit(key) : undefined;
+    if (!hit)
+        throw new Error(
+            `\`data.culture\` ${JSON.stringify(written)} names no note in this package or ` +
+                "its dependencies",
+        );
+    const culture = hit.fm ?? hit;
+    if (String(culture.type ?? hit.type) !== "lore" || culture.subType !== "culture")
+        throw new Error(
+            `\`data.culture\` ${JSON.stringify(written)} is not a culture: it names a ` +
+                `${culture.type ?? hit.type ?? "note"} of subType ${culture.subType ?? "none"}`,
+        );
+    const cultureNote = located(hit);
+    const profile = culture.data?.appearanceProfile;
+    if (profile === undefined || profile === null)
+        throw noteError(
+            cultureNote,
+            ["data"],
+            `${key} states no \`data.appearanceProfile\`, so \`npc new\` cannot draw its ` +
+                "people's look",
+        );
+    const profileErrors = profileFindings(
+        { file: cultureNote.file, raw: hit.raw, fm: culture },
+        BEING_LOOK_VOCABULARY,
+    );
+    if (profileErrors.length) {
+        for (const finding of profileErrors) emitDiagnostic(finding);
+        throw new Error(`${key}'s appearance profile has ${profileErrors.length} problem(s)`);
+    }
+
+    const tongue = culture.data?.language;
+    if (tongue === undefined || tongue === null)
+        throw noteError(
+            cultureNote,
+            ["data"],
+            `${key} states no \`data.language\`, so \`npc new\` has no name lists to draw ` +
+                "from; name the language skill note its people speak",
+        );
+    const tuple = parseAddress(tongue, {
+        package: index.contentPackage,
+        system: "note",
+        type: "skill",
+        types: index.types,
+        packages: index.packages,
+    });
+    const languageKey = tuple.reason ? undefined : renderAddress(tuple);
+    const languageHit = languageKey ? index.addressHit(languageKey) : undefined;
+    if (!languageHit)
+        throw noteError(
+            cultureNote,
+            ["data", "language"],
+            `${key}'s \`data.language\` names no note in this package or its dependencies`,
+        );
+    const language = languageHit.fm ?? languageHit;
+    if (String(language.type ?? languageHit.type) !== "skill" || language.subType !== "language")
+        throw noteError(
+            cultureNote,
+            ["data", "language"],
+            `${key}'s \`data.language\` ${languageKey} is not a language: it names a ` +
+                `${language.type ?? languageHit.type ?? "note"} of subType ` +
+                `${language.subType ?? "none"}`,
+        );
+    const languageNote = located(languageHit);
+    const names = language.data?.names;
+    if (names === undefined || names === null)
+        throw noteError(
+            languageNote,
+            ["data"],
+            `${languageKey} states no \`data.names\`, so \`npc new\` has no name lists to ` +
+                `draw ${key}'s names from`,
+        );
+    const namesErrors = namesFindings(
+        { file: languageNote.file, raw: languageHit.raw, fm: language },
+        BEING_LOOK_VOCABULARY,
+    );
+    if (namesErrors.length) {
+        for (const finding of namesErrors) emitDiagnostic(finding);
+        throw new Error(`${languageKey}'s name lists have ${namesErrors.length} problem(s)`);
+    }
+
+    const { taken, ...defaults } = npcDefaults(index, key);
+    if (typeof spec.shortcode === "string" && taken.has(spec.shortcode))
+        throw new Error(`\`shortcode: ${spec.shortcode}\` already names a being in this package`);
+    let text;
+    try {
+        ({ text } = generateNpc(spec, {
+            profile,
+            names,
+            language: languageKey,
+            seed: argv.seed,
+            present: worldInvariants(index).present,
+            dateContext: reckoningContext(index),
+            defaults,
+            taken,
+        }));
+    } catch (err) {
+        // A name that does not fit is the spec's fault, so a spec file
+        // locates it at the name it states.
+        if (specFile && Array.isArray(err?.keyPath))
+            Object.assign(err, {
+                file: specFile,
+                position: positionOfYamlPath(specText ?? "", err.keyPath),
+            });
+        throw err;
+    }
+    if (!argv.out) {
+        process.stdout.write(text);
+        return;
+    }
+    fs.mkdirSync(path.dirname(argv.out), { recursive: true });
+    try {
+        fs.writeFileSync(argv.out, text, { flag: "wx" });
+    } catch (err) {
+        if (err?.code === "EEXIST")
+            throw new Error(`${argv.out} already exists, and \`npc new\` never overwrites a note`);
+        throw err;
+    }
+}
+
+/**
+ * `package-build npc new` — a complete NPC being note from a spec, its
+ * appearance drawn from its culture's profile.
+ *
+ * @returns {object} The yargs command module.
+ */
+function npcCommand() {
+    return {
+        command: "npc <action>",
+        describe:
+            "Write a new NPC being note from a spec, its culture's appearance profile and " +
+            "its language's name lists",
+        builder: (yargs) => {
+            yargs.positional("action", {
+                describe: "The action to perform.",
+                type: "string",
+                choices: ["new"],
+            });
+            yargs.option("spec", {
+                describe:
+                    "The spec as a JSON string: frontmatter fields, with `data.culture` and " +
+                    "`data.gender` required.",
+                type: "string",
+            });
+            yargs.option("specfile", {
+                describe: "The spec as a .json, .yaml or .yml file.",
+                type: "string",
+            });
+            yargs.option("seed", {
+                describe:
+                    "Text that seeds generation beside the spec, to draw a different person " +
+                    "from the same spec.",
+                type: "string",
+            });
+            yargs.option("out", {
+                describe:
+                    "Write the note to this new file instead of standard output. An " +
+                    "existing file is never overwritten.",
+                type: "string",
+            });
+            yargs.check((parsed) => {
+                if ((parsed.spec === undefined) === (parsed.specfile === undefined))
+                    throw new Error("`npc new` takes exactly one of `--spec` and `--specfile`");
+                return true;
+            });
+        },
+        handler: async (argv) => {
+            try {
+                newNpc(loadPackConfig(), argv);
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}

package/docs/commands.md

@@ -2766,3 +2766,186 @@ $ package-build addresses diff --from build/dist/module.zip
 
 `package-build package <action> [pack] [entry]`, `package-build deps fetch`,
 [Diagnostics](diagnostics.md).
+
+### `package-build npc new`
+
+**NAME**
+
+Write a new NPC being note from a spec, its look drawn from its culture's
+appearance profile and its name from its culture's language.
+
+**SYNOPSIS**
+
+```
+package-build npc new (--spec <json> | --specfile <path>) [--seed <text>] [--out <path>]
+```
+
+**DESCRIPTION**
+
+Writes one `type: being`, `subType: npc` note: the full `data` block, an
+`# Appearance {#appearance}` section and a `# Dossier {#dossier}` section, with
+no system block. The note goes to standard output, or to a new file with
+`--out`.
+
+The spec is a possibly incomplete set of frontmatter fields, given as a JSON
+string with `--spec` or as a `.json`, `.yaml` or `.yml` file with
+`--specfile`; exactly one of the two is required. `data.culture` and
+`data.gender` are required in it. Every field the spec gives is written
+exactly as given, at every depth, and every field it leaves out is generated:
+
+| Field                                                   | Generated value                                                                                                                           |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `name.full`                                             | Drawn from the culture's language's name lists by one of its patterns for `data.gender`, the given name from the list for that gender.    |
+| `shortcode`                                             | The name transliterated to lowercase letters and digits and cut to twelve characters; a counter replaces its tail where a being holds it. |
+| `type`, `subType`, `tags`                               | `being`, `npc`, `[generated, draft]`.                                                                                                     |
+| `data.icon`, `data.species`, `data.packFolder`          | The commonest value among the package's npcs of the same culture, else among all its npcs; left out where none states one.                |
+| `data.archetypes`                                       | `[commoner]`, the archetype of a person who fits no more specific one.                                                                    |
+| `data.templatePriority`, `data.occupation`, `data.died` | `null`.                                                                                                                                   |
+| `data.lore`, `data.homes`                               | `[]`.                                                                                                                                     |
+| `data.affiliations`                                     | `{}`.                                                                                                                                     |
+| `data.born`                                             | An adult age of 18 to 60 years before the package's present, as a `<year>.<day>` date; `unknown` where the package states no present.     |
+| `data.frame`, `data.appearance.*`                       | Weighted draws from the culture's appearance profile; `extra_features` is `[]`.                                                           |
+| `data.height`                                           | From the profile's range for the gender, in feet and inches.                                                                              |
+| `data.weight`                                           | From the height and the frame's body-mass band, in pounds. A spec giving height and weight but no frame gets the frame they imply.        |
+
+Generation is seeded from the spec itself, through a canonical serialisation
+that sorts every map's keys: the same spec always writes the same note, whether
+or not it states a name, and the order the spec writes its fields in changes
+nothing. `--seed` adds text to that seed, so the same spec with a different
+`--seed` writes a different person; two people drawn from a spec that states
+only the culture and the gender differ only by their seeds.
+
+`data.culture` resolves as any culture reference does, through this package's
+content tree and its dependencies, and must name a `lore` note of
+`subType: culture`. The culture supplies two things, and the command refuses a
+culture missing either, with an error at the culture note:
+
+- **Its look**, from `data.appearanceProfile`: the words and ranges every
+  appearance field is drawn from. See
+  [appearance profiles](reference/format-details.md#appearance-profiles).
+- **Its names**, from the language skill note its `data.language` names, whose
+  `data.names` holds the pattern and the lists. A language with no
+  `data.names` is an error at the language note. See
+  [name lists](reference/format-details.md#name-lists).
+
+A profile or name lists with problems are refused with a finding at each.
+
+A spec that states `name.full` keeps it, and the name must fit the language's
+lists: one of the patterns for `data.gender`, with every placeholder filled by
+a name of its list, the given name from the list for `data.gender`. A name that does not fit is an
+error naming the part that fails and the language it was checked against; from
+a `--specfile`, the error is located at the name in the file. Where the
+gender has no given list of its own, the given name is drawn from, and
+checked against, every given list together.
+
+Two top-level spec keys are section bodies rather than frontmatter.
+`appearance` is the Appearance section's markdown, written verbatim with its
+newlines and spacing; without it, the section is a paragraph written from the
+data. `dossier` is the Dossier section's markdown, likewise verbatim; without
+it, the section is its heading alone.
+
+**OPTIONS**
+
+| Positional | Type                 | Default | Description            |
+| ---------- | -------------------- | ------- | ---------------------- |
+| `action`   | string, one of `new` | —       | The action to perform. |
+
+| Option       | Type   | Default         | Description                                                                      |
+| ------------ | ------ | --------------- | -------------------------------------------------------------------------------- |
+| `--spec`     | string | —               | The spec as a JSON string. Exactly one of `--spec` and `--specfile` is required. |
+| `--specfile` | string | —               | The spec as a `.json`, `.yaml` or `.yml` file.                                   |
+| `--seed`     | string | —               | Text that seeds generation beside the spec, to draw a different person.          |
+| `--out`      | string | standard output | Write the note to this new file. An existing file is never overwritten.          |
+
+**EXIT STATUS**
+
+1 if neither or both of `--spec` and `--specfile` are given, if the spec
+cannot be read or lacks `data.culture` or `data.gender`, if `data.culture`
+names no culture note, if the culture states no appearance profile or no
+language, if its language states no name lists, if the profile or the lists
+have problems, if the spec's `name.full` does not fit the lists, if the spec's
+`shortcode` already names a being, or if `--out` names a file that exists.
+Otherwise 0.
+
+**EXAMPLES**
+
+A spec, `spec.yaml`, stating the culture, the gender, two archetypes, an
+occupation and the dossier, and no name:
+
+```yaml
+data:
+  culture: khelathi
+  gender: male
+  archetypes: [warrior, mariner]
+  occupation: River Fleet Officer
+dossier: |
+  He holds a commission in the river fleet, and his service is a matter of
+  record rather than of reputation.
+```
+
+Run against a package whose world states `present: "720.300"`, whose
+`khelathi` culture carries the profile in
+[appearance profiles](reference/format-details.md#appearance-profiles) and
+names `language: skill-khelathilng`, and whose language carries the lists in
+[name lists](reference/format-details.md#name-lists):
+
+```
+$ package-build npc new --specfile spec.yaml
+---
+shortcode: khelemureziq
+name: {full: Khelemûr ez Iqu}
+type: being
+subType: npc
+tags: [generated, draft]
+data:
+  templatePriority: null
+  archetypes: [warrior, mariner]
+  occupation: River Fleet Officer
+  lore: []
+  culture: khelathi
+  homes: []
+  affiliations: {}
+  gender: male
+  born: "699.134"
+  died: null
+  height: 5' 11"
+  weight: 167 lbs
+  frame: medium
+  appearance:
+    eye_color: brown
+    hair_color: black
+    skin_color: brown
+    complexion: clear
+    extra_features: []
+---
+
+# Appearance {#appearance}
+
+Khelemûr ez Iqu is a 21-year-old man who stands 5'11" tall with a medium build. He has brown skin, clear complexion, black hair, and brown eyes.
+
+# Dossier {#dossier}
+
+He holds a commission in the river fleet, and his service is a matter of
+record rather than of reputation.
+```
+
+A spec file, `bad.yaml`, stating a name whose second part is in no list:
+
+```
+$ package-build npc new --specfile bad.yaml
+bad.yaml:2:9: error: name.full "Aguri ez Lut" does not fit the names of demo-note-skill-khelathilng: "Lut", the {place} part, is not in the place list
+```
+
+A spec inline, for a culture that names no language:
+
+```
+$ package-build npc new --spec '{"data":{"culture":"plainfolk","gender":"female"}}'
+assets/content/Cultures/Plainfolk.md:6:1: error: demo-note-lore-plainfolk states no `data.language`, so `npc new` has no name lists to draw from; name the language skill note its people speak
+```
+
+**SEE ALSO**
+
+`package-build lint [root]`,
+[Appearance profiles](reference/format-details.md#appearance-profiles),
+[Name lists](reference/format-details.md#name-lists),
+[A being's look](reference/format-details.md#a-beings-look).

package/docs/content-format.md

@@ -94,6 +94,8 @@ A region may list its settlements in a table under `## Settlements` — name, ma
 
 A being states its gender, frame and appearance in words from one closed vocabulary: `data.gender`, `data.frame`, and `data.appearance.eye_color`, `hair_color`, `skin_color` and `complexion` each take only the words listed for them, and any other value is an error at the value. `data.appearance.extra_features` stays free text. See [a being's look](reference/format-details.md#a-beings-look).
 
+A culture note may state what its people look like in `data.appearanceProfile`: weighted words for frame, eyes, hair, skin and complexion, and height ranges by gender, all from the same vocabulary. A culture names its tongue in `data.language`, and that language skill note may state `data.names`: the patterns its speakers' names are built by and the lists each part is drawn from. `package-build npc new` writes a complete npc note from a spec of a culture and a gender, drawing the name from those lists and everything else the spec leaves out from the profile. See [appearance profiles](reference/format-details.md#appearance-profiles), [name lists](reference/format-details.md#name-lists) and [the command](commands.md#package-build-npc-new).
+
 Places, affiliations, lore and beings may name their culture in `data.culture`, and a `doc` of `subType: settingguide` must. A place or affiliation that names none inherits the culture of its parents. See [culture in the index](reference/format-details.md#culture-in-the-index).
 
 Blockquote alerts use `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, or `[!]`, with optional attributes after the marker. They replace the former info and warn div fences; secret blocks remain supported. See [alerts](authoring/links-and-markup.md#alerts).