@ir-kit/spec-diff 0.2.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ahmed Rowaihi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# `@ir-kit/spec-diff`
+
+Cross-family API spec diff. Normalizes both inputs to OpenAPI 3 via `@ir-kit/spec-convert`, then delegates classification to [`api-smart-diff`](https://github.com/udamir/api-smart-diff) — community-standard breaking / non-breaking / annotation / unclassified / deprecated buckets.
+
+Part of [ir-kit](https://github.com/ir-kit/ir-kit).
+
+## Install
+
+```sh
+npm install @ir-kit/spec-diff
+```
+
+## Usage
+
+```ts
+import { diffSpecs } from "@ir-kit/spec-diff";
+
+const result = await diffSpecs({
+  before: "./prod.yaml",
+  after: "./staging.proto", // mix any two supported formats
+});
+
+console.log(result.summary);
+// { total: 12, breaking: 3, nonBreaking: 4, annotation: 5, unclassified: 0, deprecated: 0 }
+
+for (const diff of result.diffs.filter((d) => d.type === "breaking")) {
+  console.log(diff.action, diff.path.join("/"), diff.description);
+}
+```
+
+## API
+
+| Export                                                           | Description                                                                            |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `diffSpecs(opts)`                                                | Run a cross-family diff, return diffs + summary + the two normalized OpenAPI documents |
+| `DiffSummary`, `DiffSpecsOptions`, `DiffSpecsResult`, `DiffType` | Public types                                                                           |
+| `Diff` (re-export from `api-smart-diff`)                         | Single change record — `{ action, path, type, description?, before?, after? }`         |
+
+## CLI
+
+```sh
+ir spec diff ./before.yaml --after ./after.proto
+ir spec diff ./prod.yaml --after ./staging.yaml --failOnBreaking --out report.json
+```
+
+`--failOnBreaking` exits non-zero when any `breaking` diff is found — drop into CI to gate merges on contract stability.

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import type { ConvertSpecInput, SpecDocument, SpecFormat } from "@ir-kit/spec-convert";
+import { type Diff } from "api-smart-diff";
+export type { Diff };
+export type DiffType = "breaking" | "non-breaking" | "annotation" | "unclassified" | "deprecated";
+export interface DiffSummary {
+    total: number;
+    breaking: number;
+    nonBreaking: number;
+    annotation: number;
+    unclassified: number;
+    deprecated: number;
+}
+export interface DiffSpecsOptions {
+    before: ConvertSpecInput;
+    after: ConvertSpecInput;
+    fromBefore?: SpecFormat;
+    fromAfter?: SpecFormat;
+    cwd?: string;
+}
+export interface DiffSpecsResult {
+    diffs: Diff[];
+    summary: DiffSummary;
+    before: {
+        from: SpecFormat;
+        openapi: SpecDocument;
+    };
+    after: {
+        from: SpecFormat;
+        openapi: SpecDocument;
+    };
+}
+/**
+ * Cross-family API spec diff. Converts both inputs to OpenAPI 3 via
+ * `@ir-kit/spec-convert`, then runs `api-smart-diff`'s `compareOpenApi`.
+ * Returns the raw diff list plus a breaking/non-breaking summary.
+ */
+export declare function diffSpecs(opts: DiffSpecsOptions): Promise<DiffSpecsResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACX,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAkB,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3D,YAAY,EAAE,IAAI,EAAE,CAAC;AAErB,MAAM,MAAM,QAAQ,GAChB,UAAU,GACV,cAAc,GACd,YAAY,GACZ,cAAc,GACd,YAAY,CAAC;AAEjB,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,gBAAgB,CAAC;IACxB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;IACpD,KAAK,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,eAAe,CAAC,CAc1B"}

package/dist/index.js

@@ -0,0 +1,58 @@
+import { convertSpec } from "@ir-kit/spec-convert";
+import { compareOpenApi } from "api-smart-diff";
+/**
+ * Cross-family API spec diff. Converts both inputs to OpenAPI 3 via
+ * `@ir-kit/spec-convert`, then runs `api-smart-diff`'s `compareOpenApi`.
+ * Returns the raw diff list plus a breaking/non-breaking summary.
+ */
+export async function diffSpecs(opts) {
+    const [before, after] = await Promise.all([
+        normalizeToOpenApi(opts.before, opts.fromBefore, opts.cwd),
+        normalizeToOpenApi(opts.after, opts.fromAfter, opts.cwd),
+    ]);
+    const { diffs } = compareOpenApi(before.openapi, after.openapi);
+    return {
+        diffs,
+        summary: summarize(diffs),
+        before,
+        after,
+    };
+}
+async function normalizeToOpenApi(input, from, cwd) {
+    const result = await convertSpec({ input, from, to: "openapi3", cwd });
+    if (result.output.kind !== "document") {
+        throw new Error(`Unexpected converter output kind '${result.output.kind}' for openapi3 target`);
+    }
+    return { from: result.from, openapi: result.output.document };
+}
+function summarize(diffs) {
+    const summary = {
+        total: diffs.length,
+        breaking: 0,
+        nonBreaking: 0,
+        annotation: 0,
+        unclassified: 0,
+        deprecated: 0,
+    };
+    for (const diff of diffs) {
+        switch (diff.type) {
+            case "breaking":
+                summary.breaking++;
+                break;
+            case "non-breaking":
+                summary.nonBreaking++;
+                break;
+            case "annotation":
+                summary.annotation++;
+                break;
+            case "unclassified":
+                summary.unclassified++;
+                break;
+            case "deprecated":
+                summary.deprecated++;
+                break;
+        }
+    }
+    return summary;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAa,MAAM,gBAAgB,CAAC;AAmC3D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAsB;IAEtB,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACxC,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC;QAC1D,kBAAkB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC;KACzD,CAAC,CAAC;IAEH,MAAM,EAAE,KAAK,EAAE,GAAG,cAAc,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAEhE,OAAO;QACL,KAAK;QACL,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC;QACzB,MAAM;QACN,KAAK;KACN,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,kBAAkB,CAC/B,KAAuB,EACvB,IAA4B,EAC5B,GAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;IACvE,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,qCAAqC,MAAM,CAAC,MAAM,CAAC,IAAI,uBAAuB,CAC/E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;AAChE,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,MAAM,OAAO,GAAgB;QAC3B,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,QAAQ,EAAE,CAAC;QACX,WAAW,EAAE,CAAC;QACd,UAAU,EAAE,CAAC;QACb,YAAY,EAAE,CAAC;QACf,UAAU,EAAE,CAAC;KACd,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,UAAU;gBACb,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACnB,MAAM;YACR,KAAK,cAAc;gBACjB,OAAO,CAAC,WAAW,EAAE,CAAC;gBACtB,MAAM;YACR,KAAK,YAAY;gBACf,OAAO,CAAC,UAAU,EAAE,CAAC;gBACrB,MAAM;YACR,KAAK,cAAc;gBACjB,OAAO,CAAC,YAAY,EAAE,CAAC;gBACvB,MAAM;YACR,KAAK,YAAY;gBACf,OAAO,CAAC,UAAU,EAAE,CAAC;gBACrB,MAAM;QACV,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@ir-kit/spec-diff",
+  "version": "0.2.0",
+  "description": "Cross-family API spec diff. Converts any supported spec to OpenAPI 3, then runs `api-smart-diff` — breaking / non-breaking / annotation classification.",
+  "keywords": [
+    "openapi",
+    "asyncapi",
+    "typespec",
+    "protobuf",
+    "postman",
+    "diff",
+    "breaking-change",
+    "ir-kit"
+  ],
+  "homepage": "https://github.com/ir-kit/ir-kit/tree/main/packages/shared/spec-diff",
+  "bugs": {
+    "url": "https://github.com/ir-kit/ir-kit/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Ahmed Rowaihi",
+    "email": "ahmedrowaihi@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ir-kit/ir-kit.git",
+    "directory": "packages/shared/spec-diff"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "api-smart-diff": "^1.0.6",
+    "@ir-kit/spec-convert": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "vitest": "^4.0.0",
+    "@ir-kit/tsconfig": "0.0.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}