@williamthorsen/release-kit 10.4.4 → 10.5.0

package/dist/esm/types.d.ts

@@ -1,58 +1,140 @@
 import { z } from 'zod';
+/** Semver release type for version bumping. */
 export type ReleaseType = 'major' | 'minor' | 'patch';
+/** Target audience for a changelog section. */
 export type ChangelogAudience = 'all' | 'dev';
+/** A single item in a changelog section (typically one commit). */
 export interface ChangelogItem {
     description: string;
+    /** Optional commit body text, with trailing trailer metadata stripped. */
     body?: string;
+    /**
+     * Whether this item represents a breaking change.
+     *
+     * `true` when the commit subject carries the `!` prefix (e.g. `feat!:` or `drop(scope)!:`).
+     * The `BREAKING CHANGE:` body footer is intentionally NOT considered here — only the prefix
+     * `!` marks a changelog item as breaking. Renderers prefix breaking-item bullets with the
+     * marker constructed from `WORK_TYPES_DATA.markers.breaking` (rendered as `🚨 **Breaking:** `
+     * with the canonical SSOT values) to surface them prominently in release notes.
+     */
     breaking?: boolean;
+    /**
+     * Full git commit SHA when known. Captured from git-cliff's `--context` output and
+     * persisted in `changelog.json` so that override files can target items by hash. Synthetic
+     * propagation entries (`buildSyntheticChangelogEntry`, `buildEmptyReleaseEntry`) leave
+     * this field absent — they have no underlying commit.
+     */
     hash?: string;
 }
+/** A grouped section within a changelog entry (e.g., "Features", "Bug fixes"). */
 export interface ChangelogSection {
+    /**
+     * Section title carrying the leading emoji prefix used by `cliff.toml.template` group
+     * definitions (e.g. `"🐛 Bug fixes"`). The `<!-- NN -->` canonical-order HTML comment
+     * is stripped during transform; the emoji remains. Callers that match against `title`
+     * (e.g. `sectionOrder` configs) must include the emoji prefix.
+     */
     title: string;
     audience: ChangelogAudience;
     items: ChangelogItem[];
 }
+/** A single version's changelog data. */
 export interface ChangelogEntry {
     version: string;
     date: string;
     sections: ChangelogSection[];
 }
+/** Configuration for structured changelog JSON generation. */
 export interface ChangelogJsonConfig {
     enabled: boolean;
     outputPath: string;
     devOnlySections: string[];
 }
+/**
+ * Editorial override for a single changelog item, keyed by commit hash (or hash prefix) in
+ * the override file. All fields are optional; an entry with no fields is a validation error.
+ *
+ * `audience` declares the full forward-compatible vocabulary, but only `'skip'` is currently
+ * supported at runtime. `'all'` and `'dev'` reclassification is reserved for a v2 follow-up
+ * and rejected by the validator with an explicit "not yet supported" error so the on-disk
+ * format remains stable through the v1→v2 transition.
+ */
 export interface ChangelogOverride {
     audience?: 'all' | 'dev' | 'skip';
     description?: string;
     body?: string;
     breaking?: boolean;
 }
+/** On-disk shape of `.meta/changelog-overrides.json`: a flat record keyed by commit hash or prefix. */
 export type ChangelogOverridesFile = Record<string, ChangelogOverride>;
+/** Configuration for release notes consumption (README injection). */
 export interface ReleaseNotesConfig {
     shouldInjectIntoReadme: boolean;
 }
+/**
+ * Project-release config after merging defaults. Mirrors the `ReleaseNotesConfig`/
+ * `ResolvedReleaseNotesConfig`-style split: optional fields in `ProjectConfig` become
+ * required in `ResolvedProjectConfig`.
+ */
 export interface ResolvedProjectConfig {
+    /**
+     * Resolved commit window for the project release: the git pathspecs and git-cliff include-paths
+     * that select which commits the stage considers. Defaults to the union of every contributing
+     * workspace's `paths`.
+     */
     paths: string[];
+    /** Resolved tag prefix for project-level tags. */
     tagPrefix: string;
 }
+/** Identifies a dependency whose version bump triggered a propagated release. */
 export interface PropagationSource {
     packageName: string;
     newVersion: string;
 }
+/**
+ * A `!`-policy violation detected while parsing commits during release preparation.
+ *
+ * Surfaces from `releasePrepare`, `releasePrepareMono`, and `releasePrepareProject` via the
+ * `policyViolations` field on each per-workspace/project result. The policy itself is enforced
+ * tolerantly at release time — violations are collected and reported, never fail the release.
+ */
 export interface PolicyViolation {
+    /** Full hash of the offending commit. */
     commitHash: string;
+    /** First line of the commit message (raw, including any ticket prefix). */
     commitSubject: string;
+    /** Resolved canonical work type whose policy was violated. */
     type: string;
+    /** Where the violation was detected: `'prefix'` for `!`, `'body'` for `BREAKING CHANGE:` footer. */
     surface: 'prefix' | 'body';
 }
+/**
+ * Result of preparing a single workspace (package) for release when a release was produced.
+ *
+ * `currentVersion`, `newVersion`, `tag`, `bumpedFiles`, and `changelogFiles` are always
+ * populated. `releaseType` stays optional because it is left undefined for
+ * `--set-version` workspaces. `parsedCommitCount` stays optional because the legacy
+ * single-package bump-override path does not populate it. `commits` stays optional
+ * because propagation-only releases have no direct commits.
+ */
 export interface ReleasedWorkspaceResult {
     status: 'released';
+    /** Workspace name; absent in single-package mode, present in monorepo mode. */
     name?: string;
     previousTag?: string;
     commitCount: number;
+    /**
+     * Count of commits that parsed into a recognized work type. Always populated for
+     * results produced by the unified `decideRelease` algorithm (the monorepo path),
+     * including the no-commits case where it is `0`. May be absent for results
+     * produced by the legacy single-package executor's bump-override path. Use
+     * `bumpOverride` (not `parsedCommitCount === undefined`) as the signal for "the
+     * user supplied --bump=X".
+     */
     parsedCommitCount?: number;
+    /** Commits that could not be parsed into a recognized work type. */
     unparseableCommits?: Commit[];
+    /** Policy violations detected while parsing this workspace's commits; omitted when none. */
     policyViolations?: PolicyViolation[];
     releaseType?: ReleaseType;
     currentVersion: string;
@@ -60,29 +142,73 @@ export interface ReleasedWorkspaceResult {
     tag: string;
     bumpedFiles: string[];
     changelogFiles: string[];
+    /** Release-notes preview files; present only under `--with-release-notes`. */
     previewFiles?: string[];
+    /** Raw commits associated with this workspace (present for direct releases, absent for propagation-only). */
     commits?: Commit[];
+    /**
+     * Present when `--bump=X` was supplied and selected the release level for this workspace.
+     * Distinguishes a bump-override release from a `--force` fallback or a natural-bump release;
+     * consumed by the renderer to label the release accurately.
+     */
     bumpOverride?: ReleaseType;
+    /** Dependencies that triggered a propagated bump (present for propagated or mixed workspaces). */
     propagatedFrom?: PropagationSource[];
+    /** Present when this workspace was written via `--set-version`; the explicit version that was applied. */
     setVersion?: string;
 }
+/**
+ * Result of preparing a single workspace (package) for release when the release was skipped.
+ *
+ * Carries diagnostic data (`commitCount`, `parsedCommitCount`, `unparseableCommits`,
+ * `previousTag`) plus the human-readable `skipReason`. Release-only fields are absent.
+ */
 export interface SkippedWorkspaceResult {
     status: 'skipped';
+    /** Workspace name; absent in single-package mode, present in monorepo mode. */
     name?: string;
     previousTag?: string;
     commitCount: number;
+    /**
+     * Count of commits that parsed into a recognized work type. May be absent for results
+     * produced by the legacy single-package executor's bump-override path.
+     */
     parsedCommitCount?: number;
+    /** Commits that could not be parsed into a recognized work type. */
     unparseableCommits?: Commit[];
+    /** Policy violations detected while parsing this workspace's commits; omitted when none. */
     policyViolations?: PolicyViolation[];
     skipReason: string;
 }
+/**
+ * Result of preparing a single workspace (package) for release.
+ *
+ * Discriminated by `status`: `ReleasedWorkspaceResult` for produced releases,
+ * `SkippedWorkspaceResult` for skips.
+ */
 export type WorkspacePrepareResult = ReleasedWorkspaceResult | SkippedWorkspaceResult;
+/**
+ * Result of preparing a project-level release when a release was produced.
+ *
+ * Mirrors `ReleasedWorkspaceResult` minus the workspace-only fields (`name`,
+ * `propagatedFrom`, `setVersion`). Project releases never propagate and never use
+ * `--set-version`, so `releaseType`, `currentVersion`, `newVersion`, `tag`, and
+ * `commits` are all required.
+ */
 export interface ReleasedProjectResult {
     status: 'released';
     previousTag?: string;
     commitCount: number;
+    /**
+     * Count of commits that parsed into a recognized work type. Always populated by the
+     * unified `decideRelease` algorithm — `0` when there are no commits or when none
+     * parse. Use `bumpOverride` (not `parsedCommitCount === 0`) as the signal for "the
+     * user supplied --bump=X".
+     */
     parsedCommitCount: number;
+    /** Commits that could not be parsed into a recognized work type. */
     unparseableCommits?: Commit[];
+    /** Policy violations detected while parsing the project's commits; omitted when none. */
     policyViolations?: PolicyViolation[];
     releaseType: ReleaseType;
     currentVersion: string;
@@ -90,20 +216,49 @@ export interface ReleasedProjectResult {
     tag: string;
     bumpedFiles: string[];
     changelogFiles: string[];
+    /** Release-notes preview files; present only under `--with-release-notes`. */
     previewFiles?: string[];
+    /** Raw commits in the project's contributing-paths window since the last project tag. */
     commits: Commit[];
+    /**
+     * Present when `--bump=X` was supplied and selected the release level for the project.
+     * Distinguishes a bump-override release from a `--force` fallback or a natural-bump release;
+     * consumed by the renderer to label the release accurately.
+     */
     bumpOverride?: ReleaseType;
 }
+/**
+ * Result of preparing a project-level release when the release was skipped.
+ *
+ * Carries diagnostic data (`commitCount`, `parsedCommitCount`, `unparseableCommits`,
+ * `previousTag`) plus the human-readable `skipReason`. Release-only fields are absent.
+ */
 export interface SkippedProjectResult {
     status: 'skipped';
     previousTag?: string;
     commitCount: number;
+    /**
+     * Count of commits that parsed into a recognized work type. Always populated by the
+     * unified `decideRelease` algorithm — `0` when there are no commits or when none
+     * parse.
+     */
     parsedCommitCount: number;
+    /** Commits that could not be parsed into a recognized work type. */
     unparseableCommits?: Commit[];
+    /** Policy violations detected while parsing the project's commits; omitted when none. */
     policyViolations?: PolicyViolation[];
     skipReason: string;
 }
+/**
+ * Result of preparing a project-level release.
+ *
+ * Discriminated by `status`: `ReleasedProjectResult` for produced releases,
+ * `SkippedProjectResult` for skips. `PrepareResult.project === undefined` means either that
+ * no project block is configured or that `--only` narrowed the run, which skips the stage
+ * before it can produce a result; the skip is surfaced as a run warning instead.
+ */
 export type ProjectPrepareResult = ReleasedProjectResult | SkippedProjectResult;
+/** Aggregate result of the prepare workflow for both single-package and monorepo modes. */
 export interface PrepareResult {
     workspaces: WorkspacePrepareResult[];
     tags: string[];
@@ -111,28 +266,60 @@ export interface PrepareResult {
         command: string;
         files: string[];
     } | undefined;
+    /** Warnings surfaced during preparation (e.g., circular dependency detection). */
     warnings?: string[] | undefined;
+    /** Result of the project-level release stage (present only when `config.project` is configured and the stage ran). */
     project?: ProjectPrepareResult | undefined;
 }
+/** Configuration for a single work type used in commit categorization. */
 export interface WorkTypeConfig {
+    /** Human-readable label for the section heading in changelogs. */
     header: string;
+    /** Optional aliases that map to this work type (e.g., 'feature' -> 'feat'). */
     aliases?: string[] | undefined;
 }
+/**
+ * Defines which commit types trigger major or minor version bumps.
+ * Any recognized commit type not listed defaults to a patch bump.
+ * The sentinel `'!'` in `major` means "any breaking commit triggers a major bump".
+ */
 export interface VersionPatterns {
+    /** Patterns that trigger a major bump. Use `'!'` for any breaking change. */
     major: string[];
+    /** Commit types that trigger a minor bump. */
     minor: string[];
 }
+/**
+ * Schema for a single historical identity snapshot for a workspace.
+ *
+ * Captures what the package looked like at some earlier point: the full npm `name`
+ * (e.g., `'@williamthorsen/nmr-core'`) and the `tagPrefix` under which tags were
+ * published (e.g., `'core-v'`).
+ */
 export declare const legacyIdentitySchema: z.ZodObject<{
     name: z.ZodString;
     tagPrefix: z.ZodString;
 }, z.core.$strict>;
+/**
+ * A single historical identity snapshot for a workspace. Both fields are required — a full
+ * tuple stays unambiguous across any number of future renames.
+ */
 export type LegacyIdentity = z.infer<typeof legacyIdentitySchema>;
+/**
+ * Schema for a package that once lived in this repo but has since been extracted or removed.
+ *
+ * Unlike `legacyIdentitySchema`, retired packages are never consulted for baseline lookup
+ * or changelog attribution — they acknowledge historical tag prefixes and suppress
+ * undeclared-candidate warnings.
+ */
 export declare const retiredPackageSchema: z.ZodObject<{
     name: z.ZodString;
     tagPrefix: z.ZodString;
     successor: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/** A package that once lived in this repo but has since been extracted or removed. */
 export type RetiredPackage = z.infer<typeof retiredPackageSchema>;
+/** Schema for a single workspace override entry in the config file. */
 export declare const workspaceOverrideSchema: z.ZodObject<{
     dir: z.ZodString;
     shouldExclude: z.ZodOptional<z.ZodBoolean>;
@@ -141,38 +328,60 @@ export declare const workspaceOverrideSchema: z.ZodObject<{
         tagPrefix: z.ZodString;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
+/** Override for a single workspace in the config file. Matches a discovered workspace by `dir`. */
 export type WorkspaceOverride = z.infer<typeof workspaceOverrideSchema>;
+/** Schema for the optional `project` block. */
 export declare const projectConfigSchema: z.ZodObject<{
     paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tagPrefix: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/** Consumer-facing project-release config (`project` block). Empty object opts in to project releases. */
 export type ProjectConfig = z.infer<typeof projectConfigSchema>;
+/** Schema for the optional `changelogJson` block (input shape, all fields optional). */
 export declare const changelogJsonInputSchema: z.ZodObject<{
     enabled: z.ZodOptional<z.ZodBoolean>;
     outputPath: z.ZodOptional<z.ZodString>;
     devOnlySections: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
+/** Schema for the optional `releaseNotes` block (input shape, all fields optional). */
 export declare const releaseNotesInputSchema: z.ZodObject<{
     shouldInjectIntoReadme: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+/** Schema for a single `workTypes` entry. */
 export declare const workTypeConfigSchema: z.ZodObject<{
     header: z.ZodString;
     aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
+/** Schema for the `versionPatterns` block. Both arrays are required when the field is provided. */
 export declare const versionPatternsSchema: z.ZodObject<{
     major: z.ZodArray<z.ZodString>;
     minor: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
+/** Schema for a single `breakingPolicies` value. */
 export declare const breakingPolicyValueSchema: z.ZodEnum<{
     forbidden: "forbidden";
     optional: "optional";
     required: "required";
 }>;
+/** Schema for a single label's spec in the `repoLabels.labels` record. */
 export declare const labelSpecSchema: z.ZodObject<{
     color: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/**
+ * A label's color and optional description; the name is the record key in `repoLabels.labels`.
+ * An omitted description resolves to empty, which the generated labels file declares explicitly so that a sync
+ * clears whatever description the label carries today.
+ */
 export type LabelSpec = z.infer<typeof labelSpecSchema>;
+/**
+ * Schema for the optional `repoLabels` block, which declares the repository's label registry (the labels defined on
+ * the GitHub repo, distinct from labels applied to PRs and issues).
+ *
+ * Resolution is an ordered fold with last-writer-wins: presets in `extends` order, then the `labels` record,
+ * where an entry adds a label, replaces one an earlier layer defined, or removes it (`null`).
+ * A `null` naming a label no earlier layer defined is a resolve-time error (`resolveLabels`), not a schema error.
+ */
 export declare const repoLabelsSchema: z.ZodObject<{
     extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
     labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
@@ -180,7 +389,9 @@ export declare const repoLabelsSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>>;
 }, z.core.$strict>;
+/** Consumer-facing `repoLabels` block: bundled presets to extend plus per-name adjustments. */
 export type RepoLabelsConfig = z.infer<typeof repoLabelsSchema>;
+/** Schema for the consumer-facing config file shape (`.config/release-kit.config.ts`). */
 export declare const releaseKitConfigSchema: z.ZodObject<{
     breakingPolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
         forbidden: "forbidden";
@@ -231,52 +442,134 @@ export declare const releaseKitConfigSchema: z.ZodObject<{
         aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
+/**
+ * Consumer-facing config file shape (`.config/release-kit.config.ts`).
+ * All fields are optional; defaults are applied during config merging.
+ */
 export type ReleaseKitConfig = z.infer<typeof releaseKitConfigSchema>;
+/** A raw commit from the git log. */
 export interface Commit {
+    /** The full commit message (first line). */
     message: string;
+    /** The commit hash. */
     hash: string;
 }
+/** A commit that has been parsed to extract structured metadata. */
 export interface ParsedCommit {
+    /** The original commit message. */
     message: string;
+    /** The commit hash. */
     hash: string;
+    /** The resolved work type (e.g., 'feat', 'fix'). */
     type: string;
+    /** The commit description after the type prefix. */
     description: string;
+    /** The scope extracted from `scope|type:` or `type(scope):` format. */
     scope?: string;
+    /** Whether this is a breaking change. */
     breaking: boolean;
 }
+/** Per-workspace configuration for monorepo releases. */
 export interface WorkspaceConfig {
+    /** The package directory name (e.g., 'arrays'). Used for display and `--only` matching. */
     dir: string;
+    /** The full scoped npm name from `package.json` (e.g., `'@williamthorsen/nmr-core'`). */
     name: string;
+    /** The git tag prefix for this workspace (e.g., 'nmr-core-v'), derived from the unscoped `package.json` name. */
     tagPrefix: string;
+    /** Workspace-relative path to the package root (e.g., `packages/core`). */
     workspacePath: string;
+    /**
+     * Whether this workspace can be published to a registry. `true` when `package.json#private`
+     * is absent or `false`; `false` only when `private === true`. Consumed by `release-kit publish`
+     * to filter unpublishable workspaces; other commands ignore this field.
+     */
     isPublishable: boolean;
+    /** Paths to package.json files to bump. */
     packageFiles: string[];
+    /** Directories in which to generate changelogs. */
     changelogPaths: string[];
+    /** Glob patterns passed to `git log -- <paths>` for commit filtering. */
     paths: string[];
+    /**
+     * Prior identities of this workspace.
+     * Each identity's `tagPrefix` is consulted in addition to the current `tagPrefix` when searching for baseline
+     * tags and generating changelogs. `undefined` is equivalent to the empty array.
+     */
     legacyIdentities?: LegacyIdentity[];
 }
+/** Configuration for a monorepo release workflow with multiple workspaces. */
 export interface MonorepoReleaseConfig {
+    /** Ordered list of workspace configurations. */
     workspaces: WorkspaceConfig[];
+    /** Work type configurations shared across all workspaces. Defaults to `DEFAULT_WORK_TYPES`. */
     workTypes?: Record<string, WorkTypeConfig>;
+    /** Version bump patterns. Defaults to `DEFAULT_VERSION_PATTERNS`. */
     versionPatterns?: VersionPatterns;
+    /**
+     * Per-canonical-type breaking-policy lookup. Defaults to `DEFAULT_BREAKING_POLICIES`.
+     * When provided, replaces the default entirely.
+     * Pass `{}` to disable enforcement (parser falls back to `'optional'` for missing types).
+     */
     breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    /**
+     * Shell command to run after all changelogs are generated (e.g., 'pnpm run fmt').
+     * Modified file paths (package.json files and CHANGELOGs) are appended as space-separated
+     * arguments. Paths are repo-relative; file paths containing spaces are not supported.
+     */
     formatCommand?: string;
+    /** Path to the cliff.toml file; defaults to 'cliff.toml' when absent. */
     cliffConfigPath?: string;
+    /**
+     * Maps scope shorthand names to their canonical names.
+     * When a commit uses `shorthand|type: description` or `type(shorthand): description`,
+     * the shorthand is resolved to the canonical scope name before the parsed commit is returned.
+     */
     scopeAliases?: Record<string, string>;
+    /** Controls structured changelog JSON generation. */
     changelogJson: ChangelogJsonConfig;
+    /** Controls release notes consumption (README injection). */
     releaseNotes: ReleaseNotesConfig;
+    /**
+     * Project-level release config. Present iff the consumer declared `project: {}`.
+     * When present, `releasePrepareMono` runs an additional project-release stage after the per-workspace loop.
+     */
     project?: ResolvedProjectConfig;
 }
+/** Configuration for the release workflow. */
 export interface ReleaseConfig {
+    /** The git tag prefix used to identify version tags (e.g., 'v'). */
     tagPrefix: string;
+    /** Paths to package.json files to bump. */
     packageFiles: string[];
+    /** Paths to directories in which to generate changelogs. */
     changelogPaths: string[];
+    /** Work type configurations. Defaults to `DEFAULT_WORK_TYPES`. */
     workTypes?: Record<string, WorkTypeConfig>;
+    /** Version bump patterns. Defaults to `DEFAULT_VERSION_PATTERNS`. */
     versionPatterns?: VersionPatterns;
+    /**
+     * Per-canonical-type breaking-policy lookup. Defaults to `DEFAULT_BREAKING_POLICIES`. When
+     * provided, replaces the default entirely. Pass `{}` to disable enforcement (parser falls
+     * back to `'optional'` for missing types).
+     */
     breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    /**
+     * Shell command to run after changelog generation (e.g., 'pnpm run fmt').
+     * Modified file paths (package.json files and CHANGELOGs) are appended as space-separated arguments.
+     * Paths are repo-relative; file paths containing spaces are not supported.
+     */
     formatCommand?: string;
+    /** Path to the cliff.toml file; defaults to 'cliff.toml' when absent. */
     cliffConfigPath?: string;
+    /**
+     * Maps scope shorthand names to their canonical names.
+     * When a commit uses `shorthand|type: description` or `type(shorthand): description`,
+     * the shorthand is resolved to the canonical scope name before the parsed commit is returned.
+     */
     scopeAliases?: Record<string, string>;
+    /** Controls structured changelog JSON generation. */
     changelogJson: ChangelogJsonConfig;
+    /** Controls release notes consumption (README injection). */
     releaseNotes: ReleaseNotesConfig;
 }

package/dist/esm/validateConfig.d.ts

@@ -1,4 +1,17 @@
-import type { ReleaseKitConfig } from './types.js';
+import { type ReleaseKitConfig } from './types.js';
+/**
+ * Validate a raw config object loaded from `.config/release-kit.config.ts`.
+ *
+ * Single source of truth: `releaseKitConfigSchema` in `types.ts`, with
+ * `ReleaseKitConfig = z.infer<typeof releaseKitConfigSchema>`. Adding a field to the type
+ * without updating the schema is impossible because the type *is* derived from the
+ * schema.
+ *
+ * Pipeline: (1) preprocess strips deprecated keys and emits migration-guidance errors;
+ * (2) `releaseKitConfigSchema.safeParse` does shape validation; (3) post-parse cross-field
+ * checks (full-tuple duplicates, retired-vs-legacy collisions) operate on the typed
+ * result.
+ */
 export declare function validateConfig(raw: unknown): {
     config: ReleaseKitConfig;
     errors: string[];

package/dist/esm/validateOnlyExcludesStrandedDependents.d.ts

@@ -1,14 +1,35 @@
 import type { DependencyGraph } from './buildDependencyGraph.js';
 import type { WorkspaceConfig } from './types.js';
+/** Result of probing a workspace's commits since its last tag. */
 export interface CommitsProbeResult {
+    /** Whether the workspace has any commits since its last tag (excluding `release:` commits). */
     has: boolean;
+    /** The baseline tag the commits were measured from; `undefined` when no prior tag exists. */
     tag: string | undefined;
 }
+/** A single excluded workspace whose changes would be stranded by the `--only` invocation. */
 export interface StrandedDependentViolation {
+    /** The excluded workspace's `dir`. */
     dir: string;
+    /** The released workspace's `dir` whose release would have triggered D's republication. */
     downstreamOf: string;
+    /** The baseline tag from which D's commits were counted; `undefined` if no prior tag. */
     tag: string | undefined;
 }
+/** Probe callback that returns whether a workspace has commits since its last tag. */
 type CommitsProbe = (workspace: WorkspaceConfig) => CommitsProbeResult;
+/**
+ * Detect `--only` invocations that would silently strand changes in excluded internal dependents.
+ *
+ * Runs in two steps. First, compute the released `--only` set R via fixpoint: start with `--only`
+ * workspaces that have own commits, then iteratively add `--only` workspaces whose `workspace:`
+ * deps land in R (those will release via propagation). Second, BFS through the reverse-dep graph
+ * starting from R, recording each excluded workspace with own commits as a violation. The walk
+ * continues *through* such workspaces (anticipating that the user will add them to `--only`,
+ * surfacing deeper footguns in one pass), but stops at excluded workspaces with no commits
+ * (case-3 barriers — they don't republish, so their downstream dependents aren't affected by R).
+ *
+ * Returns `undefined` when no violations are found, or a sorted list otherwise.
+ */
 export declare function validateOnlyExcludesStrandedDependents(workspaces: readonly WorkspaceConfig[], only: readonly string[], graph: DependencyGraph, hasCommits: CommitsProbe): StrandedDependentViolation[] | undefined;
 export {};

package/dist/esm/validateOverridesCommand.d.ts

@@ -1,14 +1,44 @@
 import { type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult } from './changelogOverrides.js';
 import type { ChangelogEntry, ReleaseConfig } from './types.js';
+/**
+ * Result of {@link validateOverridesCommand}: tiered exit code paired with a human-readable
+ * message. Mirrors the shape of `checkWorkTypesDrift` so the CLI dispatch layer can stay
+ * uniformly thin.
+ *
+ * Exit codes:
+ * - `0` — clean: no errors, no warnings.
+ * - `1` — only stale-key warnings.
+ * - `2` — schema/parse or ambiguous-prefix errors (errors dominate when both classes exist).
+ */
 export interface ValidateOverridesCommandResult {
     exitCode: 0 | 1 | 2;
     message: string;
 }
+/** Injection seams for unit testing. Production callers leave defaults; tests substitute deterministic fakes. */
 export interface ValidateOverridesCommandDependencies {
     discoverWorkspaces?: () => Promise<string[] | undefined>;
     loadConfig?: () => Promise<unknown>;
+    /**
+     * Build changelog entries for a scope. Defaults to `buildChangelogEntries`, the same path
+     * `release-kit prepare` uses — anchoring `validate`'s hash universe to `prepare`'s by
+     * construction. `tagPattern` and `includePaths` are passed straight through to git-cliff.
+     */
     buildEntries?: (config: Pick<ReleaseConfig, 'cliffConfigPath' | 'changelogJson'>, tagPattern?: string, includePaths?: string[]) => ChangelogEntry[];
+    /** Pluggable validator (default: the production library function). Tests use this to drive specific result shapes through the formatter. */
     validate?: (inputs: ValidateAllChangelogOverridesInputs) => ValidateAllChangelogOverridesResult;
 }
+/**
+ * Validate every changelog override file across the project and per-workspace scopes, and
+ * return a tiered exit-code-plus-message result. Performs workspace discovery, config load,
+ * and per-scope hash collection, then delegates the actual validation to
+ * {@link validateAllChangelogOverrides}.
+ *
+ * Single-package and monorepo modes are handled uniformly: single-package collapses to one
+ * project scope; monorepo expands to a project scope plus one scope per workspace.
+ */
 export declare function validateOverridesCommand(dependencies?: ValidateOverridesCommandDependencies): Promise<ValidateOverridesCommandResult>;
+/**
+ * Pure formatter — take an aggregated validation result, return the tiered exit code and a
+ * rendered message. Exported for unit testing without going through the full discovery path.
+ */
 export declare function formatValidateOverridesResult(result: ValidateAllChangelogOverridesResult): ValidateOverridesCommandResult;