@williamthorsen/release-kit 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 All notable changes to this project will be documented in this file.
 
+## [release-kit-v5.1.0] - 2026-04-30
+
+### Bug fixes
+
+- Make publish's clean-tree safety gate reachable (#311)
+
+  Fixes an issue where `release-kit publish` failed with pnpm's "working tree is dirty" error on a clean tree whenever `releaseNotes.shouldInjectIntoReadme: true` was configured. release-kit injects the release notes into the package README before invoking `pnpm publish`, so pnpm's own working-tree check fired on a tree release-kit had just dirtied — even though the user's tree was clean at command start.
+
+- Make `--set-version` + `project` rejection explicit (#319)
+
+  Improves the error users see when invoking `release-kit prepare --set-version` with a `project` block configured. The combination is still rejected — as before — but now produces a single, project-aware message ("--set-version cannot be combined with a project release…") rather than the previous two-step chain (`--set-version requires --only`, then `--only cannot be combined with a project release` after the user added `--only`).
+
+- Reject `--only` that would strand excluded dependents (#321)
+
+  Fixes a silent footgun in `release-kit prepare --only=...`: an excluded internal dependent with its own changes would be left unreleased with no runtime signal, even though the targeted workspace it depends on was being released. The command now rejects such invocations up front, naming every excluded dependent whose changes would be stranded.
+
+- Order prerelease versions correctly in changelog sort (#334)
+
+  Fixes a latent issue in `@williamthorsen/release-kit` where prerelease version tags (e.g., `1.2.3-alpha`, `1.2.3-rc.1`) were sorted as if their prerelease component were absent, causing them to appear in the wrong position relative to releases sharing the same base version. Changelog entries are now ordered per SemVer §11: prerelease versions precede the corresponding release (`1.2.3-alpha < 1.2.3`), build metadata is ignored for ordering, and entries that fail SemVer validation sort deterministically to the bottom of the list rather than collapsing into mid-list positions.
+
+### Documentation
+
+- Document tag prefix collisions as general rule (#320)
+
+  Documents the strict-prefix tag-prefix collision rule as a general validation rule that applies to every release-kit consumer declaring more than one tag prefix: across active workspaces, declared legacy identities, retired packages, and the optional `project` block. Previously, the rule appeared only inside the `Project releases` validation list.
+
+### Features
+
+- Add `project` block for project-level release stage (#317)
+
+  Adds support for monorepos that ship a single combined deliverable to version, changelog, and release-note the project itself rather than only its constituent workspaces.
+
+- Publish JSON Schema for `.meta/label-map.json` (#325)
+
+  Adds a JSON Schema for `.meta/label-map.json` to release-kit, packaged at `packages/release-kit/schemas/label-map.json` and shipped to npm. Consumers reference it via the stable raw URL pattern `https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json` — the same shape audit-deps already uses.
+
+- Label prepare errors with the failing stage (#326)
+
+  Adds stage attribution to errors thrown during `release-kit prepare`. Errors from per-workspace bumps and changelog generation, the project release stage, and the post-release format command now begin with a stage label that identifies the failing stage and (where relevant) the affected workspace.
+
+- Make `--force` and `--bump` orthogonal (#328)
+
+  Decouples `--force` and `--bump` so each flag has a single responsibility, and unifies skip semantics across the per-workspace and project pipelines.
+
+### Refactoring
+
+- Convert prepare results to discriminated unions (#330)
+
+  Tightens `ProjectPrepareResult` and `WorkspacePrepareResult` from flat-with-optionals types into status-discriminated unions, so consumers that have already narrowed on `status === 'released'` no longer need to re-guard each release-only field with `!== undefined`. The four new sub-types (`ReleasedProjectResult`, `ReleasedWorkspaceResult`, `SkippedProjectResult`, `SkippedWorkspaceResult`) are exported from the package so callers can name the variants directly. Renderer output is byte-identical to before.
+
+- Split changelog.json generation into layered helpers (#333)
+
+  Reorganises `changelog.json` generation in `@williamthorsen/release-kit` so that producing entries (running git-cliff and shaping the output) is fully separated from persisting them (reading, merging, and writing the file). Removes the silent-discard parse-failure path at the project release stage by no longer reading the root `changelog.json` before overwriting it. Sharpens dry-run mode: `git-cliff` now runs even on dry-run so configuration mistakes surface in preview rather than only on a real release. Trims the public `index.ts` barrel from ~50 re-exports to the two type names actually consumed by external configs.
+
+### Tests
+
+- Cover untested project-release and config branches (#329)
+
+  Closes four mechanical test-coverage gaps in the project-level release surfaces flagged in the test review of #308. New cases exercise the `(no previous release found)` rendering for released projects, the unparseable-commit warning block on the released-project rendering path, the `readFileSync` I/O failure path in `readRootPackageVersion`, and the contributing-paths invariant in `releasePrepareProject`. No production code changes — these are pure-render and pure-derivation branches that previously had no test exercising them.
+
 ## [release-kit-v5.0.0] - 2026-04-23
 
 ### Bug fixes

package/README.md

@@ -5,61 +5,49 @@ Version-bumping and changelog-generation toolkit for release workflows.
 Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs with `git-cliff`.
 
 <!-- section:release-notes -->
-## Release notes — v5.0.0 (2026-04-23)
+## Release notes — v5.1.0 (2026-04-30)
 
 ### Bug fixes
 
-- Derive monorepo tag prefix from unscoped `package.json` name (#278)
+- Make publish's clean-tree safety gate reachable (#311)
 
-  Fixes a long-standing mismatch between a monorepo workspace's directory basename and its publishable package identity.
+  Fixes an issue where `release-kit publish` failed with pnpm's "working tree is dirty" error on a clean tree whenever `releaseNotes.shouldInjectIntoReadme: true` was configured. release-kit injects the release notes into the package README before invoking `pnpm publish`, so pnpm's own working-tree check fired on a tree release-kit had just dirtied — even though the user's tree was clean at command start.
 
-### Features
-
-- Improve release-notes rendering quality (#261)
-
-  Improves the quality of release notes and CHANGELOG entries generated by release-kit. Release notes sections are now ordered by work-type priority (bug fixes first, then features, then internal), and each bullet now includes the commit body text for context that a one-line title cannot provide. Refactoring commits are now excluded from the release notes.
-
-- Scaffold release-notes injection and check markers (#267)
-
-  Adds release-notes injection to the configs scaffolded by `release-kit init`, so newly-onboarded consumers get the feature without having to discover or toggle the flag. The release-kit readyup kit gains a check that warns when a consumer's README is missing the marker pair where injected notes should land — without those markers, injection silently prepends to the top of the file, pushing the README's title below the notes.
-
-- Split GitHub Release creation into its own workflow (#272)
-
-  Splits GitHub Release creation out of release-kit publish into a dedicated release-kit create-github-release CLI command and a matching reusable GitHub Actions workflow. Consumers that do not publish to npm can now create Releases independently, and the contents: write permission required to create a Release no longer leaks into the publish path.
+- Make `--set-version` + `project` rejection explicit (#319)
 
-- Replace --only with --tags on release-kit publish and push (#273)
+  Improves the error users see when invoking `release-kit prepare --set-version` with a `project` block configured. The combination is still rejected — as before — but now produces a single, project-aware message ("--set-version cannot be combined with a project release…") rather than the previous two-step chain (`--set-version requires --only`, then `--only cannot be combined with a project release` after the user added `--only`).
 
-  `release-kit publish` and `release-kit push` now filter by full tag name via `--tags=<tag1,tag2>` instead of workspace directory name via `--only=<dir>`, matching the shape already used by `create-github-release`. Callers pass the tag they care about (e.g., `core-v1.3.0`) directly, with no translation step back to the publishing workspace's directory name. The reusable workflow gains an optional `tags:` input, and the internal `publish.yaml` caller now passes `tags: ${{ github.ref_name }}`, making the publish scope explicit rather than relying on the single-tag fetch default of `actions/checkout@v6`.
+- Reject `--only` that would strand excluded dependents (#321)
 
-- Apply pre-1.0 bump rule and add --set-version CLI escape hatch (#274)
+  Fixes a silent footgun in `release-kit prepare --only=...`: an excluded internal dependent with its own changes would be left unreleased with no runtime signal, even though the targeted workspace it depends on was being released. The command now rejects such invocations up front, naming every excluded dependent whose changes would be stranded.
 
-  Fixes an issue where a `feat!` commit on a pre-1.0 package would accidentally promote it to `1.0.0`. At pre-1.0 (`0.y.z`), a `'major'` release type now collapses to a minor bump. Adds a validated `--set-version <semver>` CLI flag on `release-kit prepare` that bypasses commit-derived bump logic and writes a specific version.
+- Order prerelease versions correctly in changelog sort (#334)
 
-- Scaffold audit.yaml workflow from audit-deps init (#277)
+  Fixes a latent issue in `@williamthorsen/release-kit` where prerelease version tags (e.g., `1.2.3-alpha`, `1.2.3-rc.1`) were sorted as if their prerelease component were absent, causing them to appear in the wrong position relative to releases sharing the same base version. Changelog entries are now ordered per SemVer §11: prerelease versions precede the corresponding release (`1.2.3-alpha < 1.2.3`), build metadata is ignored for ordering, and entries that fail SemVer validation sort deterministically to the bottom of the list rather than collapsing into mid-list positions.
 
-  Adds GitHub Actions workflow scaffolding to `audit-deps init`. Running the command now writes both `.config/audit-deps.config.json` and `.github/workflows/audit.yaml` in the target repo, so that consumers no longer have to copy the canonical caller workflow by hand from this repo. The workflow content is shipped as a bundled template that ships to npm, and the repo's own workflow is kept byte-identical to that template via a consistency test — the canonical workflow cannot silently drift from what is published.
+### Features
 
-- Add migrate-tag-prefixes.sh migration tool (#282)
+- Add `project` block for project-level release stage (#317)
 
-  Adds a one-shot migration tool, `migrate-tag-prefixes.sh`, shipped inside the release-kit package. The tool creates additive annotated-tag aliases under release-kit's new unscoped-package-name prefix that point at the same commits as the previous directory-basename tags, bridging the gap so post-migration `getCommitsSinceTarget` calls can resolve prior releases.
+  Adds support for monorepos that ship a single combined deliverable to version, changelog, and release-note the project itself rather than only its constituent workspaces.
 
-- Add legacyTagPrefixes config field (#289)
+- Publish JSON Schema for `.meta/label-map.json` (#325)
 
-  Replaces the v4 → v5 tag-prefix migration mechanism (tag aliasing via `migrate-tag-prefixes.sh`) with a declarative `legacyTagPrefixes` config field. release-kit now searches for both legacy and modern prefixes when generating changelogs.
+  Adds a JSON Schema for `.meta/label-map.json` to release-kit, packaged at `packages/release-kit/schemas/label-map.json` and shipped to npm. Consumers reference it via the stable raw URL pattern `https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json` — the same shape audit-deps already uses.
 
-  Adds a companion `release-kit show-tag-prefixes` CLI command that renders a per-workspace table of derived and declared legacy prefixes, flags cross-workspace collisions, and surfaces undeclared candidate prefixes with a copy-pasteable config snippet. `release-kit prepare` gains a one-line hint pointing operators to `show-tag-prefixes` when a workspace has no baseline tag but the repo contains candidate-shaped tags.
+- Label prepare errors with the failing stage (#326)
 
-- Replace `legacyTagPrefixes` with `legacyIdentities` (#297)
+  Adds stage attribution to errors thrown during `release-kit prepare`. Errors from per-workspace bumps and changelog generation, the project release stage, and the post-release format command now begin with a stage label that identifies the failing stage and (where relevant) the affected workspace.
 
-  Replaces the per-workspace `legacyTagPrefixes: string[]` field with `legacyIdentities: LegacyIdentity[]`, a structured array of complete `(name, tagPrefix)` historical snapshots. Each legacy identity is now a self-consistent record of what a workspace used to be called and how its tags used to be prefixed, so a workspace that has been renamed (npm name change, tag-prefix change, or both) carries one entry per prior identity.
+- Make `--force` and `--bump` orthogonal (#328)
 
-- Add `retiredPackages` repo-level config field (#299)
+  Decouples `--force` and `--bump` so each flag has a single responsibility, and unifies skip semantics across the per-workspace and project pipelines.
 
-  Adds support for declaring packages that once lived in this repo but have been extracted or removed, so their historical tag prefixes (e.g., `preflight-v*` from the extracted `readyup` project) no longer surface as "Undeclared tag prefixes" in `release-kit show-tag-prefixes`. Declared retired packages are acknowledged as real history but never consulted for baseline lookup or changelog attribution — they complement `workspaces[].legacyIdentities`, which is used when a workspace still exists under a new identity.
+### Documentation
 
-- Add release-notes preview generator to `release-kit prepare` (#302)
+- Document tag prefix collisions as general rule (#320)
 
-  Adds the ability to generate release notes when running `release-kit prepare`. The `--with-release-notes` option enables the generation of per-workspace preview files so authors can verify release-note injection before publishing.  Injected release notes are also now prefixed with a `## Release notes — v{version} ({date})` heading to add missing context to the README.
+  Documents the strict-prefix tag-prefix collision rule as a general validation rule that applies to every release-kit consumer declaring more than one tag prefix: across active workspaces, declared legacy identities, retired packages, and the optional `project` block. Previously, the rule appeared only inside the `Project releases` validation list.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -172,6 +160,7 @@ The config file supports both `export default config` and `export const config =
 | `scopeAliases`    | `Record<string, string>`         | Maps shorthand scope names to canonical names in commits                                                                      |
 | `workTypes`       | `Record<string, WorkTypeConfig>` | Work type definitions, merged with defaults by key                                                                            |
 | `retiredPackages` | `RetiredPackage[]`               | Packages that once lived in this repo but have been extracted or removed; suppresses undeclared-tag-prefix warnings           |
+| `project`         | `ProjectConfig`                  | Opt-in project-level release block. Declaring `project: {}` (even empty) enables a project-release stage in `prepare`         |
 
 All fields are optional.
 
@@ -222,10 +211,95 @@ Validation rules:
 - `successor` is optional; if present, it must be a non-empty string.
 - Full-tuple `(name, tagPrefix)` duplicates within `retiredPackages` are rejected.
 - Two entries sharing the same `tagPrefix` but different `name`s are accepted — this documents a package renamed within the repo before being retired.
-- A `tagPrefix` that collides with an active workspace's derived prefix or any declared `workspaces[].legacyIdentities[].tagPrefix` is rejected. A retired prefix cannot also be current or legacy.
 
 `show-tag-prefixes` currently does not render a dedicated "Retired packages" section (deferred). Declaring a retired entry is verifiable by confirming that its `tagPrefix` stops appearing under "Undeclared tag prefixes" in the `show-tag-prefixes` output.
 
+### Tag prefix collisions
+
+Tag prefixes from distinct owners must not be identical or be a strict prefix of one another. An owner is one of:
+
+- An active workspace, comprising its derived `tagPrefix` plus any declared `legacyIdentities[].tagPrefix`. Identities of the same workspace are one owner, so their prefixes are allowed to overlap (this represents the same package across renames).
+- A `retiredPackages[]` entry (one owner per entry).
+- The `project` block, when configured.
+
+release-kit resolves baseline tags via `git describe --match=<prefix>*`, so a strict-prefix overlap between distinct owners would cause that glob to return cross-matches against the wrong owner's history. For example, a project prefix of `v` collides with a workspace prefix of `vue-helpers-v`, since `git describe --match=v*` would return both project tags and `vue-helpers` tags.
+
+The rule is enforced at config load; the resulting error identifies both colliding declarations.
+
+### Project releases
+
+Some monorepos ship a single combined deliverable — a Chrome extension, a CLI binary, a packaged desktop app — for which the per-workspace tags and changelogs alone do not describe what the user actually receives. Declare the optional `project` block to add a project-level release stage that runs alongside the per-workspace pipeline.
+
+```typescript
+import type { ReleaseKitConfig } from '@williamthorsen/release-kit';
+
+const config: ReleaseKitConfig = {
+  // Empty object is enough to opt in. Every non-excluded workspace contributes.
+  project: {},
+};
+
+export default config;
+```
+
+When configured, each `release-kit prepare` run additionally:
+
+- Computes commits since the last project tag (`<tagPrefix><version>`), filtered to the union of every contributing workspace's paths.
+- Bumps the root `package.json`'s `version` field using the same bump-derivation rules as workspaces (or the `--bump=...` override).
+- Regenerates the root `./CHANGELOG.md` via `git-cliff`, scoped to the project's `tagPrefix` and contributing paths.
+- Emits `./.meta/changelog.json` (when `changelogJson.enabled`).
+- With `--with-release-notes`, additionally emits `./docs/RELEASE_NOTES.v<version>.md`.
+- Appends the project tag to `tmp/.release-tags` so `release-kit commit` and `release-kit tag` pick it up alongside per-workspace tags.
+
+If no contributing workspace has commits since the last project tag, the project release is silently skipped — same behavior as a per-workspace skip.
+
+#### `ProjectConfig`
+
+```typescript
+interface ProjectConfig {
+  tagPrefix?: string; // Defaults to 'v'
+}
+```
+
+| Field       | Default | Description                                                          |
+| ----------- | ------- | -------------------------------------------------------------------- |
+| `tagPrefix` | `'v'`   | Prefix for project tags. The full tag is `${tagPrefix}${newVersion}` |
+
+Contributing workspaces are implicit: every non-excluded discovered workspace contributes. There is no field to override the contributing set in this initial release; if a future consumer needs to release a workspace as a component but exclude it from the project release, that override can be added then.
+
+Validation rules:
+
+- The root `package.json` must exist and declare a `version` field. release-kit reports an error at config-load time if either is missing.
+- The `project` block is rejected in single-package mode (the implicit "all non-excluded workspaces contribute" rule is meaningless in a single-package repo).
+- Unknown fields inside `project` are rejected.
+
+CLI flag interactions:
+
+- `--dry-run` previews project artifacts alongside workspace artifacts; no files are written.
+- `--bump=major|minor|patch` propagates to the project release as a level chooser. It does not trigger a release on its own when there are no commits or no bump-worthy commits.
+- `--force` runs the project release even when no commits or no bump-worthy commits exist since the last project tag. Defaults to patch when `--bump` is not given; combine with `--bump=X` to release at a different level.
+- `--only` is rejected with an error when `project` is configured. `--only` is a surgical, single-workspace operation; combining it with a project release that rolls up every contributing workspace would create ambiguous semantics. To release a single workspace, use a config without a `project` block, or run a full `prepare` (no `--only`) to include the project release.
+- `--set-version` is rejected with an error when `project` is configured. `--set-version` operates on a single workspace, but a project release rolls up every contributing workspace; the two semantics don't compose. To use `--set-version`, run on a config without a `project` block.
+
+`--bump` and `--force` are orthogonal: `--bump` is purely a level chooser; `--force` is purely a release trigger. Examples:
+
+```sh
+# Release every target at its natural bump level (no flags).
+release-kit prepare
+
+# Force a release even when no bump-worthy commits exist; defaults to patch
+# per target, with each target keeping its natural bump if one is derivable.
+release-kit prepare --force
+
+# Force a release at a uniform level across every releasing target.
+release-kit prepare --force --bump=minor
+
+# --bump=X alone is a level chooser, NOT a trigger. If a target has no
+# bump-worthy commits, it skips with a "Pass --force..." reason. If it has
+# bump-worthy commits, the override applies. (Behavioral change from earlier
+# release-kit versions, where --bump=X alone would force a release.)
+release-kit prepare --bump=minor
+```
+
 ### `VersionPatterns`
 
 Defines which commit types trigger major or minor bumps. Any recognized type not listed defaults to a patch bump.
@@ -277,15 +351,15 @@ Release-notes sections are rendered in the declaration order of the merged work-
 
 Run release preparation with automatic workspace discovery.
 
-| Flag                         | Description                                                                                                  |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `--dry-run`                  | Preview changes without writing files                                                                        |
-| `--bump=major\|minor\|patch` | Override the bump type for all workspaces                                                                    |
-| `--set-version=X.Y.Z`        | Set an explicit canonical semver version; bypasses commit-derived bumps. Requires `--only` in monorepo mode. |
-| `--force`                    | Bypass the "no commits since last tag" check (requires `--bump`)                                             |
-| `--only=name1,name2`         | Only process the named workspaces (monorepo only)                                                            |
-| `--with-release-notes`       | Write per-workspace release-notes previews under `{workspacePath}/docs/`                                     |
-| `--help`, `-h`               | Show help                                                                                                    |
+| Flag                         | Description                                                                                                                                        |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--dry-run`                  | Preview changes without writing files                                                                                                              |
+| `--bump=major\|minor\|patch` | Override the bump type for all workspaces                                                                                                          |
+| `--set-version=X.Y.Z`        | Set an explicit canonical semver version; bypasses commit-derived bumps. Requires `--only` in monorepo mode.                                       |
+| `--force`                    | Release even when no commits or no bump-worthy commits exist since the last tag (defaults to patch; combine with `--bump=X` for a different level) |
+| `--only=name1,name2`         | Only process the named workspaces (monorepo only; rejected when a `project` block is configured)                                                   |
+| `--with-release-notes`       | Write per-workspace release-notes previews under `{workspacePath}/docs/`                                                                           |
+| `--help`, `-h`               | Show help                                                                                                                                          |
 
 Workspace names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
 
@@ -385,6 +459,26 @@ Manage GitHub label definitions via config-driven YAML files.
 
 `init` scaffolds `.config/sync-labels.config.ts` with auto-detected workspace scope labels and a `.github/workflows/sync-labels.yaml` caller workflow, then generates `.github/labels.yaml`. `generate` reads the config and writes `.github/labels.yaml`. `sync` triggers the workflow remotely — it requires the `gh` CLI and an existing workflow file.
 
+#### Published JSON Schema for `.meta/label-map.json`
+
+release-kit publishes a JSON Schema for `.meta/label-map.json` — a separate, generic data file that maps commit-prefix scopes and types to GitHub label names. The schema lives at `packages/release-kit/schemas/label-map.json` in this repo and is reachable via the stable raw URL:
+
+```
+https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json
+```
+
+Consumers reference it from the top of their `.meta/label-map.json`:
+
+```json
+{
+  "$schema": "https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json",
+  "types": { "feat": "feature", "fix": "fix" },
+  "scopes": { "audit": "scope:audit" }
+}
+```
+
+release-kit publishes the schema only; it does not generate `.meta/label-map.json`. Generation requires commit-prefix knowledge that lives outside release-kit (in agent-conventions tooling), and is owned by those consumers.
+
 ## GitHub Actions workflow
 
 The `init` command scaffolds a release workflow at `.github/workflows/release.yaml` that delegates to a reusable release workflow. The scaffolded workflow accepts these inputs:

package/dist/esm/.cache

@@ -1 +1 @@
-4493cd8b695da653fc9ae7a81c0916cc0cb92c9acf3d560433b18cdd74f945a4
+fca70d83414ef35352e152c9e916f24705c93c5556b14c16388a5b791752f075

package/dist/esm/assertCleanWorkingTree.js

@@ -6,7 +6,7 @@ function assertCleanWorkingTree() {
   }).trim();
   if (status.length > 0) {
     throw new Error(
-      "Working tree has uncommitted changes. Commit or stash them before running prepare, or use --no-git-checks to bypass this check."
+      "Working tree has uncommitted changes. Commit or stash them, or use --no-git-checks to bypass this check."
     );
   }
 }

package/dist/esm/bin/release-kit.js

@@ -183,7 +183,7 @@ Publish packages that have release tags on HEAD.
 
 Options:
   --dry-run              Preview without publishing
-  --no-git-checks        Skip git checks (pnpm only)
+  --no-git-checks        Skip the clean-working-tree check
   --tags=tag1,tag2       Only publish the named tags (comma-separated, full tag names)
   --provenance           Generate provenance statement (requires OIDC, not supported by classic yarn)
   --help, -h             Show this help message

package/dist/esm/buildChangelogEntries.d.ts

@@ -0,0 +1,3 @@
+import type { GenerateChangelogOptions } from './generateChangelogs.ts';
+import type { ChangelogEntry, ReleaseConfig } from './types.ts';
+export declare function buildChangelogEntries(config: Pick<ReleaseConfig, 'cliffConfigPath' | 'changelogJson'>, tag: string, options?: GenerateChangelogOptions): ChangelogEntry[];

package/dist/esm/{generateChangelogJson.js → buildChangelogEntries.js}

@@ -1,16 +1,11 @@
 import { execFileSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import stringify from "json-stringify-pretty-compact";
-import { extractVersion, isChangelogEntry } from "./changelogJsonUtils.js";
+import { join } from "node:path";
+import { extractVersion } from "./changelogJsonUtils.js";
 import { resolveCliffConfigPath } from "./resolveCliffConfigPath.js";
 import { isRecord, isUnknownArray } from "./typeGuards.js";
-function generateChangelogJson(config, changelogPath, tag, dryRun, options) {
-  const outputFile = join(changelogPath, config.changelogJson.outputPath);
-  if (dryRun) {
-    return [outputFile];
-  }
+function buildChangelogEntries(config, tag, options) {
   const resolvedConfigPath = resolveCliffConfigPath(config.cliffConfigPath, import.meta.url);
   let cliffConfigPath = resolvedConfigPath;
   let tempDir;
@@ -33,15 +28,10 @@ function generateChangelogJson(config, changelogPath, tag, dryRun, options) {
     });
     const releases = parseCliffContext(contextJson);
     const devOnlySections = new Set(config.changelogJson.devOnlySections);
-    const entries = transformReleases(releases, devOnlySections);
-    const existingEntries = readExistingEntries(outputFile);
-    const merged = mergeEntries(entries, existingEntries);
-    mkdirSync(dirname(outputFile), { recursive: true });
-    writeFileSync(outputFile, stringify(merged, { maxLength: 100 }) + "\n", "utf8");
-    return [outputFile];
+    return transformReleases(releases, devOnlySections);
   } catch (error) {
     throw new Error(
-      `Failed to generate changelog JSON for ${outputFile}: ${error instanceof Error ? error.message : String(error)}`
+      `Failed to build changelog entries for tag ${tag}: ${error instanceof Error ? error.message : String(error)}`
     );
   } finally {
     if (tempDir !== void 0) {
@@ -49,25 +39,6 @@ function generateChangelogJson(config, changelogPath, tag, dryRun, options) {
     }
   }
 }
-function generateSyntheticChangelogJson(config, changelogPath, newVersion, date, propagatedFrom, dryRun) {
-  const outputFile = join(changelogPath, config.changelogJson.outputPath);
-  if (dryRun) {
-    return [outputFile];
-  }
-  const items = propagatedFrom.map((dep) => ({
-    description: `Bumped \`${dep.packageName}\` to ${dep.newVersion}`
-  }));
-  const entry = {
-    version: newVersion,
-    date,
-    sections: [{ title: "Dependency updates", audience: "dev", items }]
-  };
-  const existingEntries = readExistingEntries(outputFile);
-  const merged = mergeEntries([entry], existingEntries);
-  mkdirSync(dirname(outputFile), { recursive: true });
-  writeFileSync(outputFile, stringify(merged, { maxLength: 100 }) + "\n", "utf8");
-  return [outputFile];
-}
 function parseCliffContext(json) {
   const parsed = JSON.parse(json);
   if (!isUnknownArray(parsed)) {
@@ -183,50 +154,6 @@ function extractBody(message) {
   }
   return lines.slice(start, end).join("\n").trim();
 }
-function readExistingEntries(filePath) {
-  if (!existsSync(filePath)) {
-    return [];
-  }
-  try {
-    const content = readFileSync(filePath, "utf8");
-    const parsed = JSON.parse(content);
-    if (!isUnknownArray(parsed)) {
-      return [];
-    }
-    return parsed.filter(isChangelogEntry);
-  } catch (error) {
-    console.warn(
-      `Warning: could not parse existing ${filePath}: ${error instanceof Error ? error.message : String(error)}; treating as empty`
-    );
-    return [];
-  }
-}
-function mergeEntries(newEntries, existingEntries) {
-  const versionMap = /* @__PURE__ */ new Map();
-  for (const entry of existingEntries) {
-    versionMap.set(entry.version, entry);
-  }
-  for (const entry of newEntries) {
-    versionMap.set(entry.version, entry);
-  }
-  return [...versionMap.values()].sort((a, b) => compareVersionsDescending(a.version, b.version));
-}
-function parseVersionParts(version) {
-  return version.split(".").map((s) => {
-    const n = Number(s);
-    return Number.isNaN(n) ? 0 : n;
-  });
-}
-function compareVersionsDescending(a, b) {
-  const partsA = parseVersionParts(a);
-  const partsB = parseVersionParts(b);
-  for (let i = 0; i < 3; i++) {
-    const diff = (partsB[i] ?? 0) - (partsA[i] ?? 0);
-    if (diff !== 0) return diff;
-  }
-  return 0;
-}
 export {
-  generateChangelogJson,
-  generateSyntheticChangelogJson
+  buildChangelogEntries
 };

package/dist/esm/buildDependencyGraph.d.ts

@@ -3,5 +3,6 @@ export interface DependencyGraph {
     packageNameToDir: Map<string, string>;
     dirToPackageName: Map<string, string>;
     dependentsOf: Map<string, WorkspaceConfig[]>;
+    dependenciesOf: Map<string, Set<string>>;
 }
 export declare function buildDependencyGraph(workspaces: readonly WorkspaceConfig[]): DependencyGraph;

package/dist/esm/buildDependencyGraph.js

@@ -6,6 +6,7 @@ function buildDependencyGraph(workspaces) {
   const packageNameToDir = /* @__PURE__ */ new Map();
   const dirToPackageName = /* @__PURE__ */ new Map();
   const dependentsOf = /* @__PURE__ */ new Map();
+  const dependenciesOf = /* @__PURE__ */ new Map();
   const workspacePackages = /* @__PURE__ */ new Map();
   for (const workspace of workspaces) {
     const primaryPackageFile = workspace.packageFiles[0];
@@ -32,9 +33,15 @@ function buildDependencyGraph(workspaces) {
       } else {
         existing.push(workspace);
       }
+      const forward = dependenciesOf.get(workspace.dir);
+      if (forward === void 0) {
+        dependenciesOf.set(workspace.dir, /* @__PURE__ */ new Set([depName]));
+      } else {
+        forward.add(depName);
+      }
     }
   }
-  return { packageNameToDir, dirToPackageName, dependentsOf };
+  return { packageNameToDir, dirToPackageName, dependentsOf, dependenciesOf };
 }
 function readPackageJsonSubset(filePath) {
   let content;

package/dist/esm/buildReleaseSummary.js

@@ -2,7 +2,7 @@ import { stripScope } from "./stripScope.js";
 function buildReleaseSummary(result) {
   const sections = [];
   for (const workspace of result.workspaces) {
-    if (workspace.status !== "released" || workspace.tag === void 0) {
+    if (workspace.status !== "released") {
       continue;
     }
     const commits = workspace.commits;
@@ -15,6 +15,14 @@ function buildReleaseSummary(result) {
     }
     sections.push(lines.join("\n"));
   }
+  const project = result.project;
+  if (project !== void 0 && project.status === "released" && project.commits.length > 0) {
+    const lines = [project.tag];
+    for (const commit of project.commits) {
+      lines.push(`- ${stripScope(commit.message)}`);
+    }
+    sections.push(lines.join("\n"));
+  }
   return sections.join("\n\n");
 }
 export {

package/dist/esm/buildSyntheticChangelogEntry.d.ts

@@ -0,0 +1,5 @@
+import type { ChangelogEntry } from './types.ts';
+export declare function buildSyntheticChangelogEntry(propagatedFrom: ReadonlyArray<{
+    packageName: string;
+    newVersion: string;
+}>, version: string, date: string): ChangelogEntry;

package/dist/esm/buildSyntheticChangelogEntry.js

@@ -0,0 +1,13 @@
+function buildSyntheticChangelogEntry(propagatedFrom, version, date) {
+  const items = propagatedFrom.map((dep) => ({
+    description: `Bumped \`${dep.packageName}\` to ${dep.newVersion}`
+  }));
+  return {
+    version,
+    date,
+    sections: [{ title: "Dependency updates", audience: "dev", items }]
+  };
+}
+export {
+  buildSyntheticChangelogEntry
+};

package/dist/esm/changelogJsonFile.d.ts

@@ -0,0 +1,4 @@
+import type { ChangelogEntry, ReleaseConfig } from './types.ts';
+export declare function resolveChangelogJsonPath(config: Pick<ReleaseConfig, 'changelogJson'>, changelogPath: string): string;
+export declare function writeChangelogJson(filePath: string, entries: ChangelogEntry[]): string;
+export declare function upsertChangelogJson(filePath: string, entries: ChangelogEntry[]): string;

package/dist/esm/changelogJsonFile.js

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import stringify from "json-stringify-pretty-compact";
+import semver from "semver";
+import { isChangelogEntry } from "./changelogJsonUtils.js";
+import { isUnknownArray } from "./typeGuards.js";
+function resolveChangelogJsonPath(config, changelogPath) {
+  return join(changelogPath, config.changelogJson.outputPath);
+}
+function writeChangelogJson(filePath, entries) {
+  const sorted = sortNewestFirst(entries);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, stringify(sorted, { maxLength: 100 }) + "\n", "utf8");
+  return filePath;
+}
+function upsertChangelogJson(filePath, entries) {
+  const existing = readExistingEntries(filePath);
+  const merged = mergeEntries(entries, existing);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, stringify(merged, { maxLength: 100 }) + "\n", "utf8");
+  return filePath;
+}
+function sortNewestFirst(entries) {
+  return [...entries].sort((a, b) => compareVersionsDescending(a.version, b.version));
+}
+function readExistingEntries(filePath) {
+  if (!existsSync(filePath)) {
+    return [];
+  }
+  try {
+    const content = readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(content);
+    if (!isUnknownArray(parsed)) {
+      return [];
+    }
+    return parsed.filter(isChangelogEntry);
+  } catch (error) {
+    console.warn(
+      `Warning: could not parse existing ${filePath}: ${error instanceof Error ? error.message : String(error)}; treating as empty`
+    );
+    return [];
+  }
+}
+function mergeEntries(newEntries, existingEntries) {
+  const versionMap = /* @__PURE__ */ new Map();
+  for (const entry of existingEntries) {
+    versionMap.set(entry.version, entry);
+  }
+  for (const entry of newEntries) {
+    versionMap.set(entry.version, entry);
+  }
+  return sortNewestFirst(versionMap.values());
+}
+function compareVersionsDescending(a, b) {
+  const aValid = semver.valid(a);
+  const bValid = semver.valid(b);
+  if (aValid && bValid) return semver.rcompare(aValid, bValid);
+  if (aValid) return -1;
+  if (bValid) return 1;
+  if (a > b) return -1;
+  if (a < b) return 1;
+  return 0;
+}
+export {
+  resolveChangelogJsonPath,
+  upsertChangelogJson,
+  writeChangelogJson
+};