@heroiclands/package-build 0.5.0 → 0.6.0

package/types/e2e.d.mts

@@ -0,0 +1,351 @@
+/**
+ * Hash a password the way Foundry's `core/auth.mjs` does: pbkdf2, 1000 rounds,
+ * 64 bytes, sha512. A different shape logs nobody in.
+ *
+ * @param {string} password - The plaintext password.
+ * @param {string} salt - The hex salt.
+ * @returns {string} The hex hash.
+ */
+export function hashPassword(password: string, salt: string): string;
+/**
+ * The disposable world's identity and credentials.
+ *
+ * @typedef {object} E2EWorld
+ * @property {string} worldId
+ * @property {string} worldTitle
+ * @property {string} worldDescription
+ * @property {string} gmId
+ * @property {string} gmName
+ * @property {string} gmPassword
+ */
+/**
+ * Resolve the seeded world from configuration and the environment.
+ *
+ * Everything derives from the package id unless the repository says otherwise,
+ * and the environment overrides under the repository's own variable prefix —
+ * the same prefix the deploy already uses — so a contributor can point a run at
+ * a scratch world without touching committed configuration.
+ *
+ * @param {object} config - The resolved package-build configuration.
+ * @param {NodeJS.ProcessEnv} [env] - Environment to read.
+ * @returns {E2EWorld} The resolved world.
+ */
+export function resolveE2EWorld(config: object, env?: NodeJS.ProcessEnv): E2EWorld;
+/**
+ * The `world.json` a seeded world carries.
+ *
+ * Foundry re-stamps `coreVersion`, `systemVersion` and `compatibility` from the
+ * running core on launch, so a generation-level range is enough here — the
+ * point is a world that launches without a migration prompt or a setup step.
+ *
+ * @param {object} opts
+ * @param {string} opts.worldId
+ * @param {string} opts.worldTitle
+ * @param {string} opts.worldDescription
+ * @param {string} opts.systemId - The system the world runs.
+ * @param {string} opts.systemVersion - That system's version.
+ * @param {string} opts.coreVersion - The Foundry generation.
+ * @returns {object} The world manifest.
+ */
+export function worldManifest({ worldId, worldTitle, worldDescription, systemId, systemVersion, coreVersion, }: {
+    worldId: string;
+    worldTitle: string;
+    worldDescription: string;
+    systemId: string;
+    systemVersion: string;
+    coreVersion: string;
+}): object;
+/**
+ * The seeded world's single Gamemaster.
+ *
+ * @param {object} opts
+ * @param {string} opts.id - The fixed document id.
+ * @param {string} opts.name - The user name.
+ * @param {string} opts.password - The plaintext password.
+ * @param {string} opts.salt - The hex salt to hash it with.
+ * @returns {object} The user document.
+ */
+export function gmDocument({ id, name, password, salt }: {
+    id: string;
+    name: string;
+    password: string;
+    salt: string;
+}): object;
+/**
+ * The one pre-activated scene every seeded world carries.
+ *
+ * @returns {object} The scene document.
+ */
+export function defaultSceneDocument(): object;
+/**
+ * The world setting that switches a module package on.
+ *
+ * A **system** is the world's own — `world.json` names it and Foundry loads it.
+ * A **module** is not: it has to be activated, and the switch is
+ * `core.moduleConfiguration`, a world setting holding a JSON map of package id
+ * to enabled. Without it a module repository would stand its suite up against a
+ * world that never loaded the very thing under test.
+ *
+ * @param {string} packageId - The module to enable.
+ * @returns {object} The setting document.
+ */
+export function moduleConfigurationDocument(packageId: string): object;
+/**
+ * Whether a `/join` response shows a world that is actually **active**.
+ *
+ * Foundry answers on the port long before a world is serving; a suite started
+ * at that moment fails every spec for no visible reason. The join screen
+ * renders the form only once a world is active, so that is what is waited for.
+ *
+ * @param {string} body - The response body.
+ * @returns {boolean} Whether the world is active.
+ */
+export function isWorldActive(body: string): boolean;
+/**
+ * The build a sweep was asked to run against.
+ *
+ * There is no default, deliberately. The product of a sweep is a citable result
+ * — "the full suite passed on 14.367" — and a hard-coded "newest release" would
+ * rot on Foundry's next release day, quietly turning the sweep into a second
+ * pinned build. A bare major or a tag is refused for the same reason: the image
+ * passes it through verbatim, so the run would name no particular Foundry.
+ *
+ * @param {string[]} argv - Arguments after the action.
+ * @returns {string} The exact build, trimmed.
+ * @throws {Error} When none was given, or it is not an exact build.
+ */
+export function resolveSweepVersion(argv: string[]): string;
+/**
+ * What a fast loop was asked to do.
+ *
+ * @typedef {object} FastArgs
+ * @property {string[]} targets    Build targets, in declared order.
+ * @property {boolean} recreate    Whether the container must be recreated.
+ * @property {boolean} runSuite    Whether to run the suite at all.
+ * @property {string[]} suiteArgs  Arguments handed to the suite verbatim.
+ */
+/**
+ * Parse the fast loop's arguments against the repository's build table.
+ *
+ * Build order is **declaration order**, not the order they were asked for: a
+ * bundler that empties the stage has to run before the passes that copy into
+ * it, and the repository already stated that by writing them down in order.
+ *
+ * @param {string[]} argv - Arguments after the action.
+ * @param {Record<string, {script: string, recreate: boolean}>} build - The
+ *   declared build table.
+ * @returns {FastArgs} What to do.
+ * @throws {Error} On an unknown build target.
+ */
+export function parseFastArgs(argv: string[], build: Record<string, {
+    script: string;
+    recreate: boolean;
+}>): FastArgs;
+/**
+ * Seed the disposable world into the end-to-end stage's data root.
+ *
+ * Writes `world.json` and compiles each LevelDB collection from JSON, so the
+ * result is a genuine world Foundry launches without migration or setup. The
+ * world directory is wiped and rewritten each time, which is what makes a run
+ * repeatable.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - The resolved package-build configuration.
+ * @param {object} opts.packageJson - The repository's `package.json`.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {Promise<{worldDir: string, world: E2EWorld}>} Where it landed.
+ */
+export function seedTestWorld({ config, packageJson, env, log, }: {
+    config: object;
+    packageJson: object;
+    env?: NodeJS.ProcessEnv | undefined;
+    log?: ((message: string) => void) | undefined;
+}): Promise<{
+    worldDir: string;
+    world: E2EWorld;
+}>;
+/**
+ * Poll until the world is active, or fail with a diagnosis.
+ *
+ * A licence failure never recovers, so it is detected from the container's own
+ * log and reported at once rather than after a three-minute timeout that says
+ * nothing about why.
+ *
+ * @param {object} opts
+ * @param {string} opts.url - The container's base URL.
+ * @param {string} opts.container - The container name, for its log.
+ * @param {string} opts.stage - The stage, named in a licence failure.
+ * @param {number} [opts.timeoutMs] - How long to wait.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {Promise<void>} Resolves once the world is active.
+ * @throws {Error} On a licence failure or a timeout.
+ */
+export function waitForWorld({ url, container, stage, timeoutMs, log, }: {
+    url: string;
+    container: string;
+    stage: string;
+    timeoutMs?: number | undefined;
+    log?: ((message: string) => void) | undefined;
+}): Promise<void>;
+/**
+ * Run the repository's suite.
+ *
+ * `ELECTRON_RUN_AS_NODE` is stripped from the child environment. Editor
+ * terminals and most agent shells export it, and with it set an Electron-based
+ * runner launches as plain Node, rejects its own flags, and dies with a
+ * `MODULE_NOT_FOUND` naming nothing relevant.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.command - The program and its arguments.
+ * @param {string[]} [opts.args] - Extra arguments, appended verbatim.
+ * @param {string} opts.cwd - The repository root.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment for the child.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {number} The suite's exit status.
+ */
+export function runSuite({ command, args, cwd, env, log, }: {
+    command: string[];
+    args?: string[] | undefined;
+    cwd: string;
+    env?: NodeJS.ProcessEnv | undefined;
+    log?: ((message: string) => void) | undefined;
+}): number;
+/**
+ * The suite command for a mode, or a clear failure when none is declared.
+ *
+ * @param {object} config - The resolved package-build configuration.
+ * @param {"run"|"open"} mode - Which command to take.
+ * @returns {string[]} The program and its arguments.
+ * @throws {Error} When the repository declares no such command.
+ */
+export function suiteCommand(config: object, mode: "run" | "open"): string[];
+/**
+ * A full, from-scratch end-to-end run.
+ *
+ * Deploy the staged package, reseed the world, recreate the container onto it,
+ * wait for it to activate, run the suite, and tear the container down again —
+ * except in interactive mode, where it is left serving.
+ *
+ * This is the only path that may change Foundry build: the seeded world is
+ * stamped with the build that created it, and Foundry refuses to auto-launch a
+ * world stamped by another.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - The resolved package-build configuration.
+ * @param {object} opts.packageJson - The repository's `package.json`.
+ * @param {"run"|"open"} [opts.mode] - Headless or interactive.
+ * @param {string[]} [opts.suiteArgs] - Extra arguments for the suite.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {Promise<number>} The suite's exit status.
+ */
+export function e2eRun({ config, packageJson, mode, suiteArgs, env, log, }: {
+    config: object;
+    packageJson: object;
+    mode?: "open" | "run" | undefined;
+    suiteArgs?: string[] | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    log?: ((message: string) => void) | undefined;
+}): Promise<number>;
+/**
+ * The iteration loop: rebuild what changed, redeploy, cycle, re-run.
+ *
+ * Each step has a quiet failure mode, and hand-rolling the sequence means
+ * meeting them one at a time. The bundler empties the stage, so build order is
+ * the declared one; the deploy is a destructive mirror, so it runs on a
+ * complete stage; a running Foundry holds its packs open, so the world is
+ * always cycled; the container answers on its port long before the world is
+ * serving, so the loop waits for the world.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - The resolved package-build configuration.
+ * @param {string[]} [opts.argv] - Arguments after the action.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {Promise<number>} The suite's exit status.
+ */
+export function e2eFast({ config, argv, env, log, }: {
+    config: object;
+    argv?: string[] | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    log?: ((message: string) => void) | undefined;
+}): Promise<number>;
+/**
+ * The forward sweep: the full suite against a build the repository does not
+ * pin.
+ *
+ * Routine runs go against the pinned build, which is the manifest's
+ * `compatibility.minimum` — the claim the suite exists to defend. That leaves
+ * the other direction untested: a new Foundry release can break the package and
+ * nothing would notice until a user did.
+ *
+ * A green sweep is what licenses moving `compatibility.verified` to that build.
+ * A red one is the early warning it exists to produce.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - The resolved package-build configuration.
+ * @param {object} opts.packageJson - The repository's `package.json`.
+ * @param {string[]} [opts.argv] - Arguments after the action.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {Promise<number>} The suite's exit status.
+ */
+export function e2eSweep({ config, packageJson, argv, env, log, }: {
+    config: object;
+    packageJson: object;
+    argv?: string[] | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    log?: ((message: string) => void) | undefined;
+}): Promise<number>;
+/**
+ * The Gamemaster's document id in every seeded world.
+ *
+ * Fixed, and deliberately not derived from the package: a spec has to know it
+ * without a handoff from the seed, and the world is disposable, so there is
+ * nothing for a per-package id to disambiguate. Sixteen alphanumeric
+ * characters, which is the shape Foundry document ids take.
+ */
+export const E2E_GM_ID: "heroiclandsE2EGM";
+/**
+ * The seeded, pre-activated default scene's id.
+ *
+ * A non-empty world means Foundry's New User Experience does not auto-start the
+ * welcome tour, whose callout overlays sheets; an *active* scene at load means
+ * the canvas is ready, which several read paths depend on.
+ */
+export const E2E_SCENE_ID: "heroiclandsScene";
+/** How the suite may be run. */
+export const E2E_MODES: readonly string[];
+/**
+ * The disposable world's identity and credentials.
+ */
+export type E2EWorld = {
+    worldId: string;
+    worldTitle: string;
+    worldDescription: string;
+    gmId: string;
+    gmName: string;
+    gmPassword: string;
+};
+/**
+ * What a fast loop was asked to do.
+ */
+export type FastArgs = {
+    /**
+     * Build targets, in declared order.
+     */
+    targets: string[];
+    /**
+     * Whether the container must be recreated.
+     */
+    recreate: boolean;
+    /**
+     * Whether to run the suite at all.
+     */
+    runSuite: boolean;
+    /**
+     * Arguments handed to the suite verbatim.
+     */
+    suiteArgs: string[];
+};

package/types/index.d.mts

@@ -3,4 +3,8 @@ export * as bundle from "./bundle.mjs";
 export * as stage from "./stage.mjs";
 export * as release from "./release.mjs";
 export * as deploy from "./deploy.mjs";
+export * as container from "./container.mjs";
+export * as e2e from "./e2e.mjs";
 export * as lang from "./lang.mjs";
+export * as coverage from "./coverage.mjs";
+export * as templates from "./templates.mjs";

package/types/templates.d.mts

@@ -0,0 +1,74 @@
+/**
+ * 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: string, { allow }?: {
+    allow?: Iterable<string> | undefined;
+}): TemplateFinding[];
+/**
+ * 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: string): TemplateFinding[];
+/**
+ * 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: readonly string[];
+/**
+ * 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.
+ */
+export type TemplateFinding = {
+    /**
+     * - 1-based line, omitted when it cannot be
+     * established honestly.
+     */
+    line?: number | undefined;
+    /**
+     * - 1-based column, omitted likewise.
+     */
+    column?: number | undefined;
+    /**
+     * - How the finding should be treated.
+     */
+    severity: "error" | "warning";
+    /**
+     * - What is wrong, in one sentence.
+     */
+    message: string;
+};