@heroiclands/package-build 0.5.0 → 0.6.1

package/bin/package-build.mjs

@@ -51,14 +51,20 @@
  *   npx package-build assets
  *   npx package-build manifest
  *   npx package-build lang check
+ *   npx package-build lang coverage [--unused]
+ *   npx package-build lang hardcoded
  *   npx package-build bundle check
  *   npx package-build release
  *   npx package-build deploy <stage>
+ *   npx package-build container <stage> <action>
+ *   npx package-build e2e <seed|run|open|fast|sweep>
  *
  * In a consuming repository, wrapped as npm scripts — SoHL spells them:
  *   npm run clean                          // → … clean
  *   npm run build:assets                   // → … assets
  *   npm run lint:lang                      // → … lang check
+ *   npm run lint:lang-coverage             // → … lang coverage
+ *   npm run lint:lang-hardcoded            // → … lang hardcoded
  *   npm run lint:bundle-globals            // → … bundle check
  *   npm run build:pack-release             // → … release
  *   npm run push:qa                        // → … deploy qa
@@ -75,12 +81,36 @@ import { loadPackageBuildConfig } from "../config.mjs";
 import { loadPackConfig } from "@heroiclands/content-build/engine/pack-config";
 import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
 import { validateLangSource } from "../lang.mjs";
+import {
+    analyzeCoverage,
+    collectScriptReferences,
+    collectTemplateReferences,
+    keyRootsOf,
+    mergeReferences,
+} from "../coverage.mjs";
+import { findHardcodedText, findTemplateSyntaxErrors } from "../templates.mjs";
 import { checkBundleLoading } from "../bundle.mjs";
 import { packRelease } from "../release.mjs";
 import { writeManifest } from "../manifest.mjs";
 import { deployStage } from "../deploy.mjs";
+import { CONTAINER_ACTIONS, containerAction } from "../container.mjs";
+import {
+    E2E_MODES,
+    e2eFast,
+    e2eRun,
+    e2eSweep,
+    seedTestWorld,
+} from "../e2e.mjs";
 import { reportFindings } from "./report.mjs";
 
+/**
+ * How many unreferenced keys a run prints before it summarizes the rest.
+ *
+ * Enough to see the shape of the problem, few enough that the errors above
+ * them are still on the screen.
+ */
+const ADVISORY_PREVIEW = 20;
+
 /**
  * This package's own version, for `--version`.
  *
@@ -130,6 +160,55 @@ function handler(run) {
     };
 }
 
+/**
+ * Load the repository's environment files.
+ *
+ * Done inside a handler rather than at module scope: `--help` and `--version`
+ * must answer in a directory with no environment file — or no configuration —
+ * at all.
+ *
+ * @param {object} config - The resolved package-build configuration.
+ * @returns {Promise<void>} Once `.env.local` and `.env` have been applied.
+ */
+async function loadEnvironment(config) {
+    const dotenv = await import("dotenv");
+    dotenv.config({
+        path: path.join(config.rootDir, ".env.local"),
+        quiet: true,
+    });
+    dotenv.config({ path: path.join(config.rootDir, ".env"), quiet: true });
+}
+
+/**
+ * The repository's own `package.json`.
+ *
+ * @param {object} config - The resolved package-build configuration.
+ * @returns {object} The parsed manifest.
+ */
+function readPackageJson(config) {
+    return JSON.parse(
+        fs.readFileSync(path.join(config.rootDir, "package.json"), "utf8"),
+    );
+}
+
+/**
+ * Everything the user typed after an `e2e` action, verbatim.
+ *
+ * Read from the raw arguments rather than from yargs, because most of it is not
+ * this command line's to interpret: `--spec`, `--browser`, a `--` passthrough
+ * and whatever else belongs to the repository's suite. Parsing it here would
+ * mean this package learning the flags of a runner it deliberately knows
+ * nothing about.
+ *
+ * @param {string} action - The action that was run.
+ * @returns {string[]} The arguments after it.
+ */
+function e2eTail(action) {
+    const raw = hideBin(process.argv);
+    const at = raw.indexOf(action);
+    return at === -1 ? [] : raw.slice(at + 1);
+}
+
 /**
  * `clean` — remove this repository's build artifacts.
  *
@@ -246,12 +325,7 @@ function manifestCommand() {
         handler: handler(async () => {
             const config = loadPackageBuildConfig();
             const shared = loadPackConfig();
-            const packageJson = JSON.parse(
-                fs.readFileSync(
-                    path.join(config.rootDir, "package.json"),
-                    "utf8",
-                ),
-            );
+            const packageJson = readPackageJson(config);
 
             let flags;
             if (config.manifestFlags) {
@@ -290,6 +364,26 @@ function manifestCommand() {
     };
 }
 
+/**
+ * Every file matching a glob, as `{ path, text }` with the path relative to the
+ * repository root — the form both the rules and the findings want.
+ *
+ * @param {string|readonly string[]} globs - Glob or globs, relative to the root.
+ * @param {string} rootDir - The repository root.
+ * @returns {{path: string, text: string}[]} The files, in path order.
+ */
+function readMatching(globs, rootDir) {
+    return globSync([...(Array.isArray(globs) ? globs : [globs])], {
+        cwd: rootDir,
+        absolute: true,
+    })
+        .sort()
+        .map((file) => ({
+            path: path.relative(rootDir, file),
+            text: fs.readFileSync(file, "utf8"),
+        }));
+}
+
 /**
  * `lang check` — verify every localization file survives `expandObject`.
  *
@@ -297,6 +391,251 @@ function manifestCommand() {
  * Foundry then drops the whole translation file silently. The rule is the
  * library's; the glob and any repository-specific guidance are data.
  *
+ * @param {Readonly<import("../config.mjs").PackageBuildConfig>} config
+ * @returns {void}
+ */
+function langCheck(config) {
+    const files = readMatching(config.langSources, config.rootDir);
+    if (!files.length) {
+        die(
+            `no localization files matched \`${config.langSources}\` under ` +
+                `${config.rootDir}.`,
+        );
+    }
+
+    let total = 0;
+    for (const file of files) {
+        total += reportFindings(validateLangSource(file.text), {
+            file: file.path,
+        });
+    }
+
+    if (total) {
+        if (config.langHelp) console.error(`\n${config.langHelp}`);
+        process.exit(1);
+    }
+    console.log(
+        `package-build: ${files.length} localization file(s) are ` +
+            `expandObject-safe.`,
+    );
+}
+
+/**
+ * `lang coverage` — does every key the package references exist, and is every
+ * key it declares referenced?
+ *
+ * The two halves are not the same severity. A referenced key that is missing
+ * renders to a player as its own raw key string, so it fails the run; a key
+ * nothing references is reported and does not, because no scan can see every
+ * way a key is reached and a guard that fails over one teaches people to switch
+ * it off.
+ *
+ * A repository that *generates* keys by a convention of its own names a module
+ * in `packageBuild.lang.references`, exporting
+ * `references(context) -> ReferenceSet`. That is the same shape as
+ * `assetTransform` and `manifestFlags`, and for the same reason: only that
+ * repository can know its rule, and only this package can compare the result
+ * against the file.
+ *
+ * @param {Readonly<import("../config.mjs").PackageBuildConfig>} config
+ * @param {object} args - The parsed argv.
+ * @returns {Promise<void>}
+ */
+async function langCoverage(config, args) {
+    const langFile = config.langPrimary;
+    const langPath = path.join(config.rootDir, langFile);
+    if (!fs.existsSync(langPath)) {
+        die(
+            `no localization file at ${langFile} — name the one this package ` +
+                `authors in \`packageBuild.lang.primary\`.`,
+        );
+    }
+    const langSource = fs.readFileSync(langPath, "utf8");
+
+    /**
+     * Report and exit, so the two exits — nothing to compare against, and a
+     * comparison that failed — read the same way.
+     *
+     * @param {object} analysis - What {@link analyzeCoverage} returned.
+     * @returns {void}
+     */
+    const finish = ({ findings, unreferenced, stats }) => {
+        const errors = reportFindings(findings, {});
+        // Capped by default: the advisory half of a large package is pages
+        // long, and pages of warnings on every build is how a guard stops being
+        // read at all. The count is always stated, so nothing is hidden.
+        const shown =
+            args.unused ? unreferenced : (
+                unreferenced.slice(0, ADVISORY_PREVIEW)
+            );
+        reportFindings(shown, {});
+        if (shown.length < unreferenced.length) {
+            console.error(
+                `package-build: ${unreferenced.length - shown.length} further ` +
+                    `unreferenced key(s) not shown — run with --unused.`,
+            );
+        }
+
+        console.log(
+            `package-build: ${stats.declared} key(s) declared in ${langFile} · ` +
+                `${stats.referenced} referenced · ` +
+                `${stats.namespaces} namespace(s) · ` +
+                `${stats.patterns} dynamic shape(s) · ` +
+                `${stats.missing} missing · ` +
+                `${stats.unreferenced} unreferenced`,
+        );
+        if (errors) process.exit(1);
+    };
+
+    let declaredKeys;
+    try {
+        declaredKeys = Object.keys(JSON.parse(langSource));
+    } catch {
+        // Scanning would be pointless: with nothing to compare against, every
+        // key the package references reports as missing. `analyzeCoverage`
+        // says the one true thing instead.
+        finish(
+            analyzeCoverage({
+                langSource,
+                langFile,
+                references: {
+                    keys: [],
+                    namespaces: [],
+                    patterns: [],
+                    findings: [],
+                },
+            }),
+        );
+        return;
+    }
+
+    const roots = config.langKeyRoots ?? keyRootsOf(declaredKeys);
+    const scripts = readMatching(config.langScripts, config.rootDir);
+    const templates = readMatching(config.langTemplates, config.rootDir);
+    // Named rather than left to pass: with nothing scanned, every key reports
+    // as unreferenced and nothing reports as missing, so a run that looked at
+    // no files at all would exit zero and prove nothing.
+    if (!scripts.length && !templates.length) {
+        die(
+            `no sources matched \`${config.langScripts.join("`, `")}\` or ` +
+                `\`${config.langTemplates.join("`, `")}\` under ` +
+                `${config.rootDir}.`,
+        );
+    }
+    const sets = [
+        ...scripts.map((file) =>
+            collectScriptReferences(file.text, { file: file.path, roots }),
+        ),
+        ...templates.map((file) =>
+            collectTemplateReferences(file.text, { file: file.path, roots }),
+        ),
+    ];
+
+    if (config.langReferences) {
+        const module = await import(`file://${config.langReferences}`).catch(
+            (err) =>
+                die(
+                    `cannot load \`packageBuild.lang.references\` ` +
+                        `(${config.langReferences}): ${err.message}`,
+                ),
+        );
+        if (typeof module.references !== "function") {
+            die(
+                `\`packageBuild.lang.references\` ` +
+                    `(${config.langReferences}) exports no \`references\` ` +
+                    `function. It must export ` +
+                    `\`references(context) -> ReferenceSet\`.`,
+            );
+        }
+        sets.push(
+            await module.references({
+                config: loadPackConfig(),
+                rootDir: config.rootDir,
+                roots,
+                // The sources, already read, so the contributor sees exactly
+                // the text the built-in scan saw.
+                files: scripts,
+            }),
+        );
+    }
+
+    finish(
+        analyzeCoverage({
+            langSource,
+            langFile,
+            references: mergeReferences(sets),
+            retained: config.langRetained,
+            roots,
+        }),
+    );
+}
+
+/**
+ * `lang hardcoded` — does the markup's user-visible text go through
+ * localization, and does each template still compile?
+ *
+ * The reverse of `lang coverage`, which walks key → file and is blind to a
+ * template that mentions no key at all.
+ *
+ * @param {Readonly<import("../config.mjs").PackageBuildConfig>} config
+ * @returns {void}
+ */
+function langHardcoded(config) {
+    const templates = readMatching(config.langTemplates, config.rootDir);
+    if (!templates.length) {
+        die(
+            `no templates matched ` +
+                `\`${config.langTemplates.join("`, `")}\` under ` +
+                `${config.rootDir}.`,
+        );
+    }
+
+    let literals = 0;
+    let broken = 0;
+    for (const file of templates) {
+        literals += reportFindings(
+            findHardcodedText(file.text, { allow: config.langAllow }),
+            { file: file.path },
+        );
+        broken += reportFindings(findTemplateSyntaxErrors(file.text), {
+            file: file.path,
+        });
+    }
+
+    if (literals || broken) {
+        if (literals) {
+            console.error(
+                `\npackage-build: ${literals} user-visible literal(s) are not ` +
+                    `localized. Replace each with a {{localize}} call and add ` +
+                    `the key, or record it in \`packageBuild.lang.allow\` with ` +
+                    `the reason it is not prose.`,
+            );
+        }
+        if (broken) {
+            console.error(
+                `\npackage-build: ${broken} template(s) do not compile. A ` +
+                    `{{localize …}} nested inside another mustache is legal in ` +
+                    `an HTML attribute but a parse error inside a helper's ` +
+                    `hash — use a (localize …) subexpression there.`,
+            );
+        }
+        process.exit(1);
+    }
+
+    console.log(
+        `package-build: ${templates.length} template(s) fully localized and ` +
+            `compiling.`,
+    );
+}
+
+/**
+ * `lang <action>` — the three localization guards.
+ *
+ * They are three questions about one subject, and each is blind to what the
+ * others see: `check` asks whether the file will load at all, `coverage`
+ * whether the keys and the code agree, `hardcoded` whether the markup ever
+ * asks for a key in the first place.
+ *
  * @returns {object} The yargs command module.
  */
 function langCommand() {
@@ -304,39 +643,25 @@ function langCommand() {
         command: "lang <action>",
         describe: "Localization checks",
         builder: (y) =>
-            y.positional("action", {
-                choices: ["check"],
-                describe: "check: verify the files are expandObject-safe",
-            }),
-        handler: handler(() => {
+            y
+                .positional("action", {
+                    choices: ["check", "coverage", "hardcoded"],
+                    describe:
+                        "check: the files are expandObject-safe · " +
+                        "coverage: keys and code agree · " +
+                        "hardcoded: templates localize their text",
+                })
+                .option("unused", {
+                    type: "boolean",
+                    default: false,
+                    describe:
+                        "coverage: list every unreferenced key, not a preview",
+                }),
+        handler: handler(async (args) => {
             const config = loadPackageBuildConfig();
-            const files = globSync(config.langSources, {
-                cwd: config.rootDir,
-                absolute: true,
-            });
-            if (!files.length) {
-                die(
-                    `no localization files matched ` +
-                        `\`${config.langSources}\` under ${config.rootDir}.`,
-                );
-            }
-
-            let total = 0;
-            for (const file of files.sort()) {
-                total += reportFindings(
-                    validateLangSource(fs.readFileSync(file, "utf8")),
-                    { file: path.relative(config.rootDir, file) },
-                );
-            }
-
-            if (total) {
-                if (config.langHelp) console.error(`\n${config.langHelp}`);
-                process.exit(1);
-            }
-            console.log(
-                `package-build: ${files.length} localization file(s) are ` +
-                    `expandObject-safe.`,
-            );
+            if (args.action === "check") return langCheck(config);
+            if (args.action === "hardcoded") return langHardcoded(config);
+            return langCoverage(config, args);
         }),
     };
 }
@@ -457,17 +782,7 @@ function deployCommand() {
         handler: handler(async (args) => {
             const config = loadPackageBuildConfig();
 
-            // Loaded here rather than at module scope: `--help` must answer in
-            // a repository that has no environment file at all.
-            const dotenv = await import("dotenv");
-            dotenv.config({
-                path: path.join(config.rootDir, ".env.local"),
-                quiet: true,
-            });
-            dotenv.config({
-                path: path.join(config.rootDir, ".env"),
-                quiet: true,
-            });
+            await loadEnvironment(config);
 
             const { stage } = await deployStage({
                 stage: args.stage,
@@ -482,6 +797,122 @@ function deployCommand() {
     };
 }
 
+/**
+ * `container <stage> <action>` — run a stage's Foundry in a container.
+ *
+ * The seam is the deploy's own: `deploy <stage>` installs the staged package
+ * into `FOUNDRYVTT_<STAGE>_DATA`, and this mounts that same directory and
+ * serves it. Nothing about the destination is stated twice.
+ *
+ * Every action shares one shape — a stage and an action — so this is a single
+ * command with a closed set of choices rather than eight of them. The stage
+ * leads, as it does in `deploy <stage>`, which is also what lets a consumer
+ * wrap it once per stage: `npm run container:dev start`.
+ *
+ * @returns {object} The yargs command module.
+ */
+function containerCommand() {
+    return {
+        command: "container <stage> <action>",
+        describe: "Run a stage's Foundry in a container",
+        builder: (y) =>
+            y
+                .positional("stage", {
+                    type: "string",
+                    describe: "Target stage (e.g. dev, qa, prod, test)",
+                })
+                .positional("action", {
+                    choices: [...CONTAINER_ACTIONS],
+                    describe: "What to do with the stage's container",
+                }),
+        handler: handler(async (args) => {
+            const config = loadPackageBuildConfig();
+            await loadEnvironment(config);
+            const status = containerAction({
+                action: String(args.action),
+                stage: String(args.stage).trim().toLowerCase(),
+                config,
+                log: (message) => console.log(message),
+            });
+            process.exit(status);
+        }),
+    };
+}
+
+/** What `package-build e2e` can be asked to do. */
+const E2E_ACTIONS = ["seed", ...E2E_MODES, "fast", "sweep"];
+
+/**
+ * `e2e <action>` — stand a Foundry world up and drive a suite against it.
+ *
+ * **The suite itself is never this package's.** Seeding a disposable world,
+ * waiting for it to become *active* rather than merely reachable, and tearing
+ * it down again are nobody's local problem; what runs against it is entirely
+ * the repository's, and is named in `packageBuild.e2e.suite`.
+ *
+ * The actions answer different questions. `seed` writes the world.
+ * `run` and `open` are the from-scratch path — deploy, reseed, recreate, wait,
+ * run — and are the only ones that may change Foundry build, because a seeded
+ * world is stamped with the build that created it. `fast` is the iteration
+ * loop. `sweep` is the same full run against a build the repository does not
+ * pin, so `compatibility.verified` can be evidence rather than hope.
+ *
+ * Everything after the action is the suite's, and is passed through untouched.
+ *
+ * @returns {object} The yargs command module.
+ */
+function e2eCommand() {
+    return {
+        command: "e2e <action>",
+        describe: "Run a suite against a served Foundry world",
+        builder: (y) =>
+            y
+                .positional("action", {
+                    choices: E2E_ACTIONS,
+                    describe:
+                        "seed: write the world · run/open: from scratch · " +
+                        "fast: rebuild and re-run · sweep: another Foundry build",
+                })
+                // Everything after the action belongs to the suite or to the
+                // fast loop, so this command line must not judge it.
+                .strict(false),
+        handler: handler(async (args) => {
+            const action = String(args.action);
+            const config = loadPackageBuildConfig();
+            await loadEnvironment(config);
+            const log = (message) => console.log(message);
+            const tail = e2eTail(action);
+
+            if (action === "seed") {
+                await seedTestWorld({
+                    config,
+                    packageJson: readPackageJson(config),
+                    log,
+                });
+                return;
+            }
+
+            const status =
+                action === "fast" ? await e2eFast({ config, argv: tail, log })
+                : action === "sweep" ?
+                    await e2eSweep({
+                        config,
+                        packageJson: readPackageJson(config),
+                        argv: tail,
+                        log,
+                    })
+                :   await e2eRun({
+                        config,
+                        packageJson: readPackageJson(config),
+                        mode: /** @type {"run"|"open"} */ (action),
+                        suiteArgs: tail,
+                        log,
+                    });
+            process.exit(status);
+        }),
+    };
+}
+
 yargs(hideBin(process.argv))
     .scriptName("package-build")
     .command(cleanCommand())
@@ -491,6 +922,8 @@ yargs(hideBin(process.argv))
     .command(bundleCommand())
     .command(releaseCommand())
     .command(deployCommand())
+    .command(containerCommand())
+    .command(e2eCommand())
     .demandCommand(1, "Name a command.")
     .strict()
     .version(ownVersion())

package/bin/report.mjs

@@ -42,6 +42,9 @@ import { emitDiagnostic } from "@heroiclands/content-build/engine/diagnostics";
  *
  * @typedef {object} Finding
  * @property {string} message                 What is wrong, in one sentence.
+ * @property {string} [file]                  The file it is about, when the
+ *   rule knows — a rule spanning many files does, and one handed a single
+ *   file's text does not.
  * @property {"warning"|"error"} [severity]   Defaults to `error`.
  * @property {number} [line]                  1-based line, when known.
  * @property {number} [column]                1-based column, when known.
@@ -59,11 +62,16 @@ import { emitDiagnostic } from "@heroiclands/content-build/engine/diagnostics";
  * top of the file every time and reads exactly like a real position. A column
  * without a line is dropped for the same reason: it locates nothing on its own.
  *
+ * **Unless the finding names its own.** A rule handed one file's text cannot;
+ * a rule handed a whole repository — coverage, which compares the localization
+ * file against every source that references it — can name nothing else, since
+ * no single path is right for both halves of what it found.
+ *
  * @param {Finding[]} findings - What the rule returned.
  * @param {object} opts
- * @param {string} opts.file - Path to the file, relative to the working
+ * @param {string} [opts.file] - Path to the file, relative to the working
  *   directory, so the emitted line is one an editor or `cc`-style parser can
- *   open.
+ *   open. Optional only for a rule whose every finding carries its own.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "warning"|"error", message: string}>} The diagnostics, in the
  *   order the rule reported them.
@@ -74,7 +82,7 @@ export function toDiagnostics(findings, { file }) {
         const hasColumn =
             finding.column !== undefined && finding.column !== null;
         return {
-            file,
+            file: finding.file ?? file,
             ...(hasLine ? { line: finding.line } : {}),
             // Only alongside a line: `formatLocator` ignores a lone column, and
             // carrying it anyway would invite a reader to trust it.
@@ -93,7 +101,8 @@ export function toDiagnostics(findings, { file }) {
  *
  * @param {Finding[]} findings - What the rule returned.
  * @param {object} opts
- * @param {string} opts.file - Path to the file, relative to the working dir.
+ * @param {string} [opts.file] - Path to the file, relative to the working dir.
+ *   Optional only when every finding carries its own.
  * @param {(d: object) => void} [opts.emit] - How to emit one diagnostic.
  *   Injectable so a test can capture the emitted shape without reaching for
  *   the console; defaults to content-build's `emitDiagnostic`, which writes