git-release-manager 0.0.14 → 0.6.0

package/dist/modules/version/VersionController.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VersionController = void 0;
+const resolveVersionRef_1 = require("./resolveVersionRef");
+const branchChannel_1 = require("./branchChannel");
+const configManager_1 = require("../../config/configManager");
+const VersionStamper_1 = require("./VersionStamper");
+const commitProcessor_1 = require("../git/commits/commitProcessor");
+const BumpDeriver_1 = require("./BumpDeriver");
 const GitVersionManager_1 = require("./GitVersionManager");
 const ProjectVersion_1 = require("./ProjectVersion");
 const ReleaseManager_1 = require("./ReleaseManager");
@@ -12,8 +18,161 @@ class VersionController {
         this.validator = new VersionValidator_1.VersionValidator();
         this.projectVersionManager = new ProjectVersion_1.ProjectVersionManager();
     }
+    /**
+     * resolveBaselineRef — the shared resolver, kept as a method so the call
+     * sites below read unchanged.
+     *
+     * THE BODY MOVED to modules/version/resolveVersionRef (DECISIONS D4). It was
+     * private here while `--revert` and `--compare` each answered the same
+     * question their own way — three verbs, three behaviours. One place is the
+     * decision; this wrapper is what keeps it one.
+     */
+    async resolveBaselineRef(baseline, prefix) {
+        return (0, resolveVersionRef_1.resolveVersionRef)(baseline, prefix);
+    }
+    /**
+     * deriveBumpFromRange — read the commits this version would cover and grade
+     * them against the configured taxonomy.
+     *
+     * Returns null when the range cannot be established, and the caller then
+     * proceeds with its normal default rather than failing. That is deliberate:
+     * `--derive` asks the history for an OPINION, and a repository with no
+     * baseline (the first version ever) genuinely has none to give. Refusing
+     * there would make the first release the one command nobody can run.
+     */
+    async deriveBumpFromRange(options) {
+        var _a, _b, _c;
+        try {
+            const config = await (0, configManager_1.readConfig)(options.config, options.environment);
+            const baseline = (_a = options.from) !== null && _a !== void 0 ? _a : (await this.gitManager.getLatestTag(options.prefix, options.channel));
+            if (!baseline)
+                return null;
+            // THE BASELINE IS A VERSION; THE RANGE NEEDS A REF, and they are not
+            // the same string. `--from 1.0.0` is a perfectly good baseline for
+            // the arithmetic — semver does not care about a `v` — while the tag
+            // in the repository is `v1.0.0`, so handing it straight to `git log`
+            // produces "ambiguous argument '1.0.0..HEAD'". The arithmetic then
+            // still answers, from a range that was never read: a derivation that
+            // silently graded nothing.
+            //
+            // --since IS THE CALLER SAYING THE TWO CANNOT BE INFERRED FROM EACH
+            // OTHER. A project running several version LINES tags them
+            // `<line>-vX.Y.Z`, so the baseline it hands over is the bare semver
+            // core `1.0.0` while the ref that starts the range is
+            // `catalystctl-v1.0.0`. Guessing from the core alone finds the
+            // repository's OWN `v1.0.0` — a real tag, at the wrong point in
+            // history — and the derivation then grades a range belonging to a
+            // different line. Measured: a component whose tree had not been
+            // touched derived a patch bump from another line's commits.
+            const from = options.since
+                ? await this.resolveBaselineRef(options.since, options.prefix)
+                : await this.resolveBaselineRef(baseline, options.prefix);
+            if (!from) {
+                console.error(`bump: ${options.since ? `range start '${options.since}'` : `baseline '${baseline}'`} ` +
+                    `does not resolve to a ref in this repository, ` +
+                    `so there is no range to grade; falling back to the flags given`);
+                return null;
+            }
+            const to = (_b = options.to) !== null && _b !== void 0 ? _b : 'HEAD';
+            // --no-merges: a merge commit carries no type and never could. Its
+            // content is the commits it joins, and those are in this range too.
+            //
+            // --paths scopes the derivation to ONE component's tree. Without it
+            // a repository with several independently-versioned products grades
+            // every one of them against every commit, so a fix in product A
+            // bumps product B — and the two lines, whose whole purpose is to be
+            // independent, move in lockstep while each claims to be its own.
+            // `--` separates pathspecs from revisions; without it git resolves a
+            // path that happens to look like a ref and answers about the wrong
+            // thing.
+            const pathspecs = ((_c = options.paths) !== null && _c !== void 0 ? _c : '').split(/\s+/).filter(Boolean);
+            const logArgs = ['--no-merges', ...(pathspecs.length ? ['--', ...pathspecs] : [])];
+            const commits = await (0, commitProcessor_1.getGitLogAsJson)(`${from}..${to}`, logArgs);
+            if (!(commits === null || commits === void 0 ? void 0 : commits.length))
+                return null;
+            return (0, BumpDeriver_1.deriveBump)(commits, config);
+        }
+        catch (error) {
+            // A derivation that cannot run must not take the version path down
+            // with it — the caller still has an explicit default. It says so on
+            // stderr, because a SILENT fallback would look exactly like a range
+            // that legitimately voted patch.
+            console.error(`bump: could not derive from history (${error instanceof Error ? error.message : String(error)}); ` +
+                `falling back to the flags given`);
+            return null;
+        }
+    }
+    /**
+     * withConfiguredPrefix — let `tag.prefix` in the config be the default for
+     * `--prefix`.
+     *
+     * WHY THIS EXISTS. The prefix was DECLARED in three places and read in one.
+     * Measured 2026-08-06: `tag.prefix` (a project config), `tag.format` (the
+     * packaged default and the Config type) and `config.tagPrefix` (read by
+     * FlowManager, declared by no config, so it interpolated the string
+     * "undefined" into its patterns). The only live knob was the CLI flag. A
+     * setting a project writes and nothing reads is worse than no setting: the
+     * next reader assumes the prefix is configured and it is not.
+     *
+     * THE FLAG STILL WINS, always. A caller that passes --prefix has said
+     * something more specific than the file, and a caller that passes NOTHING
+     * on a project with no tag.prefix gets exactly today's behaviour — so this
+     * cannot change what any existing invocation does.
+     */
+    async withConfiguredPrefix(options) {
+        var _a;
+        if (options.prefix !== undefined)
+            return options;
+        try {
+            const config = await (0, configManager_1.readConfig)(options.config, options.environment);
+            const prefix = (_a = config === null || config === void 0 ? void 0 : config.tag) === null || _a === void 0 ? void 0 : _a.prefix;
+            if (typeof prefix === 'string' && prefix.length > 0)
+                return { ...options, prefix };
+        }
+        catch (_b) {
+            // A config that cannot be read is not a reason to fail a version
+            // command that never needed it.
+        }
+        return options;
+    }
+    /**
+     * maybeStamp — write the version into the files the project declared.
+     *
+     * Never fatal by default. Stamping is a CONVENIENCE over a version that has
+     * already been decided and, at this point, already recorded; failing the
+     * command here would leave the caller believing no version was cut when one
+     * was. A file the project marked `required` still throws — that is the
+     * project saying the stamp is not a convenience — and the throw reaches the
+     * outer catch, which is why this does not swallow those.
+     */
+    async maybeStamp(version, options) {
+        if (options.skipStamp)
+            return;
+        let config;
+        try {
+            config = await (0, configManager_1.readConfig)(options.config, options.environment);
+        }
+        catch (_a) {
+            return; // no config, nothing declared, nothing to stamp
+        }
+        if (!config)
+            return;
+        const stamper = new VersionStamper_1.VersionStamper(config, process.cwd());
+        if (!stamper.configured)
+            return;
+        if (!stamper.onBump && !options.stamp)
+            return;
+        const result = await stamper.stamp(version);
+        console.error(`stamp: ${VersionStamper_1.VersionStamper.describe(result)}`);
+        // An UNMATCHED file is the silent-failure case this feature exists to
+        // prevent, so it is named individually rather than left as a count.
+        for (const f of result.unmatched) {
+            console.error(`stamp: WARNING ${f} — the configured pattern matched nothing; not stamped`);
+        }
+    }
     async handleVersionCommand(options) {
         try {
+            options = await this.withConfiguredPrefix(options);
             // Validate version manipulation options
             this.validator.validateVersionOptions(options);
             if (options.reset) {
@@ -46,11 +205,11 @@ class VersionController {
                 return;
             }
             if (options.compare) {
-                await this.gitManager.compareVersions(options.compare);
+                await this.gitManager.compareVersions(options.compare, options.prefix);
                 return;
             }
             if (options.revert) {
-                await this.gitManager.revertToVersion(options.revert, options.push);
+                await this.gitManager.revertToVersion(options.revert, options.push, options.prefix);
                 return;
             }
             if (options.validate) {
@@ -61,6 +220,46 @@ class VersionController {
                 await this.gitManager.syncVersions(options.push);
                 return;
             }
+            // --derive: let the COMMITS name the bump, through the taxonomy this
+            // project already configured for its changelog.
+            //
+            // AN EXPLICIT FLAG ALWAYS WINS, and quietly. `--derive --minor` is an
+            // operator saying something the history cannot know — a compatibility
+            // break nobody marked, a release deliberately held back — and a tool
+            // that argued there would be overruled by hand every time until
+            // somebody stopped passing --derive at all.
+            //
+            // THE RANGE IS THE BASELINE'S. Whatever version this run bumps FROM
+            // is the only defensible start: it names the commit the previous
+            // version pointed at, so the range is exactly the work that is new.
+            // A wider range re-grades released commits and would re-derive the
+            // same major forever once one lands.
+            if (options.derive && !options.major && !options.minor && !options.patch) {
+                const evidence = await this.deriveBumpFromRange(options);
+                if (evidence) {
+                    if (options.explainBump)
+                        console.error(`bump: ${(0, BumpDeriver_1.explainBump)(evidence)}`);
+                    options = { ...options, [evidence.bump]: true };
+                }
+            }
+            // ── THE BRANCH MAY IMPLY A CHANNEL (DECISIONS D1) ───────────────
+            //
+            // A feature deploy cuts a real prerelease named after its branch:
+            // `feature/new-thing` → `v1.0.1-feature-new-thing.1`. Off unless the
+            // branch's strategy declares `channelFromBranch`, and never when the
+            // caller named a channel itself — an explicit `--channel` is the
+            // operator saying which line they mean, and deriving over it would
+            // put the build somewhere they did not ask for.
+            // The config is read HERE rather than threaded in: this path is
+            // reached from several verbs and only one of them already holds it.
+            // A config that cannot be read is not a reason to fail a version —
+            // impliedChannel simply finds no declaration and derives nothing.
+            const branchCfg = await (0, configManager_1.readConfig)(options.config, options.environment).catch(() => undefined);
+            const implied = await (0, branchChannel_1.impliedChannel)(branchCfg, options.channel);
+            if (implied) {
+                options = { ...options, channel: implied };
+                console.error(`channel: ${implied} (from the current branch — branchStrategies.channelFromBranch)`);
+            }
             // Handle version creation/update
             let newVersion = '';
             if (options.version) {
@@ -72,11 +271,47 @@ class VersionController {
             else {
                 newVersion = await this.gitManager.generateNewVersion(options);
             }
+            // --dry-run: answer "what WOULD be cut" without cutting.
+            //
+            // Every other path here mutates — createVersion writes release
+            // notes, createGitTag moves refs, push touches the remote — so
+            // asking the question used to mean performing the answer. A
+            // release plane whose only way to report the next version is to
+            // MINT it cannot be consulted by anything upstream: a build that
+            // wants to stamp the version it is about to produce, a CI gate
+            // checking the bump is the intended one, or an operator simply
+            // looking. The version is printed on stdout ALONE so it can be
+            // captured with $(...); everything explanatory goes to stderr.
+            if (options.dryRun) {
+                console.error(`dry-run: would create ${newVersion} (nothing was written)`);
+                console.log(newVersion);
+                return;
+            }
             await this.releaseManager.createVersion(newVersion, options);
+            // ── STAMP THE WORKING TREE, BEFORE THE TAG ────────────────────
+            //
+            // The order is the whole point. A tag is a pointer to a COMMIT, so
+            // stamping after tagging produces a tag whose files still say the
+            // previous version — the artefact built from that tag then carries
+            // a number that contradicts the tag it was built from, and the
+            // contradiction is invisible until somebody installs it.
+            //
+            // Opt-in twice over: nothing happens unless `versioning.stamp.files`
+            // is configured, and even then only with `--stamp` or
+            // `versioning.stamp.onBump`. A project that has never heard of this
+            // feature must behave on upgrade exactly as it did before.
+            await this.maybeStamp(newVersion, options);
             // Create git tag
             if (options.tag !== false) {
                 // Default to true if not explicitly set to false
-                await this.gitManager.createGitTag(newVersion);
+                // The note becomes the ANNOTATED TAG'S BODY. It was being
+                // dropped: createGitTag was called without it, so the tag
+                // message defaulted to the version string and the release note
+                // lived only wherever createVersion put it. An annotated tag
+                // whose body merely repeats its own name records nothing —
+                // "who cut this, from what, and why" is the entire reason the
+                // tag is an object rather than a ref.
+                await this.gitManager.createGitTag(newVersion, options.note);
                 console.log(`Created tag: ${newVersion}`);
             }
             // Push changes if requested

package/dist/modules/version/VersionController.js.map

@@ -1 +1 @@
-{"version":3,"file":"VersionController.js","sourceRoot":"","sources":["../../../src/modules/version/VersionController.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"VersionController.js","sourceRoot":"","sources":["../../../src/modules/version/VersionController.ts"],"names":[],"mappings":"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"}

package/dist/modules/version/VersionStamper.js

@@ -0,0 +1,139 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionStamper = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const simple_git_1 = __importDefault(require("simple-git"));
+const ProjectVersion_1 = require("./ProjectVersion");
+class VersionStamper {
+    constructor(config, root = process.cwd()) {
+        this.config = config;
+        this.root = root;
+    }
+    /** Whether the project has asked for any stamping at all. */
+    get configured() {
+        var _a, _b, _c, _d, _e;
+        return ((_e = (_d = (_c = (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.versioning) === null || _b === void 0 ? void 0 : _b.stamp) === null || _c === void 0 ? void 0 : _c.files) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0) > 0;
+    }
+    /** Whether a bump should stamp without being asked. Opt-in, default off. */
+    get onBump() {
+        var _a, _b;
+        return this.configured && ((_b = (_a = this.config.versioning) === null || _a === void 0 ? void 0 : _a.stamp) === null || _b === void 0 ? void 0 : _b.onBump) === true;
+    }
+    /**
+     * Expand one configured entry to concrete files.
+     *
+     * The wildcard rules are ProjectVersion's, deliberately: one matcher in the
+     * codebase, one set of refusals, one place that has been told why `glob` is
+     * not used here. A pattern this matcher cannot serve throws by name rather
+     * than resolving to "no files", which would read as "nothing to stamp".
+     */
+    expand(entry) {
+        const rel = entry.path;
+        if (!rel.includes('*')) {
+            return [rel];
+        }
+        const idx = rel.lastIndexOf('/');
+        const dir = idx === -1 ? '' : rel.slice(0, idx);
+        const base = idx === -1 ? rel : rel.slice(idx + 1);
+        const abs = (0, path_1.isAbsolute)(dir) ? dir : (0, path_1.join)(this.root, dir);
+        if (!(0, fs_1.existsSync)(abs))
+            return [];
+        return (0, ProjectVersion_1.matchFilesInDirectory)(base, abs).map(f => (dir ? `${dir}/${f}` : f));
+    }
+    /**
+     * Substitute the placeholders a project may use in `replace` and in the
+     * commit message. `{versionCore}` exists because a tag prefix belongs to the
+     * LINE, not to the version: a manifest field that must parse as semver
+     * cannot hold `v1.2.3`, and a project should not have to strip it with a
+     * regex in the replacement string.
+     */
+    fill(template, version) {
+        const core = version.replace(/^[^0-9]*/, '');
+        return template
+            .replace(/\{version\}/g, version)
+            .replace(/\{versionCore\}/g, core);
+    }
+    async stamp(version, opts = {}) {
+        var _a, _b, _c, _d, _e, _f;
+        const out = { stamped: [], unmatched: [], missing: [], unchanged: [] };
+        const stampCfg = (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.versioning) === null || _b === void 0 ? void 0 : _b.stamp;
+        if (!((_c = stampCfg === null || stampCfg === void 0 ? void 0 : stampCfg.files) === null || _c === void 0 ? void 0 : _c.length))
+            return out;
+        for (const entry of stampCfg.files) {
+            const files = this.expand(entry);
+            if (files.length === 0) {
+                if (entry.required) {
+                    throw new Error(`Version stamp: required path '${entry.path}' matched no file under ${this.root}.`);
+                }
+                out.missing.push(entry.path);
+                continue;
+            }
+            for (const rel of files) {
+                const abs = (0, path_1.isAbsolute)(rel) ? rel : (0, path_1.resolve)(this.root, rel);
+                if (!(0, fs_1.existsSync)(abs)) {
+                    if (entry.required) {
+                        throw new Error(`Version stamp: required file '${rel}' does not exist.`);
+                    }
+                    out.missing.push(rel);
+                    continue;
+                }
+                const before = (0, fs_1.readFileSync)(abs, 'utf8');
+                // `m` so `^`/`$` anchor per LINE: the overwhelmingly common
+                // shape is a single `version:` line, and without it a pattern
+                // anchored at `^` can only ever match the first line of a file.
+                const re = new RegExp(entry.pattern, (_d = entry.flags) !== null && _d !== void 0 ? _d : 'm');
+                // `test` on a /g regex ADVANCES lastIndex, and the same object
+                // is reused for the replace below. `String.replace` happens to
+                // reset it, so this is currently harmless — and it is reset
+                // explicitly anyway, because "harmless because of what the
+                // other method does" is exactly the kind of coupling that
+                // breaks when one of the two lines moves.
+                const matched = re.test(before);
+                re.lastIndex = 0;
+                if (!matched) {
+                    if (entry.required) {
+                        throw new Error(`Version stamp: pattern /${entry.pattern}/ found nothing in required file '${rel}'.`);
+                    }
+                    out.unmatched.push(rel);
+                    continue;
+                }
+                const after = before.replace(re, this.fill(entry.replace, version));
+                if (after === before) {
+                    out.unchanged.push(rel);
+                    continue;
+                }
+                if (!opts.dryRun)
+                    (0, fs_1.writeFileSync)(abs, after);
+                out.stamped.push(rel);
+            }
+        }
+        if (!opts.dryRun && out.stamped.length > 0 && ((_e = stampCfg.commit) === null || _e === void 0 ? void 0 : _e.enabled)) {
+            const git = (0, simple_git_1.default)(this.root);
+            // PATHSPEC, never `-a`. See refusal 2 in the header.
+            await git.add(['--', ...out.stamped]);
+            const msg = this.fill((_f = stampCfg.commit.message) !== null && _f !== void 0 ? _f : 'chore(version): stamp {version}', version);
+            const res = await git.commit(msg, out.stamped);
+            out.commit = res.commit || undefined;
+        }
+        return out;
+    }
+    /** A one-line human summary — the shape a CLI prints on STDERR. */
+    static describe(r) {
+        const bits = [`${r.stamped.length} stamped`];
+        if (r.unchanged.length)
+            bits.push(`${r.unchanged.length} already current`);
+        if (r.unmatched.length)
+            bits.push(`${r.unmatched.length} UNMATCHED`);
+        if (r.missing.length)
+            bits.push(`${r.missing.length} missing`);
+        if (r.commit)
+            bits.push(`committed ${r.commit.slice(0, 10)}`);
+        return bits.join(' · ');
+    }
+}
+exports.VersionStamper = VersionStamper;
+//# sourceMappingURL=VersionStamper.js.map

package/dist/modules/version/VersionStamper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VersionStamper.js","sourceRoot":"","sources":["../../../src/modules/version/VersionStamper.ts"],"names":[],"mappings":"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"}

package/dist/modules/version/branchChannel.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.channelFromBranchName = channelFromBranchName;
+exports.strategyForBranch = strategyForBranch;
+exports.impliedChannel = impliedChannel;
+const simple_git_1 = __importDefault(require("simple-git"));
+/**
+ * The prerelease channel a BRANCH implies, when its strategy asks for one.
+ *
+ * ── WHY A FEATURE DEPLOY IS A VERSION HERE (DECISIONS D1) ───────────────────
+ *
+ * A developer wants a feature branch on a server to look at. Two shapes were on
+ * the table: an identity (`feature-new-thing-<sha>`, nothing spent, nothing left
+ * behind) and a VERSION (`v1.0.1-feature-new-thing.1`). The operator chose the
+ * version, and the cost is understood rather than hidden: every look-at-it
+ * deploy spends an immutable number, and the tag outlives the branch it names.
+ *
+ * ── IT IS OFF UNTIL A STRATEGY ASKS FOR IT ──────────────────────────────────
+ *
+ * `branchStrategies.<type>.channelFromBranch: true` is the switch, and there is
+ * no global one. A project that has not asked cuts exactly what it cut before —
+ * this engine ships to other repositories, and a version scheme that turns
+ * itself on when someone happens to be on a branch would be a surprise arriving
+ * through an upgrade.
+ *
+ * ── THE CHANNEL IS THE BRANCH NAME, SANITISED, AND KEEPS ITS PREFIX ─────────
+ *
+ * `feature/new-thing` → `feature-new-thing`, not `new-thing`. Dropping the type
+ * would make `feature/login` and `bugfix/login` the same channel, so two
+ * branches would share a counter and each would renumber the other's builds.
+ * Semver's prerelease alphabet is [0-9A-Za-z-], so everything outside it
+ * becomes `-`.
+ */
+function channelFromBranchName(branch) {
+    return branch
+        .replace(/[^0-9A-Za-z-]+/g, '-') // `/`, `_`, `.`, spaces → `-`
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase();
+}
+/**
+ * The declared strategy whose prefix this branch carries, or undefined.
+ *
+ * Longest prefix wins, so a project declaring both `feature/` and
+ * `feature/exp/` gets the more specific one rather than whichever the object
+ * happened to enumerate first.
+ */
+function strategyForBranch(config, branch) {
+    var _a, _b, _c;
+    const strategies = ((_a = config === null || config === void 0 ? void 0 : config.branchStrategies) !== null && _a !== void 0 ? _a : {});
+    let best;
+    for (const name of Object.keys(strategies)) {
+        const prefix = (_c = (_b = strategies[name]) === null || _b === void 0 ? void 0 : _b.branchPrefix) !== null && _c !== void 0 ? _c : `${name}/`;
+        if (!branch.startsWith(prefix))
+            continue;
+        if (!best || prefix.length > best.prefix.length)
+            best = { name, prefix };
+    }
+    return best;
+}
+/**
+ * The channel the CURRENT branch implies, or undefined when nothing asks.
+ *
+ * Returns undefined — never a channel — when: the caller already named one, the
+ * branch matches no declared strategy, that strategy has not set
+ * `channelFromBranch`, or git cannot say which branch this is (a detached HEAD
+ * has no name to derive from, and inventing one would put a build on a channel
+ * nobody can find again).
+ */
+async function impliedChannel(config, explicit) {
+    var _a, _b;
+    if (explicit)
+        return undefined;
+    let branch = '';
+    try {
+        branch = (await (0, simple_git_1.default)().raw(['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
+    }
+    catch (_c) {
+        return undefined;
+    }
+    if (!branch || branch === 'HEAD')
+        return undefined;
+    const strategy = strategyForBranch(config, branch);
+    if (!strategy)
+        return undefined;
+    const declared = ((_a = config === null || config === void 0 ? void 0 : config.branchStrategies) !== null && _a !== void 0 ? _a : {});
+    if (((_b = declared[strategy.name]) === null || _b === void 0 ? void 0 : _b.channelFromBranch) !== true)
+        return undefined;
+    return channelFromBranchName(branch);
+}
+//# sourceMappingURL=branchChannel.js.map

package/dist/modules/version/branchChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branchChannel.js","sourceRoot":"","sources":["../../../src/modules/version/branchChannel.ts"],"names":[],"mappings":";;;;;AA8BA,sDAMC;AASD,8CAUC;AAWD,wCAgBC;AAlFD,4DAAkC;AAGlC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,qBAAqB,CAAC,MAAc;IAChD,OAAO,MAAM;SACR,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAG,8BAA8B;SAChE,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,WAAW,EAAE,CAAA;AACtB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,MAA0B,EAAE,MAAc;;IAExE,MAAM,UAAU,GAAG,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,gBAAgB,mCAAI,EAAE,CAA8C,CAAA;IAChG,IAAI,IAAkD,CAAA;IACtD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,MAAA,MAAA,UAAU,CAAC,IAAI,CAAC,0CAAE,YAAY,mCAAI,GAAG,IAAI,GAAG,CAAA;QAC3D,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,SAAQ;QACxC,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,IAAI,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;IAC5E,CAAC;IACD,OAAO,IAAI,CAAA;AACf,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,cAAc,CAAC,MAA0B,EAAE,QAAiB;;IAC9E,IAAI,QAAQ;QAAE,OAAO,SAAS,CAAA;IAC9B,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,IAAI,CAAC;QACD,MAAM,GAAG,CAAC,MAAM,IAAA,oBAAS,GAAE,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAClF,CAAC;IAAC,WAAM,CAAC;QACL,OAAO,SAAS,CAAA;IACpB,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,SAAS,CAAA;IAElD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClD,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAA;IAC/B,MAAM,QAAQ,GAAG,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,gBAAgB,mCAAI,EAAE,CAAoD,CAAA;IACpG,IAAI,CAAA,MAAA,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,0CAAE,iBAAiB,MAAK,IAAI;QAAE,OAAO,SAAS,CAAA;IAEzE,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAA;AACxC,CAAC"}

package/dist/modules/version/resolveVersionRef.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVersionRef = resolveVersionRef;
+exports.requireVersionRef = requireVersionRef;
+const simple_git_1 = __importDefault(require("simple-git"));
+/**
+ * Turn a version STRING into a ref this repository actually has.
+ *
+ * ── ONE NORMALISATION POINT, AND THAT IS THE WHOLE POINT (DECISIONS D4) ──────
+ *
+ * Every verb that takes a version by name has to answer the same question, and
+ * before this lived in one place they answered it differently — measured
+ * 2026-08-24 on a repo tagged `v1.0.0`:
+ *
+ *   grm version --validate 1.0.0   accepted     (it only checks the string's shape)
+ *   grm version --compare  1.0.0   answered     (…then built the range `1.0.0...v1.1.0`)
+ *   grm version --revert   1.0.0   FATAL        (straight into `git reset --hard`)
+ *
+ * Three verbs, three behaviours, one question. Per-verb handling is how that
+ * happens; a shared resolver is how it stops.
+ *
+ * Candidates in order: the string itself, then the configured prefix, then a
+ * bare `v`. Most-explicit-first, so a caller that already passed a real ref is
+ * never second-guessed, and `v` last because it is a convention rather than
+ * this repository's declaration.
+ *
+ * ── 🔴 THE ANSWER IS THE SHA, NOT THE ABSENCE OF A THROW ─────────────────────
+ *
+ * `rev-parse --verify --quiet` exits non-zero with EMPTY output when a ref does
+ * not resolve, and that shape does not reliably surface as a rejected promise.
+ * Measured: the first candidate was accepted for a tag that does not exist, the
+ * range stayed `1.0.0..HEAD`, and `git log` failed one call later in a place
+ * that could no longer say which spelling was wrong. So the sha is matched,
+ * not the control flow.
+ */
+async function resolveVersionRef(input, prefix) {
+    const git = (0, simple_git_1.default)();
+    const candidates = [input];
+    if (prefix && !input.startsWith(prefix))
+        candidates.push(`${prefix}${input}`);
+    if (!input.startsWith('v'))
+        candidates.push(`v${input}`);
+    for (const candidate of candidates) {
+        try {
+            const out = await git.raw(['rev-parse', '--verify', '--quiet', `${candidate}^{commit}`]);
+            if (/^[0-9a-f]{40}/.test((out !== null && out !== void 0 ? out : '').trim()))
+                return candidate;
+        }
+        catch (_a) {
+            // Not a ref here. Try the next spelling — this is a lookup, and a
+            // miss is data, not a failure.
+        }
+    }
+    return null;
+}
+/**
+ * The same lookup, with a refusal that names every spelling it tried.
+ *
+ * A verb that is about to hand the answer to git wants this one: "1.0.0 is not
+ * a version in this repository (tried 1.0.0, v1.0.0)" is a sentence an operator
+ * can act on, where `fatal: ambiguous argument` is one they have to decode.
+ */
+async function requireVersionRef(input, prefix) {
+    const ref = await resolveVersionRef(input, prefix);
+    if (ref)
+        return ref;
+    const tried = [input];
+    if (prefix && !input.startsWith(prefix))
+        tried.push(`${prefix}${input}`);
+    if (!input.startsWith('v'))
+        tried.push(`v${input}`);
+    throw new Error(`'${input}' is not a version in this repository (tried ${tried.join(', ')}). ` +
+        `Both the bare number and the tag spelling are accepted; neither resolves here.`);
+}
+//# sourceMappingURL=resolveVersionRef.js.map

package/dist/modules/version/resolveVersionRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveVersionRef.js","sourceRoot":"","sources":["../../../src/modules/version/resolveVersionRef.ts"],"names":[],"mappings":";;;;;AAgCA,8CAgBC;AASD,8CAUC;AAnED,4DAAkC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACI,KAAK,UAAU,iBAAiB,CAAC,KAAa,EAAE,MAAe;IAClE,MAAM,GAAG,GAAG,IAAA,oBAAS,GAAE,CAAA;IACvB,MAAM,UAAU,GAAG,CAAC,KAAK,CAAC,CAAA;IAC1B,IAAI,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,UAAU,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,KAAK,EAAE,CAAC,CAAA;IAC7E,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,CAAA;IAExD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACjC,IAAI,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,SAAS,WAAW,CAAC,CAAC,CAAA;YACxF,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC,GAAG,aAAH,GAAG,cAAH,GAAG,GAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBAAE,OAAO,SAAS,CAAA;QAClE,CAAC;QAAC,WAAM,CAAC;YACL,kEAAkE;YAClE,+BAA+B;QACnC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAA;AACf,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,iBAAiB,CAAC,KAAa,EAAE,MAAe;IAClE,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAClD,IAAI,GAAG;QAAE,OAAO,GAAG,CAAA;IACnB,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,CAAA;IACrB,IAAI,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,KAAK,EAAE,CAAC,CAAA;IACxE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,CAAA;IACnD,MAAM,IAAI,KAAK,CACX,IAAI,KAAK,gDAAgD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;QAC9E,gFAAgF,CACnF,CAAA;AACL,CAAC"}