@williamthorsen/release-kit 12.0.0 → 13.0.0

package/dist/esm/types.d.ts

@@ -1,3 +1,4 @@
+import type { BreakingPolicy } from '@williamthorsen/change-grammar';
 import { z } from 'zod';
 /** Semver release type for version bumping. */
 export type ReleaseType = 'major' | 'minor' | 'patch';
@@ -11,30 +12,27 @@ export interface ChangelogItem {
     /**
      * Whether this item represents a breaking change.
      *
-     * `true` when the commit subject carries the `!` prefix (e.g. `feat!:` or `drop(scope)!:`), or the
+     * `true` when the commit subject has the `!` marker (e.g. `feat!:` or `drop(scope)!:`), or the
      * change-record entry from which the item derives sets `breaking: true`, and the work-type policy
-     * permits it, so the item agrees with the version bump.
-     * The `BREAKING CHANGE:` body footer is intentionally NOT considered here. 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.
+     * permits it, so that the item agrees with the version bump. The `BREAKING CHANGE:` body footer
+     * does not set it.
      */
     breaking?: boolean;
     /**
      * Migration instruction for a consumer, taken from the `Migration:` paragraph of `body`, or from
      * the `migration` of the change-record entry from which the item derives.
      *
-     * On a title-derived item, derived from `body` wherever `body` is set, and absent where the body
-     * carries no labeled paragraph. Independent of `breaking`: a `deprecate` commit cannot carry `!` under the default
-     * breaking policy and still calls for a migration. `body` keeps the paragraph, so
-     * `CHANGELOG.md` goes on rendering it in place.
+     * On a title-derived item, derived from `body` whenever `body` is set, and absent when the body
+     * does not contain any labeled paragraph. Independent of `breaking`: A `deprecate` commit cannot
+     * take `!` under the default breaking policy and still calls for a migration. `body` keeps the
+     * paragraph, so `CHANGELOG.md` goes on rendering it in place.
      */
     migration?: string;
     /**
      * Full git commit SHA when known. Captured from the commit's release window 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.
+     * this field absent, because they do not have any underlying commit.
      */
     hash?: string;
     /**
@@ -47,8 +45,8 @@ export interface ChangelogItem {
 export interface ChangelogSection {
     /**
      * Section title, read from the work type of the commit or of its change-record entry. A default
-     * title carries the type's emoji prefix (e.g. `"🐛 Bug fixes"`), so callers that match against
-     * `title` (e.g. `sectionOrder` configs) include that prefix.
+     * title begins with the type's emoji (e.g. `"🐛 Bug fixes"`), which an exact match against
+     * `title`, such as a `sectionOrder` list, must include.
      */
     title: string;
     audience: ChangelogAudience;
@@ -69,12 +67,10 @@ export interface ChangelogJsonConfig {
 /**
  * Editorial override for changelog items, keyed in the override file by `<hash>` (every item of the commit) or
  * `<hash>:<n>` (the item derived from the commit's `n`th change-record entry), where the hash is lowercase hex
- * matched as a prefix. All fields are optional; an entry with no fields is a validation error.
+ * matched as a prefix. All fields are optional; an entry without any 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.
+ * `audience` admits `'all'` and `'dev'`, but the validator rejects both with a "not yet supported"
+ * error; only `'skip'` takes effect.
  */
 export interface ChangelogOverride {
     audience?: 'all' | 'dev' | 'skip';
@@ -91,16 +87,11 @@ export type ChangelogOverridesFile = Record<string, ChangelogOverride>;
 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`.
- */
+/** Project-release config after merging defaults: `ProjectConfig` with every field required. */
 export interface ResolvedProjectConfig {
     /**
      * Resolved commit window for the project release: the git pathspecs that select which commits
-     * the stage considers. Defaults to the union of every contributing
-     * workspace's `paths`.
+     * the stage considers. Defaults to the union of every contributing workspace's `paths`.
      */
     paths: string[];
     /** Resolved tag prefix for project-level tags. */
@@ -112,11 +103,8 @@ export interface PropagationSource {
     newVersion: string;
 }
 /**
- * A `!`-policy violation detected while reading the unreleased window 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.
+ * A `!`-policy violation detected while reading the unreleased window during release preparation. Violations are
+ * reported and never fail the release.
  */
 export interface PolicyViolation {
     /** Full hash of the offending commit. */
@@ -142,7 +130,10 @@ export interface MalformedChangeRecordBlock {
     /** The defect that stopped the read. */
     reason: string;
 }
-/** A change-record entry whose type the work-type taxonomy does not declare, so that it yielded no changelog item. */
+/**
+ * A change-record entry whose type the work-type taxonomy does not declare, so that it did not yield any changelog
+ * item.
+ */
 export interface UndeclaredEntryType {
     /** Full hash of the commit. */
     commitHash: string;
@@ -153,13 +144,32 @@ export interface UndeclaredEntryType {
     /** The type as the entry declares it. */
     type: string;
 }
+/** A change-record entry scope that does not name any workspace whose unreleased window contains its commit. */
+export interface UnroutedEntryScope {
+    /** Full hash of the commit. */
+    commitHash: string;
+    /** First line of the commit message. */
+    commitSubject: string;
+    /** 1-based position of the entry in its block. */
+    entryPosition: number;
+    /** The scope as the entry declares it. */
+    scope: string;
+}
 /**
- * Result of preparing a single workspace (package) for release when a release was produced.
- *
- * `currentVersion`, `newVersion`, `tag`, `bumpedFiles`, and `changelogFiles` are always
- * populated. `releaseType` and `parsedCommitCount` stay optional because they are left
- * undefined for `--set-version` and propagation-only workspaces. `commits` stays optional
- * because propagation-only releases have no direct commits.
+ * What `prepare` did with the existing `##` sections of one `CHANGELOG.md` that the regenerated file does not render
+ * from entries.
+ */
+export interface ChangelogPreservation {
+    /** The `CHANGELOG.md` path. */
+    file: string;
+    /** Versions whose sections were kept verbatim, because neither the built entries nor `changelog.json` contain them. */
+    preservedVersions: string[];
+    /** Headings of the sections that do not name any version, which the regenerated file does not contain. */
+    droppedUnversionedHeadings: string[];
+}
+/**
+ * Result of preparing a single workspace (package) for release when a release was produced. `releaseType` is absent
+ * for `--set-version`.
  */
 export interface ReleasedWorkspaceResult {
     status: 'released';
@@ -168,12 +178,12 @@ export interface ReleasedWorkspaceResult {
     previousTag?: string;
     commitCount: number;
     /**
-     * Count of commits that yield at least one changelog item — `0` when there are no commits or
-     * when none does. Absent for `--set-version` and propagation-only workspaces. Use
-     * `bumpOverride` as the signal for "the user supplied --bump=X".
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does
+     * not contain any commits or when none does. Absent for `--set-version` and propagation-only
+     * workspaces. `bumpOverride`, not this count, signals that the user supplied `--bump=X`.
      */
     parsedCommitCount?: number;
-    /** Commits that yield no changelog item and that no exclusion or diagnostic accounts for. */
+    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
     unparseableCommits?: Commit[];
     /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
     policyViolations?: PolicyViolation[];
@@ -181,6 +191,8 @@ export interface ReleasedWorkspaceResult {
     malformedBlocks?: MalformedChangeRecordBlock[];
     /** Change-record entries of the unreleased window whose type is undeclared; omitted when none. */
     undeclaredEntryTypes?: UndeclaredEntryType[];
+    /** Change-record entry scopes of the unreleased window that route their entry nowhere; omitted when none. */
+    unroutedEntryScopes?: UnroutedEntryScope[];
     releaseType?: ReleaseType;
     currentVersion: string;
     newVersion: string;
@@ -189,24 +201,28 @@ export interface ReleasedWorkspaceResult {
     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). */
+    /**
+     * Per `CHANGELOG.md`, the existing sections that were kept or dropped; omitted when `prepare` did not keep or drop
+     * any.
+     */
+    changelogPreservation?: ChangelogPreservation[];
+    /** Raw commits of the workspace's unreleased window. */
     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.
+     * Present when `--bump=X` was supplied and selected the release level for this workspace, which
+     * distinguishes a bump-override release from a `--force` fallback or a natural-bump release.
      */
     bumpOverride?: ReleaseType;
     /** Dependencies that triggered a propagated bump (present for propagated or mixed workspaces). */
     propagatedFrom?: PropagationSource[];
+    /** Present when propagation alone set the bump, the workspace's own commits having called for none. */
+    propagatedOnly?: true;
     /** 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.
+ * Result of preparing a single workspace (package) for release when the release was skipped: the diagnostic fields
+ * and a human-readable `skipReason`, without the release-only fields.
  */
 export interface SkippedWorkspaceResult {
     status: 'skipped';
@@ -214,9 +230,12 @@ export interface SkippedWorkspaceResult {
     name?: string;
     previousTag?: string;
     commitCount: number;
-    /** Count of commits that yield at least one changelog item — `0` when there are no commits or when none does. */
+    /**
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does not contain any
+     * commits or when none does.
+     */
     parsedCommitCount: number;
-    /** Commits that yield no changelog item and that no exclusion or diagnostic accounts for. */
+    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
     unparseableCommits?: Commit[];
     /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
     policyViolations?: PolicyViolation[];
@@ -224,6 +243,8 @@ export interface SkippedWorkspaceResult {
     malformedBlocks?: MalformedChangeRecordBlock[];
     /** Change-record entries of the unreleased window whose type is undeclared; omitted when none. */
     undeclaredEntryTypes?: UndeclaredEntryType[];
+    /** Change-record entry scopes of the unreleased window that route their entry nowhere; omitted when none. */
+    unroutedEntryScopes?: UnroutedEntryScope[];
     skipReason: string;
 }
 /**
@@ -236,22 +257,20 @@ export type WorkspacePrepareResult = ReleasedWorkspaceResult | SkippedWorkspaceR
 /**
  * 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.
+ * Mirrors `ReleasedWorkspaceResult` without the workspace-only fields. Project releases never propagate and never
+ * use `--set-version`, so `releaseType`, `parsedCommitCount`, and `commits` are required.
  */
 export interface ReleasedProjectResult {
     status: 'released';
     previousTag?: string;
     commitCount: number;
     /**
-     * Count of commits that yield at least one changelog item — `0` when there are no commits or
-     * when none does. Use `bumpOverride` (not `parsedCommitCount === 0`) as the signal for "the
-     * user supplied --bump=X".
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does
+     * not contain any commits or when none does. `bumpOverride`, not a zero count, signals that the
+     * user supplied `--bump=X`.
      */
     parsedCommitCount: number;
-    /** Commits that yield no changelog item and that no exclusion or diagnostic accounts for. */
+    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
     unparseableCommits?: Commit[];
     /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
     policyViolations?: PolicyViolation[];
@@ -267,28 +286,33 @@ export interface ReleasedProjectResult {
     changelogFiles: string[];
     /** Release-notes preview files; present only under `--with-release-notes`. */
     previewFiles?: string[];
+    /**
+     * Per `CHANGELOG.md`, the existing sections that were kept or dropped; omitted when `prepare` did not keep or drop
+     * any.
+     */
+    changelogPreservation?: ChangelogPreservation[];
     /** 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.
+     * Present when `--bump=X` was supplied and selected the release level for the project, which
+     * distinguishes a bump-override release from a `--force` fallback or a natural-bump release.
      */
     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.
+ * Result of preparing a project-level release when the release was skipped: the diagnostic fields and a
+ * human-readable `skipReason`, without the release-only fields.
  */
 export interface SkippedProjectResult {
     status: 'skipped';
     previousTag?: string;
     commitCount: number;
-    /** Count of commits that yield at least one changelog item — `0` when there are no commits or when none does. */
+    /**
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does not contain any
+     * commits or when none does.
+     */
     parsedCommitCount: number;
-    /** Commits that yield no changelog item and that no exclusion or diagnostic accounts for. */
+    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
     unparseableCommits?: Commit[];
     /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
     policyViolations?: PolicyViolation[];
@@ -303,8 +327,8 @@ export interface SkippedProjectResult {
  *
  * 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.
+ * the config does not declare a `project` block or that `--only` narrowed the run, which skips
+ * the stage before it can produce a result; `prepare` reports the skip as a run warning instead.
  */
 export type ProjectPrepareResult = ReleasedProjectResult | SkippedProjectResult;
 /** Aggregate result of the prepare workflow for both single-package and monorepo modes. */
@@ -315,7 +339,7 @@ export interface PrepareResult {
         command: string;
         files: string[];
     } | undefined;
-    /** Warnings surfaced during preparation (e.g., circular dependency detection). */
+    /** Warnings reported 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;
@@ -327,9 +351,9 @@ export interface WorkTypeConfig {
     /** Optional aliases that map to this work type (e.g., 'feature' -> 'feat'). */
     aliases?: string[] | undefined;
     /**
-     * Keeps commits and change-record entries of this type out of every changelog. They yield no
-     * item, so they contribute nothing to the version bump, and the release report does not list
-     * them as unparseable.
+     * Keeps commits and change-record entries of this type out of every changelog. They do not yield
+     * any item, so they contribute nothing to the version bump, and the release report does not
+     * list them as unparseable.
      */
     excludedFromChangelog?: boolean | undefined;
 }
@@ -356,15 +380,15 @@ export declare const legacyIdentitySchema: z.ZodObject<{
     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.
+ * A single historical identity snapshot for a workspace. Both fields are required, because a full
+ * tuple stays unambiguous across any number of 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
+ * or changelog attribution; they acknowledge historical tag prefixes and suppress
  * undeclared-candidate warnings.
  */
 export declare const retiredPackageSchema: z.ZodObject<{
@@ -415,9 +439,8 @@ export declare const versionPatternsSchema: z.ZodObject<{
 }, z.core.$strict>;
 /** Schema for a single `breakingPolicies` value. */
 export declare const breakingPolicyValueSchema: z.ZodEnum<{
-    forbidden: "forbidden";
     optional: "optional";
-    required: "required";
+    forbidden: "forbidden";
 }>;
 /** Schema for a single label's spec in the `repoLabels.labels` record. */
 export declare const labelSpecSchema: z.ZodObject<{
@@ -427,7 +450,7 @@ export declare const labelSpecSchema: z.ZodObject<{
 /**
  * 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.
+ * clears whatever description the label has on the repo.
  */
 export type LabelSpec = z.infer<typeof labelSpecSchema>;
 /**
@@ -435,10 +458,10 @@ export type LabelSpec = z.infer<typeof labelSpecSchema>;
  * 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`). Names match
+ * in which an entry adds a label, replaces one that an earlier layer defined, or removes it (`null`). Names match
  * case-insensitively, as GitHub matches them, and the replacing layer's spelling wins.
  * Two misstatements are resolve-time errors (`resolveLabels`), not schema errors: `labels` keys that differ only in
- * case, and a `null` naming a label that no earlier layer defined.
+ * case, and a `null` naming a label not defined by any earlier layer.
  */
 export declare const repoLabelsSchema: z.ZodObject<{
     extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -452,9 +475,8 @@ 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";
         optional: "optional";
-        required: "required";
+        forbidden: "forbidden";
     }>>>;
     changelogJson: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
@@ -537,12 +559,11 @@ export interface WorkspaceConfig {
     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`). */
+    /** Repo-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.
+     * is absent or `false`; `false` only when `private === true`.
      */
     isPublishable: boolean;
     /** Paths to package.json files to bump. */
@@ -571,7 +592,7 @@ export interface MonorepoReleaseConfig {
      * When provided, replaces the default entirely.
      * Pass `{}` to disable enforcement (parser falls back to `'optional'` for missing types).
      */
-    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    breakingPolicies?: Record<string, BreakingPolicy>;
     /**
      * 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
@@ -589,11 +610,13 @@ export interface MonorepoReleaseConfig {
     /** 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-level release config. Present when the config declares a `project` block, in which case
+     * `prepare` runs a project-release stage after the per-workspace loop.
      */
     project?: ResolvedProjectConfig;
 }
+/** Monorepo config as seen by the prepare workflow, which does not read release-notes configuration. */
+export type MonorepoPrepareConfig = Omit<MonorepoReleaseConfig, 'releaseNotes'>;
 /** Configuration for the release workflow. */
 export interface ReleaseConfig {
     /** The git tag prefix used to identify version tags (e.g., 'v'). */
@@ -611,7 +634,7 @@ export interface ReleaseConfig {
      * provided, replaces the default entirely. Pass `{}` to disable enforcement (parser falls
      * back to `'optional'` for missing types).
      */
-    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    breakingPolicies?: Record<string, BreakingPolicy>;
     /**
      * 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.
@@ -629,3 +652,5 @@ export interface ReleaseConfig {
     /** Controls release notes consumption (README injection). */
     releaseNotes: ReleaseNotesConfig;
 }
+/** Single-package config as seen by the prepare workflow, which does not read release-notes configuration. */
+export type PrepareConfig = Omit<ReleaseConfig, 'releaseNotes'>;

package/dist/esm/types.js

@@ -50,7 +50,7 @@ export const versionPatternsSchema = z
     minor: z.array(z.string()),
 })
     .strict();
-export const breakingPolicyValueSchema = z.enum(['forbidden', 'optional', 'required']);
+export const breakingPolicyValueSchema = z.enum(['forbidden', 'optional']);
 export const labelSpecSchema = z
     .object({
     color: z.string().min(1),

package/dist/esm/validateConfig.d.ts

@@ -1,16 +1,7 @@
 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.
+ * Validates a raw config object loaded from `.config/release-kit.config.ts`. Returns `{}` with the errors for a config
+ * that fails the schema parse, and runs the cross-field checks on one that passes.
  */
 export declare function validateConfig(raw: unknown): {
     config: ReleaseKitConfig;

package/dist/esm/validateConfig.js

@@ -31,11 +31,11 @@ function preprocessDeprecatedKeys(raw) {
     const errors = [];
     const cleaned = { ...raw };
     if (Object.hasOwn(cleaned, 'cliffConfigPath')) {
-        errors.push('cliffConfigPath is no longer supported. release-kit reads changelog history from git directly and uses no external config file. Remove this field from your config, and delete the file it names.');
+        errors.push('cliffConfigPath is no longer supported. release-kit reads changelog history from git directly and does not use any external config file. Remove this field from the config, and delete the file that it names.');
         delete cleaned['cliffConfigPath'];
     }
     if (isRecord(cleaned['releaseNotes']) && Object.hasOwn(cleaned['releaseNotes'], 'shouldCreateGithubRelease')) {
-        errors.push('releaseNotes.shouldCreateGithubRelease is no longer supported. Adoption is now signaled by installing the create-github-release workflow, which `release-kit init` scaffolds. Remove this field from your config.');
+        errors.push('releaseNotes.shouldCreateGithubRelease is no longer supported. Adoption is now signaled by installing the create-github-release workflow, which `release-kit init` scaffolds. Remove this field from the config.');
         const releaseNotesCopy = { ...cleaned['releaseNotes'] };
         delete releaseNotesCopy['shouldCreateGithubRelease'];
         cleaned['releaseNotes'] = releaseNotesCopy;

package/dist/esm/validateOnlyExcludesStrandedDependents.d.ts

@@ -4,32 +4,34 @@ import type { WorkspaceConfig } from './types.js';
 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. */
+    /**
+     * The baseline tag from which the commits were measured; `undefined` when the workspace does not have a prior tag.
+     */
     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. */
+    /** The `dir` of the released (or anticipated-release) dependency whose release republishes this workspace. */
     downstreamOf: string;
-    /** The baseline tag from which D's commits were counted; `undefined` if no prior tag. */
+    /**
+     * The baseline tag from which this workspace's commits were counted; `undefined` if the workspace does not have a
+     * 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.
+ * Detects `--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).
+ * First computes R, the `--only` workspaces that will release, then walks the reverse-dependency graph breadth-first
+ * from R and records each excluded workspace with its own commits as a violation. The walk continues through a
+ * violation, as though the user had added it to `--only`, which reports deeper violations in the same pass. It stops
+ * at an excluded workspace without commits, which does not republish, so its dependents are unaffected by R.
  *
- * Returns `undefined` when no violations are found, or a sorted list otherwise.
+ * Returns `undefined` when the walk does not find any violation, or the violations sorted by `dir`.
  */
 export declare function validateOnlyExcludesStrandedDependents(workspaces: readonly WorkspaceConfig[], only: readonly string[], graph: DependencyGraph, hasCommits: CommitsProbe): StrandedDependentViolation[] | undefined;
 export {};

package/dist/esm/validateOverridesCommand.d.ts

@@ -1,17 +1,18 @@
 import { type OutputStyle, type StreamStyles } from '@williamthorsen/nmr-core';
+import { type ReleaseHistoryConfig } from './buildChangelogEntries.js';
 import { type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult } from './changelogOverrides.js';
 import { type WorkspaceDiscovery } from './discoverWorkspaces.js';
 import { type GenerateChangelogOptions } from './generateChangelogs.js';
 import { type LoadValidatedConfigResult } from './loadValidatedConfig.js';
-import type { ChangelogEntry, ReleaseConfig } from './types.js';
+import type { ChangelogEntry } from './types.js';
 /**
- * Result of {@link validateOverridesCommand}: tiered exit code paired with a human-readable
- * message, which keeps the CLI dispatch layer thin.
+ * Result of {@link validateOverridesCommand}: a tiered exit code paired with a human-readable message.
  *
  * Exit codes:
- * - `0` — clean: no errors, no warnings.
- * - `1` — only stale-key warnings.
- * - `2` — schema/parse errors or keys that fail to match (ambiguous prefix, overlapping keys, a bare key setting fields on several items) (errors dominate when both classes exist).
+ * - `0`: clean, with no errors and no warnings.
+ * - `1`: only stale-key warnings.
+ * - `2`: schema or parse errors, or keys that fail to match (an ambiguous prefix, overlapping keys, or a bare key
+ *   that sets fields on several items). Errors take precedence when both classes exist.
  */
 export interface ValidateOverridesCommandResult {
     exitCode: 0 | 1 | 2;
@@ -22,30 +23,26 @@ export interface ValidateOverridesCommandDependencies {
     discoverWorkspaces?: () => WorkspaceDiscovery;
     loadValidatedConfig?: () => Promise<LoadValidatedConfigResult>;
     /**
-     * Build changelog entries for a scope. Defaults to `buildChangelogEntries`, the same path
-     * `release-kit prepare` uses — anchoring `validate`'s item universe to `prepare`'s by
-     * construction.
+     * Builds changelog entries for a scope. Defaults to `buildChangelogEntries`, which `release-kit prepare` also
+     * uses, so that `validate` sees the same items as `prepare`.
      */
-    buildEntries?: (config: Pick<ReleaseConfig, 'breakingPolicies' | 'changelogJson' | 'workTypes'>, options: GenerateChangelogOptions) => ChangelogEntry[];
-    /** Pluggable validator (default: the production library function). Tests use this to drive specific result shapes through the formatter. */
+    buildEntries?: (config: ReleaseHistoryConfig, options: GenerateChangelogOptions) => ChangelogEntry[];
+    /** Validator; defaults to `validateAllChangelogOverrides`. Tests use it to feed specific results to 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,
+ * Validates every changelog override file across the project and per-workspace scopes, and
+ * returns a tiered exit-code-plus-message result. Performs workspace discovery, config load,
  * and per-scope item 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. A workspace declaring
- * patterns that resolve to no package is neither, and exits `2`.
+ * 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. A workspace that doesn't resolve
+ * to any package is neither, and the command returns exit code `2` for it.
  *
  * `configPath` names the config file to read, relative to the working directory; it defaults to
  * `CONFIG_FILE_PATH`.
  */
 export declare function validateOverridesCommand(styles: StreamStyles, configPath?: string, 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.
- */
+/** Returns the tiered exit code and rendered message for an aggregated validation result. */
 export declare function formatValidateOverridesResult(result: ValidateAllChangelogOverridesResult, style: OutputStyle): ValidateOverridesCommandResult;

package/dist/esm/validateOverridesCommand.js

@@ -100,7 +100,7 @@ function buildMonorepoInputs(discoveredPaths, userConfig, buildEntries) {
     const rootPackage = readRootPackageVersion();
     const config = mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage);
     const workspaces = config.workspaces.map((workspace) => {
-        const options = { tagPrefixes: getAllTagPrefixes(workspace), paths: workspace.paths };
+        const options = { tagPrefixes: getAllTagPrefixes(workspace), paths: workspace.paths, workspaceDir: workspace.dir };
         return {
             filePath: resolveOverridePath(workspace.workspacePath),
             items: flattenEntriesToItems(buildEntries(config, options)),