@heroiclands/package-build 23.6.0 → 23.7.0

package/engine/word-rows.mjs

@@ -24,22 +24,33 @@
  * 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
  */
 
 import { renderAddress } from "./address.mjs";
 import { glossaryLanguage } from "./glossary-language.mjs";
-import { GLOSSARY_ENTRY_KEYS, LANGUAGE_SUBTYPE, WORD_KEYS } from "./word-terms.mjs";
+import {
+    AFFIX_KEYS,
+    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([
@@ -51,6 +62,12 @@ export const WORD_COLUMNS = Object.freeze([
 /** Every column of the `glossary` relation, in order. */
 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]);
+
+/** Every column of the `fields` relation, in order. */
+export const FIELD_COLUMNS = Object.freeze([...WORD_IDENTITY_COLUMNS, ...FIELD_KEYS]);
+
 /** Every column of the `language_lineage` relation, in order. */
 export const LINEAGE_COLUMNS = Object.freeze(["language", "ancestor", "depth"]);
 
@@ -64,32 +81,89 @@ const isMap = (value) => Boolean(value) && typeof value === "object" && !Array.i
 const bare = (form) => String(form).replace(/^-+|-+$/g, "");
 
 /**
- * A lookup from a built piece to its gloss, over one language's words (stems
- * included) and affixes.
+ * A lookup from a built piece to its gloss, over the words (stems included)
+ * and affixes of one or more languages.
  *
- * A piece matches a word or an affix written exactly as it is, and failing
+ * Languages are given nearest first: a language's own words, then its own
+ * affixes, then the next language's, so a daughter's entry wins over its
+ * parent's. A piece matches an entry written exactly as it is, and failing
  * that one written with the same letters and different joining hyphens, so
- * `wulf-` finds the word `wulf`. A word's own gloss wins over an affix's.
+ * `wulf-` finds the word `wulf`. Within a language a word's own gloss wins over
+ * an affix's.
  *
- * @param {object} data - The language note's `data`.
+ * @param {...object} datas - Each language note's `data`, nearest first.
  * @returns {(piece: string) => string|null} The gloss, or `null` where none resolves.
  */
-export function pieceGlosses(data) {
+export function pieceGlosses(...datas) {
     const exact = new Map();
     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);
         }
     };
-    take(data?.words);
-    take(data?.affixes);
+    for (const data of datas) {
+        take(data?.words);
+        take(data?.affixes);
+    }
     return (piece) => exact.get(piece) ?? loose.get(bare(piece)) ?? null;
 }
 
+/**
+ * The chain of languages from one up through `data.family`: the language
+ * itself, then its parent, and so on. The chain stops at a parent that is no
+ * language, and before a language it has already reached, so a cycle the lint
+ * refuses still yields a finite chain. `language_lineage`, the dictionary and
+ * the resolution of built pieces all walk it.
+ *
+ * @param {string|undefined} start - The language's key.
+ * @param {object} reader
+ * @param {(key: string) => boolean} reader.has - Whether a key is a language.
+ * @param {(key: string) => string|undefined} reader.parentOf - A language's
+ *   parent key, where it states one.
+ * @returns {string[]} The keys, nearest first.
+ */
+export function lineageChain(start, { has, parentOf }) {
+    const chain = [];
+    const seen = new Set();
+    for (let current = start; current && has(current) && !seen.has(current);) {
+        seen.add(current);
+        chain.push(current);
+        current = parentOf(current) || undefined;
+    }
+    return chain;
+}
+
+/** A language record's `data.family` where it is a plain Address string. */
+const familyKey = (record) => {
+    const family = record?.data?.family;
+    return typeof family === "string" && family ? family : undefined;
+};
+
+/**
+ * A lookup of language records by Address, and the chain walk over them.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records.
+ * @returns {{languages: Map<string, object>, chain: (key: string) => string[]}}
+ */
+export function languageLineages(records) {
+    const languages = new Map();
+    for (const record of records)
+        if (isLanguageRecord(record)) {
+            const key = noteAddressOf(record);
+            if (key && !languages.has(key)) languages.set(key, record);
+        }
+    const reader = {
+        has: (key) => languages.has(key),
+        parentOf: (key) => familyKey(languages.get(key)),
+    };
+    return { languages, chain: (key) => lineageChain(key, reader) };
+}
+
 /**
  * Whether a record is a language note's.
  *
@@ -107,7 +181,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),
@@ -117,6 +191,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.
  *
@@ -124,9 +223,23 @@ function noteAddressOf(record) {
  *
  * @param {Iterable<Record<string, any>>} records - Index records, every
  *   Address a string, already narrowed to the audience being published to.
+ * @param {Iterable<Record<string, any>>} [all] - Every record of the package,
+ *   for resolving a built piece through an ancestor the audience does not see.
  * @returns {object[]} One row per word, in record then entry order.
  */
-export function wordRows(records) {
+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;
@@ -134,7 +247,7 @@ export function wordRows(records) {
         if (!Array.isArray(words) || !words.length) continue;
         const language = noteAddressOf(record);
         if (!language) continue;
-        const glossOf = pieceGlosses(record.data);
+        const glossOf = pieceGlosses(...chain(language).map((key) => languages.get(key).data));
         words.forEach((entry, position) => {
             if (!isMap(entry)) return;
             const row = { language, position };
@@ -144,12 +257,70 @@ export function wordRows(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);
         });
     }
     return rows;
 }
 
+/**
+ * The rows of one list a language note states beside its words: one per entry,
+ * keyed by the note, with every key of the entry a column.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records.
+ * @param {string} list - The `data` key holding the entries.
+ * @param {readonly string[]} keys - The keys an entry carries.
+ * @returns {object[]} One row per entry, in record then entry order.
+ */
+function languageListRows(records, list, keys) {
+    const rows = [];
+    for (const record of records) {
+        if (!isLanguageRecord(record)) continue;
+        const entries = record.data?.[list];
+        if (!Array.isArray(entries) || !entries.length) continue;
+        const language = noteAddressOf(record);
+        if (!language) continue;
+        entries.forEach((entry, position) => {
+            if (!isMap(entry)) return;
+            const row = { language, position };
+            for (const key of keys) row[key] = entry[key] ?? null;
+            rows.push(row);
+        });
+    }
+    return rows;
+}
+
+/**
+ * The `affixes` rows of a set of index records: one per `data.affixes` entry
+ * of a language note, which is the row's `language`.
+ *
+ * @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);
+}
+
+/**
+ * The `fields` rows of a set of index records: one per `data.fields` entry of
+ * a language note, which is the row's `language`.
+ *
+ * @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 field, in record then entry order.
+ */
+export function fieldRows(records) {
+    return languageListRows(records, "fields", FIELD_KEYS);
+}
+
 /**
  * The `glossary` rows of a set of index records: one per entry of a culture's
  * or an affiliation's `data.glossary`, with `name_sort` the name and `common`
@@ -209,25 +380,13 @@ export function glossaryRows(records, all = records) {
  * @returns {object[]} One row per language and ancestor, in record then depth order.
  */
 export function lineageRows(records, all = records) {
-    const languages = new Map();
-    for (const record of all)
-        if (isLanguageRecord(record)) {
-            const key = noteAddressOf(record);
-            if (key && !languages.has(key)) languages.set(key, record);
-        }
+    const { chain } = languageLineages(all);
     const rows = [];
     for (const record of records) {
         if (!isLanguageRecord(record)) continue;
         const language = noteAddressOf(record);
         if (!language) continue;
-        const seen = new Set();
-        let current = language;
-        for (let depth = 0; current && languages.has(current) && !seen.has(current); depth++) {
-            seen.add(current);
-            rows.push({ language, ancestor: current, depth });
-            const family = languages.get(current).data?.family;
-            current = typeof family === "string" && family ? family : undefined;
-        }
+        chain(language).forEach((ancestor, depth) => rows.push({ language, ancestor, depth }));
     }
     return rows;
 }

package/engine/word-terms.mjs

@@ -88,6 +88,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 +121,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 +145,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 +174,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.
  *
@@ -217,7 +255,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,8 +286,20 @@ 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: "tones",
+        kind: "string",
+        shape: "a tone pattern, such as `L`",
+        describe: "The tone pattern the affix carries, written as a word's `tones` is.",
+    }),
 ]);
 
+/** The keys of {@link WORD_FIELD_FIELDS}, in declared order. */
+export const FIELD_KEYS = Object.freeze(WORD_FIELD_FIELDS.map((field) => field.name));
+
+/** The keys of {@link AFFIX_FIELDS}, in declared order. */
+export const AFFIX_KEYS = Object.freeze(AFFIX_FIELDS.map((field) => field.name));
+
 /**
  * The keys one entry of a culture's or an affiliation's `data.glossary`
  * carries.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.6.0",
+    "version": "23.7.0",
     "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,6 +6,8 @@
  * @property {object} [addressContext] - Address resolution context.
  * @property {(address: string) => string|undefined} [labelOf] - A note's
  *   `name.full`, by its Address.
+ * @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.
  */
@@ -61,6 +63,11 @@ export type LayoutOptions = {
      * `name.full`, by its Address.
      */
     labelOf?: ((address: string) => string | undefined) | undefined;
+    /**
+     * - Whether the key is printed;
+     * `"only"` prints the key and nothing else.
+     */
+    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[];