@williamthorsen/release-kit 12.0.0 → 13.0.0

package/dist/esm/releasePrepare.js

@@ -1,17 +1,18 @@
 import { join as joinPath } from 'node:path';
+import { assertTaggedBaseline, findUntaggedBaseline } from "./assertTaggedBaseline.js";
 import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
-import { readReleaseHistory, toChangelogEntries } from "./buildChangelogEntries.js";
-import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
+import { readReleaseHistory, toReleaseEntries } from "./buildChangelogEntries.js";
 import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyChangelogOverrides, formatStaleOverrideKeyWarning, loadOverridesForScopes, } from "./changelogOverrides.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, force, setVersion, withReleaseNotes } = options;
     const writes = [];
@@ -21,6 +22,15 @@ export function releasePrepare(config, options) {
     }
     const overrides = overridesResult.project;
     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}`;
@@ -60,11 +70,10 @@ export function releasePrepare(config, options) {
         config,
         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);
@@ -82,6 +91,7 @@ export function releasePrepare(config, options) {
         bump,
         newTag,
         changelogFiles,
+        changelogPreservation,
         releaseType,
         bumpOverride: setVersion === undefined ? bumpOverride : undefined,
         setVersion,
@@ -149,13 +159,15 @@ function buildReleasedSinglePackage(args) {
     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, history, newTag, newVersion, overrides, overrideWarnings } = args;
-    const isEmptyRange = history.unreleased.commits.length === 0;
+    const { config, history, newTag, overrides, overrideWarnings } = args;
     const today = new Date().toISOString().slice(0, 10);
-    const builtEntries = isEmptyRange ? [buildEmptyReleaseEntry(newVersion, today)] : toChangelogEntries(history, newTag);
+    const builtEntries = toReleaseEntries(history, newTag, today);
     const applied = applyChangelogOverrides(builtEntries, overrides);
     if (applied.errors.length > 0) {
         throw new Error(`Changelog override application failed:\n  - ${applied.errors.join('\n  - ')}`);
@@ -170,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) {
@@ -183,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) {
@@ -200,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)),

package/dist/esm/releasePrepareMono.d.ts

@@ -1,12 +1,14 @@
 import type { ReleasePlan } from './releasePlan.js';
 import type { ReleasePrepareOptions } from './releasePrepare.js';
-import type { MonorepoReleaseConfig } from './types.js';
+import type { MonorepoPrepareConfig } from './types.js';
 /**
- * Orchestrate release preparation for a monorepo with multiple workspaces.
+ * Orchestrates release preparation for a monorepo with multiple workspaces.
  *
- * Phase 1: Determine direct bumps from commits for each workspace.
- * Phase 2: Build the dependency graph and propagate bumps to dependents.
- * Phase 2b: Topologically sort the full release set.
- * Phase 3: Execute bumps and generate changelogs in dependency order.
+ * Phase 1: Determines direct bumps from commits for each workspace.
+ * Phase 2: Builds the dependency graph and propagates bumps to dependents.
+ * Phase 2b: Sorts the full release set topologically.
+ * Phase 3: Plans bumps and changelogs in dependency order.
+ * Phase 3b: Plans the project release.
+ * Phase 4: Renders the format command.
  */
-export declare function releasePrepareMono(config: MonorepoReleaseConfig, options: ReleasePrepareOptions): ReleasePlan;
+export declare function releasePrepareMono(config: MonorepoPrepareConfig, options: ReleasePrepareOptions): ReleasePlan;

package/dist/esm/releasePrepareMono.js

@@ -1,24 +1,26 @@
 import { join as joinPath } from 'node:path';
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
+import { assertTaggedBaseline, findUntaggedBaseline } from "./assertTaggedBaseline.js";
 import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
-import { readReleaseHistory, toChangelogEntries } from "./buildChangelogEntries.js";
+import { readReleaseHistory, toReleaseEntries } from "./buildChangelogEntries.js";
 import { buildDependencyGraph } from "./buildDependencyGraph.js";
-import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
 import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { buildSyntheticChangelogEntry } from "./buildSyntheticChangelogEntry.js";
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyWorkspaceOverrides, createOverrideContext, formatStaleOverrideKeyWarning, } from "./changelogOverrides.js";
 import { decideRelease } from "./decideRelease.js";
+import { deriveDependenciesHeader, deriveSectionOrder } from "./deriveReleaseNotesConfig.js";
 import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
+import { findUnroutedEntryScopes } from "./findUnroutedEntryScopes.js";
 import { getAllTagPrefixes } from "./generateChangelogs.js";
 import { hasPrettierConfig } from "./hasPrettierConfig.js";
 import { resolveWorkTypes } from "./loadConfig.js";
 import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
 import { planVersionBump, planVersionSet } from "./planVersionBump.js";
 import { propagateBumps } from "./propagateBumps.js";
+import { planPreservedSections } from "./readChangelogSections.js";
 import { releasePrepareProject } from "./releasePrepareProject.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
-import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
 export function releasePrepareMono(config, options) {
     const { only, withReleaseNotes } = options;
     const writes = [];
@@ -26,18 +28,18 @@ export function releasePrepareMono(config, options) {
     if (withReleaseNotes === true && !config.changelogJson.enabled) {
         warnings.push('--with-release-notes requires changelogJson.enabled; skipping preview generation');
     }
-    const sectionOrder = deriveSectionOrder(resolveWorkTypes(config.workTypes));
+    const workTypes = resolveWorkTypes(config.workTypes);
+    const sectionOrder = deriveSectionOrder(workTypes);
+    const dependenciesHeader = deriveDependenciesHeader(workTypes);
     const overrideContext = createOverrideContext(config.workspaces);
-    const { directBumps, directResults, skippedResults } = determineDirectBumps(config, options);
-    const previousTags = new Map();
-    for (const result of directResults.values()) {
-        previousTags.set(result.workspace.dir, result.history.previousTag);
-    }
-    for (const skipped of skippedResults) {
-        previousTags.set(skipped.workspace.dir, skipped.history.previousTag);
-    }
+    const { directBumps, directResults, skippedResults, untaggedBaselines } = determineDirectBumps(config, options);
+    reportUnroutedEntryScopes([...directResults.values(), ...skippedResults], config, options);
+    const skippedHistories = new Map(skippedResults.map((skipped) => [skipped.workspace.dir, skipped.history]));
     const graph = buildDependencyGraph(config.workspaces);
     const fullReleaseSet = propagateBumps(directBumps, graph);
+    assertTaggedBaseline([...untaggedBaselines]
+        .filter(([dir]) => directBumps.has(dir) || !fullReleaseSet.has(dir))
+        .map(([, untagged]) => untagged));
     const { sorted: sortedDirs, cyclicDirs } = topologicalSort(fullReleaseSet, graph);
     if (cyclicDirs.length > 0) {
         warnings.push(`Circular workspace dependencies detected among: ${cyclicDirs.join(', ')}. ` +
@@ -53,13 +55,14 @@ export function releasePrepareMono(config, options) {
         fullReleaseSet,
         config,
         directResults,
-        previousTags,
+        skippedHistories,
         writes,
         warnings,
         workspaces,
         previewOptions,
         overrideContext,
         sectionOrder,
+        dependenciesHeader,
     });
     const configOrder = new Map(config.workspaces.map((w, i) => [w.dir, i]));
     workspaces.sort((a, b) => {
@@ -112,12 +115,24 @@ function determineDirectBumps(config, options) {
     const directBumps = new Map();
     const directResults = new Map();
     const skippedResults = [];
+    const untaggedBaselines = new Map();
     const hintState = { emitted: false };
     const knownPrefixes = config.workspaces.flatMap(getAllTagPrefixes);
     for (const workspace of config.workspaces) {
         const name = workspace.dir;
         const stageLabel = workspaceStageLabel(workspace.dir);
-        const history = tryStage(stageLabel, () => readReleaseHistory(config, { tagPrefixes: getAllTagPrefixes(workspace), paths: workspace.paths }));
+        const tagPrefixes = getAllTagPrefixes(workspace);
+        const history = tryStage(stageLabel, () => readReleaseHistory(config, { tagPrefixes, paths: workspace.paths, workspaceDir: workspace.dir }));
+        const untagged = tryStage(stageLabel, () => findUntaggedBaseline({
+            label: `workspace '${workspace.dir}'`,
+            packageFiles: workspace.packageFiles,
+            changelogPaths: workspace.changelogPaths,
+            tagPrefixes,
+            previousTag: history.previousTag,
+        }, config));
+        if (untagged !== undefined) {
+            untaggedBaselines.set(workspace.dir, untagged);
+        }
         const tag = history.previousTag;
         const since = tag === undefined ? '(no previous release found)' : `since ${tag}`;
         if (tag === undefined) {
@@ -156,7 +171,13 @@ function determineDirectBumps(config, options) {
             bumpOverride,
         });
     }
-    return { directBumps, directResults, skippedResults };
+    return { directBumps, directResults, skippedResults, untaggedBaselines };
+}
+function reportUnroutedEntryScopes(results, config, options) {
+    const findings = findUnroutedEntryScopes(results.map(({ workspace, history }) => ({ dir: workspace.dir, commits: history.unreleased.commits })), options.configuredWorkspaceDirs ?? config.workspaces.map((workspace) => workspace.dir), config.scopeAliases ?? {});
+    for (const { workspace, history } of results) {
+        history.unreleased.diagnostics.unroutedEntryScopes = findings.get(workspace.dir) ?? [];
+    }
 }
 function collectSkippedWorkspaces(skippedResults, fullReleaseSet) {
     const workspaces = [];
@@ -184,7 +205,7 @@ function collectSkippedWorkspaces(skippedResults, fullReleaseSet) {
     return workspaces;
 }
 function executeReleaseSet(args) {
-    const { sortedDirs, fullReleaseSet, config, directResults, previousTags, writes, warnings, workspaces, previewOptions, overrideContext, sectionOrder, } = args;
+    const { sortedDirs, fullReleaseSet, config, directResults, skippedHistories, writes, warnings, workspaces, previewOptions, overrideContext, sectionOrder, dependenciesHeader, } = args;
     const tags = [];
     const modifiedFiles = [];
     const today = new Date().toISOString().slice(0, 10);
@@ -202,7 +223,7 @@ function executeReleaseSet(args) {
             workspace,
             releaseEntry,
             directResult: directResults.get(dir),
-            previousTags,
+            skippedHistory: skippedHistories.get(dir),
             config,
             today,
             tags,
@@ -213,12 +234,13 @@ function executeReleaseSet(args) {
             previewOptions,
             overrideContext,
             sectionOrder,
+            dependenciesHeader,
         }));
     }
     return { tags, modifiedFiles };
 }
 function executeWorkspaceRelease(args) {
-    const { dir, workspace, releaseEntry, directResult, previousTags, config, today, tags, modifiedFiles, writes, warnings, workspaces, previewOptions, overrideContext, sectionOrder, } = args;
+    const { dir, workspace, releaseEntry, directResult, skippedHistory, config, today, tags, modifiedFiles, writes, warnings, workspaces, previewOptions, overrideContext, sectionOrder, dependenciesHeader, } = args;
     const setVersionTarget = directResult?.setVersion;
     const bump = setVersionTarget === undefined
         ? planVersionBump(workspace.packageFiles, releaseEntry.releaseType)
@@ -227,8 +249,8 @@ function executeWorkspaceRelease(args) {
     tags.push(newTag);
     writes.push(...bump.writes);
     modifiedFiles.push(...workspace.packageFiles, ...workspace.changelogPaths.map((changelogPath) => joinPath(changelogPath, 'CHANGELOG.md')));
-    const directCommits = directResult?.history.unreleased.commits;
-    const { changelogFiles, previewFiles } = generateWorkspaceChangelogs({
+    const phase1History = directResult?.history ?? skippedHistory;
+    const { changelogFiles, changelogPreservation, previewFiles } = generateWorkspaceChangelogs({
         workspace,
         releaseEntry,
         newTag,
@@ -242,28 +264,31 @@ function executeWorkspaceRelease(args) {
         previewOptions,
         overrideContext,
         sectionOrder,
+        dependenciesHeader,
     });
     const released = {
         name: dir,
         status: 'released',
-        commitCount: directCommits?.length ?? 0,
+        commitCount: phase1History?.unreleased.commits.length ?? 0,
         currentVersion: bump.currentVersion,
         newVersion: bump.newVersion,
         tag: newTag,
         bumpedFiles: bump.writes.map((write) => write.path),
         changelogFiles,
         ...(previewFiles.length > 0 && { previewFiles }),
+        ...(changelogPreservation.length > 0 && { changelogPreservation }),
     };
     attachReleasedWorkspaceOptionals(released, {
-        previousTag: directResult?.history.previousTag ?? previousTags.get(dir),
+        previousTag: phase1History?.previousTag,
         directResult,
+        skippedHistory,
         releaseEntry,
         setVersionTarget,
     });
     workspaces.push(released);
 }
 function attachReleasedWorkspaceOptionals(released, args) {
-    const { previousTag, directResult, releaseEntry, setVersionTarget } = args;
+    const { previousTag, directResult, skippedHistory, releaseEntry, setVersionTarget } = args;
     if (previousTag !== undefined) {
         released.previousTag = previousTag;
     }
@@ -273,6 +298,9 @@ function attachReleasedWorkspaceOptionals(released, args) {
     if (directResult !== undefined) {
         attachDirectHistory(released, directResult.history.unreleased, setVersionTarget === undefined);
     }
+    else {
+        attachPropagatedHistory(released, skippedHistory?.unreleased);
+    }
     if (releaseEntry.propagatedFrom !== undefined) {
         released.propagatedFrom = releaseEntry.propagatedFrom;
     }
@@ -293,11 +321,31 @@ function attachDirectHistory(released, unreleased, hasDecidedBump) {
     }
     attachChangelogDiagnostics(released, unreleased.diagnostics);
 }
+function attachPropagatedHistory(released, unreleased) {
+    released.propagatedOnly = true;
+    if (unreleased === undefined) {
+        return;
+    }
+    released.commits = unreleased.commits;
+    if (unreleased.unparseableCommits !== undefined) {
+        released.unparseableCommits = unreleased.unparseableCommits;
+    }
+    attachChangelogDiagnostics(released, unreleased.diagnostics);
+}
 function generateWorkspaceChangelogs(args) {
-    const { workspace, releaseEntry, newTag, newVersion, history, config, today, modifiedFiles, writes, warnings, previewOptions, overrideContext, sectionOrder, } = args;
-    const entries = buildWorkspaceEntries({ workspace, releaseEntry, newTag, newVersion, history, today });
+    const { workspace, releaseEntry, newTag, newVersion, history, config, today, modifiedFiles, writes, warnings, previewOptions, overrideContext, sectionOrder, dependenciesHeader, } = args;
+    const entries = buildWorkspaceEntries({
+        workspace,
+        releaseEntry,
+        newTag,
+        newVersion,
+        history,
+        today,
+        dependenciesHeader,
+    });
     const applied = applyWorkspaceOverrides(entries, workspace.workspacePath, overrideContext);
     const changelogFiles = [];
+    const changelogPreservation = [];
     let firstMergedEntries;
     for (const changelogPath of workspace.changelogPaths) {
         const jsonPath = resolveChangelogJsonPath(config, changelogPath);
@@ -308,25 +356,29 @@ function generateWorkspaceChangelogs(args) {
             firstMergedEntries ??= mergedEntries;
         }
         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);
+        }
     }
     const previews = planPreviews(workspace, newTag, firstMergedEntries, previewOptions, warnings);
     writes.push(...previews);
-    return { changelogFiles, previewFiles: previews.map((write) => write.path) };
+    return { changelogFiles, changelogPreservation, previewFiles: previews.map((write) => write.path) };
 }
 function buildWorkspaceEntries(args) {
-    const { workspace, releaseEntry, newTag, newVersion, history, today } = args;
+    const { workspace, releaseEntry, newTag, newVersion, history, today, dependenciesHeader } = args;
     if (history === undefined) {
         if (releaseEntry.propagatedFrom === undefined) {
             throw new Error(`Workspace '${workspace.dir}' has neither a direct release nor a propagation source`);
         }
-        return [buildSyntheticChangelogEntry(releaseEntry.propagatedFrom, newVersion, today)];
-    }
-    if (history.unreleased.commits.length === 0) {
-        return [buildEmptyReleaseEntry(newVersion, today)];
+        return [buildSyntheticChangelogEntry(releaseEntry.propagatedFrom, newVersion, today, dependenciesHeader)];
     }
-    return toChangelogEntries(history, newTag);
+    return toReleaseEntries(history, newTag, today);
 }
 function planPreviews(workspace, newTag, entries, previewOptions, warnings) {
     if (!previewOptions.enabled || entries === undefined) {

package/dist/esm/releasePrepareProject.d.ts

@@ -1,57 +1,47 @@
 import type { PlannedWrite } from './releasePlan.js';
 import type { ReleasePrepareOptions } from './releasePrepare.js';
-import type { ChangelogOverride, MonorepoReleaseConfig, ProjectPrepareResult } from './types.js';
+import type { ChangelogOverride, MonorepoPrepareConfig, ProjectPrepareResult } from './types.js';
 /** Inputs to the project-release stage. */
 export interface ReleasePrepareProjectArgs {
     /** Resolved monorepo config; `config.project` must be defined when this function is called. */
-    config: MonorepoReleaseConfig;
+    config: MonorepoPrepareConfig;
     options: ReleasePrepareOptions;
     /** Mutated in-place to append project-level files (root package.json, root CHANGELOG.md, root changelog.json). */
     modifiedFiles: string[];
-    /** Mutated in-place to append every file this stage intends to write. */
+    /** Mutated in-place to append every file that this stage intends to write. */
     writes: PlannedWrite[];
     /** Mutated in-place to append the project tag. */
     tags: string[];
     /**
-     * Mutated in-place to surface warnings this stage raises that are not override-specific
-     * (currently the release-notes previews' skip reasons). Defaults to a discardable sink.
+     * Mutated in-place to receive the warnings that this stage raises and that are not override-specific.
+     * Defaults to a discardable sink.
      */
     warnings?: string[];
     /**
-     * Root-tier editorial overrides loaded once at the top of the prepare run. Defaults to an
-     * empty map when omitted (no overrides applied). The project changelog applies only the
-     * root-tier file — per-workspace files describe per-workspace editorial intent and have no
-     * meaning at the aggregated project tier.
+     * Root-tier editorial overrides. Defaults to an empty map. The project changelog applies only the
+     * root-tier file: Per-workspace files describe per-workspace editorial intent and are
+     * meaningless at the aggregated project tier.
      */
     rootOverrides?: Map<string, ChangelogOverride>;
     /**
-     * Mutated in-place to surface override warnings (currently empty by design — stale-key
-     * warnings are emitted by the orchestrator after aggregating across batches). Defaults to
-     * a discardable sink when omitted.
+     * Mutated in-place to receive override-application warnings. Stale-key warnings are not among them: Those
+     * depend on the matches of every batch, which `globalMatchedRootKeys` collects. Defaults to a discardable sink.
      */
     overrideWarnings?: string[];
     /**
-     * Mutated in-place: every root-tier override key matched in this stage is added so the
-     * orchestrator can dedupe stale-key warnings across the run. Defaults to a discardable
-     * sink when omitted.
+     * Mutated in-place to receive every root-tier override key that this stage matches, so that stale-key
+     * warnings can cover the whole run. Defaults to a discardable sink.
      */
     globalMatchedRootKeys?: Set<string>;
 }
 /**
- * Run the project-level release stage.
+ * Runs the project-level release stage: reads the history, decides the bump, and plans the root `package.json`
+ * bump, the root `CHANGELOG.md`, and optionally `changelog.json` and release-notes previews. Contributing paths
+ * come from the resolved `project.paths`, which defaults to the union of every (already-filtered) workspace's
+ * `paths`.
  *
- * Mirrors the per-workspace pipeline shape — read the history → decide the bump → bump version →
- * regenerate CHANGELOG → optionally emit changelog.json and release-notes previews — but
- * targets the root `package.json` and the root `CHANGELOG.md`. Contributing paths come from
- * the resolved `project.paths`, which defaults to the union of every (already-filtered)
- * workspace's `paths`.
- *
- * Returns a structured `{ status: 'skipped', skipReason, ... }` result when neither
- * commits nor `--force` provide a release signal. The caller should attach the returned
- * result to `PrepareResult.project`. `undefined` is returned only when there is no
- * configured `project` block — handled at the call site, not here.
- *
- * Caller contract: `prepareCommand` rejects `--only` upstream when a project block is
- * configured, so this orchestrator never has to reason about workspace-narrowing flags.
+ * Returns a `skipped` result when neither commits nor `--force` provide a release signal, and throws when
+ * `config.project` is undefined. A run narrowed by `--only` does not reach this stage, so it doesn't
+ * read any narrowing flag.
  */
 export declare function releasePrepareProject(args: ReleasePrepareProjectArgs): ProjectPrepareResult;

package/dist/esm/releasePrepareProject.js

@@ -1,15 +1,16 @@
 import { join as joinPath } from 'node:path';
+import { assertTaggedBaseline, findUntaggedBaseline } from "./assertTaggedBaseline.js";
 import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
-import { readReleaseHistory, toChangelogEntries } from "./buildChangelogEntries.js";
-import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
+import { readReleaseHistory, toReleaseEntries } from "./buildChangelogEntries.js";
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyChangelogOverrides } from "./changelogOverrides.js";
 import { decideRelease } from "./decideRelease.js";
 import { DEFAULT_WORK_TYPES } from "./defaults.js";
+import { deriveSectionOrder } from "./deriveReleaseNotesConfig.js";
 import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
 import { planVersionBump } from "./planVersionBump.js";
+import { planPreservedSections } from "./readChangelogSections.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
-import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
 const ROOT_PACKAGE_FILE = './package.json';
 const ROOT_CHANGELOG_PATH = '.';
 export function releasePrepareProject(args) {
@@ -22,6 +23,15 @@ export function releasePrepareProject(args) {
     }
     const workTypes = config.workTypes ?? { ...DEFAULT_WORK_TYPES };
     const history = readReleaseHistory(config, { tagPrefixes: [project.tagPrefix], paths: project.paths });
+    assertTaggedBaseline([
+        findUntaggedBaseline({
+            label: 'project',
+            packageFiles: [ROOT_PACKAGE_FILE],
+            changelogPaths: [ROOT_CHANGELOG_PATH],
+            tagPrefixes: [project.tagPrefix],
+            previousTag: history.previousTag,
+        }, config),
+    ]);
     const { commits, diagnostics, parsedCommitCount, unparseableCommits } = history.unreleased;
     const tag = history.previousTag;
     const since = tag === undefined ? '(no previous release found)' : `since ${tag}`;
@@ -59,7 +69,6 @@ export function releasePrepareProject(args) {
         config,
         history,
         newTag,
-        newVersion: bump.newVersion,
         rootOverrides,
         overrideWarnings,
         globalMatchedRootKeys,
@@ -95,6 +104,9 @@ export function releasePrepareProject(args) {
     if (previewFiles.length > 0) {
         result.previewFiles = previewFiles;
     }
+    if (changelogs.changelogPreservation.length > 0) {
+        result.changelogPreservation = changelogs.changelogPreservation;
+    }
     if (tag !== undefined) {
         result.previousTag = tag;
     }
@@ -116,10 +128,9 @@ function resolveOptionalOverrideArgs(args) {
     };
 }
 function planProjectChangelogs(args) {
-    const { config, history, newTag, newVersion, rootOverrides, overrideWarnings, globalMatchedRootKeys } = args;
-    const isEmptyRange = history.unreleased.commits.length === 0;
+    const { config, history, newTag, rootOverrides, overrideWarnings, globalMatchedRootKeys } = args;
     const today = new Date().toISOString().slice(0, 10);
-    const builtEntries = isEmptyRange ? [buildEmptyReleaseEntry(newVersion, today)] : toChangelogEntries(history, newTag);
+    const builtEntries = toReleaseEntries(history, newTag, today);
     const applied = applyChangelogOverrides(builtEntries, rootOverrides);
     if (applied.errors.length > 0) {
         throw new Error(`Changelog override application failed:\n  - ${applied.errors.join('\n  - ')}`);
@@ -130,9 +141,7 @@ function planProjectChangelogs(args) {
     }
     const changelogJsonPath = resolveChangelogJsonPath(config, ROOT_CHANGELOG_PATH);
     const sectionOrder = deriveSectionOrder(config.workTypes ?? { ...DEFAULT_WORK_TYPES });
-    const renderEntries = isEmptyRange
-        ? mergeChangelogEntriesWithDisk(changelogJsonPath, applied.entries)
-        : applied.entries;
+    const renderEntries = mergeChangelogEntriesWithDisk(changelogJsonPath, applied.entries);
     const writes = [];
     const changelogJsonFiles = [];
     if (config.changelogJson.enabled) {
@@ -140,6 +149,16 @@ function planProjectChangelogs(args) {
         changelogJsonFiles.push(changelogJsonPath);
     }
     const changelogFile = joinPath(ROOT_CHANGELOG_PATH, 'CHANGELOG.md');
-    writes.push({ path: changelogFile, content: renderChangelogMarkdown(renderEntries, { sectionOrder }) });
-    return { changelogFiles: [changelogFile], changelogJsonFiles, entries: renderEntries, writes };
+    const preserved = planPreservedSections(changelogFile, renderEntries);
+    writes.push({
+        path: changelogFile,
+        content: renderChangelogMarkdown(renderEntries, { sectionOrder, preservedSections: preserved.sections }),
+    });
+    return {
+        changelogFiles: [changelogFile],
+        changelogJsonFiles,
+        changelogPreservation: preserved.preservation === undefined ? [] : [preserved.preservation],
+        entries: renderEntries,
+        writes,
+    };
 }

package/dist/esm/renderChangelogMarkdown.d.ts

@@ -1,22 +1,28 @@
+import type { VersionedMarkdownSection } from './readChangelogSections.js';
 import type { ChangelogEntry } from './types.js';
 /** Options for `renderChangelogMarkdown`. */
 export interface RenderChangelogMarkdownOptions {
-    /** Section titles in canonical order; passed through to `renderReleaseNotesMulti`. */
+    /** Section titles in canonical order; passed through to `renderReleaseNotesSingle`. */
     sectionOrder?: string[];
+    /**
+     * Sections of the existing `CHANGELOG.md` to keep verbatim, interleaved by version among the rendered entries. A
+     * section's version must not also be an entry's version.
+     */
+    preservedSections?: readonly VersionedMarkdownSection[];
 }
 /**
- * Render `ChangelogEntry[]` into a complete `CHANGELOG.md`-shaped string.
+ * Renders `ChangelogEntry[]` into a complete `CHANGELOG.md`-shaped string.
  *
  * Format:
  *   `# Changelog`
  *   blank line
  *   `All notable changes …`
  *   blank line
- *   per-entry sections (delegated to `renderReleaseNotesMulti`)
+ *   per-entry sections (delegated to `renderReleaseNotesSingle`), with preserved sections interleaved by version
  *   blank line
  *   footer comment
  *
  * Entries are rendered in the order provided; the caller sorts (typically newest-first via
- * `changelogJsonFile`'s SemVer-aware comparator).
+ * `compareVersionsDescending`).
  */
 export declare function renderChangelogMarkdown(entries: ChangelogEntry[], options?: RenderChangelogMarkdownOptions): string;