@unispechq/unispec-core 0.3.0 → 0.3.2

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

@@ -0,0 +1,643 @@
+import assert from "node:assert";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { normalizeUniSpec } from "../../src/normalizer/index.js";
+import { createTestDocument, examplesDir, loadExample } from "./utils.js";
+describe("normalizer module - comprehensive protocol tests", () => {
+    describe("REST protocol normalization", () => {
+        it("should sort REST routes by name when available", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        rest: {
+                            routes: [
+                                {
+                                    name: "zebraRoute",
+                                    method: "GET",
+                                    path: "/zebra",
+                                    responses: { "200": { description: "OK" } },
+                                },
+                                {
+                                    name: "alphaRoute",
+                                    method: "POST",
+                                    path: "/alpha",
+                                    responses: { "201": { description: "Created" } },
+                                },
+                                {
+                                    name: "betaRoute",
+                                    method: "PUT",
+                                    path: "/beta",
+                                    responses: { "200": { description: "OK" } },
+                                },
+                            ],
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Routes should be sorted by name
+            const routes = normalized.service?.protocols?.rest?.routes || [];
+            const routeNames = routes.map((r) => r.name).filter(Boolean);
+            assert.deepStrictEqual(routeNames, [
+                "alphaRoute",
+                "betaRoute",
+                "zebraRoute",
+            ]);
+        });
+        it("should sort REST routes by path+method when name is missing", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        rest: {
+                            routes: [
+                                {
+                                    name: "",
+                                    method: "GET",
+                                    path: "/users",
+                                    responses: { "200": { description: "OK" } },
+                                },
+                                {
+                                    name: "",
+                                    method: "POST",
+                                    path: "/users",
+                                    responses: { "201": { description: "Created" } },
+                                },
+                                {
+                                    name: "",
+                                    method: "DELETE",
+                                    path: "/users/{id}",
+                                    responses: { "204": { description: "No Content" } },
+                                },
+                            ],
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Routes should be sorted by path+method
+            const routes = normalized.service?.protocols?.rest?.routes || [];
+            const routeKeys = routes.map((r) => r.name ? `${r.path} ${r.method}` : `${r.path} ${r.method}`);
+            assert.deepStrictEqual(routeKeys, [
+                "/users GET",
+                "/users POST",
+                "/users/{id} DELETE",
+            ]);
+        });
+        it("should handle mixed named and unnamed routes", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        rest: {
+                            routes: [
+                                {
+                                    name: "getUser",
+                                    method: "GET",
+                                    path: "/users/{id}",
+                                    responses: { "200": { description: "OK" } },
+                                },
+                                {
+                                    name: "",
+                                    method: "POST",
+                                    path: "/users",
+                                    responses: { "201": { description: "Created" } },
+                                },
+                                {
+                                    name: "deleteUser",
+                                    method: "DELETE",
+                                    path: "/users/{id}",
+                                    responses: { "204": { description: "No Content" } },
+                                },
+                            ],
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Routes should be sorted by name or path+method
+            const routes = normalized.service?.protocols?.rest?.routes || [];
+            const routeKeys = routes.map((r) => r.name || `${r.path} ${r.method}`);
+            assert.deepStrictEqual(routeKeys, [
+                "/users POST",
+                "deleteUser",
+                "getUser",
+            ]);
+        });
+    });
+    describe("GraphQL protocol normalization", () => {
+        it("should sort GraphQL queries by name", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        graphql: {
+                            queries: [
+                                {
+                                    name: "zebraQuery",
+                                    description: "Get zebra",
+                                    args: [],
+                                    returnType: "Zebra",
+                                },
+                                {
+                                    name: "alphaQuery",
+                                    description: "Get alpha",
+                                    args: [],
+                                    returnType: "Alpha",
+                                },
+                                {
+                                    name: "betaQuery",
+                                    description: "Get beta",
+                                    args: [],
+                                    returnType: "Beta",
+                                },
+                            ],
+                            mutations: [],
+                            subscriptions: [],
+                            schema: "type Query { alphaQuery: Alpha betaQuery: Beta zebraQuery: Zebra }",
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Queries should be sorted by name
+            const queries = normalized.service?.protocols?.graphql?.queries || [];
+            const queryNames = queries.map((q) => q.name).filter(Boolean);
+            assert.deepStrictEqual(queryNames, [
+                "alphaQuery",
+                "betaQuery",
+                "zebraQuery",
+            ]);
+        });
+        it("should sort GraphQL mutations by name", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        graphql: {
+                            queries: [],
+                            mutations: [
+                                {
+                                    name: "zebraMutation",
+                                    description: "Create zebra",
+                                    args: [],
+                                    returnType: "Zebra",
+                                },
+                                {
+                                    name: "alphaMutation",
+                                    description: "Create alpha",
+                                    args: [],
+                                    returnType: "Alpha",
+                                },
+                            ],
+                            subscriptions: [],
+                            schema: "type Mutation { alphaMutation: Alpha zebraMutation: Zebra }",
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Mutations should be sorted by name
+            const mutations = normalized.service?.protocols?.graphql?.mutations || [];
+            const mutationNames = mutations.map((m) => m.name).filter(Boolean);
+            assert.deepStrictEqual(mutationNames, ["alphaMutation", "zebraMutation"]);
+        });
+        it("should sort GraphQL subscriptions by name", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        graphql: {
+                            queries: [],
+                            mutations: [],
+                            subscriptions: [
+                                {
+                                    name: "zebraSubscription",
+                                    description: "Subscribe to zebra",
+                                    args: [],
+                                    returnType: "Zebra",
+                                },
+                                {
+                                    name: "alphaSubscription",
+                                    description: "Subscribe to alpha",
+                                    args: [],
+                                    returnType: "Alpha",
+                                },
+                            ],
+                            schema: "type Subscription { alphaSubscription: Alpha zebraSubscription: Zebra }",
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Subscriptions should be sorted by name
+            const subscriptions = normalized.service?.protocols?.graphql?.subscriptions || [];
+            const subscriptionNames = subscriptions
+                .map((s) => s.name)
+                .filter(Boolean);
+            assert.deepStrictEqual(subscriptionNames, [
+                "alphaSubscription",
+                "zebraSubscription",
+            ]);
+        });
+        it("should handle operations with missing names", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        graphql: {
+                            queries: [
+                                {
+                                    name: "",
+                                    description: "Query without name",
+                                    args: [],
+                                    returnType: "String",
+                                },
+                                {
+                                    name: "namedQuery",
+                                    description: "Named query",
+                                    args: [],
+                                    returnType: "String",
+                                },
+                            ],
+                            mutations: [],
+                            subscriptions: [],
+                            schema: "type Query { namedQuery: String }",
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Should handle missing names gracefully
+            const queries = normalized.service?.protocols?.graphql?.queries || [];
+            assert.strictEqual(queries.length, 2);
+            // Named query should come after unnamed (empty string sorts first)
+            const queryNames = queries.map((q) => q.name || "");
+            assert.deepStrictEqual(queryNames, ["", "namedQuery"]);
+        });
+    });
+    describe("WebSocket protocol normalization", () => {
+        it("should sort WebSocket channels by name", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        websocket: {
+                            channels: [
+                                {
+                                    name: "zebraChannel",
+                                    description: "Zebra channel",
+                                    messages: [],
+                                },
+                                {
+                                    name: "alphaChannel",
+                                    description: "Alpha channel",
+                                    messages: [],
+                                },
+                                {
+                                    name: "betaChannel",
+                                    description: "Beta channel",
+                                    messages: [],
+                                },
+                            ],
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Channels should be sorted by name
+            const channels = normalized.service?.protocols?.websocket?.channels || [];
+            const channelNames = channels.map((c) => c.name).filter(Boolean);
+            assert.deepStrictEqual(channelNames, [
+                "alphaChannel",
+                "betaChannel",
+                "zebraChannel",
+            ]);
+        });
+        it("should sort messages within each channel by name", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        websocket: {
+                            channels: [
+                                {
+                                    name: "notifications",
+                                    description: "Notification channel",
+                                    messages: [
+                                        {
+                                            name: "zebraMessage",
+                                            description: "Zebra notification",
+                                            direction: "subscribe",
+                                        },
+                                        {
+                                            name: "alphaMessage",
+                                            description: "Alpha notification",
+                                            direction: "publish",
+                                        },
+                                        {
+                                            name: "betaMessage",
+                                            description: "Beta notification",
+                                            direction: "both",
+                                        },
+                                    ],
+                                },
+                            ],
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Messages should be sorted by name within the channel
+            const channel = normalized.service?.protocols?.websocket?.channels?.find((c) => c.name === "notifications");
+            assert.ok(channel);
+            const messages = channel?.messages || [];
+            const messageNames = messages.map((m) => m.name).filter(Boolean);
+            assert.deepStrictEqual(messageNames, [
+                "alphaMessage",
+                "betaMessage",
+                "zebraMessage",
+            ]);
+        });
+        it("should handle channels with missing names", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        websocket: {
+                            channels: [
+                                {
+                                    name: "",
+                                    description: "Channel without name",
+                                    messages: [],
+                                },
+                                {
+                                    name: "namedChannel",
+                                    description: "Named channel",
+                                    messages: [],
+                                },
+                            ],
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Should handle missing names gracefully
+            const channels = normalized.service?.protocols?.websocket?.channels || [];
+            assert.strictEqual(channels.length, 2);
+            // Named channel should come after unnamed
+            const channelNames = channels.map((c) => c.name || "");
+            assert.deepStrictEqual(channelNames, ["", "namedChannel"]);
+        });
+        it("should handle messages with missing names", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        websocket: {
+                            channels: [
+                                {
+                                    name: "testChannel",
+                                    description: "Test channel",
+                                    messages: [
+                                        {
+                                            name: "",
+                                            description: "Message without name",
+                                            direction: "subscribe",
+                                        },
+                                        {
+                                            name: "namedMessage",
+                                            description: "Named message",
+                                            direction: "publish",
+                                        },
+                                    ],
+                                },
+                            ],
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Should handle missing names gracefully
+            const channel = normalized.service?.protocols?.websocket?.channels?.find((c) => c.name === "testChannel");
+            assert.ok(channel);
+            const messages = channel?.messages || [];
+            assert.strictEqual(messages.length, 2);
+            // Named message should come after unnamed
+            const messageNames = messages.map((m) => m.name || "");
+            assert.deepStrictEqual(messageNames, ["", "namedMessage"]);
+        });
+    });
+    describe("Mixed protocol normalization", () => {
+        it("should normalize all protocols simultaneously", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        rest: {
+                            routes: [
+                                {
+                                    name: "zebraRoute",
+                                    method: "GET",
+                                    path: "/zebra",
+                                    responses: { "200": { description: "OK" } },
+                                },
+                                {
+                                    name: "alphaRoute",
+                                    method: "POST",
+                                    path: "/alpha",
+                                    responses: { "201": { description: "Created" } },
+                                },
+                            ],
+                        },
+                        graphql: {
+                            queries: [
+                                {
+                                    name: "zebraQuery",
+                                    description: "Get zebra",
+                                    args: [],
+                                    returnType: "Zebra",
+                                },
+                                {
+                                    name: "alphaQuery",
+                                    description: "Get alpha",
+                                    args: [],
+                                    returnType: "Alpha",
+                                },
+                            ],
+                            mutations: [],
+                            subscriptions: [],
+                            schema: "type Query { alphaQuery: Alpha zebraQuery: Zebra }",
+                        },
+                        websocket: {
+                            channels: [
+                                {
+                                    name: "zebraChannel",
+                                    description: "Zebra channel",
+                                    messages: [],
+                                },
+                                {
+                                    name: "alphaChannel",
+                                    description: "Alpha channel",
+                                    messages: [],
+                                },
+                            ],
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // All protocols should be normalized
+            const protocols = normalized.service?.protocols;
+            // Check REST routes
+            const restRoutes = protocols?.rest?.routes || [];
+            const restRouteNames = restRoutes.map((r) => r.name).filter(Boolean);
+            assert.deepStrictEqual(restRouteNames, ["alphaRoute", "zebraRoute"]);
+            // Check GraphQL queries
+            const graphqlQueries = protocols?.graphql?.queries || [];
+            const graphqlQueryNames = graphqlQueries
+                .map((q) => q.name)
+                .filter(Boolean);
+            assert.deepStrictEqual(graphqlQueryNames, ["alphaQuery", "zebraQuery"]);
+            // Check WebSocket channels
+            const wsChannels = protocols?.websocket?.channels || [];
+            const wsChannelNames = wsChannels.map((c) => c.name).filter(Boolean);
+            assert.deepStrictEqual(wsChannelNames, ["alphaChannel", "zebraChannel"]);
+        });
+    });
+    describe("Structural normalization", () => {
+        it("should sort all object keys lexicographically", () => {
+            const doc = {
+                unispecVersion: "1.0.0",
+                service: {
+                    name: "test-service",
+                    description: "Test service for sorting",
+                    protocols: {
+                        rest: {
+                            routes: [
+                                {
+                                    name: "zRoute",
+                                    method: "GET",
+                                    path: "/z",
+                                    responses: { "200": { description: "OK" } },
+                                },
+                                {
+                                    name: "aRoute",
+                                    method: "POST",
+                                    path: "/a",
+                                    responses: { "201": { description: "Created" } },
+                                },
+                            ],
+                        },
+                    },
+                },
+            };
+            const normalized = normalizeUniSpec(doc);
+            // Top-level keys should be sorted
+            const docKeys = Object.keys(normalized);
+            assert.deepStrictEqual(docKeys, ["service", "unispecVersion"]);
+            // Service keys should be sorted lexicographically
+            const serviceKeys = Object.keys(normalized.service || {});
+            const expectedServiceKeys = ["description", "name", "protocols"];
+            assert.deepStrictEqual(serviceKeys, expectedServiceKeys);
+            // Protocol keys should be sorted
+            const protocolKeys = Object.keys(normalized.service?.protocols || {});
+            assert.deepStrictEqual(protocolKeys, ["rest"]);
+        });
+        it("should handle nested objects recursively", () => {
+            const doc = createTestDocument({
+                service: {
+                    name: "test-service",
+                    protocols: {
+                        rest: {
+                            routes: [
+                                {
+                                    name: "testRoute",
+                                    method: "POST",
+                                    path: "/test",
+                                    requestBody: {
+                                        description: "Request body",
+                                        content: {
+                                            "application/json": {
+                                                schemaRef: "ZSchema",
+                                            },
+                                            "text/plain": {
+                                                schemaRef: "ASchema",
+                                            },
+                                        },
+                                    },
+                                    responses: {
+                                        "201": {
+                                            description: "Created",
+                                        },
+                                        "200": {
+                                            description: "OK",
+                                        },
+                                    },
+                                },
+                            ],
+                        },
+                    },
+                },
+            });
+            const normalized = normalizeUniSpec(doc);
+            // Nested object keys should be sorted
+            const route = normalized.service?.protocols?.rest?.routes?.[0];
+            assert.ok(route);
+            // requestBody keys should be sorted lexicographically
+            const requestBodyKeys = Object.keys(route.requestBody || {});
+            assert.deepStrictEqual(requestBodyKeys, ["content", "description"]);
+            // response keys should be sorted
+            const responseKeys = Object.keys(route.responses || {});
+            assert.deepStrictEqual(responseKeys, ["200", "201"]);
+        });
+    });
+    describe("Real-world examples", () => {
+        it("should handle complex real-world example from mixed-complete.json", () => {
+            const doc = loadExample(path.join(examplesDir, "valid", "spec", "mixed-complete.json"));
+            // Should not crash
+            const normalized = normalizeUniSpec(doc);
+            assert.ok(normalized);
+            // Should have sorted structure
+            const docKeys = Object.keys(normalized);
+            assert.deepStrictEqual(docKeys, ["service", "unispecVersion"]);
+            // Should normalize all protocols present
+            const protocols = normalized.service?.protocols;
+            if (protocols?.rest?.routes) {
+                const routeKeys = protocols.rest.routes.map((r) => r.name || `${r.path} ${r.method}`);
+                const sortedRouteKeys = [...routeKeys].sort();
+                assert.deepStrictEqual(routeKeys, sortedRouteKeys);
+            }
+            if (protocols?.graphql) {
+                ["queries", "mutations", "subscriptions"].forEach((operationType) => {
+                    const operations = protocols[operationType];
+                    if (Array.isArray(operations)) {
+                        const names = operations
+                            .map((op) => op.name || "")
+                            .filter(Boolean);
+                        const sortedNames = [...names].sort();
+                        assert.deepStrictEqual(names, sortedNames);
+                    }
+                });
+            }
+            if (protocols?.websocket?.channels) {
+                const channelNames = protocols.websocket.channels
+                    .map((c) => c.name || "")
+                    .filter(Boolean);
+                const sortedChannelNames = [...channelNames].sort();
+                assert.deepStrictEqual(channelNames, sortedChannelNames);
+                // Check message sorting within channels
+                protocols.websocket.channels.forEach((channel) => {
+                    if (channel.messages) {
+                        const messageNames = channel.messages
+                            .map((m) => m.name || "")
+                            .filter(Boolean);
+                        const sortedMessageNames = [...messageNames].sort();
+                        assert.deepStrictEqual(messageNames, sortedMessageNames);
+                    }
+                });
+            }
+        });
+    });
+});

package/dist/tests/normalizer/normalizer-invalid.test.d.ts

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