rman 1.3.0 → 2.0.0-beta.3

package/commands/version.command.d.ts

@@ -1,3 +1,330 @@
-import type { Argv } from 'yargs';
-import type { Repository } from '../core/repository.js';
-export declare function initCli(repository: Repository, program: Argv): void;
+import type { RunStepValue } from '../core/interfaces/run-step.js';
+import type { ConfigValue, RmanConfig } from '../interfaces/rman-config.interface.js';
+/**
+ * Hoisted out of the metadata literal so the handler can be annotated against them - see
+ * `RmanConfig.ArgsOf` for why an inferred `argv` and the metadata's own typo checking cannot both
+ * work in one signature.
+ *
+ * `as const` on the command string is load-bearing twice over: the config key is derived from it
+ * (`'version'`), and so are the positional names it declares.
+ */
+declare const COMMAND: "version [bump]";
+declare const config: {
+    interactive: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    show: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+        conflicts: string;
+    };
+    yes: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+        conflicts: string;
+    };
+    json: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+        conflicts: string[];
+    };
+    ignoreDirty: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "boolean";
+    };
+    push: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    message: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "string";
+    };
+    changelog: {
+        target: "both";
+        describe: string;
+        type: "boolean";
+    };
+    preid: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    /**
+     * Config-only, from here down: `.rmanrc "version.*"` keys with no reason to be a flag.
+     * `--message` is `commitMessage`'s flag and is declared above; the rest are settings a repository
+     * states once, not things a single run overrides.
+     */
+    commitMessage: {
+        target: "config";
+        describe: string;
+        type: "string";
+    };
+    releaseTagPattern: {
+        target: "config";
+        describe: string;
+        type: "string";
+    };
+    stampDockerfile: {
+        target: "config";
+        describe: string;
+        type: "boolean";
+    };
+    allowBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    ignoreBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    scope: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    ignore: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    platform: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    deps: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    dependents: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+};
+/**
+ * The rest of `version.*` - the keys an option **cannot** describe, which is the whole test for
+ * belonging here.
+ *
+ * A `CommandOption` says `type: 'string'` or `type: 'boolean'`. It has no way to say "a path, or
+ * `{ file, constant }`" or "a shell command, or a function, or a list of either" - so these four
+ * are written out, intersected with the derived ones by `CommandContribution`, and the key still
+ * has exactly one owner. Everything above that *is* expressible is declared as an option instead:
+ * `Extra` is the escape hatch, not the default.
+ *
+ * **It is also the one interface in the tree holding both kinds of function**, so the value/step
+ * split is made here by hand, key by key. `stamp` is a **value**, so it is a `ConfigValue` and may
+ * be written as a function evaluated while the config resolves. The three slots are **steps**: they
+ * already take a function and it means something else - code `version` calls when the write
+ * happens, with a `RunStepContext`. Wrapping one would accept a value function where a step is what
+ * actually runs.
+ *
+ * A new key here goes on one side or the other, and the two mistakes are not symmetric: forgetting
+ * `ConfigValue` on a value key is benign (it simply cannot be written as a function yet, which is
+ * where every key started), while putting it on a step key is not. That asymmetry is why nothing
+ * wraps these automatically - see `CommandConfigFromMetadata` for the half that can be, because an
+ * option's value is a value by construction.
+ */
+export interface VersionExtraKeys {
+    /** Files whose hard-coded version is rewritten to the version being written, in the same commit
+     *  as the bump - paths relative to the package's own directory (e.g. `["src/constants.ts"]`).
+     *  Per-package cascaded; a listed file a package doesn't have is a silent no-op, so one `"[*]"`
+     *  declaration covers a repo where only some packages carry one.
+     *
+     *  Stamping the source, not the build output: a build-time rewrite leaves the checked-in file
+     *  claiming a placeholder, so anything running from source reports that placeholder, git never
+     *  records the released version, and the rewrite has to be redone on every build. */
+    stamp?: ConfigValue<VersionStampEntry | VersionStampEntry[]>;
+    /** Command(s) run at the version write itself, when the package does not declare a hook for that
+     *  slot of its own (`version` in a Node repository's `package.json#scripts`, whatever a plugin's
+     *  step source answers elsewhere - the package's own declaration wins, as in `run`). An array
+     *  runs them in sequence. `${{ pkg.targetVersion }}` is bound here and in the two below, and
+     *  nowhere else.
+     *
+     *  A `RunStepFn` runs in place of a shell command - but note that `${{ pkg.targetVersion }}` is a
+     *  *string* substitution, so a function reads the written version off `pkg` instead. */
+    exec?: RunStepValue | RunStepValue[];
+    /** Same, before the write (`preversion` in a Node repository). */
+    before?: RunStepValue | RunStepValue[];
+    /** Same, after it (`postversion` in a Node repository). */
+    after?: RunStepValue | RunStepValue[];
+}
+/** One `version.stamp` entry: a path, or a path plus the identifier to rewrite when it is not
+ *  spelled `version`. */
+export type VersionStampEntry = string | {
+    file: string;
+    constant?: string;
+};
+type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
+declare const versionCommand: (app: import("../index.js").RmanApplication) => {
+    /** `as const` so the config key stays derivable from it: `CommandMetadata['command']` is a
+     *  plain `string`, so without the assertion inference widens `'version [bump]'` and there is
+     *  nothing left to read `'version'` out of. */
+    command: "version [bump]";
+    describe: string;
+    /**
+     * Read, not owned - so they are named here rather than declared in `config`. `group` is a core
+     * per-package key that decides which packages move together, `changelog.*` is consulted when
+     * `--changelog` folds one into the bump commit, and `allowBranch`/`ignoreBranch` are repo-wide
+     * keys the shared branch-guard group only exposes as flags. `version` itself is not listed: it
+     * is this command's own key, derived from `command`.
+     */
+    configKeys: string[];
+    config: {
+        interactive: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        show: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+            conflicts: string;
+        };
+        yes: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+            conflicts: string;
+        };
+        json: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+            conflicts: string[];
+        };
+        ignoreDirty: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "boolean";
+        };
+        push: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        message: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "string";
+        };
+        changelog: {
+            target: "both";
+            describe: string;
+            type: "boolean";
+        };
+        preid: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        /**
+         * Config-only, from here down: `.rmanrc "version.*"` keys with no reason to be a flag.
+         * `--message` is `commitMessage`'s flag and is declared above; the rest are settings a repository
+         * states once, not things a single run overrides.
+         */
+        commitMessage: {
+            target: "config";
+            describe: string;
+            type: "string";
+        };
+        releaseTagPattern: {
+            target: "config";
+            describe: string;
+            type: "string";
+        };
+        stampDockerfile: {
+            target: "config";
+            describe: string;
+            type: "boolean";
+        };
+        allowBranch: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
+        ignoreBranch: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
+        scope: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        ignore: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        platform: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        deps: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        dependents: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+    };
+    examples: {
+        command: string;
+        description: string;
+    }[];
+    positionals: {
+        bump: {
+            describe: string;
+            type: "string";
+        };
+    };
+    /** Annotated rather than inferred - `RmanConfig.ArgsOf` records why, and the casts this
+     *  replaces are the reason it is worth two hoisted declarations. */
+    handler: (args: Args) => Promise<void>;
+};
+export default versionCommand;
+/**
+ * `version`'s own keys, on `RmanConfig` - derived from the `config` block above rather than written
+ * out again, so an option added there is a config key immediately and one renamed cannot leave a
+ * stale interface behind. Only `target: 'config'`/`'both'` options come through, so `--interactive`
+ * and the other CLI-only flags stay off the config type.
+ */
+declare module '../interfaces/rman-config.interface.js' {
+    namespace RmanConfig {
+        interface CommandConfigs extends RmanConfig.CommandContribution<ReturnType<typeof versionCommand>, VersionExtraKeys> {
+        }
+    }
+}