@heroiclands/package-build 23.1.1 → 23.2.0

package/engine/pdf-coverage.mjs

@@ -0,0 +1,188 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * What the declared books cover, as a pure function of their selections.
+ *
+ * Every book's filters run against one corpus before any book renders, so the
+ * questions that span books are answered once, here: which printable notes no
+ * book selects, which book is each selected note's home, and how many notes
+ * each book prints. Nothing is read or written; the build hands in the records
+ * and prints what comes back.
+ *
+ * - **A candidate** is a note a book can print — not a stub, not a `gm` note —
+ *   and not named by `pdf.unprinted`. A candidate no book selects is a finding
+ *   at the severity `pdf.coverage` names, and `off` emits none.
+ * - **The home book** is the first book in configuration order that selects the
+ *   note. A note several books select prints in each; a note selected twice
+ *   inside one book is still one book.
+ *
+ * @module engine/pdf-coverage
+ */
+
+import { isNoteRecord, isStub } from "./index-records.mjs";
+import { encodeAddresses } from "./address-values.mjs";
+import { isGmNote } from "./note-vocabulary.mjs";
+
+/** The message a note in no book carries. */
+export const UNCOVERED_MESSAGE =
+    "no book selects this note; add it to a book's query or to `pdf.unprinted`";
+
+/**
+ * Whether a record is a note a book can print.
+ *
+ * @param {object} record - An index record.
+ * @returns {boolean} False for an asset, a documentation row, a stub and a `gm` note.
+ */
+export function isPrintable(record) {
+    return isNoteRecord(record) && !isStub(record) && !isGmNote(record);
+}
+
+/**
+ * The key a note is counted by: its canonical address as text. An index record
+ * holds the address as a tuple and a row of the notes database as a string;
+ * both give the same key.
+ *
+ * @param {object} record - A printable record.
+ * @returns {string} The key.
+ */
+export function recordKey(record) {
+    const canonical = record?.address?.canonical;
+    return String(
+        canonical == null ?
+            (record?.file?.path ?? record?.shortcode ?? "")
+        :   encodeAddresses(canonical),
+    );
+}
+
+/**
+ * Whether a note has no resolved culture.
+ *
+ * @param {object} record - A record.
+ * @returns {boolean} True when `data.culture` is absent, null or empty.
+ */
+function lacksCulture(record) {
+    const culture = record?.data?.culture;
+    return culture == null || culture === "" || (Array.isArray(culture) && !culture.length);
+}
+
+/**
+ * Compute coverage, homes and the summary.
+ *
+ * @param {object} input - Options.
+ * @param {Array<{id: string, records: object[]}>} input.books - Each book's
+ *   selected records, in configuration order; a record selected twice appears
+ *   twice.
+ * @param {object[]} input.corpus - Every record in the index.
+ * @param {object[]} [input.unprinted] - The records `pdf.unprinted` selects.
+ * @param {"warning"|"error"|"off"} [input.mode] - `pdf.coverage`.
+ * @param {(record: object) => {file?: string, line?: number, column?: number}} [input.locate]
+ *   Where a note's `type:` line sits; a field it cannot supply is dropped.
+ * @returns {{findings: object[], homes: Map<string, string>, summary: object}}
+ *   The findings in corpus order, each note's home book id by address, and the
+ *   summary: per-book counts, totals and every note several books select.
+ */
+export function coverage({ books, corpus, unprinted = [], mode = "warning", locate = () => ({}) }) {
+    const shelved = new Set(unprinted.filter(isPrintable).map(recordKey));
+    const candidates = corpus.filter(
+        (record) => isPrintable(record) && !shelved.has(recordKey(record)),
+    );
+
+    /** @type {Map<string, string>} */
+    const homes = new Map();
+    /** @type {Map<string, {record: object, books: string[]}>} */
+    const carriers = new Map();
+    const perBook = books.map((book) => {
+        const distinct = new Map();
+        for (const record of book.records) {
+            const key = recordKey(record);
+            distinct.set(key, record);
+            if (!homes.has(key)) homes.set(key, book.id);
+            const carrier = carriers.get(key) ?? { record, books: [] };
+            if (!carrier.books.includes(book.id)) carrier.books.push(book.id);
+            carriers.set(key, carrier);
+        }
+        return {
+            id: book.id,
+            entries: book.records.length,
+            notes: distinct.size,
+            uncultured: [...distinct.values()].filter(lacksCulture).length,
+        };
+    });
+
+    const uncovered = candidates.filter((record) => !carriers.has(recordKey(record)));
+    const findings =
+        mode === "off" ?
+            []
+        :   uncovered.map((record) => ({
+                ...locate(record),
+                severity: mode,
+                message: UNCOVERED_MESSAGE,
+            }));
+
+    const order = new Map(books.map((book, index) => [book.id, index]));
+    const multiple = [...carriers.values()]
+        .filter((carrier) => carrier.books.length > 1)
+        .map((carrier) => ({
+            name: String(carrier.record?.name?.full ?? carrier.record?.shortcode ?? ""),
+            path: String(carrier.record?.file?.path ?? ""),
+            books: carrier.books,
+            home: carrier.books[0],
+        }))
+        .sort(
+            (a, b) =>
+                order.get(a.home) - order.get(b.home) ||
+                (a.path < b.path ? -1
+                : a.path > b.path ? 1
+                : 0),
+        );
+
+    return {
+        findings,
+        homes,
+        summary: {
+            books: perBook,
+            totals: {
+                candidates: candidates.length,
+                uncovered: uncovered.length,
+                unprinted: shelved.size,
+            },
+            multiple,
+        },
+    };
+}
+
+/**
+ * The summary as the lines the command prints.
+ *
+ * @param {object} summary - From {@link coverage}.
+ * @returns {string[]} One line per book, one for the totals, one per note
+ *   several books select.
+ */
+export function summaryLines(summary) {
+    const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+    return [
+        ...summary.books.map(
+            (book) =>
+                `${book.id}: ${plural(book.entries, "entry", "entries")}, ` +
+                `${plural(book.notes, "note", "notes")}, ${book.uncultured} without a culture`,
+        ),
+        `${plural(summary.totals.candidates, "printable note", "printable notes")}, ` +
+            `${summary.totals.uncovered} in no book, ${summary.totals.unprinted} in pdf.unprinted`,
+        ...summary.multiple.map(
+            (note) =>
+                `${note.name} (${note.path}) is printed by ${note.books.join(", ")}; ` +
+                `home: ${note.home}`,
+        ),
+    ];
+}

package/engine/pdf-index.mjs

@@ -88,11 +88,22 @@ function letterOf(key) {
 /**
  * Every term the book's index lists, in index order.
  *
+ * A book lists the notes it is home to. An entry `owns` rejects is a reprint of
+ * another book's note: it prints there, and its term belongs to its home
+ * book's index.
+ *
  * @param {object[]} entries - The plan's entries.
- * @returns {Array<{letter: string, name: string, slug: string, see?: string}>}
- *   Terms with `see` set for a cross-reference to the main name it points at.
+ * @param {object} [opts] - Options.
+ * @param {(entry: object) => boolean} [opts.owns] - Whether this book is the
+ *   entry's home. Every entry when absent.
+ * @param {Array<{slug: string, name: string, title: string, page: string|number}>} [opts.foreign] -
+ *   Notes another book prints, listed as `Name: Book title, p. N` once this
+ *   book mentions them.
+ * @returns {Array<{letter: string, name: string, slug: string, see?: string,
+ *   foreign?: {title: string, page: string}}>} Terms with `see` set for a
+ *   cross-reference to the main name it points at.
  */
-export function indexTerms(entries) {
+export function indexTerms(entries, { owns = () => true, foreign = [] } = {}) {
     const terms = [];
     const info = new Map();
     const nameByCanonical = new Map();
@@ -103,7 +114,7 @@ export function indexTerms(entries) {
         if (canonical && name) nameByCanonical.set(String(canonical), name);
     }
     for (const entry of entries ?? []) {
-        if (entry?.kind !== "note") continue;
+        if (entry?.kind !== "note" || !owns(entry)) continue;
         const slug = slugOf(entry.record);
         const name = String(entry.record?.name?.full ?? "").trim();
         if (!slug || !name || info.has(slug)) continue;
@@ -166,6 +177,18 @@ export function indexTerms(entries) {
         ...(term.main ? {} : { see: mainShown.get(term.slug) }),
         key: sortKey(shown[i]),
     }));
+    const listed = new Set(terms.map((term) => term.slug));
+    for (const other of foreign) {
+        const name = String(other.name ?? "").trim();
+        if (!other.slug || !name || listed.has(other.slug)) continue;
+        listed.add(other.slug);
+        keyed.push({
+            name,
+            slug: other.slug,
+            foreign: { title: String(other.title), page: String(other.page) },
+            key: sortKey(name),
+        });
+    }
     keyed.sort((a, b) => {
         const la = letterOf(a.key);
         const lb = letterOf(b.key);
@@ -190,9 +213,12 @@ export function indexTerms(entries) {
 /**
  * The Typst function definitions the markers and the chapter rely on.
  *
+ * @param {object} [opts] - Options.
+ * @param {boolean} [opts.seeAlso] - Whether the chapter may list notes another
+ *   book prints.
  * @returns {string} Typst source.
  */
-export function indexPreamble() {
+export function indexPreamble({ seeAlso = false } = {}) {
     return [
         // Zero-size and invisible; the label is what the chapter queries.
         "#let book-ix(key, main: false) = [#metadata((key: key, main: main)) <book-index>]",
@@ -218,10 +244,25 @@ export function indexPreamble() {
         "  }",
         "  let letter = none",
         "  for term in terms {",
+        ...(seeAlso ?
+            [
+                // A note another book prints is listed once this book mentions it.
+                '    let away = term.at("foreign", default: none)',
+                "    if away != none and by.at(term.slug, default: ()).len() == 0 { continue }",
+            ]
+        :   []),
         "    if term.letter != letter {",
         "      letter = term.letter",
         "      heading(level: 5, outlined: false, bookmarked: false)[#letter]",
         "    }",
+        ...(seeAlso ?
+            [
+                "    if away != none {",
+                "      par[#term.name: #emph[#away.title], p. #away.page]",
+                "      continue",
+                "    }",
+            ]
+        :   []),
         "    if term.see != none {",
         "      let main = merged(term.slug).filter(p => p.main)",
         "      let shown = if main.len() > 0 { link(main.first().loc)[#term.see] } else { term.see }",
@@ -241,16 +282,22 @@ export function indexPreamble() {
  *
  * @param {object[]} entries - The plan's entries.
  * @param {string} title - The book's title, which kicks the chapter.
+ * @param {object} [opts] - As {@link indexTerms}.
  * @returns {string} Typst source, or "" when the book has nothing to index.
  */
-export function indexChapter(entries, title) {
-    const terms = indexTerms(entries);
+export function indexChapter(entries, title, opts = {}) {
+    const terms = indexTerms(entries, opts);
     if (!terms.length) return "";
     const rows = terms.map(
         (term) =>
             `(letter: "${escapeString(term.letter)}", name: "${escapeString(term.name)}", ` +
             `slug: "${escapeString(term.slug)}", see: ${
                 term.see === undefined ? "none" : `"${escapeString(term.see)}"`
+            }${
+                term.foreign === undefined ?
+                    ""
+                :   `, foreign: (title: "${escapeString(term.foreign.title)}", ` +
+                    `page: "${escapeString(term.foreign.page)}")`
             })`,
     );
     return [

package/engine/pdf-pages.mjs

@@ -0,0 +1,247 @@
+/*
+ * 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
+ */
+
+/**
+ * Where each book prints each note, and how a book names a note another book
+ * prints.
+ *
+ * A PDF link cannot reach another file, so a reference to a note whose **home
+ * book** — the first book in configuration order that selects it — is another
+ * book is set as words: `Name (_Book title_, p. N)`. The page is the one the
+ * note's entry starts on in its home book. It is read from the laid-out
+ * document rather than predicted, so the build renders every book, measures the
+ * pages, and renders again with the table — see {@link module:engine/pdf-build}.
+ *
+ * - {@link homeEntries} says which book and which anchor each homed note has.
+ * - {@link readEntryPages} measures one book's `.typ` with `typst eval`, which
+ *   lays the document out and answers from its introspection. The page a
+ *   reader sees printed is the page counter at the entry's heading, so the
+ *   number needs neither the outline nor a `query` that cannot see layout.
+ * - {@link pageTable} is the table written as `pages.json`.
+ * - {@link elsewhereFor} is the lookup a book renders its cross-book
+ *   references from.
+ *
+ * @module engine/pdf-pages
+ */
+
+import { spawnSync } from "node:child_process";
+
+import { encodeAddresses } from "./address-values.mjs";
+import { recordKey } from "./pdf-coverage.mjs";
+import { labelFor } from "./pdf-render.mjs";
+
+/** What a reference prints for a page that has not been measured. */
+export const UNMEASURED_PAGE = "?";
+
+/**
+ * The Typst expression `typst eval` answers: every labelled heading and the
+ * page number the book prints for it.
+ */
+const PAGES_EXPRESSION =
+    'query(heading).filter(e => e.at("label", default: none) != none)' +
+    '.map(e => (str(e.at("label")), counter(page).at(e.location()).first()))';
+
+/**
+ * The arguments that measure a book, as data.
+ *
+ * Fonts are the compile's, because a face with other metrics lays out other
+ * pages.
+ *
+ * @param {string} typPath - The `.typ` file.
+ * @param {string[]} fontArgs - `--ignore-system-fonts --font-path …`, as the
+ *   compile passes them.
+ * @returns {string[]} The arguments, in order.
+ */
+export function evalArgs(typPath, fontArgs) {
+    return ["eval", "--in", typPath, ...fontArgs, PAGES_EXPRESSION];
+}
+
+/**
+ * Measure the page each labelled entry of a book starts on.
+ *
+ * @param {string} typPath - The `.typ` file.
+ * @param {string[]} fontArgs - The compile's font arguments.
+ * @param {string} [binary] - The Typst binary.
+ * @returns {{ok: boolean, message: string, pages: Map<string, number>}} The
+ *   printed page of every labelled heading, keyed by label.
+ */
+export function readEntryPages(typPath, fontArgs, binary = "typst") {
+    const fail = (message) => ({ ok: false, message, pages: new Map() });
+    let result;
+    try {
+        result = spawnSync(binary, evalArgs(typPath, fontArgs), {
+            encoding: "utf8",
+            maxBuffer: 1 << 28,
+        });
+    } catch (err) {
+        return fail(`could not run \`${binary}\`: ${err.message}`);
+    }
+    if (result.error) return fail(`could not run \`${binary}\`: ${result.error.message}`);
+    if (result.status !== 0) {
+        const detail = String(result.stderr || result.stdout || "")
+            .trim()
+            .split("\n")[0];
+        return fail(`\`${binary} eval\` failed: ${detail}`);
+    }
+    let rows;
+    try {
+        rows = JSON.parse(result.stdout);
+    } catch {
+        return fail(`\`${binary} eval\` printed no page table`);
+    }
+    return {
+        ok: true,
+        message: "",
+        pages: new Map(rows.map(([label, page]) => [String(label), Number(page)])),
+    };
+}
+
+/**
+ * Every note that has a home book, with the anchor its entry carries there.
+ *
+ * **A note a book prints twice has one page**: the first entry, which is the
+ * one the book's links reach. A note a book reprints from another book's home
+ * keeps its home book's page here, because the home is the first book in
+ * configuration order that selects it.
+ *
+ * @param {object} input - Options.
+ * @param {Array<{id: string, title: string, plan: {entries: object[]}}>} input.books -
+ *   The books that render, in configuration order.
+ * @param {Map<string, string>} input.homes - Each note's key → its home book's
+ *   id, from {@link module:engine/pdf-coverage.coverage}.
+ * @returns {Array<{key: string, book: string, title: string, anchor: string,
+ *   record: object, slug: string, aliases: string[]}>} One per homed note, in book order and
+ *   then entry order.
+ */
+export function homeEntries({ books, homes }) {
+    const found = [];
+    const claimed = new Set();
+    for (const book of books) {
+        for (const entry of book.plan.entries) {
+            if (entry.kind !== "note") continue;
+            const key = recordKey(entry.record);
+            if (claimed.has(key) || homes.get(key) !== book.id) continue;
+            claimed.add(key);
+            const record = entry.record;
+            found.push({
+                key,
+                book: book.id,
+                title: book.title,
+                anchor: entry.anchor,
+                record,
+                slug: String(record?.address?.slug ?? record?.shortcode ?? ""),
+                aliases: [record?.address?.canonical, record?.documentation]
+                    .filter(Boolean)
+                    .map((address) => encodeAddresses(address)),
+            });
+        }
+    }
+    return found;
+}
+
+/**
+ * The table written as `pages.json`.
+ *
+ * @param {ReturnType<typeof homeEntries>} entries - From {@link homeEntries}.
+ * @param {Map<string, Map<string, number>>} measured - Book id → label → page.
+ * @returns {Record<string, {book: string, page: number}>} Keyed by the note's
+ *   key, in sorted key order. A note whose entry was not measured is absent.
+ */
+export function pageTable(entries, measured) {
+    const table = {};
+    const sorted = [...entries].sort((a, b) =>
+        a.key < b.key ? -1
+        : a.key > b.key ? 1
+        : 0,
+    );
+    for (const entry of sorted) {
+        const page = measured.get(entry.book)?.get(labelFor(entry.anchor));
+        if (page !== undefined) table[entry.key] = { book: entry.book, page };
+    }
+    return table;
+}
+
+/**
+ * The notes whose page differs between two tables.
+ *
+ * @param {Record<string, {book: string, page: number}>} before - A table.
+ * @param {Record<string, {book: string, page: number}>} after - A later one.
+ * @returns {Array<{key: string, book: string, before: number|undefined,
+ *   after: number|undefined}>} In sorted key order.
+ */
+export function movedPages(before, after) {
+    const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
+    return keys
+        .filter((key) => before[key]?.page !== after[key]?.page)
+        .map((key) => ({
+            key,
+            book: (after[key] ?? before[key]).book,
+            before: before[key]?.page,
+            after: after[key]?.page,
+        }));
+}
+
+/**
+ * The lookup one book renders its cross-book references from.
+ *
+ * A note the book prints (a reprint included) is never in it: its link stays an
+ * internal destination. Keys are the three forms the book's own link map
+ * answers to — slug, canonical address and documentation address.
+ *
+ * `get` counts the references it answers, which is how the build knows whether
+ * a measured pass can change anything.
+ *
+ * @param {object} input - Options.
+ * @param {ReturnType<typeof homeEntries>} input.entries - From {@link homeEntries}.
+ * @param {string} input.book - The id of the book that renders.
+ * @param {Map<string, string>} input.printed - The book's own link map.
+ * @param {Record<string, {book: string, page: number}>} [input.table] - The
+ *   measured pages; every page is {@link UNMEASURED_PAGE} when absent.
+ * @param {boolean} [input.seeAlso] - Whether the book's index lists the notes
+ *   it mentions here (`pdf.indexSeeAlso`). `listed` is empty when not.
+ * @returns {{used: number, seeAlso: boolean,
+ *   listed: Array<{slug: string, name: string, title: string, page: string|number}>,
+ *   get: (key: string) => ({slug: string, title: string, page: string|number}|undefined)}}
+ *   The lookup. `listed` is every note another book prints, for the index to
+ *   show those this book mentions.
+ */
+export function elsewhereFor({ entries, book, printed, table, seeAlso = false }) {
+    const map = new Map();
+    const listed = [];
+    for (const entry of entries) {
+        if (entry.book === book) continue;
+        const keys = [entry.slug, ...entry.aliases].filter((key) => key && !printed.has(key));
+        const page = table?.[entry.key]?.page ?? UNMEASURED_PAGE;
+        for (const key of keys) {
+            if (!map.has(key)) map.set(key, { slug: entry.slug, title: entry.title, page });
+        }
+        if (seeAlso && entry.slug && !printed.has(entry.slug)) {
+            listed.push({
+                slug: entry.slug,
+                name: String(entry.record?.name?.full ?? "").trim(),
+                title: entry.title,
+                page,
+            });
+        }
+    }
+    return {
+        used: 0,
+        seeAlso,
+        listed,
+        get(key) {
+            const found = map.get(key);
+            if (found) this.used += 1;
+            return found;
+        },
+    };
+}