@williamthorsen/release-kit 10.4.4 → 10.6.0

package/dist/esm/formatPrivateSkip.d.ts

@@ -1,2 +1,8 @@
 import type { ResolvedTag } from './resolveReleaseTags.js';
+/**
+ * Format the warning emitted when a release tag's workspace is private and therefore skipped.
+ *
+ * Shared by `release-kit publish` and `release-kit create-github-release` so the skip wording
+ * is defined once and stays identical across both commands.
+ */
 export declare function formatPrivateSkip(resolvedTag: Pick<ResolvedTag, 'tag' | 'workspacePath'>): string;

package/dist/esm/generateChangelogs.d.ts

@@ -1,7 +1,32 @@
 import type { WorkspaceConfig } from './types.js';
+/**
+ * Build a git-cliff tag pattern from one or more tag prefixes.
+ *
+ * Single-prefix input preserves the historical `<prefix>[0-9].*` shape. Multi-prefix input
+ * returns `(prefix1|prefix2|...)[0-9].*` so git-cliff's regex-based `--tag-pattern` accepts
+ * tags under any listed prefix. Each prefix is regex-escaped so metacharacters in operator-
+ * supplied legacy prefixes cannot alter the pattern's meaning.
+ *
+ * @param tagPrefixes - Tag prefixes to match as a union (must contain at least one entry).
+ */
 export declare function buildTagPattern(tagPrefixes: readonly string[]): string;
+/**
+ * Return the workspace's derived tag prefix followed by each declared legacy-identity tag
+ * prefix. Shared by `releasePrepareMono` (the production prepare path) and
+ * `validateOverridesCommand` so the two compute byte-equal per-workspace tag-prefix unions.
+ */
 export declare function getAllTagPrefixes(workspace: WorkspaceConfig): string[];
+/**
+ * Options for `buildChangelogEntries`-driven flows that consume git-cliff output.
+ *
+ * The fields here mirror the subset of git-cliff CLI options that the in-package pipeline
+ * still passes through (tag-pattern union, include-path filtering for monorepo workspaces).
+ * `generateChangelog` and `generateChangelogs` (the prior cliff `--output` invokers) are
+ * removed; markdown rendering is now handled by `renderChangelogMarkdown.ts`.
+ */
 export interface GenerateChangelogOptions {
+    /** Tag pattern to match release tags (passed as --tag-pattern to git-cliff). */
     tagPattern?: string;
+    /** Paths to include in the changelog (passed as --include-path to git-cliff). */
     includePaths?: string[];
 }

package/dist/esm/getCommitsSinceTarget.d.ts

@@ -1,4 +1,20 @@
 import type { Commit } from './types.js';
+/**
+ * Gets commits since the latest baseline tag matching any of the given prefixes.
+ *
+ * Uses `git log` to retrieve commit messages and hashes between the closest reachable
+ * baseline tag and HEAD. When no tag matches any prefix, all commits reachable from HEAD
+ * are returned.
+ *
+ * Callers must pass at least one prefix; the single-prefix case is the common one (the
+ * workspace's derived prefix). Multiple prefixes are used to include historical tag prefixes
+ * from `legacyIdentities`.
+ *
+ * @param tagPrefixes - Tag prefixes to search as a union (e.g., `['core-v', 'old-core-v']`).
+ * @param paths - Optional glob patterns to filter commits by path (appended after `--` in `git log`).
+ *   Path patterns use POSIX-style forward slashes; Windows compatibility is not guaranteed.
+ * @returns An object with the found tag (if any) and the list of commits.
+ */
 export declare function getCommitsSinceTarget(tagPrefixes: readonly string[], paths?: string[]): {
     tag: string | undefined;
     commits: Commit[];

package/dist/esm/hasPrettierConfig.d.ts

@@ -1 +1,7 @@
+/**
+ * Detects whether the repo has a Prettier configuration.
+ *
+ * Checks for config files in the working directory and for a `"prettier"` key
+ * in the root `package.json`. Returns `true` if any indicator is found.
+ */
 export declare function hasPrettierConfig(): boolean;

package/dist/esm/help/prepareHelp.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Single source of truth for the `release-kit prepare` help text. Imported by the bin
+ * dispatcher and asserted by the help drift guard test; kept free of import-time side
+ * effects so both can load it.
+ */
 export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Override the bump type for all workspaces\n  --set-version=X.Y.Z   Set an explicit version; bypasses commit-derived bumps. In monorepo\n                         mode it requires --only, and is rejected when a 'project' block is configured.\n  --force               Release even when no commits or no bump-worthy commits exist\n                         since the last tag. In monorepo and project mode, defaults to\n                         patch when --bump is not given; use --bump=X for a different\n                         level. In single-package mode, a bare --force is rejected \u2014\n                         pass --bump=major|minor|patch.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).\n                         When a 'project' block is configured, the project release is skipped.\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
+/** Prints the prepare command's help text. */
 export declare function showPrepareHelp(): void;

package/dist/esm/init/checks.d.ts

@@ -1,7 +1,11 @@
+/** Result of an eligibility check. */
 export interface CheckResult {
     ok: boolean;
     message?: string;
 }
+/** Verify the current directory is inside a git repository. */
 export declare function isGitRepo(): CheckResult;
+/** Verify that package.json exists in the current directory. */
 export declare function hasPackageJson(): CheckResult;
+/** Verify that the project uses pnpm (has pnpm-lock.yaml or packageManager field). */
 export declare function usesPnpm(): CheckResult;

package/dist/esm/init/detectRepoType.d.ts

@@ -1,2 +1,9 @@
+/** Repo layout type. */
 export type RepoType = 'monorepo' | 'single-package';
+/**
+ * Detect whether the current directory is a monorepo or a single-package repo.
+ *
+ * Returns `'monorepo'` if `pnpm-workspace.yaml` exists or `package.json` has a `workspaces` field.
+ * Otherwise returns `'single-package'`.
+ */
 export declare function detectRepoType(): RepoType;

package/dist/esm/init/initCommand.d.ts

@@ -3,5 +3,11 @@ interface InitOptions {
     force: boolean;
     withConfig: boolean;
 }
+/**
+ * Run the `release-kit init` command.
+ *
+ * Checks eligibility, detects repo type, scaffolds files, and prints next steps.
+ * Returns the process exit code (0 for success, 1 for failure).
+ */
 export declare function initCommand({ dryRun, force, withConfig }: InitOptions): number;
 export {};

package/dist/esm/init/parseJsonRecord.d.ts

@@ -1 +1,5 @@
+/**
+ * Parse a JSON string and return the result if it is a plain object (Record<string, unknown>).
+ * Returns `undefined` if parsing fails or the result is not a plain object.
+ */
 export declare function parseJsonRecord(raw: string): Record<string, unknown> | undefined;

package/dist/esm/init/scaffold.d.ts

@@ -1,4 +1,4 @@
-import type { WriteResult } from '@williamthorsen/nmr-core';
+import { type WriteResult } from '@williamthorsen/nmr-core';
 import type { RepoType } from './detectRepoType.js';
 interface ScaffoldOptions {
     repoType: RepoType;
@@ -6,6 +6,8 @@ interface ScaffoldOptions {
     overwrite: boolean;
     withConfig: boolean;
 }
+/** Copy the bundled cliff.toml.template to `.config/git-cliff.toml` in the target repo. */
 export declare function copyCliffTemplate(dryRun: boolean, overwrite: boolean): WriteResult;
+/** Scaffold release-kit files for the target repo. Returns a result for each file attempted. */
 export declare function scaffoldFiles({ repoType, dryRun, overwrite, withConfig }: ScaffoldOptions): WriteResult[];
 export {};

package/dist/esm/init/templates.d.ts

@@ -1,5 +1,18 @@
 import type { RepoType } from './detectRepoType.js';
+/** Generate the `.config/release-kit.config.ts` starter config with TODOs for customization. */
 export declare function releaseConfigScript(repoType: RepoType): string;
+/**
+ * Generate the publish.yaml GitHub Actions entry-point workflow.
+ *
+ * The `permissions` block is present for explicitness; the reusable workflow declares its own
+ * permissions, so GitHub uses those rather than the caller's block.
+ */
 export declare function publishWorkflow(repoType: RepoType): string;
+/**
+ * Generate the create-github-release.yaml GitHub Actions caller workflow.
+ *
+ * Fires on tag push and delegates to the reusable workflow under `contents: write`.
+ */
 export declare function createGithubReleaseWorkflow(repoType: RepoType): string;
+/** Generate the release.yaml GitHub Actions workflow. */
 export declare function releaseWorkflow(repoType: RepoType): string;

package/dist/esm/injectReleaseNotesIntoReadme.d.ts

@@ -1,9 +1,23 @@
 import type { ChangelogEntry } from './types.js';
+/** Rendered artifacts produced by `renderInjectedReadme`. */
 export interface RenderedInjectedReadme {
+    /** The README with the release-notes section injected at the marker position. */
     injectedReadme: string;
+    /**
+     * The standalone release-notes markdown for the target version (trimmed), prefixed with a
+     * labeled `## Release notes — v{version} ({date})` heading so the file is self-identifying.
+     * The GitHub-release body is rendered separately (without this heading) by `createGithubRelease`.
+     */
     releaseNotesMarkdown: string;
 }
+/**
+ * Discriminated reason no release notes were rendered for a tag.
+ *
+ * Shares the vocabulary of `CreateReleaseSkipReason` in `createGithubRelease.ts`, which classifies
+ * the same two conditions on the GitHub-release path.
+ */
 export type RenderInjectedReadmeSkipReason = 'no-entry' | 'empty-body';
+/** Discriminated outcome of rendering release notes for a tag. */
 export type RenderInjectedReadmeResult = {
     status: 'rendered';
     rendered: RenderedInjectedReadme;
@@ -12,7 +26,32 @@ export type RenderInjectedReadmeResult = {
     reason: RenderInjectedReadmeSkipReason;
     version: string;
 };
+/**
+ * Renders a README with release notes injected at the marker position, and the standalone
+ * release-notes markdown, from an already-loaded README string and an in-memory entry set.
+ *
+ * This is the pure rendering core: it reads nothing, writes nothing, and reports nothing, so a
+ * caller holding entries a release has computed but not yet written gets the same result as one
+ * rendering from a saved file, and each caller words a skip for its own output.
+ *
+ * Carries the version on a skip because both callers name it in their message and only this
+ * function has derived it from the tag.
+ */
 export declare function renderInjectedReadmeFromEntries(readme: string, entries: readonly ChangelogEntry[], tag: string, sectionOrder?: string[]): RenderInjectedReadmeResult;
+/**
+ * Path-taking wrapper over {@link renderInjectedReadmeFromEntries} for callers rendering from a
+ * saved `changelog.json`, such as the publish-time injection flow.
+ *
+ * Adds the two skip conditions that only a file can present: the changelog is missing, or it does
+ * not parse. Warns on every skip, its own and the renderer's alike, because the publish path has
+ * no other channel for the message.
+ */
 export declare function renderInjectedReadme(readme: string, changelogJsonPath: string, tag: string, sectionOrder?: string[]): RenderedInjectedReadme | undefined;
+/**
+ * Inject release notes into a README and return the original content for restoration.
+ *
+ * Returns the original README content, or `undefined` if injection was skipped.
+ */
 export declare function injectReleaseNotesIntoReadme(readmePath: string, changelogJsonPath: string, tag: string, sectionOrder?: string[]): string | undefined;
+/** Find the README file in a workspace directory. */
 export declare function resolveReadmePath(workspacePath: string): string | undefined;

package/dist/esm/injectSection.d.ts

@@ -1 +1,7 @@
+/**
+ * Replace or insert a delimited section in file content.
+ *
+ * When markers exist, replaces the content between them. When absent, prepends the section
+ * (with markers) at the top of the content. The function is pure — no file I/O.
+ */
 export declare function injectSection(content: string, key: string, injection: string): string;

package/dist/esm/loadConfig.d.ts

@@ -1,15 +1,61 @@
 import type { MonorepoReleaseConfig, ReleaseConfig, ReleaseKitConfig, WorkTypeConfig } from './types.js';
+/** Path of the root `package.json` consulted when validating a `project` block. */
 export declare const ROOT_PACKAGE_JSON_PATH = "package.json";
+/**
+ * Read the root `package.json` and return its `version` field.
+ *
+ * Returns `{ exists: false }` when the file is missing, `{ exists: true, version: undefined }`
+ * when the file exists but has no `version` field, and `{ exists: true, version }` when both
+ * are present. The caller (`mergeMonorepoConfig`) decides whether the situation is an error.
+ */
 export declare function readRootPackageVersion(): {
     exists: boolean;
     version: string | undefined;
 };
+/** The path where the consumer-facing config file is expected. */
 export declare const CONFIG_FILE_PATH = ".config/release-kit.config.ts";
+/**
+ * Loads the config file at `.config/release-kit.config.ts`, returning the raw config object, or `undefined` when the
+ * file does not exist. Throws when the file exists but cannot be imported, or exports neither a default nor a named
+ * `config`.
+ */
 export declare function loadConfig(): Promise<unknown>;
+/**
+ * Information about the root `package.json` passed into `mergeMonorepoConfig` when a
+ * `project` block is configured. The async I/O lives in `readRootPackageVersion`; this
+ * function stays a pure transformation.
+ */
 export interface RootPackageInfo {
     exists: boolean;
     version: string | undefined;
 }
+/**
+ * Resolves a final monorepo config from discovered workspaces and an optional user config overlay.
+ *
+ * Merging rules:
+ * - `workspaces`: match overlay entries by `dir` against discovered list; `shouldExclude: true`
+ *   removes the workspace; unlisted packages keep defaults.
+ * - `workTypes`: shallow merge — consumer entries override or add to defaults by key.
+ * - `versionPatterns`: consumer value replaces defaults entirely.
+ * - `formatCommand`, `cliffConfigPath`, `scopeAliases`: consumer value wins.
+ * - `project`: present iff `userConfig.project` is declared. Resolves `tagPrefix` to
+ *   `DEFAULT_PROJECT_TAG_PREFIX` and `paths` to the union of the retained workspaces' `paths`
+ *   when omitted. Requires `rootPackage` to be passed and to contain a valid `version` field;
+ *   throws otherwise. The resolved prefix is included in the strict-prefix collision check
+ *   across all workspace and retired-package prefixes.
+ */
 export declare function mergeMonorepoConfig(discoveredPaths: string[], userConfig: ReleaseKitConfig | undefined, rootPackage?: RootPackageInfo): MonorepoReleaseConfig;
+/**
+ * Resolves a final single-package config from an optional user config overlay.
+ *
+ * Rejects a configured `project` block: project-level releases are a monorepo-only feature,
+ * since the implicit "all non-excluded workspaces contribute" rule is meaningless in a
+ * single-package repo.
+ */
 export declare function mergeSinglePackageConfig(userConfig: ReleaseKitConfig | undefined): ReleaseConfig;
+/**
+ * Merge consumer work-type overrides onto `DEFAULT_WORK_TYPES`.
+ *
+ * Preserves the declaration order of defaults; net-new consumer keys append at the end.
+ */
 export declare function resolveWorkTypes(userWorkTypes?: ReleaseKitConfig['workTypes']): Record<string, WorkTypeConfig>;

package/dist/esm/loadValidatedConfig.d.ts

@@ -1,4 +1,8 @@
 import type { ReleaseKitConfig } from './types.js';
+/**
+ * Outcome of loading and validating the consumer config file. `missing` is not reported
+ * here — whether an absent config file is an error is the caller's call.
+ */
 export type LoadValidatedConfigResult = {
     status: 'invalid';
 } | {
@@ -7,4 +11,8 @@ export type LoadValidatedConfigResult = {
     status: 'ok';
     config: ReleaseKitConfig;
 };
+/**
+ * Load `.config/release-kit.config.ts` and validate it against the shared schema,
+ * reporting load failures and validation errors to stderr.
+ */
 export declare function loadValidatedConfig(): Promise<LoadValidatedConfigResult>;

package/dist/esm/packsPath.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reports whether npm would place `path` in the published tarball, given a package.json `files` value.
+ *
+ * An absent or malformed `files` value packs everything, so it reports `true`; an empty array packs nothing
+ * beyond the files npm always includes, so it reports `false`. An entry naming an ancestor directory covers
+ * everything beneath it, which is how `files: ["dist/*"]` ships `dist/esm/index.js`, so every ancestor prefix
+ * of `path` is tested rather than `path` alone.
+ *
+ * Two approximations of npm's packing rules remain, both failing toward a silent pass: a negation entry
+ * (`!dist/*.map`) never counts toward inclusion, because gitignore-style ordered negation is not modeled; and a
+ * repo controlling its tarball through `.npmignore` alone declares no `files` field, so it reports `true`
+ * without the ignore file being read. For a check that warns about an omission, a missed report costs less than
+ * a false one.
+ */
+export declare function packsPath(filesField: unknown, path: string): boolean;

package/dist/esm/packsPath.js

@@ -0,0 +1,47 @@
+export function packsPath(filesField, path) {
+    if (!isStringArray(filesField))
+        return true;
+    const prefixes = listAncestorPrefixes(path);
+    return filesField.some((entry) => {
+        const pattern = compileEntry(entry);
+        return pattern !== undefined && prefixes.some((prefix) => pattern.test(prefix));
+    });
+}
+const GLOB_TOKEN_PATTERN = /\*\*\/|\*\*|\*|\?|[^*?]+/g;
+function compileEntry(entry) {
+    if (entry.startsWith('!'))
+        return undefined;
+    const normalized = entry.replace(/^\.?\//, '').replace(/\/+$/, '');
+    if (normalized === '')
+        return undefined;
+    return new RegExp(`^${translateGlob(normalized)}$`);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+function listAncestorPrefixes(path) {
+    const segments = path.split('/');
+    return segments.map((_segment, index) => segments.slice(0, index + 1).join('/'));
+}
+function translateGlob(pattern) {
+    let source = '';
+    for (const [token] of pattern.matchAll(GLOB_TOKEN_PATTERN)) {
+        switch (token) {
+            case '**/':
+                source += String.raw `(?:[^/]*\/)*`;
+                break;
+            case '**':
+                source += '.*';
+                break;
+            case '*':
+                source += '[^/]*';
+                break;
+            case '?':
+                source += '[^/]';
+                break;
+            default:
+                source += RegExp.escape(token);
+        }
+    }
+    return source;
+}

package/dist/esm/parseCommitMessage.d.ts

@@ -1,10 +1,52 @@
 import type { Commit, ParsedCommit, WorkTypeConfig } from './types.js';
+/** Regex patterns stripped from the start of commit messages before parsing. */
 export declare const COMMIT_PREPROCESSOR_PATTERNS: readonly RegExp[];
+/**
+ * Regex source for the pipe-prefixed scope atom (the `web` in `web|feat: ...`).
+ *
+ * Deliberately permissive: `*` is the sanctioned structural scope for changes spanning every
+ * workspace, so the atom admits any run of non-pipe characters rather than word characters.
+ * `cliff.toml.template` embeds the same atom in every ticketed commit parser, and
+ * `cliffConfigAlignment.unit.test.ts` asserts that parity — exported so neither side can drift.
+ */
 export declare const PIPE_SCOPE_SOURCE = "[^|]+";
+/** Surface where a `!`/`BREAKING CHANGE:` policy violation was detected. */
 export type PolicyViolationSurface = 'prefix' | 'body';
+/**
+ * Callback invoked when `parseCommitMessage` detects a `!`-policy violation.
+ *
+ * Two-tier policy: at write-time (commit-msg hook, OOS for ticket #355), violations are
+ * rejected outright; at release-time (this parser), violations are warn-and-continue so
+ * legacy log entries don't block releases. Callers (`decideRelease`, `releasePrepareMono`,
+ * etc.) collect callback invocations and surface them in the release report.
+ */
 export type PolicyViolationHandler = (commit: Commit, type: string, surface: PolicyViolationSurface) => void;
+/** Optional configuration for `parseCommitMessage` beyond the core inputs. */
 export interface ParseCommitMessageOptions {
+    /**
+     * Per-type breaking-policy lookup keyed by canonical type name. Missing entries are
+     * treated as `'optional'` for backward compatibility with consumers that have not
+     * supplied policies.
+     */
     breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    /** Receives policy-violation notifications. See {@link PolicyViolationHandler}. */
     onPolicyViolation?: PolicyViolationHandler;
 }
+/**
+ * Parse a commit message into structured metadata.
+ *
+ * Supports three formats:
+ * - `type: description`
+ * - `scope|type: description` (pipe-prefixed scope)
+ * - `type(scope): description` (conventional commit parenthesized scope)
+ *
+ * Resolves aliases (e.g., `feature` → `feat`) using the provided work-type configs and the
+ * canonical aliases list. Resolves scope aliases when a `scopeAliases` map is provided.
+ * Detects breaking changes via `type!:` or `BREAKING CHANGE:` in the message.
+ *
+ * `!`-policy enforcement is **release-time tolerant**: when the resolved type's policy
+ * forbids `!`, the marker is dropped from the parse (`breaking: false`) and
+ * `onPolicyViolation` is invoked. When the policy requires `!`, a bare type triggers the
+ * same warning path. The strict write-time gate (commit-msg hook) is out of scope.
+ */
 export declare function parseCommitMessage(message: string, hash: string, workTypes: Record<string, WorkTypeConfig>, scopeAliases?: Record<string, string>, options?: ParseCommitMessageOptions): ParsedCommit | undefined;

package/dist/esm/parseRequestedTags.d.ts

@@ -1 +1,8 @@
+/**
+ * Parse 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.
+ */
 export declare function parseRequestedTags(flagValue: string | undefined): string[] | undefined;

package/dist/esm/planReleaseNotesPreviews.d.ts

@@ -1,13 +1,33 @@
 import type { PlannedWrite } from './releasePlan.js';
 import type { ChangelogEntry } from './types.js';
+/** Options for `planReleaseNotesPreviews`. */
 export interface PlanReleaseNotesPreviewsOptions {
+    /** Workspace root directory beneath which `docs/` is created. */
     workspacePath: string;
+    /** Full release tag (e.g., `release-kit-v1.0.0`); used to extract the version for filenames. */
     tag: string;
+    /** The workspace's changelog entries as the release will leave them, merged but not yet written. */
     entries: readonly ChangelogEntry[];
+    /** 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. */
 export interface ReleaseNotesPreviewsPlan {
     writes: PlannedWrite[];
     warnings: string[];
 }
+/**
+ * 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.
+ *
+ * Renders from the entries 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`.
+ */
 export declare function planReleaseNotesPreviews(options: PlanReleaseNotesPreviewsOptions): ReleaseNotesPreviewsPlan;

package/dist/esm/planVersionBump.d.ts

@@ -1,9 +1,21 @@
 import type { PlannedWrite } from './releasePlan.js';
 import type { ReleaseType } from './types.js';
+/** A version change computed for a workspace's package files but not yet written. */
 export interface VersionBumpPlan {
     currentVersion: string;
     newVersion: string;
     writes: PlannedWrite[];
 }
+/**
+ * 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.
+ */
 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.
+ */
 export declare function planVersionSet(packageFiles: readonly string[], newVersion: string): VersionBumpPlan;

package/dist/esm/prepareCommand.d.ts

@@ -30,6 +30,7 @@ export declare const prepareFlagSchema: {
         type: "boolean";
     };
 };
+/** Parses CLI arguments into structured options. Prints a usage error and exits on invalid input. */
 export declare function parseArgs(argv: string[]): {
     dryRun: boolean;
     force: boolean;
@@ -39,4 +40,13 @@ export declare function parseArgs(argv: string[]): {
     setVersion: string | undefined;
     withReleaseNotes: boolean;
 };
+/**
+ * Orchestrates the CLI `prepare` command.
+ *
+ * 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`.
+ */
 export declare function prepareCommand(argv: string[]): Promise<void>;

package/dist/esm/previewTagPrefixes.d.ts

@@ -1,30 +1,50 @@
-import type { UndeclaredTagPrefix } from './detectUndeclaredTagPrefixes.js';
+import { type UndeclaredTagPrefix } from './detectUndeclaredTagPrefixes.js';
+/** One workspace's preview row in the tag-prefix preview. */
 export interface TagPrefixPreviewRow {
+    /** Workspace-relative directory path (e.g., `packages/core`). */
     workspacePath: string;
+    /** Directory basename (e.g., `core`). */
     dir: string;
+    /** The derived tag prefix, or `null` when derivation failed. */
     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. */
     derivedTagCount: number;
+    /** One entry per declared legacy prefix, with its current tag count. */
     legacyEntries: LegacyTagPrefixEntry[];
 }
+/** A single declared legacy prefix and its tag count. */
 export interface LegacyTagPrefixEntry {
     prefix: string;
     tagCount: number;
 }
+/** A declared retired package plus its current tag count. */
 export interface RetiredPackagePreviewEntry {
     name: string;
     tagPrefix: string;
     successor?: string;
     tagCount: number;
 }
+/** A tag-prefix collision between two or more workspaces. */
 export interface TagPrefixCollision {
     tagPrefix: string;
     workspacePaths: string[];
 }
+/** Aggregate preview of tag-prefix state across all workspaces. */
 export interface TagPrefixPreview {
     workspaces: TagPrefixPreviewRow[];
     collisions: TagPrefixCollision[];
     undeclaredCandidates: UndeclaredTagPrefix[];
     retiredPackages: RetiredPackagePreviewEntry[];
 }
+/**
+ * Build a structured preview of tag-prefix state for every discovered workspace.
+ *
+ * Discovers workspaces via `discoverWorkspaces()`, derives each workspace's tag prefix
+ * via `deriveWorkspaceConfig()`, and records the derivation error on failure rather than aborting.
+ * Loads `.config/release-kit.config.ts` to surface declared legacy prefixes per workspace,
+ * scans local git tags for undeclared candidate prefixes via `detectUndeclaredTagPrefixes`,
+ * and reports collisions across successfully-derived prefixes.
+ */
 export declare function previewTagPrefixes(): Promise<TagPrefixPreview>;

package/dist/esm/propagateBumps.d.ts

@@ -1,9 +1,24 @@
 import type { DependencyGraph } from './buildDependencyGraph.js';
 import type { PropagationSource, ReleaseType } from './types.js';
+/** Entry in the full release set produced by propagation. */
 export interface ReleaseEntry {
     releaseType: ReleaseType;
+    /** 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.
+     */
     newVersionOverride?: string;
 }
+/** Map from workspace `dir` to its current version string (read from package.json). */
 export type CurrentVersions = Map<string, string>;
+/**
+ * Walk upward through the dependency graph via BFS, adding `patch` bumps for dependents
+ * not already in the release set with a higher bump.
+ *
+ * Returns the full release set (direct + propagated). Direct entries that also have a
+ * propagated dependency get `propagatedFrom` metadata without changing their bump type.
+ */
 export declare function propagateBumps(directBumps: Map<string, ReleaseEntry>, graph: DependencyGraph, currentVersions: CurrentVersions): Map<string, ReleaseEntry>;

package/dist/esm/publish.d.ts

@@ -4,4 +4,5 @@ export interface PublishOptions {
     dryRun: boolean;
     provenance: boolean;
 }
+/** Publish 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 +1,5 @@
+/**
+ * Orchestrate the CLI `publish` command: parse flags, discover workspaces, resolve tags from HEAD,
+ * detect the package manager, validate `--tags`, and publish each tag with inject/restore lifecycle.
+ */
 export declare function publishCommand(argv: string[]): Promise<void>;

package/dist/esm/pushCommand.d.ts

@@ -1 +1,5 @@
+/**
+ * Orchestrate the CLI `push` command: parse flags, resolve tags from HEAD, and push
+ * the release commit and each tag individually.
+ */
 export declare function pushCommand(argv: string[]): Promise<void>;

package/dist/esm/pushRelease.d.ts

@@ -8,4 +8,10 @@ export interface PushStep {
     ref: string;
     command: readonly [string, ...string[]];
 }
+/**
+ * Push 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).
+ */
 export declare function pushRelease(resolvedTags: ResolvedTag[], options?: PushReleaseOptions): PushStep[];

package/dist/esm/readCurrentVersion.d.ts

@@ -1 +1,2 @@
+/** Read the `version` field from a package.json file. Returns undefined if the file can't be read or parsed. */
 export declare function readCurrentVersion(filePath: string): string | undefined;