@heroiclands/package-build 22.4.3 → 22.4.5

package/engine/related-pages.mjs

@@ -0,0 +1,161 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * What links to a page, and what it links to.
+ *
+ * The site build resolves every wikilink through the address index, so by the
+ * time it writes a page it holds the whole link graph. This is the half that
+ * turns the graph into front matter: the `related` block the theme's Related
+ * card reads, on every page, in one shape.
+ *
+ * **A page is identified by its URL.** An address is unique within a package
+ * and a page publishes at exactly one, so the URL is the one key both a
+ * resolved wikilink and a homepage's markdown link can be reduced to — the
+ * link resolver answers with a URL, and a homepage link *is* one. It is also
+ * what makes a `doc<type>-<shortcode>` link a link to the same page as the
+ * `<type>-<shortcode>` form: the site index keys one page under both, and both
+ * answer with one URL.
+ *
+ * **Only a page of this site is an endpoint.** A link into another package
+ * resolves to a URL the build renders but no page it writes, so it appears
+ * on neither side: a backlink can only be counted on a page this build emits,
+ * and listing a foreign mention beside local ones would make the two lists
+ * disagree about what a connection is.
+ *
+ * @module
+ */
+
+import { homepageAddresses } from "./homepage.mjs";
+
+/**
+ * One entry in a `related` list — the page a reader is pointed at.
+ *
+ * @typedef {object} RelatedEntry
+ * @property {string} title The page's published title.
+ * @property {string} url   `<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.
+ * @property {string} type  The note's `type`, which the theme groups by.
+ */
+
+/**
+ * The `related` block one page publishes.
+ *
+ * @typedef {object} Related
+ * @property {RelatedEntry[]} backlinks Pages that link to this one.
+ * @property {RelatedEntry[]} mentions  Pages this one links to.
+ */
+
+/**
+ * A stable order for a list: by type, then title.
+ *
+ * The theme groups a list by type and reads each group in the order it
+ * arrives, so the order is fixed here rather than left to walk order — which
+ * is content-path order, and would reshuffle a page's card whenever a note was
+ * filed elsewhere.
+ *
+ * @param {RelatedEntry} a
+ * @param {RelatedEntry} b
+ * @returns {number}
+ */
+function byTypeThenTitle(a, b) {
+    return a.type.localeCompare(b.type, "en") || a.title.localeCompare(b.title, "en");
+}
+
+/**
+ * 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, entries) {
+    /** @type {Map<string, {backlinks: Set<string>, mentions: Set<string>}>} */
+    const graph = new Map();
+    const node = (url) => {
+        let found = graph.get(url);
+        if (!found) {
+            found = { backlinks: new Set(), mentions: new Set() };
+            graph.set(url, found);
+        }
+        return found;
+    };
+
+    for (const [source, target] of edges) {
+        if (source === target) continue;
+        if (!entries.has(source) || !entries.has(target)) continue;
+        node(source).mentions.add(target);
+        node(target).backlinks.add(source);
+    }
+
+    const list = (urls) =>
+        [...urls]
+            .map((url) => /** @type {RelatedEntry} */ (entries.get(url)))
+            .sort(byTypeThenTitle);
+
+    const out = new Map();
+    for (const [url, { backlinks, mentions }] of graph) {
+        out.set(url, { backlinks: list(backlinks), mentions: list(mentions) });
+    }
+    return out;
+}
+
+/**
+ * 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, base) {
+    const out = [];
+    // A placeholder origin, so a relative target resolves the way a browser
+    // resolves it from the homepage. It never reaches the result: only the
+    // path is read, and only when the target stayed on this origin.
+    const origin = "http://site.invalid";
+    for (const { url } of homepageAddresses(body)) {
+        if (/^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith("//")) continue;
+        let resolved;
+        try {
+            resolved = new URL(url, `${origin}${base}`);
+        } catch {
+            continue;
+        }
+        if (resolved.origin !== origin) continue;
+        out.push(resolved.pathname);
+    }
+    return out;
+}

package/engine/site-build.mjs

@@ -81,6 +81,7 @@ import {
 } from "./homepage.mjs";
 import { publishesContentPages } from "../content-config.mjs";
 import { HUGO_CONTENT } from "./site-config.mjs";
+import { homepageLinkTargets, relatedPages } from "./related-pages.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -291,18 +292,30 @@ export function collectHomepages(contentBase, ctx) {
  * 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, pages, config) {
+export function writeHomepages(outRoot, pages, config, { related } = {}) {
     for (const page of pages) {
         const data = homepageFrontmatter(page.fm, {
             contentPackage: config.contentPackage,
             title: homepageTitle(page.fm, config),
+            related,
         });
         const dest = path.join(outRoot, HOMEPAGE_DESTINATION);
         fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -472,6 +485,12 @@ export function tableUniverse(pages) {
  * 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
@@ -486,7 +505,7 @@ export function tableUniverse(pages) {
  * @returns {object} The frontmatter to write.
  */
 export function pageFrontmatter(page, { decorate, webSrc, artSrc }) {
-    const { fm, name, slug } = page;
+    const { fm, slug } = page;
     const data = {
         ...fm,
         // Spread after the note's own frontmatter. Guarded because
@@ -500,15 +519,31 @@ export function pageFrontmatter(page, { decorate, webSrc, artSrc }) {
         // from the filename.
         slug,
         url: `/${slug}/`,
-        title: fm.title ?? name,
+        title: pageTitle(page),
         kbfolder: page.folder,
     };
     if (decorate) decorate(data, page);
     delete data.aliases;
+    delete data.related;
     if (webSrc && artSrc) resolveArtFields(data, webSrc, artSrc);
     return data;
 }
 
+/**
+ * The title a content page publishes under: an authored `title`, else the
+ * note's name.
+ *
+ * One rule, read by the page's own front matter and by every `related` entry
+ * that names the page, so a card lists a page by exactly the title its heading
+ * shows.
+ *
+ * @param {object} page - The page, from {@link collectContentPages}.
+ * @returns {string} The title.
+ */
+function pageTitle(page) {
+    return page.fm.title ?? page.name;
+}
+
 /**
  * Rewrite a page's artwork addresses into the URLs the website serves.
  *
@@ -585,10 +620,23 @@ export function pageDestination(page) {
  *    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, options) {
     const {
@@ -602,6 +650,7 @@ export function renderPages(pages, options) {
         sqlTables,
         config,
         records = [],
+        homepages = [],
     } = options;
 
     // The address space the art slots and the body's embeds resolve against:
@@ -616,6 +665,29 @@ export function renderPages(pages, options) {
     const wikiErrors = [];
     const imageErrors = [];
     const byKind = {};
+    // The link graph, as `(source URL, target URL)` — read off each page's
+    // resolution below, and off the homepage's markdown links.
+    /** @type {Array<[string, string]>} */
+    const edges = [];
+    // Every page of this site, as a `related` entry names it.
+    /** @type {Map<string, import("./related-pages.mjs").RelatedEntry>} */
+    const entries = new Map();
+    for (const page of pages) {
+        entries.set(page.url, {
+            title: pageTitle(page),
+            url: page.url,
+            type: String(page.fm.type),
+        });
+    }
+    for (const home of homepages) {
+        entries.set(home.url, { title: home.title, url: home.url, type: String(home.fm.type) });
+        for (const target of homepageLinkTargets(home.body, home.url)) {
+            edges.push([home.url, target]);
+        }
+    }
+    // What each page renders as, held until the graph is whole.
+    /** @type {Array<{page: object, body: string, data: object}>} */
+    const rendered = [];
 
     /**
      * The address the website serves for one authored pathname.
@@ -661,6 +733,8 @@ export function renderPages(pages, options) {
         // The page's path in the tree an author edits, below the content
         // root.
         const src = page.relPath ?? page.base;
+        // Every index entry a link on this page resolved to.
+        const resolved = [];
         const ctx = wikiContext(index, {
             src,
             file: page.file,
@@ -668,6 +742,7 @@ export function renderPages(pages, options) {
             errors: wikiErrors,
             foreignIndex: foreign.index,
             assets: artIndex,
+            resolved,
         });
 
         const webSrc = webAddresses(page.file);
@@ -699,13 +774,26 @@ export function renderPages(pages, options) {
         tableErrors.push(...errors);
 
         const data = pageFrontmatter(page, { decorate, webSrc, artSrc });
+        rendered.push({ page, body: protectCode(body, resolve), data });
+        // A resolved target with no URL is a pack-only package's address:
+        // real, and nowhere on the web, so not an edge.
+        for (const hit of resolved) {
+            if (hit.url) edges.push([page.url, hit.url]);
+        }
+    }
+
+    const related = relatedPages(edges, entries);
+
+    for (const { page, body, data } of rendered) {
+        const block = related.get(page.url);
+        if (block) data.related = block;
         const dest = path.join(outRoot, pageDestination(page));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, matter.stringify(protectCode(body, resolve), data));
+        fs.writeFileSync(dest, matter.stringify(body, data));
         byKind[page.kind] = (byKind[page.kind] ?? 0) + 1;
     }
 
-    return { written: pages.length, byKind, tableErrors, wikiErrors, imageErrors };
+    return { written: pages.length, byKind, tableErrors, wikiErrors, imageErrors, related };
 }
 
 /**
@@ -892,11 +980,17 @@ export function buildSite({ config, sqlTables } = {}) {
     // homepage is authored markdown published verbatim, with no table
     // expansion and no link resolution of its own, and routing it through
     // that pipeline would buy it a pass it has no input for.
+    //
+    // It is a node of the link graph all the same: `renderPages` reads its
+    // markdown links for the edges it authors, and the resolver records the
+    // ones that land on it.
     const homepageEntries = homepages.map((page) => ({
         kind: "content",
         fm: page.fm,
+        body: page.body,
         pkg: resolved.contentPackage,
         name: page.fm.name?.full ?? homepageTitle(page.fm, resolved),
+        title: homepageTitle(page.fm, resolved),
         slug: addressSlug(page.fm),
         base: path.basename(page.file),
         url: base,
@@ -926,6 +1020,7 @@ export function buildSite({ config, sqlTables } = {}) {
         index: gates.index,
         foreign: gates.foreign,
         universe: tableUniverse(pages),
+        homepages: homepageEntries,
         pass,
         // What counts as a being is the toolchain's to say, not a consumer's.
         // Asking in a consumer's script is how one came to still be checking
@@ -947,8 +1042,11 @@ export function buildSite({ config, sqlTables } = {}) {
     });
 
     // Last, and outside the mount: the package's front page is not part of the
-    // content tree it introduces.
-    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved);
+    // content tree it introduces. It publishes at `base`, which is where the
+    // graph keys its block.
+    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved, {
+        related: rendered.related.get(base),
+    });
 
     return {
         gates,

package/engine/site-config.mjs

@@ -57,7 +57,7 @@ export const HUGO_CONTENT = `${HUGO_SOURCE}/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";
 

package/engine/site-index.mjs

@@ -289,6 +289,9 @@ export function buildSiteIndex(
  *   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
@@ -299,7 +302,7 @@ export function buildSiteIndex(
  */
 export function wikiContext(
     built,
-    { src, file, type = null, errors, foreignIndex = new Map(), assets },
+    { src, file, type = null, errors, foreignIndex = new Map(), assets, resolved },
 ) {
     return {
         index: built.index,
@@ -321,6 +324,7 @@ export function wikiContext(
         errors,
         src,
         file,
+        resolved,
     };
 }
 

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/engine/web-wikilinks.mjs

@@ -311,9 +311,17 @@ function isPlainMap(value) {
  * {@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
@@ -322,7 +330,8 @@ function isPlainMap(value) {
  *   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, ctx) {
@@ -425,6 +434,8 @@ export function resolveWebWikilinks(body, ctx) {
                 lookupRead(ctx.foreign, read, ctx.contentPackage)
             :   undefined);
         if (hit) {
+            // The edge, for a caller reading the link graph off this pass.
+            ctx.resolved?.push(hit);
             // An address with an *empty* label has no prose to show (a
             // shortcode is not display text), so the document's **current**
             // name stands in and a rename shows at every citation.