@heroiclands/package-build 23.12.8 → 24.0.0

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

@@ -0,0 +1,72 @@
+/**
+ * What a preview reads to render with an index.
+ *
+ * @typedef {object} PreviewIndex
+ * @property {object} runs - The package's languages, faces and maps.
+ * @property {object|undefined} icons - The package's icon registry.
+ * @property {(src: string) => ({role?: string, width?: number|"", height?: number|""}|undefined)} lookupAsset -
+ *   From a picture's address to its asset.
+ * @property {(src: string) => string} resolveSrc - From a picture's authored
+ *   pathname to the address the website serves it at.
+ * @property {(markdown: string, note: {fm: object, file?: string}) => {markdown: string, figures: object[]}} expand -
+ *   Expand a buffer's body as the website expands a page: links, embeds,
+ *   expressions and figure numbers resolved. A query, which a buffer cannot
+ *   answer, is left as written.
+ */
+/**
+ * Build the object a preview with an index renders from.
+ *
+ * @param {object} options
+ * @param {object} options.config - The resolved package configuration.
+ * @param {object[]} options.records - The content index's records: every note
+ *   and every asset.
+ * @param {object} [options.foreign] - The dependencies' indexes, as
+ *   {@link module:engine/metadata-index.loadForeignIndexes} returns them.
+ *   Omitted, the package links only to itself.
+ * @returns {PreviewIndex} The index.
+ */
+export function previewIndex({ config, records, foreign }: {
+    config: object;
+    records: object[];
+    foreign?: object | undefined;
+}): PreviewIndex;
+/**
+ * What a preview reads to render with an index.
+ */
+export type PreviewIndex = {
+    /**
+     * - The package's languages, faces and maps.
+     */
+    runs: object;
+    /**
+     * - The package's icon registry.
+     */
+    icons: object | undefined;
+    /**
+     * -
+     * From a picture's address to its asset.
+     */
+    lookupAsset: (src: string) => ({
+        role?: string;
+        width?: number | "";
+        height?: number | "";
+    } | undefined);
+    /**
+     * - From a picture's authored
+     * pathname to the address the website serves it at.
+     */
+    resolveSrc: (src: string) => string;
+    /**
+     * -
+     * Expand a buffer's body as the website expands a page: links, embeds,
+     * expressions and figure numbers resolved. A query, which a buffer cannot
+     * answer, is left as written.
+     */
+    expand: (markdown: string, note: {
+        fm: object;
+        file?: string;
+    }) => {
+        markdown: string;
+        figures: object[];
+    };
+};

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

@@ -0,0 +1,51 @@
+/**
+ * Highlight a wikilink or an embed without interpreting any Markdown or HTML
+ * inside the source.
+ *
+ * @param {string} raw - The link as written, from `[[` or `![[` to its end.
+ * @returns {string} The highlighted source.
+ */
+export function wikiSource(raw: string): string;
+/**
+ * Install the preview target's rules.
+ *
+ * @param {import("markdown-it")} md - The shared parser.
+ * @param {object} [options]
+ * @param {boolean} [options.source] - The buffer has no index: show wikilinks,
+ *   embeds, spans and local expressions as authored source.
+ * @param {object} [options.fm] - The buffer's frontmatter, which a local
+ *   expression reads.
+ * @param {string} [options.file] - The buffer's name, for a finding.
+ * @param {Map<string, object>} [options.figures] - The buffer's captioned items
+ *   by id, which a local `ref` reads.
+ */
+export function previewSourcePlugin(md: typeof import("markdown-it"), { source, fm, file, figures }?: {
+    source?: boolean | undefined;
+    fm?: object | undefined;
+    file?: string | undefined;
+    figures?: Map<string, object> | undefined;
+}): void;
+/** Explicit dependency policy: a new registered helper requires a preview decision. */
+export const PREVIEW_HELPERS: Readonly<{
+    eq: "local";
+    gt: "local";
+    gte: "local";
+    lt: "local";
+    lte: "local";
+    not: "local";
+    and: "local";
+    or: "local";
+    words: "local";
+    digits: "local";
+    sql: "dependent";
+    dateformat: "dependent";
+    ref: "reference";
+}>;
+/**
+ * What stands for an authored `<` in the preview between
+ * {@link module:engine/content-render.inertHtml} and the rendered HTML, where
+ * it is written `&lt;`. A private-use character, so it can neither be read as
+ * markup nor collide with prose.
+ */
+export const INERT_BRACKET: "\uE000";
+export function colored(role: string, source: string): string;

package/types/engine/read-stdin.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Reads standard input to its end as UTF-8 text.
+ *
+ * The stream is read asynchronously, so a pipe whose writer is slower than the
+ * reader, or a non-blocking descriptor, delivers the whole input instead of
+ * failing with `EAGAIN`.
+ *
+ * @param {NodeJS.ReadableStream} [stream] The stream to drain; standard input by default.
+ * @returns {Promise<string>} The complete input.
+ */
+export function readStdin(stream?: NodeJS.ReadableStream): Promise<string>;

package/types/engine/run-rows.d.mts

@@ -2,7 +2,7 @@
  * One run as an index record carries it.
  *
  * @typedef {object} RecordRun
- * @property {"span"|"block"|"poetry"} kind - The construct.
+ * @property {"span"|"block"|"verse"} kind - The construct.
  * @property {string|null} lang - The language it is set in, as written: its
  *   own `lang=`, else the one the div or fence around it states.
  * @property {string|null} tag - The BCP 47 tag it resolves to, or null.
@@ -57,7 +57,7 @@ export type RecordRun = {
     /**
      * - The construct.
      */
-    kind: "span" | "block" | "poetry";
+    kind: "span" | "block" | "verse";
     /**
      * - The language it is set in, as written: its
      * own `lang=`, else the one the div or fence around it states.

package/types/engine/run-words.d.mts

@@ -1,18 +1,3 @@
-/**
- * A word as it is compared: NFC, lowercase, `’` read as `'`.
- *
- * @param {string} word - The word.
- * @returns {string} Its folded form.
- */
-export function foldWord(word: string): string;
-/**
- * The words a language note accepts of its own: its forms, and what its
- * plural rows, verb pattern and replacing suffixes derive from them.
- *
- * @param {Record<string, any>} data - The language note's `data`.
- * @returns {Set<string>} The words, folded.
- */
-export function lexiconWords(data: Record<string, any>): Set<string>;
 /**
  * The words of every name a language note registers under a tongue other than
  * `translation`.

package/types/engine/script-emphasis-terms.d.mts

@@ -0,0 +1,21 @@
+/**
+ * **The words a script note and a language note state emphasis by.** Read by
+ * the vocabulary as it is declared, so this module imports nothing; the
+ * checks and the conventions' use are in {@link module:engine/script-emphasis}.
+ *
+ * @module
+ */
+/** The conventions a script states its emphasis by. */
+export const EMPHASIS_CONVENTIONS: readonly string[];
+/** The class each convention gives an `<em>` or a `<strong>`. */
+export const EMPHASIS_CLASSES: Readonly<{
+    rubric: "emph-rubric";
+    overline: "emph-overline";
+}>;
+/**
+ * The conventions a language note states, which override its script's.
+ * `words` marks emphasis with a word, so a mark in its text is a finding.
+ */
+export const LANGUAGE_EMPHASES: readonly string[];
+/** The `subType` of a script note. */
+export const SCRIPT_SUBTYPE: "script";

package/types/engine/script-emphasis.d.mts

@@ -0,0 +1,84 @@
+/**
+ * Each face's conventions, from the script notes among the index records. The
+ * first note to list a face keeps it; a second is the lint's to report, and a
+ * note whose convention is unknown gives none.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @returns {Map<string, Emphasis>} The conventions, by face slug.
+ */
+export function emphasesFromRecords(records: Iterable<Record<string, any>> | undefined): Map<string, Emphasis>;
+/**
+ * The convention each language's note states.
+ *
+ * @param {ReadonlyMap<string, Record<string, any>>} byName - Each configured
+ *   language's note record, by language name, from
+ *   {@link module:engine/map-lexicon.languageRecordsByName}.
+ * @returns {Map<string, LanguageEmphasis>} The conventions, by language name;
+ *   a language whose note states none, or one the build does not know, is
+ *   absent.
+ */
+export function languageEmphasesOf(byName: ReadonlyMap<string, Record<string, any>>): Map<string, LanguageEmphasis>;
+/**
+ * Refuse `data.emphasis` on a skill that is not a language, at its key.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @returns {object[]} The findings.
+ */
+export function checkLanguageEmphasis(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}): object[];
+/**
+ * Check a note's `data.script`: that the note is a script, and that its
+ * `fonts` is not empty, names no generic family, lists no face twice, and
+ * lists no face another script note lists. The data-key check owns every key,
+ * its kind and the conventions; whether a face is installed is
+ * {@link checkScriptNoteFonts}'s.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @param {{index?: {notes?: Iterable<object>}}} [context] - The lint index.
+ * @returns {object[]} The findings, each at its key or entry.
+ */
+export function checkScriptField(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}, { index }?: {
+    index?: {
+        notes?: Iterable<object>;
+    };
+}): object[];
+/**
+ * Each face a script note lists that is not installed, at its entry.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @param {{faces?: ReadonlyMap<string, unknown>}} [ctx] - The installed faces,
+ *   from {@link module:engine/content-scripts.runContext}.
+ * @returns {object[]} The findings.
+ */
+export function checkScriptNoteFonts(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}, ctx?: {
+    faces?: ReadonlyMap<string, unknown>;
+}): object[];
+/**
+ * One face's conventions, one for each level of emphasis.
+ */
+export type Emphasis = {
+    /**
+     * - What `*…*` is set by.
+     */
+    em: "rubric" | "overline";
+    /**
+     * - What `**…**` is set by.
+     */
+    strong: "rubric" | "overline";
+};
+/**
+ * A convention a language note states.
+ */
+export type LanguageEmphasis = "words" | "rubric" | "overline";
+export { EMPHASIS_CLASSES, EMPHASIS_CONVENTIONS, LANGUAGE_EMPHASES } from "./script-emphasis-terms.mjs";

package/types/engine/script-font-delivery.d.mts

@@ -69,10 +69,10 @@ export function checkScriptFonts(config: DeliveryConfig): {
  */
 export function siteFontsParam(config: DeliveryConfig): string | undefined;
 /**
- * The directory under the Hugo static tree that holds this version's fonts.
+ * The directory under the site's static tree that holds this version's fonts.
  *
  * @param {string} version - The fonts package's version.
- * @returns {string} The POSIX path, relative to `build/hugo/static`.
+ * @returns {string} The POSIX path, relative to the static tree.
  */
 export function siteFontsDestination(version: string): string;
 /**
@@ -104,8 +104,8 @@ export function typstScriptFontPath(config: DeliveryConfig): string | undefined;
  */
 export const STAGED_FONTS_DIR: string;
 /**
- * Where the files land in the Hugo static tree, relative to `build/hugo/static`,
- * beneath a directory per version.
+ * Where the files land in the site's static tree, beneath a directory per
+ * version.
  *
  * @type {string}
  */

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

@@ -3,9 +3,10 @@
  *
  * @param {string} contentBase - Absolute path to the content tree.
  * @param {object} ctx - `{ packages, contentPackage, skipDirectories, base,
- *   mount, scheme }`. `contentPackage` is the package a note that declares none
- *   belongs to; `base` is where the package is served and `mount` is where its
- *   content tree sits inside it.
+ *   mount, scheme, only }`. `contentPackage` is the package a note that
+ *   declares none belongs to; `base` is where the package is served and `mount`
+ *   is where its content tree sits inside it. `only`, an absolute path, reads
+ *   that one note and no other.
  * @returns {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}
  */
 export function collectContentPages(contentBase: string, ctx: object): {
@@ -42,34 +43,10 @@ export function collectHomepages(contentBase: string, ctx: object): {
     addressFindings: object[];
 };
 /**
- * Writes each homepage as the package root's `_index.md`.
+ * Each homepage's frontmatter as its page publishes it, and its body.
  *
- * Its own writer, deliberately small. A homepage is authored markdown published
- * verbatim — no table expansion and no link resolution — so routing it through
- * {@link renderPages} would give it a pipeline it does not use.
- *
- * **Verbatim is the answer, not a gap.** A homepage's links could not be
- * *resolved* here, so they are **checked** instead:
- * {@link auditHomepageLinks} reads the body's markdown links, and reports a
- * wikilink on the page rather than resolving one.
- *
- * **Its destination is fixed**: {@link HOMEPAGE_DESTINATION}, at the package's
- * site root, which Hugo renders as the `home` kind at `/<package>/`. The page
- * states no `url` — the home kind has none to state — and the mount below it
- * holds pages and nothing else, so this is the only `_index.md` in the tree.
- *
- * **Verbatim, but not unconnected.** The homepage is a page like any other on
- * both sides of the link graph: a content page reaches it through
- * `[[homepage-root|Text]]`, and its own markdown links name content pages. So
- * it carries the same `related` block every content page does — handed in by
- * the caller, since the graph is read off the content render and a tree with
- * only a homepage has no such graph.
- *
- * @param {string} outRoot - The package's site root — the content mount's
- *   root, `build/hugo/content`, one level above the mount itself.
  * @param {readonly object[]} pages - From {@link collectHomepages}.
- * @param {object} config - The resolved configuration, for the package name and
- *   the default title.
+ * @param {object} config - The resolved configuration.
  * @param {object} [options] - Options.
  * @param {import("./related-pages.mjs").Related} [options.related] - The
  *   homepage's backlinks and mentions. Absent where nothing connects to it,
@@ -78,13 +55,18 @@ export function collectHomepages(contentBase: string, ctx: object): {
  *   address resolves against the images this package ships.
  * @param {object} [options.foreign] - The dependencies' vendored indexes, so a
  *   `data.banner` may name an image a dependency ships.
- * @returns {number} How many pages were written.
+ * @returns {Array<{file: string, body: string, data: object}>} One entry per
+ *   homepage, in walk order.
  */
-export function writeHomepages(outRoot: string, pages: readonly object[], config: object, { related, records, foreign }?: {
+export function homepageData(pages: readonly object[], config: object, { related, records, foreign }?: {
     related?: import("./related-pages.mjs").Related | undefined;
     records?: readonly object[] | undefined;
     foreign?: object | undefined;
-}): number;
+}): Array<{
+    file: string;
+    body: string;
+    data: object;
+}>;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -132,7 +114,7 @@ export function emptyGates(): object;
 /**
  * Whether any gate produced a finding.
  * @param {{homepages: unknown[], frontmatterLinks: unknown[],
- *   addressErrors: unknown[], staleManifests: unknown[],
+ *   addressErrors: unknown[], sections?: unknown[], staleManifests: unknown[],
  *   unaddressable: unknown[]}} gates - Results of the site checks.
  * @returns {boolean} Whether at least one check found an error.
  */
@@ -140,9 +122,20 @@ export function gatesFailed(gates: {
     homepages: unknown[];
     frontmatterLinks: unknown[];
     addressErrors: unknown[];
+    sections?: unknown[];
     staleManifests: unknown[];
     unaddressable: unknown[];
 }): boolean;
+/**
+ * Whether a site build found anything that stops its pages being written: a
+ * gate that fired, or a note whose table, expression, block, caption, heading,
+ * footnote, link, image or embed is in error. What drawing the maps found does
+ * not stop it.
+ *
+ * @param {object} result - From {@link buildSite}.
+ * @returns {boolean} Whether the build failed.
+ */
+export function siteBuildFailed(result: object): boolean;
 /**
  * The universe a generated table searches, grouped by package.
  *
@@ -156,39 +149,19 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
 /**
  * The frontmatter a page publishes with.
  *
- * An authored `aliases` is a list of names a reader might call the note. Hugo reads
- * `aliases` as **URL redirects**, so passing them through would publish a
- * redirect stub at each name. They are dropped, and this build emits no
- * redirects of its own.
- *
- * A content page states its own **`url`**, which is its address rather than its
- * path. It is written flat under the content mount, so Hugo would
- * otherwise publish it at `<mount><type>-<shortcode>/` rather than at the
- * package-wide address the link manifest records — the same address, one
- * segment too deep. So the address is stated and the mount does not reach it.
- *
- * **It is stated relative to the site root, and so carries no package base**.
- * Hugo resolves a `url` against `baseURL`, whose path is already where
- * the package is served — a consumer's Hugo site *is* its package — so writing
- * `page.url`, which carries the base for every href this build renders, wrote
- * that base a second time and published every content page a segment too deep
- * (`/sohl/sohl/doc-rulesintro/`). The two are separate quantities: the page
- * states `/<slug>/`, and everything that points *at* the page — the address
- * index a wikilink resolves through, and the link manifest — composes
- * `<base><slug>/`.
+ * An authored `aliases` is a list of names a reader might call the note. It is
+ * dropped: this build emits no redirects.
  *
  * 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. The
- * emitted page is what a theme reads: `breadcrumbs.html` reads
- * `.Params.package`. Writing the derived value keeps a page
+ * 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 the
- * way `aliases` is, and {@link renderPages} writes the derived block once it
+ * way `aliases` is, and {@link renderPages} sets the derived block once it
  * holds the graph.
  *
  * @param {object} page - The page.
@@ -202,41 +175,19 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  *   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 to write.
+ * @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;
-/**
- * Where a page is written, relative to the output root.
- *
- * **Flat, under the mount, named by its address**. A content page's URL
- * is its address — `/<package>/<type>-<shortcode>/` — and the file is named
- * the same way, so the two agree. No page creates a directory: a section is
- * a Hugo listing over a content directory, the `section` kind is disabled on
- * every site, and a directory chosen only to satisfy a rendering engine's idea
- * of what a section is has no business in the note format.
- *
- * The name is the *whole* address, so two types cannot fight over one file: a
- * `doc` note's `subType` may be spelled the same as another note's `type`, and
- * `doc-gear.md` and `weapongear-gear.md` are distinct.
- *
- * @param {{slug: string}} page - The page.
- * @returns {string} The file, relative to the mount.
- */
-export function pageDestination(page: {
-    slug: string;
-}): string;
-/** Transform one content page without writing the site mount. */
-export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, figuresByAddress, events, drawings, runs, }: {
+/** Transform one content page. */
+export function renderSitePage(page: any, { index, foreign, pass, decorate, sqlTables, config, artIndex, figuresByAddress, events, drawings, runs, }: {
     index: any;
     foreign: any;
-    universe: any;
     pass?: {} | undefined;
     decorate: any;
-    linkable?: ((d: any) => boolean) | undefined;
     sqlTables: any;
     config: any;
     artIndex: any;
@@ -246,11 +197,12 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     runs?: import("./content-scripts.mjs").RunContext | undefined;
 }): {
     page: any;
-    body: string;
+    markdown: string;
+    figures: object[];
     data: object;
-    resolved: any[];
+    resolved: object[];
     tableErrors: object[];
-    expressionErrors: any[];
+    expressionErrors: object[];
     secretErrors: {
         file: any;
         line: number;
@@ -260,8 +212,8 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     captionErrors: {
         file: any;
         line: any;
-        column: number;
-        message: string;
+        column: any;
+        message: any;
     }[];
     headingErrors: {
         line: number;
@@ -275,7 +227,7 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
         column: number;
         message: string;
     }[];
-    wikiErrors: any[];
+    wikiErrors: object[];
     imageErrors: any[];
     embedErrors: {
         file: string;
@@ -286,24 +238,20 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     }[];
 };
 /**
- * Renders and writes every page.
- *
- * The order inside a page is load-bearing and is the same order the pack
- * compilers use:
- *
- * 1. **Tables expand first**, and outside code-fence protection. A table is
- *    authored as a fenced `sql` block, which `protectCode` would otherwise
- *    stash away before the expander saw it. Expanding first leaves an ordinary
- *    markdown table to walk, with every other fence still protected.
- * 2. **Then, inside protection**: the consumer's `beforeLinks` pass, then
- *    wikilink resolution. A `{@link}` tag may sit in prose a wikilink also
- *    touches, so the repository's own rewrite runs before the shared one
- *    rather than replacing it.
- *
- * **Every page is rendered before any is written.** What links *to* a page is
- * known only once every other page has resolved, and it is written into the
- * page's own front matter, so the render is one pass over the tree and the
- * write is a second — with the link graph read off the first, at the one
+ * Renders every page.
+ *
+ * Each page's body is expanded by
+ * {@link module:engine/content-expand.expandContent}, the step the pack
+ * compilers take too: tables first and outside code-fence protection, then
+ * figure numbers and expressions, then, inside protection, the consumer's
+ * `beforeLinks` pass and wikilink resolution. A `{@link}` tag may sit in prose
+ * a wikilink also touches, so the repository's own rewrite runs before the
+ * shared one rather than replacing it.
+ *
+ * **Every page is rendered before any is finished.** What links *to* a page is
+ * known only once every other page has resolved, and it is set in the page's
+ * own front matter, so the render is one pass over the tree and the
+ * finishing is a second — with the link graph read off the first, at the one
  * point the resolver answers, and inverted once between them. Nothing is
  * resolved twice.
  *
@@ -320,10 +268,12 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[], embedErrors: object[],
  *   related: Map<string, import("./related-pages.mjs").Related>,
- *   maps: number}} `related`
+ *   maps: number, pages: object[], runs: object}} `related`
  *   is keyed by page URL, and holds the homepage's block beside every content
- *   page's, so the caller can write it on the page this render does not.
- *   `maps` counts the pages carrying a map.
+ *   page's, so the caller can set it on the page this render does not.
+ *   `maps` counts the pages carrying a map. `pages` holds
+ *   `{page, markdown, figures, data}` for each page and `runs` the package's
+ *   marked-text context.
  */
 export function renderPages(pages: object[], options: object): {
     written: number;
@@ -334,6 +284,8 @@ export function renderPages(pages: object[], options: object): {
     embedErrors: object[];
     related: Map<string, import("./related-pages.mjs").Related>;
     maps: number;
+    pages: object[];
+    runs: object;
 };
 /**
  * Resolves `site.pass` to its bundle.
@@ -348,7 +300,7 @@ export function resolveSitePass(name: string | undefined, options: object): {
 /** The site frontmatter decoration shared by the site writer and page preview. */
 export function sitePageDecorator(config: any, index: any): (data: any, page: any) => void;
 /**
- * Builds a Hugo content tree from a content tree, and reports what it found.
+ * Collects, checks and renders a content tree's pages, and reports what it found.
  *
  * Returns rather than exits, in every case. A caller — the command, or a test —
  * decides what a finding means; the gates below are grouped so it can report
@@ -366,8 +318,13 @@ export function sitePageDecorator(config: any, index: any): (data: any, page: an
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[], embedErrors: object[],
  *   mapFindings: object[],
- *   manifests: object|null}} `mapFindings` is what drawing the maps found —
- *   warnings, never a reason to fail the build.
+ *   manifests: object|null, site?: object}} `mapFindings` is what drawing the
+ *   maps found — warnings, never a reason to fail the build. `site` holds what a page renderer needs: `base`, `pages` (each content
+ *   page's `{page, markdown, figures, data}`), `homepages` (each
+ *   `{file, body, data}`), `runs`, `index`, `foreign` and `records`; and
+ *   `renderNote(file)`, which reads one content note again and renders it
+ *   against the rest of the build, or returns `null` when its address, name
+ *   or type changed and the whole site must be built again.
  */
 export function buildSite({ config, sqlTables }?: {
     config?: object | undefined;
@@ -381,6 +338,7 @@ export function buildSite({ config, sqlTables }?: {
     embedErrors: object[];
     mapFindings: object[];
     manifests: object | null;
+    site?: object;
 };
 export { formatUnaddressableFinding };
 import { formatUnaddressableFinding } from "./metadata-index.mjs";