@unispechq/unispec-core 0.1.2 → 0.2.2

package/dist/diff/index.js

@@ -34,8 +34,54 @@ function diffValues(oldVal, newVal, basePath, out) {
         }
         return;
     }
-    // Arrays → shallow compare by index for now
+    // Arrays
     if (Array.isArray(oldVal) && Array.isArray(newVal)) {
+        // Special handling for UniSpec collections identified by "name"
+        const isNamedCollection = basePath === "/service/protocols/rest/routes" ||
+            basePath === "/service/protocols/websocket/channels" ||
+            basePath === "/service/protocols/graphql/queries" ||
+            basePath === "/service/protocols/graphql/mutations" ||
+            basePath === "/service/protocols/graphql/subscriptions";
+        if (isNamedCollection) {
+            const oldByName = new Map();
+            const newByName = new Map();
+            for (const item of oldVal) {
+                if (item && typeof item === "object" && typeof item.name === "string") {
+                    oldByName.set(item.name, item);
+                }
+            }
+            for (const item of newVal) {
+                if (item && typeof item === "object" && typeof item.name === "string") {
+                    newByName.set(item.name, item);
+                }
+            }
+            // Removed
+            for (const [name, oldItem] of oldByName.entries()) {
+                if (!newByName.has(name)) {
+                    out.push({
+                        path: `${basePath}/${name}`,
+                        description: "Item removed",
+                        severity: "unknown",
+                    });
+                }
+                else {
+                    const newItem = newByName.get(name);
+                    diffValues(oldItem, newItem, `${basePath}/${name}`, out);
+                }
+            }
+            // Added
+            for (const [name] of newByName.entries()) {
+                if (!oldByName.has(name)) {
+                    out.push({
+                        path: `${basePath}/${name}`,
+                        description: "Item added",
+                        severity: "unknown",
+                    });
+                }
+            }
+            return;
+        }
+        // Generic shallow index-based compare
         const maxLen = Math.max(oldVal.length, newVal.length);
         for (let i = 0; i < maxLen; i++) {
             const childPath = `${basePath}/${i}`;
@@ -67,40 +113,29 @@ function diffValues(oldVal, newVal, basePath, out) {
     });
 }
 function annotateRestChange(change) {
-    if (!change.path.startsWith("/service/protocols/rest/paths/")) {
+    if (!change.path.startsWith("/service/protocols/rest/routes/")) {
         return change;
     }
     const segments = change.path.split("/").filter(Boolean);
-    // Expected shape: ["service", "protocols", "rest", "paths", pathKey?, method?]
-    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "rest" || segments[3] !== "paths") {
+    // Expected shape: ["service", "protocols", "rest", "routes", index]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "rest" || segments[3] !== "routes") {
+        return change;
+    }
+    const index = segments[4];
+    if (typeof index === "undefined") {
         return change;
     }
-    const pathKey = segments[4];
-    const method = segments[5];
-    const httpMethods = new Set(["get", "head", "options", "post", "put", "patch", "delete"]);
     const annotated = {
         ...change,
         protocol: "rest",
     };
-    if (change.description === "Field removed") {
-        if (pathKey && !method) {
-            annotated.kind = "rest.path.removed";
-            annotated.severity = "breaking";
-        }
-        else if (pathKey && method && httpMethods.has(method)) {
-            annotated.kind = "rest.operation.removed";
-            annotated.severity = "breaking";
-        }
+    if (change.description === "Item removed" || change.description === "Field removed") {
+        annotated.kind = "rest.route.removed";
+        annotated.severity = "breaking";
     }
-    else if (change.description === "Field added") {
-        if (pathKey && !method) {
-            annotated.kind = "rest.path.added";
-            annotated.severity = "non-breaking";
-        }
-        else if (pathKey && method && httpMethods.has(method)) {
-            annotated.kind = "rest.operation.added";
-            annotated.severity = "non-breaking";
-        }
+    else if (change.description === "Item added" || change.description === "Field added") {
+        annotated.kind = "rest.route.added";
+        annotated.severity = "non-breaking";
     }
     return annotated;
 }
@@ -109,35 +144,35 @@ function annotateWebSocketChange(change) {
         return change;
     }
     const segments = change.path.split("/").filter(Boolean);
-    // Expected: ["service","protocols","websocket","channels", channelName, ...]
+    // Expected base: ["service","protocols","websocket","channels", channelIndex, ...]
     if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "websocket" || segments[3] !== "channels") {
         return change;
     }
-    const channelName = segments[4];
+    const channelIndex = segments[4];
     const next = segments[5];
     const annotated = {
         ...change,
         protocol: "websocket",
     };
-    if (!channelName) {
+    if (typeof channelIndex === "undefined") {
         return annotated;
     }
-    // Channel-level changes
+    // Channel-level changes: /service/protocols/websocket/channels/{index}
     if (!next) {
-        if (change.description === "Field removed") {
+        if (change.description === "Item removed" || change.description === "Field removed") {
             annotated.kind = "websocket.channel.removed";
             annotated.severity = "breaking";
         }
-        else if (change.description === "Field added") {
+        else if (change.description === "Item added" || change.description === "Field added") {
             annotated.kind = "websocket.channel.added";
             annotated.severity = "non-breaking";
         }
         return annotated;
     }
-    // Message-level changes (channels/{channelName}/messages/{index})
+    // Message-level changes: /service/protocols/websocket/channels/{index}/messages/{msgIndex}
     if (next === "messages") {
-        const index = segments[6];
-        if (typeof index === "undefined") {
+        const messageIndex = segments[6];
+        if (typeof messageIndex === "undefined") {
             return annotated;
         }
         if (change.description === "Item removed") {
@@ -152,28 +187,31 @@ function annotateWebSocketChange(change) {
     return annotated;
 }
 function annotateGraphQLChange(change) {
-    if (!change.path.startsWith("/service/protocols/graphql/operations/")) {
+    if (!change.path.startsWith("/service/protocols/graphql/")) {
         return change;
     }
     const segments = change.path.split("/").filter(Boolean);
-    // Expected: ["service","protocols","graphql","operations", kind, opName?]
-    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "graphql" || segments[3] !== "operations") {
+    // Expected: ["service","protocols","graphql", kind, index, ...]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "graphql") {
+        return change;
+    }
+    const opKind = segments[3];
+    const index = segments[4];
+    if (!opKind || typeof index === "undefined") {
         return change;
     }
-    const opKind = segments[4];
-    const opName = segments[5];
-    if (!opKind || !opName) {
+    if (opKind !== "queries" && opKind !== "mutations" && opKind !== "subscriptions") {
         return change;
     }
     const annotated = {
         ...change,
         protocol: "graphql",
     };
-    if (change.description === "Field removed") {
+    if (change.description === "Item removed" || change.description === "Field removed") {
         annotated.kind = "graphql.operation.removed";
         annotated.severity = "breaking";
     }
-    else if (change.description === "Field added") {
+    else if (change.description === "Item added" || change.description === "Field added") {
         annotated.kind = "graphql.operation.added";
         annotated.severity = "non-breaking";
     }

package/dist/index.cjs

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types/index.js"), exports);
+__exportStar(require("./loader/index.js"), exports);
+__exportStar(require("./validator/index.js"), exports);
+__exportStar(require("./normalizer/index.js"), exports);
+__exportStar(require("./diff/index.js"), exports);
+__exportStar(require("./converters/index.js"), exports);

package/dist/normalizer/index.js

@@ -15,37 +15,22 @@ function normalizeValue(value) {
     }
     return value;
 }
-function normalizeRestPaths(doc) {
+function normalizeRestRoutes(doc) {
     if (!doc || !doc.service || !doc.service.protocols) {
         return doc;
     }
     const protocols = doc.service.protocols;
     const rest = protocols.rest;
-    if (!rest || !rest.paths || typeof rest.paths !== "object") {
+    if (!rest || !Array.isArray(rest.routes)) {
         return doc;
     }
-    const httpMethodOrder = ["get", "head", "options", "post", "put", "patch", "delete"];
-    const normalizedPaths = {};
-    for (const path of Object.keys(rest.paths).sort()) {
-        const pathItem = rest.paths[path];
-        if (!pathItem || typeof pathItem !== "object") {
-            normalizedPaths[path] = pathItem;
-            continue;
-        }
-        const pathItemObj = pathItem;
-        const ordered = {};
-        for (const method of httpMethodOrder) {
-            if (Object.prototype.hasOwnProperty.call(pathItemObj, method)) {
-                ordered[method] = pathItemObj[method];
-            }
-        }
-        const remainingKeys = Object.keys(pathItemObj).filter((k) => !httpMethodOrder.includes(k)).sort();
-        for (const key of remainingKeys) {
-            ordered[key] = pathItemObj[key];
-        }
-        normalizedPaths[path] = ordered;
-    }
-    rest.paths = normalizedPaths;
+    const routes = [...rest.routes];
+    routes.sort((a, b) => {
+        const keyA = a.name || `${a.path} ${a.method}`;
+        const keyB = b.name || `${b.path} ${b.method}`;
+        return keyA.localeCompare(keyB);
+    });
+    rest.routes = routes;
     return doc;
 }
 function normalizeWebSocket(doc) {
@@ -54,30 +39,29 @@ function normalizeWebSocket(doc) {
     }
     const protocols = doc.service.protocols;
     const websocket = protocols.websocket;
-    if (!websocket || !websocket.channels || typeof websocket.channels !== "object") {
+    if (!websocket || !Array.isArray(websocket.channels)) {
         return doc;
     }
-    const originalChannels = websocket.channels;
-    const sortedChannels = {};
-    for (const name of Object.keys(originalChannels).sort()) {
-        const channel = originalChannels[name];
-        if (!channel) {
-            continue;
-        }
-        let messages = channel.messages;
-        if (Array.isArray(messages)) {
-            messages = [...messages].sort((a, b) => {
-                const aName = a?.name ?? "";
-                const bName = b?.name ?? "";
-                return aName.localeCompare(bName);
-            });
+    const channels = websocket.channels.map((channel) => {
+        if (!channel || !Array.isArray(channel.messages)) {
+            return channel;
         }
-        sortedChannels[name] = {
+        const sortedMessages = [...channel.messages].sort((a, b) => {
+            const aName = a?.name ?? "";
+            const bName = b?.name ?? "";
+            return aName.localeCompare(bName);
+        });
+        return {
             ...channel,
-            ...(messages ? { messages } : {}),
+            messages: sortedMessages,
         };
-    }
-    websocket.channels = sortedChannels;
+    });
+    channels.sort((a, b) => {
+        const aName = a?.name ?? "";
+        const bName = b?.name ?? "";
+        return aName.localeCompare(bName);
+    });
+    websocket.channels = channels;
     return doc;
 }
 function normalizeGraphqlOperations(doc) {
@@ -86,20 +70,24 @@ function normalizeGraphqlOperations(doc) {
     }
     const protocols = doc.service.protocols;
     const graphql = protocols.graphql;
-    if (!graphql || !graphql.operations) {
+    if (!graphql) {
         return doc;
     }
-    const kinds = ["queries", "mutations", "subscriptions"];
+    const kinds = [
+        "queries",
+        "mutations",
+        "subscriptions",
+    ];
     for (const kind of kinds) {
-        const bucket = graphql.operations[kind];
-        if (!bucket || typeof bucket !== "object") {
+        const ops = graphql[kind];
+        if (!Array.isArray(ops)) {
             continue;
         }
-        const sorted = {};
-        for (const name of Object.keys(bucket).sort()) {
-            sorted[name] = bucket[name];
-        }
-        graphql.operations[kind] = sorted;
+        graphql[kind] = [...ops].sort((a, b) => {
+            const aName = a?.name ?? "";
+            const bName = b?.name ?? "";
+            return aName.localeCompare(bName);
+        });
     }
     return doc;
 }
@@ -112,5 +100,5 @@ function normalizeGraphqlOperations(doc) {
  */
 export function normalizeUniSpec(doc, _options = {}) {
     const normalized = normalizeValue(doc);
-    return normalizeWebSocket(normalizeGraphqlOperations(normalizeRestPaths(normalized)));
+    return normalizeWebSocket(normalizeGraphqlOperations(normalizeRestRoutes(normalized)));
 }

package/dist/types/index.d.ts

@@ -1,37 +1,87 @@
-export interface UniSpecGraphQLSchema {
-    sdl?: string;
-}
-export interface UniSpecGraphQLOperations {
-    queries?: Record<string, unknown>;
-    mutations?: Record<string, unknown>;
-    subscriptions?: Record<string, unknown>;
+export interface UniSpecGraphQLOperation {
+    name: string;
+    description?: string;
+    deprecated?: boolean;
+    deprecationReason?: string;
 }
 export interface UniSpecGraphQLProtocol {
-    schema?: UniSpecGraphQLSchema;
-    operations?: UniSpecGraphQLOperations;
-    extensions?: Record<string, unknown>;
+    schema?: string;
+    queries?: UniSpecGraphQLOperation[];
+    mutations?: UniSpecGraphQLOperation[];
+    subscriptions?: UniSpecGraphQLOperation[];
+}
+export interface UniSpecSecurityRequirement extends Array<string> {
 }
 export interface UniSpecWebSocketMessage {
-    name?: string;
-    summary?: string;
+    name: string;
     description?: string;
-    payload?: unknown;
-    extensions?: Record<string, unknown>;
+    schemaRef?: string;
 }
 export interface UniSpecWebSocketChannel {
-    summary?: string;
-    title?: string;
+    name: string;
     description?: string;
-    direction?: string;
+    direction?: "publish" | "subscribe" | "both";
     messages?: UniSpecWebSocketMessage[];
+    security?: UniSpecSecurityRequirement[];
     extensions?: Record<string, unknown>;
 }
 export interface UniSpecWebSocketProtocol {
-    channels?: Record<string, UniSpecWebSocketChannel>;
-    extensions?: Record<string, unknown>;
+    channels?: UniSpecWebSocketChannel[];
+    securitySchemes?: Record<string, Record<string, unknown>>;
+}
+export interface UniSpecRestParameter {
+    name: string;
+    description?: string;
+    required?: boolean;
+    schemaRef?: string;
+}
+export interface UniSpecRestMediaType {
+    schemaRef?: string;
+}
+export interface UniSpecRestContent {
+    [mediaType: string]: UniSpecRestMediaType;
+}
+export interface UniSpecRestRequestBody {
+    description?: string;
+    required?: boolean;
+    content?: UniSpecRestContent;
+}
+export interface UniSpecRestResponse {
+    description?: string;
+    content?: UniSpecRestContent;
+}
+export interface UniSpecRestRoute {
+    name?: string;
+    summary?: string;
+    description?: string;
+    path: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    pathParams?: UniSpecRestParameter[];
+    queryParams?: UniSpecRestParameter[];
+    headers?: UniSpecRestParameter[];
+    requestBody?: UniSpecRestRequestBody;
+    responses?: Record<string, UniSpecRestResponse>;
+    security?: UniSpecSecurityRequirement[];
+}
+export interface UniSpecRestProtocol {
+    routes?: UniSpecRestRoute[];
+    securitySchemes?: Record<string, Record<string, unknown>>;
+}
+export interface UniSpecSchemaDefinition {
+    jsonSchema: Record<string, unknown>;
+}
+export interface UniSpecSchemas {
+    [name: string]: UniSpecSchemaDefinition;
+}
+export interface UniSpecEnvironment {
+    name: string;
+    baseUrl: string;
+    region?: string;
+    labels?: Record<string, string>;
+    isDefault?: boolean;
 }
 export interface UniSpecServiceProtocols {
-    rest?: unknown;
+    rest?: UniSpecRestProtocol;
     graphql?: UniSpecGraphQLProtocol;
     websocket?: UniSpecWebSocketProtocol;
 }
@@ -39,7 +89,13 @@ export interface UniSpecService {
     name: string;
     title?: string;
     description?: string;
+    version?: string;
+    owner?: string;
+    tags?: string[];
+    links?: Record<string, string>;
     protocols?: UniSpecServiceProtocols;
+    schemas?: UniSpecSchemas;
+    environments?: UniSpecEnvironment[];
 }
 export interface UniSpecDocument {
     unispecVersion: string;
@@ -55,3 +111,88 @@ export interface ValidationResult {
     valid: boolean;
     errors: ValidationError[];
 }
+export type UniSpecTestProtocol = "rest" | "graphql" | "websocket";
+export interface UniSpecTestTarget {
+    protocol: UniSpecTestProtocol;
+    operationId: string;
+    environment?: string;
+}
+export interface UniSpecRestTestParams {
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+}
+export interface UniSpecRestTestRequest {
+    params?: UniSpecRestTestParams;
+    headers?: Record<string, unknown>;
+    body?: unknown;
+    authProfile?: string;
+}
+export type UniSpecRestExpectedStatus = number | number[];
+export type UniSpecRestBodyExpectationMode = "exact" | "contains" | "schemaOnly" | "snapshot";
+export interface UniSpecRestBodyExpectation {
+    mode?: UniSpecRestBodyExpectationMode;
+    json?: unknown;
+    schemaRef?: string;
+}
+export interface UniSpecRestTestExpect {
+    status: UniSpecRestExpectedStatus;
+    headers?: Record<string, unknown>;
+    body?: UniSpecRestBodyExpectation;
+}
+export interface UniSpecGraphQLTestRequest {
+    operationName?: string;
+    query: string;
+    variables?: Record<string, unknown>;
+    headers?: Record<string, unknown>;
+    authProfile?: string;
+}
+export interface UniSpecGraphQLTestExpect {
+    data?: unknown;
+    errors?: unknown;
+    bodyMode?: string;
+}
+export type UniSpecWebSocketTestMessageActionType = "send" | "expect";
+export interface UniSpecWebSocketTestMessageAction {
+    type: UniSpecWebSocketTestMessageActionType;
+    messageName: string;
+    payload?: unknown;
+}
+export interface UniSpecWebSocketTestRequest {
+    channel: string;
+    direction?: "publish" | "subscribe" | "both";
+    messages?: UniSpecWebSocketTestMessageAction[];
+    authProfile?: string;
+}
+export interface UniSpecWebSocketTestExpect {
+    messages?: UniSpecWebSocketTestMessageAction[];
+    timeoutMs?: number;
+}
+export interface UniSpecTestRequest {
+    rest?: UniSpecRestTestRequest;
+    graphql?: UniSpecGraphQLTestRequest;
+    websocket?: UniSpecWebSocketTestRequest;
+}
+export interface UniSpecTestExpect {
+    rest?: UniSpecRestTestExpect;
+    graphql?: UniSpecGraphQLTestExpect;
+    websocket?: UniSpecWebSocketTestExpect;
+}
+export interface UniSpecTestCase {
+    name: string;
+    description?: string;
+    target: UniSpecTestTarget;
+    request: UniSpecTestRequest;
+    expect: UniSpecTestExpect;
+    tags?: string[];
+    extensions?: Record<string, unknown>;
+}
+export interface UniSpecTestsDocument {
+    uniSpecTestsVersion: string;
+    target: {
+        serviceName: string;
+        serviceVersion?: string;
+        environment?: string;
+    };
+    tests: UniSpecTestCase[];
+    extensions?: Record<string, unknown>;
+}

package/dist/types/index.js

@@ -1 +1,2 @@
+// GraphQL protocol types
 export {};

package/dist/validator/index.d.ts

@@ -1,7 +1,11 @@
-import { UniSpecDocument, ValidationResult } from "../types";
+import { UniSpecDocument, UniSpecTestsDocument, ValidationResult } from "../types";
 export interface ValidateOptions {
 }
 /**
  * Validate a UniSpec document against the UniSpec JSON Schema.
  */
 export declare function validateUniSpec(doc: UniSpecDocument, _options?: ValidateOptions): Promise<ValidationResult>;
+/**
+ * Validate a UniSpec Tests document against the UniSpec Tests JSON Schema.
+ */
+export declare function validateUniSpecTests(doc: UniSpecTestsDocument, _options?: ValidateOptions): Promise<ValidationResult>;

package/dist/validator/index.js

@@ -1,18 +1,22 @@
 import Ajv2020 from "ajv/dist/2020.js";
-import { createRequire } from "module";
+import fs from "fs";
+import path from "path";
 import { unispec as unispecSchema, manifest as unispecManifest } from "@unispechq/unispec-schema";
-const require = createRequire(import.meta.url);
 const ajv = new Ajv2020({
     allErrors: true,
     strict: true,
 });
+// Register minimal URI format to satisfy UniSpec schemas (service.environments[*].baseUrl)
+ajv.addFormat("uri", true);
 // Register all UniSpec subschemas so that Ajv can resolve internal $ref links
 try {
-    const schemaRootPath = require.resolve("@unispechq/unispec-schema");
-    const schemaDir = schemaRootPath.replace(/index\.(cjs|mjs|js)$/u, "schema/");
+    const schemaDir = path.join(process.cwd(), "node_modules", "@unispechq", "unispec-schema", "schema");
     const types = unispecManifest?.types ?? {};
     const typeSchemaPaths = Object.values(types).map((rel) => String(rel));
-    const loadedTypeSchemas = typeSchemaPaths.map((relPath) => require(schemaDir + relPath));
+    const loadedTypeSchemas = typeSchemaPaths
+        .map((relPath) => path.join(schemaDir, relPath))
+        .filter((filePath) => fs.existsSync(filePath))
+        .map((filePath) => JSON.parse(fs.readFileSync(filePath, "utf8")));
     ajv.addSchema(loadedTypeSchemas);
 }
 catch {
@@ -20,6 +24,7 @@ catch {
     // parts of the schema that do not rely on those $ref references.
 }
 const validateFn = ajv.compile(unispecSchema);
+let validateTestsFn;
 function mapAjvErrors(errors) {
     if (!errors)
         return [];
@@ -45,3 +50,25 @@ export async function validateUniSpec(doc, _options = {}) {
         errors: mapAjvErrors(validateFn.errors),
     };
 }
+/**
+ * Validate a UniSpec Tests document against the UniSpec Tests JSON Schema.
+ */
+export async function validateUniSpecTests(doc, _options = {}) {
+    if (!validateTestsFn) {
+        const schemaDir = path.join(process.cwd(), "node_modules", "@unispechq", "unispec-schema", "schema");
+        const testsSchemaPath = path.join(schemaDir, "unispec-tests.schema.json");
+        const testsSchema = JSON.parse(fs.readFileSync(testsSchemaPath, "utf8"));
+        validateTestsFn = ajv.compile(testsSchema);
+    }
+    const valid = validateTestsFn(doc);
+    if (valid) {
+        return {
+            valid: true,
+            errors: [],
+        };
+    }
+    return {
+        valid: false,
+        errors: mapAjvErrors(validateTestsFn.errors),
+    };
+}