@heroiclands/package-build 23.9.0 → 23.10.0

package/engine/sql-tables.mjs

@@ -32,6 +32,7 @@ import { expandContentTables } from "./content-tables.mjs";
 import { NOTE_VOCABULARY, isGmNote } from "./note-vocabulary.mjs";
 import { encodeAddresses, flattenPublishedAddresses } from "./address-values.mjs";
 import { EVENT_COLUMNS, EVENT_SORT_COLUMNS, eventRows } from "./event-rows.mjs";
+import { NAME_COLUMNS, namesRows } from "./name-rows.mjs";
 import {
     GLOSSARY_COLUMNS,
     AFFIX_COLUMNS,
@@ -272,6 +273,7 @@ export async function openNotesDatabase(
     await connection.run("SET threads=1");
     await createRelations(connection, jsonl, encoded, "", audience);
     await createEventRelation(connection, path.join(base, "events.jsonl"), encoded, "", audience);
+    await createNameRelation(connection, path.join(base, "names.jsonl"), encoded, "", audience);
     await createWordRelations(connection, path.join(base, "notes"), encoded, "", audience);
 
     // One schema per declared dependency, so `FROM sohl.notes` reads the notes
@@ -301,6 +303,13 @@ export async function openNotesDatabase(
             `${schema}.`,
             audience,
         );
+        await createNameRelation(
+            connection,
+            flat.replace(/\.jsonl$/, "-names.jsonl"),
+            depRecords,
+            `${schema}.`,
+            audience,
+        );
         await createWordRelations(
             connection,
             flat.replace(/\.jsonl$/, ""),
@@ -334,6 +343,7 @@ export async function openNotesDatabase(
     await connection.run(`CREATE VIEW ${WITH_STUBS_SCHEMA}.notes AS SELECT * FROM entries`);
     for (const relation of [
         "events",
+        "names",
         "words",
         "affixes",
         "fields",
@@ -542,6 +552,41 @@ async function createEventRelation(connection, file, records, prefix, audience)
     await createTableFromFile(connection, `${prefix}events`, readJsonAuto(file));
 }
 
+/**
+ * Create authored name rows from own-note records, with audience filtering and
+ * fixed scalar types even when every optional classification is null.
+ * @param {object} connection - An open DuckDB connection.
+ * @param {string} file - Where to write the rows.
+ * @param {object[]} records - Index records, every Address a string.
+ * @param {string} prefix - A schema to qualify the relation name with.
+ * @param {"all"|"public"} audience - Whether to leave out GM notes.
+ * @returns {Promise<void>}
+ */
+async function createNameRelation(connection, file, records, prefix, audience) {
+    const rows = namesRows(
+        audience === "public" ? records.filter((record) => !isGmNote(record)) : records,
+    );
+    const columnTypes = NAME_COLUMNS.map((column) => [
+        column,
+        column === "line" || column === "column" ? "BIGINT" : "VARCHAR",
+    ]);
+    if (!rows.length) {
+        const columns = columnTypes.map(([column, type]) => `NULL::${type} AS "${column}"`);
+        await connection.run(
+            `CREATE VIEW ${prefix}names AS SELECT ${columns.join(", ")} WHERE false`,
+        );
+        return;
+    }
+    fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join("\n"));
+    const schema = columnTypes.map(([column, type]) => `'${column}': '${type}'`).join(", ");
+    await createTableFromFile(
+        connection,
+        `${prefix}names`,
+        `SELECT * FROM read_json('${file.replace(/'/g, "''")}', columns={${schema}}, ` +
+            "format='newline_delimited', maximum_object_size=20000000)",
+    );
+}
+
 /**
  * Create a relation as a table, so the JSONL behind it is parsed once when the
  * database opens rather than on every query. A view over `read_json_auto`
@@ -1303,21 +1348,22 @@ export function attachGeneratedSections(prepared, generated) {
  * @param {object} [config] - The resolved build configuration.
  * @returns {Promise<void>}
  */
-async function attachPreparedAnchors(prepared, records, contentBase, parsed, config) {
+async function attachPreparedAnchors(prepared, records, contentBase, parsed, config, syntax) {
     const { entriesForNote, foundryIdentities } = await import("./foundry-entries.mjs");
-    const identities = config ? foundryIdentities(config) : undefined;
+    const identities = config ? { ...foundryIdentities(config), syntax } : undefined;
     for (const record of records) {
         if (!isNoteRecord(record)) continue;
         const file = noteFile(contentBase, record);
         const results = prepared.get(file);
         if (!results) continue;
+        if (syntax) results.syntax = syntax;
         const { body } = parsed.get(file) ?? parseMarkdownFile(file);
         const expanded = expandContentTables(body, {
             source: file,
             sqlTables: results,
             pageLists: prepared.pageLists?.get(file),
         }).markdown;
-        results.anchors = collectAnchors(expanded);
+        results.anchors = collectAnchors(expanded, 1, undefined, syntax);
         if (!identities || !record.address?.slug) continue;
         const frontmatter = authoredFrontmatter(record);
         const entries = entriesForNote(
@@ -1429,13 +1475,23 @@ export async function cachedDependencies(config) {
  * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes the
  *   generated sections take in, where the caller holds them already; absent,
  *   they are read from the cache.
+ * @param {import("./content-session.mjs").ContentSyntax} [opts.syntax] - Exact-text scanner projections.
  * @returns {Promise<Map<string, object[]>|undefined>} Results by note path,
  *   carrying `inline` and `pageLists` beside them, or nothing when the tree
  *   holds no such directive and no note is given a generated section.
  */
 export async function prepareTreeSqlTables(
     contentBase,
-    { config, skipDirectories, records, parsed, database, audience = "all", foreignIndex } = {},
+    {
+        config,
+        skipDirectories,
+        records,
+        parsed,
+        database,
+        audience = "all",
+        foreignIndex,
+        syntax,
+    } = {},
 ) {
     // Imported here rather than at module scope: the index reaches the pack
     // compilers through `manifest-emit` → `journals`, so a static import from a
@@ -1514,7 +1570,7 @@ export async function prepareTreeSqlTables(
         pageOnly.inline = new Map();
         pageOnly.pageLists = preparePageLists(indexRecords, sources);
         attachGeneratedSections(pageOnly, derivedOnly);
-        await attachPreparedAnchors(pageOnly, indexRecords, contentBase, notes, config);
+        await attachPreparedAnchors(pageOnly, indexRecords, contentBase, notes, config, syntax);
         return pageOnly;
     }
     // A cell links only where the address it would emit resolves, so a table
@@ -1559,7 +1615,7 @@ export async function prepareTreeSqlTables(
         });
         prepared.inline = await prepareInlineSqlExpressions(db, sources);
         attachGeneratedSections(prepared, generated);
-        await attachPreparedAnchors(prepared, indexRecords, contentBase, notes, config);
+        await attachPreparedAnchors(prepared, indexRecords, contentBase, notes, config, syntax);
         return prepared;
     } finally {
         if (!database) await db.close();
@@ -1578,11 +1634,13 @@ export async function prepareTreeSqlTables(
  * @param {object[]} [opts.records] - Complete index records already derived.
  * @param {Map<string, {body: string, frontmatter: object|null}>} [opts.parsed] - Parsed notes.
  * @param {Map<string, object>} [opts.foreignIndex] - Published dependency indexes.
+ * @param {(audience: "all"|"public") => Promise<Map<string, object[]>|undefined>} [opts.prepareAudience] -
+ *   Context-bound preparation shared with other operations in the same session.
  * @returns {Promise<Map<string, object[]>|undefined>} Prepared tables by source.
  */
 export async function prepareLinkSqlTables(
     contentBase,
-    { config, skipDirectories, records, parsed, foreignIndex } = {},
+    { config, skipDirectories, records, parsed, foreignIndex, prepareAudience } = {},
 ) {
     const { indexRecordsFor } = await import("./content-index.mjs");
     const notes = parsed ?? new Map();
@@ -1619,14 +1677,17 @@ export async function prepareLinkSqlTables(
     selected.pageLists = new Map();
     selected.inline = new Map();
     for (const audience of new Set(sources.values())) {
-        const prepared = await prepareTreeSqlTables(contentBase, {
-            config,
-            skipDirectories,
-            records: allRecords,
-            parsed: notes,
-            foreignIndex,
-            audience,
-        });
+        const prepared =
+            prepareAudience ?
+                await prepareAudience(audience)
+            :   await prepareTreeSqlTables(contentBase, {
+                    config,
+                    skipDirectories,
+                    records: allRecords,
+                    parsed: notes,
+                    foreignIndex,
+                    audience,
+                });
         for (const [file, sourceAudience] of sources) {
             if (sourceAudience !== audience) continue;
             if (prepared?.has(file)) selected.set(file, prepared.get(file));

package/engine/stub-lint.mjs

@@ -124,13 +124,14 @@ function checkNote({ fm, body, file, raw }) {
  * @param {object} opts
  * @param {readonly object[]} opts.records - Index records the caller derived.
  * @param {string} [opts.contentPackage] - Named in the counts line.
+ * @param {Map<string, import("./content-session.mjs").ContentNoteSource>} [opts.parsed] - Captured sources, with the file reader as fallback.
  * @returns {{findings: object[], counts: {full: number, draft: number,
  *   stub: number}, byType: Array<{type: string, full: number, draft: number,
  *   stub: number}>, oldestDrafts: Array<{file: string, modified: Date}>,
  *   summary: string[]}} The findings, the ladder's counts, and the lines a
  *   reader is shown as prose rather than as findings.
  */
-export function lintNoteStates(contentBase, { records, contentPackage } = {}) {
+export function lintNoteStates(contentBase, { records, contentPackage, parsed } = {}) {
     const findings = [];
     const counts = { full: 0, draft: 0, stub: 0 };
     /** @type {Map<string, {full: number, draft: number, stub: number}>} */
@@ -149,8 +150,8 @@ export function lintNoteStates(contentBase, { records, contentPackage } = {}) {
         const absPath = noteFile(contentBase, record);
         const file = path.relative(process.cwd(), absPath);
         const fm = authoredFrontmatter(record);
-        const { body } = parseMarkdownFile(absPath);
-        const raw = fs.readFileSync(absPath, "utf8");
+        const source = parsed?.get(absPath) ?? parseMarkdownFile(absPath);
+        const { body, raw } = source;
 
         // The ladder, read exactly as the `entries` view reads it: the absent
         // address is the state, not a second body test beside it. A note with

package/engine/yaml-lint.mjs

@@ -29,6 +29,7 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { splitFrontmatter } from "./diagnostics.mjs";
 
 /** File extensions that carry YAML, either wholly or in a frontmatter fence. */
 export const YAML_GLOBS = Object.freeze(["*.md", "*.yaml", "*.yml"]);
@@ -42,9 +43,6 @@ export const YAML_GLOBS = Object.freeze(["*.md", "*.yaml", "*.yml"]);
  */
 const ALWAYS_SKIP = Object.freeze([".git/", ".claude/"]);
 
-/** A markdown file's leading frontmatter fence. Mirrors `parseMarkdownFile`. */
-const FENCE = /^---\n([\s\S]*?)\n---/;
-
 /**
  * Present a markdown file to ESLint as the YAML it begins with.
  *
@@ -68,8 +66,8 @@ export const frontmatterProcessor = {
     // container file. Nothing is gained by claiming support for it.
     supportsAutofix: false,
     preprocess(text) {
-        const fence = FENCE.exec(text);
-        return fence ? [{ text: fence[1], filename: "0.yaml" }] : [];
+        const fence = splitFrontmatter(text);
+        return fence ? [{ text: fence.yaml, filename: "0.yaml" }] : [];
     },
     postprocess(messages) {
         return (messages[0] ?? []).map((message) => ({

package/hugo-theme/static/css/style.css

@@ -86,6 +86,10 @@ body {
   -webkit-font-smoothing: antialiased;
 }
 
+.name {
+  font-weight: 700;
+}
+
 a {
   color: var(--accent);
   text-decoration: none;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.9.0",
+    "version": "23.10.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",

package/types/engine/anchors.d.mts

@@ -12,10 +12,11 @@
  *   picture's address to the role its asset declares, so a figure anchor'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] - Exact-text scanner projections.
  * @returns {Array<{slug: string, name: string, level: number, line: number,
  *   kind: string}>} In document order.
  */
-export function collectAnchors(body: string, bodyLine?: number, resolveRole?: (address: string) => string | undefined): Array<{
+export function collectAnchors(body: string, bodyLine?: number, resolveRole?: (address: string) => string | undefined, syntax?: import("./content-session.mjs").ContentSyntax): Array<{
     slug: string;
     name: string;
     level: number;
@@ -25,9 +26,10 @@ export function collectAnchors(body: string, bodyLine?: number, resolveRole?: (a
 /** Collisions involving a div, verse or inline-span anchor.
  * Heading and caption collisions are diagnosed by their existing scanners.
  * @param {string} body - Authored Markdown.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Exact-text scanner projections.
  * @returns {Array<{line: number, column: number, message: string}>} Located collisions.
  */
-export function markupAnchorFindings(body: string): Array<{
+export function markupAnchorFindings(body: string, syntax?: import("./content-session.mjs").ContentSyntax): Array<{
     line: number;
     column: number;
     message: string;

package/types/engine/compendiums.d.mts

@@ -12,6 +12,8 @@
  * @param {string} [opts.stageDest]      Directory the LevelDB packs are built
  *     into, one subdirectory per pack. Defaults to the configured stage.
  * @param {string} [opts.packName]       Restrict the run to a single pack.
+ * @param {import("./content-session.mjs").ContentSession} [opts.session] - Captured context shared with other operations.
+ * @param {boolean} [opts.reportPreparation=true] - Emit shared preparation findings unless the caller already reported them.
  * @throws {Error} If pack JSON generation reported any error. Packs compiled
  *     from incomplete or empty JSON ship blank or short compendiums, and the
  *     omission is invisible until a player looks for content that is not there
@@ -23,11 +25,13 @@
  *     map image is gone before anyone notices it was ever at risk. See
  *     {@link verifyPackSceneLevels}.
  */
-export function compilePacks({ config, sourcePacks, stageDest, packName, }?: {
+export function compilePacks({ config, sourcePacks, stageDest, packName, session, reportPreparation, }?: {
     config?: object | undefined;
     sourcePacks?: string[] | undefined;
     stageDest?: string | undefined;
     packName?: string | undefined;
+    session?: import("./content-session.mjs").ContentSession | undefined;
+    reportPreparation?: boolean | undefined;
 }): Promise<void>;
 /**
  * Cleans and formats source JSON files, removing unnecessary permissions and flags and adding the proper spacing.

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

@@ -15,20 +15,23 @@
  *   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[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
+ * @param {import("./content-session.mjs").ContentSession} [opts.session] - Captured context shared with other operations.
+ * @returns {Promise<{records: object[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[], syntax?: import("./content-session.mjs").ContentSyntax}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
-export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, router, config, problems, }: {
+export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, router, config, problems, session, }: {
     contentBase: string;
     assetsBase?: string | undefined;
     skipDirectories: readonly string[];
     router: object;
     config?: object | undefined;
     problems?: object[] | undefined;
+    session?: import("./content-session.mjs").ContentSession | undefined;
 }): Promise<{
     records: object[];
     parsed: Map<string, object>;
     linkIndex: object;
     sqlTables: Map<string, object[]> | undefined;
     problems: object[];
+    syntax?: import("./content-session.mjs").ContentSyntax;
 }>;

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

@@ -87,13 +87,17 @@ export function checkText(text: string, file: string): Array<{
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
  *   in addition to the dot-directories always skipped.
  * @param {readonly string[]} [opts.extensions] - File extensions to read.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Exact captured source strings; omitted, walks and reads the tree.
  * @returns {{findings: Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>, files: number}} The findings, and how
  *   many files produced them.
  */
-export function lintContentCharset(contentBase: string, { skipDirectories, extensions }?: {
+export function lintContentCharset(contentBase: string, { skipDirectories, extensions, sources }?: {
     skipDirectories?: readonly string[] | undefined;
     extensions?: readonly string[] | undefined;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
 }): {
     findings: Array<{
         file: string;

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

@@ -47,12 +47,16 @@ export function checkHtml(body: string, file: string, { bodyLine, bodyColumn }?:
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
  *   in addition to the dot-directories always skipped.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Exact captured source strings; omitted, walks and reads the tree.
  * @returns {{findings: Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>, files: number}} The findings, and
  *   how many files were read.
  */
-export function lintContentHtml(contentBase: string, { skipDirectories }?: {
+export function lintContentHtml(contentBase: string, { skipDirectories, sources }?: {
     skipDirectories?: readonly string[] | undefined;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
 }): {
     findings: Array<{
         file: string;

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

@@ -119,12 +119,16 @@ export function checkIconRegistry(registry: {
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
  * @param {IconRegistry} [opts.registry] - The package's registry.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Exact captured source strings; omitted, walks and reads the tree.
  * @returns {{findings: Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>, files: number}} What it found.
  */
-export function lintContentIcons(contentBase: string, { skipDirectories, registry }?: {
+export function lintContentIcons(contentBase: string, { skipDirectories, registry, sources }?: {
     skipDirectories?: readonly string[] | undefined;
     registry?: IconRegistry | undefined;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
 }): {
     findings: Array<{
         file: string;

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

@@ -215,13 +215,17 @@ export function checkImages(body: string, file: string, { bodyLine, bodyColumn,
  *   in addition to the dot-directories always skipped.
  * @param {object} [opts.config] - The resolved build configuration, passed to
  *   {@link checkImages} so an address is held to the Foundry surface too.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Exact captured source strings; omitted, walks and reads the tree.
  * @returns {{findings: Array<{file: string, line: number, column: number|undefined,
  *   severity: "error", message: string}>, files: number}} The findings, and how
  *   many files were read.
  */
-export function lintContentImages(contentBase: string, { skipDirectories, config }?: {
+export function lintContentImages(contentBase: string, { skipDirectories, config, sources }?: {
     skipDirectories?: readonly string[] | undefined;
     config?: object | undefined;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
 }): {
     findings: Array<{
         file: string;

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

@@ -100,6 +100,8 @@ export function asciiAliases(aliases: unknown): Array<string>;
  *   and for the one question that decides whether the note publishes a page. A
  *   caller that states no body is stating an empty one, and the note is a stub.
  * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
+ * @param {number} [options.bodyColumn] - The 1-based UTF-16 column of its first character.
+ * @param {Iterable<string>} [options.nameTypes] - Additional bare name kinds from configured type declarations.
  * @param {object} [options.manifest] - The package manifest, which the Foundry
  *   entries are derived against.
  * @param {object} [options.addressContext] - Address resolution context.
@@ -108,6 +110,7 @@ export function asciiAliases(aliases: unknown): Array<string>;
  *   a picture's address to the role its asset declares, so a figure anchor'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} [options.syntax] - Session scanner projections.
  * @returns {Record<string, any>} The record, keys sorted at every depth. A
  *   **stub** — a note with an empty body, on a type an empty body suppresses —
  *   carries `address` and `anchors` as `null`: it publishes no page, so it
@@ -119,7 +122,7 @@ 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, raw, contentPackage, body, bodyLine, manifest, addressContext, dateContext, resolveRole, }: {
+export function buildIndexRecord({ frontmatter, relPath, absPath, raw, contentPackage, body, bodyLine, bodyColumn, nameTypes, manifest, addressContext, dateContext, resolveRole, syntax, }: {
     frontmatter: Record<string, any>;
     relPath: string;
     absPath?: string | undefined;
@@ -127,25 +130,19 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, raw, contentPa
     contentPackage: string;
     body?: string | undefined;
     bodyLine?: number | undefined;
+    bodyColumn?: number | undefined;
+    nameTypes?: Iterable<string> | undefined;
     manifest?: object | undefined;
     addressContext?: object | undefined;
     dateContext?: object | undefined;
     resolveRole?: ((address: string) => string | undefined) | undefined;
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
 }): Record<string, any>;
-/** Derive every index record belonging to one parsed note. */
-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;
-    dateContext: any;
-    resolveRole: any;
-}): object[];
+/**
+ * Derive every index record belonging to one parsed note.
+ * @param {Parameters<typeof buildIndexRecord>[0]} options - Authored note and its context.
+ */
+export function indexRecordsForNote({ frontmatter, body, bodyLine, bodyColumn, nameTypes, relPath, absPath, raw, contentPackage, manifest, addressContext, dateContext, resolveRole, syntax, }: Parameters<typeof buildIndexRecord>[0]): object[];
 /**
  * Write each note's resolved culture into its record, as `data.culture`.
  *
@@ -243,10 +240,13 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  * @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.
+ * @param {Map<string, {raw: string}>} [options.sources] - Selected captured source strings.
+ * @param {import("./content-session.mjs").ContentSyntax} [options.syntax] - Session scanner projections.
+ * @param {Iterable<string>} [options.nameTypes] - Additional bare name kinds from configured type declarations.
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
-export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, }: {
+export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
     contentPackage: string;
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;
@@ -263,6 +263,11 @@ export function collectContentIndex(contentBase: string, { contentPackage, skipD
         bodyLine?: number;
         bodyColumn?: number;
     }> | undefined;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
+    nameTypes?: Iterable<string> | undefined;
 }): Array<Record<string, any>>;
 /**
  * Serialize records as JSON Lines.
@@ -303,9 +308,13 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  *   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.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Selected source strings, in index walk order.
+ * @param {import("./content-session.mjs").ContentSyntax} [opts.syntax] - Session scanner projections.
+ * @param {Iterable<string>} [opts.nameTypes] - Bare name kinds, defaulting to configured item types.
+ * @param {Map<string, object>} [opts.foreignIndex] - Captured dependency address view.
  * @returns {object[]} One record per note, plus one per documentation entry.
  */
-export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, parsed, }?: {
+export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, parsed, sources, syntax, nameTypes, foreignIndex, }?: {
     contentBase?: string | undefined;
     assetsBase?: string | undefined;
     config?: object | undefined;
@@ -318,6 +327,12 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
         bodyLine?: number;
         bodyColumn?: number;
     }> | undefined;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
+    nameTypes?: Iterable<string> | undefined;
+    foreignIndex?: Map<string, object> | undefined;
 }): object[];
 /**
  * Prepare the complete bodies a content-index publication describes.
@@ -325,12 +340,13 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
  * 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]
+ * @param {{contentBase?: string, config?: object, session?: import("./content-session.mjs").ContentSession}} [options]
  * @returns {Promise<PreparedContentIndex>}
  */
-export function prepareContentIndex({ contentBase, config }?: {
+export function prepareContentIndex({ contentBase, config, session }?: {
     contentBase?: string;
     config?: object;
+    session?: import("./content-session.mjs").ContentSession;
 }): Promise<PreparedContentIndex>;
 /**
  * Emit this package's content index.
@@ -426,6 +442,10 @@ export type PreparedContentIndex = {
         }>;
         generatedFrom?: number;
     }>;
+    /**
+     * - Session-local exact-text scanner projections.
+     */
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
 };
 import { collectAnchors } from "./anchors.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";

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

@@ -31,13 +31,11 @@ export function anchorsOf(body: string): Set<string>;
  * not hypothetical: this module carried its own anchor reader until the anchor
  * anchor half, and the two disagreed about which anchors existed.
  *
- * **The file is opened for its bytes and nothing else.** The index deliberately
- * carries no note *body*, and a link lives in the body — so each note is read
- * once, here, for the prose. Everything *about* the note — its frontmatter, its
- * addresses, its anchors — is already in the record, and none of it is derived
- * a second time. That is one read per note rather than the two this module did
- * before, since the walk read the file and it then read it again for the raw
- * text.
+ * **Raw sources can come from the caller's capture.** The published index
+ * carries no note body, while a link lives in the prose. A caller that already
+ * captured the sources supplies `parsed`, so this pass uses those exact raw
+ * strings. Without a captured string, it opens the file for its bytes.
+ * Frontmatter, addresses and anchors still come from the records.
  *
  * The index holds each compiled document under its complete Address. Readable
  * content uses `note`, and system documents use their declared system.
@@ -55,17 +53,33 @@ export function anchorsOf(body: string): Set<string>;
  * @param {object[]} [opts.records] - Index records the caller already derived,
  *   so a command that also needs them — every one of them does, to answer its
  *   `sql` tables — enumerates the corpus once rather than twice.
+ * @param {Map<string, {raw: string}>} [opts.parsed] - Sources captured alongside
+ *   `records` in this invocation, keyed by absolute note path. A raw string is
+ *   used verbatim; a missing string falls back to reading the file. The caller
+ *   owns the map, which this function only reads.
  * @param {object[]} [opts.problems] - Collects the notes the index cannot
  *   record, as diagnostics, instead of letting one of them abort the check
  *   before it has reported anything else.
+ * @param {ReturnType<import("./metadata-index.mjs").loadForeignIndexes>} [opts.foreign] - Captured dependency address and reference views.
  * @returns {object} The notes, the index, and the resolvers built over it.
  */
-export function buildLinkIndex(contentBase: string, { config, skipDirectories, sqlTables, records, problems }?: {
+export function buildLinkIndex(contentBase: string, { config, skipDirectories, sqlTables, records, parsed, problems, foreign: capturedForeign, }?: {
     config?: object | undefined;
     skipDirectories?: readonly string[] | undefined;
     sqlTables?: Map<string, object[]> | undefined;
     records?: object[] | undefined;
+    parsed?: Map<string, {
+        raw: string;
+    }> | undefined;
     problems?: object[] | undefined;
+    foreign?: {
+        index: Map<string, object>;
+        packages: Set<string>;
+        stale: Array<{
+            package: string;
+            reason: string;
+        }>;
+    } | undefined;
 }): object;
 /**
  * Every defect in the addresses a package homepage carries.