@heroiclands/package-build 23.9.0 → 23.11.0

package/types/engine/foundry-entries.d.mts

@@ -13,9 +13,10 @@
  * @param {string} entryId - The entry's id, which page ids hash against.
  * @param {string} body - The note's markdown body.
  * @param {string} name - The note's name, used as the lead page's title.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Session scanner projections.
  * @returns {Record<string, string>} The anchors.
  */
-export function anchorsOf(entryUuid: string, entryId: string, body: string, name: string): Record<string, string>;
+export function anchorsOf(entryUuid: string, entryId: string, body: string, name: string, syntax?: import("./content-session.mjs").ContentSyntax): Record<string, string>;
 /**
  * The manifest entries a single note produces.
  *
@@ -37,11 +38,17 @@ export function anchorsOf(entryUuid: string, entryId: string, body: string, name
  * documentation journal's is {@link itemDocEntryId} of that. Stating it here is
  * what lets the content index publish an identity it did not re-derive.
  *
- * @param {object} ctx - Resolved identities: `{ contentPackage,
- *   foundryPackageId, packRouter }`.
+ * @param {{contentPackage: string, foundryPackageId: string, packRouter: object, web?: boolean, skipDirectories?: readonly string[], syntax?: import("./content-session.mjs").ContentSyntax}} ctx - Resolved identities and optional session scanner projections.
  * @returns {Array<object>} One or two entries, in {@link buildManifest}'s shape.
  */
-export function entriesForNote(fm: object, name: string, address: string, body: string, ctx: object): Array<object>;
+export function entriesForNote(fm: object, name: string, address: string, body: string, ctx: {
+    contentPackage: string;
+    foundryPackageId: string;
+    packRouter: object;
+    web?: boolean;
+    skipDirectories?: readonly string[];
+    syntax?: import("./content-session.mjs").ContentSyntax;
+}): Array<object>;
 /**
  * Every note this package publishes, as manifest entries.
  *

package/types/engine/generate.d.mts

@@ -201,12 +201,16 @@ export function emptyPassErrors(passes: Array<{
  *   package's tree — and how the guard-order test below induces id drift, now
  *   that the manifest is located by configuration rather than by the working
  *   directory.
+ * @param {import("./content-session.mjs").ContentSession} [opts.session] - Same configuration, root and scope as this generation.
+ * @param {boolean} [opts.reportPreparation=true] - Emit shared preparation findings; false when already reported by the caller.
  * @returns {Promise<number>} Total error count across the generated packs.
  * @throws {Error} If the configured Foundry package id has drifted from the
  *   shipped manifest's `id` (see `package-manifest.mjs`).
  */
-export function generatePacksJson({ only, config }?: {
+export function generatePacksJson({ only, config, session, reportPreparation, }?: {
     only?: string | undefined;
     config?: object | undefined;
+    session?: import("./content-session.mjs").ContentSession | undefined;
+    reportPreparation?: boolean | undefined;
 }): Promise<number>;
 export function packJsonDir(name: string, config?: object): string;

package/types/engine/helpers.d.mts

@@ -17,7 +17,7 @@ export function renderFoundryMarkdown(body: string, figures?: Array<{
     label: string;
 }>, footnoteNumbers?: Map<string, number>, docId?: string, resolveRole?: (address: string) => string | undefined): string;
 /**
- * Parses a markdown file with YAML frontmatter.
+ * Parses a markdown file with LF or CRLF YAML frontmatter delimiters.
  *
  * Returns `{ frontmatter, body, description, bodyLine, bodyColumn, raw }` where
  * `body` is the trimmed raw markdown after the frontmatter block, and
@@ -29,13 +29,19 @@ export function renderFoundryMarkdown(body: string, figures?: Array<{
  * `{ frontmatter: null, body: "", description: "", raw }` and no
  * position: there is no body to have one.
  * @param {string} filePath - Markdown file to read.
- * @param {{addressContext?: object}} [opts] - Address defaults for decoded fields.
+ * @param {object} [opts]
+ * @param {object} [opts.addressContext] - Address defaults for decoded fields.
+ * @param {string} [opts.raw] - Exact captured source; omitted, reads the file.
+ * @param {boolean} [opts.renderDescription=true] - Render the body's HTML description.
+ *   False leaves `description` empty for readers that only use authored text.
  * @returns {{frontmatter: object|null, body: string, description: string, raw: string,
  *   bodyLine?: number, bodyColumn?: number, parseError?: {message: string,
  *   line?: number, column?: number}}} Parsed note and body position.
  */
-export function parseMarkdownFile(filePath: string, { addressContext }?: {
-    addressContext?: object;
+export function parseMarkdownFile(filePath: string, { addressContext, raw: capturedRaw, renderDescription }?: {
+    addressContext?: object | undefined;
+    raw?: string | undefined;
+    renderDescription?: boolean | undefined;
 }): {
     frontmatter: object | null;
     body: string;
@@ -105,17 +111,24 @@ export function assertSuppliedCorpus(records: readonly object[] | undefined, who
  *   Required: the scope is the caller's to state, so two passes cannot
  *   disagree about which files are the corpus.
  * @param {object} [opts.addressContext] - Address resolution context.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Selected sources in walk order.
+ *   Supplied, the walk parses these strings instead of reading the filesystem.
+ * @param {boolean} [opts.renderDescription=true] - Render each body's description.
  * @yields {{frontmatter: object|null, body: string, description: string,
  *   file: string, absPath: string, bodyLine?: number, bodyColumn?: number}}
  *   One entry per `.md` file found.
  * @throws {Error} When `skipDirectories` is not stated — see
  *   {@link assertStatedScope}.
  */
-export function walkMarkdownTree(rootDir: string, { skipDirectories, addressContext }?: {
+export function walkMarkdownTree(rootDir: string, { skipDirectories, addressContext, sources, renderDescription }?: {
     skipDirectories: readonly string[];
     addressContext?: object | undefined;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
+    renderDescription?: boolean | undefined;
 }): Generator<{
-    file: string & NonSharedBuffer;
+    file: string;
     absPath: string;
     frontmatter: object | null;
     body: string;
@@ -366,12 +379,22 @@ export function defaultStats(): object;
  *   compile and handed in. Required: see {@link assertSuppliedCorpus}.
  * @param {Map<string, object[]>} [opts.sqlTables] - Prepared directives,
  *   including the anchors and Foundry page maps of their expanded bodies.
+ * @param {ReturnType<import("./metadata-index.mjs").loadForeignIndexes>} [opts.foreign] -
+ *   Captured dependency address and reference views for this context.
  * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
-export function buildContentLinkIndex(contentBase: string, router?: object, { config, records, sqlTables }?: {
+export function buildContentLinkIndex(contentBase: string, router?: object, { config, records, sqlTables, foreign: capturedForeign }?: {
     config?: object | undefined;
     records?: readonly object[] | undefined;
     sqlTables?: Map<string, object[]> | undefined;
+    foreign?: {
+        index: Map<string, object>;
+        packages: Set<string>;
+        stale: Array<{
+            package: string;
+            reason: string;
+        }>;
+    } | undefined;
 }): {
     byShortcode: Map<any, any>;
     types: Set<any>;

package/types/engine/index.d.mts

@@ -50,6 +50,7 @@ export * as noteIds from "./note-ids.mjs";
 export * as metadataIndex from "./metadata-index.mjs";
 export * as foundryEntries from "./foundry-entries.mjs";
 export * as contentIndex from "./content-index.mjs";
+export * as contentSession from "./content-session.mjs";
 export * as assetTypes from "./asset-types.mjs";
 export * as assetIndex from "./asset-index.mjs";
 export * as assetShipping from "./asset-shipping.mjs";

package/types/engine/journals.d.mts

@@ -29,11 +29,12 @@
  *   picture's address to the role its asset declares, so a figure page's
  *   name reads `Map 1` rather than `Figure 1` where it is due — see
  *   {@link module:engine/content-figures.scanFigures}.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Session scanner projections.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
  *   classes: string[], figure: object|null, continues?: string,
  *   markdown: string}>} Pages in document order.
  */
-export function splitPages(body: string, leadName?: string, resolveRole?: (address: string) => string | undefined): Array<{
+export function splitPages(body: string, leadName?: string, resolveRole?: (address: string) => string | undefined, syntax?: import("./content-session.mjs").ContentSyntax): Array<{
     name: string;
     anchorSlug: string | null;
     level: number;
@@ -190,9 +191,10 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   a picture's address to the role its asset declares, so a figure page's
  *   name reads `Map 1` rather than `Figure 1` where it is due — see
  *   {@link module:engine/content-figures.scanFigures}.
+ * @param {import("./content-session.mjs").ContentSyntax} [params.syntax] - Session scanner projections.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, stats, infoboxes, notice, resolveRole, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, stats, infoboxes, notice, resolveRole, syntax, }: {
     id: string;
     name: string;
     markdown: string;
@@ -206,6 +208,7 @@ export function buildJournalEntry({ id, name, markdown, leadName, folder, stats,
     }[] | undefined;
     notice?: string | undefined;
     resolveRole?: ((address: string) => string | undefined) | undefined;
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
 }): object;
 /**
  * Journals pack compiler.

package/types/engine/lexical-sections.d.mts

@@ -35,15 +35,16 @@ export function lexicalSectionsFor(records: object[], all?: object[]): Map<strin
  *
  * @param {string} markdown - The body with authored directives expanded.
  * @param {LexicalSection[]} [sections=[]] - From {@link lexicalSectionsFor}.
- * @param {{authored?: string, lineMap?: object[], generatedFrom?: number}} [context] -
+ * @param {{authored?: string, lineMap?: object[], generatedFrom?: number, syntax?: import("./content-session.mjs").ContentSyntax}} [context] -
  *   The original authored body, source mappings and the start of appended
  *   nonlexical generated sections. Without `authored`, `markdown` is the source.
  * @returns {{markdown: string, lineMap: object[], generatedFrom?: number}}
  */
-export function insertLexicalSections(markdown: string, sections?: LexicalSection[], { authored, lineMap, generatedFrom }?: {
+export function insertLexicalSections(markdown: string, sections?: LexicalSection[], { authored, lineMap, generatedFrom, syntax }?: {
     authored?: string;
     lineMap?: object[];
     generatedFrom?: number;
+    syntax?: import("./content-session.mjs").ContentSyntax;
 }): {
     markdown: string;
     lineMap: object[];

package/types/engine/markup-validation.d.mts

@@ -3,9 +3,10 @@
  * Frontmatter is masked so literal YAML values cannot become body markup.
  * @param {string} source - Complete Markdown source, optionally with frontmatter.
  * @param {string} file - Diagnostic filename.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Exact-text scanner projections.
  * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors.
  */
-export function markupFindings(source: string, file: string): Array<{
+export function markupFindings(source: string, file: string, syntax?: import("./content-session.mjs").ContentSyntax): Array<{
     file: string;
     line: number;
     column: number;

package/types/engine/name-markup.d.mts

@@ -0,0 +1,176 @@
+/** Pure projections of parsed inline text and original marked-name positions. */
+/**
+ * An original source range with its opening file position.
+ * @typedef {object} SpanSourceSite
+ * @property {number} start - Inclusive UTF-16 source offset.
+ * @property {number} end - Exclusive UTF-16 source offset.
+ * @property {number} line - Original 1-based source line.
+ * @property {number} column - Original 1-based UTF-16 source column.
+ */
+/**
+ * The retained attribute key and value at their authored positions.
+ * @typedef {object} SpanAttributePosition
+ * @property {SpanSourceSite} key - Attribute name, without surrounding whitespace.
+ * @property {SpanSourceSite} value - Authored value, without its surrounding quotes.
+ */
+/**
+ * One actual bracketed span and its renderer-derived visible text.
+ * @typedef {object} ContentSpan
+ * @property {string} id - Normalized anchor, or an empty string.
+ * @property {number} start - Inclusive UTF-16 offset of the opening bracket.
+ * @property {number} end - Exclusive UTF-16 offset after the complete span.
+ * @property {number} line - Original 1-based line of the opening bracket.
+ * @property {number} column - Original 1-based UTF-16 column of the bracket.
+ * @property {string} text - Inline label source passed to the existing parser.
+ * @property {number} contentEnd - Original UTF-16 offset of the closing label bracket.
+ * @property {string} visible - Visible text from the actual parsed children.
+ * @property {ReadonlyArray<readonly [string, string]>} attrs - Retained permitted HTML attributes.
+ * @property {Record<string, SpanAttributePosition>} attributePositions - Authored key/value sites by retained attribute name.
+ */
+/**
+ * One located span-grammar or refused-attribute finding.
+ * @typedef {object} SpanFinding
+ * @property {number} line - Original 1-based source line.
+ * @property {number} column - Original 1-based UTF-16 source column.
+ * @property {string} message - The existing grammar or attribute diagnostic.
+ */
+/**
+ * A captured authored span inventory.
+ * @typedef {object} SpanScan
+ * @property {ContentSpan[]} spans - All actual parsed bracketed spans in source order.
+ * @property {ContentSpan[]} names - The same span objects carrying the exact name class.
+ * @property {SpanFinding[]} errors - Located diagnostics in source order.
+ */
+/**
+ * Visible name text from the renderer's actual parsed children. Footnote
+ * markers and images supply no name text; references have already resolved.
+ * @param {readonly object[]} tokens - Parsed inline tokens.
+ * @returns {string} Text without inline formatting or annotation markers.
+ */
+export function inlineText(tokens: readonly object[]): string;
+/**
+ * Rebase an authored body's captured names to its original raw file.
+ * The inventory is read only; no source parsing or second marker scan occurs.
+ * @template {ContentSpan} Span
+ * @param {readonly Span[]} spans - The captured body's name spans.
+ * @param {{raw: string, bodyLine?: number, bodyColumn?: number}} source - Original body origin.
+ * @returns {Span[]} Copies retaining the span metadata with raw offsets and file coordinates.
+ */
+export function rebaseNameSpans<Span extends ContentSpan>(spans: readonly Span[], { raw, bodyLine, bodyColumn }: {
+    raw: string;
+    bodyLine?: number;
+    bodyColumn?: number;
+}): Span[];
+/**
+ * An original source range with its opening file position.
+ */
+export type SpanSourceSite = {
+    /**
+     * - Inclusive UTF-16 source offset.
+     */
+    start: number;
+    /**
+     * - Exclusive UTF-16 source offset.
+     */
+    end: number;
+    /**
+     * - Original 1-based source line.
+     */
+    line: number;
+    /**
+     * - Original 1-based UTF-16 source column.
+     */
+    column: number;
+};
+/**
+ * The retained attribute key and value at their authored positions.
+ */
+export type SpanAttributePosition = {
+    /**
+     * - Attribute name, without surrounding whitespace.
+     */
+    key: SpanSourceSite;
+    /**
+     * - Authored value, without its surrounding quotes.
+     */
+    value: SpanSourceSite;
+};
+/**
+ * One actual bracketed span and its renderer-derived visible text.
+ */
+export type ContentSpan = {
+    /**
+     * - Normalized anchor, or an empty string.
+     */
+    id: string;
+    /**
+     * - Inclusive UTF-16 offset of the opening bracket.
+     */
+    start: number;
+    /**
+     * - Exclusive UTF-16 offset after the complete span.
+     */
+    end: number;
+    /**
+     * - Original 1-based line of the opening bracket.
+     */
+    line: number;
+    /**
+     * - Original 1-based UTF-16 column of the bracket.
+     */
+    column: number;
+    /**
+     * - Inline label source passed to the existing parser.
+     */
+    text: string;
+    /**
+     * - Original UTF-16 offset of the closing label bracket.
+     */
+    contentEnd: number;
+    /**
+     * - Visible text from the actual parsed children.
+     */
+    visible: string;
+    /**
+     * - Retained permitted HTML attributes.
+     */
+    attrs: ReadonlyArray<readonly [string, string]>;
+    /**
+     * - Authored key/value sites by retained attribute name.
+     */
+    attributePositions: Record<string, SpanAttributePosition>;
+};
+/**
+ * One located span-grammar or refused-attribute finding.
+ */
+export type SpanFinding = {
+    /**
+     * - Original 1-based source line.
+     */
+    line: number;
+    /**
+     * - Original 1-based UTF-16 source column.
+     */
+    column: number;
+    /**
+     * - The existing grammar or attribute diagnostic.
+     */
+    message: string;
+};
+/**
+ * A captured authored span inventory.
+ */
+export type SpanScan = {
+    /**
+     * - All actual parsed bracketed spans in source order.
+     */
+    spans: ContentSpan[];
+    /**
+     * - The same span objects carrying the exact name class.
+     */
+    names: ContentSpan[];
+    /**
+     * - Located diagnostics in source order.
+     */
+    errors: SpanFinding[];
+};

package/types/engine/name-rows.d.mts

@@ -0,0 +1,35 @@
+/**
+ * Project captured occurrences without reading sources or changing records.
+ * @param {Iterable<Record<string, any>>} records - Index records, already narrowed
+ *   to the audience; canonical Addresses may be typed or encoded strings.
+ * @returns {NameRow[]} One row per occurrence, in record then source order.
+ */
+export function namesRows(records: Iterable<Record<string, any>>): NameRow[];
+/** Every column of the `names` relation, in order. */
+export const NAME_COLUMNS: readonly string[];
+export type NameRow = {
+    /**
+     * - Containing authored page's canonical NOTE Address.
+     */
+    owner: string | null;
+    /**
+     * - Rendered visible text of the occurrence.
+     */
+    name: string;
+    /**
+     * - Supplied note type, or null.
+     */
+    type: string | null;
+    /**
+     * - Supplied subtype, or null.
+     */
+    subType: string | null;
+    /**
+     * - Original 1-based source line at the opening bracket.
+     */
+    line: number;
+    /**
+     * - Original 1-based UTF-16 source column at that bracket.
+     */
+    column: number;
+};