@heroiclands/package-build 22.20.0 → 22.22.0

package/engine/page-lists.mjs

@@ -0,0 +1,358 @@
+/*
+ * 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
+ */
+
+/**
+ * Page lists: a tag in, the pages carrying it out.
+ *
+ * ````markdown
+ * ```pagelist {tag="key-concept" descriptions=true}
+ * ```
+ * ````
+ *
+ * **A group expressed by intent.** A hand-enumerated list of links drifts — a
+ * page is written and nobody adds it to the landing that should name it. A page
+ * list names the *tag* instead: tag a page and it files itself, untag it and it
+ * leaves.
+ *
+ * **It is a sibling of the `sql` content table, and answered the same way.**
+ * The pages are resolved over the content index ahead of the synchronous
+ * expansion pass, then
+ * {@link module:engine/content-tables.expandContentTables} splices the result
+ * in as ordinary Markdown — a bullet list of wikilinks. So each surface's own
+ * wikilink resolver turns them into what that surface links with: a compendium
+ * UUID in Foundry, a page URL on the web and in the book. One authored
+ * construct, three real lists.
+ *
+ * **Attributes, never a body.** Everything the directive says about itself is
+ * said in the braced attribute grammar every other body extension uses, so
+ * there is one grammar to learn and one validator to maintain. The fence holds
+ * nothing, and text written inside it is reported rather than ignored.
+ *
+ * @module
+ */
+
+import { FENCE_LINE, parseHeaderArgs } from "./code-fences.mjs";
+import { booleanAttribute } from "./extension-attributes.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+import { NOTE_VOCABULARY, hasTag } from "./note-vocabulary.mjs";
+
+/** The fence language that opens a page list. */
+export const PAGE_LIST_LANGUAGE = "pagelist";
+
+/**
+ * The orders a page list may come out in.
+ *
+ * Ordering is about output rather than about the pages, so it is an attribute
+ * rather than something read off a note. `name` is alphabetical, case and
+ * accents folded; `type` groups the note types and orders by name inside each.
+ *
+ * @type {readonly string[]}
+ */
+export const PAGE_LIST_SORTS = Object.freeze(["name", "type"]);
+
+/**
+ * The attributes a page-list fence takes, with what each one is for.
+ *
+ * **This is the one list.** The fence is validated against it, the authoring
+ * document's table is generated from it, and the reference is checked against
+ * it — so an attribute added here is one both documents describe, and anything
+ * else an author writes is reported by name.
+ *
+ * @type {Readonly<Record<string, Readonly<{value: string, default: string, summary: string}>>>}
+ */
+export const PAGE_LIST_ATTRIBUTES = Object.freeze({
+    tag: Object.freeze({
+        value: "a tag",
+        default: "required",
+        summary:
+            "The tag a page carries to join the list. Matched the way `tags:` is read — " +
+            "case and a leading `#` are not significant, the spelling of the tag itself is.",
+    }),
+    type: Object.freeze({
+        value: "a note type",
+        default: "every type",
+        summary:
+            "Restricts the list to one note type. A page's address is `<type>-<shortcode>`, " +
+            "so the type is what divides the corpus into kinds of page.",
+    }),
+    sort: Object.freeze({
+        value: "`name` or `type`",
+        default: "`name`",
+        summary:
+            "The order the pages come out in. `name` is alphabetical; `type` groups the " +
+            "note types and orders by name within each.",
+    }),
+    descriptions: Object.freeze({
+        value: "`true` or `false`",
+        default: "`false`",
+        summary:
+            "Whether each page's `description` follows its link. A page that states none " +
+            "carries its link alone.",
+    }),
+    "allow-empty": Object.freeze({
+        value: "`true` or `false`",
+        default: "`false`",
+        summary:
+            "Whether a tag carried by no page is allowed. It is a finding otherwise, " +
+            "because a heading with nothing under it is how a misspelled tag goes unnoticed.",
+    }),
+});
+
+/** The note types a `type` attribute may name, from the vocabulary itself. */
+const noteTypes = () => Object.keys(NOTE_VOCABULARY);
+
+/**
+ * Every `pagelist` fence in a markdown body, with the position each occupies.
+ *
+ * Positions are 0-based lines into the body as given, which is what a
+ * diagnostic about a directive needs and what the expander uses to splice
+ * results back in.
+ *
+ * **A malformed directive is still a directive.** It is returned carrying its
+ * problems rather than skipped, so the expander finds a prepared answer at its
+ * ordinal and reports the fault where the fence sits. That includes a fence
+ * nobody closed, which the author meant as a directive and which would
+ * otherwise swallow the rest of the note into a code block.
+ *
+ * @param {string} markdown - The note body, frontmatter already stripped.
+ * @returns {Array<{line: number, close: number, indent: string, tag: string,
+ *   type: string, sort: string, descriptions: boolean, allowEmpty: boolean,
+ *   problems: string[], block: string}>} One entry per fence, in document order.
+ */
+export function findPageListBlocks(markdown) {
+    const lines = String(markdown ?? "").split("\n");
+    const blocks = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const opening = FENCE_LINE.exec(lines[i]);
+        if (!opening) continue;
+        const [, indent, marker, info] = opening;
+        const closer = new RegExp(`^[ \\t]*${marker[0]}{${marker.length},}[ \\t]*$`);
+        let close = i + 1;
+        while (close < lines.length && !closer.test(lines[close])) close += 1;
+        const { language, args, problems } = parseHeaderArgs(info);
+        if (language !== PAGE_LIST_LANGUAGE) {
+            // Not ours, but still a fence: skip its body so a directive shown
+            // as an example inside a longer fence is never read as one.
+            i = close;
+            continue;
+        }
+        const errors = [...problems];
+        for (const key of Object.keys(args)) {
+            if (!Object.hasOwn(PAGE_LIST_ATTRIBUTES, key))
+                errors.push(`${key} is not a page-list attribute`);
+        }
+        const tag = String(args.tag ?? "").trim();
+        if (!tag) errors.push("a pagelist fence needs a tag attribute");
+        const type = String(args.type ?? "").trim();
+        if (type && !noteTypes().includes(type))
+            errors.push(`type ${JSON.stringify(type)} is not a note type`);
+        const sort = String(args.sort ?? PAGE_LIST_SORTS[0]).trim();
+        if (!PAGE_LIST_SORTS.includes(sort))
+            errors.push(`sort needs ${PAGE_LIST_SORTS.join(" or ")}`);
+        const flags = { descriptions: false, allowEmpty: false };
+        for (const [key, field] of [
+            ["descriptions", "descriptions"],
+            ["allow-empty", "allowEmpty"],
+        ]) {
+            if (!Object.hasOwn(args, key)) continue;
+            try {
+                flags[field] = booleanAttribute(args[key], key);
+            } catch (error) {
+                errors.push(error.message);
+            }
+        }
+        if (close >= lines.length) errors.push("a pagelist fence needs a closing fence");
+        else if (
+            lines
+                .slice(i + 1, close)
+                .join("\n")
+                .trim()
+        )
+            errors.push("a pagelist fence takes no body; its tag is the tag attribute");
+        blocks.push({
+            line: i,
+            close,
+            indent,
+            tag,
+            type,
+            sort,
+            ...flags,
+            problems: errors,
+            block: lines.slice(i, Math.min(close + 1, lines.length)).join("\n"),
+        });
+        i = close;
+    }
+    return blocks;
+}
+
+/** A page's sort key, folded so a circumflex sorts with its letter. */
+const nameKey = (record) => String(record?.nameAscii ?? record?.name?.full ?? "").toLowerCase();
+
+/** The address a page is addressed by, as a stable tiebreak. */
+const slugKey = (record) => String(record?.address?.slug ?? "");
+
+/**
+ * By name, tiebroken on address.
+ *
+ * The tiebreak keeps the list stable where two pages share a name, which a
+ * corpus of a few thousand eventually does.
+ */
+function byName(a, b) {
+    const an = nameKey(a);
+    const bn = nameKey(b);
+    if (an !== bn) return an < bn ? -1 : 1;
+    const as = slugKey(a);
+    const bs = slugKey(b);
+    return (
+        as < bs ? -1
+        : as > bs ? 1
+        : 0
+    );
+}
+
+/** By note type, then by name within it. */
+function byType(a, b) {
+    const at = String(a?.type ?? "");
+    const bt = String(b?.type ?? "");
+    if (at !== bt) return at < bt ? -1 : 1;
+    return byName(a, b);
+}
+
+const COMPARATORS = Object.freeze({ name: byName, type: byType });
+
+/** A link label, with the characters a wikilink reads replaced. */
+function linkLabel(record) {
+    const written = String(record?.name?.full ?? record?.shortcode ?? "")
+        // A wikilink's own separator, so a name carrying one would truncate
+        // the label at it.
+        .replace(/\|/g, "/")
+        .replace(/[\r\n]+/g, " ")
+        .trim();
+    return written || slugKey(record);
+}
+
+/** A description on one line, so a list item stays a list item. */
+const oneLine = (value) => (typeof value === "string" ? value.replace(/[\r\n]+/g, " ").trim() : "");
+
+/**
+ * The pages a directive selects, as index records.
+ *
+ * A **stub** is left out: an empty body publishes no page, which the index says
+ * by holding no address, so there is nothing for the list to link to. A
+ * documentation journal and an asset are not pages an author tagged, which
+ * {@link module:engine/index-records.isNoteRecord} already answers.
+ *
+ * @param {object[]} records - Content-index records.
+ * @param {{tag: string, type: string}} directive - From {@link findPageListBlocks}.
+ * @returns {object[]} The selected records, unordered.
+ */
+export function pagesForList(records, { tag, type }) {
+    return (records ?? []).filter((record) => {
+        if (!isNoteRecord(record) || !record.address) return false;
+        if (type && record.type !== type) return false;
+        return hasTag(record, tag);
+    });
+}
+
+/**
+ * Render one directive's answer as markdown.
+ *
+ * **The emitted link is the page's `address.slug`** — the `type-shortcode`
+ * form a wikilink resolves — which is exactly what a table's `_ref` cell
+ * writes. A short form names the package the link is written in, so it is
+ * unambiguous for a list of this package's own pages, and it resolves to the
+ * note's **page** on each surface: a compendium journal in Foundry, a URL on
+ * the web and in the book. An item note's page is its documentation journal,
+ * and the short form reaches it the way prose does.
+ *
+ * @param {object[]} records - Content-index records.
+ * @param {object} directive - From {@link findPageListBlocks}.
+ * @returns {{markdown: string, pages: number}} The list, and how many pages
+ *   are in it.
+ */
+export function renderPageList(records, directive) {
+    const selected = pagesForList(records, directive).sort(
+        COMPARATORS[directive.sort] ?? COMPARATORS.name,
+    );
+    const rows = selected.map((record) => {
+        const link = `- [[${slugKey(record)}|${linkLabel(record)}]]`;
+        if (!directive.descriptions) return link;
+        const summary = oneLine(record.description);
+        return summary ? `${link} — ${summary}` : link;
+    });
+    return { markdown: rows.join("\n"), pages: selected.length };
+}
+
+/**
+ * What the expander prints where a tag selects nothing.
+ *
+ * The tag is quoted, because a misspelled tag is the whole of what goes wrong
+ * here and a reader needs to see the exact spelling the directive asked for.
+ */
+function emptyMessage({ tag, type }) {
+    const scope = type ? ` of type ${JSON.stringify(type)}` : "";
+    return (
+        `page list selects no page; no page${scope} carries the tag ${JSON.stringify(tag)}. ` +
+        "Check the spelling, tag some pages, or state {allow-empty=true}"
+    );
+}
+
+/**
+ * Answer every `pagelist` directive in a set of note bodies, ahead of expansion.
+ *
+ * **Why a separate pass.** The same reason the SQL tables have one:
+ * {@link module:engine/content-tables.expandContentTables} is synchronous and
+ * exported, and the corpus is enumerated once by whoever already holds it
+ * rather than derived again inside a renderer. A page list needs no database —
+ * it is a filter over the records — so preparing one costs a walk of what the
+ * caller already has.
+ *
+ * **Keyed by note, then by the directive's ordinal within it**, not by its
+ * line: the passes do not agree on what a body is, and trim it differently,
+ * but a directive's position in the sequence of fences is the same in each.
+ *
+ * A malformed directive is recorded rather than thrown, so one bad fence costs
+ * its own list and not the whole build's report.
+ *
+ * @param {object[]} records - Content-index records, already narrowed to the
+ *   audience the surface publishes to.
+ * @param {Array<{source: string, markdown: string}>} sources - The bodies to scan.
+ * @returns {Map<string, Array<{markdown?: string, pages?: number, empty?: string,
+ *   reason?: string, allowEmpty: boolean}>>} Note to results, in document order.
+ */
+export function preparePageLists(records, sources) {
+    const prepared = new Map();
+    for (const { source, markdown } of sources ?? []) {
+        const blocks = findPageListBlocks(markdown);
+        if (!blocks.length) continue;
+        const forNote = [];
+        prepared.set(source, forNote);
+        for (const block of blocks) {
+            if (block.problems.length) {
+                forNote.push({
+                    reason: block.problems.join("; "),
+                    allowEmpty: block.allowEmpty,
+                });
+                continue;
+            }
+            const { markdown: rendered, pages } = renderPageList(records, block);
+            forNote.push({
+                markdown: rendered,
+                pages,
+                empty: emptyMessage(block),
+                allowEmpty: block.allowEmpty,
+            });
+        }
+    }
+    return prepared;
+}

package/engine/pdf-build.mjs

@@ -97,12 +97,12 @@ import {
 import { resolveInfoboxRef, wikiContext } from "./site-index.mjs";
 import { resolveWebWikilinks } from "./web-wikilinks.mjs";
 import { linkFindingMessage } from "./wikilink-syntax.mjs";
+import { positionOfLiteral } from "./diagnostics.mjs";
 import { artPathname, assetAddressIndex } from "./art-fields.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
-import { renderSecretBlocks } from "./content-secrets.mjs";
-import { scanAdmonitions } from "./content-admonitions.mjs";
 import { numberCaptions, scanCaptions } from "./content-captions.mjs";
+import { collectAnchors } from "./anchors.mjs";
 import { protectCode } from "./code-fences.mjs";
 import { imagesIn, parseImageDirective } from "./content-images.mjs";
 import {
@@ -378,6 +378,23 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     // addresses collide would print the wrong entry under the right name.
     const scheme = resolved.publish.address;
     const base = resolved.site.base || `/${resolved.contentPackage}/`;
+    // Where the pages this book cites are served. A page's address is written
+    // from the root of a site, which is right everywhere on the web and nowhere
+    // in a PDF, so the book resolves each one against this — see
+    // {@link module:engine/pdf-render.absolutePageUrl}. `package.json`'s
+    // `homepage` is the one absolute address a build holds, and the site reads
+    // its own `baseURL` from it, so the book and the website cannot disagree
+    // about where a page is.
+    const site = typeof resolved.homepage === "string" ? resolved.homepage : "";
+    if (!site) {
+        findings.push({
+            file: "package.json",
+            severity: "error",
+            message:
+                "`homepage` is not declared, so a page the book cites is set as a path " +
+                `rather than an address a reader can follow — add \`https://www.heroiclands.org/${resolved.contentPackage}/\``,
+        });
+    }
     const ctx = {
         packages: new Set(
             resolved.site.packages.length ? resolved.site.packages : [resolved.contentPackage],
@@ -528,15 +545,11 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     for (const file of resolved.pdf.front) {
         try {
             const scan = scanCaptions(fs.readFileSync(file, "utf8"));
+            // Numbered here, because a number runs across the whole book and only
+            // this loop knows the order; what is *wrong* with a caption is
+            // reported by the renderer, which reads every one of the three kinds
+            // of markdown a book is made of.
             frontCaptions.set(file, numberCaptions(scan.captions, captionCounts));
-            for (const error of scan.errors)
-                findings.push({
-                    file,
-                    line: error.line,
-                    column: error.column,
-                    severity: "error",
-                    message: error.message,
-                });
         } catch {
             // The rendering pass reports an unreadable front-matter file.
         }
@@ -555,13 +568,21 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             linkable: (d) => Boolean(d.fm.shortcode),
             source: src,
             sqlTables: sqlTables?.get(page.file),
+            pageLists: sqlTables?.pageLists?.get(page.file),
             self: { fm: page.fm, path: page.relPath },
         });
+        // A content-table finding states its `reason`, its 0-based line within
+        // the body and its column, exactly as the site build reports them.
+        // Reading it as `message` yields `[object Object]` and discards the
+        // position, which is the one thing a reader needs to find the fence.
         for (const err of errors) {
             findings.push({
                 file: page.file,
+                ...(typeof err.line === "number" ?
+                    { line: (page.bodyLine ?? 1) + err.line, column: err.column }
+                :   {}),
                 severity: "error",
-                message: String(err.message ?? err),
+                message: err.reason ?? String(err.message ?? err),
             });
         }
         const linkCtx = wikiContext(gates.index, {
@@ -577,14 +598,10 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         linkCtx.captionLabels = new Map(
             numberedCaptions.map((caption) => [caption.id, caption.label]),
         );
-        for (const error of captionScan.errors)
-            findings.push({
-                file: page.file,
-                line: (page.bodyLine ?? 1) + (lineMap[error.line - 1]?.line ?? error.line - 1),
-                column: error.column,
-                severity: "error",
-                message: error.message,
-            });
+        // This page's own anchors, so a `[[#slug]]` self-link is checked
+        // against what the page actually declares, exactly as the site build
+        // checks it.
+        linkCtx.anchors = new Set(collectAnchors(markdown).map((anchor) => anchor.slug));
         linkCtx.output = "book";
         // Code fences are protected for the same reason every other pass
         // protects them: a wikilink shown as an example is prose about a
@@ -600,37 +617,42 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         const resolvedBody = protectCode(expressions.markdown, (text) =>
             resolveWebWikilinks(pass.beforeLinks ? pass.beforeLinks(text, page) : text, linkCtx),
         );
+        // A link finding carries the authored link and which occurrence of it
+        // this was, which is exactly what locates it: the position is implicit
+        // in the literal the pass matched, so it is recovered by searching the
+        // note for it rather than dropped. Read once per page, and only when
+        // there is a finding to locate.
+        let raw;
+        const noteSource = () => {
+            if (raw === undefined) {
+                try {
+                    raw = fs.readFileSync(page.file, "utf8");
+                } catch {
+                    raw = "";
+                }
+            }
+            return raw;
+        };
+        // An **error**, as it is from the pack build and from the site build. One
+        // authored address that resolves nowhere is one defect, and a reader of
+        // the book is the one reader who cannot act on it: a page printing
+        // `(unresolved link)` has shipped the mistake to somebody holding paper.
+        // The source is written and the compiler still runs, so the finding is a
+        // report on a book that was built, exactly as the site writes its pages
+        // and refuses the run.
         for (const err of wikiErrors) {
             findings.push({
                 file: page.file,
-                severity: "warning",
+                ...positionOfLiteral(noteSource(), err.link, err.occurrence),
+                severity: "error",
                 // A link finding names a `reason` from the shared table and no
                 // sentence of its own; an embed's directive complaint carries
                 // the sentence instead.
                 message: err.message ?? (err.reason ? linkFindingMessage(err) : String(err)),
             });
         }
-        const secrets = renderSecretBlocks(resolvedBody, "book");
-        for (const error of renderSecretBlocks(page.body, "book").errors) {
-            findings.push({
-                file: page.file,
-                line: (page.bodyLine ?? 1) + error.line - 1,
-                column: error.column,
-                severity: "error",
-                message: error.message,
-            });
-        }
-        for (const error of scanAdmonitions(page.body).errors) {
-            findings.push({
-                file: page.file,
-                line: (page.bodyLine ?? 1) + error.line - 1,
-                column: error.column,
-                severity: "error",
-                message: error.message,
-            });
-        }
-        stageImages(secrets.markdown, page.file, columns);
-        const prose = markdownToTypst(secrets.markdown, {
+        stageImages(resolvedBody, page.file, columns);
+        const prose = markdownToTypst(resolvedBody, {
             md,
             links: plan.links,
             glyphs,
@@ -638,6 +660,12 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             headingOffset,
             anchorPrefix,
             captions: numberedCaptions,
+            url: site,
+            findings,
+            file: page.file,
+            bodyLine: page.bodyLine,
+            lineMap,
+            prepared: true,
         });
         // Infoboxes follow the authored body within this note's entry.
         const boxes = noteInfoboxes(page.fm, {
@@ -646,7 +674,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             dates: gates.index.dateContext,
         });
         const panel = infoboxesToTypst(boxes, {
-            link: (value) => linkToTypst(value, plan.links, labelFor),
+            link: (value) => linkToTypst(value, plan.links, labelFor, site),
         });
         // Whether the entry is settled comes before anything it says: the
         // notice leads the leaf, before the authored body.
@@ -699,6 +727,9 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                     headingOffset: entry.depth,
                     anchorPrefix: entry.anchor,
                     captions: numberCaptions(scanCaptions(text).captions, captionCounts),
+                    url: site,
+                    findings,
+                    file,
                 }),
             );
         }
@@ -724,6 +755,9 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                 images,
                 footnotePrefix: `footnote-front-${index + 1}`,
                 captions: frontCaptions.get(file),
+                url: site,
+                findings,
+                file,
             });
         } catch {
             findings.push({