@heroiclands/package-build 23.9.0 → 23.11.0

package/engine/helpers.mjs

@@ -70,7 +70,7 @@ import { buildWikilinkIndex, convertWikilinks } from "./wikilinks.mjs";
 import { linkFindingMessage } from "./wikilink-syntax.mjs";
 // The declared tag vocabulary, which is where `draft` is stated. Read
 // from there rather than respelt, so the tag and its one reader cannot drift.
-import { isDraftNote } from "./note-vocabulary.mjs";
+import { isGmNote, 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";
@@ -78,7 +78,7 @@ 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,7 +108,7 @@ let localAssetImageInfoCache;
 export const md = markdownit({ html: true })
     .use(footnotePlugin)
     .use(deflistPlugin)
-    .use(spanMarkdownPlugin)
+    .use(spanMarkdownPlugin, { spoilers: true })
     .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.
@@ -233,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
@@ -245,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+.*$/, "");
@@ -279,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++;
@@ -288,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
@@ -376,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
@@ -395,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) {
@@ -413,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,
                 };
@@ -785,12 +812,14 @@ import { collectAnchors } from "./anchors.mjs";
  *   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, sqlTables } = {},
+    { config, records, sqlTables, foreign: capturedForeign } = {},
 ) {
     const docs = [];
     /** The files this package ships, by canonical address. */
@@ -859,6 +888,8 @@ export function buildContentLinkIndex(
             // *into* this note renders marked. It takes no part in resolution,
             // so the note is indexed, compiled and published as any other.
             draft: isDraftNote(fm),
+            gm: isGmNote(fm),
+            noteAnchors: [...(record.anchors ?? []), ...(prepared?.anchors ?? [])],
             // The anchors this note declares, carried so the *builds* can check
             // a `#section` link and not only the checker. A foreign
             // anchor has always been checked, because a fetched index
@@ -892,7 +923,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

@@ -103,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;
@@ -142,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 = [];
@@ -636,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({
@@ -648,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,
@@ -827,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
@@ -627,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

@@ -1142,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.",
     }),
 ]);
 
@@ -1472,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",

package/engine/lexical-sections.mjs

@@ -162,8 +162,8 @@ export function lexicalSectionsFor(records, all = records) {
 }
 
 /** Authored section headings outside literal content and named containers. */
-function headings(markdown) {
-    const containers = scanBlocks(markdown).blocks;
+function headings(markdown, syntax) {
+    const containers = (syntax ? syntax(markdown).blocks : scanBlocks(markdown)).blocks;
     return scanHeadingAttributes(markdown)
         .headings.filter(
             (heading) =>
@@ -181,7 +181,7 @@ function headings(markdown) {
  *
  * @param {string} markdown - The body with authored directives expanded.
  * @param {LexicalSection[]} [sections=[]] - From {@link lexicalSectionsFor}.
- * @param {{authored?: string, lineMap?: object[], generatedFrom?: number}} [context] -
+ * @param {{authored?: string, lineMap?: object[], generatedFrom?: number, syntax?: import("./content-session.mjs").ContentSyntax}} [context] -
  *   The original authored body, source mappings and the start of appended
  *   nonlexical generated sections. Without `authored`, `markdown` is the source.
  * @returns {{markdown: string, lineMap: object[], generatedFrom?: number}}
@@ -189,7 +189,7 @@ function headings(markdown) {
 export function insertLexicalSections(
     markdown,
     sections = [],
-    { authored = markdown, lineMap, generatedFrom } = {},
+    { authored = markdown, lineMap, generatedFrom, syntax } = {},
 ) {
     const lines = String(markdown ?? "").split("\n");
     const locations = lineMap ? [...lineMap] : lines.map((_, line) => ({ line, generated: false }));
@@ -200,7 +200,7 @@ export function insertLexicalSections(
             ...(generatedFrom === undefined ? {} : { generatedFrom }),
         };
     const edits = [];
-    const realHeadings = headings(String(authored ?? ""))
+    const realHeadings = headings(String(authored ?? ""), syntax)
         .map((heading) => ({
             ...heading,
             sourceLine: heading.line,

package/engine/markup-validation.mjs

@@ -19,14 +19,19 @@ import { scanAlerts } from "./content-alerts.mjs";
  * Frontmatter is masked so literal YAML values cannot become body markup.
  * @param {string} source - Complete Markdown source, optionally with frontmatter.
  * @param {string} file - Diagnostic filename.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Exact-text scanner projections.
  * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors.
  */
-export function markupFindings(source, file) {
+export function markupFindings(source, file, syntax) {
     const body = String(source ?? "").replace(
         /^\uFEFF?---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/,
         (frontmatter) => frontmatter.replace(/[^\r\n]/g, " "),
     );
-    return [...scanBlocks(body).errors, ...scanAlerts(body).errors].map((error) => ({
+    const scanned = syntax?.(body);
+    return [
+        ...(scanned?.blocks ?? scanBlocks(body)).errors,
+        ...(scanned?.alerts ?? scanAlerts(body)).errors,
+    ].map((error) => ({
         file,
         ...error,
         severity: "error",

package/engine/metadata-index.mjs

@@ -445,6 +445,7 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
             const foundry = record.foundry?.[parts.system];
             index.set(key, {
                 name: record.name?.full ?? record.name,
+                aliases: record.name?.aliases,
                 // Absent where the package publishes no page for it. A consumer
                 // must tolerate that rather than invent an href, exactly as it
                 // already tolerates an entry with no `uuid`.

package/engine/name-markup.mjs

@@ -0,0 +1,114 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/** Pure projections of parsed inline text and original marked-name positions. */
+
+/**
+ * An original source range with its opening file position.
+ * @typedef {object} SpanSourceSite
+ * @property {number} start - Inclusive UTF-16 source offset.
+ * @property {number} end - Exclusive UTF-16 source offset.
+ * @property {number} line - Original 1-based source line.
+ * @property {number} column - Original 1-based UTF-16 source column.
+ */
+
+/**
+ * The retained attribute key and value at their authored positions.
+ * @typedef {object} SpanAttributePosition
+ * @property {SpanSourceSite} key - Attribute name, without surrounding whitespace.
+ * @property {SpanSourceSite} value - Authored value, without its surrounding quotes.
+ */
+
+/**
+ * One actual bracketed span and its renderer-derived visible text.
+ * @typedef {object} ContentSpan
+ * @property {string} id - Normalized anchor, or an empty string.
+ * @property {number} start - Inclusive UTF-16 offset of the opening bracket.
+ * @property {number} end - Exclusive UTF-16 offset after the complete span.
+ * @property {number} line - Original 1-based line of the opening bracket.
+ * @property {number} column - Original 1-based UTF-16 column of the bracket.
+ * @property {string} text - Inline label source passed to the existing parser.
+ * @property {number} contentEnd - Original UTF-16 offset of the closing label bracket.
+ * @property {string} visible - Visible text from the actual parsed children.
+ * @property {ReadonlyArray<readonly [string, string]>} attrs - Retained permitted HTML attributes.
+ * @property {Record<string, SpanAttributePosition>} attributePositions - Authored key/value sites by retained attribute name.
+ */
+
+/**
+ * One located span-grammar or refused-attribute finding.
+ * @typedef {object} SpanFinding
+ * @property {number} line - Original 1-based source line.
+ * @property {number} column - Original 1-based UTF-16 source column.
+ * @property {string} message - The existing grammar or attribute diagnostic.
+ */
+
+/**
+ * A captured authored span inventory.
+ * @typedef {object} SpanScan
+ * @property {ContentSpan[]} spans - All actual parsed bracketed spans in source order.
+ * @property {ContentSpan[]} names - The same span objects carrying the exact name class.
+ * @property {SpanFinding[]} errors - Located diagnostics in source order.
+ */
+
+/**
+ * Visible name text from the renderer's actual parsed children. Footnote
+ * markers and images supply no name text; references have already resolved.
+ * @param {readonly object[]} tokens - Parsed inline tokens.
+ * @returns {string} Text without inline formatting or annotation markers.
+ */
+export function inlineText(tokens) {
+    return tokens
+        .map((token) => {
+            if (token.children && token.type !== "image") return inlineText(token.children);
+            if (token.type === "text" || token.type === "code_inline") return token.content;
+            if (token.type === "softbreak" || token.type === "hardbreak") return " ";
+            return "";
+        })
+        .join("");
+}
+
+/**
+ * Rebase an authored body's captured names to its original raw file.
+ * The inventory is read only; no source parsing or second marker scan occurs.
+ * @template {ContentSpan} Span
+ * @param {readonly Span[]} spans - The captured body's name spans.
+ * @param {{raw: string, bodyLine?: number, bodyColumn?: number}} source - Original body origin.
+ * @returns {Span[]} Copies retaining the span metadata with raw offsets and file coordinates.
+ */
+export function rebaseNameSpans(spans, { raw, bodyLine = 1, bodyColumn = 1 }) {
+    let origin = 0;
+    for (let line = 1; line < bodyLine; line++) origin = raw.indexOf("\n", origin) + 1;
+    origin += bodyColumn - 1;
+    /**
+     * @template {SpanSourceSite} Site
+     * @param {Site} position - Captured relative range and opening position.
+     * @returns {Site} The same metadata at original file coordinates.
+     */
+    const rebase = (position) => ({
+        ...position,
+        start: position.start + origin,
+        end: position.end + origin,
+        line: bodyLine + position.line - 1,
+        column: position.column + (position.line === 1 ? bodyColumn - 1 : 0),
+    });
+    return spans.map((span) => ({
+        ...rebase(span),
+        contentEnd: span.contentEnd + origin,
+        attributePositions: Object.fromEntries(
+            Object.entries(span.attributePositions ?? {}).map(([key, positions]) => [
+                key,
+                { key: rebase(positions.key), value: rebase(positions.value) },
+            ]),
+        ),
+    }));
+}

package/engine/name-rows.mjs

@@ -0,0 +1,70 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Authored `.name` occurrences projected from own-note index records into the
+ * SQL `names` relation. Documentation records and assets contribute no rows.
+ * @module
+ */
+
+import { canonicalKey, readCanonicalKey } from "./address.mjs";
+import { encodeAddresses } from "./address-values.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+
+/** Every column of the `names` relation, in order. */
+export const NAME_COLUMNS = Object.freeze(["owner", "name", "type", "subType", "line", "column"]);
+
+/**
+ * @typedef {object} NameRow
+ * @property {string|null} owner - Containing authored page's canonical NOTE Address.
+ * @property {string} name - Rendered visible text of the occurrence.
+ * @property {string|null} type - Supplied note type, or null.
+ * @property {string|null} subType - Supplied subtype, or null.
+ * @property {number} line - Original 1-based source line at the opening bracket.
+ * @property {number} column - Original 1-based UTF-16 source column at that bracket.
+ */
+
+/**
+ * The containing page's NOTE identity, including for a native Item source.
+ * @param {Record<string, any>} record - An own-note index record.
+ * @returns {string|null} The page Address, or null for an unaddressable record.
+ */
+function ownerOf(record) {
+    const parts = readCanonicalKey(encodeAddresses(record.address?.canonical));
+    return parts ? canonicalKey(parts.package, "note", parts.type, parts.shortcode) : null;
+}
+
+/**
+ * Project captured occurrences without reading sources or changing records.
+ * @param {Iterable<Record<string, any>>} records - Index records, already narrowed
+ *   to the audience; canonical Addresses may be typed or encoded strings.
+ * @returns {NameRow[]} One row per occurrence, in record then source order.
+ */
+export function namesRows(records) {
+    const rows = [];
+    for (const record of records) {
+        if (!record || !isNoteRecord(record) || !Array.isArray(record.names)) continue;
+        const owner = ownerOf(record);
+        for (const entry of record.names) {
+            rows.push({
+                owner,
+                name: entry.name,
+                type: entry.type ?? null,
+                subType: entry.subType ?? null,
+                line: entry.line,
+                column: entry.column,
+            });
+        }
+    }
+    return rows;
+}