@williamthorsen/release-kit 5.0.0 → 5.2.0

package/CHANGELOG.md

@@ -2,15 +2,109 @@
 
 All notable changes to this project will be documented in this file.
 
-## [release-kit-v5.0.0] - 2026-04-23
+## [release-kit-v5.2.0] - 2026-05-04
 
-### Bug fixes
+### 🎉 Features
 
-- Derive monorepo tag prefix from unscoped `package.json` name (#278)
+- Add emojis to changelog and release-note headings (#352)
 
-  Fixes a long-standing mismatch between a monorepo workspace's directory basename and its publishable package identity.
+  Adds emoji prefixes to the section headings rendered in `CHANGELOG.md` and release notes generated by `@williamthorsen/release-kit`. Each of the 13 default work types gets a single decorative emoji so its section is easier to spot when skimming a release: 🐛 Bug fixes, 🎉 Features, 📚 Documentation, ♻️ Refactoring, ⚡ Performance, 🔒 Security, 🧪 Tests, ⚙️ Tooling, 👷 CI, 📦 Dependencies, 🏗️ Internal, 🗑️ Deprecated, and 🤖 Agentic support. Matching of `changelogJson.devOnlySections` is emoji-tolerant: existing consumer overrides written as bare names continue to work without modification.
+
+- Surface bang violations in release prepare reports (#359)
+
+  Release-prepare flows now surface `!`-policy violations as warnings in the prepare report. Each workspace's and project's commit window is parsed against the default policy table — `internal!` is rejected as contradictory, bare `drop:` is rejected for missing the required `!`, and so on — and any violations appear under the workspace's section in the report alongside short hash, truncated subject, type, and surface (prefix or body). A new `breakingPolicies` config field lets consumers override individual entries or pass `{}` to disable enforcement entirely. Release-time enforcement remains tolerant: violations are warnings, never failures, so a single legacy commit cannot block a release.
+
+### 🐛 Bug fixes
+
+- Restrict publish to publishable workspaces (#345)
+
+  Fixes an issue where `release-kit publish` failed for workspaces marked `package.json#private: true`. The command now operates only on publishable workspaces — those where `private` is absent or `false` — and the rest of the release pipeline (`tag`, `create-github-release`, `prepare`, changelog) continues to handle private workspaces unchanged. This preserves the "versioned but not published" workflow: a private workspace can still be versioned, tagged, and published as a GitHub Release; only the registry-publish step is skipped. Without `--tags`, unpublishable tags are silently filtered (an empty result prints `Nothing to publish.` and exits 0). With `--tags` naming an unpublishable workspace, `release-kit publish` exits 1 with one error per offending tag, citing `package.json#private` and the workspace path.
+
+- Skip tooling-only releases instead of failing (#347)
+
+  Fixes an issue where `release-kit create-github-release --tags <tag>` exited 1 whenever the tag's changelog had no all-audience content. The reusable `create-github-release.reusable.yaml` workflow forwards `github.ref_name` into `--tags`, so tooling-only releases consistently produced failed workflow runs even though no failure occurred. The command now exits 1 only when a requested tag has no changelog entry; intentional skip reasons (`no-audience-content`, `empty-body`) are informational. A typoed tag still surfaces an error even when batched alongside successful tags, and the info summary reports the per-tag skip reason for diagnostic visibility.
+
+- Establish canonical work-types SSOT and restore changelog section ordering (#358)
+
+  Restores canonical section ordering in changelogs and release notes — sections were appearing in unpredictable order after the previous release added emoji prefixes to section headers. Sections now follow a stable priority: public-facing types (Features, Fixes, Security, …) first, then internal types, then process types. Release-note bullets for breaking changes carry a `🚨 **Breaking:**` prefix so they stand out at a glance. Documentation entries move out of public release notes — they continue to appear in dev changelogs.
+
+  Closes #355.
+
+### ⚡ Performance
+
+- Skip npx registry revalidation when running git-cliff (#361)
+
+  Speeds up `release-kit prepare` by skipping the npm registry cache-revalidation HTTP request that ran on every `git-cliff` invocation. Per-invocation overhead drops from ~4.6 s to ~2.0 s; in a four-workspace monorepo this saves about 10 seconds per run. Also suppresses a transient stderr spinner that briefly appeared during package resolution and looked like a half-complete log message. Network fallback is preserved — runs on machines with an empty npx cache still resolve `git-cliff` over the network.
+
+### ♻️ Refactoring
+
+- Read package version at runtime via shared helper (#338)
+
+  Fixes an issue where running `audit-deps`, `nmr`, or `release-kit` from the locally built `dist/esm/` after a `git pull` could report a stale version. Each CLI now reads its version directly from its `package.json` at startup, so version reads stay in sync with the installed source without requiring a fresh `pnpm install` or rebuild.
+
+## [release-kit-v5.1.0] - 2026-04-30
+
+### 🎉 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.
+
+### 🐛 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.
+
+### ♻️ 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.
+
+### 📚 Documentation
+
+- Document tag prefix collisions as general rule (#320)
 
-### Features
+  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.
+
+## [release-kit-v5.0.0] - 2026-04-23
+
+### 🎉 Features
 
 - Improve release-notes rendering quality (#261)
 
@@ -58,7 +152,13 @@ All notable changes to this project will be documented in this file.
 
   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.
 
-### Refactoring
+### 🐛 Bug fixes
+
+- Derive monorepo tag prefix from unscoped `package.json` name (#278)
+
+  Fixes a long-standing mismatch between a monorepo workspace's directory basename and its publishable package identity.
+
+### ♻️ Refactoring
 
 - Rename `component` to `workspace` in config API and internals (#296)
 
@@ -70,21 +170,21 @@ All notable changes to this project will be documented in this file.
 
 ## [release-kit-v4.8.0] - 2026-04-17
 
-### Bug fixes
+### 🎉 Features
 
-- Replace broad catch with `existsSync` guard in `detectRepoType` (#229)
+- Add `push` command for safe tag pushing (#243)
 
-  Fixes silent swallowing of unexpected filesystem errors in `detectRepoType`. Previously, errors like `EACCES` (permission denied) or `EMFILE` (too many open files) when reading `package.json` were caught and discarded, causing the function to silently return `'single-package'` instead of surfacing the problem.
+  Adds a `release-kit push` command that safely pushes the release commit and each tag individually, ensuring GitHub Actions fires a separate workflow run per tag. The command performs a `1 + N` push sequence: one branch push followed by one `git push --no-follow-tags origin <tag>` per resolved tag. Supports `--dry-run` (preview without pushing), `--only` (filter tags by package name), and `--tags-only` (skip the branch push).
 
-### Features
+### 🐛 Bug fixes
 
-- Add `push` command for safe tag pushing (#243)
+- Replace broad catch with `existsSync` guard in `detectRepoType` (#229)
 
-  Adds a `release-kit push` command that safely pushes the release commit and each tag individually, ensuring GitHub Actions fires a separate workflow run per tag. The command performs a `1 + N` push sequence: one branch push followed by one `git push --no-follow-tags origin <tag>` per resolved tag. Supports `--dry-run` (preview without pushing), `--only` (filter tags by package name), and `--tags-only` (skip the branch push).
+  Fixes silent swallowing of unexpected filesystem errors in `detectRepoType`. Previously, errors like `EACCES` (permission denied) or `EMFILE` (too many open files) when reading `package.json` were caught and discarded, causing the function to silently return `'single-package'` instead of surfacing the problem.
 
 ## [release-kit-v4.7.0] - 2026-04-16
 
-### Features
+### 🎉 Features
 
 - Support ## as synthetic ticket prefix in changelogs
 
@@ -92,7 +192,7 @@ All notable changes to this project will be documented in this file.
 
 ## [release-kit-v4.6.0] - 2026-04-15
 
-### Features
+### 🎉 Features
 
 - Guard `prepare` against dirty working tree (#188)
 
@@ -112,13 +212,13 @@ All notable changes to this project will be documented in this file.
 
   Adds structured changelog generation with audience tagging to the `release-kit` package, enabling GitHub Release creation and npm README injection with user-facing release notes filtered from developer-only sections. The existing CHANGELOG.md pipeline is unchanged; a new `.meta/changelog.json` artifact is generated in parallel during `release-kit prepare`, and consumed during `release-kit publish` to create GitHub Releases and inject release notes into the published package's README.
 
-### Refactoring
+### ♻️ Refactoring
 
 - Decouple GitHub Release creation and README injection from npm publish (#203)
 
   Makes GitHub Release creation available as a standalone CLI command (`release-kit github-release`) and removes README injection logic from the publish function. Non-published projects (applications, websites, internal tools) can now create GitHub Releases independently after `release-kit prepare`, and the inject/restore lifecycle is managed by the command layer rather than buried inside business logic.
 
-### Tooling
+### ⚙️ Tooling
 
 - Enable automated publication to npm (#187)
 
@@ -126,7 +226,7 @@ All notable changes to this project will be documented in this file.
 
 ## [release-kit-v4.5.1] - 2026-04-10
 
-### Bug fixes
+### 🐛 Bug fixes
 
 - Fix sync-labels init scaffolding output (#179)
 
@@ -134,13 +234,7 @@ All notable changes to this project will be documented in this file.
 
 ## [release-kit-v4.4.0] - 2026-04-04
 
-### Documentation
-
-- Refine README to match preflight documentation standard (#138)
-
-  Restructures the release-kit README to match the documentation standard established by the preflight README (#114). Reorders sections to follow the cross-package convention, converts CLI flag listings from code blocks to tables, adds representative `prepare --dry-run` output to the quick start, and condenses ~90 lines of inline workflow YAML into a summary with an inputs table and trigger examples. Fixes several accuracy gaps found by verifying documentation against source.
-
-### Features
+### 🎉 Features
 
 - Add --version flag to nmr and release-kit (#143)
 
@@ -150,7 +244,7 @@ All notable changes to this project will be documented in this file.
 
   Adds try/catch with `ERR_MODULE_NOT_FOUND` detection to all six bin wrappers across `nmr`, `preflight`, and `release-kit`. Previously, five of the six wrappers used bare `import()` calls that produced cryptic unhandled rejections when `dist/` was missing, and `preflight`'s existing try/catch gave no actionable guidance.
 
-### Refactoring
+### ♻️ Refactoring
 
 - Extract deleteFileIfExists helper (#136)
 
@@ -160,9 +254,15 @@ All notable changes to this project will be documented in this file.
 
   Add a schema-driven `parseArgs` function to `@williamthorsen/node-monorepo-core` that handles boolean flags, string flags (both `--flag=value` and `--flag value`), short aliases, positional collection, the `--` delimiter, and unknown-flag errors. Migrate all CLI argument-parsing sites in preflight (3 sites) and release-kit (5 sites) to use it. A companion `translateParseError` helper normalizes internal error messages for consistent user-facing output.
 
+### 📚 Documentation
+
+- Refine README to match preflight documentation standard (#138)
+
+  Restructures the release-kit README to match the documentation standard established by the preflight README (#114). Reorders sections to follow the cross-package convention, converts CLI flag listings from code blocks to tables, adds representative `prepare --dry-run` output to the quick start, and condenses ~90 lines of inline workflow YAML into a summary with an inputs table and trigger examples. Fixes several accuracy gaps found by verifying documentation against source.
+
 ## [release-kit-v4.0.0] - 2026-04-02
 
-### Features
+### 🎉 Features
 
 - Rename reusable workflows to .reusable.yaml convention (#129)
 
@@ -170,19 +270,7 @@ All notable changes to this project will be documented in this file.
 
 ## [release-kit-v3.0.0] - 2026-03-29
 
-### Bug fixes
-
-- Pass tag pattern to git-cliff based on tagPrefix (#77)
-
-  Fixes the issue that git-cliff was processing the entire commit history on every run instead of only commits since the last release.
-
-  Constructs the pattern from `tagPrefix` at invocation time (e.g., `release-kit-v` → `release-kit-v[0-9].*`) and pass it via `--tag-pattern`, which overrides the config file default.
-
-- Propagate version bumps to workspace dependents (#80)
-
-  Restructures `releasePrepareMono` from a single-pass loop into a phased pipeline that automatically patch-bumps workspace dependents when a component is released. A reverse dependency graph is built from `workspace:` references in `dependencies` and `peerDependencies`, then BFS propagation walks upward from bumped components to their dependents. Propagated-only components receive synthetic changelog entries instead of git-cliff invocations.
-
-### Features
+### 🎉 Features
 
 - Support conventional-commit format in commit parsing (#85)
 
@@ -202,9 +290,21 @@ All notable changes to this project will be documented in this file.
 
   Updates the scaffolded `publish.yaml` template to include `provenance: false` with an inline comment guiding public repos to opt in. Expand the `release-kit init` next-steps output with hints about the provenance setting and trusted publisher registration. Set `provenance: true` in this repo's own `publish.yaml` since it is public.
 
+### 🐛 Bug fixes
+
+- Pass tag pattern to git-cliff based on tagPrefix (#77)
+
+  Fixes the issue that git-cliff was processing the entire commit history on every run instead of only commits since the last release.
+
+  Constructs the pattern from `tagPrefix` at invocation time (e.g., `release-kit-v` → `release-kit-v[0-9].*`) and pass it via `--tag-pattern`, which overrides the config file default.
+
+- Propagate version bumps to workspace dependents (#80)
+
+  Restructures `releasePrepareMono` from a single-pass loop into a phased pipeline that automatically patch-bumps workspace dependents when a component is released. A reverse dependency graph is built from `workspace:` references in `dependencies` and `peerDependencies`, then BFS propagation walks upward from bumped components to their dependents. Propagated-only components receive synthetic changelog entries instead of git-cliff invocations.
+
 ## [release-kit-v2.3.2] - 2026-03-28
 
-### Bug fixes
+### 🐛 Bug fixes
 
 - Prevent unparseable commits from being silently dropped (#76)
 
@@ -212,7 +312,7 @@ All notable changes to this project will be documented in this file.
 
 ## [release-kit-v2.3.0] - 2026-03-28
 
-### Features
+### 🎉 Features
 
 - Add shared writeFileWithCheck utility and overwrite reporting (#66)
 
@@ -224,7 +324,7 @@ All notable changes to this project will be documented in this file.
 
   Refactors `writeReleaseTags` to use the shared `writeFileWithCheck` utility from `@node-monorepo-tools/core` instead of raw `mkdirSync`/`writeFileSync`. The function now returns a structured `WriteResult` instead of throwing, and contains no `console` calls — all presentation moves to `runAndReport`.
 
-### Tests
+### 🧪 Tests
 
 - Add eligibility check failure and short-circuit tests (#63)
 
@@ -240,7 +340,7 @@ All notable changes to this project will be documented in this file.
 
 ## [release-kit-v2.2.0] - 2026-03-27
 
-### Features
+### 🎉 Features
 
 - Add sync-labels command (#33)
 
@@ -276,7 +376,7 @@ All notable changes to this project will be documented in this file.
 
   Scopes: core, nmr
 
-### Refactoring
+### ♻️ Refactoring
 
 - Replace dist bin targets with thin wrapper scripts (#48)
 
@@ -286,7 +386,7 @@ All notable changes to this project will be documented in this file.
 
   Extracts all `console.info` calls from the prepare workflow's logic functions (`bumpAllVersions`, `generateChangelogs`, `releasePrepare`, `releasePrepareMono`) into a dedicated `reportPrepare` formatter. Logic functions now return structured result types (`BumpResult`, `ComponentPrepareResult`, `PrepareResult`). The legacy `runReleasePrepare` entry point is retired, with its utilities absorbed into `prepareCommand`.
 
-### Tests
+### 🧪 Tests
 
 - Cover multi-changelogPaths and error paths (#44)
 
@@ -297,7 +397,7 @@ All notable changes to this project will be documented in this file.
 
   Also adds a `findAllCliffOutputPaths()` test helper that collects the `--output` arg from every `git-cliff` mock call.
 
-### Tooling
+### ⚙️ Tooling
 
 - Adopt nmr to run monorepo and workspace scripts (#38)
 
@@ -305,7 +405,7 @@ All notable changes to this project will be documented in this file.
 
 ## [release-kit-v2.1.0] - 2026-03-17
 
-### Features
+### 🎉 Features
 
 - Slim down release workflow by removing unnecessary pnpm install (#21)
 
@@ -323,7 +423,7 @@ All notable changes to this project will be documented in this file.
 
   Adds a `resolveCliffConfigPath()` function that searches for a git-cliff config in a 4-step cascade (explicit path → `.config/git-cliff.toml` → `cliff.toml` → bundled `cliff.toml.template`), eliminating the requirement for consuming repos to maintain a cliff config copy. Restructures the `init` command to scaffold only the workflow file by default, with new `--with-config` and `--force` flags. Moves `.release-tags` from `/tmp/release-kit/` to project-local `tmp/` for predictable behavior in local runs.
 
-### Refactoring
+### ♻️ Refactoring
 
 - Clean up release-kit post-migration issues (#19)
 
@@ -331,7 +431,7 @@ All notable changes to this project will be documented in this file.
 
 ## [release-kit-v1.0.1] - 2026-03-14
 
-### Features
+### 🎉 Features
 
 - Migrate release-kit from toolbelt (#18)