vaspera 2.5.0

package/dist/util/concurrency.js

@@ -0,0 +1,339 @@
+/**
+ * Concurrency Control Utilities
+ *
+ * Provides a lightweight promise queue for controlling concurrent operations.
+ * Similar to p-queue but without external dependencies.
+ *
+ * Use VASPERA_SCAN_CONCURRENCY env var to configure default concurrency.
+ *
+ * @module util/concurrency
+ */
+import { logger } from "../logger.js";
+/**
+ * Default concurrency level for scanner operations
+ */
+export const DEFAULT_CONCURRENCY = 3;
+/**
+ * Get the configured concurrency level from environment
+ */
+export function getConcurrencyLevel() {
+    const envValue = process.env.VASPERA_SCAN_CONCURRENCY;
+    if (envValue) {
+        const parsed = parseInt(envValue, 10);
+        if (!isNaN(parsed) && parsed > 0 && parsed <= 20) {
+            return parsed;
+        }
+    }
+    return DEFAULT_CONCURRENCY;
+}
+/**
+ * Promise Queue for controlled concurrency
+ *
+ * Limits the number of concurrent async operations to prevent
+ * resource exhaustion and improve reliability.
+ *
+ * @example
+ * ```typescript
+ * const queue = new PromiseQueue({ concurrency: 3 });
+ *
+ * // Add tasks
+ * queue.add(() => scanFile("file1.ts"), { priority: 1 });
+ * queue.add(() => scanFile("file2.ts"), { priority: 2 }); // runs first
+ *
+ * // Wait for all tasks
+ * const results = await queue.onIdle();
+ * ```
+ */
+export class PromiseQueue {
+    concurrency;
+    autoStart;
+    defaultTimeout;
+    onEmpty;
+    onError;
+    queue = [];
+    running = new Set();
+    results = [];
+    taskIdCounter = 0;
+    isPaused = false;
+    idlePromise = null;
+    idleResolve = null;
+    constructor(options = {}) {
+        this.concurrency = options.concurrency ?? getConcurrencyLevel();
+        this.autoStart = options.autoStart ?? true;
+        this.defaultTimeout = options.timeout;
+        this.onEmpty = options.onEmpty;
+        this.onError = options.onError;
+        logger.debug("concurrency.queue_created", {
+            concurrency: this.concurrency,
+            autoStart: this.autoStart,
+        });
+    }
+    /**
+     * Add a task to the queue
+     */
+    add(fn, options) {
+        const task = {
+            id: options?.id ?? `task-${++this.taskIdCounter}`,
+            fn,
+            priority: options?.priority ?? 0,
+            addedAt: new Date(),
+            timeout: options?.timeout ?? this.defaultTimeout,
+        };
+        // Insert in priority order (higher priority first)
+        let inserted = false;
+        for (let i = 0; i < this.queue.length; i++) {
+            if (task.priority > this.queue[i].priority) {
+                this.queue.splice(i, 0, task);
+                inserted = true;
+                break;
+            }
+        }
+        if (!inserted) {
+            this.queue.push(task);
+        }
+        logger.debug("concurrency.task_added", {
+            id: task.id,
+            priority: task.priority,
+            queueSize: this.queue.length,
+        });
+        // Create promise that resolves when this task completes
+        const taskPromise = new Promise((resolve) => {
+            const checkResult = setInterval(() => {
+                const result = this.results.find((r) => r.id === task.id);
+                if (result) {
+                    clearInterval(checkResult);
+                    resolve(result);
+                }
+            }, 10);
+        });
+        // Start processing if autoStart is enabled
+        if (this.autoStart && !this.isPaused) {
+            this.process();
+        }
+        return taskPromise;
+    }
+    /**
+     * Add multiple tasks at once
+     */
+    addAll(tasks) {
+        const promises = tasks.map((t) => this.add(t.fn, { priority: t.priority, id: t.id, timeout: t.timeout }));
+        return Promise.all(promises);
+    }
+    /**
+     * Process tasks from the queue
+     */
+    async process() {
+        while (this.queue.length > 0 &&
+            this.running.size < this.concurrency &&
+            !this.isPaused) {
+            const task = this.queue.shift();
+            if (!task)
+                break;
+            this.running.add(task.id);
+            this.runTask(task);
+        }
+        // Check if idle
+        if (this.queue.length === 0 && this.running.size === 0) {
+            this.onEmpty?.();
+            if (this.idleResolve) {
+                this.idleResolve([...this.results]);
+                this.idleResolve = null;
+                this.idlePromise = null;
+            }
+        }
+    }
+    /**
+     * Run a single task
+     */
+    async runTask(task) {
+        const startTime = Date.now();
+        try {
+            // Wrap with timeout if specified
+            let value;
+            if (task.timeout) {
+                value = await Promise.race([
+                    task.fn(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error(`Task ${task.id} timed out after ${task.timeout}ms`)), task.timeout)),
+                ]);
+            }
+            else {
+                value = await task.fn();
+            }
+            const result = {
+                id: task.id,
+                success: true,
+                value,
+                durationMs: Date.now() - startTime,
+            };
+            this.results.push(result);
+            logger.debug("concurrency.task_completed", {
+                id: task.id,
+                durationMs: result.durationMs,
+            });
+        }
+        catch (error) {
+            const result = {
+                id: task.id,
+                success: false,
+                error: error,
+                durationMs: Date.now() - startTime,
+            };
+            this.results.push(result);
+            this.onError?.(error, task);
+            logger.debug("concurrency.task_failed", {
+                id: task.id,
+                error: String(error),
+                durationMs: result.durationMs,
+            });
+        }
+        finally {
+            this.running.delete(task.id);
+            // Process next tasks
+            this.process();
+        }
+    }
+    /**
+     * Start processing (if paused)
+     */
+    start() {
+        this.isPaused = false;
+        this.process();
+    }
+    /**
+     * Pause processing (current tasks continue, new tasks wait)
+     */
+    pause() {
+        this.isPaused = true;
+    }
+    /**
+     * Clear pending tasks (running tasks continue)
+     */
+    clear() {
+        this.queue = [];
+    }
+    /**
+     * Get queue statistics
+     */
+    getStats() {
+        const completed = this.results.filter((r) => r.success).length;
+        const failed = this.results.filter((r) => !r.success).length;
+        const totalDuration = this.results.reduce((sum, r) => sum + r.durationMs, 0);
+        return {
+            pending: this.queue.length,
+            running: this.running.size,
+            completed,
+            failed,
+            avgDurationMs: this.results.length > 0 ? Math.round(totalDuration / this.results.length) : 0,
+            totalDurationMs: totalDuration,
+        };
+    }
+    /**
+     * Get current queue size
+     */
+    get size() {
+        return this.queue.length;
+    }
+    /**
+     * Get number of running tasks
+     */
+    get pending() {
+        return this.running.size;
+    }
+    /**
+     * Check if queue is idle (no pending or running tasks)
+     */
+    get isIdle() {
+        return this.queue.length === 0 && this.running.size === 0;
+    }
+    /**
+     * Wait for queue to become idle
+     */
+    onIdle() {
+        if (this.isIdle) {
+            return Promise.resolve([...this.results]);
+        }
+        if (!this.idlePromise) {
+            this.idlePromise = new Promise((resolve) => {
+                this.idleResolve = resolve;
+            });
+        }
+        return this.idlePromise;
+    }
+}
+/**
+ * Run tasks with controlled concurrency
+ *
+ * @param tasks - Array of async functions to execute
+ * @param concurrency - Maximum concurrent operations
+ * @returns Array of results in order
+ *
+ * @example
+ * ```typescript
+ * const results = await runConcurrent(
+ *   files.map(f => () => scanFile(f)),
+ *   3
+ * );
+ * ```
+ */
+export async function runConcurrent(tasks, concurrency) {
+    const queue = new PromiseQueue({
+        concurrency: concurrency ?? getConcurrencyLevel(),
+    });
+    const promises = tasks.map((fn, i) => queue.add(fn, { id: `task-${i}` }));
+    return Promise.all(promises);
+}
+/**
+ * Run tasks with controlled concurrency, returning only successful values
+ *
+ * @param tasks - Array of async functions to execute
+ * @param concurrency - Maximum concurrent operations
+ * @returns Array of successful results in order (null for failed)
+ */
+export async function runConcurrentValues(tasks, concurrency) {
+    const results = await runConcurrent(tasks, concurrency);
+    return results.map((r) => (r.success ? r.value : null));
+}
+/**
+ * Map over items with controlled concurrency
+ *
+ * @param items - Items to process
+ * @param fn - Async function to apply to each item
+ * @param concurrency - Maximum concurrent operations
+ * @returns Array of results
+ */
+export async function mapConcurrent(items, fn, concurrency) {
+    const tasks = items.map((item, index) => () => fn(item, index));
+    return runConcurrent(tasks, concurrency);
+}
+/**
+ * Create a throttled version of an async function
+ *
+ * @param fn - Async function to throttle
+ * @param concurrency - Maximum concurrent calls
+ * @returns Throttled function
+ */
+export function throttle(fn, concurrency) {
+    const queue = new PromiseQueue({
+        concurrency: concurrency ?? getConcurrencyLevel(),
+    });
+    return (...args) => queue.add(() => fn(...args));
+}
+/**
+ * Batch items and process batches with controlled concurrency
+ *
+ * @param items - Items to process
+ * @param batchSize - Size of each batch
+ * @param fn - Async function to process a batch
+ * @param concurrency - Maximum concurrent batches
+ */
+export async function batchConcurrent(items, batchSize, fn, concurrency) {
+    // Create batches
+    const batches = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+        batches.push(items.slice(i, i + batchSize));
+    }
+    // Process batches concurrently
+    const tasks = batches.map((batch, index) => () => fn(batch, index));
+    return runConcurrent(tasks, concurrency);
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/util/concurrency.js.map

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

package/dist/util/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility Functions
+ *
+ * Shared utilities for path validation, JSON parsing, and other common operations.
+ *
+ * @module util
+ */
+export { validateProjectPath, validateFilePath, isPathSafe, sanitizePathForLogging, PathValidationError, type ValidatePathOptions, } from "./paths.js";
+export { parseJson, tryParseJson, parseJsonOrDefault, isValidJson, safeStringify, JsonParseError, type ParseJsonOptions, } from "./json.js";
+export { withRetry, withRetryAndCircuitBreaker, createRetryWrapper, classifyError, CircuitBreaker, RetryError, CircuitOpenError, type RetryOptions, type CircuitBreakerOptions, type ErrorType, type CircuitState, } from "./retry.js";
+export { PromiseQueue, runConcurrent, runConcurrentValues, mapConcurrent, throttle, batchConcurrent, getConcurrencyLevel, DEFAULT_CONCURRENCY, type QueueOptions, type QueueTask, type TaskResult, type QueueStats, } from "./concurrency.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/util/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,cAAc,EACd,KAAK,gBAAgB,GACtB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,SAAS,EACT,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACd,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,QAAQ,EACR,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC"}

package/dist/util/index.js

@@ -0,0 +1,12 @@
+/**
+ * Utility Functions
+ *
+ * Shared utilities for path validation, JSON parsing, and other common operations.
+ *
+ * @module util
+ */
+export { validateProjectPath, validateFilePath, isPathSafe, sanitizePathForLogging, PathValidationError, } from "./paths.js";
+export { parseJson, tryParseJson, parseJsonOrDefault, isValidJson, safeStringify, JsonParseError, } from "./json.js";
+export { withRetry, withRetryAndCircuitBreaker, createRetryWrapper, classifyError, CircuitBreaker, RetryError, CircuitOpenError, } from "./retry.js";
+export { PromiseQueue, runConcurrent, runConcurrentValues, mapConcurrent, throttle, batchConcurrent, getConcurrencyLevel, DEFAULT_CONCURRENCY, } from "./concurrency.js";
+//# sourceMappingURL=index.js.map

package/dist/util/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,sBAAsB,EACtB,mBAAmB,GAEpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,cAAc,GAEf,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,SAAS,EACT,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,UAAU,EACV,gBAAgB,GAKjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,QAAQ,EACR,eAAe,EACf,mBAAmB,EACnB,mBAAmB,GAKpB,MAAM,kBAAkB,CAAC"}

package/dist/util/json.d.ts

@@ -0,0 +1,63 @@
+/**
+ * JSON Parsing Utilities
+ *
+ * Safe JSON parsing with context for better error messages.
+ *
+ * @module util/json
+ */
+/**
+ * Error thrown when JSON parsing fails
+ */
+export declare class JsonParseError extends Error {
+    readonly source: string;
+    readonly originalError: Error;
+    readonly rawContent?: string | undefined;
+    constructor(message: string, source: string, originalError: Error, rawContent?: string | undefined);
+}
+/**
+ * Options for JSON parsing
+ */
+export interface ParseJsonOptions {
+    /** Include the raw content in error (default: false, could be large) */
+    includeRawInError?: boolean;
+    /** Maximum length of raw content to include in error */
+    maxRawLength?: number;
+    /** Reviver function for JSON.parse */
+    reviver?: (key: string, value: unknown) => unknown;
+}
+/**
+ * Parse JSON with context for better error messages
+ *
+ * @param raw - The raw JSON string to parse
+ * @param source - A label describing where this JSON came from (e.g., "semgrep output", "npm audit")
+ * @param options - Parsing options
+ * @returns The parsed JSON value
+ * @throws JsonParseError if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const data = parseJson(stdout, "gosec output");
+ * const config = parseJson(fileContent, `config file: ${filePath}`);
+ * ```
+ */
+export declare function parseJson<T = unknown>(raw: string, source: string, options?: ParseJsonOptions): T;
+/**
+ * Try to parse JSON, returning undefined on failure
+ */
+export declare function tryParseJson<T = unknown>(raw: string, source: string, options?: ParseJsonOptions): T | undefined;
+/**
+ * Parse JSON with a default value on failure
+ */
+export declare function parseJsonOrDefault<T>(raw: string, source: string, defaultValue: T, options?: ParseJsonOptions): T;
+/**
+ * Validate that a value is valid JSON (for pre-checks)
+ */
+export declare function isValidJson(raw: string): boolean;
+/**
+ * Safely stringify JSON with error handling
+ */
+export declare function safeStringify(value: unknown, options?: {
+    pretty?: boolean;
+    replacer?: (key: string, value: unknown) => unknown;
+}): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/util/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/util/json.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;aAGrB,MAAM,EAAE,MAAM;aACd,aAAa,EAAE,KAAK;aACpB,UAAU,CAAC,EAAE,MAAM;gBAHnC,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,KAAK,EACpB,UAAU,CAAC,EAAE,MAAM,YAAA;CAKtC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EACnC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,gBAAqB,GAC7B,CAAC,CAgCH;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EACtC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,gBAAqB,GAC7B,CAAC,GAAG,SAAS,CAMf;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,CAAC,EACf,OAAO,GAAE,gBAAqB,GAC7B,CAAC,CAMH;AAyBD;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOhD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CAAO,GACtF,MAAM,CASR"}

package/dist/util/json.js

@@ -0,0 +1,134 @@
+/**
+ * JSON Parsing Utilities
+ *
+ * Safe JSON parsing with context for better error messages.
+ *
+ * @module util/json
+ */
+/**
+ * Error thrown when JSON parsing fails
+ */
+export class JsonParseError extends Error {
+    source;
+    originalError;
+    rawContent;
+    constructor(message, source, originalError, rawContent) {
+        super(message);
+        this.source = source;
+        this.originalError = originalError;
+        this.rawContent = rawContent;
+        this.name = "JsonParseError";
+    }
+}
+/**
+ * Parse JSON with context for better error messages
+ *
+ * @param raw - The raw JSON string to parse
+ * @param source - A label describing where this JSON came from (e.g., "semgrep output", "npm audit")
+ * @param options - Parsing options
+ * @returns The parsed JSON value
+ * @throws JsonParseError if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const data = parseJson(stdout, "gosec output");
+ * const config = parseJson(fileContent, `config file: ${filePath}`);
+ * ```
+ */
+export function parseJson(raw, source, options = {}) {
+    const { includeRawInError = false, maxRawLength = 500, reviver } = options;
+    try {
+        return JSON.parse(raw, reviver);
+    }
+    catch (error) {
+        const originalError = error;
+        // Build a helpful error message
+        let message = `Failed to parse JSON from ${source}`;
+        // Add position info if available
+        const posMatch = originalError.message.match(/position (\d+)/);
+        if (posMatch) {
+            const position = parseInt(posMatch[1], 10);
+            const context = getJsonErrorContext(raw, position);
+            message += `: ${originalError.message}`;
+            if (context) {
+                message += `\n  Near: "${context}"`;
+            }
+        }
+        else {
+            message += `: ${originalError.message}`;
+        }
+        // Include raw content snippet if requested
+        let rawSnippet;
+        if (includeRawInError && raw) {
+            rawSnippet = raw.length > maxRawLength ? raw.slice(0, maxRawLength) + "..." : raw;
+        }
+        throw new JsonParseError(message, source, originalError, rawSnippet);
+    }
+}
+/**
+ * Try to parse JSON, returning undefined on failure
+ */
+export function tryParseJson(raw, source, options = {}) {
+    try {
+        return parseJson(raw, source, options);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parse JSON with a default value on failure
+ */
+export function parseJsonOrDefault(raw, source, defaultValue, options = {}) {
+    try {
+        return parseJson(raw, source, options);
+    }
+    catch {
+        return defaultValue;
+    }
+}
+/**
+ * Get context around a JSON parse error position
+ */
+function getJsonErrorContext(raw, position, contextSize = 30) {
+    if (!raw || position < 0 || position >= raw.length) {
+        return null;
+    }
+    const start = Math.max(0, position - contextSize);
+    const end = Math.min(raw.length, position + contextSize);
+    let context = raw.slice(start, end);
+    // Clean up for display
+    context = context.replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+    // Add ellipsis
+    if (start > 0)
+        context = "..." + context;
+    if (end < raw.length)
+        context = context + "...";
+    return context;
+}
+/**
+ * Validate that a value is valid JSON (for pre-checks)
+ */
+export function isValidJson(raw) {
+    try {
+        JSON.parse(raw);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Safely stringify JSON with error handling
+ */
+export function safeStringify(value, options = {}) {
+    const { pretty = false, replacer } = options;
+    try {
+        return JSON.stringify(value, replacer, pretty ? 2 : undefined);
+    }
+    catch (error) {
+        // Handle circular references and other stringify errors
+        return `[Unserializable: ${error.message}]`;
+    }
+}
+//# sourceMappingURL=json.js.map

package/dist/util/json.js.map

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

package/dist/util/paths.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Path Validation Utilities
+ *
+ * Security-focused path validation to prevent path traversal attacks
+ * and ensure paths are within allowed boundaries.
+ *
+ * @module util/paths
+ */
+/**
+ * Error thrown when path validation fails
+ */
+export declare class PathValidationError extends Error {
+    readonly path: string;
+    readonly reason: "not_found" | "not_directory" | "symlink_escape" | "path_traversal" | "invalid_path";
+    constructor(message: string, path: string, reason: "not_found" | "not_directory" | "symlink_escape" | "path_traversal" | "invalid_path");
+}
+/**
+ * Options for path validation
+ */
+export interface ValidatePathOptions {
+    /** Require the path to be a directory (default: true) */
+    requireDirectory?: boolean;
+    /** Allow symlinks (default: false - symlinks are resolved and checked) */
+    allowSymlinks?: boolean;
+    /** Base directory that the path must be within (optional) */
+    basePath?: string;
+}
+/**
+ * Validate a project path for security
+ *
+ * Checks:
+ * 1. Path is absolute after resolution
+ * 2. Path exists on the filesystem
+ * 3. Path is a directory (optional)
+ * 4. Symlinks are resolved and checked (optional)
+ * 5. Path doesn't escape base directory (optional)
+ *
+ * @param projectPath - The path to validate
+ * @param options - Validation options
+ * @returns The validated, resolved absolute path
+ * @throws PathValidationError if validation fails
+ */
+export declare function validateProjectPath(projectPath: string, options?: ValidatePathOptions): Promise<string>;
+/**
+ * Validate a file path (not requiring directory)
+ */
+export declare function validateFilePath(filePath: string, options?: Omit<ValidatePathOptions, "requireDirectory">): Promise<string>;
+/**
+ * Check if a path is safe (doesn't throw, returns boolean)
+ */
+export declare function isPathSafe(projectPath: string, options?: ValidatePathOptions): Promise<boolean>;
+/**
+ * Sanitize a path for use in error messages (remove sensitive info)
+ */
+export declare function sanitizePathForLogging(inputPath: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/util/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/util/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,IAAI,EAAE,MAAM;aACZ,MAAM,EAClB,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,cAAc;gBAPlB,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,EAClB,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,cAAc;CAKrB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,CAAC,CAiGjB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,kBAAkB,CAAM,GAC1D,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOhE"}