@heroiclands/package-build 23.8.0 → 23.10.0

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,10 +74,11 @@ 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";
-import { positionInBody } from "./diagnostics.mjs";
+import { positionInBody, splitFrontmatter } from "./diagnostics.mjs";
 // The pure `sohl:` frontmatter readers live in a leaf module so the item-type
 // registry can import them without reaching back through this one.
 // Re-exported here so every existing importer keeps its single import path.
@@ -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)
@@ -231,7 +233,7 @@ export function renderFoundryMarkdown(body, figures, footnoteNumbers, docId, res
 }
 
 /**
- * Parses a markdown file with YAML frontmatter.
+ * Parses a markdown file with LF or CRLF YAML frontmatter delimiters.
  *
  * Returns `{ frontmatter, body, description, bodyLine, bodyColumn, raw }` where
  * `body` is the trimmed raw markdown after the frontmatter block, and
@@ -243,20 +245,27 @@ export function renderFoundryMarkdown(body, figures, footnoteNumbers, docId, res
  * `{ 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.
+ * @param {object} [opts]
+ * @param {object} [opts.addressContext] - Address defaults for decoded fields.
+ * @param {string} [opts.raw] - Exact captured source; omitted, reads the file.
+ * @param {boolean} [opts.renderDescription=true] - Render the body's HTML description.
+ *   False leaves `description` empty for readers that only use authored text.
  * @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.
  */
-export function parseMarkdownFile(filePath, { addressContext } = {}) {
-    const content = fs.readFileSync(filePath, "utf8");
-    const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+export function parseMarkdownFile(
+    filePath,
+    { addressContext, raw: capturedRaw, renderDescription = true } = {},
+) {
+    const content = capturedRaw ?? fs.readFileSync(filePath, "utf8");
+    const fmMatch = splitFrontmatter(content);
     if (!fmMatch) {
         return { frontmatter: null, body: "", description: "", raw: content };
     }
     let frontmatter;
     try {
-        frontmatter = yaml.parse(fmMatch[1]) || {};
+        frontmatter = yaml.parse(fmMatch.yaml) || {};
     } catch (err) {
         const firstLine = String(err.message).split("\n", 1)[0];
         const message = firstLine.replace(/ at line \d+, column \d+.*$/, "");
@@ -277,7 +286,7 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
         try {
             decodeNoteAddresses(frontmatter, addressContext);
         } catch (error) {
-            const position = positionOfYamlPath(fmMatch[1], error.keyPath ?? [], {
+            const position = positionOfYamlPath(fmMatch.yaml, error.keyPath ?? [], {
                 key: error.addressKey,
             });
             if (position.line) position.line++;
@@ -286,9 +295,9 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
             throw error;
         }
     }
-    const raw = fmMatch[2];
+    const raw = fmMatch.body;
     const body = raw.trim();
-    const description = body ? renderFoundryMarkdown(body) : "";
+    const description = body && renderDescription ? renderFoundryMarkdown(body) : "";
     // Where the trimmed body starts in the *file*, so an offset within it can
     // be reported as a file position. The frontmatter's lines and the
     // blank lines `trim()` removes both sit in between, and the trim can take
@@ -374,13 +383,19 @@ export function assertSuppliedCorpus(records, who) {
  *   Required: the scope is the caller's to state, so two passes cannot
  *   disagree about which files are the corpus.
  * @param {object} [opts.addressContext] - Address resolution context.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Selected sources in walk order.
+ *   Supplied, the walk parses these strings instead of reading the filesystem.
+ * @param {boolean} [opts.renderDescription=true] - Render each body's description.
  * @yields {{frontmatter: object|null, body: string, description: string,
  *   file: string, absPath: string, bodyLine?: number, bodyColumn?: number}}
  *   One entry per `.md` file found.
  * @throws {Error} When `skipDirectories` is not stated — see
  *   {@link assertStatedScope}.
  */
-export function* walkMarkdownTree(rootDir, { skipDirectories, addressContext } = {}) {
+export function* walkMarkdownTree(
+    rootDir,
+    { skipDirectories, addressContext, sources, renderDescription = true } = {},
+) {
     // Stated by the caller, never resolved here. A default here
     // — `loadPackConfig().skipDirectories` — read whichever configuration
     // resolved from the working directory rather than the one the caller was
@@ -393,6 +408,20 @@ export function* walkMarkdownTree(rootDir, { skipDirectories, addressContext } =
     // the ambient config rather than the passed one, which a fixture can pass
     // on indefinitely.
     assertStatedScope(skipDirectories, "walkMarkdownTree");
+    if (sources) {
+        for (const [absPath, source] of sources) {
+            yield {
+                ...parseMarkdownFile(absPath, {
+                    addressContext,
+                    raw: source.raw,
+                    renderDescription,
+                }),
+                file: path.basename(absPath),
+                absPath,
+            };
+        }
+        return;
+    }
     if (!fs.existsSync(rootDir)) return;
     const stack = [rootDir];
     while (stack.length > 0) {
@@ -411,7 +440,7 @@ export function* walkMarkdownTree(rootDir, { skipDirectories, addressContext } =
                 stack.push(absPath);
             } else if (entry.isFile() && entry.name.endsWith(".md")) {
                 yield {
-                    ...parseMarkdownFile(absPath, { addressContext }),
+                    ...parseMarkdownFile(absPath, { addressContext, renderDescription }),
                     file: entry.name,
                     absPath,
                 };
@@ -781,12 +810,16 @@ 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.
+ * @param {ReturnType<import("./metadata-index.mjs").loadForeignIndexes>} [opts.foreign] -
+ *   Captured dependency address and reference views for this context.
  * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
 export function buildContentLinkIndex(
     contentBase,
     router = packRouter(),
-    { config, records } = {},
+    { config, records, sqlTables, foreign: capturedForeign } = {},
 ) {
     const docs = [];
     /** The files this package ships, by canonical address. */
@@ -812,6 +845,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
@@ -861,11 +895,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(
@@ -873,8 +908,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
@@ -886,7 +921,7 @@ export function buildContentLinkIndex(
         index: foreign,
         references: foreignReferences,
         stale,
-    } = loadForeignIndexes(resolved, [resolved.contentPackage], PACKAGE_BASE);
+    } = capturedForeign ?? loadForeignIndexes(resolved, [resolved.contentPackage], PACKAGE_BASE);
     if (stale.length) {
         for (const st of stale) {
             log.error(`Unusable content index for "${st.package}": ${st.reason}`);

package/engine/index-records.mjs

@@ -63,6 +63,7 @@ export const DERIVED_KEYS = Object.freeze([
     "asset",
     "resolvedDates",
     "citations",
+    "names",
 ]);
 
 /**

package/engine/index.mjs

@@ -187,6 +187,9 @@ export * as foundryEntries from "./foundry-entries.mjs";
 /** Publishing the note tree as a queryable JSON Lines index. */
 export * as contentIndex from "./content-index.mjs";
 
+/** One invocation's captured content and context-specific prepared views. */
+export * as contentSession from "./content-session.mjs";
+
 /** The asset types — `icon`, `image`, `audio` — and the roots they are walked from. */
 export * as assetTypes from "./asset-types.mjs";
 

package/engine/journals.mjs

@@ -73,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";
@@ -102,9 +103,9 @@ const WITHHELD_OWNERSHIP = 0;
  * @param {string} markdown - A note's body, as {@link splitPages} receives it.
  * @returns {Set<number>} 0-based line indices inside a named block.
  */
-function namedBlockLines(markdown) {
+function namedBlockLines(markdown, syntax) {
     const lines = new Set();
-    for (const { start, end } of scanBlocks(markdown).blocks) {
+    for (const { start, end } of (syntax ? syntax(markdown).blocks : scanBlocks(markdown)).blocks) {
         for (let i = start; i <= end; i++) lines.add(i);
     }
     return lines;
@@ -141,17 +142,18 @@ function namedBlockLines(markdown) {
  *   picture's address to the role its asset declares, so a figure page's
  *   name reads `Map 1` rather than `Figure 1` where it is due — see
  *   {@link module:engine/content-figures.scanFigures}.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Session scanner projections.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
  *   classes: string[], figure: object|null, continues?: string,
  *   markdown: string}>} Pages in document order.
  */
-export function splitPages(body, leadName = "Introduction", resolveRole) {
+export function splitPages(body, leadName = "Introduction", resolveRole, syntax) {
     const { markdown, definitions } = separateFootnotes(body);
     const lines = markdown.split("\n");
     const figureStarts = new Map(
         scanFigures(markdown, { resolveRole }).figures.map((figure) => [figure.line - 1, figure]),
     );
-    const blockLines = namedBlockLines(markdown);
+    const blockLines = namedBlockLines(markdown, syntax);
     const openings = pageOpenings(markdown, blockLines);
     const pages = [];
     const beforeFirstH1 = [];
@@ -635,6 +637,7 @@ export function buildPages(rawPages, entryId, noteName, figures, resolveRole) {
  *   a picture's address to the role its asset declares, so a figure page's
  *   name reads `Map 1` rather than `Figure 1` where it is due — see
  *   {@link module:engine/content-figures.scanFigures}.
+ * @param {import("./content-session.mjs").ContentSyntax} [params.syntax] - Session scanner projections.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
 export function buildJournalEntry({
@@ -647,8 +650,9 @@ export function buildJournalEntry({
     infoboxes = [],
     notice = "",
     resolveRole,
+    syntax,
 }) {
-    const rawPages = splitPages(markdown, leadName, resolveRole);
+    const rawPages = splitPages(markdown, leadName, resolveRole, syntax);
     const pages = buildPages(
         rawPages,
         id,
@@ -760,13 +764,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);
     }
 
     /**
@@ -824,6 +830,7 @@ export class Journals extends BasePackCompiler {
         const roles = pathnameRoles(this.linkIndex);
 
         return buildJournalEntry({
+            syntax: this.corpus?.syntax,
             id,
             name,
             markdown: [

package/engine/language-data.mjs

@@ -44,7 +44,7 @@
  *   syllables, its consonants per vowel or both, each range's `min` no
  *   higher than its `max`; an edge stands once for each class of name; a kind
  *   of name has one set of draws; and a held-from row takes `elements` only
- *   where it takes an `element`, and is clipped or given a genitive only
+ *   where it takes an `element`, and is clipped or given a joining ending only
  *   where it takes a name.
  *
  * @module
@@ -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.
      *
@@ -574,7 +627,7 @@ export function checkLanguageData(note, { index, types } = {}) {
                 ),
             );
         if (!HELD_NAMES.includes(row.takes))
-            for (const key of ["clip", "genitive"])
+            for (const key of ["clip", "joining"])
                 if (row[key] != null)
                     findings.push(
                         finding(

package/engine/language-rows.mjs

@@ -122,7 +122,7 @@ export const HELD_FROM_COLUMNS = Object.freeze([
     "source",
     "takes",
     "clip",
-    "genitive",
+    "joining",
     "elements",
 ]);
 /** Every column of the `near_names` relation, in order. */
@@ -232,7 +232,7 @@ export const LANGUAGE_COLUMN_TYPES = Object.freeze({
     },
     name_edges: { position: "BIGINT", sounds: LIST, vowel: "BOOLEAN" },
     name_draws: { position: "BIGINT", elements: LIST },
-    held_from: { position: "BIGINT", genitive: LIST, elements: LIST },
+    held_from: { position: "BIGINT", joining: LIST, elements: LIST },
     near_names: { position: "BIGINT", min_syllables: "BIGINT" },
     stress: {},
     finals: { position: "BIGINT" },
@@ -653,8 +653,8 @@ export function heldFromRows(records) {
     return listRows(
         records,
         (data) => namingOf(data).heldFrom,
-        ["source", "takes", "clip", "genitive", "elements"],
-        { lists: ["genitive", "elements"] },
+        ["source", "takes", "clip", "joining", "elements"],
+        { lists: ["joining", "elements"] },
     );
 }
 

package/engine/language-terms.mjs

@@ -43,6 +43,7 @@ export const LANGUAGE_DATA_KEYS = Object.freeze([
     "older",
     "negation",
     "naming",
+    "grammar",
 ]);
 
 /**
@@ -1141,10 +1142,10 @@ export const ELEMENT_FIELDS = Object.freeze([
             "ancestor.",
     }),
     Object.freeze({
-        name: "genitive",
+        name: "joining",
         kind: "string",
         shape: "the element as written, such as `-borgar`",
-        describe: "The element in the genitive, where a name governing another word takes it.",
+        describe: "The element's joining form, as written when it qualifies another word.",
     }),
 ]);
 
@@ -1471,11 +1472,11 @@ export const HELD_FROM_FIELDS = Object.freeze([
         describe: "How the name is clipped: `first`, to its first element; whole where absent.",
     }),
     Object.freeze({
-        name: "genitive",
+        name: "joining",
         kind: "list",
         shape: "a list of endings",
         entries: STRINGS,
-        describe: "The genitive endings, one of which stands at the seam after the name.",
+        describe: "The joining endings, one of which stands at the seam after the name.",
     }),
     Object.freeze({
         name: "elements",
@@ -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",
                 ),
             );