rman 0.37.4 → 1.0.1

package/services/version.service.js

@@ -0,0 +1,450 @@
+import path from 'node:path';
+import semver from 'semver';
+import { findLatestTag, tagPattern } from '../utils/change-hash.js';
+import { hasBreakingChangeFooter, parseConventionalCommit, parseReleaseAs, VERSION_BUMP_PATTERN, } from '../utils/conventional-commits.js';
+import { exec } from '../utils/exec.js';
+import { GitHelper } from '../utils/git.js';
+import { filterPackages } from '../utils/package-filter.js';
+import { parseWorkspaceRange } from '../utils/workspace-range.js';
+import { ChangelogService } from './changelog.service.js';
+export var VersionService;
+(function (VersionService) {
+    function isBumpKeyword(value) {
+        return value === 'patch' || value === 'minor' || value === 'major';
+    }
+    VersionService.isBumpKeyword = isBumpKeyword;
+    /**
+     * Computes what a version bump *would* do, across every package `.rmanrc group` puts together -
+     * never writes anything (no package.json edits, no git commits/tags) and safe to call any time,
+     * including as the "preview" a bare `rman version` (no bump given) stops at.
+     *
+     * Packages are partitioned into groups by their resolved `group` value (cascaded): `true`
+     * (the default) puts every such package into one implicit repo-wide group; a string joins
+     * exactly the other packages sharing that same string, regardless of the repo's default; `false`
+     * makes a package its own solo group. Each group's "current version" is always the highest
+     * version currently found among its own members (never persisted anywhere) - see
+     * `resolveGroupKey`.
+     *
+     * Within a group, a member with real commits since its own last release tag (or an explicit
+     * `bump`) sets the group's severity to the highest found among changed members; the new version
+     * is that current version bumped by that severity. Which members actually receive it depends on
+     * the severity: **patch** only the changed member(s) (a caret dependency range already tolerates
+     * a patch bump, no republish needed downstream); **minor** also every transitive in-group
+     * dependent; **major** the entire group, changed or not - see `computeGroupPlan`.
+     *
+     * Across groups: a package depending on another group's bumped package always gets exactly a
+     * **patch** bump of its own (never inheriting the source's severity) - the dependency reference
+     * itself is the only thing that changed for it. This never re-triggers *its own* group's
+     * minor/major cascade (a patch never cascades), but can itself ripple into a third group, and so
+     * on, until nothing new is affected - see `rippleCrossGroup`.
+     *
+     * A monorepo's root package is never a real member of any group (it's never published on its
+     * own) - it gets one trailing informational entry instead, always `'bump'`ed to whatever single
+     * version every group ended up sharing, or the overall highest version when groups diverged.
+     */
+    async function getPlan(repository, options = {}) {
+        const bump = options.bump?.trim();
+        const explicitSeverity = bump && isBumpKeyword(bump) ? bump : undefined;
+        const explicitVersion = bump && !explicitSeverity ? (semver.valid(bump) ?? undefined) : undefined;
+        if (bump && !explicitSeverity && !explicitVersion) {
+            throw new Error(`Invalid "bump": "${bump}" (expected "patch", "minor", "major", or a valid semver version)`);
+        }
+        const git = new GitHelper({ cwd: repository.dirname });
+        const packages = filterPackages(repository.getPackages(), options);
+        const dirtyFiles = await git.listDirtyFiles({ absolute: true });
+        const isDirty = (pkg) => dirtyFiles.some(f => !path.relative(pkg.dirname, f).startsWith('..'));
+        const entries = new Map();
+        const eligible = [];
+        for (const pkg of packages) {
+            if (isDirty(pkg)) {
+                entries.set(pkg.name, {
+                    package: pkg,
+                    groupKey: resolveGroupKey(pkg),
+                    group: groupLabel(resolveGroupKey(pkg)),
+                    status: options.ignoreDirty ? 'skip' : 'error',
+                    from: pkg.version,
+                    reason: 'uncommitted local changes',
+                });
+                continue;
+            }
+            eligible.push(pkg);
+        }
+        const changeByPackage = new Map();
+        await Promise.all(eligible.map(async (pkg) => {
+            if (explicitVersion) {
+                changeByPackage.set(pkg.name, { severity: undefined, reason: `explicit version ${explicitVersion}` });
+                return;
+            }
+            const tag = await findLatestTag(git, pkg);
+            const commits = tag ? await git.listCommits({ hash: tag }) : await git.listAllCommits();
+            const belongsToPkg = (c) => c.files.some(f => !path.relative(pkg.dirname, f).startsWith('..'));
+            const real = commits.filter(c => belongsToPkg(c) && !VERSION_BUMP_PATTERN.test(c.subject));
+            if (!real.length)
+                return;
+            changeByPackage.set(pkg.name, {
+                severity: explicitSeverity ?? detectSeverity(real),
+                reason: tag ? `changed since ${tag}` : 'unreleased commits',
+            });
+        }));
+        const groups = new Map();
+        for (const pkg of eligible) {
+            const key = resolveGroupKey(pkg);
+            const list = groups.get(key);
+            if (list)
+                list.push(pkg);
+            else
+                groups.set(key, [pkg]);
+        }
+        for (const [key, members] of groups) {
+            computeGroupPlan(key, members, changeByPackage, explicitVersion, options.preid, entries);
+        }
+        rippleCrossGroup(packages, entries, options.preid);
+        const result = packages.map(pkg => entries.get(pkg.name));
+        if (repository.monorepo)
+            result.push(buildRootEntry(repository, result));
+        return result;
+    }
+    VersionService.getPlan = getPlan;
+    /**
+     * Same as `getPlan`, and additionally writes every `'bump'` entry's new version into its own
+     * `package.json` (and refreshes any other bumped package's dependency range on it), runs that
+     * package's `version.preScript`/`.script`/`.postScript` (or its own real `preversion`/`version`/
+     * `postversion` npm scripts) around the write, then commits and tags **once per group** - so
+     * independently-versioned groups each get their own clean commit/tag rather than one entangled
+     * commit spanning unrelated version lines. Pushes only when `options.push` is set - same as a
+     * plain `npm version`, this never reaches the network on its own otherwise.
+     */
+    async function applyPlan(repository, plan, options = {}) {
+        const git = new GitHelper({ cwd: repository.dirname });
+        // The root's own entry is only ever a real package to write/commit like any other when this
+        // *isn't* a monorepo (see `getPlan`) - in a monorepo it's the separate, purely informational
+        // entry handled below instead, since it's never published on its own.
+        const isRealEntry = (e) => !(repository.monorepo && e.package === repository.rootPackage);
+        const bumped = plan.filter(e => e.status === 'bump' && isRealEntry(e));
+        const bumpedByName = new Map(bumped.map(e => [e.package.name, e]));
+        for (const entry of bumped) {
+            const pkg = entry.package;
+            await runVersionScript(pkg, 'preScript', 'preversion');
+            pkg.json.version = entry.to;
+            for (const depKey of DEPENDENCY_KEYS) {
+                const deps = pkg.json[depKey];
+                if (!deps)
+                    continue;
+                for (const depName of Object.keys(deps)) {
+                    const depEntry = bumpedByName.get(depName);
+                    if (!depEntry)
+                        continue;
+                    const workspace = parseWorkspaceRange(deps[depName]);
+                    if (workspace) {
+                        // A bare "workspace:*"/"^"/"~" selector always resolves to the dependency's *current*
+                        // version at publish time (see `resolveWorkspaceRange`) - nothing to rewrite here. Only
+                        // an explicit version/range after "workspace:" needs bumping, same as a plain range.
+                        if (workspace.selector === 'explicit')
+                            deps[depName] = `workspace:^${depEntry.to}`;
+                        continue;
+                    }
+                    deps[depName] = '^' + depEntry.to;
+                }
+            }
+            await runVersionScript(pkg, 'script', 'version');
+            pkg.writeJson();
+            await runVersionScript(pkg, 'postScript', 'postversion');
+        }
+        const rootEntry = repository.monorepo ? plan.find(e => e.package === repository.rootPackage) : undefined;
+        if (rootEntry?.status === 'bump') {
+            repository.rootPackage.json.version = rootEntry.to;
+            repository.rootPackage.writeJson();
+        }
+        /** Written before the per-group commits below so each group's changelog file lands in the
+         *  *same* commit as its version bump, rather than needing a separate `changelog --write` run.
+         *  Bounded by each package's own *pre-bump* tag (the same one `getPlan` measured "changed
+         *  since" from - see `expandTag`) rather than `changelog`'s own default auto-detection (an npm
+         *  registry lookup, falling back to not-yet-pushed commits) - that boundary can drift from the
+         *  one `version` itself just used, and the not-yet-pushed fallback needs a configured remote
+         *  `version` never required at all. Falls back to `changelog`'s own default only when this
+         *  package genuinely has no prior tag (a first-ever release). */
+        const changelogFileByPackage = new Map();
+        if (options.changelog) {
+            for (const entry of bumped) {
+                const fromTag = expandTag(entry.package, entry.from);
+                const from = (await git.tagExists(fromTag)) ? fromTag : undefined;
+                const changelogEntries = await ChangelogService.generateToFile(repository, {
+                    scope: entry.package.name,
+                    root: true,
+                    from,
+                });
+                for (const ce of changelogEntries) {
+                    changelogFileByPackage.set(ce.package.name, path.relative(repository.dirname, path.join(ce.package.dirname, ce.filePath)));
+                }
+            }
+        }
+        const byGroup = new Map();
+        for (const entry of bumped) {
+            const list = byGroup.get(entry.groupKey);
+            if (list)
+                list.push(entry);
+            else
+                byGroup.set(entry.groupKey, [entry]);
+        }
+        for (const [, groupEntries] of byGroup) {
+            const files = groupEntries.map(e => path.relative(repository.dirname, e.package.jsonFileName));
+            for (const e of groupEntries) {
+                const changelogFile = changelogFileByPackage.get(e.package.name);
+                if (changelogFile)
+                    files.push(changelogFile);
+            }
+            await git.commit(files, buildCommitMessage(repository, groupEntries, options.message));
+            const tags = new Set(groupEntries.map(e => expandTag(e.package, e.to)));
+            for (const tag of tags)
+                if (!(await git.tagExists(tag)))
+                    await git.createTag(tag);
+        }
+        /** The root's own informational version write isn't part of any group's release, but still
+         *  needs to land in *some* commit rather than being left as an uncommitted local edit. */
+        if (rootEntry?.status === 'bump') {
+            await git.commit([path.relative(repository.dirname, repository.rootPackage.jsonFileName)], `chore: sync root version to ${rootEntry.to}`);
+        }
+        if (options.push && bumped.length)
+            await git.push();
+        return plan;
+    }
+    VersionService.applyPlan = applyPlan;
+})(VersionService || (VersionService = {}));
+/** Every `package.json` field holding dependency ranges - shared with `PublishService`'s own
+ *  `"workspace:"` rewrite-for-publish step, since it needs to scan the same fields. */
+export const DEPENDENCY_KEYS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+const SEVERITY_RANK = { patch: 0, minor: 1, major: 2 };
+/** `.rmanrc group` (cascaded): `true` (the default - see `resolveConfig`'s cascade, this is what a
+ *  package inherits when nobody sets it at all) puts a package in the one implicit repo-wide
+ *  group; a non-empty string joins exactly the other packages sharing that string, regardless of
+ *  the repo's own default; `false` makes it a solo group of one. */
+function resolveGroupKey(pkg) {
+    const g = pkg.config?.group;
+    if (g === false)
+        return `solo:${pkg.name}`;
+    if (typeof g === 'string' && g)
+        return `named:${g}`;
+    return 'default';
+}
+function groupLabel(key) {
+    if (key.startsWith('named:'))
+        return key.slice('named:'.length);
+    if (key.startsWith('solo:'))
+        return key.slice('solo:'.length);
+    return key;
+}
+/**
+ * Highest bump type implied by `commits`: a `Release-As: patch|minor|major` footer (see
+ * `parseReleaseAs`) replaces what that one commit's own subject/footers would otherwise imply,
+ * entirely - the escape hatch for e.g. a `feat:` that needs to ship as a patch right now, without
+ * waiting for the rest of a minor's worth of work. Absent that, a `!` marker or a `BREAKING
+ * CHANGE:` footer wins outright; otherwise `feat` implies minor; anything else (a `fix`, an
+ * unrecognized type, a non-conventional message) defaults to patch - something changed, so at
+ * least a patch release is warranted.
+ */
+function detectSeverity(commits) {
+    let severity = 'patch';
+    for (const c of commits) {
+        const override = parseReleaseAs(c.body);
+        if (override === 'major')
+            return 'major';
+        if (override) {
+            if (SEVERITY_RANK[override] > SEVERITY_RANK[severity])
+                severity = override;
+            continue;
+        }
+        const parsed = parseConventionalCommit(c.subject);
+        if (parsed?.breaking || hasBreakingChangeFooter(c.body))
+            return 'major';
+        if (parsed?.type === 'feat')
+            severity = 'minor';
+    }
+    return severity;
+}
+function maxVersion(versions) {
+    return versions.reduce((m, v) => (semver.gt(v, m) ? v : m), versions[0]);
+}
+/**
+ * `semver.inc`, "pre-ified" when `preid` is given: `current` already sitting on a prerelease with
+ * that *same* identifier just has its prerelease counter incremented (`'prerelease'`, e.g.
+ * `1.2.3-beta.0` -> `1.2.3-beta.1`) rather than jumping to a new base version every time this
+ * runs again during the same beta/rc cycle; anything else (a plain release, or a prerelease under
+ * a *different* identifier - switching from `beta` to `rc`, say) starts a fresh prerelease of
+ * `severity`'s own type (`'prepatch'`/`'preminor'`/`'premajor'`, e.g. `1.2.3` -> `1.3.0-beta.0`
+ * for a `minor`). Without `preid`, this is just `semver.inc(current, severity)`.
+ */
+function incVersion(current, severity, preid) {
+    if (!preid)
+        return semver.inc(current, severity) ?? current;
+    const existing = semver.prerelease(current);
+    const releaseType = existing && String(existing[0]) === preid ? 'prerelease' : `pre${severity}`;
+    return semver.inc(current, releaseType, preid) ?? current;
+}
+/**
+ * Decides one group's new version and which of its members actually receive it, writing an
+ * `Entry` per member into `entries`. `changeByPackage` holds each eligible package's own detected
+ * severity (or `undefined` for one with no real commits since its last tag) - `undefined` here
+ * always means "unchanged", never "explicit version" (that path is handled separately below).
+ */
+function computeGroupPlan(key, members, changeByPackage, explicitVersion, preid, entries) {
+    const label = groupLabel(key);
+    const changed = members.filter(m => changeByPackage.has(m.name));
+    if (!changed.length) {
+        for (const m of members) {
+            entries.set(m.name, { package: m, groupKey: key, group: label, status: 'no-change', from: m.version });
+        }
+        return;
+    }
+    const current = maxVersion(members.map(m => m.version));
+    let to;
+    let severity;
+    if (explicitVersion) {
+        to = explicitVersion;
+    }
+    else {
+        severity = changed.reduce((worst, m) => {
+            const s = changeByPackage.get(m.name).severity;
+            return SEVERITY_RANK[s] > SEVERITY_RANK[worst] ? s : worst;
+        }, 'patch');
+        to = incVersion(current, severity, preid);
+    }
+    const bumping = new Set(changed);
+    if (!explicitVersion && severity === 'major') {
+        for (const m of members)
+            bumping.add(m);
+    }
+    else if (!explicitVersion && severity === 'minor') {
+        const worklist = [...changed];
+        while (worklist.length) {
+            const cur = worklist.pop();
+            for (const m of members) {
+                if (bumping.has(m))
+                    continue;
+                if (m.dependencies.includes(cur.name)) {
+                    bumping.add(m);
+                    worklist.push(m);
+                }
+            }
+        }
+    }
+    for (const m of members) {
+        if (bumping.has(m)) {
+            const own = changeByPackage.get(m.name);
+            entries.set(m.name, {
+                package: m,
+                groupKey: key,
+                group: label,
+                status: 'bump',
+                from: m.version,
+                to,
+                reason: own?.reason ?? `in-group dependent of a ${severity} change`,
+            });
+        }
+        else {
+            entries.set(m.name, { package: m, groupKey: key, group: label, status: 'no-change', from: m.version });
+        }
+    }
+}
+/**
+ * A package depending on another group's bumped package always receives exactly a patch bump of
+ * its own, computed from its *own* group's current ceiling (the highest `to`/version among its
+ * group right now) - never the source's version, and never the source's severity. Runs as a
+ * worklist until nothing new is affected, since patching one package can itself cross into a third
+ * group, and so on; never touches a same-group dependent that a plain patch deliberately left
+ * alone (see `computeGroupPlan`'s patch case).
+ */
+function rippleCrossGroup(packages, entries, preid) {
+    const worklist = [...entries.values()].filter(e => e.status === 'bump');
+    while (worklist.length) {
+        const source = worklist.shift();
+        for (const pkg of packages) {
+            const entry = entries.get(pkg.name);
+            if (entry.status === 'bump' || entry.groupKey === source.groupKey)
+                continue;
+            if (!pkg.dependencies.includes(source.package.name))
+                continue;
+            const groupCeiling = maxVersion(packages
+                .filter(p => entries.get(p.name).groupKey === entry.groupKey)
+                .map(p => entries.get(p.name).to ?? p.version));
+            const next = {
+                ...entry,
+                status: 'bump',
+                to: incVersion(groupCeiling, 'patch', preid),
+                reason: `depends on ${source.package.name}@${source.to}`,
+            };
+            entries.set(pkg.name, next);
+            worklist.push(next);
+        }
+    }
+}
+/** The root's own `version` field is purely informational in a monorepo (it's never published on
+ *  its own) - it always reflects whatever single version every group ended up sharing, or the
+ *  overall highest version when groups diverged onto different numbers. Reports `'no-change'`
+ *  (not `'bump'`) when nothing in the repository changed at all. */
+function buildRootEntry(repository, memberEntries) {
+    const root = repository.rootPackage;
+    const anyBumped = memberEntries.some(e => e.status === 'bump');
+    if (!anyBumped) {
+        return { package: root, groupKey: '__root__', group: 'root', status: 'no-change', from: root.version };
+    }
+    const finalVersions = memberEntries.map(e => e.to ?? e.from);
+    const unique = new Set(finalVersions);
+    const to = unique.size === 1 ? finalVersions[0] : maxVersion(finalVersions);
+    return {
+        package: root,
+        groupKey: '__root__',
+        group: 'root',
+        status: 'bump',
+        from: root.version,
+        to,
+        reason: 'informational - monorepo root is never published on its own',
+    };
+}
+/** `.rmanrc version.commitMessage` (root-level; `{version}` is replaced when every bumped package
+ *  in this commit shares one version) - defaults to `"chore(release): v{version}"`, or a plain
+ *  listing of `name@version` pairs when this particular commit spans different versions (a
+ *  cross-group ripple can land a lone forced patch in a group that otherwise didn't move). */
+function buildCommitMessage(repository, entries, messageOverride) {
+    const versions = new Set(entries.map(e => e.to));
+    if (versions.size === 1) {
+        const template = messageOverride ?? repository.rootPackage.config?.version?.commitMessage;
+        const version = entries[0].to;
+        if (typeof template === 'string' && template)
+            return template.replace(/\{version\}/g, version);
+        return `chore(release): v${version}`;
+    }
+    if (messageOverride)
+        return messageOverride;
+    return `chore(release): ${entries.map(e => `${e.package.name}@${e.to}`).join(', ')}`;
+}
+/** Expands `pkg`'s (cascaded) `.rmanrc changelog.tagPattern` into a concrete tag name for
+ *  `version` - the same pattern `changelog` reads tags back with (see `findLatestTag`), just run
+ *  forward: `{name}` becomes the package's own name, and `*` becomes `version`. */
+function expandTag(pkg, version) {
+    const pattern = tagPattern(pkg).replace('{name}', pkg.name);
+    const starIdx = pattern.indexOf('*');
+    return starIdx === -1 ? pattern : pattern.slice(0, starIdx) + version + pattern.slice(starIdx + 1);
+}
+/** A `version.<key>` value: one command, or several to run in sequence - same shape as
+ *  `run.<script>.script`/`.preScript`/`.postScript`. */
+function normalizeScriptValue(value) {
+    if (typeof value === 'string')
+        return value || undefined;
+    if (Array.isArray(value)) {
+        const parts = value.filter((v) => typeof v === 'string' && !!v);
+        return parts.length ? parts.join(' && ') : undefined;
+    }
+    return undefined;
+}
+/**
+ * Runs `pkg`'s own real npm lifecycle script (`preversion`/`version`/`postversion`) if it defines
+ * one for this phase, otherwise its `.rmanrc version.<cfgKey>` equivalent if configured - neither
+ * replaces the version write itself (unlike `ci`'s own-script override), they're hooks around a
+ * write that always happens, since dependency ranges and tags depend on it happening consistently.
+ */
+async function runVersionScript(pkg, cfgKey, npmScriptName) {
+    const own = pkg.json.scripts?.[npmScriptName];
+    const command = typeof own === 'string' && own ? own : normalizeScriptValue(pkg.config?.version?.[cfgKey]);
+    if (command)
+        await exec(command, { cwd: pkg.dirname, stdio: 'inherit' });
+}

package/services.d.ts

@@ -0,0 +1,10 @@
+export { ChangelogService } from './services/changelog.service.js';
+export { CiService } from './services/ci.service.js';
+export { CleanService } from './services/clean.service.js';
+export { ExecService } from './services/exec.service.js';
+export { ImportService } from './services/import.service.js';
+export { ListService } from './services/list.service.js';
+export { PublishService } from './services/publish.service.js';
+export { RunService } from './services/run.service.js';
+export { SystemInfo } from './services/system-info.js';
+export { VersionService } from './services/version.service.js';

package/services.js

@@ -0,0 +1,10 @@
+export { ChangelogService } from './services/changelog.service.js';
+export { CiService } from './services/ci.service.js';
+export { CleanService } from './services/clean.service.js';
+export { ExecService } from './services/exec.service.js';
+export { ImportService } from './services/import.service.js';
+export { ListService } from './services/list.service.js';
+export { PublishService } from './services/publish.service.js';
+export { RunService } from './services/run.service.js';
+export { SystemInfo } from './services/system-info.js';
+export { VersionService } from './services/version.service.js';

package/utils/branch-guard.d.ts

@@ -0,0 +1,25 @@
+import type { Argv } from 'yargs';
+import type { Repository } from '../core/repository.js';
+/** Same idea as GitHub Actions' own `branches`/`branches-ignore` workflow filters - restricts a
+ *  command to running only from certain branches (or refuses certain ones), instead of any. */
+export interface BranchGuardOptions {
+    allowBranch?: string | string[];
+    ignoreBranch?: string | string[];
+}
+/** `--allow-branch`/`--ignore-branch`, the same shape and describe text in every command that
+ *  supports them - mirrors `package-filter.ts`'s own `applyPackageFilterOptions`. */
+export declare function applyBranchGuardOptions<T>(cmd: Argv<T>): Argv<T>;
+export declare function readBranchGuardOptions(args: any): BranchGuardOptions;
+/**
+ * Refuses to let the command continue when the current branch doesn't satisfy `options` - an
+ * explicit CLI `allowBranch`/`ignoreBranch` replaces the root's own (cascade-free) `.rmanrc`
+ * equivalent entirely, same as `packageManager`'s own CLI-over-config precedence; with neither
+ * set anywhere, every branch is allowed (this is purely opt-in, same as GitHub Actions' workflows
+ * running on every branch until a `branches:` filter is added). A detached HEAD (or a directory
+ * that isn't a git repository at all) is never blocked - there's no branch name to check against.
+ *
+ * Already prints its own message and marks the error `logged` before throwing (matching every
+ * other guard check's convention in this codebase, e.g. `version`'s own dirty-check) - callers
+ * just need to `await` it before doing anything else.
+ */
+export declare function assertAllowedBranch(repository: Repository, options?: BranchGuardOptions): Promise<void>;

package/utils/branch-guard.js

@@ -0,0 +1,61 @@
+import colors from 'ansi-colors';
+import micromatch from 'micromatch';
+import { GitHelper } from './git.js';
+/** `--allow-branch`/`--ignore-branch`, the same shape and describe text in every command that
+ *  supports them - mirrors `package-filter.ts`'s own `applyPackageFilterOptions`. */
+export function applyBranchGuardOptions(cmd) {
+    return cmd
+        .option('allow-branch', {
+        describe: 'Refuse to run unless the current branch matches this glob (repeatable) - default: .rmanrc ' +
+            '"allowBranch", or no restriction at all',
+        type: 'string',
+    })
+        .option('ignore-branch', {
+        describe: 'Refuse to run if the current branch matches this glob (repeatable) - default: .rmanrc ' +
+            '"ignoreBranch", or no restriction at all',
+        type: 'string',
+    });
+}
+export function readBranchGuardOptions(args) {
+    return {
+        allowBranch: args.allowBranch,
+        ignoreBranch: args.ignoreBranch,
+    };
+}
+/**
+ * Refuses to let the command continue when the current branch doesn't satisfy `options` - an
+ * explicit CLI `allowBranch`/`ignoreBranch` replaces the root's own (cascade-free) `.rmanrc`
+ * equivalent entirely, same as `packageManager`'s own CLI-over-config precedence; with neither
+ * set anywhere, every branch is allowed (this is purely opt-in, same as GitHub Actions' workflows
+ * running on every branch until a `branches:` filter is added). A detached HEAD (or a directory
+ * that isn't a git repository at all) is never blocked - there's no branch name to check against.
+ *
+ * Already prints its own message and marks the error `logged` before throwing (matching every
+ * other guard check's convention in this codebase, e.g. `version`'s own dirty-check) - callers
+ * just need to `await` it before doing anything else.
+ */
+export async function assertAllowedBranch(repository, options = {}) {
+    const allow = options.allowBranch ?? repository.config?.allowBranch;
+    const ignore = options.ignoreBranch ?? repository.config?.ignoreBranch;
+    if (!allow && !ignore)
+        return;
+    const git = new GitHelper({ cwd: repository.dirname });
+    const branch = await git.currentBranch();
+    if (!branch)
+        return;
+    if (allow && !micromatch.isMatch(branch, toArray(allow))) {
+        fail(`Branch "${branch}" is not allowed to run this command (must match: ${toArray(allow).join(', ')})`);
+    }
+    if (ignore && micromatch.isMatch(branch, toArray(ignore))) {
+        fail(`Branch "${branch}" is not allowed to run this command (blocked by: ${toArray(ignore).join(', ')})`);
+    }
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+function fail(message) {
+    console.log(colors.red(message));
+    const err = new Error(message);
+    err.logged = true;
+    throw err;
+}

package/utils/change-hash.d.ts

@@ -0,0 +1,55 @@
+import type { Package } from '../core/package.js';
+import type { GitHelper } from './git.js';
+/** `.rmanrc changelog.tagPattern` (cascaded, per-package overridable) - a glob for this package's
+ *  release tags. `{name}` (if present) is replaced with the package's own name, e.g. `{name}@*`
+ *  for independent per-package versioning (`@scope/pkg@1.2.3`, the same scheme lerna/changesets
+ *  use - `@`/`/` are both fine in a git tag name). Without `{name}`, it's a single repo-wide tag
+ *  shared by every package (e.g. the default `v*`). */
+export declare function tagPattern(pkg: Package): string;
+/** This package's most recent release tag - the `{name}`-bearing pattern looks up that package's
+ *  *own* tags directly (newest by version sort); a repo-wide pattern instead finds the nearest tag
+ *  HEAD actually descends from, since no single package "owns" that tag. `undefined` if never
+ *  tagged at all (a fresh package, or one that's never been released). Shared by `changelog`
+ *  (reading the last-documented version) and `version` (finding the boundary a bump measures
+ *  "since"). */
+export declare function findLatestTag(git: GitHelper, pkg: Package): Promise<string | undefined>;
+/** Strips the pattern's literal prefix (everything before its first `*`) from `tag` to get just
+ *  the version part - e.g. tag `@sqb/builder@1.2.3` against pattern `@sqb/builder@*` -> `1.2.3`.
+ *  A pattern with no `*` is returned as its own "version" verbatim (an exact tag, nothing to strip). */
+export declare function extractVersion(tag: string, expandedPattern: string): string;
+/** Looks up `name`'s currently-published version on the npm registry, or `undefined` if it isn't
+ *  published there at all (private, scoped-but-unpublished, no network, ...) - the real npm CLI
+ *  call `detectChangeHash` uses by default; injectable via its `npmViewVersion` option so tests
+ *  aren't making real registry calls. */
+export declare function defaultNpmViewVersion(name: string, cwd: string): Promise<string | undefined>;
+export interface DetectChangeHashOptions {
+    /** Use this commit/hash directly instead of auto-detecting - applies the same way to every
+     *  package. `"npm"` (or omitting `from` entirely) triggers auto-detection instead of being
+     *  treated as a literal ref. */
+    from?: string;
+    /** Overrides the real npm registry lookup made when auto-detecting - mainly for tests, so they
+     *  don't depend on network access or a real published package. */
+    npmViewVersion?: (name: string, cwd: string) => Promise<string | undefined>;
+    /** An existing record of what's already been documented (typically a changelog file) - only
+     *  consulted while auto-detecting (ignored when `from` is an explicit hash). Guards against a
+     *  gap: if this file's own last-modifying commit is *older* than the npm-detected tag - e.g. the
+     *  file was last updated for 1.1.0, but 1.2.0-1.5.0 were released without ever documenting them,
+     *  and npm now reports 1.5.0 - starting from the tag alone would silently skip everything the
+     *  file never recorded. The boundary becomes the merge-base of the two, so the result always
+     *  covers at least as much as the file is missing. Has no effect when the file doesn't exist. */
+    catchUpFile?: string;
+}
+/**
+ * Resolves the commit/hash a package's changes should be measured "since" - the boundary
+ * `changelog --from` uses, but reusable anywhere a command wants to answer "what changed for this
+ * package". An explicit `options.from` (anything but `"npm"`) is returned as-is, applying the same
+ * way to every package. Otherwise, it's auto-detected from the package's currently-published npm
+ * version: looked up via `npmViewVersion`, then mapped to a git tag using `.rmanrc
+ * changelog.tagPattern` (so independent and fixed monorepo versioning schemes both work - see
+ * `tagPattern`) - and, if `catchUpFile` is given and exists, widened to also cover anything that
+ * file hasn't caught up on yet (see its doc comment). Returns `undefined` when nothing can be
+ * resolved at all (unpublished, no network, no matching tag, no catch-up file) - callers should
+ * fall back to their own default in that case (e.g. `GitHelper.listCommits`'s "not yet pushed"
+ * default when no hash is given).
+ */
+export declare function detectChangeHash(git: GitHelper, pkg: Package, options?: DetectChangeHashOptions): Promise<string | undefined>;