@unispechq/unispec-core 0.2.13 → 0.3.0

package/README.md

@@ -1,187 +1,119 @@
-# UniSpec Core Platform
-**The official UniSpec Core Engine package — parser, validator, normalizer, diff engine, and converters for the UniSpec format**
+# UniSpec Core Engine
+
+**The official UniSpec Core Engine package — parser, validator, normalizer, diff engine for the UniSpec format**
 
 ---
 
-## 🚀 Overview
+## 🚀 Quick Overview
 
-**UniSpec Core Engine** is the central runtime package of the UniSpec ecosystem.  
-It implements the mechanics of the **UniSpec Format**: loading, JSON Schema validation, normalization, diffing, and conversion to other formats.
+**UniSpec Core Engine** is the central runtime package of the UniSpec ecosystem. It implements the mechanics of the **UniSpec Format**: loading, JSON Schema validation, normalization, and diffing.
 
 This repository contains **only the Core Engine**, which is consumed by other UniSpec platform components (CLI, Registry, Portal, adapters, SDKs) that live in separate repositories.
 
-Core Engine capabilities:
+### Core Capabilities
 
-- 🧠 **Core Engine** — parser, validator, normalizer, diff engine, converters  
-- 🔄 **Format conversion** — UniSpec → OpenAPI, UniSpec → GraphQL SDL, UniSpec → WebSocket channel models  
-- 🧩 **Shared types and utilities** — types and helper functions used by the CLI, adapters, Registry, and Portal  
+- 🧠 **Core Engine** — parser, validator, normalizer, diff engine  
+- 📋 **UniSpec Config** — configuration file support for multi-service setups  
+- 🧩 **Shared types and utilities** — types and helper functions used across the UniSpec ecosystem
 
-UniSpec is designed to unify documentation for:
+### Protocol Support
 
-- REST  
-- GraphQL  
-- WebSocket  
+UniSpec unifies documentation for:
+- REST APIs  
+- GraphQL APIs  
+- WebSocket APIs  
 - Event-driven APIs (future)  
-- Multi-service architectures  
-
----
-
-## 📦 Repository Structure
-
-```pgsql
-unispec-core/
-├─ src/
-│  ├─ loader/           # File loading (YAML/JSON → JS object)
-│  ├─ validator/        # JSON Schema validation
-│  ├─ normalizer/       # UniSpec structure normalization
-│  ├─ diff/             # Comparison of two UniSpec documents
-│  ├─ converters/       # OpenAPI, GraphQL SDL, WS, etc.
-│  ├─ types/            # UniSpec types/interfaces
-│  ├─ utils/            # Small helpers
-│  └─ index.ts          # Public API
-├─ tests/               # Unit tests
-├─ package.json
-└─ README.md
-```
+- Multi-service architectures
 
 ---
 
-## 🧠 Core Concepts
-
-### 📐 1. UniSpec Format  
-Defined in a separate repository: **`unispec-spec`**.  
-UniSpec Core Engine *implements* this format but does **not** define it.
-
-### 🧱 2. Core Engine  
-Located in this repository, under the `src/` directory.
-
-Core Engine provides:
-
-- YAML/JSON loader  
-- JSON Schema validator  
-– Normalizer → canonical UniSpec output (REST routes, GraphQL operations, WebSocket channels/messages)  
-– Diff engine (with basic breaking / non-breaking classification for REST, GraphQL and WebSocket)  
-– Converters:  
-  - UniSpec → OpenAPI (REST-centric)  
-  - UniSpec → GraphQL SDL  
-  - UniSpec → WebSocket channel models for dashboards  
-
-This is the foundation used by:
-
-- the CLI (in a separate repository/package)  
-- framework adapters  
-- Registry and Portal (as separate UniSpec platform services)  
-
-### 🌉 3. Protocol Coverage in Core
-
-At the level of the Core Engine, protocol support is intentionally minimal but deterministic:
-
-- **REST**  
-  - Typed REST surface defined by `service.protocols.rest.routes[]` and reusable `service.schemas`.  
-  - Normalizer orders routes by `name` (or `path + method`) for stable diffs.  
-  - Diff engine annotates route additions and removals with breaking/non-breaking severity.  
-  - Converter exposes REST as an OpenAPI 3.1 document built from routes, schemas and environments, while preserving the original UniSpec under `x-unispec`.
-
-- **GraphQL**  
-  - Typed protocol with `schema` (SDL string) and `queries`/`mutations`/`subscriptions` as operation lists.  
-  - Normalizer orders operation names within each bucket.  
-  - Diff engine annotates operation additions/removals as non-breaking/breaking.  
-  - Converter either passes through user-provided SDL or generates a minimal, deterministic SDL shell.
-
-- **WebSocket**  
-  - Typed protocol with channels and messages backed by reusable schemas and security schemes.  
-  - Normalizer orders channels by name and messages by `name` within each channel.  
-  - Diff engine annotates channel/message additions/removals as non-breaking/breaking changes.  
-  - Converter produces a dashboard-friendly model with service metadata, a normalized channel list and the raw protocol.
-
-### 💻 4. CLI (separate platform component)  
-The CLI uses UniSpec Core Engine for validation, conversion, and working with UniSpec specifications.
+## 🏁 Getting Started
 
-Example UniSpec CLI commands:
+### Installation
 
-```pgsql
-unispec validate
-unispec push
-unispec dev
-unispec open
-unispec diff
-unispec convert
+```bash
+npm install @unispechq/unispec-core
 ```
 
+### Basic Usage
 
-### 🗂 5. Registry API (separate service)  
-Stores UniSpec specs from multiple services and uses Core Engine for validation, normalization, and change analysis.  
-Effectively acts as the "system of record" for all APIs in the company.
+```javascript
+import { validateUniSpec, loadUniSpec } from '@unispechq/unispec-core';
 
-### 🌐 6. Portal Web + API (separate service)  
-API documentation portal built on top of UniSpec and Core Engine:
+// Load and validate a UniSpec document
+const spec = await loadUniSpec('./unispec.yaml');
+const result = await validateUniSpec(spec);
 
-- service catalog  
-- API endpoints  
-- schemas  
-- interactive playgrounds  
-- version comparison  
+if (result.valid) {
+  console.log('✅ Valid UniSpec document');
+} else {
+  console.log('❌ Validation errors:', result.errors);
+}
+```
 
 ---
 
-## 🛒 Use Cases
-
-### 🟦 Monolith mode (Swagger-like)  
-A backend service includes an adapter →  
-`/unispec.json` + `/docs` are served automatically.
-
-### 🟧 Microservice mode  
-Each service pushes its UniSpec into Registry →  
-Portal Web assembles your entire company's API landscape.
-
-### 🟩 Enterprise mode  
-Includes:
-
-- SSO / permissions  
-- RBAC  
-- auditing  
-- topology map  
-- advanced analytics  
-
-(Handled via private repos.)
+## 📚 Documentation
+
+### 📖 [Core Concepts](docs/core-concepts.md)
+- UniSpec format overview
+- Core Engine architecture  
+- Protocol coverage details
+- Platform components explanation
+- Use cases and deployment patterns
+
+### 💡 [Usage Examples](docs/usage-examples.md)
+- Document validation
+- Configuration support
+- Schema reference resolution
+- Enhanced diff analysis
+- Performance optimization
+- Error handling patterns
+
+### 🔧 [API Reference](docs/api.md)
+- Complete function documentation
+- Type definitions and interfaces
+- Configuration options
+- Error types and codes
+- Performance considerations
+
+### 🛠️ [Development Guide](docs/development.md)
+- Repository structure
+- Development setup
+- Testing guidelines
+- Build process
+- Contributing guidelines
+- Plugin development
 
 ---
 
-## 🏁 Getting Started
-
-### 1. Clone the repo
-
-```pgsql
-git clone https://github.com/unispec/unispec-core.git
-cd unispec-core
-```
-
-### 2. Install dependencies
+## 📦 Repository Structure
 
-```pgsql
-pnpm install
 ```
-
-### 3. Build all packages
-
-```pgsql
-pnpm build
+unispec-core/
+├─ src/
+│  ├─ loader/           # File loading with security
+│  ├─ validator/        # JSON Schema validation
+│  ├─ normalizer/       # Structure normalization
+│  ├─ diff/             # Enhanced comparison
+│  ├─ cache/            # LRU caching
+│  ├─ types/            # TypeScript interfaces
+│  └─ index.ts          # Public API
+├─ tests/               # Unit and integration tests
+├─ docs/                # Detailed documentation
+└─ scripts/             # Build and release scripts
 ```
 
-### 4. Run locally (dev mode)
-
 ---
 
 ## 🤝 Contributing
 
-Contributions are welcome!  
-Before contributing, please review:
+Contributions are welcome! Before contributing, please review:
 
-- `docs/development.md`
-- `.windsurfrules`
+- [Development Guide](docs/development.md)
+- [`.windsurfrules`](.windsurfrules)
 
 All core changes must comply with:
-
 - the UniSpec format from `unispec-spec`
 - compatibility rules  
 - test coverage  
@@ -189,19 +121,19 @@ All core changes must comply with:
 
 ---
 
-## Related Repositories
+## 📊 Related Repositories
 
 | Repository             | Purpose |
 |------------------------|---------|
 | `unispec-spec`         | UniSpec format definition (schemas, examples) |
 | `unispec-core`         | **This repo** — UniSpec Core Engine implementation |
 | `unispec-docs`         | Documentation site |
-| `unispec-js-adapters`  | Framework integrations (Express/Nest/Fastify) built on top of Core Engine |
-| `unispec-infra`        | Helm charts, Docker, Terraform for deploying the UniSpec platform |
+| `unispec-js-adapters`  | Framework integrations (Express/Nest/Fastify) |
+| `unispec-infra`        | Helm charts, Docker, Terraform for deployment |
 
 ---
 
-## License
+## 📄 License
 
 UniSpec Core Engine is open-source and free to use under the MIT License.
 
@@ -209,15 +141,8 @@ UniSpec Core Engine is open-source and free to use under the MIT License.
 
 ## 🔥 Summary
 
-`unispec-core` is the **heart of the UniSpec ecosystem** at the code level.  
-It provides the Core Engine used to:
-
-- validate  
-- normalize  
-- diff  
-- convert  
-- and integrate  
-
-API specifications in the UniSpec format.
+`unispec-core` is the **heart of the UniSpec ecosystem** at the code level. It provides the Core Engine used to validate, normalize, diff, and integrate API specifications in the UniSpec format.
 
 If you're building tools, adapters, or platform services that rely on UniSpec → **this is where the engine lives.**
+
+For detailed information, explore the [documentation](docs/) folder.

package/dist/cache/cache-factory.d.ts

@@ -0,0 +1,31 @@
+import { UniSpecCacheManager } from "./cache-manager.js";
+import type { CacheOptions } from "./types.js";
+/**
+ * Create a new isolated cache manager instance.
+ * @param options - Cache configuration options
+ * @returns New cache manager instance
+ */
+export declare function createCacheManager(options?: CacheOptions): UniSpecCacheManager;
+/**
+ * Create a named cache manager instance with simple registry.
+ * @param name - Instance name for identification
+ * @param options - Cache configuration options
+ * @returns Cache manager instance
+ */
+export declare function createNamedCacheManager(name?: string, options?: CacheOptions): UniSpecCacheManager;
+/**
+ * Get cache manager statistics for multiple instances.
+ * @param managers - Array of cache manager instances
+ * @returns Statistics for all provided managers
+ */
+export declare function getManagersStats(managers: UniSpecCacheManager[]): Record<string, ReturnType<UniSpecCacheManager["getStats"]>>;
+/**
+ * Destroy multiple cache manager instances.
+ * @param managers - Array of cache manager instances to destroy
+ */
+export declare function destroyManagers(managers: UniSpecCacheManager[]): void;
+/**
+ * Clear test registry (for testing only).
+ * @internal
+ */
+export declare function clearTestRegistry(): void;

package/dist/cache/cache-factory.js

@@ -0,0 +1,65 @@
+import { UniSpecCacheManager } from "./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
+ */
+export function createCacheManager(options) {
+    return new 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
+ */
+export 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 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
+ */
+export 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
+ */
+export function destroyManagers(managers) {
+    for (const manager of managers) {
+        manager.destroy();
+    }
+}
+/**
+ * Clear test registry (for testing only).
+ * @internal
+ */
+export function clearTestRegistry() {
+    for (const manager of testRegistry.values()) {
+        manager.destroy();
+    }
+    testRegistry.clear();
+}

package/dist/cache/cache-manager.d.ts

@@ -0,0 +1,62 @@
+import type { ValidationResult } from "../types/index.js";
+import type { CacheOptions, CacheStats } from "./types.js";
+/**
+ * Cache manager for UniSpec operations.
+ */
+export declare class UniSpecCacheManager {
+    private validationCache;
+    private normalizationCache;
+    private diffCache;
+    private cleanupInterval;
+    constructor(options?: CacheOptions);
+    /**
+     * Get cached validation result asynchronously.
+     */
+    getValidationResult(documentHash: string): Promise<ValidationResult | undefined>;
+    /**
+     * Cache validation result asynchronously.
+     */
+    setValidationResult(documentHash: string, result: ValidationResult): Promise<void>;
+    /**
+     * Get cached normalization result asynchronously.
+     */
+    getNormalizationResult(documentHash: string): Promise<unknown>;
+    /**
+     * Cache normalization result asynchronously.
+     */
+    setNormalizationResult(documentHash: string, result: unknown): Promise<void>;
+    /**
+     * Get cached diff result asynchronously.
+     */
+    getDiffResult(docsHash: string): Promise<unknown>;
+    /**
+     * Cache diff result asynchronously.
+     */
+    setDiffResult(docsHash: string, result: unknown): Promise<void>;
+    /**
+     * Get comprehensive cache statistics.
+     */
+    getStats(): {
+        validation: CacheStats;
+        normalization: CacheStats;
+        diff: CacheStats;
+        total: {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+    };
+    /**
+     * Clear all caches.
+     */
+    clearAll(): void;
+    /**
+     * Start automatic cleanup interval.
+     */
+    private startCleanup;
+    /**
+     * Stop automatic cleanup.
+     */
+    destroy(): void;
+}

package/dist/cache/cache-manager.js

@@ -0,0 +1,122 @@
+import { CACHE_CONSTANTS, CACHE_MESSAGES } from "./constants.js";
+import { LRUCache } from "./lru-cache.js";
+/**
+ * Cache manager for UniSpec operations.
+ */
+export class UniSpecCacheManager {
+    constructor(options = {}) {
+        this.cleanupInterval = null;
+        this.validationCache = new LRUCache({
+            ...options,
+            maxSize: CACHE_CONSTANTS.VALIDATION_MAX_SIZE,
+        });
+        this.normalizationCache = new LRUCache({
+            ...options,
+            maxSize: CACHE_CONSTANTS.NORMALIZATION_MAX_SIZE,
+        });
+        this.diffCache = new LRUCache({
+            ...options,
+            maxSize: CACHE_CONSTANTS.DIFF_MAX_SIZE,
+        });
+        // Start cleanup interval
+        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(CACHE_MESSAGES.CLEANUP_ERROR, error);
+                    // Continue running cleanup even if one cache fails
+                }
+            }, CACHE_CONSTANTS.CLEANUP_INTERVAL);
+        }
+        catch (error) {
+            console.error(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();
+    }
+}

package/dist/cache/constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cache configuration constants.
+ */
+export declare const CACHE_CONSTANTS: {
+    readonly DEFAULT_MAX_SIZE: 100;
+    readonly VALIDATION_MAX_SIZE: 50;
+    readonly NORMALIZATION_MAX_SIZE: 30;
+    readonly DIFF_MAX_SIZE: 20;
+    readonly DEFAULT_TTL: number;
+    readonly CLEANUP_INTERVAL: 60000;
+    readonly HASH_GOLDEN_RATIO: 2654435761;
+    readonly HASH_BASE: 31;
+    readonly HASH_MASK: 4294967295;
+};
+export declare const CACHE_MESSAGES: {
+    readonly CLEANUP_ERROR: "Cache cleanup error";
+    readonly CLEANUP_START_ERROR: "Failed to start cleanup interval";
+    readonly CACHE_WILL_CONTINUE: "Cache will still work without automatic cleanup";
+};
+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;

package/dist/cache/constants.js

@@ -0,0 +1,22 @@
+/**
+ * Cache configuration constants.
+ */
+export const 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,
+};
+export const 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/cache/hash-utils.d.ts

@@ -0,0 +1,21 @@
+import type { UniSpecDocument } from "../types/index.js";
+/**
+ * Generate a hash for a UniSpec document for caching purposes.
+ * Uses optimized hashing for better performance and collision resistance.
+ */
+export declare function generateDocumentHash(document: UniSpecDocument): Promise<string>;
+/**
+ * Synchronous version for backward compatibility (deprecated).
+ * @deprecated Use async version for better security
+ */
+export declare function generateDocumentHashSync(document: UniSpecDocument): string;
+/**
+ * Generate a hash for two documents (for diff caching).
+ * Uses optimized diff hashing with better collision resistance.
+ */
+export declare function generateDiffHash(oldDoc: UniSpecDocument, newDoc: UniSpecDocument): Promise<string>;
+/**
+ * Synchronous version for backward compatibility (deprecated).
+ * @deprecated Use async version for better security
+ */
+export declare function generateDiffHashSync(oldDoc: UniSpecDocument, newDoc: UniSpecDocument): string;