@unispechq/unispec-core 0.2.0 → 0.2.3

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 === "/protocols/rest/routes" ||
+            basePath === "/protocols/websocket/channels" ||
+            basePath === "/protocols/graphql/queries" ||
+            basePath === "/protocols/graphql/mutations" ||
+            basePath === "/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("/protocols/rest/routes/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected shape: ["protocols", "rest", "routes", index]
+    if (segments[0] !== "protocols" || segments[1] !== "rest" || segments[2] !== "routes") {
+        return change;
+    }
+    const index = segments[3];
+    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("/protocols/websocket/channels/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected base: ["protocols","websocket","channels", channelIndex, ...]
+    if (segments[0] !== "protocols" || segments[1] !== "websocket" || segments[2] !== "channels") {
+        return change;
+    }
+    const channelIndex = segments[3];
+    const next = segments[4];
+    const annotated = {
+        ...change,
+        protocol: "websocket",
+    };
+    if (typeof channelIndex === "undefined") {
+        return annotated;
+    }
+    // Channel-level changes: /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: /protocols/websocket/channels/{index}/messages/{msgIndex}
+    if (next === "messages") {
+        const messageIndex = segments[5];
+        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("/protocols/graphql/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected: ["protocols","graphql", kind, index, ...]
+    if (segments[0] !== "protocols" || segments[1] !== "graphql") {
+        return change;
+    }
+    const opKind = segments[2];
+    const index = segments[3];
+    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.protocols) {
+        return doc;
+    }
+    const protocols = doc.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.protocols) {
+        return doc;
+    }
+    const protocols = doc.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.protocols) {
+        return doc;
+    }
+    const protocols = doc.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,92 @@
+"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 docForValidation = {
+        unispecVersion: "0.0.0",
+        service: {
+            name: doc.name,
+            description: doc.description,
+            version: doc.version,
+            protocols: doc.protocols,
+            schemas: doc.schemas,
+        },
+        extensions: doc.extensions,
+    };
+    const valid = validateFn(docForValidation);
+    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,21 +1,14 @@
 export function toOpenAPI(doc) {
-    const service = doc.service;
-    const rest = (service.protocols?.rest ?? {});
+    const rest = (doc.protocols?.rest ?? {});
     const info = {
-        title: service.title ?? service.name,
-        description: service.description,
+        title: doc.name,
+        description: doc.description,
     };
-    // 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 servers = [];
     const paths = {};
     const components = {};
-    // Map service.schemas into OpenAPI components.schemas
-    const schemas = (service.schemas ?? {});
+    // Map doc.schemas into OpenAPI components.schemas
+    const schemas = (doc.schemas ?? {});
     const componentsSchemas = {};
     for (const [name, def] of Object.entries(schemas)) {
         componentsSchemas[name] = def.jsonSchema;
@@ -140,14 +133,13 @@ export function toGraphQLSDL(doc) {
     // via a Query field. This does not attempt to interpret the full GraphQL
     // protocol structure yet, but provides a stable, deterministic SDL shape
     // based on top-level UniSpec document fields.
-    const graphql = doc.service.protocols?.graphql;
+    const graphql = doc.protocols?.graphql;
     const customSDL = graphql?.schema;
     if (typeof customSDL === "string" && customSDL.trim()) {
         return { sdl: customSDL };
     }
-    const service = doc.service;
-    const title = service.title ?? service.name;
-    const description = service.description ?? "";
+    const title = doc.name;
+    const description = doc.description ?? "";
     const lines = [];
     if (title || description) {
         lines.push("\"\"");
@@ -175,8 +167,7 @@ export function toWebSocketModel(doc) {
     // It exposes service metadata, a normalized list of channels and the raw
     // websocket protocol object, while also embedding the original UniSpec
     // document under a technical key for debugging and introspection.
-    const service = doc.service;
-    const websocket = (service.protocols?.websocket ?? {});
+    const websocket = (doc.protocols?.websocket ?? {});
     const channelsArray = Array.isArray(websocket.channels) ? websocket.channels : [];
     const channels = [...channelsArray]
         .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""))
@@ -190,9 +181,9 @@ export function toWebSocketModel(doc) {
     }));
     return {
         service: {
-            name: service.name,
-            title: service.title,
-            description: service.description,
+            name: doc.name,
+            title: undefined,
+            description: doc.description,
         },
         channels,
         rawProtocol: websocket,

package/dist/diff/index.js

@@ -37,11 +37,11 @@ function diffValues(oldVal, newVal, basePath, out) {
     // 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";
+        const isNamedCollection = basePath === "/protocols/rest/routes" ||
+            basePath === "/protocols/websocket/channels" ||
+            basePath === "/protocols/graphql/queries" ||
+            basePath === "/protocols/graphql/mutations" ||
+            basePath === "/protocols/graphql/subscriptions";
         if (isNamedCollection) {
             const oldByName = new Map();
             const newByName = new Map();
@@ -113,15 +113,15 @@ function diffValues(oldVal, newVal, basePath, out) {
     });
 }
 function annotateRestChange(change) {
-    if (!change.path.startsWith("/service/protocols/rest/routes/")) {
+    if (!change.path.startsWith("/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") {
+    // Expected shape: ["protocols", "rest", "routes", index]
+    if (segments[0] !== "protocols" || segments[1] !== "rest" || segments[2] !== "routes") {
         return change;
     }
-    const index = segments[4];
+    const index = segments[3];
     if (typeof index === "undefined") {
         return change;
     }
@@ -140,16 +140,16 @@ function annotateRestChange(change) {
     return annotated;
 }
 function annotateWebSocketChange(change) {
-    if (!change.path.startsWith("/service/protocols/websocket/channels/")) {
+    if (!change.path.startsWith("/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") {
+    // Expected base: ["protocols","websocket","channels", channelIndex, ...]
+    if (segments[0] !== "protocols" || segments[1] !== "websocket" || segments[2] !== "channels") {
         return change;
     }
-    const channelIndex = segments[4];
-    const next = segments[5];
+    const channelIndex = segments[3];
+    const next = segments[4];
     const annotated = {
         ...change,
         protocol: "websocket",
@@ -157,7 +157,7 @@ function annotateWebSocketChange(change) {
     if (typeof channelIndex === "undefined") {
         return annotated;
     }
-    // Channel-level changes: /service/protocols/websocket/channels/{index}
+    // Channel-level changes: /protocols/websocket/channels/{index}
     if (!next) {
         if (change.description === "Item removed" || change.description === "Field removed") {
             annotated.kind = "websocket.channel.removed";
@@ -169,9 +169,9 @@ function annotateWebSocketChange(change) {
         }
         return annotated;
     }
-    // Message-level changes: /service/protocols/websocket/channels/{index}/messages/{msgIndex}
+    // Message-level changes: /protocols/websocket/channels/{index}/messages/{msgIndex}
     if (next === "messages") {
-        const messageIndex = segments[6];
+        const messageIndex = segments[5];
         if (typeof messageIndex === "undefined") {
             return annotated;
         }
@@ -187,16 +187,16 @@ function annotateWebSocketChange(change) {
     return annotated;
 }
 function annotateGraphQLChange(change) {
-    if (!change.path.startsWith("/service/protocols/graphql/")) {
+    if (!change.path.startsWith("/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") {
+    // Expected: ["protocols","graphql", kind, index, ...]
+    if (segments[0] !== "protocols" || segments[1] !== "graphql") {
         return change;
     }
-    const opKind = segments[3];
-    const index = segments[4];
+    const opKind = segments[2];
+    const index = segments[3];
     if (!opKind || typeof index === "undefined") {
         return change;
     }