@unispechq/unispec-core 0.3.0 → 0.3.2

package/dist/tests/diff/diff-annotators.test.js

@@ -0,0 +1,275 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { createTestChange } from "../../tests/utils.js";
+import { annotateGraphQLChange, annotateRestChange, annotateWebSocketChange, } from "../../src/diff/annotators.js";
+describe("diff annotators", () => {
+    describe("annotateRestChange", () => {
+        it("should annotate REST route additions as non-breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/rest/routes/newRoute",
+                description: "Item added",
+            });
+            const result = annotateRestChange(change);
+            assert.strictEqual(result.protocol, "rest");
+            assert.strictEqual(result.kind, "rest.route.added");
+            assert.strictEqual(result.severity, "non-breaking");
+        });
+        it("should annotate REST route removals as breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/rest/routes/removedRoute",
+                description: "Item removed",
+            });
+            const result = annotateRestChange(change);
+            assert.strictEqual(result.protocol, "rest");
+            assert.strictEqual(result.kind, "rest.route.removed");
+            assert.strictEqual(result.severity, "breaking");
+        });
+        it("should annotate required field changes as breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/rest/routes/myRoute/requestBody/required",
+                description: "Value changed",
+            });
+            const result = annotateRestChange(change);
+            assert.strictEqual(result.protocol, "rest");
+            assert.strictEqual(result.kind, "rest.parameter.required_changed");
+            assert.strictEqual(result.severity, "breaking");
+        });
+        it("should not annotate non-REST changes", () => {
+            const change = createTestChange({
+                path: "/service/protocols/graphql/queries/myQuery",
+                description: "Item added",
+            });
+            const result = annotateRestChange(change);
+            assert.strictEqual(result.protocol, undefined);
+            assert.strictEqual(result.kind, undefined);
+            assert.strictEqual(result.severity, "unknown");
+        });
+        it("should handle malformed REST paths gracefully", () => {
+            const change = createTestChange({
+                path: "/service/protocols/rest", // Missing routes segment
+                description: "Item added",
+            });
+            const result = annotateRestChange(change);
+            assert.strictEqual(result.protocol, undefined);
+            assert.strictEqual(result.kind, undefined);
+            assert.strictEqual(result.severity, "unknown");
+        });
+    });
+    describe("annotateGraphQLChange", () => {
+        it("should annotate GraphQL query additions as non-breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/graphql/queries/newQuery",
+                description: "Item added",
+            });
+            const result = annotateGraphQLChange(change);
+            assert.strictEqual(result.protocol, "graphql");
+            assert.strictEqual(result.kind, "graphql.query.added");
+            assert.strictEqual(result.severity, "non-breaking");
+        });
+        it("should annotate GraphQL query removals as breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/graphql/queries/removedQuery",
+                description: "Item removed",
+            });
+            const result = annotateGraphQLChange(change);
+            assert.strictEqual(result.protocol, "graphql");
+            assert.strictEqual(result.kind, "graphql.query.removed");
+            assert.strictEqual(result.severity, "breaking");
+        });
+        it("should annotate GraphQL mutation additions as non-breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/graphql/mutations/newMutation",
+                description: "Item added",
+            });
+            const result = annotateGraphQLChange(change);
+            assert.strictEqual(result.protocol, "graphql");
+            assert.strictEqual(result.kind, "graphql.mutation.added");
+            assert.strictEqual(result.severity, "non-breaking");
+        });
+        it("should annotate GraphQL mutation removals as breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/graphql/mutations/removedMutation",
+                description: "Item removed",
+            });
+            const result = annotateGraphQLChange(change);
+            assert.strictEqual(result.protocol, "graphql");
+            assert.strictEqual(result.kind, "graphql.mutation.removed");
+            assert.strictEqual(result.severity, "breaking");
+        });
+        it("should annotate GraphQL subscription additions as non-breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/graphql/subscriptions/newSubscription",
+                description: "Item added",
+            });
+            const result = annotateGraphQLChange(change);
+            assert.strictEqual(result.protocol, "graphql");
+            assert.strictEqual(result.kind, "graphql.subscription.added");
+            assert.strictEqual(result.severity, "non-breaking");
+        });
+        it("should annotate GraphQL subscription removals as breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/graphql/subscriptions/removedSubscription",
+                description: "Item removed",
+            });
+            const result = annotateGraphQLChange(change);
+            assert.strictEqual(result.protocol, "graphql");
+            assert.strictEqual(result.kind, "graphql.subscription.removed");
+            assert.strictEqual(result.severity, "breaking");
+        });
+        it("should not annotate non-GraphQL changes", () => {
+            const change = createTestChange({
+                path: "/service/protocols/rest/routes/myRoute",
+                description: "Item added",
+            });
+            const result = annotateGraphQLChange(change);
+            assert.strictEqual(result.protocol, undefined);
+            assert.strictEqual(result.kind, undefined);
+            assert.strictEqual(result.severity, "unknown");
+        });
+        it("should annotate GraphQL argument additions as non-breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/graphql/queries/myQuery/args/newArg",
+                description: "Item added",
+            });
+            const result = annotateGraphQLChange(change);
+            assert.strictEqual(result.protocol, "graphql");
+            assert.strictEqual(result.kind, "graphql.query.argument_added");
+            assert.strictEqual(result.severity, "non-breaking");
+        });
+        it("should annotate GraphQL argument removals as breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/graphql/mutations/myMutation/args/oldArg",
+                description: "Item removed",
+            });
+            const result = annotateGraphQLChange(change);
+            assert.strictEqual(result.protocol, "graphql");
+            assert.strictEqual(result.kind, "graphql.mutation.argument_removed");
+            assert.strictEqual(result.severity, "breaking");
+        });
+        it("should annotate GraphQL return type changes as breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/graphql/subscriptions/mySubscription/returnType",
+                description: "Value changed",
+            });
+            const result = annotateGraphQLChange(change);
+            assert.strictEqual(result.protocol, "graphql");
+            assert.strictEqual(result.kind, "graphql.subscription.return_type_changed");
+            assert.strictEqual(result.severity, "breaking");
+        });
+    });
+    describe("annotateWebSocketChange", () => {
+        it("should annotate WebSocket channel additions as non-breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/websocket/channels/newChannel",
+                description: "Item added",
+            });
+            const result = annotateWebSocketChange(change);
+            assert.strictEqual(result.protocol, "websocket");
+            assert.strictEqual(result.kind, "websocket.channel.added");
+            assert.strictEqual(result.severity, "non-breaking");
+        });
+        it("should annotate WebSocket channel removals as breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/websocket/channels/removedChannel",
+                description: "Item removed",
+            });
+            const result = annotateWebSocketChange(change);
+            assert.strictEqual(result.protocol, "websocket");
+            assert.strictEqual(result.kind, "websocket.channel.removed");
+            assert.strictEqual(result.severity, "breaking");
+        });
+        it("should annotate WebSocket message additions as non-breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/websocket/channels/myChannel/messages/newMessage",
+                description: "Item added",
+            });
+            const result = annotateWebSocketChange(change);
+            assert.strictEqual(result.protocol, "websocket");
+            assert.strictEqual(result.kind, "websocket.message.added");
+            assert.strictEqual(result.severity, "non-breaking");
+        });
+        it("should annotate WebSocket message removals as breaking", () => {
+            const change = createTestChange({
+                path: "/service/protocols/websocket/channels/myChannel/messages/removedMessage",
+                description: "Item removed",
+            });
+            const result = annotateWebSocketChange(change);
+            assert.strictEqual(result.protocol, "websocket");
+            assert.strictEqual(result.kind, "websocket.message.removed");
+            assert.strictEqual(result.severity, "breaking");
+        });
+        it("should not annotate non-WebSocket changes", () => {
+            const change = createTestChange({
+                path: "/service/protocols/rest/routes/myRoute",
+                description: "Item added",
+            });
+            const result = annotateWebSocketChange(change);
+            assert.strictEqual(result.protocol, undefined);
+            assert.strictEqual(result.kind, undefined);
+            assert.strictEqual(result.severity, "unknown");
+        });
+    });
+    describe("annotation chaining", () => {
+        it("should handle multiple annotations correctly", () => {
+            // This simulates what happens in diffUniSpec where changes are chained through all annotators
+            const restChange = createTestChange({
+                path: "/service/protocols/rest/routes/myRoute",
+                description: "Item added",
+            });
+            const result = annotateWebSocketChange(annotateGraphQLChange(annotateRestChange(restChange)));
+            // Should only have REST annotations since it's a REST path
+            assert.strictEqual(result.protocol, "rest");
+            assert.strictEqual(result.kind, "rest.route.added");
+            assert.strictEqual(result.severity, "non-breaking");
+        });
+    });
+    describe("edge cases", () => {
+        it("should handle empty paths", () => {
+            const change = createTestChange({
+                path: "",
+                description: "Item added",
+            });
+            const restResult = annotateRestChange(change);
+            const graphqlResult = annotateGraphQLChange(change);
+            const wsResult = annotateWebSocketChange(change);
+            // None should annotate empty path
+            assert.strictEqual(restResult.protocol, undefined);
+            assert.strictEqual(graphqlResult.protocol, undefined);
+            assert.strictEqual(wsResult.protocol, undefined);
+        });
+        it("should handle undefined paths gracefully", () => {
+            const changeWithUndefined = createTestChange({
+                path: undefined,
+                description: "Item added",
+            });
+            const restResultUndef = annotateRestChange(changeWithUndefined);
+            const graphqlResultUndef = annotateGraphQLChange(changeWithUndefined);
+            const wsResultUndef = annotateWebSocketChange(changeWithUndefined);
+            assert.strictEqual(restResultUndef.protocol, undefined);
+            assert.strictEqual(graphqlResultUndef.protocol, undefined);
+            assert.strictEqual(wsResultUndef.protocol, undefined);
+        });
+        it("should handle malformed paths gracefully", () => {
+            const malformedPaths = [
+                "/service/protocols", // Incomplete
+                "/service/protocols/rest/routes", // Missing route name
+                "/service/protocols/graphql", // Missing operation type
+                "invalid/path/format",
+                "service/protocols/rest/routes/route", // Missing leading slash
+            ];
+            for (const path of malformedPaths) {
+                const change = createTestChange({
+                    path,
+                    description: "Item added",
+                });
+                const restResult = annotateRestChange(change);
+                const graphqlResult = annotateGraphQLChange(change);
+                const wsResult = annotateWebSocketChange(change);
+                // Should not crash and should not annotate malformed paths
+                assert.strictEqual(restResult.protocol, undefined);
+                assert.strictEqual(graphqlResult.protocol, undefined);
+                assert.strictEqual(wsResult.protocol, undefined);
+            }
+        });
+    });
+});

package/dist/tests/diff/diff-comprehensive.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/diff/diff-comprehensive.test.js

@@ -0,0 +1,257 @@
+import assert from "node:assert";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { examplesDir, loadExample } from "../../tests/utils.js";
+import { diffUniSpec } from "../../src/diff/core.js";
+describe("diff module - comprehensive schema examples", () => {
+    describe("valid spec examples", () => {
+        it("should handle rest-simple.json correctly", () => {
+            const doc = loadExample(path.join(examplesDir, "valid", "spec", "rest-simple.json"));
+            // Test self-comparison
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+            // Test modifications
+            const modified = JSON.parse(JSON.stringify(doc));
+            modified.service.protocols.rest.routes.push({
+                name: "newRoute",
+                method: "DELETE",
+                path: "/users/{id}",
+                responses: { 204: { description: "No content" } },
+            });
+            const diffResult = diffUniSpec(doc, modified);
+            const newRoute = diffResult.changes.find((change) => change.path.includes("newRoute"));
+            assert.ok(newRoute);
+            assert.strictEqual(newRoute.protocol, "rest");
+            assert.strictEqual(newRoute.severity, "non-breaking");
+        });
+        it("should handle graphql-simple.json correctly", () => {
+            const doc = loadExample(path.join(examplesDir, "valid", "spec", "graphql-simple.json"));
+            // Test self-comparison
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+            // Test schema change
+            const modified = JSON.parse(JSON.stringify(doc));
+            modified.service.protocols.graphql.schema +=
+                " type NewType { field: String! }";
+            const diffResult = diffUniSpec(doc, modified);
+            const schemaChange = diffResult.changes.find((change) => change.path.includes("schema"));
+            assert.ok(schemaChange);
+            assert.strictEqual(schemaChange.description, "Value changed");
+        });
+        it("should handle websocket-simple.json correctly", () => {
+            const doc = loadExample(path.join(examplesDir, "valid", "spec", "websocket-simple.json"));
+            // Test self-comparison
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+            // Test channel addition
+            const modified = JSON.parse(JSON.stringify(doc));
+            modified.service.protocols.websocket.channels.push({
+                name: "newChannel",
+                description: "New channel",
+                messages: [],
+            });
+            const diffResult = diffUniSpec(doc, modified);
+            const newChannel = diffResult.changes.find((change) => change.path.includes("newChannel"));
+            assert.ok(newChannel);
+            assert.strictEqual(newChannel.protocol, "websocket");
+            assert.strictEqual(newChannel.severity, "non-breaking");
+        });
+        it("should handle mixed-complete.json correctly", () => {
+            const doc = loadExample(path.join(examplesDir, "valid", "spec", "mixed-complete.json"));
+            // Test self-comparison
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+            // Test multiple protocol changes
+            const modified = JSON.parse(JSON.stringify(doc));
+            // Add REST route
+            if (modified.service.protocols.rest) {
+                modified.service.protocols.rest.routes.push({
+                    name: "mixedRoute",
+                    method: "PATCH",
+                    path: "/mixed",
+                    responses: { 200: { description: "OK" } },
+                });
+            }
+            // Add GraphQL query
+            if (modified.service.protocols.graphql?.queries) {
+                modified.service.protocols.graphql.queries.push({
+                    name: "mixedQuery",
+                    description: "Mixed query",
+                    args: [],
+                    returnType: "String",
+                });
+            }
+            const diffResult = diffUniSpec(doc, modified);
+            // Should have both REST and GraphQL changes
+            const restChanges = diffResult.changes.filter((change) => change.protocol === "rest");
+            const graphqlChanges = diffResult.changes.filter((change) => change.protocol === "graphql");
+            assert.ok(restChanges.length > 0);
+            assert.ok(graphqlChanges.length > 0);
+        });
+    });
+    describe("valid config examples", () => {
+        it("should handle complete-enterprise.json correctly", () => {
+            const doc = loadExample(path.join(examplesDir, "valid", "config", "complete-enterprise.json"));
+            // Test self-comparison
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+            // Test modification
+            const modified = JSON.parse(JSON.stringify(doc));
+            if (Array.isArray(modified.services)) {
+                modified.services.push({
+                    name: "new-service",
+                    baseUrl: "https://new-service.example.com",
+                });
+            }
+            const diffResult = diffUniSpec(doc, modified);
+            assert.ok(diffResult.changes.length > 0);
+        });
+        it("should handle registry-based.json correctly", () => {
+            const doc = loadExample(path.join(examplesDir, "valid", "config", "registry-based.json"));
+            // Test self-comparison
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+        });
+        it("should handle simple-multi-service.json correctly", () => {
+            const doc = loadExample(path.join(examplesDir, "valid", "config", "simple-multi-service.json"));
+            // Test self-comparison
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+        });
+    });
+    describe("invalid spec examples", () => {
+        it("should handle graphql-missing-arg-type.json without crashing", () => {
+            const doc = loadExample(path.join(examplesDir, "invalid", "spec", "graphql-missing-arg-type.json"));
+            // Should not crash on invalid documents
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+            // Should handle modifications
+            const modified = JSON.parse(JSON.stringify(doc));
+            modified.unispecVersion = "1.0.1";
+            const diffResult = diffUniSpec(doc, modified);
+            const versionChange = diffResult.changes.find((change) => change.path === "/unispecVersion");
+            assert.ok(versionChange);
+        });
+        it("should handle graphql-missing-name.json without crashing", () => {
+            const doc = loadExample(path.join(examplesDir, "invalid", "spec", "graphql-missing-name.json"));
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+        });
+        it("should handle invalid-identifier.json without crashing", () => {
+            const doc = loadExample(path.join(examplesDir, "invalid", "spec", "invalid-identifier.json"));
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+        });
+        it("should handle invalid-rest-method.json without crashing", () => {
+            const doc = loadExample(path.join(examplesDir, "invalid", "spec", "invalid-rest-method.json"));
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+        });
+        it("should handle missing-service-name.json without crashing", () => {
+            const doc = loadExample(path.join(examplesDir, "invalid", "spec", "missing-service-name.json"));
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+        });
+        it("should handle missing-unispec-version.json without crashing", () => {
+            const doc = loadExample(path.join(examplesDir, "invalid", "spec", "missing-unispec-version.json"));
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+        });
+    });
+    describe("invalid config examples", () => {
+        it("should handle empty-services-array.json without crashing", () => {
+            const doc = loadExample(path.join(examplesDir, "invalid", "config", "empty-services-array.json"));
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+        });
+        it("should handle invalid-spec-reference.json without crashing", () => {
+            const doc = loadExample(path.join(examplesDir, "invalid", "config", "invalid-spec-reference.json"));
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+        });
+        it("should handle missing-services.json without crashing", () => {
+            const doc = loadExample(path.join(examplesDir, "invalid", "config", "missing-services.json"));
+            const result = diffUniSpec(doc, doc);
+            assert.strictEqual(result.changes.length, 0);
+        });
+    });
+    describe("cross-example comparisons", () => {
+        it("should handle comparing different valid specs", () => {
+            const restDoc = loadExample(path.join(examplesDir, "valid", "spec", "rest-simple.json"));
+            const graphqlDoc = loadExample(path.join(examplesDir, "valid", "spec", "graphql-simple.json"));
+            // Should detect many differences between different specs
+            const result = diffUniSpec(restDoc, graphqlDoc);
+            assert.ok(result.changes.length > 0);
+            // Most changes will be structural and not protocol-specific
+            // since the documents have completely different structures
+            const structuralChanges = result.changes.filter((change) => change.protocol === undefined);
+            // Should have some structural changes
+            assert.ok(structuralChanges.length > 0);
+            // May have some protocol-specific changes if paths overlap
+            const restChanges = result.changes.filter((change) => change.protocol === "rest");
+            const graphqlChanges = result.changes.filter((change) => change.protocol === "graphql");
+            // At least one of them should have changes
+            assert.ok(restChanges.length > 0 ||
+                graphqlChanges.length > 0 ||
+                structuralChanges.length > 0);
+        });
+        it("should handle comparing valid and invalid specs", () => {
+            const validDoc = loadExample(path.join(examplesDir, "valid", "spec", "rest-simple.json"));
+            const invalidDoc = loadExample(path.join(examplesDir, "invalid", "spec", "missing-service-name.json"));
+            // Should handle comparisons without crashing
+            const result = diffUniSpec(validDoc, invalidDoc);
+            assert.ok(result.changes.length > 0);
+        });
+        it("should handle comparing config and spec files", () => {
+            const configDoc = loadExample(path.join(examplesDir, "valid", "config", "simple-multi-service.json"));
+            const specDoc = loadExample(path.join(examplesDir, "valid", "spec", "rest-simple.json"));
+            // Should handle completely different structures
+            const result = diffUniSpec(configDoc, specDoc);
+            assert.ok(result.changes.length > 0);
+        });
+    });
+    describe("edge cases with real examples", () => {
+        it("should handle deeply nested changes in complex examples", () => {
+            const doc = loadExample(path.join(examplesDir, "valid", "spec", "mixed-complete.json"));
+            const modified = JSON.parse(JSON.stringify(doc));
+            // Make a deep nested change - find the first route with requestBody
+            if (modified.service?.protocols?.rest?.routes) {
+                const routeWithBody = modified.service.protocols.rest.routes.find((route) => route.requestBody?.content?.["application/json"]?.schemaRef);
+                if (routeWithBody) {
+                    routeWithBody.requestBody.content["application/json"].schemaRef =
+                        "NewSchemaRef";
+                }
+            }
+            const result = diffUniSpec(doc, modified);
+            // Should have some changes
+            assert.ok(result.changes.length > 0);
+            // Look for any schema-related change
+            const schemaChange = result.changes.find((change) => change.path.includes("schemaRef"));
+            // If we found a route with schemaRef, it should be detected
+            if (doc.service?.protocols?.rest?.routes?.some((route) => route.requestBody?.content?.["application/json"]?.schemaRef)) {
+                assert.ok(schemaChange);
+                assert.strictEqual(schemaChange.description, "Value changed");
+            }
+            else {
+                // If no route had schemaRef, we should still have some changes
+                assert.ok(result.changes.length > 0);
+            }
+        });
+        it("should handle array operations in named collections correctly", () => {
+            const doc = loadExample(path.join(examplesDir, "valid", "spec", "rest-simple.json"));
+            const modified = JSON.parse(JSON.stringify(doc));
+            // Reorder routes array
+            if (modified.service.protocols.rest.routes.length >= 2) {
+                const temp = modified.service.protocols.rest.routes[0];
+                modified.service.protocols.rest.routes[0] =
+                    modified.service.protocols.rest.routes[1];
+                modified.service.protocols.rest.routes[1] = temp;
+            }
+            const result = diffUniSpec(doc, modified);
+            // Named collections should compare by name, not index
+            // So reordering should not produce changes
+            const routeChanges = result.changes.filter((change) => change.path.includes("/routes/"));
+            assert.strictEqual(routeChanges.length, 0);
+        });
+    });
+});

package/dist/tests/diff/diff-extended.test.d.ts

@@ -0,0 +1 @@
+export {};