@williamthorsen/release-kit 5.0.0 → 5.2.0

package/dist/esm/loadConfig.js

@@ -1,13 +1,41 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import {
   DEFAULT_CHANGELOG_JSON_CONFIG,
+  DEFAULT_PROJECT_TAG_PREFIX,
   DEFAULT_RELEASE_NOTES_CONFIG,
   DEFAULT_VERSION_PATTERNS,
   DEFAULT_WORK_TYPES
 } from "./defaults.js";
 import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
 import { isRecord } from "./typeGuards.js";
+const ROOT_PACKAGE_JSON_PATH = "package.json";
+function readRootPackageVersion() {
+  const absolutePath = path.resolve(process.cwd(), ROOT_PACKAGE_JSON_PATH);
+  if (!existsSync(absolutePath)) {
+    return { exists: false, version: void 0 };
+  }
+  let contents;
+  try {
+    contents = readFileSync(absolutePath, "utf8");
+  } catch (error) {
+    throw new Error(
+      `Failed to read root ${ROOT_PACKAGE_JSON_PATH}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(contents);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse root ${ROOT_PACKAGE_JSON_PATH}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!isRecord(parsed)) {
+    return { exists: true, version: void 0 };
+  }
+  return { exists: true, version: typeof parsed.version === "string" ? parsed.version : void 0 };
+}
 const CONFIG_FILE_PATH = ".config/release-kit.config.ts";
 async function loadConfig() {
   const absoluteConfigPath = path.resolve(process.cwd(), CONFIG_FILE_PATH);
@@ -28,7 +56,7 @@ async function loadConfig() {
   }
   return resolved;
 }
-function mergeMonorepoConfig(discoveredPaths, userConfig) {
+function mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage) {
   let workspaces = discoveredPaths.map((workspacePath) => deriveWorkspaceConfig(workspacePath));
   assertUniqueTagPrefixes(workspaces);
   if (userConfig?.workspaces !== void 0) {
@@ -48,10 +76,12 @@ function mergeMonorepoConfig(discoveredPaths, userConfig) {
   if (userConfig?.retiredPackages !== void 0) {
     assertRetiredPackagesDoNotCollideWithActive(workspaces, userConfig.retiredPackages);
   }
+  const project = resolveProjectConfig(userConfig?.project, rootPackage);
   const workTypes = resolveWorkTypes(userConfig?.workTypes);
   const versionPatterns = userConfig?.versionPatterns === void 0 ? { ...DEFAULT_VERSION_PATTERNS } : { ...userConfig.versionPatterns };
   const changelogJson = mergeChangelogJsonConfig(userConfig?.changelogJson);
   const releaseNotes = mergeReleaseNotesConfig(userConfig?.releaseNotes);
+  assertNoTagPrefixCollisions(workspaces, userConfig?.retiredPackages, project);
   const result = {
     workspaces,
     workTypes,
@@ -59,21 +89,30 @@ function mergeMonorepoConfig(discoveredPaths, userConfig) {
     changelogJson,
     releaseNotes
   };
-  const formatCommand = userConfig?.formatCommand;
-  if (formatCommand !== void 0) {
-    result.formatCommand = formatCommand;
+  if (project !== void 0) {
+    result.project = project;
   }
-  const cliffConfigPath = userConfig?.cliffConfigPath;
-  if (cliffConfigPath !== void 0) {
-    result.cliffConfigPath = cliffConfigPath;
+  applyOptionalPassthroughFields(result, userConfig);
+  return result;
+}
+function applyOptionalPassthroughFields(result, userConfig) {
+  if (userConfig?.formatCommand !== void 0) {
+    result.formatCommand = userConfig.formatCommand;
   }
-  const scopeAliases = userConfig?.scopeAliases;
-  if (scopeAliases !== void 0) {
-    result.scopeAliases = scopeAliases;
+  if (userConfig?.cliffConfigPath !== void 0) {
+    result.cliffConfigPath = userConfig.cliffConfigPath;
+  }
+  if (userConfig?.scopeAliases !== void 0) {
+    result.scopeAliases = userConfig.scopeAliases;
+  }
+  if (userConfig?.breakingPolicies !== void 0) {
+    result.breakingPolicies = userConfig.breakingPolicies;
   }
-  return result;
 }
 function mergeSinglePackageConfig(userConfig) {
+  if (userConfig?.project !== void 0) {
+    throw new Error("project block is not supported in single-package mode");
+  }
   const workTypes = resolveWorkTypes(userConfig?.workTypes);
   const versionPatterns = userConfig?.versionPatterns === void 0 ? { ...DEFAULT_VERSION_PATTERNS } : { ...userConfig.versionPatterns };
   const changelogJson = mergeChangelogJsonConfig(userConfig?.changelogJson);
@@ -87,18 +126,7 @@ function mergeSinglePackageConfig(userConfig) {
     changelogJson,
     releaseNotes
   };
-  const formatCommand = userConfig?.formatCommand;
-  if (formatCommand !== void 0) {
-    result.formatCommand = formatCommand;
-  }
-  const cliffConfigPath = userConfig?.cliffConfigPath;
-  if (cliffConfigPath !== void 0) {
-    result.cliffConfigPath = cliffConfigPath;
-  }
-  const scopeAliases = userConfig?.scopeAliases;
-  if (scopeAliases !== void 0) {
-    result.scopeAliases = scopeAliases;
-  }
+  applyOptionalPassthroughFields(result, userConfig);
   return result;
 }
 function resolveWorkTypes(userWorkTypes) {
@@ -137,6 +165,62 @@ function assertRetiredPackagesDoNotCollideWithActive(workspaces, retiredPackages
     }
   }
 }
+function resolveProjectConfig(userProject, rootPackage) {
+  if (userProject === void 0) {
+    return void 0;
+  }
+  if (rootPackage === void 0 || !rootPackage.exists) {
+    throw new Error(
+      `project block requires a root ${ROOT_PACKAGE_JSON_PATH}; create one with a 'version' field at the repo root`
+    );
+  }
+  if (rootPackage.version === void 0) {
+    throw new Error(
+      `project block requires root ${ROOT_PACKAGE_JSON_PATH} to have a 'version' field; add a 'version' field to your root package.json`
+    );
+  }
+  return { tagPrefix: userProject.tagPrefix ?? DEFAULT_PROJECT_TAG_PREFIX };
+}
+function assertNoTagPrefixCollisions(workspaces, retiredPackages, project) {
+  const sources = [];
+  for (const workspace of workspaces) {
+    const owner = `ws:${workspace.dir}`;
+    sources.push({ prefix: workspace.tagPrefix, label: `workspace '${workspace.dir}'`, owner });
+    for (const identity of workspace.legacyIdentities ?? []) {
+      sources.push({
+        prefix: identity.tagPrefix,
+        label: `workspace '${workspace.dir}' legacyIdentities entry (name='${identity.name}')`,
+        owner
+      });
+    }
+  }
+  for (const [index, retired] of (retiredPackages ?? []).entries()) {
+    sources.push({
+      prefix: retired.tagPrefix,
+      label: `retiredPackages entry (name='${retired.name}')`,
+      owner: `retired:${index}`
+    });
+  }
+  if (project !== void 0) {
+    sources.push({ prefix: project.tagPrefix, label: "project", owner: "project" });
+  }
+  for (let i = 0; i < sources.length; i++) {
+    for (let j = i + 1; j < sources.length; j++) {
+      const a = sources[i];
+      const b = sources[j];
+      if (a === void 0 || b === void 0) continue;
+      if (a.owner === b.owner) continue;
+      if (isPrefixCollision(a.prefix, b.prefix)) {
+        throw new Error(
+          `Tag prefix collision: '${a.prefix}' (${a.label}) and '${b.prefix}' (${b.label}). One prefix is identical to or a strict prefix of the other; this would cause \`git describe --match=<prefix>*\` to return cross-matches.`
+        );
+      }
+    }
+  }
+}
+function isPrefixCollision(a, b) {
+  return a === b || a.startsWith(b) || b.startsWith(a);
+}
 function assertUniqueTagPrefixes(workspaces) {
   const pathsByPrefix = /* @__PURE__ */ new Map();
   for (const workspace of workspaces) {
@@ -163,8 +247,10 @@ function mergeReleaseNotesConfig(partial) {
 }
 export {
   CONFIG_FILE_PATH,
+  ROOT_PACKAGE_JSON_PATH,
   loadConfig,
   mergeMonorepoConfig,
   mergeSinglePackageConfig,
+  readRootPackageVersion,
   resolveWorkTypes
 };

package/dist/esm/parseCommitMessage.d.ts

@@ -1,3 +1,9 @@
-import type { ParsedCommit, WorkTypeConfig } from './types.ts';
+import type { Commit, ParsedCommit, WorkTypeConfig } from './types.ts';
 export declare const COMMIT_PREPROCESSOR_PATTERNS: readonly RegExp[];
-export declare function parseCommitMessage(message: string, hash: string, workTypes: Record<string, WorkTypeConfig>, scopeAliases?: Record<string, string>): ParsedCommit | undefined;
+export type PolicyViolationSurface = 'prefix' | 'body';
+export type PolicyViolationHandler = (commit: Commit, type: string, surface: PolicyViolationSurface) => void;
+export interface ParseCommitMessageOptions {
+    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    onPolicyViolation?: PolicyViolationHandler;
+}
+export declare function parseCommitMessage(message: string, hash: string, workTypes: Record<string, WorkTypeConfig>, scopeAliases?: Record<string, string>, options?: ParseCommitMessageOptions): ParsedCommit | undefined;

package/dist/esm/parseCommitMessage.js

@@ -1,6 +1,7 @@
 const COMMIT_PREPROCESSOR_PATTERNS = [/^##\s+/, /^#\d+([.-]\d+)?\s+/, /^[A-Z]+-\d+\s+/];
-function parseCommitMessage(message, hash, workTypes, scopeAliases) {
-  const stripped = stripTicketPrefix(message);
+function parseCommitMessage(message, hash, workTypes, scopeAliases, options) {
+  const firstLine = message.split("\n", 1)[0] ?? "";
+  const stripped = stripTicketPrefix(firstLine);
   const match = stripped.match(/^(?:([^|]+)\|)?(\w+)(?:\(([^)]+)\))?(!)?:\s*(.*)$/);
   if (!match) {
     return void 0;
@@ -17,7 +18,15 @@ function parseCommitMessage(message, hash, workTypes, scopeAliases) {
   if (resolvedType === void 0) {
     return void 0;
   }
-  const breaking = breakingMarker === "!" || message.includes("BREAKING CHANGE:");
+  const commit = { message, hash };
+  const breaking = evaluateBreakingPolicy({
+    commit,
+    resolvedType,
+    hasPrefixBreaking: breakingMarker === "!",
+    hasFooterBreaking: message.includes("BREAKING CHANGE:"),
+    policy: options?.breakingPolicies?.[resolvedType] ?? "optional",
+    onPolicyViolation: options?.onPolicyViolation
+  });
   const rawScope = pipeScope ?? parenthesizedScope;
   const resolvedScope = rawScope !== void 0 && scopeAliases !== void 0 ? scopeAliases[rawScope] ?? rawScope : rawScope;
   return {
@@ -29,6 +38,26 @@ function parseCommitMessage(message, hash, workTypes, scopeAliases) {
     ...resolvedScope !== void 0 && { scope: resolvedScope }
   };
 }
+function evaluateBreakingPolicy(inputs) {
+  const { commit, resolvedType, hasPrefixBreaking, hasFooterBreaking, policy, onPolicyViolation } = inputs;
+  if (policy === "forbidden") {
+    if (hasPrefixBreaking) {
+      onPolicyViolation?.(commit, resolvedType, "prefix");
+    }
+    if (hasFooterBreaking) {
+      onPolicyViolation?.(commit, resolvedType, "body");
+    }
+    return false;
+  }
+  if (policy === "required") {
+    if (!hasPrefixBreaking) {
+      onPolicyViolation?.(commit, resolvedType, "prefix");
+      return false;
+    }
+    return true;
+  }
+  return hasPrefixBreaking || hasFooterBreaking;
+}
 function resolveType(rawType, workTypes) {
   const lowered = rawType.toLowerCase();
   for (const [key, config] of Object.entries(workTypes)) {

package/dist/esm/prepareCommand.js

@@ -1,13 +1,16 @@
 import { parseArgs as coreParseArgs, translateParseError, writeFileWithCheck } from "@williamthorsen/nmr-core";
 import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
+import { buildDependencyGraph } from "./buildDependencyGraph.js";
 import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { discoverWorkspaces } from "./discoverWorkspaces.js";
 import { dim } from "./format.js";
-import { loadConfig, mergeMonorepoConfig, mergeSinglePackageConfig } from "./loadConfig.js";
+import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
+import { loadConfig, mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
 import { releasePrepare } from "./releasePrepare.js";
 import { releasePrepareMono } from "./releasePrepareMono.js";
 import { reportPrepare } from "./reportPrepare.js";
 import { validateConfig } from "./validateConfig.js";
+import { validateOnlyExcludesStrandedDependents } from "./validateOnlyExcludesStrandedDependents.js";
 const RELEASE_TAGS_FILE = "tmp/.release-tags";
 const RELEASE_SUMMARY_FILE = "tmp/.release-summary";
 const VALID_BUMP_TYPES = ["major", "minor", "patch"];
@@ -22,10 +25,14 @@ Usage: npx @williamthorsen/release-kit prepare [options]
 Options:
   --dry-run             Run without modifying any files
   --bump=major|minor|patch  Override the bump type for all workspaces
-  --set-version=X.Y.Z   Set an explicit version; bypasses commit-derived bumps. Requires --only in monorepo mode.
-  --force               Force a release even when there are no commits since the last tag (requires --bump)
+  --set-version=X.Y.Z   Set an explicit version; bypasses commit-derived bumps.
+                         Requires --only in monorepo mode (rejected when a 'project' block is configured).
+  --force               Release even when no commits or no bump-worthy commits exist
+                         since the last tag. Defaults to patch when --bump is not given;
+                         use --bump=X to release at a different level.
   --no-git-checks, -n   Skip the clean-working-tree check
-  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only)
+  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only;
+                         rejected when a 'project' block is configured)
   --with-release-notes  Also write per-workspace release-notes previews under {workspacePath}/docs/
                          (docs/README.v{version}.md and docs/RELEASE_NOTES.v{version}.md).
                          Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).
@@ -84,9 +91,6 @@ function parseArgs(argv) {
   if (setVersion !== void 0 && flags.force) {
     throw new Error("--set-version cannot be combined with --force");
   }
-  if (flags.force && bumpOverride === void 0) {
-    throw new Error("--force requires --bump to specify the version bump type");
-  }
   return {
     dryRun: flags.dryRun,
     force: flags.force,
@@ -157,17 +161,36 @@ function runSinglePackageMode(userConfig, options, only, dryRun) {
     console.error("Error: --only is only supported for monorepo configurations");
     process.exit(1);
   }
+  if (options.force && options.bumpOverride === void 0) {
+    console.error(
+      "Error: --force without --bump is only supported for monorepo configurations. Use --bump=major|minor|patch to set the level for a single-package release."
+    );
+    process.exit(1);
+  }
   const config = mergeSinglePackageConfig(userConfig);
   runAndReport(() => releasePrepare(config, options), dryRun);
 }
 function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion, dryRun) {
   let config;
   try {
-    config = mergeMonorepoConfig(discoveredPaths, userConfig);
+    const rootPackage = readRootPackageVersion();
+    config = mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage);
   } catch (error) {
     console.error(`Error resolving workspaces: ${error instanceof Error ? error.message : String(error)}`);
     process.exit(1);
   }
+  if (setVersion !== void 0 && config.project !== void 0) {
+    console.error(
+      "Error: --set-version cannot be combined with a project release. --set-version operates on a single workspace; a project release rolls up every contributing workspace. To use --set-version, run on a config without a `project` block."
+    );
+    process.exit(1);
+  }
+  if (only !== void 0 && config.project !== void 0) {
+    console.error(
+      "Error: --only cannot be combined with a project release. To release a single workspace, use a config without a `project` block, or run a full `prepare` (no --only) to include the project release."
+    );
+    process.exit(1);
+  }
   if (only !== void 0) {
     const knownNames = config.workspaces.map((w) => w.dir);
     for (const name of only) {
@@ -176,6 +199,25 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
         process.exit(1);
       }
     }
+    const graph = buildDependencyGraph(config.workspaces);
+    const violations = validateOnlyExcludesStrandedDependents(config.workspaces, only, graph, (workspace) => {
+      const tagPrefixes = [
+        workspace.tagPrefix,
+        ...workspace.legacyIdentities?.map((identity) => identity.tagPrefix) ?? []
+      ];
+      const result = getCommitsSinceTarget(tagPrefixes, workspace.paths);
+      return { has: result.commits.length > 0, tag: result.tag };
+    });
+    if (violations !== void 0) {
+      console.error("Error: --only excludes packages with changes that would be stranded by the release.");
+      console.error("The following packages must be added to --only or have their dependencies removed:");
+      for (const violation of violations) {
+        const since = violation.tag ?? "the beginning";
+        console.error(`  - ${violation.dir} (downstream of ${violation.downstreamOf}; has commits since ${since})`);
+      }
+      console.error("Alternatively, run `release-kit prepare` without --only to release everything.");
+      process.exit(1);
+    }
     config.workspaces = config.workspaces.filter((w) => only.includes(w.dir));
   }
   if (setVersion !== void 0) {
@@ -221,7 +263,7 @@ function runAndReport(execute, dryRun) {
   try {
     result = execute();
   } catch (error) {
-    console.error("Error preparing release:", error instanceof Error ? error.message : String(error));
+    console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
   }
   process.stdout.write(reportPrepare(result) + "\n");

package/dist/esm/publish.d.ts

@@ -2,7 +2,6 @@ import type { PackageManager } from './detectPackageManager.ts';
 import type { ResolvedTag } from './resolveReleaseTags.ts';
 export interface PublishOptions {
     dryRun: boolean;
-    noGitChecks: boolean;
     provenance: boolean;
 }
 export declare function publishPackage(resolvedTag: ResolvedTag, packageManager: PackageManager, options: PublishOptions): void;

package/dist/esm/publish.js

@@ -1,8 +1,8 @@
 import { execFileSync } from "node:child_process";
 function publishPackage(resolvedTag, packageManager, options) {
-  const { dryRun, noGitChecks, provenance } = options;
+  const { dryRun, provenance } = options;
   const executable = resolveExecutable(packageManager);
-  const args = buildPublishArgs(packageManager, { dryRun, noGitChecks, provenance });
+  const args = buildPublishArgs(packageManager, { dryRun, provenance });
   console.info(
     `
 ${dryRun ? "[dry-run] " : ""}Running: ${executable} ${args.join(" ")} (cwd: ${resolvedTag.workspacePath})`
@@ -20,7 +20,7 @@ function buildPublishArgs(packageManager, options) {
   if (options.dryRun) {
     args.push("--dry-run");
   }
-  if (options.noGitChecks && packageManager === "pnpm") {
+  if (packageManager === "pnpm") {
     args.push("--no-git-checks");
   }
   if (options.provenance && packageManager !== "yarn") {

package/dist/esm/publishCommand.js

@@ -1,6 +1,7 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseArgs, translateParseError } from "@williamthorsen/nmr-core";
+import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
 import { detectPackageManager } from "./detectPackageManager.js";
 import { injectReleaseNotesIntoReadme, resolveReadmePath } from "./injectReleaseNotesIntoReadme.js";
 import { parseRequestedTags } from "./parseRequestedTags.js";
@@ -22,21 +23,34 @@ async function publishCommand(argv) {
     process.exit(1);
   }
   const { dryRun, noGitChecks, provenance } = parsed.flags;
+  if (!dryRun && !noGitChecks) {
+    try {
+      assertCleanWorkingTree();
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+  }
   const requestedTags = parseRequestedTags(parsed.flags.tags);
   const resolvedTags = await resolveCommandTags(requestedTags);
   if (resolvedTags.length === 0) {
     return;
   }
+  const publishableTags = filterPublishableTags(resolvedTags, requestedTags !== void 0);
+  if (publishableTags.length === 0) {
+    console.info("Nothing to publish.");
+    return;
+  }
   const packageManager = detectPackageManager();
   const { releaseNotes, changelogJsonOutputPath, sectionOrder } = await resolveReleaseNotesConfig();
   const shouldInject = releaseNotes.shouldInjectIntoReadme;
   console.info(dryRun ? "[dry-run] Would publish:" : "Publishing:");
-  for (const { tag, workspacePath } of resolvedTags) {
+  for (const { tag, workspacePath } of publishableTags) {
     console.info(`  ${tag} (${workspacePath})`);
   }
   const published = [];
   try {
-    for (const resolvedTag of resolvedTags) {
+    for (const resolvedTag of publishableTags) {
       let readmePath;
       let originalReadme;
       if (shouldInject) {
@@ -51,7 +65,7 @@ async function publishCommand(argv) {
         }
       }
       try {
-        publishPackage(resolvedTag, packageManager, { dryRun, noGitChecks, provenance });
+        publishPackage(resolvedTag, packageManager, { dryRun, provenance });
         published.push(resolvedTag.tag);
       } finally {
         if (readmePath !== void 0 && originalReadme !== void 0) {
@@ -70,6 +84,20 @@ async function publishCommand(argv) {
     process.exit(1);
   }
 }
+function filterPublishableTags(resolvedTags, isExplicit) {
+  const publishable = [];
+  const unpublishable = [];
+  for (const tag of resolvedTags) {
+    (tag.isPublishable ? publishable : unpublishable).push(tag);
+  }
+  if (isExplicit && unpublishable.length > 0) {
+    for (const { tag, workspacePath } of unpublishable) {
+      console.error(`Error: ${tag} (${workspacePath}) cannot be published: package.json#private is true.`);
+    }
+    process.exit(1);
+  }
+  return publishable;
+}
 export {
   publishCommand
 };