@machina.ai/openapi-contract-tester 2.1.0

package/dist/utils/openapi-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-discovery.js","sourceRoot":"","sources":["../../src/utils/openapi-discovery.ts"],"names":[],"mappings":"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"}

package/dist/utils/path-resolver.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Path Resolution Utilities
+ *
+ * Provides secure and robust path resolution with protection against
+ * path traversal attacks and consistent handling across platforms.
+ *
+ * @module utils/path-resolver
+ */
+/**
+ * Resolves a file path securely with path traversal protection
+ *
+ * Handles:
+ * - Absolute paths (override baseDir)
+ * - Relative paths (resolved from baseDir)
+ * - Home directory expansion (~)
+ * - Path traversal prevention (../ attacks)
+ * - Cross-platform normalization
+ *
+ * @param filePath - Path to resolve (can be absolute, relative, or use ~)
+ * @param workingDirectory - Base directory for relative path resolution (default: process.cwd())
+ * @returns Absolute, normalized, and validated file path
+ * @throws Error if path attempts to escape working directory
+ *
+ * @example
+ * ```typescript
+ * // Relative path
+ * resolveFilePath('./api.yml', '/home/user/project')
+ * // Returns: '/home/user/project/api.yml'
+ *
+ * // Absolute path (overrides baseDir)
+ * resolveFilePath('/etc/api.yml', '/home/user/project')
+ * // Returns: '/etc/api.yml'
+ *
+ * // Home directory expansion
+ * resolveFilePath('~/api.yml')
+ * // Returns: '/home/user/api.yml'
+ *
+ * // Path traversal attempt (throws error)
+ * resolveFilePath('../../../etc/passwd', '/home/user/project')
+ * // Throws: Error: Path '../../../etc/passwd' escapes working directory
+ * ```
+ */
+export declare function resolveFilePath(filePath: string, workingDirectory?: string): string;
+/**
+ * Resolves an output path for writing files
+ *
+ * Similar to resolveFilePath but ensures parent directory exists
+ * and returns metadata about the resolution.
+ *
+ * @param outputPath - Path where file will be written
+ * @param defaultFilename - Default filename if outputPath is a directory
+ * @param workingDirectory - Base directory for relative path resolution
+ * @returns Resolved output path and parent directory
+ *
+ * @example
+ * ```typescript
+ * resolveOutputPath('./results/report.html', 'report.html', '/home/user/project')
+ * // Returns: {
+ * //   filePath: '/home/user/project/results/report.html',
+ * //   directory: '/home/user/project/results'
+ * // }
+ * ```
+ */
+export declare function resolveOutputPath(outputPath: string, defaultFilename: string, workingDirectory?: string): {
+    filePath: string;
+    directory: string;
+};
+/**
+ * Validates that a path exists within allowed boundaries
+ *
+ * @param filePath - Path to validate
+ * @param allowedBaseDir - Base directory that path must be within
+ * @returns true if path is within allowed directory
+ *
+ * @example
+ * ```typescript
+ * isPathWithinDirectory('/home/user/project/api.yml', '/home/user/project')
+ * // Returns: true
+ *
+ * isPathWithinDirectory('/etc/passwd', '/home/user/project')
+ * // Returns: false
+ * ```
+ */
+export declare function isPathWithinDirectory(filePath: string, allowedBaseDir: string): boolean;
+/**
+ * Normalizes a path for cross-platform compatibility
+ *
+ * Converts Windows backslashes to forward slashes and removes
+ * redundant separators.
+ *
+ * @param filePath - Path to normalize
+ * @returns Normalized path
+ *
+ * @example
+ * ```typescript
+ * normalizePath('foo\\bar\\..\\baz')
+ * // Returns: 'foo/baz' (Unix-style)
+ * ```
+ */
+export declare function normalizePath(filePath: string): string;
+//# sourceMappingURL=path-resolver.d.ts.map

package/dist/utils/path-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/path-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,GACxB,MAAM,CA6CR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,gBAAgB,CAAC,EAAE,MAAM,GACxB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAqBzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,OAAO,CAgBT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/utils/path-resolver.js

@@ -0,0 +1,167 @@
+/**
+ * Path Resolution Utilities
+ *
+ * Provides secure and robust path resolution with protection against
+ * path traversal attacks and consistent handling across platforms.
+ *
+ * @module utils/path-resolver
+ */
+import * as path from 'path';
+import { createLogger } from './logger.js';
+const log = createLogger('path-resolver');
+/**
+ * Resolves a file path securely with path traversal protection
+ *
+ * Handles:
+ * - Absolute paths (override baseDir)
+ * - Relative paths (resolved from baseDir)
+ * - Home directory expansion (~)
+ * - Path traversal prevention (../ attacks)
+ * - Cross-platform normalization
+ *
+ * @param filePath - Path to resolve (can be absolute, relative, or use ~)
+ * @param workingDirectory - Base directory for relative path resolution (default: process.cwd())
+ * @returns Absolute, normalized, and validated file path
+ * @throws Error if path attempts to escape working directory
+ *
+ * @example
+ * ```typescript
+ * // Relative path
+ * resolveFilePath('./api.yml', '/home/user/project')
+ * // Returns: '/home/user/project/api.yml'
+ *
+ * // Absolute path (overrides baseDir)
+ * resolveFilePath('/etc/api.yml', '/home/user/project')
+ * // Returns: '/etc/api.yml'
+ *
+ * // Home directory expansion
+ * resolveFilePath('~/api.yml')
+ * // Returns: '/home/user/api.yml'
+ *
+ * // Path traversal attempt (throws error)
+ * resolveFilePath('../../../etc/passwd', '/home/user/project')
+ * // Throws: Error: Path '../../../etc/passwd' escapes working directory
+ * ```
+ */
+export function resolveFilePath(filePath, workingDirectory) {
+    const baseDir = workingDirectory || process.cwd();
+    // 1. Handle absolute paths (they override baseDir)
+    if (path.isAbsolute(filePath)) {
+        log.debug('Resolved absolute path', { filePath });
+        return path.normalize(filePath);
+    }
+    // 2. Expand home directory (~)
+    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    if (filePath.startsWith('~/') || filePath === '~') {
+        if (!homeDir) {
+            throw new Error('Cannot expand ~ - HOME environment variable not set');
+        }
+        const expanded = path.join(homeDir, filePath.slice(2));
+        log.debug('Expanded home directory', { original: filePath, expanded });
+        return path.normalize(expanded);
+    }
+    // 3. Resolve relative to baseDir
+    const resolved = path.resolve(baseDir, filePath);
+    // 4. SECURITY: Prevent path traversal attacks
+    const relative = path.relative(baseDir, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        const error = new Error(`Path traversal detected: '${filePath}' escapes working directory '${baseDir}'`);
+        log.error('Path traversal attempt blocked', {
+            filePath,
+            baseDir,
+            resolved,
+            relative,
+        });
+        throw error;
+    }
+    log.debug('Resolved relative path', {
+        filePath,
+        baseDir,
+        resolved,
+    });
+    return path.normalize(resolved);
+}
+/**
+ * Resolves an output path for writing files
+ *
+ * Similar to resolveFilePath but ensures parent directory exists
+ * and returns metadata about the resolution.
+ *
+ * @param outputPath - Path where file will be written
+ * @param defaultFilename - Default filename if outputPath is a directory
+ * @param workingDirectory - Base directory for relative path resolution
+ * @returns Resolved output path and parent directory
+ *
+ * @example
+ * ```typescript
+ * resolveOutputPath('./results/report.html', 'report.html', '/home/user/project')
+ * // Returns: {
+ * //   filePath: '/home/user/project/results/report.html',
+ * //   directory: '/home/user/project/results'
+ * // }
+ * ```
+ */
+export function resolveOutputPath(outputPath, defaultFilename, workingDirectory) {
+    const resolved = resolveFilePath(outputPath, workingDirectory);
+    // Check if path ends with directory separator (user wants to write to a directory)
+    const isDirectory = outputPath.endsWith('/') || outputPath.endsWith(path.sep);
+    const filePath = isDirectory
+        ? path.join(resolved, defaultFilename)
+        : resolved;
+    const directory = path.dirname(filePath);
+    log.debug('Resolved output path', {
+        outputPath,
+        defaultFilename,
+        filePath,
+        directory,
+    });
+    return { filePath, directory };
+}
+/**
+ * Validates that a path exists within allowed boundaries
+ *
+ * @param filePath - Path to validate
+ * @param allowedBaseDir - Base directory that path must be within
+ * @returns true if path is within allowed directory
+ *
+ * @example
+ * ```typescript
+ * isPathWithinDirectory('/home/user/project/api.yml', '/home/user/project')
+ * // Returns: true
+ *
+ * isPathWithinDirectory('/etc/passwd', '/home/user/project')
+ * // Returns: false
+ * ```
+ */
+export function isPathWithinDirectory(filePath, allowedBaseDir) {
+    const normalizedFile = path.normalize(path.resolve(filePath));
+    const normalizedBase = path.normalize(path.resolve(allowedBaseDir));
+    const relative = path.relative(normalizedBase, normalizedFile);
+    const isWithin = !relative.startsWith('..') && !path.isAbsolute(relative);
+    log.debug('Path boundary check', {
+        filePath,
+        allowedBaseDir,
+        relative,
+        isWithin,
+    });
+    return isWithin;
+}
+/**
+ * Normalizes a path for cross-platform compatibility
+ *
+ * Converts Windows backslashes to forward slashes and removes
+ * redundant separators.
+ *
+ * @param filePath - Path to normalize
+ * @returns Normalized path
+ *
+ * @example
+ * ```typescript
+ * normalizePath('foo\\bar\\..\\baz')
+ * // Returns: 'foo/baz' (Unix-style)
+ * ```
+ */
+export function normalizePath(filePath) {
+    return path.normalize(filePath).replace(/\\/g, '/');
+}
+//# sourceMappingURL=path-resolver.js.map

package/dist/utils/path-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-resolver.js","sourceRoot":"","sources":["../../src/utils/path-resolver.ts"],"names":[],"mappings":"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"}

package/dist/utils/resilience.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Resilience Utilities - Retry Logic and Circuit Breaker
+ *
+ * Provides retry mechanisms and circuit breaker pattern for handling
+ * transient failures gracefully.
+ *
+ * @module utils/resilience
+ */
+/**
+ * Retry configuration options
+ */
+export interface RetryOptions {
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds
+     * @default 1000
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay in milliseconds
+     * @default 10000
+     */
+    maxDelay?: number;
+    /**
+     * Backoff multiplier for exponential backoff
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Custom function to determine if error should be retried
+     * @default isRetryableError
+     */
+    shouldRetry?: (error: unknown) => boolean;
+    /**
+     * Callback called on each retry attempt
+     */
+    onRetry?: (attempt: number, error: unknown, delay: number) => void;
+}
+/**
+ * Executes a function with retry logic and exponential backoff
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry configuration
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => fetch('https://api.example.com/data'),
+ *   {
+ *     maxRetries: 3,
+ *     initialDelay: 1000,
+ *     onRetry: (attempt, error, delay) => {
+ *       console.log(`Retry attempt ${attempt} after ${delay}ms`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Circuit breaker states
+ */
+export declare enum CircuitState {
+    CLOSED = "CLOSED",// Normal operation
+    OPEN = "OPEN",// Circuit is open, requests fail fast
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerOptions {
+    /**
+     * Number of failures before opening circuit
+     * @default 5
+     */
+    failureThreshold?: number;
+    /**
+     * Time in milliseconds to wait before transitioning to HALF_OPEN
+     * @default 60000 (1 minute)
+     */
+    resetTimeout?: number;
+    /**
+     * Number of successful calls in HALF_OPEN before closing circuit
+     * @default 2
+     */
+    successThreshold?: number;
+    /**
+     * Callback when circuit state changes
+     */
+    onStateChange?: (oldState: CircuitState, newState: CircuitState) => void;
+}
+/**
+ * Circuit Breaker pattern implementation
+ *
+ * Prevents cascading failures by failing fast when a service is down
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   resetTimeout: 60000,
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(async () => {
+ *     return await fetch('https://api.example.com/data');
+ *   });
+ * } catch (error) {
+ *   console.error('Request failed or circuit is open');
+ * }
+ * ```
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private nextAttemptTime;
+    private readonly options;
+    constructor(options?: CircuitBreakerOptions);
+    /**
+     * Executes a function with circuit breaker protection
+     *
+     * @param fn - Async function to execute
+     * @returns Result of the function
+     * @throws Error if circuit is OPEN
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Called when operation succeeds
+     * @internal
+     */
+    private onSuccess;
+    /**
+     * Called when operation fails
+     * @internal
+     */
+    private onFailure;
+    /**
+     * Transitions circuit to a new state
+     * @internal
+     */
+    private transitionTo;
+    /**
+     * Gets current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Gets current failure count
+     */
+    getFailureCount(): number;
+    /**
+     * Manually resets the circuit breaker
+     */
+    reset(): void;
+}
+/**
+ * Creates a resilient version of a function with both retry and circuit breaker
+ *
+ * @param fn - Function to make resilient
+ * @param retryOptions - Retry configuration
+ * @param circuitBreakerOptions - Circuit breaker configuration
+ * @returns Wrapped function
+ *
+ * @example
+ * ```typescript
+ * const resilientFetch = makeResilient(
+ *   async (url: string) => fetch(url),
+ *   { maxRetries: 3 },
+ *   { failureThreshold: 5 }
+ * );
+ *
+ * const data = await resilientFetch('https://api.example.com/data');
+ * ```
+ */
+export declare function makeResilient<T extends (...args: any[]) => Promise<any>>(fn: T, retryOptions?: RetryOptions, circuitBreakerOptions?: CircuitBreakerOptions): T;
+//# sourceMappingURL=resilience.d.ts.map

package/dist/utils/resilience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.d.ts","sourceRoot":"","sources":["../../src/utils/resilience.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAoDZ;AAED;;GAEG;AACH,oBAAY,YAAY;IACtB,MAAM,WAAW,CAAM,mBAAmB;IAC1C,IAAI,SAAS,CAAU,sCAAsC;IAC7D,SAAS,cAAc;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;CAC1E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;gBAE9C,OAAO,GAAE,qBAA0B;IAS/C;;;;;;OAMG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAyBlD;;;OAGG;IACH,OAAO,CAAC,SAAS;IAmBjB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAkBjB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAqBpB;;OAEG;IACH,QAAQ,IAAI,YAAY;IAIxB;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,KAAK,IAAI,IAAI;CAOd;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACtE,EAAE,EAAE,CAAC,EACL,YAAY,CAAC,EAAE,YAAY,EAC3B,qBAAqB,CAAC,EAAE,qBAAqB,GAC5C,CAAC,CAQH"}