@unispechq/unispec-core 0.3.2 → 0.3.4

package/dist/src/index.d.ts

@@ -1,13 +0,0 @@
-export * from "./cache/index.js";
-export * from "./diff/index.js";
-export * from "./loader/index.js";
-export * from "./normalizer/index.js";
-export * from "./optimizer/index.js";
-export * from "./schemas/index.js";
-export * from "./types/index.js";
-export * from "./validator/index.js";
-export * from "./validator/object-traversal.js";
-export * from "./validator/reference-validator.js";
-export * from "./validator/schema-references.js";
-export * from "./validator/semantic-validator.js";
-export * from "./versions.js";

package/dist/src/index.js

@@ -1,43 +0,0 @@
-// ============================================================================
-// CORE TYPES AND INTERFACES
-// ============================================================================
-// ============================================================================
-// CACHING SYSTEM
-// ============================================================================
-export * from "./cache/index.js";
-// ============================================================================
-// DIFF AND CHANGE ANALYSIS
-// ============================================================================
-export * from "./diff/index.js";
-// ============================================================================
-// DOCUMENT LOADING AND PARSING
-// ============================================================================
-export * from "./loader/index.js";
-// ============================================================================
-// DOCUMENT NORMALIZATION
-// ============================================================================
-export * from "./normalizer/index.js";
-// ============================================================================
-// DOCUMENT OPTIMIZATION
-// ============================================================================
-export * from "./optimizer/index.js";
-// ============================================================================
-// SCHEMA MANAGEMENT
-// ============================================================================
-export * from "./schemas/index.js";
-export * from "./types/index.js";
-// ============================================================================
-// VALIDATION SYSTEM
-// ============================================================================
-export * from "./validator/index.js";
-// ============================================================================
-// UTILITY FUNCTIONS
-// ============================================================================
-export * from "./validator/object-traversal.js";
-export * from "./validator/reference-validator.js";
-export * from "./validator/schema-references.js";
-export * from "./validator/semantic-validator.js";
-// ============================================================================
-// VERSION INFORMATION
-// ============================================================================
-export * from "./versions.js";

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

@@ -1,5 +0,0 @@
-export { validateDocumentSecurity } from "./security-validator.js";
-export type { LoadOptions, SecureLoadOptions } from "./types.js";
-export { ALLOWED_YAML_MODULES } from "./types.js";
-export { loadUniSpec } from "./unispec-loader.js";
-export { getYamlModule, validateYamlModule } from "./yaml-loader.js";

package/dist/src/loader/index.js

@@ -1,5 +0,0 @@
-// Export all loader functionality
-export { validateDocumentSecurity } from "./security-validator.js";
-export { ALLOWED_YAML_MODULES } from "./types.js";
-export { loadUniSpec } from "./unispec-loader.js";
-export { getYamlModule, validateYamlModule } from "./yaml-loader.js";

package/dist/src/loader/security-validator.d.ts

@@ -1,5 +0,0 @@
-import type { SecureLoadOptions } from "./types.js";
-/**
- * Validate document security constraints using iterative approach to prevent stack overflow.
- */
-export declare function validateDocumentSecurity(doc: unknown, options: SecureLoadOptions): void;

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

@@ -1,50 +0,0 @@
-import { ErrorFactory } from "../errors/index.js";
-/**
- * Validate document security constraints using iterative approach to prevent stack overflow.
- */
-export 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 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 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/src/loader/types.d.ts

@@ -1,30 +0,0 @@
-export interface LoadOptions {
-    filename?: string;
-    maxDepth?: number;
-    maxKeys?: number;
-    allowedTags?: string[];
-    maxDocumentSize?: number;
-    strictYamlTags?: boolean;
-}
-export interface SecureLoadOptions {
-    maxDepth: number;
-    maxKeys: number;
-    allowedTags: string[];
-    maxDocumentSize: number;
-    strictYamlTags: boolean;
-}
-/**
- * Allowed YAML module patterns for security validation.
- */
-export declare const ALLOWED_YAML_MODULES: readonly ["js-yaml", "@js-yaml/fork", "yaml"];
-export interface YamlSchema {
-    [key: string]: unknown;
-}
-export interface YamlModule {
-    load: (input: string, options?: {
-        schema?: YamlSchema;
-        filename?: string;
-    }) => unknown;
-    FAILSAFE_SCHEMA: YamlSchema;
-    [key: string]: unknown;
-}

package/dist/src/loader/types.js

@@ -1,8 +0,0 @@
-/**
- * Allowed YAML module patterns for security validation.
- */
-export const ALLOWED_YAML_MODULES = [
-    "js-yaml",
-    "@js-yaml/fork",
-    "yaml",
-];

package/dist/src/loader/unispec-loader.d.ts

@@ -1,10 +0,0 @@
-import type { UniSpecDocument } from "../types/index.js";
-import type { LoadOptions } from "./types.js";
-/**
- * Load a UniSpec document from a raw input value.
- * Supports:
- * - JavaScript objects (treated as already parsed UniSpec)
- * - JSON strings
- * - YAML strings
- */
-export declare function loadUniSpec(input: string | object, options?: LoadOptions): Promise<UniSpecDocument>;

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

@@ -1,81 +0,0 @@
-import { ErrorFactory } from "../errors/index.js";
-import { validateDocumentSecurity } from "./security-validator.js";
-import { getYamlModule } from "./yaml-loader.js";
-/**
- * Load a UniSpec document from a raw input value.
- * Supports:
- * - JavaScript objects (treated as already parsed UniSpec)
- * - JSON strings
- * - YAML strings
- */
-export 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 ErrorFactory.createLoaderError("Cannot load UniSpec: input string is empty", "");
-        }
-        // Check document size limit
-        if (trimmed.length > secureOptions.maxDocumentSize) {
-            throw 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);
-            validateDocumentSecurity(parsed, secureOptions);
-            return parsed;
-        }
-        catch (jsonError) {
-            // If JSON fails, try YAML with security validation
-            try {
-                // Get validated YAML module
-                const yaml = await 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
-                });
-                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 = ErrorFactory.fromError(yamlError, "yaml_security_error");
-                    throw securityError;
-                }
-                throw ErrorFactory.createLoaderError(`Failed to parse input as JSON or YAML. JSON error: ${jsonMsg}. YAML error: ${yamlMsg}`, "", { jsonError: jsonMsg, yamlError: yamlMsg });
-            }
-        }
-    }
-    validateDocumentSecurity(input, secureOptions);
-    return input;
-}

package/dist/src/loader/yaml-loader.d.ts

@@ -1,10 +0,0 @@
-import type { YamlModule } from "./types.js";
-/**
- * Securely load YAML module with validation.
- * Uses static import path and validates the module structure.
- */
-export declare function getYamlModule(): Promise<YamlModule>;
-/**
- * Validate YAML module for security.
- */
-export declare function validateYamlModule(yamlModule: unknown): asserts yamlModule is YamlModule;

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

@@ -1,39 +0,0 @@
-import { ErrorFactory } from "../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.
- */
-export async function getYamlModule() {
-    if (yamlModule) {
-        return yamlModule;
-    }
-    try {
-        // Use static import path for security
-        const importedModule = (await import("js-yaml"));
-        validateYamlModule(importedModule);
-        yamlModule = importedModule;
-        return yamlModule;
-    }
-    catch (error) {
-        throw ErrorFactory.createSecurityError("Failed to load and validate YAML module", "", { error: error instanceof Error ? error.message : String(error) });
-    }
-}
-/**
- * Validate YAML module for security.
- */
-export function validateYamlModule(yamlModule) {
-    if (!yamlModule || typeof yamlModule !== "object") {
-        throw 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 ErrorFactory.createLoaderError("Invalid YAML module: missing load function", "", { hasLoad: !!module.load, loadType: typeof module.load });
-    }
-    // Check for FAILSAFE_SCHEMA
-    if (!module.FAILSAFE_SCHEMA) {
-        throw ErrorFactory.createSecurityError("YAML module must support FAILSAFE_SCHEMA for security", "", { hasFailsafeSchema: !!module.FAILSAFE_SCHEMA });
-    }
-}

package/dist/src/normalizer/core.d.ts

@@ -1,24 +0,0 @@
-import type { UniSpecDocument } from "../types/index.js";
-import type { NormalizeOptions } from "./types.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
- */
-export declare function normalizeUniSpec(doc: UniSpecDocument, _options?: NormalizeOptions): UniSpecDocument;

package/dist/src/normalizer/core.js

@@ -1,34 +0,0 @@
-import { normalizeGraphqlOperations } from "./graphql-normalizer.js";
-import { normalizeRestRoutes } from "./rest-normalizer.js";
-import { normalizeValue } from "./utils.js";
-import { normalizeWebSocket } from "./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
- */
-export function normalizeUniSpec(doc, _options = {}) {
-    // Apply protocol-specific normalizations first
-    const restNormalized = normalizeRestRoutes(doc);
-    const graphqlNormalized = normalizeGraphqlOperations(restNormalized);
-    const finalNormalized = normalizeWebSocket(graphqlNormalized);
-    // Always apply structural normalization to ensure immutability
-    // and consistent key sorting, even if no protocol changes were made
-    return normalizeValue(finalNormalized);
-}

package/dist/src/normalizer/graphql-normalizer.d.ts

@@ -1,8 +0,0 @@
-import type { UniSpecDocument } from "../types/index.js";
-/**
- * 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
- */
-export declare function normalizeGraphqlOperations(doc: UniSpecDocument): UniSpecDocument;

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

@@ -1,64 +0,0 @@
-/**
- * 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
- */
-export 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/src/normalizer/index.d.ts

@@ -1,2 +0,0 @@
-export { normalizeUniSpec } from "./core.js";
-export type { NormalizeOptions } from "./types.js";

package/dist/src/normalizer/index.js

@@ -1,3 +0,0 @@
-// Re-export types
-// Re-export core function
-export { normalizeUniSpec } from "./core.js";

package/dist/src/normalizer/rest-normalizer.d.ts

@@ -1,8 +0,0 @@
-import type { UniSpecDocument } from "../types/index.js";
-/**
- * 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
- */
-export declare function normalizeRestRoutes(doc: UniSpecDocument): UniSpecDocument;

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

@@ -1,48 +0,0 @@
-/**
- * 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
- */
-export 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/src/normalizer/types.d.ts

@@ -1,7 +0,0 @@
-import type { UniSpecGraphQLProtocol, UniSpecRestProtocol, UniSpecWebSocketProtocol } from "../types/index.js";
-export type NormalizeOptions = Record<string, never>;
-export interface UniSpecServiceProtocolsLike {
-    rest?: UniSpecRestProtocol;
-    graphql?: UniSpecGraphQLProtocol;
-    websocket?: UniSpecWebSocketProtocol;
-}

package/dist/src/normalizer/types.js

@@ -1 +0,0 @@
-export {};

package/dist/src/normalizer/utils.d.ts

@@ -1,17 +0,0 @@
-/**
- * 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
- */
-export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
-/**
- * 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)
- */
-export declare function normalizeValue(value: unknown, seen?: WeakSet<object>): unknown;

package/dist/src/normalizer/utils.js

@@ -1,45 +0,0 @@
-/**
- * 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
- */
-export 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)
- */
-export 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/src/normalizer/websocket-normalizer.d.ts

@@ -1,8 +0,0 @@
-import type { UniSpecDocument } from "../types/index.js";
-/**
- * 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
- */
-export declare function normalizeWebSocket(doc: UniSpecDocument): UniSpecDocument;