@williamthorsen/release-kit 11.0.0 → 12.0.0

package/dist/esm/enumerateReleaseWindows.js

@@ -0,0 +1,124 @@
+import { execFileSync } from 'node:child_process';
+import { GIT_OUTPUT_LIMIT } from '@williamthorsen/nmr-core';
+import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
+const FIELD_SEPARATOR = '\u{1F}';
+const RECORD_SEPARATOR = '\u{1E}';
+export function enumerateReleaseWindows(options) {
+    const { now = Date.now, paths, tagPrefixes, unreleasedTag } = options;
+    if (tagPrefixes.length === 0) {
+        throw new Error('enumerateReleaseWindows: tagPrefixes must contain at least one entry');
+    }
+    const unreleasedWindow = {
+        version: unreleasedTag,
+        timestamp: Math.floor(now() / 1_000),
+        commits: [],
+    };
+    const ancestry = readAncestry();
+    if (ancestry.parentsByHash.size === 0) {
+        return [unreleasedWindow];
+    }
+    const boundaries = readTagBoundaries(tagPrefixes, ancestry.positionByHash);
+    const releasedWindows = boundaries.map((boundary) => ({
+        version: boundary.tag,
+        timestamp: boundary.timestamp,
+        commits: [],
+    }));
+    const windowIndexByHash = claimAncestors(boundaries, ancestry.parentsByHash);
+    for (const commit of readCommits(paths).toReversed()) {
+        const windowIndex = windowIndexByHash.get(commit.hash);
+        const window = windowIndex === undefined ? unreleasedWindow : (releasedWindows[windowIndex] ?? unreleasedWindow);
+        window.commits.push(commit);
+    }
+    return [unreleasedWindow, ...releasedWindows.toReversed()];
+}
+function claimAncestors(boundaries, parentsByHash) {
+    const windowIndexByHash = new Map();
+    for (const [windowIndex, boundary] of boundaries.entries()) {
+        const pending = [boundary.hash];
+        while (pending.length > 0) {
+            const hash = pending.pop();
+            if (hash === undefined || windowIndexByHash.has(hash)) {
+                continue;
+            }
+            windowIndexByHash.set(hash, windowIndex);
+            pending.push(...(parentsByHash.get(hash) ?? []));
+        }
+    }
+    return windowIndexByHash;
+}
+function matchesTagPrefix(tagName, tagPrefixes) {
+    return tagPrefixes.some((prefix) => tagName.startsWith(prefix) && /^\d/.test(tagName.slice(prefix.length)));
+}
+function parseCommitRecord(record) {
+    const [hash, subject, message] = record.replace(/^\n+/, '').split(FIELD_SEPARATOR);
+    if (hash === undefined || subject === undefined || message === undefined || hash === '') {
+        return undefined;
+    }
+    const trimmedMessage = message.replace(/\s+$/, '');
+    const bodyStart = trimmedMessage.indexOf('\n\n');
+    const body = bodyStart === -1 ? '' : trimmedMessage.slice(bodyStart + 2);
+    return { hash, subject, body, message: trimmedMessage };
+}
+function readAncestry() {
+    const args = ['rev-list', '--topo-order', '--parents', '--ignore-missing', 'HEAD'];
+    const output = runGit(args, `'git rev-list' for HEAD`);
+    const ancestry = { parentsByHash: new Map(), positionByHash: new Map() };
+    for (const [position, line] of output.split('\n').entries()) {
+        const [hash, ...parents] = line.split(' ');
+        if (hash === undefined || hash === '') {
+            continue;
+        }
+        ancestry.parentsByHash.set(hash, parents);
+        ancestry.positionByHash.set(hash, position);
+    }
+    return ancestry;
+}
+function readCommits(paths) {
+    const format = `%H${FIELD_SEPARATOR}%s${FIELD_SEPARATOR}%B${RECORD_SEPARATOR}`;
+    const args = ['log', 'HEAD', `--pretty=format:${format}`];
+    if (paths !== undefined && paths.length > 0) {
+        args.push('--', ...paths);
+    }
+    const output = runGit(args, `'git log' for HEAD`);
+    const commits = [];
+    for (const record of output.split(RECORD_SEPARATOR)) {
+        const commit = parseCommitRecord(record);
+        if (commit !== undefined) {
+            commits.push(commit);
+        }
+    }
+    return commits;
+}
+function readTagBoundaries(tagPrefixes, positionByHash) {
+    const fields = ['%(refname:strip=2)', '%(creatordate:unix)', '%(objectname)', '%(*objectname)'];
+    const args = ['for-each-ref', `--format=${fields.join('%1f')}`, 'refs/tags'];
+    const output = runGit(args, `'git for-each-ref' for refs/tags`);
+    const boundaries = [];
+    for (const line of output.split('\n')) {
+        const [tag, creatorDate, objectName, dereferencedName] = line.split(FIELD_SEPARATOR);
+        if (tag === undefined || creatorDate === undefined || objectName === undefined) {
+            continue;
+        }
+        if (!matchesTagPrefix(tag, tagPrefixes)) {
+            continue;
+        }
+        const hash = dereferencedName || objectName;
+        const position = positionByHash.get(hash);
+        if (position !== undefined) {
+            boundaries.push({ hash, position, tag, timestamp: Number(creatorDate) });
+        }
+    }
+    return boundaries.toSorted((left, right) => right.position - left.position);
+}
+function runGit(args, description) {
+    try {
+        return execFileSync('git', args, {
+            encoding: 'utf8',
+            maxBuffer: GIT_OUTPUT_LIMIT,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (error) {
+        throw chainError(`Failed to run ${description}`, error);
+    }
+}

package/dist/esm/generateChangelogs.d.ts

@@ -1,32 +1,14 @@
 import type { WorkspaceConfig } from './types.js';
-/**
- * Build a git-cliff tag pattern from one or more tag prefixes.
- *
- * Single-prefix input preserves the historical `<prefix>[0-9].*` shape. Multi-prefix input
- * returns `(prefix1|prefix2|...)[0-9].*` so git-cliff's regex-based `--tag-pattern` accepts
- * tags under any listed prefix. Each prefix is regex-escaped so metacharacters in operator-
- * supplied legacy prefixes cannot alter the pattern's meaning.
- *
- * @param tagPrefixes - Tag prefixes to match as a union (must contain at least one entry).
- */
-export declare function buildTagPattern(tagPrefixes: readonly string[]): string;
 /**
  * Return the workspace's derived tag prefix followed by each declared legacy-identity tag
  * prefix. Shared by `releasePrepareMono` (the production prepare path) and
  * `validateOverridesCommand` so the two compute byte-equal per-workspace tag-prefix unions.
  */
 export declare function getAllTagPrefixes(workspace: WorkspaceConfig): string[];
-/**
- * Options for `buildChangelogEntries`-driven flows that consume git-cliff output.
- *
- * The fields here mirror the subset of git-cliff CLI options that the in-package pipeline
- * still passes through (tag-pattern union, include-path filtering for monorepo workspaces).
- * `generateChangelog` and `generateChangelogs` (the prior cliff `--output` invokers) are
- * removed; markdown rendering is now handled by `renderChangelogMarkdown.ts`.
- */
+/** Options for `buildChangelogEntries`: the tag prefixes and pathspecs that bound its release windows. */
 export interface GenerateChangelogOptions {
-    /** Tag pattern to match release tags (passed as --tag-pattern to git-cliff). */
-    tagPattern?: string;
-    /** Paths to include in the changelog (passed as --include-path to git-cliff). */
-    includePaths?: string[];
+    /** Tag prefixes to match as a union; must contain at least one entry. */
+    tagPrefixes: readonly string[];
+    /** Git pathspecs restricting the history to commits that touch them; all paths when omitted. */
+    paths?: readonly string[];
 }

package/dist/esm/generateChangelogs.js

@@ -1,17 +1,3 @@
-export function buildTagPattern(tagPrefixes) {
-    if (tagPrefixes.length === 0) {
-        throw new Error('buildTagPattern: tagPrefixes must contain at least one entry');
-    }
-    if (tagPrefixes.length === 1) {
-        const single = tagPrefixes[0] ?? '';
-        return `${single}[0-9].*`;
-    }
-    const escaped = tagPrefixes.map(escapeRegex);
-    return `(${escaped.join('|')})[0-9].*`;
-}
 export function getAllTagPrefixes(workspace) {
     return [workspace.tagPrefix, ...(workspace.legacyIdentities?.map((identity) => identity.tagPrefix) ?? [])];
 }
-function escapeRegex(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
-}

package/dist/esm/glyphs.d.ts

@@ -1,3 +1,3 @@
 /** Glyphs that name no status; a status marker comes from nmr-core's `STATUS_GLYPHS`. */
-export declare const RELEASE_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"bump" | "dryRun" | "tag", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
+export declare const RELEASE_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"tag" | "bump" | "dryRun", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
 export type ReleaseGlyphName = keyof (typeof RELEASE_GLYPHS)['rich'];

package/dist/esm/help/prepareHelp.d.ts

@@ -3,6 +3,6 @@
  * dispatcher and asserted by the help drift guard test; kept free of import-time side
  * effects so both can load it.
  */
-export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --config <path>       Path to config file (default: .config/release-kit.config.ts)\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Override the bump type for all workspaces\n  --set-version=X.Y.Z   Set an explicit version; bypasses commit-derived bumps. In monorepo\n                         mode it requires --only, and is rejected when a 'project' block is configured.\n  --force               Release even when no commits or no bump-worthy commits exist\n                         since the last tag. In monorepo and project mode, defaults to\n                         patch when --bump is not given; use --bump=X for a different\n                         level. In single-package mode, a bare --force is rejected \u2014\n                         pass --bump=major|minor|patch.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).\n                         When a 'project' block is configured, the project release is skipped.\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
+export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --config <path>       Path to config file (default: .config/release-kit.config.ts)\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Set the level of every release that happens; does not trigger one\n  --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo\n                         mode it requires --only, and is rejected when a 'project' block is configured.\n  --force               Release even when no commits or no bump-worthy commits exist\n                         since the last tag. Defaults to patch when --bump is not given;\n                         use --bump=X for a different level.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).\n                         When a 'project' block is configured, the project release is skipped.\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
 /** Prints the prepare command's help text. */
 export declare function showPrepareHelp(): void;

package/dist/esm/help/prepareHelp.js

@@ -6,14 +6,12 @@ Run release preparation with automatic workspace discovery.
 Options:
   --config <path>       Path to config file (default: .config/release-kit.config.ts)
   --dry-run             Run without modifying any files
-  --bump=major|minor|patch  Override the bump type for all workspaces
-  --set-version=X.Y.Z   Set an explicit version; bypasses commit-derived bumps. In monorepo
+  --bump=major|minor|patch  Set the level of every release that happens; does not trigger one
+  --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo
                          mode it requires --only, and is rejected when a 'project' block is configured.
   --force               Release even when no commits or no bump-worthy commits exist
-                         since the last tag. In monorepo and project mode, defaults to
-                         patch when --bump is not given; use --bump=X for a different
-                         level. In single-package mode, a bare --force is rejected —
-                         pass --bump=major|minor|patch.
+                         since the last tag. Defaults to patch when --bump is not given;
+                         use --bump=X for a different level.
   --no-git-checks, -n   Skip the clean-working-tree check
   --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).
                          When a 'project' block is configured, the project release is skipped.

package/dist/esm/index.d.ts

@@ -1,2 +1,2 @@
-export { type ChangelogOverrideScope, validateAllChangelogOverrides, type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult, } from './changelogOverrides.js';
+export { type ChangelogOverrideScope, type OverrideTargetItem, validateAllChangelogOverrides, type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult, } from './changelogOverrides.js';
 export { formatValidateOverridesResult, type ValidateOverridesCommandResult } from './validateOverridesCommand.js';

package/dist/esm/init/initCommand.js

@@ -62,7 +62,7 @@ export function initCommand({ dryRun, force, styles, withConfig }) {
     }
     printStep('Next steps');
     const configHint = withConfig
-        ? '1. (Optional) Customize .config/release-kit.config.ts and .config/git-cliff.toml.'
+        ? '1. (Optional) Customize .config/release-kit.config.ts.'
         : '1. (Optional) Run again with --with-config to scaffold config files.';
     console.info(`
   ${configHint}

package/dist/esm/init/scaffold.d.ts

@@ -6,8 +6,6 @@ interface ScaffoldOptions {
     overwrite: boolean;
     withConfig: boolean;
 }
-/** Copy the bundled cliff.toml.template to `.config/git-cliff.toml` in the target repo. */
-export declare function copyCliffTemplate(dryRun: boolean, overwrite: boolean): WriteResult;
 /** Scaffold release-kit files for the target repo. Returns a result for each file attempted. */
 export declare function scaffoldFiles({ repoType, dryRun, overwrite, withConfig }: ScaffoldOptions): WriteResult[];
 export {};

package/dist/esm/init/scaffold.js

@@ -1,33 +1,5 @@
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { findPackageRoot, writeFileWithCheck } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { writeFileWithCheck } from '@williamthorsen/nmr-core';
 import { createGithubReleaseWorkflow, publishWorkflow, releaseConfigScript, releaseWorkflow } from "./templates.js";
-export function copyCliffTemplate(dryRun, overwrite) {
-    const destPath = '.config/git-cliff.toml';
-    let root;
-    try {
-        root = findPackageRoot(import.meta.url);
-    }
-    catch (error) {
-        const message = describeError(error);
-        return { filePath: destPath, outcome: 'failed', error: `Failed to resolve package root: ${message}` };
-    }
-    const templatePath = resolve(root, 'cliff.toml.template');
-    let content;
-    try {
-        content = readFileSync(templatePath, 'utf8');
-    }
-    catch (error) {
-        const message = describeError(error);
-        return {
-            filePath: destPath,
-            outcome: 'failed',
-            error: `Failed to read bundled template at ${templatePath}: ${message}`,
-        };
-    }
-    return writeFileWithCheck(destPath, content, { dryRun, overwrite });
-}
 export function scaffoldFiles({ repoType, dryRun, overwrite, withConfig }) {
     const results = [
         writeFileWithCheck('.github/workflows/create-github-release.yaml', createGithubReleaseWorkflow(repoType), {
@@ -38,7 +10,7 @@ export function scaffoldFiles({ repoType, dryRun, overwrite, withConfig }) {
         writeFileWithCheck('.github/workflows/release.yaml', releaseWorkflow(repoType), { dryRun, overwrite }),
     ];
     if (withConfig) {
-        results.push(writeFileWithCheck('.config/release-kit.config.ts', releaseConfigScript(repoType), { dryRun, overwrite }), copyCliffTemplate(dryRun, overwrite));
+        results.push(writeFileWithCheck('.config/release-kit.config.ts', releaseConfigScript(repoType), { dryRun, overwrite }));
     }
     return results;
 }

package/dist/esm/loadConfig.d.ts

@@ -40,7 +40,7 @@ export interface RootPackageInfo {
  *   removes the workspace; unlisted packages keep defaults.
  * - `workTypes`: shallow merge — consumer entries override or add to defaults by key.
  * - `versionPatterns`: consumer value replaces defaults entirely.
- * - `formatCommand`, `cliffConfigPath`, `scopeAliases`: consumer value wins.
+ * - `formatCommand`, `scopeAliases`: consumer value wins.
  * - `project`: present iff `userConfig.project` is declared. Resolves `tagPrefix` to
  *   `DEFAULT_PROJECT_TAG_PREFIX` and `paths` to the union of the retained workspaces' `paths`
  *   when omitted. Requires `rootPackage` to be passed and to contain a valid `version` field;

package/dist/esm/loadConfig.js

@@ -99,9 +99,6 @@ function applyOptionalPassthroughFields(result, userConfig) {
     if (userConfig?.formatCommand !== undefined) {
         result.formatCommand = userConfig.formatCommand;
     }
-    if (userConfig?.cliffConfigPath !== undefined) {
-        result.cliffConfigPath = userConfig.cliffConfigPath;
-    }
     if (userConfig?.scopeAliases !== undefined) {
         result.scopeAliases = userConfig.scopeAliases;
     }
@@ -215,7 +212,7 @@ function assertNoTagPrefixCollisions(workspaces, retiredPackages, project) {
             if (isPrefixCollision(a.prefix, b.prefix)) {
                 throw new Error(`Tag prefix collision: '${a.prefix}' (${a.label}) and '${b.prefix}' (${b.label}). ` +
                     'One prefix is identical to or a strict prefix of the other; ' +
-                    'this would cause `git describe --match=<prefix>*` to return cross-matches.');
+                    'a tag under the longer prefix can then match the shorter one, whose releases would absorb it.');
             }
         }
     }

package/dist/esm/parseChangeRecordBlock.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reads the last `change-record` block in a commit message into the change entries that it records.
+ *
+ * The block's grammar is codeassembly's `change-record.md`: a fence whose info string is exactly `change-record`,
+ * containing a YAML mapping. A merge commit's block carries `entries` plus the top-level `pr_number` and `ticket_ref`.
+ * A key that the grammar does not declare is ignored, and a declared key whose value is null reads as absent. Any
+ * defect makes the whole block malformed; no entry is salvaged from a defective list.
+ */
+export declare function parseChangeRecordBlock(message: string): ChangeRecordBlockReading;
+/**
+ * Removes every `change-record` block from a message, fences included. A block that never closes runs to the end of
+ * the message, as a Markdown renderer reads it.
+ */
+export declare function stripChangeRecordBlocks(message: string): string;
+/**
+ * What a commit's last `change-record` block reads as: absent, malformed with the defect named, or the entries that
+ * it records with the merge's pull-request number and ticket reference when the block declares them.
+ */
+export type ChangeRecordBlockReading = {
+    kind: 'absent';
+} | {
+    kind: 'malformed';
+    reason: string;
+} | {
+    kind: 'read';
+    entries: ChangeRecordEntry[];
+    prNumber?: number;
+    ticketRef?: string;
+};
+/** One outcome of a change, as the block records it. */
+export interface ChangeRecordEntry {
+    breaking: boolean;
+    migration?: string;
+    scopes: string[];
+    text: string;
+    type: string;
+}

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

@@ -6,18 +6,20 @@ export declare const COMMIT_PREPROCESSOR_PATTERNS: readonly RegExp[];
  *
  * 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.
+ * Exported because `buildChangelogEntries.ts` builds its breaking-marker pattern from the same atom.
  */
 export declare const PIPE_SCOPE_SOURCE = "[^|]+";
-/** Surface where a `!`/`BREAKING CHANGE:` policy violation was detected. */
-export type PolicyViolationSurface = 'prefix' | 'body';
+/**
+ * Surface where a breaking-policy violation was detected: a subject's `!`, a `BREAKING CHANGE:` footer, or a
+ * change-record entry's `breaking`.
+ */
+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.
+ * `readReleaseHistory` collects the invocations for the unreleased window, and the release
+ * report lists them.
  */
 export type PolicyViolationHandler = (commit: Commit, type: string, surface: PolicyViolationSurface) => void;
 /** Optional configuration for `parseCommitMessage` beyond the core inputs. */
@@ -49,3 +51,26 @@ export interface ParseCommitMessageOptions {
  * same warning path.
  */
 export declare function parseCommitMessage(message: string, hash: string, workTypes: Record<string, WorkTypeConfig>, scopeAliases?: Record<string, string>, options?: ParseCommitMessageOptions): ParsedCommit | 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: 'forbidden' | 'optional' | 'required';
+    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

@@ -20,7 +20,7 @@ export function parseCommitMessage(message, hash, workTypes, scopeAliases, optio
     if (resolvedType === undefined) {
         return undefined;
     }
-    const commit = { message, hash };
+    const commit = { message, subject: firstLine, hash };
     const breaking = evaluateBreakingPolicy({
         commit,
         resolvedType,
@@ -40,11 +40,12 @@ export function parseCommitMessage(message, hash, workTypes, scopeAliases, optio
         ...(resolvedScope !== undefined && { scope: resolvedScope }),
     };
 }
-function evaluateBreakingPolicy(inputs) {
+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');
@@ -53,14 +54,14 @@ function evaluateBreakingPolicy(inputs) {
     }
     if (policy === 'required') {
         if (!hasPrefixBreaking) {
-            onPolicyViolation?.(commit, resolvedType, 'prefix');
+            onPolicyViolation?.(commit, resolvedType, prefixSurface);
             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) {

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";
@@ -130,11 +131,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);
 }
@@ -165,12 +161,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.');