@heroiclands/package-build 25.5.4 → 25.6.0

package/engine/settlement-terms.mjs

@@ -0,0 +1,118 @@
+/*
+ * 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
+ */
+
+/** Dependency-free settlement row declarations. @module */
+/** The generated heading. */
+export const SETTLEMENTS_HEADING = "Settlements";
+
+/** Rendered columns, in their fixed order; Held by and For appear when a row states them. */
+export const SETTLEMENT_COLUMNS = Object.freeze([
+    Object.freeze({ name: "Name", required: true }),
+    Object.freeze({ name: "Market", required: true }),
+    Object.freeze({ name: "People", required: true }),
+    Object.freeze({ name: "Held by", required: false }),
+    Object.freeze({ name: "For", required: false }),
+]);
+
+/** The closed row fields; existing subjects use native Addresses. */
+export const SETTLEMENT_ROW_FIELDS = Object.freeze(
+    [
+        {
+            name: "place",
+            kind: "address",
+            shape: "a place Address",
+            describe: "The existing settlement note; exclusive with name.",
+        },
+        {
+            name: "name",
+            kind: "string",
+            shape: "plain text",
+            describe: "A settlement without a note; exclusive with place.",
+        },
+        {
+            name: "market",
+            kind: "number",
+            required: true,
+            shape: "a market class, 1 to 6",
+            describe: "What trade the settlement supports.",
+        },
+        {
+            name: "population",
+            kind: "number",
+            required: true,
+            shape: "a positive whole number",
+            describe: "How many people live here.",
+        },
+        {
+            name: "heldBy",
+            kind: "address",
+            shape: "an affiliation or being Address",
+            describe:
+                "What holds the settlement's land, where its culture holds land; what the holder is says how it is held.",
+        },
+        {
+            name: "for",
+            kind: "string",
+            shape: "plain text",
+            describe: "Optional reason the settlement exists.",
+        },
+    ].map(Object.freeze),
+);
+
+/** The place vocabulary's single settlement declaration. */
+export const SETTLEMENTS_FIELD = Object.freeze({
+    name: "settlements",
+    kind: "map",
+    shape: "{ rows, tail }",
+    fields: Object.freeze([
+        {
+            name: "rows",
+            kind: "list",
+            required: true,
+            shape: "a list of settlement rows",
+            entries: { kind: "map", shape: "a settlement row", fields: SETTLEMENT_ROW_FIELDS },
+            describe: "One row per settlement.",
+        },
+        {
+            name: "tail",
+            kind: "string",
+            required: true,
+            shape: "a nonempty sentence",
+            describe: "What the table leaves out.",
+        },
+    ]),
+    describe:
+        "A region's settlement rows and the sentence stating what they leave out; the table is generated from this declaration.",
+});
+
+/** Every semantic finding, named once for the reference and its guards. */
+export const SETTLEMENT_TABLE_RULES = Object.freeze(
+    [
+        [
+            "body settlements table",
+            "A body table under Settlements is refused; declare data.settlements.",
+        ],
+        ["settlements shape", "A region declares rows and tail, with one name or place per row."],
+        ["unresolved settlement reference", "A place or heldBy Address does not resolve."],
+        ["market class", "A row's market is not an integer class from 1 to 6."],
+        ["people figure", "A row's population is not a positive whole number."],
+        ["not a holder", "A heldBy Address names neither an affiliation nor a being."],
+        ["not a settlement", "A place Address names a subject that is not a place."],
+        ["figure disagrees", "A linked population differs from its note, or the note states none."],
+        ["market disagrees", "A linked market differs from its note, or the note states none."],
+        ["unlinked settlement", "A plain name has an existing settlement note in this region."],
+        ["missing row", "A covered settlement note has no row."],
+        ["duplicate settlement", "A settlement has another row here or in another region."],
+        ["no tail", "The declaration has no sentence stating what it leaves out."],
+    ].map(([name, describe]) => Object.freeze({ name, describe })),
+);

package/engine/site-build.mjs

@@ -51,6 +51,7 @@
  * @module
  */
 
+import { scanPageBreaks } from "./page-breaks.mjs";
 import { scanAlerts } from "./content-alerts.mjs";
 import { positionOfYamlPath } from "./diagnostics.mjs";
 import { decodeNoteAddresses, noteAddressContext } from "./note-addresses.mjs";
@@ -274,11 +275,9 @@ export function collectContentPages(contentBase, ctx) {
             // not use it: a note is addressed as `type/shortcode` wherever it
             // is filed.
             tld: rel.split(path.sep)[0],
-            // Location below the content root, POSIX-separated — what a
-            // generated table reads as `file.path` and scopes on with `FROM`.
+            // Location below the content root, POSIX-separated.
             relPath: rel.split(path.sep).join("/"),
-            // The immediate source subfolder — what a content table reads as
-            // `file.folder`, and the page's `kbfolder`.
+            // The immediate source subfolder — the page's `kbfolder`.
             folder: path.basename(path.dirname(file)),
             // Every page is addressed by `(type, shortcode)` at the package
             // root, which takes no content mount.
@@ -695,7 +694,9 @@ export function renderSitePage(
         figuresByAddress = new Map(),
         events,
         drawings = new Map(),
-        runs = runContext(config),
+        runs = runContext(config, undefined, {
+            referenceName: (target) => resolveInfoboxRef(index, target)?.name,
+        }),
     },
 ) {
     const secretErrors = [];
@@ -797,6 +798,7 @@ export function renderSitePage(
     for (const error of [
         ...scanBlocks(page.body).errors,
         ...scanAlerts(page.body).errors,
+        ...scanPageBreaks(page.body).errors,
         ...scanSpans(page.body).errors,
         ...scanRuns(page.body, runs).errors,
         ...markupAnchorFindings(page.body),
@@ -985,7 +987,9 @@ export function renderPages(pages, options) {
     // What each page renders as, held until the graph is whole.
     /** @type {Array<{page: object, markdown: string, figures: object[], data: object}>} */
     const rendered = [];
-    const runs = runContext(config, records);
+    const runs = runContext(config, records, {
+        referenceName: (target) => resolveInfoboxRef(index, target)?.name,
+    });
 
     const renderOne = (page) =>
         renderSitePage(page, {
@@ -1141,6 +1145,7 @@ export function sitePageDecorator(config, index) {
  * @param {object} [options] - Options.
  * @param {object} [options.config] - A resolved configuration; loaded when
  *   omitted.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @param {Map<string, object[]>} [options.sqlTables] - Prepared `sql` results,
  *   keyed by the note's absolute file, from
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
@@ -1157,7 +1162,7 @@ export function sitePageDecorator(config, index) {
  *   against the rest of the build, or returns `null` when its address, name
  *   or type changed and the whole site must be built again.
  */
-export function buildSite({ config, sqlTables } = {}) {
+export function buildSite({ config, sqlTables, progress = () => {} } = {}) {
     const resolved = config ?? loadPackConfig();
     const site = resolved.site;
     const scheme = resolved.publish.address;
@@ -1247,6 +1252,7 @@ export function buildSite({ config, sqlTables } = {}) {
     // the content tree for pages, so `sohl-kethira-basic` and `harn-adventures`
     // cannot publish one whatever else their `site:` block declares.
     if (!publishesContent) {
+        progress(`rendering ${homepages.length} page(s)`);
         return {
             gates: emptyGates(),
             manifests: null,
@@ -1322,6 +1328,7 @@ export function buildSite({ config, sqlTables } = {}) {
         };
     }
 
+    progress(`rendering ${pages.length + homepages.length} page(s)`);
     const pass = resolveSitePass(site.pass, {
         ...site.passOptions,
         repoRoot: resolved.rootDir,

package/engine/site-preview.mjs

@@ -13,6 +13,7 @@
 
 /** Buffer-only HTML preview shared by editors and external renderers. @module */
 
+import { scanPageBreaks } from "./page-breaks.mjs";
 import { sharedContentRules } from "./content-styles.mjs";
 import { readMatter } from "./note-matter.mjs";
 import { scanFigures } from "./content-figures.mjs";
@@ -99,6 +100,8 @@ export function renderPreview(
     } catch (error) {
         findings.push({ file, severity: "warning", message: String(error.message) });
     }
+    for (const error of scanPageBreaks(body).errors)
+        findings.push({ file, severity: "error", ...error, line: bodyLine + error.line - 1 });
     applyComputedBeingAge(frontmatter, date);
     if (String(frontmatter.type ?? "").toLowerCase() === "being") {
         frontmatter.data ??= {};

package/engine/site-render.mjs

@@ -312,18 +312,30 @@ export function writeThemeFiles(out, staticDir = SITE_STATIC_DIR) {
  * @param {string} [options.staticDir] - The theme's own files, copied first.
  * @param {ReadonlySet<string>} [options.only] - The addresses of the pages to
  *   draw again into a site already written. Nothing else is touched.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {{files: string[], pages: string[], reachable: string[],
  *   findings: object[]}} Every file written, the address of every page, the
  *   address of each page reachable from the homepage, and the layouts' findings.
  * @throws {Error} When a page's address is outside the site, or a site served
  *   under a path asks for a sitemap index.
  */
-export function writeSite({ site, pages, out, report, staticDir = SITE_STATIC_DIR, only }) {
+export function writeSite({
+    site,
+    pages,
+    out,
+    report,
+    staticDir = SITE_STATIC_DIR,
+    only,
+    progress = () => {},
+}) {
     if (site.sitemaps && basePath(site) !== "/")
         throw new Error(
             `a sitemap index and robots.txt belong at the root of an origin, and this site is served under ${basePath(site)}`,
         );
     const tree = siteTree(site, pages);
+    progress(
+        `writing ${only ? tree.filter((page) => only.has(page.url)).length : tree.length} page(s)`,
+    );
     const published = new Set(tree.map((page) => page.url));
     const feedUrl = site.feed ? relUrl(site, `${site.feed.section}/atom.xml`) : "";
     const base = basePath(site);
@@ -659,6 +671,7 @@ export function deliverSiteFonts(config, out) {
  * @param {string} options.out - The directory the site is written to, which
  *   is the package's own directory under the deployed root.
  * @param {number} [options.year] - The year the footer states.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {Promise<{built: object, written: object|null, fonts: object|null,
  *   site?: object, pages?: object[], pageOf?: (entry: object) => object}>}
  *   What the build found, and, when it found nothing that stops it, what was
@@ -666,18 +679,19 @@ export function deliverSiteFonts(config, out) {
  *   becomes its page. `written` is `null` when a gate fired.
  * @throws {Error} When the site's settings or its cached menu cannot be read.
  */
-export async function buildPackageSite({ config, out, year }) {
+export async function buildPackageSite({ config, out, year, progress = () => {} }) {
     const settings = siteSettings({ config });
     const navigation = readCachedNavigation(config);
+    progress("indexing content");
     const sqlTables = await prepareTreeSqlTables(config.paths.content, {
         skipDirectories: config.skipDirectories,
         config,
         audience: "public",
     });
-    const built = buildSite({ config, sqlTables, write: false });
+    const built = buildSite({ config, sqlTables, progress });
     if (gatesFailed(built.gates)) return { built, written: null, fonts: null };
     const { site, pages, pageOf } = packageSite({ config, built, settings, navigation, year });
-    const written = writeSite({ site, pages, out });
+    const written = writeSite({ site, pages, out, progress });
     const fonts = deliverSiteFonts(config, out);
     return { built, written, fonts, site, pages, pageOf };
 }

package/engine/site-root.mjs

@@ -300,6 +300,7 @@ export async function indexSite({ site, output, base }) {
  *   `site.search` in the configuration. Default `true`.
  * @param {SiteIndexer} [options.indexer] - What builds it. Default
  *   {@link indexSite}.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {Promise<{files: string[], search: {dir: string, pages: number}|null}>}
  *   The files written, and the index — where it is and how many pages it
  *   holds — or `null` when none was built.
@@ -308,7 +309,14 @@ export async function indexSite({ site, output, base }) {
  *   under the prefix; or, located at the rendered site, when the indexer
  *   fails.
  */
-export async function writeSiteRoot({ pkg, base, out, search = true, indexer = indexSite }) {
+export async function writeSiteRoot({
+    pkg,
+    base,
+    out,
+    search = true,
+    indexer = indexSite,
+    progress = () => {},
+}) {
     const root = path.resolve(out);
     const prefix = base ?? `/${pkg}/`;
     const rendered = path.join(root, ...prefix.split("/").filter(Boolean));
@@ -331,6 +339,7 @@ export async function writeSiteRoot({ pkg, base, out, search = true, indexer = i
     }
     let pages;
     try {
+        progress("building the search index");
         ({ pages } = await indexer({ site: rendered, output: dir, base: prefix }));
     } catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/engine/site-serve-http.mjs

@@ -0,0 +1,151 @@
+/*
+ * 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
+ */
+
+/**
+ * HTTP stays responsive while the calling thread renders a large site.
+ * Only filesystem and listening addresses cross this boundary; the resolved
+ * configuration and the build's render closures remain with their caller.
+ * @module
+ */
+
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { parentPort, workerData } from "node:worker_threads";
+
+/** What a file is sent as, by its extension. */
+const CONTENT_TYPES = Object.freeze({
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".txt": "text/plain; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".wasm": "application/wasm",
+});
+
+/** The script a served page is sent with. */
+const RELOAD_SCRIPT = `<script>new EventSource(${JSON.stringify(workerData?.reloadPath)}).addEventListener("reload", () => location.reload());</script>`;
+
+if (parentPort) {
+    const { root, out, host, port, reloadPath: RELOAD_PATH } = workerData;
+    const listeners = new Set();
+    const server = http.createServer((req, res) => {
+        let address;
+        try {
+            address = decodeURIComponent(new URL(req.url ?? "/", "http://serve.invalid").pathname);
+        } catch {
+            res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+            res.end("Bad request.\n");
+            return;
+        }
+        if (address === RELOAD_PATH) {
+            res.writeHead(200, {
+                "content-type": "text/event-stream",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+            });
+            res.write(": connected\n\n");
+            listeners.add(res);
+            req.on("close", () => listeners.delete(res));
+            return;
+        }
+        if (!fs.existsSync(path.join(out, "index.html"))) {
+            res.writeHead(503, { "content-type": "text/plain; charset=utf-8", "retry-after": "1" });
+            res.end(
+                "No site is available yet. See build progress and diagnostics in the terminal.\n",
+            );
+            return;
+        }
+        let file = path.join(root, address);
+        if (file !== root && !file.startsWith(root + path.sep)) {
+            res.writeHead(403).end();
+            return;
+        }
+        if (fs.statSync(file, { throwIfNoEntry: false })?.isDirectory())
+            file = path.join(file, "index.html");
+        let status = 200;
+        if (!fs.existsSync(file)) {
+            status = 404;
+            file = path.join(out, "404.html");
+            if (!fs.existsSync(file)) {
+                res.writeHead(404).end();
+                return;
+            }
+        }
+        const type = CONTENT_TYPES[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+        let body = fs.readFileSync(file);
+        if (type.startsWith("text/html")) {
+            const html = body.toString("utf8");
+            const at = html.lastIndexOf("</body>");
+            body = Buffer.from(
+                at < 0 ? html + RELOAD_SCRIPT : html.slice(0, at) + RELOAD_SCRIPT + html.slice(at),
+            );
+        }
+        res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
+        res.end(body);
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, resolve);
+    });
+    const listening = /** @type {import("node:net").AddressInfo} */ (server.address());
+    parentPort.postMessage({ kind: "listening", port: listening.port });
+
+    parentPort.on("message", (message) => {
+        if (message.kind === "reload") {
+            for (const res of listeners) res.write("event: reload\ndata: {}\n\n");
+        } else if (message.kind === "install") {
+            // Requests and these renames run on one event loop, so no request
+            // observes the gap between moving the old tree and installing it.
+            let moved = false;
+            try {
+                if (fs.existsSync(out)) {
+                    fs.renameSync(out, message.previous);
+                    moved = true;
+                }
+                try {
+                    fs.renameSync(message.staged, out);
+                } catch (error) {
+                    if (moved) {
+                        try {
+                            fs.renameSync(message.previous, out);
+                        } catch (rollback) {
+                            throw new Error(
+                                `the new site could not be installed or the previous one restored; the previous site remains at ${message.previous}`,
+                                { cause: rollback },
+                            );
+                        }
+                    }
+                    throw error;
+                }
+                parentPort.postMessage({ kind: "installed" });
+            } catch (error) {
+                parentPort.postMessage({ kind: "installed", error });
+            }
+        } else if (message.kind === "close") {
+            for (const res of listeners) res.end();
+            server.close(() => parentPort.close());
+            server.closeAllConnections();
+        }
+    });
+}