@heroiclands/package-build 23.8.0 → 23.9.0

package/engine/sql-tables.mjs

@@ -26,7 +26,9 @@
  * @module
  */
 
-import { parseAddress, renderAddress, isAddressTuple } from "./address.mjs";
+import { parseAddress, readCanonicalKey, renderAddress, isAddressTuple } from "./address.mjs";
+import { collectAnchors } from "./anchors.mjs";
+import { expandContentTables } from "./content-tables.mjs";
 import { NOTE_VOCABULARY, isGmNote } from "./note-vocabulary.mjs";
 import { encodeAddresses, flattenPublishedAddresses } from "./address-values.mjs";
 import { EVENT_COLUMNS, EVENT_SORT_COLUMNS, eventRows } from "./event-rows.mjs";
@@ -45,8 +47,10 @@ import {
 } from "./word-rows.mjs";
 import { DICTIONARY_COLUMNS, TERM_COLUMNS, dictionaryAndTermRows } from "./dictionary-rows.mjs";
 import { LANGUAGE_COLUMN_TYPES, LANGUAGE_RELATIONS } from "./language-rows.mjs";
+import { VERB_PERSON_FIELDS } from "./language-terms.mjs";
 import { renderDictionary, renderGlossary } from "./dictionary-layout.mjs";
 import { glossaryLanguage } from "./glossary-language.mjs";
+import { lexicalSectionsFor } from "./lexical-sections.mjs";
 import { eventViewSections } from "./event-views.mjs";
 import { appendGeneratedSections, joinSections } from "./generated-sections.mjs";
 import fs from "node:fs";
@@ -60,7 +64,7 @@ import { MARKET_CLASSES } from "./market-class.mjs";
 import { parseMarkdownFile } from "./helpers.mjs";
 import { sqlQueriesInMarkdown } from "./markdown-expressions.mjs";
 // The record accessors only — see `engine/index-records.mjs`.
-import { isNoteRecord, noteFile, sortKeysDeep } from "./index-records.mjs";
+import { authoredFrontmatter, isNoteRecord, noteFile, sortKeysDeep } from "./index-records.mjs";
 
 /** Rendered in a cell whose value is absent. */
 const EMPTY_CELL = "—";
@@ -261,16 +265,12 @@ export async function openNotesDatabase(
     const base = dir ?? fs.mkdtempSync(path.join(os.tmpdir(), "content-sql-"));
     fs.mkdirSync(base, { recursive: true });
     const jsonl = path.join(base, "notes.jsonl");
-    fs.writeFileSync(
-        jsonl,
-        records.map((record) => JSON.stringify(sortKeysDeep(encodeAddresses(record)))).join("\n"),
-    );
+    const encoded = records.map((record) => encodeAddresses(record));
 
     const instance = await DuckDBInstance.create(":memory:");
     const connection = await instance.connect();
     await connection.run("SET threads=1");
-    await createRelations(connection, jsonl, "", audience);
-    const encoded = records.map((record) => encodeAddresses(record));
+    await createRelations(connection, jsonl, encoded, "", audience);
     await createEventRelation(connection, path.join(base, "events.jsonl"), encoded, "", audience);
     await createWordRelations(connection, path.join(base, "notes"), encoded, "", audience);
 
@@ -293,8 +293,7 @@ export async function openNotesDatabase(
             .split("\n")
             .filter((line) => line.trim())
             .map((line) => flattenPublishedAddresses(JSON.parse(line)));
-        fs.writeFileSync(flat, depRecords.map((record) => JSON.stringify(record)).join("\n"));
-        await createRelations(connection, flat, `${schema}.`, audience);
+        await createRelations(connection, flat, depRecords, `${schema}.`, audience);
         await createEventRelation(
             connection,
             flat.replace(/\.jsonl$/, "-events.jsonl"),
@@ -462,12 +461,27 @@ const WITH_STUBS_SCHEMA = "__with_stubs";
  * of the ladder falls back to a constant where its column is absent.
  *
  * @param {object} connection - An open DuckDB connection.
- * @param {string} file - The JSONL to read.
+ * @param {string} file - Where to write the audience's JSONL.
+ * @param {object[]} records - Complete index records, every Address a string.
  * @param {string} [prefix] - A schema to qualify the view names with.
+ * @param {"all"|"public"} [audience] - Whether to leave out GM notes.
  * @returns {Promise<void>}
  */
-async function createRelations(connection, file, prefix = "", audience = "all") {
-    const read = readJsonAuto(file);
+async function createRelations(connection, file, records, prefix = "", audience = "all") {
+    // Every record contributes its schema; only visible records contribute rows.
+    fs.writeFileSync(
+        file,
+        records
+            .map((record) =>
+                JSON.stringify({
+                    record: sortKeysDeep(record),
+                    visible: audience !== "public" || !isGmNote(record),
+                }),
+            )
+            .join("\n"),
+    );
+    const source = readJsonAuto(file);
+    const read = records.length ? `SELECT record.* FROM (${source}) WHERE visible` : source;
     const described = await connection.runAndReadAll(`DESCRIBE ${read}`);
     const columns = new Set(described.getRowObjects().map((row) => String(row.column_name)));
     // A row with no address is a stub. With no address column anywhere, every
@@ -481,16 +495,11 @@ async function createRelations(connection, file, prefix = "", audience = "all")
             "COALESCE(list_contains(TRY_CAST(tags AS VARCHAR[]), 'draft'), false) " +
             "OR COALESCE(TRY_CAST(tags AS VARCHAR) = 'draft', false)"
         :   "false";
-    const visible =
-        audience === "public" && columns.has("tags") ?
-            "NOT (COALESCE(list_contains(TRY_CAST(tags AS VARCHAR[]), 'gm'), false) " +
-            "OR COALESCE(TRY_CAST(tags AS VARCHAR) = 'gm', false))"
-        :   "true";
     await createTableFromFile(
         connection,
         `${prefix}entries`,
         `SELECT *, CASE WHEN ${stub} THEN 'stub' WHEN ${draft} THEN 'draft' ` +
-            `ELSE 'full' END AS state FROM (${read}) WHERE ${visible}`,
+            `ELSE 'full' END AS state FROM (${read})`,
     );
     await connection.run(
         `CREATE VIEW ${prefix}notes AS SELECT * FROM ${prefix}entries WHERE state <> 'stub'`,
@@ -617,20 +626,68 @@ async function createWordRelations(connection, stem, records, prefix, audience)
         LINEAGE_COLUMNS,
     );
     const { dictionary, terms } = dictionaryAndTermRows(visible, records);
-    await createRowRelation(
-        connection,
-        `${stem}-dictionary.jsonl`,
-        dictionary,
-        `${prefix}dictionary`,
-        DICTIONARY_COLUMNS,
-    );
-    await createRowRelation(
-        connection,
-        `${stem}-terms.jsonl`,
-        terms,
-        `${prefix}terms`,
-        TERM_COLUMNS,
-    );
+    const dictionaryTypes = {
+        etymology:
+            "STRUCT(kind VARCHAR, language VARCHAR, language_tag VARCHAR, form VARCHAR, " +
+            "parts STRUCT(form VARCHAR, gloss VARCHAR)[], root VARCHAR, frame VARCHAR)",
+        senses: "STRUCT(text VARCHAR, bodies VARCHAR[])[]",
+        usage: "VARCHAR[]",
+        depth: "BIGINT",
+        verbs: `STRUCT(invariant BOOLEAN, persons STRUCT(${VERB_PERSON_FIELDS.map((person) => `"${person.name}" VARCHAR`).join(", ")}))`,
+    };
+    const dictionaryFile = `${stem}-dictionary.jsonl`;
+    if (dictionary.length) {
+        // Only the dictionary's declared schema: optional patterns must not
+        // change its nested/list types when a corpus has no stated grammar.
+        fs.writeFileSync(dictionaryFile, dictionary.map((row) => JSON.stringify(row)).join("\n"));
+        const columns = DICTIONARY_COLUMNS.map(
+            (column) =>
+                `CAST("${column}" AS ${dictionaryTypes[column] ?? "VARCHAR"}) AS "${column}"`,
+        );
+        await createTableFromFile(
+            connection,
+            `${prefix}dictionary`,
+            `SELECT ${columns.join(", ")} FROM (${readJsonAuto(dictionaryFile)})`,
+        );
+    } else {
+        await createRowRelation(
+            connection,
+            dictionaryFile,
+            dictionary,
+            `${prefix}dictionary`,
+            DICTIONARY_COLUMNS,
+            dictionaryTypes,
+        );
+    }
+    const termTypes = {
+        senses: "STRUCT(text VARCHAR, bodies VARCHAR[])[]",
+        usage: "VARCHAR[]",
+        common: "BOOLEAN",
+        origins: "VARCHAR[]",
+        cultures: "VARCHAR[]",
+    };
+    const termsFile = `${stem}-terms.jsonl`;
+    if (terms.length) {
+        // Terms retain declared types even when every value of a column is null.
+        fs.writeFileSync(termsFile, terms.map((row) => JSON.stringify(row)).join("\n"));
+        const columns = TERM_COLUMNS.map(
+            (column) => `CAST("${column}" AS ${termTypes[column] ?? "VARCHAR"}) AS "${column}"`,
+        );
+        await createTableFromFile(
+            connection,
+            `${prefix}terms`,
+            `SELECT ${columns.join(", ")} FROM (${readJsonAuto(termsFile)})`,
+        );
+    } else {
+        await createRowRelation(
+            connection,
+            termsFile,
+            terms,
+            `${prefix}terms`,
+            TERM_COLUMNS,
+            termTypes,
+        );
+    }
     for (const [name, rowsOf, columns] of LANGUAGE_RELATIONS)
         await createRowRelation(
             connection,
@@ -953,6 +1010,20 @@ export async function prepareSqlTables(db, sources, { linkable, records, pageLan
                                 labelOf,
                                 showKey: block.showKey,
                                 pageLanguage: languageOf(source, frontmatter),
+                                pageOwner:
+                                    (
+                                        typeof frontmatter?.type === "string" &&
+                                        typeof frontmatter.shortcode === "string" &&
+                                        db.addressContext?.package
+                                    ) ?
+                                        renderAddress({
+                                            package: db.addressContext.package,
+                                            system: "note",
+                                            type: frontmatter.type,
+                                            shortcode: frontmatter.shortcode,
+                                        })
+                                    :   undefined,
+                                entryAnchors: false,
                             })
                         :   renderSqlTable(result, options),
                     rows: result.rows.length,
@@ -1108,8 +1179,11 @@ export async function prepareInlineSqlExpressions(db, sources) {
  * @param {Map<string, Map<string, string>>} [opts.derived] - The derived
  *   lists, from an earlier call over the same records, which are not derived
  *   again.
+ * @param {object[]} [opts.all=records] - Complete records for lexical lineage
+ *   traversal through providers outside the surface's audience.
  * @returns {Promise<{sections: Map<string, string>, views: Set<string>,
- *   derived: Map<string, Map<string, string>>}>} Note file to its sections,
+ *   derived: Map<string, Map<string, string>>,
+ *   lexical: Map<string, import("./lexical-sections.mjs").LexicalSection[]>}>} Note file to its sections,
  *   joined in order; the files whose sections hold an event view's fence; and
  *   the derived lists alone.
  */
@@ -1117,7 +1191,7 @@ export async function generatedSectionsFor(
     db,
     records,
     contentBase,
-    { only, foreignIndex, config, derived: given } = {},
+    { only, foreignIndex, config, derived: given, all = records } = {},
 ) {
     const notes = records.filter((record) => isNoteRecord(record));
     const fileOf = (record) => noteFile(contentBase, record);
@@ -1135,7 +1209,26 @@ export async function generatedSectionsFor(
     const sections = new Map();
     for (const file of new Set([...derived.keys(), ...views.keys()]))
         sections.set(file, joinSections([derived.get(file), views.get(file)]));
-    return { sections, views: new Set(views.keys()), derived };
+    // Automatic sections follow their source's audience even in a Foundry
+    // corpus containing both public and private packs. Explicit SQL keeps
+    // the database audience the caller requested.
+    const publicRecords = records.filter((record) => !isGmNote(record));
+    const publicOwners = lexicalSectionsFor(publicRecords, all);
+    const allOwners =
+        publicRecords.length === records.length ? publicOwners : lexicalSectionsFor(records, all);
+    const lexical = new Map();
+    for (const note of notes) {
+        const owners = isGmNote(note) ? allOwners : publicOwners;
+        const key = renderAddress({
+            package: note.package,
+            system: "note",
+            type: note.type,
+            shortcode: note.shortcode,
+        });
+        if (owners.has(key) && (only === undefined || fileOf(note) === only))
+            lexical.set(fileOf(note), owners.get(key));
+    }
+    return { sections, views: new Set(views.keys()), derived, lexical };
 }
 
 /**
@@ -1182,7 +1275,7 @@ export function joinGeneratedSections(generated, sources, parsed) {
  * empty set carrying them.
  *
  * @param {Map<string, object[]>} prepared - From {@link prepareSqlTables}.
- * @param {{sections: Map<string, string>}} generated - From
+ * @param {{sections: Map<string, string>, lexical?: Map<string, import("./lexical-sections.mjs").LexicalSection[]>}} generated - From
  *   {@link generatedSectionsFor}.
  * @returns {void}
  */
@@ -1192,6 +1285,51 @@ export function attachGeneratedSections(prepared, generated) {
         if (!results) prepared.set(absPath, (results = []));
         results.generated = text;
     }
+    for (const [absPath, sections] of generated.lexical ?? []) {
+        let results = prepared.get(absPath);
+        if (!results) prepared.set(absPath, (results = []));
+        results.lexical = sections;
+    }
+}
+
+/**
+ * Index the anchors the prepared bodies actually emit, including anchors in
+ * SQL results. Foundry maps use the same expanded body the compiler splits.
+ *
+ * @param {Map<string, object[]>} prepared - The prepared directives.
+ * @param {object[]} records - The visible content-index records.
+ * @param {string} contentBase - Root of the content tree.
+ * @param {Map<string, object>} parsed - Notes already parsed.
+ * @param {object} [config] - The resolved build configuration.
+ * @returns {Promise<void>}
+ */
+async function attachPreparedAnchors(prepared, records, contentBase, parsed, config) {
+    const { entriesForNote, foundryIdentities } = await import("./foundry-entries.mjs");
+    const identities = config ? foundryIdentities(config) : undefined;
+    for (const record of records) {
+        if (!isNoteRecord(record)) continue;
+        const file = noteFile(contentBase, record);
+        const results = prepared.get(file);
+        if (!results) continue;
+        const { body } = parsed.get(file) ?? parseMarkdownFile(file);
+        const expanded = expandContentTables(body, {
+            source: file,
+            sqlTables: results,
+            pageLists: prepared.pageLists?.get(file),
+        }).markdown;
+        results.anchors = collectAnchors(expanded);
+        if (!identities || !record.address?.slug) continue;
+        const frontmatter = authoredFrontmatter(record);
+        const entries = entriesForNote(
+            frontmatter,
+            frontmatter.name?.full ?? record.file.name,
+            record.address.slug,
+            expanded,
+            identities,
+        );
+        results.anchorUuids = entries[0]?.anchors;
+        results.docAnchorUuids = entries[1]?.anchors;
+    }
 }
 
 /**
@@ -1305,9 +1443,9 @@ export async function prepareTreeSqlTables(
     // uninitialised for whichever module the runtime happened to load first.
     const { indexRecordsFor } = await import("./content-index.mjs");
     const notes = parsed ?? new Map();
-    const indexRecords = (
-        records ?? indexRecordsFor({ contentBase, config, skipDirectories, parsed: notes })
-    ).filter((record) => audience !== "public" || !isGmNote(record));
+    const allRecords =
+        records ?? indexRecordsFor({ contentBase, config, skipDirectories, parsed: notes });
+    const indexRecords = allRecords.filter((record) => audience !== "public" || !isGmNote(record));
 
     // Which notes carry a directive, discovered over the same corpus every
     // other pass reads rather than over a walk of this one's own. The
@@ -1354,8 +1492,10 @@ export async function prepareTreeSqlTables(
     const derivedOnly = await generatedSectionsFor(undefined, indexRecords, contentBase, {
         foreignIndex: foreign,
         config,
+        all: allRecords,
     });
-    if (!sources.length && !hasEvents && !derivedOnly.sections.size) return undefined;
+    if (!sources.length && !hasEvents && !derivedOnly.sections.size && !derivedOnly.lexical.size)
+        return undefined;
 
     // A page list is a filter over the records, so it needs no database. A tree
     // whose only corpus-reading directive is one therefore opens none — which
@@ -1374,6 +1514,7 @@ export async function prepareTreeSqlTables(
         pageOnly.inline = new Map();
         pageOnly.pageLists = preparePageLists(indexRecords, sources);
         attachGeneratedSections(pageOnly, derivedOnly);
+        await attachPreparedAnchors(pageOnly, indexRecords, contentBase, notes, config);
         return pageOnly;
     }
     // A cell links only where the address it would emit resolves, so a table
@@ -1388,7 +1529,11 @@ export async function prepareTreeSqlTables(
             .filter((record) => !record.documents)
             .map((record) => record.documentation ?? record.address?.canonical)
             .map((target) => target && encodeAddresses(target))
-            .filter(Boolean),
+            .filter(Boolean)
+            .flatMap((target) => [
+                target,
+                renderAddress({ ...readCanonicalKey(target), system: "note" }),
+            ]),
     );
     // Each declared dependency's published index, attached as its own schema so
     // a table can read `FROM <package>.notes`. Imported here for the
@@ -1397,13 +1542,14 @@ export async function prepareTreeSqlTables(
     // been fetched already fails earlier with a message naming the fetch.
     const db =
         database ??
-        (await openNotesDatabase(indexRecords, {
+        (await openNotesDatabase(allRecords, {
             dependencies: await cachedDependencies(config),
             audience,
         }));
     try {
         const generated = await generatedSectionsFor(db, indexRecords, contentBase, {
             derived: derivedOnly.derived,
+            all: allRecords,
         });
         joinGeneratedSections(generated, sources, notes);
         const prepared = await prepareSqlTables(db, sources, {
@@ -1413,8 +1559,81 @@ export async function prepareTreeSqlTables(
         });
         prepared.inline = await prepareInlineSqlExpressions(db, sources);
         attachGeneratedSections(prepared, generated);
+        await attachPreparedAnchors(prepared, indexRecords, contentBase, notes, config);
         return prepared;
     } finally {
         if (!database) await db.close();
     }
 }
+
+/**
+ * Prepare authored link-check tables in each source note's audience. Public
+ * sources share one public database; GM sources share one complete database.
+ * Complete records remain available for authored-link checks.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {object} [opts.config] - Resolved configuration.
+ * @param {readonly string[]} [opts.skipDirectories] - The walk's scope.
+ * @param {object[]} [opts.records] - Complete index records already derived.
+ * @param {Map<string, {body: string, frontmatter: object|null}>} [opts.parsed] - Parsed notes.
+ * @param {Map<string, object>} [opts.foreignIndex] - Published dependency indexes.
+ * @returns {Promise<Map<string, object[]>|undefined>} Prepared tables by source.
+ */
+export async function prepareLinkSqlTables(
+    contentBase,
+    { config, skipDirectories, records, parsed, foreignIndex } = {},
+) {
+    const { indexRecordsFor } = await import("./content-index.mjs");
+    const notes = parsed ?? new Map();
+    const allRecords =
+        records ?? indexRecordsFor({ contentBase, config, skipDirectories, parsed: notes });
+    const sources = new Map();
+    const lexicalOwners = lexicalSectionsFor(allRecords);
+    for (const record of allRecords) {
+        if (!isNoteRecord(record)) continue;
+        const file = noteFile(contentBase, record);
+        let note = notes.get(file);
+        if (!note) {
+            note = parseMarkdownFile(file);
+            notes.set(file, note);
+        }
+        const body = note.body ?? "";
+        if (
+            findSqlBlocks(body).length ||
+            findPageListBlocks(body).length ||
+            sqlQueriesInMarkdown(body, note.frontmatter).length ||
+            lexicalOwners.has(
+                renderAddress({
+                    package: record.package,
+                    system: "note",
+                    type: record.type,
+                    shortcode: record.shortcode,
+                }),
+            )
+        )
+            sources.set(file, isGmNote(record) ? "all" : "public");
+    }
+    if (!sources.size) return undefined;
+    const selected = new Map();
+    selected.pageLists = new Map();
+    selected.inline = new Map();
+    for (const audience of new Set(sources.values())) {
+        const prepared = await prepareTreeSqlTables(contentBase, {
+            config,
+            skipDirectories,
+            records: allRecords,
+            parsed: notes,
+            foreignIndex,
+            audience,
+        });
+        for (const [file, sourceAudience] of sources) {
+            if (sourceAudience !== audience) continue;
+            if (prepared?.has(file)) selected.set(file, prepared.get(file));
+            if (prepared?.pageLists?.has(file))
+                selected.pageLists.set(file, prepared.pageLists.get(file));
+            if (prepared?.inline?.has(file)) selected.inline.set(file, prepared.inline.get(file));
+        }
+    }
+    return selected;
+}

package/engine/stub-lint.mjs

@@ -12,14 +12,16 @@
  */
 
 /**
- * Every typed note needs a nonempty body.
+ * Every typed note needs content: an authored body or automatic lexical data.
  *
- * A missing or whitespace-only body is an error, whether or not the note has
+ * Without automatic lexical data, a missing or whitespace-only body is an error, whether or not the note has
  * a `draft` tag or a frontmatter description. Placeholder-only bodies remain
  * errors. A nonempty body below twenty-five words receives a warning when it
  * is not tagged `draft`; the author decides whether that short note is done.
  * A `folder` note is held only to the first rule: any nonempty body passes,
  * with or without `draft`.
+ * A language's nonempty `words`, or a culture's or affiliation's nonempty
+ * `glossary`, supplies an automatic section and needs no authored prose.
  *
  * Counts and the oldest drafts remain reports. Classification and indexing
  * still derive full, draft and stub states from the existing note records;
@@ -36,6 +38,7 @@ import { positionInFrontmatter, positionOfLiteral } from "./diagnostics.mjs";
 import { parseMarkdownFile } from "./helpers.mjs";
 import { bodyWordCount, placeholderBody } from "./note-state.mjs";
 import { isDraftNote } from "./note-vocabulary.mjs";
+import { hasLexicalEntries } from "./lexical-sections.mjs";
 
 /**
  * The word count below which an unmarked body is asked whether it is a draft.
@@ -62,6 +65,7 @@ function checkNote({ fm, body, file, raw }) {
     const at = (key, value) => positionInFrontmatter(raw, key, value, { topLevel: true });
 
     if (String(body ?? "").trim() === "") {
+        if (hasLexicalEntries(fm)) return findings;
         findings.push({
             file,
             ...at("type", fm.type),

package/engine/web-wikilinks.mjs

@@ -73,12 +73,12 @@ import { resolveEmbeds } from "./content-embeds.mjs";
 /**
  * Whether a page's declared anchors include the slug a link names.
  *
- * A local page's entry carries a `Set` (built by {@link module:engine/site-index});
- * a foreign one carries the `{slug: uuid}` map a fetched manifest publishes.
- * `undefined` means neither build recorded an answer, which keeps a target
- * this check cannot speak for exactly as unchecked as it always was.
+ * A local page carries a `Set` built by {@link module:engine/site-index}.
+ * A foreign page declares prose anchors in its note metadata, independently
+ * of whether it has a Foundry target map. An empty collection declares none.
+ * An absent collection leaves the target unchecked.
  *
- * @param {Set<string>|Record<string, string>|undefined} anchors - The page's
+ * @param {Set<string>|Record<string, string>|Array<{slug: string, kind: string}>|undefined} anchors - The page's
  *   declared anchors, or `undefined` where none were recorded.
  * @param {string} slug - The anchor a link names.
  * @returns {boolean} Whether the anchor is declared, or `true` when `anchors`
@@ -87,6 +87,8 @@ import { resolveEmbeds } from "./content-embeds.mjs";
  */
 function hasAnchor(anchors, slug) {
     if (!anchors) return true;
+    if (Array.isArray(anchors))
+        return anchors.some((anchor) => anchor.kind === "prose" && anchor.slug === slug);
     return anchors instanceof Set ? anchors.has(slug) : Object.hasOwn(anchors, slug);
 }
 
@@ -478,7 +480,7 @@ export function resolveWebWikilinks(body, ctx) {
                     label ?? hit.name ?? target,
                 );
             }
-            if (anchor && hit.url && !hasAnchor(hit.anchors, anchor)) {
+            if (anchor && hit.url && !hasAnchor(hit.noteAnchors ?? hit.anchors, anchor)) {
                 return report(
                     all,
                     { target, reason: "unknown-anchor", anchor, addressed: true },

package/engine/word-rows.mjs

@@ -82,15 +82,17 @@ 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 the words (stems included)
- * and affixes of one or more languages.
+ * A lookup from a built piece to its gloss, over the words (stems included),
+ * affixes and elements of one or more languages.
  *
- * 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
+ * For each spelling, languages are given nearest first: a language's own
+ * words, then its affixes and elements, then the next language's. A piece
+ * matches an exact spelling across the lineage first, and failing that one
+ * written with the same letters and different joining hyphens, so
  * `wulf-` finds the word `wulf`. Within a language a word's own gloss wins over
- * an affix's.
+ * an affix's, and both precede an element's sense. Elements also match their
+ * declared variants; affixes also match their front-vowel forms. Spelling,
+ * including case and accents, is preserved.
  *
  * @param {...object} datas - Each language note's `data`, nearest first.
  * @returns {(piece: string) => string|null} The gloss, or `null` where none resolves.
@@ -98,18 +100,24 @@ const bare = (form) => String(form).replace(/^-+|-+$/g, "");
 export function pieceGlosses(...datas) {
     const exact = new Map();
     const loose = new Map();
-    const take = (entries) => {
+    const take = (entries, key = "gloss", alternateKey = "") => {
         for (const entry of Array.isArray(entries) ? entries : []) {
             if (!isMap(entry) || typeof entry.form !== "string") continue;
-            const gloss = glossText(entry.gloss);
+            const gloss = glossText(entry[key]);
             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);
+            const alternate = entry[alternateKey];
+            const forms = [entry.form, ...(Array.isArray(alternate) ? alternate : [alternate])];
+            for (const form of forms) {
+                if (typeof form !== "string") continue;
+                if (!exact.has(form)) exact.set(form, gloss);
+                if (!loose.has(bare(form))) loose.set(bare(form), gloss);
+            }
         }
     };
     for (const data of datas) {
         take(data?.words);
-        take(data?.affixes);
+        take(data?.affixes, "gloss", "front");
+        take(data?.elements, "sense", "variants");
     }
     return (piece) => exact.get(piece) ?? loose.get(bare(piece)) ?? null;
 }

package/engine/word-terms.mjs

@@ -136,12 +136,20 @@ export const WORD_FIELDS = Object.freeze([
             "A class from the master word classes: a base, then the modifiers the language " +
             "declares in `classModifiers`.",
     }),
+    Object.freeze({
+        name: "plural",
+        kind: "string",
+        shape: "a string",
+        describe:
+            "The noun's explicit plural, where it differs from the language's optional plural " +
+            "rule. A dictionary uses this form before the rule; no rule agreement is checked.",
+    }),
     Object.freeze({
         name: "field",
         kind: "string",
         required: true,
         shape: "one of the language's `fields` names",
-        describe: "The field the word is grouped under, named in the language's `fields`.",
+        describe: "The field tag beside the dictionary entry, named in the language's `fields`.",
     }),
     Object.freeze({
         name: "gloss",
@@ -376,27 +384,28 @@ export const GLOSSARY_ENTRY_FIELDS = Object.freeze([
         name: "name_sort",
         kind: "string",
         shape: "a string",
-        describe: "Its sort key; the name when unstated.",
+        describe: "Its sort key; the dictionary word's sort key, or the name, when unstated.",
     }),
     Object.freeze({
         name: "common",
         kind: "boolean",
         shape: "`true` or `false`",
-        describe: "A word a player is expected to know by heart; `false` when unstated.",
+        describe: "Core vocabulary for this glossary's owner; `false` when unstated.",
     }),
     Object.freeze({
         name: "definition",
         kind: "string",
         shape: "a string",
         describe:
-            "The sense text. Stated, it creates the entry or replaces every sense the " +
-            "entry's other sources give it.",
+            "The sense text, overriding the word's or governance sources' senses. Unstated, " +
+            "a named dictionary word supplies all its senses and class; a named rank or office supplies its descriptions.",
     }),
     Object.freeze({
         name: "pronunciation",
         kind: "string",
         shape: "a respelling such as `sol-MEH-reh`",
-        describe: "A respelling, held to the same rule as a word's.",
+        describe:
+            "A respelling, held to the same rule as a word's; the dictionary word's when unstated.",
     }),
     Object.freeze({
         name: "language",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.8.0",
+    "version": "23.9.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",