@williamthorsen/release-kit 11.0.0 → 13.0.0

package/dist/esm/parseChangeRecordBlock.js

@@ -0,0 +1,134 @@
+import { parseDocument } from 'yaml';
+import { isRecord } from "./typeGuards.js";
+export function parseChangeRecordBlock(message) {
+    const lines = message.split(/\r?\n/);
+    const fence = findFences(lines).at(-1);
+    if (fence === undefined) {
+        return { kind: 'absent' };
+    }
+    if (fence.close === undefined) {
+        return { kind: 'malformed', reason: 'the block opens but never closes' };
+    }
+    const document = parseDocument(lines.slice(fence.open + 1, fence.close).join('\n'));
+    const [error] = document.errors;
+    if (error !== undefined) {
+        const detail = (error.message.split('\n', 1)[0] ?? '').replace(/:$/, '');
+        return { kind: 'malformed', reason: `the payload is not valid YAML: ${detail}` };
+    }
+    return readPayload(document.toJS());
+}
+export function stripChangeRecordBlocks(message) {
+    const lines = message.split(/\r?\n/);
+    const fences = findFences(lines);
+    return lines
+        .filter((_line, index) => fences.every((fence) => index < fence.open || index > (fence.close ?? lines.length)))
+        .join('\n');
+}
+const FENCE = '```';
+function findFences(lines) {
+    const fences = [];
+    let open;
+    for (const [index, line] of lines.entries()) {
+        if (open === undefined) {
+            if (line.trim() === `${FENCE}${INFO_STRING}`) {
+                open = index;
+            }
+        }
+        else if (line.trim() === FENCE) {
+            fences.push({ close: index, open });
+            open = undefined;
+        }
+    }
+    if (open !== undefined) {
+        fences.push({ open });
+    }
+    return fences;
+}
+const INFO_STRING = 'change-record';
+function readEntry(item, index) {
+    const at = `entries[${index}]`;
+    if (!isRecord(item)) {
+        return { reason: `\`${at}\` is not a mapping` };
+    }
+    const { breaking, migration, scopes } = item;
+    if (breaking !== undefined && breaking !== null && typeof breaking !== 'boolean') {
+        return { reason: `\`${at}.breaking\` is not a boolean` };
+    }
+    if (migration !== undefined && migration !== null && typeof migration !== 'string') {
+        return { reason: `\`${at}.migration\` is not a string` };
+    }
+    if (scopes !== undefined && scopes !== null && !Array.isArray(scopes)) {
+        return { reason: `\`${at}.scopes\` is not a list` };
+    }
+    const declaredScopes = scopes ?? [];
+    const readScopes = [];
+    for (const [position, scope] of declaredScopes.entries()) {
+        if (typeof scope !== 'string') {
+            return { reason: `\`${at}.scopes[${position}]\` is not a string` };
+        }
+        readScopes.push(scope.trim());
+    }
+    const type = readRequiredString(item, at, 'type');
+    if ('reason' in type) {
+        return type;
+    }
+    const text = readRequiredString(item, at, 'text');
+    if ('reason' in text) {
+        return text;
+    }
+    const trimmedMigration = migration?.trim();
+    return {
+        entry: {
+            breaking: breaking === true,
+            ...(trimmedMigration !== undefined && trimmedMigration !== '' && { migration: trimmedMigration }),
+            scopes: readScopes,
+            text: text.value,
+            type: type.value,
+        },
+    };
+}
+function readPayload(payload) {
+    if (!isRecord(payload)) {
+        return { kind: 'malformed', reason: 'the payload is not a mapping' };
+    }
+    const { entries, pr_number: prNumber, ticket_ref: ticketRef } = payload;
+    if (prNumber !== undefined &&
+        prNumber !== null &&
+        (typeof prNumber !== 'number' || !Number.isSafeInteger(prNumber) || prNumber <= 0)) {
+        return { kind: 'malformed', reason: '`pr_number` is not a positive integer' };
+    }
+    if (ticketRef !== undefined && ticketRef !== null && typeof ticketRef !== 'string') {
+        return { kind: 'malformed', reason: '`ticket_ref` is not a string' };
+    }
+    const readEntries = [];
+    if (entries !== undefined && entries !== null) {
+        if (!Array.isArray(entries)) {
+            return { kind: 'malformed', reason: '`entries` is not a list' };
+        }
+        for (const [index, item] of entries.entries()) {
+            const read = readEntry(item, index);
+            if ('reason' in read) {
+                return { kind: 'malformed', reason: read.reason };
+            }
+            readEntries.push(read.entry);
+        }
+    }
+    const trimmedTicketRef = ticketRef?.trim();
+    return {
+        kind: 'read',
+        entries: readEntries,
+        ...(typeof prNumber === 'number' && { prNumber }),
+        ...(trimmedTicketRef !== undefined && trimmedTicketRef !== '' && { ticketRef: trimmedTicketRef }),
+    };
+}
+function readRequiredString(item, at, name) {
+    const value = item[name];
+    if (value === undefined || value === null) {
+        return { reason: `\`${at}.${name}\` is missing` };
+    }
+    if (typeof value !== 'string') {
+        return { reason: `\`${at}.${name}\` is not a string` };
+    }
+    const trimmed = value.trim();
+    return trimmed === '' ? { reason: `\`${at}.${name}\` is blank` } : { value: trimmed };
+}

package/dist/esm/parseCommitMessage.d.ts

@@ -1,51 +1,61 @@
+import { type BreakingPolicy, type ChangeRecord } from '@williamthorsen/change-grammar';
 import type { Commit, ParsedCommit, WorkTypeConfig } from './types.js';
-/** Regex patterns stripped from the start of commit messages before parsing. */
-export declare const COMMIT_PREPROCESSOR_PATTERNS: readonly RegExp[];
 /**
- * Regex source for the pipe-prefixed scope atom (the `web` in `web|feat: ...`).
- *
- * Deliberately permissive: `*` is the sanctioned structural scope for changes spanning every
- * workspace, so the atom admits any run of non-pipe characters rather than word characters.
- * `cliff.toml.template` embeds the same atom in every ticketed commit parser, and
- * `cliffConfigAlignment.unit.test.ts` asserts that parity — exported so neither side can drift.
+ * Surface where a breaking-policy violation was detected: a subject's `!`, a `BREAKING CHANGE:` footer, or a
+ * change-record entry's `breaking`.
  */
-export declare const PIPE_SCOPE_SOURCE = "[^|]+";
-/** Surface where a `!`/`BREAKING CHANGE:` policy violation was detected. */
-export type PolicyViolationSurface = 'prefix' | 'body';
+export type PolicyViolationSurface = 'prefix' | 'body' | 'entry';
 /**
  * Callback invoked when `parseCommitMessage` detects a `!`-policy violation.
  *
- * The parser warns and continues on a violation, so legacy log entries don't block releases.
- * Callers (`decideRelease`, `releasePrepareMono`, etc.) collect callback invocations and
- * surface them in the release report.
+ * Parsing continues after a violation so that an older commit in the log does not block a release.
  */
 export type PolicyViolationHandler = (commit: Commit, type: string, surface: PolicyViolationSurface) => void;
 /** Optional configuration for `parseCommitMessage` beyond the core inputs. */
 export interface ParseCommitMessageOptions {
-    /**
-     * Per-type breaking-policy lookup keyed by canonical type name. Missing entries are
-     * treated as `'optional'` for backward compatibility with consumers that have not
-     * supplied policies.
-     */
-    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    /** Per-type breaking-policy lookup keyed by canonical type name; a type without an entry is `'optional'`. */
+    breakingPolicies?: Record<string, BreakingPolicy>;
     /** Receives policy-violation notifications. See {@link PolicyViolationHandler}. */
     onPolicyViolation?: PolicyViolationHandler;
 }
 /**
- * Parse a commit message into structured metadata.
- *
- * Supports three formats:
- * - `type: description`
- * - `scope|type: description` (pipe-prefixed scope)
- * - `type(scope): description` (conventional commit parenthesized scope)
+ * Parses a commit message into structured metadata.
  *
- * Resolves aliases (e.g., `feature` → `feat`) using the provided work-type configs and the
- * canonical aliases list. Resolves scope aliases when a `scopeAliases` map is provided.
- * Detects breaking changes via `type!:` or `BREAKING CHANGE:` in the message.
+ * Reads the first line through change-grammar's `pipedScope` template (`scope|type: description`, the scope optional),
+ * then its `conventionalCommits` template (`type(scope): description`), and takes the first match. Types and aliases
+ * resolve against `workTypes`, ignoring case; scope aliases resolve when a `scopeAliases` map is provided. Detects
+ * breaking changes via the subject's `!` or `BREAKING CHANGE:` in the message.
  *
- * `!`-policy enforcement is **release-time tolerant**: when the resolved type's policy
+ * `!`-policy enforcement is **release-time tolerant**: When the resolved type's policy
  * forbids `!`, the marker is dropped from the parse (`breaking: false`) and
- * `onPolicyViolation` is invoked. When the policy requires `!`, a bare type triggers the
- * same warning path.
+ * `onPolicyViolation` is invoked.
  */
 export declare function parseCommitMessage(message: string, hash: string, workTypes: Record<string, WorkTypeConfig>, scopeAliases?: Record<string, string>, options?: ParseCommitMessageOptions): ParsedCommit | undefined;
+/**
+ * Reads a commit subject into a change record through the templates that release-kit accepts, before any breaking
+ * policy applies. The engine strips ticket prefixes.
+ */
+export declare function parseSubject(subject: string, workTypes: Record<string, WorkTypeConfig>): ChangeRecord | undefined;
+/** Inputs for {@link evaluateBreakingPolicy}. */
+export interface BreakingPolicyInputs {
+    commit: Commit;
+    resolvedType: string;
+    /** Whether the marker that `prefixSurface` names is present. */
+    hasPrefixBreaking: boolean;
+    hasFooterBreaking: boolean;
+    policy: BreakingPolicy;
+    onPolicyViolation: PolicyViolationHandler | undefined;
+    /** The surface reported for a violation of the marker; `'prefix'` when omitted. */
+    prefixSurface?: PolicyViolationSurface;
+}
+/**
+ * Applies the `!`-policy rules and returns the effective `breaking` flag.
+ *
+ * A violation invokes `onPolicyViolation` and drops the marker (`breaking: false`); the
+ * commit still parses.
+ */
+export declare function evaluateBreakingPolicy(inputs: BreakingPolicyInputs): boolean;
+/**
+ * Resolves a raw type string to its canonical type name using the record keys and aliases.
+ */
+export declare function resolveType(rawType: string, workTypes: Record<string, WorkTypeConfig>): string | undefined;

package/dist/esm/parseCommitMessage.js

@@ -1,66 +1,59 @@
-export const COMMIT_PREPROCESSOR_PATTERNS = [/^##\s+/, /^#\d+([.-]\d+)?\s+/, /^[A-Z]+-\d+\s+/];
-export const PIPE_SCOPE_SOURCE = '[^|]+';
-const COMMIT_SUBJECT_PATTERN = new RegExp(String.raw `^(?:(${PIPE_SCOPE_SOURCE})\|)?(\w+)(?:\(([^)]+)\))?(!)?:\s*(.*)$`);
+import { compileTemplate, parse, TEMPLATE_CATALOGUE, } from '@williamthorsen/change-grammar';
+const SUBJECT_TEMPLATES = [
+    compileTemplate(TEMPLATE_CATALOGUE.pipedScope),
+    compileTemplate(TEMPLATE_CATALOGUE.conventionalCommits),
+];
 export function parseCommitMessage(message, hash, workTypes, scopeAliases, options) {
     const firstLine = message.split('\n', 1)[0] ?? '';
-    const stripped = stripTicketPrefix(firstLine);
-    const match = stripped.match(COMMIT_SUBJECT_PATTERN);
-    if (!match) {
+    const record = parseSubject(firstLine, workTypes);
+    if (record?.type === undefined || record.title === undefined) {
         return undefined;
     }
-    const pipeScope = match[1];
-    const rawType = match[2];
-    const parenthesizedScope = match[3];
-    const breakingMarker = match[4];
-    const description = match[5];
-    if (rawType === undefined || description === undefined) {
-        return undefined;
-    }
-    const resolvedType = resolveType(rawType, workTypes);
-    if (resolvedType === undefined) {
-        return undefined;
-    }
-    const commit = { message, hash };
+    const commit = { message, subject: firstLine, hash };
     const breaking = evaluateBreakingPolicy({
         commit,
-        resolvedType,
-        hasPrefixBreaking: breakingMarker === '!',
+        resolvedType: record.type,
+        hasPrefixBreaking: record.breaking === true,
         hasFooterBreaking: message.includes('BREAKING CHANGE:'),
-        policy: options?.breakingPolicies?.[resolvedType] ?? 'optional',
+        policy: options?.breakingPolicies?.[record.type] ?? 'optional',
         onPolicyViolation: options?.onPolicyViolation,
     });
-    const rawScope = pipeScope ?? parenthesizedScope;
+    const rawScope = record.scope;
     const resolvedScope = rawScope !== undefined && scopeAliases !== undefined ? (scopeAliases[rawScope] ?? rawScope) : rawScope;
     return {
         message,
         hash,
-        type: resolvedType,
-        description,
+        type: record.type,
+        description: record.title,
         breaking,
         ...(resolvedScope !== undefined && { scope: resolvedScope }),
     };
 }
-function evaluateBreakingPolicy(inputs) {
+export function parseSubject(subject, workTypes) {
+    const taxonomy = toTaxonomy(workTypes);
+    for (const nodes of SUBJECT_TEMPLATES) {
+        const record = parse(nodes, subject, taxonomy);
+        if (record !== undefined) {
+            return record;
+        }
+    }
+    return undefined;
+}
+export function evaluateBreakingPolicy(inputs) {
     const { commit, resolvedType, hasPrefixBreaking, hasFooterBreaking, policy, onPolicyViolation } = inputs;
+    const prefixSurface = inputs.prefixSurface ?? 'prefix';
     if (policy === 'forbidden') {
         if (hasPrefixBreaking) {
-            onPolicyViolation?.(commit, resolvedType, 'prefix');
+            onPolicyViolation?.(commit, resolvedType, prefixSurface);
         }
         if (hasFooterBreaking) {
             onPolicyViolation?.(commit, resolvedType, 'body');
         }
         return false;
     }
-    if (policy === 'required') {
-        if (!hasPrefixBreaking) {
-            onPolicyViolation?.(commit, resolvedType, 'prefix');
-            return false;
-        }
-        return true;
-    }
     return hasPrefixBreaking || hasFooterBreaking;
 }
-function resolveType(rawType, workTypes) {
+export function resolveType(rawType, workTypes) {
     const lowered = rawType.toLowerCase();
     for (const [key, config] of Object.entries(workTypes)) {
         if (key === lowered) {
@@ -76,10 +69,9 @@ function resolveType(rawType, workTypes) {
     }
     return undefined;
 }
-function stripTicketPrefix(message) {
-    let result = message;
-    for (const pattern of COMMIT_PREPROCESSOR_PATTERNS) {
-        result = result.replace(pattern, '');
-    }
-    return result;
+function toTaxonomy(workTypes) {
+    return {
+        tiers: [],
+        types: Object.entries(workTypes).map(([key, config]) => ({ aliases: config.aliases ?? [], key, tier: '' })),
+    };
 }

package/dist/esm/parseRequestedTags.d.ts

@@ -1,8 +1,8 @@
 /**
- * Parse the comma-separated `--tags` flag value into a list of requested tag names.
+ * Parses the comma-separated `--tags` flag value into a list of requested tag names.
  *
  * Empty segments (from `--tags=`, leading/trailing commas, or `--tags=,,`) are dropped. When the
- * resulting list is empty, returns `undefined` so the caller treats it as "no filter" — the same
- * behavior as omitting `--tags` entirely.
+ * resulting list is empty, returns `undefined`, and the caller does not filter the tags, as when
+ * `--tags` is omitted.
  */
 export declare function parseRequestedTags(flagValue: string | undefined): string[] | undefined;

package/dist/esm/planReleaseNotesPreviews.d.ts

@@ -11,7 +11,7 @@ export interface PlanReleaseNotesPreviewsOptions {
     /** Section titles in priority order, typically derived from `resolveWorkTypes(config.workTypes)`. */
     sectionOrder: string[];
 }
-/** Preview files a release will write, alongside the reasons any were left out. */
+/** Preview files that a release will write, with the reasons for any that were left out. */
 export interface ReleaseNotesPreviewsPlan {
     writes: PlannedWrite[];
     warnings: string[];
@@ -20,14 +20,14 @@ export interface ReleaseNotesPreviewsPlan {
  * Computes the per-workspace release-notes previews under `{workspacePath}/docs/` without
  * writing them:
  *
- * - `docs/README.v{version}.md` — the workspace README with release notes injected at the marker.
- * - `docs/RELEASE_NOTES.v{version}.md` — the standalone release notes for this version.
+ * - `docs/README.v{version}.md`: the workspace README with release notes injected at the marker.
+ * - `docs/RELEASE_NOTES.v{version}.md`: the standalone release notes for this version.
  *
- * Renders from the entries the release will write rather than from a saved `changelog.json`, so
+ * Renders from the entries that the release will write rather than from a saved `changelog.json`, so
  * a preview describes the release being prepared rather than the one already on disk.
  *
  * The injected-README preview is omitted (the standalone file is still planned) when the
- * workspace has no readable `README.md`. Both are omitted when the renderer reports no content
- * for this version, with the reason recorded in `warnings`.
+ * workspace does not have a readable `README.md`. Both are omitted when the renderer does not
+ * report any content for this version, with the reason recorded in `warnings`.
  */
 export declare function planReleaseNotesPreviews(options: PlanReleaseNotesPreviewsOptions): ReleaseNotesPreviewsPlan;

package/dist/esm/planVersionBump.d.ts

@@ -10,13 +10,15 @@ export interface VersionBumpPlan {
  * Computes the version bump for a workspace's package files without writing them.
  *
  * The current version comes from the first package file, and the new one from the release type.
- * Every file's post-bump content is rendered in full, preserving the fields the file already
- * carries and the two-space indentation with a trailing newline.
+ * Every file's post-bump content is rendered in full, preserving every field that the file already
+ * contains, with two-space indentation and a trailing newline.
  */
 export declare function planVersionBump(packageFiles: readonly string[], releaseType: ReleaseType): VersionBumpPlan;
 /**
  * Computes an explicit version assignment for a workspace's package files without writing them,
- * bypassing commit-derived bump logic. Backs the `--set-version` flag, and so rejects a
+ * bypassing commit-derived bump logic. Implements the `--set-version` flag, and so rejects a
  * `newVersion` that is not greater than the current version.
  */
 export declare function planVersionSet(packageFiles: readonly string[], newVersion: string): VersionBumpPlan;
+/** Reads a workspace's current version from its first package file, as the version planners do. */
+export declare function readCurrentVersion(packageFiles: readonly string[]): string;

package/dist/esm/planVersionBump.js

@@ -19,6 +19,9 @@ export function planVersionSet(packageFiles, newVersion) {
     }
     return { currentVersion, newVersion, writes: renderVersionWrites(packageFiles, firstFile, firstPkg, newVersion) };
 }
+export function readCurrentVersion(packageFiles) {
+    return readPrimaryPackage(packageFiles).firstPkg.version;
+}
 function readPrimaryPackage(packageFiles) {
     const firstFile = packageFiles[0];
     if (firstFile === undefined) {

package/dist/esm/prepareCommand.d.ts

@@ -47,12 +47,9 @@ export declare function parseArgs(argv: string[]): {
     withReleaseNotes: boolean;
 };
 /**
- * Orchestrates the CLI `prepare` command.
+ * Orchestrates the CLI `prepare` command: checks the working tree, loads and validates the config, discovers the
+ * workspaces, and prepares the release in single-package or monorepo mode.
  *
- * 1. Discovers workspaces from `pnpm-workspace.yaml`.
- * 2. Loads and validates `.config/release-kit.config.ts` (if present).
- * 3. Merges discovered defaults with user config.
- * 4. Delegates to `releasePrepare` or `releasePrepareMono` to compute the release plan.
- * 5. Applies the plan, runs the format command, and prints the result via `reportPrepare`.
+ * A relative `--config` resolves against `invocationDir`.
  */
-export declare function prepareCommand(argv: string[], styles: StreamStyles): Promise<void>;
+export declare function prepareCommand(argv: string[], styles: StreamStyles, invocationDir: string): Promise<void>;

package/dist/esm/prepareCommand.js

@@ -2,11 +2,12 @@ import { execSync } from 'node:child_process';
 import { formatGlyphLine, parseArgsOrExit, reportError, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
+import { readReleaseHistory } from "./buildChangelogEntries.js";
 import { buildDependencyGraph } from "./buildDependencyGraph.js";
 import { configFlagSchema } from "./configFlagSchema.js";
 import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
 import { dim } from "./format.js";
-import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
+import { getAllTagPrefixes } from "./generateChangelogs.js";
 import { RELEASE_GLYPHS } from "./glyphs.js";
 import { mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
 import { loadValidatedConfig, reportConfigProblem, reportConfigWarnings } from "./loadValidatedConfig.js";
@@ -15,6 +16,7 @@ import { applyReleasePlan } from "./releasePlan.js";
 import { releasePrepare } from "./releasePrepare.js";
 import { releasePrepareMono } from "./releasePrepareMono.js";
 import { reportPrepare } from "./reportPrepare.js";
+import { resolveConfigFlag } from "./resolveConfigFlag.js";
 import { validateOnlyExcludesStrandedDependents } from "./validateOnlyExcludesStrandedDependents.js";
 const VALID_BUMP_TYPES = ['major', 'minor', 'patch'];
 const CANONICAL_SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
@@ -76,8 +78,8 @@ export function parseArgs(argv) {
         withReleaseNotes: flags.withReleaseNotes,
     };
 }
-export async function prepareCommand(argv, styles) {
-    const { configPath, dryRun, force, noGitChecks, bumpOverride, only, setVersion, withReleaseNotes } = parseArgs(argv);
+export async function prepareCommand(argv, styles, invocationDir) {
+    const { configPath: configFlag, dryRun, force, noGitChecks, bumpOverride, only, setVersion, withReleaseNotes, } = parseArgs(argv);
     const options = {
         force,
         ...(bumpOverride !== undefined && { bumpOverride }),
@@ -85,7 +87,7 @@ export async function prepareCommand(argv, styles) {
         ...(withReleaseNotes && { withReleaseNotes: true }),
     };
     if (dryRun) {
-        console.info(`\n${formatGlyphLine(RELEASE_GLYPHS, styles.stdout, 'dryRun', 'DRY RUN — no files will be modified')}\n`);
+        console.info(`\n${formatGlyphLine(RELEASE_GLYPHS, styles.stdout, 'dryRun', 'DRY RUN: release-kit will not modify any files')}\n`);
     }
     if (!dryRun && !noGitChecks) {
         try {
@@ -96,7 +98,7 @@ export async function prepareCommand(argv, styles) {
             process.exit(1);
         }
     }
-    const configResult = await loadValidatedConfig(configPath);
+    const configResult = await loadValidatedConfig(resolveConfigFlag(configFlag, invocationDir));
     if (configResult.status === 'invalid') {
         reportConfigProblem(configResult.problem, styles.stderr);
         process.exit(1);
@@ -130,11 +132,6 @@ function runSinglePackageMode(userConfig, options, only, dryRun, style) {
         reportError('--only is only supported for monorepo configurations');
         process.exit(1);
     }
-    if (options.force && options.bumpOverride === undefined) {
-        reportError('--force without --bump is only supported for monorepo configurations. ' +
-            'Use --bump=major|minor|patch to set the level for a single-package release.');
-        process.exit(1);
-    }
     const config = mergeSinglePackageConfig(userConfig);
     runAndReport(() => releasePrepare(config, options), dryRun, style);
 }
@@ -154,6 +151,7 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
             'contributing workspace. To use --set-version, run on a config without a `project` block.');
         process.exit(1);
     }
+    let configuredWorkspaceDirs;
     if (only !== undefined) {
         const knownNames = config.workspaces.map((w) => w.dir);
         for (const name of only) {
@@ -165,12 +163,8 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
         }
         const graph = buildDependencyGraph(config.workspaces);
         const violations = validateOnlyExcludesStrandedDependents(config.workspaces, only, graph, (workspace) => {
-            const tagPrefixes = [
-                workspace.tagPrefix,
-                ...(workspace.legacyIdentities?.map((identity) => identity.tagPrefix) ?? []),
-            ];
-            const result = getCommitsSinceTarget(tagPrefixes, workspace.paths);
-            return { has: result.commits.length > 0, tag: result.tag };
+            const history = readReleaseHistory(config, { tagPrefixes: getAllTagPrefixes(workspace), paths: workspace.paths });
+            return { has: history.unreleased.commits.length > 0, tag: history.previousTag };
         });
         if (violations !== undefined) {
             reportError('--only excludes packages with changes that would be stranded by the release.');
@@ -182,6 +176,7 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
             process.stderr.write('Alternatively, run `release-kit prepare` without --only to release everything.\n');
             process.exit(1);
         }
+        configuredWorkspaceDirs = knownNames;
         config.workspaces = config.workspaces.filter((w) => only.includes(w.dir));
     }
     if (setVersion !== undefined) {
@@ -194,7 +189,11 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
             process.exit(1);
         }
     }
-    runAndReport(() => releasePrepareMono(config, { ...options, ...(only !== undefined && { only }) }), dryRun, style);
+    runAndReport(() => releasePrepareMono(config, {
+        ...options,
+        ...(only !== undefined && { only }),
+        ...(configuredWorkspaceDirs !== undefined && { configuredWorkspaceDirs }),
+    }), dryRun, style);
 }
 function runAndReport(computePlan, dryRun, style) {
     let plan;
@@ -203,7 +202,7 @@ function runAndReport(computePlan, dryRun, style) {
     }
     catch (error) {
         reportError(describeError(error));
-        process.stderr.write('No files were written; the working tree is unchanged.\n');
+        process.stderr.write('The command did not write any files; the working tree is unchanged.\n');
         process.exit(1);
     }
     if (dryRun) {

package/dist/esm/previewTagPrefixes.d.ts

@@ -2,7 +2,7 @@ import { type UndeclaredTagPrefix } from './detectUndeclaredTagPrefixes.js';
 import type { ReleaseKitConfig } from './types.js';
 /** One workspace's preview row in the tag-prefix preview. */
 export interface TagPrefixPreviewRow {
-    /** Workspace-relative directory path (e.g., `packages/core`). */
+    /** Directory path relative to the repo root (e.g., `packages/core`). */
     workspacePath: string;
     /** Directory basename (e.g., `core`). */
     dir: string;
@@ -10,7 +10,7 @@ export interface TagPrefixPreviewRow {
     derivedPrefix: string | null;
     /** Human-readable reason derivation failed, or `null` when it succeeded. */
     derivationError: string | null;
-    /** Count of tags matching the derived prefix; `0` when derivation failed or no tags exist. */
+    /** Count of tags matching the derived prefix; `0` when derivation failed or the repo lacks matching tags. */
     derivedTagCount: number;
     /** One entry per declared legacy prefix, with its current tag count. */
     legacyEntries: LegacyTagPrefixEntry[];
@@ -40,14 +40,12 @@ export interface TagPrefixPreview {
     retiredPackages: RetiredPackagePreviewEntry[];
 }
 /**
- * Build a structured preview of tag-prefix state for every discovered workspace.
+ * Builds a structured preview of tag-prefix state for every discovered workspace.
  *
- * Derives each workspace's tag prefix via `deriveWorkspaceConfig()`, recording the derivation error on failure
- * rather than aborting. A repo releasing as a single package previews no row; one declaring patterns that
- * resolve to no package throws, because the manifest is then what needs repairing and a clean table would
- * hide that.
- * Reads the already-validated `config` to surface declared legacy prefixes per workspace, scans local
- * git tags for undeclared candidate prefixes via `detectUndeclaredTagPrefixes`, and reports collisions
- * across successfully-derived prefixes.
+ * Records a workspace's derivation error rather than aborting. For a repo releasing as a single package, the
+ * preview doesn't contain any rows; for one declaring patterns that don't resolve to any package, the function
+ * throws, because the manifest then needs repairing and a clean table would hide that. Also reports the legacy
+ * prefixes that the validated `config` declares per workspace, undeclared candidate prefixes among the local git
+ * tags, and collisions across the successfully derived prefixes.
  */
 export declare function previewTagPrefixes(config?: ReleaseKitConfig): TagPrefixPreview;

package/dist/esm/propagateBumps.d.ts

@@ -6,17 +6,16 @@ export interface ReleaseEntry {
     /** Present when this workspace was bumped (wholly or partly) due to a dependency update. */
     propagatedFrom?: PropagationSource[];
     /**
-     * Explicit new version override used for propagation metadata.
-     * When set, dependents see this value in their `propagatedFrom.newVersion` entry instead of a version computed from
-     * `releaseType`. Used by the `--set-version` CLI path so propagation reflects the overridden version.
+     * Explicit new version, which dependents record in their `propagatedFrom.newVersion` entry in place of a version
+     * computed from `releaseType`.
      */
     newVersionOverride?: string;
 }
 /**
- * Walk upward through the dependency graph via BFS, adding `patch` bumps for dependents
- * not already in the release set with a higher bump.
+ * Walks upward through the dependency graph breadth-first, adding a `patch` bump for each dependent
+ * not already in the release set.
  *
- * Returns the full release set (direct + propagated). Direct entries that also have a
- * propagated dependency get `propagatedFrom` metadata without changing their bump type.
+ * Returns the full release set (direct + propagated). An entry already in the set that also has a
+ * propagated dependency gains `propagatedFrom` metadata without a change to its bump type.
  */
 export declare function propagateBumps(directBumps: Map<string, ReleaseEntry>, graph: DependencyGraph): Map<string, ReleaseEntry>;

package/dist/esm/publish.d.ts

@@ -4,5 +4,5 @@ export interface PublishOptions {
     dryRun: boolean;
     provenance: boolean;
 }
-/** Publish a single package by running `{pm} publish` from its workspace directory. */
+/** Publishes a single package by running `{pm} publish` from its workspace directory. */
 export declare function publishPackage(resolvedTag: ResolvedTag, packageManager: PackageManager, options: PublishOptions): void;

package/dist/esm/publishCommand.d.ts

@@ -1,6 +1,7 @@
 import { type StreamStyles } from '@williamthorsen/nmr-core';
 /**
- * Orchestrate the CLI `publish` command: parse flags, open a named config, discover workspaces, resolve tags
- * from HEAD, detect the package manager, validate `--tags`, and publish each tag with inject/restore lifecycle.
+ * Orchestrates the CLI `publish` command: checks for a clean working tree, resolves the tags on HEAD, and publishes
+ * each publishable one, injecting release notes into its README for the duration of the publish.
+ * A relative `--config` resolves against `invocationDir`.
  */
-export declare function publishCommand(argv: string[], styles: StreamStyles): Promise<void>;
+export declare function publishCommand(argv: string[], styles: StreamStyles, invocationDir: string): Promise<void>;