@heroiclands/package-build 22.4.4 → 22.4.6

package/types/engine/place-relations.d.mts

@@ -0,0 +1,95 @@
+/**
+ * The bearing the other end of a relation states, or `undefined` for a value
+ * that is not a bearing.
+ *
+ * @param {unknown} bearing - A bearing.
+ * @returns {string|undefined} The one four steps around the compass.
+ */
+export function oppositeBearing(bearing: unknown): string | undefined;
+/**
+ * Check a place note's `data.borders`.
+ *
+ * Every `to` is a shortcode a place declares, every `bearing` is one of the
+ * eight, no pair is listed twice, no target is the note's own parent or child,
+ * and the other end states the pair back at the opposite bearing — a missing
+ * reciprocal is a warning naming both notes, a wrong one an error.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {object} [opts]
+ * @param {object} [opts.index] - The link index, for resolving `to`.
+ * @returns {object[]} Findings.
+ */
+export function checkBorders(note: object, { index }?: {
+    index?: object | undefined;
+}): object[];
+/**
+ * Check a place note's `data.routes`.
+ *
+ * As {@link checkBorders}, plus: `mode` and `days` are required and from
+ * their sets, `terrain` is from the registry and crossable by the mode, a pair
+ * appears once per mode, and the other end states the pair back by the same
+ * mode, at the opposite bearing, with the same days.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {object} [opts]
+ * @param {object} [opts.index] - The link index, for resolving `to`.
+ * @returns {object[]} Findings.
+ */
+export function checkRoutes(note: object, { index }?: {
+    index?: object | undefined;
+}): object[];
+/**
+ * The eight compass bearings, clockwise from north.
+ *
+ * Where a neighbour or a destination lies from the place stating it. The
+ * order is load-bearing: {@link oppositeBearing} reads four steps around it.
+ *
+ * @type {readonly string[]}
+ */
+export const BEARINGS: readonly string[];
+/**
+ * The modes a route is travelled by: `land`, `boat` on a river or a lake,
+ * `ship` on open sea.
+ *
+ * @type {readonly string[]}
+ */
+export const ROUTE_MODES: readonly string[];
+/**
+ * The days markers a route may state.
+ *
+ * Each is "about this, under normal conditions": `10`, `20` and `30` are one,
+ * two and three ten-day weeks, `180` is many months, `360` is "who knows".
+ *
+ * @type {readonly number[]}
+ */
+export const TRAVEL_DAYS: readonly number[];
+/**
+ * The terrain registry, each terrain naming the modes that cross it.
+ *
+ * A land terrain is crossed by land alone; open sea by ship; a river or a lake
+ * by boat; a coast by all three, because a coast road and a coasting voyage
+ * are both journeys along it.
+ *
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const TERRAIN_MODES: Readonly<Record<string, readonly string[]>>;
+/**
+ * The terrain names, in registry order — the closed set a `terrain` list
+ * draws from.
+ *
+ * @type {readonly string[]}
+ */
+export const TERRAINS: readonly string[];
+/**
+ * The keys a `borders` entry may carry. Both are required.
+ *
+ * @type {readonly string[]}
+ */
+export const BORDER_KEYS: readonly string[];
+/**
+ * The keys a `routes` entry may carry. `to`, `bearing`, `mode` and `days` are
+ * required; `terrain` and `leagues` are optional.
+ *
+ * @type {readonly string[]}
+ */
+export const ROUTE_KEYS: readonly string[];

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

@@ -139,7 +139,7 @@ export const HUGO_CONTENT: "build/hugo/content";
  * The directory that is deployed, relative to the repository root.
  *
  * Hugo renders into `<DEPLOY_ROOT>/<contentPackage>/`; `package-build
- * site-root` writes `_headers` and `_redirects` beside it.
+ * site-root` writes `_headers` beside it and the search index inside it.
  */
 export const DEPLOY_ROOT: "build/site";
 /** The npm package the shared theme arrives as. */

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

@@ -27,29 +27,67 @@ export function noindexHeaders(): string[];
  * @returns {string} The file's contents.
  */
 export function headers(): string;
+export function indexSite(where: {
+    site: string;
+    output: string;
+}): Promise<{
+    pages: number;
+}>;
 /**
- * Write `_headers` beside the rendered site, and remove any `_redirects`.
+ * 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 function writeSiteRoot({ pkg, out, search, indexer }: {
     pkg: string;
     out: string;
-}): {
+    search?: boolean | undefined;
+    indexer?: SiteIndexer | undefined;
+}): Promise<{
     files: string[];
-};
+    search: {
+        dir: string;
+        pages: number;
+    } | null;
+}>;
+/**
+ * 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: string;
 /**
  * The namespace the routing layer derives a package's origin in.
  *
@@ -60,3 +98,17 @@ export function writeSiteRoot({ pkg, out }: {
  * @type {string}
  */
 export const ORIGIN_SUFFIX: string;
+/**
+ * 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.
+ */
+export type SiteIndexer = (where: {
+    site: string;
+    output: string;
+}) => Promise<{
+    pages: number;
+}>;