@heroiclands/package-build 22.4.3 → 22.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.4.3",
+    "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/changelog-lint.d.mts

@@ -48,13 +48,15 @@ export function topLevelBullets(text: string, codeLines: Set<number>): Array<{
  * {@link topLevelBullets}, where a bullet marker *is* the top-level
  * construct — a `-` bullet at column 0 belongs to whatever block is
  * already open, since a label's bullets sit unindented directly under it.
- * Any other column-0 line (plain prose with no label, a bullet with no
- * block open yet) starts the one "lead" block (`label: null`) a changeset
- * with no category writes — the case `changelog group` sorts first and
- * `check` never flags. Nested detail — a wrapped line, a bullet's own
- * continuation — stays indented and belongs to whatever it follows.
- * `changelog group` folds same-label blocks together; `check` warns when a
- * block's label is not in the declared vocabulary.
+ * A plain column-0 line that is neither a label nor a bullet continues
+ * whatever block is open, because Prettier's `proseWrap` puts every line of
+ * a hard-wrapped paragraph at column 0 — it starts a new "lead" block
+ * (`label: null`) only at a paragraph boundary, the start of the section or
+ * a line right after a blank one, which is the case `changelog group`
+ * sorts first and `check` never flags. A blank line never closes a block by
+ * itself; it only ends the run of continuation lines a following column-0
+ * line can attach to. `changelog group` folds same-label blocks together;
+ * `check` warns when a block's label is not in the declared vocabulary.
  *
  * @param {string} text - Section text.
  * @param {Set<number>} codeLines - Lines inside a code region, from

package/types/engine/homepage.d.mts

@@ -148,15 +148,22 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  * redirect stub at each one. The field is retired and refused before a
  * build reaches here, which makes this a guard rather than a working path.
  *
+ * `related` is derived like every other page's — what links to the homepage
+ * is a fact about the rest of the tree — so an authored value is dropped and
+ * the caller's block, where it has one, is written in its place.
+ *
  * @param {object} fm - The note's frontmatter.
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
+ * @param {object} [options.related] - The homepage's backlinks and mentions,
+ *   where the site build found either.
  * @returns {object} The frontmatter to write.
  */
-export function homepageFrontmatter(fm: object, { contentPackage, title }: {
+export function homepageFrontmatter(fm: object, { contentPackage, title, related }: {
     contentPackage: string;
     title: string;
+    related?: object | undefined;
 }): object;
 /**
  * Every address a homepage carries: the markdown links in its body.

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[];