@williamthorsen/release-kit 5.0.0 → 5.2.0

package/dist/esm/types.d.ts

@@ -3,6 +3,7 @@ export type ChangelogAudience = 'all' | 'dev';
 export interface ChangelogItem {
     description: string;
     body?: string;
+    breaking?: boolean;
 }
 export interface ChangelogSection {
     title: string;
@@ -22,6 +23,12 @@ export interface ChangelogJsonConfig {
 export interface ReleaseNotesConfig {
     shouldInjectIntoReadme: boolean;
 }
+export interface ProjectConfig {
+    tagPrefix?: string;
+}
+export interface ResolvedProjectConfig {
+    tagPrefix: string;
+}
 export interface PropagationSource {
     packageName: string;
     newVersion: string;
@@ -31,24 +38,68 @@ export interface BumpResult {
     newVersion: string;
     files: string[];
 }
-export interface WorkspacePrepareResult {
-    name?: string | undefined;
-    status: 'released' | 'skipped';
-    previousTag?: string | undefined;
+export interface PolicyViolation {
+    commitHash: string;
+    commitSubject: string;
+    type: string;
+    surface: 'prefix' | 'body';
+}
+export interface ReleasedWorkspaceResult {
+    status: 'released';
+    name?: string;
+    previousTag?: string;
     commitCount: number;
-    parsedCommitCount?: number | undefined;
-    releaseType?: ReleaseType | undefined;
-    currentVersion?: string | undefined;
-    newVersion?: string | undefined;
-    tag?: string | undefined;
+    parsedCommitCount?: number;
+    unparseableCommits?: Commit[];
+    policyViolations?: PolicyViolation[];
+    releaseType?: ReleaseType;
+    currentVersion: string;
+    newVersion: string;
+    tag: string;
     bumpedFiles: string[];
     changelogFiles: string[];
-    commits?: Commit[] | undefined;
-    unparseableCommits?: Commit[] | undefined;
-    propagatedFrom?: PropagationSource[] | undefined;
-    skipReason?: string | undefined;
-    setVersion?: string | undefined;
+    commits?: Commit[];
+    bumpOverride?: ReleaseType;
+    propagatedFrom?: PropagationSource[];
+    setVersion?: string;
+}
+export interface SkippedWorkspaceResult {
+    status: 'skipped';
+    name?: string;
+    previousTag?: string;
+    commitCount: number;
+    parsedCommitCount?: number;
+    unparseableCommits?: Commit[];
+    policyViolations?: PolicyViolation[];
+    skipReason: string;
+}
+export type WorkspacePrepareResult = ReleasedWorkspaceResult | SkippedWorkspaceResult;
+export interface ReleasedProjectResult {
+    status: 'released';
+    previousTag?: string;
+    commitCount: number;
+    parsedCommitCount: number;
+    unparseableCommits?: Commit[];
+    policyViolations?: PolicyViolation[];
+    releaseType: ReleaseType;
+    currentVersion: string;
+    newVersion: string;
+    tag: string;
+    bumpedFiles: string[];
+    changelogFiles: string[];
+    commits: Commit[];
+    bumpOverride?: ReleaseType;
+}
+export interface SkippedProjectResult {
+    status: 'skipped';
+    previousTag?: string;
+    commitCount: number;
+    parsedCommitCount: number;
+    unparseableCommits?: Commit[];
+    policyViolations?: PolicyViolation[];
+    skipReason: string;
 }
+export type ProjectPrepareResult = ReleasedProjectResult | SkippedProjectResult;
 export interface PrepareResult {
     workspaces: WorkspacePrepareResult[];
     tags: string[];
@@ -59,6 +110,7 @@ export interface PrepareResult {
     } | undefined;
     dryRun: boolean;
     warnings?: string[] | undefined;
+    project?: ProjectPrepareResult | undefined;
 }
 export interface WorkTypeConfig {
     header: string;
@@ -72,12 +124,14 @@ export interface ReleaseKitConfig {
     workspaces?: WorkspaceOverride[];
     versionPatterns?: VersionPatterns;
     workTypes?: Record<string, WorkTypeConfig>;
+    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
     formatCommand?: string;
     cliffConfigPath?: string;
     scopeAliases?: Record<string, string>;
     changelogJson?: Partial<ChangelogJsonConfig>;
     releaseNotes?: Partial<ReleaseNotesConfig>;
     retiredPackages?: RetiredPackage[];
+    project?: ProjectConfig;
 }
 export interface LegacyIdentity {
     name: string;
@@ -110,6 +164,7 @@ export interface WorkspaceConfig {
     name: string;
     tagPrefix: string;
     workspacePath: string;
+    isPublishable: boolean;
     packageFiles: string[];
     changelogPaths: string[];
     paths: string[];
@@ -119,11 +174,13 @@ export interface MonorepoReleaseConfig {
     workspaces: WorkspaceConfig[];
     workTypes?: Record<string, WorkTypeConfig>;
     versionPatterns?: VersionPatterns;
+    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
     formatCommand?: string;
     cliffConfigPath?: string;
     scopeAliases?: Record<string, string>;
     changelogJson: ChangelogJsonConfig;
     releaseNotes: ReleaseNotesConfig;
+    project?: ResolvedProjectConfig;
 }
 export interface ReleaseConfig {
     tagPrefix: string;
@@ -131,6 +188,7 @@ export interface ReleaseConfig {
     changelogPaths: string[];
     workTypes?: Record<string, WorkTypeConfig>;
     versionPatterns?: VersionPatterns;
+    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
     formatCommand?: string;
     cliffConfigPath?: string;
     scopeAliases?: Record<string, string>;

package/dist/esm/validateConfig.js

@@ -9,6 +9,7 @@ function validateConfig(raw) {
     "changelogJson",
     "cliffConfigPath",
     "formatCommand",
+    "project",
     "releaseNotes",
     "retiredPackages",
     "scopeAliases",
@@ -30,6 +31,7 @@ function validateConfig(raw) {
   validateStringField("cliffConfigPath", raw.cliffConfigPath, config, errors);
   validateScopeAliases(raw.scopeAliases, config, errors);
   validateRetiredPackages(raw.retiredPackages, config, errors);
+  validateProjectConfig(raw.project, config, errors);
   const warnings = [];
   const changelogJsonEnabled = config.changelogJson?.enabled ?? true;
   if (!changelogJsonEnabled && config.releaseNotes?.shouldInjectIntoReadme) {
@@ -75,6 +77,30 @@ function validateChangelogJson(value, config, errors) {
   }
   config.changelogJson = result;
 }
+function validateProjectConfig(value, config, errors) {
+  if (value === void 0) return;
+  if (!isRecord(value)) {
+    errors.push("'project' must be an object");
+    return;
+  }
+  const knownProjectFields = /* @__PURE__ */ new Set(["tagPrefix"]);
+  for (const key of Object.keys(value)) {
+    if (!knownProjectFields.has(key)) {
+      errors.push(`project: unknown field '${key}'`);
+    }
+  }
+  const result = {};
+  if (value.tagPrefix !== void 0) {
+    if (typeof value.tagPrefix !== "string") {
+      errors.push("project.tagPrefix: must be a string");
+    } else if (value.tagPrefix === "") {
+      errors.push("project.tagPrefix: must be a non-empty string");
+    } else {
+      result.tagPrefix = value.tagPrefix;
+    }
+  }
+  config.project = result;
+}
 function validateReleaseNotes(value, config, errors) {
   if (value === void 0) return;
   if (!isRecord(value)) {

package/dist/esm/validateOnlyExcludesStrandedDependents.d.ts

@@ -0,0 +1,14 @@
+import type { DependencyGraph } from './buildDependencyGraph.ts';
+import type { WorkspaceConfig } from './types.ts';
+export interface CommitsProbeResult {
+    has: boolean;
+    tag: string | undefined;
+}
+export interface StrandedDependentViolation {
+    dir: string;
+    downstreamOf: string;
+    tag: string | undefined;
+}
+type CommitsProbe = (workspace: WorkspaceConfig) => CommitsProbeResult;
+export declare function validateOnlyExcludesStrandedDependents(workspaces: readonly WorkspaceConfig[], only: readonly string[], graph: DependencyGraph, hasCommits: CommitsProbe): StrandedDependentViolation[] | undefined;
+export {};

package/dist/esm/validateOnlyExcludesStrandedDependents.js

@@ -0,0 +1,109 @@
+function validateOnlyExcludesStrandedDependents(workspaces, only, graph, hasCommits) {
+  const probeCommits = memoizeCommitsProbe(hasCommits);
+  const workspaceByDir = new Map(workspaces.map((w) => [w.dir, w]));
+  const released = computeReleasedSet(only, workspaceByDir, graph, probeCommits);
+  const violations = collectStrandedViolations(released, new Set(only), graph, probeCommits);
+  if (violations.length === 0) return void 0;
+  violations.sort((a, b) => a.dir.localeCompare(b.dir));
+  return violations;
+}
+function memoizeCommitsProbe(probe) {
+  const cache = /* @__PURE__ */ new Map();
+  return (workspace) => {
+    const cached = cache.get(workspace.dir);
+    if (cached !== void 0) return cached;
+    const result = probe(workspace);
+    cache.set(workspace.dir, result);
+    return result;
+  };
+}
+function computeReleasedSet(only, workspaceByDir, graph, probeCommits) {
+  const released = /* @__PURE__ */ new Set();
+  for (const dir of only) {
+    const workspace = workspaceByDir.get(dir);
+    if (workspace !== void 0 && probeCommits(workspace).has) {
+      released.add(dir);
+    }
+  }
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const dir of only) {
+      if (released.has(dir)) continue;
+      if (hasDependencyIn(dir, graph, released)) {
+        released.add(dir);
+        changed = true;
+      }
+    }
+  }
+  return released;
+}
+function hasDependencyIn(dir, graph, released) {
+  const forwardDeps = graph.dependenciesOf.get(dir);
+  if (forwardDeps === void 0) return false;
+  for (const depPackageName of forwardDeps) {
+    const depDir = graph.packageNameToDir.get(depPackageName);
+    if (depDir !== void 0 && released.has(depDir)) return true;
+  }
+  return false;
+}
+function collectStrandedViolations(released, onlySet, graph, probeCommits) {
+  const violations = [];
+  const violationDirs = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [];
+  for (const dir of released) {
+    const packageName = graph.dirToPackageName.get(dir);
+    if (packageName !== void 0) {
+      queue.push({ packageName, attributionRoot: dir });
+    }
+  }
+  while (queue.length > 0) {
+    const item = queue.shift();
+    if (item === void 0) break;
+    if (visited.has(item.packageName)) continue;
+    visited.add(item.packageName);
+    const dependents = graph.dependentsOf.get(item.packageName);
+    if (dependents === void 0) continue;
+    for (const dependent of dependents) {
+      visitDependent(dependent, item.attributionRoot, {
+        released,
+        onlySet,
+        graph,
+        probeCommits,
+        queue,
+        violations,
+        violationDirs
+      });
+    }
+  }
+  return violations;
+}
+function visitDependent(dependent, attributionRoot, ctx) {
+  if (ctx.onlySet.has(dependent.dir)) {
+    if (ctx.released.has(dependent.dir)) {
+      enqueueDependent(dependent, ctx);
+    }
+    return;
+  }
+  const probe = ctx.probeCommits(dependent);
+  if (!probe.has) return;
+  if (!ctx.violationDirs.has(dependent.dir)) {
+    ctx.violationDirs.add(dependent.dir);
+    ctx.violations.push({
+      dir: dependent.dir,
+      downstreamOf: attributionRoot,
+      tag: probe.tag
+    });
+  }
+  enqueueDependent(dependent, ctx);
+}
+function enqueueDependent(dependent, ctx) {
+  const packageName = ctx.graph.dirToPackageName.get(dependent.dir);
+  if (packageName !== void 0) {
+    ctx.queue.push({ packageName, attributionRoot: dependent.dir });
+  }
+}
+export {
+  validateOnlyExcludesStrandedDependents
+};

package/dist/esm/work-types.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "./work-types.schema.json",
+  "tiers": ["Public", "Internal", "Process"],
+  "types": [
+    {
+      "tier": "Public",
+      "key": "feat",
+      "aliases": ["feature"],
+      "emoji": "🎉",
+      "label": "Features",
+      "breakingPolicy": "optional"
+    },
+    {
+      "tier": "Public",
+      "key": "drop",
+      "aliases": [],
+      "emoji": "🪦",
+      "label": "Removed",
+      "breakingPolicy": "required"
+    },
+    {
+      "tier": "Public",
+      "key": "deprecate",
+      "aliases": [],
+      "emoji": "🗑️",
+      "label": "Deprecated",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Public",
+      "key": "fix",
+      "aliases": ["bugfix"],
+      "emoji": "🐛",
+      "label": "Bug fixes",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Public",
+      "key": "sec",
+      "aliases": ["security"],
+      "emoji": "🔒",
+      "label": "Security",
+      "breakingPolicy": "optional"
+    },
+    {
+      "tier": "Public",
+      "key": "perf",
+      "aliases": ["performance"],
+      "emoji": "⚡",
+      "label": "Performance",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Internal",
+      "key": "internal",
+      "aliases": ["utility"],
+      "emoji": "🏗️",
+      "label": "Internal features",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Internal",
+      "key": "refactor",
+      "aliases": [],
+      "emoji": "♻️",
+      "label": "Refactoring",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Internal",
+      "key": "tests",
+      "aliases": ["test"],
+      "emoji": "🧪",
+      "label": "Tests",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Process",
+      "key": "tooling",
+      "aliases": [],
+      "emoji": "⚙️",
+      "label": "Tooling",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Process",
+      "key": "ci",
+      "aliases": [],
+      "emoji": "👷",
+      "label": "CI",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Process",
+      "key": "deps",
+      "aliases": ["dep"],
+      "emoji": "📦",
+      "label": "Dependencies",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Process",
+      "key": "ai",
+      "aliases": [],
+      "emoji": "🤖",
+      "label": "Agentic support",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Process",
+      "key": "docs",
+      "aliases": ["doc"],
+      "emoji": "📚",
+      "label": "Documentation",
+      "breakingPolicy": "forbidden"
+    },
+    {
+      "tier": "Process",
+      "key": "fmt",
+      "aliases": [],
+      "emoji": "🎨",
+      "label": "Formatting",
+      "breakingPolicy": "forbidden",
+      "excludedFromChangelog": true
+    }
+  ]
+}

package/dist/esm/work-types.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/williamthorsen/node-monorepo-tools/raw/main/packages/release-kit/src/work-types.schema.json",
+  "title": "Work types",
+  "description": "Canonical taxonomy of commit work types used by release-kit. Drives section ordering, audience classification, and the `!` (breaking) policy. The structured single-source-of-truth for everything that previously lived in `DEFAULT_WORK_TYPES` and `cliff.toml.template` group definitions.",
+  "type": "object",
+  "required": ["tiers", "types"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional reference to this schema for IDE validation."
+    },
+    "tiers": {
+      "type": "array",
+      "description": "Render tiers in canonical order. Each entry's `tier` field must reference one of these names.",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "types": {
+      "type": "array",
+      "description": "Work-type entries in canonical render order (tier order, then row order within tier).",
+      "items": { "$ref": "#/definitions/workType" },
+      "minItems": 1
+    }
+  },
+  "definitions": {
+    "workType": {
+      "type": "object",
+      "required": ["tier", "key", "aliases", "emoji", "label", "breakingPolicy"],
+      "additionalProperties": false,
+      "properties": {
+        "tier": {
+          "type": "string",
+          "description": "Render tier this entry belongs to. Must match one of the names in the top-level `tiers` array."
+        },
+        "key": {
+          "type": "string",
+          "description": "Canonical work-type identifier (e.g. `feat`, `fix`). Must be globally unique across all entries.",
+          "minLength": 1,
+          "pattern": "^[a-z][a-z0-9]*$"
+        },
+        "aliases": {
+          "type": "array",
+          "description": "Alternate identifiers that resolve to this work type. Must be globally unique and not collide with any `key`.",
+          "items": { "type": "string", "minLength": 1, "pattern": "^[a-z][a-z0-9]*$" },
+          "uniqueItems": true
+        },
+        "emoji": {
+          "type": "string",
+          "description": "Decorative emoji rendered as the prefix of the section heading.",
+          "minLength": 1
+        },
+        "label": {
+          "type": "string",
+          "description": "Human-readable section label (rendered as `${emoji} ${label}` in changelogs and release notes).",
+          "minLength": 1
+        },
+        "breakingPolicy": {
+          "type": "string",
+          "description": "Policy governing the `!` (breaking) marker for this type. `forbidden`: `!` is a policy violation. `optional`: `!` is allowed. `required`: bare type is a policy violation; only the `!` form is accepted.",
+          "enum": ["forbidden", "optional", "required"]
+        },
+        "excludedFromChangelog": {
+          "type": "boolean",
+          "description": "When `true`, this type's commits never appear in any changelog or release note. Currently only `fmt` sets this. Default: `false`.",
+          "default": false
+        }
+      }
+    }
+  }
+}

package/dist/esm/workTypesData.d.ts

@@ -0,0 +1,14 @@
+export interface WorkTypeEntry {
+    tier: string;
+    key: string;
+    aliases: string[];
+    emoji: string;
+    label: string;
+    breakingPolicy: 'forbidden' | 'optional' | 'required';
+    excludedFromChangelog?: boolean;
+}
+export interface WorkTypesData {
+    tiers: string[];
+    types: WorkTypeEntry[];
+}
+export declare const WORK_TYPES_DATA: WorkTypesData;

package/dist/esm/workTypesData.js

@@ -0,0 +1,59 @@
+const WORK_TYPES_DATA = {
+  tiers: ["Public", "Internal", "Process"],
+  types: [
+    { tier: "Public", key: "feat", aliases: ["feature"], emoji: "\u{1F389}", label: "Features", breakingPolicy: "optional" },
+    { tier: "Public", key: "drop", aliases: [], emoji: "\u{1FAA6}", label: "Removed", breakingPolicy: "required" },
+    { tier: "Public", key: "deprecate", aliases: [], emoji: "\u{1F5D1}\uFE0F", label: "Deprecated", breakingPolicy: "forbidden" },
+    { tier: "Public", key: "fix", aliases: ["bugfix"], emoji: "\u{1F41B}", label: "Bug fixes", breakingPolicy: "forbidden" },
+    { tier: "Public", key: "sec", aliases: ["security"], emoji: "\u{1F512}", label: "Security", breakingPolicy: "optional" },
+    {
+      tier: "Public",
+      key: "perf",
+      aliases: ["performance"],
+      emoji: "\u26A1",
+      label: "Performance",
+      breakingPolicy: "forbidden"
+    },
+    {
+      tier: "Internal",
+      key: "internal",
+      aliases: ["utility"],
+      emoji: "\u{1F3D7}\uFE0F",
+      label: "Internal features",
+      breakingPolicy: "forbidden"
+    },
+    {
+      tier: "Internal",
+      key: "refactor",
+      aliases: [],
+      emoji: "\u267B\uFE0F",
+      label: "Refactoring",
+      breakingPolicy: "forbidden"
+    },
+    { tier: "Internal", key: "tests", aliases: ["test"], emoji: "\u{1F9EA}", label: "Tests", breakingPolicy: "forbidden" },
+    { tier: "Process", key: "tooling", aliases: [], emoji: "\u2699\uFE0F", label: "Tooling", breakingPolicy: "forbidden" },
+    { tier: "Process", key: "ci", aliases: [], emoji: "\u{1F477}", label: "CI", breakingPolicy: "forbidden" },
+    { tier: "Process", key: "deps", aliases: ["dep"], emoji: "\u{1F4E6}", label: "Dependencies", breakingPolicy: "forbidden" },
+    { tier: "Process", key: "ai", aliases: [], emoji: "\u{1F916}", label: "Agentic support", breakingPolicy: "forbidden" },
+    {
+      tier: "Process",
+      key: "docs",
+      aliases: ["doc"],
+      emoji: "\u{1F4DA}",
+      label: "Documentation",
+      breakingPolicy: "forbidden"
+    },
+    {
+      tier: "Process",
+      key: "fmt",
+      aliases: [],
+      emoji: "\u{1F3A8}",
+      label: "Formatting",
+      breakingPolicy: "forbidden",
+      excludedFromChangelog: true
+    }
+  ]
+};
+export {
+  WORK_TYPES_DATA
+};

package/dist/esm/workTypesUtils.d.ts

@@ -0,0 +1,5 @@
+export declare function hasExpectedTopLevelShape(value: unknown): value is {
+    tiers: unknown[];
+    types: unknown[];
+};
+export declare function errorMessage(error: unknown): string;

package/dist/esm/workTypesUtils.js

@@ -0,0 +1,16 @@
+function hasExpectedTopLevelShape(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  if (!("tiers" in value) || !("types" in value)) {
+    return false;
+  }
+  return Array.isArray(value.tiers) && Array.isArray(value.types);
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  errorMessage,
+  hasExpectedTopLevelShape
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [],
   "homepage": "https://github.com/williamthorsen/node-monorepo-tools/tree/main/packages/release-kit#readme",
@@ -28,6 +28,7 @@
     "dist/*",
     "cliff.toml.template",
     "presets/**",
+    "schemas/**",
     "CHANGELOG.md"
   ],
   "dependencies": {
@@ -35,10 +36,12 @@
     "jiti": "2.6.1",
     "js-yaml": "4.1.1",
     "json-stringify-pretty-compact": "4.0.0",
-    "@williamthorsen/nmr-core": "0.3.0"
+    "semver": "7.7.4",
+    "@williamthorsen/nmr-core": "0.3.1"
   },
   "devDependencies": {
     "@types/js-yaml": "4.0.9",
+    "@types/semver": "7.7.1",
     "smol-toml": "1.6.1"
   },
   "engines": {
@@ -49,9 +52,12 @@
     "registry": "https://registry.npmjs.org"
   },
   "scripts": {
+    "build:post": "node scripts/copy-work-types.js",
     "test": "pnpm exec vitest --config=vitest.standalone.config.ts",
     "test:coverage": "pnpm exec vitest --config=vitest.standalone.config.ts --coverage",
     "test:integration": "pnpm exec vitest --config=vitest.integration.config.ts",
-    "test:watch": "pnpm exec vitest --config=vitest.standalone.config.ts --watch"
+    "test:watch": "pnpm exec vitest --config=vitest.standalone.config.ts --watch",
+    "work-types:check": "pnpm exec release-kit work-types check",
+    "work-types:sync": "pnpm exec release-kit work-types sync"
   }
 }