@unispechq/unispec-core 0.3.2 → 0.3.4

package/dist/cjs/src/index.js

@@ -1,59 +0,0 @@
-"use strict";
-// ============================================================================
-// CORE TYPES AND INTERFACES
-// ============================================================================
-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 __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-// ============================================================================
-// CACHING SYSTEM
-// ============================================================================
-__exportStar(require("./cache/index.js"), exports);
-// ============================================================================
-// DIFF AND CHANGE ANALYSIS
-// ============================================================================
-__exportStar(require("./diff/index.js"), exports);
-// ============================================================================
-// DOCUMENT LOADING AND PARSING
-// ============================================================================
-__exportStar(require("./loader/index.js"), exports);
-// ============================================================================
-// DOCUMENT NORMALIZATION
-// ============================================================================
-__exportStar(require("./normalizer/index.js"), exports);
-// ============================================================================
-// DOCUMENT OPTIMIZATION
-// ============================================================================
-__exportStar(require("./optimizer/index.js"), exports);
-// ============================================================================
-// SCHEMA MANAGEMENT
-// ============================================================================
-__exportStar(require("./schemas/index.js"), exports);
-__exportStar(require("./types/index.js"), exports);
-// ============================================================================
-// VALIDATION SYSTEM
-// ============================================================================
-__exportStar(require("./validator/index.js"), exports);
-// ============================================================================
-// UTILITY FUNCTIONS
-// ============================================================================
-__exportStar(require("./validator/object-traversal.js"), exports);
-__exportStar(require("./validator/reference-validator.js"), exports);
-__exportStar(require("./validator/schema-references.js"), exports);
-__exportStar(require("./validator/semantic-validator.js"), exports);
-// ============================================================================
-// VERSION INFORMATION
-// ============================================================================
-__exportStar(require("./versions.js"), exports);

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

@@ -1,13 +0,0 @@
-"use strict";
-// Export all loader functionality
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateYamlModule = exports.getYamlModule = exports.loadUniSpec = exports.ALLOWED_YAML_MODULES = exports.validateDocumentSecurity = void 0;
-var security_validator_1 = require("./security-validator.js");
-Object.defineProperty(exports, "validateDocumentSecurity", { enumerable: true, get: function () { return security_validator_1.validateDocumentSecurity; } });
-var types_1 = require("./types.js");
-Object.defineProperty(exports, "ALLOWED_YAML_MODULES", { enumerable: true, get: function () { return types_1.ALLOWED_YAML_MODULES; } });
-var unispec_loader_1 = require("./unispec-loader.js");
-Object.defineProperty(exports, "loadUniSpec", { enumerable: true, get: function () { return unispec_loader_1.loadUniSpec; } });
-var yaml_loader_1 = require("./yaml-loader.js");
-Object.defineProperty(exports, "getYamlModule", { enumerable: true, get: function () { return yaml_loader_1.getYamlModule; } });
-Object.defineProperty(exports, "validateYamlModule", { enumerable: true, get: function () { return yaml_loader_1.validateYamlModule; } });

package/dist/cjs/src/loader/security-validator.js

@@ -1,53 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateDocumentSecurity = validateDocumentSecurity;
-const errors_1 = require("../errors/index.js");
-/**
- * Validate document security constraints using iterative approach to prevent stack overflow.
- */
-function validateDocumentSecurity(doc, options) {
-    let keyCount = 0;
-    let maxDepth = 0;
-    // Use stack-based iteration instead of recursion
-    const stack = [
-        { obj: doc, depth: 0, path: "" },
-    ];
-    while (stack.length > 0) {
-        const item = stack.pop();
-        if (!item)
-            break;
-        const { obj, depth, path } = item;
-        // Check depth limit
-        if (depth > options.maxDepth) {
-            throw errors_1.ErrorFactory.createSecurityError(`Document depth (${depth}) exceeds maximum allowed depth (${options.maxDepth}) at path: ${path}`, path, { currentDepth: depth, maxDepth: options.maxDepth });
-        }
-        maxDepth = Math.max(maxDepth, depth);
-        if (Array.isArray(obj)) {
-            // Process array elements
-            for (let i = obj.length - 1; i >= 0; i--) {
-                stack.push({
-                    obj: obj[i],
-                    depth: depth + 1,
-                    path: `${path}[${i}]`,
-                });
-            }
-        }
-        else if (obj && typeof obj === "object") {
-            // Process object properties
-            const objRecord = obj;
-            const keys = Object.keys(objRecord);
-            for (let i = keys.length - 1; i >= 0; i--) {
-                const key = keys[i];
-                keyCount++;
-                if (keyCount > options.maxKeys) {
-                    throw errors_1.ErrorFactory.createSecurityError(`Document key count (${keyCount}) exceeds maximum allowed keys (${options.maxKeys}) at path: ${path}`, path, { keyCount, maxKeys: options.maxKeys });
-                }
-                stack.push({
-                    obj: objRecord[key],
-                    depth: depth + 1,
-                    path: path ? `${path}.${key}` : key,
-                });
-            }
-        }
-    }
-}

package/dist/cjs/src/loader/types.js

@@ -1,11 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ALLOWED_YAML_MODULES = void 0;
-/**
- * Allowed YAML module patterns for security validation.
- */
-exports.ALLOWED_YAML_MODULES = [
-    "js-yaml",
-    "@js-yaml/fork",
-    "yaml",
-];

package/dist/cjs/src/loader/unispec-loader.js

@@ -1,84 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadUniSpec = loadUniSpec;
-const index_1 = require("../errors/index.js");
-const security_validator_1 = require("./security-validator.js");
-const yaml_loader_1 = require("./yaml-loader.js");
-/**
- * Load a UniSpec document from a raw input value.
- * Supports:
- * - JavaScript objects (treated as already parsed UniSpec)
- * - JSON strings
- * - YAML strings
- */
-async function loadUniSpec(input, options = {}) {
-    // Set default security limits
-    const secureOptions = {
-        maxDepth: options.maxDepth ?? 100,
-        maxKeys: options.maxKeys ?? 10000,
-        allowedTags: options.allowedTags ?? [
-            "str",
-            "int",
-            "float",
-            "bool",
-            "null",
-            "seq",
-            "map",
-            "binary",
-            "timestamp",
-            "merge",
-            "omap",
-            "pairs",
-            "set",
-        ],
-        maxDocumentSize: options.maxDocumentSize ?? 10 * 1024 * 1024,
-        strictYamlTags: options.strictYamlTags ?? false,
-    };
-    if (typeof input === "string") {
-        const trimmed = input.trim();
-        if (!trimmed) {
-            throw index_1.ErrorFactory.createLoaderError("Cannot load UniSpec: input string is empty", "");
-        }
-        // Check document size limit
-        if (trimmed.length > secureOptions.maxDocumentSize) {
-            throw index_1.ErrorFactory.createSecurityError(`Document size (${trimmed.length} bytes) exceeds maximum allowed size (${secureOptions.maxDocumentSize} bytes)`, "", {
-                documentSize: trimmed.length,
-                maxSize: secureOptions.maxDocumentSize,
-            });
-        }
-        // Try JSON first (faster and more common)
-        try {
-            const parsed = JSON.parse(trimmed);
-            (0, security_validator_1.validateDocumentSecurity)(parsed, secureOptions);
-            return parsed;
-        }
-        catch (jsonError) {
-            // If JSON fails, try YAML with security validation
-            try {
-                // Get validated YAML module
-                const yaml = await (0, yaml_loader_1.getYamlModule)();
-                const doc = yaml.load(trimmed, {
-                    filename: options.filename,
-                    // Enhanced security options
-                    schema: yaml.FAILSAFE_SCHEMA,
-                    // Additional security constraints would go here if the library supports them
-                });
-                (0, security_validator_1.validateDocumentSecurity)(doc, secureOptions);
-                return doc;
-            }
-            catch (yamlError) {
-                const jsonMsg = jsonError instanceof Error ? jsonError.message : String(jsonError);
-                const yamlMsg = yamlError instanceof Error ? yamlError.message : String(yamlError);
-                // Create specific error based on what failed
-                if (yamlMsg.includes("not in the allowed list") ||
-                    yamlMsg.includes("security")) {
-                    const securityError = index_1.ErrorFactory.fromError(yamlError, "yaml_security_error");
-                    throw securityError;
-                }
-                throw index_1.ErrorFactory.createLoaderError(`Failed to parse input as JSON or YAML. JSON error: ${jsonMsg}. YAML error: ${yamlMsg}`, "", { jsonError: jsonMsg, yamlError: yamlMsg });
-            }
-        }
-    }
-    (0, security_validator_1.validateDocumentSecurity)(input, secureOptions);
-    return input;
-}

package/dist/cjs/src/loader/yaml-loader.js

@@ -1,76 +0,0 @@
-"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.getYamlModule = getYamlModule;
-exports.validateYamlModule = validateYamlModule;
-const index_1 = require("../errors/index.js");
-// Static import with security validation
-let yamlModule = null;
-/**
- * Securely load YAML module with validation.
- * Uses static import path and validates the module structure.
- */
-async function getYamlModule() {
-    if (yamlModule) {
-        return yamlModule;
-    }
-    try {
-        // Use static import path for security
-        const importedModule = (await Promise.resolve().then(() => __importStar(require("js-yaml"))));
-        validateYamlModule(importedModule);
-        yamlModule = importedModule;
-        return yamlModule;
-    }
-    catch (error) {
-        throw index_1.ErrorFactory.createSecurityError("Failed to load and validate YAML module", "", { error: error instanceof Error ? error.message : String(error) });
-    }
-}
-/**
- * Validate YAML module for security.
- */
-function validateYamlModule(yamlModule) {
-    if (!yamlModule || typeof yamlModule !== "object") {
-        throw index_1.ErrorFactory.createLoaderError("Invalid YAML module: module must be an object", "", { moduleType: typeof yamlModule });
-    }
-    const module = yamlModule;
-    // Check for required functions
-    if (!module.load || typeof module.load !== "function") {
-        throw index_1.ErrorFactory.createLoaderError("Invalid YAML module: missing load function", "", { hasLoad: !!module.load, loadType: typeof module.load });
-    }
-    // Check for FAILSAFE_SCHEMA
-    if (!module.FAILSAFE_SCHEMA) {
-        throw index_1.ErrorFactory.createSecurityError("YAML module must support FAILSAFE_SCHEMA for security", "", { hasFailsafeSchema: !!module.FAILSAFE_SCHEMA });
-    }
-}

package/dist/cjs/src/normalizer/core.js

@@ -1,37 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeUniSpec = normalizeUniSpec;
-const graphql_normalizer_1 = require("./graphql-normalizer.js");
-const rest_normalizer_1 = require("./rest-normalizer.js");
-const utils_1 = require("./utils.js");
-const websocket_normalizer_1 = require("./websocket-normalizer.js");
-/**
- * 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
- * - 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 = {}) {
-    // Apply protocol-specific normalizations first
-    const restNormalized = (0, rest_normalizer_1.normalizeRestRoutes)(doc);
-    const graphqlNormalized = (0, graphql_normalizer_1.normalizeGraphqlOperations)(restNormalized);
-    const finalNormalized = (0, websocket_normalizer_1.normalizeWebSocket)(graphqlNormalized);
-    // Always apply structural normalization to ensure immutability
-    // and consistent key sorting, even if no protocol changes were made
-    return (0, utils_1.normalizeValue)(finalNormalized);
-}

package/dist/cjs/src/normalizer/graphql-normalizer.js

@@ -1,67 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeGraphqlOperations = normalizeGraphqlOperations;
-/**
- * Normalize GraphQL operations by sorting them lexicographically by name within each operation type.
- *
- * @param doc - The UniSpec document to normalize
- * @returns The document with normalized GraphQL operations
- */
-function normalizeGraphqlOperations(doc) {
-    if (!doc || !doc.service?.protocols) {
-        return doc;
-    }
-    const protocols = doc.service.protocols;
-    const graphql = protocols.graphql;
-    if (!graphql) {
-        return doc;
-    }
-    const kinds = ["queries", "mutations", "subscriptions"];
-    // Sort operations within each kind only if needed
-    const normalizedOperations = {};
-    let hasChanges = false;
-    for (const kind of kinds) {
-        const ops = graphql[kind];
-        if (!Array.isArray(ops)) {
-            normalizedOperations[kind] = ops;
-            continue;
-        }
-        // Check if operations are already sorted
-        const areOpsSorted = ops.every((op, index, arr) => {
-            if (index === 0)
-                return true;
-            const prevName = arr[index - 1]?.name ?? "";
-            const currentName = op?.name ?? "";
-            return prevName.localeCompare(currentName) <= 0;
-        });
-        if (areOpsSorted) {
-            normalizedOperations[kind] = ops; // No changes needed
-        }
-        else {
-            const sortedOps = [...ops].sort((a, b) => {
-                const aName = a?.name ?? "";
-                const bName = b?.name ?? "";
-                return aName.localeCompare(bName);
-            });
-            normalizedOperations[kind] = sortedOps;
-            hasChanges = true;
-        }
-    }
-    if (!hasChanges) {
-        return doc; // No changes needed
-    }
-    // Return new document with sorted operations (immutable)
-    return {
-        ...doc,
-        service: {
-            ...doc.service,
-            protocols: {
-                ...protocols,
-                graphql: {
-                    ...graphql,
-                    ...normalizedOperations,
-                },
-            },
-        },
-    };
-}

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

@@ -1,7 +0,0 @@
-"use strict";
-// Re-export types
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeUniSpec = void 0;
-// Re-export core function
-var core_1 = require("./core.js");
-Object.defineProperty(exports, "normalizeUniSpec", { enumerable: true, get: function () { return core_1.normalizeUniSpec; } });

package/dist/cjs/src/normalizer/rest-normalizer.js

@@ -1,51 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeRestRoutes = normalizeRestRoutes;
-/**
- * Normalize REST routes by sorting them lexicographically by name or path+method.
- *
- * @param doc - The UniSpec document to normalize
- * @returns The document with normalized REST routes
- */
-function normalizeRestRoutes(doc) {
-    if (!doc || !doc.service?.protocols) {
-        return doc;
-    }
-    const protocols = doc.service.protocols;
-    const rest = protocols.rest;
-    if (!rest || !Array.isArray(rest.routes)) {
-        return doc;
-    }
-    // Check if routes are already sorted to avoid unnecessary cloning
-    const isSorted = rest.routes.every((route, index, arr) => {
-        if (index === 0)
-            return true;
-        const prevKey = arr[index - 1].name ||
-            `${arr[index - 1].path} ${arr[index - 1].method}`;
-        const currentKey = route.name || `${route.path} ${route.method}`;
-        return prevKey.localeCompare(currentKey) <= 0;
-    });
-    if (isSorted) {
-        return doc; // No changes needed
-    }
-    // Create immutable copy with sorted routes
-    const sortedRoutes = [...rest.routes].sort((a, b) => {
-        const keyA = a.name || `${a.path} ${a.method}`;
-        const keyB = b.name || `${b.path} ${b.method}`;
-        return keyA.localeCompare(keyB);
-    });
-    // Return new document with sorted routes (immutable)
-    return {
-        ...doc,
-        service: {
-            ...doc.service,
-            protocols: {
-                ...protocols,
-                rest: {
-                    ...rest,
-                    routes: sortedRoutes,
-                },
-            },
-        },
-    };
-}

package/dist/cjs/src/normalizer/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/src/normalizer/utils.js

@@ -1,49 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isPlainObject = isPlainObject;
-exports.normalizeValue = normalizeValue;
-/**
- * Check if a value is a plain object (not array, null, or other object types).
- *
- * @param value - The value to check
- * @returns true if the value is a plain object, false otherwise
- */
-function isPlainObject(value) {
-    return Object.prototype.toString.call(value) === "[object Object]";
-}
-/**
- * Normalize a value by sorting object keys lexicographically (recursive).
- * Always creates new objects to ensure immutability.
- * Handles circular references gracefully.
- *
- * @param value - The value to normalize
- * @param seen - WeakSet of already seen objects for circular reference detection
- * @returns The normalized value (always a new object for objects/arrays)
- */
-function normalizeValue(value, seen = new WeakSet()) {
-    // Handle primitives and null/undefined
-    if (value === null || typeof value !== "object") {
-        return value;
-    }
-    if (Array.isArray(value)) {
-        // Always create new array with recursively normalized items
-        return value.map((item) => normalizeValue(item, seen));
-    }
-    if (isPlainObject(value)) {
-        // Check for circular references
-        if (seen.has(value)) {
-            // Return a placeholder for circular references to avoid infinite recursion
-            return "[Circular]";
-        }
-        seen.add(value);
-        const entries = Object.entries(value);
-        // Always create new object with sorted keys and recursively normalized values
-        const sortedEntries = entries.sort(([a], [b]) => a.localeCompare(b));
-        const normalized = {};
-        for (const [key, val] of sortedEntries) {
-            normalized[key] = normalizeValue(val, seen);
-        }
-        return normalized;
-    }
-    return value;
-}

package/dist/cjs/src/normalizer/websocket-normalizer.js

@@ -1,81 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeWebSocket = normalizeWebSocket;
-/**
- * Normalize WebSocket channels and messages by sorting them lexicographically by name.
- *
- * @param doc - The UniSpec document to normalize
- * @returns The document with normalized WebSocket channels and messages
- */
-function normalizeWebSocket(doc) {
-    if (!doc || !doc.service?.protocols) {
-        return doc;
-    }
-    const protocols = doc.service.protocols;
-    const websocket = protocols.websocket;
-    if (!websocket || !Array.isArray(websocket.channels)) {
-        return doc;
-    }
-    // Check if channels are already sorted
-    const areChannelsSorted = websocket.channels.every((channel, index, arr) => {
-        if (index === 0)
-            return true;
-        const prevName = arr[index - 1]?.name ?? "";
-        const currentName = channel?.name ?? "";
-        return prevName.localeCompare(currentName) <= 0;
-    });
-    // Sort messages within each channel only if needed
-    const normalizedChannels = websocket.channels.map((channel) => {
-        if (!channel || !Array.isArray(channel.messages)) {
-            return channel;
-        }
-        // Check if messages are already sorted
-        const areMessagesSorted = channel.messages.every((message, index, arr) => {
-            if (index === 0)
-                return true;
-            const prevName = arr[index - 1]?.name ?? "";
-            const currentName = message?.name ?? "";
-            return prevName.localeCompare(currentName) <= 0;
-        });
-        if (areMessagesSorted) {
-            return channel; // No changes needed
-        }
-        const sortedMessages = [...channel.messages].sort((a, b) => {
-            const aName = a?.name ?? "";
-            const bName = b?.name ?? "";
-            return aName.localeCompare(bName);
-        });
-        // Return new channel with sorted messages (immutable)
-        return {
-            ...channel,
-            messages: sortedMessages,
-        };
-    });
-    if (areChannelsSorted) {
-        // Check if any channels were modified
-        const channelsModified = normalizedChannels.some((channel, index) => channel !== websocket.channels?.[index]);
-        if (!channelsModified) {
-            return doc; // No changes needed
-        }
-    }
-    // Sort channels
-    const sortedChannels = normalizedChannels.sort((a, b) => {
-        const aName = a?.name ?? "";
-        const bName = b?.name ?? "";
-        return aName.localeCompare(bName);
-    });
-    // Return new document with sorted channels (immutable)
-    return {
-        ...doc,
-        service: {
-            ...doc.service,
-            protocols: {
-                ...protocols,
-                websocket: {
-                    ...websocket,
-                    channels: sortedChannels,
-                },
-            },
-        },
-    };
-}