@heroiclands/package-build 23.6.1 → 23.7.1

package/engine/word-rows.mjs

@@ -24,9 +24,12 @@
  * binds.
  *
  * A word row holds the words its own note states, and nothing is copied for a
- * daughter language. `language_lineage` is one row per language and each of
- * its ancestors through `data.family`, itself included at depth `0`, so a
- * language's words with its inherited ones are a join of the two.
+ * daughter language. Its `gloss` is the word's senses joined by `; `, its
+ * `senses` each sense in order, and its `attested` the notes whose prose cites
+ * it ({@link module:engine/word-citations}), or `NULL` where none does.
+ * `language_lineage` is one row per language and each of its ancestors through
+ * `data.family`, itself included at depth `0`, so a language's words with its
+ * inherited ones are a join of the two.
  *
  * @module
  */
@@ -35,17 +38,20 @@ import { renderAddress } from "./address.mjs";
 import { glossaryLanguage } from "./glossary-language.mjs";
 import {
     AFFIX_KEYS,
+    ZERO_AFFIX,
     FIELD_KEYS,
     GLOSSARY_ENTRY_KEYS,
     LANGUAGE_SUBTYPE,
     WORD_KEYS,
+    glossSenses,
+    glossText,
 } from "./word-terms.mjs";
 
 /** The columns a word row carries before the word's own keys. */
 const WORD_IDENTITY_COLUMNS = Object.freeze(["language", "position"]);
 
 /** The columns a word row derives after the word's own keys. */
-const WORD_DERIVED_COLUMNS = Object.freeze(["built_text", "built_parts"]);
+const WORD_DERIVED_COLUMNS = Object.freeze(["built_text", "built_parts", "senses", "attested"]);
 
 /** Every column of the `words` relation, in order. */
 export const WORD_COLUMNS = Object.freeze([
@@ -58,7 +64,7 @@ export const WORD_COLUMNS = Object.freeze([
 export const GLOSSARY_COLUMNS = Object.freeze(["note", "position", ...GLOSSARY_ENTRY_KEYS]);
 
 /** Every column of the `affixes` relation, in order. */
-export const AFFIX_COLUMNS = Object.freeze([...WORD_IDENTITY_COLUMNS, ...AFFIX_KEYS]);
+export const AFFIX_COLUMNS = Object.freeze([...WORD_IDENTITY_COLUMNS, ...AFFIX_KEYS, "written"]);
 
 /** Every column of the `fields` relation, in order. */
 export const FIELD_COLUMNS = Object.freeze([...WORD_IDENTITY_COLUMNS, ...FIELD_KEYS]);
@@ -94,10 +100,11 @@ export function pieceGlosses(...datas) {
     const loose = new Map();
     const take = (entries) => {
         for (const entry of Array.isArray(entries) ? entries : []) {
-            if (!isMap(entry) || typeof entry.form !== "string" || typeof entry.gloss !== "string")
-                continue;
-            if (!exact.has(entry.form)) exact.set(entry.form, entry.gloss);
-            if (!loose.has(bare(entry.form))) loose.set(bare(entry.form), entry.gloss);
+            if (!isMap(entry) || typeof entry.form !== "string") continue;
+            const gloss = glossText(entry.gloss);
+            if (gloss === null) continue;
+            if (!exact.has(entry.form)) exact.set(entry.form, gloss);
+            if (!loose.has(bare(entry.form))) loose.set(bare(entry.form), gloss);
         }
     };
     for (const data of datas) {
@@ -175,7 +182,7 @@ export function isLanguageRecord(record) {
  * @param {Record<string, any>} record - An index record.
  * @returns {string|null} The Address, or `null` for a record naming no note.
  */
-function noteAddressOf(record) {
+export function noteAddressOf(record) {
     if (!record?.package || !record.type || !record.shortcode) return null;
     return renderAddress({
         package: String(record.package),
@@ -185,6 +192,31 @@ function noteAddressOf(record) {
     });
 }
 
+/**
+ * A lookup of the notes citing a word, from records that carry `citations`.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records.
+ * @returns {(language: string, form: string) => string[]} The citing notes;
+ *   empty where none cites the word.
+ */
+export function citationLookup(records) {
+    const byLanguage = new Map();
+    for (const record of records) {
+        if (!isLanguageRecord(record) || !Array.isArray(record.citations)) continue;
+        const language = noteAddressOf(record);
+        if (!language) continue;
+        const words = new Map();
+        for (const entry of record.citations)
+            if (isMap(entry) && typeof entry.form === "string" && Array.isArray(entry.notes))
+                words.set(
+                    entry.form,
+                    entry.notes.filter((note) => typeof note === "string"),
+                );
+        byLanguage.set(language, words);
+    }
+    return (language, form) => byLanguage.get(language)?.get(form) ?? [];
+}
+
 /**
  * The `words` rows of a set of index records.
  *
@@ -198,6 +230,17 @@ function noteAddressOf(record) {
  */
 export function wordRows(records, all = records) {
     const { languages, chain } = languageLineages(all);
+    const citedBy = citationLookup(all);
+    const visible = new Set();
+    for (const record of records) {
+        const key = noteAddressOf(record);
+        if (key) visible.add(key);
+    }
+    const known = new Set();
+    for (const record of all) {
+        const key = noteAddressOf(record);
+        if (key) known.add(key);
+    }
     const rows = [];
     for (const record of records) {
         if (!isLanguageRecord(record)) continue;
@@ -215,6 +258,13 @@ export function wordRows(records, all = records) {
             row.built_text = built.length ? built.join(" + ") : null;
             row.built_parts =
                 built.length ? built.map((form) => ({ form, gloss: glossOf(form) })) : null;
+            row.gloss = glossText(entry.gloss);
+            row.senses = glossSenses(entry.gloss);
+            // A citing note the audience does not see is left out, as the note is.
+            const attested = citedBy(language, entry.form).filter(
+                (note) => visible.has(note) || !known.has(note),
+            );
+            row.attested = attested.length ? attested : null;
             rows.push(row);
         });
     }
@@ -250,14 +300,18 @@ function languageListRows(records, list, keys) {
 
 /**
  * The `affixes` rows of a set of index records: one per `data.affixes` entry
- * of a language note, which is the row's `language`.
+ * of a language note, which is the row's `language`, with `written`, the form
+ * as a table prints it: `∅` for a zero affix, whose `form` is `NULL`.
  *
  * @param {Iterable<Record<string, any>>} records - Index records, every
  *   Address a string, already narrowed to the audience being published to.
  * @returns {object[]} One row per affix, in record then entry order.
  */
 export function affixRows(records) {
-    return languageListRows(records, "affixes", AFFIX_KEYS);
+    return languageListRows(records, "affixes", AFFIX_KEYS).map((row) => ({
+        ...row,
+        written: row.zero === true ? ZERO_AFFIX : row.form,
+    }));
 }
 
 /**

package/engine/word-terms.mjs

@@ -44,6 +44,30 @@ export const WORD_SOURCE_KINDS = Object.freeze([
     "island",
 ]);
 
+/**
+ * What an affix makes: a case, a word derived from another, a verb's tense,
+ * aspect, mood or voice, a given name's ending, or a lineage name's ending.
+ */
+export const AFFIX_KINDS = Object.freeze([
+    "case",
+    "derivation",
+    "tense",
+    "aspect",
+    "mood",
+    "voice",
+    "name",
+    "lineage",
+]);
+
+/** The affix kind whose ending says who the name is given to. */
+export const NAME_AFFIX_KIND = "name";
+
+/** How a zero affix is written where a table prints it. */
+export const ZERO_AFFIX = "∅";
+
+/** Who a given name's ending is given to. */
+export const AFFIX_GIVEN = Object.freeze(["man", "woman", "either"]);
+
 /** The source kind that requires `language`. */
 export const BORROWED_SOURCE_KIND = "borrowed";
 
@@ -88,6 +112,15 @@ export const WORD_FIELDS = Object.freeze([
         shape: "the word as cited, bare",
         describe: "The word as cited, with no backticks.",
     }),
+    Object.freeze({
+        name: "variants",
+        kind: "list",
+        shape: "a list of forms",
+        entries: Object.freeze({ kind: "string", shape: "a form, bare" }),
+        describe:
+            "The word's other forms, such as a long form beside a short one; a marked use of " +
+            "one cites the word.",
+    }),
     Object.freeze({
         name: "name_sort",
         kind: "string",
@@ -112,10 +145,12 @@ export const WORD_FIELDS = Object.freeze([
     }),
     Object.freeze({
         name: "gloss",
-        kind: "string",
+        kind: "string-or-list",
         required: true,
-        shape: "a string",
-        describe: "The meaning, in brief.",
+        shape: "a string, or a list of senses",
+        entries: Object.freeze({ kind: "string", shape: "a sense" }),
+        describe:
+            "The meaning, in brief; a list states one sense per entry, which a dictionary numbers.",
     }),
     Object.freeze({
         name: "source",
@@ -134,11 +169,11 @@ export const WORD_FIELDS = Object.freeze([
             "write them; absent for a root word.",
     }),
     Object.freeze({
-        name: "attested",
-        kind: "list",
-        shape: "a list of Addresses",
-        entries: Object.freeze({ kind: "address", shape: "an Address" }),
-        describe: "The notes the word is cited from.",
+        name: "note",
+        kind: "string",
+        shape: "a string",
+        describe:
+            "What a source says of the word beyond its pieces, such as a cognate it is read with.",
     }),
     Object.freeze({
         name: "pronunciation",
@@ -163,14 +198,41 @@ export const WORD_FIELDS = Object.freeze([
     Object.freeze({
         name: "frame",
         kind: "string",
-        shape: "a string",
-        describe: "The frame a root is set in.",
+        shape: "a frame of the language's `sounds.frames`",
+        describe: "The frame a root is set in, named in the language's `sounds.frames`.",
     }),
 ]);
 
 /** The keys of {@link WORD_FIELDS}, in declared order. */
 export const WORD_KEYS = Object.freeze(WORD_FIELDS.map((field) => field.name));
 
+/**
+ * A word's senses: one for a string gloss, one per entry for a list, each
+ * trimmed, blanks dropped.
+ *
+ * @param {unknown} gloss - The word's `gloss`.
+ * @returns {string[]} The senses, in order.
+ */
+export function glossSenses(gloss) {
+    const list = Array.isArray(gloss) ? gloss : [gloss];
+    return list
+        .filter((sense) => typeof sense === "string")
+        .map((sense) => sense.trim())
+        .filter(Boolean);
+}
+
+/**
+ * A word's gloss as one line of text: its senses joined by `; `, or `null`
+ * where it states none.
+ *
+ * @param {unknown} gloss - The word's `gloss`.
+ * @returns {string|null}
+ */
+export function glossText(gloss) {
+    const senses = glossSenses(gloss);
+    return senses.length ? senses.join("; ") : null;
+}
+
 /**
  * The keys one entry of a language note's `data.fields` carries.
  *
@@ -202,9 +264,36 @@ export const AFFIX_FIELDS = Object.freeze([
     Object.freeze({
         name: "form",
         kind: "string",
-        required: true,
         shape: "the affix as written, such as `-rith`",
-        describe: "The affix as a word's `built` names it.",
+        describe: "The affix as a word's `built` names it; absent on a zero affix.",
+    }),
+    Object.freeze({
+        name: "zero",
+        kind: "boolean",
+        shape: "`true`",
+        describe:
+            "The affix is written as nothing, such as a case with no ending; it states no " +
+            `\`form\`, prints as \`${ZERO_AFFIX}\`, and no \`built\` piece names it.`,
+    }),
+    Object.freeze({
+        name: "kind",
+        kind: "string",
+        allowed: AFFIX_KINDS,
+        shape: `one of ${AFFIX_KINDS.join(", ")}`,
+        describe: "What the affix makes.",
+    }),
+    Object.freeze({
+        name: "given",
+        kind: "string",
+        allowed: AFFIX_GIVEN,
+        shape: `one of ${AFFIX_GIVEN.join(", ")}`,
+        describe: `Who a given name closing on it belongs to; an affix of kind \`${NAME_AFFIX_KIND}\` only.`,
+    }),
+    Object.freeze({
+        name: "where",
+        kind: "string",
+        shape: "a string, such as `before a stop`",
+        describe: "Where this form stands, for an affix written two ways; everywhere where absent.",
     }),
     Object.freeze({
         name: "gloss",
@@ -217,7 +306,29 @@ export const AFFIX_FIELDS = Object.freeze([
         name: "attaches",
         kind: "string",
         shape: "a string",
-        describe: "How it attaches, such as `replaces a closing vowel`.",
+        describe: "How it attaches, in words, such as `replaces a closing vowel`.",
+    }),
+    Object.freeze({
+        name: "replaces",
+        kind: "string",
+        shape: "`vowel`, or the letters, such as `a`",
+        describe:
+            "What it takes the place of at the close of the stem: `vowel` for any closing " +
+            "vowel, or the letters it replaces; added to the whole stem where absent.",
+    }),
+    Object.freeze({
+        name: "lengthens",
+        kind: "boolean",
+        shape: "`true` or `false`",
+        describe:
+            "Whether the stem's last vowel lengthens before the affix; `false` where unstated. An " +
+            "affix that `replaces` the stem's close does not also lengthen it.",
+    }),
+    Object.freeze({
+        name: "front",
+        kind: "string",
+        shape: "the affix as written, such as `-ür`",
+        describe: "Its form after front vowels, where the language keeps vowel harmony.",
     }),
     Object.freeze({
         name: "examples",
@@ -226,6 +337,13 @@ export const AFFIX_FIELDS = Object.freeze([
         entries: Object.freeze({ kind: "string", shape: "a string" }),
         describe: "The names the affix is read from.",
     }),
+    Object.freeze({
+        name: "barredAfter",
+        kind: "list",
+        shape: "a list of sounds",
+        entries: Object.freeze({ kind: "string", shape: "a sound as written" }),
+        describe: "The sounds a stem may not close on to take the affix.",
+    }),
     Object.freeze({
         name: "tones",
         kind: "string",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.6.1",
+    "version": "23.7.1",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/dictionary-layout.d.mts

@@ -6,7 +6,8 @@
  * @property {object} [addressContext] - Address resolution context.
  * @property {(address: string) => string|undefined} [labelOf] - A note's
  *   `name.full`, by its Address.
- * @property {boolean} [showKey=true] - Whether the key is printed.
+ * @property {boolean|"only"} [showKey=true] - Whether the key is printed;
+ *   `"only"` prints the key and nothing else.
  * @property {string} [pageLanguage] - The language of the page the fence is
  *   on, which no entry is tagged with.
  */
@@ -63,9 +64,10 @@ export type LayoutOptions = {
      */
     labelOf?: ((address: string) => string | undefined) | undefined;
     /**
-     * - Whether the key is printed.
+     * - Whether the key is printed;
+     * `"only"` prints the key and nothing else.
      */
-    showKey?: boolean | undefined;
+    showKey?: boolean | "only" | undefined;
     /**
      * - The language of the page the fence is
      * on, which no entry is tagged with.

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

@@ -0,0 +1,22 @@
+/**
+ * Whether a tag a row names is one `data.tongues` declares.
+ *
+ * @param {string} tag - The tag as the row writes it.
+ * @param {Set<string>} declared - The declared tags.
+ * @returns {boolean}
+ */
+export function tongueDeclared(tag: string, declared: Set<string>): boolean;
+/**
+ * Check a `skill` note's language data against what it means.
+ *
+ * @param {object} note - A `skill` note: `file`, `raw` and parsed `fm`.
+ * @param {object} [context]
+ * @param {object} [context.index] - The index, for whether an Address
+ *   resolves. Without one, only what the note says of itself is checked.
+ * @param {readonly string[]} [context.types] - The note types a scope may name.
+ * @returns {object[]} The findings.
+ */
+export function checkLanguageData(note: object, { index, types }?: {
+    index?: object | undefined;
+    types?: readonly string[] | undefined;
+}): object[];