@zuplo/cli 6.62.7 → 6.62.9

package/dist/open-api/overlay/overlay-engine.spec.js

@@ -0,0 +1,609 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { applyOverlay, applyAction, deepClone, deepMerge, checkCondition, setValueAtPath, extractPathOrder, reorderOperationProperties, } from "./overlay-engine.js";
+describe("OpenAPI Overlay Engine", () => {
+    describe("deepClone", () => {
+        it("should deep clone an object", () => {
+            const original = { a: 1, b: { c: 2 } };
+            const cloned = deepClone(original);
+            assert.deepStrictEqual(cloned, original);
+            assert.notStrictEqual(cloned, original);
+            assert.notStrictEqual(cloned.b, original.b);
+        });
+        it("should deep clone an array", () => {
+            const original = [1, 2, { a: 3 }];
+            const cloned = deepClone(original);
+            assert.deepStrictEqual(cloned, original);
+            assert.notStrictEqual(cloned, original);
+            assert.notStrictEqual(cloned[2], original[2]);
+        });
+    });
+    describe("deepMerge", () => {
+        it("should merge two objects", () => {
+            const target = { a: 1, b: 2 };
+            const source = { b: 3, c: 4 };
+            const result = deepMerge(target, source);
+            assert.deepStrictEqual(result, { a: 1, b: 3, c: 4 });
+        });
+        it("should merge nested objects", () => {
+            const target = { a: { b: 1, c: 2 } };
+            const source = { a: { c: 3, d: 4 } };
+            const result = deepMerge(target, source);
+            assert.deepStrictEqual(result, { a: { b: 1, c: 3, d: 4 } });
+        });
+        it("should concatenate arrays by default", () => {
+            const target = { arr: [1, 2] };
+            const source = { arr: [3, 4] };
+            const result = deepMerge(target, source);
+            assert.deepStrictEqual(result, { arr: [1, 2, 3, 4] });
+        });
+        it("should merge OpenAPI parameters by name and in", () => {
+            const target = {
+                parameters: [
+                    { name: "id", in: "path", required: true },
+                    { name: "filter", in: "query" },
+                ],
+            };
+            const source = {
+                parameters: [
+                    { name: "id", in: "path", description: "The ID" },
+                    { name: "sort", in: "query" },
+                ],
+            };
+            const result = deepMerge(target, source);
+            assert.deepStrictEqual(result, {
+                parameters: [
+                    { name: "id", in: "path", required: true, description: "The ID" },
+                    { name: "filter", in: "query" },
+                    { name: "sort", in: "query" },
+                ],
+            });
+        });
+        it("should replace target with source if types differ", () => {
+            const target = { a: [1, 2] };
+            const source = { a: "string" };
+            const result = deepMerge(target, source);
+            assert.deepStrictEqual(result, { a: "string" });
+        });
+    });
+    describe("checkCondition", () => {
+        it("should return true for empty object when empty condition is true", () => {
+            assert.strictEqual(checkCondition({}, { empty: true }), true);
+        });
+        it("should return false for non-empty object when empty condition is true", () => {
+            assert.strictEqual(checkCondition({ a: 1 }, { empty: true }), false);
+        });
+        it("should return true for empty array when empty condition is true", () => {
+            assert.strictEqual(checkCondition([], { empty: true }), true);
+        });
+        it("should return false for non-empty array when empty condition is true", () => {
+            assert.strictEqual(checkCondition([1], { empty: true }), false);
+        });
+        it("should return true when property is missing", () => {
+            const obj = { a: { b: 1 } };
+            assert.strictEqual(checkCondition(obj, { missing: "a.c" }), true);
+        });
+        it("should return false when property exists", () => {
+            const obj = { a: { b: 1 } };
+            assert.strictEqual(checkCondition(obj, { missing: "a.b" }), false);
+        });
+    });
+    describe("setValueAtPath", () => {
+        it("should set value at simple path", () => {
+            const doc = {};
+            setValueAtPath(doc, "$.info.title", "My API");
+            assert.deepStrictEqual(doc, { info: { title: "My API" } });
+        });
+        it("should set value at bracket notation path", () => {
+            const doc = {};
+            setValueAtPath(doc, "$.paths['/users'].get", { summary: "Get users" });
+            assert.deepStrictEqual(doc, {
+                paths: { "/users": { get: { summary: "Get users" } } },
+            });
+        });
+        it("should create nested paths as needed", () => {
+            const doc = {};
+            setValueAtPath(doc, "$.a.b.c.d", "value");
+            assert.deepStrictEqual(doc, { a: { b: { c: { d: "value" } } } });
+        });
+        it("should handle double-quoted bracket notation", () => {
+            const doc = {};
+            setValueAtPath(doc, '$.paths["/users"].get', { summary: "Get users" });
+            assert.deepStrictEqual(doc, {
+                paths: { "/users": { get: { summary: "Get users" } } },
+            });
+        });
+        it("should handle unquoted bracket notation", () => {
+            const doc = {};
+            setValueAtPath(doc, "$.paths[users].get", { summary: "Get users" });
+            assert.deepStrictEqual(doc, {
+                paths: { users: { get: { summary: "Get users" } } },
+            });
+        });
+        it("should handle numeric indices", () => {
+            const doc = { items: [{}, {}] };
+            setValueAtPath(doc, "$.items[0].name", "First Item");
+            assert.strictEqual(doc.items[0].name, "First Item");
+        });
+        it("should handle mixed dot and bracket notation", () => {
+            const doc = {};
+            setValueAtPath(doc, "$.components.schemas['User'].properties.id", {
+                type: "string",
+            });
+            assert.deepStrictEqual(doc, {
+                components: {
+                    schemas: {
+                        User: {
+                            properties: {
+                                id: { type: "string" },
+                            },
+                        },
+                    },
+                },
+            });
+        });
+    });
+    describe("applyAction - update operations", () => {
+        it("should update root level properties", () => {
+            const doc = { info: { title: "Old Title" } };
+            const action = {
+                target: "$",
+                update: { info: { version: "1.0.0" } },
+            };
+            const result = applyAction(doc, action);
+            assert.strictEqual(result.applied, true);
+            assert.strictEqual(result.count, 1);
+            assert.deepStrictEqual(doc.info, {
+                title: "Old Title",
+                version: "1.0.0",
+            });
+        });
+        it("should update existing nested property", () => {
+            const doc = {
+                paths: {
+                    "/users": {
+                        get: { summary: "Old summary" },
+                    },
+                },
+            };
+            const action = {
+                target: "$.paths['/users'].get",
+                update: { summary: "New summary", description: "Get all users" },
+            };
+            const result = applyAction(doc, action);
+            assert.strictEqual(result.applied, true);
+            assert.strictEqual(result.count, 1);
+            assert.strictEqual(doc.paths["/users"].get.summary, "New summary");
+            assert.strictEqual(doc.paths["/users"].get.description, "Get all users");
+        });
+        it("should create new property if it doesn't exist", () => {
+            const doc = { paths: {} };
+            const action = {
+                target: "$.paths['/users']",
+                update: { get: { summary: "Get users" } },
+            };
+            const result = applyAction(doc, action);
+            assert.strictEqual(result.applied, true);
+            assert.strictEqual(result.count, 1);
+            assert.deepStrictEqual(doc.paths["/users"], {
+                get: { summary: "Get users" },
+            });
+        });
+        it("should update multiple nodes with wildcard", () => {
+            const doc = {
+                paths: {
+                    "/users": { get: { tags: [] } },
+                    "/posts": { get: { tags: [] } },
+                },
+            };
+            const action = {
+                target: "$.paths.*.get",
+                update: { tags: ["public"] },
+            };
+            const result = applyAction(doc, action);
+            assert.strictEqual(result.applied, true);
+            assert.strictEqual(result.count, 2);
+            assert.deepStrictEqual(doc.paths["/users"].get.tags, ["public"]);
+            assert.deepStrictEqual(doc.paths["/posts"].get.tags, ["public"]);
+        });
+    });
+    describe("applyAction - remove operations", () => {
+        it("should remove a property from object", () => {
+            const doc = {
+                paths: {
+                    "/users": { get: {}, delete: {} },
+                },
+            };
+            const action = {
+                target: "$.paths['/users'].delete",
+                remove: true,
+            };
+            const result = applyAction(doc, action);
+            assert.strictEqual(result.applied, true);
+            assert.strictEqual(result.count, 1);
+            assert.strictEqual("delete" in doc.paths["/users"], false);
+            assert.ok("get" in doc.paths["/users"]);
+        });
+        it("should remove multiple properties with wildcard", () => {
+            const doc = {
+                paths: {
+                    "/users": { get: {}, delete: {} },
+                    "/posts": { get: {}, delete: {} },
+                },
+            };
+            const action = {
+                target: "$.paths.*.delete",
+                remove: true,
+            };
+            const result = applyAction(doc, action);
+            assert.strictEqual(result.applied, true);
+            assert.strictEqual(result.count, 2);
+            assert.strictEqual("delete" in doc.paths["/users"], false);
+            assert.strictEqual("delete" in doc.paths["/posts"], false);
+        });
+        it("should conditionally remove empty objects", () => {
+            const doc = {
+                paths: {
+                    "/users": { get: {} },
+                    "/posts": {},
+                    "/comments": { get: {} },
+                },
+            };
+            const action = {
+                target: "$.paths.*",
+                remove: { empty: true },
+            };
+            const result = applyAction(doc, action);
+            assert.strictEqual(result.applied, true);
+            assert.strictEqual(result.count, 1);
+            assert.ok("/users" in doc.paths);
+            assert.strictEqual("/posts" in doc.paths, false);
+            assert.ok("/comments" in doc.paths);
+        });
+        it("should conditionally remove when property is missing", () => {
+            const doc = {
+                paths: {
+                    "/users": { get: { "x-internal": true } },
+                    "/posts": { get: {} },
+                },
+            };
+            const action = {
+                target: "$.paths.*",
+                remove: { missing: "get.x-internal" },
+            };
+            const result = applyAction(doc, action);
+            assert.strictEqual(result.applied, true);
+            assert.strictEqual(result.count, 1);
+            assert.ok("/users" in doc.paths);
+            assert.strictEqual("/posts" in doc.paths, false);
+        });
+        it("should return false if target not found", () => {
+            const doc = { paths: {} };
+            const action = {
+                target: "$.paths['/users']",
+                remove: true,
+            };
+            const result = applyAction(doc, action);
+            assert.strictEqual(result.applied, false);
+            assert.strictEqual(result.count, 0);
+        });
+    });
+    describe("extractPathOrder", () => {
+        it("should extract path order from overlay actions", () => {
+            const overlay = {
+                overlay: "1.0.0",
+                info: { title: "Test", version: "1.0.0" },
+                actions: [
+                    { target: "$.paths['/users'].get", update: {} },
+                    { target: "$.paths['/posts'].get", update: {} },
+                    { target: "$.paths['/users'].post", update: {} },
+                    { target: "$.info", update: {} },
+                ],
+            };
+            const order = extractPathOrder(overlay);
+            assert.deepStrictEqual(order, ["/users", "/posts"]);
+        });
+        it("should return empty array if no path actions", () => {
+            const overlay = {
+                overlay: "1.0.0",
+                info: { title: "Test", version: "1.0.0" },
+                actions: [{ target: "$.info", update: {} }],
+            };
+            const order = extractPathOrder(overlay);
+            assert.deepStrictEqual(order, []);
+        });
+    });
+    describe("reorderOperationProperties", () => {
+        it("should reorder operation properties with priority keys first", () => {
+            const operation = {
+                responses: {},
+                parameters: [],
+                operationId: "getUsers",
+                description: "Get all users",
+                summary: "Get users",
+            };
+            const result = reorderOperationProperties(operation);
+            const keys = Object.keys(result);
+            assert.strictEqual(keys[0], "summary");
+            assert.strictEqual(keys[1], "description");
+            assert.strictEqual(keys[2], "operationId");
+            assert.strictEqual(keys[3], "responses");
+            assert.strictEqual(keys[4], "parameters");
+        });
+        it("should handle missing priority keys", () => {
+            const operation = {
+                responses: {},
+                operationId: "getUsers",
+            };
+            const result = reorderOperationProperties(operation);
+            const keys = Object.keys(result);
+            assert.strictEqual(keys[0], "operationId");
+            assert.strictEqual(keys[1], "responses");
+        });
+    });
+    describe("applyOverlay - full integration", () => {
+        it("should apply a complete overlay document", () => {
+            const openapi = {
+                openapi: "3.1.0",
+                info: {
+                    title: "Original API",
+                    version: "1.0.0",
+                },
+                paths: {
+                    "/users": {
+                        get: {
+                            summary: "Get users",
+                        },
+                    },
+                },
+            };
+            const overlay = {
+                overlay: "1.0.0",
+                info: {
+                    title: "My Overlay",
+                    version: "1.0.0",
+                },
+                actions: [
+                    {
+                        target: "$.info",
+                        description: "Update API info",
+                        update: {
+                            title: "Updated API",
+                            description: "An updated API",
+                        },
+                    },
+                    {
+                        target: "$.paths['/users'].get",
+                        description: "Add operation ID",
+                        update: {
+                            operationId: "getUsers",
+                        },
+                    },
+                ],
+            };
+            const { result, stats } = applyOverlay(openapi, overlay);
+            assert.strictEqual(stats.applied, 2);
+            assert.strictEqual(stats.skipped, 0);
+            assert.strictEqual(stats.totalNodes, 2);
+            assert.strictEqual(result.info.title, "Updated API");
+            assert.strictEqual(result.info.description, "An updated API");
+            assert.strictEqual(result.info.version, "1.0.0");
+            assert.strictEqual(result.paths["/users"].get.operationId, "getUsers");
+        });
+        it("should handle overlay with remove actions", () => {
+            const openapi = {
+                openapi: "3.1.0",
+                info: { title: "API" },
+                paths: {
+                    "/users": { get: {}, delete: {} },
+                    "/internal": { get: {} },
+                },
+            };
+            const overlay = {
+                overlay: "1.0.0",
+                info: { title: "Overlay", version: "1.0.0" },
+                actions: [
+                    {
+                        target: "$.paths.*.delete",
+                        description: "Remove all delete operations",
+                        remove: true,
+                    },
+                    {
+                        target: "$.paths['/internal']",
+                        description: "Remove internal path",
+                        remove: true,
+                    },
+                ],
+            };
+            const { result, stats } = applyOverlay(openapi, overlay);
+            assert.strictEqual(stats.applied, 2);
+            assert.strictEqual(stats.totalNodes, 2);
+            assert.strictEqual("delete" in result.paths["/users"], false);
+            assert.strictEqual("/internal" in result.paths, false);
+            assert.ok("/users" in result.paths);
+        });
+        it("should throw error for invalid overlay format", () => {
+            const openapi = { openapi: "3.1.0" };
+            const invalidOverlay = {
+                info: { title: "Invalid" },
+            };
+            assert.throws(() => applyOverlay(openapi, invalidOverlay), /Invalid overlay format/);
+        });
+        it("should handle empty actions array", () => {
+            const openapi = {
+                openapi: "3.1.0",
+                info: { title: "API" },
+            };
+            const overlay = {
+                overlay: "1.0.0",
+                info: { title: "Empty Overlay", version: "1.0.0" },
+                actions: [],
+            };
+            const { result, stats } = applyOverlay(openapi, overlay);
+            assert.strictEqual(stats.applied, 0);
+            assert.strictEqual(stats.skipped, 0);
+            assert.deepStrictEqual(result.info, openapi.info);
+        });
+        it("should apply overlay with wildcards and conditions", () => {
+            const openapi = {
+                openapi: "3.1.0",
+                paths: {
+                    "/users": {
+                        get: { "x-internal": true, tags: [] },
+                        post: { tags: [] },
+                    },
+                    "/posts": { get: { tags: [] } },
+                    "/internal": { get: { "x-internal": true, tags: [] } },
+                },
+            };
+            const overlay = {
+                overlay: "1.0.0",
+                info: { title: "Conditional Overlay", version: "1.0.0" },
+                actions: [
+                    {
+                        target: "$.paths.*.*.tags",
+                        description: "Add default tag",
+                        update: ["public"],
+                    },
+                    {
+                        target: "$.paths.*",
+                        description: "Remove paths without x-internal",
+                        remove: { missing: "get.x-internal" },
+                    },
+                ],
+            };
+            const { result, stats } = applyOverlay(openapi, overlay);
+            assert.strictEqual(stats.applied, 2);
+            assert.ok("/users" in result.paths);
+            assert.ok("/internal" in result.paths);
+            assert.strictEqual("/posts" in result.paths, false);
+        });
+        it("should preserve document structure and order", () => {
+            const openapi = {
+                openapi: "3.1.0",
+                info: { title: "API", version: "1.0.0" },
+                servers: [{ url: "https://api.example.com" }],
+                paths: {},
+            };
+            const overlay = {
+                overlay: "1.0.0",
+                info: { title: "Overlay", version: "1.0.0" },
+                actions: [
+                    {
+                        target: "$.info",
+                        update: { description: "Added description" },
+                    },
+                ],
+            };
+            const { result } = applyOverlay(openapi, overlay);
+            const keys = Object.keys(result);
+            assert.strictEqual(keys[0], "openapi");
+            assert.strictEqual(keys[1], "info");
+            assert.ok(keys.includes("servers"));
+            assert.ok(keys.includes("paths"));
+            assert.strictEqual(result.info.description, "Added description");
+        });
+    });
+    describe("Complex overlay scenarios", () => {
+        it("should handle deep nested updates", () => {
+            const openapi = {
+                components: {
+                    schemas: {
+                        User: {
+                            type: "object",
+                            properties: {
+                                id: { type: "string" },
+                            },
+                        },
+                    },
+                },
+            };
+            const overlay = {
+                overlay: "1.0.0",
+                info: { title: "Schema Overlay", version: "1.0.0" },
+                actions: [
+                    {
+                        target: "$.components.schemas.User.properties",
+                        update: {
+                            name: { type: "string" },
+                            email: { type: "string", format: "email" },
+                        },
+                    },
+                ],
+            };
+            const { result } = applyOverlay(openapi, overlay);
+            assert.ok(result.components.schemas.User.properties.id);
+            assert.ok(result.components.schemas.User.properties.name);
+            assert.ok(result.components.schemas.User.properties.email);
+            assert.strictEqual(result.components.schemas.User.properties.email.format, "email");
+        });
+        it("should handle array element removal", () => {
+            const openapi = {
+                servers: [
+                    { url: "https://prod.example.com", description: "Production" },
+                    { url: "https://staging.example.com", description: "Staging" },
+                    { url: "https://dev.example.com", description: "Development" },
+                ],
+            };
+            const overlay = {
+                overlay: "1.0.0",
+                info: { title: "Server Overlay", version: "1.0.0" },
+                actions: [
+                    {
+                        target: "$.servers[?(@.description=='Development')]",
+                        remove: true,
+                    },
+                ],
+            };
+            const { result } = applyOverlay(openapi, overlay);
+            assert.strictEqual(result.servers.length, 2);
+            assert.strictEqual(result.servers[0].description, "Production");
+            assert.strictEqual(result.servers[1].description, "Staging");
+        });
+        it("should handle parameter merging correctly", () => {
+            const openapi = {
+                paths: {
+                    "/users/{id}": {
+                        parameters: [
+                            { name: "id", in: "path", required: true },
+                            { name: "fields", in: "query" },
+                        ],
+                        get: {},
+                    },
+                },
+            };
+            const overlay = {
+                overlay: "1.0.0",
+                info: { title: "Parameter Overlay", version: "1.0.0" },
+                actions: [
+                    {
+                        target: "$.paths['/users/{id}'].parameters",
+                        update: [
+                            {
+                                name: "id",
+                                in: "path",
+                                description: "User ID",
+                                schema: { type: "string" },
+                            },
+                            { name: "include", in: "query", description: "Include related" },
+                        ],
+                    },
+                ],
+            };
+            const { result } = applyOverlay(openapi, overlay);
+            const params = result.paths["/users/{id}"].parameters;
+            assert.strictEqual(params.length, 3);
+            const idParam = params.find((p) => p.name === "id");
+            assert.ok(idParam);
+            assert.strictEqual(idParam.required, true);
+            assert.strictEqual(idParam.description, "User ID");
+            assert.deepStrictEqual(idParam.schema, { type: "string" });
+            const fieldsParam = params.find((p) => p.name === "fields");
+            assert.ok(fieldsParam);
+            const includeParam = params.find((p) => p.name === "include");
+            assert.ok(includeParam);
+            assert.strictEqual(includeParam.description, "Include related");
+        });
+    });
+});
+//# sourceMappingURL=overlay-engine.spec.js.map