@williamthorsen/release-kit 10.4.3 → 10.5.0

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;

package/dist/esm/releaseFiles.d.ts

@@ -1,4 +1,26 @@
+/**
+ * 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
+ * release workflow reads it at this path, so the path and the line-delimited format are a
+ * published contract rather than an internal detail.
+ */
 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.
+ */
 export declare const RELEASE_SUMMARY_FILE = "tmp/.release-summary";
+/** Resolves the tags file against the current working directory, for use in diagnostics. */
 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.
+ *
+ * An empty or blank file yields an empty array; callers decide whether that is an error.
+ */
 export declare function readReleaseTags(): string[];

package/dist/esm/releasePlan.d.ts

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

package/dist/esm/releasePrepare.d.ts

@@ -1,10 +1,50 @@
 import type { ReleasePlan } from './releasePlan.js';
 import type { ReleaseConfig, ReleaseType } from './types.js';
+/**
+ * Options for the release preparation workflow.
+ *
+ * Carries no dry-run flag: preparation only ever computes a plan, and whether that plan is
+ * applied is the caller's decision.
+ */
 export interface ReleasePrepareOptions {
+    /**
+     * Release even when no commits or no bump-worthy commits exist since the last tag
+     * (monorepo only). Orthogonal to `bumpOverride`: when `bumpOverride` is not given,
+     * the release falls back to `patch`.
+     */
     force?: boolean;
+    /** Override the bump type instead of determining it from commits. */
     bumpOverride?: ReleaseType;
+    /**
+     * Explicit target version (canonical `N.N.N`) that bypasses commit-derived bump logic.
+     * Mutually exclusive with `bumpOverride`. In monorepo mode the caller must narrow
+     * `config.workspaces` to a single workspace before invoking.
+     */
     setVersion?: string;
+    /**
+     * Workspace directories the run was narrowed to by `--only` (monorepo only), with
+     * `config.workspaces` already filtered to match. Present only for a narrowed run, which
+     * skips the project release: the project tier rolls up every contributing workspace, and
+     * the narrowing has changed which workspaces those are.
+     */
     only?: string[];
+    /**
+     * If true, write per-workspace release-notes previews under `{workspacePath}/docs/`
+     * (`README.v{version}.md` and `RELEASE_NOTES.v{version}.md`) after each workspace's
+     * `changelog.json` is produced. Requires `config.changelogJson.enabled`; when disabled,
+     * a warning is recorded on the plan and no previews are generated.
+     */
     withReleaseNotes?: boolean;
 }
+/**
+ * Orchestrate the release preparation workflow for a single package.
+ *
+ * 1. Gets commits since the last tag.
+ * 2. Determines the bump type from commits (or uses the override).
+ * 3. Bumps all configured package.json version fields.
+ * 4. Generates changelogs via git-cliff.
+ * 5. Runs the optional format command.
+ *
+ * Returns a structured `PrepareResult` with all data needed for presentation.
+ */
 export declare function releasePrepare(config: ReleaseConfig, options: ReleasePrepareOptions): ReleasePlan;

package/dist/esm/releasePrepareMono.d.ts

@@ -1,4 +1,12 @@
 import type { ReleasePlan } from './releasePlan.js';
 import type { ReleasePrepareOptions } from './releasePrepare.js';
 import type { MonorepoReleaseConfig } from './types.js';
+/**
+ * Orchestrate release preparation for a monorepo with multiple workspaces.
+ *
+ * Phase 1: Determine direct bumps from commits for each workspace.
+ * Phase 2: Build the dependency graph and propagate bumps to dependents.
+ * Phase 2b: Topologically sort the full release set.
+ * Phase 3: Execute bumps and generate changelogs in dependency order.
+ */
 export declare function releasePrepareMono(config: MonorepoReleaseConfig, options: ReleasePrepareOptions): ReleasePlan;

package/dist/esm/releasePrepareProject.d.ts

@@ -1,15 +1,57 @@
 import type { PlannedWrite } from './releasePlan.js';
 import type { ReleasePrepareOptions } from './releasePrepare.js';
 import type { ChangelogOverride, MonorepoReleaseConfig, ProjectPrepareResult } from './types.js';
+/** Inputs to the project-release stage. */
 export interface ReleasePrepareProjectArgs {
+    /** Resolved monorepo config; `config.project` must be defined when this function is called. */
     config: MonorepoReleaseConfig;
     options: ReleasePrepareOptions;
+    /** Mutated in-place to append project-level files (root package.json, root CHANGELOG.md, root changelog.json). */
     modifiedFiles: string[];
+    /** Mutated in-place to append every file this stage intends to write. */
     writes: PlannedWrite[];
+    /** Mutated in-place to append the project tag. */
     tags: string[];
+    /**
+     * Mutated in-place to surface warnings this stage raises that are not override-specific
+     * (currently the release-notes previews' skip reasons). Defaults to a discardable sink.
+     */
     warnings?: string[];
+    /**
+     * Root-tier editorial overrides loaded once at the top of the prepare run. Defaults to an
+     * empty map when omitted (no overrides applied). The project changelog applies only the
+     * root-tier file — per-workspace files describe per-workspace editorial intent and have no
+     * meaning at the aggregated project tier.
+     */
     rootOverrides?: Map<string, ChangelogOverride>;
+    /**
+     * Mutated in-place to surface override warnings (currently empty by design — stale-key
+     * warnings are emitted by the orchestrator after aggregating across batches). Defaults to
+     * a discardable sink when omitted.
+     */
     overrideWarnings?: string[];
+    /**
+     * Mutated in-place: every root-tier override key matched in this stage is added so the
+     * orchestrator can dedupe stale-key warnings across the run. Defaults to a discardable
+     * sink when omitted.
+     */
     globalMatchedRootKeys?: Set<string>;
 }
+/**
+ * Run the project-level release stage.
+ *
+ * Mirrors the per-workspace pipeline shape — find baseline tag → derive bump → bump version →
+ * regenerate CHANGELOG → optionally emit changelog.json and release-notes previews — but
+ * targets the root `package.json` and the root `CHANGELOG.md`. Contributing paths come from
+ * the resolved `project.paths`, which defaults to the union of every (already-filtered)
+ * workspace's `paths`.
+ *
+ * Returns a structured `{ status: 'skipped', skipReason, ... }` result when neither
+ * commits nor `--force` provide a release signal. The caller should attach the returned
+ * result to `PrepareResult.project`. `undefined` is returned only when there is no
+ * configured `project` block — handled at the call site, not here.
+ *
+ * Caller contract: `prepareCommand` rejects `--only` upstream when a project block is
+ * configured, so this orchestrator never has to reason about workspace-narrowing flags.
+ */
 export declare function releasePrepareProject(args: ReleasePrepareProjectArgs): ProjectPrepareResult;

package/dist/esm/renderChangelogMarkdown.d.ts

@@ -1,5 +1,22 @@
 import type { ChangelogEntry } from './types.js';
+/** Options for `renderChangelogMarkdown`. */
 export interface RenderChangelogMarkdownOptions {
+    /** Section titles in canonical order; passed through to `renderReleaseNotesMulti`. */
     sectionOrder?: string[];
 }
+/**
+ * Render `ChangelogEntry[]` into a complete `CHANGELOG.md`-shaped string.
+ *
+ * Format:
+ *   `# Changelog`
+ *   blank line
+ *   `All notable changes …`
+ *   blank line
+ *   per-entry sections (delegated to `renderReleaseNotesMulti`)
+ *   blank line
+ *   footer comment
+ *
+ * Entries are rendered in the order provided; the caller sorts (typically newest-first via
+ * `changelogJsonFile`'s SemVer-aware comparator).
+ */
 export declare function renderChangelogMarkdown(entries: ChangelogEntry[], options?: RenderChangelogMarkdownOptions): string;

package/dist/esm/renderReleaseNotes.d.ts

@@ -1,9 +1,34 @@
 import type { ChangelogAudience, ChangelogEntry, ChangelogSection } from './types.js';
+/** Options for rendering a single changelog entry to markdown. */
 export interface RenderOptions {
+    /** Predicate to filter sections. When absent, all sections are included. */
     filter?: (section: ChangelogSection) => boolean;
+    /** Whether to include the version/date heading. Defaults to `true`. */
     includeHeading?: boolean;
+    /**
+     * Section titles in desired priority order. Known titles are emitted first in this order;
+     * titles not listed preserve their relative position after known ones. When absent, section
+     * order is preserved from the entry.
+     */
     sectionOrder?: string[];
 }
+/**
+ * Create a predicate that matches sections visible to the given audience.
+ *
+ * `"all"` matches only sections with `audience: "all"` (public-facing).
+ * `"dev"` matches all sections (developers see everything).
+ */
 export declare function matchesAudience(audience: ChangelogAudience): (section: ChangelogSection) => boolean;
+/**
+ * Render a single `ChangelogEntry` to markdown.
+ *
+ * Output format mirrors the existing CHANGELOG.md style: an H2 version heading followed by
+ * H3 section headings with bulleted items.
+ */
 export declare function renderReleaseNotesSingle(entry: ChangelogEntry, options?: RenderOptions): string;
+/**
+ * Render multiple `ChangelogEntry` values to a single markdown document.
+ *
+ * Entries are rendered in the order provided; the caller is responsible for sorting.
+ */
 export declare function renderReleaseNotesMulti(entries: ChangelogEntry[], options?: RenderOptions): string;

package/dist/esm/reportPrepare.d.ts

@@ -1,6 +1,20 @@
 import type { PrepareResult } from './types.js';
+/** How the plan was carried out, which decides the tense the report is rendered in. */
 export interface ReportPrepareOptions {
+    /** True when the plan was written to disk; false for a dry run. */
     applied: boolean;
+    /** The format command's failure message, when it ran and failed. */
     formatError?: string;
 }
+/**
+ * Format a release plan into styled terminal output.
+ *
+ * Pure function: accepts structured data, returns a string. Never writes to stdout.
+ * Single-workspace mode (no `name` field) renders flat output; multi-workspace mode
+ * renders section headers per workspace, an optional project section, and a tag summary
+ * at the end.
+ *
+ * Whether the plan was applied is a property of the render, not of the plan: the same plan
+ * produces the dry-run report and the applied report.
+ */
 export declare function reportPrepare(plan: PrepareResult, options: ReportPrepareOptions): string;

package/dist/esm/resolveCliffConfigPath.d.ts

@@ -1 +1,11 @@
+/**
+ * Resolve the git-cliff configuration file path.
+ *
+ * Checks candidates in order: explicit `cliffConfigPath` -> `.config/git-cliff.toml` ->
+ * `cliff.toml` -> bundled `cliff.toml.template`. Returns the first path that exists,
+ * or throws if even the bundled template cannot be found.
+ *
+ * When an explicit `cliffConfigPath` is provided, it is returned as-is without checking
+ * existence, preserving current behavior (git-cliff reports the error if the file is missing).
+ */
 export declare function resolveCliffConfigPath(cliffConfigPath: string | undefined, metaUrl: string): string;

package/dist/esm/resolveCommandTags.d.ts

@@ -1,2 +1,14 @@
-import type { ResolvedTag } from './resolveReleaseTags.js';
+import { type ResolvedTag } from './resolveReleaseTags.js';
+/**
+ * Discover workspaces, resolve release tags from HEAD, validate `--tags` names against the
+ * full resolved tag names (e.g., `nmr-core-v1.3.0`), and return the filtered tag list.
+ * Works in both single-package and monorepo modes. Exits with an error message on any validation
+ * failure — including `deriveWorkspaceConfig()` throws for workspaces missing a `package.json` `name` field.
+ *
+ * In both modes `deriveWorkspaceConfig` is called so `WorkspaceConfig.isPublishable` (read
+ * from `package.json#private`) propagates onto each `ResolvedTag`. Single-package mode now
+ * derives `./package.json`'s workspace config too — consumers that previously relied on
+ * single-package mode skipping the derive step need a `name` field on `./package.json`,
+ * but in practice every npm/pnpm package already has one.
+ */
 export declare function resolveCommandTags(tags: string[] | undefined): Promise<ResolvedTag[]>;

package/dist/esm/resolveReleaseNotesConfig.d.ts

@@ -2,12 +2,26 @@ import type { ReleaseNotesConfig } from './types.js';
 export interface ResolvedReleaseNotesConfig {
     releaseNotes: ReleaseNotesConfig;
     changelogJsonOutputPath: string;
+    /** Section titles in priority order, derived from the merged workTypes record. */
     sectionOrder: string[];
 }
 export interface ResolveReleaseNotesConfigOptions {
+    /**
+     * When `true`, a `loadConfig()` rejection causes `process.exit(1)` rather than a fallback to
+     * defaults. Use from CLI commands whose entire behavior depends on the resolved config (e.g.
+     * `create-github-release`), so a corrupt or unreadable config cannot silently send the command
+     * to the wrong changelog path.
+     */
     strictLoad?: boolean;
 }
+/**
+ * Load and validate the release-kit config.
+ *
+ * By default, falls back to defaults when `loadConfig()` rejects (legacy publish behavior).
+ * When `strictLoad` is `true`, a load failure prints an error and calls `process.exit(1)`.
+ */
 export declare function resolveReleaseNotesConfig(options?: ResolveReleaseNotesConfigOptions): Promise<ResolvedReleaseNotesConfig>;
+/** Extract section headers in declaration order from a merged workTypes record. */
 export declare function deriveSectionOrder(workTypes: Record<string, {
     header: string;
 }>): string[];

package/dist/esm/resolveReleaseTags.d.ts

@@ -3,12 +3,34 @@ export interface ResolvedTag {
     tag: string;
     dir: string;
     workspacePath: string;
+    /**
+     * Whether the workspace this tag belongs to can be published to a registry. Propagated
+     * from the matched `WorkspaceConfig.isPublishable` (monorepo) or from the single-package
+     * workspace config (single-package mode). Consumed by `release-kit publish` to filter the
+     * tag set; other commands ignore it.
+     */
     isPublishable: boolean;
 }
+/** Discriminated argument to `resolveReleaseTags`: exactly one of the two keys is meaningful. */
 type ResolveReleaseTagsArgs = {
     workspaces: readonly WorkspaceConfig[];
 } | {
     singleWorkspace: WorkspaceConfig;
 };
+/**
+ * Resolve release tags pointing at HEAD into publishable package descriptors.
+ *
+ * Pass `{ workspaces }` for monorepo mode: each tag is matched against the workspace
+ * whose `tagPrefix` it starts with, and that workspace's `isPublishable` propagates onto
+ * the `ResolvedTag`. Because `tagPrefix` is derived from `deriveWorkspaceConfig()` (the
+ * same source that produced the tag), encoding and decoding stay colocated.
+ *
+ * Pass `{ singleWorkspace }` for single-package mode: tags like `v1.2.3` are matched and
+ * each carries the workspace's `isPublishable` bit derived from `./package.json#private`.
+ *
+ * The no-arg form is a test-isolation convenience for unit tests that exercise tag
+ * matching without needing `isPublishable` propagation; resolved tags default to
+ * `isPublishable: true`. Production callers should pass one of the named forms.
+ */
 export declare function resolveReleaseTags(args?: ResolveReleaseTagsArgs): ResolvedTag[];
 export {};