@exadev/semantic-release-workspace 1.3.5 → 1.3.7

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;
@@ -139,13 +143,13 @@ interface DependencyBump {
 }
 /** What the scoped plugins need to know about bumps recorded so far in the run, for the package they are about to analyse. */
 interface DependencyBumpSource {
-  bumpsFor(dependent: string): readonly DependencyBump[];
+  bumpsFor: (dependent: string) => readonly DependencyBump[];
 }
 /** A publish-pipeline plugin entry as the orchestrator accepts it: a module name, optionally with a config object. */
 type PublishPluginSpec = string | readonly [string] | readonly [string, Record<string, unknown>];
 /** The standard publish pipeline this orchestrator coordinates when a workspace configures none of its own. Every entry reuses the corresponding official plugin -- the orchestrator scopes and sequences them per package, it does not reimplement npm publishing, GitHub release creation, or changelog writing. */
 export declare const DEFAULT_PUBLISH_PLUGINS: readonly PublishPluginSpec[];
-/** 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. */
+/** 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. */
 export declare const SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS: readonly PublishPluginSpec[];
 interface ScopedPlugins {
   readonly analyzeCommits: (pluginConfig: Record<string, unknown>, context: AnalyzeCommitsContext & {
@@ -158,7 +162,7 @@ interface ScopedPlugins {
 /**
  * Builds the per-package `analyzeCommits` and `generateNotes` functions handed to semantic-release as inline plugins.
  *
- * Both apply the same path scoping before delegating to the real @semantic-release/commit-analyzer and @semantic-release/release-notes-generator: the commit list semantic-release already fetched for the release range is filtered down to commits whose `git log --name-only` file list intersects the package's own directory, and only the filtered list reaches the standard plugin. Conventional-commit parsing and changelog formatting stay entirely inside the standard plugins.
+ * Both apply the same path scoping before delegating to the real `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator`: the commit list semantic-release already fetched for the release range is filtered down to commits whose `git log --name-only` file list intersects the package's own directory, and only the filtered list reaches the standard plugin. Conventional-commit parsing and changelog formatting stay entirely inside the standard plugins.
  *
  * The `analyzeCommits` wrapper carries one addition beyond filtering: when the standard analyzer finds no releasable commits but a workspace dependency range of the package's has changed, it returns 'patch' anyway. A dependent whose only change is a dependency bump still needs a release for that range to reach the registry. "Has changed" is read from two sources, merged: bumps recorded in memory earlier in the current run (`scope.bumps`), and bumps recorded in the package's own filtered commit history via the trailer `dependency-bump-commit.ts` writes and reads -- the latter is what lets a run that starts after a previous run already committed and pushed the bump (a crash recovery, or simply a later run) reach the same decision, rather than depending on state that existed only inside the process that made the commit.
  */
@@ -226,11 +230,11 @@ interface ReleaseWorkspaceOptions {
   readonly dryRun?: boolean;
   /** Release branch configuration for semantic-release. Defaults to semantic-release's own default branch list. */
   readonly branches?: readonly BranchSpec[];
-  /** Publish-pipeline plugins (changelog, npm, GitHub, git), each scoped per package by semantic-release's own `cwd`. Defaults to the standard pipeline in DEFAULT_PUBLISH_PLUGINS for `commitStrategy: 'per-package'`, or SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS (the same list minus @semantic-release/git) for `commitStrategy: 'single'`. */
+  /** Publish-pipeline plugins (changelog, npm, GitHub, git), each scoped per package by semantic-release's own `cwd`. Defaults to the standard pipeline in DEFAULT_PUBLISH_PLUGINS for `commitStrategy: 'per-package'`, or SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS (the same list minus `@semantic-release/git`) for `commitStrategy: 'single'`. */
   readonly plugins?: readonly PublishPluginSpec[];
-  /** Options for the wrapped @semantic-release/commit-analyzer, applied per package after path filtering. */
+  /** Options for the wrapped `@semantic-release/commit-analyzer`, applied per package after path filtering. */
   readonly analyzeCommits?: Record<string, unknown>;
-  /** Options for the wrapped @semantic-release/release-notes-generator, applied per package after path filtering. */
+  /** Options for the wrapped `@semantic-release/release-notes-generator`, applied per package after path filtering. */
   readonly generateNotes?: Record<string, unknown>;
   /** Progress sink for the orchestrator's own narration (semantic-release logs its own detail). Defaults to `console.log`. */
   readonly log?: (message: string) => void;
@@ -247,17 +251,22 @@ interface AppliedDependencyBump extends DependencyBump {
   /** Which manifest field held the range that was rewritten. */
   readonly field: DependencyField;
 }
-interface PackageReleaseOutcome {
+type PackageReleaseOutcome = {
   readonly name: string;
   readonly directory: string;
-  readonly released: boolean;
-  readonly version: string | undefined;
-  readonly gitTag: string | undefined;
-  /** The semantic-release release type ('minor', 'patch', ...), including the forced 'patch' of a dependency-bump-only release. */
-  readonly type: string | undefined;
   /** Dependency ranges rewritten in this package's own manifest because a workspace dependency released earlier in the run. */
   readonly dependencyBumps: readonly AppliedDependencyBump[];
-}
+} & ({
+  readonly released: true;
+  readonly version: string;
+  readonly gitTag: string;
+  readonly type: string;
+} | {
+  readonly released: false;
+  readonly version?: undefined;
+  readonly gitTag?: undefined;
+  readonly type?: undefined;
+});
 interface WorkspaceReleaseOutcome {
   /** The topological order the packages were released in. */
   readonly order: readonly string[];
@@ -289,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;
@@ -139,13 +143,13 @@ interface DependencyBump {
 }
 /** What the scoped plugins need to know about bumps recorded so far in the run, for the package they are about to analyse. */
 interface DependencyBumpSource {
-  bumpsFor(dependent: string): readonly DependencyBump[];
+  bumpsFor: (dependent: string) => readonly DependencyBump[];
 }
 /** A publish-pipeline plugin entry as the orchestrator accepts it: a module name, optionally with a config object. */
 type PublishPluginSpec = string | readonly [string] | readonly [string, Record<string, unknown>];
 /** The standard publish pipeline this orchestrator coordinates when a workspace configures none of its own. Every entry reuses the corresponding official plugin -- the orchestrator scopes and sequences them per package, it does not reimplement npm publishing, GitHub release creation, or changelog writing. */
 export declare const DEFAULT_PUBLISH_PLUGINS: readonly PublishPluginSpec[];
-/** 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. */
+/** 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. */
 export declare const SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS: readonly PublishPluginSpec[];
 interface ScopedPlugins {
   readonly analyzeCommits: (pluginConfig: Record<string, unknown>, context: AnalyzeCommitsContext & {
@@ -158,7 +162,7 @@ interface ScopedPlugins {
 /**
  * Builds the per-package `analyzeCommits` and `generateNotes` functions handed to semantic-release as inline plugins.
  *
- * Both apply the same path scoping before delegating to the real @semantic-release/commit-analyzer and @semantic-release/release-notes-generator: the commit list semantic-release already fetched for the release range is filtered down to commits whose `git log --name-only` file list intersects the package's own directory, and only the filtered list reaches the standard plugin. Conventional-commit parsing and changelog formatting stay entirely inside the standard plugins.
+ * Both apply the same path scoping before delegating to the real `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator`: the commit list semantic-release already fetched for the release range is filtered down to commits whose `git log --name-only` file list intersects the package's own directory, and only the filtered list reaches the standard plugin. Conventional-commit parsing and changelog formatting stay entirely inside the standard plugins.
  *
  * The `analyzeCommits` wrapper carries one addition beyond filtering: when the standard analyzer finds no releasable commits but a workspace dependency range of the package's has changed, it returns 'patch' anyway. A dependent whose only change is a dependency bump still needs a release for that range to reach the registry. "Has changed" is read from two sources, merged: bumps recorded in memory earlier in the current run (`scope.bumps`), and bumps recorded in the package's own filtered commit history via the trailer `dependency-bump-commit.ts` writes and reads -- the latter is what lets a run that starts after a previous run already committed and pushed the bump (a crash recovery, or simply a later run) reach the same decision, rather than depending on state that existed only inside the process that made the commit.
  */
@@ -226,11 +230,11 @@ interface ReleaseWorkspaceOptions {
   readonly dryRun?: boolean;
   /** Release branch configuration for semantic-release. Defaults to semantic-release's own default branch list. */
   readonly branches?: readonly BranchSpec[];
-  /** Publish-pipeline plugins (changelog, npm, GitHub, git), each scoped per package by semantic-release's own `cwd`. Defaults to the standard pipeline in DEFAULT_PUBLISH_PLUGINS for `commitStrategy: 'per-package'`, or SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS (the same list minus @semantic-release/git) for `commitStrategy: 'single'`. */
+  /** Publish-pipeline plugins (changelog, npm, GitHub, git), each scoped per package by semantic-release's own `cwd`. Defaults to the standard pipeline in DEFAULT_PUBLISH_PLUGINS for `commitStrategy: 'per-package'`, or SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS (the same list minus `@semantic-release/git`) for `commitStrategy: 'single'`. */
   readonly plugins?: readonly PublishPluginSpec[];
-  /** Options for the wrapped @semantic-release/commit-analyzer, applied per package after path filtering. */
+  /** Options for the wrapped `@semantic-release/commit-analyzer`, applied per package after path filtering. */
   readonly analyzeCommits?: Record<string, unknown>;
-  /** Options for the wrapped @semantic-release/release-notes-generator, applied per package after path filtering. */
+  /** Options for the wrapped `@semantic-release/release-notes-generator`, applied per package after path filtering. */
   readonly generateNotes?: Record<string, unknown>;
   /** Progress sink for the orchestrator's own narration (semantic-release logs its own detail). Defaults to `console.log`. */
   readonly log?: (message: string) => void;
@@ -247,17 +251,22 @@ interface AppliedDependencyBump extends DependencyBump {
   /** Which manifest field held the range that was rewritten. */
   readonly field: DependencyField;
 }
-interface PackageReleaseOutcome {
+type PackageReleaseOutcome = {
   readonly name: string;
   readonly directory: string;
-  readonly released: boolean;
-  readonly version: string | undefined;
-  readonly gitTag: string | undefined;
-  /** The semantic-release release type ('minor', 'patch', ...), including the forced 'patch' of a dependency-bump-only release. */
-  readonly type: string | undefined;
   /** Dependency ranges rewritten in this package's own manifest because a workspace dependency released earlier in the run. */
   readonly dependencyBumps: readonly AppliedDependencyBump[];
-}
+} & ({
+  readonly released: true;
+  readonly version: string;
+  readonly gitTag: string;
+  readonly type: string;
+} | {
+  readonly released: false;
+  readonly version?: undefined;
+  readonly gitTag?: undefined;
+  readonly type?: undefined;
+});
 interface WorkspaceReleaseOutcome {
   /** The topological order the packages were released in. */
   readonly order: readonly string[];
@@ -289,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 {}