@jterrats/smart-deployment 1.0.3

package/lib/dependencies/dependency-depth-calculator.js

@@ -0,0 +1,368 @@
+/**
+ * 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 { getLogger } from '../utils/logger.js';
+const logger = getLogger('DependencyDepthCalculator');
+/**
+ * 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 class DependencyDepthCalculator {
+    graph;
+    options;
+    cyclicNodes;
+    constructor(graph, options = {}) {
+        this.graph = graph;
+        this.options = {
+            circularDependencies: options.circularDependencies ?? [],
+            highRiskThreshold: options.highRiskThreshold ?? 10,
+        };
+        // Build set of cyclic nodes for O(1) lookup
+        this.cyclicNodes = new Set();
+        for (const cycle of this.options.circularDependencies) {
+            for (const nodeId of cycle.cycle) {
+                this.cyclicNodes.add(nodeId);
+            }
+        }
+        logger.debug('Initialized DependencyDepthCalculator', {
+            nodes: this.graph.size,
+            cyclicNodes: this.cyclicNodes.size,
+            highRiskThreshold: this.options.highRiskThreshold,
+        });
+    }
+    // Private static helper methods (must come before public methods)
+    /**
+     * @ac US-031-AC-4: Highlight critical path components
+     *
+     * Find the critical path (longest dependency chain)
+     */
+    static findCriticalPath(depths) {
+        let longestPath = [];
+        let maxDepth = 0;
+        for (const depth of depths.values()) {
+            // Skip cyclic nodes
+            if (depth.isInCycle || depth.depth === Number.POSITIVE_INFINITY) {
+                continue;
+            }
+            if (depth.depth > maxDepth) {
+                maxDepth = depth.depth;
+                longestPath = depth.pathToLeaf;
+            }
+        }
+        // Mark nodes in critical path
+        const criticalPathSet = new Set(longestPath);
+        for (const [nodeId, depth] of depths.entries()) {
+            if (criticalPathSet.has(nodeId)) {
+                depth.isCriticalPath = true;
+            }
+        }
+        logger.info('Critical path identified', {
+            length: longestPath.length,
+            depth: maxDepth,
+        });
+        return longestPath;
+    }
+    /**
+     * @ac US-031-AC-3: Generate depth distribution report
+     */
+    static generateDistribution(depths) {
+        const ranges = [
+            { range: '0-5', min: 0, max: 5 },
+            { range: '6-10', min: 6, max: 10 },
+            { range: '11-20', min: 11, max: 20 },
+            { range: '21-50', min: 21, max: 50 },
+            { range: '>50', min: 51, max: Number.POSITIVE_INFINITY },
+        ];
+        const distribution = [];
+        const total = depths.size;
+        for (const { range, min, max } of ranges) {
+            const components = [];
+            for (const depth of depths.values()) {
+                // Handle infinite depth (cycles)
+                if (depth.depth === Number.POSITIVE_INFINITY && max === Number.POSITIVE_INFINITY) {
+                    components.push(depth.nodeId);
+                }
+                else if (depth.depth >= min && depth.depth <= max) {
+                    components.push(depth.nodeId);
+                }
+            }
+            if (components.length > 0) {
+                distribution.push({
+                    depthRange: range,
+                    count: components.length,
+                    percentage: (components.length / total) * 100,
+                    components,
+                });
+            }
+        }
+        return distribution;
+    }
+    /**
+     * Calculate maximum depth
+     */
+    static calculateMaxDepth(depths) {
+        let maxDepth = 0;
+        for (const depth of depths.values()) {
+            if (depth.depth !== Number.POSITIVE_INFINITY) {
+                maxDepth = Math.max(maxDepth, depth.depth);
+            }
+        }
+        return maxDepth;
+    }
+    /**
+     * Calculate average depth (excluding cyclic nodes)
+     */
+    static calculateAverageDepth(depths) {
+        let sum = 0;
+        let count = 0;
+        for (const depth of depths.values()) {
+            if (depth.depth !== Number.POSITIVE_INFINITY) {
+                sum += depth.depth;
+                count++;
+            }
+        }
+        return count > 0 ? sum / count : 0;
+    }
+    // Public methods
+    /**
+     * 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() {
+        const startTime = Date.now();
+        // Calculate depth for each node
+        const depths = this.calculateDepths();
+        // Find high-risk components
+        const highRiskComponents = this.findHighRiskComponents(depths);
+        // Find critical path
+        const criticalPath = DependencyDepthCalculator.findCriticalPath(depths);
+        // Generate distribution
+        const distribution = DependencyDepthCalculator.generateDistribution(depths);
+        // Calculate statistics
+        const maxDepth = DependencyDepthCalculator.calculateMaxDepth(depths);
+        const averageDepth = DependencyDepthCalculator.calculateAverageDepth(depths);
+        const duration = Date.now() - startTime;
+        logger.info('Depth calculation completed', {
+            totalNodes: depths.size,
+            maxDepth,
+            averageDepth: averageDepth.toFixed(2),
+            highRisk: highRiskComponents.length,
+            cyclicNodes: this.cyclicNodes.size,
+            durationMs: duration,
+        });
+        return {
+            depths,
+            highRiskComponents,
+            criticalPath,
+            maxDepth,
+            averageDepth,
+            distribution,
+            cyclicComponents: Array.from(this.cyclicNodes),
+        };
+    }
+    /**
+     * Calculate depth for all nodes using BFS from leaf nodes
+     */
+    calculateDepths() {
+        const depths = new Map();
+        const inDegree = this.calculateInDegree();
+        const queue = this.initializeLeafNodes(depths, inDegree);
+        this.processNodesInBFS(depths, queue);
+        this.processRemainingNodes(depths);
+        return depths;
+    }
+    /**
+     * Calculate in-degree for each node
+     */
+    calculateInDegree() {
+        const inDegree = new Map();
+        for (const nodeId of this.graph.keys()) {
+            inDegree.set(nodeId, 0);
+        }
+        for (const deps of this.graph.values()) {
+            for (const dep of deps) {
+                if (inDegree.has(dep)) {
+                    inDegree.set(dep, (inDegree.get(dep) ?? 0) + 1);
+                }
+                else {
+                    inDegree.set(dep, 1);
+                }
+            }
+        }
+        return inDegree;
+    }
+    /**
+     * Initialize leaf nodes in the queue
+     */
+    initializeLeafNodes(depths, inDegree) {
+        const queue = [];
+        for (const [nodeId] of inDegree.entries()) {
+            const isInCycle = this.cyclicNodes.has(nodeId);
+            const isLeaf = (this.graph.get(nodeId)?.size ?? 0) === 0;
+            if (isLeaf && !isInCycle) {
+                queue.push({ nodeId, depth: 0, path: [nodeId] });
+                depths.set(nodeId, {
+                    nodeId,
+                    depth: 0,
+                    isInCycle: false,
+                    isLeaf: true,
+                    isHighRisk: false,
+                    isCriticalPath: false,
+                    pathToLeaf: [nodeId],
+                });
+            }
+            else if (isInCycle) {
+                // Mark cyclic nodes with infinite depth
+                depths.set(nodeId, {
+                    nodeId,
+                    depth: Number.POSITIVE_INFINITY,
+                    isInCycle: true,
+                    isLeaf: false,
+                    isHighRisk: true,
+                    isCriticalPath: false,
+                    pathToLeaf: [],
+                });
+            }
+        }
+        return queue;
+    }
+    /**
+     * Process nodes in BFS order
+     */
+    processNodesInBFS(depths, queue) {
+        const processed = new Set();
+        while (queue.length > 0) {
+            const { nodeId, path } = queue.shift();
+            if (processed.has(nodeId)) {
+                continue;
+            }
+            processed.add(nodeId);
+            // Find all nodes that depend on this node (reverse edges)
+            for (const [candidateId, candidateDeps] of this.graph.entries()) {
+                if (candidateDeps.has(nodeId) && !this.cyclicNodes.has(candidateId)) {
+                    this.updateCandidateDepth(candidateId, path, depths, queue);
+                }
+            }
+        }
+    }
+    /**
+     * Update candidate node depth if this path is longer
+     */
+    updateCandidateDepth(candidateId, path, depths, queue) {
+        const candidateDepth = this.calculateNodeDepth(candidateId, depths);
+        // Update if this is a longer path
+        const existing = depths.get(candidateId);
+        if (!existing || candidateDepth > existing.depth) {
+            const newPath = [...path, candidateId];
+            depths.set(candidateId, {
+                nodeId: candidateId,
+                depth: candidateDepth,
+                isInCycle: false,
+                isLeaf: false,
+                isHighRisk: candidateDepth > this.options.highRiskThreshold,
+                isCriticalPath: false,
+                pathToLeaf: newPath,
+            });
+            queue.push({ nodeId: candidateId, depth: candidateDepth, path: newPath });
+        }
+    }
+    /**
+     * Process remaining nodes not yet in depths map
+     */
+    processRemainingNodes(depths) {
+        for (const nodeId of this.graph.keys()) {
+            if (!depths.has(nodeId) && !this.cyclicNodes.has(nodeId)) {
+                const nodeDepth = this.calculateNodeDepth(nodeId, depths);
+                depths.set(nodeId, {
+                    nodeId,
+                    depth: nodeDepth,
+                    isInCycle: false,
+                    isLeaf: (this.graph.get(nodeId)?.size ?? 0) === 0,
+                    isHighRisk: nodeDepth > this.options.highRiskThreshold,
+                    isCriticalPath: false,
+                    pathToLeaf: [nodeId],
+                });
+            }
+        }
+    }
+    /**
+     * Calculate depth for a single node based on its dependencies
+     */
+    calculateNodeDepth(nodeId, depths) {
+        const deps = this.graph.get(nodeId);
+        if (!deps || deps.size === 0) {
+            return 0; // Leaf node
+        }
+        let maxDepth = 0;
+        for (const depId of deps) {
+            const depDepth = depths.get(depId);
+            if (depDepth) {
+                if (depDepth.isInCycle) {
+                    return Number.POSITIVE_INFINITY; // Depends on cyclic node
+                }
+                maxDepth = Math.max(maxDepth, depDepth.depth);
+            }
+        }
+        return maxDepth + 1;
+    }
+    /**
+     * @ac US-031-AC-2: Identify components with depth > 10
+     */
+    findHighRiskComponents(depths) {
+        const highRisk = [];
+        for (const depth of depths.values()) {
+            if (depth.isHighRisk) {
+                highRisk.push(depth);
+            }
+        }
+        // Sort by depth (highest first)
+        highRisk.sort((a, b) => {
+            if (a.depth === Number.POSITIVE_INFINITY && b.depth === Number.POSITIVE_INFINITY) {
+                return 0;
+            }
+            if (a.depth === Number.POSITIVE_INFINITY) {
+                return -1;
+            }
+            if (b.depth === Number.POSITIVE_INFINITY) {
+                return 1;
+            }
+            return b.depth - a.depth;
+        });
+        logger.info('High-risk components identified', {
+            count: highRisk.length,
+            threshold: this.options.highRiskThreshold,
+        });
+        return highRisk;
+    }
+    /**
+     * Get depth for a specific component
+     */
+    getDepth(nodeId) {
+        const depths = this.calculate();
+        return depths.depths.get(nodeId);
+    }
+}
+//# sourceMappingURL=dependency-depth-calculator.js.map

package/lib/dependencies/dependency-depth-calculator.js.map

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

package/lib/dependencies/dependency-graph-builder.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Dependency Graph Builder
+ * Builds a dependency graph from parsed metadata components
+ *
+ * @ac US-028-AC-1: Add nodes for each component
+ * @ac US-028-AC-2: Add edges for each dependency
+ * @ac US-028-AC-3: Handle bidirectional dependencies
+ * @ac US-028-AC-4: Track dependency types (hard, soft)
+ * @ac US-028-AC-5: Support incremental graph building
+ * @ac US-028-AC-6: Validate graph structure
+ *
+ * @issue #28
+ */
+import type { MetadataComponent } from '../types/metadata.js';
+import type { NodeId, DependencyAnalysisResult } from '../types/dependency.js';
+/**
+ * Dependency types for tracking relationship strength
+ */
+export type DependencyType = 'hard' | 'soft' | 'inferred';
+/**
+ * Extended edge information
+ */
+export type DependencyEdge = {
+    from: NodeId;
+    to: NodeId;
+    type: DependencyType;
+    reason?: string;
+};
+/**
+ * Options for building the dependency graph
+ */
+export type GraphBuilderOptions = {
+    /** Track dependency types (hard/soft/inferred) */
+    trackDependencyTypes?: boolean;
+    /** Validate graph structure during build */
+    validateStructure?: boolean;
+    /** Max nodes before warning (performance) */
+    maxNodes?: number;
+};
+/**
+ * Dependency Graph Builder
+ *
+ * Performance optimized for 10,000+ nodes:
+ * - Uses Map/Set for O(1) lookups
+ * - Lazy validation
+ * - Incremental building support
+ *
+ * @example
+ * const builder = new DependencyGraphBuilder();
+ * builder.addComponent(apexClassComponent);
+ * builder.addComponent(triggerComponent);
+ * const result = builder.build();
+ * console.log(result.stats.totalComponents); // 2
+ */
+export declare class DependencyGraphBuilder {
+    private components;
+    private graph;
+    private reverseGraph;
+    private edges;
+    private options;
+    constructor(options?: GraphBuilderOptions);
+    /**
+     * Get current size of the graph
+     */
+    get size(): number;
+    /**
+     * Check if graph is empty
+     */
+    get isEmpty(): boolean;
+    /**
+     * Create a node ID from type and name
+     */
+    private static createNodeId;
+    /**
+     * Add a metadata component to the graph
+     *
+     * @ac US-028-AC-1: Add nodes for each component
+     * @ac US-028-AC-5: Support incremental graph building
+     */
+    addComponent(component: MetadataComponent): void;
+    /**
+     * Add multiple components at once
+     *
+     * @ac US-028-AC-5: Support incremental graph building
+     */
+    addComponents(components: MetadataComponent[]): void;
+    /**
+     * Add a dependency edge between two nodes
+     *
+     * @ac US-028-AC-2: Add edges for each dependency
+     * @ac US-028-AC-3: Handle bidirectional dependencies
+     * @ac US-028-AC-4: Track dependency types
+     */
+    addEdge(from: NodeId, to: NodeId, type?: DependencyType, reason?: string): void;
+    /**
+     * Remove a component and its edges from the graph
+     */
+    removeComponent(nodeId: NodeId): boolean;
+    /**
+     * Get all dependencies of a component (outgoing edges)
+     */
+    getDependencies(nodeId: NodeId): Set<NodeId>;
+    /**
+     * Get all dependents of a component (incoming edges)
+     */
+    getDependents(nodeId: NodeId): Set<NodeId>;
+    /**
+     * Check if there's a direct dependency between two nodes
+     */
+    hasDependency(from: NodeId, to: NodeId): boolean;
+    /**
+     * Build the final dependency analysis result
+     *
+     * @ac US-028-AC-6: Validate graph structure
+     */
+    build(): DependencyAnalysisResult;
+    /**
+     * Clear the entire graph
+     */
+    clear(): void;
+    /**
+     * Validate graph structure
+     *
+     * @ac US-028-AC-6: Validate graph structure
+     */
+    private validate;
+    /**
+     * Detect circular dependencies using DFS
+     */
+    private detectCircularDependencies;
+    /**
+     * Find components with no dependencies or dependents
+     */
+    private findIsolatedComponents;
+    /**
+     * Generate graph statistics
+     */
+    private generateStats;
+    /**
+     * Calculate maximum dependency depth (simplified BFS)
+     */
+    private calculateMaxDepth;
+    /**
+     * BFS to calculate depth from a starting node
+     */
+    private bfsDepth;
+    /**
+     * Count total edges in the graph
+     */
+    private countEdges;
+}