@heroiclands/package-build 23.7.1 → 23.9.0

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

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";
@@ -429,9 +430,11 @@ export function writeHomepages(outRoot, pages, config, { related, records, forei
  * @param {object} options
  * @param {object} options.config - The resolved build configuration.
  * @param {object[]} options.records - Content-index records.
+ * @param {Map<string, object[]>} [options.sqlTables] - Prepared directives,
+ *   whose emitted anchors belong to the pages they expand in.
  * @returns {object} The gate results and, when they pass, the built index.
  */
-export function siteGates(pages, findings, { config, records }) {
+export function siteGates(pages, findings, { config, records, sqlTables }) {
     const out = {
         // Always empty here: the homepage count is decided in `buildSite`
         // before the content walk, and a failing count returns without ever
@@ -463,7 +466,18 @@ export function siteGates(pages, findings, { config, records }) {
     out.unaddressable = unaddressableForeignPackages(foreign.index);
     if (out.unaddressable.length) return out;
 
-    out.index = buildSiteIndex(pages, {
+    const expanded =
+        sqlTables ?
+            pages.map((page) => ({
+                ...page,
+                body: expandContentTables(page.body ?? "", {
+                    source: page.file,
+                    sqlTables: sqlTables.get(page.file),
+                    pageLists: sqlTables.pageLists?.get(page.file),
+                }).markdown,
+            }))
+        :   pages;
+    out.index = buildSiteIndex(expanded, {
         package: config.contentPackage,
         foreignIndex: foreign.index,
         foreignReferences: foreign.references,
@@ -1095,7 +1109,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;
@@ -1363,6 +1380,7 @@ export function buildSite({ config, sqlTables } = {}) {
     const gates = siteGates([...pages, ...homepageEntries], content, {
         config: resolved,
         records: ctx.records,
+        sqlTables,
     });
     if (gatesFailed(gates)) {
         return {

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,