@heroiclands/package-build 23.13.0 → 24.0.1

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

@@ -1,14 +1,24 @@
 /**
- * Render one complete buffer with no configuration, index, filesystem or database.
+ * Render one complete buffer.
+ *
+ * Without `index` the buffer is rendered with no configuration, content index,
+ * filesystem or database: wikilinks, spans and expressions show as highlighted
+ * authored source. With `index` the buffer is expanded as the website expands
+ * a page and rendered as every target renders it, so links, embeds, marked
+ * text, icons and figure numbers read as they will on the page; only what a
+ * buffer cannot answer, such as a query, stays highlighted source.
+ *
  * @param {string} text - Markdown, optionally beginning with YAML frontmatter.
- * @param {{dark?: boolean, infobox?: boolean, file?: string, currentDate?: string}} [options] - Explicit palette, profile visibility, diagnostic filename and neutral current date (default "720.1").
+ * @param {{dark?: boolean, infobox?: boolean, file?: string, currentDate?: string,
+ *   index?: import("./preview-index.mjs").PreviewIndex}} [options] - Explicit palette, profile visibility, diagnostic filename, neutral current date (default "720.1") and the content index, from {@link module:engine/preview-index.previewIndex}.
  * @returns {{ok: boolean, html: string, frontmatter: object, findings: object[]}} HTML and metadata with locally calculable ages; unavailable ages remain absent or null.
  */
-export function renderPreview(text: string, { dark, infobox, file, currentDate }?: {
+export function renderPreview(text: string, { dark, infobox, file, currentDate, index }?: {
     dark?: boolean;
     infobox?: boolean;
     file?: string;
     currentDate?: string;
+    index?: import("./preview-index.mjs").PreviewIndex;
 }): {
     ok: boolean;
     html: string;
@@ -23,19 +33,5 @@ export function renderPreview(text: string, { dark, infobox, file, currentDate }
 export function readPreviewCurrentDate(root: string): Promise<string>;
 /** Both explicit palettes, scoped to the preview container. */
 export function previewStyles(): string;
-/** 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";
-}>;
+export { PREVIEW_HELPERS };
+import { PREVIEW_HELPERS } from "./preview-source.mjs";

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

@@ -0,0 +1,76 @@
+/**
+ * The internal targets a page links.
+ *
+ * @param {string} html - A rendered page.
+ * @param {string} from - The page's own address, beginning with `/`.
+ * @param {string} base - The site's base path, beginning and ending with `/`.
+ * @returns {string[]} Absolute paths inside the base, without fragment or query.
+ */
+export function internalLinks(html: string, from: string, base: string): string[];
+/**
+ * The address a link to a file names a page by: `…/index.html` is its
+ * directory, and a bare directory ends in a slash.
+ *
+ * @param {string} pathname - An absolute path.
+ * @returns {string} The page address it would be keyed by.
+ */
+export function pageAddress(pathname: string): string;
+/**
+ * The pages reachable from the homepage.
+ *
+ * @param {object} options - The inputs.
+ * @param {string} options.base - The site's base path, beginning and ending
+ *   with `/`; the homepage is at the base.
+ * @param {(url: string) => string|undefined} options.html - A page's rendered
+ *   HTML by its address, or `undefined` where the site has no such page.
+ * @param {(pathname: string) => readonly string[]} [options.expand] - The page
+ *   addresses a linked non-page file, such as a feed, lists.
+ * @returns {Set<string>} The address of every reachable page, the homepage
+ *   included.
+ */
+export function reachablePages({ base, html, expand }: {
+    base: string;
+    html: (url: string) => string | undefined;
+    expand?: ((pathname: string) => readonly string[]) | undefined;
+}): Set<string>;
+/**
+ * The page addresses an Atom feed lists, as paths.
+ *
+ * @param {string} xml - The feed.
+ * @returns {string[]} The `href` of every `<link>` that is an absolute URL,
+ *   as its path.
+ */
+export function feedPaths(xml: string): string[];
+/**
+ * A page body split at {@link GENERATED_MARK}.
+ *
+ * @param {string} html - A page body.
+ * @returns {{authored: string, generated: string}} The author's text, and the
+ *   generated sections after it, `""` where there are none.
+ */
+export function splitContent(html: string): {
+    authored: string;
+    generated: string;
+};
+/**
+ * Generated sections with the entries that lead outside a set of pages taken
+ * out.
+ *
+ * An entry is a list item, a table row, or a link in a paragraph's comma
+ * separated run; a paragraph, list or table left with no entry goes, and so
+ * does a section left with nothing under its heading. A link to anything that
+ * is not a page of the site is kept, and so is text that was never a link.
+ *
+ * @param {string} html - The generated sections, rendered.
+ * @param {(href: string) => boolean} outside - Whether an `href` names a page
+ *   of the site that is not reachable.
+ * @returns {string} The sections, or `""` when nothing is left.
+ */
+export function pruneGenerated(html: string, outside: (href: string) => boolean): string;
+/**
+ * The comment that separates a page's authored text from the sections the
+ * build generated after it, in the HTML the renderer writes.
+ *
+ * @type {string}
+ */
+export const GENERATED_MARK: string;

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

@@ -0,0 +1,173 @@
+/**
+ * Pages in the order a reader walks them: by `weight`, lightest first and an
+ * unweighted page last; then newest first by `date`; then by title; then by
+ * address. A page's own `weight` and `date` are read before its `params`'.
+ *
+ * @template {{title?: string, url: string, date?: unknown, weight?: number, params?: object}} T
+ * @param {readonly T[]} pages - The pages.
+ * @returns {T[]} A sorted copy.
+ */
+export function siteOrder<T extends {
+    title?: string;
+    url: string;
+    date?: unknown;
+    weight?: number;
+    params?: object;
+}>(pages: readonly T[]): T[];
+/**
+ * Every page of a site: the pages it is given, with their siblings, and the
+ * listings derived from them.
+ *
+ * @param {object} site - The site, as {@link writeSite} takes it.
+ * @param {readonly object[]} pages - The home page, the regular pages and any
+ *   authored section pages.
+ * @returns {object[]} Every page, home first, then the regular pages, the
+ *   sections, and the tag pages.
+ */
+export function siteTree(site: object, pages: readonly object[]): object[];
+/**
+ * Write the files the layouts link: the theme's own, and the code stylesheet.
+ *
+ * @param {string} out - The directory the site is written to.
+ * @param {string} [staticDir] - The theme's own files.
+ * @returns {string[]} The files the theme generates, each written. The theme's
+ *   own files are copied as a tree and not listed.
+ */
+export function writeThemeFiles(out: string, staticDir?: string): string[];
+/**
+ * Draw a site and write it.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.site - The site, as
+ *   {@link module:engine/site-theme.createSiteTheme} takes it, with `tagPages`,
+ *   `feed` and `sitemaps` as the module description sets out. `pages` and
+ *   `pageExists` are filled in here.
+ * @param {readonly object[]} options.pages - The home page, the regular pages
+ *   and any authored section pages, each as a layout is given it.
+ * @param {string} options.out - The directory written to. Emptied first.
+ * @param {(finding: import("./site-theme.mjs").Finding) => void} [options.report] -
+ *   Receives each finding the layouts make.
+ * @param {string} [options.staticDir] - The theme's own files, copied first.
+ * @param {ReadonlySet<string>} [options.only] - The addresses of the pages to
+ *   draw again into a site already written. Nothing else is touched.
+ * @returns {{files: string[], pages: string[], reachable: string[],
+ *   findings: object[]}} Every file written, the address of every page, the
+ *   address of each page reachable from the homepage, and the layouts' findings.
+ * @throws {Error} When a page's address is outside the site, or a site served
+ *   under a path asks for a sitemap index.
+ */
+export function writeSite({ site, pages, out, report, staticDir, only }: {
+    site: object;
+    pages: readonly object[];
+    out: string;
+    report?: ((finding: import("./site-theme.mjs").Finding) => void) | undefined;
+    staticDir?: string | undefined;
+    only?: ReadonlySet<string> | undefined;
+}): {
+    files: string[];
+    pages: string[];
+    reachable: string[];
+    findings: object[];
+};
+/**
+ * A package's pages, from its site build.
+ *
+ * Each body is rendered by the `web` renderer from the markdown the build
+ * expanded, and each page carries what it tells the search; see
+ * {@link module:engine/site-search}. The site carries what the configuration
+ * asks for: `site.tags` as `tagPages`, `site.feed` as the feed's section, each
+ * package of `site.sitemaps` as its sitemap's address on the site's origin,
+ * and each of `site.mergeIndexes` as the path of its search bundle.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @param {object} options.built - What `buildSite` returned with `write: false`.
+ * @param {{baseURL: string, title: string, params: object}} options.settings -
+ *   From {@link module:engine/site-config.siteSettings}.
+ * @param {readonly {name: string, url: string, children?: object[]}[]} [options.navigation] -
+ *   The menu.
+ * @param {number} [options.year] - The year the footer states.
+ * @returns {{site: object, pages: object[], pageOf: (entry: object) => object}}
+ *   What {@link writeSite} is given, and how one note the build rendered again
+ *   becomes its page.
+ */
+export function packageSite({ config, built, settings, navigation, year }: {
+    config: object;
+    built: object;
+    settings: {
+        baseURL: string;
+        title: string;
+        params: object;
+    };
+    navigation?: readonly {
+        name: string;
+        url: string;
+        children?: object[];
+    }[] | undefined;
+    year?: number | undefined;
+}): {
+    site: object;
+    pages: object[];
+    pageOf: (entry: object) => object;
+};
+/**
+ * The directory a package's site is written to: its base path under the
+ * deployed root, so a site served at `/` is written at the root itself.
+ *
+ * @param {object} config - The resolved configuration.
+ * @param {string} root - The deployed root.
+ * @returns {string} The directory.
+ */
+export function siteDirectory(config: object, root: string): string;
+/**
+ * Copy the script fonts the site's pages set their marked text in.
+ *
+ * @param {object} config - The resolved configuration.
+ * @param {string} out - The directory the site is written to.
+ * @returns {{findings: object[], count: number, dest?: string}} What checking
+ *   the installed fonts found, and how many files were copied where. Nothing is
+ *   copied when there is a finding, or when the package sets no script.
+ */
+export function deliverSiteFonts(config: object, out: string): {
+    findings: object[];
+    count: number;
+    dest?: string;
+};
+/**
+ * Build a package's site from its content tree and write it.
+ *
+ * The site's address, title and menu are read before the tree is, so a site
+ * that cannot be described fails before anything is built. A gate that fires
+ * stops the build before anything is written; a note in error is written as
+ * its page shows it, with the finding in what is returned, which
+ * `siteBuildFailed` reads.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @param {string} options.out - The directory the site is written to, which
+ *   is the package's own directory under the deployed root.
+ * @param {number} [options.year] - The year the footer states.
+ * @returns {Promise<{built: object, written: object|null, fonts: object|null,
+ *   site?: object, pages?: object[], pageOf?: (entry: object) => object}>}
+ *   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.
+ */
+export function buildPackageSite({ config, out, year }: {
+    config: object;
+    out: string;
+    year?: number | undefined;
+}): Promise<{
+    built: object;
+    written: object | null;
+    fonts: object | null;
+    site?: object;
+    pages?: object[];
+    pageOf?: (entry: object) => object;
+}>;
+/**
+ * The files the layouts link that the theme ships as they are: the site and
+ * icon stylesheets, the spoiler script, the icon font and the theme's images.
+ */
+export const SITE_STATIC_DIR: string;

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

@@ -27,17 +27,22 @@ export function noindexHeaders(): string[];
  * that names their version, so a year's lifetime never serves a stale file.
  *
  * @param {object} [options] - Options.
- * @param {string} [options.pkg] - The content package, which is the prefix.
+ * @param {string} [options.pkg] - The content package, whose site is served at
+ *   `/<pkg>/` unless `base` says otherwise.
+ * @param {string} [options.base] - The path the site is served at, beginning
+ *   and ending with `/`.
  * @param {boolean} [options.fonts] - Whether the site carries the fonts.
  * @returns {string} The file's contents.
  */
-export function headers({ pkg, fonts }?: {
+export function headers({ pkg, base, fonts }?: {
     pkg?: string | undefined;
+    base?: string | undefined;
     fonts?: boolean | undefined;
 }): string;
 export function indexSite(where: {
     site: string;
     output: string;
+    base?: string;
 }): Promise<{
     pages: number;
 }>;
@@ -59,7 +64,10 @@ export function indexSite(where: {
  *
  * @param {object} options - Options.
  * @param {string} options.pkg - The content package name, which is also the
- *   directory Hugo rendered into.
+ *   directory the site is rendered into unless `base` says otherwise.
+ * @param {string} [options.base] - The path the site is served at, beginning
+ *   and ending with `/`; the site is rendered into that path under `out`, so
+ *   a site served at `/` is rendered at `out` itself.
  * @param {string} options.out - The directory that is deployed.
  * @param {boolean} [options.search] - Whether to build the search index;
  *   `site.search` in the configuration. Default `true`.
@@ -73,8 +81,9 @@ export function indexSite(where: {
  *   under the prefix; or, located at the rendered site, when the indexer
  *   fails.
  */
-export function writeSiteRoot({ pkg, out, search, indexer }: {
+export function writeSiteRoot({ pkg, base, out, search, indexer }: {
     pkg: string;
+    base?: string | undefined;
     out: string;
     search?: boolean | undefined;
     indexer?: SiteIndexer | undefined;
@@ -117,6 +126,7 @@ export const ORIGIN_SUFFIX: string;
 export type SiteIndexer = (where: {
     site: string;
     output: string;
+    base?: string;
 }) => Promise<{
     pages: number;
 }>;

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

@@ -0,0 +1,54 @@
+/**
+ * The continents and regions every place lies in.
+ *
+ * @param {Map<string, {shortcode: string, name: string, subType?: string, parents: string[]}>} places -
+ *   Every place, by shortcode, as {@link module:engine/map-places.mapWorld} reads them.
+ * @returns {(shortcodes: Iterable<string>) => {continents: string[], regions: string[]}}
+ *   The names of the continents and the outermost regions the given places lie
+ *   in, each sorted.
+ */
+export function placeGeography(places: Map<string, {
+    shortcode: string;
+    name: string;
+    subType?: string;
+    parents: string[];
+}>): (shortcodes: Iterable<string>) => {
+    continents: string[];
+    regions: string[];
+};
+/**
+ * The places a note lies in: itself for a place, its `homes` and its
+ * `locations` otherwise.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @returns {string[]} Shortcodes, lower case.
+ */
+export function notePlaces(fm: object): string[];
+/**
+ * What a note's page tells the search.
+ *
+ * @param {object} fm - The page's frontmatter: the note's, with its `package`.
+ * @param {object} options - What the values resolve against.
+ * @param {(shortcodes: Iterable<string>) => {continents: string[], regions: string[]}} options.geography -
+ *   From {@link placeGeography}.
+ * @param {object} [options.index] - The site's address index, which names the
+ *   culture `data.culture` names.
+ * @returns {{filters: Array<{name: string, values: string[]}>, names: string[]}}
+ *   Each filter with a value, in {@link SEARCH_FILTERS} order, and the names a
+ *   search weights.
+ */
+export function searchMetadata(fm: object, { geography, index }: {
+    geography: (shortcodes: Iterable<string>) => {
+        continents: string[];
+        regions: string[];
+    };
+    index?: object | undefined;
+}): {
+    filters: Array<{
+        name: string;
+        values: string[];
+    }>;
+    names: string[];
+};
+/** The filters a note's page carries, in the order a reader is offered them. */
+export const SEARCH_FILTERS: readonly string[];

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

@@ -0,0 +1,44 @@
+/**
+ * Serve a package's site, and keep it current.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @param {string} options.out - The site's directory under the deployed
+ *   root, which the site is written to.
+ * @param {string} [options.root] - The deployed root, which is served. The
+ *   directory above `out` by default; `out` itself for a site served at `/`.
+ * @param {string} [options.host] - The address to listen on.
+ * @param {number} [options.port] - The port; `0` takes any free one.
+ * @param {boolean} [options.search] - Build the search index after the first
+ *   build, where the site has one.
+ * @param {number} [options.year] - The year the footer states.
+ * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown}) => void} [options.report] -
+ *   Told of each build: `built` for a whole build, `page` for one note's page,
+ *   `theme` for the theme, `failed` with what the build found, `error` with
+ *   what it threw.
+ * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>}>}
+ *   The address of the site's home page, how to stop serving, and a promise
+ *   for the moment every change seen so far has been written.
+ */
+export function serveSite({ config, out, root, host, port, search, year, report, }: {
+    config: object;
+    out: string;
+    root?: string | undefined;
+    host?: string | undefined;
+    port?: number | undefined;
+    search?: boolean | undefined;
+    year?: number | undefined;
+    report?: ((event: {
+        kind: string;
+        built?: object;
+        files?: string[];
+        findings?: object[];
+        error?: unknown;
+    }) => void) | undefined;
+}): Promise<{
+    url: string;
+    close: () => Promise<void>;
+    settled: () => Promise<void>;
+}>;
+/** The address a served page listens on for the server's reloads. */
+export const RELOAD_PATH: "/__package-build/reload";

package/types/engine/site-theme-banner.d.mts

@@ -0,0 +1,51 @@
+/**
+ * The banner data the theme ships.
+ *
+ * @returns {{banners: object, kinds: object}} The inventory and the kind mapping.
+ */
+export function shippedBannerData(): {
+    banners: object;
+    kinds: object;
+};
+/**
+ * The address of a page's banner.
+ *
+ * @param {object} site - The site: `params.cdnBaseURL` and `basePath`.
+ * @param {object} fields - What the page states.
+ * @param {object} [fields.data] - The page's `data`, read for the resolved `banner`.
+ * @param {unknown} [fields.banner] - The hand-authored `banner` value.
+ * @param {string} [fields.type] - The note `type`.
+ * @param {string} [fields.subType] - The note `subType`.
+ * @param {string} [fields.category] - The page's `category`.
+ * @param {string} [fields.subtype] - The name to default to when no `type` is given.
+ * @param {string} [fields.context] - The page address, named in a report.
+ * @param {object} [options] - Options.
+ * @param {{banners: object, kinds: object}} [options.data] - The inventory and the
+ *   kind mapping. The shipped ones by default.
+ * @param {(finding: {severity: string, message: string, page?: string}) => void} [options.report] -
+ *   Receives each name that misses the inventory, once.
+ * @param {Set<string>} [options.reported] - The names already reported.
+ * @returns {string} The address, or `""` when the page has no banner.
+ */
+export function bannerUrl(site: object, fields: {
+    data?: object | undefined;
+    banner?: unknown;
+    type?: string | undefined;
+    subType?: string | undefined;
+    category?: string | undefined;
+    subtype?: string | undefined;
+    context?: string | undefined;
+}, { data, report, reported }?: {
+    data?: {
+        banners: object;
+        kinds: object;
+    } | undefined;
+    report?: ((finding: {
+        severity: string;
+        message: string;
+        page?: string;
+    }) => void) | undefined;
+    reported?: Set<string> | undefined;
+}): string;
+/** The directory holding the banner inventory and the kind mapping. */
+export const BANNER_DATA_DIR: string;

package/types/engine/site-theme-urls.d.mts

@@ -0,0 +1,60 @@
+/** Whether an address names a host: `http://`, `https://` or `//`. */
+export function isAbsoluteUrl(url: any): boolean;
+/**
+ * The path a site is served under, with a leading and a trailing slash.
+ *
+ * @param {object} site - The site; `baseURL` is its address.
+ * @returns {string} `/` for a site at its origin's root, `/thalorna/` for one under a prefix.
+ */
+export function basePath(site: object): string;
+/**
+ * A path inside the site, under its base path.
+ *
+ * A leading slash is dropped first: it would otherwise read as "from the
+ * origin" and leave the base path off.
+ *
+ * @param {object} site - The site.
+ * @param {string} [target] - The path; empty for the site's root.
+ * @returns {string} The address.
+ */
+export function relUrl(site: object, target?: string): string;
+/**
+ * An asset path, resolved against the site's asset host.
+ *
+ * An absolute address is returned as written. Otherwise the path is joined onto
+ * `params.cdnBaseURL`, and with none set it is a path inside the site.
+ *
+ * @param {object} site - The site; `params.cdnBaseURL` is the asset root.
+ * @param {string} target - The asset path.
+ * @returns {string} The address.
+ */
+export function cdnUrl(site: object, target: string): string;
+/**
+ * A link a consuming site supplied, resolved against the site it is rendered on.
+ *
+ * An absolute address, a fragment and a query are returned as written; anything
+ * else is a path inside the site.
+ *
+ * @param {object} site - The site.
+ * @param {string} [url] - The link; empty for the site's root.
+ * @returns {string} The address.
+ */
+export function siteUrl(site: object, url?: string): string;
+/**
+ * A link from a page's data, with a scheme that could run script refused.
+ *
+ * @param {unknown} url - The link as the data states it.
+ * @returns {string} The link, or `#` when its scheme is not one a reader should follow.
+ */
+export function safeUrl(url: unknown): string;
+/**
+ * The address of a tag's listing page.
+ *
+ * One function writes it for the link in a page's tag row and for the page the
+ * site build writes, so the two cannot disagree.
+ *
+ * @param {object} site - The site.
+ * @param {string} tag - The tag.
+ * @returns {string} The address.
+ */
+export function tagUrl(site: object, tag: string): string;