@williamthorsen/release-kit 11.0.0 → 13.0.0

package/dist/esm/publishCommand.js

@@ -4,14 +4,15 @@ import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
 import { configFlagSchema } from "./configFlagSchema.js";
+import { deriveReleaseNotesConfig } from "./deriveReleaseNotesConfig.js";
 import { detectPackageManager } from "./detectPackageManager.js";
 import { formatPrivateSkip } from "./formatPrivateSkip.js";
 import { injectReleaseNotesIntoReadme, resolveReadmePath } from "./injectReleaseNotesIntoReadme.js";
-import { assertConfigUsable } from "./loadValidatedConfig.js";
+import { loadUsableConfig } from "./loadValidatedConfig.js";
 import { parseRequestedTags } from "./parseRequestedTags.js";
 import { publishPackage } from "./publish.js";
 import { resolveCommandTags } from "./resolveCommandTags.js";
-import { resolveReleaseNotesConfig } from "./resolveReleaseNotesConfig.js";
+import { resolveConfigFlag } from "./resolveConfigFlag.js";
 const publishFlagSchema = {
     ...configFlagSchema,
     dryRun: { long: '--dry-run', type: 'boolean' },
@@ -19,10 +20,11 @@ const publishFlagSchema = {
     provenance: { long: '--provenance', type: 'boolean' },
     tags: { long: '--tags', type: 'string' },
 };
-export async function publishCommand(argv, styles) {
+export async function publishCommand(argv, styles, invocationDir) {
     const parsed = parseArgsOrExit(argv, publishFlagSchema);
+    const configPath = resolveConfigFlag(parsed.flags.config, invocationDir);
     const { dryRun, noGitChecks, provenance } = parsed.flags;
-    await assertConfigUsable(styles.stderr, parsed.flags.config);
+    const userConfig = await loadUsableConfig(styles.stderr, configPath);
     if (!dryRun && !noGitChecks) {
         try {
             assertCleanWorkingTree();
@@ -33,7 +35,7 @@ export async function publishCommand(argv, styles) {
         }
     }
     const requestedTags = parseRequestedTags(parsed.flags.tags);
-    const resolvedTags = resolveCommandTags(requestedTags);
+    const resolvedTags = resolveCommandTags(requestedTags, userConfig);
     if (resolvedTags.length === 0) {
         return;
     }
@@ -43,9 +45,7 @@ export async function publishCommand(argv, styles) {
         return;
     }
     const packageManager = detectPackageManager();
-    const { releaseNotes, changelogJsonOutputPath, sectionOrder } = await resolveReleaseNotesConfig(styles.stderr, {
-        ...(parsed.flags.config !== undefined && { configPath: parsed.flags.config }),
-    });
+    const { releaseNotes, changelogJsonOutputPath, sectionOrder } = deriveReleaseNotesConfig(userConfig);
     const shouldInject = releaseNotes.shouldInjectIntoReadme;
     console.info(dryRun ? '[dry-run] Would publish:' : 'Publishing:');
     for (const { tag, workspacePath } of publishableTags) {

package/dist/esm/pushCommand.d.ts

@@ -1,5 +1,6 @@
+import { type StreamStyles } from '@williamthorsen/nmr-core';
 /**
- * Orchestrate the CLI `push` command: parse flags, resolve tags from HEAD, and push
- * the release commit and each tag individually.
+ * Orchestrates the CLI `push` command: parses flags, loads the config, resolves tags from HEAD, and pushes
+ * the release commit and each tag individually. A relative `--config` resolves against `invocationDir`.
  */
-export declare function pushCommand(argv: string[]): void;
+export declare function pushCommand(argv: string[], styles: StreamStyles, invocationDir: string): Promise<void>;

package/dist/esm/pushCommand.js

@@ -1,18 +1,24 @@
 import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { configFlagSchema } from "./configFlagSchema.js";
+import { loadUsableConfig } from "./loadValidatedConfig.js";
 import { parseRequestedTags } from "./parseRequestedTags.js";
 import { pushRelease } from "./pushRelease.js";
 import { resolveCommandTags } from "./resolveCommandTags.js";
+import { resolveConfigFlag } from "./resolveConfigFlag.js";
 const pushFlagSchema = {
+    ...configFlagSchema,
     dryRun: { long: '--dry-run', type: 'boolean' },
     tags: { long: '--tags', type: 'string' },
     tagsOnly: { long: '--tags-only', type: 'boolean' },
 };
-export function pushCommand(argv) {
+export async function pushCommand(argv, styles, invocationDir) {
     const parsed = parseArgsOrExit(argv, pushFlagSchema);
+    const configPath = resolveConfigFlag(parsed.flags.config, invocationDir);
     const { dryRun, tagsOnly } = parsed.flags;
+    const userConfig = await loadUsableConfig(styles.stderr, configPath);
     const requestedTags = parseRequestedTags(parsed.flags.tags);
-    const resolvedTags = resolveCommandTags(requestedTags);
+    const resolvedTags = resolveCommandTags(requestedTags, userConfig);
     if (resolvedTags.length === 0) {
         return;
     }

package/dist/esm/pushRelease.d.ts

@@ -9,9 +9,9 @@ export interface PushStep {
     command: readonly [string, ...string[]];
 }
 /**
- * Push the release commit and each tag individually so that GitHub Actions fires
+ * Pushes the release commit and each tag individually so that GitHub Actions fires
  * a separate workflow run per tag.
  *
- * Returns the list of push steps that were executed (or would be executed in dry-run mode).
+ * Returns the push steps, which it runs only outside dry-run mode.
  */
 export declare function pushRelease(resolvedTags: ResolvedTag[], options?: PushReleaseOptions): PushStep[];

package/dist/esm/readChangelogSections.d.ts

@@ -0,0 +1,33 @@
+import type { ChangelogEntry, ChangelogPreservation } from './types.js';
+/** A `##` section of a `CHANGELOG.md` whose heading names a version. */
+export interface VersionedMarkdownSection {
+    version: string;
+    /** The section as written, heading included, with trailing blank lines trimmed. */
+    text: string;
+}
+/** The `##` sections of a `CHANGELOG.md`, split by whether their heading names a version. */
+export interface ChangelogMarkdownSections {
+    versioned: VersionedMarkdownSection[];
+    /** Headings of the `##` sections that do not name a version, as written. */
+    unversionedHeadings: string[];
+}
+/**
+ * Plans which sections of the existing `CHANGELOG.md` at `changelogFile` to keep when the file is regenerated from
+ * `entries`: every versioned section whose version matches none of the entries. Also returns what to report about the
+ * file, or undefined when nothing was kept and nothing was dropped.
+ */
+export declare function planPreservedSections(changelogFile: string, entries: readonly ChangelogEntry[]): {
+    sections: VersionedMarkdownSection[];
+    preservation: ChangelogPreservation | undefined;
+};
+/**
+ * Reads the `##` sections of the `CHANGELOG.md` at `filePath`, excluding the header above the first section and the
+ * release-kit footer comment. For a missing file, returns empty section lists.
+ */
+export declare function readChangelogSections(filePath: string): ChangelogMarkdownSections;
+/**
+ * Splits `CHANGELOG.md` content at its `##` headings. A section runs to the next `##` heading or the release-kit
+ * footer comment; `###` and deeper headings, and any heading inside a fenced code block, belong to the enclosing
+ * section.
+ */
+export declare function parseChangelogSections(content: string): ChangelogMarkdownSections;

package/dist/esm/readChangelogSections.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import semver from 'semver';
+export function planPreservedSections(changelogFile, entries) {
+    const { versioned, unversionedHeadings } = readChangelogSections(changelogFile);
+    const renderedVersions = new Set(entries.map((entry) => entry.version));
+    const sections = versioned.filter((section) => !renderedVersions.has(section.version));
+    if (sections.length === 0 && unversionedHeadings.length === 0) {
+        return { sections, preservation: undefined };
+    }
+    return {
+        sections,
+        preservation: {
+            file: changelogFile,
+            preservedVersions: sections.map((section) => section.version),
+            droppedUnversionedHeadings: unversionedHeadings,
+        },
+    };
+}
+export function readChangelogSections(filePath) {
+    if (!existsSync(filePath)) {
+        return { versioned: [], unversionedHeadings: [] };
+    }
+    return parseChangelogSections(readFileSync(filePath, 'utf8'));
+}
+export function parseChangelogSections(content) {
+    const sections = [];
+    let current;
+    let fence;
+    for (const line of content.split(/\r?\n/)) {
+        if (fence === undefined) {
+            if (FOOTER_PATTERN.test(line)) {
+                current = undefined;
+                continue;
+            }
+            if (SECTION_HEADING_PATTERN.test(line)) {
+                current = { heading: line.trimEnd(), lines: [] };
+                sections.push(current);
+            }
+        }
+        fence = updateFence(fence, line);
+        current?.lines.push(line);
+    }
+    const versioned = [];
+    const unversionedHeadings = [];
+    for (const { heading, lines } of sections) {
+        const version = extractHeadingVersion(heading);
+        if (version === undefined) {
+            unversionedHeadings.push(heading);
+        }
+        else {
+            versioned.push({ version, text: trimTrailingBlankLines(lines).join('\n') });
+        }
+    }
+    return { versioned, unversionedHeadings };
+}
+const FOOTER_PATTERN = /^<!-- Generated by release-kit\b/;
+const SECTION_HEADING_PATTERN = /^## /;
+const FENCE_PATTERN = /^ {0,3}(`{3,}|~{3,})/;
+const HEADING_VERSION_PATTERN = /(?<![\w.])v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)(?!\.?\d)/;
+function extractHeadingVersion(heading) {
+    const token = HEADING_VERSION_PATTERN.exec(heading)?.[1];
+    if (token === undefined)
+        return undefined;
+    return semver.valid(token) ?? undefined;
+}
+function trimTrailingBlankLines(lines) {
+    let end = lines.length;
+    while (end > 0 && lines[end - 1]?.trim() === '') {
+        end--;
+    }
+    return lines.slice(0, end);
+}
+function updateFence(fence, line) {
+    const marker = FENCE_PATTERN.exec(line)?.[1];
+    if (marker === undefined)
+        return fence;
+    if (fence === undefined)
+        return marker;
+    return marker[0] === fence[0] && marker.length >= fence.length ? undefined : fence;
+}

package/dist/esm/releaseFiles.d.ts

@@ -1,14 +1,14 @@
 /**
  * File written by the release preparation step, containing one tag per line.
  *
- * Relative to the project root so it works identically in CI and local runs. The reusable
+ * Relative to the project root so that it works identically in CI and local runs. The reusable
  * release workflow reads it at this path, so the path and the line-delimited format are a
- * published contract rather than an internal detail.
+ * published contract.
  */
 export declare const RELEASE_TAGS_FILE = "tmp/.release-tags";
 /**
  * File written by the release preparation step, containing the commit body summary.
- * Relative to the project root so it works identically in CI and local runs.
+ * Relative to the project root so that it works identically in CI and local runs.
  */
 export declare const RELEASE_SUMMARY_FILE = "tmp/.release-summary";
 /** Resolves the tags file against the current working directory, for use in diagnostics. */
@@ -16,10 +16,8 @@ export declare function resolveReleaseTagsPath(): string;
 /**
  * Reads the tag names written by `prepare`, one per line, discarding blank lines.
  *
- * Both consumers — `commit` and `tag` — share this reader so their diagnostics cannot drift.
- * Failure messages name the path as resolved against `process.cwd()`, which is what separates
- * a genuinely absent file from one the command looked for under a different worktree, and
- * they preserve the underlying errno instead of reporting every failure as a missing file.
+ * A failure message names the path as resolved against `process.cwd()`, which distinguishes an
+ * absent file from one that the command looked for under a different worktree.
  *
  * An empty or blank file yields an empty array; callers decide whether that is an error.
  */

package/dist/esm/releasePlan.d.ts

@@ -1,5 +1,5 @@
 import type { PrepareResult } from './types.js';
-/** One file a release will write, carried as its complete intended content. */
+/** One file that a release will write, with its complete intended content. */
 export interface PlannedWrite {
     path: string;
     content: string;
@@ -7,12 +7,11 @@ export interface PlannedWrite {
 /**
  * A release computed in full but not yet written.
  *
- * Holding every intended file up front is what lets `prepare` fail during computation without
- * leaving anything on disk. {@link applyReleasePlan} is the only step that mutates the tree, so
- * a dry run is this same plan with the apply step skipped rather than a separate code path.
+ * Because the plan contains every intended file up front, `prepare` can fail during computation
+ * without leaving anything on disk. {@link applyReleasePlan} is the only step that mutates the
+ * tree, so a dry run is this same plan with the apply step skipped.
  *
- * Extends the reporting view with the two fields only the apply step needs, so `reportPrepare`
- * can render a plan without knowing about file content.
+ * Extends the reporting view with the two fields that only the apply step reads.
  */
 export interface ReleasePlan extends PrepareResult {
     writes: readonly PlannedWrite[];
@@ -20,14 +19,13 @@ export interface ReleasePlan extends PrepareResult {
     summary: string;
 }
 /**
- * Writes every file a plan describes: content files first, then the summary, then the tags file.
+ * Writes every file that a plan describes: content files first, then the summary, then the tags file.
  *
- * The tags file goes last so its presence means the whole plan landed. Both `release-kit commit`
- * and the reusable release workflow read it as the signal that a release is ready to commit, so
- * writing it earlier would let a failure produce a tree that claims to be releasable.
+ * The tags file goes last so that its presence means that the whole plan was written to disk.
+ * Both `release-kit commit` and the reusable release workflow read it as the signal that a
+ * release is ready to commit, so writing it earlier would let a failure produce a tree that
+ * looks releasable.
  *
- * Returns the paths written, in order.
- *
- * @throws If any write fails, naming what reached disk and what did not.
+ * Returns the paths written, in order. Throws if any write fails, naming what was written and what was not.
  */
 export declare function applyReleasePlan(plan: ReleasePlan): string[];

package/dist/esm/releasePrepare.d.ts

@@ -1,19 +1,13 @@
 import type { ReleasePlan } from './releasePlan.js';
-import type { ReleaseConfig, ReleaseType } from './types.js';
-/**
- * Options for the release preparation workflow.
- *
- * Carries no dry-run flag: preparation only ever computes a plan, and whether that plan is
- * applied is the caller's decision.
- */
+import type { PrepareConfig, ReleaseType } from './types.js';
+/** Options for the release preparation workflow. */
 export interface ReleasePrepareOptions {
     /**
-     * Release even when no commits or no bump-worthy commits exist since the last tag
-     * (monorepo only). Orthogonal to `bumpOverride`: when `bumpOverride` is not given,
-     * the release falls back to `patch`.
+     * Release even when the range since the last tag doesn't contain any commits or any bump-worthy commits.
+     * Orthogonal to `bumpOverride`: When `bumpOverride` is not given, the release falls back to `patch`.
      */
     force?: boolean;
-    /** Override the bump type instead of determining it from commits. */
+    /** Level of the release, in place of the level that the changelog items call for; it doesn't trigger a release. */
     bumpOverride?: ReleaseType;
     /**
      * Explicit target version (canonical `N.N.N`) that bypasses commit-derived bump logic.
@@ -22,29 +16,35 @@ export interface ReleasePrepareOptions {
      */
     setVersion?: string;
     /**
-     * Workspace directories the run was narrowed to by `--only` (monorepo only), with
+     * Workspace directories to which `--only` narrowed the run (monorepo only), with
      * `config.workspaces` already filtered to match. Present only for a narrowed run, which
-     * skips the project release: the project tier rolls up every contributing workspace, and
+     * skips the project release: The project tier rolls up every contributing workspace, and
      * the narrowing has changed which workspaces those are.
      */
     only?: string[];
     /**
-     * If true, write per-workspace release-notes previews under `{workspacePath}/docs/`
-     * (`README.v{version}.md` and `RELEASE_NOTES.v{version}.md`) after each workspace's
-     * `changelog.json` is produced. Requires `config.changelogJson.enabled`; when disabled,
-     * a warning is recorded on the plan and no previews are generated.
+     * Every configured workspace `dir`, taken before `--only` narrowed `config.workspaces`; the unrouted-scope report
+     * does not report a scope naming one of them that the run did not read. Defaults to the `dir`s of
+     * `config.workspaces`.
+     */
+    configuredWorkspaceDirs?: readonly string[];
+    /**
+     * If true, plan per-workspace release-notes previews under `{workspacePath}/docs/`
+     * (`README.v{version}.md` and `RELEASE_NOTES.v{version}.md`) from each workspace's
+     * changelog entries. Requires `config.changelogJson.enabled`; when disabled,
+     * the planner records a warning on the plan and doesn't plan any previews.
      */
     withReleaseNotes?: boolean;
 }
 /**
- * Orchestrate the release preparation workflow for a single package.
+ * Orchestrates the release preparation workflow for a single package.
  *
- * 1. Gets commits since the last tag.
- * 2. Determines the bump type from commits (or uses the override).
- * 3. Bumps all configured package.json version fields.
- * 4. Generates changelogs via git-cliff.
- * 5. Runs the optional format command.
+ * 1. Reads the release history once, and stops when the current version is recorded but untagged.
+ * 2. Decides the release from the history's bump, `--force`, and `--bump` (or takes `--set-version`).
+ * 3. Plans the bump of every configured `package.json` version field.
+ * 4. Plans the changelogs from the same history, and the release-notes previews when requested.
+ * 5. Renders the optional format command.
  *
- * Returns a structured `PrepareResult` with all data needed for presentation.
+ * Returns the plan without writing any file.
  */
-export declare function releasePrepare(config: ReleaseConfig, options: ReleasePrepareOptions): ReleasePlan;
+export declare function releasePrepare(config: PrepareConfig, options: ReleasePrepareOptions): ReleasePlan;

package/dist/esm/releasePrepare.js

@@ -1,60 +1,54 @@
 import { join as joinPath } from 'node:path';
-import { buildChangelogEntries } from "./buildChangelogEntries.js";
-import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
+import { assertTaggedBaseline, findUntaggedBaseline } from "./assertTaggedBaseline.js";
+import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
+import { readReleaseHistory, toReleaseEntries } from "./buildChangelogEntries.js";
 import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyChangelogOverrides, formatStaleOverrideKeyWarning, loadOverridesForScopes, } from "./changelogOverrides.js";
-import { createPolicyViolationCollector } from "./collectPolicyViolations.js";
-import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
-import { determineBumpFromCommits } from "./determineBumpFromCommits.js";
-import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
+import { decideRelease } from "./decideRelease.js";
+import { deriveSectionOrder } from "./deriveReleaseNotesConfig.js";
 import { hasPrettierConfig } from "./hasPrettierConfig.js";
 import { resolveWorkTypes } from "./loadConfig.js";
 import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
 import { planVersionBump, planVersionSet } from "./planVersionBump.js";
+import { planPreservedSections } from "./readChangelogSections.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
-import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
 export function releasePrepare(config, options) {
-    const { bumpOverride, setVersion, withReleaseNotes } = options;
+    const { bumpOverride, force, 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;
     const overridesResult = loadOverridesForScopes({ project: '.' });
     if (overridesResult.errors.length > 0) {
         throw new Error(`Failed to load changelog overrides:\n  - ${overridesResult.errors.join('\n  - ')}`);
     }
     const overrides = overridesResult.project;
-    const { tag, commits } = getCommitsSinceTarget([config.tagPrefix]);
+    const history = readReleaseHistory(config, { tagPrefixes: [config.tagPrefix] });
+    assertTaggedBaseline([
+        findUntaggedBaseline({
+            label: 'package',
+            packageFiles: config.packageFiles,
+            changelogPaths: config.changelogPaths,
+            tagPrefixes: [config.tagPrefix],
+            previousTag: history.previousTag,
+        }, config),
+    ]);
+    const { commits } = history.unreleased;
+    const tag = history.previousTag;
+    const since = tag === undefined ? '(no previous release found)' : `since ${tag}`;
     let releaseType;
-    let parsedCommitCount;
-    let unparseableCommits;
-    const collector = createPolicyViolationCollector();
     let bump;
-    if (setVersion !== undefined) {
-        bump = planVersionSet(config.packageFiles, setVersion);
-    }
-    else {
-        if (bumpOverride === undefined) {
-            const determination = determineBumpFromCommits(commits, workTypes, versionPatterns, config.scopeAliases, {
-                breakingPolicies,
-                onPolicyViolation: collector.onPolicyViolation,
-            });
-            parsedCommitCount = determination.parsedCommitCount;
-            unparseableCommits = determination.unparseableCommits;
-            releaseType = determination.releaseType;
-        }
-        else {
-            releaseType = bumpOverride;
-        }
-        if (releaseType === undefined) {
-            const skipped = buildSkippedSinglePackage({
-                commitCount: commits.length,
-                previousTag: tag,
-                parsedCommitCount,
-                unparseableCommits,
-                policyViolations: collector.violations.length > 0 ? collector.violations : undefined,
-            });
+    if (setVersion === undefined) {
+        const decision = decideRelease({
+            naturalBump: history.unreleased.bump,
+            commitCount: commits.length,
+            force,
+            bumpOverride,
+            skipReasons: {
+                noCommits: `No commits ${since}. Pass --force to release at patch. Skipping.`,
+                noBumpWorthy: `No bump-worthy commits ${since}. Pass --force to release at patch (or --force --bump=X for a different level). Skipping.`,
+            },
+        });
+        if (decision.outcome === 'skip') {
+            const skipped = buildSkippedSinglePackage(history, decision.skipReason);
             return {
                 workspaces: [skipped],
                 tags: [],
@@ -63,20 +57,23 @@ export function releasePrepare(config, options) {
                 formatCommand: undefined,
             };
         }
+        releaseType = decision.releaseType;
         bump = planVersionBump(config.packageFiles, releaseType);
     }
+    else {
+        bump = planVersionSet(config.packageFiles, setVersion);
+    }
     writes.push(...bump.writes);
     const newTag = `${config.tagPrefix}${bump.newVersion}`;
     const planWarnings = [];
     const changelogs = planSinglePackageChangelogs({
         config,
-        commits,
+        history,
         newTag,
-        newVersion: bump.newVersion,
         overrides,
         overrideWarnings: planWarnings,
     });
-    const { changelogFiles, changelogJsonFiles } = changelogs;
+    const { changelogFiles, changelogJsonFiles, changelogPreservation } = changelogs;
     const previewWrites = planSinglePackagePreviews(withReleaseNotes === true, config, newTag, changelogs.entries, planWarnings);
     writes.push(...changelogs.writes, ...previewWrites);
     const formatCommandStr = config.formatCommand ?? (hasPrettierConfig() ? 'npx prettier --write' : undefined);
@@ -90,15 +87,13 @@ export function releasePrepare(config, options) {
         formatCommand = { command: `${formatCommandStr} ${modifiedFiles.join(' ')}`, files: modifiedFiles };
     }
     const released = buildReleasedSinglePackage({
-        commits,
+        history,
         bump,
         newTag,
         changelogFiles,
-        previousTag: tag,
-        parsedCommitCount,
+        changelogPreservation,
         releaseType,
-        unparseableCommits,
-        policyViolations: collector.violations.length > 0 ? collector.violations : undefined,
+        bumpOverride: setVersion === undefined ? bumpOverride : undefined,
         setVersion,
         previewFiles: previewWrites.map((write) => write.path),
     });
@@ -114,28 +109,26 @@ export function releasePrepare(config, options) {
     }
     return plan;
 }
-function buildSkippedSinglePackage(args) {
+function buildSkippedSinglePackage(history, skipReason) {
+    const { unreleased } = history;
     const skipped = {
         status: 'skipped',
-        commitCount: args.commitCount,
-        skipReason: 'No release-worthy changes found. Skipping.',
+        commitCount: unreleased.commits.length,
+        parsedCommitCount: unreleased.parsedCommitCount,
+        skipReason,
     };
-    if (args.previousTag !== undefined) {
-        skipped.previousTag = args.previousTag;
-    }
-    if (args.parsedCommitCount !== undefined) {
-        skipped.parsedCommitCount = args.parsedCommitCount;
-    }
-    if (args.unparseableCommits !== undefined) {
-        skipped.unparseableCommits = args.unparseableCommits;
+    if (history.previousTag !== undefined) {
+        skipped.previousTag = history.previousTag;
     }
-    if (args.policyViolations !== undefined) {
-        skipped.policyViolations = args.policyViolations;
+    if (unreleased.unparseableCommits !== undefined) {
+        skipped.unparseableCommits = unreleased.unparseableCommits;
     }
+    attachChangelogDiagnostics(skipped, unreleased.diagnostics);
     return skipped;
 }
 function buildReleasedSinglePackage(args) {
-    const { commits, bump, newTag, changelogFiles, previousTag, parsedCommitCount, releaseType, unparseableCommits, policyViolations, setVersion, } = args;
+    const { history, bump, newTag, changelogFiles, releaseType, bumpOverride, setVersion } = args;
+    const { commits, diagnostics, parsedCommitCount, unparseableCommits } = history.unreleased;
     const released = {
         status: 'released',
         commitCount: commits.length,
@@ -146,37 +139,36 @@ function buildReleasedSinglePackage(args) {
         changelogFiles,
         commits,
     };
-    if (previousTag !== undefined) {
-        released.previousTag = previousTag;
-    }
-    if (parsedCommitCount !== undefined) {
-        released.parsedCommitCount = parsedCommitCount;
+    if (history.previousTag !== undefined) {
+        released.previousTag = history.previousTag;
     }
     if (releaseType !== undefined) {
         released.releaseType = releaseType;
+        released.parsedCommitCount = parsedCommitCount;
+        if (unparseableCommits !== undefined) {
+            released.unparseableCommits = unparseableCommits;
+        }
     }
-    if (unparseableCommits !== undefined) {
-        released.unparseableCommits = unparseableCommits;
-    }
-    if (policyViolations !== undefined) {
-        released.policyViolations = policyViolations;
+    if (bumpOverride !== undefined) {
+        released.bumpOverride = bumpOverride;
     }
+    attachChangelogDiagnostics(released, diagnostics);
     if (setVersion !== undefined) {
         released.setVersion = setVersion;
     }
     if (args.previewFiles.length > 0) {
         released.previewFiles = args.previewFiles;
     }
+    if (args.changelogPreservation.length > 0) {
+        released.changelogPreservation = args.changelogPreservation;
+    }
     return released;
 }
 function planSinglePackageChangelogs(args) {
-    const { config, commits, newTag, newVersion, overrides, overrideWarnings } = args;
-    const isEmptyRange = commits.length === 0;
+    const { config, history, newTag, overrides, overrideWarnings } = args;
     const today = new Date().toISOString().slice(0, 10);
-    const baseEntries = isEmptyRange
-        ? [buildEmptyReleaseEntry(newVersion, today)]
-        : buildChangelogEntries(config, newTag);
-    const applied = applyChangelogOverrides(baseEntries, overrides);
+    const builtEntries = toReleaseEntries(history, newTag, today);
+    const applied = applyChangelogOverrides(builtEntries, overrides);
     if (applied.errors.length > 0) {
         throw new Error(`Changelog override application failed:\n  - ${applied.errors.join('\n  - ')}`);
     }
@@ -190,6 +182,7 @@ function planSinglePackageChangelogs(args) {
     const sectionOrder = deriveSectionOrder(resolveWorkTypes(config.workTypes));
     const changelogFiles = [];
     const changelogJsonFiles = [];
+    const changelogPreservation = [];
     const writes = [];
     let firstMergedEntries = [];
     for (const changelogPath of config.changelogPaths) {
@@ -203,10 +196,17 @@ function planSinglePackageChangelogs(args) {
             changelogJsonFiles.push(jsonPath);
         }
         const changelogFile = joinPath(changelogPath, 'CHANGELOG.md');
-        writes.push({ path: changelogFile, content: renderChangelogMarkdown(mergedEntries, { sectionOrder }) });
+        const preserved = planPreservedSections(changelogFile, mergedEntries);
+        writes.push({
+            path: changelogFile,
+            content: renderChangelogMarkdown(mergedEntries, { sectionOrder, preservedSections: preserved.sections }),
+        });
         changelogFiles.push(changelogFile);
+        if (preserved.preservation !== undefined) {
+            changelogPreservation.push(preserved.preservation);
+        }
     }
-    return { changelogFiles, changelogJsonFiles, entries: firstMergedEntries, writes };
+    return { changelogFiles, changelogJsonFiles, changelogPreservation, entries: firstMergedEntries, writes };
 }
 function planSinglePackagePreviews(withReleaseNotes, config, newTag, entries, warnings) {
     if (!withReleaseNotes) {
@@ -220,7 +220,7 @@ function planSinglePackagePreviews(withReleaseNotes, config, newTag, entries, wa
         return [];
     }
     const previews = planReleaseNotesPreviews({
-        workspacePath: process.cwd(),
+        workspacePath: '.',
         tag: newTag,
         entries,
         sectionOrder: deriveSectionOrder(resolveWorkTypes(config.workTypes)),