@williamthorsen/release-kit 10.4.4 → 10.5.0

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
-/** @noformat — @generated. Do not edit. Compiled by rdy. */
+/** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.32.0";
+export const __readyupVersion = "0.35.0";
 
 
 // .readyup/kits/default.ts
@@ -52,7 +52,7 @@ function detectRepoType() {
 
 // .readyup/kits/default.ts
 function getMinVersion() {
-  const picked = { "version": "10.4.4" };
+  const picked = { "version": "10.5.0" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("release-kit/package.json: 'version' must be a string");
   }
@@ -218,6 +218,13 @@ var default_default = defineRdyKit({
           check: () => !hasDevDependency("git-cliff"),
           fix: "pnpm remove git-cliff \u2014 release-kit handles changelog generation directly"
         },
+        {
+          name: "@changesets/cli not in devDependencies",
+          severity: "recommend",
+          quiet: true,
+          check: () => !hasDevDependency("@changesets/cli"),
+          fix: "pnpm remove @changesets/cli, then delete .changeset/ and any changeset:* scripts; release-kit supersedes changesets"
+        },
         {
           name: ".config/git-cliff.toml matches current template",
           severity: "warn",

package/.readyup/kits/npm-auto-publish.js

@@ -1,6 +1,6 @@
-/** @noformat — @generated. Do not edit. Compiled by rdy. */
+/** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.32.0";
+export const __readyupVersion = "0.35.0";
 
 
 // .readyup/kits/npm-auto-publish.ts
@@ -68,6 +68,9 @@ var packagesChecklist = defineRdyChecklist({
       },
       fix: 'Set "packageManager": "pnpm@..." in root package.json'
     },
+    // Unfalsifiable on readyup 0.33 and later, where discovery reports the repo root and throws on an unreadable
+    // root package.json rather than returning an empty list. It stays for a consumer below that, whose monorepo
+    // mode returns the matched directories alone and so returns nothing when the globs match nothing.
     {
       name: "At least one workspace discovered",
       check: () => discoverWorkspaces().length > 0,
@@ -86,7 +89,9 @@ var packagesChecklist = defineRdyChecklist({
       // reach the registry on every run regardless of the skip. Per-outcome wording goes in the check's detail.
       fix: 'Restore a usable npm session: log in with "npm login", or restore access to the registry, which the trusted-publisher check queries directly',
       get checks() {
-        return discoverWorkspaces().map((workspace) => buildWorkspaceCheck(workspace));
+        return discoverWorkspaces({ filter: belongsInPackagesChecklist }).map(
+          (workspace) => buildWorkspaceCheck(workspace)
+        );
       }
     }
   ]
@@ -95,6 +100,9 @@ var npm_auto_publish_default = defineRdyKit({
   fixLocation: "inline",
   checklists: [repoChecklist, packagesChecklist]
 });
+function belongsInPackagesChecklist(workspace) {
+  return !workspace.isRoot || workspace.isPackage;
+}
 function buildWorkspaceCheck(workspace) {
   const displayName = workspace.name ?? "(unnamed)";
   const pkgJsonPath = path.join(workspace.dir, "package.json");

package/.readyup/manifest.json

@@ -5,15 +5,15 @@
       "checklists": [
         "release-kit"
       ],
-      "esbuildVersion": "0.28.1",
+      "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "fe239d01",
+          "hash": "c948b179",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "999accdd",
+          "hash": "221d9444",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -38,30 +38,30 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.32.0",
+      "readyupVersion": "0.35.0",
       "source": "kits/default.ts",
-      "sourceHash": "fe239d01",
-      "targetHash": "e9daa536"
+      "sourceHash": "c948b179",
+      "targetHash": "08e4eb5a"
     },
     {
       "checklists": [
         "repo",
         "packages"
       ],
-      "esbuildVersion": "0.28.1",
+      "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "ac484613",
+          "hash": "15641d4a",
           "kind": "module",
           "path": "kits/npm-auto-publish.ts"
         }
       ],
       "name": "npm-auto-publish",
       "path": "kits/npm-auto-publish.js",
-      "readyupVersion": "0.32.0",
+      "readyupVersion": "0.35.0",
       "source": "kits/npm-auto-publish.ts",
-      "sourceHash": "ac484613",
-      "targetHash": "6f5398ef"
+      "sourceHash": "15641d4a",
+      "targetHash": "721e337b"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## 10.5.0 — 2026-09-01
+
+### 🎉 Features
+
+- Report a consuming repo that still declares @changesets/cli (#764)
+
+  Adds a check to the default ReadyUp kit in `@williamthorsen/release-kit` that reports a repo still declaring `@changesets/cli`, the release tool superseded by release-kit. The check reports at `recommend` severity; its fix directs the consumer to remove the dependency together with the `.changeset/` directory and any `changeset:*` scripts.
+
+### ♻️ Refactoring
+
+- Upgrade to readyup v0.34 and exclude a private repo root from kit checks (#759)
+
+  Upgrades `readyup` to v0.34, whose `discoverWorkspaces` now reports the repo root. `release-kit`'s `npm-auto-publish` kit filters that root out unless it is publishable, so a private root is no longer listed in the kit's report.
+
+  Test suites for release-kit's ReadyUp kits have been refactored to use the patterns documented in v0.34.
+
+- Upgrade eslint-config-typescript and mark the discards it now reports (#761)
+
+  Upgrades `@williamthorsen/eslint-config-typescript` to v12 and fixes violations surfaced by the newly added rule warning against a disposable that is discarded or that is bound to a declaration that never releases it.
+
 ## 10.4.4 — 2026-08-24
 
 ### ♻️ Refactoring

package/README.md

@@ -4,7 +4,15 @@ Version-bumping and changelog-generation toolkit for release workflows.
 
 Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs from `git-cliff --context` output rendered in-process (with optional [editorial overrides](#editorial-overrides)).
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v10.5.0 (2026-09-01)
+
+### 🎉 Features
+
+- Report a consuming repo that still declares @changesets/cli (#764)
+
+  Adds a check to the default ReadyUp kit in `@williamthorsen/release-kit` that reports a repo still declaring `@changesets/cli`, the release tool superseded by release-kit. The check reports at `recommend` severity; its fix directs the consumer to remove the dependency together with the `.changeset/` directory and any `changeset:*` scripts.
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -1067,7 +1075,7 @@ If your format command does not accept file arguments, update it to one that doe
 ## Migration from changesets
 
 1. Add `@williamthorsen/release-kit` as a dev dependency.
-2. Remove `@changesets/cli` from dev dependencies.
+2. Remove `@changesets/cli` from dev dependencies. The [default readyup kit](#readiness-checks) reports a repo that still declares it.
 3. Delete the `.changeset/` directory.
 4. Run `npx @williamthorsen/release-kit init` to scaffold workflow and config files.
 5. Remove `changeset:*` scripts from `package.json` (no replacement needed — the CLI handles everything).

package/dist/esm/assertCleanWorkingTree.d.ts

@@ -1 +1,6 @@
+/**
+ * Verify that the git working tree has no uncommitted changes.
+ *
+ * @throws If `git status --porcelain` reports any changes.
+ */
 export declare function assertCleanWorkingTree(): void;

package/dist/esm/buildChangelogEntries.d.ts

@@ -1,4 +1,26 @@
 import type { GenerateChangelogOptions } from './generateChangelogs.js';
 import type { ChangelogEntry, ReleaseConfig } from './types.js';
+/**
+ * Strip cliff-template decorations from a group string, returning the bare section name.
+ *
+ * The bundled `cliff.toml.template` encodes canonical row order as a hidden HTML comment
+ * (e.g. `"<!-- 04 -->🐛 Bug fixes"`) so tera's `group_by` filter sorts groups predictably.
+ * The body template's `striptags` filter erases the comment from the rendered heading,
+ * but downstream consumers that read the raw `group` value (changelog.json titles, the
+ * dev-vs-public classifier, the drift test) see the prefix and must strip it. The trailing
+ * `stripEmojiPrefix` keeps the helper backward-compatible with consumer overrides written
+ * as bare names.
+ */
 export declare function stripGroupDecorations(group: string): string;
+/**
+ * Build structured changelog entries from git history using git-cliff `--context`.
+ *
+ * Pure data: invokes git-cliff, parses its `--context` output, and returns the transformed
+ * `ChangelogEntry[]`. Performs no `changelog.json` I/O — callers persist the entries via
+ * `renderChangelogJson`.
+ *
+ * Always invokes git-cliff: dry-run is the caller's concern (it governs whether the file write happens,
+ * not whether git-cliff runs). This means dry-run exercises the full git-cliff toolchain and surfaces missing-binary,
+ * malformed-config, and template-resolution failures earlier than before.
+ */
 export declare function buildChangelogEntries(config: Pick<ReleaseConfig, 'cliffConfigPath' | 'changelogJson'>, tag: string, options?: GenerateChangelogOptions): ChangelogEntry[];

package/dist/esm/buildDependencyGraph.d.ts

@@ -1,8 +1,24 @@
 import type { WorkspaceConfig } from './types.js';
+/** Reverse adjacency map from package names to their workspace dependents. */
 export interface DependencyGraph {
+    /** Resolve a package name to its workspace `dir`. */
     packageNameToDir: Map<string, string>;
+    /** Resolve a workspace `dir` to its package name (inverse of `packageNameToDir`). */
     dirToPackageName: Map<string, string>;
+    /** Map a package name to the workspaces that depend on it. */
     dependentsOf: Map<string, WorkspaceConfig[]>;
+    /**
+     * Forward adjacency: map a workspace `dir` to the set of `workspace:`-protocol package
+     * names it declares in `dependencies` or `peerDependencies`. Complement of `dependentsOf`.
+     */
     dependenciesOf: Map<string, Set<string>>;
 }
+/**
+ * Build a reverse dependency graph from the workspaces' `package.json` files.
+ *
+ * Reads each workspace's primary `package.json` (first entry in `packageFiles`) to discover
+ * `workspace:` references in `dependencies` and `peerDependencies`. Returns a map from each
+ * package name to the workspaces that depend on it, enabling upward traversal from a bumped
+ * package to all its dependents.
+ */
 export declare function buildDependencyGraph(workspaces: readonly WorkspaceConfig[]): DependencyGraph;

package/dist/esm/buildEmptyReleaseEntry.d.ts

@@ -1,2 +1,10 @@
 import type { ChangelogEntry } from './types.js';
+/**
+ * Build a synthetic changelog entry for a forced empty-range release.
+ *
+ * Produces a single `ChangelogEntry` with one `'Notes'` section (audience `'dev'`)
+ * containing a single `'Forced version bump.'` item. Used when `release-kit prepare`
+ * proceeds via `--force`, `--bump=X`, or `--set-version` against a unit with zero
+ * qualifying commits since its last tag. Pure function: no I/O.
+ */
 export declare function buildEmptyReleaseEntry(version: string, date: string): ChangelogEntry;

package/dist/esm/buildReleaseSummary.d.ts

@@ -1,2 +1,12 @@
 import type { PrepareResult } from './types.js';
+/**
+ * Build a release commit body from a prepare result.
+ *
+ * Each released workspace with commits gets a section headed by its tag,
+ * followed by scope-stripped commit messages as bullet points. Sections
+ * are separated by blank lines. The project release (when present) is
+ * appended as a final section using the same format. Returns an empty
+ * string when no released workspaces have commits and there is no project
+ * release.
+ */
 export declare function buildReleaseSummary(result: Pick<PrepareResult, 'project' | 'workspaces'>): string;

package/dist/esm/buildSyntheticChangelogEntry.d.ts

@@ -1,4 +1,10 @@
 import type { ChangelogEntry } from './types.js';
+/**
+ * Build a synthetic changelog entry for a propagation-only bump.
+ *
+ * Produces a single `ChangelogEntry` with one `'Dependency updates'` section (audience `'dev'`)
+ * containing one item per propagated-from dependency. Pure function: no I/O.
+ */
 export declare function buildSyntheticChangelogEntry(propagatedFrom: ReadonlyArray<{
     packageName: string;
     newVersion: string;

package/dist/esm/bumpVersion.d.ts

@@ -1,2 +1,10 @@
 import type { ReleaseType } from './types.js';
+/**
+ * Bumps a semver version string by the given release type.
+ *
+ * @param version - A semver version string (e.g., '1.2.3').
+ * @param releaseType - The type of release bump to apply.
+ * @returns The bumped version string.
+ * @throws If the version string is not a valid semver format.
+ */
 export declare function bumpVersion(version: string, releaseType: ReleaseType): string;

package/dist/esm/changelogJsonFile.d.ts

@@ -1,4 +1,15 @@
 import type { ChangelogEntry, ReleaseConfig } from './types.js';
+/** Resolve the absolute output path for the `changelog.json` file under a workspace's changelog directory. */
 export declare function resolveChangelogJsonPath(config: Pick<ReleaseConfig, 'changelogJson'>, changelogPath: string): string;
+/** Renders changelog entries as a `changelog.json` file's complete content, sorted newest-first. */
 export declare function renderChangelogJson(entries: ChangelogEntry[]): string;
+/**
+ * Merges `entries` with the on-disk entries at `filePath` and returns the merged set in
+ * newest-first order, without writing.
+ *
+ * Preserves entries that exist on disk but are absent from `entries` — load-bearing for
+ * synthetic-entry preservation across propagation runs. Reads the file when present; treats a
+ * missing or malformed file as an empty existing set, so a malformed file does not abort the
+ * release.
+ */
 export declare function mergeChangelogEntriesWithDisk(filePath: string, entries: ChangelogEntry[]): ChangelogEntry[];

package/dist/esm/changelogJsonUtils.d.ts

@@ -1,5 +1,21 @@
 import type { ChangelogEntry, ChangelogItem } from './types.js';
+/**
+ * Type guard for `ChangelogItem` values parsed from JSON.
+ *
+ * Accepts the required `description` plus optional `body`, `breaking`, and `hash` fields. The
+ * `hash` field is shape-checked but not required — synthetic propagation entries omit it, and
+ * pre-hash `changelog.json` files are still considered valid.
+ */
 export declare function isChangelogItem(value: unknown): value is ChangelogItem;
+/** Type guard for `ChangelogEntry` values parsed from JSON. */
 export declare function isChangelogEntry(value: unknown): value is ChangelogEntry;
+/** Extract the version from a tag by stripping the prefix up to the first digit. */
 export declare function extractVersion(tag: string): string;
+/**
+ * Read and parse a changelog JSON file, returning validated entries.
+ *
+ * Returns `undefined` if the file cannot be read or does not contain a valid array.
+ * Silent on parse error — for the warn-and-treat-as-empty variant used by upsert callers,
+ * see `readExistingEntries` in `./changelogJsonFile.ts`.
+ */
 export declare function readChangelogEntries(filePath: string): ChangelogEntry[] | undefined;

package/dist/esm/changelogOverrides.d.ts

@@ -1,53 +1,196 @@
 import type { ChangelogEntry, ChangelogOverride, WorkspaceConfig } from './types.js';
+/** Result of loading an override file: either parsed overrides or a list of structured errors. */
 export type LoadChangelogOverridesResult = {
     overrides: Map<string, ChangelogOverride>;
 } | {
     errors: string[];
 };
+/**
+ * Load and validate the editorial overrides file at `path`.
+ *
+ * - Missing file resolves to an empty map (no-op default; matches "absent file → unchanged behavior").
+ * - Malformed JSON, wrong top-level shape, or any per-entry validation failure surfaces as
+ *   structured errors. Callers decide how to surface them.
+ *
+ * Returns either `{ overrides: Map }` on success or `{ errors: string[] }` on failure. Pure
+ * except for the single file read; performs no other I/O.
+ */
 export declare function loadChangelogOverrides(path: string): LoadChangelogOverridesResult;
+/**
+ * Validate a parsed override record. Returns the parsed `Map` along with any error messages.
+ *
+ * Each error names the offending key (e.g. `overrides['abc']: 'audience' must be one of …`)
+ * so the consumer can locate it in their override file.
+ */
 export declare function validateChangelogOverrides(raw: unknown): {
     overrides: Map<string, ChangelogOverride>;
     errors: string[];
 };
+/**
+ * Format the standard "stale override key" warning. Callers compute the set of stale keys
+ * (keys that didn't match anywhere) and use this helper to surface them uniformly. Centralized
+ * so single-package and monorepo flows produce identical warning text.
+ */
 export declare function formatStaleOverrideKeyWarning(key: string): string;
+/**
+ * Apply overrides to a `ChangelogEntry[]`, returning a new array. Pure: no mutation, no I/O.
+ *
+ * Match algorithm: each override key is treated as a string-prefix against `ChangelogItem.hash`.
+ * - 0 matches → key is recorded as unmatched in this batch (no warning emitted here).
+ * - 1 match → apply each present override field to the matched item, record key as matched.
+ * - 2+ matches → error (ambiguous prefix).
+ *
+ * `matchedKeys` lists the override keys that resolved to exactly one item in this batch.
+ * Callers are responsible for computing stale-key warnings: in a monorepo run, an override
+ * may target a commit that lives in another workspace, so the per-batch zero-match signal is
+ * insufficient on its own. Single-package and monorepo orchestrators format warnings using
+ * `formatStaleOverrideKeyWarning` after aggregating `matchedKeys` across all apply calls.
+ *
+ * v1 audience semantics:
+ * - `'skip'` removes the matched item from its containing section. Empty sections are pruned.
+ *   Versions with zero sections still appear (matches existing "empty workspace" behavior).
+ * - `'all'` and `'dev'` are validated out before reaching the applier.
+ *
+ * Items without a `hash` (synthetic propagation entries) are never matched and pass through.
+ *
+ * The function does not throw; warnings/errors accumulate and are returned alongside the
+ * transformed entries so the caller decides whether to abort or log-and-continue.
+ */
 export declare function applyChangelogOverrides(entries: ChangelogEntry[], overrides: Map<string, ChangelogOverride>): {
     entries: ChangelogEntry[];
     warnings: string[];
     errors: string[];
     matchedKeys: string[];
 };
+/**
+ * Resolve the conventional override-file path for a given scope root.
+ *
+ * `scopeRoot` is the directory at which a scope's other artifacts live (e.g., `'.'` for the
+ * project, `'packages/foo'` for a workspace). The returned path is repo-relative.
+ */
 export declare function resolveOverridePath(scopeRoot: string): string;
+/** Result of {@link loadOverridesForScopes}: per-scope maps plus accumulated load/validation errors. */
 export interface LoadOverridesForScopesResult {
+    /** Project-tier (root) overrides. Empty map when the project file is absent. */
     project: Map<string, ChangelogOverride>;
+    /** Workspace-tier overrides keyed by `workspacePath` (e.g., `'packages/foo'`). Empty map when absent. */
     perWorkspace: Map<string, Map<string, ChangelogOverride>>;
+    /** All load and validation errors across every requested scope, prefixed with the offending file path. */
     errors: string[];
 }
+/**
+ * Load and validate every requested override file in one pass.
+ *
+ * Iterates the configured scope roots, calls {@link loadChangelogOverrides} for each, and
+ * aggregates errors across all files (rather than throwing on the first failure) so a
+ * consumer who edits multiple files at once sees every problem in one report. Missing files
+ * resolve to empty maps — matches the existing single-file behavior.
+ *
+ * The caller is expected to surface a combined error when `errors.length > 0` and abort the
+ * release before any workspace begins writing.
+ */
 export declare function loadOverridesForScopes(scopes: {
     project?: string;
     workspaces?: string[];
 }): LoadOverridesForScopesResult;
+/**
+ * Compose root and workspace override maps into a single effective map for one workspace.
+ *
+ * Byte-equal-key shadowing: when a workspace key string-equals a root key, the workspace
+ * entry wins entirely (no field-level merge) and supplants the root entry in the result.
+ * Different-prefix keys that happen to resolve to the same commit do NOT shadow here — they
+ * fall through to the existing ambiguous-prefix error in {@link applyChangelogOverrides}.
+ *
+ * Pure: never mutates inputs.
+ */
 export declare function composeOverrides(rootEntries: Map<string, ChangelogOverride>, workspaceEntries: Map<string, ChangelogOverride> | undefined): Map<string, ChangelogOverride>;
+/**
+ * Shared override-application context threaded through the per-workspace and project apply
+ * sites. Bundles the loaded per-scope maps with the run-scoped warning aggregators so each
+ * call site can both consume the maps it needs and report into the same warning channel.
+ *
+ * `globalMatchedRootKeys` tracks ROOT keys matched in any apply call. Workspace-sourced
+ * matched keys are not added here — they're tracked locally per workspace because their
+ * stale-key semantics are local (a workspace key that doesn't match in its own workspace is
+ * unambiguously stale and is warned immediately, not aggregated to end-of-run).
+ */
 export interface OverrideContext {
     project: Map<string, ChangelogOverride>;
     perWorkspace: Map<string, Map<string, ChangelogOverride>>;
     overrideWarnings: string[];
     globalMatchedRootKeys: Set<string>;
 }
+/**
+ * Load all per-scope override files (root + every workspace) in one upfront pass, validate
+ * them, and bundle the results with run-scoped warning aggregators. Aborts the release with
+ * a clear error when any file is malformed — checked-in editorial config that does not parse
+ * is a bug, and we want the prepare run to fail before any workspace begins writing.
+ */
 export declare function createOverrideContext(workspaces: WorkspaceConfig[]): OverrideContext;
+/** Per-scope input to {@link validateAllChangelogOverrides}. */
 export interface ChangelogOverrideScope {
+    /** Path to the override file (relative to the repo root). Used to load the file and to attribute findings. */
     filePath: string;
+    /** Commit hashes in this scope's history window. Each override key is matched against these. */
     hashes: readonly string[];
 }
+/** Inputs to {@link validateAllChangelogOverrides}. */
 export interface ValidateAllChangelogOverridesInputs {
+    /**
+     * Project-tier scope (the override file at the repo root).
+     *
+     * The file at `filePath` is loaded once and used in two ways:
+     * - Its overrides are composed into every workspace's apply (root-tier overrides apply globally).
+     * - When `hashes` is provided, the project map is also applied directly to that hash universe
+     *   (project release in monorepo mode, or the package's history in single-package mode).
+     *
+     * Omit when no project file exists (rare — most repos have a root file even if empty).
+     */
     project?: {
         filePath: string;
         hashes?: readonly string[];
     };
+    /** Per-workspace scopes. Each workspace's file applies only to its own hash universe. */
     workspaces?: readonly ChangelogOverrideScope[];
 }
+/** Result of {@link validateAllChangelogOverrides}: aggregated errors and warnings, each prefixed with the file path it pertains to. */
 export interface ValidateAllChangelogOverridesResult {
     errors: string[];
     warnings: string[];
 }
+/**
+ * End-to-end health check across every override file and scope. Pure: takes already-collected
+ * hash universes and returns aggregated findings. The CLI command and any other consumer
+ * (programmatic library callers, future composite checks) wrap this with discovery and I/O.
+ *
+ * When invoked via the standard `validateOverridesCommand` entry point, each scope's
+ * `hashes` is built by `buildChangelogEntries` — the same path `release-kit prepare` walks —
+ * so the match-set is byte-equal to what `prepare` would compute. The tier asymmetry is part
+ * of that contract: workspace-tier keys are stale if they don't match in their own workspace;
+ * root-tier keys are stale only if they don't match in any scope (no workspace AND not the
+ * project release window). Library callers that construct `inputs` directly are responsible
+ * for supplying the same hash universes if they want this guarantee.
+ *
+ * Every returned string is prefixed with the relative override-file path it pertains to so
+ * consumers can locate the offending file without further structuring.
+ */
 export declare function validateAllChangelogOverrides(inputs: ValidateAllChangelogOverridesInputs): ValidateAllChangelogOverridesResult;
+/**
+ * Apply the composed (root + workspace) override map to a workspace's changelog entries and
+ * report stale-key warnings tier-by-tier.
+ *
+ * The composed map is applied in a single {@link applyChangelogOverrides} call. Matched keys
+ * are demultiplexed by source via `Map.has` lookups on the original (uncomposed) maps so the
+ * stale-key semantics stay tier-aware:
+ *
+ * - Workspace-sourced keys (those present in the per-workspace map, regardless of whether
+ *   the root map also has the same byte-equal key) that did NOT match are unambiguously
+ *   stale in their own apply context — push an immediate stale warning naming the key.
+ * - Root-sourced matched keys (present in root, absent from this workspace's map) are added
+ *   to `globalMatchedRootKeys` so the orchestrator's end-of-run loop can dedupe across
+ *   batches and warn only on root keys that matched nowhere.
+ *
+ * Throws when any apply call surfaces an error (e.g. ambiguous prefix). Returns the applied
+ * result so the caller can consume `applied.entries` for downstream rendering.
+ */
 export declare function applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;

package/dist/esm/checkWorkTypesDrift.d.ts

@@ -1,11 +1,36 @@
+/** URL of the upstream canonical `work-types.json` published by codeassembly. */
 export declare const UPSTREAM_WORK_TYPES_URL = "https://raw.githubusercontent.com/williamthorsen/codeassembly/main/packages/agents/content/skills/_data/work-types.json";
+/** Outcome of a drift check, paired with a human-readable message. */
 export interface DriftCheckResult {
+    /**
+     * Process exit code semantics:
+     * - `0` — match (or upstream missing/transitional, with a warning).
+     * - `1` — drift detected.
+     * - `2` — network error.
+     * - `3` — schema mismatch (upstream JSON does not parse or fails the schema invariants).
+     */
     exitCode: 0 | 1 | 2 | 3;
     message: string;
 }
+/** Minimal injection seam so unit tests can substitute a deterministic fetcher. */
 export interface CheckWorkTypesDriftDependencies {
+    /** Absolute path of the local `work-types.json`. Defaults to the bundled file. */
     localPath?: string;
+    /** HTTP fetcher. Defaults to global `fetch` (Node 18+). */
     fetch?: typeof globalThis.fetch;
+    /** Override the upstream URL (used by tests; production callers should leave default). */
     upstreamUrl?: string;
 }
+/**
+ * Compare the bundled `work-types.json` against the upstream codeassembly canonical and
+ * report drift.
+ *
+ * Failure modes:
+ * - Network error → exit 2 with a diagnostic.
+ * - Upstream 404 → exit 0 with a transitional warning (codeassembly hasn't published the
+ *   JSON yet; the check is informational while migration is in flight).
+ * - Schema mismatch → exit 3 with a diagnostic.
+ * - Drift → exit 1 with a unified-diff-style message.
+ * - Match → exit 0.
+ */
 export declare function checkWorkTypesDrift(dependencies?: CheckWorkTypesDriftDependencies): Promise<DriftCheckResult>;

package/dist/esm/collectPolicyViolations.d.ts

@@ -1,5 +1,14 @@
 import type { PolicyViolationHandler } from './parseCommitMessage.js';
 import type { PolicyViolation } from './types.js';
+/**
+ * Build a fresh `policyViolations` accumulator paired with the `onPolicyViolation` callback
+ * that pushes structured entries into it.
+ *
+ * Used by all three release-prepare orchestrators (`releasePrepare`, `releasePrepareMono`,
+ * `releasePrepareProject`) to collect parser-side `!`-policy violations into a result-attachable
+ * array. Centralizing the callback shape keeps the `commitSubject` extraction rule (`firstLine
+ * post-split`) consistent across orchestrators.
+ */
 export declare function createPolicyViolationCollector(): {
     violations: PolicyViolation[];
     onPolicyViolation: PolicyViolationHandler;

package/dist/esm/commitCommand.d.ts

@@ -1 +1,7 @@
+/**
+ * Orchestrate the CLI `commit` command.
+ *
+ * Reads the tags and summary files produced by `prepare`, stages all
+ * changes, and creates a release commit with a formatted message.
+ */
 export declare function commitCommand(argv: string[]): void;

package/dist/esm/compareVersions.d.ts

@@ -1 +1,8 @@
+/**
+ * Return true when `target` is strictly greater than `current`, comparing major, minor, then patch.
+ *
+ * Equal versions return false. Comparison is numeric (not lexical), so `0.10.0` is greater than `0.9.0`.
+ *
+ * @throws If either version is not canonical `N.N.N` semver.
+ */
 export declare function isForwardVersion(current: string, target: string): boolean;