@heroiclands/package-build 0.1.0

package/LICENSE.md

@@ -0,0 +1,25 @@
+# License Information
+
+`@heroiclands/content-build` is **source code only** and is licensed under
+[GPL-3.0-or-later](https://www.gnu.org/licenses/gpl-3.0.html).
+
+Unlike the Song of Heroic Lands system repository, this package carries no
+creative content, so the CC-BY-SA-4.0 half of that project's dual licence does
+not apply here. The content trees this toolchain _compiles_ are licensed by the
+repositories that hold them, and their licences are unaffected by this one.
+
+## Source Code License
+
+Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <https://www.gnu.org/licenses/>.

package/README.md

@@ -0,0 +1,105 @@
+# @heroiclands/package-build
+
+The shared toolchain for building and shipping a HeroicLands **Foundry
+package** — the parts Foundry loads whether or not the package ships any
+content.
+
+It is the counterpart to
+[`@heroiclands/content-build`](https://github.com/HeroicLands/content-build), and
+the two split by **input**:
+
+| Package         | Reads                                                        | Produces                                                       |
+| --------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |
+| `content-build` | `assets/content/**`                                          | compendium packs, site content, link manifest                  |
+| `package-build` | `lang/`, `styles/`, `src/`, `assets/`, the manifest template | `system.json` / `module.json`, styles, bundle, release archive |
+
+A module uses either, or both. An adventure module that ships only notes needs
+no bundler; a variant module that ships only behavior needs no Markdown
+pipeline. The coupling runs one way — `package-build` asks `content-build` for
+the compiled `packs[]` block, never the reverse.
+
+## Install
+
+```
+npm install -D @heroiclands/package-build
+```
+
+## What it covers
+
+The whole of assemble → validate → ship, one subpath each:
+
+- **`manifest`** — the Foundry package manifest, `system.json` or `module.json`:
+  read the repository's template, stamp the version and the four release
+  addresses, write it into the stage. The artifact is inferred from the
+  template's name, and every address is derived from `package.json`'s
+  `repository` — nothing is transcribed.
+- **`stage`** — assembling the build stage and clearing it away again. A listed
+  asset path that does not exist **fails the build** rather than shipping a
+  package that quietly lacks its localization or its templates, and the whole
+  list is checked before anything is copied, so a bad list leaves no
+  half-populated stage.
+- **`lang`** — what a shippable Foundry localization file must satisfy: it
+  parses, its top level is an object, no key is both a leaf and a dotted prefix
+  of another, placeholders are single-braced, and key segments carry no data.
+- **`bundle`** — whether the manifest agrees with the file it points at.
+  Declared under `"esmodules"` the bundle must parse as a module; declared under
+  `"scripts"` it must declare **nothing** at top level, because every top-level
+  declaration in a classic script is a global lexical binding and one colliding
+  with a non-configurable `window` property throws at parse time.
+- **`release`** — the two assets a GitHub Release carries, `<artifact>.zip` and
+  the manifest beside it. Waits for the archive to be _written_, not merely
+  finalized.
+- **`deploy`** — installing a staged package into a Foundry data directory, over
+  a local copy or SFTP. Always a staged, atomic swap: a running Foundry holds
+  its LevelDB packs open, and replacing them in place leaves a directory LevelDB
+  "repairs" to zero.
+- **`text`** — locating a literal inside a file, so a finding names the line and
+  column it is about.
+
+## Design
+
+**The rules are pure, and I/O is confined to functions named for it.** A rule
+takes source text or data and returns findings or values; discovery and
+reporting stay with the caller. Where a step genuinely has to touch disk or a
+network it is an export named for what it does — `writeFoundryManifest`,
+`stageAssets`, `packRelease`, `deployStage`.
+
+That is what lets one rule set serve a `lint` script, a build step and a unit
+test without any of them agreeing on how files are found or how findings are
+printed — and it is what makes the rules testable at all, which the scripts they
+were extracted from were not: each ran its work at import time and exported
+nothing.
+
+Findings carry the fields the shared diagnostic format takes (`line`, `column`,
+`severity`, `message`) but never `file`, which only the caller knows. The format
+itself is owned by `@heroiclands/content-build`'s `engine/diagnostics`, and is
+not restated here.
+
+```js
+import { validateLangSource } from "@heroiclands/package-build/lang";
+
+for (const file of globSync("lang/*.json")) {
+  for (const finding of validateLangSource(readFileSync(file, "utf8"))) {
+    reportDiagnostic({ file, ...finding });
+  }
+}
+```
+
+## Tests
+
+```
+npm test
+```
+
+Plain `vitest`, no setup file and no aliases: everything here is ESM over Node
+built-ins and three dependencies, and a harness that offered a Foundry global
+would let something reach for one.
+
+`tests/dependencies-are-declared.test.ts` is the guard an extraction most needs
+— every bare specifier in a shipped file must be a builtin, this package, or a
+declared `dependency`. Inside a workspace a missing declaration is invisible;
+installed from npm it fails on the first import.
+
+## Licence
+
+GPL-3.0-or-later.

package/bundle.mjs

@@ -0,0 +1,250 @@
+/*
+ * 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 code bundle, and the one way a manifest can disagree with it.
+ *
+ * A package that ships behavior declares its entry point in the manifest, and
+ * **which key it uses decides how the browser parses the file**:
+ *
+ * - Under `"esmodules"` the file is an ES module. Every top-level `const`,
+ *   `let`, `class` and `function` is module-scoped — private to the bundle,
+ *   colliding with nothing.
+ * - Under `"scripts"` the file is a *classic script*. Those same declarations
+ *   become **global lexical bindings**, and one whose name matches a
+ *   non-configurable own property of `window` throws
+ *   `SyntaxError: Identifier 'x' has already been declared` at **parse time** —
+ *   before a single line of the package runs.
+ *
+ * That is not hypothetical. A bundle that inlines `@codemirror/view` carries
+ * `const chrome`, and `style-mod` carries `const top`; `window.chrome` is
+ * `configurable: false` and `window.top` is `[Unforgeable]`, so under
+ * `"scripts"` either one bricks the whole package on load. Shipping `"scripts"`
+ * is exactly how SoHL v0.8.0 broke. A minified bundle escapes it only by
+ * renaming the identifiers, which is luck rather than a property.
+ *
+ * So the check is not "is the manifest key right" — it is **does the manifest
+ * agree with the file it points at**. Declared as a module, the bundle must
+ * parse as one. Declared as a script, it must declare *nothing* at top level.
+ * That second invariant is list-free: it needs no catalogue of browser globals
+ * and holds whatever identifiers a future dependency introduces.
+ *
+ * The rules are pure functions over source text. Reading the stage is the
+ * caller's job.
+ *
+ * @module
+ */
+
+import { parse } from "acorn";
+
+/**
+ * The names a top-level statement would declare in global scope.
+ *
+ * Only declaration forms matter: an expression statement or a call declares
+ * nothing. Destructuring patterns are walked, so `const { a, b } = …` reports
+ * both names — a bundler emits those routinely, and missing them would let the
+ * check pass a bundle that does collide.
+ *
+ * @param {object} node - A top-level `Program.body` entry.
+ * @returns {string[]} Declared identifier names, empty when it declares none.
+ */
+export function declaredGlobals(node) {
+    /**
+     * @param {any} pattern - A binding pattern.
+     * @param {string[]} out - Names collected so far.
+     * @returns {string[]} `out`.
+     */
+    function namesIn(pattern, out) {
+        if (!pattern) return out;
+        switch (pattern.type) {
+            case "Identifier":
+                out.push(pattern.name);
+                break;
+            case "ObjectPattern":
+                for (const p of pattern.properties)
+                    namesIn(
+                        p.type === "RestElement" ? p.argument : p.value,
+                        out,
+                    );
+                break;
+            case "ArrayPattern":
+                for (const e of pattern.elements) namesIn(e, out);
+                break;
+            case "AssignmentPattern":
+                namesIn(pattern.left, out);
+                break;
+            case "RestElement":
+                namesIn(pattern.argument, out);
+                break;
+        }
+        return out;
+    }
+
+    switch (node.type) {
+        case "VariableDeclaration": {
+            const out = [];
+            for (const d of node.declarations) namesIn(d.id, out);
+            return out;
+        }
+        case "FunctionDeclaration":
+        case "ClassDeclaration":
+            return node.id ? [node.id.name] : [];
+        default:
+            return [];
+    }
+}
+
+/**
+ * How a manifest declares an entry file.
+ *
+ * @param {object} manifest - The parsed manifest.
+ * @param {string} entry - The entry file's name, as the manifest spells it.
+ * @returns {"esmodules"|"scripts"|"both"|"neither"} Where it is declared.
+ */
+export function entryDeclaration(manifest, entry) {
+    const asModule = (manifest?.esmodules ?? []).includes(entry);
+    const asScript = (manifest?.scripts ?? []).includes(entry);
+    if (asModule && asScript) return "both";
+    if (asModule) return "esmodules";
+    if (asScript) return "scripts";
+    return "neither";
+}
+
+/**
+ * Every top-level declaration a source would create in global scope.
+ *
+ * Parses as a **classic script**, which is the only parse under which the
+ * question means anything.
+ *
+ * @param {string} source - The bundle's source text.
+ * @returns {Array<{name: string, line: number, kind: string}>} The declarations.
+ * @throws {SyntaxError} When the source does not parse as a script.
+ */
+export function globalDeclarations(source) {
+    const program = parse(source, {
+        ecmaVersion: "latest",
+        sourceType: "script",
+        locations: true,
+    });
+    const found = [];
+    for (const node of program.body) {
+        for (const name of declaredGlobals(node)) {
+            found.push({ name, line: node.loc.start.line, kind: node.type });
+        }
+    }
+    return found;
+}
+
+/**
+ * Check that a manifest and the bundle it points at agree.
+ *
+ * @param {object} opts
+ * @param {object} opts.manifest - The parsed manifest.
+ * @param {string} opts.source - The bundle's source text.
+ * @param {string} opts.entry - The entry file's name, as the manifest spells it.
+ * @param {string} [opts.manifestName] - What to call the manifest in a message.
+ * @returns {{findings: Array<{line?: number, severity: "error", message: string}>,
+ *   declaredAs: "esmodules"|"scripts"|"both"|"neither"}} The findings, empty
+ *   when the two agree, and how the entry was declared.
+ */
+export function checkBundleLoading({
+    manifest,
+    source,
+    entry,
+    manifestName = "the manifest",
+}) {
+    const declaredAs = entryDeclaration(manifest, entry);
+
+    if (declaredAs === "both") {
+        return {
+            declaredAs,
+            findings: [
+                {
+                    severity: "error",
+                    message:
+                        `${manifestName} lists ${entry} under both "esmodules" and ` +
+                        `"scripts", so Foundry would load the bundle twice. List it ` +
+                        `under "esmodules" only.`,
+                },
+            ],
+        };
+    }
+
+    if (declaredAs === "neither") {
+        return {
+            declaredAs,
+            findings: [
+                {
+                    severity: "error",
+                    message:
+                        `${manifestName} declares ${entry} under neither "esmodules" ` +
+                        `nor "scripts", so Foundry would never load it. List it under ` +
+                        `"esmodules".`,
+                },
+            ],
+        };
+    }
+
+    if (declaredAs === "esmodules") {
+        // Declared a module, so it must be one. A bundle that only parses as a
+        // script would fail at load with a message about whichever `import`
+        // statement came first, naming nothing about the manifest.
+        try {
+            parse(source, { ecmaVersion: "latest", sourceType: "module" });
+        } catch (err) {
+            return {
+                declaredAs,
+                findings: [
+                    {
+                        severity: "error",
+                        message:
+                            `${entry} is declared under "esmodules" but does not ` +
+                            `parse as an ES module: ${err.message}`,
+                    },
+                ],
+            };
+        }
+        return { declaredAs, findings: [] };
+    }
+
+    // Declared a classic script: every top-level declaration becomes global.
+    let globals;
+    try {
+        globals = globalDeclarations(source);
+    } catch (err) {
+        return {
+            declaredAs,
+            findings: [
+                {
+                    severity: "error",
+                    message:
+                        `${entry} is declared under "scripts" but does not parse ` +
+                        `as a classic script: ${err.message}`,
+                },
+            ],
+        };
+    }
+
+    return {
+        declaredAs,
+        findings: globals.map(({ name, line, kind }) => ({
+            line,
+            severity: "error",
+            message:
+                `${kind} \`${name}\` is declared at global scope; under ` +
+                `"scripts" that is a global lexical binding, and one colliding ` +
+                `with a non-configurable window property throws at parse time ` +
+                `and breaks the whole package`,
+        })),
+    };
+}