@williamthorsen/release-kit 10.2.1 → 10.3.0

package/dist/esm/planReleaseNotesPreviews.d.ts

@@ -0,0 +1,13 @@
+import type { PlannedWrite } from './releasePlan.js';
+import type { ChangelogEntry } from './types.js';
+export interface PlanReleaseNotesPreviewsOptions {
+    workspacePath: string;
+    tag: string;
+    entries: readonly ChangelogEntry[];
+    sectionOrder: string[];
+}
+export interface ReleaseNotesPreviewsPlan {
+    writes: PlannedWrite[];
+    warnings: string[];
+}
+export declare function planReleaseNotesPreviews(options: PlanReleaseNotesPreviewsOptions): ReleaseNotesPreviewsPlan;

package/dist/esm/planReleaseNotesPreviews.js

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractVersion } from "./changelogJsonUtils.js";
+import { renderInjectedReadmeFromEntries } from "./injectReleaseNotesIntoReadme.js";
+export function planReleaseNotesPreviews(options) {
+    const { workspacePath, tag, entries, sectionOrder } = options;
+    const warnings = [];
+    const readmePath = path.join(workspacePath, 'README.md');
+    const readme = readWorkspaceReadme(readmePath, warnings);
+    const rendered = renderInjectedReadmeFromEntries(readme.content, entries, tag, sectionOrder);
+    if (rendered === undefined) {
+        return { writes: [], warnings };
+    }
+    if (!readme.exists && !readme.unreadable) {
+        warnings.push(`${readmePath} not found; skipping injected-README preview but still writing standalone release notes`);
+    }
+    const version = extractVersion(tag);
+    const docsDir = path.join(workspacePath, 'docs');
+    const writes = [];
+    if (readme.exists) {
+        writes.push({ path: path.join(docsDir, `README.v${version}.md`), content: rendered.injectedReadme });
+    }
+    writes.push({
+        path: path.join(docsDir, `RELEASE_NOTES.v${version}.md`),
+        content: rendered.releaseNotesMarkdown.endsWith('\n')
+            ? rendered.releaseNotesMarkdown
+            : `${rendered.releaseNotesMarkdown}\n`,
+    });
+    return { writes, warnings };
+}
+function readWorkspaceReadme(readmePath, warnings) {
+    if (!existsSync(readmePath)) {
+        return { content: '', exists: false, unreadable: false };
+    }
+    try {
+        return { content: readFileSync(readmePath, 'utf8'), exists: true, unreadable: false };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warnings.push(`failed to read ${readmePath}: ${message}; skipping injected-README preview`);
+        return { content: '', exists: false, unreadable: true };
+    }
+}

package/dist/esm/planVersionBump.d.ts

@@ -0,0 +1,9 @@
+import type { PlannedWrite } from './releasePlan.js';
+import type { ReleaseType } from './types.js';
+export interface VersionBumpPlan {
+    currentVersion: string;
+    newVersion: string;
+    writes: PlannedWrite[];
+}
+export declare function planVersionBump(packageFiles: readonly string[], releaseType: ReleaseType): VersionBumpPlan;
+export declare function planVersionSet(packageFiles: readonly string[], newVersion: string): VersionBumpPlan;

package/dist/esm/planVersionBump.js

@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs';
+import { bumpVersion } from "./bumpVersion.js";
+function isPackageJson(value) {
+    return typeof value === 'object' && value !== null && 'version' in value && typeof value.version === 'string';
+}
+export function planVersionBump(packageFiles, releaseType) {
+    const { firstFile, firstPkg } = readPrimaryPackage(packageFiles);
+    const currentVersion = firstPkg.version;
+    const newVersion = bumpVersion(currentVersion, releaseType);
+    return { currentVersion, newVersion, writes: renderVersionWrites(packageFiles, firstFile, firstPkg, newVersion) };
+}
+export function planVersionSet(packageFiles, newVersion) {
+    const { firstFile, firstPkg } = readPrimaryPackage(packageFiles);
+    const currentVersion = firstPkg.version;
+    return { currentVersion, newVersion, writes: renderVersionWrites(packageFiles, firstFile, firstPkg, newVersion) };
+}
+function readPrimaryPackage(packageFiles) {
+    const firstFile = packageFiles[0];
+    if (firstFile === undefined) {
+        throw new Error('No package files specified');
+    }
+    return { firstFile, firstPkg: readPackageJson(firstFile) };
+}
+function renderVersionWrites(packageFiles, firstFile, firstPkg, newVersion) {
+    return packageFiles.map((filePath) => {
+        const pkg = filePath === firstFile ? firstPkg : readPackageJson(filePath);
+        pkg.version = newVersion;
+        return { path: filePath, content: JSON.stringify(pkg, null, 2) + '\n' };
+    });
+}
+function readPackageJson(filePath) {
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`Failed to read ${filePath}: ${error instanceof Error ? error.message : String(error)}`, {
+            cause: error,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse JSON in ${filePath}: ${error instanceof Error ? error.message : String(error)}`, {
+            cause: error,
+        });
+    }
+    if (!isPackageJson(parsed)) {
+        throw new Error(`No valid 'version' field found in ${filePath}`);
+    }
+    return parsed;
+}

package/dist/esm/prepareCommand.d.ts

@@ -1,7 +1,4 @@
-import type { WriteResult } from '@williamthorsen/nmr-core';
 import type { ReleaseType } from './types.js';
-export declare const RELEASE_TAGS_FILE = "tmp/.release-tags";
-export declare const RELEASE_SUMMARY_FILE = "tmp/.release-summary";
 export declare const prepareFlagSchema: {
     dryRun: {
         long: string;
@@ -42,5 +39,4 @@ export declare function parseArgs(argv: string[]): {
     setVersion: string | undefined;
     withReleaseNotes: boolean;
 };
-export declare function writeReleaseTags(tags: string[], dryRun: boolean): WriteResult | undefined;
 export declare function prepareCommand(argv: string[]): Promise<void>;

package/dist/esm/prepareCommand.js

@@ -1,18 +1,18 @@
-import { parseArgsOrExit, reportError, writeFileWithCheck } from '@williamthorsen/nmr-core';
+import { execSync } from 'node:child_process';
+import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
 import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
 import { buildDependencyGraph } from "./buildDependencyGraph.js";
-import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { discoverWorkspaces } from "./discoverWorkspaces.js";
 import { dim } from "./format.js";
 import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
 import { loadConfig, mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
+import { RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE } from "./releaseFiles.js";
+import { applyReleasePlan } from "./releasePlan.js";
 import { releasePrepare } from "./releasePrepare.js";
 import { releasePrepareMono } from "./releasePrepareMono.js";
 import { reportPrepare } from "./reportPrepare.js";
 import { validateConfig } from "./validateConfig.js";
 import { validateOnlyExcludesStrandedDependents } from "./validateOnlyExcludesStrandedDependents.js";
-export const RELEASE_TAGS_FILE = 'tmp/.release-tags';
-export const RELEASE_SUMMARY_FILE = 'tmp/.release-summary';
 const VALID_BUMP_TYPES = ['major', 'minor', 'patch'];
 const CANONICAL_SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
 function isReleaseType(value) {
@@ -71,19 +71,9 @@ export function parseArgs(argv) {
         withReleaseNotes: flags.withReleaseNotes,
     };
 }
-export function writeReleaseTags(tags, dryRun) {
-    if (tags.length === 0) {
-        return undefined;
-    }
-    return writeFileWithCheck(RELEASE_TAGS_FILE, tags.join('\n'), {
-        dryRun,
-        overwrite: true,
-    });
-}
 export async function prepareCommand(argv) {
     const { dryRun, force, noGitChecks, bumpOverride, only, setVersion, withReleaseNotes } = parseArgs(argv);
     const options = {
-        dryRun,
         force,
         ...(bumpOverride !== undefined && { bumpOverride }),
         ...(setVersion !== undefined && { setVersion }),
@@ -219,48 +209,64 @@ async function loadAndValidateConfig() {
     }
     return config;
 }
-function runAndReport(execute, dryRun) {
-    let result;
+function runAndReport(computePlan, dryRun) {
+    let plan;
     try {
-        result = execute();
+        plan = computePlan();
     }
     catch (error) {
         reportError(error instanceof Error ? error.message : String(error));
+        process.stderr.write('No files were written; the working tree is unchanged.\n');
         process.exit(1);
     }
-    process.stdout.write(reportPrepare(result) + '\n');
-    const writeResult = writeReleaseTags(result.tags, dryRun);
-    if (writeResult?.outcome === 'failed') {
-        reportError(`Failed to write release tags: ${writeResult.error ?? 'unknown error'}`);
+    if (dryRun) {
+        process.stdout.write(reportPrepare(plan, { applied: false }) + '\n');
+        reportPlanFiles(plan, true);
+        return;
+    }
+    try {
+        applyReleasePlan(plan);
+    }
+    catch (error) {
+        reportError(error instanceof Error ? error.message : String(error));
         process.exit(1);
     }
-    if (writeResult) {
-        if (dryRun) {
-            console.info(dim(`  [dry-run] Would write ${RELEASE_TAGS_FILE}: ${result.tags.join(' ')}`));
-        }
-        else {
-            console.info(dim(`  Wrote ${RELEASE_TAGS_FILE}: ${result.tags.join(' ')}`));
-            console.info(dim(`\n   Release tags file: ${RELEASE_TAGS_FILE}`));
-        }
+    const formatError = runFormatCommand(plan.formatCommand);
+    process.stdout.write(reportPrepare(plan, { applied: true, ...(formatError !== undefined && { formatError }) }) + '\n');
+    reportPlanFiles(plan, false);
+    if (formatError !== undefined) {
+        reportError(`The format command failed, but the release is prepared and ${RELEASE_TAGS_FILE} is written. ` +
+            `Format the release files and run 'release-kit commit'.`);
+        process.exit(1);
     }
-    const summary = buildReleaseSummary(result);
-    if (summary.length > 0) {
-        const summaryResult = writeFileWithCheck(RELEASE_SUMMARY_FILE, summary, {
-            dryRun,
-            overwrite: true,
-        });
-        if (summaryResult.outcome === 'failed') {
-            reportError(`Failed to write release summary: ${summaryResult.error ?? 'unknown error'}`);
-            process.exit(1);
-        }
-        if (dryRun) {
+}
+function runFormatCommand(formatCommand) {
+    if (formatCommand === undefined) {
+        return undefined;
+    }
+    try {
+        execSync(formatCommand.command, { stdio: 'inherit' });
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+function reportPlanFiles(plan, dryRun) {
+    if (plan.tags.length === 0) {
+        return;
+    }
+    if (dryRun) {
+        console.info(dim(`  [dry-run] Would write ${RELEASE_TAGS_FILE}: ${plan.tags.join(' ')}`));
+        if (plan.summary.length > 0) {
             console.info(dim(`  [dry-run] Would write ${RELEASE_SUMMARY_FILE}`));
         }
-        else {
-            console.info(dim(`  Wrote ${RELEASE_SUMMARY_FILE}`));
-        }
+        return;
     }
-    if (writeResult && !dryRun) {
-        process.stderr.write(`\nRun 'release-kit commit' to create the release commit.\n`);
+    console.info(dim(`  Wrote ${RELEASE_TAGS_FILE}: ${plan.tags.join(' ')}`));
+    console.info(dim(`\n   Release tags file: ${RELEASE_TAGS_FILE}`));
+    if (plan.summary.length > 0) {
+        console.info(dim(`  Wrote ${RELEASE_SUMMARY_FILE}`));
     }
+    process.stderr.write(`\nRun 'release-kit commit' to create the release commit.\n`);
 }

package/dist/esm/propagateBumps.js

@@ -4,7 +4,7 @@ export function propagateBumps(directBumps, graph, currentVersions) {
     for (const [dir, entry] of directBumps) {
         result.set(dir, { ...entry });
     }
-    const queue = [...directBumps.keys()];
+    const queue = directBumps.keys().toArray();
     const visited = new Set();
     while (queue.length > 0) {
         const dir = queue.shift();

package/dist/esm/releaseFiles.d.ts

@@ -0,0 +1,4 @@
+export declare const RELEASE_TAGS_FILE = "tmp/.release-tags";
+export declare const RELEASE_SUMMARY_FILE = "tmp/.release-summary";
+export declare function resolveReleaseTagsPath(): string;
+export declare function readReleaseTags(): string[];

package/dist/esm/releaseFiles.js

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+export const RELEASE_TAGS_FILE = 'tmp/.release-tags';
+export const RELEASE_SUMMARY_FILE = 'tmp/.release-summary';
+export function resolveReleaseTagsPath() {
+    return resolve(RELEASE_TAGS_FILE);
+}
+export function readReleaseTags() {
+    let content;
+    try {
+        content = readFileSync(RELEASE_TAGS_FILE, 'utf8');
+    }
+    catch (error) {
+        throw new Error(describeTagsReadFailure(error), { cause: error });
+    }
+    return content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function describeTagsReadFailure(error) {
+    const tagsPath = resolveReleaseTagsPath();
+    if (getErrnoCode(error) === 'ENOENT') {
+        return `No tags file found at ${tagsPath}. Run \`release-kit prepare\` first.`;
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    return `Cannot read the tags file at ${tagsPath}: ${detail}`;
+}
+function getErrnoCode(error) {
+    if (error instanceof Error && 'code' in error && typeof error.code === 'string') {
+        return error.code;
+    }
+    return undefined;
+}

package/dist/esm/releasePlan.d.ts

@@ -0,0 +1,10 @@
+import type { PrepareResult } from './types.js';
+export interface PlannedWrite {
+    path: string;
+    content: string;
+}
+export interface ReleasePlan extends PrepareResult {
+    writes: readonly PlannedWrite[];
+    summary: string;
+}
+export declare function applyReleasePlan(plan: ReleasePlan): string[];

package/dist/esm/releasePlan.js

@@ -0,0 +1,53 @@
+import { writeFileWithCheck } from '@williamthorsen/nmr-core';
+import { RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE } from "./releaseFiles.js";
+const HANDOFF_FILES = new Set([RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE]);
+export function applyReleasePlan(plan) {
+    const ordered = orderPlannedWrites(plan);
+    const applied = [];
+    for (const [index, write] of ordered.entries()) {
+        const result = writeFileWithCheck(write.path, write.content, { dryRun: false, overwrite: true });
+        if (result.outcome === 'failed') {
+            const unwritten = ordered.slice(index).map((pending) => pending.path);
+            throw new Error(describeApplyFailure({ failedPath: write.path, error: result.error, applied, unwritten }));
+        }
+        applied.push({ path: write.path, created: result.outcome === 'created' });
+    }
+    return applied.map((write) => write.path);
+}
+function orderPlannedWrites(plan) {
+    const ordered = [...plan.writes];
+    if (plan.summary.length > 0) {
+        ordered.push({ path: RELEASE_SUMMARY_FILE, content: plan.summary });
+    }
+    if (plan.tags.length > 0) {
+        ordered.push({ path: RELEASE_TAGS_FILE, content: plan.tags.join('\n') });
+    }
+    return ordered;
+}
+function describeApplyFailure(args) {
+    const { failedPath, error, applied, unwritten } = args;
+    const total = applied.length + unwritten.length;
+    const lines = [`Failed to write ${failedPath}: ${error ?? 'unknown error'}`, ''];
+    if (applied.length === 0) {
+        lines.push(`The release was not applied. None of its ${total} files were written.`);
+        return lines.join('\n');
+    }
+    lines.push(`The release was partially applied. ${applied.length} of ${total} files were written:`, ...applied.map((write) => `  ${write.path}`), '', 'Not written:', ...unwritten.map((path) => `  ${path}`), ...describeRecovery(applied));
+    return lines.join('\n');
+}
+function describeRecovery(applied) {
+    const releaseWrites = applied.filter((write) => !HANDOFF_FILES.has(write.path));
+    const replaced = releaseWrites.filter((write) => !write.created).map((write) => write.path);
+    const created = releaseWrites.filter((write) => write.created).map((write) => write.path);
+    if (replaced.length === 0 && created.length === 0) {
+        return [];
+    }
+    const lines = ['', 'Undo the written release files before re-running `release-kit prepare`:'];
+    if (replaced.length > 0) {
+        lines.push(`  git restore ${replaced.join(' ')}`);
+    }
+    if (created.length > 0) {
+        lines.push(`  rm ${created.join(' ')}`);
+    }
+    return lines;
+}

package/dist/esm/releasePrepare.d.ts

@@ -1,9 +1,9 @@
-import type { PrepareResult, ReleaseConfig, ReleaseType } from './types.js';
+import type { ReleasePlan } from './releasePlan.js';
+import type { ReleaseConfig, ReleaseType } from './types.js';
 export interface ReleasePrepareOptions {
-    dryRun: boolean;
     force?: boolean;
     bumpOverride?: ReleaseType;
     setVersion?: string;
     withReleaseNotes?: boolean;
 }
-export declare function releasePrepare(config: ReleaseConfig, options: ReleasePrepareOptions): PrepareResult;
+export declare function releasePrepare(config: ReleaseConfig, options: ReleasePrepareOptions): ReleasePlan;

package/dist/esm/releasePrepare.js

@@ -1,8 +1,8 @@
-import { execSync } from 'node:child_process';
+import { join as joinPath } from 'node:path';
 import { buildChangelogEntries } from "./buildChangelogEntries.js";
 import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
-import { bumpAllVersions, setAllVersions } from "./bumpAllVersions.js";
-import { mergeChangelogEntriesWithDisk, resolveChangelogJsonPath, upsertChangelogJsonAndReturn, } from "./changelogJsonFile.js";
+import { buildReleaseSummary } from "./buildReleaseSummary.js";
+import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyChangelogOverrides, formatStaleOverrideKeyWarning, loadOverridesForScopes, } from "./changelogOverrides.js";
 import { createPolicyViolationCollector } from "./collectPolicyViolations.js";
 import { isForwardVersion } from "./compareVersions.js";
@@ -11,13 +11,15 @@ import { determineBumpFromCommits } from "./determineBumpFromCommits.js";
 import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
 import { hasPrettierConfig } from "./hasPrettierConfig.js";
 import { resolveWorkTypes } from "./loadConfig.js";
+import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
+import { planVersionBump, planVersionSet } from "./planVersionBump.js";
 import { readCurrentVersion } from "./readCurrentVersion.js";
-import { writeChangelogMarkdown } from "./renderChangelogMarkdown.js";
+import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
 import { refreshGitCliffCache } from "./runGitCliff.js";
-import { writeReleaseNotesPreviews } from "./writeReleaseNotesPreviews.js";
 export function releasePrepare(config, options) {
-    const { dryRun, bumpOverride, setVersion, withReleaseNotes } = options;
+    const { bumpOverride, setVersion, withReleaseNotes } = options;
+    const writes = [];
     const workTypes = config.workTypes ?? { ...DEFAULT_WORK_TYPES };
     const versionPatterns = config.versionPatterns ?? { ...DEFAULT_VERSION_PATTERNS };
     const breakingPolicies = config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES;
@@ -45,7 +47,7 @@ export function releasePrepare(config, options) {
             throw new Error(`--set-version ${setVersion} is not greater than current version ${currentVersion}`);
         }
         refreshGitCliffCache();
-        bump = setAllVersions(config.packageFiles, setVersion, dryRun);
+        bump = planVersionSet(config.packageFiles, setVersion);
     }
     else {
         if (bumpOverride === undefined) {
@@ -71,46 +73,37 @@ export function releasePrepare(config, options) {
             return {
                 workspaces: [skipped],
                 tags: [],
-                dryRun,
+                writes: [],
+                summary: '',
+                formatCommand: undefined,
             };
         }
         refreshGitCliffCache();
-        bump = bumpAllVersions(config.packageFiles, releaseType, dryRun);
+        bump = planVersionBump(config.packageFiles, releaseType);
     }
+    writes.push(...bump.writes);
     const newTag = `${config.tagPrefix}${bump.newVersion}`;
     const overrideWarnings = [];
-    const { changelogFiles, changelogJsonFiles } = writeSinglePackageChangelogs({
+    const changelogs = planSinglePackageChangelogs({
         config,
         commits,
         newTag,
         newVersion: bump.newVersion,
-        dryRun,
         overrides,
         overrideWarnings,
     });
-    maybeWriteSinglePackagePreviews(withReleaseNotes === true, config, newTag, changelogJsonFiles[0], dryRun);
+    const { changelogFiles, changelogJsonFiles } = changelogs;
+    const previewWrites = planSinglePackagePreviews(withReleaseNotes === true, config, newTag, changelogs.entries, overrideWarnings);
+    writes.push(...changelogs.writes, ...previewWrites);
     const formatCommandStr = config.formatCommand ?? (hasPrettierConfig() ? 'npx prettier --write' : undefined);
     let formatCommand;
     if (formatCommandStr !== undefined) {
         const modifiedFiles = [
             ...config.packageFiles,
-            ...config.changelogPaths.map((p) => `${p}/CHANGELOG.md`),
+            ...config.changelogPaths.map((changelogPath) => joinPath(changelogPath, 'CHANGELOG.md')),
             ...changelogJsonFiles,
         ];
-        const fullCommand = `${formatCommandStr} ${modifiedFiles.join(' ')}`;
-        if (dryRun) {
-            formatCommand = { command: fullCommand, executed: false, files: modifiedFiles };
-        }
-        else {
-            try {
-                execSync(fullCommand, { stdio: 'inherit' });
-            }
-            catch (error) {
-                const baseMessage = error instanceof Error ? error.message : String(error);
-                throw new Error(`format stage: ${baseMessage} (command: '${fullCommand}')`, { cause: error });
-            }
-            formatCommand = { command: fullCommand, executed: true, files: modifiedFiles };
-        }
+        formatCommand = { command: `${formatCommandStr} ${modifiedFiles.join(' ')}`, files: modifiedFiles };
     }
     const released = buildReleasedSinglePackage({
         commits,
@@ -123,17 +116,19 @@ export function releasePrepare(config, options) {
         unparseableCommits,
         policyViolations: collector.violations.length > 0 ? collector.violations : undefined,
         setVersion,
+        previewFiles: previewWrites.map((write) => write.path),
     });
-    const result = {
+    const plan = {
         workspaces: [released],
         tags: [newTag],
+        writes,
+        summary: buildReleaseSummary({ workspaces: [released] }),
         formatCommand,
-        dryRun,
     };
     if (overrideWarnings.length > 0) {
-        result.warnings = overrideWarnings;
+        plan.warnings = overrideWarnings;
     }
-    return result;
+    return plan;
 }
 function buildSkippedSinglePackage(args) {
     const skipped = {
@@ -163,7 +158,7 @@ function buildReleasedSinglePackage(args) {
         currentVersion: bump.currentVersion,
         newVersion: bump.newVersion,
         tag: newTag,
-        bumpedFiles: bump.files,
+        bumpedFiles: bump.writes.map((write) => write.path),
         changelogFiles,
         commits,
     };
@@ -185,10 +180,13 @@ function buildReleasedSinglePackage(args) {
     if (setVersion !== undefined) {
         released.setVersion = setVersion;
     }
+    if (args.previewFiles.length > 0) {
+        released.previewFiles = args.previewFiles;
+    }
     return released;
 }
-function writeSinglePackageChangelogs(args) {
-    const { config, commits, newTag, newVersion, dryRun, overrides, overrideWarnings } = args;
+function planSinglePackageChangelogs(args) {
+    const { config, commits, newTag, newVersion, overrides, overrideWarnings } = args;
     const isEmptyRange = commits.length === 0;
     const today = new Date().toISOString().slice(0, 10);
     const baseEntries = isEmptyRange
@@ -208,40 +206,41 @@ function writeSinglePackageChangelogs(args) {
     const sectionOrder = deriveSectionOrder(resolveWorkTypes(config.workTypes));
     const changelogFiles = [];
     const changelogJsonFiles = [];
+    const writes = [];
+    let firstMergedEntries = [];
     for (const changelogPath of config.changelogPaths) {
         const jsonPath = resolveChangelogJsonPath(config, changelogPath);
-        const shouldWriteJson = config.changelogJson.enabled && !dryRun;
-        const mergedEntries = shouldWriteJson
-            ? upsertChangelogJsonAndReturn(jsonPath, applied.entries)
-            : mergeChangelogEntriesWithDisk(jsonPath, applied.entries);
+        const mergedEntries = mergeChangelogEntriesWithDisk(jsonPath, applied.entries);
+        if (changelogFiles.length === 0) {
+            firstMergedEntries = mergedEntries;
+        }
         if (config.changelogJson.enabled) {
+            writes.push({ path: jsonPath, content: renderChangelogJson(mergedEntries) });
             changelogJsonFiles.push(jsonPath);
         }
-        changelogFiles.push(writeChangelogMarkdown({
-            changelogPath,
-            entries: mergedEntries,
-            sectionOrder,
-            dryRun,
-        }));
-    }
-    return { changelogFiles, changelogJsonFiles };
+        const changelogFile = joinPath(changelogPath, 'CHANGELOG.md');
+        writes.push({ path: changelogFile, content: renderChangelogMarkdown(mergedEntries, { sectionOrder }) });
+        changelogFiles.push(changelogFile);
+    }
+    return { changelogFiles, changelogJsonFiles, entries: firstMergedEntries, writes };
 }
-function maybeWriteSinglePackagePreviews(withReleaseNotes, config, newTag, changelogJsonPath, dryRun) {
+function planSinglePackagePreviews(withReleaseNotes, config, newTag, entries, warnings) {
     if (!withReleaseNotes) {
-        return;
+        return [];
     }
     if (!config.changelogJson.enabled) {
         console.warn('Warning: --with-release-notes requires changelogJson.enabled; skipping preview generation');
-        return;
+        return [];
     }
-    if (changelogJsonPath === undefined) {
-        return;
+    if (config.changelogPaths.length === 0) {
+        return [];
     }
-    writeReleaseNotesPreviews({
+    const previews = planReleaseNotesPreviews({
         workspacePath: process.cwd(),
         tag: newTag,
-        changelogJsonPath,
+        entries,
         sectionOrder: deriveSectionOrder(resolveWorkTypes(config.workTypes)),
-        dryRun,
     });
+    warnings.push(...previews.warnings);
+    return previews.writes;
 }

package/dist/esm/releasePrepareMono.d.ts

@@ -1,3 +1,4 @@
+import type { ReleasePlan } from './releasePlan.js';
 import type { ReleasePrepareOptions } from './releasePrepare.js';
-import type { MonorepoReleaseConfig, PrepareResult } from './types.js';
-export declare function releasePrepareMono(config: MonorepoReleaseConfig, options: ReleasePrepareOptions): PrepareResult;
+import type { MonorepoReleaseConfig } from './types.js';
+export declare function releasePrepareMono(config: MonorepoReleaseConfig, options: ReleasePrepareOptions): ReleasePlan;