@heroiclands/package-build 23.12.8 → 24.0.0

package/engine/site-search.mjs

@@ -0,0 +1,161 @@
+/*
+ * 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 a note's page tells the site's search.** Pagefind reads the filters a
+ * page carries, so a reader can narrow a search to a package, a kind of note
+ * or a part of the world:
+ *
+ * | Filter | Value |
+ * | ------ | ----- |
+ * | `package` | the package that publishes the note |
+ * | `type` | the note's `type` |
+ * | `subtype` | the note's `subType` |
+ * | `culture` | the name of the culture `data.culture` names |
+ * | `continent` | the continent the note lies in |
+ * | `region` | the outermost region beneath that continent |
+ *
+ * A place lies where its `parents` lead; a being where its `homes` are; a
+ * scenario where its `locations` are. A continent is a region whose parent is
+ * the world. A note reached by more than one path carries every continent and
+ * region it reaches, so a being with homes in two regions is found under both.
+ *
+ * The note's name and its aliases are weighted, so a search for a name finds
+ * its note first. A note's tags and its draft state are not filters.
+ *
+ * @module
+ */
+
+import { placeShortcodes } from "./map-places.mjs";
+import { resolveInfoboxRef } from "./site-index.mjs";
+
+/** The filters a note's page carries, in the order a reader is offered them. */
+export const SEARCH_FILTERS = Object.freeze([
+    "package",
+    "type",
+    "subtype",
+    "culture",
+    "continent",
+    "region",
+]);
+
+/**
+ * @param {unknown} value - Anything.
+ * @returns {boolean} Whether it is a mapping a field may be read out of.
+ */
+const isMapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * The continents and regions every place lies in.
+ *
+ * @param {Map<string, {shortcode: string, name: string, subType?: string, parents: string[]}>} places -
+ *   Every place, by shortcode, as {@link module:engine/map-places.mapWorld} reads them.
+ * @returns {(shortcodes: Iterable<string>) => {continents: string[], regions: string[]}}
+ *   The names of the continents and the outermost regions the given places lie
+ *   in, each sorted.
+ */
+export function placeGeography(places) {
+    const worlds = new Set(
+        [...places.values()].filter((p) => p.subType === "world").map((p) => p.shortcode),
+    );
+    const isContinent = (place) =>
+        place?.subType === "region" && place.parents.some((parent) => worlds.has(parent));
+    /** @type {Map<string, {continents: Set<string>, regions: Set<string>}>} */
+    const known = new Map();
+
+    const reach = (shortcode, visiting) => {
+        if (known.has(shortcode)) return known.get(shortcode);
+        const found = { continents: new Set(), regions: new Set() };
+        const place = places.get(shortcode);
+        if (!place || visiting.has(shortcode) || worlds.has(shortcode)) return found;
+        visiting.add(shortcode);
+        if (isContinent(place)) found.continents.add(shortcode);
+        for (const parent of place.parents) {
+            if (place.subType === "region" && isContinent(places.get(parent)))
+                found.regions.add(shortcode);
+            const above = reach(parent, visiting);
+            for (const c of above.continents) found.continents.add(c);
+            for (const r of above.regions) found.regions.add(r);
+        }
+        visiting.delete(shortcode);
+        known.set(shortcode, found);
+        return found;
+    };
+
+    const names = (shortcodes) =>
+        [...new Set([...shortcodes].map((sc) => places.get(sc)?.name ?? sc))].sort();
+    return (shortcodes) => {
+        const continents = new Set();
+        const regions = new Set();
+        for (const shortcode of shortcodes) {
+            const found = reach(shortcode, new Set());
+            for (const c of found.continents) continents.add(c);
+            for (const r of found.regions) regions.add(r);
+        }
+        return { continents: names(continents), regions: names(regions) };
+    };
+}
+
+/**
+ * The places a note lies in: itself for a place, its `homes` and its
+ * `locations` otherwise.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @returns {string[]} Shortcodes, lower case.
+ */
+export function notePlaces(fm) {
+    if (fm?.type === "place") return [String(fm.shortcode ?? "").toLowerCase()].filter(Boolean);
+    const data = isMapping(fm?.data) ? fm.data : {};
+    return [...placeShortcodes(data.homes), ...placeShortcodes(data.locations)];
+}
+
+/**
+ * What a note's page tells the search.
+ *
+ * @param {object} fm - The page's frontmatter: the note's, with its `package`.
+ * @param {object} options - What the values resolve against.
+ * @param {(shortcodes: Iterable<string>) => {continents: string[], regions: string[]}} options.geography -
+ *   From {@link placeGeography}.
+ * @param {object} [options.index] - The site's address index, which names the
+ *   culture `data.culture` names.
+ * @returns {{filters: Array<{name: string, values: string[]}>, names: string[]}}
+ *   Each filter with a value, in {@link SEARCH_FILTERS} order, and the names a
+ *   search weights.
+ */
+export function searchMetadata(fm, { geography, index }) {
+    const data = isMapping(fm?.data) ? fm.data : {};
+    const text = (value) => (value === undefined || value === null ? "" : String(value).trim());
+    const culture =
+        data.culture !== undefined && data.culture !== null && data.culture !== "" ?
+            index && resolveInfoboxRef(index, data.culture, { type: "lore" })?.name
+        :   undefined;
+    const { continents, regions } = geography(notePlaces(fm));
+    const values = {
+        package: [text(fm?.package)],
+        type: [text(fm?.type)],
+        subtype: [text(fm?.subType)],
+        culture: [text(culture)],
+        continent: continents,
+        region: regions,
+    };
+    const filters = SEARCH_FILTERS.map((name) => ({
+        name,
+        values: values[name].filter(Boolean),
+    })).filter((filter) => filter.values.length);
+    const name = isMapping(fm?.name) ? fm.name : {};
+    const names = [
+        text(name.full),
+        ...(Array.isArray(name.aliases) ? name.aliases.map(text) : []),
+    ].filter(Boolean);
+    return { filters, names: [...new Set(names)] };
+}

package/engine/site-serve.mjs

@@ -0,0 +1,273 @@
+/*
+ * 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
+ */
+
+/**
+ * **A site served while it is written.** {@link serveSite} builds a package's
+ * site, serves it, and keeps it current: it watches the content tree and the
+ * theme, writes again what a change touches, and tells every open page to
+ * reload.
+ *
+ * | Change | What is written again |
+ * | ------ | --------------------- |
+ * | a note's body or frontmatter | that note's page |
+ * | a note's name, type or shortcode, a new or removed note, a note holding an `sql` table, any other file in the content tree | the whole site |
+ * | the theme's layouts, partials or files | every page, and the theme's files |
+ *
+ * A page that changes because another note changed — a table that lists the
+ * note, a link that carries its name — is written again by the next whole
+ * build. A note in error is written as its page shows it, and the error is
+ * reported; a build whose gates fire writes nothing and leaves the last good
+ * site in place.
+ *
+ * The site is served from the deployed root, so a page is at the address it is
+ * deployed at, its base path included. Every HTML page is sent with a script
+ * that listens on {@link RELOAD_PATH} for the server's `reload` event; the
+ * script is added as the page is sent and is never written to the site. The
+ * search index is built once, after the first build.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+
+import { siteBuildFailed } from "./site-build.mjs";
+import { SITE_THEME_DIR } from "./site-theme.mjs";
+import { SITE_STATIC_DIR, buildPackageSite, writeSite, writeThemeFiles } from "./site-render.mjs";
+import { SEARCH_DIR, indexSite } from "./site-root.mjs";
+
+/** The address a served page listens on for the server's reloads. */
+export const RELOAD_PATH = "/__package-build/reload";
+
+/** How long a burst of changes is gathered before it is written, in milliseconds. */
+const SETTLE_MS = 120;
+
+/** 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(RELOAD_PATH)}).addEventListener("reload", () => location.reload());</script>`;
+
+/** Whether a note's text holds a query its build prepares ahead of the render. */
+const holdsQuery = (text) => /```\s*sql\b|\{\{[^}]*\bsql\b/.test(text);
+
+/**
+ * Serve a package's site, and keep it current.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @param {string} options.out - The site's directory under the deployed
+ *   root, which the site is written to.
+ * @param {string} [options.root] - The deployed root, which is served. The
+ *   directory above `out` by default; `out` itself for a site served at `/`.
+ * @param {string} [options.host] - The address to listen on.
+ * @param {number} [options.port] - The port; `0` takes any free one.
+ * @param {boolean} [options.search] - Build the search index after the first
+ *   build, where the site has one.
+ * @param {number} [options.year] - The year the footer states.
+ * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown}) => void} [options.report] -
+ *   Told of each build: `built` for a whole build, `page` for one note's page,
+ *   `theme` for the theme, `failed` with what the build found, `error` with
+ *   what it threw.
+ * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>}>}
+ *   The address of the site's home page, how to stop serving, and a promise
+ *   for the moment every change seen so far has been written.
+ */
+export async function serveSite({
+    config,
+    out,
+    root = path.dirname(out),
+    host = "127.0.0.1",
+    port = 1313,
+    search = true,
+    year,
+    report = () => {},
+}) {
+    /** @type {Set<http.ServerResponse>} */
+    const listeners = new Set();
+    let state = null;
+
+    const reload = () => {
+        for (const res of listeners) res.write("event: reload\ndata: {}\n\n");
+    };
+
+    const buildAll = async () => {
+        const result = await buildPackageSite({ config, out, year });
+        if (!result.written || siteBuildFailed(result.built))
+            report({ kind: "failed", built: result.built });
+        if (!result.written) return false;
+        state = result;
+        report({ kind: "built", built: result.built, findings: result.written.findings });
+        return true;
+    };
+
+    const redrawNotes = (files) => {
+        if (!state) return false;
+        const changed = new Set();
+        for (const file of files) {
+            const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+            if (!file.endsWith(".md") || !text || holdsQuery(text)) return false;
+            const entry = state.built.site.renderNote(file);
+            if (!entry) return false;
+            if (entry.findings.length) {
+                report({ kind: "failed", findings: entry.findings });
+                return true;
+            }
+            const page = state.pageOf(entry);
+            state.pages = state.pages.map((old) => (old.url === page.url ? page : old));
+            changed.add(page.url);
+        }
+        const written = writeSite({ site: state.site, pages: state.pages, out, only: changed });
+        report({ kind: "page", files: written.files, findings: written.findings });
+        return true;
+    };
+
+    const redrawTheme = () => {
+        if (!state) return false;
+        writeThemeFiles(out);
+        const written = writeSite({
+            site: state.site,
+            pages: state.pages,
+            out,
+            only: new Set(state.pages.map((page) => page.url)),
+        });
+        report({ kind: "theme", files: written.files, findings: written.findings });
+        return true;
+    };
+
+    const indexForSearch = async () => {
+        if (!search || config.site.search === false || !state) return;
+        await indexSite({ site: out, output: path.join(out, SEARCH_DIR) });
+    };
+
+    await buildAll();
+    await indexForSearch();
+
+    /** @type {{content: Set<string>, theme: boolean}} */
+    let pending = { content: new Set(), theme: false };
+    let timer = null;
+    let work = Promise.resolve();
+    const flush = () => {
+        timer = null;
+        const batch = pending;
+        pending = { content: new Set(), theme: false };
+        work = work.then(async () => {
+            try {
+                let done = true;
+                if (batch.content.size && !redrawNotes([...batch.content])) {
+                    done = await buildAll();
+                    if (done) await indexForSearch();
+                } else if (batch.theme) done = redrawTheme();
+                if (done) reload();
+            } catch (error) {
+                report({ kind: "error", error });
+            }
+        });
+    };
+    const queue = (kind, file) => {
+        if (kind === "theme") pending.theme = true;
+        else pending.content.add(file);
+        if (!timer) timer = setTimeout(flush, SETTLE_MS);
+    };
+
+    const watchers = [
+        fs.watch(config.paths.content, { recursive: true }, (_event, name) => {
+            if (name) queue("content", path.join(config.paths.content, String(name)));
+        }),
+        ...[SITE_THEME_DIR, SITE_STATIC_DIR]
+            .filter((dir) => fs.existsSync(dir))
+            .map((dir) => fs.watch(dir, { recursive: true }, () => queue("theme"))),
+    ];
+
+    const server = http.createServer((req, res) => {
+        const address = decodeURIComponent(
+            new URL(req.url ?? "/", "http://serve.invalid").pathname,
+        );
+        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;
+        }
+        let file = path.join(root, address);
+        if (!file.startsWith(root)) {
+            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) => server.listen(port, host, resolve));
+    const listening = /** @type {import("node:net").AddressInfo} */ (server.address());
+    const base = new URL(config.homepage).pathname;
+
+    return {
+        url: `http://${host}:${listening.port}${base}`,
+        settled: async () => {
+            while (timer || pending.content.size || pending.theme) {
+                await new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
+            }
+            await work;
+        },
+        close: async () => {
+            if (timer) clearTimeout(timer);
+            for (const watcher of watchers) watcher.close();
+            for (const res of listeners) res.end();
+            await work;
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}

package/engine/site-theme-banner.mjs

@@ -0,0 +1,154 @@
+/*
+ * 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
+ */
+
+/**
+ * **A page's banner image.** {@link bannerUrl} turns a note's banner fields into
+ * the address of the hero image, or into `""` when the page has none.
+ *
+ * Resolution, in order:
+ *
+ * 1. `data.banner` — a note's own hero image, which the content build resolved
+ *    from an asset address. It is used as given; a blank one declines an image.
+ * 2. `banner` — a hand-authored page's value. `none` or `false` declines an
+ *    image, a full URL is used as written, and anything else is a fragment
+ *    under `images/`.
+ * 3. `<dir>/<name>.webp` — the default for the page's kind: the banner
+ *    `banner-kinds.yaml` maps its `type` and `subType` to, or its `category`
+ *    for the types the mapping lists as taking theirs from there.
+ * 4. `<dir>/<fallback>` — whenever the name step 2 or 3 picked is not in the
+ *    declared inventory of `banners.yaml`. An asset host cannot be asked
+ *    whether a name exists, so the inventory stands in for the test, and each
+ *    name that misses is reported once.
+ *
+ * The inventory is checked only for a relative path directly inside the banner
+ * directory; an absolute URL, a step 1 address and a fragment elsewhere under
+ * `images/` pass through.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import YAML from "yaml";
+
+import { cdnUrl } from "./site-theme-urls.mjs";
+
+/** The directory holding the banner inventory and the kind mapping. */
+export const BANNER_DATA_DIR = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "site-theme",
+    "data",
+);
+
+/** @type {{banners: object, kinds: object}|undefined} */
+let shipped;
+
+/**
+ * The banner data the theme ships.
+ *
+ * @returns {{banners: object, kinds: object}} The inventory and the kind mapping.
+ */
+export function shippedBannerData() {
+    shipped ??= {
+        banners: YAML.parse(fs.readFileSync(path.join(BANNER_DATA_DIR, "banners.yaml"), "utf8")),
+        kinds: YAML.parse(fs.readFileSync(path.join(BANNER_DATA_DIR, "banner-kinds.yaml"), "utf8")),
+    };
+    return shipped;
+}
+
+/** The text of a value as a template prints it, with an unset value as `<nil>`. */
+const printed = (value) => (value === undefined || value === null ? "<nil>" : String(value));
+
+/**
+ * The address of a page's banner.
+ *
+ * @param {object} site - The site: `params.cdnBaseURL` and `basePath`.
+ * @param {object} fields - What the page states.
+ * @param {object} [fields.data] - The page's `data`, read for the resolved `banner`.
+ * @param {unknown} [fields.banner] - The hand-authored `banner` value.
+ * @param {string} [fields.type] - The note `type`.
+ * @param {string} [fields.subType] - The note `subType`.
+ * @param {string} [fields.category] - The page's `category`.
+ * @param {string} [fields.subtype] - The name to default to when no `type` is given.
+ * @param {string} [fields.context] - The page address, named in a report.
+ * @param {object} [options] - Options.
+ * @param {{banners: object, kinds: object}} [options.data] - The inventory and the
+ *   kind mapping. The shipped ones by default.
+ * @param {(finding: {severity: string, message: string, page?: string}) => void} [options.report] -
+ *   Receives each name that misses the inventory, once.
+ * @param {Set<string>} [options.reported] - The names already reported.
+ * @returns {string} The address, or `""` when the page has no banner.
+ */
+export function bannerUrl(site, fields, { data = shippedBannerData(), report, reported } = {}) {
+    const banners = data.banners ?? {};
+    const kinds = data.kinds ?? {};
+    const dir = banners.dir || "images/banners";
+    const fallback = banners.fallback || "default.webp";
+    const available = banners.available ?? [];
+
+    let subtype = fields.subtype ?? "";
+    if (fields.type) {
+        const entry = (kinds.kinds ?? {})[fields.type];
+        if ((kinds.categoryTypes ?? []).includes(fields.type)) {
+            subtype = fields.category || "default";
+        } else if (entry && typeof entry === "object") {
+            subtype = entry[String(fields.subType ?? "").toLowerCase()] || fields.type;
+        } else {
+            subtype = entry || fields.type;
+        }
+    }
+
+    const raw = printed(fields.banner);
+    const declined = raw.toLowerCase() === "none" || raw === "false";
+    const resolved = fields.data ? fields.data.banner : undefined;
+    const fromBuild = resolved !== undefined && resolved !== null;
+
+    let banner = "";
+    let absolute = false;
+    if (fromBuild) {
+        banner = String(resolved);
+        absolute = true;
+    } else if (!declined) {
+        if (fields.banner) {
+            const value = String(fields.banner);
+            banner = `images/${value.replace(/^\//, "")}`;
+            if (/^(?:https?:)?\/\//.test(value)) {
+                banner = value;
+                absolute = true;
+            }
+        } else if (subtype) {
+            banner = `${dir}/${subtype}.webp`;
+        }
+        if (banner && !absolute && path.posix.dirname(banner) === dir) {
+            const name = path.posix.basename(banner, path.posix.extname(banner));
+            if (!available.includes(name)) {
+                if (!reported?.has(name)) {
+                    reported?.add(name);
+                    report?.({
+                        severity: "warning",
+                        page: fields.context || undefined,
+                        message:
+                            `hero-banner: no banner named "${name}" in the shared artwork set; ` +
+                            `falling back to ${dir}/${fallback}. Draw it and add "${name}" to ` +
+                            "data/banners.yaml, or name a hero image with `data.banner`. " +
+                            "Write `data.banner: none` to decline a hero image.",
+                    });
+                }
+                banner = `${dir}/${fallback}`;
+            }
+        }
+    }
+    return banner ? cdnUrl(site, banner) : "";
+}