@williamthorsen/release-kit 11.0.0 → 13.0.0

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,26 +1,26 @@
 import { join as joinPath } from 'node:path';
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
-import { buildChangelogEntries } from "./buildChangelogEntries.js";
+import { assertTaggedBaseline, findUntaggedBaseline } from "./assertTaggedBaseline.js";
+import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.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 { createPolicyViolationCollector } from "./collectPolicyViolations.js";
 import { decideRelease } from "./decideRelease.js";
-import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
+import { deriveDependenciesHeader, deriveSectionOrder } from "./deriveReleaseNotesConfig.js";
 import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
-import { buildTagPattern, getAllTagPrefixes } from "./generateChangelogs.js";
-import { getCommitsSinceTarget } from "./getCommitsSinceTarget.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 = [];
@@ -28,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.tag);
-    }
-    for (const skipped of skippedResults) {
-        previousTags.set(skipped.workspace.dir, skipped.tag);
-    }
+    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(', ')}. ` +
@@ -55,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) => {
@@ -111,18 +112,28 @@ function determineDirectBumps(config, options) {
     if (setVersion !== undefined && config.workspaces.length !== 1) {
         throw new Error(`--set-version requires exactly one workspace; received ${config.workspaces.length}`);
     }
-    const workTypes = config.workTypes ?? { ...DEFAULT_WORK_TYPES };
-    const versionPatterns = config.versionPatterns ?? { ...DEFAULT_VERSION_PATTERNS };
-    const breakingPolicies = config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES;
     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 { tag, commits } = tryStage(stageLabel, () => getCommitsSinceTarget(getAllTagPrefixes(workspace), 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) {
             maybeEmitBaselineHint(workspace, knownPrefixes, hintState);
@@ -131,58 +142,42 @@ function determineDirectBumps(config, options) {
             directBumps.set(workspace.dir, { releaseType: 'patch', newVersionOverride: setVersion });
             directResults.set(workspace.dir, {
                 workspace,
-                tag,
-                commits,
+                history,
                 releaseType: undefined,
-                parsedCommitCount: undefined,
-                unparseableCommits: undefined,
-                policyViolations: undefined,
                 bumpOverride: undefined,
                 setVersion,
             });
             continue;
         }
-        const collector = createPolicyViolationCollector();
-        const decision = tryStage(stageLabel, () => decideRelease({
-            commits,
+        const decision = decideRelease({
+            naturalBump: history.unreleased.bump,
+            commitCount: history.unreleased.commits.length,
             force,
             bumpOverride,
-            workTypes,
-            versionPatterns,
-            scopeAliases: config.scopeAliases,
-            breakingPolicies,
-            onPolicyViolation: collector.onPolicyViolation,
             skipReasons: {
                 noCommits: `No commits for ${name} ${since}. Pass --force to release at patch. Skipping.`,
                 noBumpWorthy: `No bump-worthy commits for ${name} ${since}. Pass --force to release at patch (or --force --bump=X for a different level). Skipping.`,
             },
-        }));
-        const policyViolations = collector.violations.length > 0 ? collector.violations : undefined;
+        });
         if (decision.outcome === 'skip') {
-            skippedResults.push({
-                workspace,
-                tag,
-                commitCount: commits.length,
-                parsedCommitCount: decision.parsedCommitCount,
-                unparseableCommits: decision.unparseableCommits,
-                policyViolations,
-                skipReason: decision.skipReason,
-            });
+            skippedResults.push({ workspace, history, skipReason: decision.skipReason });
             continue;
         }
         directBumps.set(workspace.dir, { releaseType: decision.releaseType });
         directResults.set(workspace.dir, {
             workspace,
-            tag,
-            commits,
+            history,
             releaseType: decision.releaseType,
-            parsedCommitCount: decision.parsedCommitCount,
-            unparseableCommits: decision.unparseableCommits,
-            policyViolations,
             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 = [];
@@ -190,30 +185,27 @@ function collectSkippedWorkspaces(skippedResults, fullReleaseSet) {
         if (fullReleaseSet.has(skipped.workspace.dir)) {
             continue;
         }
+        const { previousTag, unreleased } = skipped.history;
         const result = {
             name: skipped.workspace.dir,
             status: 'skipped',
-            commitCount: skipped.commitCount,
+            commitCount: unreleased.commits.length,
+            parsedCommitCount: unreleased.parsedCommitCount,
             skipReason: skipped.skipReason,
         };
-        if (skipped.tag !== undefined) {
-            result.previousTag = skipped.tag;
+        if (previousTag !== undefined) {
+            result.previousTag = previousTag;
         }
-        if (skipped.parsedCommitCount !== undefined) {
-            result.parsedCommitCount = skipped.parsedCommitCount;
-        }
-        if (skipped.unparseableCommits !== undefined) {
-            result.unparseableCommits = skipped.unparseableCommits;
-        }
-        if (skipped.policyViolations !== undefined) {
-            result.policyViolations = skipped.policyViolations;
+        if (unreleased.unparseableCommits !== undefined) {
+            result.unparseableCommits = unreleased.unparseableCommits;
         }
+        attachChangelogDiagnostics(result, unreleased.diagnostics);
         workspaces.push(result);
     }
     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);
@@ -231,7 +223,7 @@ function executeReleaseSet(args) {
             workspace,
             releaseEntry,
             directResult: directResults.get(dir),
-            previousTags,
+            skippedHistory: skippedHistories.get(dir),
             config,
             today,
             tags,
@@ -242,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)
@@ -256,15 +249,13 @@ function executeWorkspaceRelease(args) {
     tags.push(newTag);
     writes.push(...bump.writes);
     modifiedFiles.push(...workspace.packageFiles, ...workspace.changelogPaths.map((changelogPath) => joinPath(changelogPath, 'CHANGELOG.md')));
-    const isPropagationOnly = directResult === undefined;
-    const isEmptyRange = directResult !== undefined && directResult.commits.length === 0;
-    const { changelogFiles, previewFiles } = generateWorkspaceChangelogs({
+    const phase1History = directResult?.history ?? skippedHistory;
+    const { changelogFiles, changelogPreservation, previewFiles } = generateWorkspaceChangelogs({
         workspace,
         releaseEntry,
         newTag,
         newVersion: bump.newVersion,
-        isPropagationOnly,
-        isEmptyRange,
+        history: directResult?.history,
         config,
         today,
         modifiedFiles,
@@ -273,45 +264,42 @@ function executeWorkspaceRelease(args) {
         previewOptions,
         overrideContext,
         sectionOrder,
+        dependenciesHeader,
     });
     const released = {
         name: dir,
         status: 'released',
-        commitCount: directResult?.commits.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?.tag ?? 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;
     }
-    if (directResult?.parsedCommitCount !== undefined) {
-        released.parsedCommitCount = directResult.parsedCommitCount;
-    }
     if (setVersionTarget === undefined) {
         released.releaseType = releaseEntry.releaseType;
     }
-    if (directResult?.commits !== undefined) {
-        released.commits = directResult.commits;
+    if (directResult !== undefined) {
+        attachDirectHistory(released, directResult.history.unreleased, setVersionTarget === undefined);
     }
-    if (directResult?.unparseableCommits !== undefined) {
-        released.unparseableCommits = directResult.unparseableCommits;
-    }
-    if (directResult?.policyViolations !== undefined) {
-        released.policyViolations = directResult.policyViolations;
+    else {
+        attachPropagatedHistory(released, skippedHistory?.unreleased);
     }
     if (releaseEntry.propagatedFrom !== undefined) {
         released.propagatedFrom = releaseEntry.propagatedFrom;
@@ -323,20 +311,41 @@ function attachReleasedWorkspaceOptionals(released, args) {
         released.setVersion = setVersionTarget;
     }
 }
+function attachDirectHistory(released, unreleased, hasDecidedBump) {
+    released.commits = unreleased.commits;
+    if (hasDecidedBump) {
+        released.parsedCommitCount = unreleased.parsedCommitCount;
+        if (unreleased.unparseableCommits !== undefined) {
+            released.unparseableCommits = unreleased.unparseableCommits;
+        }
+    }
+    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, isPropagationOnly, isEmptyRange, config, today, modifiedFiles, writes, warnings, previewOptions, overrideContext, sectionOrder, } = args;
-    const newEntries = buildWorkspaceEntries({
+    const { workspace, releaseEntry, newTag, newVersion, history, config, today, modifiedFiles, writes, warnings, previewOptions, overrideContext, sectionOrder, dependenciesHeader, } = args;
+    const entries = buildWorkspaceEntries({
         workspace,
         releaseEntry,
         newTag,
         newVersion,
-        isPropagationOnly,
-        isEmptyRange,
-        config,
+        history,
         today,
+        dependenciesHeader,
     });
-    const applied = applyWorkspaceOverrides(newEntries, workspace.workspacePath, overrideContext);
+    const applied = applyWorkspaceOverrides(entries, workspace.workspacePath, overrideContext);
     const changelogFiles = [];
+    const changelogPreservation = [];
     let firstMergedEntries;
     for (const changelogPath of workspace.changelogPaths) {
         const jsonPath = resolveChangelogJsonPath(config, changelogPath);
@@ -347,23 +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, isPropagationOnly, isEmptyRange, config, today } = args;
-    if (isPropagationOnly && releaseEntry.propagatedFrom !== undefined) {
-        return [buildSyntheticChangelogEntry(releaseEntry.propagatedFrom, newVersion, today)];
-    }
-    if (isEmptyRange) {
-        return [buildEmptyReleaseEntry(newVersion, today)];
+    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, dependenciesHeader)];
     }
-    const tagPattern = buildTagPattern(getAllTagPrefixes(workspace));
-    return buildChangelogEntries(config, newTag, { tagPattern, includePaths: workspace.paths });
+    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 — find baseline tag → derive 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;