@heroiclands/package-build 22.15.1 → 22.16.0

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

@@ -27,7 +27,7 @@ export function parseIconAttributes(raw?: string): {
 /**
  * Look one name up.
  *
- * @param {string} name - The name written between the colons, without `icon-`.
+ * @param {string} name - The name written between the colons, without `icon `.
  * @param {IconRegistry} [registry] - The package's registry.
  * @returns {object|null} The entry, or `null` when the registry does not
  *   declare it.
@@ -63,20 +63,20 @@ export function iconsIn(text: string): Array<{
  * Report every icon a tree names that its registry does not declare.
  *
  * The whole point of a registry is that a typo is answerable, so this is the
- * half that makes `:icon-stra:` a finding rather than three words of literal
+ * half that makes `:icon stra:` a finding rather than three words of literal
  * text nobody notices in a rendered page.
  *
  * @param {string} text - The file's contents.
  * @param {string} file - Path to report.
  * @param {IconRegistry} [registry] - The package's registry.
  * @returns {Array<{file: string, line: number, column: number,
- *   severity: "warning", message: string}>} The unknown names.
+ *   severity: "warning"|"error", message: string}>} The findings.
  */
 export function lintIcons(text: string, file: string, registry?: IconRegistry): Array<{
     file: string;
     line: number;
     column: number;
-    severity: "warning";
+    severity: "warning" | "error";
     message: string;
 }>;
 /**
@@ -136,11 +136,11 @@ export function lintContentIcons(contentBase: string, { skipDirectories, registr
     files: number;
 };
 /**
- * A markdown-it plugin rendering `:icon-name:` inline.
+ * A markdown-it plugin rendering `:icon name:` inline.
  *
  * An unknown name is left **exactly as written** rather than dropped. The name
  * is reported by {@link lintIcons}, and a rendered page that still shows
- * `:icon-stra:` is how the author finds it without reading a log.
+ * `:icon stra:` is how the author finds it without reading a log.
  *
  * **A function is accepted as well as a table**, and resolved per render. The
  * shared markdown-it instance is a module-level constant, so it is built before
@@ -199,7 +199,7 @@ export function iconPlugin(registry?: Record<string, object> | (() => Record<str
  *
  * Empty rather than a starter set, because a starter set is a promise about
  * fonts this package does not ship. A tree with no `icons:` configured names no
- * icons, and `:icon-star:` in one of its notes renders as its own literal text
+ * icons, and `:icon star:` in one of its notes renders as its own literal text
  * and is reported — which is the visible failure, not a silent one.
  *
  * @type {IconRegistry}
@@ -243,25 +243,16 @@ export const ICON_ATTRIBUTES: Readonly<Record<string, {
 /**
  * The shape a note writes, and the one this module claims.
  *
- * The `icon-` prefix is what keeps it out of the way of an emoji shortcode: a
- * surface that also renders `:smile:` can tell the two apart without a lookup,
- * and a reader can tell what `:icon-star:` is without knowing this module
- * exists. Names are lowercase, digits and hyphens — the charset an address
- * segment already uses, so nothing new has to be explained.
- *
- * Not `:name[content]`. That is remark-directive syntax, and this toolchain
- * parses with markdown-it; a directive would render as its own literal text.
+ * The `icon` keyword distinguishes inline glyphs from asset Addresses and
+ * other colon-based shorthand. Names use lowercase letters, digits and
+ * hyphens, and each name resolves in the package's declared icon registry.
  *
- * An optional trailing brace carries **attributes**:
+ * An optional brace carries attributes, for example:
  *
- *     :icon-affiliation:{size: 2x}
+ *     :icon affiliation:{size=2x}
  *
- * `key: value` pairs, comma-separated, in the shape `markdown-it-attrs` and
- * remark-directive already use — so it is a convention a reader may recognise
- * rather than one this module invented. Attributes rather than a bare value
- * because `size` is merely the first one anybody needed: a fixed-width flag, a
- * rotation, a title override are the same shape of thing, and a syntax that
- * could only ever express size would have to be replaced to gain any of them.
+ * Attributes are whitespace-separated `key=value` pairs. The closed `size`
+ * values are declared in {@link ICON_SIZES}.
  *
  * One inline rule consumes the token **and** its brace, so there is no state in
  * which the icon resolves and the brace is left stranded on the page. An

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

@@ -208,7 +208,7 @@ export function renderImageFigures(body: string, resolveSrc?: (src: string) => s
  * A markdown-it plugin that reads an image's directive and renders its figure.
  *
  * **A core rule, not an inline one.** markdown-it's own `image` rule consumes
- * `![alt](src)` and leaves `{float: top-left}` behind as text, and a rule
+ * `![alt](src)` and leaves `{float=top-left}` behind as text, and a rule
  * running before it would have to re-implement link parsing to find the brace.
  * Reading the token stream afterwards costs one pass and re-implements nothing.
  *
@@ -255,7 +255,7 @@ export const IMAGE_CLASSES: Readonly<Record<string, {
 /** The named sizes an image directive accepts. */
 export const IMAGE_SIZES: readonly string[];
 /**
- * The `float:` positions an image may take, and where each puts it.
+ * The `float` positions an image may take, and where each puts it.
  *
  * `align` is the Typst alignment the float is placed at. **Print cannot wrap
  * text around an arbitrary shape**: a Typst float occupies the column measure,

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

@@ -101,6 +101,8 @@ export function asciiAliases(aliases: unknown): Array<string>;
  * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
  * @param {object} [options.manifest] - The package manifest, which the Foundry
  *   entries are derived against.
+ * @param {object} [options.addressContext] - Address resolution context.
+ * @param {object} [options.dateContext] - Calendar conversion context.
  * @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
@@ -112,7 +114,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, contentPackage, body, bodyLine, manifest, addressContext, }: {
+export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, addressContext, dateContext, }: {
     frontmatter: Record<string, any>;
     relPath: string;
     absPath?: string | undefined;
@@ -120,9 +122,11 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage
     body?: string | undefined;
     bodyLine?: number | undefined;
     manifest?: object | undefined;
+    addressContext?: object | undefined;
+    dateContext?: object | undefined;
 }): Record<string, any>;
 /** Derive every index record belonging to one parsed note. */
-export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext, }: {
+export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext, dateContext, }: {
     frontmatter: any;
     body: any;
     bodyLine: any;
@@ -131,6 +135,7 @@ export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absP
     contentPackage: any;
     manifest: any;
     addressContext: any;
+    dateContext: any;
 }): object[];
 /**
  * Read a content tree into index records, in the order they will be written.
@@ -156,6 +161,7 @@ export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absP
  *   anyway.
  * @param {object} [options.manifest] - The package manifest, which the Foundry
  *   entries are derived against.
+ * @param {object} [options.addressContext] - Address resolution context.
  * @param {object[]} [options.problems] - Supplied by a **reader**: a note that
  *   cannot be recorded is pushed here as a diagnostic and skipped. Omitted, the
  *   note throws — the contract the emitter needs, since an index missing a note
@@ -168,6 +174,7 @@ export function collectContentIndex(contentBase: string, { contentPackage, skipD
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;
     manifest?: object | undefined;
+    addressContext?: object | undefined;
     problems?: object[] | undefined;
 }): Array<Record<string, any>>;
 /**

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

@@ -72,9 +72,8 @@ export function buildLinkIndex(contentBase: string, { config, skipDirectories, s
  *
  * **Why the homepage needs its own audit at all.** Every other note addresses
  * the corpus with wikilinks, which {@link auditLinks} resolves. A homepage does
- * not and cannot: it is published *verbatim* by every publishing mode, including
- * the homepage-only mode two fan-licensed packages ship under, where the content
- * tree is never walked and there is no index for a wikilink to resolve against.
+ * not and cannot: it is published *verbatim* even when the tree contains other
+ * notes. Its body never runs through the wikilink resolver.
  * So a homepage addresses the web the way the web does — markdown links in its
  * body — and this is what looks at those. A dead link on the page a reader
  * arrives at is the one nothing else would report.
@@ -89,8 +88,7 @@ export function buildLinkIndex(contentBase: string, { config, skipDirectories, s
  *   is why every one is reported — including a bare `/<package>/`, which names
  *   another package's front page. A front page's address *is* its package
  *   prefix, so `/<package>/` is the absolute URL with the host struck off —
- *   host-free, emitted verbatim, and needing no index, which is what lets it
- *   hold in homepage-only mode where the tree is never walked.
+ *   host-free, emitted verbatim, and needing no index.
  * - A **wikilink**, which nothing on this page will ever resolve.
  *
  * **What is not checkable, and is not attempted.** Whether an external URL

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

@@ -1,145 +1,16 @@
 /**
- * Parse one `dataview` block's query.
- *
- * @param {string} source - The query text (fences already stripped).
- * @returns {{columns: Array<{header: string, expr: object}>, from: object|null,
- *   where: object|null, sort: Array<{expr: object, descending: boolean}>,
- *   limit: number|null}}
- * @throws {Error} When the query is not a supported `TABLE` query — the message
- *   names the offending clause, column, or token.
+ * Replace prepared SQL fences with Markdown tables while retaining source lines.
+ * Query execution happens in the asynchronous SQL preparation pass.
+ * @param {string} markdown - The authored body.
+ * @param {{source?: string, sqlTables?: object[]}} [context] - Prepared results.
+ * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[]}}
  */
-export function parseDataviewQuery(source: string): {
-    columns: Array<{
-        header: string;
-        expr: object;
-    }>;
-    from: object | null;
-    where: object | null;
-    sort: Array<{
-        expr: object;
-        descending: boolean;
-    }>;
-    limit: number | null;
-};
-/**
- * Resolve a dotted path against a content note. `file.*` names the note's place
- * in the tree; everything else reads frontmatter, preferring a literal dotted
- * key before walking the segments (the same precedence the pack compilers'
- * `getFrontmatter` uses) — so **any** frontmatter property is addressable,
- * however deeply nested.
- *
- * @param {ContentTableDoc} doc
- * @param {string} path
- * @returns {unknown} `null` when the note has no such field.
- * @throws {Error} On an unknown `file.*` field, which would otherwise read as a
- *   table that silently matches nothing.
- */
-export function resolveField(doc: ContentTableDoc, path: string): unknown;
-/**
- * Evaluate one parsed expression against a note.
- *
- * @param {object} node - From {@link parseDataviewQuery}.
- * @param {ContentTableDoc} doc - The row being rendered.
- * @param {ContentTableDoc} [self] - The note *containing* the query, which is
- *   what `this` reads; absent means every `this.…` resolves to nothing.
- * @returns {unknown}
- */
-export function evaluate(node: object, doc: ContentTableDoc, self?: ContentTableDoc): unknown;
-/**
- * The notes a query selects, in the order its `SORT` keys give. With no `SORT`
- * the notes keep content-path order, and the note path (then its id) breaks any
- * remaining tie, so the emitted table is byte-stable across builds regardless
- * of directory-walk order.
- *
- * @param {object} spec - From {@link parseDataviewQuery}.
- * @param {Array<ContentTableDoc>} docs
- * @param {ContentTableDoc} [self] - The note containing the query (`this`).
- * @returns {Array<ContentTableDoc>} The matching notes, sorted and limited.
- */
-export function selectRows(spec: object, docs: Array<ContentTableDoc>, self?: ContentTableDoc): Array<ContentTableDoc>;
-/**
- * Build the markdown table for one query.
- *
- * A `link(…)` cell — and the implicit `File` column — is emitted as a wikilink
- * to the row's own note, which the caller's wikilink pass resolves; a note the
- * caller reports as unlinkable (no shortcode, or a content directory that
- * compiles into no pack) degrades to plain text. A column is right-aligned when
- * every value it shows is numeric.
- *
- * @param {object} spec - From {@link parseDataviewQuery}.
- * @param {Array<ContentTableDoc>} rows - From {@link selectRows}.
- * @param {(doc: ContentTableDoc) => boolean} linkable - Can this note be linked to?
- * @param {ContentTableDoc} [self] - The note containing the query (`this`).
- * @returns {string} The markdown table (no trailing newline).
- */
-export function renderContentTable(spec: object, rows: Array<ContentTableDoc>, linkable: (doc: ContentTableDoc) => boolean, self?: ContentTableDoc): string;
-/**
- * Expand every fenced `dataview` and `sql` block in a markdown body.
- *
- * A block that cannot be honoured — malformed or unsupported — is left in the
- * body verbatim and reported in `errors`, so the failure is visible in the
- * output as well as on the console. Every other code fence, and every code
- * span, is left alone (that is how the syntax is documented).
- *
- * A query that selects **no** note is an error unless the fence says
- * `allow-empty`, which states that an empty table is the intended result.
- *
- * @param {string} markdown - The note body, frontmatter already stripped.
- * @param {object} ctx
- * @param {Array<ContentTableDoc>} ctx.docs - The searchable universe: every
- *   content note the caller considers in scope.
- * @param {(doc: ContentTableDoc) => boolean} [ctx.linkable] - Whether a note can
- *   be linked to from a cell; defaults to never.
- * @param {string} [ctx.source] - The note being expanded, for error reports.
- * @param {ContentTableDoc} [ctx.self] - The note being expanded, as a searchable
- *   doc: what a query's `this` reads.
- * @param {object[]} [ctx.sqlTables] - This note's prepared `sql` results, in
- *   document order, from
- *   {@link module:engine/sql-tables.prepareSqlTables}. An `sql` directive with
- *   no prepared result is an error: nothing here runs a query.
- * @returns {{markdown: string, errors: Array<{source: string, directive: string,
- *   reason: string, line: number, column?: number}>,
- *   warnings: Array<{source: string, line: number, column: number,
- *   reason: string}>, lineMap: Array<{line: number, generated: boolean}>}}
- *   `lineMap` is parallel to the emitted lines and says which authored line
- *   each came from, so a diagnostic about the expanded body can name an
- *   authored position. An `errors` entry carries the 0-based line of the
- *   directive that failed, for the same reason. `warnings` holds one entry per
- *   `dataview` directive the body still authors, and one per `sql` directive
- *   that leaves out stubs it would otherwise list.
- */
-export function expandContentTables(markdown: string, { docs, linkable, source, self, sqlTables, }?: {
-    docs: Array<ContentTableDoc>;
-    linkable?: ((doc: ContentTableDoc) => boolean) | undefined;
-    source?: string | undefined;
-    self?: ContentTableDoc | undefined;
-    sqlTables?: object[] | undefined;
+export function expandContentTables(markdown: string, { source, sqlTables }?: {
+    source?: string;
+    sqlTables?: object[];
 }): {
     markdown: string;
-    errors: Array<{
-        source: string;
-        directive: string;
-        reason: string;
-        line: number;
-        column?: number;
-    }>;
-    warnings: Array<{
-        source: string;
-        line: number;
-        column: number;
-        reason: string;
-    }>;
-    lineMap: Array<{
-        line: number;
-        generated: boolean;
-    }>;
-};
-/**
- * One content note as a content build hands it to the expander: its parsed
- * frontmatter plus its path below the content root, which backs the `file.*`
- * fields.
- */
-export type ContentTableDoc = {
-    fm: Record<string, any>;
-    path?: string;
+    errors: object[];
+    warnings: object[];
+    lineMap: object[];
 };

package/types/engine/culture-choice.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Require a being's primary culture to address a culture lore note.
+ * @param {object} note
+ * @param {{index?: object}} [options]
+ */
+export function checkCultureChoice(note: object, { index }?: {
+    index?: object;
+}): {
+    severity: string;
+    message: string;
+    line?: number;
+    column?: number;
+    file: any;
+}[];

package/types/engine/date-conversion.d.mts

@@ -0,0 +1,4 @@
+/** Convert a day in an addressed calendar to its canonical spelling. */
+export function dateFromCalendar(reference: any, value: any, context: any): string;
+/** Convert a canonical day to the date in the covering era of a calendar. */
+export function dateToCalendar(reference: any, value: any, context: any): any;

package/types/engine/declaration-check.d.mts

@@ -0,0 +1,24 @@
+/** All declaration entry points advertised by a package's exports map. */
+export function exportedDeclarationFiles(root: any): {
+    files: any[];
+    findings: {
+        file: string;
+        severity: string;
+        message: string;
+    }[];
+};
+/**
+ * Type-check project declarations with library checking enabled.
+ * @param {string} project - TypeScript project file.
+ * @param {{exports?: boolean}} [options]
+ * @returns {Array<{file: string, line?: number, column?: number, severity: "error", message: string}>}
+ */
+export function checkDeclarations(project: string, options?: {
+    exports?: boolean;
+}): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: "error";
+    message: string;
+}>;

package/types/engine/docs-checks.d.mts

@@ -0,0 +1,28 @@
+/** Preserve offsets while excluding literal examples from link scanning. */
+export function maskMarkdownCode(source: any, spans?: boolean): any;
+/** GitHub heading slug, retaining separate spaces after punctuation removal. */
+export function docHeadingSlug(value: any): any;
+/** @param {string} source */
+export function docAnchors(source: string): Set<any>;
+/**
+ * Check relative Markdown links beneath a documentation root.
+ * @param {string} root
+ * @returns {Array<{file: string, line: number, column: number, severity: "error", message: string}>}
+ */
+export function checkDocLinks(root: string): Array<{
+    file: string;
+    line: number;
+    column: number;
+    severity: "error";
+    message: string;
+}>;
+/**
+ * Check each direct Markdown page in each section against the root README.
+ * @param {string} root
+ * @returns {Array<{file: string, severity: "error", message: string}>}
+ */
+export function checkDocIndex(root: string): Array<{
+    file: string;
+    severity: "error";
+    message: string;
+}>;

package/types/engine/documentation-links.d.mts

@@ -0,0 +1,7 @@
+/** Keep repository-relative documentation links usable on addressed pages. */
+export function documentationLinksPass({ config, book }: {
+    config: any;
+    book?: boolean | undefined;
+}): {
+    beforeLinks(text: any, page: any): any;
+};

package/types/engine/exported-scene.d.mts

@@ -6,7 +6,11 @@
  *
  * @param {object} fm - The map note's frontmatter.
  * @param {string} markdown - Its converted Markdown body.
- * @param {object} [opts] - Pack metadata, derived JournalEntry ID, and asset resolver.
+ * @param {{journalEntryId?: string, stats?: object, resolveAddress?: Function}} [opts] - Pack metadata, derived JournalEntry ID, and asset resolver.
  * @returns {object} The keyed Scene document.
  */
-export function buildExportedScene(fm: object, markdown: string, { journalEntryId, stats, resolveAddress }?: object): object;
+export function buildExportedScene(fm: object, markdown: string, { journalEntryId, stats, resolveAddress }?: {
+    journalEntryId?: string;
+    stats?: object;
+    resolveAddress?: Function;
+}): object;

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

@@ -0,0 +1,14 @@
+/**
+ * Read the shared braced attribute grammar used by body extensions.
+ * Callers validate which names and classes their extension understands.
+ * @param {string} source - Text inside the braces.
+ * @returns {{id: string, classes: string[], values: Record<string, string>, problems: string[]}}
+ */
+export function parseExtensionAttributes(source: string): {
+    id: string;
+    classes: string[];
+    values: Record<string, string>;
+    problems: string[];
+};
+/** A Boolean attribute is spelled exactly `true` or `false`. */
+export function booleanAttribute(value: any, key: any): boolean;

package/types/engine/field-spec.d.mts

@@ -290,6 +290,9 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   which is a Shortcode at both ends and resolves nothing.
  * @property {any|((fm: object) => any)} [value] - For a field with no `name`:
  *   the constant, or a function deriving it from the frontmatter.
+ * @property {(fm: object, out: object) => boolean} [when] - Emit this field
+ *   only when the note and fields already built meet the condition. The path
+ *   remains declared for schema checks and authoring validation.
  * @property {boolean} [omitWhenAbsent] - **The key is left out entirely when
  *   the note does not carry the field**, rather than written from a
  *   declared default.
@@ -572,6 +575,12 @@ export type FieldSpec = {
      * the constant, or a function deriving it from the frontmatter.
      */
     value?: any | ((fm: object) => any);
+    /**
+     * - Emit this field
+     * only when the note and fields already built meet the condition. The path
+     * remains declared for schema checks and authoring validation.
+     */
+    when?: ((fm: object, out: object) => boolean) | undefined;
     /**
      * - **The key is left out entirely when
      * the note does not carry the field**, rather than written from a

package/types/engine/format-generated.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Format generated text using the destination file's Prettier configuration.
+ * @param {string} text
+ * @param {string} filepath
+ * @returns {Promise<string>}
+ */
+export function formatGenerated(text: string, filepath: string): Promise<string>;

package/types/engine/frontmatter.d.mts

@@ -1,14 +1,22 @@
 /**
  * Resolves a dotted frontmatter key (e.g., "name.full") into the nested
  * value. Returns `defaultValue` if any path segment is missing.
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} key - A top-level or dotted property path.
+ * @param {unknown} [defaultValue] - Value for a missing property.
+ * @returns {unknown} The property value or default.
  */
-export function getFrontmatter(fm: any, key: any, defaultValue?: undefined): any;
+export function getFrontmatter(fm: object | null | undefined, key: string, defaultValue?: unknown): unknown;
 /**
  * Reads a key from `fm.sohl` (the vault's nested system-fields block).
  * Supports dotted notation, e.g. sohlField(fm, "charges.value", 0).
  * Falls back to top-level `fm[key]` if `sohl` doesn't carry the key.
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} key - A top-level or dotted property path.
+ * @param {unknown} [defaultValue] - Value for a missing property.
+ * @returns {unknown} The system value, top-level value, or default.
  */
-export function sohlField(fm: any, key: any, defaultValue?: undefined): any;
+export function sohlField(fm: object | null | undefined, key: string, defaultValue?: unknown): unknown;
 /**
  * Read a `sohl:` field, seeing the **destination** position as well.
  *
@@ -139,11 +147,13 @@ export function requireSubType(fm: object, ctx?: string): string;
  *   - Array of "Label:MaxValue" strings, e.g. ["Ugly:4", "Plain:12"]
  *   - Array of objects, e.g. [{ label, maxValue }]
  * Returns a normalized array of `{ label, maxValue: number }`.
+ * @param {unknown} raw - An authored threshold array.
+ * @returns {Array<{label: string, maxValue: number}>} Normalized thresholds.
  */
-export function parseValueDesc(raw: any): {
+export function parseValueDesc(raw: unknown): Array<{
     label: string;
     maxValue: number;
-}[];
+}>;
 /**
  * The compendium folder a note names.
  *

package/types/engine/generate.d.mts

@@ -161,7 +161,7 @@ export function orderPassesByDependency(packs: readonly object[]): object[];
  * would produce them is not in it.
  *
  * Ordering answers the whole-package build; a run restricted to one pack
- * (`content-build package compile <name>`) cannot conjure the passes it left
+ * (`package-build package compile <name>`) cannot conjure the passes it left
  * out. Where their output is already on disk from an earlier run that is fine
  * — it is how compiling one pack at a time is meant to work — so this reports
  * only what is genuinely absent, and names the pack that would write it rather