@heroiclands/package-build 0.5.0 → 0.6.0

package/config.mjs

@@ -70,6 +70,8 @@ const SECTION_KEYS = [
     "deploy",
     "release",
     "bundle",
+    "container",
+    "e2e",
 ];
 
 /**
@@ -96,9 +98,26 @@ export const DERIVED_MANIFEST_KEYS = Object.freeze({
 });
 const ASSET_KEYS = ["from", "to"];
 const CLEAN_KEYS = ["extra"];
-const LANG_KEYS = ["sources", "help"];
+const LANG_KEYS = [
+    "sources",
+    "help",
+    "primary",
+    "scripts",
+    "templates",
+    "keyRoots",
+    "references",
+    "retained",
+    "allow",
+];
 const DEPLOY_KEYS = ["envPrefix"];
 const RELEASE_KEYS = ["artifact"];
+const CONTAINER_KEYS = ["image", "stages"];
+const CONTAINER_STAGE_KEYS = ["port", "world", "version"];
+const E2E_KEYS = ["stage", "suite", "build", "world", "gm", "documents"];
+const E2E_SUITE_KEYS = ["run", "open"];
+const E2E_WORLD_KEYS = ["id", "title", "description"];
+const E2E_GM_KEYS = ["name", "password"];
+const E2E_BUILD_TARGET_KEYS = ["script", "recreate"];
 const BUNDLE_KEYS = ["entry"];
 
 /**
@@ -218,6 +237,194 @@ function normalizeManifest(value) {
     return Object.freeze(structuredClone(input));
 }
 
+/**
+ * Normalize a setting that is one glob or several.
+ *
+ * A repository with a single conventional directory writes a string and a
+ * repository with two writes a list; requiring the list form from both would
+ * make the common case read like the exception.
+ *
+ * @param {unknown} value - What was declared, or `undefined`.
+ * @param {string[]} fallback - The conventional layout.
+ * @param {string} where - Dotted path, for the error.
+ * @returns {readonly string[]} The globs, frozen.
+ */
+function normalizeGlobs(value, fallback, where) {
+    if (value === undefined) return Object.freeze(fallback);
+    const list = Array.isArray(value) ? value : [value];
+    return Object.freeze(
+        list.map((glob, index) =>
+            requireNonEmptyString(
+                glob,
+                Array.isArray(value) ? `${where}[${index}]` : where,
+            ),
+        ),
+    );
+}
+
+/**
+ * A container stage a repository runs beyond the conventional four.
+ *
+ * The four every HeroicLands package deploys to — dev, qa, prod, test — need no
+ * entry: their data-root variable is derived and their ports are conventional.
+ * This is for a stage that is genuinely one repository's, such as an older
+ * Foundry serving a previous generation of the package.
+ *
+ * @param {unknown} value - The stage entry.
+ * @param {string} name - The stage name, for the error path.
+ * @returns {Readonly<{port: number|null, world: string|null, version: string|null}>}
+ */
+function normalizeContainerStage(value, name) {
+    const where = `packageBuild.container.stages.${name}`;
+    if (!isMapping(value)) fail(where, "must be a mapping");
+    const stage = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(stage, CONTAINER_STAGE_KEYS, `${where}.`);
+    if (stage.port !== undefined && typeof stage.port !== "number") {
+        fail(`${where}.port`, "must be a number");
+    }
+    if (stage.world !== undefined && typeof stage.world !== "string") {
+        // An empty string is meaningful — it declares "never auto-launch" —
+        // which is exactly why the type has to be checked rather than coerced.
+        fail(`${where}.world`, 'must be a string ("" forces no auto-launch)');
+    }
+    return Object.freeze({
+        port: /** @type {number|null} */ (stage.port ?? null),
+        world: /** @type {string|null} */ (stage.world ?? null),
+        version:
+            stage.version === undefined ?
+                null
+            :   requireNonEmptyString(stage.version, `${where}.version`),
+    });
+}
+
+/**
+ * One end-to-end build target: the npm script that produces it, and whether
+ * producing it means the world has to relaunch.
+ *
+ * A bare string is the common case and reads better than a mapping with one
+ * key, so both are accepted. `recreate` is for a target that writes something
+ * Foundry reads **once, at world launch** — the manifest — where deploying it
+ * into a running world deploys a file nothing will look at.
+ *
+ * @param {unknown} value - The target entry.
+ * @param {string} name - The target name, for the error path.
+ * @returns {Readonly<{script: string, recreate: boolean}>}
+ */
+function normalizeE2EBuildTarget(value, name) {
+    const where = `packageBuild.e2e.build.${name}`;
+    if (typeof value === "string") {
+        return Object.freeze({
+            script: requireNonEmptyString(value, where),
+            recreate: false,
+        });
+    }
+    if (!isMapping(value)) fail(where, "must be a script name or a mapping");
+    const target = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(target, E2E_BUILD_TARGET_KEYS, `${where}.`);
+    if (target.recreate !== undefined && typeof target.recreate !== "boolean") {
+        fail(`${where}.recreate`, "must be a boolean");
+    }
+    return Object.freeze({
+        script: requireNonEmptyString(target.script, `${where}.script`),
+        recreate: Boolean(target.recreate),
+    });
+}
+
+/**
+ * The suite a repository runs against the served world.
+ *
+ * **This is the one thing the harness does not own.** Standing Foundry up,
+ * seeding a world and waiting for it to activate are nobody's local problem;
+ * what runs against it — a Cypress suite full of one system's helpers — is
+ * entirely the repository's. So it is named here, the way an asset transform or
+ * a manifest-flags module is named.
+ *
+ * @param {unknown} value - The `suite` block, or `undefined`.
+ * @returns {Readonly<{run: readonly string[], open: readonly string[]|null}>|null}
+ */
+function normalizeE2ESuite(value) {
+    if (value === undefined) return null;
+    if (!isMapping(value)) fail("packageBuild.e2e.suite", "must be a mapping");
+    const suite = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(suite, E2E_SUITE_KEYS, "packageBuild.e2e.suite.");
+
+    /**
+     * @param {unknown} value_ - The declared command.
+     * @param {string} where - Its path, for the error.
+     * @returns {readonly string[]} The program and its arguments.
+     */
+    const commandList = (value_, where) => {
+        if (!Array.isArray(value_) || value_.length === 0) {
+            fail(where, "must be a non-empty list naming a program to run");
+        }
+        return Object.freeze(
+            value_.map((part, i) =>
+                requireNonEmptyString(part, `${where}[${i}]`),
+            ),
+        );
+    };
+
+    return Object.freeze({
+        run: commandList(suite.run, "packageBuild.e2e.suite.run"),
+        open:
+            suite.open === undefined ?
+                null
+            :   commandList(suite.open, "packageBuild.e2e.suite.open"),
+    });
+}
+
+/**
+ * A mapping whose every value is a non-empty string, frozen.
+ *
+ * @param {unknown} value - The mapping, or `undefined`.
+ * @param {string} where - Its path, for the error.
+ * @param {readonly string[]} [allowed] - Keys it may declare.
+ * @returns {Readonly<Record<string, string>>}
+ */
+function normalizeStringMap(value, where, allowed) {
+    if (value === undefined) return Object.freeze({});
+    if (!isMapping(value)) fail(where, "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    if (allowed) rejectUnknownKeys(input, allowed, `${where}.`);
+    return Object.freeze(
+        Object.fromEntries(
+            Object.entries(input).map(([key, entry]) => [
+                key,
+                requireNonEmptyString(entry, `${where}.${key}`),
+            ]),
+        ),
+    );
+}
+
+/**
+ * Normalize an escape-hatch list: entries of `{ <field>, reason }`.
+ *
+ * Both escape hatches — a key kept despite looking unreferenced, a literal kept
+ * despite looking like prose — are a claim about something no scan can see, so
+ * each entry states the claim in prose a reviewer can check. Requiring the
+ * reason is what keeps the list from silently becoming the place unexplained
+ * exceptions accumulate.
+ *
+ * @param {unknown} value - The declared list, or `undefined`.
+ * @param {string} field - The name of the entry's own field.
+ * @param {string} where - Dotted path, for the error.
+ * @returns {readonly string[]} The field values, frozen; `[]` when absent.
+ */
+function normalizeExceptions(value, field, where) {
+    if (value === undefined) return Object.freeze([]);
+    if (!Array.isArray(value)) fail(where, "must be a list");
+    return Object.freeze(
+        value.map((entry, index) => {
+            const at = `${where}[${index}]`;
+            if (!isMapping(entry)) fail(at, "must be a mapping");
+            const item = /** @type {Record<string, unknown>} */ (entry);
+            rejectUnknownKeys(item, [field, "reason"], `${at}.`);
+            requireNonEmptyString(item.reason, `${at}.reason`);
+            return requireNonEmptyString(item[field], `${at}.${field}`);
+        }),
+    );
+}
+
 /**
  * The resolved `packageBuild` section, every optional half filled in.
  *
@@ -241,9 +448,43 @@ function normalizeManifest(value) {
  *                                   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.
  */
 
 /**
@@ -321,6 +562,56 @@ export function resolvePackageBuildConfig(shared) {
     );
     const bundleInput = /** @type {Record<string, unknown>} */ (bundle);
 
+    const container = section.container ?? {};
+    if (!isMapping(container)) {
+        fail("packageBuild.container", "must be a mapping");
+    }
+    rejectUnknownKeys(
+        /** @type {Record<string, unknown>} */ (container),
+        CONTAINER_KEYS,
+        "packageBuild.container.",
+    );
+    const containerInput = /** @type {Record<string, unknown>} */ (container);
+    const declaredStages = containerInput.stages ?? {};
+    if (!isMapping(declaredStages)) {
+        fail("packageBuild.container.stages", "must be a mapping");
+    }
+    const containerStages = Object.freeze(
+        Object.fromEntries(
+            Object.entries(
+                /** @type {Record<string, unknown>} */ (declaredStages),
+            ).map(([name, entry]) => [
+                name,
+                normalizeContainerStage(entry, name),
+            ]),
+        ),
+    );
+
+    const e2e = section.e2e ?? {};
+    if (!isMapping(e2e)) fail("packageBuild.e2e", "must be a mapping");
+    rejectUnknownKeys(
+        /** @type {Record<string, unknown>} */ (e2e),
+        E2E_KEYS,
+        "packageBuild.e2e.",
+    );
+    const e2eInput = /** @type {Record<string, unknown>} */ (e2e);
+    const declaredBuild = e2eInput.build ?? {};
+    if (!isMapping(declaredBuild)) {
+        fail("packageBuild.e2e.build", "must be a mapping");
+    }
+    // Declaration order is build order — a mapping preserves it, and the
+    // bundler has to run before the passes that copy into the stage it empties.
+    const e2eBuild = Object.freeze(
+        Object.fromEntries(
+            Object.entries(
+                /** @type {Record<string, unknown>} */ (declaredBuild),
+            ).map(([name, entry]) => [
+                name,
+                normalizeE2EBuildTarget(entry, name),
+            ]),
+        ),
+    );
+
     return Object.freeze({
         rootDir: shared.rootDir,
         // Where the package is assembled before it is zipped or deployed. Every
@@ -381,6 +672,57 @@ export function resolvePackageBuildConfig(shared) {
             langInput.help === undefined ?
                 null
             :   requireNonEmptyString(langInput.help, "packageBuild.lang.help"),
+        // The file the package authors, and the one every other translation is
+        // measured against. Coverage is a question about *this* file: another
+        // language missing a key is a translation in progress, not a defect.
+        langPrimary:
+            langInput.primary === undefined ?
+                "lang/en.json"
+            :   requireNonEmptyString(
+                    langInput.primary,
+                    "packageBuild.lang.primary",
+                ),
+        langScripts: normalizeGlobs(
+            langInput.scripts,
+            ["src/**/*.{ts,mjs}"],
+            "packageBuild.lang.scripts",
+        ),
+        langTemplates: normalizeGlobs(
+            langInput.templates,
+            ["templates/**/*.hbs"],
+            "packageBuild.lang.templates",
+        ),
+        // Derived from the file's own keys unless stated — a package states
+        // them only when it references a root the file does not yet declare at
+        // all, which is the one case deriving them cannot cover.
+        langKeyRoots:
+            langInput.keyRoots === undefined ?
+                null
+            :   normalizeGlobs(
+                    langInput.keyRoots,
+                    [],
+                    "packageBuild.lang.keyRoots",
+                ),
+        langReferences:
+            langInput.references === undefined ?
+                null
+            :   path.resolve(
+                    shared.rootDir,
+                    requireNonEmptyString(
+                        langInput.references,
+                        "packageBuild.lang.references",
+                    ),
+                ),
+        langRetained: normalizeExceptions(
+            langInput.retained,
+            "prefix",
+            "packageBuild.lang.retained",
+        ),
+        langAllow: normalizeExceptions(
+            langInput.allow,
+            "literal",
+            "packageBuild.lang.allow",
+        ),
         envPrefix:
             deployInput.envPrefix === undefined ?
                 "SOHL"
@@ -404,6 +746,43 @@ export function resolvePackageBuildConfig(shared) {
                     bundleInput.entry,
                     "packageBuild.bundle.entry",
                 ),
+        // Read from the top level, where the package already claims it. The
+        // end-to-end pin derives from this, so the claim and the evidence for
+        // it are the same number and cannot drift apart.
+        compatibilityMinimum: shared.compatibility?.minimum ?? null,
+        // The system a seeded world runs. For a system package that is itself;
+        // for a module it is the system it targets, which the shared
+        // configuration already names.
+        systemId: shared.stats?.systemId ?? shared.foundryPackage,
+        systemVersion: shared.stats?.systemVersion ?? null,
+        containerImage:
+            containerInput.image === undefined ?
+                null
+            :   requireNonEmptyString(
+                    containerInput.image,
+                    "packageBuild.container.image",
+                ),
+        containerStages,
+        e2eStage:
+            e2eInput.stage === undefined ?
+                "test"
+            :   requireNonEmptyString(e2eInput.stage, "packageBuild.e2e.stage"),
+        e2eSuite: normalizeE2ESuite(e2eInput.suite),
+        e2eBuild,
+        e2eWorld: normalizeStringMap(
+            e2eInput.world,
+            "packageBuild.e2e.world",
+            E2E_WORLD_KEYS,
+        ),
+        e2eGm: normalizeStringMap(
+            e2eInput.gm,
+            "packageBuild.e2e.gm",
+            E2E_GM_KEYS,
+        ),
+        e2eDocuments: normalizeStringMap(
+            e2eInput.documents,
+            "packageBuild.e2e.documents",
+        ),
     });
 }