@heroiclands/package-build 0.4.0 → 0.6.0

package/types/container.d.mts

@@ -0,0 +1,359 @@
+/**
+ * The environment variable naming a stage's Foundry data root.
+ *
+ * Derived rather than tabulated, so a repository that adds a stage of its own
+ * gets the variable without this package learning its name.
+ *
+ * @param {string} stage - The stage name.
+ * @returns {string} The variable to read.
+ */
+export function dataEnvVar(stage: string): string;
+/**
+ * The container name for a package's stage.
+ *
+ * Named after the package so two HeroicLands packages can run their own
+ * containers side by side, and stable so Foundry's signed licence — which is
+ * bound to the container hostname — survives a recreate.
+ *
+ * @param {string} packageId - The Foundry package id.
+ * @param {string} stage - The stage name.
+ * @returns {string} The container name.
+ */
+export function containerName(packageId: string, stage: string): string;
+/**
+ * A stage declared in `packageBuild.container.stages`.
+ *
+ * @typedef {object} ContainerStage
+ * @property {number|null} port      Host port to publish.
+ * @property {string|null} world     World to auto-launch; `""` forces none.
+ * @property {string|null} version   Exact Foundry build to pin.
+ */
+/**
+ * The host port a stage publishes.
+ *
+ * `FOUNDRYVTT_<STAGE>_PORT` first, then the stage's declared port, then the
+ * conventional default.
+ *
+ * @param {string} stage - The stage name.
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {Record<string, ContainerStage>} [opts.stages] - Declared stages.
+ * @returns {number} The host port.
+ * @throws {Error} When the stage has no port from any source.
+ */
+export function resolveStagePort(stage: string, { env, stages }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    stages?: Record<string, ContainerStage> | undefined;
+}): number;
+/**
+ * The exact Foundry build a stage is pinned to, or `null` to float.
+ *
+ * `FOUNDRYVTT_<STAGE>_VERSION` wins — that is how a sweep runs against a build
+ * without touching committed configuration. Then the stage's own declared
+ * version. Then, **for the end-to-end stage only**, the package's
+ * `compatibility.minimum`.
+ *
+ * That last rule is the point. `compatibility.minimum` is a promise the
+ * manifest makes to every user, and a promise is only defended if something
+ * exercises it: a regression that breaks the floor while working on a newer
+ * build passes a suite run above the floor in silence. Deriving the pin from
+ * the claim means the evidence and the claim are the same number, and neither
+ * can drift from the other.
+ *
+ * A floor that names no build (`"14"`) cannot pin one, so the run floats on the
+ * major tag — visibly, rather than by pretending to a precision it lacks.
+ *
+ * @param {string} stage - The stage name.
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {Record<string, ContainerStage>} [opts.stages] - Declared stages.
+ * @param {string|null} [opts.compatibilityMinimum] - The claimed floor.
+ * @param {string} [opts.e2eStage] - Which stage the suite runs against.
+ * @returns {string|null} The exact build, or `null`.
+ */
+export function resolveFoundryVersion(stage: string, { env, stages, compatibilityMinimum, e2eStage, }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    stages?: Record<string, ContainerStage> | undefined;
+    compatibilityMinimum?: string | null | undefined;
+    e2eStage?: string | undefined;
+}): string | null;
+/**
+ * The image a run uses.
+ *
+ * `FOUNDRYVTT_CONTAINER_IMAGE` wins, then `packageBuild.container.image`, then
+ * felddy's major tag for whichever version the package already implies — the
+ * pinned build, or failing that the compatibility floor. Only a package that
+ * claims neither floats.
+ *
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {string|null} [opts.image] - The configured image.
+ * @param {string|null} [opts.version] - The pinned build, if any.
+ * @param {string|null} [opts.compatibilityMinimum] - The claimed floor.
+ * @returns {string} The image reference.
+ */
+export function resolveImage({ env, image, version, compatibilityMinimum, }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    image?: string | null | undefined;
+    version?: string | null | undefined;
+    compatibilityMinimum?: string | null | undefined;
+}): string;
+/**
+ * The world a stage auto-launches.
+ *
+ * `null` leaves `FOUNDRY_WORLD` alone, so whatever the image was given decides.
+ * An empty string is a *declared* "never auto-launch" — the shape a stage whose
+ * world is managed by hand needs, and distinct from saying nothing.
+ *
+ * @param {string} stage - The stage name.
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {Record<string, ContainerStage>} [opts.stages] - Declared stages.
+ * @returns {string|null} The world id, `""`, or `null`.
+ */
+export function resolveWorld(stage: string, { env, stages }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    stages?: Record<string, ContainerStage> | undefined;
+}): string | null;
+/**
+ * A stage's dedicated Foundry licence key, if it has one.
+ *
+ * Foundry is single-seat, so running a `dev` and a `test` container at once
+ * needs two keys. `FOUNDRYVTT_<STAGE>_LICENSE_KEY` dedicates one to a stage,
+ * overriding any global `FOUNDRY_LICENSE_KEY` passed through.
+ *
+ * @param {string} stage - The stage name.
+ * @param {NodeJS.ProcessEnv} [env] - Environment to read.
+ * @returns {string|null} The key, or `null`.
+ */
+export function resolveLicenseKey(stage: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * The Foundry data root for a stage, checked for what a bind mount needs.
+ *
+ * @param {string} stage - The stage name.
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @returns {string} The local path.
+ * @throws {Error} When it is unset, or names a remote host.
+ */
+export function resolveDataRoot(stage: string, { env }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+}): string;
+/**
+ * The image's own environment variables, as key/value pairs.
+ *
+ * `CONTAINER_CACHE` is deliberately withheld: it names a path *inside* the
+ * container, and {@link dockerRunArgs} sets it to match a mount it actually
+ * makes. A host path from a `.env` file would otherwise reach the image naming
+ * a directory that is not there.
+ *
+ * @param {NodeJS.ProcessEnv} [env] - Environment to read.
+ * @returns {[string, string][]} The pairs to pass through.
+ */
+export function passthroughEnv(env?: NodeJS.ProcessEnv): [string, string][];
+/**
+ * The full `docker run` argument vector for a stage's container.
+ *
+ * Order matters at the end: docker takes the **last** `-e` for a repeated key,
+ * so the per-stage version, world and licence are appended after the
+ * passthrough and win over anything it carried.
+ *
+ * @param {object} opts
+ * @param {string} opts.name - Container name.
+ * @param {string} opts.image - Image reference.
+ * @param {number} opts.port - Host port to publish.
+ * @param {string} opts.dataRoot - Host directory to mount at `/data`.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to pass through.
+ * @param {string|null} [opts.cacheDir] - Host download cache to mount.
+ * @param {string|null} [opts.version] - Exact build to pin.
+ * @param {string|null} [opts.world] - World to auto-launch; `""` forces none.
+ * @param {string|null} [opts.licenseKey] - Dedicated licence key.
+ * @returns {string[]} Arguments after `docker`.
+ */
+export function dockerRunArgs({ name, image, port, dataRoot, env, cacheDir, version, world, licenseKey, }: {
+    name: string;
+    image: string;
+    port: number;
+    dataRoot: string;
+    env?: NodeJS.ProcessEnv | undefined;
+    cacheDir?: string | null | undefined;
+    version?: string | null | undefined;
+    world?: string | null | undefined;
+    licenseKey?: string | null | undefined;
+}): string[];
+/**
+ * Run the `docker` CLI, inheriting stdio.
+ *
+ * @param {string[]} args - Arguments after `docker`.
+ * @returns {number} The exit status.
+ * @throws {Error} When `docker` is not on `PATH`.
+ */
+export function runDocker(args: string[]): number;
+/**
+ * Run the `docker` CLI and capture its output, tolerating failure.
+ *
+ * @param {string[]} args - Arguments after `docker`.
+ * @returns {string} Trimmed stdout, or `""` when the command failed.
+ */
+export function captureDocker(args: string[]): string;
+/**
+ * @param {string} name - Container name.
+ * @param {boolean} [runningOnly] - Only count a running container.
+ * @returns {boolean} Whether a container with exactly this name is present.
+ */
+export function containerExists(name: string, runningOnly?: boolean): boolean;
+/**
+ * The HeroicLands-convention Foundry containers currently running.
+ *
+ * Used to warn about a single-seat licence clash before a run starts, which is
+ * why the filter is the shared `-foundry-` convention rather than one package's
+ * prefix: the clash is between *any* two licensed instances, not between two
+ * containers of the same package.
+ *
+ * @param {string} [except] - A container to omit from the list.
+ * @returns {string[]} The container names.
+ */
+export function runningFoundryContainers(except?: string): string[];
+/**
+ * Remove the data-root lock a container left behind when it did not shut down
+ * cleanly (`docker rm -f`, a crash, an OOM).
+ *
+ * Foundry then refuses to start with "already locked by another process",
+ * naming no owner — so a stale lock turns every later boot into a failure that
+ * reads like corruption rather than litter.
+ *
+ * **Only safe while the container is stopped**, which is exactly when every
+ * boot path here calls it: with nothing running against the data root, a lock
+ * present is by definition stale.
+ *
+ * @param {string} dataRoot - The Foundry user-data root.
+ * @param {(message: string) => void} [log] - Progress reporting.
+ */
+export function clearStaleLock(dataRoot: string, log?: (message: string) => void): void;
+/**
+ * Everything a container action needs, resolved from configuration and the
+ * environment once.
+ *
+ * @typedef {object} ResolvedContainer
+ * @property {string} stage
+ * @property {string} name
+ * @property {number} port
+ * @property {string} image
+ * @property {string} url
+ * @property {string|null} version
+ * @property {string|null} world
+ * @property {string|null} licenseKey
+ * @property {string|null} cacheDir
+ */
+/**
+ * Resolve a stage's container settings.
+ *
+ * @param {object} opts
+ * @param {string} opts.stage - The stage name.
+ * @param {object} opts.config - The resolved package-build configuration.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @returns {ResolvedContainer} The resolved settings.
+ */
+export function resolveContainer({ stage, config, env }: {
+    stage: string;
+    config: object;
+    env?: NodeJS.ProcessEnv | undefined;
+}): ResolvedContainer;
+/**
+ * Start a stage's container, creating it when it does not exist yet.
+ *
+ * @param {ResolvedContainer} container - Resolved settings.
+ * @param {object} opts
+ * @param {string} opts.dataRoot - Host directory to mount at `/data`.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to pass through.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {number} The exit status.
+ */
+export function startContainer(container: ResolvedContainer, { dataRoot, env, log }: {
+    dataRoot: string;
+    env?: NodeJS.ProcessEnv | undefined;
+    log?: ((message: string) => void) | undefined;
+}): number;
+/**
+ * Stop and remove a container, tolerating "not running" and "no such
+ * container".
+ *
+ * @param {string} name - Container name.
+ * @param {(message: string) => void} [log] - Progress reporting.
+ */
+export function removeContainer(name: string, log?: (message: string) => void): void;
+/**
+ * Perform one container action for a stage.
+ *
+ * @param {object} opts
+ * @param {string} opts.action - One of {@link CONTAINER_ACTIONS}.
+ * @param {string} opts.stage - The stage name.
+ * @param {object} opts.config - The resolved package-build configuration.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {number} The exit status.
+ * @throws {Error} On an unknown action, or a stage with no usable data root.
+ */
+export function containerAction({ action, stage, config, env, log, }: {
+    action: string;
+    stage: string;
+    config: object;
+    env?: NodeJS.ProcessEnv | undefined;
+    log?: ((message: string) => void) | undefined;
+}): number;
+/**
+ * Host port each conventional stage publishes, chosen so they can run at once.
+ *
+ * A stage a repository adds of its own declares its port in
+ * `packageBuild.container.stages`; these four need no entry because every
+ * HeroicLands package deploys to the same four.
+ */
+export const DEFAULT_STAGE_PORTS: Readonly<{
+    dev: 30000;
+    qa: 30001;
+    prod: 30002;
+    test: 30003;
+}>;
+/** The port Foundry listens on inside the container. */
+export const CONTAINER_PORT: 30000;
+/**
+ * Where a host-provided download cache is mounted.
+ *
+ * A dedicated mount point rather than a subpath of `/data` keeps the cache
+ * independent of the data root, so one cache can serve every stage.
+ */
+export const CACHE_MOUNT: "/container_cache";
+/** What `package-build container` can be asked to do. */
+export const CONTAINER_ACTIONS: readonly string[];
+/**
+ * A stage declared in `packageBuild.container.stages`.
+ */
+export type ContainerStage = {
+    /**
+     * Host port to publish.
+     */
+    port: number | null;
+    /**
+     * World to auto-launch; `""` forces none.
+     */
+    world: string | null;
+    /**
+     * Exact Foundry build to pin.
+     */
+    version: string | null;
+};
+/**
+ * Everything a container action needs, resolved from configuration and the
+ * environment once.
+ */
+export type ResolvedContainer = {
+    stage: string;
+    name: string;
+    port: number;
+    image: string;
+    url: string;
+    version: string | null;
+    world: string | null;
+    licenseKey: string | null;
+    cacheDir: string | null;
+};

package/types/coverage.d.mts

@@ -0,0 +1,182 @@
+/**
+ * The roots a set of declared keys uses.
+ *
+ * Derived rather than configured by default, because a package's roots are
+ * already a fact about its localization file — asking for them again is one
+ * more thing to state and to get wrong. A repository states them only when it
+ * references a root the file does not yet declare at all.
+ *
+ * @param {Iterable<string>} keys - The declared keys.
+ * @returns {string[]} The distinct first segments, in name order.
+ */
+export function keyRootsOf(keys: Iterable<string>): string[];
+/**
+ * Read every localization reference out of a script.
+ *
+ * The **AST**, not the text, because a key named in a JSDoc `@example` is
+ * documentation: requiring it to exist would make the guard fail on prose, and
+ * counting it as a reference would let a comment keep a dead key alive.
+ *
+ * TypeScript's parser reads plain JavaScript too, so both go down one path
+ * rather than two that drift.
+ *
+ * @param {string} source - The file's contents.
+ * @param {object} options
+ * @param {string} options.file - Path to the file, for the findings.
+ * @param {readonly string[]} options.roots - The key roots.
+ * @returns {ReferenceSet} What the file references.
+ */
+export function collectScriptReferences(source: string, { file, roots }: {
+    file: string;
+    roots: readonly string[];
+}): ReferenceSet;
+/**
+ * Read every localization reference out of a template.
+ *
+ * A text scan, because a template has no AST worth building for this: its keys
+ * sit in `{{localize "…"}}` calls and in helper hashes, and nothing in a `.hbs`
+ * file resembles a comment closely enough to mislead one.
+ *
+ * @param {string} source - The file's contents.
+ * @param {object} options
+ * @param {string} options.file - Path to the file, for the findings.
+ * @param {readonly string[]} options.roots - The key roots.
+ * @returns {ReferenceSet} What the template references.
+ */
+export function collectTemplateReferences(source: string, { file, roots }: {
+    file: string;
+    roots: readonly string[];
+}): ReferenceSet;
+/**
+ * Combine reference sets into one.
+ *
+ * Keys are kept whole — every site that references a missing key is worth
+ * naming — while namespaces and patterns are de-duplicated, since neither says
+ * anything about where it came from.
+ *
+ * @param {Iterable<ReferenceSet>} sets - The sets to combine.
+ * @returns {ReferenceSet} One set holding all of them.
+ */
+export function mergeReferences(sets: Iterable<ReferenceSet>): ReferenceSet;
+/**
+ * Compare what a package declares against what it references.
+ *
+ * @param {object} options
+ * @param {string} options.langSource - The reference localization file's text.
+ * @param {string} options.langFile - Its path, for the findings about it.
+ * @param {ReferenceSet} options.references - Everything that references it.
+ * @param {readonly string[]} [options.retained] - Key prefixes to leave out of
+ *   the advisory half. Each is a repository's statement that the keys under it
+ *   are reached in a way no scan can see; the honest fix for an unreferenced
+ *   key is still to delete it.
+ * @param {readonly string[]} [options.roots] - The key roots. Derived from the
+ *   declared keys when absent.
+ * @returns {{findings: CoverageFinding[], unreferenced: CoverageFinding[],
+ *   stats: object}} What must be fixed, what is merely worth reading, and what
+ *   the run looked at. The two are separate because they are different
+ *   questions: one says the package is broken, the other that it carries
+ *   something nobody could see a use for.
+ */
+export function analyzeCoverage({ langSource, langFile, references, retained, roots, }: {
+    langSource: string;
+    langFile: string;
+    references: ReferenceSet;
+    retained?: readonly string[] | undefined;
+    roots?: readonly string[] | undefined;
+}): {
+    findings: CoverageFinding[];
+    unreferenced: CoverageFinding[];
+    stats: object;
+};
+/**
+ * One place a key is referenced, and how firmly.
+ */
+export type KeyReference = {
+    /**
+     * - The localization key, in full.
+     */
+    key: string;
+    /**
+     * - Where it is referenced, relative to the repository
+     * root — the reference is the finding's site, not the localization file.
+     */
+    file: string;
+    /**
+     * - 1-based line, when it can be established.
+     */
+    line?: number | undefined;
+    /**
+     * - 1-based column, likewise.
+     */
+    column?: number | undefined;
+    /**
+     * - When true the key must be declared verbatim,
+     * even if it happens to be a prefix of keys that are. A *generated* key is
+     * minted whole, so keys sitting beneath it do not vouch for it; an ordinary
+     * textual reference to a family name does not have that property.
+     */
+    exact?: boolean | undefined;
+    /**
+     * - The verb phrase naming how the key is
+     * referenced, for the message: `references` by default, so a contributor of
+     * generated keys can say `defineType generates` instead.
+     */
+    origin?: string | undefined;
+};
+/**
+ * Everything one scan learned about how a file addresses localization.
+ */
+export type ReferenceSet = {
+    /**
+     * - Concrete keys, each at its site.
+     */
+    keys: KeyReference[];
+    /**
+     * - Prefixes whose leaves are never named in
+     * source: a DataModel's `LOCALIZATION_PREFIXES`, the static head of a key
+     * built at runtime. A namespace vouches for *itself* being reachable, never
+     * for the keys beneath it.
+     */
+    namespaces: string[];
+    /**
+     * - Key shapes a dynamic construction can build,
+     * with `*` standing for one segment: `` `SOHL.Month.${i}.label` `` is
+     * `SOHL.Month.*.label`, and vouches for exactly what that expression can
+     * produce.
+     */
+    patterns: string[];
+    /**
+     * - What the scan could not resolve, in
+     * its own words.
+     */
+    findings: CoverageFinding[];
+};
+/**
+ * A finding about coverage.
+ *
+ * Unlike the rules in {@link module :lang}, these carry their own `file`: one
+ * run spans the localization file and every source that references it, so a
+ * single path supplied by the caller could not be right for all of them.
+ */
+export type CoverageFinding = {
+    /**
+     * - Path the finding is about.
+     */
+    file: string;
+    /**
+     * - 1-based line, when known.
+     */
+    line?: number | undefined;
+    /**
+     * - 1-based column, when known.
+     */
+    column?: number | undefined;
+    /**
+     * - How it should be treated.
+     */
+    severity: "error" | "warning";
+    /**
+     * - What is wrong, in one sentence.
+     */
+    message: string;
+};