@heroiclands/package-build 23.8.0 → 23.10.0

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

@@ -0,0 +1,96 @@
+/**
+ * Whether frontmatter supplies an automatic lexical section, including on a
+ * note with no authored prose. Such a note has content and is not a stub.
+ *
+ * @param {object|null|undefined} frontmatter - A note or its index record.
+ * @returns {boolean} Whether its own nonempty words or glossary qualify.
+ */
+export function hasLexicalEntries(frontmatter: object | null | undefined): boolean;
+/**
+ * One automatic section, whose rows are rendered at its containing heading's
+ * level when inserted.
+ *
+ * @typedef {object} LexicalSection
+ * @property {string} slug - The canonical section anchor and layout name.
+ * @property {string} heading - The heading used when none is authored.
+ * @property {readonly string[]} aliases - Authored heading anchors to reuse.
+ * @property {{columns: string[], rows: object[]}} result - The selected rows.
+ * @property {import("./dictionary-layout.mjs").LayoutOptions} options - Labels,
+ *   linkability and the page's language, shared by every surface.
+ */
+/**
+ * Automatic lexical sections by owning note's canonical Address. Only
+ * nonempty own `words` or `glossary` arrays qualify. A glossary selects only
+ * explicitly declared owner entries, including a rank only when named there.
+ *
+ * @param {object[]} records - The audience's visible index records.
+ * @param {object[]} [all=records] - Complete records for lineage traversal.
+ * @returns {Map<string, LexicalSection[]>} Sections by owning Address.
+ */
+export function lexicalSectionsFor(records: object[], all?: object[]): Map<string, LexicalSection[]>;
+/**
+ * Insert lists at the end of their authored anchored sections, or append a
+ * new H1 section when no heading names one. Source lines after an insertion
+ * retain their original positions; inserted lines point to their heading.
+ *
+ * @param {string} markdown - The body with authored directives expanded.
+ * @param {LexicalSection[]} [sections=[]] - From {@link lexicalSectionsFor}.
+ * @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, syntax }?: {
+    authored?: string;
+    lineMap?: object[];
+    generatedFrom?: number;
+    syntax?: import("./content-session.mjs").ContentSyntax;
+}): {
+    markdown: string;
+    lineMap: object[];
+    generatedFrom?: number;
+};
+/** The automatic lexical sections and the authored anchors each may reuse. */
+export const LEXICAL_SECTIONS: readonly Readonly<{
+    aliases: readonly string[];
+    types: readonly Readonly<{
+        type: string;
+        subType: string;
+    } | {
+        type: string;
+        subType?: undefined;
+    }>[];
+    slug: string;
+    heading: string;
+    dataKey: string;
+}>[];
+/**
+ * One automatic section, whose rows are rendered at its containing heading's
+ * level when inserted.
+ */
+export type LexicalSection = {
+    /**
+     * - The canonical section anchor and layout name.
+     */
+    slug: string;
+    /**
+     * - The heading used when none is authored.
+     */
+    heading: string;
+    /**
+     * - Authored heading anchors to reuse.
+     */
+    aliases: readonly string[];
+    /**
+     * - The selected rows.
+     */
+    result: {
+        columns: string[];
+        rows: object[];
+    };
+    /**
+     * - Labels,
+     * linkability and the page's language, shared by every surface.
+     */
+    options: import("./dictionary-layout.mjs").LayoutOptions;
+};

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;
+};

package/types/engine/names.d.mts

@@ -0,0 +1,356 @@
+/**
+ * An indexed whole-label match. Ambiguous labels retain every candidate.
+ * @typedef {object} NameMatch
+ * @property {string} key - Canonical page identity, or the ambiguous label identity.
+ * @property {string} full - Declared full name.
+ * @property {true} indexed - The identity belongs to the indexed catalog.
+ * @property {boolean} [fullUse] - The label is a full-name form rather than an alias.
+ * @property {NameMatch[]} [candidates] - Indexed identities sharing the label.
+ * @property {string} [destination] - Canonical Address used by a resolved link.
+ */
+/**
+ * The prepared name and declared-alias lookup.
+ * @typedef {object} NameCatalog
+ * @property {(label: string, preferred?: {key: string}) => NameMatch|undefined} recognize - Match a whole visible label.
+ * @property {(target: string) => NameMatch|undefined} resolve - Resolve an Address target without its anchor to its indexed identity.
+ */
+/**
+ * One captured marked-name occurrence.
+ * @typedef {object} MarkedName
+ * @property {string} name - Rendered visible text.
+ * @property {string|null} type - Supplied valid type, or null.
+ * @property {string|null} subType - Supplied valid subtype, or null.
+ * @property {number} line - Original 1-based file line.
+ * @property {number} column - Original 1-based UTF-16 file column.
+ */
+/**
+ * One reported source use.
+ * @typedef {object} NameUse
+ * @property {string|null} owner - Canonical NOTE owner, or null for an unaddressed record.
+ * @property {string|undefined} file - Stored path relative to the content root.
+ * @property {number} line - Original 1-based file line.
+ * @property {number} column - Original 1-based UTF-16 file column.
+ */
+/**
+ * Unwritten names sharing one supplied kind.
+ * @typedef {object} UnwrittenNameGroup
+ * @property {string|null} type - Supplied type, or null.
+ * @property {string|null} subType - Supplied subtype, or null.
+ * @property {Array<{name: string, uses: NameUse[]}>} names - Normalized labels and every source use.
+ */
+/**
+ * A parsed span with its original source sites and visible text.
+ * @typedef {object} ParsedNameSpan
+ * @property {string} visible - Text from the actual parsed children.
+ * @property {ReadonlyArray<readonly [string, string]>} attrs - Retained permitted attributes.
+ * @property {number} line - Original 1-based file line of the opening bracket.
+ * @property {number} column - Original 1-based UTF-16 file column of the bracket.
+ * @property {Readonly<Record<string, {key: {line: number, column: number}}>>} [attributePositions] - Actual attribute-key sites.
+ */
+/**
+ * One invalid supplied name kind.
+ * @typedef {object} NameKindFinding
+ * @property {string} [file] - Authored source file.
+ * @property {number} [line] - Actual attribute-key line when supplied by the parser.
+ * @property {number} [column] - Actual attribute-key UTF-16 column when known.
+ * @property {"error"} severity - Invalid supplied values fail validation.
+ * @property {string} message - The invalid value and the declaration it must follow.
+ */
+/**
+ * A marked name whose supplied kinds disagree.
+ * @typedef {object} NameConflict
+ * @property {string} name - Normalized visible label.
+ * @property {Array<{type: string, subType: string|null, uses: NameUse[]}>} kinds - Every supplied typed use; untyped uses are excluded.
+ */
+/**
+ * The current package's unwritten names and incompatible supplied facts.
+ * @typedef {object} NamesReport
+ * @property {string} package - Owning content package.
+ * @property {UnwrittenNameGroup[]} unwritten - Unresolved labels grouped by supplied kind.
+ * @property {NameConflict[]} conflicts - Labels with incompatible supplied kinds.
+ */
+/**
+ * Normalize a whole visible label without folding its case.
+ * @param {string} text - Visible name or declared alias.
+ * @returns {string} NFC text with straight apostrophes and single spaces.
+ */
+export function normalizeName(text: string): string;
+/**
+ * Whole-label possessives and regular plurals; other forms are declared aliases.
+ * @param {string} text - Full name or declared alias.
+ * @returns {string[]} Supported whole-label forms.
+ */
+export function nameForms(text: string): string[];
+/**
+ * Prepare full names, declared aliases and link identities from captured records.
+ * @param {object} options - The invocation's existing corpus and link index.
+ * @param {readonly object[]} options.records - Captured local records.
+ * @param {ReturnType<typeof import("./content-links.mjs").buildLinkIndex>} options.index - Captured address space.
+ * @returns {NameCatalog} Pure whole-label and Address lookups.
+ */
+export function createNameCatalog({ records, index }: {
+    records: readonly object[];
+    index: ReturnType<typeof import("./content-links.mjs").buildLinkIndex>;
+}): NameCatalog;
+/**
+ * Group unwritten marked names from captured record fields alone.
+ * @param {object} options - Current package records and prepared known names.
+ * @param {readonly object[]} options.records - Authored records carrying `names` entries.
+ * @param {NameCatalog} options.catalog - Invocation-owned indexed name lookup.
+ * @returns {{groups: UnwrittenNameGroup[], firstUse: NameUse|undefined}} Every use and the earliest located reported occurrence.
+ */
+export function collectUnwrittenNames({ records, catalog }: {
+    records: readonly object[];
+    catalog: NameCatalog;
+}): {
+    groups: UnwrittenNameGroup[];
+    firstUse: NameUse | undefined;
+};
+/**
+ * Analyze actual parsed name spans using one supplied-kind validation route.
+ * @param {readonly ParsedNameSpan[]} spans - Parsed spans at original file coordinates.
+ * @param {object} [options] - Existing note declarations and source context.
+ * @param {string} [options.file] - Authored source file.
+ * @param {Readonly<Record<string, {subTypes?: readonly string[]|null}>>} [options.vocabulary] - Actual note vocabulary.
+ * @param {Iterable<string>} [options.types] - Additional bare types from configured declarations.
+ * @returns {{names: MarkedName[], findings: NameKindFinding[]}} Valid occurrence fields and every invalid supplied attribute.
+ */
+export function analyzeNameSpans(spans: readonly ParsedNameSpan[], { file, vocabulary, types }?: {
+    file?: string | undefined;
+    vocabulary?: Readonly<Record<string, {
+        subTypes?: readonly string[] | null;
+    }>> | undefined;
+    types?: Iterable<string> | undefined;
+}): {
+    names: MarkedName[];
+    findings: NameKindFinding[];
+};
+/**
+ * Build one package report from captured explicit names and the prepared catalog.
+ * Untyped facts and matching parent/subtype refinements are compatible.
+ * @param {object} options - Existing package corpus and lookup.
+ * @param {string} options.package - Owning content package.
+ * @param {readonly object[]} options.records - Captured current-package records.
+ * @param {NameCatalog} options.catalog - Invocation-owned indexed name lookup.
+ * @returns {NamesReport} Deterministic structured groups without diagnostics or I/O.
+ */
+export function createNamesReport({ package: contentPackage, records, catalog }: {
+    package: string;
+    records: readonly object[];
+    catalog: NameCatalog;
+}): NamesReport;
+/**
+ * Format one readable advisory containing every reported source use.
+ * @param {NamesReport} report - Structured package report.
+ * @param {object} [options] - Source-path context for the caller's diagnostics.
+ * @param {string} [options.contentBase] - Content root for stored relative paths.
+ * @returns {{file?: string, line?: number, column?: number, severity: "warning", message: string}|undefined} One advisory, or none when both groups are empty.
+ */
+export function namesReportFinding(report: NamesReport, { contentBase }?: {
+    contentBase?: string | undefined;
+}): {
+    file?: string;
+    line?: number;
+    column?: number;
+    severity: "warning";
+    message: string;
+} | undefined;
+/**
+ * An indexed whole-label match. Ambiguous labels retain every candidate.
+ */
+export type NameMatch = {
+    /**
+     * - Canonical page identity, or the ambiguous label identity.
+     */
+    key: string;
+    /**
+     * - Declared full name.
+     */
+    full: string;
+    /**
+     * - The identity belongs to the indexed catalog.
+     */
+    indexed: true;
+    /**
+     * - The label is a full-name form rather than an alias.
+     */
+    fullUse?: boolean | undefined;
+    /**
+     * - Indexed identities sharing the label.
+     */
+    candidates?: NameMatch[] | undefined;
+    /**
+     * - Canonical Address used by a resolved link.
+     */
+    destination?: string | undefined;
+};
+/**
+ * The prepared name and declared-alias lookup.
+ */
+export type NameCatalog = {
+    /**
+     * - Match a whole visible label.
+     */
+    recognize: (label: string, preferred?: {
+        key: string;
+    }) => NameMatch | undefined;
+    /**
+     * - Resolve an Address target without its anchor to its indexed identity.
+     */
+    resolve: (target: string) => NameMatch | undefined;
+};
+/**
+ * One captured marked-name occurrence.
+ */
+export type MarkedName = {
+    /**
+     * - Rendered visible text.
+     */
+    name: string;
+    /**
+     * - Supplied valid type, or null.
+     */
+    type: string | null;
+    /**
+     * - Supplied valid subtype, or null.
+     */
+    subType: string | null;
+    /**
+     * - Original 1-based file line.
+     */
+    line: number;
+    /**
+     * - Original 1-based UTF-16 file column.
+     */
+    column: number;
+};
+/**
+ * One reported source use.
+ */
+export type NameUse = {
+    /**
+     * - Canonical NOTE owner, or null for an unaddressed record.
+     */
+    owner: string | null;
+    /**
+     * - Stored path relative to the content root.
+     */
+    file: string | undefined;
+    /**
+     * - Original 1-based file line.
+     */
+    line: number;
+    /**
+     * - Original 1-based UTF-16 file column.
+     */
+    column: number;
+};
+/**
+ * Unwritten names sharing one supplied kind.
+ */
+export type UnwrittenNameGroup = {
+    /**
+     * - Supplied type, or null.
+     */
+    type: string | null;
+    /**
+     * - Supplied subtype, or null.
+     */
+    subType: string | null;
+    /**
+     * - Normalized labels and every source use.
+     */
+    names: Array<{
+        name: string;
+        uses: NameUse[];
+    }>;
+};
+/**
+ * A parsed span with its original source sites and visible text.
+ */
+export type ParsedNameSpan = {
+    /**
+     * - Text from the actual parsed children.
+     */
+    visible: string;
+    /**
+     * - Retained permitted attributes.
+     */
+    attrs: ReadonlyArray<readonly [string, string]>;
+    /**
+     * - Original 1-based file line of the opening bracket.
+     */
+    line: number;
+    /**
+     * - Original 1-based UTF-16 file column of the bracket.
+     */
+    column: number;
+    /**
+     * - Actual attribute-key sites.
+     */
+    attributePositions?: Readonly<Record<string, {
+        key: {
+            line: number;
+            column: number;
+        };
+    }>> | undefined;
+};
+/**
+ * One invalid supplied name kind.
+ */
+export type NameKindFinding = {
+    /**
+     * - Authored source file.
+     */
+    file?: string | undefined;
+    /**
+     * - Actual attribute-key line when supplied by the parser.
+     */
+    line?: number | undefined;
+    /**
+     * - Actual attribute-key UTF-16 column when known.
+     */
+    column?: number | undefined;
+    /**
+     * - Invalid supplied values fail validation.
+     */
+    severity: "error";
+    /**
+     * - The invalid value and the declaration it must follow.
+     */
+    message: string;
+};
+/**
+ * A marked name whose supplied kinds disagree.
+ */
+export type NameConflict = {
+    /**
+     * - Normalized visible label.
+     */
+    name: string;
+    /**
+     * - Every supplied typed use; untyped uses are excluded.
+     */
+    kinds: Array<{
+        type: string;
+        subType: string | null;
+        uses: NameUse[];
+    }>;
+};
+/**
+ * The current package's unwritten names and incompatible supplied facts.
+ */
+export type NamesReport = {
+    /**
+     * - Owning content package.
+     */
+    package: string;
+    /**
+     * - Unresolved labels grouped by supplied kind.
+     */
+    unwritten: UnwrittenNameGroup[];
+    /**
+     * - Labels with incompatible supplied kinds.
+     */
+    conflicts: NameConflict[];
+};

package/types/engine/note-addresses.d.mts

@@ -8,8 +8,8 @@ export function addressPositions(fm: object, context?: {}): object[];
  * Decode declared properties at the note boundary. Raw mappings cannot impersonate tuples.
  *
  * A declared Address is read as written. A shortcode spelled with a capital is
- * refused, and every such value in the note is collected before the decode
- * throws, so each reference is reported at its own position: the thrown error
+ * refused, as is a document Address in a language-note field. Every such value
+ * is collected before the decode throws, so each is reported at its own position: the thrown error
  * describes the first, and its `findings` carry all of them.
  *
  * @param {object} fm - Parsed YAML or an index record.
@@ -18,7 +18,7 @@ export function addressPositions(fm: object, context?: {}): object[];
  *   refused shortcode when it is declared.
  * @returns {object} The same note carrying typed Address properties.
  * @throws {Error} When a declared Address is refused; `keyPath` locates it, and
- *   `findings`, where present, lists every refused shortcode.
+ *   `findings`, where present, lists every refused value.
  */
 export function decodeNoteAddresses(fm: object, context: object): object;
 /**