@heroiclands/package-build 23.3.0 → 23.3.1

package/types/engine/appearance-profile.d.mts

@@ -0,0 +1,94 @@
+/**
+ * The genders every profile states a height range for.
+ *
+ * A function as well as a constant: `note-vocabulary.mjs` reads it while the
+ * module graph is still evaluating, before any `const` here is initialised,
+ * and a function declaration is bound from the start.
+ *
+ * @returns {readonly string[]} The genders.
+ */
+export function requiredHeightGenders(): readonly string[];
+/**
+ * The profile keys that take weighted words, read from the vocabulary: every
+ * being-look field but `gender`, by its last segment.
+ *
+ * @param {Readonly<Record<string, readonly {value: string}[]>>} lookVocabulary
+ * @returns {string[]} The keys, in the vocabulary's order.
+ */
+export function profileLookKeys(lookVocabulary: Readonly<Record<string, readonly {
+    value: string;
+}[]>>): string[];
+/**
+ * Everything wrong with a profile.
+ *
+ * @param {unknown} profile - The profile as authored.
+ * @param {Readonly<Record<string, readonly {value: string}[]>>} lookVocabulary -
+ *   The being-look vocabulary.
+ * @returns {ProfileProblem[]} The problems, in the order a reader meets them.
+ */
+export function profileProblems(profile: unknown, lookVocabulary: Readonly<Record<string, readonly {
+    value: string;
+}[]>>): ProfileProblem[];
+/**
+ * The frontmatter lint's check of `data.appearanceProfile`.
+ *
+ * Scoped to a `lore` note of `subType: culture`: on any other lore it is an
+ * error at the key. On a culture it reports what the field's declared inner
+ * keys cannot: words outside the vocabulary, weights that are not positive, a
+ * word map with no words, height ranges that are unreadable, reversed or keyed
+ * by no gender, and a missing `female` or `male` range.
+ *
+ * @param {object} note - The note: `file`, `raw` and parsed `fm`.
+ * @param {Readonly<Record<string, readonly {value: string}[]>>} lookVocabulary -
+ *   The being-look vocabulary.
+ * @returns {object[]} Findings, located at the word, weight or key at fault.
+ */
+export function checkAppearanceProfile(note: object, lookVocabulary: Readonly<Record<string, readonly {
+    value: string;
+}[]>>): object[];
+/**
+ * A profile's problems as findings at the culture note that states it, for a
+ * caller holding the note but not running the lint.
+ *
+ * @param {object} note - The culture note: `file`, `raw` and parsed `fm`.
+ * @param {Readonly<Record<string, readonly {value: string}[]>>} lookVocabulary -
+ *   The being-look vocabulary.
+ * @returns {object[]} Every problem, shape included, as findings.
+ */
+export function profileFindings(note: object, lookVocabulary: Readonly<Record<string, readonly {
+    value: string;
+}[]>>): object[];
+/** The `lore` subType whose notes may carry a profile. */
+export const PROFILE_SUBTYPE: "culture";
+/** The genders every profile states a height range for. */
+export const REQUIRED_HEIGHT_GENDERS: readonly string[];
+/**
+ * The body-mass index band, in kg/m², each frame word means, lightest to
+ * heaviest. The bands meet end to end, so every weight at a given height falls
+ * in exactly one frame.
+ *
+ * @type {Readonly<Record<string, readonly [number, number]>>}
+ */
+export const FRAME_MASS_INDEX: Readonly<Record<string, readonly [number, number]>>;
+/**
+ * One thing wrong with a profile.
+ */
+export type ProfileProblem = {
+    /**
+     * - Where, from the profile itself.
+     */
+    path: Array<string | number>;
+    /**
+     * - The fault is the key at `path`, not its value.
+     */
+    key?: boolean | undefined;
+    /**
+     * - The frontmatter lint's inner-key walk reports
+     * this too, from the field's declaration.
+     */
+    shape?: boolean | undefined;
+    /**
+     * - What is wrong, naming the full `data.` path.
+     */
+    message: string;
+};

package/types/engine/data-keys.d.mts

@@ -5,7 +5,7 @@
  * @property {string} name - The key as an author writes it.
  * @property {string} [kind] - Its value's shape: `string`, `date`, `number`,
  *   `integer`, `boolean`, `address`, `list`, `map`, `scalar-or-map`,
- *   or `string-or-list` — see {@link fitsKind}. Absent, the check
+ *   `string-or-list`, or `string-list-or-map` — see {@link fitsKind}. Absent, the check
  *   makes no claim about the value.
  * @property {readonly string[]} [allowed] - The closed set a present value is
  *   one of, where the key takes a fixed word.
@@ -94,7 +94,7 @@ export type InnerKeySpec = {
     /**
      * - Its value's shape: `string`, `date`, `number`,
      * `integer`, `boolean`, `address`, `list`, `map`, `scalar-or-map`,
-     * or `string-or-list` — see {@link fitsKind}. Absent, the check
+     * `string-or-list`, or `string-list-or-map` — see {@link fitsKind}. Absent, the check
      * makes no claim about the value.
      */
     kind?: string | undefined;

package/types/engine/language-names.d.mts

@@ -0,0 +1,140 @@
+/**
+ * The genders every `data.names.given` states a list for.
+ *
+ * A function rather than a `const`: `note-vocabulary.mjs` reads it while the
+ * module graph is still evaluating.
+ *
+ * @returns {readonly string[]} The genders.
+ */
+export function requiredGivenGenders(): readonly string[];
+/**
+ * A pattern read into literal text and placeholders.
+ *
+ * @param {string} pattern - The pattern as written.
+ * @returns {{parts: PatternPart[], problems: string[]}} The parts, and what is
+ *   wrong with the pattern's own spelling.
+ */
+export function parsePattern(pattern: string): {
+    parts: PatternPart[];
+    problems: string[];
+};
+/**
+ * The patterns a name of `gender` may take: every pattern where they are not
+ * keyed by gender, the gender's own where it has some, else every pattern
+ * stated.
+ *
+ * @param {object} names - Checked `data.names`.
+ * @param {string} gender - A gender word.
+ * @returns {string[]} The patterns.
+ */
+export function patternsFor(names: object, gender: string): string[];
+/**
+ * Everything wrong with a language's name lists.
+ *
+ * @param {unknown} names - `data.names` as authored.
+ * @param {Readonly<Record<string, readonly {value: string}[]>>} lookVocabulary -
+ *   The being-look vocabulary, whose `gender` words key `given`.
+ * @returns {NamesProblem[]} The problems, in the order a reader meets them.
+ */
+export function namesProblems(names: unknown, lookVocabulary: Readonly<Record<string, readonly {
+    value: string;
+}[]>>): NamesProblem[];
+/**
+ * The frontmatter lint's check of `data.names`.
+ *
+ * Scoped to a `skill` note of `subType: language`: on any other skill it is an
+ * error at the key. On a language it reports what the field's declared inner
+ * keys cannot: a pattern that does not parse, a placeholder naming no list, a
+ * list no pattern names, a list name a placeholder cannot spell, an empty list
+ * of patterns or of names, an empty name, a pattern or given list keyed by no
+ * gender, and a missing `female` or `male` list. Each is located at the pattern, list, entry or key at fault.
+ *
+ * @param {object} note - The note: `file`, `raw` and parsed `fm`.
+ * @param {Readonly<Record<string, readonly {value: string}[]>>} lookVocabulary -
+ *   The being-look vocabulary.
+ * @returns {object[]} Findings.
+ */
+export function checkLanguageNames(note: object, lookVocabulary: Readonly<Record<string, readonly {
+    value: string;
+}[]>>): object[];
+/**
+ * A language's name-list problems as findings at the note that states them,
+ * shape included, for a caller holding the note but not running the lint.
+ *
+ * @param {object} note - The language note: `file`, `raw` and parsed `fm`.
+ * @param {Readonly<Record<string, readonly {value: string}[]>>} lookVocabulary -
+ *   The being-look vocabulary.
+ * @returns {object[]} Every problem, as findings.
+ */
+export function namesFindings(note: object, lookVocabulary: Readonly<Record<string, readonly {
+    value: string;
+}[]>>): object[];
+/**
+ * The given names a gender draws from: its own list, or every given list
+ * together where it has none.
+ *
+ * @param {object} names - Checked `data.names`.
+ * @param {string} gender - A gender word.
+ * @returns {string[]} The names.
+ */
+export function givenNames(names: object, gender: string): string[];
+/**
+ * A name drawn from a language's lists: one of the gender's patterns, where it
+ * has more than one, then each placeholder an even draw from its list.
+ *
+ * @param {object} names - Checked `data.names`.
+ * @param {string} gender - A gender word.
+ * @param {() => number} next - A stream of numbers in `[0, 1)`.
+ * @returns {string} The name.
+ */
+export function drawName(names: object, gender: string, next: () => number): string;
+/**
+ * Why a name does not fit a language's lists, or `undefined` where it fits.
+ *
+ * A name fits when it takes one of the patterns for `gender`, with every
+ * placeholder filled by a name of its list: `{given}` from the gender's given
+ * list, `{given.<gender>}` from that gender's. Names compare in Unicode NFC, so
+ * a precomposed and a decomposed accent are one letter.
+ *
+ * @param {string} full - The name as given.
+ * @param {object} names - Checked `data.names`.
+ * @param {string} gender - A gender word.
+ * @returns {string|undefined} One sentence naming the part that does not fit.
+ */
+export function nameMisfit(full: string, names: object, gender: string): string | undefined;
+/** The `skill` subType whose notes may carry name lists. */
+export const NAMES_SUBTYPE: "language";
+/** The placeholder that draws from the given-name list for a gender. */
+export const GIVEN_LIST: "given";
+/**
+ * One piece of a parsed pattern: literal text, or a placeholder naming a list
+ * and, for `given`, the gender whose list it draws from.
+ */
+export type PatternPart = {
+    literal: string;
+} | {
+    list: string;
+    gender?: string;
+};
+/**
+ * One thing wrong with a language's name lists.
+ */
+export type NamesProblem = {
+    /**
+     * - Where, from `data.names` itself.
+     */
+    path: Array<string | number>;
+    /**
+     * - The fault is the key at `path`, not its value.
+     */
+    key?: boolean | undefined;
+    /**
+     * - The frontmatter lint's inner-key walk reports
+     * this too, from the field's declaration.
+     */
+    shape?: boolean | undefined;
+    /**
+     * - What is wrong, naming the full `data.` path.
+     */
+    message: string;
+};

package/types/engine/literature-notes.d.mts

@@ -13,16 +13,27 @@ export function checkLanguageChoice(note: object, { index }?: {
     index?: object;
 }): object[];
 /**
- * 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: object): object[];
 /** 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: readonly string[];
 /**
- * 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;
+/**
+ * The fields only a `literature` note may state, beside the shared
+ * {@link LANGUAGE_FIELD}. Every one is optional.
  *
  * @type {ReadonlyArray<object>}
  */

package/types/engine/npc-generate.d.mts

@@ -0,0 +1,124 @@
+/**
+ * A value as JSON with every map's keys sorted, so two specs stating the same
+ * fields in a different order serialise alike.
+ *
+ * @param {unknown} value - A spec, or any value in one.
+ * @returns {string} The canonical serialisation.
+ */
+export function canonicalSpec(value: unknown): string;
+/**
+ * Why a spec cannot be generated from, or nothing.
+ *
+ * @param {unknown} spec - The spec as read.
+ * @returns {string[]} One sentence per problem.
+ */
+export function npcSpecProblems(spec: unknown): string[];
+/**
+ * The shortcode a name derives, free of every shortcode in `taken`.
+ *
+ * @param {string} name - `name.full`.
+ * @param {ReadonlySet<string>} taken - Shortcodes the package's beings hold.
+ * @returns {string} The shortcode.
+ */
+export function npcShortcode(name: string, taken: ReadonlySet<string>): string;
+/**
+ * The Appearance section's paragraph, in the Folk wording: "Ahmetega Zekar is
+ * a 39-year-old man who stands 6'4" tall with a heavy build. He has tawny
+ * skin, weathered complexion, black hair, and brown eyes."
+ *
+ * A fact that is absent leaves its clause out.
+ *
+ * @param {object} facts
+ * @param {string} facts.name - `name.full`.
+ * @param {number|null} [facts.age] - Whole years, or `null` where unknown.
+ * @param {string} [facts.gender]
+ * @param {unknown} [facts.height]
+ * @param {string} [facts.frame]
+ * @param {object} [facts.appearance] - The `data.appearance` map.
+ * @returns {string} The paragraph.
+ */
+export function appearanceParagraph({ name, age, gender, height, frame, appearance }: {
+    name: string;
+    age?: number | null | undefined;
+    gender?: string | undefined;
+    height?: unknown;
+    frame?: string | undefined;
+    appearance?: object | undefined;
+}): string;
+/**
+ * Generate a being note from a spec.
+ *
+ * @param {object} spec - The spec: frontmatter fields, plus `appearance` and
+ *   `dossier` section bodies.
+ * @param {object} context
+ * @param {object} context.profile - The culture's appearance profile, already
+ *   checked by `profileProblems`.
+ * @param {object} context.names - The language's `data.names`, already checked
+ *   by `namesProblems`.
+ * @param {string} [context.language] - The language's Address, for an error
+ *   about a name that does not fit.
+ * @param {string} [context.seed] - Text joined to the spec's own seed, to draw a
+ *   different person from the same spec.
+ * @param {unknown} [context.present] - The package's present, or `null`.
+ * @param {object} [context.dateContext] - The reckoning context the present
+ *   and `born` are read in, with `daysPerYear`.
+ * @param {{icon?: unknown, species?: unknown, packFolder?: unknown}} [context.defaults] -
+ *   Values derived from the package's other beings.
+ * @param {ReadonlySet<string>} [context.taken] - Shortcodes the package's beings hold.
+ * @returns {{frontmatter: object, body: string, text: string}} The note.
+ * @throws {Error} Where the spec has problems, or states a `name.full` that
+ *   does not fit the language's lists; that error carries `keyPath`
+ *   `["name", "full"]`.
+ */
+export function generateNpc(spec: object, context: {
+    profile: object;
+    names: object;
+    language?: string | undefined;
+    seed?: string | undefined;
+    present?: unknown;
+    dateContext?: object | undefined;
+    defaults?: {
+        icon?: unknown;
+        species?: unknown;
+        packFolder?: unknown;
+    } | undefined;
+    taken?: ReadonlySet<string> | undefined;
+}): {
+    frontmatter: object;
+    body: string;
+    text: string;
+};
+/**
+ * The canonical Address a `data.culture` value names, read as a culture
+ * reference is: a `lore` note in this package unless it says otherwise.
+ *
+ * @param {unknown} value - The value as written, or a decoded tuple.
+ * @param {object} index - The link index.
+ * @returns {string|undefined} The Address, or `undefined` where it reads as none.
+ */
+export function cultureKey(value: unknown, index: object): string | undefined;
+/**
+ * The commonest value of each of `icon`, `species` and `packFolder` among the
+ * package's npcs, as their notes write it: those of the same culture first,
+ * then any npc. A tie goes to the value that sorts first.
+ *
+ * @param {object} index - The link index.
+ * @param {string|undefined} culture - The culture's canonical Address.
+ * @returns {{icon?: unknown, species?: unknown, packFolder?: unknown, taken: Set<string>}}
+ *   The defaults, and the shortcodes the package's beings hold.
+ */
+export function npcDefaults(index: object, culture: string | undefined): {
+    icon?: unknown;
+    species?: unknown;
+    packFolder?: unknown;
+    taken: Set<string>;
+};
+/** The youngest and oldest age, in whole years, a generated person is born to. */
+export const ADULT_AGE: Readonly<{
+    min: 18;
+    max: 60;
+}>;
+/** The longest shortcode the derivation makes. */
+export const SHORTCODE_LENGTH: 12;
+/** The spec fields `npc new` requires, as paths. */
+export const REQUIRED_SPEC_FIELDS: readonly string[];