@williamthorsen/release-kit 4.8.0 → 5.1.0

package/dist/esm/releasePrepareMono.js

@@ -1,35 +1,51 @@
 import { execSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { buildChangelogEntries } from "./buildChangelogEntries.js";
 import { buildDependencyGraph } from "./buildDependencyGraph.js";
-import { bumpAllVersions } from "./bumpAllVersions.js";
+import { buildSyntheticChangelogEntry } from "./buildSyntheticChangelogEntry.js";
+import { bumpAllVersions, setAllVersions } from "./bumpAllVersions.js";
+import { resolveChangelogJsonPath, upsertChangelogJson } from "./changelogJsonFile.js";
+import { isForwardVersion } from "./compareVersions.js";
+import { decideRelease } from "./decideRelease.js";
 import { DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
-import { determineBumpFromCommits } from "./determineBumpFromCommits.js";
-import { generateChangelogJson, generateSyntheticChangelogJson } from "./generateChangelogJson.js";
+import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
 import { buildTagPattern, generateChangelog } 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 { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
+import { writeReleaseNotesPreviews } from "./writeReleaseNotesPreviews.js";
 import { writeSyntheticChangelog } from "./writeSyntheticChangelog.js";
 function releasePrepareMono(config, options) {
-  const { dryRun } = 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 { directBumps, directResults, skippedResults, currentVersions } = determineDirectBumps(config, options);
   const previousTags = /* @__PURE__ */ new Map();
   for (const result of directResults.values()) {
-    previousTags.set(result.component.dir, result.tag);
+    previousTags.set(result.workspace.dir, result.tag);
   }
   for (const skipped of skippedResults) {
-    previousTags.set(skipped.component.dir, skipped.tag);
+    previousTags.set(skipped.workspace.dir, skipped.tag);
   }
-  const graph = buildDependencyGraph(config.components);
+  const graph = buildDependencyGraph(config.workspaces);
   const fullReleaseSet = propagateBumps(directBumps, graph, currentVersions);
   const { sorted: sortedDirs, cyclicDirs } = topologicalSort(fullReleaseSet, graph);
   const warnings = [];
   if (cyclicDirs.length > 0) {
     warnings.push(
-      `Circular workspace dependencies detected among: ${cyclicDirs.join(", ")}. Propagation metadata may be incomplete for these components.`
+      `Circular workspace dependencies detected among: ${cyclicDirs.join(", ")}. Propagation metadata may be incomplete for these workspaces.`
     );
   }
-  const components = collectSkippedComponents(skippedResults, fullReleaseSet);
+  const workspaces = collectSkippedWorkspaces(skippedResults, fullReleaseSet);
+  const previewOptions = {
+    enabled: withReleaseNotes === true && config.changelogJson.enabled,
+    sectionOrder
+  };
   const { tags, modifiedFiles } = executeReleaseSet(
     sortedDirs,
     fullReleaseSet,
@@ -37,108 +53,148 @@ function releasePrepareMono(config, options) {
     directResults,
     previousTags,
     dryRun,
-    components
+    workspaces,
+    previewOptions
   );
-  const configOrder = new Map(config.components.map((c, i) => [c.dir, i]));
-  components.sort((a, b) => {
+  const configOrder = new Map(config.workspaces.map((w, i) => [w.dir, i]));
+  workspaces.sort((a, b) => {
     const orderA = configOrder.get(a.name ?? "") ?? 0;
     const orderB = configOrder.get(b.name ?? "") ?? 0;
     return orderA - orderB;
   });
+  let project;
+  if (config.project !== void 0) {
+    project = tryStage("project release stage", () => releasePrepareProject({ config, options, modifiedFiles, tags }));
+  }
   const formatCommand = runFormatCommand(config, tags, modifiedFiles, dryRun);
   return {
-    components,
+    workspaces,
     tags,
     formatCommand,
     dryRun,
-    ...warnings.length > 0 ? { warnings } : {}
+    ...warnings.length > 0 ? { warnings } : {},
+    ...project === void 0 ? {} : { project }
   };
 }
 function determineDirectBumps(config, options) {
-  const { force, bumpOverride } = options;
+  const { force, bumpOverride, setVersion } = options;
+  if (setVersion !== void 0 && config.workspaces.length !== 1) {
+    throw new Error(`--set-version requires exactly one workspace; received ${config.workspaces.length}`);
+  }
   const workTypes = config.workTypes ?? { ...DEFAULT_WORK_TYPES };
   const versionPatterns = config.versionPatterns ?? { ...DEFAULT_VERSION_PATTERNS };
   const directBumps = /* @__PURE__ */ new Map();
   const directResults = /* @__PURE__ */ new Map();
   const skippedResults = [];
   const currentVersions = /* @__PURE__ */ new Map();
-  for (const component of config.components) {
-    const name = component.dir;
-    const { tag, commits } = getCommitsSinceTarget(component.tagPrefix, component.paths);
+  const hintState = { emitted: false };
+  const knownPrefixes = config.workspaces.flatMap(getAllTagPrefixes);
+  for (const workspace of config.workspaces) {
+    const name = workspace.dir;
+    const stageLabel = workspaceStageLabel(workspace.dir);
+    const { tag, commits } = tryStage(
+      stageLabel,
+      () => getCommitsSinceTarget(getAllTagPrefixes(workspace), workspace.paths)
+    );
     const since = tag === void 0 ? "(no previous release found)" : `since ${tag}`;
-    const primaryPackageFile = component.packageFiles[0];
+    if (tag === void 0) {
+      maybeEmitBaselineHint(workspace, knownPrefixes, hintState);
+    }
+    const primaryPackageFile = workspace.packageFiles[0];
     if (primaryPackageFile !== void 0) {
-      const currentVersion = readCurrentVersion(primaryPackageFile);
+      const currentVersion = tryStage(stageLabel, () => readCurrentVersion(primaryPackageFile));
       if (currentVersion !== void 0) {
-        currentVersions.set(component.dir, currentVersion);
+        currentVersions.set(workspace.dir, currentVersion);
       }
     }
-    if (commits.length === 0 && !force) {
-      skippedResults.push({
-        component,
+    if (setVersion !== void 0) {
+      const currentVersion = currentVersions.get(workspace.dir);
+      if (currentVersion === void 0) {
+        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,
         tag,
-        commitCount: 0,
+        commits,
+        releaseType: void 0,
         parsedCommitCount: void 0,
         unparseableCommits: void 0,
-        skipReason: `No changes for ${name} ${since}. Skipping.`
+        bumpOverride: void 0,
+        setVersion
       });
       continue;
     }
-    let releaseType;
-    let parsedCommitCount;
-    let unparseableCommits;
-    if (bumpOverride === void 0) {
-      const determination = determineBumpFromCommits(commits, workTypes, versionPatterns, config.scopeAliases);
-      parsedCommitCount = determination.parsedCommitCount;
-      unparseableCommits = determination.unparseableCommits;
-      releaseType = determination.releaseType;
-    } else {
-      releaseType = bumpOverride;
-    }
-    if (releaseType === void 0) {
+    const decision = tryStage(
+      stageLabel,
+      () => decideRelease({
+        commits,
+        force,
+        bumpOverride,
+        workTypes,
+        versionPatterns,
+        scopeAliases: config.scopeAliases,
+        skipReasons: {
+          noCommits: `No commits for ${name} ${since}. Pass --force to release at patch. Skipping.`,
+          noBumpWorthy: `No bump-worthy commits for ${name} ${since}. Pass --force to release at patch (or --force --bump=X for a different level). Skipping.`
+        }
+      })
+    );
+    if (decision.outcome === "skip") {
       skippedResults.push({
-        component,
+        workspace,
         tag,
         commitCount: commits.length,
-        parsedCommitCount,
-        unparseableCommits,
-        skipReason: `No release-worthy changes for ${name} ${since}. Skipping.`
+        parsedCommitCount: decision.parsedCommitCount,
+        unparseableCommits: decision.unparseableCommits,
+        skipReason: decision.skipReason
       });
       continue;
     }
-    directBumps.set(component.dir, { releaseType });
-    directResults.set(component.dir, {
-      component,
+    directBumps.set(workspace.dir, { releaseType: decision.releaseType });
+    directResults.set(workspace.dir, {
+      workspace,
       tag,
       commits,
-      releaseType,
-      parsedCommitCount,
-      unparseableCommits
+      releaseType: decision.releaseType,
+      parsedCommitCount: decision.parsedCommitCount,
+      unparseableCommits: decision.unparseableCommits,
+      bumpOverride
     });
   }
   return { directBumps, directResults, skippedResults, currentVersions };
 }
-function collectSkippedComponents(skippedResults, fullReleaseSet) {
-  const components = [];
+function collectSkippedWorkspaces(skippedResults, fullReleaseSet) {
+  const workspaces = [];
   for (const skipped of skippedResults) {
-    if (fullReleaseSet.has(skipped.component.dir)) {
+    if (fullReleaseSet.has(skipped.workspace.dir)) {
       continue;
     }
-    components.push({
-      name: skipped.component.dir,
+    const result = {
+      name: skipped.workspace.dir,
       status: "skipped",
-      previousTag: skipped.tag,
       commitCount: skipped.commitCount,
-      parsedCommitCount: skipped.parsedCommitCount,
-      unparseableCommits: skipped.unparseableCommits,
-      bumpedFiles: [],
-      changelogFiles: [],
       skipReason: skipped.skipReason
-    });
+    };
+    if (skipped.tag !== void 0) {
+      result.previousTag = skipped.tag;
+    }
+    if (skipped.parsedCommitCount !== void 0) {
+      result.parsedCommitCount = skipped.parsedCommitCount;
+    }
+    if (skipped.unparseableCommits !== void 0) {
+      result.unparseableCommits = skipped.unparseableCommits;
+    }
+    workspaces.push(result);
   }
-  return components;
+  return workspaces;
 }
-function executeReleaseSet(sortedDirs, fullReleaseSet, config, directResults, previousTags, dryRun, components) {
+function executeReleaseSet(sortedDirs, fullReleaseSet, config, directResults, previousTags, dryRun, workspaces, previewOptions) {
   const tags = [];
   const modifiedFiles = [];
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
@@ -147,79 +203,178 @@ function executeReleaseSet(sortedDirs, fullReleaseSet, config, directResults, pr
     if (releaseEntry === void 0) {
       continue;
     }
-    const component = findComponent(config.components, dir);
-    if (component === void 0) {
+    const workspace = findWorkspace(config.workspaces, dir);
+    if (workspace === void 0) {
       continue;
     }
-    const bump = bumpAllVersions(component.packageFiles, releaseEntry.releaseType, dryRun);
-    const newTag = `${component.tagPrefix}${bump.newVersion}`;
-    tags.push(newTag);
-    modifiedFiles.push(...component.packageFiles, ...component.changelogPaths.map((p) => `${p}/CHANGELOG.md`));
-    const changelogFiles = [];
-    const directResult = directResults.get(dir);
-    const isPropagationOnly = directResult === void 0;
-    if (isPropagationOnly && releaseEntry.propagatedFrom !== void 0) {
-      for (const changelogPath of component.changelogPaths) {
-        changelogFiles.push(
-          writeSyntheticChangelog({
-            changelogPath,
-            newVersion: bump.newVersion,
-            date: today,
-            propagatedFrom: releaseEntry.propagatedFrom,
-            dryRun
-          })
-        );
-      }
-      if (config.changelogJson.enabled) {
-        for (const changelogPath of component.changelogPaths) {
-          const jsonFiles = generateSyntheticChangelogJson(
-            config,
-            changelogPath,
-            bump.newVersion,
-            today,
-            releaseEntry.propagatedFrom,
-            dryRun
-          );
-          modifiedFiles.push(...jsonFiles);
-        }
-      }
-    } else {
-      for (const changelogPath of component.changelogPaths) {
-        changelogFiles.push(
-          ...generateChangelog(config, changelogPath, newTag, dryRun, {
-            tagPattern: buildTagPattern(component.tagPrefix),
-            includePaths: component.paths
-          })
-        );
-      }
-      if (config.changelogJson.enabled) {
-        for (const changelogPath of component.changelogPaths) {
-          const jsonFiles = generateChangelogJson(config, changelogPath, newTag, dryRun, {
-            tagPattern: buildTagPattern(component.tagPrefix),
-            includePaths: component.paths
-          });
-          modifiedFiles.push(...jsonFiles);
+    tryStage(
+      workspaceStageLabel(dir),
+      () => executeWorkspaceRelease({
+        dir,
+        workspace,
+        releaseEntry,
+        directResult: directResults.get(dir),
+        previousTags,
+        config,
+        dryRun,
+        today,
+        tags,
+        modifiedFiles,
+        workspaces,
+        previewOptions
+      })
+    );
+  }
+  return { tags, modifiedFiles };
+}
+function executeWorkspaceRelease(args) {
+  const {
+    dir,
+    workspace,
+    releaseEntry,
+    directResult,
+    previousTags,
+    config,
+    dryRun,
+    today,
+    tags,
+    modifiedFiles,
+    workspaces,
+    previewOptions
+  } = args;
+  const setVersionTarget = directResult?.setVersion;
+  const bump = setVersionTarget === void 0 ? bumpAllVersions(workspace.packageFiles, releaseEntry.releaseType, dryRun) : setAllVersions(workspace.packageFiles, setVersionTarget, dryRun);
+  const newTag = `${workspace.tagPrefix}${bump.newVersion}`;
+  tags.push(newTag);
+  modifiedFiles.push(...workspace.packageFiles, ...workspace.changelogPaths.map((p) => `${p}/CHANGELOG.md`));
+  const isPropagationOnly = directResult === void 0;
+  const changelogFiles = generateWorkspaceChangelogs({
+    workspace,
+    releaseEntry,
+    newTag,
+    newVersion: bump.newVersion,
+    isPropagationOnly,
+    config,
+    dryRun,
+    today,
+    modifiedFiles,
+    previewOptions
+  });
+  const released = {
+    name: dir,
+    status: "released",
+    commitCount: directResult?.commits.length ?? 0,
+    currentVersion: bump.currentVersion,
+    newVersion: bump.newVersion,
+    tag: newTag,
+    bumpedFiles: bump.files,
+    changelogFiles
+  };
+  const previousTag = directResult?.tag ?? previousTags.get(dir);
+  if (previousTag !== void 0) {
+    released.previousTag = previousTag;
+  }
+  if (directResult?.parsedCommitCount !== void 0) {
+    released.parsedCommitCount = directResult.parsedCommitCount;
+  }
+  if (setVersionTarget === void 0) {
+    released.releaseType = releaseEntry.releaseType;
+  }
+  if (directResult?.commits !== void 0) {
+    released.commits = directResult.commits;
+  }
+  if (directResult?.unparseableCommits !== void 0) {
+    released.unparseableCommits = directResult.unparseableCommits;
+  }
+  if (releaseEntry.propagatedFrom !== void 0) {
+    released.propagatedFrom = releaseEntry.propagatedFrom;
+  }
+  if (directResult?.bumpOverride !== void 0) {
+    released.bumpOverride = directResult.bumpOverride;
+  }
+  if (setVersionTarget !== void 0) {
+    released.setVersion = setVersionTarget;
+  }
+  workspaces.push(released);
+}
+function generateWorkspaceChangelogs(args) {
+  const {
+    workspace,
+    releaseEntry,
+    newTag,
+    newVersion,
+    isPropagationOnly,
+    config,
+    dryRun,
+    today,
+    modifiedFiles,
+    previewOptions
+  } = args;
+  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
+        })
+      );
+    }
+    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;
       }
     }
-    components.push({
-      name: dir,
-      status: "released",
-      previousTag: directResult?.tag ?? previousTags.get(dir),
-      commitCount: directResult?.commits.length ?? 0,
-      parsedCommitCount: directResult?.parsedCommitCount,
-      releaseType: releaseEntry.releaseType,
-      currentVersion: bump.currentVersion,
-      newVersion: bump.newVersion,
-      tag: newTag,
-      bumpedFiles: bump.files,
-      changelogFiles,
-      commits: directResult?.commits,
-      unparseableCommits: directResult?.unparseableCommits,
-      propagatedFrom: releaseEntry.propagatedFrom
+    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
+      })
+    );
+  }
+  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;
+    }
   }
-  return { tags, modifiedFiles };
+  maybeWritePreviews(workspace, newTag, firstChangelogJsonPath, previewOptions, dryRun);
+  return changelogFiles;
+}
+function maybeWritePreviews(workspace, newTag, changelogJsonPath, previewOptions, dryRun) {
+  if (!previewOptions.enabled || changelogJsonPath === void 0) {
+    return;
+  }
+  writeReleaseNotesPreviews({
+    workspacePath: workspace.workspacePath,
+    tag: newTag,
+    changelogJsonPath,
+    sectionOrder: previewOptions.sectionOrder,
+    dryRun
+  });
 }
 function runFormatCommand(config, tags, modifiedFiles, dryRun) {
   const formatCommandStr = config.formatCommand ?? (hasPrettierConfig() ? "npx prettier --write" : void 0);
@@ -233,28 +388,39 @@ function runFormatCommand(config, tags, modifiedFiles, dryRun) {
   try {
     execSync(fullCommand, { stdio: "inherit" });
   } catch (error) {
-    throw new Error(
-      `Format command failed ('${fullCommand}'): ${error instanceof Error ? error.message : String(error)}`
-    );
+    const baseMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`format stage: ${baseMessage} (command: '${fullCommand}')`, { cause: error });
   }
   return { command: fullCommand, executed: true, files: modifiedFiles };
 }
-function findComponent(components, dir) {
-  return components.find((c) => c.dir === dir);
+function findWorkspace(workspaces, dir) {
+  return workspaces.find((w) => w.dir === dir);
 }
-function hasVersionField(value) {
-  return typeof value === "object" && value !== null && "version" in value && typeof value.version === "string";
+function wrapStageError(stageLabel, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return new Error(`${stageLabel}: ${message}`, { cause: error });
 }
-function readCurrentVersion(filePath) {
+function tryStage(stageLabel, fn) {
   try {
-    const content = readFileSync(filePath, "utf8");
-    const parsed = JSON.parse(content);
-    if (hasVersionField(parsed)) {
-      return parsed.version;
-    }
-  } catch {
+    return fn();
+  } catch (error) {
+    throw wrapStageError(stageLabel, error);
   }
-  return void 0;
+}
+function workspaceStageLabel(dir) {
+  return `workspace '${dir}' release stage`;
+}
+function maybeEmitBaselineHint(workspace, knownPrefixes, state) {
+  if (state.emitted) return;
+  if ((workspace.legacyIdentities?.length ?? 0) > 0) return;
+  const candidates = detectUndeclaredTagPrefixes(knownPrefixes);
+  if (candidates.length === 0) return;
+  const totalTags = candidates.reduce((sum, candidate) => sum + candidate.tagCount, 0);
+  const example = candidates[0]?.exampleTags[0] ?? `${candidates[0]?.prefix ?? ""}?`;
+  console.error(
+    `Hint: no baseline tag found for ${workspace.dir} under '${workspace.tagPrefix}', but ${totalTags} candidate-shaped tags exist (e.g., ${example}). Run 'release-kit show-tag-prefixes' to check for undeclared legacy prefixes.`
+  );
+  state.emitted = true;
 }
 function topologicalSort(releaseSet, graph) {
   const releaseDirs = new Set(releaseSet.keys());
@@ -314,6 +480,9 @@ function topologicalSort(releaseSet, graph) {
   }
   return { sorted, cyclicDirs };
 }
+function getAllTagPrefixes(workspace) {
+  return [workspace.tagPrefix, ...workspace.legacyIdentities?.map((identity) => identity.tagPrefix) ?? []];
+}
 export {
   releasePrepareMono
 };

package/dist/esm/releasePrepareProject.d.ts

@@ -0,0 +1,9 @@
+import type { ReleasePrepareOptions } from './releasePrepare.ts';
+import type { MonorepoReleaseConfig, ProjectPrepareResult } from './types.ts';
+export interface ReleasePrepareProjectArgs {
+    config: MonorepoReleaseConfig;
+    options: ReleasePrepareOptions;
+    modifiedFiles: string[];
+    tags: string[];
+}
+export declare function releasePrepareProject(args: ReleasePrepareProjectArgs): ProjectPrepareResult;