@williamthorsen/release-kit 12.0.0 → 13.1.0

package/dist/esm/releasePrepareProject.js

@@ -1,15 +1,16 @@
 import { join as joinPath } from 'node:path';
+import { assertTaggedBaseline, findUntaggedBaseline } from "./assertTaggedBaseline.js";
 import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
-import { readReleaseHistory, toChangelogEntries } from "./buildChangelogEntries.js";
-import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
+import { readReleaseHistory, toReleaseEntries } from "./buildChangelogEntries.js";
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyChangelogOverrides } from "./changelogOverrides.js";
 import { decideRelease } from "./decideRelease.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) {
@@ -22,6 +23,15 @@ export function releasePrepareProject(args) {
     }
     const workTypes = config.workTypes ?? { ...DEFAULT_WORK_TYPES };
     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}`;
@@ -59,7 +69,6 @@ export function releasePrepareProject(args) {
         config,
         history,
         newTag,
-        newVersion: bump.newVersion,
         rootOverrides,
         overrideWarnings,
         globalMatchedRootKeys,
@@ -95,6 +104,9 @@ 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;
     }
@@ -116,10 +128,9 @@ function resolveOptionalOverrideArgs(args) {
     };
 }
 function planProjectChangelogs(args) {
-    const { config, history, newTag, newVersion, rootOverrides, overrideWarnings, globalMatchedRootKeys } = args;
-    const isEmptyRange = history.unreleased.commits.length === 0;
+    const { config, history, newTag, rootOverrides, overrideWarnings, globalMatchedRootKeys } = args;
     const today = new Date().toISOString().slice(0, 10);
-    const builtEntries = isEmptyRange ? [buildEmptyReleaseEntry(newVersion, today)] : toChangelogEntries(history, newTag);
+    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  - ')}`);
@@ -130,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) {
@@ -140,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

@@ -51,7 +51,7 @@ function formatSingleWorkspace(result, options) {
     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');
 }
@@ -111,14 +111,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 generate changelog: ${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))}`);
 }
@@ -136,7 +129,7 @@ function formatWorkspaceSection(lines, workspace, dryRun, style) {
         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, '  ');
@@ -145,14 +138,14 @@ function formatWorkspaceSection(lines, workspace, dryRun, style) {
     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`));
@@ -192,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 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 = '') {
@@ -237,17 +242,17 @@ function formatPolicyViolations(lines, violations, style, indent = '') {
         const subject = violation.commitSubject;
         const truncatedSubject = truncateSubject(subject);
         const location = violation.surface === 'entry' ? `entry ${violation.entryPosition ?? '?'}` : `${violation.surface} surface`;
-        lines.push(`${indent}    · ${shortHash} '${truncatedSubject}' — type '${violation.type}' at ${location}`);
+        lines.push(`${indent}    · ${shortHash} '${truncatedSubject}': type '${violation.type}' at ${location}`);
     }
 }
 function formatChangeRecordWarnings(lines, release, style, indent = '') {
-    const { malformedBlocks = [], undeclaredEntryTypes = [] } = release;
+    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}`);
+            lines.push(`${indent}    · ${block.commitHash.slice(0, 7)} '${truncateSubject(block.commitSubject)}': ${block.reason}`);
         }
     }
     if (undeclaredEntryTypes.length > 0) {
@@ -256,7 +261,16 @@ function formatChangeRecordWarnings(lines, release, style, indent = '') {
         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}`);
+            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}`);
         }
     }
 }

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;

package/dist/esm/resolveConfigFlag.js

@@ -0,0 +1,4 @@
+import path from 'node:path';
+export function resolveConfigFlag(config, invocationDir) {
+    return config === undefined ? undefined : path.resolve(invocationDir, config);
+}

package/dist/esm/resolveReleaseTags.d.ts

@@ -4,10 +4,8 @@ export interface ResolvedTag {
     dir: string;
     workspacePath: string;
     /**
-     * Whether the workspace this tag belongs to can be published to a registry. Propagated
-     * from the matched `WorkspaceConfig.isPublishable` (monorepo) or from the single-package
-     * workspace config (single-package mode). Consumed by `release-kit publish` to filter the
-     * tag set; other commands ignore it.
+     * Whether the workspace to which this tag belongs can be published to a registry, copied from the matched
+     * workspace's `WorkspaceConfig.isPublishable`.
      */
     isPublishable: boolean;
 }
@@ -18,15 +16,15 @@ type ResolveReleaseTagsArgs = {
     singleWorkspace: WorkspaceConfig;
 };
 /**
- * Resolve release tags pointing at HEAD into publishable package descriptors.
+ * Resolves release tags pointing at HEAD into publishable package descriptors.
  *
- * Pass `{ workspaces }` for monorepo mode: each tag is matched against the workspace
+ * Pass `{ workspaces }` for monorepo mode: Each tag is matched against the workspace
  * whose `tagPrefix` it starts with, and that workspace's `isPublishable` propagates onto
  * the `ResolvedTag`. Because `tagPrefix` is derived from `deriveWorkspaceConfig()` (the
  * same source that produced the tag), encoding and decoding stay colocated.
  *
- * Pass `{ singleWorkspace }` for single-package mode: tags like `v1.2.3` are matched and
- * each carries the workspace's `isPublishable` bit derived from `./package.json#private`.
+ * Pass `{ singleWorkspace }` for single-package mode: Tags like `v1.2.3` are matched and
+ * each has the workspace's `isPublishable` bit derived from `./package.json#private`.
  *
  * The no-arg form is a test-isolation convenience for unit tests that exercise tag
  * matching without needing `isPublishable` propagation; resolved tags default to

package/dist/esm/resolveReleaseTags.js

@@ -30,7 +30,7 @@ function resolveSinglePackageTags(tags, singleWorkspace) {
     return matched.map((tag) => ({ tag, dir: '.', workspacePath: '.', isPublishable }));
 }
 function resolveMonorepoTags(tags, workspaces) {
-    const sortedWorkspaces = [...workspaces].sort((a, b) => b.tagPrefix.length - a.tagPrefix.length);
+    const sortedWorkspaces = workspaces.toSorted((a, b) => b.tagPrefix.length - a.tagPrefix.length);
     const resolved = [];
     for (const tag of tags) {
         const match = findMatchingWorkspace(tag, sortedWorkspaces);

package/dist/esm/resolveStylesOrExit.d.ts

@@ -1,10 +1,10 @@
 import { type StreamStyles } from '@williamthorsen/nmr-core';
-/** The environment variable holding the caller's standing style preference: `auto`, `plain`, or `rich`. */
+/** The environment variable that sets the caller's standing style preference: `auto`, `plain`, or `rich`. */
 export declare const OUTPUT_STYLE_ENV_VAR = "RELEASE_KIT_OUTPUT_STYLE";
 export interface ResolveStylesOptions {
     readonly env: Readonly<Record<string, string | undefined>>;
     readonly stderrIsTty: boolean;
     readonly stdoutIsTty: boolean;
 }
-/** Resolves the style of each output stream, exiting with a usage error when the variable names no setting. */
+/** Resolves the style of each output stream, exiting with a usage error when the variable does not name a setting. */
 export declare function resolveStylesOrExit(options: ResolveStylesOptions): StreamStyles;

package/dist/esm/showTagPrefixesCommand.d.ts

@@ -1,15 +1,12 @@
 import { type StreamStyles } from '@williamthorsen/nmr-core';
 /**
- * Orchestrate the CLI `show-tag-prefixes` command.
+ * Runs the CLI `show-tag-prefixes` command and returns its exit code.
  *
- * Prints a per-workspace table of derived prefixes, tag counts, and declared legacy
- * entries, followed by an "Undeclared tag prefixes" section when candidate-shaped tags
- * exist outside the known set. Exits `0` on full derivation success and no collisions;
- * `1` on any derivation failure or collision. Undeclared candidates do not affect the
- * exit code. A config that exists and either fails to load or fails validation reports to stderr and
- * exits `1` in both repo modes, rather than falling back to a default-config preview that would
- * understate the declared legacy prefixes. An absent default config previews against derived defaults.
- *
- * @returns The exit code the caller should use.
+ * Prints a per-workspace table of derived prefixes, tag counts, and declared legacy entries, followed by an
+ * "Undeclared tag prefixes" section when candidate-shaped tags exist outside the known set. Returns `1` on any
+ * derivation failure or collision and `0` otherwise; undeclared candidates do not affect the exit code. When a config
+ * exists and either fails to load or fails validation, the command reports it to stderr and returns `1` in both repo
+ * modes, because a default-config preview would understate the declared legacy prefixes. When the default config is
+ * absent, the command previews against derived defaults.
  */
 export declare function showTagPrefixesCommand(styles: StreamStyles, configPath?: string): Promise<number>;

package/dist/esm/showTagPrefixesCommand.js

@@ -41,7 +41,7 @@ function renderMonorepo(preview, style) {
         lines.push('', ...preview.collisions.map((collision) => formatStatusLine(style, 'failed', `tag prefix collision: '${collision.tagPrefix}' used by ${collision.workspacePaths.join(', ')}`)));
     }
     if (preview.undeclaredCandidates.length > 0) {
-        lines.push('', 'Undeclared tag prefixes:', '', ...preview.undeclaredCandidates.map((candidate) => `  '${candidate.prefix}' — ${candidate.tagCount} tags (e.g., ${candidate.exampleTags.join(', ')})`), '', 'Suggested config snippet (adjust `dir` to match your workspace if the guess is wrong, and replace the `name` placeholder with the legacy npm name):', '', renderSuggestedSnippet(preview.undeclaredCandidates), '', "If the suggested `dir` does not match your workspace, adjust before pasting. Each legacy identity requires a `name` — replace the `TODO-fill-in-legacy-npm-name` placeholder with the package's prior npm name.");
+        lines.push('', 'Undeclared tag prefixes:', '', ...preview.undeclaredCandidates.map((candidate) => `  '${candidate.prefix}': ${candidate.tagCount} tags (e.g., ${candidate.exampleTags.join(', ')})`), '', 'Suggested config snippet (adjust `dir` to match the workspace if the guess is wrong, and replace the `name` placeholder with the legacy npm name):', '', renderSuggestedSnippet(preview.undeclaredCandidates), '', "If the suggested `dir` does not match the workspace, adjust it before pasting. Each legacy identity requires a `name`: Replace the `TODO-fill-in-legacy-npm-name` placeholder with the package's prior npm name.");
     }
     lines.push('');
     return lines.join('\n');
@@ -50,20 +50,20 @@ function renderWorkspaceRow(row, style) {
     const lines = [];
     if (row.derivedPrefix === null) {
         const failure = formatStatusLine(style, 'failed', `derivation failed: ${row.derivationError ?? 'unknown error'}`);
-        lines.push(`  ${row.workspacePath} — ${failure}`);
+        lines.push(`  ${row.workspacePath}: ${failure}`);
         return lines;
     }
     const statusMarker = row.derivedTagCount > 0
         ? formatStatusLine(style, 'passed', `${row.derivedTagCount} tags`)
         : formatStatusLine(style, 'warning', 'no existing tags');
-    lines.push(`  ${row.workspacePath} — derived prefix '${row.derivedPrefix}', ${statusMarker}`);
+    lines.push(`  ${row.workspacePath}: derived prefix '${row.derivedPrefix}', ${statusMarker}`);
     for (const entry of row.legacyEntries) {
         if (entry.tagCount > 0) {
             const recognized = `${entry.tagCount} legacy tags with '${entry.prefix}' prefix (recognized)`;
             lines.push(`      ${formatStatusLine(style, 'passed', recognized)}`);
         }
         else {
-            const tagless = `recorded legacy prefix '${entry.prefix}' has no tags`;
+            const tagless = `recorded legacy prefix '${entry.prefix}' does not have any tags`;
             lines.push(`      ${formatStatusLine(style, 'warning', tagless)}`);
         }
     }

package/dist/esm/stripEmojiPrefix.d.ts

@@ -1 +1,2 @@
+/** Removes a leading emoji and one space from a section title, returning the title unchanged when it has none. */
 export declare function stripEmojiPrefix(value: string): string;

package/dist/esm/stripScope.d.ts

@@ -1,8 +1,8 @@
 /**
- * Strip scope indicators from a raw commit message.
+ * Strips scope indicators from a raw commit message.
  *
  * Handles `scope|type: desc`, `type(scope): desc`, and messages with
  * ticket prefixes (e.g., `#72 release-kit|fix: ...`). Returns the
- * message unchanged when no scope is detected.
+ * message unchanged when it does not detect a scope.
  */
 export declare function stripScope(message: string): string;