@heroiclands/package-build 23.9.0 → 23.11.0

package/types/engine/anchors.d.mts

@@ -12,22 +12,25 @@
  *   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.
+ *   kind: string, secret?: boolean}>} 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;
     line: number;
     kind: string;
+    secret?: boolean;
 }>;
 /** 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.

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

@@ -0,0 +1,108 @@
+/**
+ * Capture one source tree for index, lint, links and compilation.
+ * No source or parser state is persisted or reused by another invocation.
+ * Prepared SQL databases close within their existing preparation functions.
+ * @param {object} [options]
+ * @param {import("../content-config.mjs").ContentBuildConfig} [options.config] - Exact resolved configuration.
+ * @param {string} [options.contentBase] - Content root, defaulting to configuration.
+ * @param {string} [options.assetsBase] - Assets root, defaulting to configuration.
+ * @param {readonly string[]} [options.skipDirectories] - Resolved content scope.
+ * @param {ReturnType<typeof routerFor>} [options.router] - One router shared by this session's compile.
+ * @returns {Promise<ContentSession>} Captured sources and lazy prepared views; dispose after use.
+ */
+export function createContentSession({ config, contentBase, assetsBase, skipDirectories, router, }?: {
+    config?: import("../content-config.mjs").ContentBuildConfig | undefined;
+    contentBase?: string | undefined;
+    assetsBase?: string | undefined;
+    skipDirectories?: readonly string[] | undefined;
+    router?: {
+        resolve: (fm: object, docType: string, system?: string) => string | undefined;
+        resolveOrNull: (fm: object, docType: string, system?: string) => string | undefined;
+        packsOfType: (docType: string) => string[];
+        defaultOf: (docType: string) => string | undefined;
+    } | undefined;
+}): Promise<ContentSession>;
+/**
+ * @typedef {"index"|"lint"|"links"|"compile"} ContentTarget
+ * @typedef {(source: string) => {blocks: ReturnType<typeof blocks.scanBlocks>, alerts: ReturnType<typeof alerts.scanAlerts>, spans: ReturnType<typeof spans.scanSpans>}} ContentSyntax
+ * @typedef {{config?: import("../content-config.mjs").ContentBuildConfig, contentBase?: string, assetsBase?: string, skipDirectories?: readonly string[], router?: ReturnType<typeof routerFor>}} ContentSessionContext
+ * @typedef {{frontmatter: object|null, body: string, raw: string, bodyLine?: number, bodyColumn?: number}} ContentNoteSource
+ * @typedef {object} ContentSession
+ * @property {import("../content-config.mjs").ContentBuildConfig} config
+ * @property {string} contentBase
+ * @property {string} assetsBase
+ * @property {readonly string[]} skipDirectories
+ * @property {ReturnType<typeof routerFor>} router
+ * @property {ReturnType<typeof captureContentSources>} inventory
+ * @property {Map<string, {raw: string}>} sources
+ * @property {object[]} records
+ * @property {Map<string, ContentNoteSource>} parsed
+ * @property {object[]} problems
+ * @property {ReturnType<typeof loadForeignIndexes>} foreign
+ * @property {ContentSyntax} syntax
+ * @property {(options?: ContentSessionContext) => void} assertContext
+ * @property {(audience?: "all"|"public") => ReturnType<typeof sql.prepareTreeSqlTables>} sqlTables
+ * @property {() => ReturnType<typeof sql.prepareLinkSqlTables>} linkTables
+ * @property {(kind?: "lint"|"links") => Promise<ReturnType<typeof buildLinkIndex>>} audit
+ * @property {() => Promise<import("./content-index.mjs").PreparedContentIndex>} publication
+ * @property {() => ReturnType<import("./compile-corpus.mjs").buildCompileCorpus>} compileCorpus
+ * @property {(targets: readonly ContentTarget[]) => Promise<ContentSession>} prepare
+ * @property {() => void} dispose
+ */
+/**
+ * The explicit runner's target vocabulary and execution order.
+ * @type {readonly ContentTarget[]}
+ */
+export const CONTENT_TARGETS: readonly ContentTarget[];
+export type ContentTarget = "index" | "lint" | "links" | "compile";
+export type ContentSyntax = (source: string) => {
+    blocks: ReturnType<typeof blocks.scanBlocks>;
+    alerts: ReturnType<typeof alerts.scanAlerts>;
+    spans: ReturnType<typeof spans.scanSpans>;
+};
+export type ContentSessionContext = {
+    config?: import("../content-config.mjs").ContentBuildConfig;
+    contentBase?: string;
+    assetsBase?: string;
+    skipDirectories?: readonly string[];
+    router?: ReturnType<typeof routerFor>;
+};
+export type ContentNoteSource = {
+    frontmatter: object | null;
+    body: string;
+    raw: string;
+    bodyLine?: number;
+    bodyColumn?: number;
+};
+export type ContentSession = {
+    config: import("../content-config.mjs").ContentBuildConfig;
+    contentBase: string;
+    assetsBase: string;
+    skipDirectories: readonly string[];
+    router: ReturnType<typeof routerFor>;
+    inventory: ReturnType<typeof captureContentSources>;
+    sources: Map<string, {
+        raw: string;
+    }>;
+    records: object[];
+    parsed: Map<string, ContentNoteSource>;
+    problems: object[];
+    foreign: ReturnType<typeof loadForeignIndexes>;
+    syntax: ContentSyntax;
+    assertContext: (options?: ContentSessionContext) => void;
+    sqlTables: (audience?: "all" | "public") => ReturnType<typeof sql.prepareTreeSqlTables>;
+    linkTables: () => ReturnType<typeof sql.prepareLinkSqlTables>;
+    audit: (kind?: "lint" | "links") => Promise<ReturnType<typeof buildLinkIndex>>;
+    publication: () => Promise<import("./content-index.mjs").PreparedContentIndex>;
+    compileCorpus: () => ReturnType<typeof import("./compile-corpus.mjs").buildCompileCorpus>;
+    prepare: (targets: readonly ContentTarget[]) => Promise<ContentSession>;
+    dispose: () => void;
+};
+import * as blocks from "./content-blocks.mjs";
+import * as alerts from "./content-alerts.mjs";
+import * as spans from "./content-spans.mjs";
+import { routerFor } from "./pack-router.mjs";
+import { captureContentSources } from "./content-sources.mjs";
+import { loadForeignIndexes } from "./metadata-index.mjs";
+import * as sql from "./sql-tables.mjs";
+import { buildLinkIndex } from "./content-links.mjs";

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

@@ -0,0 +1,32 @@
+/**
+ * Capture exact text once and retain directory entries for physical checks.
+ * The index walk and raw check walks retain their established traversal orders.
+ * @param {string} contentBase - Absolute content root.
+ * @param {string} assetsBase - Absolute assets root.
+ * @param {readonly string[]} skipDirectories - Resolved directory scope.
+ * @returns {{sources: Map<string, {raw: string}>, indexSources: Map<string, {raw: string}>, paths: Array<{root: string, file: string, name: string, directory: boolean}>}} Captured input and physical walk order.
+ */
+export function captureContentSources(contentBase: string, assetsBase: string, skipDirectories: readonly string[]): {
+    sources: Map<string, {
+        raw: string;
+    }>;
+    indexSources: Map<string, {
+        raw: string;
+    }>;
+    paths: Array<{
+        root: string;
+        file: string;
+        name: string;
+        directory: boolean;
+    }>;
+};
+/**
+ * Select the exact physical scope of a raw checker from a captured map.
+ * @param {string} contentBase - Content root.
+ * @param {Map<string, {raw: string}>} sources - Captured physical sources.
+ * @param {readonly string[]} skipDirectories - Directory names to ignore.
+ * @param {Set<string>} extensions - Lowercase extensions accepted by the caller.
+ */
+export function capturedSources(contentBase: string, sources: Map<string, {
+    raw: string;
+}>, skipDirectories: readonly string[], extensions: Set<string>): Generator<string[], void, unknown>;

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

@@ -1,18 +1,20 @@
 /** Add bracket spans after recognized Markdown links and footnotes.
  * @param {import("markdown-it")} md - Markdown parser to extend.
+ * @param {object} [options] - Surface presentation.
+ * @param {boolean} [options.spoilers] - Add visible static Secret labels (Foundry).
  */
-export function spanMarkdownPlugin(md: typeof import("markdown-it")): void;
+export function spanMarkdownPlugin(md: typeof import("markdown-it"), { spoilers }?: {
+    spoilers?: boolean | undefined;
+}): void;
 /** Read span anchors and located attribute diagnostics outside literal code.
  * @param {string} source - Authored Markdown.
+ * @returns {import("./name-markup.mjs").SpanScan} Actual spans, explicit names and located diagnostics.
  */
-export function scanSpans(source: string): {
-    spans: any[];
-    errors: any[];
-};
+export function scanSpans(source: string): import("./name-markup.mjs").SpanScan;
 /** Emit span tags while leaving their inline content as Markdown for Hugo.
  * @param {string} source - Authored Markdown.
  */
 export function renderSpans(source: string): {
     markdown: string;
-    errors: any[];
+    errors: import("./name-markup.mjs").SpanFinding[];
 };

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

@@ -43,12 +43,16 @@ export function checkTaskLists(body: string, file: string, { bodyLine, bodyColum
  * @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 lintContentTaskLists(contentBase: string, { skipDirectories }?: {
+export function lintContentTaskLists(contentBase: string, { skipDirectories, sources }?: {
     skipDirectories?: readonly string[] | undefined;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
 }): {
     findings: Array<{
         file: string;

package/types/engine/diagnostics.d.mts

@@ -1,3 +1,13 @@
+/**
+ * Split opening YAML frontmatter from its untrimmed body without parsing it.
+ * LF and CRLF delimiters retain the exact source strings and their offsets.
+ * @param {string} raw - Complete Markdown source.
+ * @returns {{yaml: string, body: string}|null} Source slices, or no fence.
+ */
+export function splitFrontmatter(raw: string): {
+    yaml: string;
+    body: string;
+} | null;
 /**
  * The `file:line:column` locator, with whatever is known.
  *

package/types/engine/extension-attributes.d.mts

@@ -6,15 +6,29 @@
  * @param {RegExp} [options.idPattern=NAME] - What an `#id` may be named. A
  *   construct whose id is published as an HTML `id` admits a digit first and
  *   passes a looser pattern; the default is the pattern every other name takes.
- * @returns {{id: string, classes: string[], values: Record<string, string>, problems: string[]}}
+ * @param {boolean} [options.positions=false] - Retain the first supplied
+ *   attribute's key/value ranges as UTF-16 offsets within this input.
+ * @returns {{id: string, classes: string[], values: Record<string, string>, problems: string[],
+ *   positions?: Record<string, {key: {start: number, end: number}, value: {start: number, end: number}}>}}
  */
-export function parseExtensionAttributes(source: string, { idPattern }?: {
+export function parseExtensionAttributes(source: string, { idPattern, positions }?: {
     idPattern?: RegExp | undefined;
+    positions?: boolean | undefined;
 }): {
     id: string;
     classes: string[];
     values: Record<string, string>;
     problems: string[];
+    positions?: Record<string, {
+        key: {
+            start: number;
+            end: number;
+        };
+        value: {
+            start: number;
+            end: number;
+        };
+    }>;
 };
 /** A Boolean attribute is spelled exactly `true` or `false`. */
 export function booleanAttribute(value: any, key: any): boolean;

package/types/engine/first-use.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Prepare indexed names once, then check only explicit occurrences without reading files.
+ * @param {{records: readonly object[], index: object,
+ *   catalog?: import("./names.mjs").NameCatalog,
+ *   parsed?: Map<string, {raw: string, body: string, bodyLine?: number, bodyColumn?: number}>,
+ *   syntax?: import("./content-session.mjs").ContentSyntax}} options - Lint's
+ *   records/resolver and optional captured authored-body projections.
+ * @returns {(note: {file: string, raw: string}) => Array<{file: string, line: number, column: number, severity: "warning", rules: string[], message: string}>} Located warning diagnostics.
+ */
+export function createFirstUseChecker({ records, index, parsed, syntax, catalog, }: {
+    records: readonly object[];
+    index: object;
+    catalog?: import("./names.mjs").NameCatalog;
+    parsed?: Map<string, {
+        raw: string;
+        body: string;
+        bodyLine?: number;
+        bodyColumn?: number;
+    }>;
+    syntax?: import("./content-session.mjs").ContentSyntax;
+}): (note: {
+    file: string;
+    raw: string;
+}) => Array<{
+    file: string;
+    line: number;
+    column: number;
+    severity: "warning";
+    rules: string[];
+    message: string;
+}>;