@unispechq/unispec-core 0.2.9 → 0.2.11

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

@@ -17,6 +17,7 @@ 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("./schemas/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

@@ -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

@@ -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

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSchemaRef = resolveSchemaRef;
+exports.registerSchema = registerSchema;
+exports.dedupeSchemas = dedupeSchemas;
+function normalizeSchemaRef(ref) {
+    const trimmed = ref.trim();
+    if (trimmed.length === 0)
+        return "";
+    const withoutHash = trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
+    const parts = withoutHash.split("/").filter(Boolean);
+    return parts.length > 0 ? parts[parts.length - 1] : withoutHash;
+}
+function stableStringify(value) {
+    if (value === null)
+        return "null";
+    const t = typeof value;
+    if (t === "number" || t === "boolean")
+        return JSON.stringify(value);
+    if (t === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    if (t !== "object")
+        return JSON.stringify(value);
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const entries = keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+    return `{${entries.join(",")}}`;
+}
+function resolveSchemaRef(doc, ref) {
+    const name = normalizeSchemaRef(ref);
+    if (!name)
+        return undefined;
+    return doc.schemas?.[name];
+}
+function registerSchema(doc, name, jsonSchema) {
+    if (!doc.schemas) {
+        doc.schemas = {};
+    }
+    const definition = {
+        jsonSchema,
+    };
+    doc.schemas[name] = definition;
+    return definition;
+}
+function updateSchemaRefs(doc, mapping) {
+    const rest = doc.protocols?.rest;
+    const websocket = doc.protocols?.websocket;
+    if (rest?.routes) {
+        for (const route of rest.routes) {
+            for (const params of [route.pathParams, route.queryParams, route.headers]) {
+                if (!params)
+                    continue;
+                for (const p of params) {
+                    if (!p.schemaRef)
+                        continue;
+                    const key = normalizeSchemaRef(p.schemaRef);
+                    const next = mapping[key];
+                    if (next && next !== key)
+                        p.schemaRef = next;
+                }
+            }
+            const requestContent = route.requestBody?.content;
+            if (requestContent) {
+                for (const media of Object.values(requestContent)) {
+                    if (!media.schemaRef)
+                        continue;
+                    const key = normalizeSchemaRef(media.schemaRef);
+                    const next = mapping[key];
+                    if (next && next !== key)
+                        media.schemaRef = next;
+                }
+            }
+            const responses = route.responses;
+            if (responses) {
+                for (const resp of Object.values(responses)) {
+                    const respContent = resp.content;
+                    if (!respContent)
+                        continue;
+                    for (const media of Object.values(respContent)) {
+                        if (!media.schemaRef)
+                            continue;
+                        const key = normalizeSchemaRef(media.schemaRef);
+                        const next = mapping[key];
+                        if (next && next !== key)
+                            media.schemaRef = next;
+                    }
+                }
+            }
+        }
+    }
+    if (websocket?.channels) {
+        for (const channel of websocket.channels) {
+            if (!channel.messages)
+                continue;
+            for (const message of channel.messages) {
+                if (!message.schemaRef)
+                    continue;
+                const key = normalizeSchemaRef(message.schemaRef);
+                const next = mapping[key];
+                if (next && next !== key)
+                    message.schemaRef = next;
+            }
+        }
+    }
+}
+function dedupeSchemas(doc) {
+    if (!doc.schemas)
+        return;
+    const names = Object.keys(doc.schemas);
+    const hashToName = new Map();
+    const renameMap = {};
+    for (const name of names) {
+        const schema = doc.schemas[name];
+        const hash = stableStringify(schema?.jsonSchema ?? null);
+        const existing = hashToName.get(hash);
+        if (!existing) {
+            hashToName.set(hash, name);
+            continue;
+        }
+        renameMap[name] = existing;
+    }
+    const duplicates = Object.keys(renameMap);
+    if (duplicates.length === 0)
+        return;
+    updateSchemaRefs(doc, renameMap);
+    for (const dup of duplicates) {
+        delete doc.schemas[dup];
+    }
+}