@heroiclands/package-build 25.6.3 → 25.7.0

package/types/engine/index.d.mts

@@ -60,6 +60,7 @@ export * as assetReferences from "./asset-references.mjs";
 export * as packages from "./packages.mjs";
 export * as packagebuildIndex from "./packagebuild-index.mjs";
 export * as siteBuild from "./site-build.mjs";
+export * as sitePage from "./site-page.mjs";
 export * as sitePreview from "./site-preview.mjs";
 export * as previewIndex from "./preview-index.mjs";
 export * as contentRender from "./content-render.mjs";

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

@@ -0,0 +1,149 @@
+/**
+ * Pack a value into bytes {@link unpackValue} restores as an equal copy:
+ * Addresses, anchored links and Address maps keep their types, Maps, Sets,
+ * Dates and `undefined` survive, and a value shared by two places is still
+ * shared.
+ *
+ * @param {unknown} value - The value.
+ * @returns {Buffer} The bytes.
+ * @throws {Error} For a value holding a function, a symbol, or an object of
+ *   another class.
+ */
+export function packValue(value: unknown): Buffer;
+/**
+ * Restore a value {@link packValue} packed. Every call returns a fresh copy.
+ *
+ * @param {Buffer|Uint8Array} bytes - The packed value.
+ * @returns {unknown} The value.
+ * @throws {Error} When the bytes are not a packed value.
+ */
+export function unpackValue(bytes: Buffer | Uint8Array): unknown;
+/**
+ * Where a package's note cache is kept: `build/cache/note-page/` under the
+ * package root.
+ *
+ * @param {{rootDir: string}} config - The resolved configuration.
+ * @returns {string} The directory.
+ */
+export function noteCacheDirectory(config: {
+    rootDir: string;
+}): string;
+/**
+ * The toolchain a cached answer was derived with: package-build's version and
+ * the bytes of its own modules, the Node.js version, and the DuckDB version
+ * the query answers came from.
+ *
+ * @returns {string} Its hash.
+ */
+export function toolchainFingerprint(): string;
+/**
+ * What a note of a package renders against.
+ *
+ * @typedef {object} NoteTree
+ * @property {object[]} records - The tree's index records, as
+ *   {@link module:engine/content-index.indexRecordsFor} derives them.
+ * @property {{index: Map<string, object>}} foreign - The dependencies'
+ *   indexes, as {@link module:engine/metadata-index.loadForeignIndexes}
+ *   returns them: the very ones the records were derived with.
+ * @property {(files: Iterable<string>, own?: string) => Promise<{sqlTables: Map<string, object[]>, tables: "hit"|"miss"|"off"}>} answers -
+ *   The query answers and generated sections of the notes named, by absolute
+ *   path, as {@link module:engine/sql-tables.prepareTreeSqlTables} prepares
+ *   them; `tables` is `"hit"` when every one was read from the store. `own`
+ *   is the note being rendered, whose answers are always whole; every other
+ *   note named may be answered with the view a linking note needs. Rejects
+ *   with {@link NoteInputsChanged}, storing nothing, when the configuration,
+ *   fonts or dependency indexes are not the ones the records were derived
+ *   from, before or after the preparation.
+ * @property {(file: string) => string} textOf - A note's text, as the records
+ *   were derived from it.
+ * @property {{tree: "hit"|"miss"|"off", notes: number}} cache - What the
+ *   cache answered: the tree's records whole or not, and how many notes
+ *   derived their own records.
+ */
+/**
+ * The content tree's records, and its notes' query answers on demand, from
+ * the cache under `build/` while every input they were derived from is
+ * unchanged, and derived and stored otherwise.
+ *
+ * The dependencies' indexes are read here, between two readings of every
+ * input the store keys by: when the two differ, something changed while it
+ * was read, and the whole reading is done again, so what is stored is always
+ * derived from the bytes its key names.
+ *
+ * @param {object} config - The resolved configuration.
+ * @param {object} [options]
+ * @param {boolean} [options.cache=true] - Whether to read and write the
+ *   cache; `false` derives everything and touches nothing.
+ * @param {string} [options.toolchain] - The toolchain's fingerprint;
+ *   {@link toolchainFingerprint} by default.
+ * @param {typeof import("./sql-tables.mjs").prepareTreeSqlTables} [options.prepareTables] -
+ *   Prepares query answers; {@link module:engine/sql-tables.prepareTreeSqlTables}
+ *   by default.
+ * @param {typeof loadForeignIndexes} [options.loadForeign] - Reads the
+ *   dependencies' indexes; {@link module:engine/metadata-index.loadForeignIndexes}
+ *   by default.
+ * @returns {Promise<NoteTree>} The records, the indexes, the answers and what
+ *   the cache did.
+ * @throws {Error} As the derivation does: a note that cannot be indexed, a
+ *   dependency that has not been fetched or cannot be read, naming
+ *   `package-build deps fetch`; and when the inputs keep changing while they
+ *   are read.
+ */
+export function noteTree(config: object, { cache, toolchain, loadForeign, prepareTables, }?: {
+    cache?: boolean | undefined;
+    toolchain?: string | undefined;
+    prepareTables?: typeof import("./sql-tables.mjs").prepareTreeSqlTables | undefined;
+    loadForeign?: typeof loadForeignIndexes | undefined;
+}): Promise<NoteTree>;
+/** The error a reading raises when its inputs moved while it was read. */
+export class NoteInputsChanged extends Error {
+}
+/** How often a reading is done again when its inputs move under it. */
+export const READ_ATTEMPTS: 3;
+/**
+ * What a note of a package renders against.
+ */
+export type NoteTree = {
+    /**
+     * - The tree's index records, as
+     * {@link module :engine/content-index.indexRecordsFor} derives them.
+     */
+    records: object[];
+    /**
+     * - The dependencies'
+     * indexes, as {@link module :engine/metadata-index.loadForeignIndexes}returns them: the very ones the records were derived with.
+     */
+    foreign: {
+        index: Map<string, object>;
+    };
+    /**
+     * -
+     * The query answers and generated sections of the notes named, by absolute
+     * path, as {@link module :engine/sql-tables.prepareTreeSqlTables} prepares
+     * them; `tables` is `"hit"` when every one was read from the store. `own`
+     * is the note being rendered, whose answers are always whole; every other
+     * note named may be answered with the view a linking note needs. Rejects
+     * with {@link NoteInputsChanged}, storing nothing, when the configuration,
+     * fonts or dependency indexes are not the ones the records were derived
+     * from, before or after the preparation.
+     */
+    answers: (files: Iterable<string>, own?: string) => Promise<{
+        sqlTables: Map<string, object[]>;
+        tables: "hit" | "miss" | "off";
+    }>;
+    /**
+     * - A note's text, as the records
+     * were derived from it.
+     */
+    textOf: (file: string) => string;
+    /**
+     * - What the
+     * cache answered: the tree's records whole or not, and how many notes
+     * derived their own records.
+     */
+    cache: {
+        tree: "hit" | "miss" | "off";
+        notes: number;
+    };
+};
+import { loadForeignIndexes } from "./metadata-index.mjs";

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

@@ -0,0 +1,92 @@
+/**
+ * A rendered note.
+ *
+ * @typedef {object} NotePage
+ * @property {string} html - The page body, as the site theme receives it,
+ *   with every page it links counted as reachable from the homepage.
+ * @property {string} styles - The CSS the theme applies to a page body; see
+ *   {@link module:engine/content-styles.noteBodyStylesheet}.
+ * @property {Array<{file?: string, line?: number, column?: number,
+ *   severity: string, message: string}>} findings - What the render found,
+ *   each printing as `file:line:column: severity: message` through
+ *   `formatDiagnostic`.
+ * @property {{tree: "hit"|"miss"|"off", notes: number, tables: "hit"|"miss"|"off"}} cache -
+ *   What the cache answered: `tree` whether the content tree's records were
+ *   reused whole, `notes` how many notes derived their own records again, and
+ *   `tables` whether the query answers of the note and of the notes it links
+ *   were all reused.
+ */
+/**
+ * Render one note of a repository to the body HTML of its site page.
+ *
+ * Loads the repository's `package-build.config.yaml`, its dependencies'
+ * fetched indexes, the content tree's records and the note's own query
+ * answers, and renders the note against them as `package-build site build`
+ * renders its page. The records and answers come from
+ * `build/cache/note-page/` while every input they were derived from is
+ * unchanged; see {@link module:engine/note-cache.noteTree}. The note is read
+ * from disk, so what is rendered is what is saved.
+ *
+ * @param {string} file - The note, relative to `root` or absolute.
+ * @param {object} [options]
+ * @param {string} [options.root] - The repository, or a directory inside it;
+ *   the working directory by default.
+ * @param {boolean} [options.cache=true] - Whether to read and write the cache;
+ *   `false` derives everything and writes nothing.
+ * @param {typeof import("./sql-tables.mjs").prepareTreeSqlTables} [options.prepareTables] -
+ *   Prepares the query answers;
+ *   {@link module:engine/sql-tables.prepareTreeSqlTables} by default. A host
+ *   may wrap it, to time or observe the preparation.
+ * @returns {Promise<NotePage>} The body, its styles, the findings and what the
+ *   cache did.
+ * @throws {Error} When there is no configuration; when the file is not a
+ *   note of the content tree; when a dependency's index has not been fetched
+ *   or cannot be read, naming `package-build deps fetch`; when a note of the
+ *   tree cannot be indexed, as the content-index build reports it; and when
+ *   the configuration, fonts or dependency indexes keep changing while they
+ *   are read.
+ */
+export function renderNoteFile(file: string, { root, cache, prepareTables }?: {
+    root?: string | undefined;
+    cache?: boolean | undefined;
+    prepareTables?: typeof import("./sql-tables.mjs").prepareTreeSqlTables | undefined;
+}): Promise<NotePage>;
+/**
+ * A rendered note.
+ */
+export type NotePage = {
+    /**
+     * - The page body, as the site theme receives it,
+     * with every page it links counted as reachable from the homepage.
+     */
+    html: string;
+    /**
+     * - The CSS the theme applies to a page body; see
+     * {@link module :engine/content-styles.noteBodyStylesheet}.
+     */
+    styles: string;
+    /**
+     * - What the render found,
+     * each printing as `file:line:column: severity: message` through
+     * `formatDiagnostic`.
+     */
+    findings: Array<{
+        file?: string;
+        line?: number;
+        column?: number;
+        severity: string;
+        message: string;
+    }>;
+    /**
+     * -
+     * What the cache answered: `tree` whether the content tree's records were
+     * reused whole, `notes` how many notes derived their own records again, and
+     * `tables` whether the query answers of the note and of the notes it links
+     * were all reused.
+     */
+    cache: {
+        tree: "hit" | "miss" | "off";
+        notes: number;
+        tables: "hit" | "miss" | "off";
+    };
+};

package/types/engine/pack-config.d.mts

@@ -114,6 +114,36 @@ export function configFromData(data: unknown, configPath: string): import("../co
  *   compilers know neither what to compile nor where to put it.
  */
 export function loadPackConfig(): import("../content-config.mjs").ContentBuildConfig;
+/**
+ * The resolved, frozen configuration one file declares.
+ *
+ * {@link loadPackConfig} reads the file the working directory resolves to and
+ * keeps it; this reads the file named, every time, for a caller working on a
+ * repository other than the one it stands in.
+ *
+ * @param {string} configPath - Absolute path of the configuration file.
+ * @returns {import("../content-config.mjs").ContentBuildConfig} The frozen configuration.
+ * @throws {Error} As {@link loadPackConfig}, when the file cannot be loaded.
+ */
+export function readPackConfig(configPath: string): import("../content-config.mjs").ContentBuildConfig;
+/**
+ * Run `fn` with `config` as the configuration {@link loadPackConfig} answers.
+ *
+ * The engine reads configured values through {@link loadPackConfig} wherever
+ * a caller passes no configuration. A caller working on a repository other
+ * than the one it stands in makes those reads answer with that repository's
+ * configuration for the whole of `fn`, its asynchronous continuations
+ * included, and for nothing else running beside it.
+ *
+ * @template T
+ * @param {import("../content-config.mjs").ContentBuildConfig} config - The
+ *   resolved configuration.
+ * @param {() => T} fn - The work, synchronous or asynchronous.
+ * @param {string} [file] - The file `config` was read from, which
+ *   {@link packConfigPath} answers within `fn`.
+ * @returns {T} What `fn` returned.
+ */
+export function withPackConfig<T>(config: import("../content-config.mjs").ContentBuildConfig, fn: () => T, file?: string): T;
 /**
  * The file {@link loadPackConfig} resolved the configuration from.
  *

package/types/engine/prepared-only.d.mts

@@ -0,0 +1,14 @@
+/**
+ * The `only` a query preparation takes: one note file, several, or none.
+ *
+ * @module
+ */
+/**
+ * Whether a note file falls outside a preparation's `only`.
+ *
+ * @param {string|Iterable<string>|undefined} only - One note file, several,
+ *   or none, which keeps every note.
+ * @param {string} file - The note file.
+ * @returns {boolean} Whether `only` is given and leaves `file` out.
+ */
+export function outsideOnly(only: string | Iterable<string> | undefined, file: string): boolean;

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

@@ -13,6 +13,41 @@
  *   expressions and figure numbers resolved. A query, which a buffer cannot
  *   answer, is left as written.
  */
+/**
+ * What a page of the package resolves against, from its content-index records.
+ *
+ * The site build reads the same answers from its whole tree; this derives
+ * them from the records alone, so a single note renders as its page does
+ * without the tree. Each note that publishes a page is an entry at the URL
+ * the site gives it: the homepage at the package root, a note
+ * `site.sections` names at its section, and every other at its address.
+ *
+ * @param {object} options
+ * @param {object} options.config - The resolved package configuration.
+ * @param {object[]} options.records - The content index's records.
+ * @param {object} [options.foreign] - The dependencies' indexes, as
+ *   {@link module:engine/metadata-index.loadForeignIndexes} returns them.
+ * @param {(record: object) => object[]|undefined} [options.anchorsOf] - A
+ *   note's anchors as its page emits them, where they differ from the
+ *   record's: those of its body with its query answers and generated sections
+ *   expanded. Absent, or answering nothing, the record's own.
+ * @returns {{site: object, assets: object, events: Map<string, object>, runs: object,
+ *   pages: Map<string, object>}} The link index, the asset address space,
+ *   every note's events, the package's marked-text context, and the record
+ *   behind each page by its URL.
+ */
+export function recordSiteContext({ config, records, foreign, anchorsOf }: {
+    config: object;
+    records: object[];
+    foreign?: object | undefined;
+    anchorsOf?: ((record: object) => object[] | undefined) | undefined;
+}): {
+    site: object;
+    assets: object;
+    events: Map<string, object>;
+    runs: object;
+    pages: Map<string, object>;
+};
 /**
  * Build the object a preview with an index renders from.
  *

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

@@ -146,93 +146,6 @@ export function siteBuildFailed(result: object): boolean;
  * @returns {Map<string, object[]>} Package → the notes it may tabulate.
  */
 export function tableUniverse(pages: object[]): Map<string, object[]>;
-/**
- * The frontmatter a page publishes with.
- *
- * A content page carries the package the build **derived**. No note
- * declares one, so the note's frontmatter alone would publish a page that does
- * not say which package it belongs to. Writing the derived value keeps a page
- * self-describing and makes sweeping the field out of a content tree
- * output-preserving for a site as it already is for the packs.
- *
- * **`related` is derived, never authored.** What links to a page is a fact
- * about every other page, known only once the whole tree has resolved — see
- * {@link module:engine/related-pages} — so an authored value is dropped, and
- * {@link renderPages} sets the derived block once it holds the graph.
- *
- * @param {object} page - The page.
- * @param {object} options
- * @param {(data: object, page: object) => void} [options.decorate] - Called
- *   with each page's frontmatter, for whatever a consumer's own pass adds.
- * @param {(value: unknown, type: string, accepts?: Iterable<string>) => string|null} [options.artSrc] -
- *   Translates an art address into the pathname the website resolver takes, or
- *   `null` where nothing answers it.
- * @param {(src: string) => string} [options.webSrc] - Translates an authored
- *   pathname into the address the website serves. Every artwork field goes
- *   through it, so a page's `img:` and its body images name the same file the
- *   same way.
- * @returns {object} The frontmatter.
- */
-export function pageFrontmatter(page: object, { decorate, webSrc, artSrc }: {
-    decorate?: ((data: object, page: object) => void) | undefined;
-    artSrc?: ((value: unknown, type: string, accepts?: Iterable<string>) => string | null) | undefined;
-    webSrc?: ((src: string) => string) | undefined;
-}): object;
-/** Transform one content page. */
-export function renderSitePage(page: any, { index, foreign, pass, decorate, sqlTables, config, artIndex, figuresByAddress, events, drawings, runs, }: {
-    index: any;
-    foreign: any;
-    pass?: {} | undefined;
-    decorate: any;
-    sqlTables: any;
-    config: any;
-    artIndex: any;
-    figuresByAddress?: Map<any, any> | undefined;
-    events: any;
-    drawings?: Map<any, any> | undefined;
-    runs?: import("./content-scripts.mjs").RunContext | undefined;
-}): {
-    page: any;
-    markdown: string;
-    figures: object[];
-    data: object;
-    resolved: object[];
-    tableErrors: object[];
-    expressionErrors: object[];
-    secretErrors: {
-        file: any;
-        line: number;
-        column: number;
-        message: string;
-    }[];
-    captionErrors: {
-        file: any;
-        line: any;
-        column: any;
-        message: any;
-    }[];
-    headingErrors: {
-        line: number;
-        column: number;
-        message: string;
-        file: any;
-    }[];
-    footnoteErrors: {
-        file: any;
-        line: number;
-        column: number;
-        message: string;
-    }[];
-    wikiErrors: object[];
-    imageErrors: any[];
-    embedErrors: {
-        file: string;
-        line: number;
-        column: number | undefined;
-        severity: "error";
-        message: string;
-    }[];
-};
 /**
  * Renders every page.
  *
@@ -283,18 +196,6 @@ export function renderPages(pages: object[], options: object): {
     pages: object[];
     runs: object;
 };
-/**
- * Resolves `site.pass` to its bundle.
- *
- * @param {string|undefined} name - The configured name.
- * @param {object} options - The configured options, plus `repoRoot`.
- * @returns {{beforeLinks?: Function}} The bundle.
- */
-export function resolveSitePass(name: string | undefined, options: object): {
-    beforeLinks?: Function;
-};
-/** The site frontmatter decoration shared by the site writer and page preview. */
-export function sitePageDecorator(config: any, index: any): (data: any, page: any) => void;
 /**
  * Collects, checks and renders a content tree's pages, and reports what it found.
  *
@@ -338,5 +239,9 @@ export function buildSite({ config, sqlTables, progress }?: {
     manifests: object | null;
     site?: object;
 };
-export { formatUnaddressableFinding };
+import { pageFrontmatter } from "./site-page.mjs";
+import { renderSitePage } from "./site-page.mjs";
+import { resolveSitePass } from "./site-page.mjs";
+import { sitePageDecorator } from "./site-page.mjs";
 import { formatUnaddressableFinding } from "./metadata-index.mjs";
+export { pageFrontmatter, renderSitePage, resolveSitePass, sitePageDecorator, formatUnaddressableFinding };

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

@@ -1,7 +1,7 @@
 /**
  * Check a navigation's shape, and return it.
  *
- * `[{name, url, children?: [{name, url}]}]`, every `url` absolute. Checked
+ * `[{name, url, children?: [{name, url}]}]`, every `url` a non-empty string. Checked
  * on fetch and again on read: a file that is not a navigation would otherwise
  * reach the menu as `undefined` labels and links.
  *
@@ -19,7 +19,7 @@ export function checkNavigation(value: unknown, where?: string): NavigationEntry
  */
 export function navigationCacheDir(config: object): string;
 /**
- * The cached navigation.
+ * The cached navigation, with canonical owned links on the effective homepage origin.
  *
  * **Reads the cache only.** A cold cache is an error naming the command that
  * fills it, rather than a download nobody asked for: a site build that reaches
@@ -93,6 +93,7 @@ export const BRAND: Readonly<{
 }>;
 /** Where the navigation is published. */
 export const NAVIGATION_URL: "https://www.heroiclands.org/nav.json";
+export { CANONICAL_CDN_ORIGIN } from "./site-origins.mjs";
 /** The cached navigation's file name. */
 export const NAVIGATION_FILE: "nav.json";
 /**

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

@@ -33,16 +33,22 @@ export function inlineSvg(svg: string): string;
  * @param {object} opts.config - The resolved configuration.
  * @param {string} opts.base - The site base every page is served under,
  *   ending in a slash: what every name in a drawing links through.
+ * @param {Iterable<string>} [opts.only] - The places to draw, by shortcode,
+ *   of those given a map; absent, every one.
+ * @param {string} [opts.outDir] - Where to draw, emptied first;
+ *   {@link SITE_MAP_DIR} under the package root by default.
  * @returns {{maps: Map<string, SiteMap>, findings: Array<{file: string,
  *   line?: number, column?: number, severity: "error"|"warning",
  *   message: string}>}} The drawings, keyed by the file name a **From here**
  *   section names, and warnings for relations that name no place.
  */
-export function drawSiteMaps({ records, foreignIndex, config, base }: {
+export function drawSiteMaps({ records, foreignIndex, config, base, only, outDir, }: {
     records: Array<Record<string, any>>;
     foreignIndex: Map<string, object>;
     config: object;
     base: string;
+    only?: Iterable<string> | undefined;
+    outDir?: string | undefined;
 }): {
     maps: Map<string, SiteMap>;
     findings: Array<{
@@ -53,16 +59,6 @@ export function drawSiteMaps({ records, foreignIndex, config, base }: {
         message: string;
     }>;
 };
-/**
- * The figure the website sets a drawing in: the SVG inline, so its place names
- * stay links, with no blank line inside it — a blank line would end the HTML
- * block and hand the rest of the drawing to the Markdown renderer.
- *
- * @param {string} svg - The drawing, as {@link inlineSvg} wrote it.
- * @param {string} alt - What the drawing shows, for a screen reader.
- * @returns {string} One HTML block.
- */
-export function inlineDrawingFigure(svg: string, alt: string): string;
 /**
  * Where the site build draws, below the package root.
  *

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

@@ -0,0 +1,9 @@
+/**
+ * The owned CDN origin, re-exported by site-config beside the chrome addresses.
+ * Kept in a leaf because site-config reaches pathnames through configuration and
+ * content rendering; importing site-config from pathnames would close that cycle.
+ *
+ * @module
+ */
+/** The canonical public origin whose asset URLs follow the selected build host. */
+export const CANONICAL_CDN_ORIGIN: "https://cdn.heroiclands.org";