@williamthorsen/release-kit 5.2.1 → 5.3.0

package/dist/esm/releasePrepareMono.js

@@ -1,30 +1,42 @@
 import { execSync } from "node:child_process";
 import { buildChangelogEntries } from "./buildChangelogEntries.js";
 import { buildDependencyGraph } from "./buildDependencyGraph.js";
+import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
 import { buildSyntheticChangelogEntry } from "./buildSyntheticChangelogEntry.js";
 import { bumpAllVersions, setAllVersions } from "./bumpAllVersions.js";
-import { resolveChangelogJsonPath, upsertChangelogJson } from "./changelogJsonFile.js";
+import {
+  mergeChangelogEntriesWithDisk,
+  resolveChangelogJsonPath,
+  upsertChangelogJsonAndReturn
+} 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";
-import { buildTagPattern, generateChangelog } from "./generateChangelogs.js";
+import { buildTagPattern } from "./generateChangelogs.js";
 import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
 import { hasPrettierConfig } from "./hasPrettierConfig.js";
 import { resolveWorkTypes } from "./loadConfig.js";
 import { propagateBumps } from "./propagateBumps.js";
 import { readCurrentVersion } from "./readCurrentVersion.js";
 import { releasePrepareProject } from "./releasePrepareProject.js";
+import { writeChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
+import { refreshGitCliffCache } from "./runGitCliff.js";
 import { writeReleaseNotesPreviews } from "./writeReleaseNotesPreviews.js";
-import { writeSyntheticChangelog } from "./writeSyntheticChangelog.js";
 function releasePrepareMono(config, options) {
   const { dryRun, withReleaseNotes } = options;
   if (withReleaseNotes === true && !config.changelogJson.enabled) {
     console.warn("Warning: --with-release-notes requires changelogJson.enabled; skipping preview generation");
   }
   const sectionOrder = deriveSectionOrder(resolveWorkTypes(config.workTypes));
+  const overrideContext = createOverrideContext(config.workspaces);
   const { directBumps, directResults, skippedResults, currentVersions } = determineDirectBumps(config, options);
   const previousTags = /* @__PURE__ */ new Map();
   for (const result of directResults.values()) {
@@ -47,7 +59,10 @@ function releasePrepareMono(config, options) {
     enabled: withReleaseNotes === true && config.changelogJson.enabled,
     sectionOrder
   };
-  const { tags, modifiedFiles } = executeReleaseSet(
+  if (fullReleaseSet.size > 0) {
+    refreshGitCliffCache();
+  }
+  const { tags, modifiedFiles } = executeReleaseSet({
     sortedDirs,
     fullReleaseSet,
     config,
@@ -55,8 +70,10 @@ function releasePrepareMono(config, options) {
     previousTags,
     dryRun,
     workspaces,
-    previewOptions
-  );
+    previewOptions,
+    overrideContext,
+    sectionOrder
+  });
   const configOrder = new Map(config.workspaces.map((w, i) => [w.dir, i]));
   workspaces.sort((a, b) => {
     const orderA = configOrder.get(a.name ?? "") ?? 0;
@@ -65,15 +82,32 @@ function releasePrepareMono(config, options) {
   });
   let project;
   if (config.project !== void 0) {
-    project = tryStage("project release stage", () => releasePrepareProject({ config, options, modifiedFiles, tags }));
+    project = tryStage(
+      "project release stage",
+      () => releasePrepareProject({
+        config,
+        options,
+        modifiedFiles,
+        tags,
+        rootOverrides: overrideContext.project,
+        overrideWarnings: overrideContext.overrideWarnings,
+        globalMatchedRootKeys: overrideContext.globalMatchedRootKeys
+      })
+    );
   }
   const formatCommand = runFormatCommand(config, tags, modifiedFiles, dryRun);
+  for (const overrideKey of overrideContext.project.keys()) {
+    if (!overrideContext.globalMatchedRootKeys.has(overrideKey)) {
+      overrideContext.overrideWarnings.push(formatStaleOverrideKeyWarning(overrideKey));
+    }
+  }
+  const allWarnings = [...warnings, ...overrideContext.overrideWarnings];
   return {
     workspaces,
     tags,
     formatCommand,
     dryRun,
-    ...warnings.length > 0 ? { warnings } : {},
+    ...allWarnings.length > 0 ? { warnings: allWarnings } : {},
     ...project === void 0 ? {} : { project }
   };
 }
@@ -206,7 +240,19 @@ function collectSkippedWorkspaces(skippedResults, fullReleaseSet) {
   }
   return workspaces;
 }
-function executeReleaseSet(sortedDirs, fullReleaseSet, config, directResults, previousTags, dryRun, workspaces, previewOptions) {
+function executeReleaseSet(args) {
+  const {
+    sortedDirs,
+    fullReleaseSet,
+    config,
+    directResults,
+    previousTags,
+    dryRun,
+    workspaces,
+    previewOptions,
+    overrideContext,
+    sectionOrder
+  } = args;
   const tags = [];
   const modifiedFiles = [];
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
@@ -233,7 +279,9 @@ function executeReleaseSet(sortedDirs, fullReleaseSet, config, directResults, pr
         tags,
         modifiedFiles,
         workspaces,
-        previewOptions
+        previewOptions,
+        overrideContext,
+        sectionOrder
       })
     );
   }
@@ -252,7 +300,9 @@ function executeWorkspaceRelease(args) {
     tags,
     modifiedFiles,
     workspaces,
-    previewOptions
+    previewOptions,
+    overrideContext,
+    sectionOrder
   } = args;
   const setVersionTarget = directResult?.setVersion;
   const bump = setVersionTarget === void 0 ? bumpAllVersions(workspace.packageFiles, releaseEntry.releaseType, dryRun) : setAllVersions(workspace.packageFiles, setVersionTarget, dryRun);
@@ -260,17 +310,21 @@ function executeWorkspaceRelease(args) {
   tags.push(newTag);
   modifiedFiles.push(...workspace.packageFiles, ...workspace.changelogPaths.map((p) => `${p}/CHANGELOG.md`));
   const isPropagationOnly = directResult === void 0;
+  const isEmptyRange = directResult !== void 0 && directResult.commits.length === 0;
   const changelogFiles = generateWorkspaceChangelogs({
     workspace,
     releaseEntry,
     newTag,
     newVersion: bump.newVersion,
     isPropagationOnly,
+    isEmptyRange,
     config,
     dryRun,
     today,
     modifiedFiles,
-    previewOptions
+    previewOptions,
+    overrideContext,
+    sectionOrder
   });
   const released = {
     name: dir,
@@ -327,66 +381,59 @@ function generateWorkspaceChangelogs(args) {
     newTag,
     newVersion,
     isPropagationOnly,
+    isEmptyRange,
     config,
     dryRun,
     today,
     modifiedFiles,
-    previewOptions
+    previewOptions,
+    overrideContext,
+    sectionOrder
   } = args;
+  const newEntries = buildWorkspaceEntries({
+    workspace,
+    releaseEntry,
+    newTag,
+    newVersion,
+    isPropagationOnly,
+    isEmptyRange,
+    config,
+    today
+  });
+  const applied = applyWorkspaceOverrides(newEntries, workspace.workspacePath, overrideContext);
   const changelogFiles = [];
   let firstChangelogJsonPath;
-  if (isPropagationOnly && releaseEntry.propagatedFrom !== void 0) {
-    for (const changelogPath of workspace.changelogPaths) {
-      changelogFiles.push(
-        writeSyntheticChangelog({
-          changelogPath,
-          newVersion,
-          date: today,
-          propagatedFrom: releaseEntry.propagatedFrom,
-          dryRun
-        })
-      );
-    }
+  for (const changelogPath of workspace.changelogPaths) {
+    const jsonPath = resolveChangelogJsonPath(config, changelogPath);
+    const shouldWriteJson = config.changelogJson.enabled && !dryRun;
+    const mergedEntries = shouldWriteJson ? upsertChangelogJsonAndReturn(jsonPath, applied.entries) : mergeChangelogEntriesWithDisk(jsonPath, applied.entries);
     if (config.changelogJson.enabled) {
-      const syntheticEntry = buildSyntheticChangelogEntry(releaseEntry.propagatedFrom, newVersion, today);
-      for (const changelogPath of workspace.changelogPaths) {
-        const jsonPath = resolveChangelogJsonPath(config, changelogPath);
-        if (!dryRun) {
-          upsertChangelogJson(jsonPath, [syntheticEntry]);
-        }
-        modifiedFiles.push(jsonPath);
-        firstChangelogJsonPath ??= jsonPath;
-      }
+      modifiedFiles.push(jsonPath);
+      firstChangelogJsonPath ??= jsonPath;
     }
-    maybeWritePreviews(workspace, newTag, firstChangelogJsonPath, previewOptions, dryRun);
-    return changelogFiles;
-  }
-  const tagPattern = buildTagPattern(getAllTagPrefixes(workspace));
-  for (const changelogPath of workspace.changelogPaths) {
     changelogFiles.push(
-      ...generateChangelog(config, changelogPath, newTag, dryRun, {
-        tagPattern,
-        includePaths: workspace.paths
+      writeChangelogMarkdown({
+        changelogPath,
+        entries: mergedEntries,
+        sectionOrder,
+        dryRun
       })
     );
   }
-  if (config.changelogJson.enabled) {
-    const entries = buildChangelogEntries(config, newTag, {
-      tagPattern,
-      includePaths: workspace.paths
-    });
-    for (const changelogPath of workspace.changelogPaths) {
-      const jsonPath = resolveChangelogJsonPath(config, changelogPath);
-      if (!dryRun) {
-        upsertChangelogJson(jsonPath, entries);
-      }
-      modifiedFiles.push(jsonPath);
-      firstChangelogJsonPath ??= jsonPath;
-    }
-  }
   maybeWritePreviews(workspace, newTag, firstChangelogJsonPath, previewOptions, dryRun);
   return changelogFiles;
 }
+function buildWorkspaceEntries(args) {
+  const { workspace, releaseEntry, newTag, newVersion, isPropagationOnly, isEmptyRange, config, today } = args;
+  if (isPropagationOnly && releaseEntry.propagatedFrom !== void 0) {
+    return [buildSyntheticChangelogEntry(releaseEntry.propagatedFrom, newVersion, today)];
+  }
+  if (isEmptyRange) {
+    return [buildEmptyReleaseEntry(newVersion, today)];
+  }
+  const tagPattern = buildTagPattern(getAllTagPrefixes(workspace));
+  return buildChangelogEntries(config, newTag, { tagPattern, includePaths: workspace.paths });
+}
 function maybeWritePreviews(workspace, newTag, changelogJsonPath, previewOptions, dryRun) {
   if (!previewOptions.enabled || changelogJsonPath === void 0) {
     return;

package/dist/esm/releasePrepareProject.d.ts

@@ -1,9 +1,12 @@
 import type { ReleasePrepareOptions } from './releasePrepare.ts';
-import type { MonorepoReleaseConfig, ProjectPrepareResult } from './types.ts';
+import type { ChangelogOverride, MonorepoReleaseConfig, ProjectPrepareResult } from './types.ts';
 export interface ReleasePrepareProjectArgs {
     config: MonorepoReleaseConfig;
     options: ReleasePrepareOptions;
     modifiedFiles: string[];
     tags: string[];
+    rootOverrides?: Map<string, ChangelogOverride>;
+    overrideWarnings?: string[];
+    globalMatchedRootKeys?: Set<string>;
 }
 export declare function releasePrepareProject(args: ReleasePrepareProjectArgs): ProjectPrepareResult;

package/dist/esm/releasePrepareProject.js

@@ -1,17 +1,21 @@
 import { buildChangelogEntries } from "./buildChangelogEntries.js";
+import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
 import { bumpAllVersions } from "./bumpAllVersions.js";
-import { resolveChangelogJsonPath, writeChangelogJson } from "./changelogJsonFile.js";
+import { mergeChangelogEntriesWithDisk, resolveChangelogJsonPath, writeChangelogJson } from "./changelogJsonFile.js";
+import { applyChangelogOverrides } from "./changelogOverrides.js";
 import { createPolicyViolationCollector } from "./collectPolicyViolations.js";
 import { decideRelease } from "./decideRelease.js";
 import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
-import { buildTagPattern, generateChangelog } from "./generateChangelogs.js";
+import { buildTagPattern } from "./generateChangelogs.js";
 import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
+import { writeChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
 import { writeReleaseNotesPreviews } from "./writeReleaseNotesPreviews.js";
 const ROOT_PACKAGE_FILE = "./package.json";
 const ROOT_CHANGELOG_PATH = ".";
 function releasePrepareProject(args) {
   const { config, options, modifiedFiles, tags } = args;
+  const { rootOverrides, overrideWarnings, globalMatchedRootKeys } = resolveOptionalOverrideArgs(args);
   const { dryRun, bumpOverride, withReleaseNotes, force } = options;
   const project = config.project;
   if (project === void 0) {
@@ -60,23 +64,18 @@ function releasePrepareProject(args) {
   const { releaseType, parsedCommitCount, unparseableCommits } = decision;
   const bump = bumpAllVersions([ROOT_PACKAGE_FILE], releaseType, dryRun);
   const newTag = `${project.tagPrefix}${bump.newVersion}`;
-  const tagPattern = buildTagPattern([project.tagPrefix]);
-  const changelogFiles = generateChangelog(config, ROOT_CHANGELOG_PATH, newTag, dryRun, {
-    tagPattern,
-    includePaths: contributingPaths
+  const { changelogFiles, changelogJsonFiles } = writeProjectChangelogs({
+    config,
+    project,
+    commits,
+    contributingPaths,
+    newTag,
+    newVersion: bump.newVersion,
+    dryRun,
+    rootOverrides,
+    overrideWarnings,
+    globalMatchedRootKeys
   });
-  const changelogJsonFiles = [];
-  if (config.changelogJson.enabled) {
-    const changelogJsonPath = resolveChangelogJsonPath(config, ROOT_CHANGELOG_PATH);
-    const entries = buildChangelogEntries(config, newTag, {
-      tagPattern,
-      includePaths: contributingPaths
-    });
-    if (!dryRun) {
-      writeChangelogJson(changelogJsonPath, entries);
-    }
-    changelogJsonFiles.push(changelogJsonPath);
-  }
   const firstChangelogJsonPath = changelogJsonFiles[0];
   if (withReleaseNotes === true && config.changelogJson.enabled && firstChangelogJsonPath !== void 0) {
     const sectionOrder = deriveSectionOrder(workTypes);
@@ -116,6 +115,63 @@ function releasePrepareProject(args) {
   }
   return result;
 }
+function resolveOptionalOverrideArgs(args) {
+  return {
+    rootOverrides: args.rootOverrides ?? /* @__PURE__ */ new Map(),
+    overrideWarnings: args.overrideWarnings ?? [],
+    globalMatchedRootKeys: args.globalMatchedRootKeys ?? /* @__PURE__ */ new Set()
+  };
+}
+function writeProjectChangelogs(args) {
+  const {
+    config,
+    project,
+    commits,
+    contributingPaths,
+    newTag,
+    newVersion,
+    dryRun,
+    rootOverrides,
+    overrideWarnings,
+    globalMatchedRootKeys
+  } = args;
+  const isEmptyRange = commits.length === 0;
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const tagPattern = buildTagPattern([project.tagPrefix]);
+  const newEntries = isEmptyRange ? [buildEmptyReleaseEntry(newVersion, today)] : buildChangelogEntries(config, newTag, { tagPattern, includePaths: contributingPaths });
+  const applied = applyChangelogOverrides(newEntries, rootOverrides);
+  if (applied.errors.length > 0) {
+    throw new Error(`Changelog override application failed:
+  - ${applied.errors.join("\n  - ")}`);
+  }
+  overrideWarnings.push(...applied.warnings);
+  for (const matched of applied.matchedKeys) {
+    globalMatchedRootKeys.add(matched);
+  }
+  const changelogJsonPath = resolveChangelogJsonPath(config, ROOT_CHANGELOG_PATH);
+  const sectionOrder = deriveSectionOrder(config.workTypes ?? { ...DEFAULT_WORK_TYPES });
+  const renderEntries = isEmptyRange ? mergeChangelogEntriesWithDisk(changelogJsonPath, applied.entries) : applied.entries;
+  if (config.changelogJson.enabled && !dryRun) {
+    if (isEmptyRange) {
+      writeChangelogJson(changelogJsonPath, renderEntries);
+    } else {
+      writeChangelogJson(changelogJsonPath, applied.entries);
+    }
+  }
+  const changelogFiles = [
+    writeChangelogMarkdown({
+      changelogPath: ROOT_CHANGELOG_PATH,
+      entries: renderEntries,
+      sectionOrder,
+      dryRun
+    })
+  ];
+  const changelogJsonFiles = [];
+  if (config.changelogJson.enabled) {
+    changelogJsonFiles.push(changelogJsonPath);
+  }
+  return { changelogFiles, changelogJsonFiles };
+}
 export {
   releasePrepareProject
 };

package/dist/esm/renderChangelogMarkdown.d.ts

@@ -0,0 +1,12 @@
+import type { ChangelogEntry } from './types.ts';
+export interface RenderChangelogMarkdownOptions {
+    sectionOrder?: string[];
+}
+export declare function renderChangelogMarkdown(entries: ChangelogEntry[], options?: RenderChangelogMarkdownOptions): string;
+export interface WriteChangelogMarkdownParams {
+    changelogPath: string;
+    entries: ChangelogEntry[];
+    sectionOrder?: string[];
+    dryRun?: boolean;
+}
+export declare function writeChangelogMarkdown(params: WriteChangelogMarkdownParams): string;

package/dist/esm/renderChangelogMarkdown.js

@@ -0,0 +1,32 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join as joinPath } from "node:path";
+import { renderReleaseNotesMulti } from "./renderReleaseNotes.js";
+const CHANGELOG_HEADER = `# Changelog
+
+All notable changes to this project will be documented in this file.`;
+const CHANGELOG_FOOTER = `<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->`;
+function renderChangelogMarkdown(entries, options) {
+  const body = renderReleaseNotesMulti(entries, options);
+  const trimmedBody = body.trimEnd();
+  const parts = [CHANGELOG_HEADER];
+  if (trimmedBody.length > 0) {
+    parts.push(trimmedBody);
+  }
+  parts.push(CHANGELOG_FOOTER);
+  return parts.join("\n\n") + "\n";
+}
+function writeChangelogMarkdown(params) {
+  const { changelogPath, entries, sectionOrder, dryRun = false } = params;
+  const filePath = joinPath(changelogPath, "CHANGELOG.md");
+  if (dryRun) {
+    return filePath;
+  }
+  const rendered = renderChangelogMarkdown(entries, sectionOrder !== void 0 ? { sectionOrder } : void 0);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, rendered, "utf8");
+  return filePath;
+}
+export {
+  renderChangelogMarkdown,
+  writeChangelogMarkdown
+};

package/dist/esm/renderReleaseNotes.js

@@ -1,3 +1,8 @@
+import { WORK_TYPES_DATA } from "./workTypesData.js";
+function getBreakingPrefix() {
+  const { emoji, label } = WORK_TYPES_DATA.markers.breaking;
+  return `${emoji} **${label}:** `;
+}
 function allSections() {
   return true;
 }
@@ -26,7 +31,7 @@ function renderReleaseNotesSingle(entry, options) {
     }
     lines.push(`### ${section.title}`, "");
     for (const [index, item] of section.items.entries()) {
-      const prefix = item.breaking === true ? "\u{1F6A8} **Breaking:** " : "";
+      const prefix = item.breaking === true ? getBreakingPrefix() : "";
       lines.push(`- ${prefix}${item.description}`);
       if (item.body !== void 0 && item.body.length > 0) {
         lines.push("", ...indentBodyLines(item.body));

package/dist/esm/resolveReleaseNotesConfig.js

@@ -33,7 +33,9 @@ async function resolveReleaseNotesConfig(options = {}) {
     console.warn(`  \u26A0\uFE0F  ${warning}`);
   }
   return {
-    releaseNotes: { ...DEFAULT_RELEASE_NOTES_CONFIG, ...config.releaseNotes },
+    releaseNotes: {
+      shouldInjectIntoReadme: config.releaseNotes?.shouldInjectIntoReadme ?? DEFAULT_RELEASE_NOTES_CONFIG.shouldInjectIntoReadme
+    },
     changelogJsonOutputPath: config.changelogJson?.outputPath ?? DEFAULT_CHANGELOG_JSON_CONFIG.outputPath,
     sectionOrder: deriveSectionOrder(resolveWorkTypes(config.workTypes))
   };

package/dist/esm/runGitCliff.d.ts

@@ -1,2 +1,3 @@
 import { type StdioOptions } from 'node:child_process';
 export declare function runGitCliff(cliffConfigPath: string, cliffArgs: readonly string[], stdio: StdioOptions): string;
+export declare function refreshGitCliffCache(): void;

package/dist/esm/runGitCliff.js

@@ -22,6 +22,13 @@ function runGitCliff(cliffConfigPath, cliffArgs, stdio) {
     }
   }
 }
+function refreshGitCliffCache() {
+  execFileSync("npx", ["--yes", "git-cliff", "--version"], {
+    stdio: ["ignore", "pipe", "inherit"],
+    env: { ...process.env, npm_config_progress: "false" }
+  });
+}
 export {
+  refreshGitCliffCache,
   runGitCliff
 };

package/dist/esm/syncWorkTypes.js

@@ -3,7 +3,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { UPSTREAM_WORK_TYPES_URL } from "./checkWorkTypesDrift.js";
 import { isRecord } from "./typeGuards.js";
-import { errorMessage, hasExpectedTopLevelShape } from "./workTypesUtils.js";
+import { buildFetchInit, errorMessage, hasExpectedTopLevelShape } from "./workTypesUtils.js";
 function resolveDefaultLocalPath() {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
   return resolve(moduleDir, "work-types.json");
@@ -25,9 +25,10 @@ async function syncWorkTypes(dependencies = {}) {
   const localPath = dependencies.localPath ?? resolveDefaultLocalPath();
   const fetcher = dependencies.fetch ?? globalThis.fetch;
   const url = dependencies.upstreamUrl ?? UPSTREAM_WORK_TYPES_URL;
+  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,