@williamthorsen/release-kit 14.1.0 → 14.2.0

package/dist/esm/prepareTarget.js

@@ -0,0 +1,274 @@
+import { join as joinPath } from 'node:path';
+import { findUntaggedBaseline } from "./assertTaggedBaseline.js";
+import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
+import { readReleaseHistory, toReleaseEntries } from "./buildChangelogEntries.js";
+import { buildSyntheticChangelogEntry } from "./buildSyntheticChangelogEntry.js";
+import { describeArchivePath, listArchiveFiles } from "./changelogArchive.js";
+import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
+import { applyWorkspaceOverrides } from "./changelogOverrides.js";
+import { decideRelease } from "./decideRelease.js";
+import { getAllTagPrefixes } from "./generateChangelogs.js";
+import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
+import { planVersionBump, planVersionSet } from "./planVersionBump.js";
+import { planPreservedSections } from "./readChangelogSections.js";
+import { renderChangelogFiles } from "./renderChangelogMarkdown.js";
+import { PROJECT_TARGET_ID } from "./resolveReleaseTargets.js";
+export function readTargetHistory(target, settings) {
+    const options = describeHistoryWindow(target);
+    const history = readReleaseHistory(settings, options);
+    const untagged = findUntaggedBaseline({
+        label: describeBaselineLabel(target),
+        packageFiles: target.versionFiles,
+        changelogPaths: [target.changelogDir],
+        tagPrefixes: options.tagPrefixes,
+        previousTag: history.previousTag,
+    }, settings);
+    return { history, untagged };
+}
+export function describeHistoryWindow(target) {
+    return {
+        tagPrefixes: getAllTagPrefixes(target),
+        ...(target.paths !== undefined && { paths: target.paths }),
+        ...(isScopeRouted(target) && { scope: target.id }),
+    };
+}
+export function decideTargetRelease(target, history, options) {
+    const { force, bumpOverride, setVersion } = options;
+    if (setVersion !== undefined) {
+        return { outcome: 'release', releaseType: undefined, bumpOverride: undefined, setVersion };
+    }
+    const tag = history.previousTag;
+    const since = tag === undefined ? '(no previous release found)' : `since ${tag}`;
+    const subject = isScopeRouted(target) || target.kind === 'directory' ? ` for ${target.id}` : '';
+    const decision = decideRelease({
+        naturalBump: history.unreleased.bump,
+        commitCount: history.unreleased.commits.length,
+        force,
+        bumpOverride,
+        skipReasons: {
+            noCommits: `No commits${subject} ${since}. Pass --force to release at patch. Skipping.`,
+            noBumpWorthy: `No bump-worthy commits${subject} ${since}. Pass --force to release at patch (or --force --bump=X for a different level). Skipping.`,
+        },
+    });
+    if (decision.outcome === 'skip') {
+        return decision;
+    }
+    return { outcome: 'release', releaseType: decision.releaseType, bumpOverride, setVersion: undefined };
+}
+export function planTargetRelease(args) {
+    const { target, settings, release, decision, history, overrideContext, sectionOrder, shouldPlanPreviews, today } = args;
+    const setVersion = decision?.setVersion;
+    const bump = setVersion === undefined
+        ? planVersionBump(target.versionFiles, release.releaseType)
+        : planVersionSet(target.versionFiles, setVersion);
+    const tag = `${target.tagPrefix}${bump.newVersion}`;
+    const writes = [...bump.writes];
+    const entries = decision === undefined
+        ? buildPropagationEntries(target, release, bump.newVersion, today, args.dependenciesHeader)
+        : toReleaseEntries(history, tag, today);
+    const overrideScope = describeOverrideScope(target);
+    const applied = applyWorkspaceOverrides(entries, overrideScope, overrideContext);
+    const changelogs = planChangelogFiles(target.changelogDir, applied.entries, settings, sectionOrder);
+    writes.push(...changelogs.writes);
+    const warnings = [];
+    const previewFiles = [];
+    if (shouldPlanPreviews) {
+        const previews = planReleaseNotesPreviews({
+            workspacePath: target.changelogDir,
+            tag,
+            entries: changelogs.entries,
+            sectionOrder,
+        });
+        writes.push(...previews.writes);
+        warnings.push(...previews.warnings);
+        previewFiles.push(...previews.writes.map((write) => write.path));
+    }
+    const releaseFields = {
+        targetId: target.id,
+        commitCount: history.unreleased.commits.length,
+        currentVersion: bump.currentVersion,
+        newVersion: bump.newVersion,
+        tag,
+        bumpedFiles: bump.writes.map((write) => write.path),
+        changelogFiles: changelogs.changelogFiles,
+        ...(changelogs.removals.length > 0 && { removedChangelogFiles: changelogs.removals }),
+        ...(previewFiles.length > 0 && { previewFiles }),
+        ...(changelogs.preservation !== undefined && { changelogPreservation: [changelogs.preservation] }),
+        ...(history.previousTag !== undefined && { previousTag: history.previousTag }),
+    };
+    const result = buildReleasedResult(target, releaseFields, release, decision, history);
+    return {
+        result,
+        tag,
+        writes,
+        removals: changelogs.removals,
+        modifiedFiles: [...target.versionFiles, ...changelogs.changelogFiles, ...changelogs.changelogJsonFiles],
+        warnings,
+    };
+}
+export function buildSkippedTargetResult(target, history, skipReason) {
+    const { unreleased } = history;
+    const fields = {
+        targetId: target.id,
+        status: 'skipped',
+        commitCount: unreleased.commits.length,
+        parsedCommitCount: unreleased.parsedCommitCount,
+        skipReason,
+        ...(history.previousTag !== undefined && { previousTag: history.previousTag }),
+        ...(unreleased.unparseableCommits !== undefined && { unparseableCommits: unreleased.unparseableCommits }),
+    };
+    const skipped = labelSkippedResult(target, fields);
+    attachChangelogDiagnostics(skipped, unreleased.diagnostics);
+    return skipped;
+}
+export function isRepoRoot(target) {
+    return target.directoryPath === '.';
+}
+function buildReleasedDirectory(target, fields, release, decision, history) {
+    const { unreleased } = history;
+    const setVersion = decision?.setVersion;
+    const result = {
+        ...fields,
+        status: 'released',
+        kind: 'directory',
+        name: target.id,
+        commits: unreleased.commits,
+        ...(setVersion === undefined && {
+            releaseType: release.releaseType,
+            parsedCommitCount: unreleased.parsedCommitCount,
+        }),
+        ...(decision?.bumpOverride !== undefined && { bumpOverride: decision.bumpOverride }),
+        ...(setVersion !== undefined && { setVersion }),
+    };
+    if (setVersion === undefined && unreleased.unparseableCommits !== undefined) {
+        result.unparseableCommits = unreleased.unparseableCommits;
+    }
+    attachChangelogDiagnostics(result, unreleased.diagnostics);
+    return result;
+}
+function buildReleasedComposite(fields, release, decision, history) {
+    const { unreleased } = history;
+    const result = {
+        ...fields,
+        status: 'released',
+        kind: 'composite',
+        parsedCommitCount: unreleased.parsedCommitCount,
+        releaseType: release.releaseType,
+        commits: unreleased.commits,
+        ...(unreleased.unparseableCommits !== undefined && { unparseableCommits: unreleased.unparseableCommits }),
+        ...(decision?.bumpOverride !== undefined && { bumpOverride: decision.bumpOverride }),
+    };
+    attachChangelogDiagnostics(result, unreleased.diagnostics);
+    return result;
+}
+function buildReleasedPackage(target, fields, release, decision, history) {
+    const { unreleased } = history;
+    const setVersion = decision?.setVersion;
+    const hasParseCounts = decision !== undefined && setVersion === undefined;
+    const result = {
+        ...fields,
+        status: 'released',
+        kind: 'package',
+        commits: unreleased.commits,
+        ...(target.isWorkspace && { name: target.id }),
+        ...(setVersion === undefined && { releaseType: release.releaseType }),
+        ...(hasParseCounts && { parsedCommitCount: unreleased.parsedCommitCount }),
+        ...(decision === undefined && { propagatedOnly: true }),
+        ...(release.propagatedFrom !== undefined && { propagatedFrom: release.propagatedFrom }),
+        ...(decision?.bumpOverride !== undefined && { bumpOverride: decision.bumpOverride }),
+        ...(setVersion !== undefined && { setVersion }),
+    };
+    if (setVersion === undefined && unreleased.unparseableCommits !== undefined) {
+        result.unparseableCommits = unreleased.unparseableCommits;
+    }
+    attachChangelogDiagnostics(result, unreleased.diagnostics);
+    return result;
+}
+function buildReleasedResult(target, fields, release, decision, history) {
+    switch (target.kind) {
+        case 'package':
+            return buildReleasedPackage(target, fields, release, decision, history);
+        case 'directory':
+            return buildReleasedDirectory(target, fields, release, decision, history);
+        case 'composite':
+            return buildReleasedComposite(fields, release, decision, history);
+    }
+}
+function buildPropagationEntries(target, release, newVersion, today, dependenciesHeader) {
+    if (release.propagatedFrom === undefined) {
+        throw new Error(`Workspace '${target.id}' has neither a direct release nor a propagation source`);
+    }
+    return [buildSyntheticChangelogEntry(release.propagatedFrom, newVersion, today, dependenciesHeader)];
+}
+function describeBaselineLabel(target) {
+    switch (target.kind) {
+        case 'composite':
+            return target.id === PROJECT_TARGET_ID ? 'project' : `composite '${target.id}'`;
+        case 'directory':
+            return `directory '${target.id}'`;
+        case 'package':
+            return target.isWorkspace ? `workspace '${target.id}'` : 'package';
+    }
+}
+function labelSkippedResult(target, fields) {
+    switch (target.kind) {
+        case 'package':
+            return { ...fields, kind: 'package', ...(target.isWorkspace && { name: target.id }) };
+        case 'directory':
+            return { ...fields, kind: 'directory', name: target.id };
+        case 'composite':
+            return { ...fields, kind: 'composite' };
+    }
+}
+function describeOverrideScope(target) {
+    switch (target.kind) {
+        case 'package':
+            return target.packagePath;
+        case 'directory':
+            return isRepoRoot(target) ? undefined : target.directoryPath;
+        case 'composite':
+            return undefined;
+    }
+}
+function isScopeRouted(target) {
+    if (target.kind === 'directory') {
+        return !isRepoRoot(target);
+    }
+    return target.kind === 'package' && target.isWorkspace;
+}
+function planChangelogFiles(changelogDir, newEntries, settings, sectionOrder) {
+    const jsonPath = resolveChangelogJsonPath(settings, changelogDir);
+    const entries = mergeChangelogEntriesWithDisk(jsonPath, newEntries);
+    const writes = [];
+    const changelogJsonFiles = [];
+    if (settings.changelogJson.enabled) {
+        writes.push({ path: jsonPath, content: renderChangelogJson(entries) });
+        changelogJsonFiles.push(jsonPath);
+    }
+    const changelogFile = joinPath(changelogDir, 'CHANGELOG.md');
+    const preserved = planPreservedSections(changelogDir, entries);
+    const keepVersions = settings.changelogMarkdown?.keepVersions;
+    const rendered = renderChangelogFiles(entries, {
+        sectionOrder,
+        preservedSections: preserved.sections,
+        ...(keepVersions !== undefined && { keepVersions }),
+    });
+    writes.push({ path: changelogFile, content: rendered.main });
+    const archiveFiles = [];
+    for (const { major, content } of rendered.archives) {
+        const path = joinPath(changelogDir, describeArchivePath(major));
+        writes.push({ path, content });
+        archiveFiles.push(path);
+    }
+    const removals = listArchiveFiles(changelogDir)
+        .map((archive) => archive.path)
+        .filter((path) => !archiveFiles.includes(path));
+    return {
+        changelogFiles: [changelogFile, ...archiveFiles],
+        changelogJsonFiles,
+        entries,
+        preservation: preserved.preservation,
+        removals,
+        writes,
+    };
+}

package/dist/esm/previewTagPrefixes.d.ts

@@ -1,6 +1,6 @@
 import { type UndeclaredTagPrefix } from './detectUndeclaredTagPrefixes.js';
 import type { ReleaseKitConfig } from './types.js';
-/** One workspace's preview row in the tag-prefix preview. */
+/** One workspace's or directory target's preview row in the tag-prefix preview. */
 export interface TagPrefixPreviewRow {
     /** Directory path relative to the repo root (e.g., `packages/core`). */
     workspacePath: string;
@@ -40,12 +40,14 @@ export interface TagPrefixPreview {
     retiredPackages: RetiredPackagePreviewEntry[];
 }
 /**
- * Builds a structured preview of tag-prefix state for every discovered workspace.
+ * Builds a structured preview of tag-prefix state for every discovered workspace and every directory that the
+ * `releases` block declares.
  *
  * 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.
+ * tags, and collisions across the successfully derived prefixes. A declared composite's tag prefix counts as known, so
+ * that its tags are not reported as undeclared.
  */
 export declare function previewTagPrefixes(config?: ReleaseKitConfig): TagPrefixPreview;

package/dist/esm/previewTagPrefixes.js

@@ -2,47 +2,78 @@ import { execFileSync } from 'node:child_process';
 import { basename } from 'node:path';
 import { GIT_OUTPUT_LIMIT } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { DEFAULT_PROJECT_TAG_PREFIX } from "./defaults.js";
+import { deriveDirectoryConfig } from "./deriveDirectoryConfig.js";
 import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
 import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
 import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
 import { matchesTagPrefix } from "./matchesTagPrefix.js";
+import { normalizeWorkspacePath } from "./resolveReleaseDeclaration.js";
 export function previewTagPrefixes(config) {
     const workspace = discoverWorkspaces();
     if (workspace.kind === 'empty') {
         throw new Error(`No workspace package to preview. ${describeEmptyWorkspace(workspace)}`);
     }
     const workspacePaths = workspace.kind === 'packages' ? workspace.packageDirs : [];
-    const overridesByDir = buildOverrideMap(config);
-    const workspaces = Array.from(workspacePaths, (workspacePath) => buildPreviewRow(workspacePath, overridesByDir));
+    const overridesByPath = buildOverrideMap(config, workspacePaths);
+    const workspaces = [
+        ...Array.from(workspacePaths, (workspacePath) => buildPreviewRow(workspacePath, () => deriveWorkspaceConfig(workspacePath).tagPrefix, overridesByPath)),
+        ...buildDirectoryRows(config, workspacePaths, overridesByPath),
+    ];
     const retiredPackages = buildRetiredPreviewEntries(config?.retiredPackages ?? []);
     const collisions = detectCollisions(workspaces);
-    const knownPrefixes = collectKnownPrefixes(workspaces, retiredPackages);
+    const knownPrefixes = collectKnownPrefixes(workspaces, retiredPackages, findCompositeTagPrefix(config));
     const undeclaredCandidates = detectUndeclaredTagPrefixes(knownPrefixes);
     return { workspaces, collisions, undeclaredCandidates, retiredPackages };
 }
-function buildOverrideMap(config) {
+function buildOverrideMap(config, workspacePaths) {
     const map = new Map();
-    if (config?.workspaces === undefined)
-        return map;
-    for (const entry of config.workspaces) {
-        if (entry.legacyIdentities !== undefined) {
-            map.set(entry.dir, entry.legacyIdentities);
+    const workspaceEntries = config?.workspaces ?? [];
+    for (const { dir, legacyIdentities } of workspaceEntries) {
+        if (legacyIdentities === undefined)
+            continue;
+        for (const workspacePath of workspacePaths) {
+            if (basename(workspacePath) === dir) {
+                map.set(workspacePath, legacyIdentities);
+            }
+        }
+    }
+    const releaseEntries = Object.values(config?.releases ?? {});
+    for (const entry of releaseEntries) {
+        if (entry !== false && 'path' in entry && entry.legacyIdentities !== undefined) {
+            map.set(normalizeWorkspacePath(entry.path), entry.legacyIdentities);
         }
     }
     return map;
 }
-function buildPreviewRow(workspacePath, overridesByDir) {
+function buildDirectoryRows(config, workspacePaths, overridesByPath) {
+    const discovered = new Set(workspacePaths);
+    return Object.entries(config?.releases ?? {}).flatMap(([name, entry]) => {
+        if (entry === false || !('path' in entry))
+            return [];
+        const directoryPath = normalizeWorkspacePath(entry.path);
+        if (discovered.has(directoryPath))
+            return [];
+        const declared = {
+            name,
+            path: directoryPath,
+            ...(entry.tagPrefix !== undefined && { tagPrefix: entry.tagPrefix }),
+        };
+        return [buildPreviewRow(directoryPath, () => deriveDirectoryConfig(declared).tagPrefix, overridesByPath)];
+    });
+}
+function buildPreviewRow(workspacePath, derivePrefix, overridesByPath) {
     const dir = basename(workspacePath);
     let derivedPrefix = null;
     let derivationError = null;
     try {
-        derivedPrefix = deriveWorkspaceConfig(workspacePath).tagPrefix;
+        derivedPrefix = derivePrefix();
     }
     catch (error) {
         derivationError = describeError(error);
     }
     const derivedTagCount = derivedPrefix === null ? 0 : countTagsMatching(derivedPrefix);
-    const declaredIdentities = overridesByDir.get(dir) ?? [];
+    const declaredIdentities = overridesByPath.get(workspacePath) ?? [];
     const legacyEntries = declaredIdentities.map((identity) => ({
         prefix: identity.tagPrefix,
         tagCount: countTagsMatching(identity.tagPrefix),
@@ -90,7 +121,7 @@ function detectCollisions(rows) {
     }
     return collisions;
 }
-function collectKnownPrefixes(rows, retiredPackages) {
+function collectKnownPrefixes(rows, retiredPackages, compositeTagPrefix) {
     const known = new Set();
     for (const row of rows) {
         if (row.derivedPrefix !== null)
@@ -102,6 +133,8 @@ function collectKnownPrefixes(rows, retiredPackages) {
     for (const retired of retiredPackages) {
         known.add(retired.tagPrefix);
     }
+    if (compositeTagPrefix !== undefined)
+        known.add(compositeTagPrefix);
     return [...known];
 }
 function buildRetiredPreviewEntries(retiredPackages) {
@@ -112,3 +145,15 @@ function buildRetiredPreviewEntries(retiredPackages) {
         ...(retired.successor !== undefined && { successor: retired.successor }),
     }));
 }
+function findCompositeTagPrefix(config) {
+    if (config?.project !== undefined) {
+        return config.project.tagPrefix ?? DEFAULT_PROJECT_TAG_PREFIX;
+    }
+    const releaseEntries = Object.values(config?.releases ?? {});
+    for (const entry of releaseEntries) {
+        if (entry !== false && 'includes' in entry) {
+            return entry.tagPrefix ?? DEFAULT_PROJECT_TAG_PREFIX;
+        }
+    }
+    return undefined;
+}

package/dist/esm/propagateBumps.js

@@ -30,7 +30,7 @@ export function propagateBumps(directBumps, graph) {
             continue;
         }
         for (const dependent of dependents) {
-            const dependentDir = dependent.dir;
+            const dependentDir = dependent.id;
             const existing = result.get(dependentDir);
             const propagationInfo = { packageName, newVersion };
             if (existing === undefined) {

package/dist/esm/publishCommand.js

@@ -6,7 +6,9 @@ import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
 import { configFlagSchema } from "./configFlagSchema.js";
 import { deriveReleaseNotesConfig } from "./deriveReleaseNotesConfig.js";
 import { detectPackageManager } from "./detectPackageManager.js";
+import { formatDirectoryPublishSkip } from "./formatDirectoryPublishSkip.js";
 import { formatPrivateSkip } from "./formatPrivateSkip.js";
+import { formatProjectPublishSkip } from "./formatProjectPublishSkip.js";
 import { injectReleaseNotesIntoReadme, resolveReadmePath } from "./injectReleaseNotesIntoReadme.js";
 import { loadUsableConfig } from "./loadValidatedConfig.js";
 import { parseRequestedTags } from "./parseRequestedTags.js";
@@ -92,8 +94,18 @@ function filterPublishableTags(resolvedTags, isExplicit) {
     }
     if (isExplicit) {
         for (const resolvedTag of unpublishable) {
-            console.warn(formatPrivateSkip(resolvedTag));
+            console.warn(formatPublishSkip(resolvedTag));
         }
     }
     return publishable;
 }
+function formatPublishSkip(resolvedTag) {
+    switch (resolvedTag.kind) {
+        case 'directory':
+            return formatDirectoryPublishSkip(resolvedTag);
+        case 'project':
+            return formatProjectPublishSkip(resolvedTag);
+        case 'package':
+            return formatPrivateSkip(resolvedTag);
+    }
+}

package/dist/esm/readChangelogSections.d.ts

@@ -12,11 +12,13 @@ export interface ChangelogMarkdownSections {
     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.
+ * Plans which sections of the existing `CHANGELOG.md` in `changelogDir` and its archive files to keep when they are
+ * regenerated from `entries`: every versioned section whose version matches none of the entries. A version found in
+ * more than one file is taken from the first file read, `CHANGELOG.md` first, then archives newest major first. Also
+ * returns what to report about the changelog, under the `CHANGELOG.md` path, or undefined when nothing was kept and
+ * nothing was dropped.
  */
-export declare function planPreservedSections(changelogFile: string, entries: readonly ChangelogEntry[]): {
+export declare function planPreservedSections(changelogDir: string, entries: readonly ChangelogEntry[]): {
     sections: VersionedMarkdownSection[];
     preservation: ChangelogPreservation | undefined;
 };

package/dist/esm/readChangelogSections.js

@@ -1,9 +1,23 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 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));
+import { listArchiveFiles } from "./changelogArchive.js";
+export function planPreservedSections(changelogDir, entries) {
+    const changelogFile = join(changelogDir, 'CHANGELOG.md');
+    const files = [changelogFile, ...listArchiveFiles(changelogDir).map((archive) => archive.path)];
+    const seenVersions = new Set(entries.map((entry) => entry.version));
+    const sections = [];
+    const unversionedHeadings = [];
+    for (const file of files) {
+        const read = readChangelogSections(file);
+        for (const section of read.versioned) {
+            if (seenVersions.has(section.version))
+                continue;
+            seenVersions.add(section.version);
+            sections.push(section);
+        }
+        unversionedHeadings.push(...read.unversionedHeadings);
+    }
     if (sections.length === 0 && unversionedHeadings.length === 0) {
         return { sections, preservation: undefined };
     }

package/dist/esm/releasePlan.d.ts

@@ -15,17 +15,19 @@ export interface PlannedWrite {
  */
 export interface ReleasePlan extends PrepareResult {
     writes: readonly PlannedWrite[];
+    /** Files that the release removes, such as changelog archive files that the render no longer produces. */
+    removals: readonly string[];
     /** Body of the release commit message, written alongside the tags file. */
     summary: string;
 }
 /**
- * Writes every file that a plan describes: content files first, then the summary, then the tags file.
+ * Applies every step that a plan describes: content files first, then removals, then the summary, then the tags file.
  *
  * 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 was written and what was not.
+ * Returns the paths written or removed, in order. Throws if any step fails, naming what was applied and what was not.
  */
 export declare function applyReleasePlan(plan: ReleasePlan): string[];

package/dist/esm/releasePlan.js

@@ -1,33 +1,55 @@
 import { writeFileWithCheck } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { deleteFileIfExists } from "./deleteFileIfExists.js";
 import { RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE } from "./releaseFiles.js";
 const HANDOFF_FILES = new Set([RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE]);
 export function applyReleasePlan(plan) {
-    const ordered = orderPlannedWrites(plan);
+    const ordered = orderPlannedSteps(plan);
     const applied = [];
-    for (const [index, write] of ordered.entries()) {
-        const result = writeFileWithCheck(write.path, write.content, { dryRun: false, overwrite: true });
-        if (result.outcome === 'failed') {
+    for (const [index, step] of ordered.entries()) {
+        const outcome = applyStep(step);
+        if (outcome.outcome === 'failed') {
             const unwritten = ordered.slice(index).map((pending) => pending.path);
-            throw new Error(describeApplyFailure({ failedPath: write.path, error: result.error, applied, unwritten }));
+            throw new Error(describeApplyFailure({ failedStep: step, error: outcome.error, applied, unwritten }));
         }
-        applied.push({ path: write.path, created: result.outcome === 'created' });
+        applied.push({ path: step.path, created: outcome.outcome === 'created' });
     }
     return applied.map((write) => write.path);
 }
-function orderPlannedWrites(plan) {
-    const ordered = [...plan.writes];
+function applyStep(step) {
+    if (step.kind === 'remove') {
+        try {
+            deleteFileIfExists(step.path);
+            return { outcome: 'applied' };
+        }
+        catch (error) {
+            return { outcome: 'failed', error: describeError(error) };
+        }
+    }
+    const result = writeFileWithCheck(step.path, step.content, { dryRun: false, overwrite: true });
+    if (result.outcome === 'failed') {
+        return { outcome: 'failed', ...(result.error !== undefined && { error: result.error }) };
+    }
+    return { outcome: result.outcome === 'created' ? 'created' : 'applied' };
+}
+function orderPlannedSteps(plan) {
+    const ordered = [
+        ...plan.writes.map((write) => ({ kind: 'write', ...write })),
+        ...plan.removals.map((path) => ({ kind: 'remove', path })),
+    ];
     if (plan.summary.length > 0) {
-        ordered.push({ path: RELEASE_SUMMARY_FILE, content: plan.summary });
+        ordered.push({ kind: 'write', path: RELEASE_SUMMARY_FILE, content: plan.summary });
     }
     if (plan.tags.length > 0) {
-        ordered.push({ path: RELEASE_TAGS_FILE, content: plan.tags.join('\n') });
+        ordered.push({ kind: 'write', path: RELEASE_TAGS_FILE, content: plan.tags.join('\n') });
     }
     return ordered;
 }
 function describeApplyFailure(args) {
-    const { failedPath, error, applied, unwritten } = args;
+    const { failedStep, error, applied, unwritten } = args;
     const total = applied.length + unwritten.length;
-    const lines = [`Failed to write ${failedPath}: ${error ?? 'unknown error'}`, ''];
+    const verb = failedStep.kind === 'remove' ? 'remove' : 'write';
+    const lines = [`Failed to ${verb} ${failedStep.path}: ${error ?? 'unknown error'}`, ''];
     if (applied.length === 0) {
         lines.push(`The release was not applied. None of its ${total} files were written.`);
         return lines.join('\n');

package/dist/esm/releasePrepareTargets.d.ts

@@ -0,0 +1,47 @@
+import { type TargetPrepareSettings } from './prepareTarget.js';
+import type { ReleasePlan } from './releasePlan.js';
+import type { ReleaseTarget, ReleaseType } from './types.js';
+/** The targets of a prepare run and the settings that they share. */
+export interface TargetPrepareConfig {
+    targets: ReleaseTarget[];
+    settings: TargetPrepareSettings;
+}
+/** Options for the release preparation workflow. */
+export interface TargetPrepareOptions {
+    /**
+     * 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;
+    /** Level of the release, in place of the level that the changelog items call for; it doesn't trigger a release. */
+    bumpOverride?: ReleaseType;
+    /**
+     * If true, plan release-notes previews under each released target's `docs/` (`README.v{version}.md` and
+     * `RELEASE_NOTES.v{version}.md`) from its changelog entries. Requires `changelogJson.enabled`; when disabled, the
+     * plan records a warning and doesn't plan any previews.
+     */
+    withReleaseNotes?: boolean;
+    /**
+     * Ids of the targets from which the release starts; the run plans the named package targets and their transitive
+     * dependents, and each named composite, which reads its own window. Present only for a narrowed run, which skips
+     * every composite that it doesn't name.
+     */
+    only?: readonly string[];
+    /**
+     * Explicit versions (canonical `N.N.N`), keyed by package target id. Each named target starts the release and
+     * releases at its version, which takes precedence over `bumpOverride` and `force`.
+     */
+    setVersions?: ReadonlyMap<string, string>;
+}
+/**
+ * Plans a release over a list of targets, without writing any file.
+ *
+ * 1. Selects the planned package and directory targets: every one, or, under `only`, those named and their transitive
+ *    dependents.
+ * 2. Reads each planned target's history and decides its direct release.
+ * 3. Propagates bumps to dependents, asserts the baselines that matter, and sorts the release set topologically.
+ * 4. Plans each release in dependency order.
+ * 5. Prepares each composite after every package target, unless `only` narrowed the run without naming it.
+ * 6. Renders the format command over the modified files.
+ */
+export declare function releasePrepareTargets(config: TargetPrepareConfig, options: TargetPrepareOptions): ReleasePlan;