@unispechq/unispec-core 0.3.0 → 0.3.2

package/dist/cjs/diff/annotators.js

@@ -4,6 +4,10 @@ exports.annotateRestChange = annotateRestChange;
 exports.annotateWebSocketChange = annotateWebSocketChange;
 exports.annotateGraphQLChange = annotateGraphQLChange;
 function annotateRestChange(change) {
+    // Add defensive check for null/undefined path
+    if (!change.path || typeof change.path !== "string") {
+        return change;
+    }
     if (!change.path.startsWith("/service/protocols/rest/routes/")) {
         return change;
     }
@@ -40,6 +44,10 @@ function annotateRestChange(change) {
     return annotated;
 }
 function annotateWebSocketChange(change) {
+    // Add defensive check for null/undefined path
+    if (!change.path || typeof change.path !== "string") {
+        return change;
+    }
     if (!change.path.startsWith("/service/protocols/websocket/channels/")) {
         return change;
     }
@@ -90,6 +98,10 @@ function annotateWebSocketChange(change) {
     return annotated;
 }
 function annotateGraphQLChange(change) {
+    // Add defensive check for null/undefined path
+    if (!change.path || typeof change.path !== "string") {
+        return change;
+    }
     if (!change.path.startsWith("/service/protocols/graphql/")) {
         return change;
     }
@@ -114,19 +126,34 @@ function annotateGraphQLChange(change) {
         ...change,
         protocol: "graphql",
     };
-    if (change.description === "Item removed") {
-        annotated.kind = "graphql.operation.removed";
+    // Create operation-specific annotations
+    const singularMap = {
+        queries: "query",
+        mutations: "mutation",
+        subscriptions: "subscription"
+    };
+    const operationKind = `graphql.${singularMap[operationType]}`;
+    // Check for specific changes first, then general ones
+    if (change.path.includes("/returnType") &&
+        change.description === "Value changed") {
+        // Changing return type is breaking
+        annotated.kind = `${operationKind}.return_type_changed`;
         annotated.severity = "breaking";
     }
-    else if (change.description === "Item added") {
-        annotated.kind = "graphql.operation.added";
-        annotated.severity = "non-breaking";
+    else if (change.path.includes("/args") &&
+        (change.description === "Item added" || change.description === "Item removed")) {
+        // Argument changes
+        const action = change.description === "Item added" ? "added" : "removed";
+        annotated.kind = `${operationKind}.argument_${action}`;
+        annotated.severity = action === "added" ? "non-breaking" : "breaking";
     }
-    else if (change.path.includes("/returnType") &&
-        change.description === "Value changed") {
-        // Changing return type is breaking
-        annotated.kind = "graphql.operation.return_type_changed";
+    else if (change.description === "Item removed") {
+        annotated.kind = `${operationKind}.removed`;
         annotated.severity = "breaking";
     }
+    else if (change.description === "Item added") {
+        annotated.kind = `${operationKind}.added`;
+        annotated.severity = "non-breaking";
+    }
     return annotated;
 }

package/dist/cjs/src/cache/cache-factory.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCacheManager = createCacheManager;
+exports.createNamedCacheManager = createNamedCacheManager;
+exports.getManagersStats = getManagersStats;
+exports.destroyManagers = destroyManagers;
+exports.clearTestRegistry = clearTestRegistry;
+const cache_manager_1 = require("./cache-manager.js");
+/**
+ * Simple registry for test cleanup (minimal, not persistent global state)
+ */
+const testRegistry = new Map();
+/**
+ * Create a new isolated cache manager instance.
+ * @param options - Cache configuration options
+ * @returns New cache manager instance
+ */
+function createCacheManager(options) {
+    return new cache_manager_1.UniSpecCacheManager(options);
+}
+/**
+ * Create a named cache manager instance with simple registry.
+ * @param name - Instance name for identification
+ * @param options - Cache configuration options
+ * @returns Cache manager instance
+ */
+function createNamedCacheManager(name = "default", options) {
+    // For testing, keep simple registry to enable cleanup
+    if (testRegistry.has(name)) {
+        const existing = testRegistry.get(name);
+        if (existing) {
+            existing.destroy(); // Cleanup existing instance
+        }
+    }
+    const manager = new cache_manager_1.UniSpecCacheManager(options);
+    manager._name = name; // Store name for debugging
+    testRegistry.set(name, manager); // Add to registry for cleanup
+    return manager;
+}
+/**
+ * Get cache manager statistics for multiple instances.
+ * @param managers - Array of cache manager instances
+ * @returns Statistics for all provided managers
+ */
+function getManagersStats(managers) {
+    const stats = {};
+    for (const [index, manager] of managers.entries()) {
+        const name = manager._name ||
+            `manager_${index}`;
+        stats[name] = manager.getStats();
+    }
+    return stats;
+}
+/**
+ * Destroy multiple cache manager instances.
+ * @param managers - Array of cache manager instances to destroy
+ */
+function destroyManagers(managers) {
+    for (const manager of managers) {
+        manager.destroy();
+    }
+}
+/**
+ * Clear test registry (for testing only).
+ * @internal
+ */
+function clearTestRegistry() {
+    for (const manager of testRegistry.values()) {
+        manager.destroy();
+    }
+    testRegistry.clear();
+}

package/dist/cjs/src/cache/cache-manager.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UniSpecCacheManager = void 0;
+const constants_1 = require("./constants.js");
+const lru_cache_1 = require("./lru-cache.js");
+/**
+ * Cache manager for UniSpec operations.
+ */
+class UniSpecCacheManager {
+    constructor(options = {}) {
+        this.cleanupInterval = null;
+        this.validationCache = new lru_cache_1.LRUCache({
+            ...options,
+            maxSize: options.maxSize || constants_1.CACHE_CONSTANTS.VALIDATION_MAX_SIZE,
+        });
+        this.normalizationCache = new lru_cache_1.LRUCache({
+            ...options,
+            maxSize: options.maxSize || constants_1.CACHE_CONSTANTS.NORMALIZATION_MAX_SIZE,
+        });
+        this.diffCache = new lru_cache_1.LRUCache({
+            ...options,
+            maxSize: options.maxSize || constants_1.CACHE_CONSTANTS.DIFF_MAX_SIZE,
+        });
+        // Only start cleanup if not in test environment
+        if (process.env.NODE_ENV !== "test") {
+            this.startCleanup();
+        }
+    }
+    /**
+     * Get cached validation result asynchronously.
+     */
+    async getValidationResult(documentHash) {
+        return await this.validationCache.get(documentHash);
+    }
+    /**
+     * Cache validation result asynchronously.
+     */
+    async setValidationResult(documentHash, result) {
+        await this.validationCache.set(documentHash, result);
+    }
+    /**
+     * Get cached normalization result asynchronously.
+     */
+    async getNormalizationResult(documentHash) {
+        return await this.normalizationCache.get(documentHash);
+    }
+    /**
+     * Cache normalization result asynchronously.
+     */
+    async setNormalizationResult(documentHash, result) {
+        await this.normalizationCache.set(documentHash, result);
+    }
+    /**
+     * Get cached diff result asynchronously.
+     */
+    async getDiffResult(docsHash) {
+        return await this.diffCache.get(docsHash);
+    }
+    /**
+     * Cache diff result asynchronously.
+     */
+    async setDiffResult(docsHash, result) {
+        await this.diffCache.set(docsHash, result);
+    }
+    /**
+     * Get comprehensive cache statistics.
+     */
+    getStats() {
+        const validationStats = this.validationCache.getStats();
+        const normalizationStats = this.normalizationCache.getStats();
+        const diffStats = this.diffCache.getStats();
+        const total = {
+            size: validationStats.size + normalizationStats.size + diffStats.size,
+            hits: validationStats.hits + normalizationStats.hits + diffStats.hits,
+            misses: validationStats.misses + normalizationStats.misses + diffStats.misses,
+            hitRate: 0,
+        };
+        const totalRequests = total.hits + total.misses;
+        total.hitRate = totalRequests > 0 ? total.hits / totalRequests : 0;
+        return {
+            validation: validationStats,
+            normalization: normalizationStats,
+            diff: diffStats,
+            total,
+        };
+    }
+    /**
+     * Clear all caches.
+     */
+    clearAll() {
+        this.validationCache.clear();
+        this.normalizationCache.clear();
+        this.diffCache.clear();
+    }
+    /**
+     * Start automatic cleanup interval.
+     */
+    startCleanup() {
+        try {
+            this.cleanupInterval = setInterval(() => {
+                try {
+                    this.validationCache.cleanup();
+                    this.normalizationCache.cleanup();
+                    this.diffCache.cleanup();
+                }
+                catch (error) {
+                    console.error(constants_1.CACHE_MESSAGES.CLEANUP_ERROR, error);
+                    // Continue running cleanup even if one cache fails
+                }
+            }, constants_1.CACHE_CONSTANTS.CLEANUP_INTERVAL);
+        }
+        catch (error) {
+            console.error(constants_1.CACHE_MESSAGES.CLEANUP_START_ERROR, error);
+            // Cache will still work without automatic cleanup
+        }
+    }
+    /**
+     * Stop automatic cleanup.
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.clearAll();
+    }
+}
+exports.UniSpecCacheManager = UniSpecCacheManager;

package/dist/cjs/src/cache/constants.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Cache configuration constants.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_MESSAGES = exports.CACHE_CONSTANTS = void 0;
+exports.CACHE_CONSTANTS = {
+    // Default cache sizes
+    DEFAULT_MAX_SIZE: 100,
+    VALIDATION_MAX_SIZE: 50,
+    NORMALIZATION_MAX_SIZE: 30,
+    DIFF_MAX_SIZE: 20,
+    // TTL values (in milliseconds)
+    DEFAULT_TTL: 5 * 60 * 1000, // 5 minutes
+    CLEANUP_INTERVAL: 60000, // 1 minute
+    // Hash configuration
+    HASH_GOLDEN_RATIO: 2654435761,
+    HASH_BASE: 31,
+    HASH_MASK: 0xffffffff,
+};
+exports.CACHE_MESSAGES = {
+    CLEANUP_ERROR: "Cache cleanup error",
+    CLEANUP_START_ERROR: "Failed to start cleanup interval",
+    CACHE_WILL_CONTINUE: "Cache will still work without automatic cleanup",
+};

package/dist/cjs/src/cache/hash-utils.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDocumentHash = generateDocumentHash;
+exports.generateDiffHash = generateDiffHash;
+const hashing_1 = require("./hashing.js");
+/**
+ * Generate a hash for a UniSpec document for caching purposes.
+ * Uses optimized hashing for better performance and collision resistance.
+ */
+async function generateDocumentHash(document) {
+    return await (0, hashing_1.generateOptimizedDocumentHash)(document);
+}
+/**
+ * Generate a hash for two documents (for diff caching).
+ * Uses optimized diff hashing with better collision resistance.
+ */
+async function generateDiffHash(oldDoc, newDoc) {
+    return await (0, hashing_1.generateOptimizedDiffHash)(oldDoc, newDoc);
+}

package/dist/cjs/src/cache/hashing.js

@@ -0,0 +1,230 @@
+"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.generateOptimizedDocumentHash = generateOptimizedDocumentHash;
+exports.generateOptimizedDiffHash = generateOptimizedDiffHash;
+exports.simpleHash = simpleHash;
+exports.stableStringify = stableStringify;
+const constants_1 = require("../cache/constants.js");
+/**
+ * Secure document hashing utilities using Web Crypto API.
+ */
+/**
+ * Secure hash using Web Crypto API (SHA-256) or Node.js crypto.
+ * Fallback to FNV-1a only if both crypto APIs are unavailable.
+ */
+async function secureHash(str) {
+    // Try Web Crypto API first (browser environments)
+    if (typeof crypto !== "undefined" && crypto.subtle) {
+        try {
+            const encoder = new TextEncoder();
+            const data = encoder.encode(str);
+            const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+            const hashArray = Array.from(new Uint8Array(hashBuffer));
+            return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+        }
+        catch (error) {
+            console.warn("Web Crypto API failed, trying Node.js crypto:", error);
+        }
+    }
+    // Try Node.js crypto API (server environments)
+    try {
+        // Dynamic import for Node.js crypto to avoid browser compatibility issues
+        const crypto = await Promise.resolve().then(() => __importStar(require("node:crypto")));
+        const hash = crypto.createHash("sha256");
+        hash.update(str, "utf8");
+        return hash.digest("hex");
+    }
+    catch (error) {
+        console.warn("Node.js crypto API failed, falling back to FNV-1a:", error);
+    }
+    // Last resort: FNV-1a algorithm (non-cryptographic, for compatibility only)
+    console.warn("Using FNV-1a fallback hash - consider installing crypto support");
+    return fnv1aHashFallback(str).toString();
+}
+/**
+ * FNV-1a fallback hash function (non-cryptographic, for compatibility).
+ */
+function fnv1aHashFallback(str) {
+    let hash = 2166136261; // FNV offset basis
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = (hash * 16777619) & constants_1.CACHE_CONSTANTS.HASH_MASK; // FNV prime
+    }
+    return hash;
+}
+/**
+ * Generate a secure hash for a document using optimized sorting and Web Crypto API.
+ */
+async function generateOptimizedDocumentHash(document) {
+    // Use optimized stable stringification
+    const str = stableStringify(document);
+    // Use secure hash for better distribution and collision resistance
+    const hash = await secureHash(str);
+    // Add length and type prefix for additional collision resistance
+    const typePrefix = getDocumentTypePrefix(document);
+    const combined = `${hash}_${str.length}_${typePrefix}`;
+    // Create final hash with combined string
+    const finalHash = await secureHash(combined);
+    return `${finalHash.slice(0, 16)}_${str.length}`;
+}
+/**
+ * Default configuration for stable stringification.
+ */
+const DEFAULT_STRINGIFY_CONFIG = {
+    maxDepth: 100,
+    maxKeys: 10000,
+    handleCircular: true,
+    handleDeepObjects: true,
+};
+/**
+ * Optimized stable stringification that avoids recursion depth issues.
+ */
+function stableStringify(obj, config = {}, depth = 0, visited = new WeakSet()) {
+    const finalConfig = { ...DEFAULT_STRINGIFY_CONFIG, ...config };
+    // Prevent infinite recursion
+    if (depth > finalConfig.maxDepth) {
+        return `"[MAX_DEPTH_REACHED:${depth}]"`;
+    }
+    // Handle circular references
+    if (finalConfig.handleCircular && obj && typeof obj === "object") {
+        if (visited.has(obj)) {
+            return `"[CIRCULAR_REFERENCE:${obj.constructor?.name || "Object"}]"`;
+        }
+        visited.add(obj);
+    }
+    // Handle primitives
+    if (obj === null || typeof obj !== "object") {
+        return JSON.stringify(obj);
+    }
+    // Handle special object types
+    if (obj instanceof Date) {
+        return obj.toISOString();
+    }
+    if (obj instanceof RegExp) {
+        return `"[REGEX:${obj.toString()}]"`;
+    }
+    if (obj instanceof Error) {
+        return `"[ERROR:${obj.name}:${obj.message}]"`;
+    }
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(obj)) {
+        return `"[BUFFER:${obj.toString("base64")}]"`;
+    }
+    // Handle Array
+    if (Array.isArray(obj)) {
+        if (obj.length > finalConfig.maxKeys) {
+            return `"[ARRAY_TOO_LARGE:${obj.length}]"`;
+        }
+        const elements = obj.map((item, index) => {
+            try {
+                return stableStringify(item, finalConfig, depth + 1, visited);
+            }
+            catch (error) {
+                return `"[ERROR_AT_INDEX_${index}:${error instanceof Error ? error.message : String(error)}]"`;
+            }
+        });
+        return `[${elements.join(",")}]`;
+    }
+    // Handle Object
+    if (typeof obj === "object") {
+        const objRecord = obj;
+        const keys = Object.keys(objRecord);
+        if (keys.length > finalConfig.maxKeys) {
+            return `"[OBJECT_TOO_LARGE:${keys.length}]"`;
+        }
+        const sortedKeys = keys.sort();
+        const pairs = [];
+        for (const key of sortedKeys) {
+            try {
+                const value = stableStringify(objRecord[key], finalConfig, depth + 1, visited);
+                pairs.push(`"${key}":${value}`);
+            }
+            catch (error) {
+                pairs.push(`"${key}":"[ERROR:${error instanceof Error ? error.message : String(error)}]"`);
+            }
+        }
+        return `{${pairs.join(",")}}`;
+    }
+    return "{}";
+}
+/**
+ * Get a numeric prefix based on document type to reduce collisions.
+ */
+function getDocumentTypePrefix(document) {
+    if (!document || typeof document !== "object")
+        return 0;
+    const doc = document;
+    // Check for UniSpec document
+    if (doc.unispecVersion)
+        return 1;
+    if (doc.uniSpecTestsVersion)
+        return 2;
+    if (doc.version && doc.services)
+        return 3;
+    // Check for common patterns
+    if (Array.isArray(document))
+        return 4;
+    if (doc.$schema)
+        return 5;
+    if (doc.type)
+        return typeof doc.type === "string" ? doc.type.charCodeAt(0) || 6 : 6;
+    return 7;
+}
+/**
+ * Generate a secure hash for two documents (for diff caching) with optimized collision resistance.
+ */
+async function generateOptimizedDiffHash(oldDoc, newDoc) {
+    const oldHash = await generateOptimizedDocumentHash(oldDoc);
+    const newHash = await generateOptimizedDocumentHash(newDoc);
+    // Combine hashes using order-sensitive operation
+    const combined = `${oldHash}:${newHash}`;
+    // Hash the combined string to get final result
+    const finalHash = await secureHash(combined);
+    return `${finalHash.slice(0, 16)}_${oldHash.length}_${newHash.length}`;
+}
+/**
+ * Simple hash for small objects (keys, strings) using built-in hash.
+ * Kept for backward compatibility but consider using secureHash for new code.
+ */
+function simpleHash(str) {
+    let hash = 5381; // DJB2 hash initial value
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) + hash + char) & constants_1.CACHE_CONSTANTS.HASH_MASK;
+    }
+    // Convert to hex and pad to 8 characters
+    const hex = hash.toString(16);
+    return hex.padStart(8, "0").slice(-8);
+}

package/dist/cjs/src/cache/index.js

@@ -0,0 +1,24 @@
+"use strict";
+// Constants and messages
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LRUCache = exports.generateDocumentHash = exports.generateDiffHash = exports.CACHE_MESSAGES = exports.CACHE_CONSTANTS = exports.UniSpecCacheManager = exports.getManagersStats = exports.destroyManagers = exports.createNamedCacheManager = exports.createCacheManager = exports.clearTestRegistry = void 0;
+// Cache factory
+var cache_factory_1 = require("./cache-factory.js");
+Object.defineProperty(exports, "clearTestRegistry", { enumerable: true, get: function () { return cache_factory_1.clearTestRegistry; } });
+Object.defineProperty(exports, "createCacheManager", { enumerable: true, get: function () { return cache_factory_1.createCacheManager; } });
+Object.defineProperty(exports, "createNamedCacheManager", { enumerable: true, get: function () { return cache_factory_1.createNamedCacheManager; } });
+Object.defineProperty(exports, "destroyManagers", { enumerable: true, get: function () { return cache_factory_1.destroyManagers; } });
+Object.defineProperty(exports, "getManagersStats", { enumerable: true, get: function () { return cache_factory_1.getManagersStats; } });
+// Cache manager
+var cache_manager_1 = require("./cache-manager.js");
+Object.defineProperty(exports, "UniSpecCacheManager", { enumerable: true, get: function () { return cache_manager_1.UniSpecCacheManager; } });
+var constants_1 = require("./constants.js");
+Object.defineProperty(exports, "CACHE_CONSTANTS", { enumerable: true, get: function () { return constants_1.CACHE_CONSTANTS; } });
+Object.defineProperty(exports, "CACHE_MESSAGES", { enumerable: true, get: function () { return constants_1.CACHE_MESSAGES; } });
+// Hash utilities
+var hash_utils_1 = require("./hash-utils.js");
+Object.defineProperty(exports, "generateDiffHash", { enumerable: true, get: function () { return hash_utils_1.generateDiffHash; } });
+Object.defineProperty(exports, "generateDocumentHash", { enumerable: true, get: function () { return hash_utils_1.generateDocumentHash; } });
+// Core cache implementation
+var lru_cache_1 = require("./lru-cache.js");
+Object.defineProperty(exports, "LRUCache", { enumerable: true, get: function () { return lru_cache_1.LRUCache; } });