@selvakumaresra/specship 0.1.1 → 0.1.3

package/dist/utils.d.ts

@@ -1,205 +0,0 @@
-/**
- * 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

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