@unispechq/unispec-core 0.3.2 → 0.3.4

package/dist/src/cache/hashing.js

@@ -1,193 +0,0 @@
-import { CACHE_CONSTANTS } from "../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 import("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) & CACHE_CONSTANTS.HASH_MASK; // FNV prime
-    }
-    return hash;
-}
-/**
- * Generate a secure hash for a document using optimized sorting and Web Crypto API.
- */
-export 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.
- */
-export 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.
- */
-export 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) & CACHE_CONSTANTS.HASH_MASK;
-    }
-    // Convert to hex and pad to 8 characters
-    const hex = hash.toString(16);
-    return hex.padStart(8, "0").slice(-8);
-}
-// Export stableStringify for use in hash-utils
-export { stableStringify };

package/dist/src/cache/index.d.ts

@@ -1,6 +0,0 @@
-export { clearTestRegistry, createCacheManager, createNamedCacheManager, destroyManagers, getManagersStats, } from "./cache-factory.js";
-export { UniSpecCacheManager } from "./cache-manager.js";
-export { CACHE_CONSTANTS, CACHE_MESSAGES } from "./constants.js";
-export { generateDiffHash, generateDocumentHash, } from "./hash-utils.js";
-export { LRUCache } from "./lru-cache.js";
-export type { CacheEntry, CacheOptions, CacheSize, CacheStats, TTL, } from "./types.js";

package/dist/src/cache/index.js

@@ -1,10 +0,0 @@
-// Constants and messages
-// Cache factory
-export { clearTestRegistry, createCacheManager, createNamedCacheManager, destroyManagers, getManagersStats, } from "./cache-factory.js";
-// Cache manager
-export { UniSpecCacheManager } from "./cache-manager.js";
-export { CACHE_CONSTANTS, CACHE_MESSAGES } from "./constants.js";
-// Hash utilities
-export { generateDiffHash, generateDocumentHash, } from "./hash-utils.js";
-// Core cache implementation
-export { LRUCache } from "./lru-cache.js";

package/dist/src/cache/lru-cache.d.ts

@@ -1,44 +0,0 @@
-import type { CacheOptions, CacheStats } from "./types.js";
-/**
- * Simple LRU (Least Recently Used) cache implementation.
- */
-export declare class LRUCache<T> {
-    private cache;
-    private maxSize;
-    private ttl;
-    private enableStats;
-    private stats;
-    constructor(options?: CacheOptions);
-    /**
-     * Get a value from the cache asynchronously.
-     */
-    get(key: string): Promise<T | undefined>;
-    /**
-     * Set a value in the cache asynchronously.
-     */
-    set(key: string, value: T): Promise<void>;
-    /**
-     * Delete a value from the cache.
-     */
-    delete(key: string): boolean;
-    /**
-     * Clear all entries from the cache.
-     */
-    clear(): void;
-    /**
-     * Get cache statistics.
-     */
-    getStats(): CacheStats;
-    /**
-     * Check if an entry is expired.
-     */
-    private isExpired;
-    /**
-     * Update hit rate statistics.
-     */
-    private updateHitRate;
-    /**
-     * Clean up expired entries.
-     */
-    cleanup(): number;
-}

package/dist/src/cache/lru-cache.js

@@ -1,140 +0,0 @@
-import { CACHE_CONSTANTS } from "./constants.js";
-/**
- * Simple LRU (Least Recently Used) cache implementation.
- */
-export class LRUCache {
-    constructor(options = {}) {
-        this.cache = new Map();
-        this.maxSize = options.maxSize || CACHE_CONSTANTS.DEFAULT_MAX_SIZE;
-        this.ttl = options.ttl || CACHE_CONSTANTS.DEFAULT_TTL;
-        this.enableStats = options.enableStats || false;
-        this.stats = {
-            hits: 0,
-            misses: 0,
-            size: 0,
-            hitRate: 0,
-            evictions: 0,
-        };
-    }
-    /**
-     * Get a value from the cache asynchronously.
-     */
-    async get(key) {
-        const entry = this.cache.get(key);
-        if (!entry) {
-            if (this.enableStats) {
-                this.stats.misses++;
-                this.updateHitRate();
-            }
-            return undefined;
-        }
-        // Check TTL
-        if (this.isExpired(entry)) {
-            this.cache.delete(key);
-            if (this.enableStats) {
-                this.stats.misses++;
-                this.stats.size--;
-                this.updateHitRate();
-            }
-            return undefined;
-        }
-        // Update access info
-        entry.accessCount++;
-        entry.lastAccessed = Date.now();
-        // Move to end (most recently used)
-        this.cache.delete(key);
-        this.cache.set(key, entry);
-        if (this.enableStats) {
-            this.stats.hits++;
-            this.updateHitRate();
-        }
-        return entry.value;
-    }
-    /**
-     * Set a value in the cache asynchronously.
-     */
-    async set(key, value) {
-        // Remove existing entry if present
-        if (this.cache.has(key)) {
-            this.cache.delete(key);
-        }
-        // Evict oldest entries if cache is full
-        while (this.cache.size >= this.maxSize) {
-            const oldestKey = this.cache.keys().next().value;
-            if (oldestKey) {
-                this.cache.delete(oldestKey);
-                if (this.enableStats) {
-                    this.stats.evictions++;
-                    this.stats.size--;
-                }
-            }
-            else {
-                break;
-            }
-        }
-        const entry = {
-            value,
-            timestamp: Date.now(),
-            accessCount: 1,
-            lastAccessed: Date.now(),
-        };
-        this.cache.set(key, entry);
-        if (this.enableStats) {
-            this.stats.size++;
-        }
-    }
-    /**
-     * Delete a value from the cache.
-     */
-    delete(key) {
-        const deleted = this.cache.delete(key);
-        if (deleted && this.enableStats) {
-            this.stats.size--;
-        }
-        return deleted;
-    }
-    /**
-     * Clear all entries from the cache.
-     */
-    clear() {
-        this.cache.clear();
-        if (this.enableStats) {
-            this.stats.size = 0;
-        }
-    }
-    /**
-     * Get cache statistics.
-     */
-    getStats() {
-        return { ...this.stats };
-    }
-    /**
-     * Check if an entry is expired.
-     */
-    isExpired(entry) {
-        return Date.now() - entry.timestamp > this.ttl;
-    }
-    /**
-     * Update hit rate statistics.
-     */
-    updateHitRate() {
-        const total = this.stats.hits + this.stats.misses;
-        this.stats.hitRate = total > 0 ? this.stats.hits / total : 0;
-    }
-    /**
-     * Clean up expired entries.
-     */
-    cleanup() {
-        let cleaned = 0;
-        for (const [key, entry] of this.cache.entries()) {
-            if (this.isExpired(entry)) {
-                this.cache.delete(key);
-                cleaned++;
-                if (this.enableStats) {
-                    this.stats.size--;
-                }
-            }
-        }
-        return cleaned;
-    }
-}

package/dist/src/cache/types.d.ts

@@ -1,24 +0,0 @@
-/**
- * Cache interfaces and types.
- */
-export interface CacheOptions {
-    maxSize?: number;
-    ttl?: number;
-    enableStats?: boolean;
-}
-export interface CacheEntry<T> {
-    value: T;
-    timestamp: number;
-    accessCount: number;
-    lastAccessed: number;
-}
-export interface CacheStats {
-    hits: number;
-    misses: number;
-    size: number;
-    hitRate: number;
-    evictions: number;
-}
-export type CacheSize = typeof CACHE_CONSTANTS.DEFAULT_MAX_SIZE | typeof CACHE_CONSTANTS.VALIDATION_MAX_SIZE | typeof CACHE_CONSTANTS.NORMALIZATION_MAX_SIZE | typeof CACHE_CONSTANTS.DIFF_MAX_SIZE;
-export type TTL = typeof CACHE_CONSTANTS.DEFAULT_TTL | typeof CACHE_CONSTANTS.CLEANUP_INTERVAL;
-import type { CACHE_CONSTANTS } from "./constants.js";

package/dist/src/cache/types.js

@@ -1,4 +0,0 @@
-/**
- * Cache interfaces and types.
- */
-export {};

package/dist/src/diff/annotators.d.ts

@@ -1,4 +0,0 @@
-import type { UniSpecChange } from "./types.js";
-export declare function annotateRestChange(change: UniSpecChange): UniSpecChange;
-export declare function annotateWebSocketChange(change: UniSpecChange): UniSpecChange;
-export declare function annotateGraphQLChange(change: UniSpecChange): UniSpecChange;

package/dist/src/diff/annotators.js

@@ -1,155 +0,0 @@
-export 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;
-    }
-    const segments = change.path.split("/").filter(Boolean);
-    // Expected shape: ["service", "protocols", "rest", "routes", routeName, ...]
-    if (segments[0] !== "service" ||
-        segments[1] !== "protocols" ||
-        segments[2] !== "rest" ||
-        segments[3] !== "routes") {
-        return change;
-    }
-    const routeName = segments[4];
-    if (typeof routeName === "undefined") {
-        return change;
-    }
-    const annotated = {
-        ...change,
-        protocol: "rest",
-    };
-    if (change.description === "Item removed") {
-        annotated.kind = "rest.route.removed";
-        annotated.severity = "breaking";
-    }
-    else if (change.description === "Item added") {
-        annotated.kind = "rest.route.added";
-        annotated.severity = "non-breaking";
-    }
-    else if (change.path.includes("/required") &&
-        change.description === "Value changed") {
-        // Changing required field from false to true is breaking
-        annotated.kind = "rest.parameter.required_changed";
-        annotated.severity = "breaking";
-    }
-    return annotated;
-}
-export 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;
-    }
-    const segments = change.path.split("/").filter(Boolean);
-    // Expected base: ["service","protocols","websocket","channels", channelName, ...]
-    if (segments[0] !== "service" ||
-        segments[1] !== "protocols" ||
-        segments[2] !== "websocket" ||
-        segments[3] !== "channels") {
-        return change;
-    }
-    const channelName = segments[4];
-    const next = segments[5];
-    const annotated = {
-        ...change,
-        protocol: "websocket",
-    };
-    if (typeof channelName === "undefined") {
-        return annotated;
-    }
-    // Channel-level changes: /service/protocols/websocket/channels/{channelName}
-    if (!next) {
-        if (change.description === "Item removed") {
-            annotated.kind = "websocket.channel.removed";
-            annotated.severity = "breaking";
-        }
-        else if (change.description === "Item added") {
-            annotated.kind = "websocket.channel.added";
-            annotated.severity = "non-breaking";
-        }
-        return annotated;
-    }
-    // Message-level changes: /service/protocols/websocket/channels/{channelName}/messages/{messageName}
-    if (next === "messages") {
-        const messageName = segments[6];
-        if (typeof messageName === "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;
-}
-export 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;
-    }
-    const segments = change.path.split("/").filter(Boolean);
-    // Expected: ["service","protocols","graphql", operationType, operationName, ...]
-    if (segments[0] !== "service" ||
-        segments[1] !== "protocols" ||
-        segments[2] !== "graphql") {
-        return change;
-    }
-    const operationType = segments[3];
-    const operationName = segments[4];
-    if (!operationType || typeof operationName === "undefined") {
-        return change;
-    }
-    if (operationType !== "queries" &&
-        operationType !== "mutations" &&
-        operationType !== "subscriptions") {
-        return change;
-    }
-    const annotated = {
-        ...change,
-        protocol: "graphql",
-    };
-    // 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.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.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/src/diff/change-reports.d.ts

@@ -1,37 +0,0 @@
-import type { EnhancedDiffResult, EnhancedUniSpecChange } from "./enhanced-diff.js";
-export interface ReportOptions {
-    format: "markdown" | "html" | "json";
-    includeSuggestions?: boolean;
-    includeExamples?: boolean;
-    groupByRisk?: boolean;
-    groupByProtocol?: boolean;
-    title?: string;
-    versionInfo?: {
-        oldVersion?: string;
-        newVersion?: string;
-        comparisonDate?: string;
-    };
-}
-export interface ChangeReport {
-    title: string;
-    summary: {
-        totalChanges: number;
-        breakingChanges: number;
-        compatibilityScore: number;
-        migrationEffort: string;
-    };
-    sections: ReportSection[];
-}
-export interface ReportSection {
-    title: string;
-    changes: EnhancedUniSpecChange[];
-    summary: string;
-}
-/**
- * Generate a comprehensive change report.
- *
- * @param diff - Enhanced diff result
- * @param options - Report generation options
- * @returns Formatted report in the specified format
- */
-export declare function generateChangeReport(diff: EnhancedDiffResult, options: ReportOptions): string;