@eventcatalog/diff 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,244 @@
+import { IndexResourceType, EdgeDirection, Index } from '@eventcatalog/sdk';
+export { EdgeDirection, Index, IndexResource, IndexResourceType, IndexSchema } from '@eventcatalog/sdk';
+
+/**
+ * ArchitectureDiff
+ *
+ * The single versioned document produced by `diff(a, b)`. Consumers (CI actions,
+ * policy engines, notifiers, UIs) build on top of this and never re-walk the graph.
+ *
+ * Input is the SDK `Index` returned by `buildIndex()`. Vocabulary follows the SDK:
+ * resources have a `type`, edges have a `direction`.
+ */
+
+declare const ARCHITECTURE_DIFF_SCHEMA_VERSION: 1;
+type CompatibilityStrategy = 'backward' | 'forward' | 'full' | 'none';
+/** Which side a breaking change hurts. `both` only occurs under the `full` strategy. */
+type BreakingDirection = 'backward' | 'forward' | 'both';
+/** Resource types that carry schemas and travel along sends/receives edges. */
+type MessageType = Extract<IndexResourceType, 'event' | 'command' | 'query'>;
+/** Where an index came from: the SDK index `source` and `commit`. */
+type DiffRef = {
+    source: string;
+    commit: string;
+};
+/** A value that differs between the baseline (a) and the candidate (b). */
+type Change<T> = {
+    a: T;
+    b: T;
+};
+type DiffSummary = {
+    breaking: boolean;
+    resourcesAdded: number;
+    resourcesRemoved: number;
+    resourcesChanged: number;
+    edgesAdded: number;
+    edgesRemoved: number;
+    schemaChanges: number;
+    schemaBreaking: number;
+    /** Schema changes with no verdict (`breaking: null`). Policy should decide whether these warn or fail. */
+    schemaUnknown: number;
+};
+type ResourceRef = {
+    type: IndexResourceType;
+    id: string;
+    version?: string;
+};
+type ResourceAdded = ResourceRef;
+type ResourceRemoved = ResourceRef;
+/** The fields of a resource the diff compares. Markdown content and schema files are covered elsewhere. */
+type ResourceField = 'version' | 'name' | 'owners' | 'deprecated';
+type ResourceChanged = {
+    type: IndexResourceType;
+    id: string;
+    /** Latest version on each side. Equal when only metadata changed. */
+    version: Change<string | undefined>;
+    /** Which fields differ between the latest version on each side. */
+    fields: ResourceField[];
+};
+/** One end of an edge. `type` is absent when the target could not be resolved in the index. */
+type EdgeEnd = {
+    type?: IndexResourceType;
+    id: string;
+    version?: string;
+};
+/**
+ * An edge between two resources, as resolved by the SDK. Identity ignores versions,
+ * so bumping a message does not churn every edge that points at it.
+ */
+type DiffEdge = {
+    direction: EdgeDirection;
+    from: EdgeEnd;
+    to: EdgeEnd;
+    /** The field the pointer came from when it is not the direction itself, e.g. `steps`. */
+    via?: string;
+};
+type SchemaPointer = {
+    path: string;
+    hash?: string;
+    /** Raw schema text. Only present when `diff()` is called with `includeSchemaContent: true`. */
+    content?: string;
+};
+type SchemaOp = {
+    op: 'add' | 'remove' | 'replace';
+    /** JSON pointer into the schema document, e.g. `/properties/customerId`. */
+    path: string;
+    /** Stable machine-readable change kind, e.g. `required.added`, for consumers that key on it. */
+    kind: string;
+    /** Human-readable explanation. */
+    reason: string;
+    /** Whether this op alone breaks the chosen strategy. */
+    breaking: boolean;
+};
+type SchemaChange = {
+    message: {
+        type: MessageType;
+        id: string;
+        version: Change<string | undefined>;
+    };
+    /** `modified` when the same schema file changed; `added` / `removed` when a schema file appeared or disappeared. */
+    change: 'modified' | 'added' | 'removed';
+    /** Absent when the schema was added. */
+    before?: SchemaPointer;
+    /** Absent when the schema was removed. */
+    after?: SchemaPointer;
+    /**
+     * `null` when no verdict was possible: the schema was added or removed, the index was
+     * built without schema content, the content is not valid JSON, or the format is not
+     * one we can compare yet. Counted in `summary.schemaUnknown` so it is never silent.
+     */
+    breaking: boolean | null;
+    strategy: CompatibilityStrategy;
+    /** Which side the change breaks. `null` when not breaking or when no verdict was possible. */
+    direction: BreakingDirection | null;
+    ops: SchemaOp[];
+};
+type ImpactReason = 'schema_breaking_change' | 'schema_changed' | 'message_removed' | 'producer_removed' | 'consumer_removed';
+type ImpactedResource = {
+    type: IndexResourceType;
+    id: string;
+    version?: string;
+    owners?: string[];
+};
+/**
+ * Who a change hurts, derived from the baseline graph so consumers of the diff
+ * never have to walk edges themselves.
+ *
+ * - `forward` breaking: the consumers listed are on the old schema and will fail
+ *   to read new messages.
+ * - `backward` breaking: the consumers listed will fail to read old messages once
+ *   they move to the new schema (e.g. when replaying history).
+ * - `both`: both of the above.
+ */
+type Impact = {
+    message: {
+        type: MessageType;
+        id: string;
+        version?: string;
+    };
+    reason: ImpactReason;
+    /** Which direction broke. Only present for schema-related reasons. */
+    direction?: BreakingDirection;
+    producers: ImpactedResource[];
+    consumers: ImpactedResource[];
+};
+type ArchitectureDiff = {
+    schemaVersion: typeof ARCHITECTURE_DIFF_SCHEMA_VERSION;
+    refs: {
+        a: DiffRef;
+        b: DiffRef;
+    };
+    compatibility: {
+        strategy: CompatibilityStrategy;
+    };
+    summary: DiffSummary;
+    resources: {
+        added: ResourceAdded[];
+        removed: ResourceRemoved[];
+        changed: ResourceChanged[];
+    };
+    edges: {
+        added: DiffEdge[];
+        removed: DiffEdge[];
+    };
+    schemaChanges: SchemaChange[];
+    impact: Impact[];
+};
+
+type DiffOptions = {
+    /**
+     * Compatibility strategy used when comparing schemas. Defaults to `full`, so a
+     * change is breaking if it could break either producers or consumers.
+     */
+    strategy?: CompatibilityStrategy;
+    /**
+     * Copy the raw before and after schema text onto each schema change, so a
+     * consumer can render a side-by-side diff without going back to the index.
+     * Off by default to keep the document small.
+     */
+    includeSchemaContent?: boolean;
+};
+declare const DEFAULT_STRATEGY: CompatibilityStrategy;
+/**
+ * Compare two catalog indexes and return a single ArchitectureDiff document.
+ *
+ * `a` is the baseline (e.g. `main`) and `b` is the candidate (e.g. a PR branch).
+ * Both are SDK `Index` documents as returned by `buildIndex()`. Build them with
+ * `includeSchemaContent: true` to get schema compatibility verdicts.
+ */
+declare const diff: (a: Index, b: Index, options?: DiffOptions) => ArchitectureDiff;
+
+/** A JSON Schema document. Boolean schemas (`true` / `false`) are valid in draft-06 and later. */
+type JsonSchema = boolean | {
+    [keyword: string]: unknown;
+};
+/**
+ * Every kind of change the comparer can detect. Each kind has exactly one row in
+ * the rules table, which decides whether it is breaking under each strategy.
+ */
+type JsonSchemaChangeKind = 'property.added' | 'property.added-to-closed-object' | 'property.removed' | 'property.removed-from-closed-object' | 'required.added' | 'required.added-with-default' | 'required.removed' | 'type.widened' | 'type.narrowed' | 'type.changed' | 'enum.added' | 'enum.removed' | 'enum.value.added' | 'enum.value.removed' | 'constraint.tightened' | 'constraint.loosened' | 'constraint.changed' | 'additionalProperties.closed' | 'additionalProperties.opened' | 'tuple.item.added' | 'tuple.item.removed' | 'union.branch.added' | 'union.branch.removed' | 'allOf.branch.added' | 'allOf.branch.removed' | 'schema.restricted' | 'schema.relaxed' | 'schema.deprecated' | 'keyword.changed';
+/** A single semantic change between two schemas, with the values on both sides. */
+type JsonSchemaChange = {
+    kind: JsonSchemaChangeKind;
+    /** JSON pointer to the affected node, e.g. `/properties/customerId`. */
+    path: string;
+    /** The keyword involved, when the kind is generic (e.g. `minLength`, `oneOf`). */
+    keyword?: string;
+    before?: unknown;
+    after?: unknown;
+};
+
+/**
+ * Walks two JSON schemas side by side and emits every semantic change found.
+ *
+ * This is deliberately rule-free: it only says *what* changed, never whether
+ * that matters. `rules.ts` decides what is breaking under each strategy.
+ *
+ * Supported: properties, required (with `default`), type (including `integer`
+ * within `number` and nullable unions), enum and const, the min/max constraint
+ * families, pattern, format, multipleOf, uniqueItems, additionalProperties,
+ * items and tuples (`items` array or `prefixItems`), oneOf, anyOf, allOf, local
+ * `$ref` (changes reported once, at the definition), and boolean schemas.
+ *
+ * Annotations (title, description, examples, $comment, default ...) are ignored.
+ * Keywords we cannot reason about are reported as `keyword.changed` so they are
+ * never silently passed.
+ */
+declare const compareJsonSchemas: (before: JsonSchema, after: JsonSchema) => JsonSchemaChange[];
+
+type JsonSchemaCompatibility = {
+    breaking: boolean;
+    /** Which side the change breaks under the strategy, or `null` when it is not breaking. */
+    direction: BreakingDirection | null;
+    ops: SchemaOp[];
+};
+/**
+ * Compare two JSON schemas and judge the result under a compatibility strategy.
+ *
+ * Returns every change as an op (so consumers can show what happened), a single
+ * verdict (breaking if at least one op is breaking under the strategy) and the
+ * direction that broke, so impact can say who is hurt.
+ */
+declare const checkJsonSchemaCompatibility: (before: JsonSchema, after: JsonSchema, strategy: CompatibilityStrategy) => JsonSchemaCompatibility;
+
+export { ARCHITECTURE_DIFF_SCHEMA_VERSION, type ArchitectureDiff, type BreakingDirection, type Change, type CompatibilityStrategy, DEFAULT_STRATEGY, type DiffEdge, type DiffOptions, type DiffRef, type DiffSummary, type EdgeEnd, type Impact, type ImpactReason, type ImpactedResource, type JsonSchema, type JsonSchemaChange, type JsonSchemaChangeKind, type JsonSchemaCompatibility, type MessageType, type ResourceAdded, type ResourceChanged, type ResourceField, type ResourceRef, type ResourceRemoved, type SchemaChange, type SchemaOp, type SchemaPointer, checkJsonSchemaCompatibility, compareJsonSchemas, diff };

package/dist/index.d.ts

@@ -0,0 +1,244 @@
+import { IndexResourceType, EdgeDirection, Index } from '@eventcatalog/sdk';
+export { EdgeDirection, Index, IndexResource, IndexResourceType, IndexSchema } from '@eventcatalog/sdk';
+
+/**
+ * ArchitectureDiff
+ *
+ * The single versioned document produced by `diff(a, b)`. Consumers (CI actions,
+ * policy engines, notifiers, UIs) build on top of this and never re-walk the graph.
+ *
+ * Input is the SDK `Index` returned by `buildIndex()`. Vocabulary follows the SDK:
+ * resources have a `type`, edges have a `direction`.
+ */
+
+declare const ARCHITECTURE_DIFF_SCHEMA_VERSION: 1;
+type CompatibilityStrategy = 'backward' | 'forward' | 'full' | 'none';
+/** Which side a breaking change hurts. `both` only occurs under the `full` strategy. */
+type BreakingDirection = 'backward' | 'forward' | 'both';
+/** Resource types that carry schemas and travel along sends/receives edges. */
+type MessageType = Extract<IndexResourceType, 'event' | 'command' | 'query'>;
+/** Where an index came from: the SDK index `source` and `commit`. */
+type DiffRef = {
+    source: string;
+    commit: string;
+};
+/** A value that differs between the baseline (a) and the candidate (b). */
+type Change<T> = {
+    a: T;
+    b: T;
+};
+type DiffSummary = {
+    breaking: boolean;
+    resourcesAdded: number;
+    resourcesRemoved: number;
+    resourcesChanged: number;
+    edgesAdded: number;
+    edgesRemoved: number;
+    schemaChanges: number;
+    schemaBreaking: number;
+    /** Schema changes with no verdict (`breaking: null`). Policy should decide whether these warn or fail. */
+    schemaUnknown: number;
+};
+type ResourceRef = {
+    type: IndexResourceType;
+    id: string;
+    version?: string;
+};
+type ResourceAdded = ResourceRef;
+type ResourceRemoved = ResourceRef;
+/** The fields of a resource the diff compares. Markdown content and schema files are covered elsewhere. */
+type ResourceField = 'version' | 'name' | 'owners' | 'deprecated';
+type ResourceChanged = {
+    type: IndexResourceType;
+    id: string;
+    /** Latest version on each side. Equal when only metadata changed. */
+    version: Change<string | undefined>;
+    /** Which fields differ between the latest version on each side. */
+    fields: ResourceField[];
+};
+/** One end of an edge. `type` is absent when the target could not be resolved in the index. */
+type EdgeEnd = {
+    type?: IndexResourceType;
+    id: string;
+    version?: string;
+};
+/**
+ * An edge between two resources, as resolved by the SDK. Identity ignores versions,
+ * so bumping a message does not churn every edge that points at it.
+ */
+type DiffEdge = {
+    direction: EdgeDirection;
+    from: EdgeEnd;
+    to: EdgeEnd;
+    /** The field the pointer came from when it is not the direction itself, e.g. `steps`. */
+    via?: string;
+};
+type SchemaPointer = {
+    path: string;
+    hash?: string;
+    /** Raw schema text. Only present when `diff()` is called with `includeSchemaContent: true`. */
+    content?: string;
+};
+type SchemaOp = {
+    op: 'add' | 'remove' | 'replace';
+    /** JSON pointer into the schema document, e.g. `/properties/customerId`. */
+    path: string;
+    /** Stable machine-readable change kind, e.g. `required.added`, for consumers that key on it. */
+    kind: string;
+    /** Human-readable explanation. */
+    reason: string;
+    /** Whether this op alone breaks the chosen strategy. */
+    breaking: boolean;
+};
+type SchemaChange = {
+    message: {
+        type: MessageType;
+        id: string;
+        version: Change<string | undefined>;
+    };
+    /** `modified` when the same schema file changed; `added` / `removed` when a schema file appeared or disappeared. */
+    change: 'modified' | 'added' | 'removed';
+    /** Absent when the schema was added. */
+    before?: SchemaPointer;
+    /** Absent when the schema was removed. */
+    after?: SchemaPointer;
+    /**
+     * `null` when no verdict was possible: the schema was added or removed, the index was
+     * built without schema content, the content is not valid JSON, or the format is not
+     * one we can compare yet. Counted in `summary.schemaUnknown` so it is never silent.
+     */
+    breaking: boolean | null;
+    strategy: CompatibilityStrategy;
+    /** Which side the change breaks. `null` when not breaking or when no verdict was possible. */
+    direction: BreakingDirection | null;
+    ops: SchemaOp[];
+};
+type ImpactReason = 'schema_breaking_change' | 'schema_changed' | 'message_removed' | 'producer_removed' | 'consumer_removed';
+type ImpactedResource = {
+    type: IndexResourceType;
+    id: string;
+    version?: string;
+    owners?: string[];
+};
+/**
+ * Who a change hurts, derived from the baseline graph so consumers of the diff
+ * never have to walk edges themselves.
+ *
+ * - `forward` breaking: the consumers listed are on the old schema and will fail
+ *   to read new messages.
+ * - `backward` breaking: the consumers listed will fail to read old messages once
+ *   they move to the new schema (e.g. when replaying history).
+ * - `both`: both of the above.
+ */
+type Impact = {
+    message: {
+        type: MessageType;
+        id: string;
+        version?: string;
+    };
+    reason: ImpactReason;
+    /** Which direction broke. Only present for schema-related reasons. */
+    direction?: BreakingDirection;
+    producers: ImpactedResource[];
+    consumers: ImpactedResource[];
+};
+type ArchitectureDiff = {
+    schemaVersion: typeof ARCHITECTURE_DIFF_SCHEMA_VERSION;
+    refs: {
+        a: DiffRef;
+        b: DiffRef;
+    };
+    compatibility: {
+        strategy: CompatibilityStrategy;
+    };
+    summary: DiffSummary;
+    resources: {
+        added: ResourceAdded[];
+        removed: ResourceRemoved[];
+        changed: ResourceChanged[];
+    };
+    edges: {
+        added: DiffEdge[];
+        removed: DiffEdge[];
+    };
+    schemaChanges: SchemaChange[];
+    impact: Impact[];
+};
+
+type DiffOptions = {
+    /**
+     * Compatibility strategy used when comparing schemas. Defaults to `full`, so a
+     * change is breaking if it could break either producers or consumers.
+     */
+    strategy?: CompatibilityStrategy;
+    /**
+     * Copy the raw before and after schema text onto each schema change, so a
+     * consumer can render a side-by-side diff without going back to the index.
+     * Off by default to keep the document small.
+     */
+    includeSchemaContent?: boolean;
+};
+declare const DEFAULT_STRATEGY: CompatibilityStrategy;
+/**
+ * Compare two catalog indexes and return a single ArchitectureDiff document.
+ *
+ * `a` is the baseline (e.g. `main`) and `b` is the candidate (e.g. a PR branch).
+ * Both are SDK `Index` documents as returned by `buildIndex()`. Build them with
+ * `includeSchemaContent: true` to get schema compatibility verdicts.
+ */
+declare const diff: (a: Index, b: Index, options?: DiffOptions) => ArchitectureDiff;
+
+/** A JSON Schema document. Boolean schemas (`true` / `false`) are valid in draft-06 and later. */
+type JsonSchema = boolean | {
+    [keyword: string]: unknown;
+};
+/**
+ * Every kind of change the comparer can detect. Each kind has exactly one row in
+ * the rules table, which decides whether it is breaking under each strategy.
+ */
+type JsonSchemaChangeKind = 'property.added' | 'property.added-to-closed-object' | 'property.removed' | 'property.removed-from-closed-object' | 'required.added' | 'required.added-with-default' | 'required.removed' | 'type.widened' | 'type.narrowed' | 'type.changed' | 'enum.added' | 'enum.removed' | 'enum.value.added' | 'enum.value.removed' | 'constraint.tightened' | 'constraint.loosened' | 'constraint.changed' | 'additionalProperties.closed' | 'additionalProperties.opened' | 'tuple.item.added' | 'tuple.item.removed' | 'union.branch.added' | 'union.branch.removed' | 'allOf.branch.added' | 'allOf.branch.removed' | 'schema.restricted' | 'schema.relaxed' | 'schema.deprecated' | 'keyword.changed';
+/** A single semantic change between two schemas, with the values on both sides. */
+type JsonSchemaChange = {
+    kind: JsonSchemaChangeKind;
+    /** JSON pointer to the affected node, e.g. `/properties/customerId`. */
+    path: string;
+    /** The keyword involved, when the kind is generic (e.g. `minLength`, `oneOf`). */
+    keyword?: string;
+    before?: unknown;
+    after?: unknown;
+};
+
+/**
+ * Walks two JSON schemas side by side and emits every semantic change found.
+ *
+ * This is deliberately rule-free: it only says *what* changed, never whether
+ * that matters. `rules.ts` decides what is breaking under each strategy.
+ *
+ * Supported: properties, required (with `default`), type (including `integer`
+ * within `number` and nullable unions), enum and const, the min/max constraint
+ * families, pattern, format, multipleOf, uniqueItems, additionalProperties,
+ * items and tuples (`items` array or `prefixItems`), oneOf, anyOf, allOf, local
+ * `$ref` (changes reported once, at the definition), and boolean schemas.
+ *
+ * Annotations (title, description, examples, $comment, default ...) are ignored.
+ * Keywords we cannot reason about are reported as `keyword.changed` so they are
+ * never silently passed.
+ */
+declare const compareJsonSchemas: (before: JsonSchema, after: JsonSchema) => JsonSchemaChange[];
+
+type JsonSchemaCompatibility = {
+    breaking: boolean;
+    /** Which side the change breaks under the strategy, or `null` when it is not breaking. */
+    direction: BreakingDirection | null;
+    ops: SchemaOp[];
+};
+/**
+ * Compare two JSON schemas and judge the result under a compatibility strategy.
+ *
+ * Returns every change as an op (so consumers can show what happened), a single
+ * verdict (breaking if at least one op is breaking under the strategy) and the
+ * direction that broke, so impact can say who is hurt.
+ */
+declare const checkJsonSchemaCompatibility: (before: JsonSchema, after: JsonSchema, strategy: CompatibilityStrategy) => JsonSchemaCompatibility;
+
+export { ARCHITECTURE_DIFF_SCHEMA_VERSION, type ArchitectureDiff, type BreakingDirection, type Change, type CompatibilityStrategy, DEFAULT_STRATEGY, type DiffEdge, type DiffOptions, type DiffRef, type DiffSummary, type EdgeEnd, type Impact, type ImpactReason, type ImpactedResource, type JsonSchema, type JsonSchemaChange, type JsonSchemaChangeKind, type JsonSchemaCompatibility, type MessageType, type ResourceAdded, type ResourceChanged, type ResourceField, type ResourceRef, type ResourceRemoved, type SchemaChange, type SchemaOp, type SchemaPointer, checkJsonSchemaCompatibility, compareJsonSchemas, diff };