@williamthorsen/release-kit 5.2.1 → 5.3.1

package/dist/esm/changelogOverrides.js

@@ -0,0 +1,424 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { isRecord } from "./typeGuards.js";
+const OVERRIDES_FILENAME = ".meta/changelog-overrides.json";
+const VALID_AUDIENCE_VALUES = /* @__PURE__ */ new Set(["all", "dev", "skip"]);
+const V1_SUPPORTED_AUDIENCE_VALUES = /* @__PURE__ */ new Set(["skip"]);
+const KNOWN_OVERRIDE_FIELDS = /* @__PURE__ */ new Set(["audience", "description", "body", "breaking"]);
+function loadChangelogOverrides(path2) {
+  if (!existsSync(path2)) {
+    return { overrides: /* @__PURE__ */ new Map() };
+  }
+  let content;
+  try {
+    content = readFileSync(path2, "utf8");
+  } catch (error) {
+    return {
+      errors: [`Failed to read override file ${path2}: ${error instanceof Error ? error.message : String(error)}`]
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    return {
+      errors: [`Failed to parse override file ${path2}: ${error instanceof Error ? error.message : String(error)}`]
+    };
+  }
+  const result = validateChangelogOverrides(parsed);
+  if (result.errors.length > 0) {
+    return { errors: result.errors };
+  }
+  return { overrides: result.overrides };
+}
+function validateChangelogOverrides(raw) {
+  const overrides = /* @__PURE__ */ new Map();
+  const errors = [];
+  if (!isRecord(raw)) {
+    errors.push("Override file: top-level value must be an object keyed by commit hash");
+    return { overrides, errors };
+  }
+  for (const [key, rawEntry] of Object.entries(raw)) {
+    if (key === "") {
+      errors.push("Override file: empty-string key is not a valid commit hash");
+      continue;
+    }
+    const validated = validateSingleOverride(key, rawEntry, errors);
+    if (validated !== void 0) {
+      overrides.set(key, validated);
+    }
+  }
+  return { overrides, errors };
+}
+function validateSingleOverride(key, rawEntry, errors) {
+  if (!isRecord(rawEntry)) {
+    errors.push(`overrides['${key}']: must be an object`);
+    return void 0;
+  }
+  let entryValid = true;
+  for (const fieldName of Object.keys(rawEntry)) {
+    if (!KNOWN_OVERRIDE_FIELDS.has(fieldName)) {
+      errors.push(`overrides['${key}']: unknown field '${fieldName}'`);
+      entryValid = false;
+    }
+  }
+  const result = {};
+  if (rawEntry.audience !== void 0) {
+    const audienceResult = validateAudience(key, rawEntry.audience, errors);
+    if (audienceResult === void 0) {
+      entryValid = false;
+    } else {
+      result.audience = audienceResult;
+    }
+  }
+  if (rawEntry.description !== void 0) {
+    if (typeof rawEntry.description !== "string") {
+      errors.push(`overrides['${key}']: 'description' must be a string`);
+      entryValid = false;
+    } else {
+      result.description = rawEntry.description;
+    }
+  }
+  if (rawEntry.body !== void 0) {
+    if (typeof rawEntry.body !== "string") {
+      errors.push(`overrides['${key}']: 'body' must be a string`);
+      entryValid = false;
+    } else {
+      result.body = rawEntry.body;
+    }
+  }
+  if (rawEntry.breaking !== void 0) {
+    if (typeof rawEntry.breaking !== "boolean") {
+      errors.push(`overrides['${key}']: 'breaking' must be a boolean`);
+      entryValid = false;
+    } else {
+      result.breaking = rawEntry.breaking;
+    }
+  }
+  if (Object.keys(result).length === 0 && entryValid) {
+    errors.push(`overrides['${key}']: at least one override field must be set`);
+    return void 0;
+  }
+  if (!entryValid) {
+    return void 0;
+  }
+  return result;
+}
+function validateAudience(key, value, errors) {
+  if (typeof value !== "string" || !VALID_AUDIENCE_VALUES.has(value)) {
+    errors.push(`overrides['${key}']: 'audience' must be one of 'all' | 'dev' | 'skip'`);
+    return void 0;
+  }
+  if (!V1_SUPPORTED_AUDIENCE_VALUES.has(value)) {
+    errors.push(`overrides['${key}']: audience '${value}' is not yet supported; only 'skip' is currently accepted`);
+    return void 0;
+  }
+  return "skip";
+}
+function formatStaleOverrideKeyWarning(key) {
+  return `Override key '${key}' did not match any commit hash in the changelog (likely a stale reference)`;
+}
+function applyChangelogOverrides(entries, overrides) {
+  const warnings = [];
+  const errors = [];
+  const matchedKeys = [];
+  if (overrides.size === 0) {
+    return { entries: entries.map(cloneEntry), warnings, errors, matchedKeys };
+  }
+  const allHashes = [];
+  for (const entry of entries) {
+    for (const section of entry.sections) {
+      for (const item of section.items) {
+        if (item.hash !== void 0) {
+          allHashes.push(item.hash);
+        }
+      }
+    }
+  }
+  const keyToMatchedHashes = /* @__PURE__ */ new Map();
+  for (const overrideKey of overrides.keys()) {
+    const matches = allHashes.filter((hash) => hash.startsWith(overrideKey));
+    if (matches.length === 0) {
+      continue;
+    }
+    if (matches.length > 1) {
+      errors.push(
+        `Override key '${overrideKey}' is ambiguous: matches multiple commits (${matches.join(", ")}). Use a longer prefix or the full commit hash.`
+      );
+      continue;
+    }
+    keyToMatchedHashes.set(overrideKey, matches);
+    matchedKeys.push(overrideKey);
+  }
+  const hashToOverride = /* @__PURE__ */ new Map();
+  for (const [overrideKey, matchedHashes] of keyToMatchedHashes) {
+    const override = overrides.get(overrideKey);
+    if (override === void 0) continue;
+    for (const hash of matchedHashes) {
+      hashToOverride.set(hash, override);
+    }
+  }
+  const transformedEntries = [];
+  for (const entry of entries) {
+    const transformedSections = [];
+    for (const section of entry.sections) {
+      const transformedItems = applyOverridesToItems(section.items, hashToOverride);
+      if (transformedItems.length === 0) {
+        continue;
+      }
+      transformedSections.push({ ...section, items: transformedItems });
+    }
+    transformedEntries.push({ ...entry, sections: transformedSections });
+  }
+  return { entries: transformedEntries, warnings, errors, matchedKeys };
+}
+function applyOverridesToItems(items, hashToOverride) {
+  const result = [];
+  for (const item of items) {
+    if (item.hash === void 0) {
+      result.push(cloneItem(item));
+      continue;
+    }
+    const override = hashToOverride.get(item.hash);
+    if (override === void 0) {
+      result.push(cloneItem(item));
+      continue;
+    }
+    if (override.audience === "skip") {
+      continue;
+    }
+    result.push(applyOverrideToItem(item, override));
+  }
+  return result;
+}
+function applyOverrideToItem(item, override) {
+  const result = { ...item };
+  if (override.description !== void 0) {
+    result.description = override.description;
+  }
+  if (override.body !== void 0) {
+    result.body = override.body;
+  }
+  if (override.breaking !== void 0) {
+    result.breaking = override.breaking;
+  }
+  return result;
+}
+function cloneItem(item) {
+  return { ...item };
+}
+function cloneEntry(entry) {
+  return {
+    ...entry,
+    sections: entry.sections.map((section) => ({ ...section, items: section.items.map(cloneItem) }))
+  };
+}
+function resolveOverridePath(scopeRoot) {
+  return path.posix.join(scopeRoot, OVERRIDES_FILENAME);
+}
+function loadOverridesForScopes(scopes) {
+  const errors = [];
+  let project = /* @__PURE__ */ new Map();
+  const perWorkspace = /* @__PURE__ */ new Map();
+  if (scopes.project !== void 0) {
+    const result = loadChangelogOverrides(resolveOverridePath(scopes.project));
+    if ("errors" in result) {
+      errors.push(...result.errors);
+    } else {
+      project = result.overrides;
+    }
+  }
+  for (const workspacePath of scopes.workspaces ?? []) {
+    const result = loadChangelogOverrides(resolveOverridePath(workspacePath));
+    if ("errors" in result) {
+      errors.push(...result.errors);
+    } else if (result.overrides.size > 0) {
+      perWorkspace.set(workspacePath, result.overrides);
+    }
+  }
+  return { project, perWorkspace, errors };
+}
+function composeOverrides(rootEntries, workspaceEntries) {
+  const composed = new Map(rootEntries);
+  if (workspaceEntries !== void 0) {
+    for (const [key, value] of workspaceEntries) {
+      composed.set(key, value);
+    }
+  }
+  return composed;
+}
+function createOverrideContext(workspaces) {
+  const result = loadOverridesForScopes({
+    project: ".",
+    workspaces: workspaces.map((workspace) => workspace.workspacePath)
+  });
+  if (result.errors.length > 0) {
+    throw new Error(`Failed to load changelog overrides:
+  - ${result.errors.join("\n  - ")}`);
+  }
+  return {
+    project: result.project,
+    perWorkspace: result.perWorkspace,
+    overrideWarnings: [],
+    globalMatchedRootKeys: /* @__PURE__ */ new Set()
+  };
+}
+function validateAllChangelogOverrides(inputs) {
+  const errors = [];
+  const warnings = [];
+  const projectFilePath = inputs.project?.filePath;
+  const projectMap = loadScopeMap(projectFilePath, errors);
+  const workspaceMaps = (inputs.workspaces ?? []).map((scope) => ({
+    filePath: scope.filePath,
+    hashes: scope.hashes,
+    map: loadScopeMap(scope.filePath, errors)
+  }));
+  const globalMatchedRootKeys = /* @__PURE__ */ new Set();
+  for (const workspace of workspaceMaps) {
+    processWorkspaceScope({
+      workspace,
+      projectFilePath,
+      projectMap,
+      errors,
+      warnings,
+      globalMatchedRootKeys
+    });
+  }
+  const projectHashes = inputs.project?.hashes;
+  if (projectFilePath !== void 0 && projectHashes !== void 0) {
+    processProjectScope({ projectFilePath, projectMap, projectHashes, errors, globalMatchedRootKeys });
+  }
+  if (projectFilePath !== void 0) {
+    collectRootStaleWarnings(projectFilePath, projectMap, globalMatchedRootKeys, warnings);
+  }
+  return { errors, warnings };
+}
+function processWorkspaceScope(args) {
+  const { workspace, projectFilePath, projectMap, errors, warnings, globalMatchedRootKeys } = args;
+  const { filePath, hashes, map } = workspace;
+  const workspaceApplied = applyChangelogOverrides(makeValidationEntries(hashes), map);
+  for (const message of workspaceApplied.errors) {
+    errors.push(prefixWithFilePath(filePath, message));
+  }
+  if (projectFilePath !== void 0 && projectMap.size > 0) {
+    const projectMinusShadowed = filterShadowedKeys(projectMap, map);
+    const projectApplied = applyChangelogOverrides(makeValidationEntries(hashes), projectMinusShadowed);
+    for (const message of projectApplied.errors) {
+      errors.push(prefixWithFilePath(projectFilePath, message));
+    }
+  }
+  for (const key of map.keys()) {
+    if (!hasAnyMatch(key, hashes)) {
+      warnings.push(formatWorkspaceStaleWarning(filePath, key));
+    }
+  }
+  for (const key of projectMap.keys()) {
+    if (map.has(key)) continue;
+    if (hasAnyMatch(key, hashes)) {
+      globalMatchedRootKeys.add(key);
+    }
+  }
+}
+function processProjectScope(args) {
+  const { projectFilePath, projectMap, projectHashes, errors, globalMatchedRootKeys } = args;
+  const applied = applyChangelogOverrides(makeValidationEntries(projectHashes), projectMap);
+  for (const message of applied.errors) {
+    errors.push(prefixWithFilePath(projectFilePath, message));
+  }
+  for (const key of projectMap.keys()) {
+    if (hasAnyMatch(key, projectHashes)) {
+      globalMatchedRootKeys.add(key);
+    }
+  }
+}
+function collectRootStaleWarnings(projectFilePath, projectMap, globalMatchedRootKeys, warnings) {
+  for (const key of projectMap.keys()) {
+    if (!globalMatchedRootKeys.has(key)) {
+      warnings.push(formatRootStaleWarning(projectFilePath, key));
+    }
+  }
+}
+function hasAnyMatch(key, hashes) {
+  return hashes.some((hash) => hash.startsWith(key));
+}
+function filterShadowedKeys(projectMap, workspaceMap) {
+  const result = /* @__PURE__ */ new Map();
+  for (const [key, value] of projectMap) {
+    if (workspaceMap.has(key)) continue;
+    result.set(key, value);
+  }
+  return result;
+}
+function loadScopeMap(filePath, errors) {
+  if (filePath === void 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  const result = loadChangelogOverrides(filePath);
+  if ("errors" in result) {
+    for (const message of result.errors) {
+      errors.push(prefixWithFilePath(filePath, message));
+    }
+    return /* @__PURE__ */ new Map();
+  }
+  return result.overrides;
+}
+function makeValidationEntries(hashes) {
+  return [
+    {
+      version: "0.0.0",
+      date: "0000-00-00",
+      sections: [
+        {
+          title: "Validation",
+          audience: "all",
+          items: hashes.map((hash) => ({ description: "", hash }))
+        }
+      ]
+    }
+  ];
+}
+function prefixWithFilePath(filePath, message) {
+  return `${filePath}: ${message}`;
+}
+function formatWorkspaceStaleWarning(filePath, key) {
+  return `${filePath}: Override key '${key}' did not match any commit in this workspace's history (likely a stale reference)`;
+}
+function formatRootStaleWarning(filePath, key) {
+  return `${filePath}: Override key '${key}' did not match any commit in any scope (likely a stale reference)`;
+}
+function applyWorkspaceOverrides(newEntries, workspacePath, overrideContext) {
+  const { project, perWorkspace, overrideWarnings, globalMatchedRootKeys } = overrideContext;
+  const workspaceOverrides = perWorkspace.get(workspacePath);
+  const composed = composeOverrides(project, workspaceOverrides);
+  const applied = applyChangelogOverrides(newEntries, composed);
+  if (applied.errors.length > 0) {
+    throw new Error(`Changelog override application failed:
+  - ${applied.errors.join("\n  - ")}`);
+  }
+  overrideWarnings.push(...applied.warnings);
+  const matchedSet = new Set(applied.matchedKeys);
+  if (workspaceOverrides !== void 0) {
+    for (const key of workspaceOverrides.keys()) {
+      if (!matchedSet.has(key)) {
+        overrideWarnings.push(formatStaleOverrideKeyWarning(key));
+      }
+    }
+  }
+  for (const key of applied.matchedKeys) {
+    if (workspaceOverrides?.has(key)) continue;
+    globalMatchedRootKeys.add(key);
+  }
+  return applied;
+}
+export {
+  applyChangelogOverrides,
+  applyWorkspaceOverrides,
+  composeOverrides,
+  createOverrideContext,
+  formatStaleOverrideKeyWarning,
+  loadChangelogOverrides,
+  loadOverridesForScopes,
+  resolveOverridePath,
+  validateAllChangelogOverrides,
+  validateChangelogOverrides
+};

package/dist/esm/checkWorkTypesDrift.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { errorMessage, hasExpectedTopLevelShape } from "./workTypesUtils.js";
+import { buildFetchInit, errorMessage, hasExpectedTopLevelShape } from "./workTypesUtils.js";
 const UPSTREAM_WORK_TYPES_URL = "https://raw.githubusercontent.com/williamthorsen/codeassembly/main/packages/agents/content/skills/_data/work-types.json";
 function resolveDefaultLocalPath() {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
@@ -21,9 +21,10 @@ async function checkWorkTypesDrift(dependencies = {}) {
       message: `Local work-types.json is not valid JSON: ${errorMessage(error)}`
     };
   }
+  const fetchInit = buildFetchInit();
   let response;
   try {
-    response = await fetcher(url);
+    response = fetchInit === void 0 ? await fetcher(url) : await fetcher(url, fetchInit);
   } catch (error) {
     return {
       exitCode: 2,

package/dist/esm/defaults.js

@@ -3,7 +3,7 @@ import { WORK_TYPES_DATA as WORK_TYPES_DATA2 } from "./workTypesData.js";
 function composeHeader(entry) {
   return `${entry.emoji} ${entry.label}`;
 }
-const DEV_ONLY_TIERS = /* @__PURE__ */ new Set(["Internal", "Process"]);
+const DEV_ONLY_TIERS = /* @__PURE__ */ new Set(["internal", "process"]);
 function deriveDefaultWorkTypes() {
   const result = {};
   for (const entry of WORK_TYPES_DATA.types) {

package/dist/esm/generateChangelogs.d.ts

@@ -1,8 +1,7 @@
-import type { ReleaseConfig } from './types.ts';
+import type { WorkspaceConfig } from './types.ts';
 export declare function buildTagPattern(tagPrefixes: readonly string[]): string;
+export declare function getAllTagPrefixes(workspace: WorkspaceConfig): string[];
 export interface GenerateChangelogOptions {
     tagPattern?: string;
     includePaths?: string[];
 }
-export declare function generateChangelog(config: Pick<ReleaseConfig, 'cliffConfigPath'>, changelogPath: string, tag: string, dryRun: boolean, options?: GenerateChangelogOptions): string[];
-export declare function generateChangelogs(config: ReleaseConfig, tag: string, dryRun: boolean): string[];

package/dist/esm/generateChangelogs.js

@@ -1,5 +1,3 @@
-import { resolveCliffConfigPath } from "./resolveCliffConfigPath.js";
-import { runGitCliff } from "./runGitCliff.js";
 function buildTagPattern(tagPrefixes) {
   if (tagPrefixes.length === 0) {
     throw new Error("buildTagPattern: tagPrefixes must contain at least one entry");
@@ -11,41 +9,13 @@ function buildTagPattern(tagPrefixes) {
   const escaped = tagPrefixes.map(escapeRegex);
   return `(${escaped.join("|")})[0-9].*`;
 }
+function getAllTagPrefixes(workspace) {
+  return [workspace.tagPrefix, ...workspace.legacyIdentities?.map((identity) => identity.tagPrefix) ?? []];
+}
 function escapeRegex(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
 }
-function generateChangelog(config, changelogPath, tag, dryRun, options) {
-  const outputFile = `${changelogPath}/CHANGELOG.md`;
-  if (dryRun) {
-    return [outputFile];
-  }
-  const resolvedConfigPath = resolveCliffConfigPath(config.cliffConfigPath, import.meta.url);
-  const cliffArgs = ["--output", outputFile, "--tag", tag];
-  if (options?.tagPattern !== void 0) {
-    cliffArgs.push("--tag-pattern", options.tagPattern);
-  }
-  for (const includePath of options?.includePaths ?? []) {
-    cliffArgs.push("--include-path", includePath);
-  }
-  try {
-    runGitCliff(resolvedConfigPath, cliffArgs, "inherit");
-  } catch (error) {
-    throw new Error(
-      `Failed to generate changelog for ${outputFile}: ${error instanceof Error ? error.message : String(error)}`
-    );
-  }
-  return [outputFile];
-}
-function generateChangelogs(config, tag, dryRun) {
-  const tagPattern = buildTagPattern([config.tagPrefix]);
-  const results = [];
-  for (const changelogPath of config.changelogPaths) {
-    results.push(...generateChangelog(config, changelogPath, tag, dryRun, { tagPattern }));
-  }
-  return results;
-}
 export {
   buildTagPattern,
-  generateChangelog,
-  generateChangelogs
+  getAllTagPrefixes
 };

package/dist/esm/index.d.ts

@@ -1,2 +1,4 @@
+export { type ChangelogOverrideScope, validateAllChangelogOverrides, type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult, } from './changelogOverrides.ts';
 export type { SyncLabelsConfig } from './sync-labels/types.ts';
 export type { ReleaseKitConfig } from './types.ts';
+export { formatValidateOverridesResult, type ValidateOverridesCommandResult } from './validateOverridesCommand.ts';

package/dist/esm/index.js

@@ -0,0 +1,8 @@
+import {
+  validateAllChangelogOverrides
+} from "./changelogOverrides.js";
+import { formatValidateOverridesResult } from "./validateOverridesCommand.js";
+export {
+  formatValidateOverridesResult,
+  validateAllChangelogOverrides
+};

package/dist/esm/loadConfig.d.ts

@@ -12,4 +12,4 @@ export interface RootPackageInfo {
 }
 export declare function mergeMonorepoConfig(discoveredPaths: string[], userConfig: ReleaseKitConfig | undefined, rootPackage?: RootPackageInfo): MonorepoReleaseConfig;
 export declare function mergeSinglePackageConfig(userConfig: ReleaseKitConfig | undefined): ReleaseConfig;
-export declare function resolveWorkTypes(userWorkTypes?: Record<string, WorkTypeConfig>): Record<string, WorkTypeConfig>;
+export declare function resolveWorkTypes(userWorkTypes?: ReleaseKitConfig['workTypes']): Record<string, WorkTypeConfig>;

package/dist/esm/releasePrepare.js

@@ -1,23 +1,40 @@
 import { execSync } from "node:child_process";
 import { buildChangelogEntries } from "./buildChangelogEntries.js";
+import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
 import { bumpAllVersions, setAllVersions } from "./bumpAllVersions.js";
-import { resolveChangelogJsonPath, upsertChangelogJson } from "./changelogJsonFile.js";
+import {
+  mergeChangelogEntriesWithDisk,
+  resolveChangelogJsonPath,
+  upsertChangelogJsonAndReturn
+} 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 { generateChangelogs } from "./generateChangelogs.js";
 import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
 import { hasPrettierConfig } from "./hasPrettierConfig.js";
 import { resolveWorkTypes } from "./loadConfig.js";
 import { readCurrentVersion } from "./readCurrentVersion.js";
+import { writeChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
+import { refreshGitCliffCache } from "./runGitCliff.js";
 import { writeReleaseNotesPreviews } from "./writeReleaseNotesPreviews.js";
 function releasePrepare(config, options) {
   const { dryRun, bumpOverride, setVersion, withReleaseNotes } = options;
   const workTypes = config.workTypes ?? { ...DEFAULT_WORK_TYPES };
   const versionPatterns = config.versionPatterns ?? { ...DEFAULT_VERSION_PATTERNS };
   const breakingPolicies = config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES;
+  const overridesResult = loadOverridesForScopes({ project: "." });
+  if (overridesResult.errors.length > 0) {
+    throw new Error(`Failed to load changelog overrides:
+  - ${overridesResult.errors.join("\n  - ")}`);
+  }
+  const overrides = overridesResult.project;
   const { tag, commits } = getCommitsSinceTarget([config.tagPrefix]);
   let releaseType;
   let parsedCommitCount;
@@ -36,6 +53,7 @@ function releasePrepare(config, options) {
     if (!isForwardVersion(currentVersion, setVersion)) {
       throw new Error(`--set-version ${setVersion} is not greater than current version ${currentVersion}`);
     }
+    refreshGitCliffCache();
     bump = setAllVersions(config.packageFiles, setVersion, dryRun);
   } else {
     if (bumpOverride === void 0) {
@@ -63,11 +81,20 @@ function releasePrepare(config, options) {
         dryRun
       };
     }
+    refreshGitCliffCache();
     bump = bumpAllVersions(config.packageFiles, releaseType, dryRun);
   }
   const newTag = `${config.tagPrefix}${bump.newVersion}`;
-  const changelogFiles = generateChangelogs(config, newTag, dryRun);
-  const changelogJsonFiles = config.changelogJson.enabled ? buildAndPersistChangelogJson(config, newTag, dryRun) : [];
+  const overrideWarnings = [];
+  const { changelogFiles, changelogJsonFiles } = writeSinglePackageChangelogs({
+    config,
+    commits,
+    newTag,
+    newVersion: bump.newVersion,
+    dryRun,
+    overrides,
+    overrideWarnings
+  });
   maybeWriteSinglePackagePreviews(withReleaseNotes === true, config, newTag, changelogJsonFiles[0], dryRun);
   const formatCommandStr = config.formatCommand ?? (hasPrettierConfig() ? "npx prettier --write" : void 0);
   let formatCommand;
@@ -102,12 +129,16 @@ function releasePrepare(config, options) {
     policyViolations: collector.violations.length > 0 ? collector.violations : void 0,
     setVersion
   });
-  return {
+  const result = {
     workspaces: [released],
     tags: [newTag],
     formatCommand,
     dryRun
   };
+  if (overrideWarnings.length > 0) {
+    result.warnings = overrideWarnings;
+  }
+  return result;
 }
 function buildSkippedSinglePackage(args) {
   const skipped = {
@@ -172,17 +203,43 @@ function buildReleasedSinglePackage(args) {
   }
   return released;
 }
-function buildAndPersistChangelogJson(config, newTag, dryRun) {
+function writeSinglePackageChangelogs(args) {
+  const { config, commits, newTag, newVersion, dryRun, overrides, overrideWarnings } = args;
+  const isEmptyRange = commits.length === 0;
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const baseEntries = isEmptyRange ? [buildEmptyReleaseEntry(newVersion, today)] : buildChangelogEntries(config, newTag);
+  const applied = applyChangelogOverrides(baseEntries, overrides);
+  if (applied.errors.length > 0) {
+    throw new Error(`Changelog override application failed:
+  - ${applied.errors.join("\n  - ")}`);
+  }
+  overrideWarnings.push(...applied.warnings);
+  const matchedSet = new Set(applied.matchedKeys);
+  for (const overrideKey of overrides.keys()) {
+    if (!matchedSet.has(overrideKey)) {
+      overrideWarnings.push(formatStaleOverrideKeyWarning(overrideKey));
+    }
+  }
+  const sectionOrder = deriveSectionOrder(resolveWorkTypes(config.workTypes));
+  const changelogFiles = [];
   const changelogJsonFiles = [];
-  const entries = buildChangelogEntries(config, newTag);
   for (const changelogPath of config.changelogPaths) {
     const jsonPath = resolveChangelogJsonPath(config, changelogPath);
-    if (!dryRun) {
-      upsertChangelogJson(jsonPath, entries);
+    const shouldWriteJson = config.changelogJson.enabled && !dryRun;
+    const mergedEntries = shouldWriteJson ? upsertChangelogJsonAndReturn(jsonPath, applied.entries) : mergeChangelogEntriesWithDisk(jsonPath, applied.entries);
+    if (config.changelogJson.enabled) {
+      changelogJsonFiles.push(jsonPath);
     }
-    changelogJsonFiles.push(jsonPath);
+    changelogFiles.push(
+      writeChangelogMarkdown({
+        changelogPath,
+        entries: mergedEntries,
+        sectionOrder,
+        dryRun
+      })
+    );
   }
-  return changelogJsonFiles;
+  return { changelogFiles, changelogJsonFiles };
 }
 function maybeWriteSinglePackagePreviews(withReleaseNotes, config, newTag, changelogJsonPath, dryRun) {
   if (!withReleaseNotes) {