@williamthorsen/release-kit 4.7.0 → 5.0.0

package/dist/esm/releasePrepareMono.js

@@ -1,35 +1,48 @@
 import { execSync } from "node:child_process";
-import { readFileSync } from "node:fs";
 import { buildDependencyGraph } from "./buildDependencyGraph.js";
-import { bumpAllVersions } from "./bumpAllVersions.js";
+import { bumpAllVersions, setAllVersions } from "./bumpAllVersions.js";
+import { isForwardVersion } from "./compareVersions.js";
 import { DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
+import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
 import { determineBumpFromCommits } from "./determineBumpFromCommits.js";
 import { generateChangelogJson, generateSyntheticChangelogJson } from "./generateChangelogJson.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 { 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,17 +50,18 @@ 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;
   });
   const formatCommand = runFormatCommand(config, tags, modifiedFiles, dryRun);
   return {
-    components,
+    workspaces,
     tags,
     formatCommand,
     dryRun,
@@ -55,27 +69,57 @@ function releasePrepareMono(config, options) {
   };
 }
 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 { tag, commits } = 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);
       if (currentVersion !== void 0) {
-        currentVersions.set(component.dir, currentVersion);
+        currentVersions.set(workspace.dir, currentVersion);
+      }
+    }
+    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,
+        commits,
+        releaseType: void 0,
+        parsedCommitCount: void 0,
+        unparseableCommits: void 0,
+        setVersion
+      });
+      continue;
     }
     if (commits.length === 0 && !force) {
       skippedResults.push({
-        component,
+        workspace,
         tag,
         commitCount: 0,
         parsedCommitCount: void 0,
@@ -97,7 +141,7 @@ function determineDirectBumps(config, options) {
     }
     if (releaseType === void 0) {
       skippedResults.push({
-        component,
+        workspace,
         tag,
         commitCount: commits.length,
         parsedCommitCount,
@@ -106,9 +150,9 @@ function determineDirectBumps(config, options) {
       });
       continue;
     }
-    directBumps.set(component.dir, { releaseType });
-    directResults.set(component.dir, {
-      component,
+    directBumps.set(workspace.dir, { releaseType });
+    directResults.set(workspace.dir, {
+      workspace,
       tag,
       commits,
       releaseType,
@@ -118,14 +162,14 @@ function determineDirectBumps(config, options) {
   }
   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,
+    workspaces.push({
+      name: skipped.workspace.dir,
       status: "skipped",
       previousTag: skipped.tag,
       commitCount: skipped.commitCount,
@@ -136,9 +180,9 @@ function collectSkippedComponents(skippedResults, fullReleaseSet) {
       skipReason: skipped.skipReason
     });
   }
-  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 +191,157 @@ 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
-          })
+    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
+  });
+  workspaces.push({
+    name: dir,
+    status: "released",
+    previousTag: directResult?.tag ?? previousTags.get(dir),
+    commitCount: directResult?.commits.length ?? 0,
+    parsedCommitCount: directResult?.parsedCommitCount,
+    // For --set-version workspaces releaseType is left undefined so reporting can branch
+    // on the override case without conflating it with a bump type.
+    releaseType: setVersionTarget === void 0 ? releaseEntry.releaseType : void 0,
+    currentVersion: bump.currentVersion,
+    newVersion: bump.newVersion,
+    tag: newTag,
+    bumpedFiles: bump.files,
+    changelogFiles,
+    commits: directResult?.commits,
+    unparseableCommits: directResult?.unparseableCommits,
+    propagatedFrom: releaseEntry.propagatedFrom,
+    ...setVersionTarget === void 0 ? {} : { setVersion: setVersionTarget }
+  });
+}
+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) {
+      for (const changelogPath of workspace.changelogPaths) {
+        const jsonFiles = generateSyntheticChangelogJson(
+          config,
+          changelogPath,
+          newVersion,
+          today,
+          releaseEntry.propagatedFrom,
+          dryRun
         );
-      }
-      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);
-        }
+        modifiedFiles.push(...jsonFiles);
+        firstChangelogJsonPath ??= jsonFiles[0];
       }
     }
-    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;
   }
-  return { tags, modifiedFiles };
+  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) {
+    for (const changelogPath of workspace.changelogPaths) {
+      const jsonFiles = generateChangelogJson(config, changelogPath, newTag, dryRun, {
+        tagPattern,
+        includePaths: workspace.paths
+      });
+      modifiedFiles.push(...jsonFiles);
+      firstChangelogJsonPath ??= jsonFiles[0];
+    }
+  }
+  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);
@@ -239,22 +361,20 @@ function runFormatCommand(config, tags, modifiedFiles, dryRun) {
   }
   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 readCurrentVersion(filePath) {
-  try {
-    const content = readFileSync(filePath, "utf8");
-    const parsed = JSON.parse(content);
-    if (hasVersionField(parsed)) {
-      return parsed.version;
-    }
-  } catch {
-  }
-  return void 0;
+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 +434,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/renderReleaseNotes.d.ts

@@ -2,6 +2,7 @@ import type { ChangelogAudience, ChangelogEntry, ChangelogSection } from './type
 export interface RenderOptions {
     filter?: (section: ChangelogSection) => boolean;
     includeHeading?: boolean;
+    sectionOrder?: string[];
 }
 export declare function matchesAudience(audience: ChangelogAudience): (section: ChangelogSection) => boolean;
 export declare function renderReleaseNotesSingle(entry: ChangelogEntry, options?: RenderOptions): string;

package/dist/esm/renderReleaseNotes.js

@@ -10,7 +10,9 @@ function matchesAudience(audience) {
 function renderReleaseNotesSingle(entry, options) {
   const filter = options?.filter;
   const includeHeading = options?.includeHeading ?? true;
-  const sections = filter !== void 0 ? entry.sections.filter(filter) : entry.sections;
+  const sectionOrder = options?.sectionOrder;
+  const filtered = filter !== void 0 ? entry.sections.filter(filter) : entry.sections;
+  const sections = sectionOrder !== void 0 ? sortSectionsByOrder(filtered, sectionOrder) : filtered;
   if (sections.length === 0) {
     return "";
   }
@@ -23,12 +25,37 @@ function renderReleaseNotesSingle(entry, options) {
       lines.push("");
     }
     lines.push(`### ${section.title}`, "");
-    for (const item of section.items) {
+    for (const [index, item] of section.items.entries()) {
       lines.push(`- ${item.description}`);
+      if (item.body !== void 0 && item.body.length > 0) {
+        lines.push("", ...indentBodyLines(item.body));
+        if (index < section.items.length - 1) {
+          lines.push("");
+        }
+      }
     }
   }
   return lines.join("\n") + "\n";
 }
+function sortSectionsByOrder(sections, order) {
+  const priority = /* @__PURE__ */ new Map();
+  for (const [index, title] of order.entries()) {
+    priority.set(title, index);
+  }
+  const indexed = sections.map((section, index) => ({ section, index }));
+  indexed.sort((a, b) => {
+    const priorityA = priority.get(a.section.title) ?? Number.POSITIVE_INFINITY;
+    const priorityB = priority.get(b.section.title) ?? Number.POSITIVE_INFINITY;
+    if (priorityA !== priorityB) {
+      return priorityA - priorityB;
+    }
+    return a.index - b.index;
+  });
+  return indexed.map(({ section }) => section);
+}
+function indentBodyLines(body) {
+  return body.split("\n").map((line) => line.length === 0 ? "" : `  ${line}`);
+}
 function renderReleaseNotesMulti(entries, options) {
   const parts = entries.map((entry) => renderReleaseNotesSingle(entry, options)).filter((part) => part.length > 0);
   return parts.join("\n");