@exadev/semantic-release-workspace 1.1.7 → 1.2.1

package/dist/cli.js

@@ -12,8 +12,9 @@ import { readFile, writeFile } from "node:fs/promises";
 import validateNpmPackageName from "validate-npm-package-name";
 import { glob } from "tinyglobby";
 import { parse } from "yaml";
+import { pathToFileURL } from "node:url";
 //#region package.json
-var version = "1.1.7";
+var version = "1.2.1";
 //#endregion
 //#region src/errors.ts
 /**
@@ -141,11 +142,36 @@ const BOT_IDENTITY = {
 	name: "semantic-release-bot",
 	email: "semantic-release-bot@martynus.net"
 };
+/**
+* The environment variables git itself sets when it invokes a hook (`pre-push`, `pre-commit`, and friends), which then leak into every child process a hook spawns unless a child explicitly clears them: `GIT_DIR` (and, in a worktree checkout, its value points at that worktree's own git-dir under the main repository's `.git/worktrees/<name>`), `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_PREFIX`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES`, `GIT_COMMON_DIR`, and `GIT_NAMESPACE`. Every one of these overrides git's normal cwd-based repository discovery, so if any of them survive into a `git()` call this package makes with an explicit `cwd` (most obviously `git init` on a throwaway temporary directory in the test suite's own fixtures), the command silently targets whatever repository the *outer* invocation was hooked from instead of the directory this package actually asked for -- observed directly as `git init` in a fixture's temp directory failing to lock the real repository's own `.git/config`, because `GIT_DIR` inherited from this package's own `pre-push` hook pointed straight back at it. `GIT_EXEC_PATH`, `GIT_EDITOR`, and networking/auth-related `GIT_*` variables (SSH, proxy, credential helpers) are deliberately left alone: they do not affect which repository a command targets, only how it behaves once it has found one.
+*/
+const GIT_REPOSITORY_DISCOVERY_ENV_KEYS = [
+	"GIT_DIR",
+	"GIT_WORK_TREE",
+	"GIT_INDEX_FILE",
+	"GIT_PREFIX",
+	"GIT_OBJECT_DIRECTORY",
+	"GIT_ALTERNATE_OBJECT_DIRECTORIES",
+	"GIT_COMMON_DIR",
+	"GIT_NAMESPACE"
+];
+/**
+* A copy of the given environment with every repository-discovery-affecting `GIT_*` key removed -- see `GIT_REPOSITORY_DISCOVERY_ENV_KEYS`.
+*
+* Exported (not just used internally by `git()`) because this package hands an environment to two different kinds of subprocess: its own `git()` calls (sanitized unconditionally below, from `process.env`, since those never take a caller-supplied environment) and semantic-release's own programmatic API, which spawns its *own* internal git subprocesses (tag, push, verifyAuth) using whatever `env` this package passes it -- release.ts and single-commit-release.ts both call this on the environment they construct for that, so a `GIT_DIR` inherited from an outer hook cannot leak into semantic-release's internal git calls either, not just into this package's own.
+*/
+function sanitizeGitEnv(env) {
+	const sanitized = { ...env };
+	for (const key of GIT_REPOSITORY_DISCOVERY_ENV_KEYS) delete sanitized[key];
+	return sanitized;
+}
+const SANITIZED_PROCESS_GIT_ENV = sanitizeGitEnv(process.env);
 async function git(args, options) {
 	try {
 		const { stdout } = await execFileAsync$1("git", [...args], {
 			cwd: options.cwd,
-			maxBuffer: GIT_MAX_BUFFER_BYTES
+			maxBuffer: GIT_MAX_BUFFER_BYTES,
+			env: SANITIZED_PROCESS_GIT_ENV
 		});
 		return stdout;
 	} catch (cause) {
@@ -238,6 +264,50 @@ async function pushHead(options) {
 		`HEAD:${await currentBranch(options)}`
 	], options);
 }
+/** Creates a lightweight tag (`git tag <name> <ref>`, no annotation) at the given commit -- the same form semantic-release's own core creates its release tags with (see its `lib/git.js`), so a tag this tool creates directly is indistinguishable from one semantic-release would have made itself. */
+async function createTag(name, ref, options) {
+	await git([
+		"tag",
+		name,
+		ref
+	], options);
+}
+/**
+* Lists every path with a working-tree or index change (modified, added, deleted, untracked), repository-root-relative, via `git status --porcelain=v1 -z`. `commitStrategy: 'single'` uses this rather than predicting which files each configured prepare plugin touched (a version bump, a changelog write, a dependency-range rewrite, a regenerated lockfile) by name: asking git what actually changed is correct regardless of which prepare plugins are configured or how they name their own output files.
+*
+* `-z` NUL-terminates every field so a path containing a space or newline cannot be misread as two paths; a rename or copy (status codes `R`/`C`) carries two NUL-terminated fields (the new path first, then the origin path), so it consumes two tokens instead of one.
+*/
+async function workingTreeChanges(options) {
+	const tokens = (await git([
+		"status",
+		"--porcelain=v1",
+		"--untracked-files=all",
+		"-z"
+	], options)).split("\0").filter((token) => token !== "");
+	const paths = [];
+	for (let index = 0; index < tokens.length; index += 1) {
+		const entry = tokens[index];
+		if (entry === void 0 || entry.length < 4) continue;
+		const statusCode = entry.slice(0, 2);
+		paths.push(entry.slice(3));
+		if (statusCode.includes("R") || statusCode.includes("C")) index += 1;
+	}
+	return paths;
+}
+/** Fails loudly if the working tree is not clean, rather than silently folding pre-existing, unrelated dirty state into a release commit. `commitStrategy: 'single'` calls this before it starts, since it relies on `workingTreeChanges` to discover exactly what its own run touches. */
+async function assertCleanWorkingTree(options) {
+	const changes = await workingTreeChanges(options);
+	if (changes.length > 0) throw new WorkspaceStateError(`The working tree in ${options.cwd} is not clean: ${changes.join(", ")}. commitStrategy "single" discovers what it touched via "git status", so it requires a clean tree to start from; commit, stash elsewhere, or discard these changes first.`);
+}
+/** Pushes the current branch's head and a set of tags to origin in one push, so a combined release commit and every tag pointing at it land on the remote as a single atomic-looking update rather than as separate pushes an interrupted run could split across. */
+async function pushHeadAndTags(tagNames, options) {
+	await git([
+		"push",
+		"origin",
+		`HEAD:${await currentBranch(options)}`,
+		...tagNames
+	], options);
+}
 function toGitCommandError(args, cwd, cause) {
 	const exitCode = cause instanceof Error && "code" in cause && typeof cause.code === "number" ? cause.code : void 0;
 	const stderr = cause instanceof Error && "stderr" in cause && typeof cause.stderr === "string" ? cause.stderr.trim() : "";
@@ -255,6 +325,12 @@ const DEFAULT_PUBLISH_PLUGINS = [
 		message: "chore(release): ${nextRelease.gitTag} [skip ci]"
 	}]
 ];
+/** The standard publish pipeline for `commitStrategy: 'single'`: the same as `DEFAULT_PUBLISH_PLUGINS` minus @semantic-release/git, which that mode never runs -- see `resolvePublishPlugins`'s `forbidGitPlugin` option for why it is rejected outright rather than merely unused. Single-commit mode does its own committing (one combined commit for every released package), so a `prepare`-step git plugin here would create the very per-package commits that mode exists to avoid. */
+const SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS = [
+	"@semantic-release/changelog",
+	"@semantic-release/npm",
+	"@semantic-release/github"
+];
 const STEP_PLUGINS_THE_ORCHESTRATOR_OWNS = /* @__PURE__ */ new Set(["@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator"]);
 /**
 * Builds the per-package `analyzeCommits` and `generateNotes` functions handed to semantic-release as inline plugins.
@@ -275,7 +351,9 @@ function createScopedPlugins(scope) {
 			from,
 			paths: changedPathsSince(from, { cwd: context.cwd })
 		};
-		return filterCommitsToDirectory(context.commits, await cached.paths, scope.pkg.repoRelativeDirectory);
+		const commits = filterCommitsToDirectory(context.commits, await cached.paths, scope.pkg.repoRelativeDirectory);
+		scope.onCommitsResolved?.(commits);
+		return commits;
 	}
 	return {
 		async analyzeCommits(_pluginConfig, context) {
@@ -346,7 +424,10 @@ function resolvePublishPlugins(specs, workspaceRoot, options) {
 	for (const spec of specs) {
 		const [name, config] = parsePublishPluginSpec(spec);
 		if (STEP_PLUGINS_THE_ORCHESTRATOR_OWNS.has(name)) throw new ReleaseConfigurationError(`"${name}" is listed as a publish plugin, but ${packageName} always provides the ${name === "@semantic-release/commit-analyzer" ? "analyzeCommits" : "generateNotes"} step itself, wrapped around that plugin. Passing it here would make its configuration a silent no-op; set that configuration on the orchestrator's analyzeCommits/generateNotes options instead.`);
-		if (name === "@semantic-release/git") hasGitPlugin = true;
+		if (name === "@semantic-release/git") {
+			hasGitPlugin = true;
+			if (options.forbidGitPlugin === true) throw new ReleaseConfigurationError(`"@semantic-release/git" is listed as a publish plugin, but commitStrategy "single" does its own committing -- one combined commit for every released package, tagged once every package has been analysed -- rather than letting each package's own release commit itself. Remove @semantic-release/git from the plugin list; its version bump and changelog write still happen (via its sibling prepare plugins), just folded into the combined commit instead of made on their own.`);
+		}
 		const entry = [resolvePluginModule(name, requireFromTool, requireFromWorkspace), config];
 		resolved.push(entry);
 	}
@@ -415,6 +496,70 @@ async function writeDependencyRange(path, field, dependency, range) {
 	await writeFile(path, stringifyJsonLike(parsed, text), "utf8");
 }
 //#endregion
+//#region src/version-range.ts
+const WORKSPACE_PROTOCOL = "workspace:";
+const CATALOG_PROTOCOL = "catalog:";
+const NPM_ALIAS_PROTOCOL = "npm:";
+/** The `workspace:` suffixes pnpm resolves against the sibling's version at pack time rather than against anything written in the manifest. */
+const PUBLISH_RESOLVED_WORKSPACE_SUFFIXES = [
+	"*",
+	"^",
+	"~"
+];
+/** Ranges that pin nothing, so a sibling's new version cannot change what they mean. */
+const WILDCARD_RANGES = [
+	"",
+	"*",
+	"x",
+	"X",
+	"latest"
+];
+/**
+* A single comparator whose version can be replaced in place without changing the comparator's intent. `<` and `<=` are deliberately absent: rewriting `<2.0.0` to `<1.4.0` narrows an upper bound to the very version being released, which is never what the author meant, so such a range is rejected rather than mangled.
+*/
+const REWRITABLE_COMPARATOR = /^(\^|~|>=|=)?(\d+\.\d+\.\d+(?:-[\dA-Za-z.-]+)?(?:\+[\dA-Za-z.-]+)?)$/;
+/**
+* Classifies a dependency range's shape, throwing `UnsupportedDependencyRangeError` for anything this tool cannot rewrite with confidence: a compound range (`>=1.0.0 <2.0.0`), a union (`1.x || 2.x`), a `catalog:` reference whose real version lives in `pnpm-workspace.yaml`, an `npm:` alias, a git or tarball URL. Guessing at those would either corrupt the range or silently leave it pointing at a version that no longer exists in the workspace, and a stale published range is exactly the divergence this tool exists to prevent.
+*
+* This never needs the version a sibling is releasing: every case above depends only on the shape of `current` itself, which is what lets `releaseWorkspace` validate every workspace dependency edge up front, before any package has published anything, rather than discovering an unsupported range only when the first dependency it names happens to release.
+*/
+function classifyDependencyRange(current) {
+	const range = current.trim();
+	if (range.startsWith(WORKSPACE_PROTOCOL)) {
+		const suffix = range.slice(10);
+		if (PUBLISH_RESOLVED_WORKSPACE_SUFFIXES.includes(suffix)) return { kind: "resolved-at-publish" };
+		const inner = classifyDependencyRange(suffix);
+		if (inner.kind !== "rewritable") throw new UnsupportedDependencyRangeError(`Cannot bump the workspace dependency range "${current}": only "workspace:*", "workspace:^", "workspace:~", and "workspace:" followed by a single concrete version range are supported.`);
+		return {
+			kind: "rewritable",
+			workspacePrefixed: true,
+			comparator: inner.comparator
+		};
+	}
+	if (range.startsWith(CATALOG_PROTOCOL)) throw new UnsupportedDependencyRangeError(`Cannot bump the workspace dependency range "${current}": the version of a "catalog:" dependency lives in pnpm-workspace.yaml, not in the package manifest, so bumping it here would leave the catalog entry stale. Depend on the sibling directly (for example "workspace:^") instead.`);
+	if (range.startsWith(NPM_ALIAS_PROTOCOL)) throw new UnsupportedDependencyRangeError(`Cannot bump the workspace dependency range "${current}": an "npm:" alias points at a differently-named package, so the version released in this workspace is not necessarily the version this range refers to.`);
+	if (WILDCARD_RANGES.includes(range)) return { kind: "wildcard" };
+	const match = REWRITABLE_COMPARATOR.exec(range);
+	if (match === null) throw new UnsupportedDependencyRangeError(`Cannot bump the workspace dependency range "${current}": only a single "^", "~", ">=", "=", or bare version comparator can be rewritten in place.`);
+	return {
+		kind: "rewritable",
+		workspacePrefixed: false,
+		comparator: match[1] ?? ""
+	};
+}
+/**
+* Computes what a dependency range on a workspace sibling becomes once that sibling releases `version`, by classifying the range's shape and then, for a rewritable shape, substituting `version` in place of the version it currently names.
+*/
+function updateDependencyRange(current, version) {
+	const shape = classifyDependencyRange(current);
+	if (shape.kind !== "rewritable") return shape;
+	const rewritten = `${shape.comparator}${version}`;
+	return {
+		kind: "rewritten",
+		range: shape.workspacePrefixed ? `${WORKSPACE_PROTOCOL}${rewritten}` : rewritten
+	};
+}
+//#endregion
 //#region src/workspace.ts
 /** The one filename pnpm recognises as a workspace definition. */
 const WORKSPACE_MANIFEST = "pnpm-workspace.yaml";
@@ -569,6 +714,22 @@ function firstUnplacedDependency(name, graph, unplaced) {
 	if (name === void 0) return [...unplaced].sort()[0];
 	return (graph.dependencies.get(name) ?? []).map((edge) => edge.dependency).filter((dependency) => unplaced.has(dependency)).sort()[0];
 }
+/**
+* Checks every workspace dependency edge's range shape before anything releases, so an `UnsupportedDependencyRangeError` stops a run before the first publish rather than after some sibling has already been published, tagged, committed, and pushed. The shape a range supports depends only on the range text itself (see `classifyDependencyRange`), never on which version a sibling ends up releasing, so this can run once up front for the whole graph instead of only being discovered edge by edge as each dependency happens to release.
+*
+* Shared by both commit strategies (`release.ts`'s per-package loop and `single-commit-release.ts`'s analysis phase), which is why it lives alongside the graph it validates rather than inside either strategy's own module.
+*/
+function validateDependencyRangeShapes(graph) {
+	for (const edges of graph.dependencies.values()) for (const edge of edges) classifyDependencyRange(edge.range);
+}
+/**
+* Looks up a value the caller already knows must be present -- a package or edge the topological order or graph just produced -- throwing rather than returning `undefined` if it somehow is not. An internal-consistency guard, not a user-facing validation, so both commit strategies share it rather than each carrying its own copy.
+*/
+function mustGet(map, key, what) {
+	const value = map.get(key);
+	if (value === void 0) throw new WorkspaceReleaseError(`Internal error: ${what} "${key}" disappeared from the dependency graph mid-run.`);
+	return value;
+}
 //#endregion
 //#region src/pnpm.ts
 const execFileAsync = promisify(execFile);
@@ -587,69 +748,274 @@ async function regenerateLockfile(options) {
 	}
 }
 //#endregion
-//#region src/version-range.ts
-const WORKSPACE_PROTOCOL = "workspace:";
-const CATALOG_PROTOCOL = "catalog:";
-const NPM_ALIAS_PROTOCOL = "npm:";
-/** The `workspace:` suffixes pnpm resolves against the sibling's version at pack time rather than against anything written in the manifest. */
-const PUBLISH_RESOLVED_WORKSPACE_SUFFIXES = [
-	"*",
-	"^",
-	"~"
-];
-/** Ranges that pin nothing, so a sibling's new version cannot change what they mean. */
-const WILDCARD_RANGES = [
-	"",
-	"*",
-	"x",
-	"X",
-	"latest"
-];
-/**
-* A single comparator whose version can be replaced in place without changing the comparator's intent. `<` and `<=` are deliberately absent: rewriting `<2.0.0` to `<1.4.0` narrows an upper bound to the very version being released, which is never what the author meant, so such a range is rejected rather than mangled.
-*/
-const REWRITABLE_COMPARATOR = /^(\^|~|>=|=)?(\d+\.\d+\.\d+(?:-[\dA-Za-z.-]+)?(?:\+[\dA-Za-z.-]+)?)$/;
+//#region src/single-commit-release.ts
 /**
-* Classifies a dependency range's shape, throwing `UnsupportedDependencyRangeError` for anything this tool cannot rewrite with confidence: a compound range (`>=1.0.0 <2.0.0`), a union (`1.x || 2.x`), a `catalog:` reference whose real version lives in `pnpm-workspace.yaml`, an `npm:` alias, a git or tarball URL. Guessing at those would either corrupt the range or silently leave it pointing at a version that no longer exists in the workspace, and a stale published range is exactly the divergence this tool exists to prevent.
+* `commitStrategy: 'single'`: one combined commit for the whole run instead of one commit per package release plus one per dependency bump.
 *
-* This never needs the version a sibling is releasing: every case above depends only on the shape of `current` itself, which is what lets `releaseWorkspace` validate every workspace dependency edge up front, before any package has published anything, rather than discovering an unsupported range only when the first dependency it names happens to release.
+* Five phases, all inside one `releaseWorkspaceSingleCommit` call:
+*
+* 1. **Analyse** (this file's `analysePackage`): for every package, in topological order, run semantic-release with `dryRun: true` forced (regardless of the caller's own `dryRun` option) using the same path-scoped `analyzeCommits`/`generateNotes` wrapper `commitStrategy: 'per-package'` uses -- computing each package's next version and notes without writing, committing, tagging, or publishing anything. Cross-package dependency bumps are tracked purely in memory during this phase (`pendingBumps`), exactly as the per-package strategy tracks them for the span of one run; nothing is committed yet for a later run to recover from, because this strategy never leaves a partial commit for a crash to recover from in the first place -- either the whole combined commit lands, or nothing does.
+* 2. **Verify** every released package's configured publish plugins' `verifyConditions` step (npm registry auth, GitHub token/repo access), before any file is written -- the same fail-fast-before-anything-releases discipline `validateDependencyRangeShapes` already applies to dependency ranges.
+* 3. **Prepare**: for every released package, in topological order, apply any dependency-range bump its own manifest received (writing `package.json` directly, the same `writeDependencyRange` the per-package strategy uses), then run every configured publish plugin's own `prepare` step generically (whichever it defines -- @semantic-release/npm bumps `package.json`'s version, @semantic-release/changelog writes `CHANGELOG.md`). @semantic-release/git is rejected outright from this mode's plugin list (see `resolvePublishPlugins`'s `forbidGitPlugin`), since its own `prepare` step would create exactly the per-package commit this mode exists to avoid. The lockfile is regenerated once at the end, not once per bump, since `pnpm install --lockfile-only` recomputes it from whatever is on disk regardless of how many manifests changed.
+* 4. **Commit**: discover every file phase 3 touched via `git status` (rather than predicting filenames per plugin), make one commit, tag it once per released package (`name@version`, lightweight, matching semantic-release's own tag form), and push the commit and every tag together.
+* 5. **Publish**: for every released package, in topological order, call each configured plugin's own `publish` step directly (not through semantic-release's top-level orchestrator -- see the note below), then `success`.
+*
+* Why publish is not just another semantic-release() call: semantic-release's own `run()` unconditionally derives `lastRelease` from the newest tag already on the branch matching `tagFormat`, and this mode has, by the time phase 5 runs, already created and pushed that exact tag itself. A second real `semanticRelease()` call would see its own just-created tag as the already-published release and compute the wrong next version from it. Phase 5 instead calls each resolved plugin module's own exported `verifyConditions`/`publish`/`success` functions directly, with a hand-built context -- the same public per-plugin API surface semantic-release's own core calls internally, just invoked without going through the parts of `run()` that assume a not-yet-tagged repository.
 */
-function classifyDependencyRange(current) {
-	const range = current.trim();
-	if (range.startsWith(WORKSPACE_PROTOCOL)) {
-		const suffix = range.slice(10);
-		if (PUBLISH_RESOLVED_WORKSPACE_SUFFIXES.includes(suffix)) return { kind: "resolved-at-publish" };
-		const inner = classifyDependencyRange(suffix);
-		if (inner.kind !== "rewritable") throw new UnsupportedDependencyRangeError(`Cannot bump the workspace dependency range "${current}": only "workspace:*", "workspace:^", "workspace:~", and "workspace:" followed by a single concrete version range are supported.`);
-		return {
-			kind: "rewritable",
-			workspacePrefixed: true,
-			comparator: inner.comparator
-		};
+async function releaseWorkspaceSingleCommit(options) {
+	const root = resolve(options.root ?? process.cwd());
+	const log = options.log ?? console.log;
+	const dryRun = options.dryRun === true;
+	const env = sanitizeGitEnv(options.env ?? process.env);
+	const workspace = await discoverWorkspace(root);
+	const repoRoot = (await git(["rev-parse", "--show-toplevel"], { cwd: workspace.root })).trim();
+	await assertCleanWorkingTree({ cwd: repoRoot });
+	const graph = buildDependencyGraph(workspace.packages);
+	validateDependencyRangeShapes(graph);
+	const order = topologicalOrder(graph);
+	log(`${packageName}: ${order.length} packages in release order: ${order.join(" -> ")} (commitStrategy: single)`);
+	const resolvedPlugins = resolvePublishPlugins(options.plugins ?? SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS, workspace.root, {
+		requireGitPlugin: false,
+		forbidGitPlugin: true
+	});
+	const analyzeCommitsConfig = options.analyzeCommits ?? {};
+	const generateNotesConfig = options.generateNotes ?? {};
+	const capturedCommits = /* @__PURE__ */ new Map();
+	const captured = {
+		branch: void 0,
+		repositoryUrl: void 0
+	};
+	const pendingBumps = /* @__PURE__ */ new Map();
+	const outcomes = [];
+	const planned = [];
+	for (const name of order) {
+		const pkg = mustGet(graph.packages, name, "package");
+		const bumpsForThisPackage = pendingBumps.get(name) ?? [];
+		pendingBumps.delete(name);
+		const nextRelease = await analysePackage(pkg, {
+			resolvedPlugins,
+			analyzeCommitsConfig,
+			generateNotesConfig,
+			bumpsForThisPackage,
+			env,
+			branches: options.branches,
+			onCommitsResolved: (commits) => capturedCommits.set(name, commits),
+			onContextCaptured: (context) => {
+				captured.branch = context.branch;
+				captured.repositoryUrl = context.repositoryUrl;
+			}
+		});
+		outcomes.push({
+			name,
+			directory: pkg.directory,
+			released: nextRelease !== void 0,
+			version: nextRelease?.version,
+			gitTag: nextRelease?.gitTag,
+			type: nextRelease?.type,
+			dependencyBumps: bumpsForThisPackage
+		});
+		if (nextRelease === void 0) {
+			log(`${name}: no release`);
+			continue;
+		}
+		log(`${name}: would release ${nextRelease.gitTag}`);
+		planned.push({
+			pkg,
+			type: nextRelease.type,
+			version: nextRelease.version,
+			gitTag: nextRelease.gitTag,
+			notes: nextRelease.notes,
+			bumps: bumpsForThisPackage
+		});
+		for (const bump of planDependentBumps(pkg, nextRelease.version, graph)) {
+			const forDependent = pendingBumps.get(bump.dependent) ?? [];
+			forDependent.push(bump);
+			pendingBumps.set(bump.dependent, forDependent);
+		}
+	}
+	if (dryRun || planned.length === 0) return {
+		order,
+		packages: outcomes
+	};
+	const branch = captured.branch;
+	const repositoryUrl = captured.repositoryUrl;
+	if (branch === void 0 || repositoryUrl === void 0) throw new ReleaseConfigurationError(`Internal error: ${packageName} analysed ${planned.length} package release(s) but never captured a branch/repositoryUrl from semantic-release's own context. This should be impossible when at least one package releases.`);
+	const shared = {
+		env,
+		branch,
+		repositoryUrl,
+		log
+	};
+	const moduleCache = /* @__PURE__ */ new Map();
+	for (const release of planned) for (const [modulePath, pluginConfig] of resolvedPlugins) {
+		const plugin = await loadReleasePlugin(modulePath, moduleCache);
+		if (plugin.verifyConditions) await plugin.verifyConditions(pluginConfig, buildPluginContext(release, shared, capturedCommits, []));
+	}
+	let anyRangeRewritten = false;
+	for (const release of planned) {
+		for (const bump of release.bumps) {
+			if (bump.kind !== "rewritten") continue;
+			await writeDependencyRange(release.pkg.manifestPath, bump.field, bump.dependency, bump.range);
+			anyRangeRewritten = true;
+		}
+		for (const [modulePath, pluginConfig] of resolvedPlugins) {
+			const plugin = await loadReleasePlugin(modulePath, moduleCache);
+			if (plugin.prepare) await plugin.prepare(pluginConfig, buildPluginContext(release, shared, capturedCommits, []));
+		}
+	}
+	if (anyRangeRewritten) await regenerateLockfile({ cwd: workspace.root });
+	const touchedPaths = await workingTreeChanges({ cwd: repoRoot });
+	if (touchedPaths.length === 0) throw new ReleaseConfigurationError(`${packageName}: analysis planned ${planned.length} release(s), but no files changed while preparing them. Every configured publish plugin's own "prepare" step (bumping package.json, writing CHANGELOG.md) produced nothing to commit -- check the plugin list includes something that writes the version, e.g. @semantic-release/npm.`);
+	const identity = await resolveCommitIdentity({ cwd: repoRoot });
+	await commitFiles(touchedPaths, describeCombinedCommit(planned), {
+		cwd: repoRoot,
+		identity
+	});
+	const commitSha = (await git(["rev-parse", "HEAD"], { cwd: repoRoot })).trim();
+	const tagNames = planned.map((release) => release.gitTag);
+	for (const tagName of tagNames) await createTag(tagName, commitSha, { cwd: repoRoot });
+	await pushHeadAndTags(tagNames, { cwd: repoRoot });
+	log(`${packageName}: committed ${commitSha} and pushed ${tagNames.length} tag(s): ${tagNames.join(", ")}`);
+	for (const release of planned) {
+		const releases = [];
+		for (const [modulePath, pluginConfig] of resolvedPlugins) {
+			const plugin = await loadReleasePlugin(modulePath, moduleCache);
+			if (plugin.publish) {
+				const result = await plugin.publish(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+				if (result !== false && result !== void 0) releases.push(result);
+			}
+		}
+		for (const [modulePath, pluginConfig] of resolvedPlugins) {
+			const plugin = await loadReleasePlugin(modulePath, moduleCache);
+			if (plugin.success) await plugin.success(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+		}
+		log(`${release.pkg.name}: published ${release.gitTag}`);
 	}
-	if (range.startsWith(CATALOG_PROTOCOL)) throw new UnsupportedDependencyRangeError(`Cannot bump the workspace dependency range "${current}": the version of a "catalog:" dependency lives in pnpm-workspace.yaml, not in the package manifest, so bumping it here would leave the catalog entry stale. Depend on the sibling directly (for example "workspace:^") instead.`);
-	if (range.startsWith(NPM_ALIAS_PROTOCOL)) throw new UnsupportedDependencyRangeError(`Cannot bump the workspace dependency range "${current}": an "npm:" alias points at a differently-named package, so the version released in this workspace is not necessarily the version this range refers to.`);
-	if (WILDCARD_RANGES.includes(range)) return { kind: "wildcard" };
-	const match = REWRITABLE_COMPARATOR.exec(range);
-	if (match === null) throw new UnsupportedDependencyRangeError(`Cannot bump the workspace dependency range "${current}": only a single "^", "~", ">=", "=", or bare version comparator can be rewritten in place.`);
 	return {
-		kind: "rewritable",
-		workspacePrefixed: false,
-		comparator: match[1] ?? ""
+		order,
+		packages: outcomes
 	};
 }
 /**
-* Computes what a dependency range on a workspace sibling becomes once that sibling releases `version`, by classifying the range's shape and then, for a rewritable shape, substituting `version` in place of the version it currently names.
+* Runs one package's analysis with semantic-release's own real `dryRun: true` mode (which still fully computes `nextRelease.version`/`notes` and the branch/repository context; only the plugin steps whose own definition opts out of dry runs -- prepare, publish, addChannel, success, fail -- are skipped), using the exact same path-scoped `analyzeCommits`/`generateNotes` wrapper `commitStrategy: 'per-package'` uses. `dryRun: true` is forced here regardless of the caller's own `dryRun` option: this is always how phase 1 computes what *would* release, whether or not the run goes on to actually commit it.
 */
-function updateDependencyRange(current, version) {
-	const shape = classifyDependencyRange(current);
-	if (shape.kind !== "rewritable") return shape;
-	const rewritten = `${shape.comparator}${version}`;
+async function analysePackage(pkg, options) {
+	const scoped = createScopedPlugins({
+		pkg,
+		analyzeCommitsConfig: options.analyzeCommitsConfig,
+		generateNotesConfig: options.generateNotesConfig,
+		bumps: { bumpsFor: () => options.bumpsForThisPackage },
+		onCommitsResolved: options.onCommitsResolved
+	});
+	const semanticReleaseOptions = {
+		tagFormat: `${pkg.name}@\${version}`,
+		plugins: options.resolvedPlugins,
+		dryRun: true,
+		async analyzeCommits(pluginConfig, context) {
+			if (context.options.repositoryUrl === void 0) throw new ReleaseConfigurationError("Internal error: semantic-release did not resolve a repository URL before analyzeCommits ran.");
+			options.onContextCaptured({
+				branch: context.branch,
+				repositoryUrl: context.options.repositoryUrl
+			});
+			return scoped.analyzeCommits(pluginConfig, context);
+		},
+		generateNotes: scoped.generateNotes
+	};
+	if (options.branches !== void 0) semanticReleaseOptions.branches = options.branches;
+	const result = await semanticRelease(semanticReleaseOptions, {
+		cwd: pkg.directory,
+		env: { ...options.env }
+	});
+	if (result === false) return;
+	if (result.nextRelease.notes === void 0) throw new ReleaseConfigurationError(`Internal error: ${pkg.name} released with no notes computed.`);
 	return {
-		kind: "rewritten",
-		range: shape.workspacePrefixed ? `${WORKSPACE_PROTOCOL}${rewritten}` : rewritten
+		type: result.nextRelease.type,
+		version: result.nextRelease.version,
+		gitTag: result.nextRelease.gitTag,
+		notes: result.nextRelease.notes
 	};
 }
+/** Pure classification of what a released package's version does to each dependent's declared range -- the same logic `bumpDependents` in `release.ts` applies, minus the file write/commit/push: `commitStrategy: 'single'` defers every write to phase 3, applying the same classification once analysis has finished for the whole run. */
+function planDependentBumps(released, version, graph) {
+	const applied = [];
+	const dependents = graph.dependents.get(released.name);
+	if (dependents === void 0) return applied;
+	for (const edge of dependents) {
+		const update = updateDependencyRange(edge.range, version);
+		if (update.kind === "wildcard") continue;
+		applied.push({
+			dependent: edge.dependent,
+			dependency: released.name,
+			field: edge.field,
+			version,
+			range: update.kind === "rewritten" ? update.range : edge.range,
+			kind: update.kind
+		});
+	}
+	return applied;
+}
+function describeCombinedCommit(planned) {
+	return [
+		"chore(release): batch release [skip ci]",
+		"",
+		...planned.map((release) => {
+			const bumpDescriptions = release.bumps.map((bump) => `${bump.dependency} to ${bump.range}`);
+			const bumpSuffix = bumpDescriptions.length === 0 ? "" : ` (dependenc${bumpDescriptions.length === 1 ? "y" : "ies"} bumped: ${bumpDescriptions.join(", ")})`;
+			return `- ${release.gitTag} (${release.type})${bumpSuffix}`;
+		})
+	].join("\n");
+}
+function buildPluginContext(release, shared, capturedCommits, releases) {
+	const logger = {
+		log: (...args) => shared.log(`[${release.pkg.name}] ${args.map(String).join(" ")}`),
+		warn: (...args) => shared.log(`[${release.pkg.name}] warn: ${args.map(String).join(" ")}`),
+		error: (...args) => shared.log(`[${release.pkg.name}] error: ${args.map(String).join(" ")}`),
+		success: (...args) => shared.log(`[${release.pkg.name}] ${args.map(String).join(" ")}`)
+	};
+	return {
+		cwd: release.pkg.directory,
+		env: { ...shared.env },
+		stdout: process.stdout,
+		stderr: process.stderr,
+		logger,
+		options: { repositoryUrl: shared.repositoryUrl },
+		branch: shared.branch,
+		commits: capturedCommits.get(release.pkg.name) ?? [],
+		releases,
+		nextRelease: {
+			type: release.type,
+			version: release.version,
+			gitTag: release.gitTag,
+			name: release.gitTag,
+			notes: release.notes,
+			channel: channelOrNull(shared.branch.channel)
+		}
+	};
+}
+/** Matches semantic-release's own core exactly (`context.branch.channel || null` in its `index.js`): a branch's `channel` is `string | false | undefined`, and any falsy value (including `false` and an empty string) means "the default channel", represented here as `null`. Written as explicit comparisons rather than `||`/`??` so the falsy-to-null collapse (deliberately including `false` and `''`, which `??` alone would not fold) reads as intentional rather than as a fallback for `undefined`/`null` alone. */
+function channelOrNull(channel) {
+	return channel === void 0 || channel === false || channel === "" ? null : channel;
+}
+function isReleaseLifecycleFnOrUndefined(value) {
+	return value === void 0 || typeof value === "function";
+}
+function isReleasePluginModule(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if ("verifyConditions" in value && !isReleaseLifecycleFnOrUndefined(value.verifyConditions)) return false;
+	if ("prepare" in value && !isReleaseLifecycleFnOrUndefined(value.prepare)) return false;
+	if ("publish" in value && !isReleaseLifecycleFnOrUndefined(value.publish)) return false;
+	if ("success" in value && !isReleaseLifecycleFnOrUndefined(value.success)) return false;
+	return true;
+}
+/** Loads a publish plugin module directly (bypassing semantic-release's own step-pipeline machinery, since phase 5 cannot go through it -- see this file's own top-of-file note), caching by resolved path so a plugin shared by several packages is imported once per run rather than once per package per phase. */
+async function loadReleasePlugin(absolutePath, cache) {
+	const cached = cache.get(absolutePath);
+	if (cached !== void 0) return cached;
+	const loaded = await import(pathToFileURL(absolutePath).href);
+	if (!isReleasePluginModule(loaded)) throw new ReleaseConfigurationError(`The publish plugin resolved to ${absolutePath} does not export a recognised semantic-release plugin interface (verifyConditions/prepare/publish/success functions), so commitStrategy "single" cannot call its lifecycle steps directly.`);
+	cache.set(absolutePath, loaded);
+	return loaded;
+}
 //#endregion
 //#region src/release.ts
 /**
@@ -658,10 +1024,11 @@ function updateDependencyRange(current, version) {
 * For each package, in topological order: run semantic-release's programmatic API with `cwd` scoped to the package directory, a `name@version` tag format to keep each package's tags distinct in the one shared tag namespace, and inline `analyzeCommits`/`generateNotes` plugins that filter the release range's commits down to the package's own directory before delegating to the standard plugins. When a package releases, every workspace package that depends on it and has not run yet gets its dependency range rewritten in its manifest and committed immediately -- before its own turn, so its commit analysis and its published manifest both see the new range.
 */
 async function releaseWorkspace(options = {}) {
+	if ((options.commitStrategy ?? "per-package") === "single") return releaseWorkspaceSingleCommit(options);
 	const root = resolve(options.root ?? process.cwd());
 	const log = options.log ?? console.log;
 	const dryRun = options.dryRun === true;
-	const env = options.env ?? process.env;
+	const env = sanitizeGitEnv(options.env ?? process.env);
 	const workspace = await discoverWorkspace(root);
 	const graph = buildDependencyGraph(workspace.packages);
 	validateDependencyRangeShapes(graph);
@@ -720,12 +1087,6 @@ async function releaseWorkspace(options = {}) {
 		packages: outcomes
 	};
 }
-/**
-* Checks every workspace dependency edge's range shape before anything releases, so an `UnsupportedDependencyRangeError` stops the run before the first publish rather than after some sibling has already been published, tagged, committed, and pushed. The shape a range supports depends only on the range text itself (see `classifyDependencyRange`), never on which version a sibling ends up releasing, so this can run once up front for the whole graph instead of only being discovered edge by edge as each dependency happens to release.
-*/
-function validateDependencyRangeShapes(graph) {
-	for (const edges of graph.dependencies.values()) for (const edge of edges) classifyDependencyRange(edge.range);
-}
 async function runPackageRelease(pkg, options) {
 	const scoped = createScopedPlugins({
 		pkg,
@@ -794,11 +1155,6 @@ async function bumpDependents(released, version, graph, options) {
 	}
 	return applied;
 }
-function mustGet(map, key, what) {
-	const value = map.get(key);
-	if (value === void 0) throw new WorkspaceReleaseError(`Internal error: ${what} "${key}" disappeared from the dependency graph mid-run.`);
-	return value;
-}
 //#endregion
 //#region src/cli.ts
 const CONFIG_OPTION_KEYS = /* @__PURE__ */ new Set([
@@ -806,8 +1162,13 @@ const CONFIG_OPTION_KEYS = /* @__PURE__ */ new Set([
 	"branches",
 	"plugins",
 	"analyzeCommits",
-	"generateNotes"
+	"generateNotes",
+	"commitStrategy"
 ]);
+const COMMIT_STRATEGIES = /* @__PURE__ */ new Set(["per-package", "single"]);
+function isCommitStrategy(value) {
+	return COMMIT_STRATEGIES.has(value);
+}
 /**
 * Builds the commander program but never parses argv or exits the process itself in construction, so the command tree stays testable in isolation. `release` is the orchestration entry point: discover the workspace, order it topologically, and run semantic-release per package.
 */
@@ -823,16 +1184,22 @@ function createProgram() {
 	release.option("--plugin <spec>", "publish-pipeline plugin, repeatable: a module name, or a JSON array of [name, config]; defaults to the standard changelog/npm/github/git pipeline", collectRepeated, []);
 	release.option("--analyze-commits <json>", "options for the wrapped @semantic-release/commit-analyzer, as a JSON object");
 	release.option("--generate-notes <json>", "options for the wrapped @semantic-release/release-notes-generator, as a JSON object");
-	release.option("--config <file>", "config file (.json, .yaml, .yml, .js, .cjs, or .ts) providing any of the release options (dryRun, branches, plugins, analyzeCommits, generateNotes); explicit flags win");
+	release.option("--commit-strategy <mode>", "how the run commits its released changes: \"per-package\" (default; today's behaviour, one commit per release plus one per dependency bump) or \"single\" (one combined commit for the whole run, tagged once per released package)", parseCommitStrategy);
+	release.option("--config <file>", "config file (.json, .yaml, .yml, .js, .cjs, or .ts) providing any of the release options (dryRun, branches, plugins, analyzeCommits, generateNotes, commitStrategy); explicit flags win");
 	release.action(runRelease);
 	return program;
 }
+function parseCommitStrategy(value) {
+	if (!isCommitStrategy(value)) throw new InvalidArgumentError(`--commit-strategy must be one of: ${[...COMMIT_STRATEGIES].join(", ")}`);
+	return value;
+}
 const NO_CONFIG_FILE = {
 	dryRun: void 0,
 	branches: void 0,
 	plugins: void 0,
 	analyzeCommits: void 0,
-	generateNotes: void 0
+	generateNotes: void 0,
+	commitStrategy: void 0
 };
 async function runRelease(flags) {
 	const file = flags.config === void 0 ? NO_CONFIG_FILE : readReleaseConfigFile(flags.config);
@@ -840,9 +1207,10 @@ async function runRelease(flags) {
 		root: flags.root,
 		dryRun: flags.dryRun ?? (file.dryRun === true ? true : void 0),
 		branches: flags.branches.length > 0 ? flags.branches : file.branches,
-		plugins: flags.plugin.length > 0 ? flags.plugin.map((spec) => parsePluginSpec(spec)) : file.plugins ?? DEFAULT_PUBLISH_PLUGINS,
+		plugins: flags.plugin.length > 0 ? flags.plugin.map((spec) => parsePluginSpec(spec)) : file.plugins,
 		analyzeCommits: flags.analyzeCommits === void 0 ? file.analyzeCommits : parseJsonObjectFlag(flags.analyzeCommits, "--analyze-commits"),
-		generateNotes: flags.generateNotes === void 0 ? file.generateNotes : parseJsonObjectFlag(flags.generateNotes, "--generate-notes")
+		generateNotes: flags.generateNotes === void 0 ? file.generateNotes : parseJsonObjectFlag(flags.generateNotes, "--generate-notes"),
+		commitStrategy: flags.commitStrategy ?? file.commitStrategy
 	});
 	for (const pkg of outcome.packages) console.log(describeOutcome(pkg));
 }
@@ -888,18 +1256,20 @@ function readReleaseConfigFile(path) {
 	const parsed = readConfigFile(path);
 	if (!isJsonObject(parsed)) throw new InvalidArgumentError(`--config file ${path} must contain a JSON object`);
 	for (const key of Object.keys(parsed)) if (!CONFIG_OPTION_KEYS.has(key)) throw new InvalidArgumentError(`--config file ${path} has an unknown option "${key}"; recognised options: ${[...CONFIG_OPTION_KEYS].join(", ")}`);
-	const { dryRun, branches, plugins, analyzeCommits, generateNotes } = parsed;
+	const { dryRun, branches, plugins, analyzeCommits, generateNotes, commitStrategy } = parsed;
 	if (dryRun !== void 0 && typeof dryRun !== "boolean") throw new InvalidArgumentError(`--config file ${path}: "dryRun" must be a boolean`);
 	if (branches !== void 0 && !isStringArray(branches)) throw new InvalidArgumentError(`--config file ${path}: "branches" must be an array of branch name strings`);
 	if (plugins !== void 0 && !Array.isArray(plugins)) throw new InvalidArgumentError(`--config file ${path}: "plugins" must be an array`);
 	if (analyzeCommits !== void 0 && !isJsonObject(analyzeCommits)) throw new InvalidArgumentError(`--config file ${path}: "analyzeCommits" must be an object`);
 	if (generateNotes !== void 0 && !isJsonObject(generateNotes)) throw new InvalidArgumentError(`--config file ${path}: "generateNotes" must be an object`);
+	if (commitStrategy !== void 0 && (typeof commitStrategy !== "string" || !isCommitStrategy(commitStrategy))) throw new InvalidArgumentError(`--config file ${path}: "commitStrategy" must be one of: ${[...COMMIT_STRATEGIES].join(", ")}`);
 	return {
 		dryRun,
 		branches,
 		plugins: plugins === void 0 ? void 0 : plugins.map((spec) => parseConfigFilePlugin(spec, path)),
 		analyzeCommits,
-		generateNotes
+		generateNotes,
+		commitStrategy
 	};
 }
 function parseConfigFilePlugin(spec, path) {