@williamthorsen/release-kit 11.0.0 → 12.0.0

package/dist/esm/reportPrepare.js

@@ -1,8 +1,6 @@
 import { formatGlyphLine, formatStatusLine, measureGlyphColumn, STATUS_GLYPHS, truncateToWidth, } from '@williamthorsen/nmr-core';
 import { bold, dim, sectionHeader } from "./format.js";
 import { RELEASE_GLYPHS } from "./glyphs.js";
-import { GIT_CLIFF_NPX_ARGS } from "./runGitCliff.js";
-const CLIFF_DRY_RUN_COMMAND = `npx ${GIT_CLIFF_NPX_ARGS.join(' ')} ...`;
 const SUBJECT_COLUMN_BUDGET = 72;
 export function reportPrepare(plan, options) {
     const isMultiWorkspace = plan.workspaces.some((w) => w.name !== undefined) || plan.project !== undefined;
@@ -27,6 +25,7 @@ function formatSingleWorkspace(result, options) {
     formatUnparseableWarning(lines, workspace, style);
     formatPolicyViolations(lines, workspace.policyViolations, style);
     if (workspace.status === 'skipped') {
+        formatChangeRecordWarnings(lines, workspace, style);
         lines.push(formatStatusLine(style, 'skipped', workspace.skipReason));
         formatWarnings(lines, result, style);
         return lines.join('\n');
@@ -49,6 +48,7 @@ function formatSingleWorkspace(result, options) {
     else if (workspace.releaseType !== undefined) {
         lines.push(formatGlyphLine(RELEASE_GLYPHS, style, 'bump', `${workspace.currentVersion} → ${bold(workspace.newVersion)} (${workspace.releaseType})`));
     }
+    formatChangeRecordWarnings(lines, workspace, style);
     formatBumpFiles(lines, workspace, dryRun);
     lines.push(dim('Generating changelogs...'));
     formatChangelogFiles(lines, workspace, dryRun);
@@ -87,6 +87,8 @@ function formatProjectSection(lines, project, dryRun, style) {
     lines.push(dim(`  Found ${project.commitCount} commits ${since}`));
     formatPolicyViolations(lines, project.policyViolations, style, '  ');
     if (project.status === 'skipped') {
+        formatUnparseableWarning(lines, project, style, '  ');
+        formatChangeRecordWarnings(lines, project, style, '  ');
         lines.push(`  ${formatStatusLine(style, 'skipped', project.skipReason)}`);
         return;
     }
@@ -97,7 +99,8 @@ function formatProjectSection(lines, project, dryRun, style) {
     if (project.bumpOverride !== undefined) {
         lines.push(`  Using bump override: ${project.bumpOverride}`);
     }
-    formatProjectUnparseable(lines, project, style);
+    formatUnparseableWarning(lines, project, style, '  ');
+    formatChangeRecordWarnings(lines, project, style, '  ');
     lines.push(dim(`  Bumping versions (${releaseType})...`), `  ${formatGlyphLine(RELEASE_GLYPHS, style, 'bump', `${currentVersion} → ${bold(newVersion)} (${releaseType})`)}`);
     for (const file of project.bumpedFiles) {
         if (dryRun) {
@@ -110,7 +113,7 @@ function formatProjectSection(lines, project, dryRun, style) {
     lines.push(dim('  Generating changelogs...'));
     for (const file of project.changelogFiles) {
         if (dryRun) {
-            lines.push(dim(`    [dry-run] Would run: ${CLIFF_DRY_RUN_COMMAND} --output ${file}`));
+            lines.push(dim(`    [dry-run] Would generate changelog: ${file}`));
         }
         else {
             lines.push(dim(`    Generating changelog: ${file}`));
@@ -119,21 +122,6 @@ function formatProjectSection(lines, project, dryRun, style) {
     formatPreviewFiles(lines, project, dryRun, '  ');
     lines.push(`  ${formatGlyphLine(RELEASE_GLYPHS, style, 'tag', bold(tag))}`);
 }
-function formatProjectUnparseable(lines, project, style) {
-    const unparseable = project.unparseableCommits;
-    if (unparseable === undefined || unparseable.length === 0) {
-        return;
-    }
-    const count = unparseable.length;
-    const isPatchFloor = project.parsedCommitCount === 0;
-    const suffix = isPatchFloor ? ' (defaulting to patch bump)' : '';
-    lines.push(`    ${formatStatusLine(style, 'warning', `${count} commit${count === 1 ? '' : 's'} could not be parsed${suffix}`)}`);
-    for (const commit of unparseable) {
-        const shortHash = commit.hash.slice(0, 7);
-        const truncatedMessage = truncateSubject(commit.message);
-        lines.push(`      · ${shortHash} ${truncatedMessage}`);
-    }
-}
 function formatWorkspaceSection(lines, workspace, dryRun, style) {
     if (workspace.name !== undefined) {
         lines.push(`\n${sectionHeader(workspace.name)}`);
@@ -141,6 +129,9 @@ function formatWorkspaceSection(lines, workspace, dryRun, style) {
     const since = workspace.previousTag === undefined ? '(no previous release found)' : `since ${workspace.previousTag}`;
     lines.push(dim(`  Found ${workspace.commitCount} commits ${since}`));
     if (workspace.status === 'skipped') {
+        formatUnparseableWarning(lines, workspace, style, '  ');
+        formatPolicyViolations(lines, workspace.policyViolations, style, '  ');
+        formatChangeRecordWarnings(lines, workspace, style, '  ');
         lines.push(`  ${formatStatusLine(style, 'skipped', workspace.skipReason)}`);
         return;
     }
@@ -149,6 +140,7 @@ function formatWorkspaceSection(lines, workspace, dryRun, style) {
     formatCommitSummary(lines, workspace, propagatedFrom, isPropagatedOnly);
     formatUnparseableWarning(lines, workspace, style, '  ');
     formatPolicyViolations(lines, workspace.policyViolations, style, '  ');
+    formatChangeRecordWarnings(lines, workspace, style, '  ');
     formatBumpLabels(lines, workspace, isPropagatedOnly);
     formatVersionLine(lines, workspace, propagatedFrom, isPropagatedOnly, style);
     formatBumpFiles(lines, workspace, dryRun, '  ');
@@ -203,7 +195,7 @@ function formatBumpFiles(lines, workspace, dryRun, indent = '') {
 function formatChangelogFiles(lines, workspace, dryRun, indent = '') {
     for (const file of workspace.changelogFiles) {
         if (dryRun) {
-            lines.push(dim(`${indent}  [dry-run] Would run: ${CLIFF_DRY_RUN_COMMAND} --output ${file}`));
+            lines.push(dim(`${indent}  [dry-run] Would generate changelog: ${file}`));
         }
         else {
             lines.push(dim(`${indent}  Generating changelog: ${file}`));
@@ -221,19 +213,17 @@ function formatPreviewFiles(lines, release, dryRun, indent = '') {
         }
     }
 }
-function formatUnparseableWarning(lines, workspace, style, indent = '') {
-    const unparseable = workspace.unparseableCommits;
+function formatUnparseableWarning(lines, release, style, indent = '') {
+    const unparseable = release.unparseableCommits;
     if (unparseable === undefined || unparseable.length === 0) {
         return;
     }
     const count = unparseable.length;
-    const isPatchFloor = workspace.parsedCommitCount === 0;
-    const suffix = isPatchFloor ? ' (defaulting to patch bump)' : '';
-    lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${count} commit${count === 1 ? '' : 's'} could not be parsed${suffix}`)}`);
+    lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${count} commit${count === 1 ? '' : 's'} could not be parsed`)}`);
     for (const commit of unparseable) {
         const shortHash = commit.hash.slice(0, 7);
-        const truncatedMessage = truncateSubject(commit.message);
-        lines.push(`${indent}    · ${shortHash} ${truncatedMessage}`);
+        const truncatedSubject = truncateSubject(commit.subject);
+        lines.push(`${indent}    · ${shortHash} ${truncatedSubject}`);
     }
 }
 function formatPolicyViolations(lines, violations, style, indent = '') {
@@ -246,7 +236,28 @@ function formatPolicyViolations(lines, violations, style, indent = '') {
         const shortHash = violation.commitHash.slice(0, 7);
         const subject = violation.commitSubject;
         const truncatedSubject = truncateSubject(subject);
-        lines.push(`${indent}    · ${shortHash} '${truncatedSubject}' — type '${violation.type}' at ${violation.surface} surface`);
+        const location = violation.surface === 'entry' ? `entry ${violation.entryPosition ?? '?'}` : `${violation.surface} surface`;
+        lines.push(`${indent}    · ${shortHash} '${truncatedSubject}' — type '${violation.type}' at ${location}`);
+    }
+}
+function formatChangeRecordWarnings(lines, release, style, indent = '') {
+    const { malformedBlocks = [], undeclaredEntryTypes = [] } = release;
+    if (malformedBlocks.length > 0) {
+        const count = malformedBlocks.length;
+        const header = `${count} change-record block${count === 1 ? '' : 's'} could not be read (item taken from the title)`;
+        lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${header}:`)}`);
+        for (const block of malformedBlocks) {
+            lines.push(`${indent}    · ${block.commitHash.slice(0, 7)} '${truncateSubject(block.commitSubject)}' — ${block.reason}`);
+        }
+    }
+    if (undeclaredEntryTypes.length > 0) {
+        const count = undeclaredEntryTypes.length;
+        const header = `${count} change-record entr${count === 1 ? 'y has an' : 'ies have'} undeclared type${count === 1 ? '' : 's'} (no item)`;
+        lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${header}:`)}`);
+        for (const entry of undeclaredEntryTypes) {
+            const shortHash = entry.commitHash.slice(0, 7);
+            lines.push(`${indent}    · ${shortHash} '${truncateSubject(entry.commitSubject)}' — type '${entry.type}' at entry ${entry.entryPosition}`);
+        }
     }
 }
 function formatPropagationSuffix(propagatedFrom) {

package/dist/esm/types.d.ts

@@ -11,8 +11,9 @@ 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.
+     * `true` when the commit subject carries the `!` prefix (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 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
@@ -20,29 +21,34 @@ export interface ChangelogItem {
      */
     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
+     * On a title-derived item, 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.
      */
     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.
      */
     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 carries the type's emoji prefix (e.g. `"🐛 Bug fixes"`), so callers that match against
+     * `title` (e.g. `sectionOrder` configs) include that prefix.
      */
     title: string;
     audience: ChangelogAudience;
@@ -61,8 +67,9 @@ 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 with no 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
@@ -75,7 +82,10 @@ 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 {
@@ -88,8 +98,8 @@ export interface ReleaseNotesConfig {
  */
 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
+     * 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[];
@@ -102,7 +112,7 @@ export interface PropagationSource {
     newVersion: string;
 }
 /**
- * A `!`-policy violation detected while parsing commits during release preparation.
+ * A `!`-policy violation detected while reading the unreleased window during release preparation.
  *
  * Surfaces from `releasePrepare`, `releasePrepareMono`, and `releasePrepareProject` via the
  * `policyViolations` field on each per-workspace/project result. The policy itself is enforced
@@ -115,16 +125,40 @@ 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;
+}
+/** A change-record entry whose type the work-type taxonomy does not declare, so that it yielded no 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;
 }
 /**
  * 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
+ * populated. `releaseType` and `parsedCommitCount` stay optional because they are left
+ * undefined for `--set-version` and propagation-only workspaces. `commits` stays optional
  * because propagation-only releases have no direct commits.
  */
 export interface ReleasedWorkspaceResult {
@@ -134,18 +168,19 @@ 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 there are no commits or
+     * when none does. Absent for `--set-version` and propagation-only workspaces. Use
+     * `bumpOverride` as the signal for "the user supplied --bump=X".
      */
     parsedCommitCount?: number;
-    /** Commits that could not be parsed into a recognized work type. */
+    /** Commits that yield no changelog item and that no exclusion or diagnostic accounts for. */
     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[];
     releaseType?: ReleaseType;
     currentVersion: string;
     newVersion: string;
@@ -179,15 +214,16 @@ export interface SkippedWorkspaceResult {
     name?: string;
     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.
-     */
-    parsedCommitCount?: number;
-    /** Commits that could not be parsed into a recognized work type. */
+    /** Count of commits that yield at least one changelog item — `0` when there are no commits or when none does. */
+    parsedCommitCount: number;
+    /** Commits that yield no changelog item and that no exclusion or diagnostic accounts for. */
     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[];
     skipReason: string;
 }
 /**
@@ -210,16 +246,19 @@ export interface ReleasedProjectResult {
     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
+     * Count of commits that yield at least one changelog item — `0` when there are no commits or
+     * when none does. Use `bumpOverride` (not `parsedCommitCount === 0`) as the signal for "the
      * user supplied --bump=X".
      */
     parsedCommitCount: number;
-    /** Commits that could not be parsed into a recognized work type. */
+    /** Commits that yield no changelog item and that no exclusion or diagnostic accounts for. */
     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;
@@ -247,16 +286,16 @@ 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 there are no commits or when none does. */
     parsedCommitCount: number;
-    /** Commits that could not be parsed into a recognized work type. */
+    /** Commits that yield no changelog item and that no exclusion or diagnostic accounts for. */
     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;
 }
 /**
@@ -287,6 +326,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 yield no
+     * 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.
@@ -361,6 +406,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<{
@@ -415,7 +461,6 @@ export declare const releaseKitConfigSchema: z.ZodObject<{
         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 +497,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 +507,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;
@@ -530,8 +578,6 @@ export interface MonorepoReleaseConfig {
      * 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`,
@@ -572,8 +618,6 @@ export interface ReleaseConfig {
      * 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`,

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
@@ -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.js

@@ -30,6 +30,10 @@ function preprocessDeprecatedKeys(raw) {
         return { cleaned: raw, deprecationErrors: [] };
     const errors = [];
     const cleaned = { ...raw };
+    if (Object.hasOwn(cleaned, 'cliffConfigPath')) {
+        errors.push('cliffConfigPath is no longer supported. release-kit reads changelog history from git directly and uses no external config file. Remove this field from your config, and delete the file it names.');
+        delete cleaned['cliffConfigPath'];
+    }
     if (isRecord(cleaned['releaseNotes']) && Object.hasOwn(cleaned['releaseNotes'], 'shouldCreateGithubRelease')) {
         errors.push('releaseNotes.shouldCreateGithubRelease is no longer supported. Adoption is now signaled by installing the create-github-release workflow, which `release-kit init` scaffolds. Remove this field from your config.');
         const releaseNotesCopy = { ...cleaned['releaseNotes'] };

package/dist/esm/validateOverridesCommand.d.ts

@@ -1,6 +1,7 @@
 import { type OutputStyle, type StreamStyles } from '@williamthorsen/nmr-core';
 import { type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult } from './changelogOverrides.js';
 import { type WorkspaceDiscovery } from './discoverWorkspaces.js';
+import { type GenerateChangelogOptions } from './generateChangelogs.js';
 import { type LoadValidatedConfigResult } from './loadValidatedConfig.js';
 import type { ChangelogEntry, ReleaseConfig } from './types.js';
 /**
@@ -10,7 +11,7 @@ import type { ChangelogEntry, ReleaseConfig } from './types.js';
  * Exit codes:
  * - `0` — clean: no errors, no warnings.
  * - `1` — only stale-key warnings.
- * - `2` — schema/parse or ambiguous-prefix errors (errors dominate when both classes exist).
+ * - `2` — schema/parse errors or keys that fail to match (ambiguous prefix, overlapping keys, a bare key setting fields on several items) (errors dominate when both classes exist).
  */
 export interface ValidateOverridesCommandResult {
     exitCode: 0 | 1 | 2;
@@ -22,17 +23,17 @@ export interface ValidateOverridesCommandDependencies {
     loadValidatedConfig?: () => Promise<LoadValidatedConfigResult>;
     /**
      * Build changelog entries for a scope. Defaults to `buildChangelogEntries`, the same path
-     * `release-kit prepare` uses — anchoring `validate`'s hash universe to `prepare`'s by
-     * construction. `tagPattern` and `includePaths` are passed straight through to git-cliff.
+     * `release-kit prepare` uses — anchoring `validate`'s item universe to `prepare`'s by
+     * construction.
      */
-    buildEntries?: (config: Pick<ReleaseConfig, 'cliffConfigPath' | 'changelogJson'>, tagPattern?: string, includePaths?: string[]) => ChangelogEntry[];
+    buildEntries?: (config: Pick<ReleaseConfig, 'breakingPolicies' | 'changelogJson' | 'workTypes'>, options: GenerateChangelogOptions) => ChangelogEntry[];
     /** Pluggable validator (default: the production library function). Tests use this to drive specific result shapes through the formatter. */
     validate?: (inputs: ValidateAllChangelogOverridesInputs) => ValidateAllChangelogOverridesResult;
 }
 /**
  * Validate every changelog override file across the project and per-workspace scopes, and
  * return a tiered exit-code-plus-message result. Performs workspace discovery, config load,
- * and per-scope hash collection, then delegates the actual validation to
+ * and per-scope item collection, then delegates the actual validation to
  * {@link validateAllChangelogOverrides}.
  *
  * Single-package and monorepo modes are handled uniformly: single-package collapses to one

package/dist/esm/validateOverridesCommand.js

@@ -3,7 +3,7 @@ import { describeError } from '@williamthorsen/toolbelt.errors';
 import { buildChangelogEntries } from "./buildChangelogEntries.js";
 import { resolveOverridePath, validateAllChangelogOverrides, } from "./changelogOverrides.js";
 import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
-import { buildTagPattern, getAllTagPrefixes } from "./generateChangelogs.js";
+import { getAllTagPrefixes } from "./generateChangelogs.js";
 import { mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
 import { loadValidatedConfig } from "./loadValidatedConfig.js";
 const SYNTHETIC_VALIDATE_TAG = 'validate-only';
@@ -68,28 +68,21 @@ function formatSummaryLine(errorCount, warningCount) {
 function pluralize(count, noun) {
     return count === 1 ? `${count} ${noun}` : `${count} ${noun}s`;
 }
-function defaultBuildEntries(config, tagPattern, includePaths) {
-    const options = {};
-    if (tagPattern !== undefined) {
-        options.tagPattern = tagPattern;
-    }
-    if (includePaths !== undefined) {
-        options.includePaths = includePaths;
-    }
-    return buildChangelogEntries(config, SYNTHETIC_VALIDATE_TAG, options);
+function defaultBuildEntries(config, options) {
+    return buildChangelogEntries(config, SYNTHETIC_VALIDATE_TAG, options).entries;
 }
-function flattenEntriesToHashes(entries) {
-    const hashes = [];
+function flattenEntriesToItems(entries) {
+    const items = [];
     for (const entry of entries) {
         for (const section of entry.sections) {
-            for (const item of section.items) {
-                if (item.hash !== undefined) {
-                    hashes.push(item.hash);
-                }
+            for (const { hash, entry: position } of section.items) {
+                if (hash === undefined)
+                    continue;
+                items.push(position === undefined ? { hash } : { hash, entry: position });
             }
         }
     }
-    return hashes;
+    return items;
 }
 function formatConfigProblem(problem) {
     return problem.kind === 'load'
@@ -98,19 +91,19 @@ function formatConfigProblem(problem) {
 }
 function buildSinglePackageInputs(userConfig, buildEntries) {
     const config = mergeSinglePackageConfig(userConfig);
-    const hashes = flattenEntriesToHashes(buildEntries(config));
+    const items = flattenEntriesToItems(buildEntries(config, { tagPrefixes: [config.tagPrefix] }));
     return {
-        project: { filePath: resolveOverridePath('.'), hashes },
+        project: { filePath: resolveOverridePath('.'), items },
     };
 }
 function buildMonorepoInputs(discoveredPaths, userConfig, buildEntries) {
     const rootPackage = readRootPackageVersion();
     const config = mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage);
     const workspaces = config.workspaces.map((workspace) => {
-        const tagPattern = buildTagPattern(getAllTagPrefixes(workspace));
+        const options = { tagPrefixes: getAllTagPrefixes(workspace), paths: workspace.paths };
         return {
             filePath: resolveOverridePath(workspace.workspacePath),
-            hashes: flattenEntriesToHashes(buildEntries(config, tagPattern, workspace.paths)),
+            items: flattenEntriesToItems(buildEntries(config, options)),
         };
     });
     const project = config.project;
@@ -118,8 +111,8 @@ function buildMonorepoInputs(discoveredPaths, userConfig, buildEntries) {
         filePath: resolveOverridePath('.'),
     };
     if (project !== undefined) {
-        const projectTagPattern = buildTagPattern([project.tagPrefix]);
-        projectScope.hashes = flattenEntriesToHashes(buildEntries(config, projectTagPattern, project.paths));
+        const options = { tagPrefixes: [project.tagPrefix], paths: project.paths };
+        projectScope.items = flattenEntriesToItems(buildEntries(config, options));
     }
     return { project: projectScope, workspaces };
 }