@heroiclands/package-build 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @heroiclands/package-build
 
+## 0.4.0
+
+### Minor Changes
+
+- 2c2fc37: **`package-build bundle check` — the last capability that had no command.**
+  
+  The bundle-loading check was exported as a library function and reachable no
+  other way, so a consumer that wanted it had to write the script the command line
+  exists to remove: read the manifest, read the bundle, call the function, decide
+  how to print findings, choose an exit code. It now runs from configuration like
+  every other job.
+  
+  It catches three ways a package builds successfully and still does not load,
+  none of which a bundler can see, because each is a disagreement between two
+  files rather than a fault in either:
+  
+  | The manifest says                                                         | What Foundry does                                                                  |
+  | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+  | the entry under both `esmodules` and `scripts`                            | loads the bundle twice                                                             |
+  | the entry under neither                                                   | never loads it at all                                                              |
+  | the entry under `esmodules`, but the file only parses as a classic script | fails at load, naming whichever `import` came first and nothing about the manifest |
+  
+  Both files are read from the stage, because the stage is what ships.
+  
+  **The entry is derived, not stated.** `packageBuild.bundle.entry` defaults to
+  `<packageId>.mjs`, which is already derived from `package.json` `name`; a
+  repository states it only when its bundler emits something else. It is
+  deliberately _not_ read back out of the generated manifest — a value taken from
+  there would agree with itself by construction, and the check's whole question is
+  whether the manifest declares this file the way Foundry needs it.
+  
+  **Reporting is now decided once.** `lang check` had the diagnostic contract —
+  `file:line:column: severity: message`, the path starting the line, a field
+  dropped rather than guessed — spelled out inline in its handler. Both commands
+  now report through one seam that maps findings onto the format
+  `@heroiclands/content-build` already owns, so the two packages cannot drift into
+  two nearly-identical formats. `lang check`'s output is unchanged.
+  
+  **The command surface has a stated shape.** A capability with a single operation
+  is a bare command (`clean`, `assets`, `manifest`, `release`, `deploy <stage>`);
+  one with more than a single operation takes a positional action, so a second can
+  be added without renaming the first (`lang check`, `bundle check`).
+  
+  Closes #12
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -96,6 +96,14 @@ packageBuild:
     # Prefix of the shared SFTP override variables. Default `SOHL`.
     envPrefix: SOHL
 
+  bundle:
+    # The file Foundry loads, as the manifest spells it, relative to the stage.
+    # Defaults to `<packageId>.mjs`; state it only when the bundler emits
+    # something else. Deliberately not read back out of the manifest — a value
+    # taken from there would agree with itself by construction, and `bundle
+    # check` asks whether the manifest declares this file correctly.
+    entry: sohl.mjs
+
   # Optional. A module exporting `flags(config)` returning namespaced Foundry
   # flags the repository has to *compute* — an address that only exists once
   # the content tree has been walked, say. Merged over any declared below.
@@ -176,11 +184,12 @@ other's schema — they split by input, and the dependency runs one way.
 
 **What is derived, not stated:**
 
-| Field                      | Derived from                                                         |
-| -------------------------- | -------------------------------------------------------------------- |
-| the repository root        | the configuration file's own location                                |
-| `packageKind`, `packageId` | the shared configuration's top level                                 |
-| the release artifact       | `packageKind` — a system ships `system.json`, a module `module.json` |
+| Field                      | Derived from                                                                |
+| -------------------------- | --------------------------------------------------------------------------- |
+| the repository root        | the configuration file's own location                                       |
+| `packageKind`, `packageId` | the shared configuration's top level                                        |
+| the release artifact       | `packageKind` — a system ships `system.json`, a module `module.json`        |
+| the bundle entry           | `packageId` — `<id>.mjs`, unless `packageBuild.bundle.entry` says otherwise |
 
 ## Command line
 
@@ -189,6 +198,7 @@ npx package-build clean [--distclean]
 npx package-build assets
 npx package-build manifest
 npx package-build lang check
+npx package-build bundle check
 npx package-build release
 npx package-build deploy <stage>
 ```
@@ -201,11 +211,34 @@ Wrapped as npm scripts — SoHL spells them:
   "distclean": "package-build clean --distclean",
   "build:assets": "package-build assets",
   "lint:lang": "package-build lang check",
+  "lint:bundle-globals": "package-build bundle check",
   "build:pack-release": "package-build release",
   "push:qa": "package-build deploy qa"
 }
 ```
 
+**The shape of the surface.** A capability with a single operation is a bare
+command (`clean`, `assets`, `manifest`, `release`, `deploy <stage>`); one with
+more than a single operation takes a positional action, so a second can be added
+without renaming the first (`lang check`, `bundle check`). Flat `lang:check`
+names would make every operation a new top-level command and hide which ones
+belong together.
+
+**What `bundle check` checks.** Three ways a package builds successfully and
+still does not load, none of which a bundler can see, because each is a
+disagreement between two files rather than a fault in either:
+
+| The manifest says                                                         | What Foundry does                                                                  |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| the entry under both `esmodules` and `scripts`                            | loads the bundle twice                                                             |
+| the entry under neither                                                   | never loads it at all                                                              |
+| the entry under `esmodules`, but the file only parses as a classic script | fails at load, naming whichever `import` came first and nothing about the manifest |
+
+It reads both files from the stage, because the stage is what ships — checking
+sources would answer for a package nobody installs. Findings are emitted as
+`file:line:column: severity: message`, and the command exits non-zero when any
+of them is an error.
+
 **Why the CLI exists.** This package was library-only, so every consuming
 repository wrote a wrapper script per job — six of them in the SoHL repository,
 441 lines that between them contained no logic. `clean.mjs` was 47 lines that

package/bin/package-build.mjs

@@ -34,6 +34,13 @@
  * stay import-safe, so a consuming repository's build — or a test — can call
  * them without any of it happening.
  *
+ * **The shape of the command surface.** A capability with a single operation is
+ * a bare command (`clean`, `assets`, `manifest`, `release`, `deploy <stage>`);
+ * one with more than a single operation takes a positional action, so it can
+ * grow another without renaming the first (`lang check`, `bundle check`). The
+ * alternative — flat `lang:check`-style names — makes the second operation a
+ * new top-level command and the relationship between them invisible.
+ *
  * The side effects that need *configuration* live inside the command handlers,
  * never at module scope, so `--version` and `--help` answer in a directory with
  * no configuration at all. Running an actual command still resolves it, and
@@ -44,6 +51,7 @@
  *   npx package-build assets
  *   npx package-build manifest
  *   npx package-build lang check
+ *   npx package-build bundle check
  *   npx package-build release
  *   npx package-build deploy <stage>
  *
@@ -51,6 +59,7 @@
  *   npm run clean                          // → … clean
  *   npm run build:assets                   // → … assets
  *   npm run lint:lang                      // → … lang check
+ *   npm run lint:bundle-globals            // → … bundle check
  *   npm run build:pack-release             // → … release
  *   npm run push:qa                        // → … deploy qa
  */
@@ -66,9 +75,11 @@ 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 { checkBundleLoading } from "../bundle.mjs";
 import { packRelease } from "../release.mjs";
 import { writeManifest } from "../manifest.mjs";
 import { deployStage } from "../deploy.mjs";
+import { reportFindings } from "./report.mjs";
 
 /**
  * This package's own version, for `--version`.
@@ -312,20 +323,10 @@ function langCommand() {
 
             let total = 0;
             for (const file of files.sort()) {
-                const relative = path.relative(config.rootDir, file);
-                for (const finding of validateLangSource(
-                    fs.readFileSync(file, "utf8"),
-                )) {
-                    total++;
-                    // The diagnostics contract: the path starts the line, and a
-                    // field is dropped rather than guessed.
-                    const at = [relative, finding.line, finding.column]
-                        .filter((part) => part !== undefined && part !== null)
-                        .join(":");
-                    console.error(
-                        `${at}: ${finding.severity ?? "error"}: ${finding.message}`,
-                    );
-                }
+                total += reportFindings(
+                    validateLangSource(fs.readFileSync(file, "utf8")),
+                    { file: path.relative(config.rootDir, file) },
+                );
             }
 
             if (total) {
@@ -340,6 +341,72 @@ function langCommand() {
     };
 }
 
+/**
+ * `bundle check` — does the manifest agree with the bundle it points at?
+ *
+ * Three ways a package can be built successfully and still not load, none of
+ * which the bundler can see because each is a disagreement between two files:
+ * the entry listed under both `esmodules` and `scripts` (Foundry loads it
+ * twice), under neither (Foundry never loads it), or under `esmodules` while
+ * the emitted file only parses as a classic script. The last fails at runtime
+ * with a message about whichever `import` came first and says nothing about the
+ * manifest, which is the kind of error that costs an afternoon.
+ *
+ * Both files are read from the stage, because the stage is what ships. Checking
+ * sources would answer for a package nobody installs.
+ *
+ * @returns {object} The yargs command module.
+ */
+function bundleCommand() {
+    return {
+        command: "bundle <action>",
+        describe: "Code-bundle checks",
+        builder: (y) =>
+            y.positional("action", {
+                choices: ["check"],
+                describe:
+                    "check: verify the manifest and the staged bundle agree",
+            }),
+        handler: handler(() => {
+            const config = loadPackageBuildConfig();
+            const stageDir = path.join(config.rootDir, config.stageDir);
+            const manifestPath = path.join(stageDir, `${config.artifact}.json`);
+            const bundlePath = path.join(stageDir, config.bundleEntry);
+
+            // Named explicitly rather than left to a missing-file stack trace:
+            // both absences mean "the stage was not built", and a reader who
+            // sees the path knows which step to run.
+            for (const [what, where] of [
+                ["manifest", manifestPath],
+                ["bundle", bundlePath],
+            ]) {
+                if (!fs.existsSync(where)) {
+                    die(
+                        `no staged ${what} at ` +
+                            `${path.relative(config.rootDir, where)} — build ` +
+                            `the stage before checking it.`,
+                    );
+                }
+            }
+
+            const relative = path.relative(config.rootDir, bundlePath);
+            const { findings, declaredAs } = checkBundleLoading({
+                manifest: JSON.parse(fs.readFileSync(manifestPath, "utf8")),
+                source: fs.readFileSync(bundlePath, "utf8"),
+                entry: config.bundleEntry,
+                manifestName: path.relative(config.rootDir, manifestPath),
+            });
+
+            if (reportFindings(findings, { file: relative })) process.exit(1);
+
+            console.log(
+                `package-build: ${config.bundleEntry} is declared under ` +
+                    `"${declaredAs}" and loads as one.`,
+            );
+        }),
+    };
+}
+
 /**
  * `release` — zip the staged package for a GitHub release.
  *
@@ -421,6 +488,7 @@ yargs(hideBin(process.argv))
     .command(assetsCommand())
     .command(manifestCommand())
     .command(langCommand())
+    .command(bundleCommand())
     .command(releaseCommand())
     .command(deployCommand())
     .demandCommand(1, "Name a command.")

package/bin/report.mjs

@@ -0,0 +1,108 @@
+/*
+ * 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
+ */
+
+/**
+ * How the command line reports what a rule found.
+ *
+ * The package's rules are pure: they take source text and return findings,
+ * leaving discovery, I/O and reporting to whoever called them. That is what
+ * makes them testable, but it also means every caller has to decide the same
+ * two things — what a finding looks like once emitted, and what a run's exit
+ * code should be. Before there was a command line, every consumer decided them
+ * separately, and no two agreed.
+ *
+ * This module is where the binary decides them once. It lives under `bin/`
+ * rather than beside the rules deliberately: it is the *caller's* half, not
+ * part of the pure surface, and nothing importing this package as a library
+ * should reach it.
+ *
+ * The emitted form is the toolchain's diagnostic contract —
+ * `file:line:column: severity: message`, the path starting the line, a field
+ * dropped rather than guessed — which `@heroiclands/content-build` already
+ * owns. This module maps findings onto it rather than restating it, so the two
+ * packages cannot drift into two nearly-identical formats.
+ *
+ * @module
+ */
+
+import { emitDiagnostic } from "@heroiclands/content-build/engine/diagnostics";
+
+/**
+ * A finding as the pure rules report one.
+ *
+ * @typedef {object} Finding
+ * @property {string} message                 What is wrong, in one sentence.
+ * @property {"warning"|"error"} [severity]   Defaults to `error`.
+ * @property {number} [line]                  1-based line, when known.
+ * @property {number} [column]                1-based column, when known.
+ */
+
+/**
+ * Turn a rule's findings into diagnostics, attaching the file they are about.
+ *
+ * A rule is handed source text and never learns the path it came from, so the
+ * caller is the only one who can say it — and a finding without a file is one
+ * nothing can navigate to.
+ *
+ * **A field is dropped, never guessed.** A finding that knows no line emits as
+ * `file: severity: message`, because defaulting to `1:1` sends a reader to the
+ * 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.
+ *
+ * @param {Finding[]} findings - What the rule returned.
+ * @param {object} opts
+ * @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.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "warning"|"error", message: string}>} The diagnostics, in the
+ *   order the rule reported them.
+ */
+export function toDiagnostics(findings, { file }) {
+    return findings.map((finding) => {
+        const hasLine = finding.line !== undefined && finding.line !== null;
+        const hasColumn =
+            finding.column !== undefined && finding.column !== null;
+        return {
+            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.
+            ...(hasLine && hasColumn ? { column: finding.column } : {}),
+            severity: finding.severity ?? "error",
+            message: finding.message,
+        };
+    });
+}
+
+/**
+ * Emit a rule's findings and say how many of them fail the run.
+ *
+ * Warnings are emitted and counted separately from the return value, so a
+ * command can report something worth reading without failing a build over it.
+ *
+ * @param {Finding[]} findings - What the rule returned.
+ * @param {object} opts
+ * @param {string} opts.file - Path to the file, relative to the working dir.
+ * @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
+ *   both severities to stderr.
+ * @returns {number} How many diagnostics were errors — the count a command
+ *   turns into its exit code.
+ */
+export function reportFindings(findings, { file, emit = emitDiagnostic }) {
+    const diagnostics = toDiagnostics(findings, { file });
+    for (const diagnostic of diagnostics) emit(diagnostic);
+    return diagnostics.filter((d) => d.severity === "error").length;
+}

package/config.mjs

@@ -69,6 +69,7 @@ const SECTION_KEYS = [
     "lang",
     "deploy",
     "release",
+    "bundle",
 ];
 
 /**
@@ -98,6 +99,7 @@ const CLEAN_KEYS = ["extra"];
 const LANG_KEYS = ["sources", "help"];
 const DEPLOY_KEYS = ["envPrefix"];
 const RELEASE_KEYS = ["artifact"];
+const BUNDLE_KEYS = ["entry"];
 
 /**
  * The artifact name each package kind ships, so no repository states it.
@@ -240,6 +242,8 @@ function normalizeManifest(value) {
  * @property {string} langSources    Glob for the localization files to check.
  * @property {string|null} langHelp  Extra guidance printed after a failure.
  * @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.
  */
 
 /**
@@ -308,6 +312,15 @@ export function resolvePackageBuildConfig(shared) {
     );
     const releaseInput = /** @type {Record<string, unknown>} */ (release);
 
+    const bundle = section.bundle ?? {};
+    if (!isMapping(bundle)) fail("packageBuild.bundle", "must be a mapping");
+    rejectUnknownKeys(
+        /** @type {Record<string, unknown>} */ (bundle),
+        BUNDLE_KEYS,
+        "packageBuild.bundle.",
+    );
+    const bundleInput = /** @type {Record<string, unknown>} */ (bundle);
+
     return Object.freeze({
         rootDir: shared.rootDir,
         // Where the package is assembled before it is zipped or deployed. Every
@@ -375,6 +388,22 @@ export function resolvePackageBuildConfig(shared) {
                     deployInput.envPrefix,
                     "packageBuild.deploy.envPrefix",
                 ),
+        // The file Foundry loads, as the manifest spells it. Named after the
+        // package by convention, and the id is already derived from
+        // package.json `name` — so a repository states this only when its
+        // bundler emits something else.
+        //
+        // Deliberately *not* read back out of the generated manifest: the
+        // check's question is whether the manifest declares this file the way
+        // Foundry needs it, and a value taken from the manifest could never
+        // answer that — it would agree with itself by construction.
+        bundleEntry:
+            bundleInput.entry === undefined ?
+                `${shared.foundryPackage}.mjs`
+            :   requireNonEmptyString(
+                    bundleInput.entry,
+                    "packageBuild.bundle.entry",
+                ),
     });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package \u2014 manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/config.d.mts

@@ -22,6 +22,8 @@
  * @property {string} langSources    Glob for the localization files to check.
  * @property {string|null} langHelp  Extra guidance printed after a failure.
  * @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.
  */
 /**
  * Resolve a package-build configuration from an already-loaded shared one.
@@ -135,4 +137,9 @@ export type PackageBuildConfig = {
      * Prefix of the deploy environment variables.
      */
     envPrefix: string;
+    /**
+     * The bundle file Foundry loads, as the
+     * manifest spells it. Derived from the package id.
+     */
+    bundleEntry: string;
 };