@williamthorsen/release-kit 12.0.0 → 13.0.0

package/dist/esm/changelogOverrides.d.ts

@@ -10,64 +10,47 @@ export type LoadChangelogOverridesResult = {
     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.
+ * Loads and validates the editorial overrides file at `path`. A missing file yields an empty map; an unreadable file,
+ * malformed JSON, a wrong top-level shape, or any per-entry validation failure yields errors.
  */
 export declare function loadChangelogOverrides(path: string): LoadChangelogOverridesResult;
 /**
- * Validate a parsed override record. Returns the parsed `Map` along with any error messages.
+ * Validates a parsed override record, returning the valid overrides and an error message for each problem.
  *
- * 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.
+ * Each error names the offending key (e.g. `overrides['abc']: 'audience' must be one of …`) so that the user can find
+ * it in the override file.
  */
 export declare function validateChangelogOverrides(raw: unknown): {
     overrides: Map<string, ChangelogOverride>;
     errors: string[];
 };
-/** Split a valid override key into its hash prefix and, for an ordinal key, its 1-based entry position. */
+/** Splits a valid override key into its hash prefix and, for an ordinal key, its 1-based entry position. */
 export declare function parseOverrideKey(key: string): {
     hashPrefix: string;
     entry?: number;
 };
-/**
- * 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.
- */
+/** Formats the warning for an override key that did not match any item in the changelog. */
 export declare function formatStaleOverrideKeyWarning(key: string): string;
 /**
- * Apply overrides to a `ChangelogEntry[]`, returning a new array. Pure: no mutation, no I/O.
+ * Applies overrides to changelog entries, returning new entries without mutating the input.
  *
- * Match algorithm: each key's hash prefix is matched against the distinct `ChangelogItem.hash` values.
- * - 0 matches → key is recorded as unmatched in this batch (no warning emitted here).
- * - 1 match → a bare key resolves to every item of that commit, and an ordinal key `<hash>:<n>` to the items whose
- *   `entry` is `n`. A key that resolves to no item is unmatched, so an ordinal key on a title-derived item goes stale.
- * - 2+ matches → error (ambiguous prefix).
+ * Each key's hash prefix is matched against the distinct `ChangelogItem.hash` values:
+ * - No match: The key is unmatched in this batch, and this function doesn't emit a warning.
+ * - One match: A bare key resolves to every item of that commit, and an ordinal key `<hash>:<n>` to the items whose
+ *   `entry` is `n`. A key that doesn't resolve to any item is unmatched, so an ordinal key on a title-derived item
+ *   goes stale.
+ * - Several matches: an error (ambiguous prefix).
  *
  * Two more conditions are errors, and the keys involved apply nowhere: a bare key that sets `description` or `body` on a
  * commit with several items, and two keys that resolve to the same item.
  *
- * `matchedKeys` lists the override keys that resolved to at least one item without error 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.
+ * `matchedKeys` lists the keys that resolved to at least one item without error. The caller computes stale-key
+ * warnings, because in a monorepo a key may target a commit in another workspace: A key unmatched in one batch is not
+ * necessarily stale.
  *
- * 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.
+ * An override whose audience is `'skip'` removes its item, and a section left empty is dropped; an entry left without
+ * sections is kept. An item without a `hash`, such as a synthetic propagation item, passes through unmatched. Errors
+ * are returned rather than thrown, and the caller decides whether to abort.
  */
 export declare function applyChangelogOverrides(entries: ChangelogEntry[], overrides: Map<string, ChangelogOverride>): {
     entries: ChangelogEntry[];
@@ -76,10 +59,8 @@ export declare function applyChangelogOverrides(entries: ChangelogEntry[], overr
     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.
+ * Resolves the conventional override-file path for a scope root: the directory in 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. */
@@ -92,40 +73,27 @@ export interface LoadOverridesForScopesResult {
     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.
+ * Loads and validates the override file of every requested scope, collecting the errors of all files rather than
+ * stopping at the first, so that a user who edits several files sees every problem in one report. A missing file
+ * yields an empty map.
  */
 export declare function loadOverridesForScopes(scopes: {
     project?: string;
     workspaces?: string[];
 }): LoadOverridesForScopesResult;
 /**
- * Compose root and workspace override maps into a single effective map for one workspace.
+ * Composes root and workspace override maps into the effective map for one workspace, without mutating either.
  *
- * 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.
- * Non-identical keys that resolve to the same item do NOT shadow here: {@link applyChangelogOverrides}
- * reports them as overlapping.
- *
- * Pure: never mutates inputs.
+ * A workspace key identical to a root key replaces the root entry entirely, without a field-level merge. Distinct keys
+ * that resolve to the same item do not shadow each other here: {@link applyChangelogOverrides} reports them as
+ * overlapping.
  */
 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.
+ * The loaded per-scope override maps and the run's warning aggregators, shared by every apply of a prepare run.
  *
- * `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).
+ * `globalMatchedRootKeys` contains the root keys matched in any apply. Workspace keys are not added: A workspace key
+ * that matches nothing in its own workspace is stale, and it is warned about at once rather than at the end of the run.
  */
 export interface OverrideContext {
     project: Map<string, ChangelogOverride>;
@@ -134,10 +102,9 @@ export interface OverrideContext {
     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.
+ * Loads and validates the override files of the root and every workspace, and bundles them with empty warning
+ * aggregators. Throws if any file fails to load, so that a malformed checked-in override file stops `prepare` before
+ * any workspace writes.
  */
 export declare function createOverrideContext(workspaces: WorkspaceConfig[]): OverrideContext;
 /** A changelog item as override matching sees it. `entry` is absent for a title-derived item. */
@@ -147,7 +114,10 @@ export interface OverrideTargetItem {
 }
 /** 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. */
+    /**
+     * Path to the override file, used to load the file and to attribute findings. A relative path resolves against the
+     * process working directory.
+     */
     filePath: string;
     /** Items in this scope's history window. Each override key is matched against these. */
     items: readonly OverrideTargetItem[];
@@ -162,7 +132,7 @@ export interface ValidateAllChangelogOverridesInputs {
      * - When `items` is provided, the project map is also applied directly to those items
      *   (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).
+     * Omit when the project file doesn't exist.
      */
     project?: {
         filePath: string;
@@ -171,44 +141,35 @@ export interface ValidateAllChangelogOverridesInputs {
     /** Per-workspace scopes. Each workspace's file applies only to its own items. */
     workspaces?: readonly ChangelogOverrideScope[];
 }
-/** Result of {@link validateAllChangelogOverrides}: aggregated errors and warnings, each prefixed with the file path it pertains to. */
+/**
+ * Result of {@link validateAllChangelogOverrides}: aggregated errors and warnings, each prefixed with the path of the
+ * file to which it pertains.
+ */
 export interface ValidateAllChangelogOverridesResult {
     errors: string[];
     warnings: string[];
 }
 /**
- * End-to-end health check across every override file and scope. Pure: takes already-collected
- * item 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.
+ * Validates every override file against the items of its scopes and returns the aggregated findings. It reads the
+ * override files but doesn't collect any items: The caller supplies each scope's items.
+ *
+ * Items built by `buildChangelogEntries`, as `release-kit prepare` builds them, yield the matches that `prepare`
+ * computes, tier asymmetry included: A workspace-tier key is stale when it matches nothing in its own workspace, and a
+ * root-tier key only when it matches nothing in any scope, the project release window included.
  *
- * When invoked via the standard `validateOverridesCommand` entry point, each scope's
- * `items` 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 item universes if they want this guarantee.
+ * Every returned string is prefixed with the path of the override file to which it pertains.
  *
- * Every returned string is prefixed with the relative override-file path it pertains to so
- * consumers can locate the offending file without further structuring.
+ * A relative `filePath`, in any scope, resolves against the process working directory, not against the repo root.
+ * A caller running from elsewhere passes absolute paths or changes directory first.
  */
 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.
+ * Applies the composed root and workspace override map to a workspace's changelog entries, and records stale keys by
+ * tier.
  *
- * 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.
+ * A workspace key that matched nothing, whether or not the root map has the same key, is stale, and it is warned about
+ * at once. The function adds each root key that matched without being shadowed to `globalMatchedRootKeys`, from which
+ * the caller warns, at the end of the run, about the root keys that matched nowhere. Throws if applying reports any
+ * error, such as an ambiguous prefix.
  */
 export declare function applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;

package/dist/esm/classifyChangelogCommit.d.ts

@@ -18,20 +18,18 @@ export type ChangelogClassification = {
 /**
  * Classifies a commit by its title.
  *
- * Four gates decide, in order: a `release:` or `Merge` subject is excluded; a subject carrying no ticket-ID prefix is
+ * Four gates decide, in order: A `release:` or `Merge` subject is excluded; a subject without a ticket-ID prefix is
  * unparseable; a type that `parseCommitMessage` cannot resolve against `workTypes` is unparseable; and a type that
- * `workTypes` excludes from the changelog is excluded. A commit that passes all four takes the header its type declares.
+ * `workTypes` excludes from the changelog is excluded. A commit that passes all four takes the header that its type
+ * declares.
  *
- * `options` reaches the parse, so a policy violation is reported for every ticketed commit whose type resolves,
- * excluded types included.
- *
- * The header carries no order encoding. `buildChangelogEntries` sorts sections by canonical priority, so
- * the position a section occupies comes from the taxonomy rather than from the header string.
+ * The function passes `options` to the parse, so a policy violation is reported for every ticketed commit whose type
+ * resolves, excluded types included.
  */
 export declare function classifyChangelogCommit(commit: Pick<Commit, 'hash' | 'message'>, workTypes: Record<string, WorkTypeConfig>, options?: ParseCommitMessageOptions): ChangelogClassification;
 /**
- * Reports whether a subject belongs to a commit that never reaches a changelog: a `release:` commit, which records
- * version bumps, or a git merge commit, whose content the merged commits already report.
+ * Reports whether a subject belongs to a commit that is never included in a changelog: a `release:` commit, which
+ * records version bumps, or a git merge commit, whose content the merged commits already report.
  */
 export declare function isNonChangeSubject(subject: string): boolean;
 /** Reports whether a subject belongs to a `release:` commit, which records version bumps rather than a change. */

package/dist/esm/classifyChangelogCommit.js

@@ -1,4 +1,5 @@
-import { COMMIT_PREPROCESSOR_PATTERNS, parseCommitMessage, } from "./parseCommitMessage.js";
+import { TICKET_PREFIX_PATTERNS } from '@williamthorsen/change-grammar';
+import { parseCommitMessage } from "./parseCommitMessage.js";
 const RELEASE_SUBJECT_PATTERN = /^release:/;
 const MERGE_SUBJECT_PATTERN = /^Merge/;
 export function classifyChangelogCommit(commit, workTypes, options) {
@@ -29,5 +30,5 @@ export function isReleaseSubject(subject) {
     return RELEASE_SUBJECT_PATTERN.test(subject);
 }
 function hasTicketPrefix(subject) {
-    return COMMIT_PREPROCESSOR_PATTERNS.some((pattern) => pattern.test(subject));
+    return TICKET_PREFIX_PATTERNS.some((pattern) => pattern.test(subject));
 }

package/dist/esm/commitCommand.d.ts

@@ -1,7 +1,5 @@
 /**
- * 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.
+ * Runs the CLI `commit` command: reads the tags and summary files written by `prepare`, stages all changes, and
+ * creates the release commit.
  */
 export declare function commitCommand(argv: string[]): void;

package/dist/esm/compareVersions.d.ts

@@ -1,8 +1,14 @@
 /**
- * Return true when `target` is strictly greater than `current`, comparing major, minor, then patch.
+ * Compares two version strings in descending order (newest first).
  *
- * 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.
+ * Valid SemVer inputs are ordered per SemVer §11 (delegated to `semver.rcompare`): prerelease
+ * versions precede the corresponding release (`1.2.3-alpha < 1.2.3`), and build metadata is
+ * ignored for ordering. Inputs that fail `semver.valid` sort to the bottom of the descending
+ * list, ordered lexically among themselves. The comparator never throws.
+ */
+export declare function compareVersionsDescending(a: string, b: string): number;
+/**
+ * Reports whether `target` is strictly greater than `current`, comparing major, minor, then patch numerically; throws
+ * unless both are canonical `N.N.N` semver.
  */
 export declare function isForwardVersion(current: string, target: string): boolean;

package/dist/esm/compareVersions.js

@@ -1,3 +1,4 @@
+import semver from 'semver';
 const CANONICAL_SEMVER_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/;
 function parseCanonicalSemver(version) {
     const match = version.match(CANONICAL_SEMVER_PATTERN);
@@ -11,6 +12,21 @@ function parseCanonicalSemver(version) {
         patch: Number.parseInt(patch, 10),
     };
 }
+export function compareVersionsDescending(a, b) {
+    const aValid = semver.valid(a);
+    const bValid = semver.valid(b);
+    if (aValid && bValid)
+        return semver.rcompare(aValid, bValid);
+    if (aValid)
+        return -1;
+    if (bValid)
+        return 1;
+    if (a > b)
+        return -1;
+    if (a < b)
+        return 1;
+    return 0;
+}
 export function isForwardVersion(current, target) {
     const currentParsed = parseCanonicalSemver(current);
     const targetParsed = parseCanonicalSemver(target);

package/dist/esm/configFlagSchema.d.ts

@@ -1,7 +1,7 @@
 /**
  * The `--config` flag, shared by every subcommand that reads the config file.
  *
- * Spread into a subcommand's own schema rather than repeated, so that seven subcommands cannot drift to seven
+ * Spread into a subcommand's own schema rather than repeated, so that the subcommands cannot drift to different
  * spellings of one flag.
  */
 export declare const configFlagSchema: {

package/dist/esm/createGithubRelease.d.ts

@@ -7,12 +7,8 @@ export interface CreateGithubReleaseOptions {
     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.
+ * Why a tag was skipped. `'no-entry'` covers every case of missing data (no changelog file, unparseable JSON, no entry
+ * for the version); the warnings that `createGithubRelease` prints tell them apart.
  */
 export type CreateReleaseSkipReason = 'no-entry' | 'no-audience-content' | 'empty-body';
 /** Discriminated outcome of attempting to create a single GitHub Release. */
@@ -23,13 +19,11 @@ export type CreateReleaseResult = {
     reason: CreateReleaseSkipReason;
 };
 /**
- * Create a GitHub Release from changelog.json using the `gh` CLI.
+ * Creates a GitHub Release for a tag through the `gh` CLI, with the all-audience notes of the tag's `changelog.json`
+ * entry as its body.
  *
- * 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.
+ * Returns a skip when the entry is missing (with a warning), doesn't have any all-audience content, or renders an empty
+ * body. Throws when `gh` fails, so that the caller does not exit 0 on a failed release.
  */
 export declare function createGithubRelease(options: CreateGithubReleaseOptions): CreateReleaseResult;
 /** Outcome of a `createGithubReleases` invocation. */
@@ -42,13 +36,7 @@ export interface CreateGithubReleasesOutcome {
         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.
- */
+/** Creates a GitHub Release for each tag and records each skip with its reason; throws at once when `gh` fails. */
 export declare function createGithubReleases(tags: Array<{
     tag: string;
     workspacePath: string;

package/dist/esm/createGithubReleaseCommand.d.ts

@@ -1,9 +1,9 @@
 import { type StreamStyles } from '@williamthorsen/nmr-core';
 /**
- * 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.
+ * Runs the CLI `create-github-release` command: creates GitHub Releases from `changelog.json` for the tags on HEAD, or
+ * a comma-separated `--tags` subset, without publishing to npm.
  *
- * 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.
+ * A private workspace's tag is skipped with a warning and doesn't get a Release; an all-private tag set is a clean
+ * no-op. A relative `--config` resolves against `invocationDir`.
  */
-export declare function createGithubReleaseCommand(argv: string[], styles: StreamStyles): Promise<void>;
+export declare function createGithubReleaseCommand(argv: string[], styles: StreamStyles, invocationDir: string): Promise<void>;

package/dist/esm/createGithubReleaseCommand.js

@@ -2,22 +2,24 @@ import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { configFlagSchema } from "./configFlagSchema.js";
 import { createGithubReleases } from "./createGithubRelease.js";
+import { deriveReleaseNotesConfig } from "./deriveReleaseNotesConfig.js";
 import { formatPrivateSkip } from "./formatPrivateSkip.js";
-import { assertConfigUsable } from "./loadValidatedConfig.js";
+import { loadUsableConfig } from "./loadValidatedConfig.js";
 import { parseRequestedTags } from "./parseRequestedTags.js";
 import { resolveCommandTags } from "./resolveCommandTags.js";
-import { resolveReleaseNotesConfig } from "./resolveReleaseNotesConfig.js";
+import { resolveConfigFlag } from "./resolveConfigFlag.js";
 const createGithubReleaseFlagSchema = {
     ...configFlagSchema,
     dryRun: { long: '--dry-run', type: 'boolean' },
     tags: { long: '--tags', type: 'string' },
 };
-export async function createGithubReleaseCommand(argv, styles) {
+export async function createGithubReleaseCommand(argv, styles, invocationDir) {
     const parsed = parseArgsOrExit(argv, createGithubReleaseFlagSchema);
+    const configPath = resolveConfigFlag(parsed.flags.config, invocationDir);
     const { dryRun } = parsed.flags;
-    await assertConfigUsable(styles.stderr, parsed.flags.config);
+    const userConfig = await loadUsableConfig(styles.stderr, configPath);
     const requestedTags = parseRequestedTags(parsed.flags.tags);
-    const resolvedTags = resolveCommandTags(requestedTags);
+    const resolvedTags = resolveCommandTags(requestedTags, userConfig);
     const publishableTags = resolvedTags.filter((resolvedTag) => resolvedTag.isPublishable);
     for (const resolvedTag of resolvedTags) {
         if (!resolvedTag.isPublishable) {
@@ -27,9 +29,7 @@ export async function createGithubReleaseCommand(argv, styles) {
     if (publishableTags.length === 0) {
         return;
     }
-    const { changelogJsonOutputPath, sectionOrder } = await resolveReleaseNotesConfig(styles.stderr, {
-        ...(parsed.flags.config !== undefined && { configPath: parsed.flags.config }),
-    });
+    const { changelogJsonOutputPath, sectionOrder } = deriveReleaseNotesConfig(userConfig);
     let outcome;
     try {
         outcome = createGithubReleases(publishableTags, changelogJsonOutputPath, dryRun, sectionOrder);
@@ -40,6 +40,6 @@ export async function createGithubReleaseCommand(argv, styles) {
     }
     if (outcome.skipped.length > 0) {
         const formatted = outcome.skipped.map((s) => `${s.tag} (${s.reason})`).join(', ');
-        console.info(`Skipped ${outcome.skipped.length} tag(s) with no releasable content: ${formatted}.`);
+        console.info(`Skipped ${outcome.skipped.length} tag(s) without releasable content: ${formatted}.`);
     }
 }

package/dist/esm/createTags.d.ts

@@ -5,8 +5,7 @@ export interface CreateTagsOptions {
     style: OutputStyle;
 }
 /**
- * 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).
+ * Creates an annotated git tag for each name in the tags file written by `prepare`, then deletes the tags and summary
+ * files, and returns the tag names. In dry-run mode, it only lists the names.
  */
 export declare function createTags(options: CreateTagsOptions): string[];

package/dist/esm/decideRelease.d.ts

@@ -10,8 +10,8 @@ export interface DecideReleaseArgs {
     /** Explicit `--bump=X` override. When set, the level is X regardless of the natural bump. */
     bumpOverride: ReleaseType | undefined;
     /**
-     * Skip wordings to use when no commits exist (`noCommits`) or when commits exist but none yields a changelog item
-     * (`noBumpWorthy`). Each path passes its own pre-rendered wordings.
+     * Skip wordings to use when the window doesn't contain any commits (`noCommits`) or when it contains commits but none
+     * yields a changelog item (`noBumpWorthy`). Each path passes its own pre-rendered wordings.
      */
     skipReasons: {
         noCommits: string;
@@ -29,10 +29,6 @@ export type DecideReleaseResult = {
 /**
  * Decides whether a window releases, and at which level.
  *
- * Algorithm:
- *   shouldRelease = naturalBump !== undefined OR force === true
- *   releaseLevel  = bumpOverride ?? naturalBump ?? 'patch'
- *
  * A window without a natural bump releases only under `--force`, so `--bump=X` chooses a level without triggering a
  * release, and `--force` triggers one without choosing a level.
  */

package/dist/esm/defaults.d.ts

@@ -1,33 +1,14 @@
+import { type BreakingPolicy } from '@williamthorsen/change-grammar';
 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) cannot disagree on the composition rule.
- */
+/** Composes the rendered section heading of a work-type entry as `${emoji} ${label}`. */
 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.
- */
+/** Default work types, ordered by canonical priority. */
 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'>;
+/** The breaking policy of each canonical work type, which decides whether a `!` on it is a policy violation. */
+export declare const DEFAULT_BREAKING_POLICIES: Record<string, BreakingPolicy>;
 /** Default version bump patterns. */
 export declare const DEFAULT_VERSION_PATTERNS: VersionPatterns;
 /** Default configuration for structured changelog JSON generation. */

package/dist/esm/defaults.js

@@ -1,12 +1,11 @@
-import { WORK_TYPES_DATA } from "./workTypesData.js";
-export { WORK_TYPES_DATA } from "./workTypesData.js";
+import { CANONICAL_TAXONOMY } from '@williamthorsen/change-grammar';
 export function composeHeader(entry) {
     return `${entry.emoji} ${entry.label}`;
 }
 const DEV_ONLY_TIERS = new Set(['internal', 'process']);
 function deriveDefaultWorkTypes() {
     const result = {};
-    for (const entry of WORK_TYPES_DATA.types) {
+    for (const entry of CANONICAL_TAXONOMY.types) {
         const config = {
             header: composeHeader(entry),
         };
@@ -22,7 +21,7 @@ function deriveDefaultWorkTypes() {
 }
 function deriveDevOnlySections() {
     const sections = [];
-    for (const entry of WORK_TYPES_DATA.types) {
+    for (const entry of CANONICAL_TAXONOMY.types) {
         if (!DEV_ONLY_TIERS.has(entry.tier)) {
             continue;
         }
@@ -34,7 +33,7 @@ function deriveDevOnlySections() {
     return sections;
 }
 export const DEFAULT_WORK_TYPES = deriveDefaultWorkTypes();
-export const DEFAULT_BREAKING_POLICIES = Object.fromEntries(WORK_TYPES_DATA.types.map((entry) => [entry.key, entry.breakingPolicy]));
+export const DEFAULT_BREAKING_POLICIES = Object.fromEntries(CANONICAL_TAXONOMY.types.map((entry) => [entry.key, entry.breakingPolicy]));
 export const DEFAULT_VERSION_PATTERNS = {
     major: ['!'],
     minor: ['feat'],

package/dist/esm/defineConfig.d.ts

@@ -1,7 +1,7 @@
 import type { ReleaseKitConfig } from './types.js';
 export type { LabelSpec, ReleaseKitConfig, RepoLabelsConfig } from './types.js';
 /**
- * Type-safe identity function for configuration files.
+ * Returns a configuration unchanged, typing it as a `ReleaseKitConfig`.
  *
  * Usage in `.config/release-kit.config.ts`:
  * ```ts

package/dist/esm/deleteFileIfExists.d.ts

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

package/dist/esm/deriveReleaseNotesConfig.d.ts

@@ -0,0 +1,20 @@
+import type { ReleaseKitConfig, ReleaseNotesConfig } from './types.js';
+export interface ResolvedReleaseNotesConfig {
+    releaseNotes: ReleaseNotesConfig;
+    changelogJsonOutputPath: string;
+    /** Section titles in priority order, derived from the merged workTypes record. */
+    sectionOrder: string[];
+}
+/**
+ * Returns the header of a merged `workTypes` record's `deps` entry, which titles the synthetic propagation section.
+ * Throws when the record lacks one, which `resolveWorkTypes` never produces.
+ */
+export declare function deriveDependenciesHeader(workTypes: Record<string, {
+    header: string;
+}>): string;
+/** Derives the release-notes settings from a loaded config, falling back to the defaults for an absent one. */
+export declare function deriveReleaseNotesConfig(config: ReleaseKitConfig | undefined): ResolvedReleaseNotesConfig;
+/** Returns the section headers of a merged `workTypes` record, in declaration order. */
+export declare function deriveSectionOrder(workTypes: Record<string, {
+    header: string;
+}>): string[];