feat: breaking schema change detection with governance webhooks

.changeset/breaking-schema-detection.md

@@ -0,0 +1,8 @@
+---
+"@eventcatalog/breaking-changes": minor
+"@eventcatalog/cli": minor
+---
+
+feat: add breaking schema change detection with governance webhooks
+
+New `schema_breaking_change` governance trigger that detects breaking JSON Schema changes per compatibility strategy (BACKWARD, FORWARD, FULL, NONE). Users configure `compatibility.strategy` in governance.yaml and subscribe to breaking change webhooks with detailed diff information.

.gitignore

@@ -69,4 +69,5 @@ PERFORMANCE-ANALYSIS.md
 
 
 .agents/skills/copy*
-ec-test/
+ec-test/
+.worktrees/

packages/breaking-changes/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@eventcatalog/breaking-changes",
+  "version": "0.1.0",
+  "description": "Breaking schema change detection for EventCatalog",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:bin": "tsup",
+    "test": "vitest --run",
+    "test:ci": "vitest --run",
+    "format": "prettier --write .",
+    "format:diff": "prettier --list-different ."
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "prettier": "^3.3.3",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.3",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog"
+  }
+}

packages/breaking-changes/src/index.ts

@@ -0,0 +1,9 @@
+export type {
+  CompatibilityStrategy,
+  SchemaChange,
+  BreakingChange,
+  SchemaChangeType,
+} from "./types";
+
+export { detectBreakingChanges } from "./json-schema/rules";
+export { diffJsonSchemas } from "./json-schema/differ";

packages/breaking-changes/src/json-schema/differ.ts

@@ -0,0 +1,122 @@
+import type { SchemaChange } from "../types";
+
+type JsonSchemaObject = {
+  type?: string;
+  properties?: Record<string, JsonSchemaObject>;
+  required?: string[];
+  [key: string]: any;
+};
+
+const hasProperties = (schema: JsonSchemaObject): boolean =>
+  !!(schema.properties || schema.required);
+
+export const diffJsonSchemas = (
+  before: JsonSchemaObject,
+  after: JsonSchemaObject,
+): SchemaChange[] => {
+  const changes: SchemaChange[] = [];
+
+  // Detect root-level type changes
+  if (before.type && after.type && before.type !== after.type) {
+    changes.push({
+      type: "TYPE_CHANGED",
+      field: "(root)",
+      message: `Root type changed from '${before.type}' to '${after.type}'`,
+      previousType: before.type,
+      currentType: after.type,
+    });
+  }
+
+  compareProperties(before, after, "", changes);
+  return changes;
+};
+
+const compareProperties = (
+  before: JsonSchemaObject,
+  after: JsonSchemaObject,
+  prefix: string,
+  changes: SchemaChange[],
+): void => {
+  const beforeProps = before.properties || {};
+  const afterProps = after.properties || {};
+  const beforeRequired = new Set(before.required || []);
+  const afterRequired = new Set(after.required || []);
+
+  const allFields = new Set([
+    ...Object.keys(beforeProps),
+    ...Object.keys(afterProps),
+  ]);
+
+  for (const field of allFields) {
+    const fullPath = prefix ? `${prefix}.${field}` : field;
+    const inBefore = field in beforeProps;
+    const inAfter = field in afterProps;
+
+    if (!inBefore && inAfter) {
+      const isRequired = afterRequired.has(field);
+      changes.push({
+        type: isRequired ? "FIELD_ADDED_REQUIRED" : "FIELD_ADDED_OPTIONAL",
+        field: fullPath,
+        message: `${isRequired ? "Required" : "Optional"} field '${fullPath}' was added`,
+      });
+      continue;
+    }
+
+    if (inBefore && !inAfter) {
+      const wasRequired = beforeRequired.has(field);
+      changes.push({
+        type: wasRequired ? "FIELD_REMOVED_REQUIRED" : "FIELD_REMOVED_OPTIONAL",
+        field: fullPath,
+        message: `${wasRequired ? "Required" : "Optional"} field '${fullPath}' was removed`,
+      });
+      continue;
+    }
+
+    // Field exists in both — check type
+    const beforeType = beforeProps[field].type;
+    const afterType = afterProps[field].type;
+
+    if (beforeType && afterType && beforeType !== afterType) {
+      changes.push({
+        type: "TYPE_CHANGED",
+        field: fullPath,
+        message: `Field '${fullPath}' type changed from '${beforeType}' to '${afterType}'`,
+        previousType: beforeType,
+        currentType: afterType,
+      });
+    }
+
+    // Check required status change
+    const wasPreviouslyRequired = beforeRequired.has(field);
+    const isNowRequired = afterRequired.has(field);
+
+    if (!wasPreviouslyRequired && isNowRequired) {
+      changes.push({
+        type: "REQUIRED_ADDED",
+        field: fullPath,
+        message: `Field '${fullPath}' was made required`,
+      });
+    } else if (wasPreviouslyRequired && !isNowRequired) {
+      changes.push({
+        type: "REQUIRED_REMOVED",
+        field: fullPath,
+        message: `Field '${fullPath}' was made optional`,
+      });
+    }
+
+    // Recurse into nested objects (explicit type or implicit via properties/required)
+    if (
+      beforeProps[field].type === "object" ||
+      afterProps[field].type === "object" ||
+      hasProperties(beforeProps[field]) ||
+      hasProperties(afterProps[field])
+    ) {
+      compareProperties(
+        beforeProps[field],
+        afterProps[field],
+        fullPath,
+        changes,
+      );
+    }
+  }
+};

packages/breaking-changes/src/json-schema/rules.ts

@@ -0,0 +1,44 @@
+import type {
+  CompatibilityStrategy,
+  SchemaChange,
+  BreakingChange,
+  SchemaChangeType,
+} from "../types";
+import { diffJsonSchemas } from "./differ";
+
+const BREAKING_RULES: Record<CompatibilityStrategy, Set<SchemaChangeType>> = {
+  BACKWARD: new Set([
+    "FIELD_ADDED_REQUIRED",
+    "FIELD_REMOVED_REQUIRED",
+    "TYPE_CHANGED",
+    "REQUIRED_ADDED",
+  ]),
+  FORWARD: new Set([
+    "FIELD_ADDED_REQUIRED",
+    "FIELD_REMOVED_REQUIRED",
+    "TYPE_CHANGED",
+    "REQUIRED_ADDED",
+  ]),
+  FULL: new Set([
+    "FIELD_ADDED_REQUIRED",
+    "FIELD_REMOVED_REQUIRED",
+    "TYPE_CHANGED",
+    "REQUIRED_ADDED",
+  ]),
+  NONE: new Set(),
+};
+
+export const detectBreakingChanges = (
+  before: object,
+  after: object,
+  strategy: CompatibilityStrategy,
+): BreakingChange[] => {
+  if (strategy === "NONE") return [];
+
+  const changes = diffJsonSchemas(before, after);
+  const breakingTypes = BREAKING_RULES[strategy];
+
+  return changes
+    .filter((change) => breakingTypes.has(change.type))
+    .map((change) => ({ ...change, breaking: true as const }));
+};

packages/breaking-changes/src/test/index.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from "vitest";
+import { detectBreakingChanges, diffJsonSchemas } from "../index";
+
+describe("public API", () => {
+  it("detectBreakingChanges returns breaking changes for a real schema evolution", () => {
+    const v1 = {
+      type: "object",
+      properties: {
+        orderId: { type: "string" },
+        amount: { type: "string" },
+        currency: { type: "string" },
+      },
+      required: ["orderId", "amount"],
+    };
+
+    const v2 = {
+      type: "object",
+      properties: {
+        orderId: { type: "string" },
+        amount: { type: "number" },
+        currency: { type: "string" },
+        region: { type: "string" },
+      },
+      required: ["orderId", "amount", "region"],
+    };
+
+    const result = detectBreakingChanges(v1, v2, "BACKWARD");
+
+    expect(result).toContainEqual(
+      expect.objectContaining({
+        type: "TYPE_CHANGED",
+        field: "amount",
+        breaking: true,
+      }),
+    );
+    expect(result).toContainEqual(
+      expect.objectContaining({
+        type: "FIELD_ADDED_REQUIRED",
+        field: "region",
+        breaking: true,
+      }),
+    );
+    expect(result).toHaveLength(2);
+  });
+
+  it("diffJsonSchemas is exported and returns all changes", () => {
+    const before = {
+      type: "object",
+      properties: { name: { type: "string" } },
+    };
+    const after = {
+      type: "object",
+      properties: { name: { type: "number" } },
+    };
+
+    const changes = diffJsonSchemas(before, after);
+    expect(changes).toHaveLength(1);
+    expect(changes[0].type).toBe("TYPE_CHANGED");
+  });
+
+  it("NONE strategy always returns empty", () => {
+    const result = detectBreakingChanges(
+      {
+        type: "object",
+        properties: { a: { type: "string" } },
+        required: ["a"],
+      },
+      { type: "object" },
+      "NONE",
+    );
+    expect(result).toEqual([]);
+  });
+});