@heroiclands/package-build 0.5.0 → 0.6.0

package/index.mjs

@@ -54,5 +54,17 @@ export * as release from "./release.mjs";
 /** Deploying a staged package into a Foundry data directory. */
 export * as deploy from "./deploy.mjs";
 
+/** Running a built package inside a Foundry VTT container. */
+export * as container from "./container.mjs";
+
+/** The end-to-end harness: a disposable world, served, with a suite driven at it. */
+export * as e2e from "./e2e.mjs";
+
 /** Localization files: what a shippable `lang/*.json` must satisfy. */
 export * as lang from "./lang.mjs";
+
+/** Localization coverage: the keys a package references against the keys it declares. */
+export * as coverage from "./coverage.mjs";
+
+/** Templates: whether their user-visible text is localized, and whether they compile. */
+export * as templates from "./templates.mjs";

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "0.5.0",
-    "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package \u2014 manifest, localization, staging, bundle, release and deployment.",
+    "version": "0.6.0",
+    "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
     "main": "./index.mjs",
@@ -15,10 +15,26 @@
             "types": "./types/bundle.d.mts",
             "import": "./bundle.mjs"
         },
+        "./config": {
+            "types": "./types/config.d.mts",
+            "import": "./config.mjs"
+        },
+        "./container": {
+            "types": "./types/container.d.mts",
+            "import": "./container.mjs"
+        },
+        "./coverage": {
+            "types": "./types/coverage.d.mts",
+            "import": "./coverage.mjs"
+        },
         "./deploy": {
             "types": "./types/deploy.d.mts",
             "import": "./deploy.mjs"
         },
+        "./e2e": {
+            "types": "./types/e2e.d.mts",
+            "import": "./e2e.mjs"
+        },
         "./lang": {
             "types": "./types/lang.d.mts",
             "import": "./lang.mjs"
@@ -27,6 +43,7 @@
             "types": "./types/manifest.d.mts",
             "import": "./manifest.mjs"
         },
+        "./package.json": "./package.json",
         "./release": {
             "types": "./types/release.d.mts",
             "import": "./release.mjs"
@@ -35,25 +52,28 @@
             "types": "./types/stage.d.mts",
             "import": "./stage.mjs"
         },
-        "./package.json": "./package.json",
-        "./config": {
-            "types": "./types/config.d.mts",
-            "import": "./config.mjs"
+        "./templates": {
+            "types": "./types/templates.d.mts",
+            "import": "./templates.mjs"
         }
     },
     "files": [
+        "CHANGELOG.md",
+        "README.md",
+        "bin",
         "bundle.mjs",
+        "config.mjs",
+        "container.mjs",
+        "coverage.mjs",
         "deploy.mjs",
+        "e2e.mjs",
         "index.mjs",
         "lang.mjs",
         "manifest.mjs",
         "release.mjs",
         "stage.mjs",
-        "types",
-        "CHANGELOG.md",
-        "README.md",
-        "bin",
-        "config.mjs"
+        "templates.mjs",
+        "types"
     ],
     "scripts": {
         "test": "vitest run",
@@ -67,19 +87,21 @@
         "prepare": "git config core.hooksPath .githooks || true"
     },
     "dependencies": {
+        "@foundryvtt/foundryvtt-cli": "^3.0.4",
         "@heroiclands/content-build": "^1.0.0",
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",
         "dotenv": "^17.2.3",
         "glob": "^11.0.3",
+        "handlebars": "^4.7.9",
         "ssh2-sftp-client": "^12.1.1",
+        "typescript": "^6.0.3",
         "yargs": "^18.1.0"
     },
     "devDependencies": {
         "@changesets/cli": "^3.0.0",
         "@types/node": "^26.2.0",
         "prettier": "^3.9.6",
-        "typescript": "^6.0.3",
         "vitest": "^4.1.10"
     },
     "engines": {

package/templates.mjs

@@ -0,0 +1,224 @@
+/*
+ * 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
+ */
+
+/**
+ * Whether a template's user-visible text goes through localization at all.
+ *
+ * This is the **reverse** of {@link module:coverage}, and the two are
+ * deliberate opposites. Coverage walks *key → file*: it can tell you that every
+ * key the code names exists, and it is completely blind to a template that
+ * names no key whatsoever. This walks *text → key*: every user-visible literal
+ * in the markup must be a `{{localize}}` call rather than English sitting in
+ * the file.
+ *
+ * The Song of Heroic Lands repository is the argument for having both. Before
+ * the work that prompted this guard there were **516 hardcoded English literals
+ * across 61 templates**, and translating every key in `en.json` would have left
+ * every one of them in English — a fully "translated" package that renders half
+ * in the translator's language and half in the author's.
+ *
+ * It also **compiles** every template, because the usual way to break one while
+ * localizing it is to nest `{{localize …}}` inside another mustache. That is
+ * legal in an HTML attribute and a parse error inside a helper's hash, where a
+ * `(localize …)` subexpression is required — so the mistake ships from a
+ * template that looks exactly like its working neighbour.
+ *
+ * Both functions are pure: source text in, findings out. Discovery, I/O and
+ * reporting stay with the caller.
+ *
+ * @module
+ */
+
+import Handlebars from "handlebars";
+import { positionOfLiteral } from "@heroiclands/content-build/engine/diagnostics";
+
+/**
+ * A single finding, in the fields the shared diagnostic format takes.
+ *
+ * `file` is absent for the same reason it is absent from a localization
+ * finding: these functions are handed source text, not a path.
+ *
+ * @typedef {object} TemplateFinding
+ * @property {number} [line] - 1-based line, omitted when it cannot be
+ *   established honestly.
+ * @property {number} [column] - 1-based column, omitted likewise.
+ * @property {"error"|"warning"} severity - How the finding should be treated.
+ * @property {string} message - What is wrong, in one sentence.
+ */
+
+/**
+ * Attributes whose value the user reads.
+ *
+ * Every one of these renders as prose somewhere — a tooltip, a placeholder, a
+ * screen reader's announcement — so English in one is as untranslated as
+ * English in a heading, and far easier to miss.
+ *
+ * @type {readonly string[]}
+ */
+export const VISIBLE_ATTRIBUTES = Object.freeze([
+    "title",
+    "placeholder",
+    "aria-label",
+    "alt",
+    "data-tooltip",
+    "data-title",
+]);
+
+/**
+ * Remove everything that is not user-visible prose.
+ *
+ * Handlebars expressions go first (their contents are code), then `<style>` and
+ * `<script>` bodies (theirs are too). What is left is what a player reads.
+ *
+ * Substitutions are single spaces rather than removals so that nothing new is
+ * glued together — `>{{a}}<` must not become `><`, which would read as an empty
+ * text node rather than as no text node at all.
+ *
+ * @param {string} source - The template source.
+ * @returns {string} The source with every non-prose region blanked.
+ */
+function stripNonProse(source) {
+    return source
+        .replace(/\{\{![\s\S]*?\}\}/g, " ")
+        .replace(/\{\{[^}]*\}\}/g, " ")
+        .replace(/<style[\s\S]*?<\/style>/g, " ")
+        .replace(/<script[\s\S]*?<\/script>/g, " ");
+}
+
+/**
+ * Whether a run of text is prose a player would expect in their own language.
+ *
+ * An HTML entity (`&infin;`, `&middot;`) is a symbol, not prose — its letters
+ * are markup — so entities are dropped before looking for words. Two letters is
+ * the threshold: it admits "OK" and excludes every unit, separator and numeral.
+ *
+ * @param {string} text - The candidate, whitespace already normalized.
+ * @param {Set<string>} allowed - Literals the repository has justified.
+ * @returns {boolean} Whether it should have been localized.
+ */
+function isProse(text, allowed) {
+    return (
+        /[A-Za-z]{2}/.test(text.replace(/&[a-zA-Z]+;|&#\d+;/g, " ")) &&
+        !allowed.has(text)
+    );
+}
+
+/**
+ * Every user-visible literal a template leaves untranslated.
+ *
+ * @param {string} source - The template source.
+ * @param {object} [options]
+ * @param {Iterable<string>} [options.allow] - Literals that are deliberately
+ *   not localization keys — a code sample shown as a placeholder, say. This is
+ *   the escape hatch, not the rule: anything that is ordinary UI prose belongs
+ *   in the localization file, and a repository states each entry with the
+ *   reason it cannot be one.
+ * @returns {TemplateFinding[]} The findings, in the order they appear.
+ */
+export function findHardcodedText(source, { allow = [] } = {}) {
+    const allowed = new Set(allow);
+    const stripped = stripNonProse(source);
+    const found = [];
+
+    /**
+     * Locate one literal in the **source**, not in the stripped text.
+     *
+     * The stripped copy has had substitutions of a different length, so a match
+     * index taken there cannot be carried across — the finding would name a
+     * position that drifts further from the truth the more Handlebars a file
+     * contains. Searching the source for the literal itself is exact, and
+     * counting occurrences keeps a literal that appears twice from reporting
+     * the same line twice.
+     *
+     * @param {string} needle - The literal exactly as the source spells it.
+     * @returns {{line?: number, column?: number}} Spreadable position fields.
+     */
+    const seen = new Map();
+    const at = (needle) => {
+        const occurrence = (seen.get(needle) ?? 0) + 1;
+        seen.set(needle, occurrence);
+        return positionOfLiteral(source, needle, occurrence);
+    };
+
+    for (const match of stripped.matchAll(/>([^<>]+)</g)) {
+        const text = match[1].replace(/\s+/g, " ").trim();
+        if (!isProse(text, allowed)) continue;
+        found.push({
+            ...at(match[1]),
+            severity: "error",
+            message: `hardcoded user-visible string: ${text}`,
+        });
+    }
+
+    for (const attr of VISIBLE_ATTRIBUTES) {
+        // `\b` alone would match `title` inside `data-title`, reporting one
+        // literal twice under two names; a hyphen is a word boundary to a
+        // regular expression and part of the attribute name to HTML.
+        const pattern = new RegExp(`(?<![\\w-])${attr}="([^"]*)"`, "g");
+        for (const match of stripped.matchAll(pattern)) {
+            const text = match[1].replace(/\s+/g, " ").trim();
+            if (!isProse(text, allowed)) continue;
+            found.push({
+                ...at(match[0]),
+                severity: "error",
+                message: `hardcoded user-visible string: ${attr}="${text}"`,
+            });
+        }
+    }
+
+    return found;
+}
+
+/**
+ * Whether the template compiles at all.
+ *
+ * Precompiling rather than compiling: the question is whether Handlebars can
+ * *parse* the source, and precompilation answers it without needing any of the
+ * helpers the template calls to exist.
+ *
+ * @param {string} source - The template source.
+ * @returns {TemplateFinding[]} One finding when it does not parse, else none.
+ */
+export function findTemplateSyntaxErrors(source) {
+    try {
+        Handlebars.precompile(source);
+        return [];
+    } catch (err) {
+        // Handlebars states a position three different ways depending on which
+        // stage rejected the template, and populates `hash.loc` for almost
+        // none of them — so the line printed in its own message is the one that
+        // is usually there. Reading it back is not guesswork: it is Handlebars'
+        // answer, in the only place this error carries it.
+        const loc = err?.hash?.loc;
+        const stated = /Parse error on line (\d+)/.exec(String(err?.message));
+        const line =
+            loc?.first_line ??
+            err?.lineNumber ??
+            (stated ? Number(stated[1]) : undefined);
+        return [
+            {
+                ...(typeof line === "number" ? { line } : {}),
+                ...((
+                    typeof line === "number" &&
+                    typeof loc?.first_column === "number"
+                ) ?
+                    { column: loc.first_column + 1 }
+                :   {}),
+                severity: "error",
+                message: `template does not compile: ${
+                    String(err).split("\n")[0]
+                }`,
+            },
+        ];
+    }
+}

package/types/config.d.mts

@@ -21,9 +21,43 @@
  *                                   conventional build artifacts.
  * @property {string} langSources    Glob for the localization files to check.
  * @property {string|null} langHelp  Extra guidance printed after a failure.
+ * @property {string} langPrimary    The localization file coverage is measured
+ *                                   against — the one the package authors.
+ * @property {readonly string[]} langScripts    Globs for the sources scanned
+ *                                   for key references.
+ * @property {readonly string[]} langTemplates  Globs for the templates scanned
+ *                                   for references and for hardcoded text.
+ * @property {readonly string[]|null} langKeyRoots  The key roots, when the
+ *                                   package references one its file does not
+ *                                   yet declare. `null` derives them.
+ * @property {string|null} langReferences  Module to load a `references`
+ *                                   function from, contributing the keys only
+ *                                   this repository's conventions can find.
+ * @property {readonly string[]} langRetained  Key prefixes exempt from the
+ *                                   unreferenced advisory.
+ * @property {readonly string[]} langAllow  Template literals that are
+ *                                   deliberately not localization keys.
  * @property {string} envPrefix      Prefix of the deploy environment variables.
  * @property {string} bundleEntry   The bundle file Foundry loads, as the
  *   manifest spells it. Derived from the package id.
+ * @property {string|null} compatibilityMinimum  The Foundry floor the package
+ *   claims, read from the shared configuration's top level.
+ * @property {string} systemId       The system a world runs — the package
+ *   itself for a system, its target for a module.
+ * @property {string|null} systemVersion  That system's version, when the shared
+ *   configuration stamps one.
+ * @property {string|null} containerImage  Image override for every stage.
+ * @property {Readonly<Record<string, Readonly<{port: number|null, world: string|null, version: string|null}>>>} containerStages
+ *   Container stages beyond the conventional four.
+ * @property {string} e2eStage       Which stage the suite runs against.
+ * @property {Readonly<{run: readonly string[], open: readonly string[]|null}>|null} e2eSuite
+ *   What to run against the served world; `null` when the repository has none.
+ * @property {Readonly<Record<string, Readonly<{script: string, recreate: boolean}>>>} e2eBuild
+ *   Build targets the fast loop can produce, in declaration order.
+ * @property {Readonly<Record<string, string>>} e2eWorld  Declared world identity.
+ * @property {Readonly<Record<string, string>>} e2eGm  Declared GM credentials.
+ * @property {Readonly<Record<string, string>>} e2eDocuments  Extra world
+ *   collections, as collection → source directory.
  */
 /**
  * Resolve a package-build configuration from an already-loaded shared one.
@@ -133,6 +167,43 @@ export type PackageBuildConfig = {
      * Extra guidance printed after a failure.
      */
     langHelp: string | null;
+    /**
+     * The localization file coverage is measured
+     * against — the one the package authors.
+     */
+    langPrimary: string;
+    /**
+     * Globs for the sources scanned
+     * for key references.
+     */
+    langScripts: readonly string[];
+    /**
+     * Globs for the templates scanned
+     * for references and for hardcoded text.
+     */
+    langTemplates: readonly string[];
+    /**
+     * The key roots, when the
+     * package references one its file does not
+     * yet declare. `null` derives them.
+     */
+    langKeyRoots: readonly string[] | null;
+    /**
+     * Module to load a `references`
+     * function from, contributing the keys only
+     * this repository's conventions can find.
+     */
+    langReferences: string | null;
+    /**
+     * Key prefixes exempt from the
+     * unreferenced advisory.
+     */
+    langRetained: readonly string[];
+    /**
+     * Template literals that are
+     * deliberately not localization keys.
+     */
+    langAllow: readonly string[];
     /**
      * Prefix of the deploy environment variables.
      */
@@ -142,4 +213,62 @@ export type PackageBuildConfig = {
      * manifest spells it. Derived from the package id.
      */
     bundleEntry: string;
+    /**
+     * The Foundry floor the package
+     * claims, read from the shared configuration's top level.
+     */
+    compatibilityMinimum: string | null;
+    /**
+     * The system a world runs — the package
+     * itself for a system, its target for a module.
+     */
+    systemId: string;
+    /**
+     * That system's version, when the shared
+     * configuration stamps one.
+     */
+    systemVersion: string | null;
+    /**
+     * Image override for every stage.
+     */
+    containerImage: string | null;
+    /**
+     *   Container stages beyond the conventional four.
+     */
+    containerStages: Readonly<Record<string, Readonly<{
+        port: number | null;
+        world: string | null;
+        version: string | null;
+    }>>>;
+    /**
+     * Which stage the suite runs against.
+     */
+    e2eStage: string;
+    /**
+     *   What to run against the served world; `null` when the repository has none.
+     */
+    e2eSuite: Readonly<{
+        run: readonly string[];
+        open: readonly string[] | null;
+    }> | null;
+    /**
+     *   Build targets the fast loop can produce, in declaration order.
+     */
+    e2eBuild: Readonly<Record<string, Readonly<{
+        script: string;
+        recreate: boolean;
+    }>>>;
+    /**
+     * Declared world identity.
+     */
+    e2eWorld: Readonly<Record<string, string>>;
+    /**
+     * Declared GM credentials.
+     */
+    e2eGm: Readonly<Record<string, string>>;
+    /**
+     * Extra world
+     * collections, as collection → source directory.
+     */
+    e2eDocuments: Readonly<Record<string, string>>;
 };