@heroiclands/package-build 4.0.0 → 6.0.0

package/engine/generate.mjs

@@ -23,10 +23,15 @@
  * Each `*` compiler walks the whole content tree and selects its own entries by
  * the note's `type` — every note in the tree belongs to this repository's
  * `contentPackage` (#56) — so routing is directory-agnostic: a file lands in a
- * pack because of its `type`, not its location. Which packs exist, in what order, and which folder
- * hierarchy each one loads are all declared in `package-build.config.yaml`;
- * folder files live under the content root and are referenced from entry
- * frontmatter via `sohl.folder: <id>`.
+ * pack because of its `type`, not its location. Which packs exist and which
+ * folder hierarchy each one loads are declared in
+ * `package-build.config.yaml`; folder files live under the content root and are
+ * referenced from entry frontmatter via `sohl.folder: <id>`.
+ *
+ * **The order the passes run in is derived, not declared** — see
+ * {@link orderPassesByDependency}. The declared list is the manifest's `packs`
+ * array as well, so it is ordered for a reader; a pass that reads another's
+ * output states that on its compiler and is scheduled after it (#73).
  *
  * This replaces the retired `packs:export` (vault → committed `_source/`); the
  * HeroicLands vault is no longer a build input for SoHL content.
@@ -50,6 +55,7 @@ import {
     writeFolderDocs,
 } from "./helpers.mjs";
 import { countContentNotes } from "./content-tree.mjs";
+import { emitDiagnostic } from "./diagnostics.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { routerFor } from "./pack-router.mjs";
 
@@ -89,8 +95,9 @@ export const packJsonDir = (name, config = loadPackConfig()) =>
  * and an actor's embedded items may be sourced from any of them. Finding one
  * pack and stopping is how embedded-item resolution would silently miss every
  * item that landed in another. Returned in configured order, which is also the
- * order they compile in, so a pack later in the list cannot be read before it
- * is written.
+ * order they compile in — {@link orderPassesByDependency} keeps the declared
+ * order among packs of one type — and every one of them is written before the
+ * actors pass that reads them.
  *
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
@@ -104,6 +111,126 @@ export function itemPackJsonDirs(config = loadPackConfig()) {
         .map((pack) => packJsonDir(pack.name, config));
 }
 
+/**
+ * The document types whose compiled output a pass of this type reads.
+ *
+ * Asked of the compiler rather than held in a table here, so the dependency
+ * lives in the class that does the reading and a consumer's own compiler can
+ * declare its own. A type no compiler is registered for waits on nothing —
+ * {@link generatePack} reports it as an unknown type, which is the better
+ * message.
+ *
+ * @param {string} type - A pack's document type.
+ * @returns {readonly string[]} The types it reads the output of.
+ */
+function readsOutputOf(type) {
+    return COMPILERS[type]?.readsPackOutputOf ?? [];
+}
+
+/**
+ * The passes to run, ordered so that each one follows the output it reads.
+ *
+ * **Declaration order is presentation, not compile order (#73).** The same
+ * `packs:` list is the manifest's `packs` array, which a consumer orders for a
+ * reader browsing compendiums; the actors pass, meanwhile, resolves each
+ * being's embedded items against the item passes' *output*. Making one list
+ * satisfy both meant an Actor pack declared first compiled only where a
+ * previous run had already left `build/packs-json` populated — green on a warm
+ * tree, exit 1 on every fresh checkout and every CI runner, and `build/` is
+ * gitignored so that is the state CI always starts from.
+ *
+ * **The reordering is the smallest one that works.** Each step takes the
+ * *earliest declared* pass whose dependencies are all already emitted, so a
+ * list that was already in a workable order comes back untouched, and one that
+ * was not moves exactly the passes that had to move. A dependency is satisfied
+ * only when **every** pack of that type has run: a being addresses an item by
+ * `(type, shortcode)` without knowing which Item pack ships it, so waiting for
+ * one of several would resolve some beings and silently fail others.
+ *
+ * A dependency on a type this configuration declares no pack of is not waited
+ * for. A package may ship an Actor pack and no Item pack; the pass that needs
+ * one refuses on its own, with a message about items rather than about order.
+ *
+ * @param {readonly object[]} packs - The passes to be run, as declared.
+ * @returns {object[]} A new list, in compile order. The input is untouched.
+ * @throws {Error} If the passes read each other's output in a cycle, which no
+ *   order can satisfy. Only reachable from a mis-declared compiler, so it names
+ *   the passes rather than blaming the pack list.
+ */
+export function orderPassesByDependency(packs) {
+    const declared = new Set(packs.map((pack) => pack.type));
+    const remaining = [...packs];
+    const emitted = new Set();
+    /** @type {object[]} */
+    const ordered = [];
+
+    /** Whether every pack this pass reads the output of has already run. */
+    const ready = (pack) =>
+        readsOutputOf(pack.type).every(
+            (dependency) =>
+                !declared.has(dependency) ||
+                packs.every(
+                    (other) =>
+                        other.type !== dependency || emitted.has(other.name),
+                ),
+        );
+
+    while (remaining.length) {
+        const next = remaining.findIndex(ready);
+        if (next === -1) {
+            throw new Error(
+                `package-build: the configured passes read each other's ` +
+                    `output in a cycle (` +
+                    `${remaining.map((pack) => `${pack.name} (${pack.type})`).join(", ")}` +
+                    `); no compile order can satisfy that.`,
+            );
+        }
+        const [pack] = remaining.splice(next, 1);
+        emitted.add(pack.name);
+        ordered.push(pack);
+    }
+    return ordered;
+}
+
+/**
+ * The dependencies this run cannot satisfy by ordering, because the pass that
+ * would produce them is not in it.
+ *
+ * Ordering answers the whole-package build; a run restricted to one pack
+ * (`content-build package compile <name>`) cannot conjure the passes it left
+ * out. Where their output is already on disk from an earlier run that is fine
+ * — it is how compiling one pack at a time is meant to work — so this reports
+ * only what is genuinely absent, and names the pack that would write it rather
+ * than the directory that is missing.
+ *
+ * @param {readonly object[]} running - The passes this run will execute.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string[]} One message per unsatisfiable dependency.
+ */
+export function unsatisfiedPassDependencies(running, config) {
+    const included = new Set(running.map((pack) => pack.name));
+    /** @type {string[]} */
+    const messages = [];
+    for (const pack of running) {
+        for (const dependency of readsOutputOf(pack.type)) {
+            for (const producer of config.packs) {
+                if (producer.type !== dependency) continue;
+                if (included.has(producer.name)) continue;
+                const dir = packJsonDir(producer.name, config);
+                if (fs.existsSync(dir)) continue;
+                messages.push(
+                    `pack "${pack.name}" (${pack.type}) reads the compiled ` +
+                        `output of the ${producer.type} pack ` +
+                        `"${producer.name}", which this run does not compile ` +
+                        `and which ${dir} does not hold — compile the whole ` +
+                        `package, or compile "${producer.name}" first`,
+                );
+            }
+        }
+    }
+    return messages;
+}
+
 /**
  * Generate the per-entry JSON for one pack into `build/packs-json/<name>/`.
  *
@@ -280,9 +407,31 @@ export async function generatePacksJson({
         if (!firstOfType.has(pack.type)) firstOfType.set(pack.type, pack.name);
     }
 
+    // Compile order is derived from what each pass reads, not from the order
+    // `packs:` declares — that list is also the manifest's, which a consumer
+    // orders for a reader (#73).
+    const ordered = orderPassesByDependency(packs);
+    if (ordered.some((pack, index) => pack !== packs[index])) {
+        log.info(
+            `Pass order: ${ordered.map((pack) => pack.name).join(", ")} — a ` +
+                `pass that reads another's output compiles after it, whatever ` +
+                `order \`packs:\` declares.`,
+        );
+    }
+
+    // What ordering cannot reach: a run restricted to one pack, whose
+    // dependencies are simply not in it and not on disk either.
+    const unsatisfied = unsatisfiedPassDependencies(ordered, config);
+    if (unsatisfied.length) {
+        for (const message of unsatisfied) {
+            emitDiagnostic({ severity: "error", message });
+        }
+        return unsatisfied.length;
+    }
+
     let totalErrors = 0;
     const passes = [];
-    for (const pack of packs) {
+    for (const pack of ordered) {
         const { errors, compiled } = await generatePack(
             pack,
             config,

package/engine/homepage.mjs

@@ -0,0 +1,259 @@
+/*
+ * 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 package homepage — a note that compiles to a **page** rather than to a
+ * compendium document (#51).
+ *
+ * Every HeroicLands package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
+ * and what a reader finds there is one markdown file in the content tree,
+ * written by a person: what the module is, which system it needs, how to install
+ * it, where its source lives. Nothing about it is derived.
+ *
+ * **Authored, not assembled.** An earlier sketch generated the page in tiers —
+ * identity and licence from the manifest, install URL from the release address,
+ * "requires" links from `relationships`, a card per configured section. It would
+ * have worked and needed almost no authoring, and it produces a page nobody
+ * chose the contents of. The things that matter most on these pages cannot be
+ * derived: that Kethira requires buying the book from Keléstia, what Thalorna's
+ * setting *is*, which of twenty sections a reader should start with. So the only
+ * thing defaulted here is the title, from `packageBuild.manifest.title`, so that
+ * the package's name is not written twice.
+ *
+ * **Dispatched by `type`, not by filename.** A fixed `homepage.md` the walker
+ * special-cased would be the anomaly: notes are routed by frontmatter, not by
+ * location, and `NOTE_SCHEMAS` already routes `doc`, `macro`, `being` and the
+ * map types. `homepage` is one more entry whose compile step emits a page. It is
+ * deliberately not `README.md`: `landing: readme` already means "a `README.md`
+ * is its section's landing page", and `sohl-thalorna/assets/content/README.md`
+ * is a developer explainer about the source tree — adopting that name would make
+ * Thalorna's public front page its build documentation.
+ *
+ * **Engine, not `sohl/`.** The `engine/` ÷ `sohl/` line separates *note-format*
+ * knowledge from *game-system* knowledge, and a homepage is note format: it
+ * carries no `system` block, mirrors no item builder, and would mean the same
+ * thing for a game system that is not SoHL. Reachability is the symptom that
+ * makes it obvious — `HarnMaster-3-FoundryVTT` declares no `itemBuilders`, so a
+ * type living in the SoHL registry would be unavailable to HM3 and to every HM3
+ * module, which is most of the packages that need a homepage and nothing else.
+ *
+ * **Its address is the package's, not the note's.** A homepage publishes at
+ * `/<contentPackage>/` because that is where the package is, so `name.full`,
+ * `shortcode` and `id` decide nothing on it (#53 refuses them outright; this
+ * module simply never reads them). It compiles into no document, so it carries
+ * no compendium UUID and appears in no pack and in no link-manifest entry.
+ *
+ * @module
+ */
+
+import { matchAllOutsideCode } from "./code-fences.mjs";
+
+/**
+ * The note type that compiles to the package homepage.
+ *
+ * @type {string}
+ */
+export const HOMEPAGE_TYPE = "homepage";
+
+/**
+ * What a homepage note may write under `sohl:` — nothing.
+ *
+ * Empty on purpose, and declared rather than omitted: a type with no vocabulary
+ * and a type that is unknown are different findings, and only the second is an
+ * authoring error. The whole envelope is the two top-level keys `type` and an
+ * optional `title`; there is no game-system data on a page that compiles to no
+ * document.
+ *
+ * @type {readonly import("./field-spec.mjs").FieldSpec[]}
+ */
+export const HOMEPAGE_FIELDS = Object.freeze([]);
+
+/**
+ * Where a homepage is written, relative to the package's site root.
+ *
+ * Hugo's section landing, because the page *is* the package's landing: the
+ * package root is a section and this is its index.
+ *
+ * @type {string}
+ */
+export const HOMEPAGE_DESTINATION = "_index.md";
+
+/**
+ * Whether a note's frontmatter declares the homepage type.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether it is a homepage note.
+ */
+export function isHomepage(fm) {
+    return Boolean(fm) && fm.type === HOMEPAGE_TYPE;
+}
+
+/**
+ * The title a homepage publishes under.
+ *
+ * The one defaulted value on the page, and it defaults to the package's own
+ * `packageBuild.manifest.title` — the name Foundry already shows for the
+ * package — so a homepage that adds nothing to it need not restate it. An
+ * authored `title` wins, because a front page is allowed to greet a reader
+ * differently from a package browser.
+ *
+ * Falls back to `contentPackage` last, so a package that has no manifest of its
+ * own still yields a titled page rather than a blank heading.
+ *
+ * @param {object|null|undefined} fm - The note's frontmatter.
+ * @param {object} config - The resolved configuration.
+ * @returns {string} The title.
+ */
+export function homepageTitle(fm, config) {
+    const authored = fm?.title;
+    if (typeof authored === "string" && authored.trim()) return authored;
+    const manifest = /** @type {Record<string, unknown>|undefined} */ (
+        config?.packageBuild?.manifest
+    );
+    const title = manifest?.title;
+    return typeof title === "string" && title.trim() ?
+            title
+        :   config.contentPackage;
+}
+
+/**
+ * The frontmatter a homepage publishes with.
+ *
+ * The note's own, plus the two derived values every emitted page carries: the
+ * resolved `title`, and the package the build derived — no note declares one
+ * (`package:` is retired, #56) and the theme's breadcrumb partial reads
+ * `.Params.package`.
+ *
+ * An authored `aliases` is dropped for the same reason it is on every other
+ * page: Obsidian reads it as names a reader might call the note, Hugo reads it
+ * as URL redirects, and passing it through would publish a redirect stub at
+ * each one.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package this build publishes.
+ * @param {string} options.title - The resolved title.
+ * @returns {object} The frontmatter to write.
+ */
+export function homepageFrontmatter(fm, { contentPackage, title }) {
+    const data = { ...fm, package: contentPackage, title };
+    delete data.aliases;
+    return data;
+}
+
+/**
+ * An inline markdown link — `[text](target)`, but not an image.
+ *
+ * Reference-style links are deliberately not matched: a landing's prose fields
+ * are single YAML scalars with nowhere to put a link definition, so a `[x][y]`
+ * in one could never resolve and is not an address anybody wrote.
+ *
+ * @type {RegExp}
+ */
+const MARKDOWN_LINK = /(?<!!)\[[^\]]*\]\(\s*([^)\s]+)(?:\s+"[^"]*")?\s*\)/g;
+
+/**
+ * The two frontmatter keys that hold an address, and what each one means.
+ *
+ * They are **not** interchangeable, and a check that treated them as one would
+ * be wrong about both. The theme resolves a `url` against the site with
+ * `relURL`, so a package writes `kb/rules/` and is served `/sohl/kb/rules/`
+ * without ever naming its own prefix. An `href` is an address that is *already*
+ * resolved and is used verbatim — which is what `cards.source: sections` fills
+ * in, since a section's permalink already carries the prefix.
+ *
+ * So a leading `/` is a defect in a `url` (it is prefixed a second time) and
+ * correct in an `href`.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const HOMEPAGE_ADDRESS_KEYS = Object.freeze(new Set(["url", "href"]));
+
+/**
+ * Collect the markdown links in one prose value.
+ *
+ * @param {string} text - The value.
+ * @param {string} field - Where it came from.
+ * @param {string} kind - The address kind to record.
+ * @param {object[]} out - Accumulator.
+ * @param {boolean} [skipCode] - Whether to ignore links inside code.
+ */
+function collectProse(text, field, kind, out, skipCode = false) {
+    const pattern = new RegExp(MARKDOWN_LINK.source, "g");
+    const matches =
+        skipCode ?
+            matchAllOutsideCode(text, pattern)
+        :   [...text.matchAll(pattern)];
+    for (const m of matches) out.push({ field, url: m[1], kind });
+}
+
+/**
+ * Every address a homepage carries, wherever it is written.
+ *
+ * **Both halves of the page are in scope, and that is the finding rather than
+ * the assumption.** Of the six homepages authored today, four carry every link
+ * in the body as ordinary markdown and two carry them in `landing:` — and the
+ * one whose dead links prompted the check has an *empty body*, so a body-only
+ * reading would have found nothing at all on it. A dead link in a card is
+ * exactly as broken as one in a paragraph.
+ *
+ * Three shapes are gathered, and the caller needs to tell them apart because
+ * the rules differ:
+ *
+ * - **`url`** — package-relative, resolved against the site by the theme.
+ * - **`href`** — already resolved, used verbatim.
+ * - **prose and body markdown links** — emitted as written and resolved by the
+ *   browser against the landing's own address, which *is* the package root, so
+ *   a relative one means the same thing a `url` does.
+ *
+ * `banner:` is not an address: it is an image path resolved through the CDN
+ * base, and `banner: none` is a sentinel rather than a target. Top-level
+ * `title` and `description` are not walked either — they are set as text, never
+ * rendered as markdown.
+ *
+ * @param {object|null|undefined} fm - The note's frontmatter.
+ * @param {string} [body] - The note's markdown body.
+ * @returns {Array<{field: string, url: string, kind: string}>} Every address,
+ *   frontmatter first and then the body, each with the dotted path it was
+ *   written at.
+ */
+export function homepageAddresses(fm, body = "") {
+    const out = [];
+
+    const walk = (value, field) => {
+        if (typeof value === "string") {
+            collectProse(value, field, "prose", out);
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((v, i) => walk(v, `${field}[${i}]`));
+            return;
+        }
+        if (!value || typeof value !== "object") return;
+        for (const [key, v] of Object.entries(value)) {
+            const child = `${field}.${key}`;
+            // An address field holds an address, not prose: reading it for
+            // markdown links as well would report the same target twice
+            // whenever one happened to look like a link.
+            if (HOMEPAGE_ADDRESS_KEYS.has(key) && typeof v === "string") {
+                out.push({ field: child, url: v, kind: key });
+                continue;
+            }
+            walk(v, child);
+        }
+    };
+
+    walk(fm?.landing, "landing");
+    collectProse(String(body ?? ""), "body", "body", out, true);
+    return out;
+}

package/engine/index.mjs

@@ -60,6 +60,12 @@ export * as notePackage from "./note-package.mjs";
 /** Frontmatter fields a note may no longer declare, and the refusal of them. */
 export * as retiredFields from "./retired-fields.mjs";
 
+/** The package homepage: the note type that compiles to a page, not a document. */
+export * as homepage from "./homepage.mjs";
+
+/** The note types the engine itself declares, whatever a consumer registers. */
+export * as noteSchemas from "./note-schemas.mjs";
+
 /** The shipped Foundry manifest: locating it, reading it, guarding its id. */
 
 /** The URL a content note is published at — the one web-address rule. */

package/engine/manifest-emit.mjs

@@ -59,6 +59,7 @@ import { assertNoDraftField } from "./retired-fields.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
+import { publishesContentPages } from "../content-config.mjs";
 
 /**
  * The reserved anchor name for a journal's **first** page.
@@ -271,7 +272,7 @@ export function manifestContext(config = loadPackConfig()) {
         foundryPackageId: config.foundryPackage,
         packRouter: routerFor(config),
         scheme: config.publish.address,
-        web: config.publish.site,
+        web: publishesContentPages(config),
         // The walk's own configuration, threaded through rather than left to
         // its default, so a caller that passes a config drives every read.
         skipDirectories: config.skipDirectories,

package/engine/note-schemas.mjs

@@ -0,0 +1,44 @@
+/*
+ * 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 note types the **engine** declares — the ones whose vocabulary is a fact
+ * about the note format rather than about any game system (#51).
+ *
+ * `sohl/note-schemas.mjs` is the other half, and the line between them is the
+ * `engine/` ÷ `sohl/` line everywhere else in this package: note-format
+ * knowledge here, game-system knowledge there. It is not a permission boundary
+ * between consumers — every content project authors the full vocabulary — but it
+ * is a reachability one in exactly one direction. A package that declares no
+ * `itemBuilders` (`HarnMaster-3-FoundryVTT`, and every HM3 module) uses only the
+ * packaging half of the toolchain, so a type declared in the SoHL registry would
+ * be unavailable to it. These are the types every package has, whatever it
+ * ships.
+ *
+ * One entry today. A consumer merges it under its own registry —
+ * `{ ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS }` — so a game system may extend
+ * these but the engine's declaration stands wherever no registry is configured.
+ *
+ * @module
+ */
+
+import { HOMEPAGE_FIELDS, HOMEPAGE_TYPE } from "./homepage.mjs";
+
+/**
+ * Every engine-level content type, and what a note of that type may write.
+ *
+ * @type {Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>}
+ */
+export const ENGINE_NOTE_SCHEMAS = Object.freeze({
+    [HOMEPAGE_TYPE]: HOMEPAGE_FIELDS,
+});

package/engine/pack-config.mjs

@@ -453,6 +453,9 @@ function loadCodeConfig(configPath) {
 /** The loaded configuration, memoised — the file is read at most once. */
 let loaded;
 
+/** The file {@link loadPackConfig} read, alongside the memoised result. */
+let loadedFrom;
+
 /**
  * The consuming repository's resolved, frozen configuration.
  *
@@ -492,5 +495,23 @@ export function loadPackConfig() {
                 YAML.parse(fs.readFileSync(configPath, "utf8")),
                 configPath,
             );
+    loadedFrom = configPath;
     return loaded;
 }
+
+/**
+ * The file {@link loadPackConfig} resolved the configuration from.
+ *
+ * A diagnostic about a *configured* value has to name the file it was declared
+ * in, and re-deriving that path at the point of the finding would be a second
+ * resolution free to disagree with the first — the `PACKAGE_BUILD_CONFIG`
+ * override, the upward walk and the one-file-per-directory rule all have to
+ * come out the same way. This reports the path actually read.
+ *
+ * @returns {string} Its absolute path.
+ * @throws {Error} As {@link loadPackConfig}, when there is no configuration.
+ */
+export function packConfigPath() {
+    loadPackConfig();
+    return /** @type {string} */ (loadedFrom);
+}