@heroiclands/package-build 23.7.1 → 23.8.0

package/engine/see-also.mjs

@@ -0,0 +1,150 @@
+/*
+ * 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
+ */
+
+import { parseAddress, renderAddress, hasAnchor } from "./address.mjs";
+import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/**
+ * Validate note references, refusing unresolved, repeated and self destinations.
+ * @param {object} note - The authored note, including its raw source.
+ * @param {object} [options] - The local and declared dependency context.
+ * @param {object} [options.index] - The local and declared dependency index.
+ * @param {string} [options.index.contentPackage] - The package owning the note.
+ * @param {Set<string>} [options.index.types] - The indexed note types.
+ * @param {Set<string>} [options.index.packages] - The indexed packages.
+ * @param {(key: string) => {url?: string, uuid?: string, file?: string}|undefined}
+ *   [options.index.addressHit] - Resolve a canonical Address to its destination.
+ * @param {import("./address.mjs").AddressDefaults} [options.addressContext]
+ *   - The Address defaults and vocabularies at the authored reference.
+ * @returns {object[]} Findings located at the offending address.
+ */
+export function checkSeeAlso(note, { index, addressContext } = {}) {
+    const entries = note.fm?.data?.seeAlso;
+    if (!Array.isArray(entries)) return [];
+    const defaults = {
+        package: index?.contentPackage,
+        system: "note",
+        types: index?.types,
+        packages: index?.packages,
+        ...addressContext,
+        type: undefined,
+    };
+    const own = parseAddress(note.fm.shortcode, { ...defaults, type: note.fm.type });
+    const seen = new Set();
+    const findings = [];
+    entries.forEach((entry, i) => {
+        if (entry === null) {
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(note.raw ?? "", ["data", "seeAlso", i]),
+                severity: "error",
+                message: `\`data.seeAlso.${i}\` should be a map with an address`,
+            });
+            return;
+        }
+        if (!entry || typeof entry !== "object" || entry.address == null) return;
+        const tuple = parseAddress(entry.address, defaults, { declared: true });
+        const key = tuple.reason ? undefined : renderAddress(tuple);
+        const target = key ? index?.addressHit?.(key) : undefined;
+        const destination = target?.url ?? target?.uuid ?? target?.file ?? key;
+        const self =
+            (!own.reason &&
+                tuple.package === own.package &&
+                tuple.type === own.type &&
+                tuple.shortcode === own.shortcode) ||
+            (target?.file && target.file === note.file);
+        const reason =
+            hasAnchor(entry.address) ? "takes no anchor — it names a whole note"
+            : tuple.reason || ASSET_TYPE_NAMES.has(tuple.type) ? "should be a note Address"
+            : index?.addressHit && !target ?
+                "does not resolve in this package or its declared dependencies"
+            : self ? "names the note itself"
+            : seen.has(destination) ? "is a duplicate destination"
+            : undefined;
+        seen.add(destination);
+        if (reason)
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(note.raw ?? "", ["data", "seeAlso", i, "address"]),
+                severity: "error",
+                message: `\`data.seeAlso.${i}.address\` ${reason}`,
+            });
+    });
+    return findings;
+}
+
+/**
+ * Resolve deliberate references in authored order using the surface's index.
+ * @param {object} fm - The note frontmatter.
+ * @param {(address: unknown) => object|undefined} resolve - The surface's reference resolver.
+ * @returns {object[]} Display names, destinations and optional glosses.
+ */
+export function seeAlsoEntries(fm, resolve) {
+    const entries = fm?.data?.seeAlso;
+    if (!Array.isArray(entries)) return [];
+    return entries.flatMap((entry) => {
+        const target = entry?.address == null ? undefined : resolve(entry.address);
+        if (!target) return [];
+        return [{ ...target, text: target.name, ...(entry.gloss ? { gloss: entry.gloss } : {}) }];
+    });
+}
+
+/** Plain text in a generated Markdown paragraph. */
+const plain = (text) =>
+    String(text ?? "")
+        .replace(/([\\`*_[\]<>{}|#!~])/g, "\\$1")
+        .replace(/\r?\n/g, " ");
+
+/**
+ * A generated section; an empty list emits nothing.
+ * @param {object[]} entries - Resolved references in authored order.
+ * @param {(entry: object) => string} link - The medium's link markup.
+ * @param {number} [level=2] - Heading level; a journal uses one for a separate page.
+ * @returns {string} Markdown for the section.
+ */
+export function seeAlsoMarkdown(entries, link, level = 2) {
+    if (!entries.length) return "";
+    return `${"#".repeat(level)} See also\n\n${entries.map((entry) => `- ${link(entry)}${entry.gloss ? ` — ${plain(entry.gloss)}` : ""}`).join("\n")}\n`;
+}
+
+/**
+ * A reference rendered as an ordinary Markdown link for the book pipeline.
+ * @param {object} entry - A resolved name and URL.
+ * @returns {string} Markdown.
+ */
+export function seeAlsoWebLink(entry) {
+    return entry.url ? `[${plain(entry.text)}](<${entry.url}>)` : plain(entry.text);
+}
+
+/**
+ * Deliberate site connections for a set of pages, including dependency pages.
+ * @param {object[]} pages - Pages carrying frontmatter and their published URL.
+ * @param {(address: unknown) => object|undefined} resolve - The site's reference resolver.
+ * @returns {Map<string, import("./related-pages.mjs").RelatedEntry[]>} Entries keyed by source URL.
+ */
+export function seeAlsoPages(pages, resolve) {
+    const deliberate = new Map();
+    for (const page of pages) {
+        const refs = seeAlsoEntries(page.fm, resolve)
+            .filter((ref) => ref.url)
+            .map((ref) => ({
+                title: ref.name,
+                url: ref.url,
+                type: ref.address.type,
+                ...(ref.gloss ? { gloss: ref.gloss } : {}),
+            }));
+        if (refs.length) deliberate.set(page.url, refs);
+    }
+    return deliberate;
+}

package/engine/site-build.mjs

@@ -109,6 +109,7 @@ import {
 } from "./homepage.mjs";
 import { publishesContentPages } from "../content-config.mjs";
 import { HUGO_CONTENT } from "./site-config.mjs";
+import { seeAlsoPages } from "./see-also.mjs";
 import { homepageLinkTargets, relatedPages } from "./related-pages.mjs";
 import { drawSiteMaps, inlineDrawingFigure } from "./site-maps.mjs";
 import { generatedDrawing, markGenerated, splitGenerated } from "./generated-sections.mjs";
@@ -1095,7 +1096,10 @@ export function renderPages(pages, options) {
         for (const hit of result.resolved) if (hit.url) edges.push([page.url, hit.url]);
     }
 
-    const related = relatedPages(edges, entries);
+    const deliberate = seeAlsoPages([...pages, ...homepages], (ref) =>
+        resolveInfoboxRef(index, ref),
+    );
+    const related = relatedPages(edges, entries, deliberate);
 
     let withMap = 0;
     const outputs = capture === true ? new Map() : null;

package/engine/site-preview.mjs

@@ -22,7 +22,8 @@ import { foundryIdentities } from "./foundry-entries.mjs";
 import { applyComputedBeingAge, presentAmongRecords } from "./being-age.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 import { cachedMetadataIndexes, noContentIndexPackages } from "./metadata-index.mjs";
-import { buildSiteIndex } from "./site-index.mjs";
+import { seeAlsoPages } from "./see-also.mjs";
+import { buildSiteIndex, resolveInfoboxRef } from "./site-index.mjs";
 import {
     attachGeneratedSections,
     findSqlBlocks,
@@ -320,7 +321,8 @@ export async function prepareSitePreview({ config = loadPackConfig() } = {}) {
                     url: page.url,
                     type: String(fm.type),
                 });
-                const related = relatedPages(edges, entries).get(page.url);
+                const deliberate = seeAlsoPages([page], (ref) => resolveInfoboxRef(index, ref));
+                const related = relatedPages(edges, entries, deliberate).get(page.url);
                 if (related) result.data.related = related;
                 return {
                     ok: true,

package/engine/sql-tables.mjs

@@ -879,8 +879,9 @@ export function renderSqlTable(
  * its own table and not the whole build's report.
  *
  * @param {object} db - From {@link openNotesDatabase}.
- * @param {Array<{source: string, markdown: string}>} sources - The bodies to
- *   scan.
+ * @param {Array<{source: string, markdown: string, frontmatter?: object, authoredSqlBlocks?: number}>} sources -
+ *   The bodies to scan. `joinGeneratedSections` records the number of authored
+ *   fences; following generated event fences need no stub comparison.
  * @param {object} [opts]
  * @param {(ref: string) => boolean} [opts.linkable] - Passed to
  *   {@link renderSqlTable}.
@@ -904,26 +905,33 @@ export async function prepareSqlTables(db, sources, { linkable, records, pageLan
     const prepared = new Map();
     if (records) prepared.pageLists = preparePageLists(records, sources);
     // The corpus does not change while a preparation runs, so a query written
-    // twice has one answer. Each use gets its own copy, because a caller
-    // rewrites the rows it is handed.
+    // twice has one answer in each stub context. The normal result and the
+    // inclusive comparison occupy separate fields of the same cache entry.
+    // Each result use gets a copy because a caller rewrites the rows.
     const answers = new Map();
     const reader = {
         ...db,
         async query(sql) {
-            if (!answers.has(sql)) answers.set(sql, await db.query(sql));
-            return structuredClone(answers.get(sql));
+            if (!answers.has(sql)) answers.set(sql, { result: await db.query(sql) });
+            return structuredClone(answers.get(sql).result);
+        },
+        async stubsExcluded(sql, rows) {
+            const answer = answers.get(sql);
+            if (!Object.hasOwn(answer, "excluded"))
+                answer.excluded = await db.stubsExcluded?.(sql, rows);
+            return answer.excluded;
         },
     };
     let labels;
     const labelOf = (address) => labels.get(address);
     const languageOf =
         pageLanguage ?? ((_source, frontmatter) => frontmatterLanguage(frontmatter, db));
-    for (const { source, markdown, frontmatter } of sources) {
+    for (const { source, markdown, frontmatter, authoredSqlBlocks = Infinity } of sources) {
         const blocks = findSqlBlocks(markdown);
         if (!blocks.length) continue;
         const forNote = [];
         prepared.set(source, forNote);
-        for (const block of blocks) {
+        for (const [ordinal, block] of blocks.entries()) {
             try {
                 if (block.problems.length) throw new Error(block.problems.join("; "));
                 const result = await runSqlQuery(reader, block.query);
@@ -952,7 +960,12 @@ export async function prepareSqlTables(db, sources, { linkable, records, pageLan
                     // relation, so a fence that has not adopted stubs says so
                     // rather than quietly listing fewer settlements than the
                     // region has.
-                    stubsExcluded: await db.stubsExcluded?.(block.query, result.rows.length),
+                    // Generated event views read entries and events, whose
+                    // meaning is identical in both stub contexts.
+                    stubsExcluded:
+                        ordinal >= authoredSqlBlocks ? 0 : (
+                            await reader.stubsExcluded(block.query, result.rows.length)
+                        ),
                     allowEmpty: block.allowEmpty,
                 });
             } catch (err) {
@@ -1138,7 +1151,7 @@ export async function generatedSectionsFor(
  *
  * @param {{sections: Map<string, string>, views: Set<string>}} generated -
  *   From {@link generatedSectionsFor}.
- * @param {Array<{source: string, markdown: string, frontmatter?: object}>} sources -
+ * @param {Array<{source: string, markdown: string, frontmatter?: object, authoredSqlBlocks?: number}>} sources -
  *   The bodies to answer, extended in place.
  * @param {Map<string, {body: string, frontmatter: object|null}>} [parsed] -
  *   Notes already parsed, keyed by file; a note absent from it is read.
@@ -1148,6 +1161,7 @@ export function joinGeneratedSections(generated, sources, parsed) {
     for (const [absPath, text] of generated.sections) {
         const source = sources.find((one) => one.source === absPath);
         if (source) {
+            source.authoredSqlBlocks ??= findSqlBlocks(source.markdown).length;
             source.markdown = appendGeneratedSections(source.markdown, text);
             continue;
         }
@@ -1157,6 +1171,7 @@ export function joinGeneratedSections(generated, sources, parsed) {
             source: absPath,
             markdown: appendGeneratedSections(body, text),
             frontmatter,
+            authoredSqlBlocks: findSqlBlocks(body).length,
         });
     }
 }

package/engine/standings.mjs

@@ -378,17 +378,19 @@ function resolveBody(note, index, body) {
 
 /** Findings about the body an entry names. */
 function bodyFindings(note, body, path, isKey, found) {
-    const at = position(note, path, isKey);
+    const at = () => position(note, path, isKey);
     const written = isAddressTuple(body) ? renderAddress(body) : String(body);
     const label = `\`data.affiliations\`${isKey ? " key" : ""} ${JSON.stringify(written)}`;
     if (found.reason)
-        return [{ ...at, message: `${label} is not a complete Address (${found.reason})` }];
+        return [{ ...at(), message: `${label} is not a complete Address (${found.reason})` }];
     if (found.type)
-        return [{ ...at, message: `\`data.affiliations\` accepts affiliation, not ${found.type}` }];
+        return [
+            { ...at(), message: `\`data.affiliations\` accepts affiliation, not ${found.type}` },
+        ];
     if (found.missing)
         return [
             {
-                ...at,
+                ...at(),
                 message:
                     `\`data.affiliations\` names ${found.address}, which does not resolve ` +
                     "in this package or its declared dependencies",
@@ -438,12 +440,12 @@ function absentRankFindings(note, body, path) {
 function rankFindings(note, standing, body, path, resolved) {
     // Absent, or not a whole number: the inner-key check's finding.
     if (!fitsKind(standing.rank ?? null, "integer")) return [];
-    const at = position(note, [...path, "rank"]);
+    const at = () => position(note, [...path, "rank"]);
     const level = typeof standing.rank === "number" ? standing.rank : Number(standing.rank);
     if (typeof standing.rank !== "number" || !Number.isInteger(level))
         return [
             {
-                ...at,
+                ...at(),
                 message:
                     `\`data.affiliations\` entry for ${body}: \`rank\` must be the level on that body's own ` +
                     `ladder, as a whole number, but reads ${JSON.stringify(standing.rank)}`,
@@ -455,7 +457,7 @@ function rankFindings(note, standing, body, path, resolved) {
     if (!ladder.size)
         return [
             {
-                ...at,
+                ...at(),
                 message:
                     `\`data.affiliations\` entry for ${body} states a rung, and that body ` +
                     "declares no `data.governance.ranks` ladder to hold one",
@@ -464,7 +466,7 @@ function rankFindings(note, standing, body, path, resolved) {
     const levels = [...ladder.keys()].sort((a, b) => a - b);
     return [
         {
-            ...at,
+            ...at(),
             message:
                 `\`data.affiliations\` entry for ${body}: rank ${level} is not a level ` +
                 `${resolved.address} confers; its ladder runs ${levels.join(", ")}`,
@@ -477,11 +479,11 @@ function officeFindings(note, standing, body, path, resolved) {
     // Absent is a membership with no post; a value that is not text is the
     // inner-key check's finding.
     if (typeof standing.office !== "string") return [];
-    const at = position(note, [...path, "office"]);
+    const at = () => position(note, [...path, "office"]);
     if (!standing.office.trim())
         return [
             {
-                ...at,
+                ...at(),
                 message:
                     `\`data.affiliations\` entry for ${body}: \`office\` must name a post from its ` +
                     `\`governance.offices\`, but reads ${JSON.stringify(standing.office)}`,
@@ -493,7 +495,7 @@ function officeFindings(note, standing, body, path, resolved) {
     if (!roster.size)
         return [
             {
-                ...at,
+                ...at(),
                 message:
                     `\`data.affiliations\` entry for ${body} names an office, and that body ` +
                     `${resolved.address} declares no \`data.governance.offices\` to hold one`,
@@ -501,7 +503,7 @@ function officeFindings(note, standing, body, path, resolved) {
         ];
     return [
         {
-            ...at,
+            ...at(),
             message:
                 `\`data.affiliations\` entry for ${body}: office ${JSON.stringify(standing.office)} is not ` +
                 `an office ${resolved.address} names; it holds ${[...roster.keys()].join(", ")}`,

package/hugo-theme/layouts/partials/related.html

@@ -6,11 +6,13 @@
 
   Structure in front matter:
     related:
+      seeAlso:   [{ title, url, type, gloss? }, ...] # deliberate references
       backlinks: [{ title, url, type }, ...]   # pages that link here
       mentions:  [{ title, url, type }, ...]   # pages this page links to
 
   Rendering strategy:
-    - Merge both directions into a single deduped pool (direction
+    - Render deliberate references in authored order, with their glosses.
+    - Merge both inferred directions into a single deduped pool (direction
       doesn't matter to a reader — a connection is a connection).
     - Group by the referenced page's `type`.
     - Emit one labelled group per type, its entries laid out as a
@@ -20,7 +22,7 @@
     - The whole block is wrapped in a bordered, tinted card so it
       visually sets off the end of the article.
 
-  Silent disappear: a page with no `related`, or whose two lists are both
+  Silent disappear: a page with no `related`, or whose lists are all
   empty, emits nothing at all rather than an empty heading. The rows are
   computed first and the <section> is rendered only when there is something
   to put in it.
@@ -34,15 +36,23 @@
 {{- /* `default dict` keeps the lookups below safe on a page with no
        `related` at all, so the whole computation stays flat. */ -}}
 {{- $rel := .Params.related | default dict -}}
+{{- $seeAlso := or $rel.seealso slice -}}
 {{- $backlinks := or $rel.backlinks slice -}}
 {{- $mentions  := or $rel.mentions  slice -}}
 
 {{- /* Merge both directions, deduped by URL. `union` can't hash
        slices of maps, so we walk the two lists in order and dedupe
-       by URL manually. Mentions come first so explicit author
-       choices win when a page appears in both directions. */ -}}
+       by URL manually. Deliberate references take priority; mentions
+       precede backlinks among inferred connections. */ -}}
 {{- $seen := slice -}}
 {{- $merged := slice -}}
+{{- $deliberate := slice -}}
+{{- range $seeAlso -}}
+  {{- if not (in $seen .url) -}}
+    {{- $seen = $seen | append .url -}}
+    {{- $deliberate = $deliberate | append . -}}
+  {{- end -}}
+{{- end -}}
 {{- range $mentions -}}
   {{- if not (in $seen .url) -}}
     {{- $seen = $seen | append .url -}}
@@ -101,12 +111,19 @@
   {{- $rows = sort $rows "label" "asc" -}}
 {{- end -}}
 
-{{- /* Deliberately not indented under the `if`: keeping the markup at
-       column 0 leaves the emitted HTML byte-identical to what pages with
-       `related` rendered before the guard was added. */ -}}
-{{- if $rows -}}
+{{- if or $rows $deliberate -}}
 <section class="related" aria-labelledby="related-heading" data-pagefind-ignore>
   <h2 id="related-heading" class="related-heading">Related</h2>
+  {{- with $deliberate }}
+  <div class="related-group">
+    <h3 class="related-group-label">See also</h3>
+    <ul class="related-group-grid">
+      {{- range . }}
+      <li><a href="{{ .url }}">{{ .title }}</a>{{ with .gloss }} — {{ . }}{{ end }}</li>
+      {{- end }}
+    </ul>
+  </div>
+  {{- end }}
   {{- range $rows }}
   <div class="related-group">
     <h3 class="related-group-label">{{ .label }}</h3>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.7.1",
+    "version": "23.8.0",
     "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",
@@ -132,6 +132,7 @@
     "dependencies": {
         "@duckdb/node-api": "^1.5.5-r.4",
         "@foundryvtt/foundryvtt-cli": "^3.0.4",
+        "@puppeteer/browsers": "^3.2.5",
         "@viz-js/viz": "^3.30.0",
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",

package/types/container.d.mts

@@ -247,8 +247,8 @@ export function s3RunArgs(plan: S3Plan): string[];
  */
 export function s3ShellArgs(plan: S3Plan, command: string): string[];
 /**
- * Start the S3 server on its network and create the bucket, unless it is
- * already running, and copy the `awsConfig` into the data root.
+ * Start or reuse the S3 server on its network, wait for readiness, ensure the
+ * bucket exists, and copy the `awsConfig` into the data root.
  *
  * @param {object} opts
  * @param {S3Plan} opts.plan - The S3 plan.
@@ -261,7 +261,8 @@ export function s3ShellArgs(plan: S3Plan, command: string): string[];
  * @param {(ms: number) => void} [opts.sleep] - Waits.
  * @param {number} [opts.attempts] - How often to ask the server whether it is
  *   ready.
- * @throws {Error} When an input file is missing or the server never answers.
+ * @throws {Error} When an input is not a readable regular file, a reused
+ *   identities mount is incompatible, or the S3 HTTP service never answers.
  */
 export function ensureS3({ plan, dataRoot, log, run, capture, sleep, attempts, }: {
     plan: S3Plan;

package/types/e2e.d.mts

@@ -236,6 +236,32 @@ export function waitForWorld({ url, container, stage, dataRoot, readLog, timeout
  * @returns {string[]} The executables to resolve, in the order to report them.
  */
 export function suiteExecutables(command: readonly string[]): string[];
+/**
+ * The browser cache survives reseeding and container teardown.
+ * @param {NodeJS.ProcessEnv} [env] - Environment overrides.
+ * @returns {string} The browser cache directory.
+ */
+export function browserCacheDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * Supply pinned Chrome only to a recognizable Cypress command without a browser.
+ * Explicit browser arguments remain verbatim, including Electron and paths.
+ * @param {object} opts
+ * @param {readonly string[]} opts.command - The configured suite command.
+ * @param {string[]} [opts.args] - Extra suite arguments.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Cache overrides.
+ * @param {string} [opts.platform] - Host operating system.
+ * @param {string} [opts.arch] - Host architecture.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {Promise<string[]>} Arguments to append to the suite command.
+ */
+export function prepareSuiteBrowser({ command, args, env, platform, arch, log, }: {
+    command: readonly string[];
+    args?: string[] | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    platform?: string | undefined;
+    arch?: string | undefined;
+    log?: ((message: string) => void) | undefined;
+}): Promise<string[]>;
 /**
  * Find an executable the way the child process will: a path is a path, and a
  * bare name is looked for in the repository's `node_modules/.bin` first, then
@@ -467,6 +493,8 @@ export const E2E_GM_ID: "heroiclandsE2EGM";
 export const E2E_SCENE_ID: "heroiclandsScene";
 /** How the suite may be run. */
 export const E2E_MODES: readonly string[];
+/** The Chrome for Testing build shared by local and CI Cypress runs. */
+export const CHROME_BUILD_ID: "155.0.8059.84";
 /**
  * The disposable world's identity and credentials.
  */

package/types/engine/base-compiler.d.mts

@@ -631,8 +631,8 @@ export class BasePackCompiler {
     compile(): Promise<void>;
     currentNote: {
         absPath: string;
-        bodyLine: number | undefined;
-        bodyColumn: number | undefined;
+        bodyLine: any;
+        bodyColumn: any;
     } | undefined;
     #private;
 }

package/types/engine/compile-corpus.d.mts

@@ -15,7 +15,7 @@
  *   created when none is passed, and returned on the corpus either way — a note
  *   the index refuses is a note the compile must still *report*, exactly as the
  *   compile loop reported it when the loop was the first to see it.
- * @returns {Promise<{records: object[], linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
+ * @returns {Promise<{records: object[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
 export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, router, config, problems, }: {
@@ -27,6 +27,7 @@ export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, r
     problems?: object[] | undefined;
 }): Promise<{
     records: object[];
+    parsed: Map<string, object>;
     linkIndex: object;
     sqlTables: Map<string, object[]> | undefined;
     problems: object[];

package/types/engine/content-index.d.mts

@@ -94,6 +94,7 @@ export function asciiAliases(aliases: unknown): Array<string>;
  * @param {string} options.relPath - Its path below the content root, POSIX-separated.
  * @param {string} [options.absPath] - The file, read only on the failing path to
  *   locate the offending key.
+ * @param {string} [options.raw] - Source text already read by the caller.
  * @param {string} options.contentPackage - The package the tree compiles as.
  * @param {string} [options.body] - The note's markdown body, for its anchors
  *   and for the one question that decides whether the note publishes a page. A
@@ -118,10 +119,11 @@ export function asciiAliases(aliases: unknown): Array<string>;
  *   otherwise be overwritten without a word. `file` and, where the file was
  *   read, `position` ride on the error.
  */
-export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, addressContext, dateContext, resolveRole, }: {
+export function buildIndexRecord({ frontmatter, relPath, absPath, raw, contentPackage, body, bodyLine, manifest, addressContext, dateContext, resolveRole, }: {
     frontmatter: Record<string, any>;
     relPath: string;
     absPath?: string | undefined;
+    raw?: string | undefined;
     contentPackage: string;
     body?: string | undefined;
     bodyLine?: number | undefined;
@@ -131,12 +133,13 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage
     resolveRole?: ((address: string) => string | undefined) | undefined;
 }): Record<string, any>;
 /** Derive every index record belonging to one parsed note. */
-export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext, dateContext, resolveRole, }: {
+export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, raw, contentPackage, manifest, addressContext, dateContext, resolveRole, }: {
     frontmatter: any;
     body: any;
     bodyLine: any;
     relPath: any;
     absPath: any;
+    raw: any;
     contentPackage: any;
     manifest: any;
     addressContext: any;
@@ -188,16 +191,20 @@ export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absP
  *   immediate parent whose package is not this one.
  * @param {object[]} [options.problems] - Receives each conflict as a finding.
  *   Omitted, every conflict is collected and one Error lists them all.
+ * @param {Map<string, {raw: string}>} [options.parsed] - Notes already read, keyed by file.
  * @returns {Array<Record<string, any>>} The same records.
  * @throws {Error} When `problems` is omitted and any note's sources disagree.
  */
-export function resolveCultures(records: Array<Record<string, any>>, { contentPackage, contentBase, foreignRecord, problems }: {
+export function resolveCultures(records: Array<Record<string, any>>, { contentPackage, contentBase, foreignRecord, problems, parsed }: {
     contentPackage: string;
     contentBase?: string | undefined;
     foreignRecord?: ((key: string) => ({
         culture?: unknown;
     } | undefined)) | undefined;
     problems?: object[] | undefined;
+    parsed?: Map<string, {
+        raw: string;
+    }> | undefined;
 }): Array<Record<string, any>>;
 /**
  * Read a content tree into index records, in the order they will be written.
@@ -233,9 +240,9 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  * @param {(key: string) => ({culture?: unknown}|undefined)} [options.foreignRecord] -
  *   Another package's entry for a canonical address, read for a parent that
  *   package publishes; see {@link resolveCultures}.
- * @param {Map<string, {body: string, frontmatter: object|null}>} [options.parsed] -
- *   Filled with each note's body and its frontmatter as authored, keyed by the
- *   note's file, so a later pass reads the notes this walk already parsed.
+ * @param {Map<string, {body: string, frontmatter: object|null, raw: string, bodyLine?: number, bodyColumn?: number}>} [options.parsed] -
+ *   Filled with each note's source text, body coordinates and frontmatter as
+ *   authored, keyed by file, for reuse throughout the command.
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
@@ -252,6 +259,9 @@ export function collectContentIndex(contentBase: string, { contentPackage, skipD
     parsed?: Map<string, {
         body: string;
         frontmatter: object | null;
+        raw: string;
+        bodyLine?: number;
+        bodyColumn?: number;
     }> | undefined;
 }): Array<Record<string, any>>;
 /**
@@ -289,7 +299,7 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  *   aborting the derivation. Omitted, the note throws — which is the contract
  *   the emitter needs, since an index missing a note asserts that it does not
  *   exist.
- * @param {Map<string, {body: string, frontmatter: object|null}>} [opts.parsed] -
+ * @param {Map<string, {body: string, frontmatter: object|null, raw: string, bodyLine?: number, bodyColumn?: number}>} [opts.parsed] -
  *   Filled with each note's body and authored frontmatter, keyed by the note's
  *   file. Handed to {@link module:engine/sql-tables.prepareTreeSqlTables}, it
  *   spares that pass reading and parsing every note again.
@@ -304,6 +314,9 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
     parsed?: Map<string, {
         body: string;
         frontmatter: object | null;
+        raw: string;
+        bodyLine?: number;
+        bodyColumn?: number;
     }> | undefined;
 }): object[];
 /**