@williamthorsen/release-kit 10.4.4 → 10.5.0

package/dist/esm/runGitCliff.d.ts

@@ -1,2 +1,45 @@
+/**
+ * Invokes `git-cliff` via `npx` and returns the output it produced.
+ *
+ * Single entry point for `git-cliff` invocations from `release-kit`. Owns three pieces of shared lifecycle
+ * that would otherwise duplicate (and silently drift) across call sites: the npx flags, the spawned-process
+ * environment, and the temp dir holding both the `.template`→`.toml` config copy and cliff's output file.
+ *
+ * Output is routed through `--output` to a temp file and read back. `--context` emits a workspace's
+ * entire matching tag history on every run, so its size grows without bound with the repo;
+ * a file accommodates that, while a pipe is bounded by `maxBuffer`.
+ *
+ * The `--prefer-offline` flag and `npm_config_progress=false` env entry are deliberate: `--prefer-offline` skips
+ * npx's per-call npm-registry revalidation HTTP round-trip (~2.5 s per invocation on a warm cache), and
+ * `npm_config_progress=false` suppresses npx's animated stderr spinner, which otherwise renders as a transient flicker.
+ *
+ * Because `--prefer-offline` also suppresses npx's cache-staleness check, the cached `git-cliff` binary
+ * would otherwise drift further and further behind upstream, with each cliff invocation re-emitting the
+ * "A new version of git-cliff is available" notice and the local cache never updating.
+ * `refreshGitCliffCache` (below) revalidates the cache once at the top of each `prepare` run so that
+ * subsequent `--prefer-offline` calls run against a current binary.
+ *
+ * The helper injects `--config <path>` and `--output <path>` itself — callers must NOT include either in `cliffArgs`.
+ * `--output` is appended last so a caller that passes one anyway cannot redirect the output the helper then reads.
+ * The caller is responsible for resolving the cliff config path (via `resolveCliffConfigPath`) before calling,
+ * since the resolution depends on the caller's `import.meta.url`.
+ *
+ * Errors from `execFileSync` are not caught: callers wrap with site-specific messages.
+ * The temp-dir cleanup runs in a `finally` so it still happens on throw.
+ */
 export declare function runGitCliff(cliffConfigPath: string, cliffArgs: readonly string[]): string;
+/**
+ * Revalidate npx's cache for `git-cliff` once per `prepare` run.
+ *
+ * Spawns `npx --yes git-cliff --version` *without* `--prefer-offline`, so that npm performs its normal
+ * registry-staleness check and refreshes the cached binary if a newer version is available.
+ * Subsequent `runGitCliff` calls within the same run keep `--prefer-offline` (preserving the per-call perf win)
+ * but now run against an up-to-date cache, so git-cliff's own self-update notice no longer fires repeatedly.
+ *
+ * Stdio: stdin ignored, stdout piped (the version line is suppressed as noise), stderr inherited (npm errors and
+ * any rare upgrade notice surface, but only once per run). `maxBuffer` is declared even though the piped output
+ * is a single version line, because every call that pipes stdout declares one.
+ *
+ * Errors propagate unchanged — a failed cache refresh fails the prepare run loudly rather than silently degrading.
+ */
 export declare function refreshGitCliffCache(): void;

package/dist/esm/showTagPrefixesCommand.d.ts

@@ -1 +1,12 @@
+/**
+ * Orchestrate the CLI `show-tag-prefixes` command.
+ *
+ * Prints a per-workspace table of derived prefixes, tag counts, and declared legacy
+ * entries, followed by an "Undeclared tag prefixes" section when candidate-shaped tags
+ * exist outside the known set. Exits `0` on full derivation success and no collisions;
+ * `1` on any derivation failure or collision. Undeclared candidates do not affect the
+ * exit code.
+ *
+ * @returns The exit code the caller should use.
+ */
 export declare function showTagPrefixesCommand(): Promise<number>;

package/dist/esm/stripScope.d.ts

@@ -1 +1,8 @@
+/**
+ * Strip scope indicators from a raw commit message.
+ *
+ * Handles `scope|type: desc`, `type(scope): desc`, and messages with
+ * ticket prefixes (e.g., `#72 release-kit|fix: ...`). Returns the
+ * message unchanged when no scope is detected.
+ */
 export declare function stripScope(message: string): string;

package/dist/esm/sync-labels/generateCommand.d.ts

@@ -1,10 +1,27 @@
 import type { RepoLabelsConfig } from '../types.js';
 import type { LabelDefinition } from './types.js';
+/** Output path for the generated labels file. */
 export declare const LABELS_OUTPUT_PATH = ".github/labels.yaml";
+/** Formats resolved labels as YAML with generated header including preset hashes. */
 export declare function formatLabelsYaml(labels: LabelDefinition[], presetHashes: Map<string, string>): string;
+/**
+ * Loads `.config/release-kit.config.ts` and returns its `repoLabels` block.
+ *
+ * Reports an actionable error and returns `undefined` when the config file is missing,
+ * fails to load or validate, or carries no `repoLabels` block.
+ */
 export declare function loadRepoLabelsConfig(): Promise<RepoLabelsConfig | undefined>;
+/** Options for the `sync-labels generate` subcommand. */
 interface GenerateOptions {
+    /** Compare the regenerated content against the committed file instead of writing. */
     check?: boolean;
 }
+/**
+ * Runs the `sync-labels generate` command.
+ *
+ * Loads the `repoLabels` block from `.config/release-kit.config.ts`, resolves presets and label adjustments,
+ * and writes `.github/labels.yaml` -- or, with `check`, regenerates in memory and reports whether the committed file
+ * is stale, writing nothing. Returns 0 on success, 1 on failure.
+ */
 export declare function generateCommand({ check }?: GenerateOptions): Promise<number>;
 export {};

package/dist/esm/sync-labels/initCommand.d.ts

@@ -1,6 +1,15 @@
+/** Options for the `sync-labels init` subcommand. */
 interface InitOptions {
     dryRun: boolean;
     force: boolean;
 }
+/**
+ * Run the `sync-labels init` subcommand.
+ *
+ * Discovers workspaces and retired packages, scaffolds the caller workflow, then seeds the
+ * `repoLabels` block: into a new `.config/release-kit.config.ts` when none exists, or
+ * printed to stdout for manual paste when the file is already there — an existing,
+ * hand-authored config is never rewritten. Returns 0 on success, 1 on failure.
+ */
 export declare function syncLabelsInitCommand({ dryRun, force }: InitOptions): Promise<number>;
 export {};

package/dist/esm/sync-labels/presets.d.ts

@@ -1,3 +1,9 @@
 import type { LabelDefinition } from './types.js';
+/** Computes SHA-256 hex digest of a preset file's raw content. Throws if the preset does not exist. */
 export declare function hashPresetFile(presetName: string): string;
+/**
+ * Loads a named preset from the bundled YAML files.
+ *
+ * Returns the parsed label definitions. Throws if the preset does not exist or has invalid content.
+ */
 export declare function loadPreset(presetName: string): LabelDefinition[];

package/dist/esm/sync-labels/resolveLabels.d.ts

@@ -1,3 +1,13 @@
 import type { RepoLabelsConfig } from '../types.js';
 import type { LabelDefinition } from './types.js';
+/**
+ * Resolves the repository's label set from a `repoLabels` config block.
+ *
+ * Resolution is an ordered fold with last-writer-wins: presets are loaded in `extends` order (a later preset replaces
+ * an earlier preset's label of the same name), then the `labels` record is applied: An entry adds a label, replaces
+ * one an earlier layer defined, or removes it (`null`). Replacement is wholesale, so an entry omitting `description`
+ * drops the one an earlier layer supplied rather than inheriting it.
+ * Throws only on a dangling `null`: a removal naming a label no preset defined, which is a stale reference that
+ * would otherwise produce no output diff to review.
+ */
 export declare function resolveLabels(config: RepoLabelsConfig): LabelDefinition[];

package/dist/esm/sync-labels/retiredConfig.d.ts

@@ -1,2 +1,10 @@
+/** Path of the retired standalone sync-labels config file. */
 export declare const RETIRED_SYNC_LABELS_CONFIG_PATH = ".config/sync-labels.config.ts";
+/**
+ * Report an actionable migration error when the retired standalone config file is present.
+ *
+ * Returns `true` when the file exists, in which case the caller must abort. The check is
+ * unconditional on config content: file presence alone triggers it, so a half-migrated
+ * repo cannot silently lose its custom labels.
+ */
 export declare function checkRetiredSyncLabelsConfig(): boolean;

package/dist/esm/sync-labels/syncCommand.d.ts

@@ -1 +1,7 @@
+/**
+ * Run the `sync-labels sync` subcommand.
+ *
+ * Validates prerequisites (gh CLI, workflow file), then triggers the sync-labels workflow
+ * via `gh workflow run`. Returns 0 on success, 1 on failure.
+ */
 export declare function syncLabelsCommand(): number;

package/dist/esm/sync-labels/templates.d.ts

@@ -1,5 +1,19 @@
 import type { LabelDefinition } from './types.js';
+/** Generates the caller workflow YAML for `sync-labels`. */
 export declare function syncLabelsWorkflow(): string;
+/**
+ * Generates scope labels from workspace paths and retired-package names.
+ *
+ * Workspace labels are named after the path basename; retired-package labels after the unscoped package name.
+ * None carries a description: GitHub renders a described label taller and more prominently than a bare one, and
+ * the scope labels are meant to read as a compact group.
+ * Describing only the retired scopes would single them out for that prominence.
+ */
 export declare function buildScopeLabels(workspacePaths: string[], retiredNames?: string[]): LabelDefinition[];
+/**
+ * Renders the `repoLabels` config block, indented for pasting into the object passed to `defineConfig` in
+ * `.config/release-kit.config.ts`.
+ */
 export declare function renderRepoLabelsBlock(scopeLabels: LabelDefinition[]): string;
+/** Generates a new `.config/release-kit.config.ts` carrying the `repoLabels` block. */
 export declare function repoLabelsConfigScript(scopeLabels: LabelDefinition[]): string;

package/dist/esm/sync-labels/types.d.ts

@@ -1,5 +1,9 @@
+/** A single GitHub label definition compatible with EndBug/label-sync. */
 export interface LabelDefinition {
+    /** Display name of the label. */
     name: string;
+    /** Hex color code without the leading `#`. */
     color: string;
+    /** Short description shown in the GitHub UI. Absent when the label carries none. */
     description?: string;
 }

package/dist/esm/syncWorkTypes.d.ts

@@ -1,10 +1,28 @@
+/** Outcome of a sync operation. */
 export interface SyncResult {
+    /**
+     * Process exit code semantics:
+     * - `0` — sync succeeded (file may be unchanged).
+     * - `2` — network error or local write failure.
+     * - `3` — schema mismatch (upstream JSON does not parse or fails the shape check).
+     */
     exitCode: 0 | 2 | 3;
     message: string;
 }
+/** Minimal injection seam so unit tests can substitute a deterministic fetcher. */
 export interface SyncWorkTypesDependencies {
+    /** Absolute path of the local `work-types.json`. Defaults to the bundled file. */
     localPath?: string;
+    /** HTTP fetcher. Defaults to global `fetch`. */
     fetch?: typeof globalThis.fetch;
+    /** Override the upstream URL (used by tests). */
     upstreamUrl?: string;
 }
+/**
+ * Fetch the upstream `work-types.json`, validate its top-level shape, and overwrite the
+ * locally-bundled copy with the formatted upstream contents.
+ *
+ * Output is reformatted to match the local file's conventions (2-space indent, trailing
+ * newline) so subsequent diffs are content-driven, not whitespace-driven.
+ */
 export declare function syncWorkTypes(dependencies?: SyncWorkTypesDependencies): Promise<SyncResult>;

package/dist/esm/tagCommand.d.ts

@@ -1 +1,2 @@
+/** Orchestrate the CLI `tag` command: parse flags and delegate to `createTags`. */
 export declare function tagCommand(argv: string[]): void;

package/dist/esm/typeGuards.d.ts

@@ -1,2 +1,4 @@
+/** Check whether a value is a plain object (non-null, non-array). */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Narrow an `unknown` value to `unknown[]` via `Array.isArray`, avoiding `any[]`. */
 export declare function isUnknownArray(value: unknown): value is unknown[];