@heroiclands/package-build 22.21.0 → 22.23.0

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

@@ -30,16 +30,28 @@ export function parseImageDirective(raw?: string): {
     problems: string[];
 };
 /**
- * The classes a figure carries, from a parsed directive.
+ * The class a picture's role names, or `""` for no role or one outside the
+ * closed set — the same silent-degrade rule every other unrecognised value
+ * here gets, since a role this far downstream has already been validated or
+ * dropped by the asset record that carries it.
  *
- * @param {{classes?: string[], size?: string, float?: string}} [directive] - As parsed.
+ * @param {string} [role] - The role, from the resolved asset record.
+ * @returns {string} The class, or `""`.
+ */
+export function roleClass(role?: string): string;
+/**
+ * The classes a figure carries, from a parsed directive and its asset's role.
+ *
+ * @param {{classes?: string[], size?: string, float?: string, role?: string}} [directive] -
+ *   As parsed, plus the role the resolved asset record carries, if any.
  * @returns {string} A space-separated class list, always naming
  *   {@link IMAGE_FIGURE_CLASS} first.
  */
-export function figureClasses({ classes, size, float }?: {
+export function figureClasses({ classes, size, float, role }?: {
     classes?: string[];
     size?: string;
     float?: string;
+    role?: string;
 }): string;
 /**
  * Text going inside an HTML attribute or between tags.
@@ -55,28 +67,57 @@ export function escapeHtml(text: string): string;
  * function, so the two cannot drift into styling the same directive through
  * different class names.
  *
+ * **No `<figcaption>` is emitted here.** A `:::figure` fence draws its own
+ * label and authored caption around whatever this returns; the alt text stays
+ * on the `img` element alone.
+ *
+ * **The role class and the `width`/`height` attributes are what a stylesheet
+ * elsewhere keys a role's size on.** This module states none — the measure a
+ * `portrait` fills on a page is a Hugo theme's or a Foundry system's own
+ * decision — and emits only what the resolved asset record states: a role
+ * class when the picture declares one, and the attributes whenever the
+ * picture resolved to an asset record at all, blank for a vector. The
+ * attributes reserve the picture's own layout space before it loads, which is
+ * what lets a page avoid reflowing as pictures load in.
+ *
  * @param {object} image - The image.
  * @param {string} image.src - The address, resolved for the surface.
- * @param {string} [image.alt] - The alt text, which is also the caption.
+ * @param {string} [image.alt] - The alt text, for a reader who cannot see the
+ *   picture.
  * @param {string[]} [image.classes] - Width classes, from the directive.
  * @param {string} [image.size] - Named display size, from the directive.
  * @param {string} [image.float] - The float position, from the directive.
+ * @param {string} [image.role] - The picture's declared role, from the
+ *   resolved asset record.
+ * @param {number|""} [image.width] - The file's own pixel width, from the
+ *   resolved asset record; `""` for a vector. Omitted entirely when the
+ *   address resolved to no asset record at all.
+ * @param {number|""} [image.height] - As `width`.
  * @returns {string} The figure, as one HTML block.
  */
-export function imageFigureHtml({ src, alt, classes, size, float }: {
+export function imageFigureHtml({ src, alt, classes, size, float, role, width, height, }: {
     src: string;
     alt?: string | undefined;
     classes?: string[] | undefined;
     size?: string | undefined;
     float?: string | undefined;
+    role?: string | undefined;
+    width?: number | "" | undefined;
+    height?: number | "" | undefined;
 }): string;
 /**
  * Whether a match sits alone in its own paragraph.
  *
- * "Alone" is the whole of a block: nothing else on its line, and a blank line
- * or the end of the body either side of it. A leading `>` or list marker
- * disqualifies it for the same reason a word does — the paragraph it belongs to
- * holds something the figure would have to be lifted out of.
+ * "Alone" is the whole of a block: nothing else on its line, and a blank line,
+ * a body-extension delimiter or the end of the body either side of it. A
+ * leading `>` or list marker disqualifies it for the same reason a word does —
+ * the paragraph it belongs to holds something the figure would have to be
+ * lifted out of.
+ *
+ * **A footnote reference trailing the match is not "other text."** `[^note]`
+ * annotates the picture rather than sitting beside it in prose, the same
+ * standing its own directive already has, so `![A ranger](r.webp)[^note]` is
+ * still alone.
  *
  * @param {string} text - The body the match indexes into.
  * @param {number} start - Where the match begins.
@@ -127,6 +168,9 @@ export function imageSourcesIn(body: string): string[];
  * @param {object} [opts]
  * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
  * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @param {Array<{line: number, generated: boolean}>} [opts.lineMap] - From
+ *   table expansion, mapping each line of `body` back to the line an author
+ *   wrote, for a caller handing in a body whose tables already expanded.
  * @param {object} [opts.config] - The resolved build configuration. Supplied,
  *   an address is also held to the one surface a pathname can be dead on
  *   without any other pass noticing — see the Foundry address below. Omitted,
@@ -136,9 +180,13 @@ export function imageSourcesIn(body: string): string[];
  *   severity: "error", message: string}>} One finding per defect, in source
  *   order.
  */
-export function checkImages(body: string, file: string, { bodyLine, bodyColumn, config }?: {
+export function checkImages(body: string, file: string, { bodyLine, bodyColumn, lineMap, config }?: {
     bodyLine?: number | undefined;
     bodyColumn?: number | undefined;
+    lineMap?: {
+        line: number;
+        generated: boolean;
+    }[] | undefined;
     config?: object | undefined;
 }): Array<{
     file: string;
@@ -201,9 +249,18 @@ export function lintContentImages(contentBase: string, { skipDirectories, config
  * @param {(src: string) => string} [resolveSrc] - Translates an authored
  *   pathname into the address this surface serves. The default is the identity,
  *   for a caller rendering the format rather than publishing it.
+ * @param {(src: string) => {type?: string, role?: string, width?: number|"", height?: number|""}|undefined}
+ *   [lookupAsset] - What the resolved asset record says about the address, as
+ *   authored — before `resolveSrc` translates it. The default answers nothing,
+ *   which is what an address resolving to no asset record gets anyway.
  * @returns {string} The same body, with each block image as a `<figure>`.
  */
-export function renderImageFigures(body: string, resolveSrc?: (src: string) => string): string;
+export function renderImageFigures(body: string, resolveSrc?: (src: string) => string, lookupAsset?: (src: string) => {
+    type?: string;
+    role?: string;
+    width?: number | "";
+    height?: number | "";
+} | undefined): string;
 /**
  * A markdown-it plugin that reads an image's directive and renders its figure.
  *
@@ -226,9 +283,18 @@ export function renderImageFigures(body: string, resolveSrc?: (src: string) => s
  *   address into the one this surface serves. Foundry is handed the path inside
  *   the install; a renderer that resolves the address itself — the book stages
  *   its own copy — passes nothing and gets the address as authored.
+ * @param {(src: string) => {type?: string, role?: string, width?: number|"", height?: number|""}|undefined}
+ *   [lookupAsset] - What the resolved asset record says about the address, as
+ *   authored — before `resolveSrc` runs. The default answers nothing, which is
+ *   what an address resolving to no asset record gets anyway.
  * @returns {(md: object) => void} A markdown-it plugin.
  */
-export function imagePlugin(resolveSrc?: (src: string) => string): (md: object) => void;
+export function imagePlugin(resolveSrc?: (src: string) => string, lookupAsset?: (src: string) => {
+    type?: string;
+    role?: string;
+    width?: number | "";
+    height?: number | "";
+} | undefined): (md: object) => void;
 /**
  * The width classes an image may carry, and what each means to a renderer.
  *

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

@@ -103,6 +103,10 @@ export function asciiAliases(aliases: unknown): Array<string>;
  *   entries are derived against.
  * @param {object} [options.addressContext] - Address resolution context.
  * @param {object} [options.dateContext] - Calendar conversion context.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - From
+ *   a picture's address to the role its asset declares, so a figure anchor's
+ *   `name` reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @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
@@ -114,7 +118,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, dateContext, }: {
+export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, addressContext, dateContext, resolveRole, }: {
     frontmatter: Record<string, any>;
     relPath: string;
     absPath?: string | undefined;
@@ -124,9 +128,10 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage
     manifest?: object | undefined;
     addressContext?: object | undefined;
     dateContext?: object | undefined;
+    resolveRole?: ((address: string) => string | undefined) | undefined;
 }): Record<string, any>;
 /** Derive every index record belonging to one parsed note. */
-export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext, dateContext, }: {
+export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext, dateContext, resolveRole, }: {
     frontmatter: any;
     body: any;
     bodyLine: any;
@@ -136,6 +141,7 @@ export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absP
     manifest: any;
     addressContext: any;
     dateContext: any;
+    resolveRole: any;
 }): object[];
 /**
  * Read a content tree into index records, in the order they will be written.

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

@@ -1,13 +1,21 @@
 /**
- * Replace prepared SQL fences with Markdown tables while retaining source lines.
- * Query execution happens in the asynchronous SQL preparation pass.
+ * Replace prepared SQL fences and page lists with Markdown while retaining
+ * source lines.
+ *
+ * Both directives read the content index, so both are answered before this
+ * pass runs — query execution in the asynchronous SQL preparation pass, page
+ * lists in {@link module:engine/page-lists.preparePageLists} — and each is
+ * looked up by the ordinal of its own kind of fence within the body.
+ *
  * @param {string} markdown - The authored body.
- * @param {{source?: string, sqlTables?: object[]}} [context] - Prepared results.
+ * @param {{source?: string, sqlTables?: object[], pageLists?: object[]}} [context] -
+ *   Prepared results.
  * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[]}}
  */
-export function expandContentTables(markdown: string, { source, sqlTables }?: {
+export function expandContentTables(markdown: string, { source, sqlTables, pageLists }?: {
     source?: string;
     sqlTables?: object[];
+    pageLists?: object[];
 }): {
     markdown: string;
     errors: object[];

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

@@ -0,0 +1,72 @@
+/**
+ * What a note opening a list item with `[ ]` or `[x]` is told.
+ *
+ * @param {string} marker - The matched marker, as written.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function taskListMessage(marker: string): string;
+/**
+ * Every list item opened with `[ ]` or `[x]` in one note's body.
+ *
+ * @param {string} body - The note's markdown, without its frontmatter.
+ * @param {string} file - The note's path, for the finding.
+ * @param {object} [opts]
+ * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
+ * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @returns {Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>} One finding per item, in source
+ *   order.
+ */
+export function checkTaskLists(body: string, file: string, { bodyLine, bodyColumn }?: {
+    bodyLine?: number | undefined;
+    bodyColumn?: number | undefined;
+}): Array<{
+    file: string;
+    line: number;
+    column: number;
+    severity: "warning";
+    message: string;
+}>;
+/**
+ * Walk a content tree and report every list item opened with `[ ]` or `[x]`.
+ *
+ * The frontmatter fence is taken off first, so what is scanned is the body and
+ * the positions are still the file's. A file with no frontmatter is scanned
+ * whole: it is not a note, but a stray `.md` in the tree carrying the marker is
+ * the same problem for the same reason.
+ *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
+ *   in addition to the dot-directories always skipped.
+ * @returns {{findings: Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>, files: number}} The findings, and
+ *   how many files were read.
+ */
+export function lintContentTaskLists(contentBase: string, { skipDirectories }?: {
+    skipDirectories?: readonly string[] | undefined;
+}): {
+    findings: Array<{
+        file: string;
+        line: number;
+        column: number;
+        severity: "warning";
+        message: string;
+    }>;
+    files: number;
+};
+/**
+ * A list item's marker, immediately followed by `[ ]` or `[x]` and a space —
+ * bulleted (`-`, `*`, `+`) or ordered (`1.` or `1)`), at the start of a line.
+ *
+ * The leading indentation is a lookbehind rather than part of the match, so a
+ * nested item's finding points at the marker itself, not at the line's first
+ * column.
+ *
+ * @type {RegExp}
+ */
+export const TASK_LIST_MARKER: RegExp;

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

@@ -2,9 +2,15 @@
  * 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.
+ * @param {object} [options={}]
+ * @param {RegExp} [options.idPattern=NAME] - What an `#id` may be named. A
+ *   construct whose id is published as an HTML `id` admits a digit first and
+ *   passes a looser pattern; the default is the pattern every other name takes.
  * @returns {{id: string, classes: string[], values: Record<string, string>, problems: string[]}}
  */
-export function parseExtensionAttributes(source: string): {
+export function parseExtensionAttributes(source: string, { idPattern }?: {
+    idPattern?: RegExp | undefined;
+}): {
     id: string;
     classes: string[];
     values: Record<string, string>;
@@ -12,3 +18,18 @@ export function parseExtensionAttributes(source: string): {
 };
 /** A Boolean attribute is spelled exactly `true` or `false`. */
 export function booleanAttribute(value: any, key: any): boolean;
+/**
+ * The attribute keys no construct writes onto an element.
+ *
+ * `id=` and `class=` are refused in favour of `#id` and `.class`, which the
+ * grammar already states; a key beginning `on` is an event handler, and nothing
+ * authored in a note becomes code on a published page.
+ *
+ * Shared by every construct that writes an author's attributes onto an element,
+ * because a refusal that held on one and not the next would be the hole the
+ * other construct is checked for.
+ *
+ * @param {Record<string, string>} values - The `key=value` attributes parsed.
+ * @returns {string[]} One message per refused key, in the order written.
+ */
+export function refusedAttributes(values: Record<string, string>): string[];

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

@@ -1,3 +1,24 @@
+/**
+ * The one line explaining why a single field's shared top-level fallback is
+ * off.
+ *
+ * **The field's reason stands on its own** — a complete sentence, or more
+ * than one — rather than completing a clause the frame starts. A field that
+ * collides with a top-level spelling meaning something else can say so
+ * ("`weight` is the item's own, independent of the note's."); a field whose
+ * top-level spelling is refused outright by the closed vocabulary can say
+ * that instead, honestly, which "there it means …" cannot: a refused key
+ * carries no meaning to report.
+ *
+ * Exported so a guard can walk every field declaring `topLevelMeans` across
+ * every registry and check that each one composes into a grammatical
+ * sentence, without reimplementing the frame it is checking.
+ *
+ * @param {import("./field-spec.mjs").FieldSpec} field - A field declaring
+ *   `topLevelMeans`.
+ * @returns {string} The composed markdown line.
+ */
+export function topLevelExemptionLine(field: import("./field-spec.mjs").FieldSpec): string;
 /**
  * Render the per-type item frontmatter reference.
  *

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

@@ -213,19 +213,21 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   retiring one — so a field can move into `data:` while the corpus catches
  *   up, instead of on a flag day across four repositories. A declaration that
  *   names one is mid-sweep by construction; see {@link readsLegacyKey}.
- * @property {string} [topLevelMeans] - **What the note's top-level key of this
- *   name means instead** — declared only where it means something else, and
- *   stating it removes the shared top-level position from this field's
- *   resolution order.
+ * @property {string} [topLevelMeans] - **Why the note's top-level key of this
+ *   name is not this field's source** — declared wherever that key's spelling
+ *   means something else at the note level, or the closed top-level
+ *   vocabulary refuses it outright, and stating either removes the shared
+ *   top-level position from this field's resolution order.
  *
  *   A field's `name` doubles as its identity and as the shared property it
  *   draws from, which is right wherever the two levels state the same quantity
  *   — `data.weight` is the weight, whoever reads it. It is wrong wherever a
- *   spelling collides across the two vocabularies. An `affiliation` item's
+ *   spelling collides across the two vocabularies, or names a key the closed
+ *   top-level vocabulary does not admit at all. An `affiliation` item's
  *   `system.title` is the style of address an office carries; a note's
- *   top-level `title` is the note's own heading. Nothing relates them, and
- *   before this key one silently fed the other, stringifying an authored
- *   `title: null` into fifteen documents.
+ *   top-level `title` is refused outright. Nothing relates them, and before
+ *   this key one silently fed the other, stringifying an authored `title:
+ *   null` into fifteen documents.
  *
  *   **The value is the reason**, not a flag with a comment beside it. A boolean
  *   would record the decision and lose the case for it, and the next person
@@ -466,19 +468,21 @@ export type FieldSpec = {
      */
     legacyKey?: string | undefined;
     /**
-     * - **What the note's top-level key of this
-     * name means instead** — declared only where it means something else, and
-     * stating it removes the shared top-level position from this field's
-     * resolution order.
+     * - **Why the note's top-level key of this
+     * name is not this field's source** — declared wherever that key's spelling
+     * means something else at the note level, or the closed top-level
+     * vocabulary refuses it outright, and stating either removes the shared
+     * top-level position from this field's resolution order.
      *
      * A field's `name` doubles as its identity and as the shared property it
      * draws from, which is right wherever the two levels state the same quantity
      * — `data.weight` is the weight, whoever reads it. It is wrong wherever a
-     * spelling collides across the two vocabularies. An `affiliation` item's
+     * spelling collides across the two vocabularies, or names a key the closed
+     * top-level vocabulary does not admit at all. An `affiliation` item's
      * `system.title` is the style of address an office carries; a note's
-     * top-level `title` is the note's own heading. Nothing relates them, and
-     * before this key one silently fed the other, stringifying an authored
-     * `title: null` into fifteen documents.
+     * top-level `title` is refused outright. Nothing relates them, and before
+     * this key one silently fed the other, stringifying an authored `title:
+     * null` into fifteen documents.
      *
      * **The value is the reason**, not a flag with a comment beside it. A boolean
      * would record the decision and lose the case for it, and the next person

package/types/engine/foreign-catalog.d.mts

@@ -11,6 +11,20 @@ export function itemCatalogRelationships(config: object): Array<{
     kind: string;
     verified: string | undefined;
 }>;
+/**
+ * Every declared relationship that opted into supplying its release archive
+ * for asset bytes alone, with no item catalogue built from it.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Array<{id: string, manifest: string, kind: string, verified: string|undefined}>}
+ *   The opted-in relationships, in declaration order.
+ */
+export function assetArchiveRelationships(config: object): Array<{
+    id: string;
+    manifest: string;
+    kind: string;
+    verified: string | undefined;
+}>;
 /**
  * The cache directory for one dependency at one version.
  *
@@ -95,6 +109,26 @@ export function fetchCatalog(config: object, rel: {
     id: string;
     manifest: string;
 }): Promise<string>;
+/**
+ * Fetch one dependency's release archive for its asset bytes alone, building
+ * no item catalogue from it.
+ *
+ * Idempotent: a complete cache for the resolved version is left alone. Where a
+ * relationship also declares `itemCatalog: true`, {@link fetchCatalog} already
+ * unpacked this same archive into this same cache directory, and
+ * {@link fetchAllCatalogs} does not call this function for it — the two never
+ * download the same bytes twice.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {{id: string, manifest: string, verified?: string}} rel - The
+ *   declared relationship.
+ * @returns {Promise<string>} The dependency's cache directory.
+ */
+export function fetchAssetArchive(config: object, rel: {
+    id: string;
+    manifest: string;
+    verified?: string;
+}): Promise<string>;
 /**
  * Fill the cache from a locally built artifact rather than a release.
  *
@@ -167,6 +201,11 @@ export function fetchAllMetadata(config: object): Promise<number>;
 /**
  * Fetch every opted-in dependency. The `deps fetch` command.
  *
+ * A relationship declaring both `itemCatalog: true` and `assetArchive: true`
+ * is fetched once: {@link fetchCatalog} already unpacks the archive on its
+ * way to extracting the item catalogue, so this skips the archive-only fetch
+ * for any id {@link fetchCatalog} already handled.
+ *
  * @param {object} config - The resolved build configuration.
  * @returns {Promise<number>} How many dependencies were fetched.
  */

package/types/engine/frontmatter.d.mts

@@ -137,7 +137,7 @@ export function resolveRelation(fm: object, ctx?: string): Record<string, string
  *
  * @param {object} fm - The item frontmatter.
  * @param {string} [ctx] - Optional label for the error (defaults to the item's
- *   title/name, else "item").
+ *   display name, else "item").
  * @returns {string} The declared subType.
  * @throws {Error} When `subType` is missing or blank.
  */