@exadev/semantic-release-workspace 0.0.0 → 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,259 @@
+import { AnalyzeCommitsContext, BranchSpec, GenerateNotesContext } from "semantic-release";
+//#region src/package-name.d.ts
+declare const packageName = "@exadev/semantic-release-workspace";
+//#endregion
+//#region src/manifest.d.ts
+/**
+ * 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.
+ */
+type DependencyField = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
+interface PackageManifest {
+  readonly name: string;
+  readonly version: string;
+  /** Only the fields actually present in the file, each mapping dependency name to its declared range. */
+  readonly dependencies: ReadonlyMap<DependencyField, ReadonlyMap<string, string>>;
+}
+declare function readManifest(path: string): Promise<PackageManifest>;
+/**
+ * Rewrites one dependency range in a manifest on disk.
+ *
+ * Deliberately re-reads the file rather than editing a copy held from discovery time: by the time a cross-package bump is applied, semantic-release's own `@semantic-release/npm` prepare step may already have rewritten `version` in this same file for an earlier package in the run. Writing back a manifest parsed before that would silently revert it.
+ */
+declare function writeDependencyRange(path: string, field: DependencyField, dependency: string, range: string): Promise<void>;
+//#endregion
+//#region src/workspace.d.ts
+interface WorkspacePackage {
+  readonly name: string;
+  readonly version: string;
+  /** 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. */
+  readonly relativeDirectory: string;
+  /** Path relative to the git repository's toplevel, always POSIX-separated. This is the base every `git log --name-only` path is compared against, because git reports changed paths relative to the repository root regardless of the directory a command runs from -- equal to `relativeDirectory` only when `pnpm-workspace.yaml` itself sits at the repository's toplevel. */
+  readonly repoRelativeDirectory: string;
+  readonly manifestPath: string;
+  readonly dependencies: ReadonlyMap<DependencyField, ReadonlyMap<string, string>>;
+}
+interface Workspace {
+  /** Absolute path to the directory holding `pnpm-workspace.yaml`. */
+  readonly root: string;
+  /** Every discovered package, ordered by directory so discovery is reproducible regardless of filesystem iteration order. */
+  readonly packages: readonly WorkspacePackage[];
+}
+/**
+ * Reads `pnpm-workspace.yaml` and every package manifest its globs match, producing the input to both the dependency graph and the per-package release runs.
+ *
+ * Nothing here knows anything about a particular repository's layout: the globs come from the workspace file, and the package names, versions, and dependency ranges come from the manifests those globs match. Pointing this at any pnpm workspace is the entire configuration.
+ */
+declare function discoverWorkspace(root: string): Promise<Workspace>;
+//#endregion
+//#region src/graph.d.ts
+/** One package's dependency on another package in the same workspace. */
+interface WorkspaceDependency {
+  /** The depending package's name. */
+  readonly dependent: string;
+  /** The depended-upon package's name. */
+  readonly dependency: string;
+  readonly field: DependencyField;
+  /** The range exactly as written in the dependent's manifest. */
+  readonly range: string;
+}
+interface DependencyGraph {
+  readonly packages: ReadonlyMap<string, WorkspacePackage>;
+  /** For each package, the workspace siblings it depends on. */
+  readonly dependencies: ReadonlyMap<string, readonly WorkspaceDependency[]>;
+  /** For each package, the workspace siblings that depend on it. */
+  readonly dependents: ReadonlyMap<string, readonly WorkspaceDependency[]>;
+}
+/**
+ * Builds the inter-package dependency graph from the manifests alone.
+ *
+ * A dependency on a package outside the workspace is not an edge: it neither constrains the release order nor gets rewritten when something here releases. A package that names itself becomes a self-edge, which `topologicalOrder` then reports as the one-package cycle it is, rather than being quietly dropped.
+ */
+declare function buildDependencyGraph(packages: readonly WorkspacePackage[]): DependencyGraph;
+/**
+ * Orders packages so every package appears after every workspace sibling it depends on, using Kahn's algorithm.
+ *
+ * Packages whose dependencies have all been placed are taken in name order, so the same workspace always produces the same order -- a release run that reorders itself between CI runs is impossible to reason about when something goes wrong halfway through.
+ *
+ * A cycle has no valid order at all, so it throws rather than picking one of the wrong answers. In a release context an arbitrary order is worse than a failure: it would publish a package whose sibling dependency range points at a version that does not exist yet.
+ */
+declare function topologicalOrder(graph: DependencyGraph): readonly string[];
+//#endregion
+//#region src/version-range.d.ts
+/**
+ * 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.
+ */
+type DependencyRangeUpdate =
+/** The range names a concrete version that has to be rewritten in the manifest. */
+{
+  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. */
+{
+  readonly kind: 'resolved-at-publish';
+} |
+/** A range naming no version at all (`*`, `x`, `latest`). Nothing to rewrite, and the published range is unaffected by the sibling's new version. */
+{
+  readonly kind: 'wildcard';
+};
+/**
+ * What a dependency range's own shape supports, independent of any particular version -- the classification that decides whether `updateDependencyRange` can succeed at all, split out so it can be checked for every workspace dependency edge before a release run starts, not just when the range's sibling actually releases.
+ */
+type DependencyRangeShape = {
+  readonly kind: 'rewritable';
+  readonly workspacePrefixed: boolean;
+  readonly comparator: string;
+} | {
+  readonly kind: 'resolved-at-publish';
+} | {
+  readonly kind: 'wildcard';
+};
+/**
+ * Classifies a dependency range's shape, throwing `UnsupportedDependencyRangeError` for anything this tool cannot rewrite with confidence: a compound range (`>=1.0.0 <2.0.0`), a union (`1.x || 2.x`), a `catalog:` reference whose real version lives in `pnpm-workspace.yaml`, an `npm:` alias, a git or tarball URL. Guessing at those would either corrupt the range or silently leave it pointing at a version that no longer exists in the workspace, and a stale published range is exactly the divergence this tool exists to prevent.
+ *
+ * This never needs the version a sibling is releasing: every case above depends only on the shape of `current` itself, which is what lets `releaseWorkspace` validate every workspace dependency edge up front, before any package has published anything, rather than discovering an unsupported range only when the first dependency it names happens to release.
+ */
+declare function classifyDependencyRange(current: string): DependencyRangeShape;
+/**
+ * Computes what a dependency range on a workspace sibling becomes once that sibling releases `version`, by classifying the range's shape and then, for a rewritable shape, substituting `version` in place of the version it currently names.
+ */
+declare function updateDependencyRange(current: string, version: string): DependencyRangeUpdate;
+//#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.
+ */
+interface DependencyBump {
+  readonly dependency: string;
+  readonly version: string;
+  /** The range as it now stands in the dependent's manifest -- the new concrete range for `rewritten`, the untouched `workspace:` range for `resolved-at-publish`. */
+  readonly range: string;
+  readonly kind: 'rewritten' | 'resolved-at-publish';
+}
+/** 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[];
+}
+/** 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. */
+declare const DEFAULT_PUBLISH_PLUGINS: readonly PublishPluginSpec[];
+interface ScopedPlugins {
+  readonly analyzeCommits: (pluginConfig: Record<string, unknown>, context: AnalyzeCommitsContext & {
+    cwd: string;
+  }) => Promise<string | false | undefined>;
+  readonly generateNotes: (pluginConfig: Record<string, unknown>, context: GenerateNotesContext & {
+    cwd: string;
+  }) => Promise<string | false | undefined>;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+declare function createScopedPlugins(scope: {
+  readonly pkg: WorkspacePackage;
+  readonly analyzeCommitsConfig: Record<string, unknown>;
+  readonly generateNotesConfig: Record<string, unknown>;
+  readonly bumps: DependencyBumpSource;
+}): ScopedPlugins;
+/**
+ * Keeps a commit for the package when any path it changed lies under the package's directory. The trailing-slash prefix comparison stops `packages/a` from matching `packages/abc/x`.
+ *
+ * A commit missing from the changed-paths map is kept rather than dropped: it is inside the package's release range (semantic-release put it there), so a failure to parse its file list must not silently swallow a release. Absent evidence errs towards publishing, which is the visible direction for a release tool.
+ */
+declare function filterCommitsToDirectory<T extends {
+  readonly hash: string;
+}>(commits: readonly T[], changedPaths: ReadonlyMap<string, ReadonlySet<string>>, directory: string): readonly T[];
+/** A publish plugin entry with its module name resolved to an absolute path, so semantic-release loads the workspace's installed plugins regardless of the package directory it runs from. */
+type ResolvedPublishPlugin = [string, Record<string, unknown>];
+declare function resolvePublishPlugins(specs: readonly PublishPluginSpec[], workspaceRoot: string, options: {
+  readonly requireGitPlugin: boolean;
+}): readonly ResolvedPublishPlugin[];
+//#endregion
+//#region src/release.d.ts
+interface ReleaseWorkspaceOptions {
+  /** Directory holding the workspace's `pnpm-workspace.yaml`. Defaults to the process working directory. */
+  readonly root?: string;
+  /** Environment for the per-package semantic-release runs. Defaults to `process.env`; passing a copy lets tests and embedders control the CI detection semantic-release performs on it. */
+  readonly env?: NodeJS.ProcessEnv;
+  /** Passed straight through to every per-package semantic-release run: analysis runs, nothing is published, tagged, committed, or pushed. */
+  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. */
+  readonly plugins?: readonly PublishPluginSpec[];
+  /** 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. */
+  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;
+}
+/** 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 {
+  readonly dependent: string;
+  /** Which manifest field held the range that was rewritten. */
+  readonly field: DependencyField;
+}
+interface 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[];
+}
+interface WorkspaceReleaseOutcome {
+  /** The topological order the packages were released in. */
+  readonly order: readonly string[];
+  readonly packages: readonly PackageReleaseOutcome[];
+}
+/**
+ * Releases every package in a pnpm workspace with independent versions, in dependency order.
+ *
+ * For each package, in topological order: run semantic-release's programmatic API with `cwd` scoped to the package directory, a `name@version` tag format to keep each package's tags distinct in the one shared tag namespace, and inline `analyzeCommits`/`generateNotes` plugins that filter the release range's commits down to the package's own directory before delegating to the standard plugins. When a package releases, every workspace package that depends on it and has not run yet gets its dependency range rewritten in its manifest and committed immediately -- before its own turn, so its commit analysis and its published manifest both see the new range.
+ */
+declare function releaseWorkspace(options?: ReleaseWorkspaceOptions): Promise<WorkspaceReleaseOutcome>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Every failure this package raises deliberately is one of these, so a caller (or the CLI) can tell an orchestration failure it should report cleanly apart from an unexpected crash it should let propagate with a stack trace.
+ *
+ * All of them are thrown, never returned as a status: the orchestrator deliberately has no "skip this package and carry on" path. A workspace that can't be discovered, ordered, or bumped correctly would otherwise publish a partially-consistent set of packages, which is strictly worse than publishing nothing.
+ */
+declare class WorkspaceReleaseError extends Error {
+  constructor(message: string);
+}
+/** The workspace itself could not be read: no `pnpm-workspace.yaml`, no `packages` globs, an unreadable or malformed `package.json`, two packages claiming the same name, or a package sitting at the workspace root (which cannot be path-scoped -- see `discoverWorkspace`). */
+declare class WorkspaceDiscoveryError extends WorkspaceReleaseError {}
+/** The intra-workspace dependency graph contains a cycle, so no release order exists in which every package releases after its own dependencies. */
+declare class DependencyCycleError extends WorkspaceReleaseError {
+  /** The packages forming the cycle, in dependency order, with the first package repeated at the end so the loop reads end to end. */
+  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. */
+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. */
+declare class ReleaseConfigurationError extends WorkspaceReleaseError {}
+/** A git command the orchestrator runs itself (history filtering, dependency-bump commits, pushes) failed. Carries the exit code so callers can distinguish "configuration is missing" (exit 1) from real repository failures. */
+declare class GitCommandError extends WorkspaceReleaseError {
+  readonly exitCode: number | undefined;
+  constructor(args: readonly string[], cwd: string, exitCode: number | undefined, detail: string);
+}
+/** The workspace's git state does not support the release operation -- for example a detached HEAD, which names no branch that dependency-bump commits could be pushed to. */
+declare class WorkspaceStateError extends WorkspaceReleaseError {}
+//#endregion
+export { type AppliedDependencyBump, DEFAULT_PUBLISH_PLUGINS, type DependencyBump, type DependencyBumpSource, DependencyCycleError, type DependencyField, type DependencyGraph, type DependencyRangeShape, type DependencyRangeUpdate, GitCommandError, type PackageManifest, type PackageReleaseOutcome, type PublishPluginSpec, ReleaseConfigurationError, type ReleaseWorkspaceOptions, type ResolvedPublishPlugin, type ScopedPlugins, UnsupportedDependencyRangeError, type Workspace, type WorkspaceDependency, WorkspaceDiscoveryError, type WorkspacePackage, WorkspaceReleaseError, type WorkspaceReleaseOutcome, WorkspaceStateError, buildDependencyGraph, classifyDependencyRange, createScopedPlugins, discoverWorkspace, filterCommitsToDirectory, packageName, readManifest, releaseWorkspace, resolvePublishPlugins, topologicalOrder, updateDependencyRange, writeDependencyRange };

package/dist/index.d.ts

@@ -0,0 +1,259 @@
+import { AnalyzeCommitsContext, BranchSpec, GenerateNotesContext } from "semantic-release";
+//#region src/package-name.d.ts
+declare const packageName = "@exadev/semantic-release-workspace";
+//#endregion
+//#region src/manifest.d.ts
+/**
+ * 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.
+ */
+type DependencyField = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
+interface PackageManifest {
+  readonly name: string;
+  readonly version: string;
+  /** Only the fields actually present in the file, each mapping dependency name to its declared range. */
+  readonly dependencies: ReadonlyMap<DependencyField, ReadonlyMap<string, string>>;
+}
+declare function readManifest(path: string): Promise<PackageManifest>;
+/**
+ * Rewrites one dependency range in a manifest on disk.
+ *
+ * Deliberately re-reads the file rather than editing a copy held from discovery time: by the time a cross-package bump is applied, semantic-release's own `@semantic-release/npm` prepare step may already have rewritten `version` in this same file for an earlier package in the run. Writing back a manifest parsed before that would silently revert it.
+ */
+declare function writeDependencyRange(path: string, field: DependencyField, dependency: string, range: string): Promise<void>;
+//#endregion
+//#region src/workspace.d.ts
+interface WorkspacePackage {
+  readonly name: string;
+  readonly version: string;
+  /** 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. */
+  readonly relativeDirectory: string;
+  /** Path relative to the git repository's toplevel, always POSIX-separated. This is the base every `git log --name-only` path is compared against, because git reports changed paths relative to the repository root regardless of the directory a command runs from -- equal to `relativeDirectory` only when `pnpm-workspace.yaml` itself sits at the repository's toplevel. */
+  readonly repoRelativeDirectory: string;
+  readonly manifestPath: string;
+  readonly dependencies: ReadonlyMap<DependencyField, ReadonlyMap<string, string>>;
+}
+interface Workspace {
+  /** Absolute path to the directory holding `pnpm-workspace.yaml`. */
+  readonly root: string;
+  /** Every discovered package, ordered by directory so discovery is reproducible regardless of filesystem iteration order. */
+  readonly packages: readonly WorkspacePackage[];
+}
+/**
+ * Reads `pnpm-workspace.yaml` and every package manifest its globs match, producing the input to both the dependency graph and the per-package release runs.
+ *
+ * Nothing here knows anything about a particular repository's layout: the globs come from the workspace file, and the package names, versions, and dependency ranges come from the manifests those globs match. Pointing this at any pnpm workspace is the entire configuration.
+ */
+declare function discoverWorkspace(root: string): Promise<Workspace>;
+//#endregion
+//#region src/graph.d.ts
+/** One package's dependency on another package in the same workspace. */
+interface WorkspaceDependency {
+  /** The depending package's name. */
+  readonly dependent: string;
+  /** The depended-upon package's name. */
+  readonly dependency: string;
+  readonly field: DependencyField;
+  /** The range exactly as written in the dependent's manifest. */
+  readonly range: string;
+}
+interface DependencyGraph {
+  readonly packages: ReadonlyMap<string, WorkspacePackage>;
+  /** For each package, the workspace siblings it depends on. */
+  readonly dependencies: ReadonlyMap<string, readonly WorkspaceDependency[]>;
+  /** For each package, the workspace siblings that depend on it. */
+  readonly dependents: ReadonlyMap<string, readonly WorkspaceDependency[]>;
+}
+/**
+ * Builds the inter-package dependency graph from the manifests alone.
+ *
+ * A dependency on a package outside the workspace is not an edge: it neither constrains the release order nor gets rewritten when something here releases. A package that names itself becomes a self-edge, which `topologicalOrder` then reports as the one-package cycle it is, rather than being quietly dropped.
+ */
+declare function buildDependencyGraph(packages: readonly WorkspacePackage[]): DependencyGraph;
+/**
+ * Orders packages so every package appears after every workspace sibling it depends on, using Kahn's algorithm.
+ *
+ * Packages whose dependencies have all been placed are taken in name order, so the same workspace always produces the same order -- a release run that reorders itself between CI runs is impossible to reason about when something goes wrong halfway through.
+ *
+ * A cycle has no valid order at all, so it throws rather than picking one of the wrong answers. In a release context an arbitrary order is worse than a failure: it would publish a package whose sibling dependency range points at a version that does not exist yet.
+ */
+declare function topologicalOrder(graph: DependencyGraph): readonly string[];
+//#endregion
+//#region src/version-range.d.ts
+/**
+ * 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.
+ */
+type DependencyRangeUpdate =
+/** The range names a concrete version that has to be rewritten in the manifest. */
+{
+  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. */
+{
+  readonly kind: 'resolved-at-publish';
+} |
+/** A range naming no version at all (`*`, `x`, `latest`). Nothing to rewrite, and the published range is unaffected by the sibling's new version. */
+{
+  readonly kind: 'wildcard';
+};
+/**
+ * What a dependency range's own shape supports, independent of any particular version -- the classification that decides whether `updateDependencyRange` can succeed at all, split out so it can be checked for every workspace dependency edge before a release run starts, not just when the range's sibling actually releases.
+ */
+type DependencyRangeShape = {
+  readonly kind: 'rewritable';
+  readonly workspacePrefixed: boolean;
+  readonly comparator: string;
+} | {
+  readonly kind: 'resolved-at-publish';
+} | {
+  readonly kind: 'wildcard';
+};
+/**
+ * Classifies a dependency range's shape, throwing `UnsupportedDependencyRangeError` for anything this tool cannot rewrite with confidence: a compound range (`>=1.0.0 <2.0.0`), a union (`1.x || 2.x`), a `catalog:` reference whose real version lives in `pnpm-workspace.yaml`, an `npm:` alias, a git or tarball URL. Guessing at those would either corrupt the range or silently leave it pointing at a version that no longer exists in the workspace, and a stale published range is exactly the divergence this tool exists to prevent.
+ *
+ * This never needs the version a sibling is releasing: every case above depends only on the shape of `current` itself, which is what lets `releaseWorkspace` validate every workspace dependency edge up front, before any package has published anything, rather than discovering an unsupported range only when the first dependency it names happens to release.
+ */
+declare function classifyDependencyRange(current: string): DependencyRangeShape;
+/**
+ * Computes what a dependency range on a workspace sibling becomes once that sibling releases `version`, by classifying the range's shape and then, for a rewritable shape, substituting `version` in place of the version it currently names.
+ */
+declare function updateDependencyRange(current: string, version: string): DependencyRangeUpdate;
+//#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.
+ */
+interface DependencyBump {
+  readonly dependency: string;
+  readonly version: string;
+  /** The range as it now stands in the dependent's manifest -- the new concrete range for `rewritten`, the untouched `workspace:` range for `resolved-at-publish`. */
+  readonly range: string;
+  readonly kind: 'rewritten' | 'resolved-at-publish';
+}
+/** 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[];
+}
+/** 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. */
+declare const DEFAULT_PUBLISH_PLUGINS: readonly PublishPluginSpec[];
+interface ScopedPlugins {
+  readonly analyzeCommits: (pluginConfig: Record<string, unknown>, context: AnalyzeCommitsContext & {
+    cwd: string;
+  }) => Promise<string | false | undefined>;
+  readonly generateNotes: (pluginConfig: Record<string, unknown>, context: GenerateNotesContext & {
+    cwd: string;
+  }) => Promise<string | false | undefined>;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+declare function createScopedPlugins(scope: {
+  readonly pkg: WorkspacePackage;
+  readonly analyzeCommitsConfig: Record<string, unknown>;
+  readonly generateNotesConfig: Record<string, unknown>;
+  readonly bumps: DependencyBumpSource;
+}): ScopedPlugins;
+/**
+ * Keeps a commit for the package when any path it changed lies under the package's directory. The trailing-slash prefix comparison stops `packages/a` from matching `packages/abc/x`.
+ *
+ * A commit missing from the changed-paths map is kept rather than dropped: it is inside the package's release range (semantic-release put it there), so a failure to parse its file list must not silently swallow a release. Absent evidence errs towards publishing, which is the visible direction for a release tool.
+ */
+declare function filterCommitsToDirectory<T extends {
+  readonly hash: string;
+}>(commits: readonly T[], changedPaths: ReadonlyMap<string, ReadonlySet<string>>, directory: string): readonly T[];
+/** A publish plugin entry with its module name resolved to an absolute path, so semantic-release loads the workspace's installed plugins regardless of the package directory it runs from. */
+type ResolvedPublishPlugin = [string, Record<string, unknown>];
+declare function resolvePublishPlugins(specs: readonly PublishPluginSpec[], workspaceRoot: string, options: {
+  readonly requireGitPlugin: boolean;
+}): readonly ResolvedPublishPlugin[];
+//#endregion
+//#region src/release.d.ts
+interface ReleaseWorkspaceOptions {
+  /** Directory holding the workspace's `pnpm-workspace.yaml`. Defaults to the process working directory. */
+  readonly root?: string;
+  /** Environment for the per-package semantic-release runs. Defaults to `process.env`; passing a copy lets tests and embedders control the CI detection semantic-release performs on it. */
+  readonly env?: NodeJS.ProcessEnv;
+  /** Passed straight through to every per-package semantic-release run: analysis runs, nothing is published, tagged, committed, or pushed. */
+  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. */
+  readonly plugins?: readonly PublishPluginSpec[];
+  /** 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. */
+  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;
+}
+/** 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 {
+  readonly dependent: string;
+  /** Which manifest field held the range that was rewritten. */
+  readonly field: DependencyField;
+}
+interface 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[];
+}
+interface WorkspaceReleaseOutcome {
+  /** The topological order the packages were released in. */
+  readonly order: readonly string[];
+  readonly packages: readonly PackageReleaseOutcome[];
+}
+/**
+ * Releases every package in a pnpm workspace with independent versions, in dependency order.
+ *
+ * For each package, in topological order: run semantic-release's programmatic API with `cwd` scoped to the package directory, a `name@version` tag format to keep each package's tags distinct in the one shared tag namespace, and inline `analyzeCommits`/`generateNotes` plugins that filter the release range's commits down to the package's own directory before delegating to the standard plugins. When a package releases, every workspace package that depends on it and has not run yet gets its dependency range rewritten in its manifest and committed immediately -- before its own turn, so its commit analysis and its published manifest both see the new range.
+ */
+declare function releaseWorkspace(options?: ReleaseWorkspaceOptions): Promise<WorkspaceReleaseOutcome>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Every failure this package raises deliberately is one of these, so a caller (or the CLI) can tell an orchestration failure it should report cleanly apart from an unexpected crash it should let propagate with a stack trace.
+ *
+ * All of them are thrown, never returned as a status: the orchestrator deliberately has no "skip this package and carry on" path. A workspace that can't be discovered, ordered, or bumped correctly would otherwise publish a partially-consistent set of packages, which is strictly worse than publishing nothing.
+ */
+declare class WorkspaceReleaseError extends Error {
+  constructor(message: string);
+}
+/** The workspace itself could not be read: no `pnpm-workspace.yaml`, no `packages` globs, an unreadable or malformed `package.json`, two packages claiming the same name, or a package sitting at the workspace root (which cannot be path-scoped -- see `discoverWorkspace`). */
+declare class WorkspaceDiscoveryError extends WorkspaceReleaseError {}
+/** The intra-workspace dependency graph contains a cycle, so no release order exists in which every package releases after its own dependencies. */
+declare class DependencyCycleError extends WorkspaceReleaseError {
+  /** The packages forming the cycle, in dependency order, with the first package repeated at the end so the loop reads end to end. */
+  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. */
+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. */
+declare class ReleaseConfigurationError extends WorkspaceReleaseError {}
+/** A git command the orchestrator runs itself (history filtering, dependency-bump commits, pushes) failed. Carries the exit code so callers can distinguish "configuration is missing" (exit 1) from real repository failures. */
+declare class GitCommandError extends WorkspaceReleaseError {
+  readonly exitCode: number | undefined;
+  constructor(args: readonly string[], cwd: string, exitCode: number | undefined, detail: string);
+}
+/** The workspace's git state does not support the release operation -- for example a detached HEAD, which names no branch that dependency-bump commits could be pushed to. */
+declare class WorkspaceStateError extends WorkspaceReleaseError {}
+//#endregion
+export { type AppliedDependencyBump, DEFAULT_PUBLISH_PLUGINS, type DependencyBump, type DependencyBumpSource, DependencyCycleError, type DependencyField, type DependencyGraph, type DependencyRangeShape, type DependencyRangeUpdate, GitCommandError, type PackageManifest, type PackageReleaseOutcome, type PublishPluginSpec, ReleaseConfigurationError, type ReleaseWorkspaceOptions, type ResolvedPublishPlugin, type ScopedPlugins, UnsupportedDependencyRangeError, type Workspace, type WorkspaceDependency, WorkspaceDiscoveryError, type WorkspacePackage, WorkspaceReleaseError, type WorkspaceReleaseOutcome, WorkspaceStateError, buildDependencyGraph, classifyDependencyRange, createScopedPlugins, discoverWorkspace, filterCommitsToDirectory, packageName, readManifest, releaseWorkspace, resolvePublishPlugins, topologicalOrder, updateDependencyRange, writeDependencyRange };