@heroiclands/package-build 23.8.0 → 23.10.0

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/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.8.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,7 +327,27 @@ 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.
+ * 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, session?: import("./content-session.mjs").ContentSession}} [options]
+ * @returns {Promise<PreparedContentIndex>}
+ */
+export function prepareContentIndex({ contentBase, config, session }?: {
+    contentBase?: string;
+    config?: object;
+    session?: import("./content-session.mjs").ContentSession;
+}): Promise<PreparedContentIndex>;
 /**
  * Emit this package's content index.
  *
@@ -328,6 +357,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}}}
@@ -341,10 +371,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;
@@ -363,6 +394,59 @@ 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;
+    }>;
+    /**
+     * - Session-local exact-text scanner projections.
+     */
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
+};
 import { collectAnchors } from "./anchors.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";
 import { DERIVED_KEYS } 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.