@heroiclands/package-build 22.4.3 → 22.4.5

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/related-pages.d.mts

@@ -0,0 +1,70 @@
+/**
+ * Inverts a link graph into each page's backlinks and mentions.
+ *
+ * An edge is `(source URL, target URL)`, and a URL that is not in `entries` is
+ * not a page of this site, so an edge touching one is dropped. A self-link says
+ * nothing a reader is not already looking at, and a page that links another
+ * three times is connected to it once, so both collapse.
+ *
+ * The result holds only pages with at least one connection, so the caller can
+ * write nothing on a page with none — the theme's silent-disappear convention,
+ * kept at the source rather than papered over with an empty block.
+ *
+ * @param {Iterable<readonly [string, string]>} edges - Every resolved link, as
+ *   the source page's URL and the target page's.
+ * @param {ReadonlyMap<string, RelatedEntry>} entries - Every page of this
+ *   site, keyed by URL.
+ * @returns {Map<string, Related>} URL → the page's `related` block, both lists
+ *   sorted, for every page with at least one entry in either.
+ */
+export function relatedPages(edges: Iterable<readonly [string, string]>, entries: ReadonlyMap<string, RelatedEntry>): Map<string, Related>;
+/**
+ * The pages a homepage's body links to, as URLs.
+ *
+ * A homepage is published verbatim — no wikilink on it resolves, and its links
+ * are ordinary markdown the browser resolves against the page's own address,
+ * which is the package root. So its edges are read the same way: each target
+ * resolved against `base`, the way a browser would. A package-relative
+ * `being-x/`, a root-relative `/pkg/being-x/` and a `./being-x/#anchor` all
+ * name the same page; a bare `#anchor` names the homepage itself.
+ *
+ * A link that names a host or a scheme leaves the site, whatever path it
+ * carries, and yields nothing: the site's own pages are addressed without one.
+ *
+ * @param {string} body - The homepage's markdown body.
+ * @param {string} base - Where the package is served — the homepage's own URL.
+ * @returns {string[]} The targets' URLs, in body order, repeats included.
+ */
+export function homepageLinkTargets(body: string, base: string): string[];
+/**
+ * One entry in a `related` list — the page a reader is pointed at.
+ */
+export type RelatedEntry = {
+    /**
+     * The page's published title.
+     */
+    title: string;
+    /**
+     * `<base><slug>/` — the page's address as every href
+     * this build renders composes it, never the
+     * site-root-relative form the page states for itself.
+     */
+    url: string;
+    /**
+     * The note's `type`, which the theme groups by.
+     */
+    type: string;
+};
+/**
+ * The `related` block one page publishes.
+ */
+export type Related = {
+    /**
+     * Pages that link to this one.
+     */
+    backlinks: RelatedEntry[];
+    /**
+     * Pages this one links to.
+     */
+    mentions: RelatedEntry[];
+};

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

@@ -65,14 +65,27 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * states no `url` — the home kind has none to state — and the mount below it
  * holds pages and nothing else, so this is the only `_index.md` in the tree.
  *
+ * **Verbatim, but not unconnected.** The homepage is a page like any other on
+ * both sides of the link graph: a content page reaches it through
+ * `[[homepage-root|Text]]`, and its own markdown links name content pages. So
+ * it carries the same `related` block every content page does — handed in by
+ * the caller, since the graph is read off the content render and homepage-only
+ * mode has none.
+ *
  * @param {string} outRoot - The package's site root — the content mount's
  *   root, `build/hugo/content`, one level above the mount itself.
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
+ * @param {object} [options] - Options.
+ * @param {import("./related-pages.mjs").Related} [options.related] - The
+ *   homepage's backlinks and mentions. Absent where nothing connects to it,
+ *   and in homepage-only mode, where no link resolves.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot: string, pages: readonly object[], config: object): number;
+export function writeHomepages(outRoot: string, pages: readonly object[], config: object, { related }?: {
+    related?: import("./related-pages.mjs").Related | undefined;
+}): number;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -159,6 +172,12 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * 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 the
+ * way `aliases` is, and {@link renderPages} writes 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
@@ -210,10 +229,23 @@ export function pageDestination(page: object): string;
  *    touches, so the repository's own rewrite runs before the shared one
  *    rather than replacing it.
  *
+ * **Every page is rendered before any is written.** What links *to* a page is
+ * known only once every other page has resolved, and it is written into the
+ * page's own front matter, so the render is one pass over the tree and the
+ * write is a second — with the link graph read off the first, at the one
+ * point the resolver answers, and inverted once between them. Nothing is
+ * resolved twice.
+ *
  * @param {object[]} pages - Every page.
- * @param {object} options - Everything the render needs.
+ * @param {object} options - Everything the render needs. `homepages` is the
+ *   homepage as the index knows it — `{ fm, body, url, title }` — which takes
+ *   no part in the render and every part in the graph: a content page links
+ *   it by wikilink, and its own markdown links name content pages.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[]}}
+ *   wikiErrors: object[], imageErrors: object[],
+ *   related: Map<string, import("./related-pages.mjs").Related>}} `related`
+ *   is keyed by page URL, and holds the homepage's block beside every content
+ *   page's, so the caller can write it on the page this render does not.
  */
 export function renderPages(pages: object[], options: object): {
     written: number;
@@ -221,6 +253,7 @@ export function renderPages(pages: object[], options: object): {
     tableErrors: object[];
     wikiErrors: object[];
     imageErrors: object[];
+    related: Map<string, import("./related-pages.mjs").Related>;
 };
 /**
  * Resolves `site.pass` to its bundle.

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-index.d.mts

@@ -41,6 +41,9 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, no
  *   resolvers that distinguish a foreign hit from a local one.
  * @param {object} [options.assets] - The address space an `![[…]]` embed
  *   resolves against, shaped as every asset resolver reads one.
+ * @param {object[]} [options.resolved] - Collector the resolver appends every
+ *   resolved target's index entry to — the page's outbound edges, read off
+ *   the one pass that resolves them.
  * @returns {object} The resolver context.
  *
  * There is deliberately **no `manifestsComplete`**. It used to let a resolver
@@ -49,13 +52,14 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, no
  * checker never had it and one authored link must not get two verdicts. A
  * caller still passing it is ignored rather than obeyed.
  */
-export function wikiContext(built: SiteIndex, { src, file, type, errors, foreignIndex, assets }: {
+export function wikiContext(built: SiteIndex, { src, file, type, errors, foreignIndex, assets, resolved }: {
     src: string;
     type?: string | null | undefined;
     errors: object[];
     file?: string | undefined;
     foreignIndex?: Map<string, object> | undefined;
     assets?: object | undefined;
+    resolved?: object[] | undefined;
 }): object;
 /**
  * Resolve one infobox reference against a site index.

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;
+}>;

package/types/engine/web-wikilinks.d.mts

@@ -76,9 +76,17 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  * {@link module:engine/content-images.renderImageFigures} turns into a figure
  * for the website, and what the book reads its staging list out of.
  *
+ * ## Every hit is recorded, so the page's edges come out of one pass
+ *
+ * A caller that hands in `ctx.resolved` is given every index entry a link on
+ * the page resolved to, in body order, repeats included. That is the link
+ * graph, read at the one point where it exists: the build never has to walk a
+ * page a second time to learn what it links to. Nothing is recorded for a
+ * same-page anchor or for a target that resolved nowhere.
+ *
  * @param {string} body - The markdown body.
  * @param {object} ctx - `{ index, assets, collide, contentTypes,
- *   packages, noIndexPackages, foreign, type, errors, src, file }`.
+ *   packages, noIndexPackages, foreign, type, errors, src, file, resolved }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type;
  *   `noIndexPackages` is every package declared `contentIndex: false`, so a
@@ -87,7 +95,8 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  *   is the cross-package manifest index; `assets` is the address space an embed
  *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
- *   stands in.
+ *   stands in. `resolved`, when supplied, is the array every resolved
+ *   target's index entry is appended to.
  * @returns {string} The body with embeds and wikilinks rewritten.
  */
 export function resolveWebWikilinks(body: string, ctx: object): string;