@williamthorsen/release-kit 11.0.0 → 13.0.0

package/dist/esm/releasePrepareProject.js

@@ -1,17 +1,16 @@
 import { join as joinPath } from 'node:path';
-import { buildChangelogEntries } from "./buildChangelogEntries.js";
-import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
+import { assertTaggedBaseline, findUntaggedBaseline } from "./assertTaggedBaseline.js";
+import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
+import { readReleaseHistory, toReleaseEntries } from "./buildChangelogEntries.js";
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyChangelogOverrides } from "./changelogOverrides.js";
-import { createPolicyViolationCollector } from "./collectPolicyViolations.js";
 import { decideRelease } from "./decideRelease.js";
-import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
-import { buildTagPattern } from "./generateChangelogs.js";
-import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
+import { DEFAULT_WORK_TYPES } from "./defaults.js";
+import { deriveSectionOrder } from "./deriveReleaseNotesConfig.js";
 import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
 import { planVersionBump } from "./planVersionBump.js";
+import { planPreservedSections } from "./readChangelogSections.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
-import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
 const ROOT_PACKAGE_FILE = './package.json';
 const ROOT_CHANGELOG_PATH = '.';
 export function releasePrepareProject(args) {
@@ -23,56 +22,53 @@ export function releasePrepareProject(args) {
         throw new Error('releasePrepareProject called without a configured project block');
     }
     const workTypes = config.workTypes ?? { ...DEFAULT_WORK_TYPES };
-    const versionPatterns = config.versionPatterns ?? { ...DEFAULT_VERSION_PATTERNS };
-    const breakingPolicies = config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES;
-    const contributingPaths = project.paths;
-    const { tag, commits } = getCommitsSinceTarget([project.tagPrefix], contributingPaths);
+    const history = readReleaseHistory(config, { tagPrefixes: [project.tagPrefix], paths: project.paths });
+    assertTaggedBaseline([
+        findUntaggedBaseline({
+            label: 'project',
+            packageFiles: [ROOT_PACKAGE_FILE],
+            changelogPaths: [ROOT_CHANGELOG_PATH],
+            tagPrefixes: [project.tagPrefix],
+            previousTag: history.previousTag,
+        }, config),
+    ]);
+    const { commits, diagnostics, parsedCommitCount, unparseableCommits } = history.unreleased;
+    const tag = history.previousTag;
     const since = tag === undefined ? '(no previous release found)' : `since ${tag}`;
-    const collector = createPolicyViolationCollector();
     const decision = decideRelease({
-        commits,
+        naturalBump: history.unreleased.bump,
+        commitCount: commits.length,
         force,
         bumpOverride,
-        workTypes,
-        versionPatterns,
-        scopeAliases: config.scopeAliases,
-        breakingPolicies,
-        onPolicyViolation: collector.onPolicyViolation,
         skipReasons: {
             noCommits: `No commits ${since}. Pass --force to release at patch. Skipping.`,
             noBumpWorthy: `No bump-worthy commits ${since}. Pass --force to release at patch (or --force --bump=X for a different level). Skipping.`,
         },
     });
-    const policyViolations = collector.violations.length > 0 ? collector.violations : undefined;
     if (decision.outcome === 'skip') {
         const skipped = {
             status: 'skipped',
             commitCount: commits.length,
-            parsedCommitCount: decision.parsedCommitCount,
+            parsedCommitCount,
             skipReason: decision.skipReason,
         };
         if (tag !== undefined) {
             skipped.previousTag = tag;
         }
-        if (decision.unparseableCommits !== undefined) {
-            skipped.unparseableCommits = decision.unparseableCommits;
-        }
-        if (policyViolations !== undefined) {
-            skipped.policyViolations = policyViolations;
+        if (unparseableCommits !== undefined) {
+            skipped.unparseableCommits = unparseableCommits;
         }
+        attachChangelogDiagnostics(skipped, diagnostics);
         return skipped;
     }
-    const { releaseType, parsedCommitCount, unparseableCommits } = decision;
+    const { releaseType } = decision;
     const bump = planVersionBump([ROOT_PACKAGE_FILE], releaseType);
     writes.push(...bump.writes);
     const newTag = `${project.tagPrefix}${bump.newVersion}`;
     const changelogs = planProjectChangelogs({
         config,
-        project,
-        commits,
-        contributingPaths,
+        history,
         newTag,
-        newVersion: bump.newVersion,
         rootOverrides,
         overrideWarnings,
         globalMatchedRootKeys,
@@ -108,18 +104,19 @@ export function releasePrepareProject(args) {
     if (previewFiles.length > 0) {
         result.previewFiles = previewFiles;
     }
+    if (changelogs.changelogPreservation.length > 0) {
+        result.changelogPreservation = changelogs.changelogPreservation;
+    }
     if (tag !== undefined) {
         result.previousTag = tag;
     }
     if (unparseableCommits !== undefined) {
         result.unparseableCommits = unparseableCommits;
     }
-    if (policyViolations !== undefined) {
-        result.policyViolations = policyViolations;
-    }
     if (bumpOverride !== undefined) {
         result.bumpOverride = bumpOverride;
     }
+    attachChangelogDiagnostics(result, diagnostics);
     return result;
 }
 function resolveOptionalOverrideArgs(args) {
@@ -131,14 +128,10 @@ function resolveOptionalOverrideArgs(args) {
     };
 }
 function planProjectChangelogs(args) {
-    const { config, project, commits, contributingPaths, newTag, newVersion, rootOverrides, overrideWarnings, globalMatchedRootKeys, } = args;
-    const isEmptyRange = commits.length === 0;
+    const { config, history, newTag, rootOverrides, overrideWarnings, globalMatchedRootKeys } = args;
     const today = new Date().toISOString().slice(0, 10);
-    const tagPattern = buildTagPattern([project.tagPrefix]);
-    const newEntries = isEmptyRange
-        ? [buildEmptyReleaseEntry(newVersion, today)]
-        : buildChangelogEntries(config, newTag, { tagPattern, includePaths: contributingPaths });
-    const applied = applyChangelogOverrides(newEntries, rootOverrides);
+    const builtEntries = toReleaseEntries(history, newTag, today);
+    const applied = applyChangelogOverrides(builtEntries, rootOverrides);
     if (applied.errors.length > 0) {
         throw new Error(`Changelog override application failed:\n  - ${applied.errors.join('\n  - ')}`);
     }
@@ -148,9 +141,7 @@ function planProjectChangelogs(args) {
     }
     const changelogJsonPath = resolveChangelogJsonPath(config, ROOT_CHANGELOG_PATH);
     const sectionOrder = deriveSectionOrder(config.workTypes ?? { ...DEFAULT_WORK_TYPES });
-    const renderEntries = isEmptyRange
-        ? mergeChangelogEntriesWithDisk(changelogJsonPath, applied.entries)
-        : applied.entries;
+    const renderEntries = mergeChangelogEntriesWithDisk(changelogJsonPath, applied.entries);
     const writes = [];
     const changelogJsonFiles = [];
     if (config.changelogJson.enabled) {
@@ -158,6 +149,16 @@ function planProjectChangelogs(args) {
         changelogJsonFiles.push(changelogJsonPath);
     }
     const changelogFile = joinPath(ROOT_CHANGELOG_PATH, 'CHANGELOG.md');
-    writes.push({ path: changelogFile, content: renderChangelogMarkdown(renderEntries, { sectionOrder }) });
-    return { changelogFiles: [changelogFile], changelogJsonFiles, entries: renderEntries, writes };
+    const preserved = planPreservedSections(changelogFile, renderEntries);
+    writes.push({
+        path: changelogFile,
+        content: renderChangelogMarkdown(renderEntries, { sectionOrder, preservedSections: preserved.sections }),
+    });
+    return {
+        changelogFiles: [changelogFile],
+        changelogJsonFiles,
+        changelogPreservation: preserved.preservation === undefined ? [] : [preserved.preservation],
+        entries: renderEntries,
+        writes,
+    };
 }

package/dist/esm/renderChangelogMarkdown.d.ts

@@ -1,22 +1,28 @@
+import type { VersionedMarkdownSection } from './readChangelogSections.js';
 import type { ChangelogEntry } from './types.js';
 /** Options for `renderChangelogMarkdown`. */
 export interface RenderChangelogMarkdownOptions {
-    /** Section titles in canonical order; passed through to `renderReleaseNotesMulti`. */
+    /** Section titles in canonical order; passed through to `renderReleaseNotesSingle`. */
     sectionOrder?: string[];
+    /**
+     * Sections of the existing `CHANGELOG.md` to keep verbatim, interleaved by version among the rendered entries. A
+     * section's version must not also be an entry's version.
+     */
+    preservedSections?: readonly VersionedMarkdownSection[];
 }
 /**
- * Render `ChangelogEntry[]` into a complete `CHANGELOG.md`-shaped string.
+ * Renders `ChangelogEntry[]` into a complete `CHANGELOG.md`-shaped string.
  *
  * Format:
  *   `# Changelog`
  *   blank line
  *   `All notable changes …`
  *   blank line
- *   per-entry sections (delegated to `renderReleaseNotesMulti`)
+ *   per-entry sections (delegated to `renderReleaseNotesSingle`), with preserved sections interleaved by version
  *   blank line
  *   footer comment
  *
  * Entries are rendered in the order provided; the caller sorts (typically newest-first via
- * `changelogJsonFile`'s SemVer-aware comparator).
+ * `compareVersionsDescending`).
  */
 export declare function renderChangelogMarkdown(entries: ChangelogEntry[], options?: RenderChangelogMarkdownOptions): string;

package/dist/esm/renderChangelogMarkdown.js

@@ -1,10 +1,15 @@
-import { renderReleaseNotesMulti } from "./renderReleaseNotes.js";
+import { compareVersionsDescending } from "./compareVersions.js";
+import { renderReleaseNotesSingle } from "./renderReleaseNotes.js";
 const CHANGELOG_HEADER = `# Changelog
 
 All notable changes to this project will be documented in this file.`;
 const CHANGELOG_FOOTER = `<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->`;
 export function renderChangelogMarkdown(entries, options) {
-    const body = renderReleaseNotesMulti(entries, options);
+    const sections = interleavePreservedSections(entries.map((entry) => ({ version: entry.version, text: renderReleaseNotesSingle(entry, options) })), options?.preservedSections ?? []);
+    const body = sections
+        .map((part) => part.text)
+        .filter((text) => text.length > 0)
+        .join('\n');
     const trimmedBody = body.trimEnd();
     const parts = [CHANGELOG_HEADER];
     if (trimmedBody.length > 0) {
@@ -13,3 +18,23 @@ export function renderChangelogMarkdown(entries, options) {
     parts.push(CHANGELOG_FOOTER);
     return parts.join('\n\n') + '\n';
 }
+function interleavePreservedSections(rendered, preserved) {
+    const sorted = preserved.toSorted((a, b) => compareVersionsDescending(a.version, b.version));
+    const pending = sorted.map(withTrailingNewline);
+    const result = [];
+    let index = 0;
+    for (const part of rendered) {
+        let section = pending[index];
+        while (section !== undefined && compareVersionsDescending(section.version, part.version) < 0) {
+            result.push(section);
+            index++;
+            section = pending[index];
+        }
+        result.push(part);
+    }
+    result.push(...pending.slice(index));
+    return result;
+}
+function withTrailingNewline(section) {
+    return { version: section.version, text: `${section.text}\n` };
+}

package/dist/esm/renderReleaseNotes.d.ts

@@ -13,22 +13,14 @@ export interface RenderOptions {
     sectionOrder?: string[];
 }
 /**
- * Create a predicate that matches sections visible to the given audience.
+ * Creates a predicate that matches sections visible to the given audience.
  *
  * `"all"` matches only sections with `audience: "all"` (public-facing).
  * `"dev"` matches all sections (developers see everything).
  */
 export declare function matchesAudience(audience: ChangelogAudience): (section: ChangelogSection) => boolean;
 /**
- * Render a single `ChangelogEntry` to markdown.
- *
- * Output format mirrors the existing CHANGELOG.md style: an H2 version heading followed by
- * H3 section headings with bulleted items.
+ * Renders a single `ChangelogEntry` to markdown: an H2 version heading followed by H3 section
+ * headings with bulleted items.
  */
 export declare function renderReleaseNotesSingle(entry: ChangelogEntry, options?: RenderOptions): string;
-/**
- * Render multiple `ChangelogEntry` values to a single markdown document.
- *
- * Entries are rendered in the order provided; the caller is responsible for sorting.
- */
-export declare function renderReleaseNotesMulti(entries: ChangelogEntry[], options?: RenderOptions): string;

package/dist/esm/renderReleaseNotes.js

@@ -1,6 +1,6 @@
-import { WORK_TYPES_DATA } from "./workTypesData.js";
+import { CANONICAL_TAXONOMY } from '@williamthorsen/change-grammar';
 function getBreakingPrefix() {
-    const { emoji, label } = WORK_TYPES_DATA.markers.breaking;
+    const { emoji, label } = CANONICAL_TAXONOMY.markers.breaking;
     return `${emoji} **${label}:** `;
 }
 function allSections() {
@@ -62,7 +62,3 @@ function sortSectionsByOrder(sections, order) {
 function indentBodyLines(body) {
     return body.split('\n').map((line) => (line.length === 0 ? '' : `  ${line}`));
 }
-export function renderReleaseNotesMulti(entries, options) {
-    const parts = entries.map((entry) => renderReleaseNotesSingle(entry, options)).filter((part) => part.length > 0);
-    return parts.join('\n');
-}

package/dist/esm/reportPrepare.d.ts

@@ -1,6 +1,6 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { PrepareResult } from './types.js';
-/** How the plan was carried out, which decides the tense the report is rendered in. */
+/** How the plan was carried out, which decides the report's tense. */
 export interface ReportPrepareOptions {
     /** True when the plan was written to disk; false for a dry run. */
     applied: boolean;
@@ -9,14 +9,13 @@ export interface ReportPrepareOptions {
     style: OutputStyle;
 }
 /**
- * Format a release plan into styled terminal output.
+ * Formats a release plan into styled terminal output, without writing it.
  *
- * Pure function: accepts structured data, returns a string. Never writes to stdout.
- * Single-workspace mode (no `name` field) renders flat output; multi-workspace mode
+ * Single-workspace mode (without a `name` field) renders flat output; multi-workspace mode
  * renders section headers per workspace, an optional project section, and a tag summary
  * at the end.
  *
- * Whether the plan was applied is a property of the render, not of the plan: the same plan
+ * Whether the plan was applied is a property of the render, not of the plan: The same plan
  * produces the dry-run report and the applied report.
  */
 export declare function reportPrepare(plan: PrepareResult, options: ReportPrepareOptions): string;

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,9 +48,10 @@ 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);
+    formatChangelogFiles(lines, workspace, dryRun, style);
     formatPreviewFiles(lines, workspace, dryRun);
     formatFormatCommand(lines, result, options);
     formatWarnings(lines, result, style);
@@ -77,7 +77,7 @@ function formatMultiWorkspace(result, options) {
         }
     }
     else {
-        lines.push(`\n${formatStatusLine(style, 'skipped', 'No workspaces had release-worthy changes.')}`);
+        lines.push(`\n${formatStatusLine(style, 'skipped', 'The run did not find release-worthy changes in any workspace.')}`);
     }
     return lines.join('\n');
 }
@@ -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) {
@@ -108,32 +111,10 @@ 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}`));
-        }
-        else {
-            lines.push(dim(`    Generating changelog: ${file}`));
-        }
-    }
+    formatChangelogFiles(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,26 +122,30 @@ 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;
     }
     const { propagatedFrom } = workspace;
-    const isPropagatedOnly = propagatedFrom !== undefined && workspace.commitCount === 0;
+    const isPropagatedOnly = workspace.propagatedOnly === true;
     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, '  ');
     lines.push(dim('  Generating changelogs...'));
-    formatChangelogFiles(lines, workspace, dryRun, '  ');
+    formatChangelogFiles(lines, workspace, dryRun, style, '  ');
     formatPreviewFiles(lines, workspace, dryRun, '  ');
     lines.push(`  ${formatGlyphLine(RELEASE_GLYPHS, style, 'tag', bold(workspace.tag))}`);
 }
 function formatCommitSummary(lines, workspace, propagatedFrom, isPropagatedOnly) {
     if (isPropagatedOnly && propagatedFrom !== undefined) {
         const depNames = propagatedFrom.map((p) => p.packageName).join(', ');
-        lines.push(dim(`  0 commits (bumped via dependency: ${depNames})`));
+        lines.push(dim(`  Bumped via dependency: ${depNames}`));
     }
     else if (workspace.parsedCommitCount !== undefined && workspace.parsedCommitCount > 0) {
         lines.push(dim(`  Parsed ${workspace.parsedCommitCount} typed commits`));
@@ -200,14 +185,26 @@ function formatBumpFiles(lines, workspace, dryRun, indent = '') {
         }
     }
 }
-function formatChangelogFiles(lines, workspace, dryRun, indent = '') {
-    for (const file of workspace.changelogFiles) {
+function formatChangelogFiles(lines, release, dryRun, style, indent = '') {
+    for (const file of release.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}`));
         }
+        const preservation = release.changelogPreservation?.find((candidate) => candidate.file === file);
+        if (preservation === undefined) {
+            continue;
+        }
+        if (preservation.preservedVersions.length > 0) {
+            lines.push(dim(`${indent}    Kept from the existing file: ${preservation.preservedVersions.join(', ')}`));
+        }
+        const dropped = preservation.droppedUnversionedHeadings;
+        if (dropped.length > 0) {
+            const message = `Dropped ${dropped.length} section${dropped.length === 1 ? '' : 's'} without a version: ${dropped.join(', ')}`;
+            lines.push(`${indent}    ${formatStatusLine(style, 'warning', message)}`);
+        }
     }
 }
 function formatPreviewFiles(lines, release, dryRun, indent = '') {
@@ -221,19 +218,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 +241,37 @@ 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 = [], unroutedEntryScopes = [] } = 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}`);
+        }
+    }
+    if (unroutedEntryScopes.length > 0) {
+        const count = unroutedEntryScopes.length;
+        const header = `${count} change-record entry scope${count === 1 ? ' does not match' : 's do not match'} any workspace in the commit's window (no item there)`;
+        lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${header}:`)}`);
+        for (const finding of unroutedEntryScopes) {
+            const shortHash = finding.commitHash.slice(0, 7);
+            lines.push(`${indent}    · ${shortHash} '${truncateSubject(finding.commitSubject)}': scope '${finding.scope}' at entry ${finding.entryPosition}`);
+        }
     }
 }
 function formatPropagationSuffix(propagatedFrom) {

package/dist/esm/resolveCommandTags.d.ts

@@ -1,15 +1,19 @@
 import { type ResolvedTag } from './resolveReleaseTags.js';
+import type { ReleaseKitConfig } from './types.js';
 /**
- * Discover workspaces, resolve release tags from HEAD, validate `--tags` names against the
- * full resolved tag names (e.g., `nmr-core-v1.3.0`), and return the filtered tag list.
- * Works in both single-package and monorepo modes. Exits with an error message on any validation
- * failure — including `deriveWorkspaceConfig()` throws for workspaces missing a `package.json` `name` field,
- * and a workspace declaring patterns that resolve to no package, which is not single-package mode.
+ * Discovers workspaces, resolves release tags from HEAD, validates `--tags` names against the full resolved tag
+ * names (e.g., `nmr-core-v1.3.0`), and returns the filtered tag list. Exits with an error message on any validation
+ * failure, including a workspace whose `package.json` does not have a `name` field, a config that
+ * `mergeMonorepoConfig` rejects, and a workspace that does not resolve to any package, which is not single-package
+ * mode.
  *
- * In both modes `deriveWorkspaceConfig` is called so `WorkspaceConfig.isPublishable` (read
- * from `package.json#private`) propagates onto each `ResolvedTag`. Single-package mode now
- * derives `./package.json`'s workspace config too — consumers that previously relied on
- * single-package mode skipping the derive step need a `name` field on `./package.json`,
- * but in practice every npm/pnpm package already has one.
+ * In monorepo mode the workspace list is `userConfig` merged over the discovered workspaces, as `prepare` builds it.
+ * A tag on HEAD whose workspace the config excludes still counts as a tag on HEAD, so `--tags` may name it and a
+ * HEAD whose tags are all excluded returns an empty list rather than failing. Each excluded tag that the run
+ * selects, every one without `--tags` or the named ones with it, is dropped with a warning.
+ * Single-package mode ignores `userConfig`.
+ *
+ * In both modes the workspace configs come from `deriveWorkspaceConfig`, so that `WorkspaceConfig.isPublishable`
+ * (read from `package.json#private`) propagates onto each `ResolvedTag`.
  */
-export declare function resolveCommandTags(tags: string[] | undefined): ResolvedTag[];
+export declare function resolveCommandTags(tags: string[] | undefined, userConfig: ReleaseKitConfig | undefined): ResolvedTag[];

package/dist/esm/resolveCommandTags.js

@@ -1,9 +1,12 @@
+import { basename } from 'node:path';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
 import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
+import { formatExcludedSkip } from "./formatExcludedSkip.js";
+import { mergeMonorepoConfig, readRootPackageVersion } from "./loadConfig.js";
 import { resolveReleaseTags } from "./resolveReleaseTags.js";
-export function resolveCommandTags(tags) {
+export function resolveCommandTags(tags, userConfig) {
     let workspace;
     try {
         workspace = discoverWorkspaces();
@@ -18,12 +21,13 @@ export function resolveCommandTags(tags) {
     }
     let workspaces;
     let singleWorkspace;
+    const excludedDirs = workspace.kind === 'packages' ? collectExcludedDirs(userConfig) : new Set();
     try {
         if (workspace.kind === 'single-package') {
             singleWorkspace = deriveWorkspaceConfig('.');
         }
         else {
-            workspaces = workspace.packageDirs.map((workspacePath) => deriveWorkspaceConfig(workspacePath));
+            workspaces = buildMonorepoWorkspaces(workspace.packageDirs, userConfig, excludedDirs);
         }
     }
     catch (error) {
@@ -38,10 +42,10 @@ export function resolveCommandTags(tags) {
         resolvedTags = resolveReleaseTags({ singleWorkspace });
     }
     else {
-        throw new Error('resolveCommandTags: invariant violated — neither workspaces nor singleWorkspace was derived');
+        throw new Error('resolveCommandTags: invariant violated; neither workspaces nor singleWorkspace was derived');
     }
     if (resolvedTags.length === 0) {
-        reportError('No release tags found on HEAD. Create tags with `release-kit tag` first.');
+        reportError('HEAD does not have any release tags. Create tags with `release-kit tag` first.');
         process.exit(1);
     }
     if (tags !== undefined) {
@@ -55,5 +59,31 @@ export function resolveCommandTags(tags) {
         }
         resolvedTags = resolvedTags.filter((t) => tags.includes(t.tag));
     }
-    return resolvedTags;
+    return dropExcludedTags(resolvedTags, excludedDirs);
+}
+function buildMonorepoWorkspaces(packageDirs, userConfig, excludedDirs) {
+    const { workspaces } = mergeMonorepoConfig(packageDirs, userConfig, readRootPackageVersion());
+    if (excludedDirs.size === 0) {
+        return workspaces;
+    }
+    const excluded = packageDirs
+        .filter((packageDir) => excludedDirs.has(basename(packageDir)))
+        .map((packageDir) => deriveWorkspaceConfig(packageDir));
+    return [...workspaces, ...excluded];
+}
+function collectExcludedDirs(userConfig) {
+    const overrides = userConfig?.workspaces ?? [];
+    return new Set(overrides.filter((override) => override.shouldExclude === true).map((override) => override.dir));
+}
+function dropExcludedTags(resolvedTags, excludedDirs) {
+    const retained = [];
+    for (const resolvedTag of resolvedTags) {
+        if (excludedDirs.has(resolvedTag.dir)) {
+            console.warn(formatExcludedSkip(resolvedTag));
+        }
+        else {
+            retained.push(resolvedTag);
+        }
+    }
+    return retained;
 }

package/dist/esm/resolveConfigFlag.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolves a `--config` value against the directory from which `release-kit` was invoked, which differs from the
+ * working directory once the process has moved to the repo root.
+ *
+ * Returns `undefined` when the flag is absent, so that `loadConfig` falls back to the default path under the root.
+ */
+export declare function resolveConfigFlag(config: string | undefined, invocationDir: string): string | undefined;