@williamthorsen/release-kit 11.0.0 → 13.0.0

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

@@ -4,11 +4,14 @@ import { describeError } from '@williamthorsen/toolbelt.errors';
 import { commitCommand } from "../commitCommand.js";
 import { configFlagSchema } from "../configFlagSchema.js";
 import { createGithubReleaseCommand } from "../createGithubReleaseCommand.js";
+import { enterRepoRoot } from "../enterRepoRoot.js";
 import { showPrepareHelp } from "../help/prepareHelp.js";
 import { initCommand } from "../init/initCommand.js";
+import { updateTemplatesCommand } from "../init/updateTemplatesCommand.js";
 import { prepareCommand } from "../prepareCommand.js";
 import { publishCommand } from "../publishCommand.js";
 import { pushCommand } from "../pushCommand.js";
+import { resolveConfigFlag } from "../resolveConfigFlag.js";
 import { OUTPUT_STYLE_ENV_VAR, resolveStylesOrExit } from "../resolveStylesOrExit.js";
 import { showTagPrefixesCommand } from "../showTagPrefixesCommand.js";
 import { generateCommand } from "../sync-labels/generateCommand.js";
@@ -30,6 +33,7 @@ Commands:
   create-github-release  Create GitHub Releases from changelog.json for tags on HEAD
   show-tag-prefixes  Show derived and declared legacy tag prefixes per workspace
   init             Initialize release-kit in the current repository
+  update-templates Update the scaffolded workflows to the current templates
   overrides        Manage editorial changelog overrides
   sync-labels      Manage GitHub label synchronization
 
@@ -69,7 +73,8 @@ retired packages, then generate .github/labels.yaml. When the config file alread
 exists, print the block for manual paste instead of rewriting the file.
 
 Options:
-  --config <path>  Path to config file (default: .config/release-kit.config.ts)
+  --config <path>  Config file, relative to the current directory
+                   (default: .config/release-kit.config.ts at the repo root)
   --dry-run        Preview changes without writing files
   --force          Overwrite existing files instead of skipping them
   --help, -h       Show this help message
@@ -83,7 +88,8 @@ Regenerate .github/labels.yaml from the repoLabels block of .config/release-kit.
 
 Options:
   --check          Report whether .github/labels.yaml is stale instead of writing it
-  --config <path>  Path to config file (default: .config/release-kit.config.ts)
+  --config <path>  Config file, relative to the current directory
+                   (default: .config/release-kit.config.ts at the repo root)
   --help, -h       Show this help message
 `);
 }
@@ -105,12 +111,26 @@ Initialize release-kit in the current repository.
 By default, scaffolds only the GitHub Actions workflow files.
 
 Options:
-  --with-config   Also scaffold .config/release-kit.config.ts and .config/git-cliff.toml
+  --with-config   Also scaffold .config/release-kit.config.ts
   --force         Overwrite existing files instead of skipping them
   --dry-run       Preview changes without writing files
   --help, -h      Show this help message
 `);
 }
+function showUpdateTemplatesHelp() {
+    console.info(`
+Usage: release-kit update-templates [options]
+
+Update the GitHub Actions workflows that release-kit scaffolds to the templates
+of the installed version, showing what changed in each file. Creates a missing
+workflow that \`init\` would create, and refreshes sync-labels.yaml only when it
+exists. Keeps publish.yaml's provenance setting. Never touches config files.
+
+Options:
+  --dry-run       Preview changes without writing files
+  --help, -h      Show this help message
+`);
+}
 function showCommitHelp() {
     console.info(`
 Usage: release-kit commit [options]
@@ -139,10 +159,12 @@ function showPushHelp() {
     console.info(`
 Usage: release-kit push [options]
 
-Push the release commit and each tag individually, ensuring GitHub Actions
-fires a separate workflow run per tag.
+Push the release commit and each tag individually, so that GitHub Actions
+starts a separate workflow run for each tag.
 
 Options:
+  --config <path>        Config file, relative to the current directory
+                         (default: .config/release-kit.config.ts at the repo root)
   --dry-run              Preview without pushing
   --tags=tag1,tag2       Only push the named tags (comma-separated, full tag names)
   --tags-only            Skip the branch push (push tags only)
@@ -154,10 +176,12 @@ function showCreateGithubReleaseHelp() {
 Usage: release-kit create-github-release [options]
 
 Create GitHub Releases from changelog.json for tags on HEAD. Private
-(package.json#private) workspaces are skipped with a warning and get no Release.
+(package.json#private) workspaces are skipped with a warning, and the command
+doesn't create a Release for them.
 
 Options:
-  --config <path>        Path to config file (default: .config/release-kit.config.ts)
+  --config <path>        Config file, relative to the current directory
+                         (default: .config/release-kit.config.ts at the repo root)
   --dry-run              Preview without creating releases
   --tags=tag1,tag2       Only create releases for the named tags (comma-separated, full tag names)
   --help, -h             Show this help message
@@ -168,12 +192,13 @@ function showShowTagPrefixesHelp() {
 Usage: release-kit show-tag-prefixes [options]
 
 Print a per-workspace table of derived tag prefixes, tag counts, and declared
-legacy tag prefixes. Surfaces any release-shaped tags whose prefix is neither a
+legacy tag prefixes. Reports any release-shaped tags whose prefix is neither a
 derived prefix nor declared in \`legacyIdentities\`, with a copy-pasteable
 config snippet.
 
 Options:
-  --config <path>  Path to config file (default: .config/release-kit.config.ts)
+  --config <path>  Config file, relative to the current directory
+                   (default: .config/release-kit.config.ts at the repo root)
   --help, -h       Show this help message
 `);
 }
@@ -195,15 +220,17 @@ function showOverridesValidateHelp() {
 Usage: release-kit overrides validate
 
 Validate every \`.meta/changelog-overrides.json\` file across the project and per-workspace
-scopes. Reports schema/parse errors, ambiguous-prefix errors, and stale-key warnings.
+scopes. Reports schema/parse errors, ambiguous-prefix errors, conflicting-key errors, and
+stale-key warnings.
 
 Exit codes:
-  0    Clean — no errors, no stale keys
+  0    Clean: no errors, no stale keys
   1    Stale-key warnings only (no errors)
-  2    Schema/parse or ambiguous-prefix errors (errors dominate)
+  2    Schema/parse, ambiguous-prefix, or conflicting-key errors (errors take precedence)
 
 Options:
-  --config <path>  Path to config file (default: .config/release-kit.config.ts)
+  --config <path>  Config file, relative to the current directory
+                   (default: .config/release-kit.config.ts at the repo root)
   --help, -h       Show this help message
 `);
 }
@@ -211,13 +238,14 @@ function showPublishHelp() {
     console.info(`
 Usage: release-kit publish [options]
 
-Publish packages that have release tags on HEAD. Operates only on workspaces where
+Publish packages that have release tags on HEAD. Operates only on workspaces whose
 package.json#private is absent or false. Without --tags, unpublishable workspaces are
 silently filtered out. With --tags, an unpublishable tag is skipped with a warning while
-any publishable tags still publish.
+any publishable tags are still published.
 
 Options:
-  --config <path>        Path to config file (default: .config/release-kit.config.ts)
+  --config <path>        Config file, relative to the current directory
+                         (default: .config/release-kit.config.ts at the repo root)
   --dry-run              Preview without publishing
   --no-git-checks        Skip the clean-working-tree check
   --tags=tag1,tag2       Only publish the named tags (comma-separated, full tag names)
@@ -225,6 +253,15 @@ Options:
   --help, -h             Show this help message
 `);
 }
+function enterRepoRootOrExit() {
+    try {
+        return enterRepoRoot();
+    }
+    catch (error) {
+        reportError(describeError(error));
+        process.exit(1);
+    }
+}
 const args = process.argv.slice(2);
 const command = args[0];
 if (command === '--version' || command === '-V') {
@@ -246,7 +283,8 @@ if (command === 'prepare') {
         showPrepareHelp();
         process.exit(0);
     }
-    await prepareCommand(flags, styles);
+    const { invocationDir } = enterRepoRootOrExit();
+    await prepareCommand(flags, styles, invocationDir);
     process.exit(0);
 }
 if (command === 'commit') {
@@ -254,6 +292,7 @@ if (command === 'commit') {
         showCommitHelp();
         process.exit(0);
     }
+    enterRepoRootOrExit();
     try {
         commitCommand(flags);
     }
@@ -268,6 +307,7 @@ if (command === 'tag') {
         showTagHelp();
         process.exit(0);
     }
+    enterRepoRootOrExit();
     tagCommand(flags, styles);
     process.exit(0);
 }
@@ -276,7 +316,8 @@ if (command === 'push') {
         showPushHelp();
         process.exit(0);
     }
-    pushCommand(flags);
+    const { invocationDir } = enterRepoRootOrExit();
+    await pushCommand(flags, styles, invocationDir);
     process.exit(0);
 }
 if (command === 'create-github-release') {
@@ -284,7 +325,8 @@ if (command === 'create-github-release') {
         showCreateGithubReleaseHelp();
         process.exit(0);
     }
-    await createGithubReleaseCommand(flags, styles);
+    const { invocationDir } = enterRepoRootOrExit();
+    await createGithubReleaseCommand(flags, styles, invocationDir);
     process.exit(0);
 }
 if (command === 'publish') {
@@ -292,7 +334,8 @@ if (command === 'publish') {
         showPublishHelp();
         process.exit(0);
     }
-    await publishCommand(flags, styles);
+    const { invocationDir } = enterRepoRootOrExit();
+    await publishCommand(flags, styles, invocationDir);
     process.exit(0);
 }
 if (command === 'show-tag-prefixes') {
@@ -300,8 +343,9 @@ if (command === 'show-tag-prefixes') {
         showShowTagPrefixesHelp();
         process.exit(0);
     }
+    const { invocationDir } = enterRepoRootOrExit();
     const { config } = parseArgsOrExit(flags, configFlagSchema).flags;
-    const exitCode = await showTagPrefixesCommand(styles, config);
+    const exitCode = await showTagPrefixesCommand(styles, resolveConfigFlag(config, invocationDir));
     process.exit(exitCode);
 }
 if (command === 'init') {
@@ -309,6 +353,7 @@ if (command === 'init') {
         showInitHelp();
         process.exit(0);
     }
+    enterRepoRootOrExit();
     const initFlagSchema = {
         dryRun: { long: '--dry-run', type: 'boolean' },
         force: { long: '--force', type: 'boolean' },
@@ -318,6 +363,19 @@ if (command === 'init') {
     const exitCode = initCommand({ dryRun, force, styles, withConfig });
     process.exit(exitCode);
 }
+if (command === 'update-templates') {
+    if (flags.some((f) => f === '--help' || f === '-h')) {
+        showUpdateTemplatesHelp();
+        process.exit(0);
+    }
+    enterRepoRootOrExit();
+    const updateTemplatesFlagSchema = {
+        dryRun: { long: '--dry-run', type: 'boolean' },
+    };
+    const { dryRun } = parseArgsOrExit(flags, updateTemplatesFlagSchema).flags;
+    const exitCode = updateTemplatesCommand({ dryRun, styles });
+    process.exit(exitCode);
+}
 if (command === 'sync-labels') {
     const subcommand = flags[0];
     if (subcommand === undefined || ['--help', '-h'].includes(subcommand)) {
@@ -330,14 +388,16 @@ if (command === 'sync-labels') {
             showSyncLabelsInitHelp();
             process.exit(0);
         }
+        const { invocationDir } = enterRepoRootOrExit();
         const syncLabelsInitFlagSchema = {
             ...configFlagSchema,
             dryRun: { long: '--dry-run', type: 'boolean' },
             force: { long: '--force', type: 'boolean' },
         };
         const { config, dryRun, force } = parseArgsOrExit(subflags, syncLabelsInitFlagSchema).flags;
+        const configPath = resolveConfigFlag(config, invocationDir);
         const exitCode = await syncLabelsInitCommand({
-            ...(config !== undefined && { configPath: config }),
+            ...(configPath !== undefined && { configPath }),
             dryRun,
             force,
             styles,
@@ -349,12 +409,14 @@ if (command === 'sync-labels') {
             showSyncLabelsGenerateHelp();
             process.exit(0);
         }
+        const { invocationDir } = enterRepoRootOrExit();
         const generateFlagSchema = {
             ...configFlagSchema,
             check: { long: '--check', type: 'boolean' },
         };
         const { check, config } = parseArgsOrExit(subflags, generateFlagSchema).flags;
-        const exitCode = await generateCommand({ check, ...(config !== undefined && { configPath: config }), styles });
+        const configPath = resolveConfigFlag(config, invocationDir);
+        const exitCode = await generateCommand({ check, ...(configPath !== undefined && { configPath }), styles });
         process.exit(exitCode);
     }
     if (subcommand === 'sync') {
@@ -366,6 +428,7 @@ if (command === 'sync-labels') {
             reportError(`Unknown option: ${subflags[0]}`);
             process.exit(1);
         }
+        enterRepoRootOrExit();
         const exitCode = syncLabelsCommand();
         process.exit(exitCode);
     }
@@ -385,8 +448,9 @@ if (command === 'overrides') {
             showOverridesValidateHelp();
             process.exit(0);
         }
+        const { invocationDir } = enterRepoRootOrExit();
         const { config } = parseArgsOrExit(subflags, configFlagSchema).flags;
-        const result = await validateOverridesCommand(styles, config);
+        const result = await validateOverridesCommand(styles, resolveConfigFlag(config, invocationDir));
         if (result.exitCode === 0) {
             console.info(result.message);
         }

package/dist/esm/buildChangelogEntries.d.ts

@@ -1,26 +1,78 @@
+import { type RawCommit } from './enumerateReleaseWindows.js';
 import type { GenerateChangelogOptions } from './generateChangelogs.js';
-import type { ChangelogEntry, ReleaseConfig } from './types.js';
+import type { ChangelogEntry, ChangelogSection, MalformedChangeRecordBlock, PolicyViolation, ReleaseConfig, ReleaseType, UndeclaredEntryType, UnroutedEntryScope } from './types.js';
 /**
- * Strip cliff-template decorations from a group string, returning the bare section name.
+ * Strips a section title down to its bare name.
  *
- * The bundled `cliff.toml.template` encodes canonical row order as a hidden HTML comment
- * (e.g. `"<!-- 04 -->🐛 Bug fixes"`) so tera's `group_by` filter sorts groups predictably.
- * The body template's `striptags` filter erases the comment from the rendered heading,
- * but downstream consumers that read the raw `group` value (changelog.json titles, the
- * dev-vs-public classifier, the drift test) see the prefix and must strip it. The trailing
- * `stripEmojiPrefix` keeps the helper backward-compatible with consumer overrides written
- * as bare names.
+ * A default title has a leading emoji (e.g. `"🐛 Bug fixes"`), while a consumer's
+ * `devOnlySections` or `workTypes` override may be written as a bare name. Comparing both sides
+ * through this helper lets the two forms match.
  */
 export declare function stripGroupDecorations(group: string): string;
 /**
- * Build structured changelog entries from git history using git-cliff `--context`.
+ * Builds structured changelog entries from the release windows of git history, naming the unreleased window `tag`.
  *
- * Pure data: invokes git-cliff, parses its `--context` output, and returns the transformed
- * `ChangelogEntry[]`. Performs no `changelog.json` I/O — callers persist the entries via
- * `renderChangelogJson`.
+ * Composes `readReleaseHistory` and `toChangelogEntries` for a caller that knows the tag before it reads.
+ */
+export declare function buildChangelogEntries(config: ReleaseHistoryConfig, tag: string, options: GenerateChangelogOptions): {
+    entries: ChangelogEntry[];
+    diagnostics: ChangelogDiagnostics;
+};
+/** What reading the unreleased window reports beyond its items. */
+export interface ChangelogDiagnostics {
+    malformedBlocks: MalformedChangeRecordBlock[];
+    /** Breaking-policy violations of the window's titles and change-record entries. */
+    policyViolations: PolicyViolation[];
+    undeclaredEntryTypes: UndeclaredEntryType[];
+    /**
+     * Entry scopes that don't route to any workspace. A read leaves it empty: Only a pass over every workspace can fill
+     * it.
+     */
+    unroutedEntryScopes: UnroutedEntryScope[];
+}
+/**
+ * Reads a scope's release windows once and returns the changelog items of every window, with what the unreleased
+ * window decides: its commits, its bump, and its diagnostics.
  *
- * Always invokes git-cliff: dry-run is the caller's concern (it governs whether the file write happens,
- * not whether git-cliff runs). This means dry-run exercises the full git-cliff toolchain and surfaces missing-binary,
- * malformed-config, and template-resolution failures earlier than before.
+ * A commit whose last `change-record` block records entries yields one item per entry routed to
+ * `options.workspaceDir`; any other commit is classified by its title through `classifyChangelogCommit`. A `release:`
+ * or merge subject yields nothing either way. The read records diagnostics only for the unreleased window, since the
+ * released windows were reported when they were prepared.
+ */
+export declare function readReleaseHistory(config: ReleaseHistoryConfig, options: GenerateChangelogOptions): ReleaseHistory;
+/** The configuration that `readReleaseHistory` reads. */
+export type ReleaseHistoryConfig = Pick<ReleaseConfig, 'breakingPolicies' | 'changelogJson' | 'scopeAliases' | 'versionPatterns' | 'workTypes'>;
+/** One read of a scope's release windows. */
+export interface ReleaseHistory {
+    /** The newest matching tag that HEAD reaches; undefined when none does. */
+    previousTag: string | undefined;
+    /** Entries of the released windows, newest first; a window that doesn't yield any item contributes none. */
+    releasedEntries: ChangelogEntry[];
+    unreleased: UnreleasedWindowReading;
+}
+/** The unreleased window: its changelog sections and commits, and the bump and diagnostics that they determine. */
+export interface UnreleasedWindowReading {
+    /** The highest bump that the window's items call for; undefined when the window doesn't yield any item. */
+    bump: ReleaseType | undefined;
+    /** The window's commits, newest first, without release commits. */
+    commits: RawCommit[];
+    /** The date of the window's entry, from the time of the read. */
+    date: string;
+    diagnostics: ChangelogDiagnostics;
+    /** The number of commits that yield at least one item. */
+    parsedCommitCount: number;
+    sections: ChangelogSection[];
+    /**
+     * Commits that don't yield any item and that neither an exclusion nor a diagnostic accounts for, newest first;
+     * undefined when none.
+     */
+    unparseableCommits: RawCommit[] | undefined;
+}
+/** Labels the unreleased window of `history` with `tag` and returns the entries of every window, newest first. */
+export declare function toChangelogEntries(history: ReleaseHistory, tag: string): ChangelogEntry[];
+/**
+ * Returns the entries that a direct release tagged `tag` records: those of `toChangelogEntries`, or, when the
+ * unreleased window doesn't yield any item, the synthetic "Forced version bump." entry dated `today` ahead of the
+ * released entries.
  */
-export declare function buildChangelogEntries(config: Pick<ReleaseConfig, 'breakingPolicies' | 'changelogJson' | 'cliffConfigPath' | 'workTypes'>, tag: string, options?: GenerateChangelogOptions): ChangelogEntry[];
+export declare function toReleaseEntries(history: ReleaseHistory, tag: string, today: string): ChangelogEntry[];