@heroiclands/package-build 22.4.4 → 22.4.5

package/engine/site-root.mjs

@@ -20,6 +20,18 @@
  * `_redirects` is written. One left beside the site by an earlier build is
  * removed rather than left to send every reader somewhere nothing publishes.
  *
+ * **And one directory inside the prefix, `pagefind/`.** Every package site
+ * ends the same way — Hugo renders into the output directory, this
+ * post-processes it there — so the search index is built in this step and
+ * every site gets one without each repository adding a dependency and a
+ * script. Pagefind indexes the rendered pages and writes `<package>/pagefind/`
+ * beside them, served at `/<package>/pagefind/` with the rest of the site;
+ * the theme loads it relative to the site's base URL like any other asset.
+ * `site.search: false` skips the step, and removes an index an earlier build
+ * left. What is indexed is whatever the theme rendered: the theme marks its
+ * own chrome `data-pagefind-ignore`, and this package's part is only to run
+ * the indexer over the result.
+ *
  * **One implementation, because it is one policy.** What is indexable is a
  * decision about the hosting rather than about any one package. Held in each
  * consumer it is the same file with one constant changed, which is a file that
@@ -31,6 +43,21 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import * as pagefind from "pagefind";
+
+import { formatDiagnostic } from "./diagnostics.mjs";
+
+/**
+ * The directory the search index is written to, inside the rendered site.
+ *
+ * Pagefind's own default, and the one its browser bundle derives the site's
+ * base URL from: `pagefind.js` at `/<package>/pagefind/pagefind.js` means
+ * every result's `url` is joined onto `/<package>/`, so nothing about the
+ * prefix is configured on either side.
+ *
+ * @type {string}
+ */
+export const SEARCH_DIR = "pagefind";
 
 /**
  * The namespace the routing layer derives a package's origin in.
@@ -89,23 +116,112 @@ export function headers() {
 }
 
 /**
- * Write `_headers` beside the rendered site, and remove any `_redirects`.
+ * What runs the search indexer over a rendered site.
+ *
+ * {@link indexSite} is the one the command uses; a test hands
+ * {@link writeSiteRoot} a stand-in, so the step's own contract — what it is
+ * given, when it runs, how its failure is reported — is checked without a
+ * binary.
+ *
+ * @callback SiteIndexer
+ * @param {{site: string, output: string}} where - The rendered site, and the
+ *   directory inside it the index is written to.
+ * @returns {Promise<{pages: number}>} How many pages were indexed.
+ */
+
+/**
+ * Build the search index of a rendered site with Pagefind.
+ *
+ * Pagefind's Node API drives the binary the `pagefind` package installs for
+ * the platform as an optional dependency, so there is nothing to put on a
+ * `PATH`. Three things it does not do on its own are done here, because each
+ * is a quiet failure otherwise:
+ *
+ * - A directory that is not there indexes as zero pages and no error, so the
+ *   site is checked first.
+ * - Zero pages from a directory that _is_ there means the pages were not
+ *   read — an empty index is deployable and finds nothing — so it is refused.
+ * - The binary missing is reported by the package as an install failure of
+ *   its own; it is rethrown naming the platform package to install.
+ *
+ * The output directory is emptied first, so an index of an earlier build's
+ * pages never survives beside the current one.
+ *
+ * @type {SiteIndexer}
+ */
+export async function indexSite({ site, output }) {
+    if (!fs.statSync(site, { throwIfNoEntry: false })?.isDirectory()) {
+        throw new Error(`${site} is not a directory, so there is nothing to index`);
+    }
+    fs.rmSync(output, { recursive: true, force: true });
+
+    let index;
+    try {
+        ({ index } = await pagefind.createIndex({ verbose: false }));
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // The package's own wording for "no binary resolved for this
+        // platform", the one failure of the step that is not the site's.
+        if (/Failed to install/.test(message)) {
+            const platform = process.platform === "win32" ? "windows" : process.platform;
+            throw new Error(
+                `the pagefind binary for ${platform}-${process.arch} is not installed — ` +
+                    `\`npm ci\` installs it as the optional dependency ` +
+                    `@pagefind/${platform}-${process.arch} of pagefind; on a platform it ` +
+                    `has no build for, set PAGEFIND_BINARY_PATH to a binary from ` +
+                    `https://github.com/Pagefind/pagefind/releases`,
+            );
+        }
+        throw err;
+    }
+    try {
+        const added = await index.addDirectory({ path: site });
+        if (added.errors.length) throw new Error(added.errors.join("; "));
+        const pages = added.page_count;
+        if (!pages) {
+            throw new Error(`no page under ${site} was indexed — the site holds no HTML`);
+        }
+        const written = await index.writeFiles({ outputPath: output });
+        if (written.errors.length) throw new Error(written.errors.join("; "));
+        return { pages };
+    } finally {
+        await pagefind.close();
+    }
+}
+
+/**
+ * Write `_headers` beside the rendered site, remove any `_redirects`, and
+ * index the site for search.
  *
  * The removal is part of owning the root: a `_redirects` this build did not
  * write is one an earlier build left, and Cloudflare Pages applies whatever
  * sits there. Left in place it would redirect the prefix root — the homepage —
- * to an address nothing publishes.
+ * to an address nothing publishes. The same holds for a `pagefind/` left by an
+ * earlier build when `search` is off: deployed, it is a working search over
+ * pages that may no longer exist, so it goes too.
+ *
+ * `_headers` is written before the index is built, so a failed index leaves
+ * the root files as they would be — the failure is the indexer's, reported as
+ * one finding naming the rendered site, and nothing else about the deployment
+ * is in doubt.
  *
  * @param {object} options - Options.
  * @param {string} options.pkg - The content package name, which is also the
  *   directory Hugo rendered into.
  * @param {string} options.out - The directory that is deployed.
- * @returns {{files: string[]}} The files written.
+ * @param {boolean} [options.search] - Whether to build the search index;
+ *   `site.search` in the configuration. Default `true`.
+ * @param {SiteIndexer} [options.indexer] - What builds it. Default
+ *   {@link indexSite}.
+ * @returns {Promise<{files: string[], search: {dir: string, pages: number}|null}>}
+ *   The files written, and the index — where it is and how many pages it
+ *   holds — or `null` when none was built.
  * @throws {Error} When no rendered site is there, which means the site build
  *   has not run and writing root files would publish a deployment with nothing
- *   under the prefix.
+ *   under the prefix; or, located at the rendered site, when the indexer
+ *   fails.
  */
-export function writeSiteRoot({ pkg, out }) {
+export async function writeSiteRoot({ pkg, out, search = true, indexer = indexSite }) {
     const root = path.resolve(out);
     const rendered = path.join(root, pkg);
     if (!fs.existsSync(path.join(rendered, "index.html"))) {
@@ -117,5 +233,30 @@ export function writeSiteRoot({ pkg, out }) {
     const file = path.join(root, "_headers");
     fs.writeFileSync(file, headers());
     fs.rmSync(path.join(root, "_redirects"), { force: true });
-    return { files: [file] };
+
+    const dir = path.join(rendered, SEARCH_DIR);
+    if (!search) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        return { files: [file], search: null };
+    }
+    let pages;
+    try {
+        ({ pages } = await indexer({ site: rendered, output: dir }));
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // A directory, so the locator is the file field alone: there is no
+        // line to name, and `1:1` would send a reader to the homepage's
+        // markup for a failure that is the indexer's.
+        throw Object.assign(
+            new Error(
+                formatDiagnostic({
+                    file: rendered,
+                    severity: "error",
+                    message: `search index: ${message}`,
+                }),
+            ),
+            { located: true, file: rendered },
+        );
+    }
+    return { files: [file], search: { dir, pages } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.4.4",
+    "version": "22.4.5",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -137,7 +137,7 @@
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",
         "classic-level": "^3.0.0",
-        "dotenv": "^17.2.3",
+        "dotenv": "^18.0.0",
         "eslint": "^10.10.0",
         "eslint-plugin-yml": "^3.8.1",
         "fflate": "^0.8.3",
@@ -148,6 +148,7 @@
         "loglevel-plugin-prefix": "^0.8.4",
         "markdown-it": "^15.0.0",
         "markdownlint-cli2": "^0.23.2",
+        "pagefind": "^1.5.2",
         "prettier": "^3.9.6",
         "smol-toml": "^1.7.0",
         "ssh2-sftp-client": "^12.1.1",

package/types/engine/index.d.mts

@@ -15,6 +15,12 @@ export * as derivedFields from "./derived-fields.mjs";
 export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
 export * as noteVocabulary from "./note-vocabulary.mjs";
+export * as placeRelations from "./place-relations.mjs";
+export * as mapPlaces from "./map-places.mjs";
+export * as mapLayout from "./map-layout.mjs";
+export * as mapDot from "./map-dot.mjs";
+export * as mapGraphviz from "./map-graphviz.mjs";
+export * as mapBuild from "./map-build.mjs";
 export * as systems from "./systems.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";

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

@@ -0,0 +1,78 @@
+/**
+ * Every place that states, or is named in, a border or a route — the places
+ * `--from all` draws.
+ *
+ * @param {Map<string, import("./map-places.mjs").MapPlace>} places - Every place.
+ * @returns {string[]} Shortcodes, sorted.
+ */
+export function relatedPlaces(places: Map<string, import("./map-places.mjs").MapPlace>): string[];
+/**
+ * Build the maps.
+ *
+ * @param {object} opts
+ * @param {import("./map-places.mjs").MapWorld} opts.world - The places, as
+ *   {@link module:engine/map-places.loadMapWorld} returns them.
+ * @param {string} opts.outDir - Where to write; created if absent.
+ * @param {boolean} [opts.tree] - Draw the containment tree.
+ * @param {string} [opts.root] - With `tree`, the subtree beneath this place.
+ * @param {string[]} [opts.from] - Draw the map from each of these places, or
+ *   from every related place for {@link FROM_ALL}.
+ * @param {boolean} [opts.travel] - Draw the whole route graph.
+ * @param {string} [opts.engine="dot"] - The tree's engine: `dot`, `twopi` or
+ *   `neato`. The map from a place is always `neato` with every node pinned,
+ *   and the route graph always `neato`.
+ * @param {string} [opts.rankdir="TB"] - The tree's rank direction, `dot` only.
+ * @param {number} [opts.nodesep] - The tree's `nodesep`, inches.
+ * @param {number} [opts.ranksep] - The tree's `ranksep`, inches.
+ * @param {number} [opts.scale=1] - Multiplies every node's size and font.
+ * @param {boolean} [opts.polities=true] - Whether the tree draws polities.
+ * @param {(engine: string) => string|undefined} [opts.locate] - How a GraphViz
+ *   engine's binary is found; the real lookup by default.
+ * @param {boolean} [opts.requireGraphviz=true] - Whether a missing engine is
+ *   an error. False, the `.dot` files are written, the renderings skipped,
+ *   and one warning returned.
+ * @returns {{written: string[], findings: Array<{file: string, line?: number,
+ *   column?: number, severity: "error"|"warning", message: string}>,
+ *   skipped: boolean}} What was written, what was found, and whether the
+ *   rendering was skipped for want of GraphViz.
+ * @throws {Error} When no mode is asked for, a named place is not one, or
+ *   GraphViz is required and absent.
+ */
+export function buildMaps({ world, outDir, tree, root, from, travel, engine, rankdir, nodesep, ranksep, scale, polities, locate, requireGraphviz, }: {
+    world: import("./map-places.mjs").MapWorld;
+    outDir: string;
+    tree?: boolean | undefined;
+    root?: string | undefined;
+    from?: string[] | undefined;
+    travel?: boolean | undefined;
+    engine?: string | undefined;
+    rankdir?: string | undefined;
+    nodesep?: number | undefined;
+    ranksep?: number | undefined;
+    scale?: number | undefined;
+    polities?: boolean | undefined;
+    locate?: ((engine: string) => string | undefined) | undefined;
+    requireGraphviz?: boolean | undefined;
+}): {
+    written: string[];
+    findings: Array<{
+        file: string;
+        line?: number;
+        column?: number;
+        severity: "error" | "warning";
+        message: string;
+    }>;
+    skipped: boolean;
+};
+/**
+ * The directory the maps land in, below a package's root.
+ *
+ * @type {string}
+ */
+export const MAP_DIR: string;
+/**
+ * The value of `--from` that means every place with a relation.
+ *
+ * @type {string}
+ */
+export const FROM_ALL: string;

package/types/engine/map-dot.d.mts

@@ -0,0 +1,130 @@
+/**
+ * A DOT double-quoted string.
+ *
+ * @param {unknown} value - The text.
+ * @returns {string} Quoted and escaped, newlines folded to spaces.
+ */
+export function dotString(value: unknown): string;
+/**
+ * The containment tree as DOT.
+ *
+ * With no `root`, every place, clustered by continent — a region parented
+ * directly on the world — and the places reaching no continent floating
+ * outside every cluster. With a `root`, the subtree beneath that place, in
+ * one cluster, the world drawn beside it only when the root is the world or
+ * a continent. Edges run child → parent, as `parents` states them. A polity
+ * is drawn dashed beside every region note in its directory, unless
+ * `polities` is false.
+ *
+ * @param {object} opts
+ * @param {Map<string, import("./map-places.mjs").MapPlace>} opts.places
+ * @param {import("./map-places.mjs").MapPolity[]} [opts.polities]
+ * @param {import("./map-places.mjs").Containment} opts.analysis
+ * @param {string} [opts.root] - Draw the subtree beneath this place.
+ * @param {string} [opts.title] - The drawing's title, defaulting to the
+ *   world's or the root's name.
+ * @param {string} [opts.engine="dot"] - `dot`, `twopi` or `neato`.
+ * @param {string} [opts.rankdir="TB"] - `dot` only.
+ * @param {number} [opts.nodesep] - Inches; defaults by scale.
+ * @param {number} [opts.ranksep] - Inches; defaults by engine and scale.
+ * @param {number} [opts.scale=1] - Multiplies every size.
+ * @param {boolean} [opts.drawPolities=true] - Whether to draw the polities.
+ * @returns {string} The DOT text.
+ */
+export function treeDot({ places, polities, analysis, root, title, engine, rankdir, nodesep, ranksep, scale, drawPolities, }: {
+    places: Map<string, import("./map-places.mjs").MapPlace>;
+    polities?: import("./map-places.mjs").MapPolity[] | undefined;
+    analysis: import("./map-places.mjs").Containment;
+    root?: string | undefined;
+    title?: string | undefined;
+    engine?: string | undefined;
+    rankdir?: string | undefined;
+    nodesep?: number | undefined;
+    ranksep?: number | undefined;
+    scale?: number | undefined;
+    drawPolities?: boolean | undefined;
+}): string;
+/**
+ * The map from a place as DOT, for `neato -n2`.
+ *
+ * Every node is pinned at the position the layout computed, so the engine
+ * only draws. The rings are circles pinned at the origin, drawn faintly,
+ * each labelled with its days marker at the top; the rim is one more. The
+ * centre is drawn in its `subType` style at full size, a neighbour at the
+ * layout's scale, and a second hop dimmer. A place beyond the horizon or
+ * with unknown days is a name at the rim, its label carrying its days or `?`.
+ * A border edge is dashed; every edge is labelled with its bearing and days.
+ *
+ * @param {ReturnType<typeof import("./map-layout.mjs").layoutFrom>} layout - The layout.
+ * @param {Map<string, import("./map-places.mjs").MapPlace>} places - Every place.
+ * @param {object} [opts]
+ * @param {number} [opts.scale=1] - Multiplies every size.
+ * @param {string} [opts.title] - Defaults to `From <name>`.
+ * @returns {string} The DOT text.
+ */
+export function fromDot(layout: ReturnType<typeof import("./map-layout.mjs").layoutFrom>, places: Map<string, import("./map-places.mjs").MapPlace>, { scale, title }?: {
+    scale?: number | undefined;
+    title?: string | undefined;
+}): string;
+/**
+ * The whole route graph as DOT, for `neato`.
+ *
+ * Undirected, one edge per pair, each asking the engine for a length from
+ * its days; the engine solves the positions. A border is dashed. Every node
+ * that takes part in a relation is drawn in its `subType` style.
+ *
+ * @param {ReturnType<typeof import("./map-layout.mjs").travelGraph>} graph - The graph.
+ * @param {Map<string, import("./map-places.mjs").MapPlace>} places - Every place.
+ * @param {object} [opts]
+ * @param {number} [opts.scale=1] - Multiplies every size.
+ * @param {string} [opts.title] - Defaults to `Routes`.
+ * @returns {string} The DOT text.
+ */
+export function travelDot(graph: ReturnType<typeof import("./map-layout.mjs").travelGraph>, places: Map<string, import("./map-places.mjs").MapPlace>, { scale, title }?: {
+    scale?: number | undefined;
+    title?: string | undefined;
+}): string;
+/**
+ * One row of the style table.
+ *
+ * @typedef {object} NodeStyle
+ * @property {string} shape
+ * @property {string} fill
+ * @property {string} border
+ * @property {number} fontsize
+ * @property {number} width - Inches, a minimum: a long label still grows the node.
+ * @property {number} height - Inches.
+ * @property {number} penwidth
+ * @property {string} extraStyle - `rounded`, `dashed`, or none.
+ */
+/**
+ * Shape, colour and size by `subType`, plus the synthetic `polity` row for
+ * the affiliation notes drawn beside their regions. The world is largest;
+ * regions large with a bold label; settlements small with a thin border;
+ * site, feature and structure between.
+ *
+ * @type {Readonly<Record<string, NodeStyle>>}
+ */
+export const STYLE: Readonly<Record<string, NodeStyle>>;
+/**
+ * One row of the style table.
+ */
+export type NodeStyle = {
+    shape: string;
+    fill: string;
+    border: string;
+    fontsize: number;
+    /**
+     * - Inches, a minimum: a long label still grows the node.
+     */
+    width: number;
+    /**
+     * - Inches.
+     */
+    height: number;
+    penwidth: number;
+    /**
+     * - `rounded`, `dashed`, or none.
+     */
+    extraStyle: string;
+};

package/types/engine/map-graphviz.d.mts

@@ -0,0 +1,61 @@
+/**
+ * Find a GraphViz engine's binary.
+ *
+ * `PATH` first, then the directories a package manager installs into, so a
+ * shell whose profile does not export Homebrew's directory still finds it.
+ * The result is a path to a file that exists; whether it runs is the render's
+ * business.
+ *
+ * @param {string} engine - One of {@link GRAPHVIZ_ENGINES}.
+ * @param {object} [opts]
+ * @param {Record<string, string|undefined>} [opts.env] - The environment to
+ *   read `PATH` from, defaulting to the process's.
+ * @param {readonly string[]} [opts.fallbacks] - The directories tried after
+ *   `PATH`, defaulting to the package managers' ones.
+ * @returns {string|undefined} The binary, or `undefined` when none is found.
+ * @throws {Error} When `engine` is not a GraphViz engine this command uses.
+ */
+export function findGraphviz(engine: string, { env, fallbacks }?: {
+    env?: Record<string, string | undefined> | undefined;
+    fallbacks?: readonly string[] | undefined;
+}): string | undefined;
+/**
+ * What to say when an engine is not installed: the name, and what installs
+ * it on the two platforms a contributor is likely to be on.
+ *
+ * @param {string} engine - The engine that was wanted.
+ * @returns {string} The message.
+ */
+export function graphvizMissingMessage(engine: string): string;
+/**
+ * Render a `.dot` file with a GraphViz engine.
+ *
+ * The engine is run over the file rather than fed the text, so the file the
+ * command keeps is exactly what was drawn. Warnings GraphViz prints — an
+ * unknown font, an overlapping label — are returned rather than swallowed,
+ * and a non-zero exit is an error naming the file.
+ *
+ * @param {string} dotPath - The `.dot` file.
+ * @param {string} outPath - Where to write the rendering.
+ * @param {object} opts
+ * @param {string} opts.binary - The engine's binary, from {@link findGraphviz}.
+ * @param {string} [opts.format="svg"] - The `-T` format.
+ * @param {string[]} [opts.args] - Further arguments, before the file.
+ * @returns {{warnings: string}} What the engine printed on stderr.
+ * @throws {Error} When the engine exits non-zero or cannot be run.
+ */
+export function renderDot(dotPath: string, outPath: string, { binary, format, args }: {
+    binary: string;
+    format?: string | undefined;
+    args?: string[] | undefined;
+}): {
+    warnings: string;
+};
+/**
+ * The layout engines the map command may ask for. `dot` draws a tree by
+ * rank, `twopi` the same tree radially, `neato` a graph by its edge lengths —
+ * and, with every node pinned, the map from a place.
+ *
+ * @type {readonly string[]}
+ */
+export const GRAPHVIZ_ENGINES: readonly string[];