@williamthorsen/release-kit 10.4.4 → 10.6.0

package/dist/esm/changelogJsonUtils.js

@@ -1,18 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { isRecord, isUnknownArray } from "./typeGuards.js";
-export function isChangelogItem(value) {
-    if (!isRecord(value))
-        return false;
-    if (typeof value['description'] !== 'string')
-        return false;
-    if (value['body'] !== undefined && typeof value['body'] !== 'string')
-        return false;
-    if (value['breaking'] !== undefined && typeof value['breaking'] !== 'boolean')
-        return false;
-    if (value['hash'] !== undefined && typeof value['hash'] !== 'string')
-        return false;
-    return true;
-}
 export function isChangelogEntry(value) {
     return (isRecord(value) &&
         typeof value['version'] === 'string' &&

package/dist/esm/changelogOverrides.d.ts

@@ -1,53 +1,196 @@
 import type { ChangelogEntry, ChangelogOverride, WorkspaceConfig } from './types.js';
+/** Result of loading an override file: either parsed overrides or a list of structured errors. */
 export type LoadChangelogOverridesResult = {
     overrides: Map<string, ChangelogOverride>;
 } | {
     errors: string[];
 };
+/**
+ * Load and validate the editorial overrides file at `path`.
+ *
+ * - Missing file resolves to an empty map (no-op default; matches "absent file → unchanged behavior").
+ * - Malformed JSON, wrong top-level shape, or any per-entry validation failure surfaces as
+ *   structured errors. Callers decide how to surface them.
+ *
+ * Returns either `{ overrides: Map }` on success or `{ errors: string[] }` on failure. Pure
+ * except for the single file read; performs no other I/O.
+ */
 export declare function loadChangelogOverrides(path: string): LoadChangelogOverridesResult;
+/**
+ * Validate a parsed override record. Returns the parsed `Map` along with any error messages.
+ *
+ * Each error names the offending key (e.g. `overrides['abc']: 'audience' must be one of …`)
+ * so the consumer can locate it in their override file.
+ */
 export declare function validateChangelogOverrides(raw: unknown): {
     overrides: Map<string, ChangelogOverride>;
     errors: string[];
 };
+/**
+ * Format the standard "stale override key" warning. Callers compute the set of stale keys
+ * (keys that didn't match anywhere) and use this helper to surface them uniformly. Centralized
+ * so single-package and monorepo flows produce identical warning text.
+ */
 export declare function formatStaleOverrideKeyWarning(key: string): string;
+/**
+ * Apply overrides to a `ChangelogEntry[]`, returning a new array. Pure: no mutation, no I/O.
+ *
+ * Match algorithm: each override key is treated as a string-prefix against `ChangelogItem.hash`.
+ * - 0 matches → key is recorded as unmatched in this batch (no warning emitted here).
+ * - 1 match → apply each present override field to the matched item, record key as matched.
+ * - 2+ matches → error (ambiguous prefix).
+ *
+ * `matchedKeys` lists the override keys that resolved to exactly one item in this batch.
+ * Callers are responsible for computing stale-key warnings: in a monorepo run, an override
+ * may target a commit that lives in another workspace, so the per-batch zero-match signal is
+ * insufficient on its own. Single-package and monorepo orchestrators format warnings using
+ * `formatStaleOverrideKeyWarning` after aggregating `matchedKeys` across all apply calls.
+ *
+ * v1 audience semantics:
+ * - `'skip'` removes the matched item from its containing section. Empty sections are pruned.
+ *   Versions with zero sections still appear (matches existing "empty workspace" behavior).
+ * - `'all'` and `'dev'` are validated out before reaching the applier.
+ *
+ * Items without a `hash` (synthetic propagation entries) are never matched and pass through.
+ *
+ * The function does not throw; warnings/errors accumulate and are returned alongside the
+ * transformed entries so the caller decides whether to abort or log-and-continue.
+ */
 export declare function applyChangelogOverrides(entries: ChangelogEntry[], overrides: Map<string, ChangelogOverride>): {
     entries: ChangelogEntry[];
     warnings: string[];
     errors: string[];
     matchedKeys: string[];
 };
+/**
+ * Resolve the conventional override-file path for a given scope root.
+ *
+ * `scopeRoot` is the directory at which a scope's other artifacts live (e.g., `'.'` for the
+ * project, `'packages/foo'` for a workspace). The returned path is repo-relative.
+ */
 export declare function resolveOverridePath(scopeRoot: string): string;
+/** Result of {@link loadOverridesForScopes}: per-scope maps plus accumulated load/validation errors. */
 export interface LoadOverridesForScopesResult {
+    /** Project-tier (root) overrides. Empty map when the project file is absent. */
     project: Map<string, ChangelogOverride>;
+    /** Workspace-tier overrides keyed by `workspacePath` (e.g., `'packages/foo'`). Empty map when absent. */
     perWorkspace: Map<string, Map<string, ChangelogOverride>>;
+    /** All load and validation errors across every requested scope, prefixed with the offending file path. */
     errors: string[];
 }
+/**
+ * Load and validate every requested override file in one pass.
+ *
+ * Iterates the configured scope roots, calls {@link loadChangelogOverrides} for each, and
+ * aggregates errors across all files (rather than throwing on the first failure) so a
+ * consumer who edits multiple files at once sees every problem in one report. Missing files
+ * resolve to empty maps — matches the existing single-file behavior.
+ *
+ * The caller is expected to surface a combined error when `errors.length > 0` and abort the
+ * release before any workspace begins writing.
+ */
 export declare function loadOverridesForScopes(scopes: {
     project?: string;
     workspaces?: string[];
 }): LoadOverridesForScopesResult;
+/**
+ * Compose root and workspace override maps into a single effective map for one workspace.
+ *
+ * Byte-equal-key shadowing: when a workspace key string-equals a root key, the workspace
+ * entry wins entirely (no field-level merge) and supplants the root entry in the result.
+ * Different-prefix keys that happen to resolve to the same commit do NOT shadow here — they
+ * fall through to the existing ambiguous-prefix error in {@link applyChangelogOverrides}.
+ *
+ * Pure: never mutates inputs.
+ */
 export declare function composeOverrides(rootEntries: Map<string, ChangelogOverride>, workspaceEntries: Map<string, ChangelogOverride> | undefined): Map<string, ChangelogOverride>;
+/**
+ * Shared override-application context threaded through the per-workspace and project apply
+ * sites. Bundles the loaded per-scope maps with the run-scoped warning aggregators so each
+ * call site can both consume the maps it needs and report into the same warning channel.
+ *
+ * `globalMatchedRootKeys` tracks ROOT keys matched in any apply call. Workspace-sourced
+ * matched keys are not added here — they're tracked locally per workspace because their
+ * stale-key semantics are local (a workspace key that doesn't match in its own workspace is
+ * unambiguously stale and is warned immediately, not aggregated to end-of-run).
+ */
 export interface OverrideContext {
     project: Map<string, ChangelogOverride>;
     perWorkspace: Map<string, Map<string, ChangelogOverride>>;
     overrideWarnings: string[];
     globalMatchedRootKeys: Set<string>;
 }
+/**
+ * Load all per-scope override files (root + every workspace) in one upfront pass, validate
+ * them, and bundle the results with run-scoped warning aggregators. Aborts the release with
+ * a clear error when any file is malformed — checked-in editorial config that does not parse
+ * is a bug, and we want the prepare run to fail before any workspace begins writing.
+ */
 export declare function createOverrideContext(workspaces: WorkspaceConfig[]): OverrideContext;
+/** Per-scope input to {@link validateAllChangelogOverrides}. */
 export interface ChangelogOverrideScope {
+    /** Path to the override file (relative to the repo root). Used to load the file and to attribute findings. */
     filePath: string;
+    /** Commit hashes in this scope's history window. Each override key is matched against these. */
     hashes: readonly string[];
 }
+/** Inputs to {@link validateAllChangelogOverrides}. */
 export interface ValidateAllChangelogOverridesInputs {
+    /**
+     * Project-tier scope (the override file at the repo root).
+     *
+     * The file at `filePath` is loaded once and used in two ways:
+     * - Its overrides are composed into every workspace's apply (root-tier overrides apply globally).
+     * - When `hashes` is provided, the project map is also applied directly to that hash universe
+     *   (project release in monorepo mode, or the package's history in single-package mode).
+     *
+     * Omit when no project file exists (rare — most repos have a root file even if empty).
+     */
     project?: {
         filePath: string;
         hashes?: readonly string[];
     };
+    /** Per-workspace scopes. Each workspace's file applies only to its own hash universe. */
     workspaces?: readonly ChangelogOverrideScope[];
 }
+/** Result of {@link validateAllChangelogOverrides}: aggregated errors and warnings, each prefixed with the file path it pertains to. */
 export interface ValidateAllChangelogOverridesResult {
     errors: string[];
     warnings: string[];
 }
+/**
+ * End-to-end health check across every override file and scope. Pure: takes already-collected
+ * hash universes and returns aggregated findings. The CLI command and any other consumer
+ * (programmatic library callers, future composite checks) wrap this with discovery and I/O.
+ *
+ * When invoked via the standard `validateOverridesCommand` entry point, each scope's
+ * `hashes` is built by `buildChangelogEntries` — the same path `release-kit prepare` walks —
+ * so the match-set is byte-equal to what `prepare` would compute. The tier asymmetry is part
+ * of that contract: workspace-tier keys are stale if they don't match in their own workspace;
+ * root-tier keys are stale only if they don't match in any scope (no workspace AND not the
+ * project release window). Library callers that construct `inputs` directly are responsible
+ * for supplying the same hash universes if they want this guarantee.
+ *
+ * Every returned string is prefixed with the relative override-file path it pertains to so
+ * consumers can locate the offending file without further structuring.
+ */
 export declare function validateAllChangelogOverrides(inputs: ValidateAllChangelogOverridesInputs): ValidateAllChangelogOverridesResult;
+/**
+ * Apply the composed (root + workspace) override map to a workspace's changelog entries and
+ * report stale-key warnings tier-by-tier.
+ *
+ * The composed map is applied in a single {@link applyChangelogOverrides} call. Matched keys
+ * are demultiplexed by source via `Map.has` lookups on the original (uncomposed) maps so the
+ * stale-key semantics stay tier-aware:
+ *
+ * - Workspace-sourced keys (those present in the per-workspace map, regardless of whether
+ *   the root map also has the same byte-equal key) that did NOT match are unambiguously
+ *   stale in their own apply context — push an immediate stale warning naming the key.
+ * - Root-sourced matched keys (present in root, absent from this workspace's map) are added
+ *   to `globalMatchedRootKeys` so the orchestrator's end-of-run loop can dedupe across
+ *   batches and warn only on root keys that matched nowhere.
+ *
+ * Throws when any apply call surfaces an error (e.g. ambiguous prefix). Returns the applied
+ * result so the caller can consume `applied.entries` for downstream rendering.
+ */
 export declare function applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;

package/dist/esm/changelogOverrides.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { extractMigration } from "./extractMigration.js";
 import { isRecord } from "./typeGuards.js";
 const OVERRIDES_FILENAME = '.meta/changelog-overrides.json';
 const VALID_AUDIENCE_VALUES = new Set(['all', 'dev', 'skip']);
@@ -206,6 +207,13 @@ function applyOverrideToItem(item, override) {
     }
     if (override.body !== undefined) {
         result.body = override.body;
+        const migration = extractMigration(override.body);
+        if (migration === undefined) {
+            delete result.migration;
+        }
+        else {
+            result.migration = migration;
+        }
     }
     if (override.breaking !== undefined) {
         result.breaking = override.breaking;

package/dist/esm/checkWorkTypesDrift.d.ts

@@ -1,11 +1,36 @@
+/** URL of the upstream canonical `work-types.json` published by codeassembly. */
 export declare const UPSTREAM_WORK_TYPES_URL = "https://raw.githubusercontent.com/williamthorsen/codeassembly/main/packages/agents/content/skills/_data/work-types.json";
+/** Outcome of a drift check, paired with a human-readable message. */
 export interface DriftCheckResult {
+    /**
+     * Process exit code semantics:
+     * - `0` — match (or upstream missing/transitional, with a warning).
+     * - `1` — drift detected.
+     * - `2` — network error.
+     * - `3` — schema mismatch (upstream JSON does not parse or fails the schema invariants).
+     */
     exitCode: 0 | 1 | 2 | 3;
     message: string;
 }
+/** Minimal injection seam so unit tests can substitute a deterministic fetcher. */
 export interface CheckWorkTypesDriftDependencies {
+    /** Absolute path of the local `work-types.json`. Defaults to the bundled file. */
     localPath?: string;
+    /** HTTP fetcher. Defaults to global `fetch` (Node 18+). */
     fetch?: typeof globalThis.fetch;
+    /** Override the upstream URL (used by tests; production callers should leave default). */
     upstreamUrl?: string;
 }
+/**
+ * Compare the bundled `work-types.json` against the upstream codeassembly canonical and
+ * report drift.
+ *
+ * Failure modes:
+ * - Network error → exit 2 with a diagnostic.
+ * - Upstream 404 → exit 0 with a transitional warning (codeassembly hasn't published the
+ *   JSON yet; the check is informational while migration is in flight).
+ * - Schema mismatch → exit 3 with a diagnostic.
+ * - Drift → exit 1 with a unified-diff-style message.
+ * - Match → exit 0.
+ */
 export declare function checkWorkTypesDrift(dependencies?: CheckWorkTypesDriftDependencies): Promise<DriftCheckResult>;

package/dist/esm/collectPolicyViolations.d.ts

@@ -1,5 +1,14 @@
 import type { PolicyViolationHandler } from './parseCommitMessage.js';
 import type { PolicyViolation } from './types.js';
+/**
+ * Build a fresh `policyViolations` accumulator paired with the `onPolicyViolation` callback
+ * that pushes structured entries into it.
+ *
+ * Used by all three release-prepare orchestrators (`releasePrepare`, `releasePrepareMono`,
+ * `releasePrepareProject`) to collect parser-side `!`-policy violations into a result-attachable
+ * array. Centralizing the callback shape keeps the `commitSubject` extraction rule (`firstLine
+ * post-split`) consistent across orchestrators.
+ */
 export declare function createPolicyViolationCollector(): {
     violations: PolicyViolation[];
     onPolicyViolation: PolicyViolationHandler;

package/dist/esm/commitCommand.d.ts

@@ -1 +1,7 @@
+/**
+ * Orchestrate the CLI `commit` command.
+ *
+ * Reads the tags and summary files produced by `prepare`, stages all
+ * changes, and creates a release commit with a formatted message.
+ */
 export declare function commitCommand(argv: string[]): void;

package/dist/esm/compareVersions.d.ts

@@ -1 +1,8 @@
+/**
+ * Return true when `target` is strictly greater than `current`, comparing major, minor, then patch.
+ *
+ * Equal versions return false. Comparison is numeric (not lexical), so `0.10.0` is greater than `0.9.0`.
+ *
+ * @throws If either version is not canonical `N.N.N` semver.
+ */
 export declare function isForwardVersion(current: string, target: string): boolean;

package/dist/esm/createGithubRelease.d.ts

@@ -1,24 +1,54 @@
+/** Options for creating a GitHub Release. */
 export interface CreateGithubReleaseOptions {
     tag: string;
     changelogJsonPath: string;
     dryRun: boolean;
+    /** Section titles in priority order. When omitted, entry order is preserved. */
     sectionOrder?: string[];
 }
+/**
+ * Discriminated reason a single tag was skipped.
+ *
+ * `'no-entry'` is the umbrella for all "data missing" sub-cases (changelog file not found,
+ * JSON unparseable, version not in changelog) — distinguishing them programmatically adds no
+ * value to the consumer, while the existing `console.warn` messages already discriminate them
+ * for human diagnostics.
+ */
 export type CreateReleaseSkipReason = 'no-entry' | 'no-audience-content' | 'empty-body';
+/** Discriminated outcome of attempting to create a single GitHub Release. */
 export type CreateReleaseResult = {
     status: 'created';
 } | {
     status: 'skipped';
     reason: CreateReleaseSkipReason;
 };
+/**
+ * Create a GitHub Release from changelog.json using the `gh` CLI.
+ *
+ * Reads the changelog JSON, finds the entry matching the tag's version, renders all-audience
+ * release notes, and creates the release. Returns a discriminated `{status: 'skipped', reason}`
+ * (with a warning) when the changelog entry is missing, the entry has no all-audience content,
+ * or the rendered body is empty. Throws when the `gh` CLI invocation itself fails so callers
+ * can surface the failure rather than exit 0 silently.
+ */
 export declare function createGithubRelease(options: CreateGithubReleaseOptions): CreateReleaseResult;
+/** Outcome of a `createGithubReleases` invocation. */
 export interface CreateGithubReleasesOutcome {
+    /** Tags for which a Release was created (or would be, under `--dry-run`). */
     created: string[];
+    /** Tags that were skipped, paired with the discriminated reason for each skip. */
     skipped: Array<{
         tag: string;
         reason: CreateReleaseSkipReason;
     }>;
 }
+/**
+ * Create GitHub Releases for each provided tag.
+ *
+ * Per-tag soft-fails (missing changelog entry, no all-audience content, empty rendered body) are
+ * recorded in `skipped` with their discriminated reason and do not throw. Hard failures from the
+ * `gh` CLI itself throw and short-circuit the loop so callers can surface them.
+ */
 export declare function createGithubReleases(tags: Array<{
     tag: string;
     workspacePath: string;

package/dist/esm/createGithubReleaseCommand.d.ts

@@ -1 +1,8 @@
+/**
+ * Orchestrate the CLI `create-github-release` command: Create GitHub Releases from changelog.json
+ * for tags on HEAD (or a comma-separated `--tags` subset), without requiring npm publish.
+ *
+ * Private/unpublishable workspaces are skipped with a warning and never get a Release, matching
+ * `release-kit publish`; an all-private tag set is a clean no-op.
+ */
 export declare function createGithubReleaseCommand(argv: string[]): Promise<void>;

package/dist/esm/createTags.d.ts

@@ -2,4 +2,9 @@ export interface CreateTagsOptions {
     dryRun: boolean;
     noGitChecks: boolean;
 }
+/**
+ * Read tag names from the tags file produced by `prepare` and create annotated git tags.
+ *
+ * Returns the list of tag names that were created (or would be created in dry-run mode).
+ */
 export declare function createTags(options: CreateTagsOptions): string[];

package/dist/esm/decideRelease.d.ts

@@ -1,19 +1,30 @@
 import { type PolicyViolationHandler } from './parseCommitMessage.js';
 import type { Commit, ReleaseType, VersionPatterns, WorkTypeConfig } from './types.js';
+/** Inputs to the unified release decision used by both pipelines. */
 export interface DecideReleaseArgs {
     commits: readonly Commit[];
+    /** True when `--force` was passed; treats absence of a natural bump as patch. Defaults to false. */
     force?: boolean | undefined;
+    /** Explicit `--bump=X` override. When set, the level is X regardless of the natural bump. */
     bumpOverride: ReleaseType | undefined;
     workTypes: Record<string, WorkTypeConfig>;
     versionPatterns: VersionPatterns;
     scopeAliases: Record<string, string> | undefined;
+    /** Per-canonical-type breaking-policy lookup. When provided, drives `!` policy enforcement in `parseCommitMessage`. */
     breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    /** Receives policy-violation notifications from `parseCommitMessage`. */
     onPolicyViolation?: PolicyViolationHandler;
+    /**
+     * Skip wordings to use when no commits exist (`noCommits`) or when commits exist but
+     * none parse to a bump-worthy work type (`noBumpWorthy`). Both pipelines pass their
+     * own pre-rendered wordings (with `{name}` / `since` substitutions already applied).
+     */
     skipReasons: {
         noCommits: string;
         noBumpWorthy: string;
     };
 }
+/** Outcome of `decideRelease`: either release at a chosen level or skip with a reason. */
 export type DecideReleaseResult = {
     outcome: 'release';
     releaseType: ReleaseType;
@@ -25,4 +36,30 @@ export type DecideReleaseResult = {
     parsedCommitCount: number;
     unparseableCommits: Commit[] | undefined;
 };
+/**
+ * Apply the unified release-decision algorithm shared by both `releasePrepareProject`
+ * and the per-workspace path in `releasePrepareMono`.
+ *
+ * Algorithm:
+ *   shouldRelease = naturalBump !== undefined OR force === true
+ *   releaseLevel  = bumpOverride ?? naturalBump ?? 'patch'
+ *
+ * "natural bump" is the raw output of `determineBumpType` over the parsed commits — it
+ * is `undefined` when no commits exist or when none of the parsed commits map to a
+ * bump-worthy work type. Note that this differs from `determineBumpFromCommits`, which
+ * applies a patch floor whenever any commits exist; the patch floor is intentionally
+ * not applied here so that `--bump=X` and `--force` remain orthogonal (the floor is
+ * applied only when `--force` is set, by virtue of the `naturalBump ?? 'patch'`
+ * fallback in the release-level expression above).
+ *
+ * `parsedCommitCount` and `unparseableCommits` are returned in both branches so callers
+ * can surface diagnostic data uniformly regardless of skip/release outcome.
+ *
+ * Scope: this is the canonical algorithm for the orthogonal-flag model in the
+ * monorepo path (`releasePrepareProject` + per-workspace `determineDirectBumps`). The
+ * single-package executor (`releasePrepare`) deliberately retains
+ * `determineBumpFromCommits` and the legacy patch-floor semantics; `prepareCommand`
+ * rejects `--force` without `--bump` in single-package mode to surface that gap. A
+ * future ticket can unify the single-package path; see #313's external plan.
+ */
 export declare function decideRelease(args: DecideReleaseArgs): DecideReleaseResult;

package/dist/esm/defaults.d.ts

@@ -1,13 +1,38 @@
 import type { ChangelogJsonConfig, ReleaseNotesConfig, VersionPatterns, WorkTypeConfig } from './types.js';
+/** Re-export the runtime taxonomy so consumers don't have to depend on `workTypesData.ts` directly. */
 export type { WorkTypesData } from './workTypesData.js';
 export { WORK_TYPES_DATA } from './workTypesData.js';
+/**
+ * Compose the rendered section heading for a work-type entry as `${emoji} ${label}`.
+ *
+ * Single-sourced here so callers (DEFAULT_WORK_TYPES derivation, devOnlySections
+ * derivation, cliff-template drift comparison) cannot disagree on the composition rule.
+ */
 export declare function composeHeader(entry: {
     emoji: string;
     label: string;
 }): string;
+/**
+ * Default work types ordered by canonical priority.
+ *
+ * Derived from `work-types.json` (the canonical SSOT, mirrored at runtime by
+ * `workTypesData.ts`). To change the taxonomy, edit `work-types.json` and update
+ * `workTypesData.ts` to match — a drift test enforces lockstep.
+ */
 export declare const DEFAULT_WORK_TYPES: Record<string, WorkTypeConfig>;
+/**
+ * Per-canonical-type breaking-policy lookup derived from the canonical taxonomy.
+ *
+ * Pass this to `parseCommitMessage` (or an equivalent caller) so the parser knows which
+ * types tolerate `!` and which trigger a policy-violation warning. Missing entries default
+ * to `'optional'` to preserve back-compat for consumers that supply custom work-types.
+ */
 export declare const DEFAULT_BREAKING_POLICIES: Record<string, 'forbidden' | 'optional' | 'required'>;
+/** Default version bump patterns. */
 export declare const DEFAULT_VERSION_PATTERNS: VersionPatterns;
+/** Default configuration for structured changelog JSON generation. */
 export declare const DEFAULT_CHANGELOG_JSON_CONFIG: ChangelogJsonConfig;
+/** Default configuration for release notes consumption. */
 export declare const DEFAULT_RELEASE_NOTES_CONFIG: ReleaseNotesConfig;
+/** Default tag prefix for project-level releases. */
 export declare const DEFAULT_PROJECT_TAG_PREFIX = "v";

package/dist/esm/defineConfig.d.ts

@@ -1,3 +1,12 @@
 import type { ReleaseKitConfig } from './types.js';
 export type { LabelSpec, ReleaseKitConfig, RepoLabelsConfig } from './types.js';
+/**
+ * Type-safe identity function for configuration files.
+ *
+ * Usage in `.config/release-kit.config.ts`:
+ * ```ts
+ * import { defineConfig } from '@williamthorsen/release-kit/config';
+ * export default defineConfig({ ... });
+ * ```
+ */
 export declare function defineConfig(config: ReleaseKitConfig): ReleaseKitConfig;

package/dist/esm/deleteFileIfExists.d.ts

@@ -1 +1,2 @@
+/** Delete a file, silently ignoring the case where it does not exist. */
 export declare function deleteFileIfExists(filePath: string): void;

package/dist/esm/deriveWorkspaceConfig.d.ts

@@ -1,2 +1,11 @@
 import type { WorkspaceConfig } from './types.js';
+/**
+ * Derives a workspace configuration from a workspace-relative path.
+ *
+ * Reads `package.json` at the workspace path to derive the tag identifier from the
+ * package's `name` field (with any leading `@scope/` stripped). The `dir` field remains
+ * the basename of the path — it is the stable internal identifier used for `--only`,
+ * config overrides, and dependency-graph lookups. The `tagPrefix` is `${unscopedName}-v`,
+ * so tags reflect the package identity rather than the directory layout.
+ */
 export declare function deriveWorkspaceConfig(workspacePath: string): WorkspaceConfig;

package/dist/esm/detectPackageManager.d.ts

@@ -1,2 +1,8 @@
 export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'yarn-berry';
+/**
+ * Detect the repo's package manager by checking the `packageManager` field in root `package.json`,
+ * then falling back to lockfile detection, then defaulting to `npm`.
+ *
+ * Yarn v2+ is returned as `'yarn-berry'` to distinguish it from Yarn Classic.
+ */
 export declare function detectPackageManager(): PackageManager;

package/dist/esm/detectUndeclaredTagPrefixes.d.ts

@@ -1,7 +1,25 @@
+/** A candidate tag prefix found in the repo that is not in the known-prefix set. */
 export interface UndeclaredTagPrefix {
+    /** The extracted prefix, including the trailing `-v` (e.g., `'core-v'`). */
     prefix: string;
+    /** Count of tags matching this prefix. */
     tagCount: number;
+    /** Up to `EXAMPLE_TAG_LIMIT` example tag names under this prefix. */
     exampleTags: string[];
+    /**
+     * Heuristic `dir` to suggest when offering a paste-ready config snippet; the prefix with
+     * the trailing `-v` stripped. The operator may need to remap this to the actual workspace
+     * directory basename.
+     */
     suggestedDir: string;
 }
+/**
+ * Scan local git tags for release-shaped tags whose prefix is not in the known set.
+ *
+ * Reads only the local tag list; callers expecting to see recently-fetched remote tags
+ * should `git fetch --tags` first. Returns an empty array when the repo has no tags
+ * or no candidate-shaped tags outside the known set.
+ *
+ * @param knownPrefixes - Union of derived and declared prefixes across all workspaces.
+ */
 export declare function detectUndeclaredTagPrefixes(knownPrefixes: readonly string[]): UndeclaredTagPrefix[];

package/dist/esm/determineBumpFromCommits.d.ts

@@ -1,12 +1,17 @@
 import { type PolicyViolationHandler } from './parseCommitMessage.js';
 import type { Commit, ReleaseType, VersionPatterns, WorkTypeConfig } from './types.js';
+/** Aggregate result of parsing commits and determining the bump type. */
 export interface BumpDetermination {
     releaseType: ReleaseType | undefined;
     parsedCommitCount: number;
     unparseableCommits: Commit[] | undefined;
 }
+/** Optional configuration for parser-policy plumbing. */
 export interface DetermineBumpOptions {
+    /** Per-canonical-type breaking-policy lookup (drives `!` policy enforcement). */
     breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    /** Receives policy-violation notifications from `parseCommitMessage`. */
     onPolicyViolation?: PolicyViolationHandler;
 }
+/** Parse commits, determine bump type, and apply patch floor when commits exist but none parsed. */
 export declare function determineBumpFromCommits(commits: Commit[], workTypes: Record<string, WorkTypeConfig>, versionPatterns: VersionPatterns, scopeAliases: Record<string, string> | undefined, options?: DetermineBumpOptions): BumpDetermination;

package/dist/esm/determineBumpType.d.ts

@@ -1,2 +1,14 @@
 import type { ParsedCommit, ReleaseType, VersionPatterns, WorkTypeConfig } from './types.js';
+/**
+ * Determines the overall bump type from a set of parsed commits.
+ *
+ * Uses `versionPatterns` to decide which commit types trigger major/minor bumps.
+ * The `'!'` sentinel in `versionPatterns.major` means "any breaking commit triggers major".
+ * Any recognized commit type not listed in major or minor patterns defaults to patch.
+ *
+ * @param commits - The parsed commits to analyze.
+ * @param workTypes - The work type configurations to verify recognized types.
+ * @param versionPatterns - Rules for determining major and minor bumps.
+ * @returns The determined release type, or undefined if no commits match a known work type.
+ */
 export declare function determineBumpType(commits: readonly ParsedCommit[], workTypes: Record<string, WorkTypeConfig>, versionPatterns: VersionPatterns): ReleaseType | undefined;

package/dist/esm/discoverWorkspaces.d.ts

@@ -1 +1,13 @@
+/**
+ * Reads `pnpm-workspace.yaml` and resolves its `packages` globs to discover workspace directories.
+ *
+ * Returns an array of workspace-relative directory paths (e.g., `['packages/arrays', 'packages/strings']`).
+ * Only directories containing a `package.json` are included.
+ *
+ * Note: The returned paths are full relative paths from the repo root (e.g., `packages/arrays`,
+ * `libs/core`). These paths are passed directly to `deriveWorkspaceConfig()`, which uses them for all
+ * file path construction and derives the display name via `path.basename()`.
+ *
+ * @returns The discovered workspace paths, or `undefined` if no workspace config is found.
+ */
 export declare function discoverWorkspaces(): Promise<string[] | undefined>;

package/dist/esm/extractMigration.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Extracts the instruction from a commit body's `Migration:` paragraph.
+ *
+ * The first paragraph opening with the label wins: the lede doctrine specifies one labeled
+ * paragraph per body, so a second is ignored rather than appended. The match is anchored and
+ * case-sensitive, so `migration:` and `**Migration:**` yield nothing; the doctrine calls the
+ * label literal, and tolerating variants would let the form drift.
+ *
+ * Newlines inside the paragraph are preserved. The first character is capitalized, which is
+ * inert for the imperative the doctrine requires and repairs the lowercase continuation of a
+ * paragraph written before it. Returns `undefined` when no paragraph carries the label, or when
+ * the label is followed by nothing.
+ */
+export declare function extractMigration(body: string | undefined): string | undefined;

package/dist/esm/extractMigration.js

@@ -0,0 +1,18 @@
+const PARAGRAPH_SEPARATOR = /\n(?:[ \t]*\n)+/;
+const MIGRATION_LABEL = /^Migration:[ \t]*/;
+export function extractMigration(body) {
+    if (body === undefined) {
+        return undefined;
+    }
+    for (const paragraph of body.split(PARAGRAPH_SEPARATOR)) {
+        if (!MIGRATION_LABEL.test(paragraph)) {
+            continue;
+        }
+        const instruction = paragraph.replace(MIGRATION_LABEL, '').trim();
+        if (instruction.length === 0) {
+            return undefined;
+        }
+        return instruction.charAt(0).toUpperCase() + instruction.slice(1);
+    }
+    return undefined;
+}

package/dist/esm/format.d.ts

@@ -1,3 +1,6 @@
+/** Wrap text in ANSI bold. */
 export declare function bold(text: string): string;
+/** Wrap text in ANSI dim. */
 export declare function dim(text: string): string;
+/** Render a section header for separating workspaces in CLI output. */
 export declare function sectionHeader(name: string): string;