@heroiclands/package-build 23.7.1 → 23.9.0

package/engine/foundry-entries.mjs

@@ -78,6 +78,8 @@ import { isHomepage } from "./homepage.mjs";
 import { declaresNoPack } from "./pack-router.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
 import { collectAnchors } from "./anchors.mjs";
+import { scanSpans } from "./content-spans.mjs";
+import { DICTIONARY_ENTRY_CLASS } from "./dictionary-layout.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
@@ -94,7 +96,9 @@ import { publishesContentPages } from "../content-config.mjs";
 export const LEAD_ANCHOR = "$lead";
 
 /**
- * Every page of a note's journal, as `anchorName → whole UUID`.
+ * Every anchor of a note's journal, as `anchorName → Foundry target`.
+ * A dictionary word's native heading carries its fragment after the
+ * containing page's UUID.
  *
  * Whole, not a fragment appended to the entry's UUID: nothing owns a page
  * address, so a complete link restates no fact, and it keeps the page-id hash
@@ -112,9 +116,20 @@ export function anchorsOf(entryUuid, entryId, body, name) {
     const anchors = {};
     splitPages(body, name).forEach((page, index) => {
         const uuid = pageUuid(entryUuid, journalPageId(entryId, page));
+        const words = new Set(
+            scanSpans(page.markdown)
+                .spans.filter((span) =>
+                    span.attrs.some(
+                        ([key, value]) =>
+                            key === "class" && value.split(/\s+/).includes(DICTIONARY_ENTRY_CLASS),
+                    ),
+                )
+                .map((span) => span.id),
+        );
         if (index === 0) anchors[LEAD_ANCHOR] = uuid;
         if (page.anchorSlug) anchors[page.anchorSlug] = uuid;
-        for (const anchor of collectAnchors(page.markdown)) anchors[anchor.slug] = uuid;
+        for (const anchor of collectAnchors(page.markdown))
+            anchors[anchor.slug] = words.has(anchor.slug) ? `${uuid}#${anchor.slug}` : uuid;
     });
     return anchors;
 }
@@ -290,7 +305,10 @@ export function entriesForNote(fm, name, address, body, ctx) {
             id: fm.id,
             uuid: own,
             systemUuids: systemUuidsFor(fm.type, fm.id),
-            anchors: own && fm.type === "doc" ? anchorsOf(own, fm.id, body ?? "", name) : undefined,
+            anchors:
+                own && packForType(fm.type)?.docType === "JournalEntry" ?
+                    anchorsOf(own, fm.id, body ?? "", name)
+                :   undefined,
         },
     ];
 }

package/engine/frontmatter-lint.mjs

@@ -1541,7 +1541,7 @@ export function lintNote(
         for (const field of fields) {
             if (note.inheritedCultureFields?.has(field.name)) continue;
             if (typeof field.check !== "function") continue;
-            findings.push(...field.check(note, { index }));
+            findings.push(...field.check(note, { index, addressContext: referenceContext }));
         }
         // A check the type declares of the whole note, with the same index.
         if (typeof entry.check === "function") findings.push(...entry.check(note, { index }));

package/engine/generate.mjs

@@ -38,7 +38,7 @@
  * The HeroicLands vault is not a build input for SoHL content.
  */
 
-import { noteAddressContext } from "./note-addresses.mjs";
+import { noteAddressContext, decodeNoteAddresses } from "./note-addresses.mjs";
 import { GENERATED_DRAWING_DIR } from "./generated-sections.mjs";
 import fs from "fs";
 import path from "path";
@@ -54,7 +54,7 @@ import { Hm3Actors } from "../hm3/actors.mjs";
 import { Macros } from "./macros.mjs";
 import { Scenes } from "./scenes.mjs";
 import { Bundles } from "./bundles.mjs";
-import { statsForPack, parseMarkdownFile, folderFilename } from "./helpers.mjs";
+import { statsForPack, folderFilename } from "./helpers.mjs";
 import {
     buildFolderNoteIndex,
     collectFolderNotes,
@@ -800,7 +800,10 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
     // every type a system deliberately does not map, which is exactly the
     // silence the rule requires. Independent of `only`, since it is a fact about the
     // configured pack list rather than about which passes this run executes.
-    const unclaimed = unclaimedNoteFindings(config, undefined, { records: corpus.records });
+    const unclaimed = unclaimedNoteFindings(config, undefined, {
+        records: corpus.records,
+        parsed: corpus.parsed,
+    });
     for (const finding of unclaimed) emitDiagnostic(finding);
 
     fs.mkdirSync(config.paths.packJson, { recursive: true });
@@ -831,22 +834,8 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
     try {
         folderNotes = buildFolderNoteIndex(
             collectFolderNotes(
-                // The corpus this compile derived picks the notes; the
-                // file supplies their frontmatter, and this is one of the few
-                // places where that distinction is load-bearing rather than
-                // incidental.
-                //
-                // `collectFolderNotes` treats `fm.id` as an **authored pin**,
-                // which wins over the id it derives under the folder namespace.
-                // A record's `id` is not that: the index fills it in for every
-                // addressable note, so handing records straight over
-                // would make every folder look pinned. The *value*
-                // would be right either way — the index derives a folder's id
-                // under the folder namespace, so the two agree — but `derivedId`
-                // would not, and it is what tells an author whether a duplicate
-                // id was two pins or two addresses. The index cannot tell a pin
-                // from a derivation, so the note is read — and only folder notes
-                // are, 79 of `sohl`'s 1,685 rather than all of them.
+                // Folder pins are authored ids; index-derived ids must not
+                // turn an unpinned folder into a pinned one.
                 corpus.records
                     .filter(
                         (record) =>
@@ -856,9 +845,10 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
                     .map((record) => {
                         const absPath = noteFile(contentBase, record);
                         return {
-                            frontmatter: parseMarkdownFile(absPath, {
-                                addressContext: noteAddressContext(config),
-                            }).frontmatter,
+                            frontmatter: decodeNoteAddresses(
+                                structuredClone(corpus.parsed.get(absPath).frontmatter),
+                                noteAddressContext(config),
+                            ),
                             absPath,
                         };
                     }),

package/engine/glossary-entries.mjs

@@ -16,12 +16,12 @@
  * `lore` note of `subType: culture` or on an `affiliation`, a list of
  * `{ name, name_sort?, common?, definition?, pronunciation?, language? }`.
  *
- * It holds the terms that belong to the people or body using them rather than
- * to a language's grammar: euphemisms, idioms, terms of art, and titles that
- * are not ranks. An entry with a `definition` creates a term or replaces every
- * sense the term's other sources give it. An entry without one changes no
- * sense, and only marks a term the note already has — a word of a language
- * that reaches it, or a rank or office — as common, sorted or pronounced.
+ * An entry chooses a common word, gives a dictionary word a contextual
+ * meaning, or defines a phrase, compound or term of art. An entry naming a
+ * word of its resolved language carries that word's senses and class unless
+ * its own `definition` supplies the sense. A rank or office can also be named.
+ * Common marks, sort keys and pronunciation overrides belong to the entry's
+ * own glossary.
  *
  * The shape is the inner-key check's; this check owns what an entry means:
  *
@@ -88,7 +88,7 @@ export function checkGlossary(note, { index } = {}) {
     if (!Array.isArray(data.glossary)) return [];
 
     const findings = [];
-    const terms = index?.notes ? noteTerms(index, note) : undefined;
+    const hasTerms = Boolean(index?.notes);
     const seen = new Set();
     data.glossary.forEach((entry, i) => {
         if (!isMap(entry) || typeof entry.name !== "string" || !entry.name.trim()) return;
@@ -116,7 +116,7 @@ export function checkGlossary(note, { index } = {}) {
                     ),
                 );
         }
-        if (!terms) return;
+        if (!hasTerms) return;
         const stated = entry.language !== undefined && entry.language !== null;
         const named = stated ? languageProblem(index, entry.language) : undefined;
         if (named) findings.push(at([i, "language"], "error", named));
@@ -133,15 +133,15 @@ export function checkGlossary(note, { index } = {}) {
                         "; state `language` on the entry or `data.language` on the note",
                 ),
             );
-        const senses = terms.get(name);
+        const senses = noteTerms(index, note, entry).get(name);
         const defined = typeof entry.definition === "string" && entry.definition.trim() !== "";
         if (!defined && !senses)
             findings.push(
                 at(
                     [i, "name"],
                     "error",
-                    `\`${entry.name}\` names nothing: it is no word of a language that reaches ` +
-                        "this note and no rank or office it holds, and the entry gives no " +
+                    `\`${entry.name}\` names nothing: it is no word of its resolved language ` +
+                        "and no rank or office that reaches this note, and the entry gives no " +
                         "`definition` to make it a term",
                 ),
             );

package/engine/heading-attributes.mjs

@@ -28,12 +28,26 @@
  * **A leaf, deliberately.** `anchors.mjs` is shared by the compilers, the index
  * and the link checker and cannot import any of them; the figure pass is
  * imported by `anchors.mjs` and so cannot import it back. A module that imports
- * only the attribute grammar can be asked by all of them.
+ * the attribute grammar and Markdown literal ranges can be asked by all of them.
  *
  * @module
  */
 
 import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+import MarkdownIt from "markdown-it";
+
+/** Literal block ranges use the renderer's Markdown grammar. */
+const structureParser = new MarkdownIt({ html: true });
+
+/** Body lines occupied by code or raw HTML, including comment examples. */
+function literalHeadingLines(source) {
+    const lines = new Set();
+    for (const token of structureParser.parse(String(source ?? ""), {})) {
+        if (!token.map || !["fence", "code_block", "html_block"].includes(token.type)) continue;
+        for (let line = token.map[0]; line < token.map[1]; line++) lines.add(line);
+    }
+    return lines;
+}
 
 /**
  * A heading line: its hashes and the text after them.
@@ -134,8 +148,8 @@ export function opensPage({ level, id }) {
 /**
  * Every heading in a body, with what its attribute block declares.
  *
- * Fenced code is skipped: `#` opens a comment in most of what gets fenced, and
- * an example heading in a document is not a heading of it.
+ * Code and raw HTML blocks are skipped: an example heading in a document is
+ * not a heading of it, including an example in an HTML comment.
  *
  * @param {string} source - A note's markdown body.
  * @param {number} [bodyLine=1] - The 1-based file line the body starts on, so a
@@ -148,18 +162,9 @@ export function scanHeadingAttributes(source, bodyLine = 1) {
     const lines = String(source ?? "").split("\n");
     const headings = [];
     const errors = [];
-    let codeFence = null;
+    const literal = literalHeadingLines(source);
     for (let i = 0; i < lines.length; i++) {
-        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(lines[i]);
-        if (codeFence) {
-            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length)
-                codeFence = null;
-            continue;
-        }
-        if (fence) {
-            codeFence = fence[1];
-            continue;
-        }
+        if (literal.has(i)) continue;
         const heading = HEADING_LINE.exec(lines[i]);
         if (!heading) continue;
         const parsed = splitHeadingAttributes(heading[2]);
@@ -267,21 +272,9 @@ export function parseHeadingLine(line) {
 export function pageOpenings(source, blockLines = new Set()) {
     const lines = String(source ?? "").split("\n");
     const openings = new Map();
-    let codeFence = null;
+    const literal = literalHeadingLines(source);
     for (const [index, line] of lines.entries()) {
-        // A fence's closer must carry the same character as its opener and
-        // be at least as long, same as {@link scanHeadingAttributes} tracks
-        // it below — a longer fence is what lets a fenced example carry a
-        // shorter fence of its own as literal content.
-        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(line);
-        if (codeFence) {
-            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length) {
-                codeFence = null;
-            }
-        } else if (fence) {
-            codeFence = fence[1];
-        }
-        if (codeFence !== null || blockLines.has(index)) continue;
+        if (literal.has(index) || blockLines.has(index)) continue;
         const heading = parseHeadingLine(line);
         if (!heading?.startsPage) continue;
         openings.set(index, { ...heading, line: index + 1 });

package/engine/helpers.mjs

@@ -74,6 +74,7 @@ import { isDraftNote } from "./note-vocabulary.mjs";
 import { DERIVED_PACKED_TYPES, NEVER_PACKED_TYPES } from "./note-claims.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { spanMarkdownPlugin } from "./content-spans.mjs";
+import { dictionaryEntryPlugin } from "./dictionary-layout.mjs";
 import { renderBlocks } from "./content-blocks.mjs";
 import { headingAttributesPlugin } from "./heading-attributes.mjs";
 import { renderFigureBlocks, scanFigures } from "./content-figures.mjs";
@@ -108,6 +109,7 @@ export const md = markdownit({ html: true })
     .use(footnotePlugin)
     .use(deflistPlugin)
     .use(spanMarkdownPlugin)
+    .use(dictionaryEntryPlugin)
     // A heading's attribute block, written onto the heading element rather than
     // typeset into it — the reading the website's renderer does for itself.
     .use(headingAttributesPlugin)
@@ -233,17 +235,18 @@ export function renderFoundryMarkdown(body, figures, footnoteNumbers, docId, res
 /**
  * Parses a markdown file with YAML frontmatter.
  *
- * Returns `{ frontmatter, body, description, bodyLine, bodyColumn }` where
+ * Returns `{ frontmatter, body, description, bodyLine, bodyColumn, raw }` where
  * `body` is the trimmed raw markdown after the frontmatter block, and
- * `description` is `body` rendered to HTML. `bodyLine` / `bodyColumn` are the
+ * `description` is `body` rendered to HTML. The full source is retained as
+ * `raw` for diagnostic locations. `bodyLine` / `bodyColumn` are the
  * 1-based **file** position of the body's first character, which is what turns
  * an offset within `body` into a position a diagnostic can name — see
  * {@link positionInBody}. If the file has no frontmatter block, returns
- * `{ frontmatter: null, body: "", description: "" }` with a warn log, and no
+ * `{ frontmatter: null, body: "", description: "", raw }` and no
  * position: there is no body to have one.
  * @param {string} filePath - Markdown file to read.
  * @param {{addressContext?: object}} [opts] - Address defaults for decoded fields.
- * @returns {{frontmatter: object|null, body: string, description: string,
+ * @returns {{frontmatter: object|null, body: string, description: string, raw: string,
  *   bodyLine?: number, bodyColumn?: number, parseError?: {message: string,
  *   line?: number, column?: number}}} Parsed note and body position.
  */
@@ -251,7 +254,7 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
     const content = fs.readFileSync(filePath, "utf8");
     const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
     if (!fmMatch) {
-        return { frontmatter: null, body: "", description: "" };
+        return { frontmatter: null, body: "", description: "", raw: content };
     }
     let frontmatter;
     try {
@@ -264,6 +267,7 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
             frontmatter: null,
             body: "",
             description: "",
+            raw: content,
             parseError: {
                 message: `YAML parse error: ${message}`,
                 ...(Number.isInteger(location?.line) ? { line: location.line + 1 } : {}),
@@ -295,7 +299,7 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
     const before = content.slice(0, bodyStart);
     const bodyLine = before.split("\n").length;
     const bodyColumn = bodyStart - before.lastIndexOf("\n");
-    return { frontmatter, body, description, bodyLine, bodyColumn };
+    return { frontmatter, body, description, bodyLine, bodyColumn, raw: content };
 }
 
 /**
@@ -779,12 +783,14 @@ import { collectAnchors } from "./anchors.mjs";
  *   omitted.
  * @param {readonly object[]} [opts.records] - The corpus, derived once per
  *   compile and handed in. Required: see {@link assertSuppliedCorpus}.
+ * @param {Map<string, object[]>} [opts.sqlTables] - Prepared directives,
+ *   including the anchors and Foundry page maps of their expanded bodies.
  * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
 export function buildContentLinkIndex(
     contentBase,
     router = packRouter(),
-    { config, records } = {},
+    { config, records, sqlTables } = {},
 ) {
     const docs = [];
     /** The files this package ships, by canonical address. */
@@ -810,6 +816,7 @@ export function buildContentLinkIndex(
         // authored fields, and neither may be handed the keys the index derived.
         const fm = authoredFrontmatter(record);
         const absPath = noteFile(contentBase, record);
+        const prepared = sqlTables?.get(absPath);
         // The id a note's document is filed under: its authored pin, or the
         // one derived from its canonical address. Derived by the index
         // against the configuration this build resolved — never here through
@@ -859,11 +866,12 @@ export function buildContentLinkIndex(
             // discarded here — the walk yields the body and nothing read it.
             // Read from the record rather than from a second reading of the
             // note's headings — the one-anchor-reader rule.
-            anchors: new Set(
-                (record.anchors ?? [])
+            anchors: new Set([
+                ...(record.anchors ?? [])
                     .filter((anchor) => anchor.kind === "prose")
                     .map((anchor) => anchor.slug),
-            ),
+                ...(prepared?.anchors ?? []).map((anchor) => anchor.slug),
+            ]),
             // The note's event ids, which a wikilink may not name: a link to
             // one is refused with its own message rather than as unknown.
             eventAnchors: new Set(
@@ -871,8 +879,8 @@ export function buildContentLinkIndex(
                     .filter((anchor) => anchor.kind === "event")
                     .map((anchor) => anchor.slug),
             ),
-            anchorUuids: record.foundry?.note?.anchors,
-            docAnchorUuids: documentation?.foundry?.note?.anchors,
+            anchorUuids: prepared?.anchorUuids ?? record.foundry?.note?.anchors,
+            docAnchorUuids: prepared?.docAnchorUuids ?? documentation?.foundry?.note?.anchors,
         });
     }
     // Packages this build links *into* but does not publish. Each publishes

package/engine/infobox.mjs

@@ -277,6 +277,9 @@ export const GEAR_UNITS = Object.freeze({
  *   unit?: string, group?: string, phrase?: (value: any) => string}>>}
  */
 export const NOTE_FIELD_PRESENTATION = Object.freeze({
+    seeAlso: Object.freeze({
+        withheld: "navigation machinery, rendered in its own reading section",
+    }),
     ...DURATION_LABELS,
     ...GEAR_UNITS,
 

package/engine/journals.mjs

@@ -50,6 +50,7 @@
  */
 
 import log from "loglevel";
+import { seeAlsoEntries, seeAlsoMarkdown } from "./see-also.mjs";
 
 import path from "node:path";
 
@@ -72,6 +73,7 @@ import { reckoningContext } from "./reckoning-markers.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { JOURNAL_TYPES } from "./ids.mjs";
 import { journalHasContent } from "./note-state.mjs";
+import { hasLexicalEntries } from "./lexical-sections.mjs";
 import { draftNoticeFor } from "./draft-notice.mjs";
 import { scanFigures } from "./content-figures.mjs";
 import { separateFootnotes } from "./content-footnotes.mjs";
@@ -759,13 +761,15 @@ export class Journals extends BasePackCompiler {
      * An entry holding only its infobox is empty by this test. The panel is a
      * rendering of `data:` that the content index already carries, so a
      * compendium entry of nothing else tells a reader what the index told them.
+     * A frontmatter dictionary or glossary supplies pages of its own, so it
+     * qualifies before the shared body expansion inserts it.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {string} body - The note body, frontmatter stripped.
      * @returns {boolean} True to skip the note.
      */
     skipNote(fm, body) {
-        return !journalHasContent(body);
+        return !journalHasContent(body) && !hasLexicalEntries(fm);
     }
 
     /**
@@ -825,7 +829,16 @@ export class Journals extends BasePackCompiler {
         return buildJournalEntry({
             id,
             name,
-            markdown,
+            markdown: [
+                markdown,
+                seeAlsoMarkdown(
+                    seeAlsoEntries(fm, (ref) => resolveReference(this.linkIndex, ref)),
+                    linkToUuid,
+                    1,
+                ),
+            ]
+                .filter(Boolean)
+                .join("\n\n"),
             resolveRole: (pathname) => roles.get(pathname),
             infoboxes: boxes.map((box) => ({
                 id: box.id,

package/engine/language-data.mjs

@@ -160,6 +160,59 @@ export function checkLanguageData(note, { index, types } = {}) {
 
     const findings = [];
 
+    // Only the shape of a supplied declaration: no word is compared with it.
+    const grammar = isMap(data.grammar) ? data.grammar : {};
+    listOf(grammar.plural).forEach((row, i) => {
+        if (row == null || (Array.isArray(row) && row.length === 0))
+            findings.push(
+                finding(
+                    ["data", "grammar", "plural", i],
+                    "error",
+                    `\`data.grammar.plural[${i}]\` must be a map with ending and becomes strings`,
+                ),
+            );
+    });
+    const verbs = grammar.verbs;
+    if (Array.isArray(verbs) && verbs.length === 0)
+        findings.push(
+            finding(
+                ["data", "grammar", "verbs"],
+                "error",
+                "`data.grammar.verbs` must state `invariant: true` or the six `persons` strings",
+            ),
+        );
+    if (isMap(verbs)) {
+        const invariant = Object.hasOwn(verbs, "invariant");
+        const persons = Object.hasOwn(verbs, "persons");
+        if (invariant === persons)
+            findings.push(
+                finding(
+                    ["data", "grammar", "verbs"],
+                    "error",
+                    "`data.grammar.verbs` must state exactly one of `invariant: true` or `persons`",
+                ),
+            );
+        else if (invariant && (verbs.invariant == null || verbs.invariant === false))
+            findings.push(
+                finding(
+                    ["data", "grammar", "verbs", "invariant"],
+                    "error",
+                    "`data.grammar.verbs.invariant` must be true",
+                ),
+            );
+        else if (
+            persons &&
+            (verbs.persons == null || (Array.isArray(verbs.persons) && verbs.persons.length === 0))
+        )
+            findings.push(
+                finding(
+                    ["data", "grammar", "verbs", "persons"],
+                    "error",
+                    "`data.grammar.verbs.persons` must be a map of all six ending strings",
+                ),
+            );
+    }
+
     /**
      * The note an Address names, or a finding where it names none.
      *

package/engine/language-terms.mjs

@@ -43,6 +43,7 @@ export const LANGUAGE_DATA_KEYS = Object.freeze([
     "older",
     "negation",
     "naming",
+    "grammar",
 ]);
 
 /**
@@ -1594,6 +1595,81 @@ function listOfMaps(name, fields, describe) {
     });
 }
 
+/**
+ * The six present persons of the one optional regular verb pattern, in
+ * presentation order. Empty endings leave the citation form unchanged.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const VERB_PERSON_FIELDS = Object.freeze(
+    [
+        ["I", "I"],
+        ["you", "you"],
+        ["heShe", "he/she"],
+        ["we", "we"],
+        ["youAll", "you all"],
+        ["they", "they"],
+    ].map(([name, label]) =>
+        Object.freeze({
+            name,
+            label,
+            kind: "string",
+            required: true,
+            allowEmpty: true,
+            shape: "an ending string, empty for unchanged",
+            describe: `The ending added to the citation form for ${label}.`,
+        }),
+    ),
+);
+
+/** The two alternatives of a supplied optional verb pattern. */
+const VERB_PATTERN_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "invariant",
+        kind: "boolean",
+        shape: "true, as the alternative to persons",
+        describe: "True where verbs keep the citation form for every person; excludes `persons`.",
+    }),
+    Object.freeze({
+        name: "persons",
+        kind: "map",
+        shape: "a map — `{ I, you, heShe, we, youAll, they }` of ending strings",
+        fields: VERB_PERSON_FIELDS,
+        describe: "All six present endings, each added to the citation form; excludes `invariant`.",
+    }),
+]);
+
+/** The optional, display-only noun and verb patterns of one language. */
+const GRAMMAR_FIELDS = Object.freeze([
+    innerList(
+        "plural",
+        Object.freeze(
+            ["ending", "becomes"].map((name) =>
+                Object.freeze({
+                    name,
+                    kind: "string",
+                    required: true,
+                    allowEmpty: true,
+                    shape: "a literal ending string, which may be empty",
+                    describe:
+                        name === "ending" ?
+                            "The bare suffix replaced by this rule; empty matches every noun."
+                        :   "The bare replacement; empty removes the matching suffix.",
+                }),
+            ),
+        ),
+        "Default noun plurals, replacing the first matching literal ending in authored order. " +
+            "A word's explicit plural wins; no word is checked against this rule.",
+    ),
+    Object.freeze({
+        name: "verbs",
+        kind: "map",
+        shape: "a map — `{ invariant: true }` or `{ persons: { I, you, heShe, we, youAll, they } }`",
+        fields: VERB_PATTERN_FIELDS,
+        describe: "One optional regular present pattern, printed once at the dictionary head.",
+    }),
+]);
+
 /**
  * The `data` fields this module declares, in the order the vocabulary lists
  * them. {@link module:engine/language-data.checkLanguageData} checks what the
@@ -1602,6 +1678,16 @@ function listOfMaps(name, fields, describe) {
  * @type {readonly object[]}
  */
 export const LANGUAGE_DATA_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "grammar",
+        kind: "map",
+        shape: "a map — `{ plural?, verbs? }`",
+        fields: GRAMMAR_FIELDS,
+        describe:
+            "Optional noun plurals and one verb pattern for dictionary presentation. Only the " +
+            "shape of supplied keys is checked; no word must follow or state a rule. A language " +
+            "skill note only.",
+    }),
     listOfMaps(
         "tongues",
         TONGUE_FIELDS,

package/engine/language-words.mjs

@@ -36,7 +36,7 @@
  *   an ancestor's;
  * - every source language resolves, and names a language skill;
  * - a pronunciation is a respelling;
- * - a `built` piece no word or affix of the language glosses is a warning.
+ * - a `built` piece no word, affix or element of the language glosses is a warning.
  *
  * {@link checkLanguageFamily} owns `data.family`, the parent language a
  * daughter reads words from: it is stated only on a language, names a
@@ -285,7 +285,7 @@ export function checkLanguageWords(note, { index } = {}) {
                 finding(
                     [...at("built"), j],
                     "warning",
-                    `the piece \`${piece}\` of \`${word.form}\` matches no word or affix of this ` +
+                    `the piece \`${piece}\` of \`${word.form}\` matches no word, affix or element of this ` +
                         "language or its ancestors, so it prints with no gloss",
                 ),
             );