rman 0.37.4 → 1.0.1

package/services/run.service.js

@@ -0,0 +1,432 @@
+import os from 'node:os';
+import parseNpmScript from '@netlify/parse-npm-script';
+import colors from 'ansi-colors';
+import { tokenize } from 'fast-tokenizer';
+import { Task } from 'power-tasks';
+import { exec } from '../utils/exec.js';
+import { LOG_LEVELS, resolveRootLogLevel } from '../utils/logger.js';
+import { filterPackages } from '../utils/package-filter.js';
+import { ProgressPanel } from '../utils/progress-panel.js';
+export var RunService;
+(function (RunService) {
+    /**
+     * A package's `.rmanrc` (cascaded) can configure `run.<script>.*` - e.g.
+     *   run:
+     *     build:
+     *       concurrency: 2
+     *     lint:
+     *       topo: false
+     *       bail: false
+     * and a package can opt itself out of a script entirely:
+     *   run:
+     *     build:
+     *       skip: true
+     * or supply the command(s) to run when its own package.json doesn't define this script (or its
+     * pre/post hooks) at all - a single string, or an array to run several in sequence - see
+     * `getScriptSteps`:
+     *   run:
+     *     build:
+     *       script: tsc -b
+     *       preScript: [node ./generate.js, node ./validate.js]
+     *       postScript: node ./copy-assets.js
+     *       override: true   # use these even if the package *does* define its own
+     */
+    function getConfig(pkg, script) {
+        const runCfg = pkg.config?.run;
+        const cfg = runCfg && typeof runCfg === 'object' ? runCfg[script] : undefined;
+        return cfg && typeof cfg === 'object' ? cfg : {};
+    }
+    RunService.getConfig = getConfig;
+    function resolveEnvPlaceholders(value) {
+        return value.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => process.env[name] ?? '');
+    }
+    /** Recursive-descent parser over `tokenizeIf`'s output: expr := or ; or := and ('or' and)* ;
+     *  and := unary ('and' unary)* ; unary := 'not' unary | GROUP | NAME ['=' VALUE] */
+    function parseIfExpr(raw) {
+        if (typeof raw !== 'string' || !raw.trim())
+            return undefined;
+        const tokens = tokenizeIf(raw);
+        if (!tokens.length)
+            return undefined;
+        let i = 0;
+        const peek = () => tokens[i];
+        const next = () => tokens[i++];
+        function parseUnary() {
+            if (peek()?.toLowerCase() === 'not') {
+                next();
+                return { kind: 'not', node: parseUnary() };
+            }
+            const tok = next() ?? '';
+            /** A token containing whitespace can only be a collapsed `(...)` group - plain
+             *  atom/operator tokens never do, since they're themselves split on whitespace. */
+            if (/\s/.test(tok)) {
+                const inner = parseIfExpr(tok);
+                if (!inner)
+                    throw new Error(`Empty group in "if" expression: "${raw}"`);
+                return inner;
+            }
+            let value;
+            if (peek() === '=') {
+                next();
+                value = resolveEnvPlaceholders(next() ?? '');
+            }
+            return { kind: 'atom', name: tok, value };
+        }
+        function parseAnd() {
+            let node = parseUnary();
+            while (peek()?.toLowerCase() === 'and') {
+                next();
+                node = { kind: 'and', left: node, right: parseUnary() };
+            }
+            return node;
+        }
+        function parseOr() {
+            let node = parseAnd();
+            while (peek()?.toLowerCase() === 'or') {
+                next();
+                node = { kind: 'or', left: node, right: parseAnd() };
+            }
+            return node;
+        }
+        return parseOr();
+    }
+    RunService.parseIfExpr = parseIfExpr;
+    /** Evaluates a parsed `if` expression for one package. `statusCache` avoids repeat `git` calls
+     *  for the same reference hash across packages/scripts in a single run. */
+    async function evaluateIf(repository, pkg, node, statusCache) {
+        if (node.kind === 'and') {
+            if (!(await evaluateIf(repository, pkg, node.left, statusCache)))
+                return false;
+            return evaluateIf(repository, pkg, node.right, statusCache);
+        }
+        if (node.kind === 'or') {
+            if (await evaluateIf(repository, pkg, node.left, statusCache))
+                return true;
+            return evaluateIf(repository, pkg, node.right, statusCache);
+        }
+        if (node.kind === 'not') {
+            return !(await evaluateIf(repository, pkg, node.node, statusCache));
+        }
+        return evaluateIfAtom(repository, pkg, node.name, node.value, statusCache);
+    }
+    RunService.evaluateIf = evaluateIf;
+    async function runScript(repository, script, options = {}) {
+        const commandName = options.commandName || 'run';
+        const rootCfg = getConfig(repository.rootPackage, script);
+        const logLevelDefault = resolveRootLogLevel(repository);
+        /** Standing inside a single package's own directory scopes the run to just that package
+         *  (and drops the root bookend below) unless `--root` asks for the whole repository anyway -
+         *  a no-op when already at the root, or outside any known package. */
+        const cwdScope = options.root ? undefined : repository.currentPackage;
+        /** Global fallback for topo - individual packages can still override their own linking below,
+         *  but the initial sort (topological vs alphabetical) has to be decided for the whole list at once. */
+        const topo = resolveBool(options.topo, repository.rootPackage, script, 'topo', true);
+        let packages = repository.getPackages({ toposort: topo, scope: cwdScope?.name });
+        if (!topo)
+            packages = [...packages].sort((a, b) => a.name.localeCompare(b.name));
+        packages = filterPackages(packages, options);
+        const changed = resolveBool(options.changed, repository.rootPackage, script, 'changed', false);
+        const changedSince = options.changedSince ?? (typeof rootCfg.changedSince === 'string' ? rootCfg.changedSince : undefined);
+        if (changed || changedSince) {
+            const status = await repository.listStatus({ hash: changedSince });
+            packages = packages.filter(p => status[p.name] !== 'clean');
+        }
+        const concurrency = options.parallel === false
+            ? 1
+            : typeof options.parallel === 'number'
+                ? options.parallel
+                : options.parallel === true
+                    ? os.cpus().length
+                    : resolveNumber(undefined, repository.rootPackage, script, 'concurrency', os.cpus().length);
+        const progress = resolveBool(options.progress, repository.rootPackage, script, 'progress', true);
+        const panel = new ProgressPanel(`RUN ${script}`, !!process.stdout.isTTY && progress);
+        /** Set once the aggregate Task exists, so a package's own failure can trigger a manual
+         *  abort using *its own* resolved bail setting (see `runSteps` below) - power-tasks' own
+         *  `bail` is a single blanket policy for the whole batch, it can't vary per package. */
+        let rootTask;
+        const runSteps = async (ctx, pkgLabel, steps, cwd, pkgBail, pkgLogLevel) => {
+            ctx.status = 'running';
+            ctx.startedAt = Date.now();
+            try {
+                for (let i = 0; i < steps.length; i++) {
+                    const step = steps[i];
+                    ctx.currentStep = step.name;
+                    ctx.stepIndex = i;
+                    if (panel.enabled) {
+                        await exec(step.command, {
+                            cwd,
+                            stdio: 'pipe',
+                            onLine: (line, stdio) => {
+                                ctx.log.push(line);
+                                ctx.lastLine = line;
+                                void stdio;
+                            },
+                        });
+                    }
+                    else {
+                        /** Match the classic rman output: raw command output streams straight through
+                         *  (unbuffered, unprefixed), followed by our own one-line-per-step summary. */
+                        printLegacyExecutingLine(commandName, pkgLabel, step, pkgLogLevel);
+                        const stepStart = Date.now();
+                        let stepError;
+                        try {
+                            await exec(step.command, { cwd, stdio: 'inherit' });
+                        }
+                        catch (e) {
+                            stepError = e;
+                        }
+                        printLegacyStepLine(commandName, pkgLabel, step, Date.now() - stepStart, pkgLogLevel, stepError);
+                        if (stepError)
+                            throw stepError;
+                    }
+                }
+                ctx.status = 'success';
+            }
+            catch (e) {
+                ctx.status = 'failed';
+                if (pkgBail)
+                    rootTask?.abort();
+                throw e;
+            }
+            finally {
+                ctx.finishedAt = Date.now();
+            }
+        };
+        const children = [];
+        /** Shared across all `if: changed[ = hash]` evaluations so the same reference is only `git`-queried once. */
+        const ifStatusCache = new Map();
+        /** Repo-wide bookend: root's own pre/post hooks run once each, exclusively, around every package
+         *  (unless root itself opts out via `run.<script>.skip`, fails its own `run.<script>.if`, or the
+         *  run is scoped to a single package by `cwdScope` - a repo-wide bookend has no place there). */
+        const rootIf = !cwdScope && parseIfExpr(rootCfg.if);
+        const rootIfPasses = rootIf ? await evaluateIf(repository, repository.rootPackage, rootIf, ifStatusCache) : true;
+        const rootSkipped = !!cwdScope || rootCfg.skip === true || !rootIfPasses;
+        const rootSteps = rootSkipped ? [] : getScriptSteps(repository.rootPackage, script);
+        const rootPre = rootSteps.filter(s => s.name === 'pre' + script);
+        const rootPost = rootSteps.filter(s => s.name === 'post' + script);
+        const rootPreName = 'root (pre)';
+        const rootPostName = 'root (post)';
+        if (rootPre.length) {
+            const ctx = panel.addItem(rootPreName, rootPre.length);
+            const pkgBail = resolveBail(options.bail, repository.rootPackage, script, true);
+            const pkgLogLevel = resolveLogLevel(options.logLevel, repository.rootPackage, script, logLevelDefault);
+            children.push(new Task(() => runSteps(ctx, 'root', rootPre, repository.dirname, pkgBail, pkgLogLevel), {
+                name: ctx.name,
+                exclusive: true,
+            }));
+        }
+        const stepsByPackage = new Map();
+        for (const pkg of packages) {
+            const pkgCfg = getConfig(pkg, script);
+            if (pkgCfg.skip === true)
+                continue;
+            const pkgIf = parseIfExpr(pkgCfg.if);
+            if (pkgIf && !(await evaluateIf(repository, pkg, pkgIf, ifStatusCache)))
+                continue;
+            const steps = getScriptSteps(pkg, script);
+            if (steps.length)
+                stepsByPackage.set(pkg.name, steps);
+        }
+        for (const pkg of packages) {
+            const steps = stepsByPackage.get(pkg.name);
+            if (!steps)
+                continue;
+            const ctx = panel.addItem(pkg.name, steps.length);
+            const pkgTopo = resolveBool(options.topo, pkg, script, 'topo', topo);
+            const pkgBail = resolveBail(options.bail, pkg, script, true);
+            const pkgLogLevel = resolveLogLevel(options.logLevel, pkg, script, logLevelDefault);
+            const dependencies = pkgTopo ? pkg.dependencies.filter(d => stepsByPackage.has(d)) : [];
+            if (rootPre.length)
+                dependencies.push(rootPreName);
+            children.push(new Task(() => runSteps(ctx, pkg.name, steps, pkg.dirname, pkgBail, pkgLogLevel), {
+                name: ctx.name,
+                dependencies,
+            }));
+        }
+        if (rootPost.length) {
+            const ctx = panel.addItem(rootPostName, rootPost.length);
+            const pkgBail = resolveBail(options.bail, repository.rootPackage, script, true);
+            const pkgLogLevel = resolveLogLevel(options.logLevel, repository.rootPackage, script, logLevelDefault);
+            children.push(new Task(() => runSteps(ctx, 'root', rootPost, repository.dirname, pkgBail, pkgLogLevel), {
+                name: ctx.name,
+                exclusive: true,
+                /** Must wait for every package task to finish, not just be "exclusive" once it starts. */
+                dependencies: [...stepsByPackage.keys()],
+            }));
+        }
+        if (!children.length) {
+            console.log(colors.gray(`No package defines a "${script}" script.`));
+            return;
+        }
+        panel.start();
+        let failed = false;
+        try {
+            /** bail:false here - each package's own resolved bail setting decides whether to call
+             *  `rootTask.abort()` itself (see `runSteps`), since power-tasks' own `bail` can't vary per package. */
+            rootTask = new Task(children, { concurrency, bail: false });
+            await rootTask.toPromise();
+        }
+        catch {
+            failed = true;
+        }
+        finally {
+            panel.stop();
+        }
+        panel.printSummary();
+        if (failed) {
+            const err = new Error(`"${script}" failed`);
+            err.logged = true;
+            throw err;
+        }
+    }
+    RunService.runScript = runScript;
+})(RunService || (RunService = {}));
+/**
+ * Classic one-line-per-step log ("info build pkg ┆ step success ┆ command  (123 ms)"),
+ * matching rman's original npmlog-based output. Used when the live panel is off.
+ *
+ * Respects `logLevel`: 'verbose' also prints an "executing" line before the step runs
+ * (rman's old behavior, hidden by default); 'error' suppresses success lines; 'silent'
+ * suppresses everything but a real failure.
+ */
+function printLegacyExecutingLine(commandName, pkgLabel, step, level) {
+    if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf('verbose'))
+        return;
+    const sep = colors.gray('┆');
+    console.log(colors.magenta('verbose'), commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), colors.cyanBright.bold('executing'), sep, step.command);
+}
+function printLegacyStepLine(commandName, pkgLabel, step, durationMs, level, error) {
+    if (!error && LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf('info'))
+        return;
+    if (error && level === 'silent')
+        return;
+    const sep = colors.gray('┆');
+    const levelLabel = error ? colors.red('error') : colors.green('info');
+    const status = error ? colors.red.bold('failed') : colors.green.bold('success');
+    console.log(levelLabel, commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), status, sep, step.command, colors.yellow(` (${durationMs} ms)`));
+}
+/** A `run.<script>.script`/`.preScript`/`.postScript` value: one command, or several to run in sequence. */
+function normalizeScriptValue(value) {
+    if (typeof value === 'string')
+        return value || undefined;
+    if (Array.isArray(value)) {
+        // joined with "&&", same as a multi-command package.json script - each entry becomes its
+        // own step below, and an earlier failure stops the rest (npm's own semantics).
+        const parts = value.filter((v) => typeof v === 'string' && !!v);
+        return parts.length ? parts.join(' && ') : undefined;
+    }
+    return undefined;
+}
+/**
+ * Resolves a package's steps for `script`, including its own pre/post hooks (npm's own
+ * convention) - `.rmanrc run.<script>.script`/`.preScript`/`.postScript` (cascaded) can each supply
+ * a command (or an array of them, run in sequence) to use when the package's own package.json has
+ * none for that slot (`script`/`pre<script>`/`post<script>`), letting a package run a script it
+ * never defined at all. `run.<script>.override` goes further: with it, the config's command
+ * replaces the package's own for a slot even when the package *does* define one there.
+ */
+function getScriptSteps(pkg, script) {
+    const cfg = RunService.getConfig(pkg, script);
+    const json = { ...pkg.json, scripts: { ...(pkg.json.scripts || {}) } };
+    const applyConfigScript = (key, rawValue) => {
+        const value = normalizeScriptValue(rawValue);
+        if (!value)
+            return;
+        const hasOwn = typeof json.scripts[key] === 'string' && json.scripts[key];
+        if (cfg.override === true || !hasOwn)
+            json.scripts[key] = value;
+    };
+    applyConfigScript(script, cfg.script);
+    applyConfigScript('pre' + script, cfg.preScript);
+    applyConfigScript('post' + script, cfg.postScript);
+    json.scripts[script] = json.scripts[script] || '#';
+    const info = parseNpmScript(json, 'npm run ' + script);
+    if (!info?.raw?.length)
+        return [];
+    const steps = [];
+    for (const s of info.steps) {
+        const parsed = Array.isArray(s.parsed) ? s.parsed : [s.parsed];
+        for (const command of parsed) {
+            if (command === '#')
+                continue;
+            steps.push({ name: s.name, command });
+        }
+    }
+    return steps;
+}
+/**
+ * Splits on whitespace, but a `(...)` group collapses to a single token holding its inner text
+ * (parens stripped, inner whitespace kept) - `evaluate` below re-tokenizes any token that still
+ * contains whitespace, which is what makes nested groups "just work" without a separate grammar
+ * for parens: `((a or b) and c)` peels off one bracket layer per recursive `tokenizeIf` call.
+ */
+function tokenizeIf(raw) {
+    return tokenize(raw, { delimiters: /\s+/, brackets: true, keepBrackets: false }).all();
+}
+const warnedUnknownIf = new Set();
+const warnedEmptyIfValue = new Set();
+async function evaluateIfAtom(repository, pkg, name, value, statusCache) {
+    switch (name) {
+        case 'changed':
+        case 'dirty':
+        case 'committed': {
+            if (value !== undefined && !value) {
+                const warnKey = `${pkg.name}:${name}`;
+                if (!warnedEmptyIfValue.has(warnKey)) {
+                    warnedEmptyIfValue.add(warnKey);
+                    console.log(colors.yellow(`[${pkg.name}] "if: ${name} = ..." resolved to an empty value - treating as not matched.`));
+                }
+                return false;
+            }
+            const cacheKey = value || '';
+            let statusMap = statusCache.get(cacheKey);
+            if (!statusMap) {
+                statusMap = await repository.listStatus(value ? { hash: value } : undefined);
+                statusCache.set(cacheKey, statusMap);
+            }
+            const status = statusMap[pkg.name];
+            /** With a hash, status only ever resolves to 'changed'/'clean' (see Repository.listStatus) -
+             *  the dirty/committed distinction only exists relative to upstream, so those two conditions
+             *  naturally never match when a hash is given. */
+            if (name === 'changed')
+                return status !== 'clean';
+            return status === name;
+        }
+        default:
+            if (!warnedUnknownIf.has(name)) {
+                warnedUnknownIf.add(name);
+                console.log(colors.yellow(`Unknown "if" condition "${name}" - ignoring, package will still run.`));
+            }
+            return true;
+    }
+}
+/** Resolution order: explicit CLI flag > the package's resolved `.rmanrc` > `fallback`. */
+export function resolveBool(cliValue, pkg, script, key, fallback) {
+    if (cliValue !== undefined)
+        return cliValue;
+    const v = RunService.getConfig(pkg, script)[key];
+    return typeof v === 'boolean' ? v : fallback;
+}
+/**
+ * Bail is the one setting where a package's own `.rmanrc` outranks even an explicit CLI flag:
+ * "this package's failure must always stop the batch" is a more specific, intentional statement
+ * than a broad `--no-bail` meant for the run as a whole, and shouldn't be silently overridable by it.
+ */
+export function resolveBail(cliValue, pkg, script, fallback) {
+    const v = RunService.getConfig(pkg, script).bail;
+    if (typeof v === 'boolean')
+        return v;
+    return cliValue !== undefined ? cliValue : fallback;
+}
+export function resolveNumber(cliValue, pkg, script, key, fallback) {
+    if (cliValue !== undefined)
+        return cliValue;
+    const v = RunService.getConfig(pkg, script)[key];
+    return typeof v === 'number' ? v : fallback;
+}
+export function resolveLogLevel(cliValue, pkg, script, fallback) {
+    if (cliValue !== undefined)
+        return cliValue;
+    const v = RunService.getConfig(pkg, script).logLevel;
+    return typeof v === 'string' && LOG_LEVELS.includes(v) ? v : fallback;
+}

package/services/system-info.d.ts

@@ -0,0 +1,16 @@
+import envinfo from 'envinfo';
+import type { Repository } from '../core/repository.js';
+export declare namespace SystemInfo {
+    interface RepositoryInfo {
+        type: 'monorepo' | 'package';
+        name: string;
+        version: string;
+        root: string;
+        packageCount: number;
+    }
+    /** Whatever `envinfo` reports (OS/CPU/Memory/Shell, Node/Yarn/npm, git, installed
+     *  rman/typescript versions), grouped by category - shape is `envinfo`'s own, not ours. */
+    type SystemInfo = Record<string, Record<string, unknown>>;
+    function getSystemInfo(options?: envinfo.RunConfig): Promise<SystemInfo.SystemInfo>;
+    function getRepositoryInfo(repository: Repository): SystemInfo.RepositoryInfo;
+}

package/services/system-info.js

@@ -0,0 +1,25 @@
+import envinfo from 'envinfo';
+export var SystemInfo;
+(function (SystemInfo) {
+    async function getSystemInfo(options) {
+        return JSON.parse(await envinfo.run({
+            System: ['OS', 'CPU', 'Memory', 'Shell'],
+            Binaries: ['Node', 'Yarn', 'npm'],
+            Utilities: ['Git'],
+            npmPackages: ['rman', 'typescript'],
+            npmGlobalPackages: ['typescript'],
+            ...options,
+        }, { json: true }));
+    }
+    SystemInfo.getSystemInfo = getSystemInfo;
+    function getRepositoryInfo(repository) {
+        return {
+            type: repository.monorepo ? 'monorepo' : 'package',
+            name: repository.rootPackage.name,
+            version: repository.rootPackage.version,
+            root: repository.dirname,
+            packageCount: repository.getPackages().length,
+        };
+    }
+    SystemInfo.getRepositoryInfo = getRepositoryInfo;
+})(SystemInfo || (SystemInfo = {}));

package/services/version.service.d.ts

@@ -0,0 +1,95 @@
+import type { Package } from '../core/package.js';
+import type { Repository } from '../core/repository.js';
+import { type PackageFilterOptions } from '../utils/package-filter.js';
+export declare namespace VersionService {
+    type BumpKeyword = 'patch' | 'minor' | 'major';
+    function isBumpKeyword(value: unknown): value is BumpKeyword;
+    interface Options extends PackageFilterOptions {
+        /** A release-type keyword (applied as the severity for every group that has real changes) or
+         *  a concrete semver version (applied as the literal new version wherever something changed) -
+         *  either way, this replaces auto-detection entirely. Omit to auto-detect the severity per
+         *  group from conventional-commit subjects since each package's/group's last release tag. */
+        bump?: string;
+        /** A package with uncommitted local changes is excluded from bumping (status `'skip'`)
+         *  instead of aborting the whole plan (status `'error'`). Default false. */
+        ignoreDirty?: boolean;
+        /** Makes every computed bump a prerelease (`1.2.3` -> `1.3.0-beta.0` for a `minor`, say)
+         *  tagged with this identifier, instead of a normal release - same idea as `npm version
+         *  <type> --preid <name>`. A group already sitting on a matching prerelease (same identifier)
+         *  just has its prerelease counter incremented instead of jumping to a new base version - see
+         *  `incVersion`. Has no effect when `bump` is an explicit semver version rather than a keyword
+         *  (there's no severity left to "pre-fix" at that point). */
+        preid?: string;
+    }
+    interface ApplyOptions {
+        /** Push the resulting commit(s) and tag(s) to the remote once applied. Default false - same
+         *  as a plain `npm version`, which never pushes on its own either. */
+        push?: boolean;
+        /** Overrides `.rmanrc version.commitMessage` (and the built-in default) for every group's
+         *  commit this run produces - `{version}` is still substituted the same way. */
+        message?: string;
+        /** Also writes each bumped package's `CHANGELOG.md` (via `ChangelogService.generateToFile`,
+         *  scoped to just the packages this run actually bumped) and folds those file changes into the
+         *  same per-group commit, instead of requiring a separate `rman changelog --write` run. */
+        changelog?: boolean;
+    }
+    /** One package's outcome in a version plan - see `getPlan`. */
+    interface Entry {
+        package: Package;
+        /** Internal group identity packages are batched by (not for display) - see `resolveGroupKey`. */
+        groupKey: string;
+        /** Human-readable group name: `'default'` for the implicit repo-wide group, the configured
+         *  name for a named `group`, or the package's own name when it isn't grouped with anyone. */
+        group: string;
+        status: 'bump' | 'skip' | 'error' | 'no-change';
+        from: string;
+        /** Only set when `status === 'bump'`. */
+        to?: string;
+        /** Human-readable explanation - e.g. why a package was skipped, or why it's being bumped
+         *  despite having no commits of its own (a dependency of it changed elsewhere). */
+        reason?: string;
+    }
+    /**
+     * 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.
+     */
+    function getPlan(repository: Repository, options?: Options): Promise<Entry[]>;
+    /**
+     * 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.
+     */
+    function applyPlan(repository: Repository, plan: Entry[], options?: ApplyOptions): Promise<Entry[]>;
+}
+/** 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 declare const DEPENDENCY_KEYS: readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];