@williamthorsen/release-kit 10.6.0 → 10.8.0

package/dist/esm/work-types.json

@@ -1,133 +1,149 @@
 {
   "$schema": "./work-types.schema.json",
+  "markers": {
+    "breaking": {
+      "emoji": "🚨",
+      "label": "Breaking"
+    }
+  },
   "tiers": ["public", "internal", "process"],
   "types": [
     {
-      "tier": "public",
-      "key": "feat",
       "aliases": ["feature"],
+      "breakingPolicy": "optional",
+      "description": "A change that gives consumers a new capability or extends an existing one.",
       "emoji": "🎉",
+      "key": "feat",
       "label": "Features",
-      "breakingPolicy": "optional"
+      "tier": "public"
     },
     {
-      "tier": "public",
-      "key": "drop",
       "aliases": [],
+      "breakingPolicy": "required",
+      "description": "A change that removes a capability or surface on which consumers depend.",
       "emoji": "🪦",
+      "key": "drop",
       "label": "Removed",
-      "breakingPolicy": "required"
+      "tier": "public"
     },
     {
-      "tier": "public",
-      "key": "deprecate",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change that marks a capability or surface for removal while the capability or surface keeps working.",
       "emoji": "🗑️",
+      "key": "deprecate",
       "label": "Deprecated",
-      "breakingPolicy": "forbidden"
+      "tier": "public"
     },
     {
-      "tier": "public",
-      "key": "fix",
       "aliases": ["bugfix"],
+      "breakingPolicy": "optional",
+      "description": "A change that corrects behavior that consumers meet and that differs from what was intended.",
       "emoji": "🐛",
+      "key": "fix",
       "label": "Bug fixes",
-      "breakingPolicy": "forbidden"
+      "tier": "public"
     },
     {
-      "tier": "public",
-      "key": "sec",
       "aliases": ["security"],
+      "breakingPolicy": "optional",
+      "description": "A change that closes a vulnerability or hardens a consumer-facing surface against attack.",
       "emoji": "🔒",
+      "key": "sec",
       "label": "Security",
-      "breakingPolicy": "optional"
+      "tier": "public"
     },
     {
-      "tier": "public",
-      "key": "perf",
       "aliases": ["performance"],
+      "breakingPolicy": "optional",
+      "description": "A change that reduces the time, memory, or other resources that consumer-facing work uses, without changing its result.",
       "emoji": "⚡",
+      "key": "perf",
       "label": "Performance",
-      "breakingPolicy": "forbidden"
+      "tier": "public"
     },
     {
-      "tier": "internal",
-      "key": "internal",
       "aliases": ["utility"],
+      "breakingPolicy": "forbidden",
+      "description": "A change that adds or extends a capability that consumers do not use directly, such as a helper or an internal module.",
       "emoji": "🏗️",
+      "key": "internal",
       "label": "Internal features",
-      "breakingPolicy": "forbidden"
+      "tier": "internal"
     },
     {
-      "tier": "internal",
-      "key": "refactor",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change that restructures existing code without changing its behavior.",
       "emoji": "♻️",
+      "key": "refactor",
       "label": "Refactoring",
-      "breakingPolicy": "forbidden"
+      "tier": "internal"
     },
     {
-      "tier": "internal",
-      "key": "tests",
       "aliases": ["test"],
+      "breakingPolicy": "forbidden",
+      "description": "A change confined to tests, test fixtures, or test helpers, including one that unblocks a build or a type check.",
       "emoji": "🧪",
+      "key": "tests",
       "label": "Tests",
-      "breakingPolicy": "forbidden"
+      "tier": "internal"
     },
     {
-      "tier": "process",
-      "key": "tooling",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change to the tools used to develop the project: build, lint, formatting, and release configuration, and development scripts.",
       "emoji": "⚙️",
+      "key": "tooling",
       "label": "Tooling",
-      "breakingPolicy": "forbidden"
+      "tier": "process"
     },
     {
-      "tier": "process",
-      "key": "ci",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change to continuous-integration workflows and their configuration.",
       "emoji": "👷",
+      "key": "ci",
       "label": "CI",
-      "breakingPolicy": "forbidden"
+      "tier": "process"
     },
     {
-      "tier": "process",
-      "key": "deps",
       "aliases": ["dep"],
+      "breakingPolicy": "forbidden",
+      "description": "A change that adds, removes, or upgrades a dependency, including its lockfile and version-catalog entries.",
       "emoji": "📦",
+      "key": "deps",
       "label": "Dependencies",
-      "breakingPolicy": "forbidden"
+      "tier": "process"
     },
     {
-      "tier": "process",
-      "key": "ai",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change to guidance on working in the repository itself, such as its `AGENTS.md` or a repo-local skill, or to the repository's agent configuration.",
       "emoji": "🤖",
+      "key": "ai",
       "label": "Agentic support",
-      "breakingPolicy": "forbidden"
+      "tier": "process"
     },
     {
-      "tier": "process",
-      "key": "docs",
       "aliases": ["doc"],
+      "breakingPolicy": "forbidden",
+      "description": "A change to documentation for human readers, such as a README, a guide, or a code comment.",
       "emoji": "📚",
+      "key": "docs",
       "label": "Documentation",
-      "breakingPolicy": "forbidden"
+      "tier": "process"
     },
     {
-      "tier": "process",
-      "key": "fmt",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change to formatting alone, such as whitespace or line wrapping, that leaves the content unchanged.",
       "emoji": "🎨",
+      "excludedFromChangelog": true,
+      "key": "fmt",
       "label": "Formatting",
-      "breakingPolicy": "forbidden",
-      "excludedFromChangelog": true
+      "tier": "process"
     }
   ],
-  "markers": {
-    "breaking": {
-      "emoji": "🚨",
-      "label": "Breaking"
-    }
-  }
+  "version": "1.1.0"
 }

package/dist/esm/work-types.schema.json

@@ -4,13 +4,18 @@
   "title": "Work types",
   "description": "Canonical taxonomy of commit work types used by release-kit. Drives section ordering, audience classification, and the `!` (breaking) policy. The structured single-source-of-truth for everything that previously lived in `DEFAULT_WORK_TYPES` and `cliff.toml.template` group definitions.",
   "type": "object",
-  "required": ["tiers", "types", "markers"],
+  "required": ["tiers", "types", "markers", "version"],
   "additionalProperties": false,
   "properties": {
     "$schema": {
       "type": "string",
       "description": "Optional reference to this schema for IDE validation."
     },
+    "version": {
+      "type": "string",
+      "description": "Semantic version of the data shape. Bumped when the structure changes in a way that breaks downstream consumers.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
     "tiers": {
       "type": "array",
       "description": "Render tiers in canonical order. Each entry's `tier` field must reference one of these names.",
@@ -55,7 +60,7 @@
     },
     "workType": {
       "type": "object",
-      "required": ["tier", "key", "aliases", "emoji", "label", "breakingPolicy"],
+      "required": ["tier", "key", "aliases", "emoji", "label", "breakingPolicy", "description"],
       "additionalProperties": false,
       "properties": {
         "tier": {
@@ -84,6 +89,11 @@
           "description": "Human-readable section label (rendered as `${emoji} ${label}` in changelogs and release notes).",
           "minLength": 1
         },
+        "description": {
+          "type": "string",
+          "description": "The changes that the type covers, read by an agent choosing a type for a change.",
+          "minLength": 1
+        },
         "breakingPolicy": {
           "type": "string",
           "description": "Policy governing the `!` (breaking) marker for this type. `forbidden`: `!` is a policy violation. `optional`: `!` is allowed. `required`: bare type is a policy violation; only the `!` form is accepted.",

package/dist/esm/workTypesData.d.ts

@@ -1,15 +1,13 @@
 /**
- * Canonical work-types data — runtime mirror of `work-types.json`.
+ * Canonical work-types data: the runtime mirror of `work-types.json`.
  *
- * `work-types.json` is the canonical SSOT for the taxonomy and is the file
- * `release-kit work-types check` / `:sync` operate on. This `.ts` mirror exists for
- * runtime consumption: ESM JSON imports require an `import attributes` clause that
- * esbuild's `bundle: false` mode strips, so a plain TS module is the most reliable way
- * to ship the data to consumers.
+ * `work-types.json` is release-kit's copy of the codeassembly canonical. This `.ts` mirror exists for
+ * runtime consumption: The compiler baseline does not enable JSON module imports, and a TS constant keeps
+ * `breakingPolicy` typed as its three-value union.
  *
- * A drift test (`workTypesData.unit.test.ts`) asserts that this constant deep-equals the
- * parsed contents of `work-types.json`. To change the taxonomy, edit BOTH files (or run
- * `nmr work-types:sync` to pull from upstream).
+ * `nmr work-types:sync` updates only the JSON, so copy its change here by hand. A drift test
+ * (`workTypesData.unit.test.ts`) asserts that this constant deep-equals the parsed contents of
+ * `work-types.json`.
  */
 /** Schema for a single entry. */
 export interface WorkTypeEntry {
@@ -18,6 +16,7 @@ export interface WorkTypeEntry {
     aliases: string[];
     emoji: string;
     label: string;
+    description: string;
     breakingPolicy: 'forbidden' | 'optional' | 'required';
     excludedFromChangelog?: boolean;
 }
@@ -34,6 +33,8 @@ export interface MarkerEntry {
 }
 /** Schema for the full data. */
 export interface WorkTypesData {
+    /** Semantic version of the data shape, as declared by the upstream canonical. */
+    version: string;
     tiers: string[];
     types: WorkTypeEntry[];
     /**

package/dist/esm/workTypesData.js

@@ -1,18 +1,60 @@
 export const WORK_TYPES_DATA = {
+    version: '1.1.0',
     tiers: ['public', 'internal', 'process'],
     types: [
-        { tier: 'public', key: 'feat', aliases: ['feature'], emoji: '🎉', label: 'Features', breakingPolicy: 'optional' },
-        { tier: 'public', key: 'drop', aliases: [], emoji: '🪦', label: 'Removed', breakingPolicy: 'required' },
-        { tier: 'public', key: 'deprecate', aliases: [], emoji: '🗑️', label: 'Deprecated', breakingPolicy: 'forbidden' },
-        { tier: 'public', key: 'fix', aliases: ['bugfix'], emoji: '🐛', label: 'Bug fixes', breakingPolicy: 'forbidden' },
-        { tier: 'public', key: 'sec', aliases: ['security'], emoji: '🔒', label: 'Security', breakingPolicy: 'optional' },
+        {
+            tier: 'public',
+            key: 'feat',
+            aliases: ['feature'],
+            emoji: '🎉',
+            label: 'Features',
+            description: 'A change that gives consumers a new capability or extends an existing one.',
+            breakingPolicy: 'optional',
+        },
+        {
+            tier: 'public',
+            key: 'drop',
+            aliases: [],
+            emoji: '🪦',
+            label: 'Removed',
+            description: 'A change that removes a capability or surface on which consumers depend.',
+            breakingPolicy: 'required',
+        },
+        {
+            tier: 'public',
+            key: 'deprecate',
+            aliases: [],
+            emoji: '🗑️',
+            label: 'Deprecated',
+            description: 'A change that marks a capability or surface for removal while the capability or surface keeps working.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'public',
+            key: 'fix',
+            aliases: ['bugfix'],
+            emoji: '🐛',
+            label: 'Bug fixes',
+            description: 'A change that corrects behavior that consumers meet and that differs from what was intended.',
+            breakingPolicy: 'optional',
+        },
+        {
+            tier: 'public',
+            key: 'sec',
+            aliases: ['security'],
+            emoji: '🔒',
+            label: 'Security',
+            description: 'A change that closes a vulnerability or hardens a consumer-facing surface against attack.',
+            breakingPolicy: 'optional',
+        },
         {
             tier: 'public',
             key: 'perf',
             aliases: ['performance'],
             emoji: '⚡',
             label: 'Performance',
-            breakingPolicy: 'forbidden',
+            description: 'A change that reduces the time, memory, or other resources that consumer-facing work uses, without changing its result.',
+            breakingPolicy: 'optional',
         },
         {
             tier: 'internal',
@@ -20,6 +62,7 @@ export const WORK_TYPES_DATA = {
             aliases: ['utility'],
             emoji: '🏗️',
             label: 'Internal features',
+            description: 'A change that adds or extends a capability that consumers do not use directly, such as a helper or an internal module.',
             breakingPolicy: 'forbidden',
         },
         {
@@ -28,19 +71,61 @@ export const WORK_TYPES_DATA = {
             aliases: [],
             emoji: '♻️',
             label: 'Refactoring',
+            description: 'A change that restructures existing code without changing its behavior.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'internal',
+            key: 'tests',
+            aliases: ['test'],
+            emoji: '🧪',
+            label: 'Tests',
+            description: 'A change confined to tests, test fixtures, or test helpers, including one that unblocks a build or a type check.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'process',
+            key: 'tooling',
+            aliases: [],
+            emoji: '⚙️',
+            label: 'Tooling',
+            description: 'A change to the tools used to develop the project: build, lint, formatting, and release configuration, and development scripts.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'process',
+            key: 'ci',
+            aliases: [],
+            emoji: '👷',
+            label: 'CI',
+            description: 'A change to continuous-integration workflows and their configuration.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'process',
+            key: 'deps',
+            aliases: ['dep'],
+            emoji: '📦',
+            label: 'Dependencies',
+            description: 'A change that adds, removes, or upgrades a dependency, including its lockfile and version-catalog entries.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'process',
+            key: 'ai',
+            aliases: [],
+            emoji: '🤖',
+            label: 'Agentic support',
+            description: "A change to guidance on working in the repository itself, such as its `AGENTS.md` or a repo-local skill, or to the repository's agent configuration.",
             breakingPolicy: 'forbidden',
         },
-        { tier: 'internal', key: 'tests', aliases: ['test'], emoji: '🧪', label: 'Tests', breakingPolicy: 'forbidden' },
-        { tier: 'process', key: 'tooling', aliases: [], emoji: '⚙️', label: 'Tooling', breakingPolicy: 'forbidden' },
-        { tier: 'process', key: 'ci', aliases: [], emoji: '👷', label: 'CI', breakingPolicy: 'forbidden' },
-        { tier: 'process', key: 'deps', aliases: ['dep'], emoji: '📦', label: 'Dependencies', breakingPolicy: 'forbidden' },
-        { tier: 'process', key: 'ai', aliases: [], emoji: '🤖', label: 'Agentic support', breakingPolicy: 'forbidden' },
         {
             tier: 'process',
             key: 'docs',
             aliases: ['doc'],
             emoji: '📚',
             label: 'Documentation',
+            description: 'A change to documentation for human readers, such as a README, a guide, or a code comment.',
             breakingPolicy: 'forbidden',
         },
         {
@@ -49,6 +134,7 @@ export const WORK_TYPES_DATA = {
             aliases: [],
             emoji: '🎨',
             label: 'Formatting',
+            description: 'A change to formatting alone, such as whitespace or line wrapping, that leaves the content unchanged.',
             breakingPolicy: 'forbidden',
             excludedFromChangelog: true,
         },

package/docs/api.md

@@ -0,0 +1,73 @@
+# Programmatic API
+
+How to build a release config by hand with `deriveWorkspaceConfig()`, the script-based approach that predates the CLI, and the workspace records that `resolveReleaseTags` takes.
+
+## Using `deriveWorkspaceConfig()` for manual configuration
+
+If you need to build a `MonorepoReleaseConfig` manually (e.g., for the legacy script-based approach), the exported `deriveWorkspaceConfig()` helper creates a `WorkspaceConfig` from a workspace-relative path. It reads the workspace's `package.json` to derive the tag prefix from the package name:
+
+```typescript
+import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
+
+// packages/arrays/package.json contains `"name": "@scope/arrays"`
+deriveWorkspaceConfig('packages/arrays');
+// => {
+//   dir: 'arrays',
+//   name: '@scope/arrays',
+//   tagPrefix: 'arrays-v',
+//   workspacePath: 'packages/arrays',
+//   packageFiles: ['packages/arrays/package.json'],
+//   changelogPaths: ['packages/arrays'],
+//   paths: ['packages/arrays/**'],
+// }
+```
+
+`dir` is the basename of the workspace path and is the stable internal identifier used by `--only`, `WorkspaceOverride.dir`, and the dependency graph. `tagPrefix` is derived from the unscoped `package.json` `name` — any leading `@scope/` is stripped — so tags reflect the package identity rather than the directory layout. For example, a workspace at `packages/core` with `"name": "@williamthorsen/nmr-core"` produces `tagPrefix: 'nmr-core-v'`, yielding tags like `nmr-core-v1.3.0`.
+
+The workspace's `package.json` must declare a non-empty `name` field; `deriveWorkspaceConfig()` throws otherwise. If two workspaces produce the same `tagPrefix` (because their unscoped names collide), `mergeMonorepoConfig()` throws and names the colliding workspaces so you can rename one.
+
+## Legacy script-based approach
+
+The CLI-driven approach is recommended for new setups. The script-based approach (using `runReleasePrepare` with a manually maintained config) is still supported for backward compatibility.
+
+```typescript
+// .github/scripts/release.config.ts
+import type { MonorepoReleaseConfig } from '@williamthorsen/release-kit';
+import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
+
+export const config: MonorepoReleaseConfig = {
+  workspaces: [deriveWorkspaceConfig('packages/arrays'), deriveWorkspaceConfig('packages/strings')],
+  formatCommand: 'npx prettier --write',
+};
+```
+
+```typescript
+// .github/scripts/release-prepare.ts
+import { runReleasePrepare } from '@williamthorsen/release-kit';
+import { config } from './release.config.ts';
+
+runReleasePrepare(config);
+```
+
+The key difference: the script-based approach requires manually listing every workspace, while the CLI auto-discovers them from `pnpm-workspace.yaml`.
+
+## `resolveReleaseTags` takes workspaces; `WorkspaceConfig` requires `workspacePath`
+
+Tag resolution is now driven by workspace records rather than a caller-supplied directory map, so `resolveReleaseTags` can report both the workspace `dir` and its `workspacePath` for every resolved tag.
+
+- `resolveReleaseTags` signature changed from `(workspaceMap?: Map<string, string>)` to `(workspaces?: readonly WorkspaceConfig[])`.
+- `WorkspaceConfig` gained a required `workspacePath: string` field.
+
+Replace direct `Map`-based calls with `deriveWorkspaceConfig()`, which now populates `workspacePath` for you:
+
+```diff
+-import { resolveReleaseTags } from '@williamthorsen/release-kit';
+-
+-const workspaceMap = new Map([['core', 'packages/core']]);
+-resolveReleaseTags(workspaceMap);
++import { deriveWorkspaceConfig, resolveReleaseTags } from '@williamthorsen/release-kit';
++
++resolveReleaseTags([deriveWorkspaceConfig('packages/core')]);
+```
+
+If you construct `WorkspaceConfig` objects directly, add `workspacePath` alongside the other required fields.

package/docs/changelogs.md

@@ -0,0 +1,70 @@
+# Changelogs
+
+What reaches a published tarball, what each `.meta/changelog.json` item contains, how the git-cliff config is resolved, and how release notes reach a README.
+
+Neither `CHANGELOG.md` nor `.meta/changelog.json` 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.
+
+## `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 and the commit's type permits it. See [`!` (breaking change) policy](work-types.md#-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 `deprecate` cannot carry `!` under the default breaking policy, and a `deprecate` still calls for 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](editorial-overrides.md#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.
+
+## cliff.toml setup
+
+The package includes a bundled `cliff.toml.template` that is used automatically when no custom config is found. The resolution order:
+
+| Priority | Path                          | Notes                                           |
+| -------- | ----------------------------- | ----------------------------------------------- |
+| 1        | `cliffConfigPath` in config   | Explicit path, returned without existence check |
+| 2        | `.config/git-cliff.toml`      | Project-level override                          |
+| 3        | `cliff.toml`                  | Repo root fallback                              |
+| 4        | Bundled `cliff.toml.template` | Automatic fallback                              |
+
+The bundled template provides a generic git-cliff configuration that:
+
+- Strips issue-ticket prefixes matching `^[A-Z]+-\d+\s+` (e.g., `TOOL-123 `, `AFG-456 `)
+- Handles both `type: description` and `workspace|type: description` commit formats
+- Groups commits by work type via `[git].commit_parsers`
+
+The body template is intentionally empty: release-kit reads cliff's `--context` JSON output and renders `CHANGELOG.md` in-process via `renderChangelogMarkdown` (see [How it works](../README.md#how-it-works) for the rationale). The `[git].commit_parsers` section remains load-bearing for `--context` group assignment.
+
+To customize, scaffold a local copy with `release-kit init --with-config` and edit `.config/git-cliff.toml`. Edit only the `[git]` section — body-template changes have no effect.
+
+## Release-notes injection
+
+With `releaseNotes.shouldInjectIntoReadme` set to `true`, `release-kit publish` writes each package's release notes into its `README.md` for the duration of the publish, then restores the file. The notes are the all-audience sections of the released version's entry in `.meta/changelog.json`, under a `## Release notes — v<version> (<date>)` heading, and they replace whatever lies between the marker pair:
+
+```markdown
+<!-- section:release-notes --><!-- /section:release-notes -->
+```
+
+A README without the marker pair receives the notes at its top, above its title, and release-kit's readyup kit reports a README that lacks the markers. Injection is skipped with a warning when `changelogJson.enabled` is `false`, when the version has no entry, or when the entry has no all-audience content. `release-kit prepare --with-release-notes` writes the same injected README as a [preview](releasing.md#previewing-release-notes-with---with-release-notes).