@heroiclands/package-build 25.6.3 → 25.7.0

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

@@ -0,0 +1,261 @@
+/**
+ * A note's frontmatter and body, from its source text.
+ *
+ * @param {string} source - The note as authored.
+ * @param {string} file - Where it is, for a finding.
+ * @param {object} ctx - `{ config, contentPackage }`, which decode its
+ *   addresses.
+ * @returns {{fm: object, body: string, bodyLine: number}|null} `null` for text
+ *   that is not front-mattered markdown.
+ * @throws {Error} When an address in its frontmatter cannot be decoded; the
+ *   error carries `file` and `position`.
+ */
+export function parseNote(source: string, file: string, ctx: object): {
+    fm: object;
+    body: string;
+    bodyLine: number;
+} | null;
+/**
+ * The page a note publishes as, or why it publishes none.
+ *
+ * @param {{fm: object, body: string, bodyLine: number}} note - From {@link parseNote}.
+ * @param {object} ctx - `{ file, fileBase, relPath, folder, base, packages,
+ *   contentPackage, sectionPages, present, dates }`: the note's path, its
+ *   file name, its path below the content root and its folder's name; the
+ *   package's site address; the packages the site publishes and the one the
+ *   note belongs to; the pages `site.sections` names; and the present and
+ *   reckoning a being's age is computed in.
+ * @returns {{page?: object, fmLinks: object[], addressFinding?: object}|null}
+ *   `null` for a note with no page: a homepage, a stub, a GM note, or one
+ *   outside the published packages. Otherwise the page, or the finding that
+ *   says why it has no address, with any wikilink authored in frontmatter.
+ */
+export function contentPage(note: {
+    fm: object;
+    body: string;
+    bodyLine: number;
+}, ctx: object): {
+    page?: object;
+    fmLinks: object[];
+    addressFinding?: object;
+} | null;
+/**
+ * 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 module:engine/site-maps.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;
+/**
+ * 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 module:engine/site-build.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;
+/**
+ * The title a content page publishes under — the note's name.
+ *
+ * One rule, read by the page's own front matter and by every `related` entry
+ * that names the page, so a card lists a page by exactly the title its heading
+ * shows.
+ *
+ * @param {object} page - The page, from {@link module:engine/site-build.collectContentPages}.
+ * @returns {string} The title.
+ */
+export function pageTitle(page: object): string;
+/**
+ * Rewrite a page's artwork addresses into the URLs the website serves.
+ *
+ * The slots are read from {@link module:engine/art-fields.ART_SLOTS}, so a slot
+ * added to the vocabulary reaches the page without anyone remembering this
+ * function exists. Only an authored **string** is touched: `null` is a note
+ * naming no art and `""` is one naming none on purpose, and neither is an
+ * address to resolve. A slot's declining word (`banner: none`) is emitted as
+ * a blank, the value a theme reads as "draw no image".
+ *
+ * **An address nothing answers is dropped**, not emitted as written. The theme
+ * renders nothing where a value is absent — its silent-disappear convention —
+ * and a raw address left in place would reach the reader as a broken image
+ * source with nothing saying why.
+ *
+ * @param {object} data - The frontmatter being emitted, rewritten in place.
+ * @param {(src: string) => string} webSrc - The website's pathname resolver.
+ * @param {(value: unknown, type: string, accepts?: Iterable<string>) => string|null} artSrc -
+ *   The address resolver, yielding the pathname `webSrc` takes.
+ * @returns {void}
+ */
+export function resolveArtFields(data: object, webSrc: (src: string) => string, artSrc: (value: unknown, type: string, accepts?: Iterable<string>) => string | null): void;
+/**
+ * @param {unknown} value - Anything.
+ * @returns {boolean} Whether it is a mapping a field may be read out of.
+ */
+export function isPlainObject(value: unknown): boolean;
+/**
+ * Transform one content page.
+ *
+ * `page` is from {@link contentPage}; the options are what it resolves
+ * against: the site `index`, the `foreign` indexes, the consumer's `pass`, the
+ * frontmatter `decorate`, the prepared `sqlTables`, the `config`, the asset
+ * `artIndex`, other pages' `figuresByAddress`, the `events` index, `drawing`
+ * and the marked-text `runs`. The result holds the expanded `markdown`, its
+ * `figures`, the page's frontmatter as `data`, the links it `resolved`, and
+ * each kind of finding.
+ *
+ * Reads no file. A drawing a generated **From here** section names is asked
+ * of `drawing`, by its file name, for its SVG text, and set inline when it
+ * answers.
+ */
+export function renderSitePage(page: any, { index, foreign, pass, decorate, sqlTables, config, artIndex, figuresByAddress, events, drawing, runs, }: {
+    index: any;
+    foreign: any;
+    pass?: {} | undefined;
+    decorate: any;
+    sqlTables: any;
+    config: any;
+    artIndex: any;
+    figuresByAddress?: Map<any, any> | undefined;
+    events: any;
+    drawing?: (() => undefined) | 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;
+    }[];
+};
+/**
+ * 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;
+/**
+ * How a site renders a page body from the markdown its build expanded.
+ *
+ * @param {object} config - The resolved configuration.
+ * @returns {(markdown: string, options?: {runs?: object, figures?: object[]}) => string}
+ *   The body HTML as the site writer receives it.
+ */
+export function siteBodyRenderer(config: object): (markdown: string, options?: {
+    runs?: object;
+    figures?: object[];
+}) => string;
+/**
+ * Each finding of a page render as a diagnostic, kind by kind.
+ *
+ * @param {object} result - From {@link renderSitePage}, or the site build's
+ *   gathered result, which carries the same lists.
+ * @param {(file: string) => string} rawOf - A note's source text, which
+ *   locates a link or an image by the literal it was handed.
+ * @returns {Array<{file?: string, line?: number, column?: number,
+ *   severity: string, message: string}>} The diagnostics.
+ */
+export function pageDiagnostics(result: object, rawOf: (file: string) => string): Array<{
+    file?: string;
+    line?: number;
+    column?: number;
+    severity: string;
+    message: string;
+}>;
+/**
+ * A wikilink authored in a note's frontmatter, as a diagnostic.
+ *
+ * @param {{file: string, link: string, path: string}} finding - From
+ *   {@link contentPage}'s `fmLinks`.
+ * @returns {{file: string, severity: "error", message: string}} The diagnostic.
+ */
+export function frontmatterLinkDiagnostic(finding: {
+    file: string;
+    link: string;
+    path: string;
+}): {
+    file: string;
+    severity: "error";
+    message: string;
+};
+/**
+ * A note whose page has no address, as a diagnostic.
+ *
+ * @param {{file: string, reason: string}} finding - From {@link contentPage}'s
+ *   `addressFinding`.
+ * @returns {{file: string, severity: "error", message: string}} The diagnostic.
+ */
+export function addressDiagnostic(finding: {
+    file: string;
+    reason: string;
+}): {
+    file: string;
+    severity: "error";
+    message: string;
+};

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

@@ -155,7 +155,13 @@ export function deliverSiteFonts(config: object, out: string): {
  *   What the build found, and, when it found nothing that stops it, what was
  *   written, the pages it was written from and how a note rendered again
  *   becomes its page. `written` is `null` when a gate fired.
- * @throws {Error} When the site's settings or its cached menu cannot be read.
+ * With `site.inputs`, the local default-exported provider receives `{config}`
+ * and supplies the navigation plus text artifacts. All artifact paths are checked
+ * before replacing output; artifacts are then written after the renderer clears
+ * and writes the site, and included in `written.files`.
+ *
+ * @throws {Error} When the site's settings, cached menu or input provider fail,
+ *   or a provider artifact is unsafe or collides with builder-owned output.
  */
 export function buildPackageSite({ config, out, year, progress }: {
     config: object;
@@ -175,3 +181,16 @@ export function buildPackageSite({ config, out, year, progress }: {
  * icon stylesheets, the spoiler script, the icon font and the theme's images.
  */
 export const SITE_STATIC_DIR: string;
+export type SiteInputs = {
+    /**
+     * The selected menu.
+     */
+    navigation: import("./site-config.mjs").NavigationEntry[];
+    /**
+     * Text artifacts relative to the site's output.
+     */
+    files: Record<string, string>;
+};
+export type SiteInputsProvider = (options: {
+    config: import("../content-config.mjs").ContentBuildConfig;
+}) => SiteInputs | Promise<SiteInputs>;

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

@@ -214,8 +214,8 @@ export function prepareInlineSqlExpressions(db: any, sources: any): Promise<Map<
  *   surface publishes to.
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
- * @param {string} [opts.only] - One note file to give sections to; absent,
- *   every note.
+ * @param {string|Set<string>} [opts.only] - The note file, or files, to give
+ *   sections to; absent, every note.
  * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes, whose
  *   places, affiliations and works the lists take in.
  * @param {object} [opts.config] - The resolved configuration.
@@ -233,7 +233,7 @@ export function prepareInlineSqlExpressions(db: any, sources: any): Promise<Map<
  *   the derived lists alone.
  */
 export function generatedSectionsFor(db: object | undefined, records: object[], contentBase: string, { only, foreignIndex, config, derived: given, all, parsed }?: {
-    only?: string | undefined;
+    only?: string | Set<string> | undefined;
     foreignIndex?: Map<string, object> | undefined;
     config?: object | undefined;
     derived?: Map<string, Map<string, string>> | undefined;
@@ -351,11 +351,14 @@ export function cachedDependencies(config?: object): Promise<Array<{
  *   generated sections take in, where the caller holds them already; absent,
  *   they are read from the cache.
  * @param {import("./content-session.mjs").ContentSyntax} [opts.syntax] - Exact-text scanner projections.
+ * @param {string|Iterable<string>} [opts.only] - One note's file, or several:
+ *   answer their directives and give them their generated sections, and no
+ *   other note's. The queries still read the whole corpus.
  * @returns {Promise<Map<string, object[]>|undefined>} Results by note path,
  *   carrying `inline` and `pageLists` beside them, or nothing when the tree
  *   holds no such directive and no note is given a generated section.
  */
-export function prepareTreeSqlTables(contentBase: string, { config, skipDirectories, records, parsed, database, audience, foreignIndex, syntax, }?: {
+export function prepareTreeSqlTables(contentBase: string, { config, skipDirectories, records, parsed, database, audience, foreignIndex, syntax, only, }?: {
     config?: object | undefined;
     skipDirectories?: readonly string[] | undefined;
     records?: object[] | undefined;
@@ -367,6 +370,7 @@ export function prepareTreeSqlTables(contentBase: string, { config, skipDirector
     audience?: "all" | "public" | undefined;
     foreignIndex?: Map<string, object> | undefined;
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
+    only?: string | Iterable<string> | undefined;
 }): Promise<Map<string, object[]> | undefined>;
 /**
  * Prepare authored link-check tables in each source note's audience. Public