@jterrats/smart-deployment 1.0.3

package/lib/dependencies/dependency-cache.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Dependency Cache
+ * Caches dependency analysis results for faster subsequent runs
+ *
+ * @ac US-036-AC-1: Cache graph structure
+ * @ac US-036-AC-2: Invalidate cache on file changes
+ * @ac US-036-AC-3: Cache topological sort results
+ * @ac US-036-AC-4: Cache cycle detection results
+ * @ac US-036-AC-5: Cache heuristic inferences
+ * @ac US-036-AC-6: Configurable cache TTL
+ *
+ * @issue #36
+ */
+/**
+ * Cache entry structure
+ */
+export type CacheEntry<T> = {
+    data: T;
+    timestamp: number;
+    version: string;
+    fileHashes: Map<string, string>;
+};
+/**
+ * Cache key types
+ */
+export type CacheKey = 'graph' | 'topological-sort' | 'circular-dependencies' | 'heuristic-inferences' | 'depth-analysis' | 'impact-analysis';
+/**
+ * Cache options
+ */
+export type CacheOptions = {
+    /** Cache directory */
+    cacheDir?: string;
+    /** Time to live in seconds (default: 3600 = 1 hour) */
+    ttl?: number;
+    /** Enable cache (default: true) */
+    enabled?: boolean;
+    /** Cache version (for invalidation) */
+    version?: string;
+};
+/**
+ * Dependency Cache
+ *
+ * Caches dependency analysis results to speed up subsequent runs.
+ * Automatically invalidates cache when files change.
+ *
+ * Performance: O(1) read/write
+ *
+ * @example
+ * const cache = new DependencyCache({ ttl: 3600 });
+ *
+ * // Try to load from cache
+ * const graph = await cache.get('graph', filePaths);
+ * if (graph) {
+ *   console.log('Using cached graph');
+ * } else {
+ *   const newGraph = buildGraph();
+ *   await cache.set('graph', newGraph, filePaths);
+ * }
+ */
+export declare class DependencyCache {
+    private options;
+    private memoryCache;
+    constructor(options?: CacheOptions);
+    /**
+     * @ac US-036-AC-1: Cache graph structure
+     */
+    get<T>(key: CacheKey, filePaths: string[]): Promise<T | undefined>;
+    /**
+     * @ac US-036-AC-1: Cache graph structure
+     * @ac US-036-AC-3: Cache topological sort results
+     * @ac US-036-AC-4: Cache cycle detection results
+     * @ac US-036-AC-5: Cache heuristic inferences
+     */
+    set<T>(key: CacheKey, data: T, filePaths: string[]): Promise<void>;
+    /**
+     * @ac US-036-AC-2: Invalidate cache on file changes
+     */
+    invalidate(key: CacheKey): Promise<void>;
+    /**
+     * Invalidate all cache entries
+     */
+    invalidateAll(): Promise<void>;
+    /**
+     * Delete a cache entry
+     */
+    private delete;
+    /**
+     * @ac US-036-AC-2: Invalidate cache on file changes
+     * @ac US-036-AC-6: Configurable cache TTL
+     */
+    private isValid;
+    /**
+     * Hash files for change detection
+     */
+    private hashFiles;
+    /**
+     * Get cache file path
+     */
+    private getCacheFilePath;
+    /**
+     * JSON replacer for Sets and Maps
+     */
+    private replacer;
+    /**
+     * JSON reviver for Sets and Maps
+     */
+    private reviver;
+    private isSerializedSet;
+    private isSerializedMap;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        memoryEntries: number;
+        enabled: boolean;
+        ttl: number;
+    };
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Enable cache
+     */
+    enable(): void;
+    /**
+     * Disable cache
+     */
+    disable(): void;
+}
+/**
+ * Helper: Create a cache key from file paths
+ */
+export declare function createCacheKey(baseKey: CacheKey, filePaths: string[]): string;

package/lib/dependencies/dependency-cache.js

@@ -0,0 +1,303 @@
+/**
+ * Dependency Cache
+ * Caches dependency analysis results for faster subsequent runs
+ *
+ * @ac US-036-AC-1: Cache graph structure
+ * @ac US-036-AC-2: Invalidate cache on file changes
+ * @ac US-036-AC-3: Cache topological sort results
+ * @ac US-036-AC-4: Cache cycle detection results
+ * @ac US-036-AC-5: Cache heuristic inferences
+ * @ac US-036-AC-6: Configurable cache TTL
+ *
+ * @issue #36
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { getLogger } from '../utils/logger.js';
+const logger = getLogger('DependencyCache');
+/**
+ * Dependency Cache
+ *
+ * Caches dependency analysis results to speed up subsequent runs.
+ * Automatically invalidates cache when files change.
+ *
+ * Performance: O(1) read/write
+ *
+ * @example
+ * const cache = new DependencyCache({ ttl: 3600 });
+ *
+ * // Try to load from cache
+ * const graph = await cache.get('graph', filePaths);
+ * if (graph) {
+ *   console.log('Using cached graph');
+ * } else {
+ *   const newGraph = buildGraph();
+ *   await cache.set('graph', newGraph, filePaths);
+ * }
+ */
+export class DependencyCache {
+    options;
+    memoryCache;
+    constructor(options = {}) {
+        this.options = {
+            cacheDir: options.cacheDir ?? path.join(process.cwd(), '.sf-deploy-cache'),
+            ttl: options.ttl ?? 3600,
+            enabled: options.enabled ?? true,
+            version: options.version ?? '1.0.0',
+        };
+        this.memoryCache = new Map();
+        logger.debug('Initialized DependencyCache', {
+            cacheDir: this.options.cacheDir,
+            ttl: this.options.ttl,
+            enabled: this.options.enabled,
+        });
+    }
+    /**
+     * @ac US-036-AC-1: Cache graph structure
+     */
+    async get(key, filePaths) {
+        if (!this.options.enabled) {
+            return undefined;
+        }
+        // Try memory cache first
+        const memEntry = this.memoryCache.get(key);
+        if (memEntry && (await this.isValid(memEntry, filePaths))) {
+            logger.debug('Cache hit (memory)', { key });
+            return memEntry.data;
+        }
+        // Try disk cache
+        try {
+            const cacheFile = this.getCacheFilePath(key);
+            const content = await fs.readFile(cacheFile, 'utf-8');
+            const entry = JSON.parse(content, (_key, value) => this.reviver(_key, value));
+            if (await this.isValid(entry, filePaths)) {
+                // Store in memory for faster access
+                this.memoryCache.set(key, entry);
+                logger.debug('Cache hit (disk)', { key });
+                return entry.data;
+            }
+            else {
+                logger.debug('Cache invalid', { key });
+                await this.delete(key);
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                logger.warn('Failed to read cache', { key, error });
+            }
+        }
+        logger.debug('Cache miss', { key });
+        return undefined;
+    }
+    /**
+     * @ac US-036-AC-1: Cache graph structure
+     * @ac US-036-AC-3: Cache topological sort results
+     * @ac US-036-AC-4: Cache cycle detection results
+     * @ac US-036-AC-5: Cache heuristic inferences
+     */
+    async set(key, data, filePaths) {
+        if (!this.options.enabled) {
+            return;
+        }
+        const fileHashes = await this.hashFiles(filePaths);
+        const entry = {
+            data,
+            timestamp: Date.now(),
+            version: this.options.version,
+            fileHashes,
+        };
+        // Store in memory
+        this.memoryCache.set(key, entry);
+        // Store on disk
+        try {
+            await fs.mkdir(this.options.cacheDir, { recursive: true });
+            const cacheFile = this.getCacheFilePath(key);
+            const content = JSON.stringify(entry, (_key, value) => this.replacer(_key, value), 2);
+            await fs.writeFile(cacheFile, content, 'utf-8');
+            logger.debug('Cache stored', { key, files: filePaths.length });
+        }
+        catch (error) {
+            logger.warn('Failed to write cache', { key, error });
+        }
+    }
+    /**
+     * @ac US-036-AC-2: Invalidate cache on file changes
+     */
+    async invalidate(key) {
+        await this.delete(key);
+        logger.debug('Cache invalidated', { key });
+    }
+    /**
+     * Invalidate all cache entries
+     */
+    async invalidateAll() {
+        this.memoryCache.clear();
+        try {
+            await fs.rm(this.options.cacheDir, { recursive: true, force: true });
+            logger.debug('All cache invalidated');
+        }
+        catch (error) {
+            logger.warn('Failed to invalidate all cache', { error });
+        }
+    }
+    /**
+     * Delete a cache entry
+     */
+    async delete(key) {
+        this.memoryCache.delete(key);
+        try {
+            const cacheFile = this.getCacheFilePath(key);
+            await fs.unlink(cacheFile);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                logger.warn('Failed to delete cache file', { key, error });
+            }
+        }
+    }
+    /**
+     * @ac US-036-AC-2: Invalidate cache on file changes
+     * @ac US-036-AC-6: Configurable cache TTL
+     */
+    async isValid(entry, filePaths) {
+        // Check version
+        if (entry.version !== this.options.version) {
+            logger.debug('Cache version mismatch', {
+                cached: entry.version,
+                current: this.options.version,
+            });
+            return false;
+        }
+        // Check TTL
+        const age = (Date.now() - entry.timestamp) / 1000;
+        if (age > this.options.ttl) {
+            logger.debug('Cache expired', { age, ttl: this.options.ttl });
+            return false;
+        }
+        // Check file hashes
+        const currentHashes = await this.hashFiles(filePaths);
+        if (currentHashes.size !== entry.fileHashes.size) {
+            logger.debug('File count changed', {
+                cached: entry.fileHashes.size,
+                current: currentHashes.size,
+            });
+            return false;
+        }
+        for (const [file, hash] of currentHashes.entries()) {
+            if (entry.fileHashes.get(file) !== hash) {
+                logger.debug('File modified', { file });
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Hash files for change detection
+     */
+    async hashFiles(filePaths) {
+        const hashes = new Map();
+        let chain = Promise.resolve();
+        filePaths.forEach((filePath) => {
+            chain = chain.then(async () => {
+                try {
+                    const stat = await fs.stat(filePath);
+                    // Simple hash: mtime + size
+                    const hash = crypto.createHash('md5').update(`${stat.mtimeMs}-${stat.size}`).digest('hex');
+                    hashes.set(filePath, hash);
+                }
+                catch (error) {
+                    logger.warn('Failed to hash file', { filePath, error });
+                }
+            });
+        });
+        await chain;
+        return hashes;
+    }
+    /**
+     * Get cache file path
+     */
+    getCacheFilePath(key) {
+        return path.join(this.options.cacheDir, `${key}.json`);
+    }
+    /**
+     * JSON replacer for Sets and Maps
+     */
+    replacer(_key, value) {
+        if (value instanceof Set) {
+            return { kind: 'Set', data: Array.from(value) };
+        }
+        if (value instanceof Map) {
+            return { kind: 'Map', data: Array.from(value.entries()) };
+        }
+        return value;
+    }
+    /**
+     * JSON reviver for Sets and Maps
+     */
+    reviver(_key, value) {
+        if (typeof value === 'object' && value !== null) {
+            if (this.isSerializedSet(value)) {
+                return new Set(value.data);
+            }
+            if (this.isSerializedMap(value)) {
+                return new Map(value.data);
+            }
+        }
+        return value;
+    }
+    isSerializedSet(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            'kind' in value &&
+            'data' in value &&
+            value.kind === 'Set' &&
+            Array.isArray(value.data));
+    }
+    isSerializedMap(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            'kind' in value &&
+            'data' in value &&
+            value.kind === 'Map' &&
+            Array.isArray(value.data));
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return {
+            memoryEntries: this.memoryCache.size,
+            enabled: this.options.enabled,
+            ttl: this.options.ttl,
+        };
+    }
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled() {
+        return this.options.enabled;
+    }
+    /**
+     * Enable cache
+     */
+    enable() {
+        this.options.enabled = true;
+        logger.debug('Cache enabled');
+    }
+    /**
+     * Disable cache
+     */
+    disable() {
+        this.options.enabled = false;
+        logger.debug('Cache disabled');
+    }
+}
+/**
+ * Helper: Create a cache key from file paths
+ */
+export function createCacheKey(baseKey, filePaths) {
+    const hash = crypto.createHash('md5').update(filePaths.sort().join('|')).digest('hex');
+    return `${baseKey}-${hash.substring(0, 8)}`;
+}
+//# sourceMappingURL=dependency-cache.js.map

package/lib/dependencies/dependency-cache.js.map

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

package/lib/dependencies/dependency-depth-calculator.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Dependency Depth Calculator
+ * Calculates dependency depth for each component to identify high-risk components
+ *
+ * @ac US-031-AC-1: Calculate depth from leaf nodes
+ * @ac US-031-AC-2: Identify components with depth > 10 (warning)
+ * @ac US-031-AC-3: Generate depth distribution report
+ * @ac US-031-AC-4: Highlight critical path components
+ * @ac US-031-AC-5: Consider cycle depth as infinite
+ *
+ * @issue #31
+ */
+import type { NodeId, DependencyGraph, CircularDependency } from '../types/dependency.js';
+/**
+ * Depth information for a component
+ */
+export type ComponentDepth = {
+    nodeId: NodeId;
+    depth: number;
+    isInCycle: boolean;
+    isLeaf: boolean;
+    isHighRisk: boolean;
+    isCriticalPath: boolean;
+    pathToLeaf: NodeId[];
+};
+/**
+ * Depth distribution report
+ */
+export type DepthDistribution = {
+    depthRange: string;
+    count: number;
+    percentage: number;
+    components: NodeId[];
+};
+/**
+ * Complete depth analysis result
+ */
+export type DepthAnalysisResult = {
+    /** Depth information for each component */
+    depths: Map<NodeId, ComponentDepth>;
+    /** Components with depth > 10 */
+    highRiskComponents: ComponentDepth[];
+    /** Critical path (longest dependency chain) */
+    criticalPath: NodeId[];
+    /** Maximum depth in the graph */
+    maxDepth: number;
+    /** Average depth */
+    averageDepth: number;
+    /** Depth distribution */
+    distribution: DepthDistribution[];
+    /** Components in cycles (infinite depth) */
+    cyclicComponents: NodeId[];
+};
+/**
+ * Options for depth calculation
+ */
+export type DepthCalculationOptions = {
+    /** Circular dependencies to consider */
+    circularDependencies?: CircularDependency[];
+    /** Depth threshold for high-risk warning */
+    highRiskThreshold?: number;
+};
+/**
+ * Dependency Depth Calculator
+ *
+ * Calculates the dependency depth of each component from leaf nodes.
+ * Leaf nodes (no dependencies) have depth 0.
+ * Components depending on others have depth = max(dep.depth) + 1.
+ *
+ * Performance: O(V + E) using topological sort
+ *
+ * @example
+ * const calculator = new DependencyDepthCalculator(graph);
+ * const result = calculator.calculate();
+ * console.log(`Max depth: ${result.maxDepth}`);
+ * console.log(`High-risk: ${result.highRiskComponents.length}`);
+ */
+export declare class DependencyDepthCalculator {
+    private graph;
+    private options;
+    private cyclicNodes;
+    constructor(graph: DependencyGraph, options?: DepthCalculationOptions);
+    /**
+     * @ac US-031-AC-4: Highlight critical path components
+     *
+     * Find the critical path (longest dependency chain)
+     */
+    private static findCriticalPath;
+    /**
+     * @ac US-031-AC-3: Generate depth distribution report
+     */
+    private static generateDistribution;
+    /**
+     * Calculate maximum depth
+     */
+    private static calculateMaxDepth;
+    /**
+     * Calculate average depth (excluding cyclic nodes)
+     */
+    private static calculateAverageDepth;
+    /**
+     * Calculate depths for all components
+     *
+     * @ac US-031-AC-1: Calculate depth from leaf nodes
+     * @ac US-031-AC-2: Identify components with depth > 10
+     * @ac US-031-AC-5: Consider cycle depth as infinite
+     */
+    calculate(): DepthAnalysisResult;
+    /**
+     * Calculate depth for all nodes using BFS from leaf nodes
+     */
+    private calculateDepths;
+    /**
+     * Calculate in-degree for each node
+     */
+    private calculateInDegree;
+    /**
+     * Initialize leaf nodes in the queue
+     */
+    private initializeLeafNodes;
+    /**
+     * Process nodes in BFS order
+     */
+    private processNodesInBFS;
+    /**
+     * Update candidate node depth if this path is longer
+     */
+    private updateCandidateDepth;
+    /**
+     * Process remaining nodes not yet in depths map
+     */
+    private processRemainingNodes;
+    /**
+     * Calculate depth for a single node based on its dependencies
+     */
+    private calculateNodeDepth;
+    /**
+     * @ac US-031-AC-2: Identify components with depth > 10
+     */
+    private findHighRiskComponents;
+    /**
+     * Get depth for a specific component
+     */
+    getDepth(nodeId: NodeId): ComponentDepth | undefined;
+}