@williamthorsen/release-kit 12.0.0 → 13.1.0

package/dist/esm/parseCommitMessage.js

@@ -1,45 +1,44 @@
-export const COMMIT_PREPROCESSOR_PATTERNS = [/^##\s+/, /^#\d+([.-]\d+)?\s+/, /^[A-Z]+-\d+\s+/];
-export const PIPE_SCOPE_SOURCE = '[^|]+';
-const COMMIT_SUBJECT_PATTERN = new RegExp(String.raw `^(?:(${PIPE_SCOPE_SOURCE})\|)?(\w+)(?:\(([^)]+)\))?(!)?:\s*(.*)$`);
+import { compileTemplate, parse, TEMPLATE_CATALOGUE, } from '@williamthorsen/change-grammar';
+const SUBJECT_TEMPLATES = [
+    compileTemplate(TEMPLATE_CATALOGUE.pipedScope),
+    compileTemplate(TEMPLATE_CATALOGUE.conventionalCommits),
+];
 export function parseCommitMessage(message, hash, workTypes, scopeAliases, options) {
     const firstLine = message.split('\n', 1)[0] ?? '';
-    const stripped = stripTicketPrefix(firstLine);
-    const match = stripped.match(COMMIT_SUBJECT_PATTERN);
-    if (!match) {
-        return undefined;
-    }
-    const pipeScope = match[1];
-    const rawType = match[2];
-    const parenthesizedScope = match[3];
-    const breakingMarker = match[4];
-    const description = match[5];
-    if (rawType === undefined || description === undefined) {
-        return undefined;
-    }
-    const resolvedType = resolveType(rawType, workTypes);
-    if (resolvedType === undefined) {
+    const record = parseSubject(firstLine, workTypes);
+    if (record?.type === undefined || record.title === undefined) {
         return undefined;
     }
     const commit = { message, subject: firstLine, hash };
     const breaking = evaluateBreakingPolicy({
         commit,
-        resolvedType,
-        hasPrefixBreaking: breakingMarker === '!',
+        resolvedType: record.type,
+        hasPrefixBreaking: record.breaking === true,
         hasFooterBreaking: message.includes('BREAKING CHANGE:'),
-        policy: options?.breakingPolicies?.[resolvedType] ?? 'optional',
+        policy: options?.breakingPolicies?.[record.type] ?? 'optional',
         onPolicyViolation: options?.onPolicyViolation,
     });
-    const rawScope = pipeScope ?? parenthesizedScope;
+    const rawScope = record.scope;
     const resolvedScope = rawScope !== undefined && scopeAliases !== undefined ? (scopeAliases[rawScope] ?? rawScope) : rawScope;
     return {
         message,
         hash,
-        type: resolvedType,
-        description,
+        type: record.type,
+        description: record.title,
         breaking,
         ...(resolvedScope !== undefined && { scope: resolvedScope }),
     };
 }
+export function parseSubject(subject, workTypes) {
+    const taxonomy = toTaxonomy(workTypes);
+    for (const nodes of SUBJECT_TEMPLATES) {
+        const record = parse(nodes, subject, taxonomy);
+        if (record !== undefined) {
+            return record;
+        }
+    }
+    return undefined;
+}
 export function evaluateBreakingPolicy(inputs) {
     const { commit, resolvedType, hasPrefixBreaking, hasFooterBreaking, policy, onPolicyViolation } = inputs;
     const prefixSurface = inputs.prefixSurface ?? 'prefix';
@@ -52,13 +51,6 @@ export function evaluateBreakingPolicy(inputs) {
         }
         return false;
     }
-    if (policy === 'required') {
-        if (!hasPrefixBreaking) {
-            onPolicyViolation?.(commit, resolvedType, prefixSurface);
-            return false;
-        }
-        return true;
-    }
     return hasPrefixBreaking || hasFooterBreaking;
 }
 export function resolveType(rawType, workTypes) {
@@ -77,10 +69,9 @@ export function resolveType(rawType, workTypes) {
     }
     return undefined;
 }
-function stripTicketPrefix(message) {
-    let result = message;
-    for (const pattern of COMMIT_PREPROCESSOR_PATTERNS) {
-        result = result.replace(pattern, '');
-    }
-    return result;
+function toTaxonomy(workTypes) {
+    return {
+        tiers: [],
+        types: Object.entries(workTypes).map(([key, config]) => ({ aliases: config.aliases ?? [], key, tier: '' })),
+    };
 }

package/dist/esm/parseRequestedTags.d.ts

@@ -1,8 +1,8 @@
 /**
- * Parse the comma-separated `--tags` flag value into a list of requested tag names.
+ * Parses the comma-separated `--tags` flag value into a list of requested tag names.
  *
  * Empty segments (from `--tags=`, leading/trailing commas, or `--tags=,,`) are dropped. When the
- * resulting list is empty, returns `undefined` so the caller treats it as "no filter" — the same
- * behavior as omitting `--tags` entirely.
+ * resulting list is empty, returns `undefined`, and the caller does not filter the tags, as when
+ * `--tags` is omitted.
  */
 export declare function parseRequestedTags(flagValue: string | undefined): string[] | undefined;

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.
  */