@unispechq/unispec-core 0.1.2 → 0.2.2

package/dist/cjs/diff/index.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffUniSpec = diffUniSpec;
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === "[object Object]";
+}
+function diffValues(oldVal, newVal, basePath, out) {
+    if (oldVal === newVal) {
+        return;
+    }
+    // Both plain objects → recurse by keys
+    if (isPlainObject(oldVal) && isPlainObject(newVal)) {
+        const oldKeys = new Set(Object.keys(oldVal));
+        const newKeys = new Set(Object.keys(newVal));
+        // Removed keys
+        for (const key of oldKeys) {
+            if (!newKeys.has(key)) {
+                out.push({
+                    path: `${basePath}/${key}`,
+                    description: "Field removed",
+                    severity: "unknown",
+                });
+            }
+        }
+        // Added / changed keys
+        for (const key of newKeys) {
+            const childPath = `${basePath}/${key}`;
+            if (!oldKeys.has(key)) {
+                out.push({
+                    path: childPath,
+                    description: "Field added",
+                    severity: "unknown",
+                });
+                continue;
+            }
+            diffValues(oldVal[key], newVal[key], childPath, out);
+        }
+        return;
+    }
+    // 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}`;
+            if (i >= oldVal.length) {
+                out.push({
+                    path: childPath,
+                    description: "Item added",
+                    severity: "unknown",
+                });
+            }
+            else if (i >= newVal.length) {
+                out.push({
+                    path: childPath,
+                    description: "Item removed",
+                    severity: "unknown",
+                });
+            }
+            else {
+                diffValues(oldVal[i], newVal[i], childPath, out);
+            }
+        }
+        return;
+    }
+    // Primitive or mismatched types → treat as value change
+    out.push({
+        path: basePath,
+        description: "Value changed",
+        severity: "unknown",
+    });
+}
+function annotateRestChange(change) {
+    if (!change.path.startsWith("/service/protocols/rest/routes/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // 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 annotated = {
+        ...change,
+        protocol: "rest",
+    };
+    if (change.description === "Item removed" || change.description === "Field removed") {
+        annotated.kind = "rest.route.removed";
+        annotated.severity = "breaking";
+    }
+    else if (change.description === "Item added" || change.description === "Field added") {
+        annotated.kind = "rest.route.added";
+        annotated.severity = "non-breaking";
+    }
+    return annotated;
+}
+function annotateWebSocketChange(change) {
+    if (!change.path.startsWith("/service/protocols/websocket/channels/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected base: ["service","protocols","websocket","channels", channelIndex, ...]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "websocket" || segments[3] !== "channels") {
+        return change;
+    }
+    const channelIndex = segments[4];
+    const next = segments[5];
+    const annotated = {
+        ...change,
+        protocol: "websocket",
+    };
+    if (typeof channelIndex === "undefined") {
+        return annotated;
+    }
+    // Channel-level changes: /service/protocols/websocket/channels/{index}
+    if (!next) {
+        if (change.description === "Item removed" || change.description === "Field removed") {
+            annotated.kind = "websocket.channel.removed";
+            annotated.severity = "breaking";
+        }
+        else if (change.description === "Item added" || change.description === "Field added") {
+            annotated.kind = "websocket.channel.added";
+            annotated.severity = "non-breaking";
+        }
+        return annotated;
+    }
+    // Message-level changes: /service/protocols/websocket/channels/{index}/messages/{msgIndex}
+    if (next === "messages") {
+        const messageIndex = segments[6];
+        if (typeof messageIndex === "undefined") {
+            return annotated;
+        }
+        if (change.description === "Item removed") {
+            annotated.kind = "websocket.message.removed";
+            annotated.severity = "breaking";
+        }
+        else if (change.description === "Item added") {
+            annotated.kind = "websocket.message.added";
+            annotated.severity = "non-breaking";
+        }
+    }
+    return annotated;
+}
+function annotateGraphQLChange(change) {
+    if (!change.path.startsWith("/service/protocols/graphql/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // 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;
+    }
+    if (opKind !== "queries" && opKind !== "mutations" && opKind !== "subscriptions") {
+        return change;
+    }
+    const annotated = {
+        ...change,
+        protocol: "graphql",
+    };
+    if (change.description === "Item removed" || change.description === "Field removed") {
+        annotated.kind = "graphql.operation.removed";
+        annotated.severity = "breaking";
+    }
+    else if (change.description === "Item added" || change.description === "Field added") {
+        annotated.kind = "graphql.operation.added";
+        annotated.severity = "non-breaking";
+    }
+    return annotated;
+}
+/**
+ * Compute a structural diff between two UniSpec documents.
+ *
+ * Current behavior:
+ * - Tracks added, removed, and changed fields and array items.
+ * - Uses JSON Pointer-like paths rooted at "" (e.g., "/info/title").
+ * - Marks all changes with severity "unknown" for now.
+ */
+function diffUniSpec(oldDoc, newDoc) {
+    const changes = [];
+    diffValues(oldDoc, newDoc, "", changes);
+    const annotated = changes.map((change) => annotateWebSocketChange(annotateGraphQLChange(annotateRestChange(change))));
+    return { changes: annotated };
+}

package/dist/cjs/index.js

@@ -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/cjs/loader/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadUniSpec = loadUniSpec;
+/**
+ * Load a UniSpec document from a raw input value.
+ * Currently supports:
+ * - JavaScript objects (treated as already parsed UniSpec)
+ * - JSON strings
+ *
+ * YAML and filesystem helpers will be added later, keeping this API stable.
+ */
+async function loadUniSpec(input, _options = {}) {
+    if (typeof input === "string") {
+        const trimmed = input.trim();
+        if (!trimmed) {
+            throw new Error("Cannot load UniSpec: input string is empty");
+        }
+        // For now we assume JSON; YAML support will be added later.
+        return JSON.parse(trimmed);
+    }
+    return input;
+}

package/dist/cjs/normalizer/index.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeUniSpec = normalizeUniSpec;
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === "[object Object]";
+}
+function normalizeValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeValue(item));
+    }
+    if (isPlainObject(value)) {
+        const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+        const normalized = {};
+        for (const [key, val] of entries) {
+            normalized[key] = normalizeValue(val);
+        }
+        return normalized;
+    }
+    return value;
+}
+function normalizeRestRoutes(doc) {
+    if (!doc || !doc.service || !doc.service.protocols) {
+        return doc;
+    }
+    const protocols = doc.service.protocols;
+    const rest = protocols.rest;
+    if (!rest || !Array.isArray(rest.routes)) {
+        return doc;
+    }
+    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) {
+    if (!doc || !doc.service || !doc.service.protocols) {
+        return doc;
+    }
+    const protocols = doc.service.protocols;
+    const websocket = protocols.websocket;
+    if (!websocket || !Array.isArray(websocket.channels)) {
+        return doc;
+    }
+    const channels = websocket.channels.map((channel) => {
+        if (!channel || !Array.isArray(channel.messages)) {
+            return channel;
+        }
+        const sortedMessages = [...channel.messages].sort((a, b) => {
+            const aName = a?.name ?? "";
+            const bName = b?.name ?? "";
+            return aName.localeCompare(bName);
+        });
+        return {
+            ...channel,
+            messages: sortedMessages,
+        };
+    });
+    channels.sort((a, b) => {
+        const aName = a?.name ?? "";
+        const bName = b?.name ?? "";
+        return aName.localeCompare(bName);
+    });
+    websocket.channels = channels;
+    return doc;
+}
+function normalizeGraphqlOperations(doc) {
+    if (!doc || !doc.service || !doc.service.protocols) {
+        return doc;
+    }
+    const protocols = doc.service.protocols;
+    const graphql = protocols.graphql;
+    if (!graphql) {
+        return doc;
+    }
+    const kinds = [
+        "queries",
+        "mutations",
+        "subscriptions",
+    ];
+    for (const kind of kinds) {
+        const ops = graphql[kind];
+        if (!Array.isArray(ops)) {
+            continue;
+        }
+        graphql[kind] = [...ops].sort((a, b) => {
+            const aName = a?.name ?? "";
+            const bName = b?.name ?? "";
+            return aName.localeCompare(bName);
+        });
+    }
+    return doc;
+}
+/**
+ * Normalize a UniSpec document into a canonical, deterministic form.
+ *
+ * Current behavior:
+ * - Recursively sorts object keys lexicographically.
+ * - Preserves values as-is.
+ */
+function normalizeUniSpec(doc, _options = {}) {
+    const normalized = normalizeValue(doc);
+    return normalizeWebSocket(normalizeGraphqlOperations(normalizeRestRoutes(normalized)));
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/types/index.js

@@ -0,0 +1,3 @@
+"use strict";
+// GraphQL protocol types
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/validator/index.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateUniSpec = validateUniSpec;
+exports.validateUniSpecTests = validateUniSpecTests;
+const _2020_js_1 = __importDefault(require("ajv/dist/2020.js"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const unispec_schema_1 = require("@unispechq/unispec-schema");
+const ajv = new _2020_js_1.default({
+    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 schemaDir = path_1.default.join(process.cwd(), "node_modules", "@unispechq", "unispec-schema", "schema");
+    const types = unispec_schema_1.manifest?.types ?? {};
+    const typeSchemaPaths = Object.values(types).map((rel) => String(rel));
+    const loadedTypeSchemas = typeSchemaPaths
+        .map((relPath) => path_1.default.join(schemaDir, relPath))
+        .filter((filePath) => fs_1.default.existsSync(filePath))
+        .map((filePath) => JSON.parse(fs_1.default.readFileSync(filePath, "utf8")));
+    ajv.addSchema(loadedTypeSchemas);
+}
+catch {
+    // If subschemas cannot be loaded for some reason, validation will still work for
+    // parts of the schema that do not rely on those $ref references.
+}
+const validateFn = ajv.compile(unispec_schema_1.unispec);
+let validateTestsFn;
+function mapAjvErrors(errors) {
+    if (!errors)
+        return [];
+    return errors.map((error) => ({
+        message: error.message || "UniSpec validation error",
+        path: error.instancePath || error.schemaPath,
+        code: error.keyword,
+    }));
+}
+/**
+ * Validate a UniSpec document against the UniSpec JSON Schema.
+ */
+async function validateUniSpec(doc, _options = {}) {
+    const valid = validateFn(doc);
+    if (valid) {
+        return {
+            valid: true,
+            errors: [],
+        };
+    }
+    return {
+        valid: false,
+        errors: mapAjvErrors(validateFn.errors),
+    };
+}
+/**
+ * Validate a UniSpec Tests document against the UniSpec Tests JSON Schema.
+ */
+async function validateUniSpecTests(doc, _options = {}) {
+    if (!validateTestsFn) {
+        const schemaDir = path_1.default.join(process.cwd(), "node_modules", "@unispechq", "unispec-schema", "schema");
+        const testsSchemaPath = path_1.default.join(schemaDir, "unispec-tests.schema.json");
+        const testsSchema = JSON.parse(fs_1.default.readFileSync(testsSchemaPath, "utf8"));
+        validateTestsFn = ajv.compile(testsSchema);
+    }
+    const valid = validateTestsFn(doc);
+    if (valid) {
+        return {
+            valid: true,
+            errors: [],
+        };
+    }
+    return {
+        valid: false,
+        errors: mapAjvErrors(validateTestsFn.errors),
+    };
+}

package/dist/converters/index.js

@@ -1,22 +1,137 @@
 export function toOpenAPI(doc) {
     const service = doc.service;
-    const rest = service.protocols?.rest;
+    const rest = (service.protocols?.rest ?? {});
     const info = {
         title: service.title ?? service.name,
         description: service.description,
     };
-    const servers = rest?.servers ?? [];
-    const paths = rest?.paths ?? {};
-    // Transparently forward additional REST protocol fields into the OpenAPI document.
-    // This allows users to describe components, security, tags and other structures
-    // without forcing a specific REST model at the core layer.
-    const { servers: _omitServers, paths: _omitPaths, ...restExtras } = rest ?? {};
+    // Derive OpenAPI servers from UniSpec environments when available.
+    const servers = Array.isArray(service.environments)
+        ? service.environments.map((env) => ({
+            url: env.baseUrl,
+            description: env.name,
+        }))
+        : [];
+    const paths = {};
+    const components = {};
+    // Map service.schemas into OpenAPI components.schemas
+    const schemas = (service.schemas ?? {});
+    const componentsSchemas = {};
+    for (const [name, def] of Object.entries(schemas)) {
+        componentsSchemas[name] = def.jsonSchema;
+    }
+    if (Object.keys(componentsSchemas).length > 0) {
+        components.schemas = componentsSchemas;
+    }
+    // Helper to build a $ref into components.schemas when schemaRef is present.
+    function schemaRefToOpenAPI(schemaRef) {
+        if (!schemaRef) {
+            return {};
+        }
+        return { $ref: `#/components/schemas/${schemaRef}` };
+    }
+    // Build paths from REST routes.
+    if (Array.isArray(rest.routes)) {
+        for (const route of rest.routes) {
+            const pathItem = (paths[route.path] ?? {});
+            const method = route.method.toLowerCase();
+            const parameters = [];
+            // Path params
+            for (const param of route.pathParams ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "path",
+                    required: param.required ?? true,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Query params
+            for (const param of route.queryParams ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "query",
+                    required: param.required ?? false,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Header params
+            for (const param of route.headers ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "header",
+                    required: param.required ?? false,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Request body
+            let requestBody;
+            if (route.requestBody && route.requestBody.content) {
+                const content = {};
+                for (const [mediaType, media] of Object.entries(route.requestBody.content)) {
+                    content[mediaType] = {
+                        schema: schemaRefToOpenAPI(media.schemaRef),
+                    };
+                }
+                requestBody = {
+                    description: route.requestBody.description,
+                    required: route.requestBody.required,
+                    content,
+                };
+            }
+            // Responses
+            const responses = {};
+            for (const [status, resp] of Object.entries(route.responses ?? {})) {
+                const content = {};
+                if (resp.content) {
+                    for (const [mediaType, media] of Object.entries(resp.content)) {
+                        content[mediaType] = {
+                            schema: schemaRefToOpenAPI(media.schemaRef),
+                        };
+                    }
+                }
+                responses[status] = {
+                    description: resp.description ?? "",
+                    ...(Object.keys(content).length > 0 ? { content } : {}),
+                };
+            }
+            const operation = {
+                operationId: route.name,
+                summary: route.summary,
+                description: route.description,
+                ...(parameters.length > 0 ? { parameters } : {}),
+                responses: Object.keys(responses).length > 0 ? responses : { default: { description: "" } },
+            };
+            if (requestBody) {
+                operation.requestBody = requestBody;
+            }
+            // Security requirements
+            if (Array.isArray(route.security) && route.security.length > 0) {
+                operation.security = route.security.map((req) => {
+                    const obj = {};
+                    for (const schemeName of req) {
+                        obj[schemeName] = [];
+                    }
+                    return obj;
+                });
+            }
+            pathItem[method] = operation;
+            paths[route.path] = pathItem;
+        }
+    }
+    // Security schemes pass-through from REST protocol
+    const componentsSecuritySchemes = rest.securitySchemes ?? {};
+    if (Object.keys(componentsSecuritySchemes).length > 0) {
+        components.securitySchemes = componentsSecuritySchemes;
+    }
     return {
         openapi: "3.1.0",
         info,
         servers,
         paths,
-        ...restExtras,
+        ...(Object.keys(components).length > 0 ? { components } : {}),
         "x-unispec": doc,
     };
 }
@@ -26,7 +141,7 @@ export function toGraphQLSDL(doc) {
     // protocol structure yet, but provides a stable, deterministic SDL shape
     // based on top-level UniSpec document fields.
     const graphql = doc.service.protocols?.graphql;
-    const customSDL = graphql?.schema?.sdl;
+    const customSDL = graphql?.schema;
     if (typeof customSDL === "string" && customSDL.trim()) {
         return { sdl: customSDL };
     }
@@ -62,20 +177,17 @@ export function toWebSocketModel(doc) {
     // document under a technical key for debugging and introspection.
     const service = doc.service;
     const websocket = (service.protocols?.websocket ?? {});
-    const channelsRecord = (websocket && typeof websocket === "object" && websocket.channels && typeof websocket.channels === "object")
-        ? websocket.channels
-        : {};
-    const channels = Object.keys(channelsRecord).sort().map((name) => {
-        const channel = channelsRecord[name] ?? {};
-        return {
-            name,
-            summary: channel.summary ?? channel.title,
-            description: channel.description,
-            direction: channel.direction,
-            messages: channel.messages,
-            raw: channel,
-        };
-    });
+    const channelsArray = Array.isArray(websocket.channels) ? websocket.channels : [];
+    const channels = [...channelsArray]
+        .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""))
+        .map((channel) => ({
+        name: channel.name,
+        summary: undefined,
+        description: channel.description,
+        direction: channel.direction,
+        messages: channel.messages,
+        raw: channel,
+    }));
     return {
         service: {
             name: service.name,