@williamthorsen/release-kit 11.0.0 → 13.0.0

package/dist/esm/types.d.ts

@@ -1,3 +1,4 @@
+import type { BreakingPolicy } from '@williamthorsen/change-grammar';
 import { z } from 'zod';
 /** Semver release type for version bumping. */
 export type ReleaseType = 'major' | 'minor' | 'patch';
@@ -11,38 +12,41 @@ export interface ChangelogItem {
     /**
      * Whether this item represents a breaking change.
      *
-     * `true` when the commit subject carries the `!` prefix (e.g. `feat!:` or `drop(scope)!:`) and
-     * the commit's work-type policy permits it, so the item agrees with the version bump.
-     * The `BREAKING CHANGE:` body footer is intentionally NOT considered here. Renderers prefix
-     * breaking-item bullets with the marker constructed from `WORK_TYPES_DATA.markers.breaking`
-     * (rendered as `🚨 **Breaking:** ` with the canonical SSOT values) to surface them prominently
-     * in release notes.
+     * `true` when the commit subject has the `!` marker (e.g. `feat!:` or `drop(scope)!:`), or the
+     * change-record entry from which the item derives sets `breaking: true`, and the work-type policy
+     * permits it, so that the item agrees with the version bump. The `BREAKING CHANGE:` body footer
+     * does not set it.
      */
     breaking?: boolean;
     /**
-     * Migration instruction for a consumer, taken from the `Migration:` paragraph of `body`.
+     * Migration instruction for a consumer, taken from the `Migration:` paragraph of `body`, or from
+     * the `migration` of the change-record entry from which the item derives.
      *
-     * Derived from `body` wherever `body` is set, and absent where the body carries no labeled
-     * paragraph. Independent of `breaking`: a `deprecate` commit cannot carry `!` under the default
-     * breaking policy and still calls for a migration. `body` keeps the paragraph, so
-     * `CHANGELOG.md` goes on rendering it in place.
+     * On a title-derived item, derived from `body` whenever `body` is set, and absent when the body
+     * does not contain any labeled paragraph. Independent of `breaking`: A `deprecate` commit cannot
+     * take `!` under the default breaking policy and still calls for a migration. `body` keeps the
+     * paragraph, so `CHANGELOG.md` goes on rendering it in place.
      */
     migration?: string;
     /**
-     * Full git commit SHA when known. Captured from git-cliff's `--context` output and
+     * Full git commit SHA when known. Captured from the commit's release window and
      * persisted in `changelog.json` so that override files can target items by hash. Synthetic
      * propagation entries (`buildSyntheticChangelogEntry`, `buildEmptyReleaseEntry`) leave
-     * this field absent — they have no underlying commit.
+     * this field absent, because they do not have any underlying commit.
      */
     hash?: string;
+    /**
+     * 1-based position of the change-record entry from which this item derives, counted over the block's entries as
+     * written. Absent for an item derived from the commit's title.
+     */
+    entry?: number;
 }
 /** A grouped section within a changelog entry (e.g., "Features", "Bug fixes"). */
 export interface ChangelogSection {
     /**
-     * Section title carrying the leading emoji prefix used by `cliff.toml.template` group
-     * definitions (e.g. `"🐛 Bug fixes"`). The `<!-- NN -->` canonical-order HTML comment
-     * is stripped during transform; the emoji remains. Callers that match against `title`
-     * (e.g. `sectionOrder` configs) must include the emoji prefix.
+     * Section title, read from the work type of the commit or of its change-record entry. A default
+     * title begins with the type's emoji (e.g. `"🐛 Bug fixes"`), which an exact match against
+     * `title`, such as a `sectionOrder` list, must include.
      */
     title: string;
     audience: ChangelogAudience;
@@ -61,13 +65,12 @@ export interface ChangelogJsonConfig {
     devOnlySections: string[];
 }
 /**
- * Editorial override for a single changelog item, keyed by commit hash (or hash prefix) in
- * the override file. All fields are optional; an entry with no fields is a validation error.
+ * Editorial override for changelog items, keyed in the override file by `<hash>` (every item of the commit) or
+ * `<hash>:<n>` (the item derived from the commit's `n`th change-record entry), where the hash is lowercase hex
+ * matched as a prefix. All fields are optional; an entry without any fields is a validation error.
  *
- * `audience` declares the full forward-compatible vocabulary, but only `'skip'` is currently
- * supported at runtime. `'all'` and `'dev'` reclassification is reserved for a v2 follow-up
- * and rejected by the validator with an explicit "not yet supported" error so the on-disk
- * format remains stable through the v1→v2 transition.
+ * `audience` admits `'all'` and `'dev'`, but the validator rejects both with a "not yet supported"
+ * error; only `'skip'` takes effect.
  */
 export interface ChangelogOverride {
     audience?: 'all' | 'dev' | 'skip';
@@ -75,22 +78,20 @@ export interface ChangelogOverride {
     body?: string;
     breaking?: boolean;
 }
-/** On-disk shape of `.meta/changelog-overrides.json`: a flat record keyed by commit hash or prefix. */
+/**
+ * Overrides in `.meta/changelog-overrides.json`: a flat record keyed by `<hash>` or `<hash>:<n>`. The file may also contain
+ * a top-level `$schema` string, which the loader drops.
+ */
 export type ChangelogOverridesFile = Record<string, ChangelogOverride>;
 /** Configuration for release notes consumption (README injection). */
 export interface ReleaseNotesConfig {
     shouldInjectIntoReadme: boolean;
 }
-/**
- * Project-release config after merging defaults. Mirrors the `ReleaseNotesConfig`/
- * `ResolvedReleaseNotesConfig`-style split: optional fields in `ProjectConfig` become
- * required in `ResolvedProjectConfig`.
- */
+/** Project-release config after merging defaults: `ProjectConfig` with every field required. */
 export interface ResolvedProjectConfig {
     /**
-     * Resolved commit window for the project release: the git pathspecs and git-cliff include-paths
-     * that select which commits the stage considers. Defaults to the union of every contributing
-     * workspace's `paths`.
+     * Resolved commit window for the project release: the git pathspecs that select which commits
+     * the stage considers. Defaults to the union of every contributing workspace's `paths`.
      */
     paths: string[];
     /** Resolved tag prefix for project-level tags. */
@@ -102,11 +103,8 @@ export interface PropagationSource {
     newVersion: string;
 }
 /**
- * A `!`-policy violation detected while parsing commits during release preparation.
- *
- * Surfaces from `releasePrepare`, `releasePrepareMono`, and `releasePrepareProject` via the
- * `policyViolations` field on each per-workspace/project result. The policy itself is enforced
- * tolerantly at release time — violations are collected and reported, never fail the release.
+ * A `!`-policy violation detected while reading the unreleased window during release preparation. Violations are
+ * reported and never fail the release.
  */
 export interface PolicyViolation {
     /** Full hash of the offending commit. */
@@ -115,17 +113,63 @@ export interface PolicyViolation {
     commitSubject: string;
     /** Resolved canonical work type whose policy was violated. */
     type: string;
-    /** Where the violation was detected: `'prefix'` for `!`, `'body'` for `BREAKING CHANGE:` footer. */
-    surface: 'prefix' | 'body';
+    /**
+     * Where the violation was detected: `'prefix'` for `!`, `'body'` for `BREAKING CHANGE:` footer, `'entry'` for a
+     * change-record entry's `breaking`.
+     */
+    surface: 'prefix' | 'body' | 'entry';
+    /** 1-based position of the offending change-record entry; present only for surface `'entry'`. */
+    entryPosition?: number;
+}
+/** A commit whose `change-record` block could not be read, so that its changelog item came from its title. */
+export interface MalformedChangeRecordBlock {
+    /** Full hash of the commit. */
+    commitHash: string;
+    /** First line of the commit message. */
+    commitSubject: string;
+    /** The defect that stopped the read. */
+    reason: string;
 }
 /**
- * Result of preparing a single workspace (package) for release when a release was produced.
- *
- * `currentVersion`, `newVersion`, `tag`, `bumpedFiles`, and `changelogFiles` are always
- * populated. `releaseType` stays optional because it is left undefined for
- * `--set-version` workspaces. `parsedCommitCount` stays optional because the legacy
- * single-package bump-override path does not populate it. `commits` stays optional
- * because propagation-only releases have no direct commits.
+ * A change-record entry whose type the work-type taxonomy does not declare, so that it did not yield any changelog
+ * item.
+ */
+export interface UndeclaredEntryType {
+    /** Full hash of the commit. */
+    commitHash: string;
+    /** First line of the commit message. */
+    commitSubject: string;
+    /** 1-based position of the entry in its block. */
+    entryPosition: number;
+    /** The type as the entry declares it. */
+    type: string;
+}
+/** A change-record entry scope that does not name any workspace whose unreleased window contains its commit. */
+export interface UnroutedEntryScope {
+    /** Full hash of the commit. */
+    commitHash: string;
+    /** First line of the commit message. */
+    commitSubject: string;
+    /** 1-based position of the entry in its block. */
+    entryPosition: number;
+    /** The scope as the entry declares it. */
+    scope: string;
+}
+/**
+ * What `prepare` did with the existing `##` sections of one `CHANGELOG.md` that the regenerated file does not render
+ * from entries.
+ */
+export interface ChangelogPreservation {
+    /** The `CHANGELOG.md` path. */
+    file: string;
+    /** Versions whose sections were kept verbatim, because neither the built entries nor `changelog.json` contain them. */
+    preservedVersions: string[];
+    /** Headings of the sections that do not name any version, which the regenerated file does not contain. */
+    droppedUnversionedHeadings: string[];
+}
+/**
+ * Result of preparing a single workspace (package) for release when a release was produced. `releaseType` is absent
+ * for `--set-version`.
  */
 export interface ReleasedWorkspaceResult {
     status: 'released';
@@ -134,18 +178,21 @@ export interface ReleasedWorkspaceResult {
     previousTag?: string;
     commitCount: number;
     /**
-     * Count of commits that parsed into a recognized work type. Always populated for
-     * results produced by the unified `decideRelease` algorithm (the monorepo path),
-     * including the no-commits case where it is `0`. May be absent for results
-     * produced by the legacy single-package executor's bump-override path. Use
-     * `bumpOverride` (not `parsedCommitCount === undefined`) as the signal for "the
-     * user supplied --bump=X".
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does
+     * not contain any commits or when none does. Absent for `--set-version` and propagation-only
+     * workspaces. `bumpOverride`, not this count, signals that the user supplied `--bump=X`.
      */
     parsedCommitCount?: number;
-    /** Commits that could not be parsed into a recognized work type. */
+    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
     unparseableCommits?: Commit[];
-    /** Policy violations detected while parsing this workspace's commits; omitted when none. */
+    /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
     policyViolations?: PolicyViolation[];
+    /** Commits of the unreleased window whose `change-record` block could not be read; omitted when none. */
+    malformedBlocks?: MalformedChangeRecordBlock[];
+    /** Change-record entries of the unreleased window whose type is undeclared; omitted when none. */
+    undeclaredEntryTypes?: UndeclaredEntryType[];
+    /** Change-record entry scopes of the unreleased window that route their entry nowhere; omitted when none. */
+    unroutedEntryScopes?: UnroutedEntryScope[];
     releaseType?: ReleaseType;
     currentVersion: string;
     newVersion: string;
@@ -154,24 +201,28 @@ export interface ReleasedWorkspaceResult {
     changelogFiles: string[];
     /** Release-notes preview files; present only under `--with-release-notes`. */
     previewFiles?: string[];
-    /** Raw commits associated with this workspace (present for direct releases, absent for propagation-only). */
+    /**
+     * Per `CHANGELOG.md`, the existing sections that were kept or dropped; omitted when `prepare` did not keep or drop
+     * any.
+     */
+    changelogPreservation?: ChangelogPreservation[];
+    /** Raw commits of the workspace's unreleased window. */
     commits?: Commit[];
     /**
-     * Present when `--bump=X` was supplied and selected the release level for this workspace.
-     * Distinguishes a bump-override release from a `--force` fallback or a natural-bump release;
-     * consumed by the renderer to label the release accurately.
+     * Present when `--bump=X` was supplied and selected the release level for this workspace, which
+     * distinguishes a bump-override release from a `--force` fallback or a natural-bump release.
      */
     bumpOverride?: ReleaseType;
     /** Dependencies that triggered a propagated bump (present for propagated or mixed workspaces). */
     propagatedFrom?: PropagationSource[];
+    /** Present when propagation alone set the bump, the workspace's own commits having called for none. */
+    propagatedOnly?: true;
     /** Present when this workspace was written via `--set-version`; the explicit version that was applied. */
     setVersion?: string;
 }
 /**
- * Result of preparing a single workspace (package) for release when the release was skipped.
- *
- * Carries diagnostic data (`commitCount`, `parsedCommitCount`, `unparseableCommits`,
- * `previousTag`) plus the human-readable `skipReason`. Release-only fields are absent.
+ * Result of preparing a single workspace (package) for release when the release was skipped: the diagnostic fields
+ * and a human-readable `skipReason`, without the release-only fields.
  */
 export interface SkippedWorkspaceResult {
     status: 'skipped';
@@ -180,14 +231,20 @@ export interface SkippedWorkspaceResult {
     previousTag?: string;
     commitCount: number;
     /**
-     * Count of commits that parsed into a recognized work type. May be absent for results
-     * produced by the legacy single-package executor's bump-override path.
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does not contain any
+     * commits or when none does.
      */
-    parsedCommitCount?: number;
-    /** Commits that could not be parsed into a recognized work type. */
+    parsedCommitCount: number;
+    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
     unparseableCommits?: Commit[];
-    /** Policy violations detected while parsing this workspace's commits; omitted when none. */
+    /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
     policyViolations?: PolicyViolation[];
+    /** Commits of the unreleased window whose `change-record` block could not be read; omitted when none. */
+    malformedBlocks?: MalformedChangeRecordBlock[];
+    /** Change-record entries of the unreleased window whose type is undeclared; omitted when none. */
+    undeclaredEntryTypes?: UndeclaredEntryType[];
+    /** Change-record entry scopes of the unreleased window that route their entry nowhere; omitted when none. */
+    unroutedEntryScopes?: UnroutedEntryScope[];
     skipReason: string;
 }
 /**
@@ -200,26 +257,27 @@ export type WorkspacePrepareResult = ReleasedWorkspaceResult | SkippedWorkspaceR
 /**
  * Result of preparing a project-level release when a release was produced.
  *
- * Mirrors `ReleasedWorkspaceResult` minus the workspace-only fields (`name`,
- * `propagatedFrom`, `setVersion`). Project releases never propagate and never use
- * `--set-version`, so `releaseType`, `currentVersion`, `newVersion`, `tag`, and
- * `commits` are all required.
+ * Mirrors `ReleasedWorkspaceResult` without the workspace-only fields. Project releases never propagate and never
+ * use `--set-version`, so `releaseType`, `parsedCommitCount`, and `commits` are required.
  */
 export interface ReleasedProjectResult {
     status: 'released';
     previousTag?: string;
     commitCount: number;
     /**
-     * Count of commits that parsed into a recognized work type. Always populated by the
-     * unified `decideRelease` algorithm — `0` when there are no commits or when none
-     * parse. Use `bumpOverride` (not `parsedCommitCount === 0`) as the signal for "the
-     * user supplied --bump=X".
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does
+     * not contain any commits or when none does. `bumpOverride`, not a zero count, signals that the
+     * user supplied `--bump=X`.
      */
     parsedCommitCount: number;
-    /** Commits that could not be parsed into a recognized work type. */
+    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
     unparseableCommits?: Commit[];
-    /** Policy violations detected while parsing the project's commits; omitted when none. */
+    /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
     policyViolations?: PolicyViolation[];
+    /** Commits of the unreleased window whose `change-record` block could not be read; omitted when none. */
+    malformedBlocks?: MalformedChangeRecordBlock[];
+    /** Change-record entries of the unreleased window whose type is undeclared; omitted when none. */
+    undeclaredEntryTypes?: UndeclaredEntryType[];
     releaseType: ReleaseType;
     currentVersion: string;
     newVersion: string;
@@ -228,35 +286,40 @@ export interface ReleasedProjectResult {
     changelogFiles: string[];
     /** Release-notes preview files; present only under `--with-release-notes`. */
     previewFiles?: string[];
+    /**
+     * Per `CHANGELOG.md`, the existing sections that were kept or dropped; omitted when `prepare` did not keep or drop
+     * any.
+     */
+    changelogPreservation?: ChangelogPreservation[];
     /** Raw commits in the project's contributing-paths window since the last project tag. */
     commits: Commit[];
     /**
-     * Present when `--bump=X` was supplied and selected the release level for the project.
-     * Distinguishes a bump-override release from a `--force` fallback or a natural-bump release;
-     * consumed by the renderer to label the release accurately.
+     * Present when `--bump=X` was supplied and selected the release level for the project, which
+     * distinguishes a bump-override release from a `--force` fallback or a natural-bump release.
      */
     bumpOverride?: ReleaseType;
 }
 /**
- * Result of preparing a project-level release when the release was skipped.
- *
- * Carries diagnostic data (`commitCount`, `parsedCommitCount`, `unparseableCommits`,
- * `previousTag`) plus the human-readable `skipReason`. Release-only fields are absent.
+ * Result of preparing a project-level release when the release was skipped: the diagnostic fields and a
+ * human-readable `skipReason`, without the release-only fields.
  */
 export interface SkippedProjectResult {
     status: 'skipped';
     previousTag?: string;
     commitCount: number;
     /**
-     * Count of commits that parsed into a recognized work type. Always populated by the
-     * unified `decideRelease` algorithm — `0` when there are no commits or when none
-     * parse.
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does not contain any
+     * commits or when none does.
      */
     parsedCommitCount: number;
-    /** Commits that could not be parsed into a recognized work type. */
+    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
     unparseableCommits?: Commit[];
-    /** Policy violations detected while parsing the project's commits; omitted when none. */
+    /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
     policyViolations?: PolicyViolation[];
+    /** Commits of the unreleased window whose `change-record` block could not be read; omitted when none. */
+    malformedBlocks?: MalformedChangeRecordBlock[];
+    /** Change-record entries of the unreleased window whose type is undeclared; omitted when none. */
+    undeclaredEntryTypes?: UndeclaredEntryType[];
     skipReason: string;
 }
 /**
@@ -264,8 +327,8 @@ export interface SkippedProjectResult {
  *
  * Discriminated by `status`: `ReleasedProjectResult` for produced releases,
  * `SkippedProjectResult` for skips. `PrepareResult.project === undefined` means either that
- * no project block is configured or that `--only` narrowed the run, which skips the stage
- * before it can produce a result; the skip is surfaced as a run warning instead.
+ * the config does not declare a `project` block or that `--only` narrowed the run, which skips
+ * the stage before it can produce a result; `prepare` reports the skip as a run warning instead.
  */
 export type ProjectPrepareResult = ReleasedProjectResult | SkippedProjectResult;
 /** Aggregate result of the prepare workflow for both single-package and monorepo modes. */
@@ -276,7 +339,7 @@ export interface PrepareResult {
         command: string;
         files: string[];
     } | undefined;
-    /** Warnings surfaced during preparation (e.g., circular dependency detection). */
+    /** Warnings reported during preparation (e.g., circular dependency detection). */
     warnings?: string[] | undefined;
     /** Result of the project-level release stage (present only when `config.project` is configured and the stage ran). */
     project?: ProjectPrepareResult | undefined;
@@ -287,6 +350,12 @@ export interface WorkTypeConfig {
     header: string;
     /** Optional aliases that map to this work type (e.g., 'feature' -> 'feat'). */
     aliases?: string[] | undefined;
+    /**
+     * Keeps commits and change-record entries of this type out of every changelog. They do not yield
+     * any item, so they contribute nothing to the version bump, and the release report does not
+     * list them as unparseable.
+     */
+    excludedFromChangelog?: boolean | undefined;
 }
 /**
  * Defines which commit types trigger major or minor version bumps.
@@ -311,15 +380,15 @@ export declare const legacyIdentitySchema: z.ZodObject<{
     tagPrefix: z.ZodString;
 }, z.core.$strict>;
 /**
- * A single historical identity snapshot for a workspace. Both fields are required — a full
- * tuple stays unambiguous across any number of future renames.
+ * A single historical identity snapshot for a workspace. Both fields are required, because a full
+ * tuple stays unambiguous across any number of renames.
  */
 export type LegacyIdentity = z.infer<typeof legacyIdentitySchema>;
 /**
  * Schema for a package that once lived in this repo but has since been extracted or removed.
  *
  * Unlike `legacyIdentitySchema`, retired packages are never consulted for baseline lookup
- * or changelog attribution — they acknowledge historical tag prefixes and suppress
+ * or changelog attribution; they acknowledge historical tag prefixes and suppress
  * undeclared-candidate warnings.
  */
 export declare const retiredPackageSchema: z.ZodObject<{
@@ -361,6 +430,7 @@ export declare const releaseNotesInputSchema: z.ZodObject<{
 export declare const workTypeConfigSchema: z.ZodObject<{
     header: z.ZodString;
     aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludedFromChangelog: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 /** Schema for the `versionPatterns` block. Both arrays are required when the field is provided. */
 export declare const versionPatternsSchema: z.ZodObject<{
@@ -369,9 +439,8 @@ export declare const versionPatternsSchema: z.ZodObject<{
 }, z.core.$strict>;
 /** Schema for a single `breakingPolicies` value. */
 export declare const breakingPolicyValueSchema: z.ZodEnum<{
-    forbidden: "forbidden";
     optional: "optional";
-    required: "required";
+    forbidden: "forbidden";
 }>;
 /** Schema for a single label's spec in the `repoLabels.labels` record. */
 export declare const labelSpecSchema: z.ZodObject<{
@@ -381,7 +450,7 @@ export declare const labelSpecSchema: z.ZodObject<{
 /**
  * A label's color and optional description; the name is the record key in `repoLabels.labels`.
  * An omitted description resolves to empty, which the generated labels file declares explicitly so that a sync
- * clears whatever description the label carries today.
+ * clears whatever description the label has on the repo.
  */
 export type LabelSpec = z.infer<typeof labelSpecSchema>;
 /**
@@ -389,10 +458,10 @@ export type LabelSpec = z.infer<typeof labelSpecSchema>;
  * the GitHub repo, distinct from labels applied to PRs and issues).
  *
  * Resolution is an ordered fold with last-writer-wins: presets in `extends` order, then the `labels` record,
- * where an entry adds a label, replaces one an earlier layer defined, or removes it (`null`). Names match
+ * in which an entry adds a label, replaces one that an earlier layer defined, or removes it (`null`). Names match
  * case-insensitively, as GitHub matches them, and the replacing layer's spelling wins.
  * Two misstatements are resolve-time errors (`resolveLabels`), not schema errors: `labels` keys that differ only in
- * case, and a `null` naming a label that no earlier layer defined.
+ * case, and a `null` naming a label not defined by any earlier layer.
  */
 export declare const repoLabelsSchema: z.ZodObject<{
     extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -406,16 +475,14 @@ export type RepoLabelsConfig = z.infer<typeof repoLabelsSchema>;
 /** Schema for the consumer-facing config file shape (`.config/release-kit.config.ts`). */
 export declare const releaseKitConfigSchema: z.ZodObject<{
     breakingPolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
-        forbidden: "forbidden";
         optional: "optional";
-        required: "required";
+        forbidden: "forbidden";
     }>>>;
     changelogJson: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         outputPath: z.ZodOptional<z.ZodString>;
         devOnlySections: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
-    cliffConfigPath: z.ZodOptional<z.ZodString>;
     formatCommand: z.ZodOptional<z.ZodString>;
     project: z.ZodOptional<z.ZodObject<{
         paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -452,6 +519,7 @@ export declare const releaseKitConfigSchema: z.ZodObject<{
     workTypes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         header: z.ZodString;
         aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        excludedFromChangelog: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 /**
@@ -461,14 +529,16 @@ export declare const releaseKitConfigSchema: z.ZodObject<{
 export type ReleaseKitConfig = z.infer<typeof releaseKitConfigSchema>;
 /** A raw commit from the git log. */
 export interface Commit {
-    /** The full commit message (first line). */
+    /** The commit message, subject and body together. */
     message: string;
+    /** The first line of the commit message. */
+    subject: string;
     /** The commit hash. */
     hash: string;
 }
 /** A commit that has been parsed to extract structured metadata. */
 export interface ParsedCommit {
-    /** The original commit message. */
+    /** The original commit message, subject and body together. */
     message: string;
     /** The commit hash. */
     hash: string;
@@ -489,12 +559,11 @@ export interface WorkspaceConfig {
     name: string;
     /** The git tag prefix for this workspace (e.g., 'nmr-core-v'), derived from the unscoped `package.json` name. */
     tagPrefix: string;
-    /** Workspace-relative path to the package root (e.g., `packages/core`). */
+    /** Repo-relative path to the package root (e.g., `packages/core`). */
     workspacePath: string;
     /**
      * Whether this workspace can be published to a registry. `true` when `package.json#private`
-     * is absent or `false`; `false` only when `private === true`. Consumed by `release-kit publish`
-     * to filter unpublishable workspaces; other commands ignore this field.
+     * is absent or `false`; `false` only when `private === true`.
      */
     isPublishable: boolean;
     /** Paths to package.json files to bump. */
@@ -523,15 +592,13 @@ export interface MonorepoReleaseConfig {
      * When provided, replaces the default entirely.
      * Pass `{}` to disable enforcement (parser falls back to `'optional'` for missing types).
      */
-    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    breakingPolicies?: Record<string, BreakingPolicy>;
     /**
      * Shell command to run after all changelogs are generated (e.g., 'pnpm run fmt').
      * Modified file paths (package.json files and CHANGELOGs) are appended as space-separated
      * arguments. Paths are repo-relative; file paths containing spaces are not supported.
      */
     formatCommand?: string;
-    /** Path to the cliff.toml file; defaults to 'cliff.toml' when absent. */
-    cliffConfigPath?: string;
     /**
      * Maps scope shorthand names to their canonical names.
      * When a commit uses `shorthand|type: description` or `type(shorthand): description`,
@@ -543,11 +610,13 @@ export interface MonorepoReleaseConfig {
     /** Controls release notes consumption (README injection). */
     releaseNotes: ReleaseNotesConfig;
     /**
-     * Project-level release config. Present iff the consumer declared `project: {}`.
-     * When present, `releasePrepareMono` runs an additional project-release stage after the per-workspace loop.
+     * Project-level release config. Present when the config declares a `project` block, in which case
+     * `prepare` runs a project-release stage after the per-workspace loop.
      */
     project?: ResolvedProjectConfig;
 }
+/** Monorepo config as seen by the prepare workflow, which does not read release-notes configuration. */
+export type MonorepoPrepareConfig = Omit<MonorepoReleaseConfig, 'releaseNotes'>;
 /** Configuration for the release workflow. */
 export interface ReleaseConfig {
     /** The git tag prefix used to identify version tags (e.g., 'v'). */
@@ -565,15 +634,13 @@ export interface ReleaseConfig {
      * provided, replaces the default entirely. Pass `{}` to disable enforcement (parser falls
      * back to `'optional'` for missing types).
      */
-    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    breakingPolicies?: Record<string, BreakingPolicy>;
     /**
      * Shell command to run after changelog generation (e.g., 'pnpm run fmt').
      * Modified file paths (package.json files and CHANGELOGs) are appended as space-separated arguments.
      * Paths are repo-relative; file paths containing spaces are not supported.
      */
     formatCommand?: string;
-    /** Path to the cliff.toml file; defaults to 'cliff.toml' when absent. */
-    cliffConfigPath?: string;
     /**
      * Maps scope shorthand names to their canonical names.
      * When a commit uses `shorthand|type: description` or `type(shorthand): description`,
@@ -585,3 +652,5 @@ export interface ReleaseConfig {
     /** Controls release notes consumption (README injection). */
     releaseNotes: ReleaseNotesConfig;
 }
+/** Single-package config as seen by the prepare workflow, which does not read release-notes configuration. */
+export type PrepareConfig = Omit<ReleaseConfig, 'releaseNotes'>;

package/dist/esm/types.js

@@ -41,6 +41,7 @@ export const workTypeConfigSchema = z
     .object({
     header: z.string(),
     aliases: z.array(z.string()).optional(),
+    excludedFromChangelog: z.boolean().optional(),
 })
     .strict();
 export const versionPatternsSchema = z
@@ -49,7 +50,7 @@ export const versionPatternsSchema = z
     minor: z.array(z.string()),
 })
     .strict();
-export const breakingPolicyValueSchema = z.enum(['forbidden', 'optional', 'required']);
+export const breakingPolicyValueSchema = z.enum(['forbidden', 'optional']);
 export const labelSpecSchema = z
     .object({
     color: z.string().min(1),
@@ -66,7 +67,6 @@ export const releaseKitConfigSchema = z
     .object({
     breakingPolicies: z.record(z.string(), breakingPolicyValueSchema).optional(),
     changelogJson: changelogJsonInputSchema.optional(),
-    cliffConfigPath: z.string().min(1).optional(),
     formatCommand: z.string().min(1).optional(),
     project: projectConfigSchema.optional(),
     releaseNotes: releaseNotesInputSchema.optional(),

package/dist/esm/validateConfig.d.ts

@@ -1,16 +1,7 @@
 import { type ReleaseKitConfig } from './types.js';
 /**
- * Validate a raw config object loaded from `.config/release-kit.config.ts`.
- *
- * Single source of truth: `releaseKitConfigSchema` in `types.ts`, with
- * `ReleaseKitConfig = z.infer<typeof releaseKitConfigSchema>`. Adding a field to the type
- * without updating the schema is impossible because the type *is* derived from the
- * schema.
- *
- * Pipeline: (1) preprocess strips deprecated keys and emits migration-guidance errors;
- * (2) `releaseKitConfigSchema.safeParse` does shape validation; (3) post-parse cross-field
- * checks (full-tuple duplicates, retired-vs-legacy collisions) operate on the typed
- * result.
+ * Validates a raw config object loaded from `.config/release-kit.config.ts`. Returns `{}` with the errors for a config
+ * that fails the schema parse, and runs the cross-field checks on one that passes.
  */
 export declare function validateConfig(raw: unknown): {
     config: ReleaseKitConfig;