@heroiclands/package-build 23.8.0 → 23.9.0

package/engine/content-tables.mjs

@@ -14,6 +14,7 @@
 import { FENCE_LINE } from "./code-fences.mjs";
 import { PAGE_LIST_LANGUAGE } from "./page-lists.mjs";
 import { appendGeneratedSections } from "./generated-sections.mjs";
+import { insertLexicalSections } from "./lexical-sections.mjs";
 
 /**
  * Replace prepared SQL fences and page lists with Markdown while retaining
@@ -29,7 +30,8 @@ import { appendGeneratedSections } from "./generated-sections.mjs";
  *   Prepared results.
  * A note's generated sections — see {@link module:engine/generated-sections} —
  * are appended to the body first, from the `generated` text the preparation
- * set on its results, and expanded with it.
+ * set on its results, and expanded with it. Automatic lexical lists, carried
+ * on `lexical`, then fill their authored sections or append a new section.
  *
  * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[],
  *   generatedFrom?: number}} `generatedFrom` is the 0-based line of the
@@ -148,10 +150,12 @@ export function expandContentTables(markdown, { source = "", sqlTables, pageList
         i = close;
     }
     return {
-        markdown: out.join("\n"),
+        ...insertLexicalSections(out.join("\n"), sqlTables?.lexical, {
+            authored,
+            lineMap,
+            generatedFrom,
+        }),
         errors,
         warnings,
-        lineMap,
-        ...(generatedFrom === undefined ? {} : { generatedFrom }),
     };
 }

package/engine/culture-reach.mjs

@@ -15,17 +15,14 @@
  * Which terms reach a culture or an affiliation, and whether an affiliation
  * reaches a culture at all.
  *
- * A culture's terms are the words of its language, and the ranks, offices and
- * language words of every affiliation that reaches it — through its own
- * `data.culture`, the one the index resolves for it, or the culture of an
- * affiliation above it through `data.parents` —
- * each affiliation's language being the one its glossary resolves to
- * ({@link module:engine/glossary-language}). An affiliation's terms are its own
- * ranks and offices and the words of that language. A language's words include
- * the words it inherits through `data.family`, and a word is a term only where
+ * A culture can name the ranks and offices of every affiliation that reaches
+ * it through `data.culture` or `data.parents`. An affiliation can name its own
+ * ranks and offices. Each glossary entry can also name a word of its resolved
+ * language ({@link module:engine/glossary-language}). A language's words include
+ * those it inherits through `data.family`, and a word is a term only where
  * its class's base is a glossary base. The `dictionary` relation
- * ({@link module:engine/dictionary-rows}) names a glossary entry's term from
- * the same reach.
+ * ({@link module:engine/dictionary-rows}) uses the same resolved-language and
+ * governance sources.
  *
  * **An affiliation that reaches no culture is a warning**, at its `type`, in a
  * tree that describes peoples, which is a tree holding at least one culture
@@ -42,7 +39,7 @@ import { AddressLink } from "./address-values.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { glossaryLanguage } from "./glossary-language.mjs";
 import { parseWordClass, WORD_CLASS_BASES } from "./word-classes.mjs";
-import { LANGUAGE_SUBTYPE } from "./word-terms.mjs";
+import { glossSenses, LANGUAGE_SUBTYPE } from "./word-terms.mjs";
 
 /** The bases whose words are glossary terms. */
 const GLOSSARY_BASES = new Set(
@@ -189,6 +186,11 @@ export function entryLanguage(index, note, entry) {
  * @property {Map<string, Map<string, string[]>>} terms - Each culture's and
  *   affiliation's terms by NFC name, each with the sense texts its sources
  *   give it.
+ * @property {Map<string, Map<string, string[]>>} governance - The ranks and
+ *   offices each owner can name.
+ * @property {Map<string, Array<{form: string, gloss: unknown}>>} words - Each
+ *   language's dictionary words.
+ * @property {Map<string, string|undefined>} families - Each language's parent.
  */
 
 /** @type {WeakMap<object, GlossaryCorpus>} */
@@ -239,6 +241,23 @@ function reachedCultures(index, note) {
     return [...out];
 }
 
+/** Add the nearest dictionary definition of each form in a language's lineage. */
+function addLanguageWords(terms, key, language, words, families) {
+    const seen = new Set();
+    const forms = new Set();
+    for (let current = language; current && !seen.has(current); current = families.get(current)) {
+        seen.add(current);
+        for (const word of words.get(current) ?? []) {
+            const form = glossaryName(word.form);
+            if (forms.has(form)) continue;
+            forms.add(form);
+            const senses = glossSenses(word.gloss);
+            if (!senses.length) addTerm(terms, key, form, undefined);
+            for (const sense of senses) addTerm(terms, key, form, sense);
+        }
+    }
+}
+
 /**
  * The glossary corpus of an index.
  *
@@ -257,18 +276,7 @@ export function glossaryCorpus(index) {
             if (key) families.set(key, addressKeyOf(dataOf(note).family, index, "skill"));
         }
     const terms = new Map();
-    // A language's words include those it inherits through `data.family`.
-    const addWords = (key, language) => {
-        const seen = new Set();
-        for (
-            let current = language;
-            current && !seen.has(current);
-            current = families.get(current)
-        ) {
-            seen.add(current);
-            for (const word of words.get(current) ?? []) addTerm(terms, key, word.form, word.gloss);
-        }
-    };
+    const governance = new Map();
     for (const note of notes) {
         const culture = isCultureNote(note);
         if (!culture && typeOf(note) !== "affiliation") continue;
@@ -276,18 +284,22 @@ export function glossaryCorpus(index) {
         if (!key) continue;
         if (!terms.has(key)) terms.set(key, new Map());
         const data = dataOf(note);
-        if (culture) {
-            addWords(key, addressKeyOf(data.language, index, "skill"));
-            continue;
-        }
+        addLanguageWords(terms, key, entryLanguage(index, note, undefined), words, families);
+        if (culture) continue;
         addGovernance(terms, key, data);
-        addWords(key, entryLanguage(index, note, undefined));
+        addGovernance(governance, key, data);
         for (const home of reachedCultures(index, note)) {
             addGovernance(terms, home, data);
-            addWords(home, entryLanguage(index, note, undefined));
+            addGovernance(governance, home, data);
         }
     }
-    const corpus = { describesPeoples: notes.some(isCultureNote), terms };
+    const corpus = {
+        describesPeoples: notes.some(isCultureNote),
+        terms,
+        governance,
+        words,
+        families,
+    };
     CORPUS.set(index, corpus);
     return corpus;
 }
@@ -298,16 +310,31 @@ export function glossaryCorpus(index) {
  *
  * @param {object} index - The link index.
  * @param {object} note - The culture or affiliation note.
+ * @param {object} [entry] - A glossary entry, whose resolved language selects
+ *   its dictionary words. Absent, the note's own language is used.
  * @returns {Map<string, string[]>} The terms; empty for a note no source reaches.
  */
-export function noteTerms(index, note) {
+export function noteTerms(index, note, entry) {
     const key = ownKey(note, index);
-    return (key && glossaryCorpus(index).terms.get(key)) || new Map();
+    const corpus = glossaryCorpus(index);
+    if (!entry) return (key && corpus.terms.get(key)) || new Map();
+    const own = new Map(
+        [...(corpus.governance.get(key) ?? [])].map(([name, senses]) => [name, [...senses]]),
+    );
+    addLanguageWords(
+        new Map([[key, own]]),
+        key,
+        entryLanguage(index, note, entry),
+        corpus.words,
+        corpus.families,
+    );
+    return own;
 }
 
 /**
  * Warn of an affiliation that reaches no culture, its own or one it inherits,
- * in a tree that describes peoples.
+ * in a tree that describes peoples. Its ranks and offices then have no
+ * culture associations for term queries.
  *
  * @param {object} note - An `affiliation` note.
  * @param {{index?: object}} [context]
@@ -323,7 +350,7 @@ export function checkAffiliationReach(note, { index } = {}) {
             severity: "warning",
             message:
                 "this affiliation reaches no culture, its own or one inherited through " +
-                "`data.parents`, so its ranks, offices and language enter no culture's glossary; " +
+                "`data.parents`, so its ranks and offices have no culture associations for term queries; " +
                 "state `data.culture`",
         },
     ];

package/engine/data-keys.mjs

@@ -70,6 +70,8 @@ import { nearest } from "./near-miss.mjs";
  *   every surface shows it exactly as written, never recased.
  * @property {string} shape - The shape in words, for a finding and the reference.
  * @property {boolean} [required] - The key must be stated, with a value.
+ * @property {boolean} [allowEmpty] - A required string may be empty where
+ *   empty text is a stated value.
  * @property {boolean} [nullable] - An explicit `null` states the key, for a
  *   required key whose null has a meaning of its own.
  * @property {string} [label] - The infobox row label, where humanising the key
@@ -234,7 +236,7 @@ export function pathLabel(path) {
 function stated(value, spec) {
     if (value === undefined) return false;
     if (value === null) return Boolean(spec.nullable);
-    if (typeof value === "string") return value.trim() !== "";
+    if (typeof value === "string") return Boolean(spec.allowEmpty) || value.trim() !== "";
     return true;
 }
 

package/engine/dictionary-layout.mjs

@@ -22,18 +22,21 @@
  * surface sets it as it sets a note:
  *
  * - **the key**, once, at the head unless the fence sets `key=false`: the abbreviations this rendering uses,
- *   each with its expansion, then the common mark where an entry carries it.
+ *   each with its expansion, then a glossary's common mark where an entry carries it.
  *   A fence setting `key=only` prints the key alone;
  * - **a heading per letter**, from `letter`, at the fence's `section-level`;
  * - **one paragraph per entry**: the common mark, the bold headword, the
- *   pronunciation between slashes, the language tag (and for a word its
- *   class) in italics, a word's etymology in brackets, the senses, and the
+ *   pronunciation between slashes, the language tag and word class in
+ *   italics, a dictionary word's field tag and etymology in brackets, the senses, and the
  *   citations as links.
  *
  * A glossary sets the rows that share a headword and a language as one entry:
  * their senses numbered in the order the rows arrive, each tagged with the
- * bodies it comes from, a sense several rows give printed once with all of
- * them. A word's senses carry no bodies, and a glossary's always do.
+ * bodies it comes from, except a sole owner's label on its own page. A sense
+ * several rows give is printed once with all its bodies. A dictionary word's
+ * senses carry no bodies; a glossary's contextual
+ * and governance senses name their owners. A glossary headword naming a
+ * dictionary word links to that word's anchored entry on its language page.
  *
  * The entries are ordered here rather than by the query: by letter, then by
  * `name_sort` with its accents taken off and its case folded, then as written.
@@ -43,8 +46,9 @@
  * @module
  */
 
-import { parseAddress, renderAddress } from "./address.mjs";
-import { dictionaryLetter } from "./dictionary-rows.mjs";
+import { parseAddress, readCanonicalKey, renderAddress, splitAnchor } from "./address.mjs";
+import { dictionaryEntryAnchor, dictionaryLetter } from "./dictionary-rows.mjs";
+import { VERB_PERSON_FIELDS } from "./language-terms.mjs";
 import {
     WORD_CLASS_BASES,
     WORD_CLASS_MODIFIERS,
@@ -61,6 +65,50 @@ export const LAYOUT_REQUIRED_COLUMNS = Object.freeze({
 /** The mark a common entry opens with. */
 export const COMMON_MARK = "•";
 
+/** The word-entry span class whose Foundry rendering is a native TOC heading. */
+export const DICTIONARY_ENTRY_CLASS = "dictionary-entry";
+
+/**
+ * Render a dictionary entry's marked headword as an inline native heading in
+ * Foundry. Its paragraph becomes a div, so the heading has a valid container.
+ * The shared Markdown keeps its span and its containing journal page.
+ *
+ * @param {import("markdown-it")} md - The Foundry Markdown parser.
+ */
+export function dictionaryEntryPlugin(md) {
+    md.core.ruler.after("inline", "dictionary_entry_headings", (state) => {
+        for (let i = 1; i < state.tokens.length - 1; i++) {
+            const inline = state.tokens[i];
+            const opening = inline.children?.[0];
+            if (
+                inline.type !== "inline" ||
+                state.tokens[i - 1].type !== "paragraph_open" ||
+                state.tokens[i + 1].type !== "paragraph_close" ||
+                opening?.type !== "span_open" ||
+                !opening.attrGet("id") ||
+                !String(opening.attrGet("class") ?? "")
+                    .split(/\s+/)
+                    .includes(DICTIONARY_ENTRY_CLASS)
+            )
+                continue;
+            let depth = 0;
+            const closing = inline.children.find((token) => {
+                if (token.type === "span_open") depth++;
+                if (token.type === "span_close") return --depth === 0;
+                return false;
+            });
+            if (!closing) continue;
+            opening.tag = closing.tag = "h6";
+            opening.attrSet(
+                "style",
+                "display: inline; margin: 0; padding: 0; border: 0; font: inherit; text-transform: none",
+            );
+            state.tokens[i - 1].tag = state.tokens[i + 1].tag = "div";
+            state.tokens[i - 1].attrSet("style", "margin: 0 0 0.5em");
+        }
+    });
+}
+
 /** What the key says of the common mark. */
 const COMMON_KEY = "a common word, which a player is expected to know by heart";
 
@@ -93,10 +141,16 @@ function sentence(text) {
  * @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 {boolean|"only"} [showKey=true] - Whether the key and dictionary
+ *   head tables are 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.
+ * @property {string} [pageOwner] - The containing page's canonical note Address;
+ *   a sense attributed only to its own row's owner omits that label on this page.
+ * @property {boolean} [entryAnchors=true] - Whether dictionary headwords carry
+ *   their canonical targets; custom SQL views leave those to the automatic list.
+ * @property {object} [verbs] - The owning language's stated pattern, including
+ *   when its automatic dictionary has no eligible word entries.
  */
 
 /**
@@ -114,9 +168,56 @@ export function renderDictionary(result, opts = {}) {
         result.rows.map((row) => ({ ...row, rows: [row] })),
         opts,
         true,
+        verbTables(result.rows, opts),
     );
 }
 
+/** A table cell cannot carry a literal pipe or a line break. */
+const verbCell = (text) =>
+    String(text)
+        .replace(/\|/g, "\\|")
+        .replace(/[\r\n]+/g, " ");
+
+/** One head table per represented language, with no forms invented for a word. */
+function verbTables(rows, opts) {
+    const patterns = new Map();
+    for (const row of rows)
+        if (row.verbs && typeof row.verbs === "object")
+            patterns.set(row.language ?? opts.pageLanguage ?? "", {
+                verbs: row.verbs,
+                label: row.language_tag,
+            });
+    if (opts.verbs && !patterns.has(opts.pageLanguage ?? ""))
+        patterns.set(opts.pageLanguage ?? "", { verbs: opts.verbs });
+    const tables = [];
+    for (const [language, { verbs, label }] of [...patterns].sort(([a], [b]) => compare(a, b))) {
+        let endings;
+        if (verbs.invariant === true) endings = [["All persons", "unchanged"]];
+        else if (
+            VERB_PERSON_FIELDS.every((person) => typeof verbs.persons?.[person.name] === "string")
+        )
+            endings = VERB_PERSON_FIELDS.map((person) => [
+                person.label,
+                verbs.persons[person.name] ? `-${verbs.persons[person.name]}` : "unchanged",
+            ]);
+        else continue;
+        const title =
+            patterns.size > 1 ?
+                `**Verbs (${String(opts.labelOf?.(language) ?? label ?? language).replace(/[\r\n]+/g, " ")})**`
+            :   "**Verbs**";
+        tables.push(
+            [
+                title,
+                "",
+                "| Person | Ending added to citation form |",
+                "| --- | --- |",
+                ...endings.map((ending) => `| ${ending.map(verbCell).join(" | ")} |`),
+            ].join("\n"),
+        );
+    }
+    return tables.join("\n\n");
+}
+
 /**
  * Render a result of terms as a glossary.
  *
@@ -141,10 +242,18 @@ export function renderGlossary(result, opts = {}) {
                 for (const sense of Array.isArray(row.senses) ? row.senses : []) {
                     const same = senses.find((one) => one.text === sense?.text);
                     const bodies = Array.isArray(sense?.bodies) ? sense.bodies : [];
-                    if (!same) senses.push({ text: sense?.text, bodies: [...bodies] });
-                    else
+                    const omitBody = Boolean(
+                        opts.pageOwner &&
+                        row.owner === opts.pageOwner &&
+                        bodies.length === 1 &&
+                        bodies[0] === row.owner,
+                    );
+                    if (!same) senses.push({ text: sense?.text, bodies: [...bodies], omitBody });
+                    else {
+                        same.omitBody &&= omitBody;
                         for (const body of bodies)
                             if (!same.bodies.includes(body)) same.bodies.push(body);
+                    }
                 }
             for (const sense of senses) sense.bodies.sort(compare);
             const first = (column) =>
@@ -157,7 +266,8 @@ export function renderGlossary(result, opts = {}) {
                 pronunciation: first("pronunciation"),
                 name_sort: first("name_sort"),
                 letter: first("letter"),
-                class: undefined,
+                class: first("class"),
+                word: first("word"),
                 etymology: undefined,
             };
         }),
@@ -181,8 +291,9 @@ function requireColumns(result, layout) {
  *
  * @param {object[]} entries - One per entry, with the row columns.
  * @param {LayoutOptions} opts
- * @param {boolean} words - Whether the entries are words, with a class and an
- *   etymology.
+ * @param {boolean} words - Whether the entries are dictionary words, with
+ *   their own anchors and etymology.
+ * @param {string} [head] - Optional dictionary head tables.
  * @returns {string}
  */
 function render(
@@ -194,14 +305,17 @@ function render(
         labelOf = () => undefined,
         showKey = true,
         pageLanguage,
+        entryAnchors = true,
     },
     words,
+    head = "",
 ) {
     const label = (address) => labelOf(address) ?? address;
     const usedTags = new Map();
     const usedBases = new Set();
     const usedModifiers = new Set();
     let anyCommon = false;
+    let anyPlural = false;
 
     const cite = (address) => {
         const text = label(address);
@@ -236,25 +350,40 @@ function render(
             paragraphs.push(`${"#".repeat(sectionLevel)} ${letter}`);
         }
         const parts = [];
-        if (row.common === true) {
+        if (!words && row.common === true) {
             anyCommon = true;
             parts.push(COMMON_MARK);
         }
-        parts.push(`**${row.name}**`);
+        let headword = `**${row.name}**`;
+        if (words && entryAnchors && typeof row.language === "string")
+            headword = `[${headword}]{#${dictionaryEntryAnchor(row.language, row.name)} .${DICTIONARY_ENTRY_CLASS}}`;
+        else if (!words && typeof row.word === "string") {
+            const { address, anchor } = splitAnchor(row.word);
+            const ref = readCanonicalKey(address);
+            if (ref && anchor && linkable(ref))
+                headword = `**[[${renderAddress(ref)}#${anchor}|${String(row.name).replace(/\|/g, "/")}]]**`;
+        }
+        parts.push(headword);
         if (row.pronunciation) parts.push(`/${row.pronunciation}/`);
 
         const italic = [];
         if (row.language_tag && row.language !== pageLanguage)
             italic.push(tag(row.language, row.language_tag));
-        if (words && row.class) {
+        if (row.class) {
             const parsed = parseWordClass(row.class);
             if (!parsed.reason) {
                 usedBases.add(parsed.base);
                 for (const token of parsed.modifiers) usedModifiers.add(token);
-                italic.push(abbreviateWordClass(parsed));
+                let classification = abbreviateWordClass(parsed);
+                if (words && parsed.base === "n" && typeof row.plural === "string" && row.plural) {
+                    classification += `, pl. ${row.plural}`;
+                    anyPlural = true;
+                }
+                italic.push(classification);
             } else italic.push(String(row.class));
         }
         if (italic.length) parts.push(`_${italic.join(" ")}_`);
+        if (words && row.field) parts.push(`(_${row.field}_)`);
 
         if (words) {
             const bracket = etymologyText(row.etymology, row.language, tag);
@@ -264,7 +393,8 @@ function render(
         const senses = Array.isArray(row.senses) ? row.senses : [];
         const senseText = (sense) => {
             const bodies = Array.isArray(sense?.bodies) ? sense.bodies : [];
-            const by = bodies.length ? `(_${bodies.map(label).join(", ")}_) ` : "";
+            const by =
+                bodies.length && !sense.omitBody ? `(_${bodies.map(label).join(", ")}_) ` : "";
             return `${by}${sentence(sense?.text)}`;
         };
         if (senses.length === 1) parts.push(senseText(senses[0]));
@@ -287,9 +417,11 @@ function render(
     for (const modifier of WORD_CLASS_MODIFIERS)
         if (usedModifiers.has(modifier.token))
             key.push(`_${modifier.abbreviation}_ ${modifier.expansion}`);
+    if (anyPlural) key.push("_pl._ plural");
     if (anyCommon) key.push(`${COMMON_MARK} ${COMMON_KEY}`);
     const line = key.length ? `**Key:** ${key.join("; ")}.` : "";
     if (showKey === "only") return line;
+    if (showKey && head) paragraphs.unshift(head);
     if (showKey && line) paragraphs.unshift(line);
     return paragraphs.join("\n\n");
 }