@heroiclands/package-build 23.7.1 → 23.8.0

package/engine/diagnostics.mjs

@@ -249,15 +249,20 @@ export function positionInFrontmatter(raw, key, value = undefined, { topLevel =
  *   {@link positionInFrontmatter}.
  * @param {boolean} [options.topLevel=false] - Require the key at column 1, so
  *   an identically named nested key cannot answer for it.
+ * @param {string} [options.raw] - Source text already read by the caller.
  * @returns {{line?: number, column?: number}|undefined} Spreadable position
  *   fields, dropped rather than guessed when the file cannot be read or the key
  *   cannot be found — as `formatDiagnostic` requires.
  */
-export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel = false } = {}) {
-    if (!absPath) return undefined;
-    let raw;
+export function locateFrontmatterKey(
+    absPath,
+    key,
+    value = undefined,
+    { topLevel = false, raw } = {},
+) {
+    if (!absPath && raw === undefined) return undefined;
     try {
-        raw = fs.readFileSync(absPath, "utf8");
+        raw ??= fs.readFileSync(absPath, "utf8");
     } catch {
         return undefined;
     }
@@ -306,6 +311,9 @@ export function positionOfLiteral(text, needle, occurrence = 1) {
     };
 }
 
+/** The most recently located text; retaining one document bounds memory. */
+let locatedYaml;
+
 /**
  * Where a **key or value in a YAML document** sits, addressed by its path.
  *
@@ -315,11 +323,10 @@ export function positionOfLiteral(text, needle, occurrence = 1) {
  * first occurrence is routinely not the one the finding is about — which is the
  * one thing the located form exists to prevent.
  *
- * A path resolves the exact node instead. The document is re-parsed here rather
- * than threaded from the loader because the loader returns plain data: `yaml`
- * discards ranges once a document is materialised, and carrying a parallel
- * position tree through configuration resolution would be a second
- * representation of the same file to keep in step.
+ * A path resolves the exact node. The most recently located text retains its
+ * document and line counter, so several findings in one note share a parse.
+ * A different text replaces that entry, including an edited copy of the same
+ * file. The loader returns plain data without source ranges.
  *
  * Every failure — unparseable text, an `.mjs` configuration, a path that
  * resolves to nothing — yields `{}`, so a caller spreads the result and the
@@ -348,9 +355,15 @@ export function positionOfYamlPath(text, keyPath, { key = false } = {}) {
     if (!Array.isArray(keyPath) || keyPath.length === 0) return {};
 
     let node;
-    const counter = new LineCounter();
+    let counter;
     try {
-        const doc = YAML.parseDocument(text, { lineCounter: counter });
+        if (locatedYaml?.text !== text) {
+            const lineCounter = new LineCounter();
+            const doc = YAML.parseDocument(text, { lineCounter });
+            locatedYaml = { text, doc, counter: lineCounter };
+        }
+        const { doc } = locatedYaml;
+        counter = locatedYaml.counter;
         // `keepScalar` returns the Scalar node rather than its value, which is
         // the only form carrying a range.
         node = doc.getIn(keyPath, true);

package/engine/frontmatter-lint.mjs

@@ -1541,7 +1541,7 @@ export function lintNote(
         for (const field of fields) {
             if (note.inheritedCultureFields?.has(field.name)) continue;
             if (typeof field.check !== "function") continue;
-            findings.push(...field.check(note, { index }));
+            findings.push(...field.check(note, { index, addressContext: referenceContext }));
         }
         // A check the type declares of the whole note, with the same index.
         if (typeof entry.check === "function") findings.push(...entry.check(note, { index }));

package/engine/generate.mjs

@@ -38,7 +38,7 @@
  * The HeroicLands vault is not a build input for SoHL content.
  */
 
-import { noteAddressContext } from "./note-addresses.mjs";
+import { noteAddressContext, decodeNoteAddresses } from "./note-addresses.mjs";
 import { GENERATED_DRAWING_DIR } from "./generated-sections.mjs";
 import fs from "fs";
 import path from "path";
@@ -54,7 +54,7 @@ import { Hm3Actors } from "../hm3/actors.mjs";
 import { Macros } from "./macros.mjs";
 import { Scenes } from "./scenes.mjs";
 import { Bundles } from "./bundles.mjs";
-import { statsForPack, parseMarkdownFile, folderFilename } from "./helpers.mjs";
+import { statsForPack, folderFilename } from "./helpers.mjs";
 import {
     buildFolderNoteIndex,
     collectFolderNotes,
@@ -800,7 +800,10 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
     // every type a system deliberately does not map, which is exactly the
     // silence the rule requires. Independent of `only`, since it is a fact about the
     // configured pack list rather than about which passes this run executes.
-    const unclaimed = unclaimedNoteFindings(config, undefined, { records: corpus.records });
+    const unclaimed = unclaimedNoteFindings(config, undefined, {
+        records: corpus.records,
+        parsed: corpus.parsed,
+    });
     for (const finding of unclaimed) emitDiagnostic(finding);
 
     fs.mkdirSync(config.paths.packJson, { recursive: true });
@@ -831,22 +834,8 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
     try {
         folderNotes = buildFolderNoteIndex(
             collectFolderNotes(
-                // The corpus this compile derived picks the notes; the
-                // file supplies their frontmatter, and this is one of the few
-                // places where that distinction is load-bearing rather than
-                // incidental.
-                //
-                // `collectFolderNotes` treats `fm.id` as an **authored pin**,
-                // which wins over the id it derives under the folder namespace.
-                // A record's `id` is not that: the index fills it in for every
-                // addressable note, so handing records straight over
-                // would make every folder look pinned. The *value*
-                // would be right either way — the index derives a folder's id
-                // under the folder namespace, so the two agree — but `derivedId`
-                // would not, and it is what tells an author whether a duplicate
-                // id was two pins or two addresses. The index cannot tell a pin
-                // from a derivation, so the note is read — and only folder notes
-                // are, 79 of `sohl`'s 1,685 rather than all of them.
+                // Folder pins are authored ids; index-derived ids must not
+                // turn an unpinned folder into a pinned one.
                 corpus.records
                     .filter(
                         (record) =>
@@ -856,9 +845,10 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
                     .map((record) => {
                         const absPath = noteFile(contentBase, record);
                         return {
-                            frontmatter: parseMarkdownFile(absPath, {
-                                addressContext: noteAddressContext(config),
-                            }).frontmatter,
+                            frontmatter: decodeNoteAddresses(
+                                structuredClone(corpus.parsed.get(absPath).frontmatter),
+                                noteAddressContext(config),
+                            ),
                             absPath,
                         };
                     }),

package/engine/helpers.mjs

@@ -233,17 +233,18 @@ export function renderFoundryMarkdown(body, figures, footnoteNumbers, docId, res
 /**
  * Parses a markdown file with YAML frontmatter.
  *
- * Returns `{ frontmatter, body, description, bodyLine, bodyColumn }` where
+ * Returns `{ frontmatter, body, description, bodyLine, bodyColumn, raw }` where
  * `body` is the trimmed raw markdown after the frontmatter block, and
- * `description` is `body` rendered to HTML. `bodyLine` / `bodyColumn` are the
+ * `description` is `body` rendered to HTML. The full source is retained as
+ * `raw` for diagnostic locations. `bodyLine` / `bodyColumn` are the
  * 1-based **file** position of the body's first character, which is what turns
  * an offset within `body` into a position a diagnostic can name — see
  * {@link positionInBody}. If the file has no frontmatter block, returns
- * `{ frontmatter: null, body: "", description: "" }` with a warn log, and no
+ * `{ frontmatter: null, body: "", description: "", raw }` and no
  * position: there is no body to have one.
  * @param {string} filePath - Markdown file to read.
  * @param {{addressContext?: object}} [opts] - Address defaults for decoded fields.
- * @returns {{frontmatter: object|null, body: string, description: string,
+ * @returns {{frontmatter: object|null, body: string, description: string, raw: string,
  *   bodyLine?: number, bodyColumn?: number, parseError?: {message: string,
  *   line?: number, column?: number}}} Parsed note and body position.
  */
@@ -251,7 +252,7 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
     const content = fs.readFileSync(filePath, "utf8");
     const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
     if (!fmMatch) {
-        return { frontmatter: null, body: "", description: "" };
+        return { frontmatter: null, body: "", description: "", raw: content };
     }
     let frontmatter;
     try {
@@ -264,6 +265,7 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
             frontmatter: null,
             body: "",
             description: "",
+            raw: content,
             parseError: {
                 message: `YAML parse error: ${message}`,
                 ...(Number.isInteger(location?.line) ? { line: location.line + 1 } : {}),
@@ -295,7 +297,7 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
     const before = content.slice(0, bodyStart);
     const bodyLine = before.split("\n").length;
     const bodyColumn = bodyStart - before.lastIndexOf("\n");
-    return { frontmatter, body, description, bodyLine, bodyColumn };
+    return { frontmatter, body, description, bodyLine, bodyColumn, raw: content };
 }
 
 /**

package/engine/infobox.mjs

@@ -277,6 +277,9 @@ export const GEAR_UNITS = Object.freeze({
  *   unit?: string, group?: string, phrase?: (value: any) => string}>>}
  */
 export const NOTE_FIELD_PRESENTATION = Object.freeze({
+    seeAlso: Object.freeze({
+        withheld: "navigation machinery, rendered in its own reading section",
+    }),
     ...DURATION_LABELS,
     ...GEAR_UNITS,
 

package/engine/journals.mjs

@@ -50,6 +50,7 @@
  */
 
 import log from "loglevel";
+import { seeAlsoEntries, seeAlsoMarkdown } from "./see-also.mjs";
 
 import path from "node:path";
 
@@ -825,7 +826,16 @@ export class Journals extends BasePackCompiler {
         return buildJournalEntry({
             id,
             name,
-            markdown,
+            markdown: [
+                markdown,
+                seeAlsoMarkdown(
+                    seeAlsoEntries(fm, (ref) => resolveReference(this.linkIndex, ref)),
+                    linkToUuid,
+                    1,
+                ),
+            ]
+                .filter(Boolean)
+                .join("\n\n"),
             resolveRole: (pathname) => roles.get(pathname),
             infoboxes: boxes.map((box) => ({
                 id: box.id,

package/engine/markdownlint-run.mjs

@@ -41,6 +41,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { markupFindings } from "./markup-validation.mjs";
 
 import ignore from "ignore";
 import {
@@ -447,8 +448,9 @@ function gitignoreHooks(root) {
  *   `config`, `ignores`, `gitignore` and `globs`.
  * @param {boolean} [params.fix=false] - Repair what markdownlint can, then
  *   report what remains.
- * @returns {Promise<{results: object[]}>} markdownlint results, each with its
+ * @returns {Promise<{results: object[], markup: object[]}>} markdownlint results, each with its
  *   `fileName` relative to `directory`, ordered by file, line and rule.
+ *   `markup` carries block syntax diagnostics with absolute filenames.
  * @throws {MarkdownConfigError} A configuration file the contract refuses.
  */
 export async function runMarkdownlint(params) {
@@ -530,12 +532,20 @@ export async function runMarkdownlint(params) {
     };
 
     const resultsByFile = new Map();
+    const markup = [];
     for (const [dir, files] of groups) {
         const options = await lintOptions(dir, files);
+        const malformed = new Set();
+        for (const file of files) {
+            const findings = markupFindings(fs.readFileSync(file, "utf8"), file);
+            if (findings.length) malformed.add(file);
+            markup.push(...findings);
+        }
         let results = await lint(options);
         if (fix) {
             const toFix = [];
             for (const file of files) {
+                if (malformed.has(file)) continue;
                 const fixable = (results[file] ?? []).filter((error) => error.fixInfo);
                 if (!fixable.length) continue;
                 const original = fs.readFileSync(file, "utf8");
@@ -563,5 +573,5 @@ export async function runMarkdownlint(params) {
             a.ruleNames[0].localeCompare(b.ruleNames[0]) ||
             order.get(a) - order.get(b),
     );
-    return { results: flat };
+    return { results: flat, markup };
 }

package/engine/markup-validation.mjs

@@ -0,0 +1,34 @@
+/*
+ * 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 { scanBlocks } from "./content-blocks.mjs";
+import { scanAlerts } from "./content-alerts.mjs";
+
+/**
+ * Validate authored block syntax with positions in the original file.
+ * Frontmatter is masked so literal YAML values cannot become body markup.
+ * @param {string} source - Complete Markdown source, optionally with frontmatter.
+ * @param {string} file - Diagnostic filename.
+ * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors.
+ */
+export function markupFindings(source, file) {
+    const body = String(source ?? "").replace(
+        /^\uFEFF?---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/,
+        (frontmatter) => frontmatter.replace(/[^\r\n]/g, " "),
+    );
+    return [...scanBlocks(body).errors, ...scanAlerts(body).errors].map((error) => ({
+        file,
+        ...error,
+        severity: "error",
+    }));
+}

package/engine/note-addresses.mjs

@@ -41,6 +41,7 @@ export {
 
 /** Structured positions whose Address is nested inside a declared container. */
 export const STRUCTURED_ADDRESSES = Object.freeze([
+    { path: ["data", "seeAlso", "*", "address"], shape: "value", lenient: true },
     {
         path: ["packFolder"],
         shape: "scalar-or-map",

package/engine/note-claims.mjs

@@ -666,11 +666,12 @@ function packsServing(config, docType, system) {
  * @param {string} absPath - The note's path, for the finding's position.
  * @param {string} type - The note's type.
  * @param {object} config - The resolved build configuration.
+ * @param {string} [raw] - Source text already read by the caller.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per
  *   discarded block.
  */
-function discardedSystemBlockFindings(fm, absPath, type, config) {
+function discardedSystemBlockFindings(fm, absPath, type, config, raw) {
     const findings = [];
     for (const system of SHIPPED_SYSTEMS) {
         if (!carriesSystemBlock(fm, system)) continue;
@@ -683,7 +684,7 @@ function discardedSystemBlockFindings(fm, absPath, type, config) {
         if (!packs || serving) continue;
         findings.push({
             file: absPath,
-            ...locateFrontmatterKey(absPath, system, undefined, { topLevel: true }),
+            ...locateFrontmatterKey(absPath, system, undefined, { topLevel: true, raw }),
             severity: /** @type {"error"} */ ("error"),
             type,
             message:
@@ -715,10 +716,16 @@ function discardedSystemBlockFindings(fm, absPath, type, config) {
  * @param {object} [opts] - Options.
  * @param {readonly object[]} [opts.records] - The corpus, derived once by the
  *   compile and handed in — required, for the reason above.
+ * @param {Map<string, {body: string, raw: string}>} [opts.parsed] - Already parsed
+ *   notes, keyed by file, for body checks and finding positions.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per note.
  */
-export function unclaimedNoteFindings(config = loadPackConfig(), sources, { records } = {}) {
+export function unclaimedNoteFindings(
+    config = loadPackConfig(),
+    sources,
+    { records, parsed } = {},
+) {
     const resolved = resolveSources(sources);
     const vocabulary = noteTypeVocabulary(resolved);
     const findings = [];
@@ -752,17 +759,19 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         // Asked first, and asked whatever the type's claim turns out to be: a
         // note whose documents all have packs may still carry a block none of
         // them reads, and that is invisible to every question below.
-        findings.push(...discardedSystemBlockFindings(fm, absPath, type, config));
+        findings.push(
+            ...discardedSystemBlockFindings(fm, absPath, type, config, parsed?.get(absPath)?.raw),
+        );
 
         // Every document this note produces, against the classes this
         // configuration has a pack for. Three outcomes, and the middle one is
         // the half-claimed one — invisible while the question is only "is anything
         // claiming this note", because the answer there is yes.
         const produces = documentClassesFor(type, resolved, {
-            // Lazy: only a doc-carrying type whose JournalEntry has nowhere to
-            // go asks, so a tree with a JournalEntry pack — which is most of
-            // them — reads no bodies at all.
-            hasProse: () => noteHasProse(absPath),
+            hasProse: () => {
+                const source = parsed?.get(absPath);
+                return source ? Boolean(source.body) : noteHasProse(absPath);
+            },
         });
         const missing = produces.filter((docType) => !configured.has(docType));
         const compiled = produces.filter((docType) => configured.has(docType));
@@ -791,7 +800,7 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         if (compiled.length) {
             findings.push({
                 file: absPath,
-                ...locateFrontmatterKey(absPath, "type", type),
+                ...locateFrontmatterKey(absPath, "type", type, { raw: parsed?.get(absPath)?.raw }),
                 severity: /** @type {"error"} */ ("error"),
                 type,
                 message: partialMessage(type, missing, compiled),
@@ -801,7 +810,7 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
 
         findings.push({
             file: absPath,
-            ...locateFrontmatterKey(absPath, "type", type),
+            ...locateFrontmatterKey(absPath, "type", type, { raw: parsed?.get(absPath)?.raw }),
             severity: /** @type {"error"} */ ("error"),
             type,
             message:

package/engine/note-package.mjs

@@ -62,12 +62,13 @@ export function searchableFrontmatter(fm, configured) {
  * @param {string} [options.absPath] - The note's file on disk, read only on the
  *   failing path to locate the offending line and column. The position rides on
  *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @param {string} [options.raw] - Source text already read by the caller.
  * @param {string} [options.configured] - The package this build compiles.
  *   Defaults to the configured `contentPackage`.
  * @returns {void}
  * @throws {Error} When the note declares the field.
  */
-export function assertNoDeclaredPackage(fm, { file, absPath, configured } = {}) {
+export function assertNoDeclaredPackage(fm, { file, absPath, configured, raw } = {}) {
     if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "package")) return;
 
     const target = configured ?? contentPackage();
@@ -84,10 +85,7 @@ export function assertNoDeclaredPackage(fm, { file, absPath, configured } = {})
             `\`contentPackage\` ("${target}", in package-build.config.yaml), ` +
             `and every note in the tree belongs to it.`,
     );
-    // Where the field is, so the caller's diagnostic opens on the line that has
-    // to be deleted. Read here rather than carried through every walk: this is
-    // the failing path, and the build stops on it.
-    const position = locateFrontmatterKey(absPath, "package");
+    const position = locateFrontmatterKey(absPath, "package", undefined, { raw });
     if (position) err.position = position;
     throw err;
 }

package/engine/note-vocabulary.mjs

@@ -72,6 +72,7 @@
  * @module
  */
 
+import { checkSeeAlso } from "./see-also.mjs";
 // The one charset, read rather than restated. A second spelling of the pattern
 // is how a disagreement between the three arises.
 import { ART_SLOTS } from "./art-slots.mjs";
@@ -203,7 +204,7 @@ import { checkSettlementTables } from "./settlement-tables.mjs";
  * @property {"pack"} [keys] - For a `scalar-or-map` field, what its keys name.
  *   `"pack"` means each is a pack this package declares, so a key naming none
  *   is a finding of its own: it addresses a hierarchy nothing will ever read.
- * @property {(note: object, opts: {index?: object}) => object[]} [check] - A
+ * @property {(note: object, opts: {index?: object, addressContext?: object}) => object[]} [check] - A
  *   check of the value beyond its shape, run by the frontmatter lint with the
  *   link index once the container has been checked. The lint stays
  *   vocabulary-agnostic this way: the rule lives beside the field that needs
@@ -1001,6 +1002,33 @@ export const NOTE_TOP_LEVEL_KEY_SET = Object.freeze(new Set(NOTE_TOP_LEVEL_KEYS)
  * @type {readonly DataFieldSpec[]}
  */
 export const SHARED_DATA_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "seeAlso",
+        kind: "list",
+        shape: "list of `{ address, gloss? }`",
+        entries: Object.freeze({
+            kind: "map",
+            shape: "`{ address, gloss? }`",
+            fields: Object.freeze([
+                Object.freeze({
+                    name: "address",
+                    kind: "address",
+                    shape: "a note Address",
+                    required: true,
+                    describe: "The note to read next.",
+                }),
+                Object.freeze({
+                    name: "gloss",
+                    kind: "string",
+                    shape: "a string",
+                    describe: "A short phrase saying why to follow the reference.",
+                }),
+            ]),
+        }),
+        check: checkSeeAlso,
+        describe:
+            "Deliberate cross-references in reading order, with optional glosses; shown on the site, in journals and in books.",
+    }),
     Object.freeze({
         name: "id",
         ...TEXT,

package/engine/pdf-build.mjs

@@ -120,6 +120,7 @@ import {
 import { artPathname, assetAddressIndex, pathnameRoles } from "./art-fields.mjs";
 import { embedRole } from "./content-embeds.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { seeAlsoEntries, seeAlsoMarkdown, seeAlsoWebLink } from "./see-also.mjs";
 import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
 import { eventNoteIndex } from "./event-fields.mjs";
 import { numberFigures, scanFigures } from "./content-figures.mjs";
@@ -1645,7 +1646,13 @@ async function buildBook(book, shared) {
         // Whether the entry is settled comes before anything it says: the
         // notice leads the leaf, before the authored body.
         const notice = isDraftNote(page.fm) ? draftNoticeTypst() : "";
-        const parts = [notice, prose, panel].filter((part) => part);
+        const references = seeAlsoMarkdown(
+            seeAlsoEntries(page.fm, (ref) => resolveInfoboxRef(gates.index, ref)),
+            seeAlsoWebLink,
+        );
+        const parts = [notice, prose, panel, references ? typst(references, {}) : ""].filter(
+            (part) => part,
+        );
         return parts.join("\n\n");
     };
 

package/engine/prose-lint.mjs

@@ -43,6 +43,7 @@ import {
     sharedPrettierDivergence,
     sharedPrettierOptionsFor,
 } from "./prose-config.mjs";
+import { markupFindings } from "./markup-validation.mjs";
 import { MarkdownConfigError, runMarkdownlint } from "./markdownlint-run.mjs";
 import { walkFiles } from "./walk-files.mjs";
 
@@ -152,6 +153,13 @@ export async function checkFormatting(root, opts = {}) {
             filepath: file,
         };
         const source = fs.readFileSync(file, "utf8");
+        if (["markdown", "mdx"].includes(info.inferredParser)) {
+            const syntaxErrors = markupFindings(source, file);
+            if (syntaxErrors.length) {
+                findings.push(...syntaxErrors);
+                continue;
+            }
+        }
 
         // A file Prettier cannot parse is a finding, not a crash. Its own CLI
         // reports the syntax error and carries on to the next file, and a
@@ -399,9 +407,9 @@ export async function lintMarkdown(root, opts = {}) {
     const { paths, fix = false } = opts;
     const directory = path.resolve(root);
 
-    let results;
+    let results, markup;
     try {
-        ({ results } = await runMarkdownlint({
+        ({ results, markup } = await runMarkdownlint({
             directory,
             globs: paths,
             fix,
@@ -430,8 +438,6 @@ export async function lintMarkdown(root, opts = {}) {
         };
     }
 
-    return {
-        findings: results.map((result) => toDiagnostic(directory, result)),
-        exitCode: results.length ? 1 : 0,
-    };
+    const findings = [...results.map((result) => toDiagnostic(directory, result)), ...markup];
+    return { findings, exitCode: findings.length ? 1 : 0 };
 }

package/engine/related-pages.mjs

@@ -27,11 +27,12 @@
  * `<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
+ * **Only a page of this site is an inferred 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.
+ * disagree about what a connection is. Deliberate see-also references also
+ * name pages in declared dependencies.
  *
  * @module
  */
@@ -46,6 +47,7 @@ import { homepageAddresses } from "./homepage.mjs";
  * @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} [gloss] Why the author recommends this page.
  * @property {string} type  The note's `type`, which the theme groups by.
  */
 
@@ -53,6 +55,7 @@ import { homepageAddresses } from "./homepage.mjs";
  * The `related` block one page publishes.
  *
  * @typedef {object} Related
+ * @property {RelatedEntry[]} [seeAlso] Deliberate references in authored order.
  * @property {RelatedEntry[]} backlinks Pages that link to this one.
  * @property {RelatedEntry[]} mentions  Pages this one links to.
  */
@@ -89,10 +92,11 @@ function byTypeThenTitle(a, b) {
  *   the source page's URL and the target page's.
  * @param {ReadonlyMap<string, RelatedEntry>} entries - Every page of this
  *   site, keyed by URL.
+ * @param {ReadonlyMap<string, RelatedEntry[]>} [deliberate] Authored references, including foreign destinations.
  * @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) {
+export function relatedPages(edges, entries, deliberate = new Map()) {
     /** @type {Map<string, {backlinks: Set<string>, mentions: Set<string>}>} */
     const graph = new Map();
     const node = (url) => {
@@ -120,6 +124,21 @@ export function relatedPages(edges, entries) {
     for (const [url, { backlinks, mentions }] of graph) {
         out.set(url, { backlinks: list(backlinks), mentions: list(mentions) });
     }
+    for (const [url, refs] of deliberate) {
+        const seen = new Set([url]);
+        const seeAlso = refs.filter((ref) => {
+            if (seen.has(ref.url)) return false;
+            seen.add(ref.url);
+            return true;
+        });
+        if (!seeAlso.length) continue;
+        const block = out.get(url) ?? { backlinks: [], mentions: [] };
+        out.set(url, {
+            seeAlso,
+            backlinks: block.backlinks.filter((ref) => !seen.has(ref.url)),
+            mentions: block.mentions.filter((ref) => !seen.has(ref.url)),
+        });
+    }
     return out;
 }