@heroiclands/package-build 23.7.1 → 23.9.0

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/hugo-theme/layouts/partials/related.html

@@ -6,11 +6,13 @@
 
   Structure in front matter:
     related:
+      seeAlso:   [{ title, url, type, gloss? }, ...] # deliberate references
       backlinks: [{ title, url, type }, ...]   # pages that link here
       mentions:  [{ title, url, type }, ...]   # pages this page links to
 
   Rendering strategy:
-    - Merge both directions into a single deduped pool (direction
+    - Render deliberate references in authored order, with their glosses.
+    - Merge both inferred directions into a single deduped pool (direction
       doesn't matter to a reader — a connection is a connection).
     - Group by the referenced page's `type`.
     - Emit one labelled group per type, its entries laid out as a
@@ -20,7 +22,7 @@
     - The whole block is wrapped in a bordered, tinted card so it
       visually sets off the end of the article.
 
-  Silent disappear: a page with no `related`, or whose two lists are both
+  Silent disappear: a page with no `related`, or whose lists are all
   empty, emits nothing at all rather than an empty heading. The rows are
   computed first and the <section> is rendered only when there is something
   to put in it.
@@ -34,15 +36,23 @@
 {{- /* `default dict` keeps the lookups below safe on a page with no
        `related` at all, so the whole computation stays flat. */ -}}
 {{- $rel := .Params.related | default dict -}}
+{{- $seeAlso := or $rel.seealso slice -}}
 {{- $backlinks := or $rel.backlinks slice -}}
 {{- $mentions  := or $rel.mentions  slice -}}
 
 {{- /* Merge both directions, deduped by URL. `union` can't hash
        slices of maps, so we walk the two lists in order and dedupe
-       by URL manually. Mentions come first so explicit author
-       choices win when a page appears in both directions. */ -}}
+       by URL manually. Deliberate references take priority; mentions
+       precede backlinks among inferred connections. */ -}}
 {{- $seen := slice -}}
 {{- $merged := slice -}}
+{{- $deliberate := slice -}}
+{{- range $seeAlso -}}
+  {{- if not (in $seen .url) -}}
+    {{- $seen = $seen | append .url -}}
+    {{- $deliberate = $deliberate | append . -}}
+  {{- end -}}
+{{- end -}}
 {{- range $mentions -}}
   {{- if not (in $seen .url) -}}
     {{- $seen = $seen | append .url -}}
@@ -101,12 +111,19 @@
   {{- $rows = sort $rows "label" "asc" -}}
 {{- end -}}
 
-{{- /* Deliberately not indented under the `if`: keeping the markup at
-       column 0 leaves the emitted HTML byte-identical to what pages with
-       `related` rendered before the guard was added. */ -}}
-{{- if $rows -}}
+{{- if or $rows $deliberate -}}
 <section class="related" aria-labelledby="related-heading" data-pagefind-ignore>
   <h2 id="related-heading" class="related-heading">Related</h2>
+  {{- with $deliberate }}
+  <div class="related-group">
+    <h3 class="related-group-label">See also</h3>
+    <ul class="related-group-grid">
+      {{- range . }}
+      <li><a href="{{ .url }}">{{ .title }}</a>{{ with .gloss }} — {{ . }}{{ end }}</li>
+      {{- end }}
+    </ul>
+  </div>
+  {{- end }}
   {{- range $rows }}
   <div class="related-group">
     <h3 class="related-group-label">{{ .label }}</h3>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.7.1",
+    "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",
@@ -132,6 +132,7 @@
     "dependencies": {
         "@duckdb/node-api": "^1.5.5-r.4",
         "@foundryvtt/foundryvtt-cli": "^3.0.4",
+        "@puppeteer/browsers": "^3.2.5",
         "@viz-js/viz": "^3.30.0",
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",

package/types/container.d.mts

@@ -247,8 +247,8 @@ export function s3RunArgs(plan: S3Plan): string[];
  */
 export function s3ShellArgs(plan: S3Plan, command: string): string[];
 /**
- * Start the S3 server on its network and create the bucket, unless it is
- * already running, and copy the `awsConfig` into the data root.
+ * Start or reuse the S3 server on its network, wait for readiness, ensure the
+ * bucket exists, and copy the `awsConfig` into the data root.
  *
  * @param {object} opts
  * @param {S3Plan} opts.plan - The S3 plan.
@@ -261,7 +261,8 @@ export function s3ShellArgs(plan: S3Plan, command: string): string[];
  * @param {(ms: number) => void} [opts.sleep] - Waits.
  * @param {number} [opts.attempts] - How often to ask the server whether it is
  *   ready.
- * @throws {Error} When an input file is missing or the server never answers.
+ * @throws {Error} When an input is not a readable regular file, a reused
+ *   identities mount is incompatible, or the S3 HTTP service never answers.
  */
 export function ensureS3({ plan, dataRoot, log, run, capture, sleep, attempts, }: {
     plan: S3Plan;

package/types/e2e.d.mts

@@ -236,6 +236,32 @@ export function waitForWorld({ url, container, stage, dataRoot, readLog, timeout
  * @returns {string[]} The executables to resolve, in the order to report them.
  */
 export function suiteExecutables(command: readonly string[]): string[];
+/**
+ * The browser cache survives reseeding and container teardown.
+ * @param {NodeJS.ProcessEnv} [env] - Environment overrides.
+ * @returns {string} The browser cache directory.
+ */
+export function browserCacheDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * Supply pinned Chrome only to a recognizable Cypress command without a browser.
+ * Explicit browser arguments remain verbatim, including Electron and paths.
+ * @param {object} opts
+ * @param {readonly string[]} opts.command - The configured suite command.
+ * @param {string[]} [opts.args] - Extra suite arguments.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Cache overrides.
+ * @param {string} [opts.platform] - Host operating system.
+ * @param {string} [opts.arch] - Host architecture.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {Promise<string[]>} Arguments to append to the suite command.
+ */
+export function prepareSuiteBrowser({ command, args, env, platform, arch, log, }: {
+    command: readonly string[];
+    args?: string[] | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    platform?: string | undefined;
+    arch?: string | undefined;
+    log?: ((message: string) => void) | undefined;
+}): Promise<string[]>;
 /**
  * Find an executable the way the child process will: a path is a path, and a
  * bare name is looked for in the repository's `node_modules/.bin` first, then
@@ -467,6 +493,8 @@ export const E2E_GM_ID: "heroiclandsE2EGM";
 export const E2E_SCENE_ID: "heroiclandsScene";
 /** How the suite may be run. */
 export const E2E_MODES: readonly string[];
+/** The Chrome for Testing build shared by local and CI Cypress runs. */
+export const CHROME_BUILD_ID: "155.0.8059.84";
 /**
  * The disposable world's identity and credentials.
  */

package/types/engine/base-compiler.d.mts

@@ -631,8 +631,8 @@ export class BasePackCompiler {
     compile(): Promise<void>;
     currentNote: {
         absPath: string;
-        bodyLine: number | undefined;
-        bodyColumn: number | undefined;
+        bodyLine: any;
+        bodyColumn: any;
     } | undefined;
     #private;
 }

package/types/engine/compile-corpus.d.mts

@@ -15,7 +15,7 @@
  *   created when none is passed, and returned on the corpus either way — a note
  *   the index refuses is a note the compile must still *report*, exactly as the
  *   compile loop reported it when the loop was the first to see it.
- * @returns {Promise<{records: object[], linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
+ * @returns {Promise<{records: object[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
 export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, router, config, problems, }: {
@@ -27,6 +27,7 @@ export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, r
     problems?: object[] | undefined;
 }): Promise<{
     records: object[];
+    parsed: Map<string, object>;
     linkIndex: object;
     sqlTables: Map<string, object[]> | undefined;
     problems: object[];

package/types/engine/content-index.d.mts

@@ -94,6 +94,7 @@ export function asciiAliases(aliases: unknown): Array<string>;
  * @param {string} options.relPath - Its path below the content root, POSIX-separated.
  * @param {string} [options.absPath] - The file, read only on the failing path to
  *   locate the offending key.
+ * @param {string} [options.raw] - Source text already read by the caller.
  * @param {string} options.contentPackage - The package the tree compiles as.
  * @param {string} [options.body] - The note's markdown body, for its anchors
  *   and for the one question that decides whether the note publishes a page. A
@@ -118,10 +119,11 @@ export function asciiAliases(aliases: unknown): Array<string>;
  *   otherwise be overwritten without a word. `file` and, where the file was
  *   read, `position` ride on the error.
  */
-export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, addressContext, dateContext, resolveRole, }: {
+export function buildIndexRecord({ frontmatter, relPath, absPath, raw, contentPackage, body, bodyLine, manifest, addressContext, dateContext, resolveRole, }: {
     frontmatter: Record<string, any>;
     relPath: string;
     absPath?: string | undefined;
+    raw?: string | undefined;
     contentPackage: string;
     body?: string | undefined;
     bodyLine?: number | undefined;
@@ -131,12 +133,13 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage
     resolveRole?: ((address: string) => string | undefined) | undefined;
 }): Record<string, any>;
 /** Derive every index record belonging to one parsed note. */
-export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext, dateContext, resolveRole, }: {
+export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, raw, contentPackage, manifest, addressContext, dateContext, resolveRole, }: {
     frontmatter: any;
     body: any;
     bodyLine: any;
     relPath: any;
     absPath: any;
+    raw: any;
     contentPackage: any;
     manifest: any;
     addressContext: any;
@@ -188,16 +191,20 @@ export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absP
  *   immediate parent whose package is not this one.
  * @param {object[]} [options.problems] - Receives each conflict as a finding.
  *   Omitted, every conflict is collected and one Error lists them all.
+ * @param {Map<string, {raw: string}>} [options.parsed] - Notes already read, keyed by file.
  * @returns {Array<Record<string, any>>} The same records.
  * @throws {Error} When `problems` is omitted and any note's sources disagree.
  */
-export function resolveCultures(records: Array<Record<string, any>>, { contentPackage, contentBase, foreignRecord, problems }: {
+export function resolveCultures(records: Array<Record<string, any>>, { contentPackage, contentBase, foreignRecord, problems, parsed }: {
     contentPackage: string;
     contentBase?: string | undefined;
     foreignRecord?: ((key: string) => ({
         culture?: unknown;
     } | undefined)) | undefined;
     problems?: object[] | undefined;
+    parsed?: Map<string, {
+        raw: string;
+    }> | undefined;
 }): Array<Record<string, any>>;
 /**
  * Read a content tree into index records, in the order they will be written.
@@ -233,9 +240,9 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  * @param {(key: string) => ({culture?: unknown}|undefined)} [options.foreignRecord] -
  *   Another package's entry for a canonical address, read for a parent that
  *   package publishes; see {@link resolveCultures}.
- * @param {Map<string, {body: string, frontmatter: object|null}>} [options.parsed] -
- *   Filled with each note's body and its frontmatter as authored, keyed by the
- *   note's file, so a later pass reads the notes this walk already parsed.
+ * @param {Map<string, {body: string, frontmatter: object|null, raw: string, bodyLine?: number, bodyColumn?: number}>} [options.parsed] -
+ *   Filled with each note's source text, body coordinates and frontmatter as
+ *   authored, keyed by file, for reuse throughout the command.
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
@@ -252,6 +259,9 @@ export function collectContentIndex(contentBase: string, { contentPackage, skipD
     parsed?: Map<string, {
         body: string;
         frontmatter: object | null;
+        raw: string;
+        bodyLine?: number;
+        bodyColumn?: number;
     }> | undefined;
 }): Array<Record<string, any>>;
 /**
@@ -289,7 +299,7 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  *   aborting the derivation. Omitted, the note throws — which is the contract
  *   the emitter needs, since an index missing a note asserts that it does not
  *   exist.
- * @param {Map<string, {body: string, frontmatter: object|null}>} [opts.parsed] -
+ * @param {Map<string, {body: string, frontmatter: object|null, raw: string, bodyLine?: number, bodyColumn?: number}>} [opts.parsed] -
  *   Filled with each note's body and authored frontmatter, keyed by the note's
  *   file. Handed to {@link module:engine/sql-tables.prepareTreeSqlTables}, it
  *   spares that pass reading and parsing every note again.
@@ -304,8 +314,24 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
     parsed?: Map<string, {
         body: string;
         frontmatter: object | null;
+        raw: string;
+        bodyLine?: number;
+        bodyColumn?: number;
     }> | undefined;
 }): object[];
+/**
+ * Prepare the complete bodies a content-index publication describes.
+ * Prose declarations use each source's audience. Native SQL uses the complete
+ * corpus, with target maps limited to that source's declared prose slugs.
+ * No output files are written, and the returned inputs are read-only to the emitter.
+ *
+ * @param {{contentBase?: string, config?: object}} [options]
+ * @returns {Promise<PreparedContentIndex>}
+ */
+export function prepareContentIndex({ contentBase, config }?: {
+    contentBase?: string;
+    config?: object;
+}): Promise<PreparedContentIndex>;
 /**
  * Emit this package's content index.
  *
@@ -315,6 +341,7 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
  * @param {string} [options.outDir] - Where to write; defaults to the configured
  *   `paths.contentIndex`.
  * @param {object} [options.config] - A resolved configuration; loaded when omitted.
+ * @param {PreparedContentIndex} [options.publication] - Complete preparation for this tree and configuration.
  * @returns {{file: string, notes: number, assets: number, records: number,
  *   bytes: number, full: number, draft: number, stub: number,
  *   dictionary: {file: string, rows: number}, terms: {file: string, rows: number}}}
@@ -328,10 +355,11 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
  *   reader would take it as the authoritative statement that this package has
  *   no content.
  */
-export function emitContentIndex({ contentBase, outDir, config }?: {
+export function emitContentIndex({ contentBase, outDir, config, publication }?: {
     contentBase?: string | undefined;
     outDir?: string | undefined;
     config?: object | undefined;
+    publication?: PreparedContentIndex | undefined;
 }): {
     file: string;
     notes: number;
@@ -350,6 +378,55 @@ export function emitContentIndex({ contentBase, outDir, config }?: {
         rows: number;
     };
 };
+/**
+ * A captured source context, consumed without mutation by the synchronous emitter.
+ */
+export type PreparedContentIndex = {
+    /**
+     * - The exact resolved configuration for preparation.
+     */
+    config: object;
+    /**
+     * - The absolute captured source root.
+     */
+    contentBase: string;
+    /**
+     * - Complete index records, including hidden providers.
+     */
+    records: object[];
+    /**
+     * - Authored sources by absolute file.
+     */
+    parsed: Map<string, {
+        frontmatter: object | null;
+        body: string;
+        raw: string;
+        bodyLine?: number;
+        bodyColumn?: number;
+    }>;
+    /**
+     * - Complete rendered bodies in each note's audience.
+     */
+    expandedBodies: Map<string, {
+        markdown: string;
+        lineMap: Array<{
+            line: number;
+            generated: boolean;
+        }>;
+        generatedFrom?: number;
+    }>;
+    /**
+     * - Complete native bodies with explicit SQL using the ALL corpus.
+     */
+    foundryBodies: Map<string, {
+        markdown: string;
+        lineMap: Array<{
+            line: number;
+            generated: boolean;
+        }>;
+        generatedFrom?: number;
+    }>;
+};
 import { collectAnchors } from "./anchors.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";
 import { DERIVED_KEYS } from "./index-records.mjs";

package/types/engine/content-tables.d.mts

@@ -12,7 +12,8 @@
  *   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

package/types/engine/culture-reach.d.mts

@@ -32,12 +32,15 @@ export function glossaryCorpus(index: object): GlossaryCorpus;
  *
  * @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: object, note: object): Map<string, string[]>;
+export function noteTerms(index: object, note: object, entry?: object): Map<string, string[]>;
 /**
  * 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]
@@ -63,4 +66,21 @@ export type GlossaryCorpus = {
      * give it.
      */
     terms: Map<string, Map<string, string[]>>;
+    /**
+     * - The ranks and
+     * offices each owner can name.
+     */
+    governance: Map<string, Map<string, string[]>>;
+    /**
+     * - Each
+     * language's dictionary words.
+     */
+    words: Map<string, Array<{
+        form: string;
+        gloss: unknown;
+    }>>;
+    /**
+     * - Each language's parent.
+     */
+    families: Map<string, string | undefined>;
 };

package/types/engine/data-keys.d.mts

@@ -13,6 +13,8 @@
  *   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
@@ -117,6 +119,11 @@ export type InnerKeySpec = {
      * - The key must be stated, with a value.
      */
     required?: boolean | undefined;
+    /**
+     * - A required string may be empty where
+     * empty text is a stated value.
+     */
+    allowEmpty?: boolean | undefined;
     /**
      * - An explicit `null` states the key, for a
      * required key whose null has a meaning of its own.

package/types/engine/diagnostics.d.mts

@@ -150,12 +150,14 @@ export function positionInFrontmatter(raw: string, key: string, value?: string,
  *   {@link positionInFrontmatter}.
  * @param {boolean} [options.topLevel=false] - Require the key at column 1, so
  *   an identically named nested key cannot answer for it.
+ * @param {string} [options.raw] - Source text already read by the caller.
  * @returns {{line?: number, column?: number}|undefined} Spreadable position
  *   fields, dropped rather than guessed when the file cannot be read or the key
  *   cannot be found — as `formatDiagnostic` requires.
  */
-export function locateFrontmatterKey(absPath: string | undefined, key: string, value?: string, { topLevel }?: {
+export function locateFrontmatterKey(absPath: string | undefined, key: string, value?: string, { topLevel, raw }?: {
     topLevel?: boolean | undefined;
+    raw?: string | undefined;
 }): {
     line?: number;
     column?: number;
@@ -195,11 +197,10 @@ export function positionOfLiteral(text: string, needle: string, occurrence?: num
  * first occurrence is routinely not the one the finding is about — which is the
  * one thing the located form exists to prevent.
  *
- * A path resolves the exact node instead. The document is re-parsed here rather
- * than threaded from the loader because the loader returns plain data: `yaml`
- * discards ranges once a document is materialised, and carrying a parallel
- * position tree through configuration resolution would be a second
- * representation of the same file to keep in step.
+ * A path resolves the exact node. The most recently located text retains its
+ * document and line counter, so several findings in one note share a parse.
+ * A different text replaces that entry, including an edited copy of the same
+ * file. The loader returns plain data without source ranges.
  *
  * Every failure — unparseable text, an `.mjs` configuration, a path that
  * resolves to nothing — yields `{}`, so a caller spreads the result and the