@williamthorsen/release-kit 12.0.0 → 13.0.0

package/dist/esm/planReleaseNotesPreviews.d.ts

@@ -11,7 +11,7 @@ export interface PlanReleaseNotesPreviewsOptions {
     /** Section titles in priority order, typically derived from `resolveWorkTypes(config.workTypes)`. */
     sectionOrder: string[];
 }
-/** Preview files a release will write, alongside the reasons any were left out. */
+/** Preview files that a release will write, with the reasons for any that were left out. */
 export interface ReleaseNotesPreviewsPlan {
     writes: PlannedWrite[];
     warnings: string[];
@@ -20,14 +20,14 @@ export interface ReleaseNotesPreviewsPlan {
  * Computes the per-workspace release-notes previews under `{workspacePath}/docs/` without
  * writing them:
  *
- * - `docs/README.v{version}.md` — the workspace README with release notes injected at the marker.
- * - `docs/RELEASE_NOTES.v{version}.md` — the standalone release notes for this version.
+ * - `docs/README.v{version}.md`: the workspace README with release notes injected at the marker.
+ * - `docs/RELEASE_NOTES.v{version}.md`: the standalone release notes for this version.
  *
- * Renders from the entries the release will write rather than from a saved `changelog.json`, so
+ * Renders from the entries that the release will write rather than from a saved `changelog.json`, so
  * a preview describes the release being prepared rather than the one already on disk.
  *
  * The injected-README preview is omitted (the standalone file is still planned) when the
- * workspace has no readable `README.md`. Both are omitted when the renderer reports no content
- * for this version, with the reason recorded in `warnings`.
+ * workspace does not have a readable `README.md`. Both are omitted when the renderer does not
+ * report any content for this version, with the reason recorded in `warnings`.
  */
 export declare function planReleaseNotesPreviews(options: PlanReleaseNotesPreviewsOptions): ReleaseNotesPreviewsPlan;

package/dist/esm/planVersionBump.d.ts

@@ -10,13 +10,15 @@ export interface VersionBumpPlan {
  * Computes the version bump for a workspace's package files without writing them.
  *
  * The current version comes from the first package file, and the new one from the release type.
- * Every file's post-bump content is rendered in full, preserving the fields the file already
- * carries and the two-space indentation with a trailing newline.
+ * Every file's post-bump content is rendered in full, preserving every field that the file already
+ * contains, with two-space indentation and a trailing newline.
  */
 export declare function planVersionBump(packageFiles: readonly string[], releaseType: ReleaseType): VersionBumpPlan;
 /**
  * Computes an explicit version assignment for a workspace's package files without writing them,
- * bypassing commit-derived bump logic. Backs the `--set-version` flag, and so rejects a
+ * bypassing commit-derived bump logic. Implements the `--set-version` flag, and so rejects a
  * `newVersion` that is not greater than the current version.
  */
 export declare function planVersionSet(packageFiles: readonly string[], newVersion: string): VersionBumpPlan;
+/** Reads a workspace's current version from its first package file, as the version planners do. */
+export declare function readCurrentVersion(packageFiles: readonly string[]): string;

package/dist/esm/planVersionBump.js

@@ -19,6 +19,9 @@ export function planVersionSet(packageFiles, newVersion) {
     }
     return { currentVersion, newVersion, writes: renderVersionWrites(packageFiles, firstFile, firstPkg, newVersion) };
 }
+export function readCurrentVersion(packageFiles) {
+    return readPrimaryPackage(packageFiles).firstPkg.version;
+}
 function readPrimaryPackage(packageFiles) {
     const firstFile = packageFiles[0];
     if (firstFile === undefined) {

package/dist/esm/prepareCommand.d.ts

@@ -47,12 +47,9 @@ export declare function parseArgs(argv: string[]): {
     withReleaseNotes: boolean;
 };
 /**
- * Orchestrates the CLI `prepare` command.
+ * Orchestrates the CLI `prepare` command: checks the working tree, loads and validates the config, discovers the
+ * workspaces, and prepares the release in single-package or monorepo mode.
  *
- * 1. Discovers workspaces from `pnpm-workspace.yaml`.
- * 2. Loads and validates `.config/release-kit.config.ts` (if present).
- * 3. Merges discovered defaults with user config.
- * 4. Delegates to `releasePrepare` or `releasePrepareMono` to compute the release plan.
- * 5. Applies the plan, runs the format command, and prints the result via `reportPrepare`.
+ * A relative `--config` resolves against `invocationDir`.
  */
-export declare function prepareCommand(argv: string[], styles: StreamStyles): Promise<void>;
+export declare function prepareCommand(argv: string[], styles: StreamStyles, invocationDir: string): Promise<void>;

package/dist/esm/prepareCommand.js

@@ -16,6 +16,7 @@ import { applyReleasePlan } from "./releasePlan.js";
 import { releasePrepare } from "./releasePrepare.js";
 import { releasePrepareMono } from "./releasePrepareMono.js";
 import { reportPrepare } from "./reportPrepare.js";
+import { resolveConfigFlag } from "./resolveConfigFlag.js";
 import { validateOnlyExcludesStrandedDependents } from "./validateOnlyExcludesStrandedDependents.js";
 const VALID_BUMP_TYPES = ['major', 'minor', 'patch'];
 const CANONICAL_SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
@@ -77,8 +78,8 @@ export function parseArgs(argv) {
         withReleaseNotes: flags.withReleaseNotes,
     };
 }
-export async function prepareCommand(argv, styles) {
-    const { configPath, dryRun, force, noGitChecks, bumpOverride, only, setVersion, withReleaseNotes } = parseArgs(argv);
+export async function prepareCommand(argv, styles, invocationDir) {
+    const { configPath: configFlag, dryRun, force, noGitChecks, bumpOverride, only, setVersion, withReleaseNotes, } = parseArgs(argv);
     const options = {
         force,
         ...(bumpOverride !== undefined && { bumpOverride }),
@@ -86,7 +87,7 @@ export async function prepareCommand(argv, styles) {
         ...(withReleaseNotes && { withReleaseNotes: true }),
     };
     if (dryRun) {
-        console.info(`\n${formatGlyphLine(RELEASE_GLYPHS, styles.stdout, 'dryRun', 'DRY RUN — no files will be modified')}\n`);
+        console.info(`\n${formatGlyphLine(RELEASE_GLYPHS, styles.stdout, 'dryRun', 'DRY RUN: release-kit will not modify any files')}\n`);
     }
     if (!dryRun && !noGitChecks) {
         try {
@@ -97,7 +98,7 @@ export async function prepareCommand(argv, styles) {
             process.exit(1);
         }
     }
-    const configResult = await loadValidatedConfig(configPath);
+    const configResult = await loadValidatedConfig(resolveConfigFlag(configFlag, invocationDir));
     if (configResult.status === 'invalid') {
         reportConfigProblem(configResult.problem, styles.stderr);
         process.exit(1);
@@ -150,6 +151,7 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
             'contributing workspace. To use --set-version, run on a config without a `project` block.');
         process.exit(1);
     }
+    let configuredWorkspaceDirs;
     if (only !== undefined) {
         const knownNames = config.workspaces.map((w) => w.dir);
         for (const name of only) {
@@ -174,6 +176,7 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
             process.stderr.write('Alternatively, run `release-kit prepare` without --only to release everything.\n');
             process.exit(1);
         }
+        configuredWorkspaceDirs = knownNames;
         config.workspaces = config.workspaces.filter((w) => only.includes(w.dir));
     }
     if (setVersion !== undefined) {
@@ -186,7 +189,11 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
             process.exit(1);
         }
     }
-    runAndReport(() => releasePrepareMono(config, { ...options, ...(only !== undefined && { only }) }), dryRun, style);
+    runAndReport(() => releasePrepareMono(config, {
+        ...options,
+        ...(only !== undefined && { only }),
+        ...(configuredWorkspaceDirs !== undefined && { configuredWorkspaceDirs }),
+    }), dryRun, style);
 }
 function runAndReport(computePlan, dryRun, style) {
     let plan;
@@ -195,7 +202,7 @@ function runAndReport(computePlan, dryRun, style) {
     }
     catch (error) {
         reportError(describeError(error));
-        process.stderr.write('No files were written; the working tree is unchanged.\n');
+        process.stderr.write('The command did not write any files; the working tree is unchanged.\n');
         process.exit(1);
     }
     if (dryRun) {

package/dist/esm/previewTagPrefixes.d.ts

@@ -2,7 +2,7 @@ import { type UndeclaredTagPrefix } from './detectUndeclaredTagPrefixes.js';
 import type { ReleaseKitConfig } from './types.js';
 /** One workspace's preview row in the tag-prefix preview. */
 export interface TagPrefixPreviewRow {
-    /** Workspace-relative directory path (e.g., `packages/core`). */
+    /** Directory path relative to the repo root (e.g., `packages/core`). */
     workspacePath: string;
     /** Directory basename (e.g., `core`). */
     dir: string;
@@ -10,7 +10,7 @@ export interface TagPrefixPreviewRow {
     derivedPrefix: string | null;
     /** Human-readable reason derivation failed, or `null` when it succeeded. */
     derivationError: string | null;
-    /** Count of tags matching the derived prefix; `0` when derivation failed or no tags exist. */
+    /** Count of tags matching the derived prefix; `0` when derivation failed or the repo lacks matching tags. */
     derivedTagCount: number;
     /** One entry per declared legacy prefix, with its current tag count. */
     legacyEntries: LegacyTagPrefixEntry[];
@@ -40,14 +40,12 @@ export interface TagPrefixPreview {
     retiredPackages: RetiredPackagePreviewEntry[];
 }
 /**
- * Build a structured preview of tag-prefix state for every discovered workspace.
+ * Builds a structured preview of tag-prefix state for every discovered workspace.
  *
- * Derives each workspace's tag prefix via `deriveWorkspaceConfig()`, recording the derivation error on failure
- * rather than aborting. A repo releasing as a single package previews no row; one declaring patterns that
- * resolve to no package throws, because the manifest is then what needs repairing and a clean table would
- * hide that.
- * Reads the already-validated `config` to surface declared legacy prefixes per workspace, scans local
- * git tags for undeclared candidate prefixes via `detectUndeclaredTagPrefixes`, and reports collisions
- * across successfully-derived prefixes.
+ * Records a workspace's derivation error rather than aborting. For a repo releasing as a single package, the
+ * preview doesn't contain any rows; for one declaring patterns that don't resolve to any package, the function
+ * throws, because the manifest then needs repairing and a clean table would hide that. Also reports the legacy
+ * prefixes that the validated `config` declares per workspace, undeclared candidate prefixes among the local git
+ * tags, and collisions across the successfully derived prefixes.
  */
 export declare function previewTagPrefixes(config?: ReleaseKitConfig): TagPrefixPreview;

package/dist/esm/propagateBumps.d.ts

@@ -6,17 +6,16 @@ export interface ReleaseEntry {
     /** Present when this workspace was bumped (wholly or partly) due to a dependency update. */
     propagatedFrom?: PropagationSource[];
     /**
-     * Explicit new version override used for propagation metadata.
-     * When set, dependents see this value in their `propagatedFrom.newVersion` entry instead of a version computed from
-     * `releaseType`. Used by the `--set-version` CLI path so propagation reflects the overridden version.
+     * Explicit new version, which dependents record in their `propagatedFrom.newVersion` entry in place of a version
+     * computed from `releaseType`.
      */
     newVersionOverride?: string;
 }
 /**
- * Walk upward through the dependency graph via BFS, adding `patch` bumps for dependents
- * not already in the release set with a higher bump.
+ * Walks upward through the dependency graph breadth-first, adding a `patch` bump for each dependent
+ * not already in the release set.
  *
- * Returns the full release set (direct + propagated). Direct entries that also have a
- * propagated dependency get `propagatedFrom` metadata without changing their bump type.
+ * Returns the full release set (direct + propagated). An entry already in the set that also has a
+ * propagated dependency gains `propagatedFrom` metadata without a change to its bump type.
  */
 export declare function propagateBumps(directBumps: Map<string, ReleaseEntry>, graph: DependencyGraph): Map<string, ReleaseEntry>;

package/dist/esm/publish.d.ts

@@ -4,5 +4,5 @@ export interface PublishOptions {
     dryRun: boolean;
     provenance: boolean;
 }
-/** Publish a single package by running `{pm} publish` from its workspace directory. */
+/** Publishes a single package by running `{pm} publish` from its workspace directory. */
 export declare function publishPackage(resolvedTag: ResolvedTag, packageManager: PackageManager, options: PublishOptions): void;

package/dist/esm/publishCommand.d.ts

@@ -1,6 +1,7 @@
 import { type StreamStyles } from '@williamthorsen/nmr-core';
 /**
- * Orchestrate the CLI `publish` command: parse flags, open a named config, discover workspaces, resolve tags
- * from HEAD, detect the package manager, validate `--tags`, and publish each tag with inject/restore lifecycle.
+ * Orchestrates the CLI `publish` command: checks for a clean working tree, resolves the tags on HEAD, and publishes
+ * each publishable one, injecting release notes into its README for the duration of the publish.
+ * A relative `--config` resolves against `invocationDir`.
  */
-export declare function publishCommand(argv: string[], styles: StreamStyles): Promise<void>;
+export declare function publishCommand(argv: string[], styles: StreamStyles, invocationDir: string): Promise<void>;

package/dist/esm/publishCommand.js

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

package/dist/esm/pushCommand.d.ts

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

package/dist/esm/pushCommand.js

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

package/dist/esm/pushRelease.d.ts

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

package/dist/esm/readChangelogSections.d.ts

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

package/dist/esm/readChangelogSections.js

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

package/dist/esm/releaseFiles.d.ts

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

package/dist/esm/releasePlan.d.ts

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

package/dist/esm/releasePrepare.d.ts

@@ -1,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;