@williamthorsen/release-kit 5.2.1 → 5.3.0

package/cliff.toml.template

@@ -18,45 +18,10 @@
 # unique group (not per parser entry) — all parsers routing to the same group
 # share the same prefix.
 
-[changelog]
-header = """
-# Changelog
-
-All notable changes to this project will be documented in this file."""
-# Render each commit as a bullet with the description (stripped of ticket ID
-# and scope|type prefix). If the commit has a body, render it as indented
-# continuation paragraphs under the bullet.
-body = """{%- if version %}
-## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
-{%- else %}
-## [unreleased]
-{%- endif -%}
-{%- set non_merge = commits | filter(attribute="merge_commit", value=false) -%}
-{%- for group, group_commits in non_merge | group_by(attribute="group") %}
-
-### {{ group | striptags | trim | upper_first }}
-
-{% for commit in group_commits -%}
-{%- set subject = commit.message | split(pat="\n") | first -%}
-{%- set desc = subject | split(pat=": ") | slice(start=1) | join(sep=": ") -%}
-{%- set body_lines = commit.message | split(pat="\n") | slice(start=2) -%}
-{%- set body_text = body_lines | join(sep="\n") | trim -%}
-{%- if not loop.first %}
-
-{% endif -%}
-- {{ desc | upper_first }}
-{%- if body_text %}
-
-  {{ body_text | split(pat="\n") | join(sep="\n  ") }}
-{%- endif -%}
-{%- endfor -%}
-{%- endfor %}
-"""
-footer = """
-
-<!-- generated by git-cliff -->
-"""
-trim = false
+# Markdown rendering is handled in-process by `renderChangelogMarkdown.ts`. cliff is invoked
+# only for `--context` JSON output (see `buildChangelogEntries.ts`), so no `[changelog]` block
+# is needed. The `[git].commit_parsers` section below remains load-bearing for group
+# assignment in the `--context` payload.
 
 [git]
 conventional_commits = false

package/dist/esm/.cache

@@ -1 +1 @@
-704a70608ce284c9f8ef2dda2e6604a5f38ac0c995c9419ae39206ed053775c6
+18bd566d86a692ebdc23649a475e7d5e01562a58df99b6091e222e890cef8f80

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

@@ -13,6 +13,7 @@ import { syncLabelsInitCommand } from "../sync-labels/initCommand.js";
 import { syncLabelsCommand } from "../sync-labels/syncCommand.js";
 import { syncWorkTypes } from "../syncWorkTypes.js";
 import { tagCommand } from "../tagCommand.js";
+import { validateOverridesCommand } from "../validateOverridesCommand.js";
 const VERSION = readPackageVersion(import.meta.url);
 function showUsage() {
   console.info(`
@@ -27,6 +28,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
+  overrides        Manage editorial changelog overrides
   sync-labels      Manage GitHub label synchronization
   work-types       Check for or sync work-type taxonomy drift against the upstream canonical
 
@@ -174,6 +176,35 @@ legacy tag prefixes. Surfaces any release-shaped tags whose prefix is neither a
 derived prefix nor declared in \`legacyIdentities\`, with a copy-pasteable
 config snippet.
 
+Options:
+  --help, -h    Show this help message
+`);
+}
+function showOverridesHelp() {
+  console.info(`
+Usage: release-kit overrides <subcommand> [options]
+
+Manage editorial changelog overrides.
+
+Subcommands:
+  validate      Validate every \`.meta/changelog-overrides.json\` file across all scopes
+
+Options:
+  --help, -h    Show this help message
+`);
+}
+function showOverridesValidateHelp() {
+  console.info(`
+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.
+
+Exit codes:
+  0    Clean \u2014 no errors, no stale keys
+  1    Stale-key warnings only (no errors)
+  2    Schema/parse or ambiguous-prefix errors (errors dominate)
+
 Options:
   --help, -h    Show this help message
 `);
@@ -389,6 +420,34 @@ if (command === "sync-labels") {
   showSyncLabelsHelp();
   process.exit(1);
 }
+if (command === "overrides") {
+  const subcommand = flags[0];
+  const subflags = flags.slice(1);
+  if (subcommand === "--help" || subcommand === "-h" || subcommand === void 0) {
+    showOverridesHelp();
+    process.exit(0);
+  }
+  if (subcommand === "validate") {
+    if (subflags.some((f) => f === "--help" || f === "-h")) {
+      showOverridesValidateHelp();
+      process.exit(0);
+    }
+    if (subflags.length > 0) {
+      console.error(`Error: Unknown option: ${subflags[0]}`);
+      process.exit(1);
+    }
+    const result = await validateOverridesCommand();
+    if (result.exitCode === 0) {
+      console.info(result.message);
+    } else {
+      console.error(result.message);
+    }
+    process.exit(result.exitCode);
+  }
+  console.error(`Error: Unknown subcommand: ${subcommand}`);
+  showOverridesHelp();
+  process.exit(1);
+}
 if (command === "work-types") {
   const subcommand = flags[0];
   const subflags = flags.slice(1);

package/dist/esm/buildChangelogEntries.js

@@ -69,6 +69,9 @@ function toCliffContextCommit(value) {
   if (typeof value.group === "string") {
     commit.group = value.group;
   }
+  if (typeof value.id === "string") {
+    commit.id = value.id;
+  }
   return commit;
 }
 function transformReleases(releases, devOnlySections) {
@@ -98,6 +101,9 @@ function transformReleases(releases, devOnlySections) {
       if (breaking) {
         item.breaking = true;
       }
+      if (commit.id !== void 0 && commit.id !== "") {
+        item.hash = commit.id;
+      }
       items.push(item);
     }
     const sections = [];

package/dist/esm/buildEmptyReleaseEntry.d.ts

@@ -0,0 +1,2 @@
+import type { ChangelogEntry } from './types.ts';
+export declare function buildEmptyReleaseEntry(version: string, date: string): ChangelogEntry;

package/dist/esm/buildEmptyReleaseEntry.js

@@ -0,0 +1,16 @@
+function buildEmptyReleaseEntry(version, date) {
+  return {
+    version,
+    date,
+    sections: [
+      {
+        title: "Notes",
+        audience: "dev",
+        items: [{ description: "Forced version bump." }]
+      }
+    ]
+  };
+}
+export {
+  buildEmptyReleaseEntry
+};

package/dist/esm/changelogJsonFile.d.ts

@@ -2,3 +2,5 @@ import type { ChangelogEntry, ReleaseConfig } from './types.ts';
 export declare function resolveChangelogJsonPath(config: Pick<ReleaseConfig, 'changelogJson'>, changelogPath: string): string;
 export declare function writeChangelogJson(filePath: string, entries: ChangelogEntry[]): string;
 export declare function upsertChangelogJson(filePath: string, entries: ChangelogEntry[]): string;
+export declare function upsertChangelogJsonAndReturn(filePath: string, entries: ChangelogEntry[]): ChangelogEntry[];
+export declare function mergeChangelogEntriesWithDisk(filePath: string, entries: ChangelogEntry[]): ChangelogEntry[];

package/dist/esm/changelogJsonFile.js

@@ -14,11 +14,19 @@ function writeChangelogJson(filePath, entries) {
   return filePath;
 }
 function upsertChangelogJson(filePath, entries) {
+  upsertChangelogJsonAndReturn(filePath, entries);
+  return filePath;
+}
+function upsertChangelogJsonAndReturn(filePath, entries) {
   const existing = readExistingEntries(filePath);
   const merged = mergeEntries(entries, existing);
   mkdirSync(dirname(filePath), { recursive: true });
   writeFileSync(filePath, stringify(merged, { maxLength: 100 }) + "\n", "utf8");
-  return filePath;
+  return merged;
+}
+function mergeChangelogEntriesWithDisk(filePath, entries) {
+  const existing = readExistingEntries(filePath);
+  return mergeEntries(entries, existing);
 }
 function sortNewestFirst(entries) {
   return [...entries].sort((a, b) => compareVersionsDescending(a.version, b.version));
@@ -62,7 +70,9 @@ function compareVersionsDescending(a, b) {
   return 0;
 }
 export {
+  mergeChangelogEntriesWithDisk,
   resolveChangelogJsonPath,
   upsertChangelogJson,
+  upsertChangelogJsonAndReturn,
   writeChangelogJson
 };

package/dist/esm/changelogJsonUtils.d.ts

@@ -1,4 +1,5 @@
-import type { ChangelogEntry } from './types.ts';
+import type { ChangelogEntry, ChangelogItem } from './types.ts';
+export declare function isChangelogItem(value: unknown): value is ChangelogItem;
 export declare function isChangelogEntry(value: unknown): value is ChangelogEntry;
 export declare function extractVersion(tag: string): string;
 export declare function readChangelogEntries(filePath: string): ChangelogEntry[] | undefined;

package/dist/esm/changelogJsonUtils.js

@@ -1,5 +1,13 @@
 import { existsSync, readFileSync } from "node:fs";
 import { isRecord, isUnknownArray } from "./typeGuards.js";
+function isChangelogItem(value) {
+  if (!isRecord(value)) return false;
+  if (typeof value.description !== "string") return false;
+  if (value.body !== void 0 && typeof value.body !== "string") return false;
+  if (value.breaking !== void 0 && typeof value.breaking !== "boolean") return false;
+  if (value.hash !== void 0 && typeof value.hash !== "string") return false;
+  return true;
+}
 function isChangelogEntry(value) {
   return isRecord(value) && typeof value.version === "string" && typeof value.date === "string" && isUnknownArray(value.sections);
 }
@@ -25,5 +33,6 @@ function readChangelogEntries(filePath) {
 export {
   extractVersion,
   isChangelogEntry,
+  isChangelogItem,
   readChangelogEntries
 };

package/dist/esm/changelogOverrides.d.ts

@@ -0,0 +1,53 @@
+import type { ChangelogEntry, ChangelogOverride, WorkspaceConfig } from './types.ts';
+export type LoadChangelogOverridesResult = {
+    overrides: Map<string, ChangelogOverride>;
+} | {
+    errors: string[];
+};
+export declare function loadChangelogOverrides(path: string): LoadChangelogOverridesResult;
+export declare function validateChangelogOverrides(raw: unknown): {
+    overrides: Map<string, ChangelogOverride>;
+    errors: string[];
+};
+export declare function formatStaleOverrideKeyWarning(key: string): string;
+export declare function applyChangelogOverrides(entries: ChangelogEntry[], overrides: Map<string, ChangelogOverride>): {
+    entries: ChangelogEntry[];
+    warnings: string[];
+    errors: string[];
+    matchedKeys: string[];
+};
+export declare function resolveOverridePath(scopeRoot: string): string;
+export interface LoadOverridesForScopesResult {
+    project: Map<string, ChangelogOverride>;
+    perWorkspace: Map<string, Map<string, ChangelogOverride>>;
+    errors: string[];
+}
+export declare function loadOverridesForScopes(scopes: {
+    project?: string;
+    workspaces?: string[];
+}): LoadOverridesForScopesResult;
+export declare function composeOverrides(rootEntries: Map<string, ChangelogOverride>, workspaceEntries: Map<string, ChangelogOverride> | undefined): Map<string, ChangelogOverride>;
+export interface OverrideContext {
+    project: Map<string, ChangelogOverride>;
+    perWorkspace: Map<string, Map<string, ChangelogOverride>>;
+    overrideWarnings: string[];
+    globalMatchedRootKeys: Set<string>;
+}
+export declare function createOverrideContext(workspaces: WorkspaceConfig[]): OverrideContext;
+export interface ChangelogOverrideScope {
+    filePath: string;
+    hashes: readonly string[];
+}
+export interface ValidateAllChangelogOverridesInputs {
+    project?: {
+        filePath: string;
+        hashes?: readonly string[];
+    };
+    workspaces?: readonly ChangelogOverrideScope[];
+}
+export interface ValidateAllChangelogOverridesResult {
+    errors: string[];
+    warnings: string[];
+}
+export declare function validateAllChangelogOverrides(inputs: ValidateAllChangelogOverridesInputs): ValidateAllChangelogOverridesResult;
+export declare function applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;