@williamthorsen/release-kit 12.0.0 → 13.1.0

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,18 +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.
-     * 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;
-    /** Choose the level of a release instead of the level that the changelog items call for; triggers no release. */
+    /** 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.
@@ -21,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. Reads the release history once.
+ * 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. Bumps all configured package.json version fields.
- * 4. Generates changelogs from the same history.
+ * 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,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;