@unispechq/unispec-core 0.2.10 → 0.2.12

package/dist/cjs/converters/index.js

@@ -4,16 +4,16 @@ exports.toOpenAPI = toOpenAPI;
 exports.toGraphQLSDL = toGraphQLSDL;
 exports.toWebSocketModel = toWebSocketModel;
 function toOpenAPI(doc) {
-    const rest = (doc.protocols?.rest ?? {});
+    const rest = (doc.service?.protocols?.rest ?? {});
     const info = {
-        title: doc.name,
-        description: doc.description,
+        title: doc.service.name,
+        description: doc.service.description,
     };
     const servers = [];
     const paths = {};
     const components = {};
-    // Map doc.schemas into OpenAPI components.schemas
-    const schemas = (doc.schemas ?? {});
+    // Map doc.service.schemas into OpenAPI components.schemas
+    const schemas = (doc.service?.schemas ?? {});
     const componentsSchemas = {};
     for (const [name, def] of Object.entries(schemas)) {
         componentsSchemas[name] = def.jsonSchema;
@@ -138,13 +138,16 @@ 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.protocols?.graphql;
+    const graphql = doc.service?.protocols?.graphql;
     const customSDL = graphql?.schema;
     if (typeof customSDL === "string" && customSDL.trim()) {
-        return { sdl: customSDL };
+        return {
+            sdl: customSDL,
+            url: graphql?.url
+        };
     }
-    const title = doc.name;
-    const description = doc.description ?? "";
+    const title = doc.service.name;
+    const description = doc.service.description ?? "";
     const lines = [];
     if (title || description) {
         lines.push("\"\"");
@@ -165,14 +168,17 @@ function toGraphQLSDL(doc) {
     lines.push("  _serviceInfo: String!\n");
     lines.push("}");
     const sdl = lines.join("\n");
-    return { sdl };
+    return {
+        sdl,
+        url: graphql?.url
+    };
 }
 function toWebSocketModel(doc) {
     // Base WebSocket model intended for a modern, dashboard-oriented UI.
     // 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 websocket = (doc.protocols?.websocket ?? {});
+    const websocket = (doc.service?.protocols?.websocket ?? {});
     const channelsArray = Array.isArray(websocket.channels) ? websocket.channels : [];
     const channels = [...channelsArray]
         .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""))
@@ -186,10 +192,11 @@ function toWebSocketModel(doc) {
     }));
     return {
         service: {
-            name: doc.name,
+            name: doc.service.name,
             title: undefined,
-            description: doc.description,
+            description: doc.service.description,
         },
+        url: websocket.url,
         channels,
         rawProtocol: websocket,
         "x-unispec-ws": doc,

package/dist/cjs/diff/index.js

@@ -221,12 +221,25 @@ function annotateGraphQLChange(change) {
     return annotated;
 }
 /**
- * Compute a structural diff between two UniSpec documents.
+ * Compare two UniSpec documents and return detected changes.
  *
- * 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.
+ * This function performs a deep comparison between two UniSpec documents
+ * and categorizes changes by severity and protocol. Useful for:
+ * - API change detection in CI/CD pipelines
+ * - Breaking change analysis
+ * - Version compatibility checks
+ * - Audit trails for API evolution
+ *
+ * Features:
+ * - Detects added/removed fields at any depth
+ * - Special handling for named collections (routes, operations, channels)
+ * - Severity classification: "breaking" | "non-breaking" | "unknown"
+ * - Protocol categorization: "rest" | "graphql" | "websocket"
+ * - Detailed change descriptions with JSON paths
+ *
+ * @param oldDoc - The previous version of the UniSpec document
+ * @param newDoc - The current version of the UniSpec document
+ * @returns Object containing all detected changes
  */
 function diffUniSpec(oldDoc, newDoc) {
     const changes = [];

package/dist/cjs/loader/index.js

@@ -1,22 +1,77 @@
 "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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadUniSpec = loadUniSpec;
 /**
  * Load a UniSpec document from a raw input value.
- * Currently supports:
+ * Supports:
  * - JavaScript objects (treated as already parsed UniSpec)
  * - JSON strings
- *
- * YAML and filesystem helpers will be added later, keeping this API stable.
+ * - YAML strings
  */
-async function loadUniSpec(input, _options = {}) {
+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);
+        // Try JSON first (faster and more common)
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch (jsonError) {
+            // If JSON fails, try YAML
+            try {
+                // Dynamic import to avoid bundling yaml parser if not needed
+                const yamlModule = await Promise.resolve().then(() => __importStar(require("js-yaml")));
+                if (!yamlModule.load) {
+                    throw new Error("js-yaml module not available");
+                }
+                const doc = yamlModule.load(trimmed, {
+                    filename: options.filename,
+                    // Basic security options
+                    schema: yamlModule.FAILSAFE_SCHEMA
+                });
+                return doc;
+            }
+            catch (yamlError) {
+                const jsonMsg = jsonError instanceof Error ? jsonError.message : String(jsonError);
+                const yamlMsg = yamlError instanceof Error ? yamlError.message : String(yamlError);
+                throw new Error(`Failed to parse input as JSON or YAML. JSON error: ${jsonMsg}. YAML error: ${yamlMsg}`);
+            }
+        }
     }
     return input;
 }

package/dist/cjs/normalizer/index.js

@@ -19,10 +19,10 @@ function normalizeValue(value) {
     return value;
 }
 function normalizeRestRoutes(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const rest = protocols.rest;
     if (!rest || !Array.isArray(rest.routes)) {
         return doc;
@@ -37,10 +37,10 @@ function normalizeRestRoutes(doc) {
     return doc;
 }
 function normalizeWebSocket(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const websocket = protocols.websocket;
     if (!websocket || !Array.isArray(websocket.channels)) {
         return doc;
@@ -68,10 +68,10 @@ function normalizeWebSocket(doc) {
     return doc;
 }
 function normalizeGraphqlOperations(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const graphql = protocols.graphql;
     if (!graphql) {
         return doc;
@@ -97,9 +97,23 @@ function normalizeGraphqlOperations(doc) {
 /**
  * Normalize a UniSpec document into a canonical, deterministic form.
  *
+ * This function ensures consistent representation of UniSpec documents
+ * by sorting object keys and protocol-specific structures in a predictable order.
+ * Useful for:
+ * - Generating stable diffs between documents
+ * - Creating consistent output for caching
+ * - Ensuring reproducible builds
+ *
  * Current behavior:
- * - Recursively sorts object keys lexicographically.
- * - Preserves values as-is.
+ * - Recursively sorts object keys lexicographically
+ * - Sorts REST routes by name or path+method
+ * - Sorts GraphQL operations by name within each operation type
+ * - Sorts WebSocket channels and messages by name
+ * - Preserves all values as-is
+ *
+ * @param doc - The UniSpec document to normalize
+ * @param options - Normalization options (currently unused, reserved for future)
+ * @returns The normalized UniSpec document
  */
 function normalizeUniSpec(doc, _options = {}) {
     const normalized = normalizeValue(doc);

package/dist/cjs/schemas/index.js

@@ -32,21 +32,24 @@ function resolveSchemaRef(doc, ref) {
     const name = normalizeSchemaRef(ref);
     if (!name)
         return undefined;
-    return doc.schemas?.[name];
+    return doc.service?.schemas?.[name];
 }
 function registerSchema(doc, name, jsonSchema) {
-    if (!doc.schemas) {
-        doc.schemas = {};
+    if (!doc.service) {
+        doc.service = { name: "" };
+    }
+    if (!doc.service.schemas) {
+        doc.service.schemas = {};
     }
     const definition = {
         jsonSchema,
     };
-    doc.schemas[name] = definition;
+    doc.service.schemas[name] = definition;
     return definition;
 }
 function updateSchemaRefs(doc, mapping) {
-    const rest = doc.protocols?.rest;
-    const websocket = doc.protocols?.websocket;
+    const rest = doc.service?.protocols?.rest;
+    const websocket = doc.service?.protocols?.websocket;
     if (rest?.routes) {
         for (const route of rest.routes) {
             for (const params of [route.pathParams, route.queryParams, route.headers]) {
@@ -106,13 +109,13 @@ function updateSchemaRefs(doc, mapping) {
     }
 }
 function dedupeSchemas(doc) {
-    if (!doc.schemas)
+    if (!doc.service?.schemas)
         return;
-    const names = Object.keys(doc.schemas);
+    const names = Object.keys(doc.service.schemas);
     const hashToName = new Map();
     const renameMap = {};
     for (const name of names) {
-        const schema = doc.schemas[name];
+        const schema = doc.service.schemas[name];
         const hash = stableStringify(schema?.jsonSchema ?? null);
         const existing = hashToName.get(hash);
         if (!existing) {
@@ -126,6 +129,6 @@ function dedupeSchemas(doc) {
         return;
     updateSchemaRefs(doc, renameMap);
     for (const dup of duplicates) {
-        delete doc.schemas[dup];
+        delete doc.service.schemas[dup];
     }
 }