@selvakumaresra/specship 0.1.3 → 0.3.0

package/dist/utils.d.ts

@@ -0,0 +1,205 @@
+/**
+ * SpecShip Utilities
+ *
+ * Common utility functions for memory management, concurrency, batching,
+ * and security validation.
+ *
+ * @module utils
+ *
+ * @example
+ * ```typescript
+ * import { Mutex, processInBatches, MemoryMonitor, validatePathWithinRoot } from 'specship';
+ *
+ * // Use mutex for concurrent safety
+ * const mutex = new Mutex();
+ * await mutex.withLock(async () => {
+ *   await performCriticalOperation();
+ * });
+ *
+ * // Process items in batches to manage memory
+ * const results = await processInBatches(items, 100, async (item) => {
+ *   return await processItem(item);
+ * });
+ *
+ * // Monitor memory usage
+ * const monitor = new MemoryMonitor(512, (usage) => {
+ *   console.warn(`Memory usage exceeded 512MB: ${usage / 1024 / 1024}MB`);
+ * });
+ * monitor.start();
+ * ```
+ */
+/**
+ * Validate that a resolved file path stays within the project root.
+ * Prevents path traversal attacks (e.g. node.filePath = "../../etc/passwd").
+ *
+ * @param projectRoot - The project root directory
+ * @param filePath - The relative file path to validate
+ * @returns The resolved absolute path, or null if it escapes the root
+ */
+export declare function validatePathWithinRoot(projectRoot: string, filePath: string): string | null;
+/**
+ * Validate that a path is a safe project root directory.
+ *
+ * Rejects sensitive system directories and ensures the path is
+ * a real, existing directory. Used at MCP and API entry points
+ * to prevent arbitrary directory access.
+ *
+ * @param dirPath - The path to validate
+ * @returns An error message if invalid, or null if valid
+ */
+export declare function validateProjectPath(dirPath: string): string | null;
+/**
+ * Check if a file path resolves to a location within the given root directory.
+ *
+ * Prevents path traversal attacks by ensuring the resolved absolute path
+ * starts with the resolved root path. Handles '..' sequences, symlink-like
+ * relative paths, and platform-specific separators.
+ *
+ * @param filePath - The path to check (can be relative or absolute)
+ * @param rootDir - The root directory that filePath must stay within
+ * @returns true if filePath resolves to a location within rootDir
+ */
+export declare function isPathWithinRoot(filePath: string, rootDir: string): boolean;
+/**
+ * Like isPathWithinRoot but also resolves symlinks via fs.realpathSync.
+ *
+ * This catches symlink escapes where the logical path appears to be within
+ * root but the real path on disk points elsewhere. Falls back to logical
+ * path checking if realpath resolution fails (e.g. broken symlink).
+ */
+export declare function isPathWithinRootReal(filePath: string, rootDir: string): boolean;
+/**
+ * Safely parse JSON with a fallback value.
+ * Prevents crashes from corrupted database metadata.
+ */
+export declare function safeJsonParse<T>(value: string, fallback: T): T;
+/**
+ * Clamp a numeric value to a range.
+ * Used to enforce sane limits on MCP tool inputs.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Normalize a file path to use forward slashes.
+ * Fixes Windows backslash paths so glob matching works consistently.
+ */
+export declare function normalizePath(filePath: string): string;
+/**
+ * Cross-process file lock using a lock file with PID tracking.
+ *
+ * Prevents multiple processes (e.g., git hooks, CLI, MCP server) from
+ * writing to the same database simultaneously.
+ */
+export declare class FileLock {
+    private lockPath;
+    private held;
+    /** Locks older than this are considered stale regardless of PID status */
+    private static readonly STALE_TIMEOUT_MS;
+    constructor(lockPath: string);
+    /**
+     * Acquire the lock. Throws if the lock is held by another live process.
+     */
+    acquire(): void;
+    /**
+     * Release the lock
+     */
+    release(): void;
+    /**
+     * Execute a function while holding the lock
+     */
+    withLock<T>(fn: () => T): T;
+    /**
+     * Execute an async function while holding the lock
+     */
+    withLockAsync<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Check if a process is still running
+     */
+    private isProcessAlive;
+}
+/**
+ * Process items in batches to manage memory
+ *
+ * @param items - Array of items to process
+ * @param batchSize - Number of items per batch
+ * @param processor - Function to process each item
+ * @param onBatchComplete - Optional callback after each batch
+ * @returns Array of results
+ */
+export declare function processInBatches<T, R>(items: T[], batchSize: number, processor: (item: T, index: number) => Promise<R>, onBatchComplete?: (completed: number, total: number) => void): Promise<R[]>;
+/**
+ * Simple mutex lock for preventing concurrent operations
+ */
+export declare class Mutex {
+    private locked;
+    private waitQueue;
+    /**
+     * Acquire the lock
+     *
+     * @returns A release function to call when done
+     */
+    acquire(): Promise<() => void>;
+    /**
+     * Execute a function while holding the lock
+     */
+    withLock<T>(fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * Check if the lock is currently held
+     */
+    isLocked(): boolean;
+}
+/**
+ * Chunked file reader for large files
+ *
+ * Reads a file in chunks to avoid loading entire file into memory.
+ */
+export declare function readFileInChunks(filePath: string, chunkSize?: number): AsyncGenerator<string, void, undefined>;
+/**
+ * Debounce a function
+ *
+ * @param fn - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ */
+export declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle a function
+ *
+ * @param fn - Function to throttle
+ * @param limit - Minimum time between calls in milliseconds
+ * @returns Throttled function
+ */
+export declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * Estimate memory usage of an object (rough approximation)
+ *
+ * @param obj - Object to measure
+ * @returns Approximate size in bytes
+ */
+export declare function estimateSize(obj: unknown): number;
+/**
+ * Memory monitor for tracking usage during operations
+ */
+export declare class MemoryMonitor {
+    private checkInterval;
+    private peakUsage;
+    private threshold;
+    private onThresholdExceeded?;
+    constructor(thresholdMB?: number, onThresholdExceeded?: (usage: number) => void);
+    /**
+     * Start monitoring memory usage
+     */
+    start(intervalMs?: number): void;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    /**
+     * Get peak memory usage in bytes
+     */
+    getPeakUsage(): number;
+    /**
+     * Get current memory usage in bytes
+     */
+    getCurrentUsage(): number;
+}
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

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