@heroiclands/package-build 25.1.3 → 25.2.0

package/engine/changelog-lint.mjs

@@ -607,73 +607,196 @@ function checkCodeLikeTokens(text, maskedRegions) {
 }
 
 /**
- * A block's bold label absent from the declared `changelog.labels`
- * vocabulary — the drift `**Character data**` beside `**Characters**`
- * produces, invisible until something reads the declared list against what a
- * changeset actually wrote. A warning, not an error: an undeclared label
- * still ships and still groups (`changelog group` files it last), so nothing
- * here blocks a release — it only says the vocabulary and the prose have
- * drifted apart.
- *
- * @param {Array<{startLine: number, label: string|null}>} blocks - From
- *   {@link topLevelBlocks}.
- * @param {readonly string[]|null|undefined} labels - `changelog.labels`, or
- *   `null`/`undefined` when the repository declares none, in which case
- *   nothing is checked — there is no vocabulary for a label to drift from.
+ * The label every repository may use without declaring it, for the changes
+ * that fit no declared label. `changelog group` writes it last.
+ */
+export const MISCELLANEOUS = "Miscellaneous";
+
+/** A label line that holds the label and nothing else. */
+const LABEL_ONLY_RE = /^\*\*([^*]+)\*\*[ \t]*$/;
+
+/**
+ * Hold a changeset body, or a release section's body, to the house shape:
+ * one or more blocks, each a `**Label**` line on its own followed by bullets
+ * and nothing else.
+ *
+ * Findings: a `lead-paragraph` (prose before any label), `unlabelled` (a
+ * bullet before any label), `stray-prose` (prose after a label opens, between
+ * or after its bullets), `label-line` (text sharing the label's line),
+ * `empty-block` (a label with no bullet) and `unknown-label` (a label neither
+ * declared in the changelog `labels` nor {@link MISCELLANEOUS}). Nested lists,
+ * headings and bullet length are separate rules. Code regions are skipped; a
+ * fenced block has its own finding.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines - Lines inside a code region.
+ * @param {Set<number>} scaffoldLines - Generated lines, never authored.
+ * @param {readonly string[]|null|undefined} labels - the changelog `labels`, or
+ *   `null`/`undefined` when the repository declares none.
  * @returns {RelativeFinding[]}
  */
-function checkUnknownLabels(blocks, labels) {
-    if (!labels) return [];
+function checkShape(text, codeLines, scaffoldLines, labels) {
+    const lines = text.split("\n");
+    const declared = labels ?? [];
     /** @type {RelativeFinding[]} */
     const findings = [];
-    for (const block of blocks) {
-        if (block.label === null || labels.includes(block.label)) continue;
+    /** @type {{line: number, label: string, bullets: number}|null} */
+    let open = null;
+    let reportedLead = false;
+    const closeBlock = () => {
+        if (open && open.bullets === 0)
+            findings.push({
+                line: open.line,
+                column: 1,
+                severity: "error",
+                message:
+                    `changelog-check/empty-block the block labelled "${open.label}" has no ` +
+                    "bullets — a block is a label line, then bullets",
+            });
+        open = null;
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        const raw = lines[i];
+        if (codeLines.has(lineNo) || scaffoldLines.has(lineNo)) continue;
+        if (raw.trim() === "") continue;
+        const atColumnZero = !/^[ \t]/.test(raw);
+        if (!atColumnZero) continue; // a bullet's continuation, or a nested item
+        if (/^#{1,6}\s/.test(raw)) {
+            closeBlock();
+            continue; // reported by the heading rule
+        }
+
+        const label = LABEL_LINE_RE.exec(raw)?.[1];
+        if (label !== undefined) {
+            closeBlock();
+            open = { line: lineNo, label, bullets: 0 };
+            if (!LABEL_ONLY_RE.test(raw))
+                findings.push({
+                    line: lineNo,
+                    column: 1,
+                    severity: "error",
+                    message:
+                        "changelog-check/label-line the label stands on a line of its own, " +
+                        "`**Label**`, with the bullets beneath it",
+                });
+            if (label !== MISCELLANEOUS && !declared.includes(label))
+                findings.push({
+                    line: lineNo,
+                    column: 3, // right after the opening `**`
+                    severity: "error",
+                    message:
+                        `changelog-check/unknown-label "${label}" is not a declared label — ` +
+                        (declared.length > 0 ?
+                            `declared: ${declared.join(", ")}; ${MISCELLANEOUS} is always available`
+                        :   `declare \`labels\` in the changelog options of .changeset/config.json, ` +
+                            `or use ${MISCELLANEOUS}`),
+                });
+            continue;
+        }
+
+        if (TOP_BULLET_RE.test(raw)) {
+            if (open) open.bullets++;
+            else
+                findings.push({
+                    line: lineNo,
+                    column: 1,
+                    severity: "error",
+                    message:
+                        "changelog-check/unlabelled a bullet belongs under a `**Label**` line — " +
+                        `use a declared label, or ${MISCELLANEOUS}`,
+                });
+            continue;
+        }
+
+        if (!open) {
+            if (!reportedLead)
+                findings.push({
+                    line: lineNo,
+                    column: 1,
+                    severity: "error",
+                    message:
+                        "changelog-check/lead-paragraph a changeset is labelled blocks of " +
+                        "bullets; a paragraph before the first `**Label**` has no place",
+                });
+            reportedLead = true;
+            continue;
+        }
         findings.push({
-            line: block.startLine,
-            column: 3, // right after the opening `**`
-            severity: "warning",
+            line: lineNo,
+            column: 1,
+            severity: "error",
             message:
-                `changelog-check/unknown-label "${block.label}" is not declared in ` +
-                "`changelog.labels` (declared: " +
-                `${labels.join(", ")}) — add it there, or correct the label`,
+                "changelog-check/stray-prose only bullets sit under a label — move this " +
+                "into a bullet, or drop it",
         });
     }
+    closeBlock();
     return findings;
 }
 
 /**
  * The 1-based lines a caller drops from the heading rule because they are the
- * generated scaffold, never authored prose: the section's own `## <version>`
- * opening and any `### <Bump> Changes` line.
+ * generated scaffold, never authored prose: a release section's own
+ * `## <version>` opening. Only a release has one.
  *
  * @param {string} text - Section text.
+ * @param {boolean} release - Whether `text` is a release section.
  * @returns {Set<number>}
  */
-function scaffoldLineSet(text) {
-    const lines = text.split("\n");
+function scaffoldLineSet(text, release) {
     const set = new Set();
-    if (RELEASE_HEADING_RE.test(lines[0] ?? "")) set.add(1);
-    for (let i = 0; i < lines.length; i++) {
-        if (CHANGES_HEADING_RE.test(lines[i])) set.add(i + 1);
-    }
+    if (release && RELEASE_HEADING_RE.test(text.split("\n")[0] ?? "")) set.add(1);
     return set;
 }
 
+/**
+ * A `### <Bump> Changes` heading in a release section — the scaffold
+ * `changelog group` removes, so one that remains means group has not run.
+ *
+ * @param {string} text - Release section text.
+ * @param {Set<number>} codeLines
+ * @returns {RelativeFinding[]}
+ */
+function checkChangesHeadings(text, codeLines) {
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    text.split("\n").forEach((line, i) => {
+        if (codeLines.has(i + 1) || !CHANGES_HEADING_RE.test(line)) return;
+        findings.push({
+            line: i + 1,
+            column: 1,
+            severity: "error",
+            message:
+                "changelog-check/changes-heading a `### … Changes` heading survives in the " +
+                "release — run `package-build changelog group`, which removes it",
+        });
+    });
+    return findings;
+}
+
 /**
  * Run every rule over one section of release prose.
  *
  * @param {string} text - The section, already isolated by the caller.
  * @param {object} [opts]
- * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, for
- *   {@link checkUnknownLabels}. `null`/absent checks nothing.
+ * @param {readonly string[]|null} [opts.labels] - the changelog `labels`, for
+ *   {@link checkShape}.
+ * @param {boolean} [opts.release] - `text` is a release section, whose
+ *   `## <version>` line is scaffold and whose `### … Changes` headings are
+ *   findings.
  * @returns {RelativeFinding[]} Findings with line numbers relative to `text`.
  */
-function lintSection(text, { labels = null } = {}) {
+function lintSection(text, { labels = null, release = false } = {}) {
     const codeLines = codeLineSet(text);
     const maskedRegions = codeRegions(text, { spans: true });
-    const scaffoldLines = scaffoldLineSet(text);
+    const scaffoldLines = scaffoldLineSet(text, release);
+    if (release)
+        text.split("\n").forEach((line, i) => {
+            if (CHANGES_HEADING_RE.test(line)) scaffoldLines.add(i + 1);
+        });
     const bullets = topLevelBullets(text, codeLines);
-    const blocks = topLevelBlocks(text, codeLines, scaffoldLines);
 
     return [
         ...checkCommitHash(text, codeLines, scaffoldLines),
@@ -687,7 +810,8 @@ function lintSection(text, { labels = null } = {}) {
         ...checkTooManyBullets(bullets),
         ...checkTooManyLines(text),
         ...checkCodeLikeTokens(text, maskedRegions),
-        ...checkUnknownLabels(blocks, labels),
+        ...checkShape(text, codeLines, scaffoldLines, labels),
+        ...(release ? checkChangesHeadings(text, codeLines) : []),
     ].sort((a, b) => a.line - b.line || (a.column ?? 0) - (b.column ?? 0));
 }
 
@@ -738,9 +862,9 @@ function extractReleaseSection(text) {
  *
  * @param {string} text - The file's full contents, frontmatter included.
  * @param {object} [opts]
- * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
- *   display order, or `null`/absent when the repository declares none —
- *   {@link checkUnknownLabels} checks nothing in that case.
+ * @param {readonly string[]|null} [opts.labels] - the changelog `labels`, in
+ *   display order, or `null`/absent when the repository declares none, in
+ *   which case only {@link MISCELLANEOUS} is accepted.
  * @returns {{findings: Array<{line: number, column?: number,
  *   severity: "error"|"warning", message: string}>}}
  */
@@ -758,9 +882,9 @@ export function lintChangesetText(text, { labels = null } = {}) {
  *
  * @param {string} text - The changelog's full contents.
  * @param {object} [opts]
- * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
- *   display order, or `null`/absent when the repository declares none —
- *   {@link checkUnknownLabels} checks nothing in that case.
+ * @param {readonly string[]|null} [opts.labels] - the changelog `labels`, in
+ *   display order, or `null`/absent when the repository declares none, in
+ *   which case only {@link MISCELLANEOUS} is accepted.
  * @returns {{findings: Array<{line?: number, column?: number,
  *   severity: "error"|"warning", message: string}>}}
  */
@@ -776,7 +900,7 @@ export function lintReleaseText(text, { labels = null } = {}) {
             ],
         };
     }
-    const findings = lintSection(section.body, { labels }).map((f) => ({
+    const findings = lintSection(section.body, { labels, release: true }).map((f) => ({
         ...f,
         line: f.line + section.startLine - 1,
     }));

package/engine/content-expand.mjs

@@ -26,7 +26,10 @@
  *    `[[#id]]` link read the label.
  * 3. **Expressions.** `{{…}}` is evaluated — `sql`, `ref`, dates and the
  *    helpers — see {@link module:engine/markdown-expressions.renderMarkdownExpressions}.
- * 4. **Wikilinks.** Each `[[…]]` outside code is resolved against the index by
+ * 4. **First uses.** The first use of each name in the author's prose is
+ *    marked bold — see {@link module:engine/first-use.boldFirstUses}. The
+ *    generated sections take no mark.
+ * 5. **Wikilinks.** Each `[[…]]` outside code is resolved against the index by
  *    {@link module:engine/wikilinks.resolveWikilinks}, and written in the
  *    target's form.
  *
@@ -55,7 +58,8 @@ import { collectAnchors, eventAnchors } from "./anchors.mjs";
 import { protectCode } from "./code-fences.mjs";
 import { scanFigures } from "./content-figures.mjs";
 import { expandContentTables } from "./content-tables.mjs";
-import { markGenerated, splitGenerated } from "./generated-sections.mjs";
+import { boldFirstUses } from "./first-use.mjs";
+import { GENERATED_BOUNDARY, markGenerated, splitGenerated } from "./generated-sections.mjs";
 import { convertNoteWikilinks } from "./helpers.mjs";
 import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
@@ -239,35 +243,32 @@ export function expandContent(
             ]),
     );
 
-    const expressions = renderMarkdownExpressions(
-        web ? markGenerated(tables.markdown, generatedFrom) : tables.markdown,
-        {
-            fm,
-            dates: web ? index.dateContext : reckoningContext(index),
-            file,
-            bodyLine,
-            sqlResults: prepared.inline,
-            events,
-            figures:
-                web ?
-                    {
-                        get: (id) => figuresById.get(id),
-                        // A cross-note `ref` resolves the written address
-                        // exactly as a wikilink does, against every page's
-                        // figures scanned before any page's expressions render.
-                        note: (address) =>
-                            resolveCrossNoteFigures(address, {
-                                contentTypes: index.contentTypes,
-                                packages: index.packages,
-                                noIndexPackages: index.noIndexPackages,
-                                contentPackage: index.contentPackage,
-                                siteIndexMap: index.index,
-                                figuresByAddress,
-                            }),
-                    }
-                :   { get: (id) => figuresById.get(id), link: foundryRefLink },
-        },
-    );
+    const expressions = renderMarkdownExpressions(markGenerated(tables.markdown, generatedFrom), {
+        fm,
+        dates: web ? index.dateContext : reckoningContext(index),
+        file,
+        bodyLine,
+        sqlResults: prepared.inline,
+        events,
+        figures:
+            web ?
+                {
+                    get: (id) => figuresById.get(id),
+                    // A cross-note `ref` resolves the written address
+                    // exactly as a wikilink does, against every page's
+                    // figures scanned before any page's expressions render.
+                    note: (address) =>
+                        resolveCrossNoteFigures(address, {
+                            contentTypes: index.contentTypes,
+                            packages: index.packages,
+                            noIndexPackages: index.noIndexPackages,
+                            contentPackage: index.contentPackage,
+                            siteIndexMap: index.index,
+                            figuresByAddress,
+                        }),
+                }
+            :   { get: (id) => figuresById.get(id), link: foundryRefLink },
+    });
 
     const findings = {
         tables: tables.errors,
@@ -276,11 +277,24 @@ export function expandContent(
         links: [],
     };
 
+    // The first use of each name is counted in the author's prose alone.
+    const sections = splitGenerated(expressions.markdown);
+    const named = {
+        authored: boldFirstUses(sections.authored, {
+            types: web ? index.contentTypes : index.types,
+            packages: index.packages,
+            noIndexPackages: index.noIndexPackages,
+            contentPackage: index.contentPackage,
+        }),
+        generated: sections.generated,
+    };
+
     if (!web) {
+        const marked = named.generated ? `${named.authored}\n${named.generated}` : named.authored;
         let converted;
         let linkError;
         try {
-            converted = convertNoteWikilinks(expressions.markdown, {
+            converted = convertNoteWikilinks(marked, {
                 type: fm.type,
                 id: fm.id,
                 file,
@@ -295,7 +309,7 @@ export function expandContent(
         } catch (error) {
             linkError = error;
         }
-        const body = converted?.markdown ?? expressions.markdown;
+        const body = converted?.markdown ?? marked;
         return {
             markdown: body,
             authored: body,
@@ -338,7 +352,14 @@ export function expandContent(
     // The book resolves the body whole, so a link's occurrence counts across
     // the author's text and the generated sections it prints after it.
     if (book) {
-        const split = splitGenerated(protectCode(expressions.markdown, resolve));
+        const split = splitGenerated(
+            protectCode(
+                named.generated ?
+                    `${named.authored}\n${GENERATED_BOUNDARY}\n${named.generated}`
+                :   named.authored,
+                resolve,
+            ),
+        );
         return {
             markdown: split.generated ? `${split.authored}\n${split.generated}` : split.authored,
             authored: split.authored,
@@ -356,12 +377,11 @@ export function expandContent(
     // The author's text and the generated sections are resolved apart, so a
     // caller can tell the links the author wrote from the ones a section
     // derives.
-    const split = splitGenerated(expressions.markdown);
-    const authored = protectCode(split.authored, resolve);
+    const authored = protectCode(named.authored, resolve);
     const authoredLinks = resolved.length;
-    const generated = split.generated ? protectCode(split.generated, resolve) : "";
+    const generated = named.generated ? protectCode(named.generated, resolve) : "";
     return {
-        markdown: split.generated ? `${authored}\n${generated}` : authored,
+        markdown: named.generated ? `${authored}\n${generated}` : authored,
         authored,
         generated,
         lineMap,

package/engine/content-format.yaml

@@ -55,7 +55,6 @@ types:
             - lore
             - parents
             - culture
-            - language
             - glossary
             - relations
         subTypes:
@@ -283,7 +282,6 @@ types:
             - culture
             - form
             - subjects
-            - language
             - events
             - appearanceProfile
             - glossary

package/engine/content-index.mjs

@@ -87,6 +87,8 @@
 
 import { isAddressSegment } from "./address-charset.mjs";
 import { configFileIn, resolveNoteCalendars } from "./note-calendars.mjs";
+import { resolveNoteLanguages } from "./note-language.mjs";
+import { nameFormLists } from "./name-forms.mjs";
 import { cultureInheritance, reportCultureParents } from "./culture-parents.mjs";
 import {
     formatDiagnostic,
@@ -106,6 +108,7 @@ import { AddressLink } from "./address-values.mjs";
 import { scanSpans } from "./content-spans.mjs";
 import { rebaseNameSpans } from "./name-markup.mjs";
 import { analyzeNameSpans } from "./names.mjs";
+import { nameRefFindings } from "./name-refs.mjs";
 import { fillEncodingRuns, recordRuns } from "./run-rows.mjs";
 import fs from "node:fs";
 import path from "node:path";
@@ -249,27 +252,31 @@ export function noteAddress(frontmatter, contentPackage) {
 }
 
 /**
- * A note's `name.aliases` reduced to printable 7-bit ASCII, in order.
+ * A note's listed name forms reduced to printable 7-bit ASCII, by language.
  *
- * An alias is the name a reader is at least as likely to reach for as the
- * canonical one — `Killer Whale` for an orca, `Ice Bear` for a polar bear,
- * `Ix'balam` for a jaguar — so anything searching or completing over the index
- * has to match them too, and needs the same keyboard-typeable form
- * {@link asciiName} gives the primary name.
+ * A listed form is a name a reader is at least as likely to reach for as the
+ * full one — `Killer Whale` for an orca, a people's own name for the people —
+ * so anything searching or completing over the index has to match them too,
+ * and needs the same keyboard-typeable form {@link asciiName} gives the full
+ * name.
  *
- * Order is the authored order, so a caller can pair an entry with the alias it
- * came from. An alias that is not a non-empty string, or that leaves nothing
- * printable behind, is dropped rather than left as a hole — the array is a set
- * of names to match, and a null in it is not one.
+ * Each language keeps its authored order, so a caller can pair an entry with
+ * the form it came from. A form that leaves nothing printable behind is
+ * dropped rather than left as a hole, and a language left with no form is
+ * left out.
  *
- * @param {unknown} aliases - The note's `name.aliases`; may be absent or null.
- * @returns {Array<string>} Possibly empty, never null: a note with no aliases
- *   has an empty set of them, which is a fact rather than a missing value, and
- *   a consumer iterating it should not have to check first.
+ * @param {unknown} name - The note's `name`; may be absent or null.
+ * @returns {Record<string, string[]>} Possibly empty, never null: a note
+ *   listing no form has an empty map, which a consumer iterating it need not
+ *   check first.
  */
-export function asciiAliases(aliases) {
-    if (!Array.isArray(aliases)) return [];
-    return aliases.map((alias) => asciiName(alias)).filter((alias) => alias !== null);
+export function asciiForms(name) {
+    const out = {};
+    for (const [code, forms] of nameFormLists(name)) {
+        const folded = forms.map((form) => asciiName(form)).filter((form) => form !== null);
+        if (folded.length) out[code] = folded;
+    }
+    return out;
 }
 
 /**
@@ -423,7 +430,7 @@ function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage, raw)
  * Build one index record from a note's frontmatter and its place in the tree.
  *
  * The frontmatter as authored, plus what the index derives from it: the package
- * it compiles as, its address, ASCII folds of its name and aliases, the anchors
+ * it compiles as, its address, ASCII folds of its name and listed forms, the anchors
  * of its body, its Foundry block, the address of its documentation journal, and
  * where the file sits within the tree.
  *
@@ -482,10 +489,20 @@ export function buildIndexRecord({
     assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage, raw);
 
     const source = body ?? "";
-    const spans = syntax ? syntax(source).spans.names : scanSpans(source).names;
-    const marked = analyzeNameSpans(
-        rebaseNameSpans(spans, { raw: raw ?? source, bodyLine, bodyColumn }),
-        { file: absPath ?? relPath, types: nameTypes },
+    const scannedSpans = syntax ? syntax(source).spans : scanSpans(source);
+    const origin = { raw: raw ?? source, bodyLine, bodyColumn };
+    const marked = analyzeNameSpans(rebaseNameSpans(scannedSpans.names, origin), {
+        file: absPath ?? relPath,
+        types: nameTypes,
+    });
+    marked.findings.push(
+        ...nameRefFindings(
+            rebaseNameSpans(
+                scannedSpans.spans.filter((span) => span.attrs.some(([key]) => key === "ref")),
+                origin,
+            ),
+            { file: absPath ?? relPath },
+        ),
     );
     if (marked.findings.length) {
         const findings = marked.findings.map(({ line, column, ...finding }) => ({
@@ -548,7 +565,7 @@ export function buildIndexRecord({
                 runs: recordRuns(source, { context: runContext, bodyLine, bodyColumn, syntax }),
                 address: stub ? null : address,
                 nameAscii: asciiName(frontmatter?.name?.full),
-                aliasesAscii: asciiAliases(frontmatter?.name?.aliases),
+                formsAscii: asciiForms(frontmatter?.name),
                 // Each anchor carries the link that reaches it, so a section is
                 // addressable from the index without anyone re-deriving how an
                 // anchor is spelled — its file line, so an editor can jump
@@ -1284,6 +1301,15 @@ export function collectContentIndex(
         problems,
         parsed,
     });
+    // Languages read the culture a note states, as calendars do.
+    resolveNoteLanguages(records, {
+        contentPackage,
+        languages,
+        contentBase,
+        foreignRecord,
+        problems,
+        parsed,
+    });
     resolveCultures(records, { contentPackage, contentBase, foreignRecord, problems, parsed });
     const cultureNotes = records
         .filter((record) => isNoteRecord(record) && record.type === "lore")

package/engine/content-links.mjs

@@ -242,6 +242,10 @@ export function buildLinkIndex(
         // The calendar the index resolved, which the reckoning context built
         // over these notes hands to every date printed for this note.
         if (record.resolvedCalendar) note.resolvedCalendar = record.resolvedCalendar;
+        // The language the index derived, and the code a language note is the
+        // note of, which the glossary and `npc new` read.
+        if (typeof record.lang === "string") note.lang = record.lang;
+        if (typeof record.languageCode === "string") note.languageCode = record.languageCode;
         const hierarchyProblems = cultureRecordProblems(record);
         note.inheritedCultureFields = cultureInheritedFields(record);
         if (hierarchyProblems)

package/engine/content-lint.mjs

@@ -42,9 +42,8 @@
  * **Nothing here writes.** A check reports and an author fixes.
  *
  * **There is deliberately no third rule** requiring every note to repeat its
- * own `type-shortcode` address in a top-level `aliases:` list. It would serve
- * no build reader: the resolver and the checker parse the hyphen
- * qualifier themselves.
+ * own `type-shortcode` address in its frontmatter. It would serve no build
+ * reader: the resolver and the checker parse the hyphen qualifier themselves.
  *
  * **What is deliberately absent.** Corpus reachability — "every Rules document
  * is reachable from the book's root" — is a statement about what one package

package/engine/content-render.mjs

@@ -27,12 +27,13 @@
  * | a heading's id | as authored | as authored, or its text's | as authored | as authored |
  * | quotes, dashes and ellipses | as written | typographic | as written | as written, set by Typst |
  * | raw HTML in a note | passed through | passed through | shown as text | shown as text |
+ * | a name's first use | bold | bold | bold, with an index | bold |
  * | the output | HTML | HTML | HTML | the token stream, for the Typst stage |
  *
  * A target differs from the others only in that table. The shared plugins are
  * footnotes, definition lists, dictionary rows, bracket spans, dictionary
- * entries, heading attributes, icons and body images; each renderer's `plugins`
- * lists what its target installs.
+ * entries, heading attributes, icons, body images and first uses; each
+ * renderer's `plugins` lists what its target installs.
  *
  * ## The stages of a render
  *
@@ -72,6 +73,7 @@ import { dictionaryListPlugin } from "./definition-list.mjs";
 import { alertMarkdownPlugin, renderAlerts, scanAlerts } from "./content-alerts.mjs";
 import { renderBlocks, renderWithheldSections } from "./content-blocks.mjs";
 import { renderFigureBlocks } from "./content-figures.mjs";
+import { firstUsePlugin } from "./first-use.mjs";
 import { iconPlugin } from "./content-icons.mjs";
 import { imagePlugin } from "./content-images.mjs";
 import { renderRuns } from "./content-scripts.mjs";
@@ -390,6 +392,7 @@ export function createRenderer(target, options = {}) {
         use("definition-lists", deflistPlugin);
         use("icons", iconPlugin(options.icons));
         use("images", imagePlugin());
+        use("first-use", firstUsePlugin);
     } else {
         use("cartouche-figures", cartoucheFigures);
         use("definition-lists", deflistPlugin);
@@ -409,6 +412,7 @@ export function createRenderer(target, options = {}) {
         // A buffer with no index has no registry to draw an icon from.
         if (!source) use("icons", iconPlugin(options.icons));
         use("images", imagePlugin(options.images?.resolveSrc, options.images?.lookupAsset));
+        use("first-use", firstUsePlugin);
         footnoteMarkup(md);
         if (preview)
             use("preview-source", previewSourcePlugin, { ...options.sourceContext, source });

package/engine/culture-parents.mjs

@@ -15,7 +15,7 @@ import { isDeepStrictEqual } from "node:util";
 import { canonicalKey, parseAddress, renderAddress } from "./address.mjs";
 import { positionOfFrontmatterPath, formatDiagnostic } from "./diagnostics.mjs";
 
-const fields = ["language", "appearanceProfile"];
+const fields = ["appearanceProfile"];
 const payload = (note) => note.fm ?? note;
 const dataOf = (note) => payload(note).data ?? payload(note);
 const culture = (note) => payload(note).type === "lore" && payload(note).subType === "culture";