@williamthorsen/release-kit 10.4.4 → 10.6.0

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
-/** @noformat — @generated. Do not edit. Compiled by rdy. */
+/** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.32.0";
+export const __readyupVersion = "0.35.0";
 
 
 // .readyup/kits/default.ts
@@ -50,9 +50,55 @@ function detectRepoType() {
   return "single-package";
 }
 
+// src/packsPath.ts
+function packsPath(filesField, path) {
+  if (!isStringArray(filesField)) return true;
+  const prefixes = listAncestorPrefixes(path);
+  return filesField.some((entry) => {
+    const pattern = compileEntry(entry);
+    return pattern !== void 0 && prefixes.some((prefix) => pattern.test(prefix));
+  });
+}
+var GLOB_TOKEN_PATTERN = /\*\*\/|\*\*|\*|\?|[^*?]+/g;
+function compileEntry(entry) {
+  if (entry.startsWith("!")) return void 0;
+  const normalized = entry.replace(/^\.?\//, "").replace(/\/+$/, "");
+  if (normalized === "") return void 0;
+  return new RegExp(`^${translateGlob(normalized)}$`);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function listAncestorPrefixes(path) {
+  const segments = path.split("/");
+  return segments.map((_segment, index) => segments.slice(0, index + 1).join("/"));
+}
+function translateGlob(pattern) {
+  let source = "";
+  for (const [token] of pattern.matchAll(GLOB_TOKEN_PATTERN)) {
+    switch (token) {
+      case "**/":
+        source += String.raw`(?:[^/]*\/)*`;
+        break;
+      case "**":
+        source += ".*";
+        break;
+      case "*":
+        source += "[^/]*";
+        break;
+      case "?":
+        source += "[^/]";
+        break;
+      default:
+        source += RegExp.escape(token);
+    }
+  }
+  return source;
+}
+
 // .readyup/kits/default.ts
 function getMinVersion() {
-  const picked = { "version": "10.4.4" };
+  const picked = { "version": "10.6.0" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("release-kit/package.json: 'version' must be a string");
   }
@@ -61,6 +107,7 @@ function getMinVersion() {
 function hasPublishablePackages() {
   return discoverWorkspaces({ filter: (w) => w.isPackage }).length > 0;
 }
+var DEFAULT_CHANGELOG_JSON_PATH = ".meta/changelog.json";
 var CONFIG_EXPORT_PATTERNS = [
   /export\s+default\b/,
   /export\s+(?:const|let|var)\s+config\b/,
@@ -204,6 +251,32 @@ var default_default = defineRdyKit({
             }
           ]
         },
+        // Deliberately outside the config gate above: that check skips where the config file is absent, and a repo
+        // with no config file still defaults `changelogJson.enabled` to true and still publishes tarballs.
+        {
+          name: "published packages ship CHANGELOG.md",
+          severity: "warn",
+          skip: () => !hasPublishablePackages() ? "no publishable packages" : false,
+          check: () => packagesShipChangelog(),
+          fix: 'Add "CHANGELOG.md" to the files field of each affected package.json'
+        },
+        {
+          name: "changelog.json generation is enabled",
+          severity: "recommend",
+          skip: () => !hasPublishablePackages() ? "no publishable packages" : false,
+          check: () => changelogJsonIsEnabled(),
+          fix: "Remove changelogJson.enabled: false from .config/release-kit.config.ts so release-kit writes the machine-readable changelog that upgrade tooling reads before CHANGELOG.md",
+          checks: [
+            {
+              name: "published packages ship the changelog JSON",
+              severity: "warn",
+              check: () => packagesShipChangelogJson(),
+              get fix() {
+                return `Add "${resolveChangelogJsonOutputPath()}" to the files field of each affected package.json`;
+              }
+            }
+          ]
+        },
         {
           name: "config does not use removed releaseNotes.shouldCreateGithubRelease",
           severity: "error",
@@ -218,6 +291,13 @@ var default_default = defineRdyKit({
           check: () => !hasDevDependency("git-cliff"),
           fix: "pnpm remove git-cliff \u2014 release-kit handles changelog generation directly"
         },
+        {
+          name: "@changesets/cli not in devDependencies",
+          severity: "recommend",
+          quiet: true,
+          check: () => !hasDevDependency("@changesets/cli"),
+          fix: "pnpm remove @changesets/cli, then delete .changeset/ and any changeset:* scripts; release-kit supersedes changesets"
+        },
         {
           name: ".config/git-cliff.toml matches current template",
           severity: "warn",
@@ -257,6 +337,11 @@ var default_default = defineRdyKit({
     }
   ]
 });
+function changelogJsonIsEnabled() {
+  const content = readFile(".config/release-kit.config.ts");
+  if (content === void 0) return true;
+  return !/changelogJson\s*:\s*\{[^}]*enabled\s*:\s*false/.test(content);
+}
 function configFileExportsConfig() {
   const content = readFile(".config/release-kit.config.ts");
   if (content === void 0) return false;
@@ -269,6 +354,12 @@ function labelsHaveCurrentPresetHash(presetName, expectedHash) {
   const match = pattern.exec(content);
   return match !== null && match[1] === expectedHash;
 }
+function packagesShipChangelog() {
+  return reportWorkspacesOmitting("CHANGELOG.md");
+}
+function packagesShipChangelogJson() {
+  return reportWorkspacesOmitting(resolveChangelogJsonOutputPath());
+}
 function readmeHasReleaseNotesMarkers(content) {
   return content.includes("<!-- section:release-notes -->") && content.includes("<!-- /section:release-notes -->");
 }
@@ -301,16 +392,41 @@ function releaseNotesInjectsIntoReadme() {
   if (content === void 0) return false;
   return /shouldInjectIntoReadme\s*:\s*true/.test(content);
 }
+function reportWorkspacesOmitting(path) {
+  const failing = [];
+  const packageWorkspaces = discoverWorkspaces({ filter: (w) => w.isPackage });
+  for (const { dir, packageJson } of packageWorkspaces) {
+    if (!packsPath(packageJson["files"], path)) {
+      failing.push(dir === "." ? "package.json" : `${dir}/package.json`);
+    }
+  }
+  if (failing.length === 0) return true;
+  return {
+    ok: false,
+    detail: `files field omits ${path}: ${failing.join(", ")}`
+  };
+}
+function resolveChangelogJsonOutputPath() {
+  const content = readFile(".config/release-kit.config.ts");
+  if (content === void 0) return DEFAULT_CHANGELOG_JSON_PATH;
+  const match = /changelogJson\s*:\s*\{[^}]*outputPath\s*:\s*['"]([^'"]+)['"]/.exec(content);
+  return match?.[1] ?? DEFAULT_CHANGELOG_JSON_PATH;
+}
 export {
   CLIFF_TEMPLATE_HASH,
   COMMON_PRESET_HASH,
+  DEFAULT_CHANGELOG_JSON_PATH,
   PUBLISH_WORKFLOW_HASH_MONOREPO,
   PUBLISH_WORKFLOW_HASH_SINGLE,
   RELEASE_WORKFLOW_HASH_MONOREPO,
   RELEASE_WORKFLOW_HASH_SINGLE,
   SYNC_LABELS_WORKFLOW_HASH,
+  changelogJsonIsEnabled,
   configFileExportsConfig,
   default_default as default,
+  packagesShipChangelog,
+  packagesShipChangelogJson,
   readmeHasReleaseNotesMarkers,
-  readmesHaveReleaseNotesMarkers
+  readmesHaveReleaseNotesMarkers,
+  resolveChangelogJsonOutputPath
 };

package/.readyup/kits/npm-auto-publish.js

@@ -1,6 +1,6 @@
-/** @noformat — @generated. Do not edit. Compiled by rdy. */
+/** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.32.0";
+export const __readyupVersion = "0.35.0";
 
 
 // .readyup/kits/npm-auto-publish.ts
@@ -68,6 +68,9 @@ var packagesChecklist = defineRdyChecklist({
       },
       fix: 'Set "packageManager": "pnpm@..." in root package.json'
     },
+    // Unfalsifiable on readyup 0.33 and later, where discovery reports the repo root and throws on an unreadable
+    // root package.json rather than returning an empty list. It stays for a consumer below that, whose monorepo
+    // mode returns the matched directories alone and so returns nothing when the globs match nothing.
     {
       name: "At least one workspace discovered",
       check: () => discoverWorkspaces().length > 0,
@@ -86,7 +89,9 @@ var packagesChecklist = defineRdyChecklist({
       // reach the registry on every run regardless of the skip. Per-outcome wording goes in the check's detail.
       fix: 'Restore a usable npm session: log in with "npm login", or restore access to the registry, which the trusted-publisher check queries directly',
       get checks() {
-        return discoverWorkspaces().map((workspace) => buildWorkspaceCheck(workspace));
+        return discoverWorkspaces({ filter: belongsInPackagesChecklist }).map(
+          (workspace) => buildWorkspaceCheck(workspace)
+        );
       }
     }
   ]
@@ -95,6 +100,9 @@ var npm_auto_publish_default = defineRdyKit({
   fixLocation: "inline",
   checklists: [repoChecklist, packagesChecklist]
 });
+function belongsInPackagesChecklist(workspace) {
+  return !workspace.isRoot || workspace.isPackage;
+}
 function buildWorkspaceCheck(workspace) {
   const displayName = workspace.name ?? "(unnamed)";
   const pkgJsonPath = path.join(workspace.dir, "package.json");

package/.readyup/manifest.json

@@ -5,15 +5,15 @@
       "checklists": [
         "release-kit"
       ],
-      "esbuildVersion": "0.28.1",
+      "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "fe239d01",
+          "hash": "4a359cc9",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "999accdd",
+          "hash": "bb217228",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -30,6 +30,11 @@
           "kind": "module",
           "path": "../src/init/parseJsonRecord.ts"
         },
+        {
+          "hash": "b798d024",
+          "kind": "module",
+          "path": "../src/packsPath.ts"
+        },
         {
           "hash": "646fe51b",
           "kind": "module",
@@ -38,30 +43,30 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.32.0",
+      "readyupVersion": "0.35.0",
       "source": "kits/default.ts",
-      "sourceHash": "fe239d01",
-      "targetHash": "e9daa536"
+      "sourceHash": "4a359cc9",
+      "targetHash": "5b3e6dcf"
     },
     {
       "checklists": [
         "repo",
         "packages"
       ],
-      "esbuildVersion": "0.28.1",
+      "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "ac484613",
+          "hash": "15641d4a",
           "kind": "module",
           "path": "kits/npm-auto-publish.ts"
         }
       ],
       "name": "npm-auto-publish",
       "path": "kits/npm-auto-publish.js",
-      "readyupVersion": "0.32.0",
+      "readyupVersion": "0.35.0",
       "source": "kits/npm-auto-publish.ts",
-      "sourceHash": "ac484613",
-      "targetHash": "6f5398ef"
+      "sourceHash": "15641d4a",
+      "targetHash": "721e337b"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to this project will be documented in this file.
 
+## 10.6.0 — 2026-09-08
+
+### 🎉 Features
+
+- Report a package whose tarball would omit its changelog (#768)
+
+  Adds ReadyUp checks to verify that every published package bundles its changelog files: the human-readable `CHANGELOG.md` and the machine-readable `changelog.json`.
+
+- Add a migration field to changelog.json items (#770)
+
+  Adds an optional `migration` field to entries in the `.meta/changelog.json` that `release-kit` generates. If a commit body contains a labeled migration step, that content is copied to the `migration` field.
+
+### 🐛 Bug fixes
+
+- Pin git-cliff and remove the per-run npx cache refresh (#776)
+
+  Fixes an issue where git-cliff's version was unpinned, resulting in a per-run cache refresh. An exact version is now pinned.
+
+  Removes the per-run cache refresh, which re-ran `npx` without `--prefer-offline` once per prepare and forced a registry round trip. An exact version leaves npm nothing to revalidate, so a prepare run no longer waits on registry latency.
+
+  Also silences git-cliff's INFO output, in particular the crates.io update notice.
+
+### ♻️ Refactoring
+
+- Remove the unwired isChangelogItem type guard (#771)
+
+  Removes the unused `isChangelogItem` from `release-kit`'s `changelogJsonUtils.ts`, together with its tests.
+
+  Documentation is updated to record the boundary on `isChangelogEntry`: Entries parsed from `.meta/changelog.json` are shape-checked at the top level only, and strict validation applies only to the human-authored `.meta/changelog-overrides.json`.
+
+### 🧪 Tests
+
+- Read console spy output with listConsoleLines rather than by hand (#781)
+
+  - Replaces the hand-rolled reads of a console spy's `mock.calls` in the `nmr`, `release-kit`, and `v11y-check` test suites with `listConsoleLines` from `@williamthorsen/toolbelt.vitest/candidate`.
+  - Clears the `toolbelt.vitest/no-console-calls-read` recommendation that `rdy run --packages` reported.
+
+## 10.5.0 — 2026-09-01
+
+### 🎉 Features
+
+- Report a consuming repo that still declares @changesets/cli (#764)
+
+  Adds a check to the default ReadyUp kit in `@williamthorsen/release-kit` that reports a repo still declaring `@changesets/cli`, the release tool superseded by release-kit. The check reports at `recommend` severity; its fix directs the consumer to remove the dependency together with the `.changeset/` directory and any `changeset:*` scripts.
+
+### ♻️ Refactoring
+
+- Upgrade to readyup v0.34 and exclude a private repo root from kit checks (#759)
+
+  Upgrades `readyup` to v0.34, whose `discoverWorkspaces` now reports the repo root. `release-kit`'s `npm-auto-publish` kit filters that root out unless it is publishable, so a private root is no longer listed in the kit's report.
+
+  Test suites for release-kit's ReadyUp kits have been refactored to use the patterns documented in v0.34.
+
+- Upgrade eslint-config-typescript and mark the discards it now reports (#761)
+
+  Upgrades `@williamthorsen/eslint-config-typescript` to v12 and fixes violations surfaced by the newly added rule warning against a disposable that is discarded or that is bound to a declaration that never releases it.
+
 ## 10.4.4 — 2026-08-24
 
 ### ♻️ Refactoring

package/README.md

@@ -4,7 +4,29 @@ 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 from `git-cliff --context` output rendered in-process (with optional [editorial overrides](#editorial-overrides)).
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v10.6.0 (2026-09-08)
+
+### 🎉 Features
+
+- Report a package whose tarball would omit its changelog (#768)
+
+  Adds ReadyUp checks to verify that every published package bundles its changelog files: the human-readable `CHANGELOG.md` and the machine-readable `changelog.json`.
+
+- Add a migration field to changelog.json items (#770)
+
+  Adds an optional `migration` field to entries in the `.meta/changelog.json` that `release-kit` generates. If a commit body contains a labeled migration step, that content is copied to the `migration` field.
+
+### 🐛 Bug fixes
+
+- Pin git-cliff and remove the per-run npx cache refresh (#776)
+
+  Fixes an issue where git-cliff's version was unpinned, resulting in a per-run cache refresh. An exact version is now pinned.
+
+  Removes the per-run cache refresh, which re-ran `npx` without `--prefer-offline` once per prepare and forced a registry round trip. An exact version leaves npm nothing to revalidate, so a prepare run no longer waits on registry latency.
+
+  Also silences git-cliff's INFO output, in particular the crates.io update notice.
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -64,6 +86,8 @@ That's it for most repos. The CLI auto-discovers workspaces and applies sensible
 4. **Version bump + changelog**: bumps `package.json` versions, builds structured `ChangelogEntry[]` from `git-cliff --context`, applies any [editorial overrides](#editorial-overrides) from per-scope `.meta/changelog-overrides.json` files, and renders both `CHANGELOG.md` and `.meta/changelog.json` from that single source. `git-cliff` is invoked only for its `--context` JSON; markdown rendering happens in-process so `.meta/changelog.json` and `CHANGELOG.md` always agree.
 5. **Release tags file**: writes computed tags to `tmp/.release-tags` for the release workflow to read when tagging and pushing.
 
+Neither changelog reaches a published tarball on its own. npm stopped including `CHANGELOG` automatically in npm 7, so a package that declares a `files` field ships a changelog only where that field names `CHANGELOG.md` and `.meta/changelog.json`. release-kit's readyup kit reports a publishable workspace whose `files` field omits either.
+
 ## Commit format
 
 release-kit parses commits in these formats:
@@ -392,6 +416,40 @@ Work types from your config are merged with these defaults by key — your entri
 
 The default `devOnlySections` (excluded from public release notes but still written to `CHANGELOG.md`) are derived from the `internal` and `process` tiers (excluding `fmt`). Override via `changelogJson.devOnlySections` in your config; matching is decorator-tolerant, so a bare-name override like `['Internal features']` keeps working against the emoji-prefixed and prefix-decorated default titles.
 
+## `changelog.json` item schema
+
+Each item under a section in `.meta/changelog.json` carries one required field and four optional ones:
+
+| Field         | Type      | Meaning                                                                                                                           |
+| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `description` | `string`  | The bullet headline, taken from the commit subject with the ticket ID and type prefix stripped.                                   |
+| `body`        | `string`  | The commit body, with trailing trailer metadata stripped.                                                                         |
+| `breaking`    | `boolean` | Present and `true` where the commit subject carried the `!` prefix. See [`!` (breaking change) policy](#-breaking-change-policy). |
+| `migration`   | `string`  | The migration step for a consumer. See below.                                                                                     |
+| `hash`        | `string`  | The full commit SHA, and the key on which an override entry matches. Absent on synthetic propagation entries.                     |
+
+Every optional field is omitted rather than emitted as `null`, so a consumer tests for presence.
+
+### The `migration` field
+
+A commit body states a migration step as a paragraph opening with the literal label `Migration:`. Where one is present, `migration` carries that paragraph with the label stripped:
+
+```jsonc
+{
+  "description": "Rename the workspace field",
+  "body": "Renames `name` to `id`.\n\nMigration: Change any uses of `name` to `id`.",
+  "migration": "Change any uses of `name` to `id`.",
+}
+```
+
+Three properties are worth knowing:
+
+- **It is independent of `breaking`.** A `fix` cannot carry `!` under the default breaking policy, and a `fix` that tightens validation still imposes a migration. Filter on `migration` to find every step; filter on `breaking` to find every breaking change.
+- **`body` keeps the paragraph.** The field is an extraction, not a move, so `CHANGELOG.md` and `.meta/changelog.json` go on agreeing.
+- **It is derived, not authored.** `migration` is not a field an override file can set (see [File shape](#file-shape)); it is re-derived from whatever `body` an override installs, and cleared where that body carries no labeled paragraph. To change the migration text, override `body`.
+
+The label match is exact: `migration:` and `**Migration:**` are not recognized.
+
 ## Editorial overrides
 
 Generated changelogs occasionally need editorial correction — typos, redacted scope, reworded entries, or historical commits whose bodies carry verbatim PR-template scaffolding (`## What`, `## Why`, etc.) that renders as literal text in user-facing release notes. Rewriting git history is not viable, and any in-place edit to `CHANGELOG.md` or `.meta/changelog.json` is overwritten on the next release because release-kit regenerates both artifacts from scratch.
@@ -453,6 +511,8 @@ Per-entry fields are all optional, but at least one must be present per entry:
 | `body`        | `string`                   | Replaces the entry's body (the prose that renders below the bullet). Other fields are preserved.                                  |
 | `breaking`    | `boolean`                  | Toggles the `🚨 **Breaking:** ` marker on the bullet.                                                                             |
 
+There is no `migration` key: the field is derived from `body`, so an override that replaces `body` re-derives it. See [The `migration` field](#the-migration-field).
+
 ### Hash-prefix matching
 
 Keys can be either the full 40-character commit SHA or a non-ambiguous prefix. The matcher walks every `ChangelogItem.hash` value present in the entry tree and resolves each override key to its set of matching hashes:
@@ -908,7 +968,7 @@ These kits are no longer reachable through `rdy run --from github:williamthorsen
 This package shells out to two external tools:
 
 - **`git`** — must be available on `PATH`. Used to find tags and retrieve commit history.
-- **`git-cliff`** — automatically downloaded and cached via `npx` on first invocation. No need to install it as a dev dependency.
+- **`git-cliff`** — pinned to an exact version and fetched via `npx` on first invocation, then served from npx's cache. No need to install it as a dev dependency. The pin moves only when a new release-kit version names a newer git-cliff, so two releases cut months apart run the same changelog generator.
 
 ## Upgrading from v4 to v5
 
@@ -1062,12 +1122,12 @@ If your format command does not accept file arguments, update it to one that doe
 
 ### v1.1.0: `git-cliff` is no longer a required dev dependency
 
-`git-cliff` is now invoked via `npx --yes git-cliff` instead of requiring it as a dev dependency. You can remove it from your `devDependencies`. The version is not pinned, so `npx` downloads and caches the latest version on first invocation. To pin a specific version, use `npx --yes git-cliff@2.12.0` by wrapping the call in a custom script.
+`git-cliff` is now invoked via `npx` instead of requiring it as a dev dependency. You can remove it from your `devDependencies`. release-kit names an exact version in the invocation, so the version you get is decided by the release-kit version you install rather than by whatever the registry serves that day.
 
 ## Migration from changesets
 
 1. Add `@williamthorsen/release-kit` as a dev dependency.
-2. Remove `@changesets/cli` from dev dependencies.
+2. Remove `@changesets/cli` from dev dependencies. The [default readyup kit](#readiness-checks) reports a repo that still declares it.
 3. Delete the `.changeset/` directory.
 4. Run `npx @williamthorsen/release-kit init` to scaffold workflow and config files.
 5. Remove `changeset:*` scripts from `package.json` (no replacement needed — the CLI handles everything).

package/dist/esm/assertCleanWorkingTree.d.ts

@@ -1 +1,6 @@
+/**
+ * Verify that the git working tree has no uncommitted changes.
+ *
+ * @throws If `git status --porcelain` reports any changes.
+ */
 export declare function assertCleanWorkingTree(): void;

package/dist/esm/buildChangelogEntries.d.ts

@@ -1,4 +1,26 @@
 import type { GenerateChangelogOptions } from './generateChangelogs.js';
 import type { ChangelogEntry, ReleaseConfig } from './types.js';
+/**
+ * Strip cliff-template decorations from a group string, returning the bare section name.
+ *
+ * The bundled `cliff.toml.template` encodes canonical row order as a hidden HTML comment
+ * (e.g. `"<!-- 04 -->🐛 Bug fixes"`) so tera's `group_by` filter sorts groups predictably.
+ * The body template's `striptags` filter erases the comment from the rendered heading,
+ * but downstream consumers that read the raw `group` value (changelog.json titles, the
+ * dev-vs-public classifier, the drift test) see the prefix and must strip it. The trailing
+ * `stripEmojiPrefix` keeps the helper backward-compatible with consumer overrides written
+ * as bare names.
+ */
 export declare function stripGroupDecorations(group: string): string;
+/**
+ * Build structured changelog entries from git history using git-cliff `--context`.
+ *
+ * Pure data: invokes git-cliff, parses its `--context` output, and returns the transformed
+ * `ChangelogEntry[]`. Performs no `changelog.json` I/O — callers persist the entries via
+ * `renderChangelogJson`.
+ *
+ * Always invokes git-cliff: dry-run is the caller's concern (it governs whether the file write happens,
+ * not whether git-cliff runs). This means dry-run exercises the full git-cliff toolchain and surfaces missing-binary,
+ * malformed-config, and template-resolution failures earlier than before.
+ */
 export declare function buildChangelogEntries(config: Pick<ReleaseConfig, 'cliffConfigPath' | 'changelogJson'>, tag: string, options?: GenerateChangelogOptions): ChangelogEntry[];

package/dist/esm/buildChangelogEntries.js

@@ -1,6 +1,7 @@
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { extractVersion } from "./changelogJsonUtils.js";
 import { DEFAULT_WORK_TYPES } from "./defaults.js";
+import { extractMigration } from "./extractMigration.js";
 import { COMMIT_PREPROCESSOR_PATTERNS, PIPE_SCOPE_SOURCE } from "./parseCommitMessage.js";
 import { resolveCliffConfigPath } from "./resolveCliffConfigPath.js";
 import { runGitCliff } from "./runGitCliff.js";
@@ -101,6 +102,10 @@ function transformReleases(releases, devOnlySections) {
             if (breaking) {
                 item.breaking = true;
             }
+            const migration = extractMigration(body);
+            if (migration !== undefined) {
+                item.migration = migration;
+            }
             if (commit.id !== undefined && commit.id !== '') {
                 item.hash = commit.id;
             }

package/dist/esm/buildDependencyGraph.d.ts

@@ -1,8 +1,24 @@
 import type { WorkspaceConfig } from './types.js';
+/** Reverse adjacency map from package names to their workspace dependents. */
 export interface DependencyGraph {
+    /** Resolve a package name to its workspace `dir`. */
     packageNameToDir: Map<string, string>;
+    /** Resolve a workspace `dir` to its package name (inverse of `packageNameToDir`). */
     dirToPackageName: Map<string, string>;
+    /** Map a package name to the workspaces that depend on it. */
     dependentsOf: Map<string, WorkspaceConfig[]>;
+    /**
+     * Forward adjacency: map a workspace `dir` to the set of `workspace:`-protocol package
+     * names it declares in `dependencies` or `peerDependencies`. Complement of `dependentsOf`.
+     */
     dependenciesOf: Map<string, Set<string>>;
 }
+/**
+ * Build a reverse dependency graph from the workspaces' `package.json` files.
+ *
+ * Reads each workspace's primary `package.json` (first entry in `packageFiles`) to discover
+ * `workspace:` references in `dependencies` and `peerDependencies`. Returns a map from each
+ * package name to the workspaces that depend on it, enabling upward traversal from a bumped
+ * package to all its dependents.
+ */
 export declare function buildDependencyGraph(workspaces: readonly WorkspaceConfig[]): DependencyGraph;

package/dist/esm/buildEmptyReleaseEntry.d.ts

@@ -1,2 +1,10 @@
 import type { ChangelogEntry } from './types.js';
+/**
+ * Build a synthetic changelog entry for a forced empty-range release.
+ *
+ * Produces a single `ChangelogEntry` with one `'Notes'` section (audience `'dev'`)
+ * containing a single `'Forced version bump.'` item. Used when `release-kit prepare`
+ * proceeds via `--force`, `--bump=X`, or `--set-version` against a unit with zero
+ * qualifying commits since its last tag. Pure function: no I/O.
+ */
 export declare function buildEmptyReleaseEntry(version: string, date: string): ChangelogEntry;

package/dist/esm/buildReleaseSummary.d.ts

@@ -1,2 +1,12 @@
 import type { PrepareResult } from './types.js';
+/**
+ * Build a release commit body from a prepare result.
+ *
+ * Each released workspace with commits gets a section headed by its tag,
+ * followed by scope-stripped commit messages as bullet points. Sections
+ * are separated by blank lines. The project release (when present) is
+ * appended as a final section using the same format. Returns an empty
+ * string when no released workspaces have commits and there is no project
+ * release.
+ */
 export declare function buildReleaseSummary(result: Pick<PrepareResult, 'project' | 'workspaces'>): string;

package/dist/esm/buildSyntheticChangelogEntry.d.ts

@@ -1,4 +1,10 @@
 import type { ChangelogEntry } from './types.js';
+/**
+ * Build a synthetic changelog entry for a propagation-only bump.
+ *
+ * Produces a single `ChangelogEntry` with one `'Dependency updates'` section (audience `'dev'`)
+ * containing one item per propagated-from dependency. Pure function: no I/O.
+ */
 export declare function buildSyntheticChangelogEntry(propagatedFrom: ReadonlyArray<{
     packageName: string;
     newVersion: string;

package/dist/esm/bumpVersion.d.ts

@@ -1,2 +1,10 @@
 import type { ReleaseType } from './types.js';
+/**
+ * Bumps a semver version string by the given release type.
+ *
+ * @param version - A semver version string (e.g., '1.2.3').
+ * @param releaseType - The type of release bump to apply.
+ * @returns The bumped version string.
+ * @throws If the version string is not a valid semver format.
+ */
 export declare function bumpVersion(version: string, releaseType: ReleaseType): string;

package/dist/esm/changelogJsonFile.d.ts

@@ -1,4 +1,15 @@
 import type { ChangelogEntry, ReleaseConfig } from './types.js';
+/** Resolve the absolute output path for the `changelog.json` file under a workspace's changelog directory. */
 export declare function resolveChangelogJsonPath(config: Pick<ReleaseConfig, 'changelogJson'>, changelogPath: string): string;
+/** Renders changelog entries as a `changelog.json` file's complete content, sorted newest-first. */
 export declare function renderChangelogJson(entries: ChangelogEntry[]): string;
+/**
+ * Merges `entries` with the on-disk entries at `filePath` and returns the merged set in
+ * newest-first order, without writing.
+ *
+ * Preserves entries that exist on disk but are absent from `entries` — load-bearing for
+ * synthetic-entry preservation across propagation runs. Reads the file when present; treats a
+ * missing or malformed file as an empty existing set, so a malformed file does not abort the
+ * release.
+ */
 export declare function mergeChangelogEntriesWithDisk(filePath: string, entries: ChangelogEntry[]): ChangelogEntry[];

package/dist/esm/changelogJsonUtils.d.ts

@@ -1,5 +1,19 @@
-import type { ChangelogEntry, ChangelogItem } from './types.js';
-export declare function isChangelogItem(value: unknown): value is ChangelogItem;
+import type { ChangelogEntry } from './types.js';
+/**
+ * Type guard for `ChangelogEntry` values parsed from JSON.
+ *
+ * Checks the entry's top level only: `sections` is verified to be an array, and its contents pass
+ * through unvalidated. `.meta/changelog.json` is written by release-kit and read tolerantly; strict
+ * validation applies to the human-authored `.meta/changelog-overrides.json`, in `changelogOverrides.ts`.
+ */
 export declare function isChangelogEntry(value: unknown): value is ChangelogEntry;
+/** Extract the version from a tag by stripping the prefix up to the first digit. */
 export declare function extractVersion(tag: string): string;
+/**
+ * Read and parse a changelog JSON file, returning validated entries.
+ *
+ * Returns `undefined` if the file cannot be read or does not contain a valid array.
+ * Silent on parse error — for the warn-and-treat-as-empty variant used by upsert callers,
+ * see `readExistingEntries` in `./changelogJsonFile.ts`.
+ */
 export declare function readChangelogEntries(filePath: string): ChangelogEntry[] | undefined;