@williamthorsen/release-kit 10.4.3 → 10.5.0

package/dist/esm/createGithubRelease.d.ts

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

package/dist/esm/createGithubReleaseCommand.d.ts

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

package/dist/esm/createTags.d.ts

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

package/dist/esm/decideRelease.d.ts

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

package/dist/esm/defaults.d.ts

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

package/dist/esm/defineConfig.d.ts

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

package/dist/esm/deleteFileIfExists.d.ts

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

package/dist/esm/deriveWorkspaceConfig.d.ts

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

package/dist/esm/detectPackageManager.d.ts

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

package/dist/esm/detectUndeclaredTagPrefixes.d.ts

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

package/dist/esm/determineBumpFromCommits.d.ts

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

package/dist/esm/determineBumpType.d.ts

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

package/dist/esm/discoverWorkspaces.d.ts

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

package/dist/esm/format.d.ts

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

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>;