@exadev/semantic-release-workspace 1.3.6 → 1.3.8

package/README.md

@@ -37,20 +37,22 @@ Why commit immediately, rather than the alternatives:
 
 Because every dependent sits downstream in topological order, its own run always sees the bump commit: the commit touches only the dependent's directory, so it passes that dependent's path filter and participates in its analysis.
 
-**A package whose only change is dependency bumps still gets a patch release — deliberately.** Whether the range was rewritten on disk (`^1.0.0` → `^1.1.0`) or is a `workspace:^`-style range that pnpm re-resolves at pack time, the dependent's *published* dependency range changes, so the dependent must be republished for the change to reach consumers. This is not left to chance: the wrapped `analyzeCommits` returns `patch` whenever the standard analyzer found nothing but this run bumped one of the package's dependency ranges, so the behaviour does not depend on how the workspace's own analyzer config happens to classify `chore(deps)` commits (many presets release nothing for `chore`). Release notes gain a `### Dependencies` section listing the bumps, so the release is self-explaining rather than empty.
+**A package whose only change is dependency bumps still gets a patch release — deliberately.** A range rewritten on disk (`^1.0.0` → `^1.1.0`) changes the dependent's *published* dependency range, so the dependent must be republished for the change to reach consumers. A range that names no version, such as a bare `workspace:^` in a private package, has nothing to rewrite, but the dependent still releases, so a package always follows a sibling it depends on. This is not left to chance: the wrapped `analyzeCommits` returns `patch` whenever the standard analyzer found nothing but this run bumped one of the package's dependency ranges, so the behaviour does not depend on how the workspace's own analyzer config happens to classify `chore(deps)` commits (many presets release nothing for `chore`). Release notes gain a `### Dependencies` section listing the bumps, so the release is self-explaining rather than empty.
 
 Dependency-range handling, in full:
 
 | Range in the dependent's manifest | What happens |
 | --- | --- |
-| `^1.0.0`, `~1.0.0`, `>=1.0.0`, `=1.0.0`, `1.0.0`, `workspace:^1.0.0` | Rewritten in place, preserving the comparator (`^1.0.0` → `^1.1.0`); `pnpm-lock.yaml` is regenerated to match, and both are committed and pushed together; dependent gets at least a patch release |
-| `workspace:*`, `workspace:^`, `workspace:~` | No manifest edit (pnpm resolves these at pack time), but the published range still changes, so the dependent still gets a patch release |
+| `^1.0.0`, `~1.0.0`, `>=1.0.0`, `=1.0.0`, `1.0.0` | Rewritten in place, preserving the comparator (`^1.0.0` → `^1.1.0`); `pnpm-lock.yaml` is regenerated to match, and both are committed and pushed together; dependent gets at least a patch release |
+| `workspace:^1.0.0` and the other anchored `workspace:` forms, in `devDependencies` or a private package | Rewritten in place with the `workspace:` prefix kept (`workspace:^1.0.0` → `workspace:^1.1.0`), committed and pushed as above; dependent gets at least a patch release |
+| `workspace:*`, `workspace:^`, `workspace:~`, in `devDependencies` or a private package | No manifest edit, since the range names no version; the dependent still gets a patch release |
+| Any `workspace:`, `catalog:`, `link:`, or `file:` specifier in the `dependencies`, `peerDependencies`, or `optionalDependencies` of a package that is not private, whichever package it names | The run stops with `UnsupportedDependencyRangeError`: `npm publish` ships the specifier unchanged, so the published package could not be installed |
 | `*`, `x`, `latest` | Nothing to update and the published range is unaffected — no bump, no forced release |
 | Compound ranges (`>=1.0.0 <2.0.0`), unions (`1.x \|\| 2.x`), `<`/`<=` bounds, `catalog:`, `npm:` aliases, git/tarball URLs | The run stops with `UnsupportedDependencyRangeError` — rewriting any of these wrongly, or leaving them silently stale, both produce a published manifest that disagrees with the repository, so neither is attempted |
 
-Every workspace dependency edge's range is validated against this table before the release loop starts, not just when the dependency it names happens to release: an unsupported range is a static property of the manifests, knowable at discovery time, so `UnsupportedDependencyRangeError` stops the run before the first package publishes, rather than after some upstream sibling has already been published, tagged, committed, and pushed.
+Every range above is validated before the release loop starts, not just when the dependency it names happens to release: both the shape of each workspace dependency edge and the specifiers in each publishable package's installed dependency fields are static properties of the manifests, knowable at discovery time, so `UnsupportedDependencyRangeError` stops the run before the first package publishes, rather than after some upstream sibling has already been published, tagged, committed, and pushed. Every offending entry is listed in one error. `resume` checks the manifests again before it publishes anything.
 
-For that reason concrete ranges (which the orchestrator maintains for you) are the recommended mode. Publishing `workspace:` ranges correctly additionally requires a pack step that substitutes them, as `pnpm publish` does.
+Publishing goes through `@semantic-release/npm`, which is plain `npm publish`: it ships a manifest's specifiers unchanged and never substitutes pnpm's protocols the way `pnpm publish` does. A publishable package therefore declares a concrete version range for each workspace sibling, which the orchestrator keeps up to date for you, and keeps `linkWorkspacePackages: true` in `pnpm-workspace.yaml` so pnpm still links the sibling locally instead of fetching it from the registry. `workspace:` ranges remain usable in private packages, which never publish, and in `devDependencies`, which no consumer installs.
 
 ## Commit strategies
 
@@ -149,7 +151,7 @@ The core technique is the same one multi-semantic-release proved in production:
 - **In-process delegation, not CLI wrapping.** semantic-release is invoked through its programmatic API with inline plugin functions, so the wrappers delegate to the real @semantic-release/commit-analyzer and @semantic-release/release-notes-generator running in the same process. (The analysed plugins are ESM named exports here, resolved as peers of this package — no plugin re-implementation anywhere.)
 - **Bump-only dependents always release.** multi-semantic-release rewrites dependency ranges in the working tree without committing them, so a dependent whose only change is a dependency update can go unreleased until some other commit triggers it. Here the bump is committed before the dependent's turn and a patch release is forced deterministically (see the timing section above).
 - **Loud failures by design.** A dependency cycle, an unsupported dependency range, a publish pipeline without @semantic-release/git (which would leave released manifests uncommitted), an unresolvable plugin, a duplicate package name — each stops the run with a specific error rather than degrading silently. There is deliberately no "skip this package and carry on" path: a partially-consistent set of publishes is worse than none.
-- **pnpm-native range semantics.** `workspace:*`/`workspace:^`/`workspace:~` are understood as publish-resolved (bump the release, not the manifest text); `catalog:` and `npm:` aliases are rejected with an explanation instead of being mangled.
+- **Only installable specifiers reach the registry.** `workspace:`, `catalog:`, `link:`, and `file:` specifiers in a publishable package's installed dependency fields are rejected instead of being published as written. In private packages and `devDependencies`, `workspace:*`/`workspace:^`/`workspace:~` are understood as naming no version (bump the release, not the manifest text), and `catalog:` and `npm:` aliases on a workspace sibling are rejected with an explanation instead of being mangled.
 - **Workspace-agnostic discovery.** Everything comes from `pnpm-workspace.yaml` and the manifests its globs match; pointing the orchestrator at any pnpm workspace is the entire configuration.
 
 Out of scope, on purpose: parallelising independent branches of the dependency graph (packages release sequentially in topological order for correctness first — a real future optimisation, not attempted here), and any Changesets-style explicit-changeset mode, which is a different paradigm rather than a missing feature.

package/dist/cli.js

@@ -14,7 +14,7 @@ import { generateNotes } from "@semantic-release/release-notes-generator";
 import semanticRelease from "semantic-release";
 import { pathToFileURL } from "node:url";
 //#region package.json
-var version = "1.3.6";
+var version = "1.3.8";
 //#endregion
 //#region src/errors.ts
 /**
@@ -39,7 +39,7 @@ var DependencyCycleError = class extends WorkspaceReleaseError {
 		this.cycle = cycle;
 	}
 };
-/** A dependency on a workspace sibling uses a range this tool cannot rewrite with confidence. Rewriting it wrongly, or leaving it silently stale, both produce a published manifest that disagrees with the repository, so the run stops instead. */
+/** A dependency range this tool cannot release correctly: either a range on a workspace sibling that it cannot rewrite with confidence (rewriting it wrongly, or leaving it silently stale, produces a published manifest that disagrees with the repository), or a `workspace:`, `catalog:`, `link:`, or `file:` specifier in a publishable package's published dependencies, which `npm publish` ships verbatim and no consumer can install. The run stops instead. */
 var UnsupportedDependencyRangeError = class extends WorkspaceReleaseError {};
 /** The semantic-release options handed to the orchestrator cannot be scoped to a single package -- typically a publish plugin list that would leave a release commit or a cross-package manifest bump uncommitted. */
 var ReleaseConfigurationError = class extends WorkspaceReleaseError {};
@@ -308,6 +308,12 @@ const DEPENDENCY_FIELDS = [
 	"peerDependencies",
 	"optionalDependencies"
 ];
+/** The fields whose entries a consumer's package manager resolves when it installs the published package. `devDependencies` is absent: it is published, but nothing ever installs it for a consumer. */
+const INSTALLED_DEPENDENCY_FIELDS = [
+	"dependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
 async function readManifest(path) {
 	const text = await readFile(path, "utf8");
 	const parsed = JSON.parse(text);
@@ -327,6 +333,7 @@ async function readManifest(path) {
 	return {
 		name,
 		version,
+		private: parsed.private === true,
 		dependencies
 	};
 }
@@ -349,7 +356,14 @@ async function writeDependencyRange(path, field, dependency, range) {
 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. */
+/** Specifier protocols that only a workspace-aware package manager resolves locally. `npm publish` copies them into the registry as written, so a published package declaring one in an installed dependency field cannot be installed. */
+const UNPUBLISHABLE_SPECIFIER_PROTOCOLS = [
+	WORKSPACE_PROTOCOL,
+	CATALOG_PROTOCOL,
+	"link:",
+	"file:"
+];
+/** The `workspace:` suffixes that name no version, and so leave nothing in the manifest to rewrite. */
 const PUBLISH_RESOLVED_WORKSPACE_SUFFIXES = [
 	"*",
 	"^",
@@ -364,6 +378,13 @@ const WILDCARD_RANGES = [
 	"latest"
 ];
 /**
+* The protocol of a specifier that `npm publish` would ship verbatim while no consumer's package manager can resolve it (`workspace:`, `catalog:`, `link:`, `file:`), or `undefined` for a specifier a consumer can install.
+*/
+function unpublishableSpecifierProtocol(specifier) {
+	const trimmed = specifier.trim();
+	return UNPUBLISHABLE_SPECIFIER_PROTOCOLS.find((protocol) => trimmed.startsWith(protocol));
+}
+/**
 * 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.-]+)?)$/;
@@ -385,7 +406,7 @@ function classifyDependencyRange(current) {
 			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(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. Declare the sibling's version range directly (for example "^1.0.0") 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);
@@ -409,6 +430,27 @@ function updateDependencyRange(current, version) {
 	};
 }
 //#endregion
+//#region src/publishable-dependencies.ts
+/**
+* Throws `UnsupportedDependencyRangeError` unless every publishable package's installed dependencies (`dependencies`, `peerDependencies`, `optionalDependencies`) are ranges a consumer's package manager can resolve.
+*
+* Publishing goes through `@semantic-release/npm`, that is plain `npm publish`, which copies the manifest's specifiers into the registry unchanged. A `workspace:`, `catalog:`, `link:`, or `file:` specifier therefore reaches consumers as written and makes the package uninstallable, whichever sibling or external package it names and whether or not the tool would have rewritten it. `pnpm publish` would substitute some of them at pack time, but this tool never packs with pnpm, so accepting them would mean publishing a broken package with no warning.
+*
+* A `private` package never publishes and is exempt, and so is `devDependencies`, which no consumer installs. Every offending entry across every package is reported in one error, so a workspace with several of them is fixed in one pass rather than one failed run per entry.
+*/
+function assertPublishableDependencies(packages) {
+	const offences = [];
+	for (const pkg of packages) {
+		if (pkg.private) continue;
+		for (const field of INSTALLED_DEPENDENCY_FIELDS) {
+			const declared = pkg.dependencies.get(field);
+			if (declared === void 0) continue;
+			for (const [dependency, specifier] of declared) if (unpublishableSpecifierProtocol(specifier) !== void 0) offences.push(`  ${pkg.name}: "${dependency}" in ${field} is declared as "${specifier}"`);
+		}
+	}
+	if (offences.length > 0) throw new UnsupportedDependencyRangeError(`Refusing to release: npm publish ships these dependency specifiers unchanged, so the published package could not be installed.\n${offences.join("\n")}\nDeclare a plain version range instead (for example "^1.2.3"). For a sibling in this workspace, keep "linkWorkspacePackages: true" in pnpm-workspace.yaml so pnpm still links it locally; this tool rewrites the range whenever the sibling releases. Packages marked "private" are never published and are exempt.`);
+}
+//#endregion
 //#region src/workspace.ts
 /** The one filename pnpm recognises as a workspace definition. */
 const WORKSPACE_MANIFEST = "pnpm-workspace.yaml";
@@ -445,6 +487,7 @@ async function discoverWorkspace(root) {
 		packages.push({
 			name: manifest.name,
 			version: manifest.version,
+			private: manifest.private,
 			directory,
 			relativeDirectory,
 			repoRelativeDirectory,
@@ -564,11 +607,15 @@ function firstUnplacedDependency(name, graph, unplaced) {
 	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.
+* Validates every dependency range in the workspace before anything releases, so a run stops before the first publish rather than after some sibling has already been published, tagged, committed, and pushed. Two independent checks, both static properties of the manifests:
+*
+* - Every publishable package's installed dependencies must be specifiers a consumer can install (see `assertPublishableDependencies`), whichever package they name.
+* - Every workspace dependency edge's range must have a shape this tool can maintain (see `classifyDependencyRange`, which depends only on the range text and never on which version a sibling ends up releasing).
 *
-* 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.
+* Both throw `UnsupportedDependencyRangeError`. Shared by every release path (`release.ts`'s per-package loop, `single-commit-release.ts`'s analysis phase, and `gate-publish.ts`'s detach), which is why it lives alongside the graph it validates rather than inside any one of them.
 */
-function validateDependencyRangeShapes(graph) {
+function validateDependencyRanges(graph) {
+	assertPublishableDependencies([...graph.packages.values()]);
 	for (const edges of graph.dependencies.values()) for (const edge of edges) classifyDependencyRange(edge.range);
 }
 /**
@@ -785,7 +832,7 @@ async function regenerateLockfile(options) {
 * 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.
+* 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 `validateDependencyRanges` 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`.
@@ -801,7 +848,7 @@ async function releaseWorkspaceSingleCommit(options) {
 	const repoRoot = (await git(["rev-parse", "--show-toplevel"], { cwd: workspace.root })).trim();
 	await assertCleanWorkingTree({ cwd: repoRoot });
 	const graph = buildDependencyGraph(workspace.packages);
-	validateDependencyRangeShapes(graph);
+	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")} (commitStrategy: single)`);
 	const resolvedPlugins = resolvePublishPlugins(options.plugins ?? SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS, workspace.root, {
@@ -1080,7 +1127,7 @@ async function releaseWorkspace(options = {}) {
 	const env = sanitizeGitEnv(options.env ?? process.env);
 	const workspace = await discoverWorkspace(root);
 	const graph = buildDependencyGraph(workspace.packages);
-	validateDependencyRangeShapes(graph);
+	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")}`);
 	const publishPlugins = resolvePublishPlugins(options.plugins ?? DEFAULT_PUBLISH_PLUGINS, workspace.root, { requireGitPlugin: !dryRun });
@@ -1243,7 +1290,7 @@ async function detachWorkspaceRelease(options) {
 	const env = sanitizeGitEnv(options.env ?? process.env);
 	const workspace = await discoverWorkspace(root);
 	const graph = buildDependencyGraph(workspace.packages);
-	validateDependencyRangeShapes(graph);
+	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order (gated -- tag only, publish deferred): ${order.join(" -> ")}`);
 	const publishPlugins = resolvePublishPlugins(options.plugins ?? DEFAULT_PUBLISH_PLUGINS, workspace.root, { requireGitPlugin: !dryRun });
@@ -1332,6 +1379,7 @@ async function resumeWorkspaceRelease(options) {
 	const root = resolve(options.root ?? process.cwd());
 	const log = options.log ?? console.log;
 	const env = sanitizeGitEnv(options.env ?? process.env);
+	assertPublishableDependencies(await Promise.all(options.detached.filter((entry) => entry.state !== null).map(async (entry) => readManifest(resolve(root, entry.relativeDirectory, "package.json")))));
 	const order = [];
 	const packages = [];
 	for (const entry of options.detached) {

package/dist/index.cjs

@@ -61,7 +61,7 @@ var DependencyCycleError = class extends WorkspaceReleaseError {
 		this.cycle = cycle;
 	}
 };
-/** A dependency on a workspace sibling uses a range this tool cannot rewrite with confidence. Rewriting it wrongly, or leaving it silently stale, both produce a published manifest that disagrees with the repository, so the run stops instead. */
+/** A dependency range this tool cannot release correctly: either a range on a workspace sibling that it cannot rewrite with confidence (rewriting it wrongly, or leaving it silently stale, produces a published manifest that disagrees with the repository), or a `workspace:`, `catalog:`, `link:`, or `file:` specifier in a publishable package's published dependencies, which `npm publish` ships verbatim and no consumer can install. The run stops instead. */
 var UnsupportedDependencyRangeError = class extends WorkspaceReleaseError {};
 /** The semantic-release options handed to the orchestrator cannot be scoped to a single package -- typically a publish plugin list that would leave a release commit or a cross-package manifest bump uncommitted. */
 var ReleaseConfigurationError = class extends WorkspaceReleaseError {};
@@ -324,6 +324,12 @@ const DEPENDENCY_FIELDS = [
 	"peerDependencies",
 	"optionalDependencies"
 ];
+/** The fields whose entries a consumer's package manager resolves when it installs the published package. `devDependencies` is absent: it is published, but nothing ever installs it for a consumer. */
+const INSTALLED_DEPENDENCY_FIELDS = [
+	"dependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
 async function readManifest(path) {
 	const text = await (0, node_fs_promises.readFile)(path, "utf8");
 	const parsed = JSON.parse(text);
@@ -343,6 +349,7 @@ async function readManifest(path) {
 	return {
 		name,
 		version,
+		private: parsed.private === true,
 		dependencies
 	};
 }
@@ -397,6 +404,7 @@ async function discoverWorkspace(root) {
 		packages.push({
 			name: manifest.name,
 			version: manifest.version,
+			private: manifest.private,
 			directory,
 			relativeDirectory,
 			repoRelativeDirectory,
@@ -445,7 +453,14 @@ function toPosix(path) {
 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. */
+/** Specifier protocols that only a workspace-aware package manager resolves locally. `npm publish` copies them into the registry as written, so a published package declaring one in an installed dependency field cannot be installed. */
+const UNPUBLISHABLE_SPECIFIER_PROTOCOLS = [
+	WORKSPACE_PROTOCOL,
+	CATALOG_PROTOCOL,
+	"link:",
+	"file:"
+];
+/** The `workspace:` suffixes that name no version, and so leave nothing in the manifest to rewrite. */
 const PUBLISH_RESOLVED_WORKSPACE_SUFFIXES = [
 	"*",
 	"^",
@@ -460,6 +475,13 @@ const WILDCARD_RANGES = [
 	"latest"
 ];
 /**
+* The protocol of a specifier that `npm publish` would ship verbatim while no consumer's package manager can resolve it (`workspace:`, `catalog:`, `link:`, `file:`), or `undefined` for a specifier a consumer can install.
+*/
+function unpublishableSpecifierProtocol(specifier) {
+	const trimmed = specifier.trim();
+	return UNPUBLISHABLE_SPECIFIER_PROTOCOLS.find((protocol) => trimmed.startsWith(protocol));
+}
+/**
 * 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.-]+)?)$/;
@@ -481,7 +503,7 @@ function classifyDependencyRange(current) {
 			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(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. Declare the sibling's version range directly (for example "^1.0.0") 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);
@@ -505,6 +527,27 @@ function updateDependencyRange(current, version) {
 	};
 }
 //#endregion
+//#region src/publishable-dependencies.ts
+/**
+* Throws `UnsupportedDependencyRangeError` unless every publishable package's installed dependencies (`dependencies`, `peerDependencies`, `optionalDependencies`) are ranges a consumer's package manager can resolve.
+*
+* Publishing goes through `@semantic-release/npm`, that is plain `npm publish`, which copies the manifest's specifiers into the registry unchanged. A `workspace:`, `catalog:`, `link:`, or `file:` specifier therefore reaches consumers as written and makes the package uninstallable, whichever sibling or external package it names and whether or not the tool would have rewritten it. `pnpm publish` would substitute some of them at pack time, but this tool never packs with pnpm, so accepting them would mean publishing a broken package with no warning.
+*
+* A `private` package never publishes and is exempt, and so is `devDependencies`, which no consumer installs. Every offending entry across every package is reported in one error, so a workspace with several of them is fixed in one pass rather than one failed run per entry.
+*/
+function assertPublishableDependencies(packages) {
+	const offences = [];
+	for (const pkg of packages) {
+		if (pkg.private) continue;
+		for (const field of INSTALLED_DEPENDENCY_FIELDS) {
+			const declared = pkg.dependencies.get(field);
+			if (declared === void 0) continue;
+			for (const [dependency, specifier] of declared) if (unpublishableSpecifierProtocol(specifier) !== void 0) offences.push(`  ${pkg.name}: "${dependency}" in ${field} is declared as "${specifier}"`);
+		}
+	}
+	if (offences.length > 0) throw new UnsupportedDependencyRangeError(`Refusing to release: npm publish ships these dependency specifiers unchanged, so the published package could not be installed.\n${offences.join("\n")}\nDeclare a plain version range instead (for example "^1.2.3"). For a sibling in this workspace, keep "linkWorkspacePackages: true" in pnpm-workspace.yaml so pnpm still links it locally; this tool rewrites the range whenever the sibling releases. Packages marked "private" are never published and are exempt.`);
+}
+//#endregion
 //#region src/graph.ts
 /**
 * Builds the inter-package dependency graph from the manifests alone.
@@ -580,11 +623,15 @@ function firstUnplacedDependency(name, graph, unplaced) {
 	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.
+* Validates every dependency range in the workspace before anything releases, so a run stops before the first publish rather than after some sibling has already been published, tagged, committed, and pushed. Two independent checks, both static properties of the manifests:
+*
+* - Every publishable package's installed dependencies must be specifiers a consumer can install (see `assertPublishableDependencies`), whichever package they name.
+* - Every workspace dependency edge's range must have a shape this tool can maintain (see `classifyDependencyRange`, which depends only on the range text and never on which version a sibling ends up releasing).
 *
-* 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.
+* Both throw `UnsupportedDependencyRangeError`. Shared by every release path (`release.ts`'s per-package loop, `single-commit-release.ts`'s analysis phase, and `gate-publish.ts`'s detach), which is why it lives alongside the graph it validates rather than inside any one of them.
 */
-function validateDependencyRangeShapes(graph) {
+function validateDependencyRanges(graph) {
+	assertPublishableDependencies([...graph.packages.values()]);
 	for (const edges of graph.dependencies.values()) for (const edge of edges) classifyDependencyRange(edge.range);
 }
 /**
@@ -798,7 +845,7 @@ async function regenerateLockfile(options) {
 * 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.
+* 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 `validateDependencyRanges` 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`.
@@ -814,7 +861,7 @@ async function releaseWorkspaceSingleCommit(options) {
 	const repoRoot = (await git(["rev-parse", "--show-toplevel"], { cwd: workspace.root })).trim();
 	await assertCleanWorkingTree({ cwd: repoRoot });
 	const graph = buildDependencyGraph(workspace.packages);
-	validateDependencyRangeShapes(graph);
+	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")} (commitStrategy: single)`);
 	const resolvedPlugins = resolvePublishPlugins(options.plugins ?? SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS, workspace.root, {
@@ -1086,7 +1133,7 @@ async function detachWorkspaceRelease(options) {
 	const env = sanitizeGitEnv(options.env ?? process.env);
 	const workspace = await discoverWorkspace(root);
 	const graph = buildDependencyGraph(workspace.packages);
-	validateDependencyRangeShapes(graph);
+	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order (gated -- tag only, publish deferred): ${order.join(" -> ")}`);
 	const publishPlugins = resolvePublishPlugins(options.plugins ?? DEFAULT_PUBLISH_PLUGINS, workspace.root, { requireGitPlugin: !dryRun });
@@ -1163,6 +1210,7 @@ async function resumeWorkspaceRelease(options) {
 	const root = (0, node_path.resolve)(options.root ?? process.cwd());
 	const log = options.log ?? console.log;
 	const env = sanitizeGitEnv(options.env ?? process.env);
+	assertPublishableDependencies(await Promise.all(options.detached.filter((entry) => entry.state !== null).map(async (entry) => readManifest((0, node_path.resolve)(root, entry.relativeDirectory, "package.json")))));
 	const order = [];
 	const packages = [];
 	for (const entry of options.detached) {
@@ -1223,7 +1271,7 @@ async function releaseWorkspace(options = {}) {
 	const env = sanitizeGitEnv(options.env ?? process.env);
 	const workspace = await discoverWorkspace(root);
 	const graph = buildDependencyGraph(workspace.packages);
-	validateDependencyRangeShapes(graph);
+	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")}`);
 	const publishPlugins = resolvePublishPlugins(options.plugins ?? DEFAULT_PUBLISH_PLUGINS, workspace.root, { requireGitPlugin: !dryRun });

package/dist/index.d.cts

@@ -7,12 +7,14 @@ export declare const packageName = "@exadev/semantic-release-workspace";
 /**
  * The manifest fields that can name a workspace sibling.
  *
- * All four contribute edges to the release order: whatever field a dependency sits in, the sibling has to have released before the dependent's manifest can name its new version. All four also contribute to the decision to release a dependent (see `releaseWorkspace`), because pnpm rewrites `workspace:` ranges in every one of them at pack time -- a `devDependencies` entry is part of the published artifact even though consumers never install it.
+ * All four contribute edges to the release order: whatever field a dependency sits in, the sibling has to have released before the dependent's manifest can name its new version. All four also contribute to the decision to release a dependent (see `releaseWorkspace`).
  */
 type DependencyField = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
 interface PackageManifest {
   readonly name: string;
   readonly version: string;
+  /** Whether the manifest sets `private` to the boolean `true`, the one value `@semantic-release/npm` treats as "never publish this package". */
+  readonly private: boolean;
   /** Only the fields actually present in the file, each mapping dependency name to its declared range. */
   readonly dependencies: ReadonlyMap<DependencyField, ReadonlyMap<string, string>>;
 }
@@ -28,6 +30,8 @@ export declare function writeDependencyRange(path: string, field: DependencyFiel
 interface WorkspacePackage {
   readonly name: string;
   readonly version: string;
+  /** Whether the package is marked `private`, which means it is never published to npm. */
+  readonly private: boolean;
   /** Absolute path to the package directory. */
   readonly directory: string;
   /** Path relative to the workspace root, always POSIX-separated. Used for filesystem and git-pathspec purposes scoped to the workspace itself (for example `git add` run with the workspace root as `cwd`) -- never for matching against `git log` output, which `git` always reports relative to the repository's toplevel, not to whatever `cwd` a command happened to run from. Compare `repoRelativeDirectory` for that. */
@@ -87,7 +91,7 @@ export declare function topologicalOrder(graph: DependencyGraph): readonly strin
 /**
  * What happens to one dependency range when the sibling it points at releases a new version.
  *
- * The distinction between `rewritten` and `resolved-at-publish` matters for the manifest, not for the release decision: both mean the dependent's *published* dependency range changes, and therefore that the dependent needs a release of its own for that change to reach consumers. Only `wildcard` leaves the published artifact genuinely identical.
+ * The distinction between `rewritten` and `resolved-at-publish` matters for the manifest, not for the release decision: both make the dependent release in its own right, so it always follows a sibling it depends on. Only `wildcard` leaves the dependent entirely unaffected.
  */
 type DependencyRangeUpdate =
 /** The range names a concrete version that has to be rewritten in the manifest. */
@@ -95,7 +99,7 @@ type DependencyRangeUpdate =
   readonly kind: 'rewritten';
   readonly range: string;
 } |
-/** A bare `workspace:*`, `workspace:^`, or `workspace:~` range: pnpm substitutes the sibling's current version at pack time, so the manifest on disk needs no edit even though the published range does change. */
+/** A bare `workspace:*`, `workspace:^`, or `workspace:~` range: it names no version, so the manifest on disk needs no edit. Only a private package or a `devDependencies` entry can carry one and still be released (see `assertPublishableDependencies`), because `npm publish` ships the specifier unchanged. */
 {
   readonly kind: 'resolved-at-publish';
 } |
@@ -128,7 +132,7 @@ export declare function updateDependencyRange(current: string, version: string):
 //#endregion
 //#region src/plugins.d.ts
 /**
- * One workspace dependency range that changed because its package released a new version during this run. `rewritten` means the dependent's manifest was edited on disk; `resolved-at-publish` means a `workspace:^`-style range whose on-disk text is unchanged but whose published value pnpm re-resolves at pack time. Both change the dependent's published artifact, which is why both count towards its release.
+ * One workspace dependency range that changed because its package released a new version during this run. `rewritten` means the dependent's manifest was edited on disk; `resolved-at-publish` means a bare `workspace:^`-style range whose on-disk text is unchanged. Both count towards the dependent's release.
  */
 interface DependencyBump {
   readonly dependency: string;
@@ -294,7 +298,7 @@ export declare class DependencyCycleError extends WorkspaceReleaseError {
   readonly cycle: readonly string[];
   constructor(cycle: readonly string[]);
 }
-/** A dependency on a workspace sibling uses a range this tool cannot rewrite with confidence. Rewriting it wrongly, or leaving it silently stale, both produce a published manifest that disagrees with the repository, so the run stops instead. */
+/** A dependency range this tool cannot release correctly: either a range on a workspace sibling that it cannot rewrite with confidence (rewriting it wrongly, or leaving it silently stale, produces a published manifest that disagrees with the repository), or a `workspace:`, `catalog:`, `link:`, or `file:` specifier in a publishable package's published dependencies, which `npm publish` ships verbatim and no consumer can install. The run stops instead. */
 export declare class UnsupportedDependencyRangeError extends WorkspaceReleaseError {}
 /** The semantic-release options handed to the orchestrator cannot be scoped to a single package -- typically a publish plugin list that would leave a release commit or a cross-package manifest bump uncommitted. */
 export declare class ReleaseConfigurationError extends WorkspaceReleaseError {}

package/dist/index.d.ts

@@ -7,12 +7,14 @@ export declare const packageName = "@exadev/semantic-release-workspace";
 /**
  * The manifest fields that can name a workspace sibling.
  *
- * All four contribute edges to the release order: whatever field a dependency sits in, the sibling has to have released before the dependent's manifest can name its new version. All four also contribute to the decision to release a dependent (see `releaseWorkspace`), because pnpm rewrites `workspace:` ranges in every one of them at pack time -- a `devDependencies` entry is part of the published artifact even though consumers never install it.
+ * All four contribute edges to the release order: whatever field a dependency sits in, the sibling has to have released before the dependent's manifest can name its new version. All four also contribute to the decision to release a dependent (see `releaseWorkspace`).
  */
 type DependencyField = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
 interface PackageManifest {
   readonly name: string;
   readonly version: string;
+  /** Whether the manifest sets `private` to the boolean `true`, the one value `@semantic-release/npm` treats as "never publish this package". */
+  readonly private: boolean;
   /** Only the fields actually present in the file, each mapping dependency name to its declared range. */
   readonly dependencies: ReadonlyMap<DependencyField, ReadonlyMap<string, string>>;
 }
@@ -28,6 +30,8 @@ export declare function writeDependencyRange(path: string, field: DependencyFiel
 interface WorkspacePackage {
   readonly name: string;
   readonly version: string;
+  /** Whether the package is marked `private`, which means it is never published to npm. */
+  readonly private: boolean;
   /** Absolute path to the package directory. */
   readonly directory: string;
   /** Path relative to the workspace root, always POSIX-separated. Used for filesystem and git-pathspec purposes scoped to the workspace itself (for example `git add` run with the workspace root as `cwd`) -- never for matching against `git log` output, which `git` always reports relative to the repository's toplevel, not to whatever `cwd` a command happened to run from. Compare `repoRelativeDirectory` for that. */
@@ -87,7 +91,7 @@ export declare function topologicalOrder(graph: DependencyGraph): readonly strin
 /**
  * What happens to one dependency range when the sibling it points at releases a new version.
  *
- * The distinction between `rewritten` and `resolved-at-publish` matters for the manifest, not for the release decision: both mean the dependent's *published* dependency range changes, and therefore that the dependent needs a release of its own for that change to reach consumers. Only `wildcard` leaves the published artifact genuinely identical.
+ * The distinction between `rewritten` and `resolved-at-publish` matters for the manifest, not for the release decision: both make the dependent release in its own right, so it always follows a sibling it depends on. Only `wildcard` leaves the dependent entirely unaffected.
  */
 type DependencyRangeUpdate =
 /** The range names a concrete version that has to be rewritten in the manifest. */
@@ -95,7 +99,7 @@ type DependencyRangeUpdate =
   readonly kind: 'rewritten';
   readonly range: string;
 } |
-/** A bare `workspace:*`, `workspace:^`, or `workspace:~` range: pnpm substitutes the sibling's current version at pack time, so the manifest on disk needs no edit even though the published range does change. */
+/** A bare `workspace:*`, `workspace:^`, or `workspace:~` range: it names no version, so the manifest on disk needs no edit. Only a private package or a `devDependencies` entry can carry one and still be released (see `assertPublishableDependencies`), because `npm publish` ships the specifier unchanged. */
 {
   readonly kind: 'resolved-at-publish';
 } |
@@ -128,7 +132,7 @@ export declare function updateDependencyRange(current: string, version: string):
 //#endregion
 //#region src/plugins.d.ts
 /**
- * One workspace dependency range that changed because its package released a new version during this run. `rewritten` means the dependent's manifest was edited on disk; `resolved-at-publish` means a `workspace:^`-style range whose on-disk text is unchanged but whose published value pnpm re-resolves at pack time. Both change the dependent's published artifact, which is why both count towards its release.
+ * One workspace dependency range that changed because its package released a new version during this run. `rewritten` means the dependent's manifest was edited on disk; `resolved-at-publish` means a bare `workspace:^`-style range whose on-disk text is unchanged. Both count towards the dependent's release.
  */
 interface DependencyBump {
   readonly dependency: string;
@@ -294,7 +298,7 @@ export declare class DependencyCycleError extends WorkspaceReleaseError {
   readonly cycle: readonly string[];
   constructor(cycle: readonly string[]);
 }
-/** A dependency on a workspace sibling uses a range this tool cannot rewrite with confidence. Rewriting it wrongly, or leaving it silently stale, both produce a published manifest that disagrees with the repository, so the run stops instead. */
+/** A dependency range this tool cannot release correctly: either a range on a workspace sibling that it cannot rewrite with confidence (rewriting it wrongly, or leaving it silently stale, produces a published manifest that disagrees with the repository), or a `workspace:`, `catalog:`, `link:`, or `file:` specifier in a publishable package's published dependencies, which `npm publish` ships verbatim and no consumer can install. The run stops instead. */
 export declare class UnsupportedDependencyRangeError extends WorkspaceReleaseError {}
 /** The semantic-release options handed to the orchestrator cannot be scoped to a single package -- typically a publish plugin list that would leave a release commit or a cross-package manifest bump uncommitted. */
 export declare class ReleaseConfigurationError extends WorkspaceReleaseError {}

package/dist/index.js

@@ -36,7 +36,7 @@ var DependencyCycleError = class extends WorkspaceReleaseError {
 		this.cycle = cycle;
 	}
 };
-/** A dependency on a workspace sibling uses a range this tool cannot rewrite with confidence. Rewriting it wrongly, or leaving it silently stale, both produce a published manifest that disagrees with the repository, so the run stops instead. */
+/** A dependency range this tool cannot release correctly: either a range on a workspace sibling that it cannot rewrite with confidence (rewriting it wrongly, or leaving it silently stale, produces a published manifest that disagrees with the repository), or a `workspace:`, `catalog:`, `link:`, or `file:` specifier in a publishable package's published dependencies, which `npm publish` ships verbatim and no consumer can install. The run stops instead. */
 var UnsupportedDependencyRangeError = class extends WorkspaceReleaseError {};
 /** The semantic-release options handed to the orchestrator cannot be scoped to a single package -- typically a publish plugin list that would leave a release commit or a cross-package manifest bump uncommitted. */
 var ReleaseConfigurationError = class extends WorkspaceReleaseError {};
@@ -299,6 +299,12 @@ const DEPENDENCY_FIELDS = [
 	"peerDependencies",
 	"optionalDependencies"
 ];
+/** The fields whose entries a consumer's package manager resolves when it installs the published package. `devDependencies` is absent: it is published, but nothing ever installs it for a consumer. */
+const INSTALLED_DEPENDENCY_FIELDS = [
+	"dependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
 async function readManifest(path) {
 	const text = await readFile(path, "utf8");
 	const parsed = JSON.parse(text);
@@ -318,6 +324,7 @@ async function readManifest(path) {
 	return {
 		name,
 		version,
+		private: parsed.private === true,
 		dependencies
 	};
 }
@@ -372,6 +379,7 @@ async function discoverWorkspace(root) {
 		packages.push({
 			name: manifest.name,
 			version: manifest.version,
+			private: manifest.private,
 			directory,
 			relativeDirectory,
 			repoRelativeDirectory,
@@ -420,7 +428,14 @@ function toPosix(path) {
 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. */
+/** Specifier protocols that only a workspace-aware package manager resolves locally. `npm publish` copies them into the registry as written, so a published package declaring one in an installed dependency field cannot be installed. */
+const UNPUBLISHABLE_SPECIFIER_PROTOCOLS = [
+	WORKSPACE_PROTOCOL,
+	CATALOG_PROTOCOL,
+	"link:",
+	"file:"
+];
+/** The `workspace:` suffixes that name no version, and so leave nothing in the manifest to rewrite. */
 const PUBLISH_RESOLVED_WORKSPACE_SUFFIXES = [
 	"*",
 	"^",
@@ -435,6 +450,13 @@ const WILDCARD_RANGES = [
 	"latest"
 ];
 /**
+* The protocol of a specifier that `npm publish` would ship verbatim while no consumer's package manager can resolve it (`workspace:`, `catalog:`, `link:`, `file:`), or `undefined` for a specifier a consumer can install.
+*/
+function unpublishableSpecifierProtocol(specifier) {
+	const trimmed = specifier.trim();
+	return UNPUBLISHABLE_SPECIFIER_PROTOCOLS.find((protocol) => trimmed.startsWith(protocol));
+}
+/**
 * 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.-]+)?)$/;
@@ -456,7 +478,7 @@ function classifyDependencyRange(current) {
 			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(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. Declare the sibling's version range directly (for example "^1.0.0") 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);
@@ -480,6 +502,27 @@ function updateDependencyRange(current, version) {
 	};
 }
 //#endregion
+//#region src/publishable-dependencies.ts
+/**
+* Throws `UnsupportedDependencyRangeError` unless every publishable package's installed dependencies (`dependencies`, `peerDependencies`, `optionalDependencies`) are ranges a consumer's package manager can resolve.
+*
+* Publishing goes through `@semantic-release/npm`, that is plain `npm publish`, which copies the manifest's specifiers into the registry unchanged. A `workspace:`, `catalog:`, `link:`, or `file:` specifier therefore reaches consumers as written and makes the package uninstallable, whichever sibling or external package it names and whether or not the tool would have rewritten it. `pnpm publish` would substitute some of them at pack time, but this tool never packs with pnpm, so accepting them would mean publishing a broken package with no warning.
+*
+* A `private` package never publishes and is exempt, and so is `devDependencies`, which no consumer installs. Every offending entry across every package is reported in one error, so a workspace with several of them is fixed in one pass rather than one failed run per entry.
+*/
+function assertPublishableDependencies(packages) {
+	const offences = [];
+	for (const pkg of packages) {
+		if (pkg.private) continue;
+		for (const field of INSTALLED_DEPENDENCY_FIELDS) {
+			const declared = pkg.dependencies.get(field);
+			if (declared === void 0) continue;
+			for (const [dependency, specifier] of declared) if (unpublishableSpecifierProtocol(specifier) !== void 0) offences.push(`  ${pkg.name}: "${dependency}" in ${field} is declared as "${specifier}"`);
+		}
+	}
+	if (offences.length > 0) throw new UnsupportedDependencyRangeError(`Refusing to release: npm publish ships these dependency specifiers unchanged, so the published package could not be installed.\n${offences.join("\n")}\nDeclare a plain version range instead (for example "^1.2.3"). For a sibling in this workspace, keep "linkWorkspacePackages: true" in pnpm-workspace.yaml so pnpm still links it locally; this tool rewrites the range whenever the sibling releases. Packages marked "private" are never published and are exempt.`);
+}
+//#endregion
 //#region src/graph.ts
 /**
 * Builds the inter-package dependency graph from the manifests alone.
@@ -555,11 +598,15 @@ function firstUnplacedDependency(name, graph, unplaced) {
 	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.
+* Validates every dependency range in the workspace before anything releases, so a run stops before the first publish rather than after some sibling has already been published, tagged, committed, and pushed. Two independent checks, both static properties of the manifests:
+*
+* - Every publishable package's installed dependencies must be specifiers a consumer can install (see `assertPublishableDependencies`), whichever package they name.
+* - Every workspace dependency edge's range must have a shape this tool can maintain (see `classifyDependencyRange`, which depends only on the range text and never on which version a sibling ends up releasing).
 *
-* 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.
+* Both throw `UnsupportedDependencyRangeError`. Shared by every release path (`release.ts`'s per-package loop, `single-commit-release.ts`'s analysis phase, and `gate-publish.ts`'s detach), which is why it lives alongside the graph it validates rather than inside any one of them.
 */
-function validateDependencyRangeShapes(graph) {
+function validateDependencyRanges(graph) {
+	assertPublishableDependencies([...graph.packages.values()]);
 	for (const edges of graph.dependencies.values()) for (const edge of edges) classifyDependencyRange(edge.range);
 }
 /**
@@ -773,7 +820,7 @@ async function regenerateLockfile(options) {
 * 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.
+* 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 `validateDependencyRanges` 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`.
@@ -789,7 +836,7 @@ async function releaseWorkspaceSingleCommit(options) {
 	const repoRoot = (await git(["rev-parse", "--show-toplevel"], { cwd: workspace.root })).trim();
 	await assertCleanWorkingTree({ cwd: repoRoot });
 	const graph = buildDependencyGraph(workspace.packages);
-	validateDependencyRangeShapes(graph);
+	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")} (commitStrategy: single)`);
 	const resolvedPlugins = resolvePublishPlugins(options.plugins ?? SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS, workspace.root, {
@@ -1061,7 +1108,7 @@ async function detachWorkspaceRelease(options) {
 	const env = sanitizeGitEnv(options.env ?? process.env);
 	const workspace = await discoverWorkspace(root);
 	const graph = buildDependencyGraph(workspace.packages);
-	validateDependencyRangeShapes(graph);
+	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order (gated -- tag only, publish deferred): ${order.join(" -> ")}`);
 	const publishPlugins = resolvePublishPlugins(options.plugins ?? DEFAULT_PUBLISH_PLUGINS, workspace.root, { requireGitPlugin: !dryRun });
@@ -1138,6 +1185,7 @@ async function resumeWorkspaceRelease(options) {
 	const root = resolve(options.root ?? process.cwd());
 	const log = options.log ?? console.log;
 	const env = sanitizeGitEnv(options.env ?? process.env);
+	assertPublishableDependencies(await Promise.all(options.detached.filter((entry) => entry.state !== null).map(async (entry) => readManifest(resolve(root, entry.relativeDirectory, "package.json")))));
 	const order = [];
 	const packages = [];
 	for (const entry of options.detached) {
@@ -1198,7 +1246,7 @@ async function releaseWorkspace(options = {}) {
 	const env = sanitizeGitEnv(options.env ?? process.env);
 	const workspace = await discoverWorkspace(root);
 	const graph = buildDependencyGraph(workspace.packages);
-	validateDependencyRangeShapes(graph);
+	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")}`);
 	const publishPlugins = resolvePublishPlugins(options.plugins ?? DEFAULT_PUBLISH_PLUGINS, workspace.root, { requireGitPlugin: !dryRun });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exadev/semantic-release-workspace",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "Independent per-package semantic-release orchestration for pnpm workspaces, without lockstep versioning.",
   "type": "module",
   "repository": {