@heroiclands/package-build 23.9.0 → 23.11.0

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;
 /**

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

@@ -21,13 +21,28 @@ export function offendingPathCharacters(text: string): string[];
  * @param {string} opts.assetsBase - The package's asset directory, whose
  *   picture roots are walked.
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
+ * @param {ReturnType<import("./content-sources.mjs").captureContentSources>} [opts.inventory] - Captured physical paths in root walk order.
  * @returns {{findings: Array<{file: string, severity: "error", message: string}>,
  *   files: number}} The findings, and how many paths were checked.
  */
-export function lintPathCharset({ contentBase, assetsBase, skipDirectories }: {
+export function lintPathCharset({ contentBase, assetsBase, skipDirectories, inventory }: {
     contentBase: string;
     assetsBase: string;
     skipDirectories?: readonly string[] | undefined;
+    inventory?: {
+        sources: Map<string, {
+            raw: string;
+        }>;
+        indexSources: Map<string, {
+            raw: string;
+        }>;
+        paths: Array<{
+            root: string;
+            file: string;
+            name: string;
+            directory: boolean;
+        }>;
+    } | undefined;
 }): {
     findings: Array<{
         file: string;

package/types/engine/site-build.d.mts

@@ -253,8 +253,8 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     secretErrors: {
         file: any;
         line: number;
-        column: any;
-        message: any;
+        column: number;
+        message: string;
     }[];
     captionErrors: {
         file: any;

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

@@ -13,9 +13,10 @@
  *   ordinary dead address.
  * @param {object[]} [options.records] - Content-index records.
  * @param {Map<string, object>} [options.foreignReferences] - Foreign reference targets.
+ * @param {import("./content-session.mjs").ContentSyntax} [options.syntax] - Exact-text scanner projections.
  * @returns {SiteIndex} The index, and what could not be addressed unambiguously.
  */
-export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, noIndexPackages, package: builderPackage, records, foreignReferences, }?: {
+export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, noIndexPackages, package: builderPackage, records, foreignReferences, syntax, }?: {
     foreignIndex?: Map<string, {
         package: string;
         type?: string;
@@ -23,6 +24,7 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, no
     noIndexPackages?: Set<string> | undefined;
     records?: object[] | undefined;
     foreignReferences?: Map<string, object> | undefined;
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
 }): SiteIndex;
 /**
  * The address keys one page's figures are reachable by — the same two forms

package/types/engine/sql-tables.d.mts

@@ -303,11 +303,12 @@ export function cachedDependencies(config?: object): Promise<Array<{
  * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes the
  *   generated sections take in, where the caller holds them already; absent,
  *   they are read from the cache.
+ * @param {import("./content-session.mjs").ContentSyntax} [opts.syntax] - Exact-text scanner projections.
  * @returns {Promise<Map<string, object[]>|undefined>} Results by note path,
  *   carrying `inline` and `pageLists` beside them, or nothing when the tree
  *   holds no such directive and no note is given a generated section.
  */
-export function prepareTreeSqlTables(contentBase: string, { config, skipDirectories, records, parsed, database, audience, foreignIndex }?: {
+export function prepareTreeSqlTables(contentBase: string, { config, skipDirectories, records, parsed, database, audience, foreignIndex, syntax, }?: {
     config?: object | undefined;
     skipDirectories?: readonly string[] | undefined;
     records?: object[] | undefined;
@@ -318,6 +319,7 @@ export function prepareTreeSqlTables(contentBase: string, { config, skipDirector
     database?: object | undefined;
     audience?: "all" | "public" | undefined;
     foreignIndex?: Map<string, object> | undefined;
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
 }): Promise<Map<string, object[]> | undefined>;
 /**
  * Prepare authored link-check tables in each source note's audience. Public
@@ -331,9 +333,11 @@ export function prepareTreeSqlTables(contentBase: string, { config, skipDirector
  * @param {object[]} [opts.records] - Complete index records already derived.
  * @param {Map<string, {body: string, frontmatter: object|null}>} [opts.parsed] - Parsed notes.
  * @param {Map<string, object>} [opts.foreignIndex] - Published dependency indexes.
+ * @param {(audience: "all"|"public") => Promise<Map<string, object[]>|undefined>} [opts.prepareAudience] -
+ *   Context-bound preparation shared with other operations in the same session.
  * @returns {Promise<Map<string, object[]>|undefined>} Prepared tables by source.
  */
-export function prepareLinkSqlTables(contentBase: string, { config, skipDirectories, records, parsed, foreignIndex }?: {
+export function prepareLinkSqlTables(contentBase: string, { config, skipDirectories, records, parsed, foreignIndex, prepareAudience }?: {
     config?: object | undefined;
     skipDirectories?: readonly string[] | undefined;
     records?: object[] | undefined;
@@ -342,6 +346,7 @@ export function prepareLinkSqlTables(contentBase: string, { config, skipDirector
         frontmatter: object | null;
     }> | undefined;
     foreignIndex?: Map<string, object> | undefined;
+    prepareAudience?: ((audience: "all" | "public") => Promise<Map<string, object[]> | undefined>) | undefined;
 }): Promise<Map<string, object[]> | undefined>;
 /**
  * Aliases the renderer reads rather than printing.

package/types/engine/stub-lint.d.mts

@@ -11,15 +11,17 @@
  * @param {object} opts
  * @param {readonly object[]} opts.records - Index records the caller derived.
  * @param {string} [opts.contentPackage] - Named in the counts line.
+ * @param {Map<string, import("./content-session.mjs").ContentNoteSource>} [opts.parsed] - Captured sources, with the file reader as fallback.
  * @returns {{findings: object[], counts: {full: number, draft: number,
  *   stub: number}, byType: Array<{type: string, full: number, draft: number,
  *   stub: number}>, oldestDrafts: Array<{file: string, modified: Date}>,
  *   summary: string[]}} The findings, the ladder's counts, and the lines a
  *   reader is shown as prose rather than as findings.
  */
-export function lintNoteStates(contentBase: string, { records, contentPackage }?: {
+export function lintNoteStates(contentBase: string, { records, contentPackage, parsed }?: {
     records: readonly object[];
     contentPackage?: string | undefined;
+    parsed?: Map<string, import("./content-session.mjs").ContentNoteSource> | undefined;
 }): {
     findings: object[];
     counts: {

package/types/engine/wikilink-syntax.d.mts

@@ -9,6 +9,7 @@
  * @property {string} anchor - The `#section` slug, `""` when there is none.
  * @property {string|null} display - The text after `|`, or `null` when the link
  *   is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
+ * @property {ReturnType<typeof parseExtensionAttributes>} [attributes] - Trailing extension attributes.
  * @property {boolean} labelled - Whether a `|` was present at all. A link
  *   without one addresses nothing and is a finding — see
  *   {@link unlabelledLinkMessage} — so every reader has to be able to ask.
@@ -20,9 +21,10 @@
  * not the whole link, so a caller that has already matched does not re-match.
  *
  * @param {string} rawInner - The text between `[[` and `]]`.
+ * @param {string} [literal] - Whole matched link, including trailing attributes.
  * @returns {ParsedWikilink} The parts, each trimmed.
  */
-export function parseWikilink(rawInner: string): ParsedWikilink;
+export function parseWikilink(rawInner: string, literal?: string): ParsedWikilink;
 /**
  * The label an author actually supplied, or `null` when they supplied none.
  *
@@ -158,13 +160,14 @@ export function ambiguousAddressMessage(target: string, packages?: Iterable<stri
  * @param {string} [finding.stub] - For `stub`, where the stub is.
  * @param {string} [finding.shortcode] - For `shortcode-not-lowercase`, the
  *   shortcode as written.
+ * @param {string[]} [finding.problems] - Invalid attribute diagnostics.
  * @param {string} [finding.declared] - For `shortcode-not-lowercase`, the
  *   lowercase spelling, when it is a declared shortcode.
  * @returns {string} The message.
  * @throws {Error} On a reason outside the closed set — a resolver inventing one
  *   would otherwise report a link with no explanation at all.
  */
-export function linkFindingMessage({ reason, target, packages, anchor, type, stub, shortcode, declared, }: {
+export function linkFindingMessage({ reason, target, packages, anchor, type, stub, shortcode, declared, problems, }: {
     reason: string;
     target: string;
     packages?: Iterable<string> | undefined;
@@ -172,6 +175,7 @@ export function linkFindingMessage({ reason, target, packages, anchor, type, stu
     type?: string | undefined;
     stub?: string | undefined;
     shortcode?: string | undefined;
+    problems?: string[] | undefined;
     declared?: string | undefined;
 }): string;
 /**
@@ -188,9 +192,23 @@ export function isSamePage({ target, anchor }: ParsedWikilink): boolean;
  * Read an operational link target in its enclosing Address context.
  * @param {string} inner - Lexical link contents.
  * @param {object} context - Builder defaults and type vocabulary.
+ * @param {string} [literal] - Whole matched link, including trailing attributes.
  * @returns {object} Typed target and diagnostic source spelling.
  */
-export function readWikilink(inner: string, context: object): object;
+export function readWikilink(inner: string, context: object, literal?: string): object;
+/** Whether the actual referenced destination needs spoiler presentation.
+ * @param {object} destination - Resolved note metadata.
+ * @param {string} [anchor] - Referenced prose anchor.
+ * @returns {boolean} Whole-note or section audience.
+ */
+export function secretDestination(destination: object, anchor?: string): boolean;
+/** Apply destination-derived presentation without changing its address.
+ * @param {string} reference - Rendered reference Markdown.
+ * @param {object} parsed - Shared parsed wikilink.
+ * @param {object} destination - Resolved target metadata.
+ * @returns {string} Inline spoiler or visible reference.
+ */
+export function presentWikilink(reference: string, parsed: object, destination: object): string;
 /**
  * What a `[[…]]` **is**, before anything decides where it points.
  *
@@ -297,6 +315,25 @@ export type ParsedWikilink = {
      * is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
      */
     display: string | null;
+    /**
+     * - Trailing extension attributes.
+     */
+    attributes?: {
+        id: string;
+        classes: string[];
+        values: Record<string, string>;
+        problems: string[];
+        positions?: Record<string, {
+            key: {
+                start: number;
+                end: number;
+            };
+            value: {
+                start: number;
+                end: number;
+            };
+        }>;
+    } | undefined;
     /**
      * - Whether a `|` was present at all. A link
      * without one addresses nothing and is a finding — see