@heroiclands/package-build 0.6.1 → 3.0.0

package/sohl/items.mjs

@@ -0,0 +1,197 @@
+/*
+ * 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
+ */
+
+/**
+ * Items pack compiler — produces JSON pack files for the single "items"
+ * Foundry compendium from markdown notes in the `assets/content/` tree.
+ *
+ * The content root (`contentBase`) is walked recursively; any `.md` file whose
+ * frontmatter declares a recognized `type:` is compiled into one JSON entry.
+ * Files outside the whitelist (blog posts, rules text, templates) are
+ * silently skipped.
+ *
+ * Type-specific `system.*` fields come from the nested `sohl:` block in
+ * vault frontmatter, read via `sohlField()`. The body is **not** rendered
+ * here: it compiles into the item's doc in the journals pack, and
+ * `system.docHtml` becomes a pointer to it (see `item-docs.mjs`). Folder
+ * assignment is deferred — every item currently emits `folder: null`.
+ *
+ * Not a standalone script — exports the `Items` compiler class, imported and
+ * driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
+ *
+ * The walk itself — filtering by package and type, skipping drafts,
+ * expanding tables, converting wikilinks, writing the JSON and counting
+ * errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
+ * states only what makes this pass its own (#1509).
+ */
+
+import log from "loglevel";
+
+import {
+    sohlField,
+    resolveName,
+    resolveImg,
+    defaultStats,
+    withArchetypeFlag,
+} from "../engine/helpers.mjs";
+import { BasePackCompiler } from "../engine/base-compiler.mjs";
+// Per-type default art lives in one framework-free module shared with the
+// runtime (`SohlItem.getDefaultArtwork`), so the two can't drift — see #932.
+// It lives in the build package, not `src/`: a relative path out of the package
+// resolves to garbage once this pipeline runs from `node_modules` (#1510).
+import { journalPageId, splitPages } from "../engine/journals.mjs";
+import { foundryPackageId } from "../engine/content-package.mjs";
+import { itemDocEntryId, itemDocPointer } from "../engine/item-docs.mjs";
+// The whitelist and the per-type `system` builders both come from the resolved
+// configuration, so the types this pass claims and the builders it compiles
+// them with are one table — the consuming repository's, not this package's
+// (#1504/#1563).
+import { itemTypes, itemBuilder, itemArt } from "../engine/item-registry.mjs";
+
+/**
+ * The description an item carries: a pointer to its **item doc**, the
+ * JournalEntry the journals pass compiles this same body into (#1348).
+ *
+ * The prose is not rendered here at all. Carrying it would duplicate it onto
+ * every actor holding the item — 7.59 MB of copies across the actors pack, of
+ * which 133 KB was distinct — where a link is 60 bytes and always current. The
+ * two passes derive the target from the note's own id, so neither has to see
+ * the other's output; both split the *converted* markdown, so an H1 carrying a
+ * wikilink names the same page on both sides.
+ *
+ * An item with no prose points at nothing, exactly as the journals pass writes
+ * no entry for it.
+ *
+ * @param {string} markdown - The note body, tables expanded and wikilinks
+ *   resolved.
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} name - The item's name.
+ * @returns {string} The pointer, or "" for a note with no body.
+ */
+function itemDescription(markdown, fm, name) {
+    if (!String(markdown).trim()) return "";
+    const [leadPage] = splitPages(markdown, name);
+    const pageId = journalPageId(itemDocEntryId(fm.id), leadPage, 0);
+    return itemDocPointer(foundryPackageId(), fm.id, name, pageId);
+}
+
+/**
+ * Build the `system.*` fields shared by every item type:
+ *   shortcode, actionDefs, notes, docHtml.
+ */
+function commonSystem(fm, description) {
+    return {
+        shortcode: fm.shortcode,
+        actionDefs: Array.isArray(fm.actionDefs) ? fm.actionDefs : [],
+        notes: "",
+        docHtml: description || "",
+    };
+}
+
+/* -------------------------------------------------------------------- */
+/*  Synthesized Active Effects                                          */
+/* -------------------------------------------------------------------- */
+
+/* -------------------------------------------------------------------- */
+/*  Compiler                                                            */
+/* -------------------------------------------------------------------- */
+
+export class Items extends BasePackCompiler {
+    static id = "items";
+    static label = "item";
+
+    /**
+     * How many of each item type this pass wrote, for the summary. Every type
+     * is present from the start so the tally reads as a census of the
+     * whitelist rather than of what happened to compile.
+     *
+     * @type {Record<string, number>}
+     */
+    counts = Object.fromEntries([...itemTypes()].map((t) => [t, 0]));
+
+    /**
+     * Every content type that compiles into an item.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {boolean} True for a whitelisted item type.
+     */
+    selects(fm) {
+        return Boolean(fm.type) && itemTypes().has(fm.type);
+    }
+
+    /** An item is named by its own type in the log, not by "item". */
+    noteLabel(fm) {
+        return fm.type;
+    }
+
+    /**
+     * Construct the full compendium envelope for one item, including
+     * synthesized Active Effects where applicable.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} markdown - The body, tables expanded and wikilinks
+     *   resolved.
+     * @returns {object} The item document, keyed for the pack.
+     */
+    buildEntry(fm, markdown) {
+        const type = fm.type;
+        const name = resolveName(fm);
+        const description = itemDescription(markdown, fm, name);
+        const id = fm.id;
+        const system = {
+            ...commonSystem(fm, description),
+            ...itemBuilder(type)(fm),
+        };
+
+        const effects = Array.isArray(fm.effects) ? [...fm.effects] : [];
+
+        const folderId = sohlField(fm, "folder", null);
+        const folder = this.folderResolver(folderId);
+
+        return {
+            name,
+            type,
+            img: resolveImg(fm.img) || itemArt(type),
+            _id: id,
+            system,
+            effects,
+            // `sohl.archetype` (required nullable number) drives
+            // `flags.sohl.docArchetype` (#640 / archetype contract #604).
+            flags: withArchetypeFlag(fm, fm.flags, `item "${name}"`),
+            _stats: defaultStats(),
+            ownership: { default: 0 },
+            folder,
+            _key: `!items!${id}`,
+        };
+    }
+
+    /** @inheritdoc */
+    onCompiled(fm) {
+        this.counts[fm.type]++;
+    }
+
+    /** @inheritdoc */
+    reportCompiled(stats) {
+        log.info(`Compiled ${stats.compiled} items:`);
+        for (const [t, n] of Object.entries(this.counts)) {
+            if (n > 0) log.info(`  ${t}: ${n}`);
+        }
+    }
+
+    /** @inheritdoc */
+    reportDetail(stats) {
+        log.debug(
+            `Skipped ${stats.skippedOther} non-item file(s) (no recognized type)`,
+        );
+    }
+}

package/sohl/kb-passes.mjs

@@ -0,0 +1,207 @@
+/*
+ * 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
+ */
+
+/**
+ * The `sohl` knowledgebase's own body passes (#63).
+ *
+ * `content-build site` publishes a content tree as a website, and almost all of
+ * that job is the same for every package. These two rewrites are not: they are
+ * driven by a TypeDoc symbol map and a repository layout only this package has,
+ * and #63 rules them explicitly per-consumer.
+ *
+ * They live here rather than in a script in the consuming repository for the
+ * same reason `sohl/item-builders.mjs` and `sohl/being-info.mjs` do: a
+ * configuration is data and cannot hold a function, so a package-specific table
+ * of code is **named** from configuration and resolved from a registry. What is
+ * package-specific is the code; what is repository-specific — where the symbol
+ * map sits, what the API is served at, which GitHub tree to link into — is
+ * options, supplied beside the name.
+ *
+ * Neither pass ever fails a build. A `{@link}` the map does not know degrades to
+ * a code span, and a relative link that resolves outside the documentation tree
+ * becomes a GitHub blob URL. Both are legible to a reader; a broken link or a
+ * failed build for a syntax example in prose would not be.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Reads the TypeDoc symbol map, or an empty one.
+ *
+ * Absent is not an error: the map is generated by `npm run docs`, and a
+ * knowledgebase build that runs before it — or in a checkout that has never run
+ * it — should publish prose with `{@link}` tags degraded to code spans rather
+ * than refuse to build.
+ *
+ * @param {string|undefined} file - Path to the map, if configured.
+ * @returns {Record<string, string>} Qualified name → API page path.
+ */
+function readSymbolMap(file) {
+    if (!file) return {};
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Resolves inline TypeDoc `{@link}` / `{@linkcode}` / `{@linkplain}` tags
+ * against the API symbol map.
+ *
+ * - A known target becomes a Markdown link to its page on the API site;
+ *   `@linkcode` renders the text as code.
+ * - Optional display text (`{@link Target | text}` or `{@link Target text}`)
+ *   wins; otherwise the last dotted segment is the link text.
+ * - An external URL target becomes a plain Markdown link.
+ * - Anything the map does not know — `{@link Symbol.member}` written as a syntax
+ *   example, say — degrades to a code span. Never a broken link, never a build
+ *   failure.
+ *
+ * @param {string} body - The markdown body.
+ * @param {Record<string, string>} symbols - The symbol map.
+ * @param {string} apiBase - Where the generated API documentation is served.
+ * @returns {string} The body with every tag resolved.
+ */
+export function resolveApiLinks(body, symbols, apiBase) {
+    return body.replace(
+        /\{@link(code|plain)?\s+([^}]+)\}/g,
+        (_m, kind, inner) => {
+            inner = inner.trim();
+            let target, text;
+            const pipe = inner.indexOf("|");
+            const space = inner.search(/\s/);
+            if (pipe !== -1) {
+                target = inner.slice(0, pipe).trim();
+                text = inner.slice(pipe + 1).trim();
+            } else if (space !== -1) {
+                target = inner.slice(0, space);
+                text = inner.slice(space + 1).trim();
+            } else {
+                target = inner;
+                text = "";
+            }
+
+            if (/^https?:\/\//.test(target)) {
+                return `[${text || target}](${target})`;
+            }
+
+            const url = symbols[target];
+            const display = text || target.split(".").pop();
+            if (url) {
+                const href = apiBase + url;
+                return kind === "code" ?
+                        `[\`${display}\`](${href})`
+                    :   `[${display}](${href})`;
+            }
+            return kind === "plain" ? display : `\`${display}\``;
+        },
+    );
+}
+
+/**
+ * Rewrites the relative links in a developer-doc body so they resolve on the
+ * published site.
+ *
+ * Developer docs are authored to link one another and the source tree with
+ * repository-relative paths, and neither target exists at the same path once
+ * rendered. Each link is resolved against the doc's own location:
+ *
+ * - a `*.md` link landing inside the documentation tree becomes the published
+ *   route, preserving any `#anchor`; a `README` is its directory's landing, so
+ *   that segment is dropped.
+ * - anything else — source, templates, a repository-root `*.md` — becomes its
+ *   GitHub blob URL.
+ *
+ * Absolute URLs, anchor-only links, `mailto:` and site-root links are untouched.
+ *
+ * @param {string} body - The markdown body.
+ * @param {string} docRel - The doc's path relative to the documentation tree.
+ * @param {object} options - `{ repoRoot, docsSrc, docsRel, route, blob }`.
+ * @returns {string} The body with every relative link rewritten.
+ */
+export function rewriteRepoLinks(body, docRel, options) {
+    const { repoRoot, docsSrc, docsRel, route, blob } = options;
+    const docDir = path.dirname(docRel);
+    return body.replace(/\]\(([^)]+)\)/g, (whole, raw) => {
+        // Peel an optional link title: [text](url "title").
+        const sp = raw.search(/\s/);
+        const href = sp === -1 ? raw : raw.slice(0, sp);
+        const title = sp === -1 ? "" : raw.slice(sp);
+        if (/^(https?:|mailto:|tel:|#|\/)/.test(href)) return whole;
+
+        const hash = href.indexOf("#");
+        const filePart = hash === -1 ? href : href.slice(0, hash);
+        const anchor = hash === -1 ? "" : href.slice(hash);
+        if (!filePart) return whole;
+
+        const repoRel = path
+            .relative(repoRoot, path.resolve(docsSrc, docDir, filePart))
+            .replace(/\\/g, "/");
+
+        let out;
+        if (repoRel.startsWith(`${docsRel}/`) && repoRel.endsWith(".md")) {
+            const rel2 = repoRel.slice(docsRel.length + 1, -3).toLowerCase();
+            const devPath =
+                path.basename(rel2) === "readme" ?
+                    path.posix.dirname(rel2)
+                :   rel2;
+            out = `${route}${devPath === "." ? "" : `${devPath}/`}${anchor}`;
+        } else {
+            out = `${blob}${repoRel}${anchor}`;
+        }
+        return `](${out}${title})`;
+    });
+}
+
+/**
+ * The `sohl` knowledgebase pass bundle, built from its options.
+ *
+ * A pass bundle is two optional hooks the page renderer calls around wikilink
+ * resolution, and the order matters:
+ *
+ * - `beforeLinks` runs on every page, before wikilinks resolve, because a
+ *   `{@link}` tag may sit inside prose a wikilink also touches.
+ * - `afterLinks` runs only on pages from an **extra tree** — the documentation
+ *   tree — because repository-relative links are a property of how those pages
+ *   are authored, not of content notes.
+ *
+ * Both run inside code-fence protection, so neither can rewrite a fenced example.
+ *
+ * @param {object} options - Resolved from `site.passOptions`.
+ * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map.
+ * @param {string} [options.apiBase] - Where the API documentation is served.
+ * @param {string} [options.blob] - GitHub blob base for repository files.
+ * @param {string} options.repoRoot - The repository root, for relative paths.
+ * @returns {{beforeLinks: Function, afterLinks: Function}} The bundle.
+ */
+export function sohlKbPass(options) {
+    const symbols = readSymbolMap(options.symbolMap);
+    const apiBase = options.apiBase ?? "";
+    return {
+        beforeLinks: (text) => resolveApiLinks(text, symbols, apiBase),
+        afterLinks: (text, page) =>
+            page.tree ?
+                rewriteRepoLinks(text, page.rel, {
+                    repoRoot: options.repoRoot,
+                    docsSrc: page.tree.from,
+                    docsRel: page.tree.rel,
+                    route: page.tree.route,
+                    blob: options.blob ?? "",
+                })
+            :   text,
+    };
+}