@exadev/semantic-release-workspace 2.1.0 → 2.2.0

package/README.md

@@ -14,7 +14,7 @@ One orchestrator run, five stages:
 
 1. **Workspace discovery.** Reads the `packages` globs from `pnpm-workspace.yaml` and every matched package's `package.json` (`dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`), building the inter-package dependency graph keyed by package name. Packages must live in subdirectories (a package at the workspace root touches every commit and cannot be path-scoped) and names must be unique. This stage also resolves the workspace root's own path relative to the git repository's toplevel (`git rev-parse --show-prefix`), because `git log --name-only` always reports changed paths relative to that toplevel, not to `pnpm-workspace.yaml`'s own directory -- the two differ whenever the workspace is nested inside a larger repository, and every package's commit filtering is scoped against the repository-relative path, not the workspace-relative one, so nested workspaces are path-scoped correctly rather than silently matching nothing.
 2. **Topological release ordering.** Kahn's algorithm over the discovered graph, so a package only releases after every workspace sibling it depends on has already released in this run. Ties are broken alphabetically within each dependency layer, so the same workspace always produces the same order. A dependency cycle has no valid order at all — the run fails loudly, naming the loop (`x -> y -> x`), rather than picking one of the wrong answers and publishing a package whose sibling dependency points at a version that does not exist yet.
-3. **Per-package scoped release.** For each package in order, the orchestrator calls semantic-release's programmatic API (`require('semantic-release')`, not the CLI) with `cwd` set to the package's directory, `tagFormat` set to `name@version` so each package's tags stay distinct in the one shared tag namespace, and inline `analyzeCommits`/`generateNotes` plugins. Each wrapper runs one `git log --name-only --no-renames` pass over the same release range semantic-release already analysed (from the package's last matching tag to `HEAD`, or the whole history for a first release), maps every commit to the paths it changed, and filters the commit list down to commits touching the package's own directory **before delegating to the real @semantic-release/commit-analyzer and @semantic-release/release-notes-generator**. Conventional-commit parsing and changelog formatting stay entirely inside the standard plugins — the orchestrator only scopes what they see.
+3. **Per-package scoped release.** For each package in order, the orchestrator calls semantic-release's programmatic API (`require('semantic-release')`, not the CLI) with `cwd` set to the package's directory, `tagFormat` resolved from the `tagFormat` option (default `'${name}@${version}'`) so each package's tags stay distinct in the one shared tag namespace, and inline `analyzeCommits`/`generateNotes` plugins. Each wrapper runs one `git log --name-only --no-renames` pass over the same release range semantic-release already analysed (from the package's last matching tag to `HEAD`, or the whole history for a first release), maps every commit to the paths it changed, and filters the commit list down to commits touching the package's own directory **before delegating to the real @semantic-release/commit-analyzer and @semantic-release/release-notes-generator**. Conventional-commit parsing and changelog formatting stay entirely inside the standard plugins — the orchestrator only scopes what they see.
 4. **Cross-package manifest bumping** — the heart of the design, covered in its own section below.
 5. **Standard plugins do the publishing.** @semantic-release/npm, @semantic-release/github, @semantic-release/changelog, and @semantic-release/git run per package exactly as in a single-package repository, scoped by `cwd`. The orchestrator coordinates and sequences them; it does not reimplement npm publishing, GitHub release creation, or changelog file writing.
 
@@ -66,7 +66,13 @@ Everything above describes `commitStrategy: 'per-package'`, the default: unchang
 | Default publish plugins | `DEFAULT_PUBLISH_PLUGINS` (changelog, npm, github, git) | `SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS` — the same list minus git |
 | Crash recovery        | A bump commit already sitting in git history (from this run or an earlier one) is recognised via a machine-parseable trailer, so a run that resumes after a partial push still forces the right dependent releases | Not needed: either the whole combined commit lands and pushes, or the run fails before touching git at all, so there is never a partial push to recover from |
 
-Everything about *what* releases (topological order, forced-patch dependents, dependency-range classification, path-scoped commit analysis, unsupported-range rejection) is identical between the two modes — `commitStrategy` only changes how the result is committed, tagged, and pushed. Set it via the `--commit-strategy <mode>` CLI flag, the `commitStrategy` field in a `--config` file, or the `commitStrategy` option to `releaseWorkspace()`; omit it and nothing changes.
+Everything about *what* releases (topological order, forced-patch dependents, dependency-range classification, path-scoped commit analysis, unsupported-range rejection) is identical between the two modes — `commitStrategy` only changes how the result is committed, tagged, and pushed. ## Tag format
+
+Each package's release tag comes from the `tagFormat` option, a lodash template with `${name}` and `${version}` placeholders, defaulting to `'${name}@${version}'`. Set it via the `tagFormat` field in a `--config` file or the `tagFormat` option to `releaseWorkspace()`. The template must contain `${version}` and may contain `${name}`; anything else is rejected before any package releases.
+
+Override it when the tags are consumed as refs outside git: GitHub Actions pins composite actions as `owner/repo/path@ref`, and GitHub's workflow parser rejects a ref containing `@` -- so a repository of actions sets `'${name}-v${version}'` and every workflow pins `...@<action>-v<major>`. Note that switching an existing repository's format starts a fresh tag namespace: semantic-release will not see prior releases recorded under the old format, so rename existing tags to the new template as part of the switch.
+
+Set it via the `--commit-strategy <mode>` CLI flag, the `commitStrategy` field in a `--config` file, or the `commitStrategy` option to `releaseWorkspace()`; omit it and nothing changes.
 
 `'single'` mode still runs each package's own configured publish plugins afterward (npm publish with provenance, GitHub releases), scoped per package exactly as `'per-package'` mode does — it just runs their `verifyConditions`/`publish`/`success` steps directly against the already-committed-and-tagged repository state, since by that point semantic-release's own top-level orchestrator would misread the tag this mode already created as an existing release. `addChannel` and `fail` are not called in this mode (pre-release channel promotion and posting an automated failure comment/issue, respectively) — a deliberate scope boundary, not a silent gap: raise an issue if your workflow needs them.
 

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 = "2.1.0";
+var version = "2.2.0";
 //#endregion
 //#region src/errors.ts
 /**
@@ -59,6 +59,21 @@ var PnpmCommandError = class extends WorkspaceReleaseError {
 		super(`pnpm install --lockfile-only failed in ${cwd}: ${detail}`);
 	}
 };
+/**
+* Validate a caller-supplied tagFormat once per run, before any package releases. The template must contain `${version}` (semantic-release interpolates it; without it every package would compute the same tag and overwrite its predecessor) and may contain `${name}`, which the orchestrator substitutes per package. Any other `${...}` token is a typo or a placeholder semantic-release does not support in tagFormat, so it is rejected here rather than released as a literal into a tag name.
+*/
+function validateTagFormat(tagFormat) {
+	if (!tagFormat.includes("${version}")) throw new ReleaseConfigurationError(`tagFormat must contain '\${version}' so each package's release tag carries its version; got: ${tagFormat}`);
+	const unknown = [...tagFormat.matchAll(/\$\{([^}]*)\}/g)].map((match) => match[1] ?? "").filter((token) => token !== "name" && token !== "version").filter((token) => token !== "");
+	if (unknown.length > 0) throw new ReleaseConfigurationError(`tagFormat supports only the '\${name}' and '\${version}' placeholders; unknown token(s): ${unknown.map((token) => `\${${token}}`).join(", ")}`);
+	return tagFormat;
+}
+/**
+* Substitute `${name}` for one package. Called per package at release time; the returned template still carries the literal `${version}` for semantic-release to interpolate, exactly as the default `name@version` format always has.
+*/
+function formatTagForPackage(tagFormat, name) {
+	return tagFormat.replaceAll("${name}", name);
+}
 //#endregion
 //#region src/exec-file.ts
 /**
@@ -880,6 +895,7 @@ async function releaseWorkspaceSingleCommit(options) {
 	});
 	const analyzeCommitsConfig = options.analyzeCommits ?? {};
 	const generateNotesConfig = options.generateNotes ?? {};
+	const tagFormat = validateTagFormat(options.tagFormat ?? "${name}@${version}");
 	const capturedCommits = /* @__PURE__ */ new Map();
 	const captured = {
 		branch: void 0,
@@ -893,6 +909,7 @@ async function releaseWorkspaceSingleCommit(options) {
 		const bumpsForThisPackage = pendingBumps.get(name) ?? [];
 		pendingBumps.delete(name);
 		const nextRelease = await analysePackage(pkg, {
+			tagFormat,
 			resolvedPlugins: mustGet(resolvedPlugins, name, "publish plugins"),
 			analyzeCommitsConfig,
 			generateNotesConfig,
@@ -1015,7 +1032,7 @@ async function analysePackage(pkg, options) {
 		onCommitsResolved: options.onCommitsResolved
 	});
 	const semanticReleaseOptions = {
-		tagFormat: `${pkg.name}@\${version}`,
+		tagFormat: formatTagForPackage(options.tagFormat, pkg.name),
 		plugins: options.resolvedPlugins,
 		dryRun: true,
 		async analyzeCommits(pluginConfig, context) {
@@ -1163,6 +1180,7 @@ async function releaseWorkspace(options = {}) {
 		order,
 		packages: (await runReleaseLoop(graph, order, workspace, dryRun, log, async (pkg, bumpsForThisPackage) => {
 			const result = await runPackageRelease(pkg, {
+				tagFormat: validateTagFormat(options.tagFormat ?? "${name}@${version}"),
 				publishPlugins: mustGet(publishPlugins, pkg.name, "publish plugins"),
 				analyzeCommitsConfig,
 				generateNotesConfig,
@@ -1244,7 +1262,7 @@ async function runPackageRelease(pkg, options) {
 		bumps: { bumpsFor: () => options.bumpsForThisPackage }
 	});
 	const semanticReleaseOptions = {
-		tagFormat: `${pkg.name}@\${version}`,
+		tagFormat: formatTagForPackage(options.tagFormat, pkg.name),
 		plugins: options.publishPlugins,
 		analyzeCommits: scoped.analyzeCommits,
 		generateNotes: scoped.generateNotes
@@ -1331,6 +1349,7 @@ async function detachWorkspaceRelease(options) {
 			analyzeCommitsConfig,
 			generateNotesConfig,
 			bumpsForThisPackage,
+			tagFormat: validateTagFormat(options.tagFormat ?? "${name}@${version}"),
 			dryRun,
 			env,
 			branches: options.branches
@@ -1373,7 +1392,7 @@ async function runPackageDetach(pkg, options) {
 		bumps: { bumpsFor: () => options.bumpsForThisPackage }
 	});
 	const cliOptions = {
-		tagFormat: `${pkg.name}@\${version}`,
+		tagFormat: formatTagForPackage(options.tagFormat, pkg.name),
 		plugins: options.publishPlugins,
 		analyzeCommits: scoped.analyzeCommits,
 		generateNotes: scoped.generateNotes

package/dist/index.cjs

@@ -857,6 +857,21 @@ async function regenerateLockfile(options) {
 		throw new PnpmCommandError(options.cwd, detail);
 	}
 }
+/**
+* Validate a caller-supplied tagFormat once per run, before any package releases. The template must contain `${version}` (semantic-release interpolates it; without it every package would compute the same tag and overwrite its predecessor) and may contain `${name}`, which the orchestrator substitutes per package. Any other `${...}` token is a typo or a placeholder semantic-release does not support in tagFormat, so it is rejected here rather than released as a literal into a tag name.
+*/
+function validateTagFormat(tagFormat) {
+	if (!tagFormat.includes("${version}")) throw new ReleaseConfigurationError(`tagFormat must contain '\${version}' so each package's release tag carries its version; got: ${tagFormat}`);
+	const unknown = [...tagFormat.matchAll(/\$\{([^}]*)\}/g)].map((match) => match[1] ?? "").filter((token) => token !== "name" && token !== "version").filter((token) => token !== "");
+	if (unknown.length > 0) throw new ReleaseConfigurationError(`tagFormat supports only the '\${name}' and '\${version}' placeholders; unknown token(s): ${unknown.map((token) => `\${${token}}`).join(", ")}`);
+	return tagFormat;
+}
+/**
+* Substitute `${name}` for one package. Called per package at release time; the returned template still carries the literal `${version}` for semantic-release to interpolate, exactly as the default `name@version` format always has.
+*/
+function formatTagForPackage(tagFormat, name) {
+	return tagFormat.replaceAll("${name}", name);
+}
 //#endregion
 //#region src/single-commit-release.ts
 /**
@@ -893,6 +908,7 @@ async function releaseWorkspaceSingleCommit(options) {
 	});
 	const analyzeCommitsConfig = options.analyzeCommits ?? {};
 	const generateNotesConfig = options.generateNotes ?? {};
+	const tagFormat = validateTagFormat(options.tagFormat ?? "${name}@${version}");
 	const capturedCommits = /* @__PURE__ */ new Map();
 	const captured = {
 		branch: void 0,
@@ -906,6 +922,7 @@ async function releaseWorkspaceSingleCommit(options) {
 		const bumpsForThisPackage = pendingBumps.get(name) ?? [];
 		pendingBumps.delete(name);
 		const nextRelease = await analysePackage(pkg, {
+			tagFormat,
 			resolvedPlugins: mustGet(resolvedPlugins, name, "publish plugins"),
 			analyzeCommitsConfig,
 			generateNotesConfig,
@@ -1028,7 +1045,7 @@ async function analysePackage(pkg, options) {
 		onCommitsResolved: options.onCommitsResolved
 	});
 	const semanticReleaseOptions = {
-		tagFormat: `${pkg.name}@\${version}`,
+		tagFormat: formatTagForPackage(options.tagFormat, pkg.name),
 		plugins: options.resolvedPlugins,
 		dryRun: true,
 		async analyzeCommits(pluginConfig, context) {
@@ -1171,6 +1188,7 @@ async function detachWorkspaceRelease(options) {
 			analyzeCommitsConfig,
 			generateNotesConfig,
 			bumpsForThisPackage,
+			tagFormat: validateTagFormat(options.tagFormat ?? "${name}@${version}"),
 			dryRun,
 			env,
 			branches: options.branches
@@ -1213,7 +1231,7 @@ async function runPackageDetach(pkg, options) {
 		bumps: { bumpsFor: () => options.bumpsForThisPackage }
 	});
 	const cliOptions = {
-		tagFormat: `${pkg.name}@\${version}`,
+		tagFormat: formatTagForPackage(options.tagFormat, pkg.name),
 		plugins: options.publishPlugins,
 		analyzeCommits: scoped.analyzeCommits,
 		generateNotes: scoped.generateNotes
@@ -1310,6 +1328,7 @@ async function releaseWorkspace(options = {}) {
 		order,
 		packages: (await runReleaseLoop(graph, order, workspace, dryRun, log, async (pkg, bumpsForThisPackage) => {
 			const result = await runPackageRelease(pkg, {
+				tagFormat: validateTagFormat(options.tagFormat ?? "${name}@${version}"),
 				publishPlugins: mustGet(publishPlugins, pkg.name, "publish plugins"),
 				analyzeCommitsConfig,
 				generateNotesConfig,
@@ -1391,7 +1410,7 @@ async function runPackageRelease(pkg, options) {
 		bumps: { bumpsFor: () => options.bumpsForThisPackage }
 	});
 	const semanticReleaseOptions = {
-		tagFormat: `${pkg.name}@\${version}`,
+		tagFormat: formatTagForPackage(options.tagFormat, pkg.name),
 		plugins: options.publishPlugins,
 		analyzeCommits: scoped.analyzeCommits,
 		generateNotes: scoped.generateNotes

package/dist/index.d.cts

@@ -260,6 +260,14 @@ interface ReleaseWorkspaceOptions {
    * Opt-in, orthogonal to `commitStrategy` -- it governs *when* publish/success run relative to tag+push, not *how many commits* the release makes. When `true`, each package's release is tagged and pushed via `@exadev/release-gate`'s `detachRelease` but never published: `WorkspaceReleaseOutcome.detached` carries the state `resumeWorkspaceRelease` needs to finish publishing later, from the same process or a different one, once an external gate confirms the release should actually go out. Rejected outright in combination with `commitStrategy: 'single'` -- `single-commit-release.ts`'s tag/publish machinery is entirely bespoke and never goes through semantic-release's own `run()`, so it has no insertion point for `release-gate`'s primitives. Defaults to `false`, today's exact existing behaviour.
    */
   readonly gatePublish?: boolean;
+  /**
+   * Lodash template for each package's release tag, with `${name}` and `${version}` placeholders.
+   * Defaults to `'${name}@${version}'`. Override it when the tags double as refs consumed outside
+   * git: GitHub Actions pins composite actions as `owner/repo/path@ref`, and GitHub's workflow
+   * parser rejects a ref containing `@`, so a repository of actions sets `'${name}-v${version}'`
+   * and pins `...@<action>-v1`. Validated once per run by `validateTagFormat`.
+   */
+  readonly tagFormat?: string;
 }
 /** One dependency-range change applied to a dependent package's manifest during the run, attached to the dependent's own outcome. */
 interface AppliedDependencyBump extends DependencyBump {

package/dist/index.d.ts

@@ -260,6 +260,14 @@ interface ReleaseWorkspaceOptions {
    * Opt-in, orthogonal to `commitStrategy` -- it governs *when* publish/success run relative to tag+push, not *how many commits* the release makes. When `true`, each package's release is tagged and pushed via `@exadev/release-gate`'s `detachRelease` but never published: `WorkspaceReleaseOutcome.detached` carries the state `resumeWorkspaceRelease` needs to finish publishing later, from the same process or a different one, once an external gate confirms the release should actually go out. Rejected outright in combination with `commitStrategy: 'single'` -- `single-commit-release.ts`'s tag/publish machinery is entirely bespoke and never goes through semantic-release's own `run()`, so it has no insertion point for `release-gate`'s primitives. Defaults to `false`, today's exact existing behaviour.
    */
   readonly gatePublish?: boolean;
+  /**
+   * Lodash template for each package's release tag, with `${name}` and `${version}` placeholders.
+   * Defaults to `'${name}@${version}'`. Override it when the tags double as refs consumed outside
+   * git: GitHub Actions pins composite actions as `owner/repo/path@ref`, and GitHub's workflow
+   * parser rejects a ref containing `@`, so a repository of actions sets `'${name}-v${version}'`
+   * and pins `...@<action>-v1`. Validated once per run by `validateTagFormat`.
+   */
+  readonly tagFormat?: string;
 }
 /** One dependency-range change applied to a dependent package's manifest during the run, attached to the dependent's own outcome. */
 interface AppliedDependencyBump extends DependencyBump {

package/dist/index.js

@@ -832,6 +832,21 @@ async function regenerateLockfile(options) {
 		throw new PnpmCommandError(options.cwd, detail);
 	}
 }
+/**
+* Validate a caller-supplied tagFormat once per run, before any package releases. The template must contain `${version}` (semantic-release interpolates it; without it every package would compute the same tag and overwrite its predecessor) and may contain `${name}`, which the orchestrator substitutes per package. Any other `${...}` token is a typo or a placeholder semantic-release does not support in tagFormat, so it is rejected here rather than released as a literal into a tag name.
+*/
+function validateTagFormat(tagFormat) {
+	if (!tagFormat.includes("${version}")) throw new ReleaseConfigurationError(`tagFormat must contain '\${version}' so each package's release tag carries its version; got: ${tagFormat}`);
+	const unknown = [...tagFormat.matchAll(/\$\{([^}]*)\}/g)].map((match) => match[1] ?? "").filter((token) => token !== "name" && token !== "version").filter((token) => token !== "");
+	if (unknown.length > 0) throw new ReleaseConfigurationError(`tagFormat supports only the '\${name}' and '\${version}' placeholders; unknown token(s): ${unknown.map((token) => `\${${token}}`).join(", ")}`);
+	return tagFormat;
+}
+/**
+* Substitute `${name}` for one package. Called per package at release time; the returned template still carries the literal `${version}` for semantic-release to interpolate, exactly as the default `name@version` format always has.
+*/
+function formatTagForPackage(tagFormat, name) {
+	return tagFormat.replaceAll("${name}", name);
+}
 //#endregion
 //#region src/single-commit-release.ts
 /**
@@ -868,6 +883,7 @@ async function releaseWorkspaceSingleCommit(options) {
 	});
 	const analyzeCommitsConfig = options.analyzeCommits ?? {};
 	const generateNotesConfig = options.generateNotes ?? {};
+	const tagFormat = validateTagFormat(options.tagFormat ?? "${name}@${version}");
 	const capturedCommits = /* @__PURE__ */ new Map();
 	const captured = {
 		branch: void 0,
@@ -881,6 +897,7 @@ async function releaseWorkspaceSingleCommit(options) {
 		const bumpsForThisPackage = pendingBumps.get(name) ?? [];
 		pendingBumps.delete(name);
 		const nextRelease = await analysePackage(pkg, {
+			tagFormat,
 			resolvedPlugins: mustGet(resolvedPlugins, name, "publish plugins"),
 			analyzeCommitsConfig,
 			generateNotesConfig,
@@ -1003,7 +1020,7 @@ async function analysePackage(pkg, options) {
 		onCommitsResolved: options.onCommitsResolved
 	});
 	const semanticReleaseOptions = {
-		tagFormat: `${pkg.name}@\${version}`,
+		tagFormat: formatTagForPackage(options.tagFormat, pkg.name),
 		plugins: options.resolvedPlugins,
 		dryRun: true,
 		async analyzeCommits(pluginConfig, context) {
@@ -1146,6 +1163,7 @@ async function detachWorkspaceRelease(options) {
 			analyzeCommitsConfig,
 			generateNotesConfig,
 			bumpsForThisPackage,
+			tagFormat: validateTagFormat(options.tagFormat ?? "${name}@${version}"),
 			dryRun,
 			env,
 			branches: options.branches
@@ -1188,7 +1206,7 @@ async function runPackageDetach(pkg, options) {
 		bumps: { bumpsFor: () => options.bumpsForThisPackage }
 	});
 	const cliOptions = {
-		tagFormat: `${pkg.name}@\${version}`,
+		tagFormat: formatTagForPackage(options.tagFormat, pkg.name),
 		plugins: options.publishPlugins,
 		analyzeCommits: scoped.analyzeCommits,
 		generateNotes: scoped.generateNotes
@@ -1285,6 +1303,7 @@ async function releaseWorkspace(options = {}) {
 		order,
 		packages: (await runReleaseLoop(graph, order, workspace, dryRun, log, async (pkg, bumpsForThisPackage) => {
 			const result = await runPackageRelease(pkg, {
+				tagFormat: validateTagFormat(options.tagFormat ?? "${name}@${version}"),
 				publishPlugins: mustGet(publishPlugins, pkg.name, "publish plugins"),
 				analyzeCommitsConfig,
 				generateNotesConfig,
@@ -1366,7 +1385,7 @@ async function runPackageRelease(pkg, options) {
 		bumps: { bumpsFor: () => options.bumpsForThisPackage }
 	});
 	const semanticReleaseOptions = {
-		tagFormat: `${pkg.name}@\${version}`,
+		tagFormat: formatTagForPackage(options.tagFormat, pkg.name),
 		plugins: options.publishPlugins,
 		analyzeCommits: scoped.analyzeCommits,
 		generateNotes: scoped.generateNotes

package/package.json

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