@williamthorsen/release-kit 10.5.0 → 10.7.0

package/dist/esm/bin/release-kit.js

@@ -35,8 +35,9 @@ Commands:
   work-types       Check for or sync work-type taxonomy drift against the upstream canonical
 
 Options:
-  --dry-run     Preview changes without writing files
-  --help, -h    Show this help message
+  --dry-run        Preview changes without writing files
+  --help, -h       Show this help message
+  --version, -V    Show the version number
 `);
 }
 function showSyncLabelsHelp() {
@@ -95,7 +96,7 @@ function showInitHelp() {
 Usage: release-kit init [options]
 
 Initialize release-kit in the current repository.
-By default, scaffolds only the GitHub Actions workflow file.
+By default, scaffolds only the GitHub Actions workflow files.
 
 Options:
   --with-config   Also scaffold .config/release-kit.config.ts and .config/git-cliff.toml

package/dist/esm/buildChangelogEntries.js

@@ -1,6 +1,7 @@
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { extractVersion } from "./changelogJsonUtils.js";
 import { DEFAULT_WORK_TYPES } from "./defaults.js";
+import { extractMigration } from "./extractMigration.js";
 import { COMMIT_PREPROCESSOR_PATTERNS, PIPE_SCOPE_SOURCE } from "./parseCommitMessage.js";
 import { resolveCliffConfigPath } from "./resolveCliffConfigPath.js";
 import { runGitCliff } from "./runGitCliff.js";
@@ -101,6 +102,10 @@ function transformReleases(releases, devOnlySections) {
             if (breaking) {
                 item.breaking = true;
             }
+            const migration = extractMigration(body);
+            if (migration !== undefined) {
+                item.migration = migration;
+            }
             if (commit.id !== undefined && commit.id !== '') {
                 item.hash = commit.id;
             }

package/dist/esm/buildDependencyGraph.d.ts

@@ -1,10 +1,12 @@
 import type { WorkspaceConfig } from './types.js';
-/** Reverse adjacency map from package names to their workspace dependents. */
+/** Identities, current versions, and `workspace:` dependency edges of the workspaces' packages. */
 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>;
+    /** Resolve a workspace `dir` to its current version; absent when its `package.json` has no string `version`. */
+    dirToVersion: Map<string, string>;
     /** Map a package name to the workspaces that depend on it. */
     dependentsOf: Map<string, WorkspaceConfig[]>;
     /**
@@ -14,11 +16,10 @@ export interface DependencyGraph {
     dependenciesOf: Map<string, Set<string>>;
 }
 /**
- * Build a reverse dependency graph from the workspaces' `package.json` files.
+ * Builds the 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.
+ * `workspace:` references in `dependencies` and `peerDependencies`, and to record its current
+ * version.
  */
 export declare function buildDependencyGraph(workspaces: readonly WorkspaceConfig[]): DependencyGraph;

package/dist/esm/buildDependencyGraph.js

@@ -6,6 +6,7 @@ function isPackageJsonSubset(value) {
 export function buildDependencyGraph(workspaces) {
     const packageNameToDir = new Map();
     const dirToPackageName = new Map();
+    const dirToVersion = new Map();
     const dependentsOf = new Map();
     const dependenciesOf = new Map();
     const workspacePackages = new Map();
@@ -16,6 +17,9 @@ export function buildDependencyGraph(workspaces) {
         }
         const pkg = readPackageJsonSubset(primaryPackageFile);
         workspacePackages.set(workspace, pkg);
+        if (typeof pkg.version === 'string') {
+            dirToVersion.set(workspace.dir, pkg.version);
+        }
         if (pkg.name === undefined) {
             continue;
         }
@@ -44,7 +48,7 @@ export function buildDependencyGraph(workspaces) {
             }
         }
     }
-    return { packageNameToDir, dirToPackageName, dependentsOf, dependenciesOf };
+    return { packageNameToDir, dirToPackageName, dirToVersion, dependentsOf, dependenciesOf };
 }
 function readPackageJsonSubset(filePath) {
     let content;

package/dist/esm/changelogJsonUtils.d.ts

@@ -1,13 +1,11 @@
-import type { ChangelogEntry, ChangelogItem } from './types.js';
+import type { ChangelogEntry } from './types.js';
 /**
- * Type guard for `ChangelogItem` values parsed from JSON.
+ * Type guard for `ChangelogEntry` 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.
+ * Checks the entry's top level only: `sections` is verified to be an array, and its contents pass
+ * through unvalidated. `.meta/changelog.json` is written by release-kit and read tolerantly; strict
+ * validation applies to the human-authored `.meta/changelog-overrides.json`, in `changelogOverrides.ts`.
  */
-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;

package/dist/esm/changelogJsonUtils.js

@@ -1,18 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { isRecord, isUnknownArray } from "./typeGuards.js";
-export function isChangelogItem(value) {
-    if (!isRecord(value))
-        return false;
-    if (typeof value['description'] !== 'string')
-        return false;
-    if (value['body'] !== undefined && typeof value['body'] !== 'string')
-        return false;
-    if (value['breaking'] !== undefined && typeof value['breaking'] !== 'boolean')
-        return false;
-    if (value['hash'] !== undefined && typeof value['hash'] !== 'string')
-        return false;
-    return true;
-}
 export function isChangelogEntry(value) {
     return (isRecord(value) &&
         typeof value['version'] === 'string' &&

package/dist/esm/changelogOverrides.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { extractMigration } from "./extractMigration.js";
 import { isRecord } from "./typeGuards.js";
 const OVERRIDES_FILENAME = '.meta/changelog-overrides.json';
 const VALID_AUDIENCE_VALUES = new Set(['all', 'dev', 'skip']);
@@ -206,6 +207,13 @@ function applyOverrideToItem(item, override) {
     }
     if (override.body !== undefined) {
         result.body = override.body;
+        const migration = extractMigration(override.body);
+        if (migration === undefined) {
+            delete result.migration;
+        }
+        else {
+            result.migration = migration;
+        }
     }
     if (override.breaking !== undefined) {
         result.breaking = override.breaking;

package/dist/esm/extractMigration.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Extracts the instruction from a commit body's `Migration:` paragraph.
+ *
+ * The first paragraph opening with the label wins: the lede doctrine specifies one labeled
+ * paragraph per body, so a second is ignored rather than appended. The match is anchored and
+ * case-sensitive, so `migration:` and `**Migration:**` yield nothing; the doctrine calls the
+ * label literal, and tolerating variants would let the form drift.
+ *
+ * Newlines inside the paragraph are preserved. The first character is capitalized, which is
+ * inert for the imperative the doctrine requires and repairs the lowercase continuation of a
+ * paragraph written before it. Returns `undefined` when no paragraph carries the label, or when
+ * the label is followed by nothing.
+ */
+export declare function extractMigration(body: string | undefined): string | undefined;

package/dist/esm/extractMigration.js

@@ -0,0 +1,18 @@
+const PARAGRAPH_SEPARATOR = /\n(?:[ \t]*\n)+/;
+const MIGRATION_LABEL = /^Migration:[ \t]*/;
+export function extractMigration(body) {
+    if (body === undefined) {
+        return undefined;
+    }
+    for (const paragraph of body.split(PARAGRAPH_SEPARATOR)) {
+        if (!MIGRATION_LABEL.test(paragraph)) {
+            continue;
+        }
+        const instruction = paragraph.replace(MIGRATION_LABEL, '').trim();
+        if (instruction.length === 0) {
+            return undefined;
+        }
+        return instruction.charAt(0).toUpperCase() + instruction.slice(1);
+    }
+    return undefined;
+}

package/dist/esm/init/scaffold.js

@@ -1,22 +1,30 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { findPackageRoot, writeFileWithCheck } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { createGithubReleaseWorkflow, publishWorkflow, releaseConfigScript, releaseWorkflow } from "./templates.js";
 export function copyCliffTemplate(dryRun, overwrite) {
     const destPath = '.config/git-cliff.toml';
-    const root = findPackageRoot(import.meta.url);
-    const templatePath = resolve(root, 'cliff.toml.template');
-    if (!existsSync(templatePath)) {
-        return { filePath: destPath, outcome: 'failed', error: `Could not find bundled template at ${templatePath}` };
+    let root;
+    try {
+        root = findPackageRoot(import.meta.url);
+    }
+    catch (error) {
+        const message = describeError(error);
+        return { filePath: destPath, outcome: 'failed', error: `Failed to resolve package root: ${message}` };
     }
+    const templatePath = resolve(root, 'cliff.toml.template');
     let content;
     try {
         content = readFileSync(templatePath, 'utf8');
     }
     catch (error) {
         const message = describeError(error);
-        return { filePath: destPath, outcome: 'failed', error: `Failed to read template ${templatePath}: ${message}` };
+        return {
+            filePath: destPath,
+            outcome: 'failed',
+            error: `Failed to read bundled template at ${templatePath}: ${message}`,
+        };
     }
     return writeFileWithCheck(destPath, content, { dryRun, overwrite });
 }

package/dist/esm/packsPath.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reports whether npm would place `path` in the published tarball, given a package.json `files` value.
+ *
+ * An absent or malformed `files` value packs everything, so it reports `true`; an empty array packs nothing
+ * beyond the files npm always includes, so it reports `false`. An entry naming an ancestor directory covers
+ * everything beneath it, which is how `files: ["dist/*"]` ships `dist/esm/index.js`, so every ancestor prefix
+ * of `path` is tested rather than `path` alone.
+ *
+ * Two approximations of npm's packing rules remain, both failing toward a silent pass: a negation entry
+ * (`!dist/*.map`) never counts toward inclusion, because gitignore-style ordered negation is not modeled; and a
+ * repo controlling its tarball through `.npmignore` alone declares no `files` field, so it reports `true`
+ * without the ignore file being read. For a check that warns about an omission, a missed report costs less than
+ * a false one.
+ */
+export declare function packsPath(filesField: unknown, path: string): boolean;

package/dist/esm/packsPath.js

@@ -0,0 +1,47 @@
+export function packsPath(filesField, path) {
+    if (!isStringArray(filesField))
+        return true;
+    const prefixes = listAncestorPrefixes(path);
+    return filesField.some((entry) => {
+        const pattern = compileEntry(entry);
+        return pattern !== undefined && prefixes.some((prefix) => pattern.test(prefix));
+    });
+}
+const GLOB_TOKEN_PATTERN = /\*\*\/|\*\*|\*|\?|[^*?]+/g;
+function compileEntry(entry) {
+    if (entry.startsWith('!'))
+        return undefined;
+    const normalized = entry.replace(/^\.?\//, '').replace(/\/+$/, '');
+    if (normalized === '')
+        return undefined;
+    return new RegExp(`^${translateGlob(normalized)}$`);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+function listAncestorPrefixes(path) {
+    const segments = path.split('/');
+    return segments.map((_segment, index) => segments.slice(0, index + 1).join('/'));
+}
+function translateGlob(pattern) {
+    let source = '';
+    for (const [token] of pattern.matchAll(GLOB_TOKEN_PATTERN)) {
+        switch (token) {
+            case '**/':
+                source += String.raw `(?:[^/]*\/)*`;
+                break;
+            case '**':
+                source += '.*';
+                break;
+            case '*':
+                source += '[^/]*';
+                break;
+            case '?':
+                source += '[^/]';
+                break;
+            default:
+                source += RegExp.escape(token);
+        }
+    }
+    return source;
+}

package/dist/esm/planVersionBump.d.ts

@@ -16,6 +16,7 @@ export interface VersionBumpPlan {
 export declare function planVersionBump(packageFiles: readonly string[], releaseType: ReleaseType): VersionBumpPlan;
 /**
  * Computes an explicit version assignment for a workspace's package files without writing them,
- * bypassing commit-derived bump logic. Backs the `--set-version` flag.
+ * bypassing commit-derived bump logic. Backs the `--set-version` flag, and so rejects a
+ * `newVersion` that is not greater than the current version.
  */
 export declare function planVersionSet(packageFiles: readonly string[], newVersion: string): VersionBumpPlan;

package/dist/esm/planVersionBump.js

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { bumpVersion } from "./bumpVersion.js";
+import { isForwardVersion } from "./compareVersions.js";
 function isPackageJson(value) {
     return typeof value === 'object' && value !== null && 'version' in value && typeof value.version === 'string';
 }
@@ -13,6 +14,9 @@ export function planVersionBump(packageFiles, releaseType) {
 export function planVersionSet(packageFiles, newVersion) {
     const { firstFile, firstPkg } = readPrimaryPackage(packageFiles);
     const currentVersion = firstPkg.version;
+    if (!isForwardVersion(currentVersion, newVersion)) {
+        throw new Error(`--set-version ${newVersion} is not greater than current version ${currentVersion}`);
+    }
     return { currentVersion, newVersion, writes: renderVersionWrites(packageFiles, firstFile, firstPkg, newVersion) };
 }
 function readPrimaryPackage(packageFiles) {

package/dist/esm/propagateBumps.d.ts

@@ -12,8 +12,6 @@ export interface ReleaseEntry {
      */
     newVersionOverride?: string;
 }
-/** Map from workspace `dir` to its current version string (read from package.json). */
-export type CurrentVersions = Map<string, string>;
 /**
  * Walk upward through the dependency graph via BFS, adding `patch` bumps for dependents
  * not already in the release set with a higher bump.
@@ -21,4 +19,4 @@ export type CurrentVersions = Map<string, string>;
  * Returns the full release set (direct + propagated). Direct entries that also have a
  * propagated dependency get `propagatedFrom` metadata without changing their bump type.
  */
-export declare function propagateBumps(directBumps: Map<string, ReleaseEntry>, graph: DependencyGraph, currentVersions: CurrentVersions): Map<string, ReleaseEntry>;
+export declare function propagateBumps(directBumps: Map<string, ReleaseEntry>, graph: DependencyGraph): Map<string, ReleaseEntry>;

package/dist/esm/propagateBumps.js

@@ -1,5 +1,5 @@
 import { bumpVersion } from "./bumpVersion.js";
-export function propagateBumps(directBumps, graph, currentVersions) {
+export function propagateBumps(directBumps, graph) {
     const result = new Map();
     for (const [dir, entry] of directBumps) {
         result.set(dir, { ...entry });
@@ -19,7 +19,7 @@ export function propagateBumps(directBumps, graph, currentVersions) {
         if (packageName === undefined) {
             continue;
         }
-        const currentVersion = currentVersions.get(dir);
+        const currentVersion = graph.dirToVersion.get(dir);
         const entry = result.get(dir);
         if (currentVersion === undefined || entry === undefined) {
             continue;

package/dist/esm/releasePrepare.js

@@ -5,7 +5,6 @@ import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyChangelogOverrides, formatStaleOverrideKeyWarning, loadOverridesForScopes, } from "./changelogOverrides.js";
 import { createPolicyViolationCollector } from "./collectPolicyViolations.js";
-import { isForwardVersion } from "./compareVersions.js";
 import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
 import { determineBumpFromCommits } from "./determineBumpFromCommits.js";
 import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
@@ -13,10 +12,8 @@ import { hasPrettierConfig } from "./hasPrettierConfig.js";
 import { resolveWorkTypes } from "./loadConfig.js";
 import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
 import { planVersionBump, planVersionSet } from "./planVersionBump.js";
-import { readCurrentVersion } from "./readCurrentVersion.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
-import { refreshGitCliffCache } from "./runGitCliff.js";
 export function releasePrepare(config, options) {
     const { bumpOverride, setVersion, withReleaseNotes } = options;
     const writes = [];
@@ -35,18 +32,6 @@ export function releasePrepare(config, options) {
     const collector = createPolicyViolationCollector();
     let bump;
     if (setVersion !== undefined) {
-        const primaryPackageFile = config.packageFiles[0];
-        if (primaryPackageFile === undefined) {
-            throw new Error('No package files specified');
-        }
-        const currentVersion = readCurrentVersion(primaryPackageFile);
-        if (currentVersion === undefined) {
-            throw new Error(`Cannot validate --set-version: failed to read current version from ${primaryPackageFile}`);
-        }
-        if (!isForwardVersion(currentVersion, setVersion)) {
-            throw new Error(`--set-version ${setVersion} is not greater than current version ${currentVersion}`);
-        }
-        refreshGitCliffCache();
         bump = planVersionSet(config.packageFiles, setVersion);
     }
     else {
@@ -78,7 +63,6 @@ export function releasePrepare(config, options) {
                 formatCommand: undefined,
             };
         }
-        refreshGitCliffCache();
         bump = planVersionBump(config.packageFiles, releaseType);
     }
     writes.push(...bump.writes);

package/dist/esm/releasePrepareMono.js

@@ -8,7 +8,6 @@ import { buildSyntheticChangelogEntry } from "./buildSyntheticChangelogEntry.js"
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyWorkspaceOverrides, createOverrideContext, formatStaleOverrideKeyWarning, } from "./changelogOverrides.js";
 import { createPolicyViolationCollector } from "./collectPolicyViolations.js";
-import { isForwardVersion } from "./compareVersions.js";
 import { decideRelease } from "./decideRelease.js";
 import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
 import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
@@ -19,11 +18,9 @@ import { resolveWorkTypes } from "./loadConfig.js";
 import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
 import { planVersionBump, planVersionSet } from "./planVersionBump.js";
 import { propagateBumps } from "./propagateBumps.js";
-import { readCurrentVersion } from "./readCurrentVersion.js";
 import { releasePrepareProject } from "./releasePrepareProject.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
-import { refreshGitCliffCache } from "./runGitCliff.js";
 export function releasePrepareMono(config, options) {
     const { only, withReleaseNotes } = options;
     const writes = [];
@@ -33,7 +30,7 @@ export function releasePrepareMono(config, options) {
     }
     const sectionOrder = deriveSectionOrder(resolveWorkTypes(config.workTypes));
     const overrideContext = createOverrideContext(config.workspaces);
-    const { directBumps, directResults, skippedResults, currentVersions } = determineDirectBumps(config, options);
+    const { directBumps, directResults, skippedResults } = determineDirectBumps(config, options);
     const previousTags = new Map();
     for (const result of directResults.values()) {
         previousTags.set(result.workspace.dir, result.tag);
@@ -42,7 +39,7 @@ export function releasePrepareMono(config, options) {
         previousTags.set(skipped.workspace.dir, skipped.tag);
     }
     const graph = buildDependencyGraph(config.workspaces);
-    const fullReleaseSet = propagateBumps(directBumps, graph, currentVersions);
+    const fullReleaseSet = propagateBumps(directBumps, graph);
     const { sorted: sortedDirs, cyclicDirs } = topologicalSort(fullReleaseSet, graph);
     if (cyclicDirs.length > 0) {
         warnings.push(`Circular workspace dependencies detected among: ${cyclicDirs.join(', ')}. ` +
@@ -53,9 +50,6 @@ export function releasePrepareMono(config, options) {
         enabled: withReleaseNotes === true && config.changelogJson.enabled,
         sectionOrder,
     };
-    if (fullReleaseSet.size > 0) {
-        refreshGitCliffCache();
-    }
     const { tags, modifiedFiles } = executeReleaseSet({
         sortedDirs,
         fullReleaseSet,
@@ -123,7 +117,6 @@ function determineDirectBumps(config, options) {
     const directBumps = new Map();
     const directResults = new Map();
     const skippedResults = [];
-    const currentVersions = new Map();
     const hintState = { emitted: false };
     const knownPrefixes = config.workspaces.flatMap(getAllTagPrefixes);
     for (const workspace of config.workspaces) {
@@ -134,21 +127,7 @@ function determineDirectBumps(config, options) {
         if (tag === undefined) {
             maybeEmitBaselineHint(workspace, knownPrefixes, hintState);
         }
-        const primaryPackageFile = workspace.packageFiles[0];
-        if (primaryPackageFile !== undefined) {
-            const currentVersion = tryStage(stageLabel, () => readCurrentVersion(primaryPackageFile));
-            if (currentVersion !== undefined) {
-                currentVersions.set(workspace.dir, currentVersion);
-            }
-        }
         if (setVersion !== undefined) {
-            const currentVersion = currentVersions.get(workspace.dir);
-            if (currentVersion === undefined) {
-                throw new Error(`Cannot validate --set-version: failed to read current version from ${primaryPackageFile ?? '(no package file)'}`);
-            }
-            if (!isForwardVersion(currentVersion, setVersion)) {
-                throw new Error(`--set-version ${setVersion} is not greater than current version ${currentVersion}`);
-            }
             directBumps.set(workspace.dir, { releaseType: 'patch', newVersionOverride: setVersion });
             directResults.set(workspace.dir, {
                 workspace,
@@ -203,7 +182,7 @@ function determineDirectBumps(config, options) {
             bumpOverride,
         });
     }
-    return { directBumps, directResults, skippedResults, currentVersions };
+    return { directBumps, directResults, skippedResults };
 }
 function collectSkippedWorkspaces(skippedResults, fullReleaseSet) {
     const workspaces = [];

package/dist/esm/reportPrepare.js

@@ -1,4 +1,6 @@
 import { bold, dim, sectionHeader } from "./format.js";
+import { GIT_CLIFF_NPX_ARGS } from "./runGitCliff.js";
+const CLIFF_DRY_RUN_COMMAND = `npx ${GIT_CLIFF_NPX_ARGS.join(' ')} ...`;
 export function reportPrepare(plan, options) {
     const isMultiWorkspace = plan.workspaces.some((w) => w.name !== undefined) || plan.project !== undefined;
     if (isMultiWorkspace) {
@@ -103,7 +105,7 @@ function formatProjectSection(lines, project, dryRun) {
     lines.push(dim('  Generating changelogs...'));
     for (const file of project.changelogFiles) {
         if (dryRun) {
-            lines.push(dim(`    [dry-run] Would run: npx --yes git-cliff ... --output ${file}`));
+            lines.push(dim(`    [dry-run] Would run: ${CLIFF_DRY_RUN_COMMAND} --output ${file}`));
         }
         else {
             lines.push(dim(`    Generating changelog: ${file}`));
@@ -195,7 +197,7 @@ function formatBumpFiles(lines, workspace, dryRun, indent = '') {
 function formatChangelogFiles(lines, workspace, dryRun, indent = '') {
     for (const file of workspace.changelogFiles) {
         if (dryRun) {
-            lines.push(dim(`${indent}  [dry-run] Would run: npx --yes git-cliff ... --output ${file}`));
+            lines.push(dim(`${indent}  [dry-run] Would run: ${CLIFF_DRY_RUN_COMMAND} --output ${file}`));
         }
         else {
             lines.push(dim(`${indent}  Generating changelog: ${file}`));

package/dist/esm/runGitCliff.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The exact `git-cliff` version every invocation resolves.
+ *
+ * npm's `git-cliff` trails the upstream release, so this pin normally sits behind the newest version cliff
+ * itself reports. Bumping it is an edit to this line, once npm publishes the version you want.
+ */
+export declare const GIT_CLIFF_VERSION = "2.13.1";
+/** The npx arguments that precede the cliff args at every invocation, and that the dry-run report renders. */
+export declare const GIT_CLIFF_NPX_ARGS: readonly string[];
 /**
  * Invokes `git-cliff` via `npx` and returns the output it produced.
  *
@@ -9,15 +18,14 @@
  * entire matching tag history on every run, so its size grows without bound with the repo;
  * a file accommodates that, while a pipe is bounded by `maxBuffer`.
  *
- * The `--prefer-offline` flag and `npm_config_progress=false` env entry are deliberate: `--prefer-offline` skips
- * npx's per-call npm-registry revalidation HTTP round-trip (~2.5 s per invocation on a warm cache), and
- * `npm_config_progress=false` suppresses npx's animated stderr spinner, which otherwise renders as a transient flicker.
+ * The npx spec names an exact version, which leaves npm no staleness to check, so `--prefer-offline` skips the
+ * per-call registry revalidation round-trip (~2.5 s per invocation on a warm cache) without stranding the run
+ * on whatever the cache happens to hold.
  *
- * Because `--prefer-offline` also suppresses npx's cache-staleness check, the cached `git-cliff` binary
- * would otherwise drift further and further behind upstream, with each cliff invocation re-emitting the
- * "A new version of git-cliff is available" notice and the local cache never updating.
- * `refreshGitCliffCache` (below) revalidates the cache once at the top of each `prepare` run so that
- * subsequent `--prefer-offline` calls run against a current binary.
+ * Two env entries are set for the child. `npm_config_progress=false` suppresses npx's animated stderr spinner,
+ * which otherwise renders as a transient flicker. `RUST_LOG=warn` drops cliff's INFO lines, among them the
+ * crates.io update notice it emits on every invocation while npm trails upstream, and leaves warnings and errors
+ * in place; an inherited `RUST_LOG` wins, so raising the level for debugging still works.
  *
  * The helper injects `--config <path>` and `--output <path>` itself — callers must NOT include either in `cliffArgs`.
  * `--output` is appended last so a caller that passes one anyway cannot redirect the output the helper then reads.
@@ -28,18 +36,3 @@
  * The temp-dir cleanup runs in a `finally` so it still happens on throw.
  */
 export declare function runGitCliff(cliffConfigPath: string, cliffArgs: readonly string[]): string;
-/**
- * Revalidate npx's cache for `git-cliff` once per `prepare` run.
- *
- * Spawns `npx --yes git-cliff --version` *without* `--prefer-offline`, so that npm performs its normal
- * registry-staleness check and refreshes the cached binary if a newer version is available.
- * Subsequent `runGitCliff` calls within the same run keep `--prefer-offline` (preserving the per-call perf win)
- * but now run against an up-to-date cache, so git-cliff's own self-update notice no longer fires repeatedly.
- *
- * Stdio: stdin ignored, stdout piped (the version line is suppressed as noise), stderr inherited (npm errors and
- * any rare upgrade notice surface, but only once per run). `maxBuffer` is declared even though the piped output
- * is a single version line, because every call that pipes stdout declares one.
- *
- * Errors propagate unchanged — a failed cache refresh fails the prepare run loudly rather than silently degrading.
- */
-export declare function refreshGitCliffCache(): void;

package/dist/esm/runGitCliff.js

@@ -2,7 +2,8 @@ import { execFileSync } from 'node:child_process';
 import { copyFileSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { GIT_OUTPUT_LIMIT } from '@williamthorsen/nmr-core';
+export const GIT_CLIFF_VERSION = '2.13.1';
+export const GIT_CLIFF_NPX_ARGS = ['--prefer-offline', '--yes', `git-cliff@${GIT_CLIFF_VERSION}`];
 export function runGitCliff(cliffConfigPath, cliffArgs) {
     const tempDir = mkdtempSync(join(tmpdir(), 'cliff-'));
     try {
@@ -12,9 +13,9 @@ export function runGitCliff(cliffConfigPath, cliffArgs) {
             copyFileSync(cliffConfigPath, configPath);
         }
         const outputPath = join(tempDir, 'output.json');
-        execFileSync('npx', ['--prefer-offline', '--yes', 'git-cliff', '--config', configPath, ...cliffArgs, '--output', outputPath], {
+        execFileSync('npx', [...GIT_CLIFF_NPX_ARGS, '--config', configPath, ...cliffArgs, '--output', outputPath], {
             stdio: ['ignore', 'ignore', 'inherit'],
-            env: { ...process.env, npm_config_progress: 'false' },
+            env: { ...process.env, npm_config_progress: 'false', RUST_LOG: process.env['RUST_LOG'] ?? 'warn' },
         });
         return readFileSync(outputPath, 'utf8');
     }
@@ -22,10 +23,3 @@ export function runGitCliff(cliffConfigPath, cliffArgs) {
         rmSync(tempDir, { recursive: true, force: true });
     }
 }
-export function refreshGitCliffCache() {
-    execFileSync('npx', ['--yes', 'git-cliff', '--version'], {
-        maxBuffer: GIT_OUTPUT_LIMIT,
-        stdio: ['ignore', 'pipe', 'inherit'],
-        env: { ...process.env, npm_config_progress: 'false' },
-    });
-}

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

@@ -5,9 +5,11 @@ import type { LabelDefinition } from './types.js';
  *
  * Resolution is an ordered fold with last-writer-wins: presets are loaded in `extends` order (a later preset replaces
  * an earlier preset's label of the same name), then the `labels` record is applied: An entry adds a label, replaces
- * one an earlier layer defined, or removes it (`null`). Replacement is wholesale, so an entry omitting `description`
+ * one an earlier layer defined, or removes it (`null`). Names match case-insensitively, as GitHub matches them, and the
+ * replacing layer's spelling becomes the label's name. Replacement is wholesale, so an entry omitting `description`
  * drops the one an earlier layer supplied rather than inheriting it.
- * Throws only on a dangling `null`: a removal naming a label no preset defined, which is a stale reference that
- * would otherwise produce no output diff to review.
+ * Throws on two misstatements that would otherwise leave no trace in the output diff: keys in the `labels` record that
+ * differ only in case, all but one of which the fold would discard, and a dangling `null`, a removal naming a label that
+ * no preset defined.
  */
 export declare function resolveLabels(config: RepoLabelsConfig): LabelDefinition[];