@jterrats/smart-deployment 1.0.3

package/lib/waves/wave-builder.js

@@ -0,0 +1,286 @@
+/**
+ * Wave Builder
+ * Generates deployment waves using topological sort
+ *
+ * @ac US-038-AC-1: Generate waves from dependency graph
+ * @ac US-038-AC-2: Each wave contains independent components
+ * @ac US-038-AC-3: Components in wave N don't depend on wave N+1
+ * @ac US-038-AC-4: Handle components with no dependencies (wave 1)
+ * @ac US-038-AC-5: Handle isolated components
+ * @ac US-038-AC-6: Generate wave metadata
+ *
+ * @issue #38
+ */
+import { getLogger } from '../utils/logger.js';
+const logger = getLogger('WaveBuilder');
+/**
+ * Metadata type deployment order (Salesforce recommended)
+ */
+const TYPE_DEPLOYMENT_ORDER = [
+    'CustomObject',
+    'CustomField',
+    'RecordType',
+    'BusinessProcess',
+    'CompactLayout',
+    'Layout',
+    'Profile',
+    'PermissionSet',
+    'ApexClass',
+    'ApexTrigger',
+    'Flow',
+    'ValidationRule',
+    'WorkflowRule',
+    'EmailTemplate',
+    'FlexiPage',
+];
+/**
+ * Wave Builder
+ *
+ * Generates deployment waves using topological sort algorithm.
+ * Each wave contains components that can be deployed in parallel.
+ *
+ * Algorithm:
+ * 1. Calculate in-degree for all nodes
+ * 2. Add nodes with in-degree 0 to first wave
+ * 3. Remove those nodes and update in-degrees
+ * 4. Repeat until all nodes are placed
+ *
+ * Performance: O(V + E)
+ *
+ * @example
+ * const builder = new WaveBuilder({
+ *   maxComponentsPerWave: 10000,
+ *   respectTypeOrder: true
+ * });
+ *
+ * const result = builder.generateWaves(graph);
+ * console.log(`Generated ${result.waves.length} waves`);
+ */
+export class WaveBuilder {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            maxComponentsPerWave: options.maxComponentsPerWave ?? 0,
+            respectTypeOrder: options.respectTypeOrder ?? true,
+            handleCircularDeps: options.handleCircularDeps ?? true,
+        };
+        logger.debug('Initialized WaveBuilder', {
+            maxComponentsPerWave: this.options.maxComponentsPerWave,
+            respectTypeOrder: this.options.respectTypeOrder,
+        });
+    }
+    /**
+     * @ac US-038-AC-1: Generate waves from dependency graph
+     * @ac US-038-AC-2: Each wave contains independent components
+     * @ac US-038-AC-3: Components in wave N don't depend on wave N+1
+     */
+    generateWaves(graph) {
+        const startTime = Date.now();
+        // Calculate in-degree for all nodes
+        const inDegree = this.calculateInDegree(graph);
+        const waves = [];
+        const processed = new Set();
+        const unplacedComponents = [];
+        let waveNumber = 1;
+        // Build waves using topological sort
+        while (processed.size < graph.size) {
+            // Find nodes with in-degree 0
+            const currentWave = [];
+            for (const [nodeId, degree] of inDegree.entries()) {
+                if (degree === 0 && !processed.has(nodeId)) {
+                    currentWave.push(nodeId);
+                }
+            }
+            // No progress - circular dependency
+            if (currentWave.length === 0) {
+                this.handleCircularWave(graph, processed, unplacedComponents, waves, waveNumber);
+                break;
+            }
+            // Sort by type order if configured
+            if (this.options.respectTypeOrder) {
+                currentWave.sort((a, b) => this.compareByTypeOrder(a, b));
+            }
+            // Split into multiple waves if exceeds max size
+            if (this.options.maxComponentsPerWave > 0 && currentWave.length > this.options.maxComponentsPerWave) {
+                const chunks = this.chunkArray(currentWave, this.options.maxComponentsPerWave);
+                for (const chunk of chunks) {
+                    waves.push({
+                        number: waveNumber++,
+                        components: chunk,
+                        metadata: this.generateWaveMetadata(chunk, false),
+                    });
+                    // Mark as processed
+                    for (const nodeId of chunk) {
+                        processed.add(nodeId);
+                    }
+                }
+            }
+            else {
+                // Add wave
+                waves.push({
+                    number: waveNumber++,
+                    components: currentWave,
+                    metadata: this.generateWaveMetadata(currentWave, false),
+                });
+                // Mark as processed
+                for (const nodeId of currentWave) {
+                    processed.add(nodeId);
+                }
+            }
+            // Update in-degrees: reduce count for nodes that depended on current wave nodes
+            for (const [nodeId, deps] of graph.entries()) {
+                if (processed.has(nodeId))
+                    continue;
+                // Count how many of its dependencies were in the current wave
+                let removedDeps = 0;
+                for (const dep of deps) {
+                    if (currentWave.includes(dep)) {
+                        removedDeps++;
+                    }
+                }
+                if (removedDeps > 0) {
+                    inDegree.set(nodeId, (inDegree.get(nodeId) ?? 0) - removedDeps);
+                }
+            }
+        }
+        // Calculate statistics
+        const stats = this.calculateStats(waves);
+        const duration = Date.now() - startTime;
+        logger.info('Wave generation completed', {
+            waves: waves.length,
+            components: processed.size,
+            unplaced: unplacedComponents.length,
+            durationMs: duration,
+        });
+        // Ensure waves are sorted by number before returning
+        waves.sort((a, b) => a.number - b.number);
+        return {
+            waves,
+            totalComponents: graph.size,
+            unplacedComponents,
+            circularDependencies: [],
+            stats,
+        };
+    }
+    /**
+     * Calculate in-degree for all nodes
+     * In-degree = number of dependencies this node has (how many nodes it depends on)
+     * Nodes with in-degree 0 have no dependencies and can be deployed first
+     */
+    calculateInDegree(graph) {
+        const inDegree = new Map();
+        // Initialize all nodes with their dependency count
+        for (const [nodeId, deps] of graph.entries()) {
+            inDegree.set(nodeId, deps.size);
+        }
+        return inDegree;
+    }
+    handleCircularWave(graph, processed, unplacedComponents, waves, waveNumber) {
+        const remaining = this.collectRemainingNodes(graph, processed);
+        unplacedComponents.push(...remaining);
+        logger.warn('Circular dependencies detected', {
+            remaining: remaining.length,
+        });
+        if (this.options.handleCircularDeps) {
+            waves.push({
+                number: waveNumber,
+                components: remaining,
+                metadata: this.generateWaveMetadata(remaining, true),
+            });
+        }
+    }
+    collectRemainingNodes(graph, processed) {
+        const remaining = [];
+        for (const nodeId of graph.keys()) {
+            if (!processed.has(nodeId)) {
+                remaining.push(nodeId);
+            }
+        }
+        return remaining;
+    }
+    /**
+     * @ac US-038-AC-6: Generate wave metadata
+     */
+    generateWaveMetadata(components, hasCircularDeps) {
+        const types = new Set();
+        const maxDepth = 0;
+        for (const component of components) {
+            const [type] = component.split(':');
+            types.add(type);
+        }
+        // Estimate deployment time (rough estimate: 0.1s per component)
+        const estimatedTime = Math.ceil(components.length * 0.1);
+        return {
+            componentCount: components.length,
+            types: Array.from(types),
+            maxDepth,
+            hasCircularDeps,
+            estimatedTime,
+        };
+    }
+    /**
+     * Compare nodes by type deployment order
+     */
+    compareByTypeOrder(a, b) {
+        const typeA = a.split(':')[0];
+        const typeB = b.split(':')[0];
+        const orderA = TYPE_DEPLOYMENT_ORDER.indexOf(typeA);
+        const orderB = TYPE_DEPLOYMENT_ORDER.indexOf(typeB);
+        // If not in order list, put at end
+        const finalOrderA = orderA === -1 ? 9999 : orderA;
+        const finalOrderB = orderB === -1 ? 9999 : orderB;
+        return finalOrderA - finalOrderB;
+    }
+    /**
+     * Split array into chunks
+     */
+    chunkArray(array, chunkSize) {
+        const chunks = [];
+        for (let i = 0; i < array.length; i += chunkSize) {
+            chunks.push(array.slice(i, i + chunkSize));
+        }
+        return chunks;
+    }
+    /**
+     * Calculate wave statistics
+     */
+    calculateStats(waves) {
+        if (waves.length === 0) {
+            return {
+                totalWaves: 0,
+                avgComponentsPerWave: 0,
+                largestWaveSize: 0,
+                smallestWaveSize: 0,
+                totalEstimatedTime: 0,
+            };
+        }
+        const sizes = waves.map((w) => w.components.length);
+        const totalComponents = sizes.reduce((sum, size) => sum + size, 0);
+        const totalTime = waves.reduce((sum, w) => sum + w.metadata.estimatedTime, 0);
+        return {
+            totalWaves: waves.length,
+            avgComponentsPerWave: Math.round(totalComponents / waves.length),
+            largestWaveSize: Math.max(...sizes),
+            smallestWaveSize: Math.min(...sizes),
+            totalEstimatedTime: totalTime,
+        };
+    }
+    /**
+     * Get wave by number
+     */
+    getWave(result, waveNumber) {
+        return result.waves.find((w) => w.number === waveNumber);
+    }
+    /**
+     * Get component wave number
+     */
+    getComponentWave(result, componentId) {
+        for (const wave of result.waves) {
+            if (wave.components.includes(componentId)) {
+                return wave.number;
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=wave-builder.js.map

package/lib/waves/wave-builder.js.map

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

package/lib/waves/wave-diff-generator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Wave Diff Generator - US-045
+ *
+ * @ac US-045-AC-1: Compare two wave generations
+ * @ac US-045-AC-2: Show added/removed components
+ * @ac US-045-AC-3: Show wave reordering
+ * @ac US-045-AC-4: Show dependency changes
+ * @issue #45
+ */
+import type { Wave } from './wave-builder.js';
+export declare class WaveDiffGenerator {
+    generateDiff(oldWaves: Wave[], newWaves: Wave[]): {
+        added: string[];
+        removed: string[];
+        reordered: boolean;
+    };
+}

package/lib/waves/wave-diff-generator.js

@@ -0,0 +1,6 @@
+export class WaveDiffGenerator {
+    generateDiff(oldWaves, newWaves) {
+        return { added: [], removed: [], reordered: oldWaves.length !== newWaves.length };
+    }
+}
+//# sourceMappingURL=wave-diff-generator.js.map

package/lib/waves/wave-diff-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wave-diff-generator.js","sourceRoot":"","sources":["../../src/waves/wave-diff-generator.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,iBAAiB;IACrB,YAAY,CACjB,QAAgB,EAChB,QAAgB;QAMhB,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;IACpF,CAAC;CACF"}

package/lib/waves/wave-executor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Wave Executor Utilities
+ * Ensures waves are executed in correct numerical order
+ *
+ * @ac Wave ordering fix: Ensure numerical execution order
+ */
+import type { Wave, WaveResult } from './wave-builder.js';
+/**
+ * Sort waves by numerical order (not alphabetical)
+ *
+ * @example sortWavesByNumber({ waves: [wave10, wave2, wave1] }) => [wave1, wave2, wave10]
+ */
+export declare function sortWavesByNumber(result: WaveResult): Wave[];
+/**
+ * Get waves in execution order (numerically sorted)
+ */
+export declare function getWavesInExecutionOrder(result: WaveResult): Wave[];
+/**
+ * Format wave ID with zero-padding for consistent alphabetical sorting
+ *
+ * @example formatWaveId(1, 15) => "wave-001"
+ */
+export declare function formatWaveId(waveNumber: number, totalWaves: number): string;
+/**
+ * Parse wave ID back to number
+ *
+ * @example parseWaveId("wave-001") => 1
+ */
+export declare function parseWaveId(waveId: string): number | undefined;
+/**
+ * Validate wave execution order
+ */
+export declare function validateWaveOrder(waves: Wave[]): boolean;

package/lib/waves/wave-executor.js

@@ -0,0 +1,50 @@
+/**
+ * Wave Executor Utilities
+ * Ensures waves are executed in correct numerical order
+ *
+ * @ac Wave ordering fix: Ensure numerical execution order
+ */
+/**
+ * Sort waves by numerical order (not alphabetical)
+ *
+ * @example sortWavesByNumber({ waves: [wave10, wave2, wave1] }) => [wave1, wave2, wave10]
+ */
+export function sortWavesByNumber(result) {
+    return [...result.waves].sort((a, b) => a.number - b.number);
+}
+/**
+ * Get waves in execution order (numerically sorted)
+ */
+export function getWavesInExecutionOrder(result) {
+    return sortWavesByNumber(result);
+}
+/**
+ * Format wave ID with zero-padding for consistent alphabetical sorting
+ *
+ * @example formatWaveId(1, 15) => "wave-001"
+ */
+export function formatWaveId(waveNumber, totalWaves) {
+    const padding = Math.max(3, String(totalWaves).length);
+    return `wave-${String(waveNumber).padStart(padding, '0')}`;
+}
+/**
+ * Parse wave ID back to number
+ *
+ * @example parseWaveId("wave-001") => 1
+ */
+export function parseWaveId(waveId) {
+    const match = /^wave-(\d+)$/.exec(waveId);
+    return match ? Number.parseInt(match[1], 10) : undefined;
+}
+/**
+ * Validate wave execution order
+ */
+export function validateWaveOrder(waves) {
+    for (let i = 0; i < waves.length; i++) {
+        if (waves[i].number !== i + 1) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=wave-executor.js.map

package/lib/waves/wave-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wave-executor.js","sourceRoot":"","sources":["../../src/waves/wave-executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAkB;IAClD,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;AAC/D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAkB;IACzD,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,UAAkB;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;IACvD,OAAO,QAAQ,MAAM,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/waves/wave-merger.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Wave Merger
+ * Merges small adjacent waves to reduce total deployment time
+ *
+ * @ac US-041-AC-1: Identify waves with <50 components
+ * @ac US-041-AC-2: Merge if combined < 300 components
+ * @ac US-041-AC-3: Respect dependency order
+ * @ac US-041-AC-4: Don't merge if different test requirements
+ * @ac US-041-AC-5: Report merge decisions
+ * @ac US-041-AC-6: User override option
+ *
+ * @issue #41
+ */
+import type { Wave } from './wave-builder.js';
+/**
+ * Merge result
+ */
+export type MergeResult = {
+    originalWaves: Wave[];
+    mergedWaves: Wave[];
+    decisions: MergeDecision[];
+    stats: MergeStats;
+};
+/**
+ * Merge decision
+ */
+export type MergeDecision = {
+    mergedWaves: number[];
+    resultWaveNumber: number;
+    reason: string;
+    originalCount: number[];
+    mergedCount: number;
+};
+/**
+ * Merge statistics
+ */
+export type MergeStats = {
+    originalWaveCount: number;
+    mergedWaveCount: number;
+    wavesSaved: number;
+    componentsAffected: number;
+};
+/**
+ * Merger options
+ */
+export type MergerOptions = {
+    minComponentsForMerge?: number;
+    maxComponentsAfterMerge?: number;
+    respectTestRequirements?: boolean;
+    allowUserOverride?: boolean;
+};
+/**
+ * Wave Merger
+ *
+ * Merges small adjacent waves to reduce total deployment time.
+ *
+ * Algorithm:
+ * 1. Identify small waves (< threshold)
+ * 2. Check if adjacent waves can be merged
+ * 3. Validate no dependency violations
+ * 4. Merge waves and renumber
+ *
+ * Performance: O(V)
+ *
+ * @example
+ * const merger = new WaveMerger({
+ *   minComponentsForMerge: 50,
+ *   maxComponentsAfterMerge: 300
+ * });
+ *
+ * const result = merger.mergeWaves(waves, graph);
+ * console.log(`Saved ${result.stats.wavesSaved} waves`);
+ */
+export declare class WaveMerger {
+    private options;
+    constructor(options?: MergerOptions);
+    /**
+     * @ac US-041-AC-1: Identify waves with <50 components
+     * @ac US-041-AC-2: Merge if combined < 300 components
+     * @ac US-041-AC-3: Respect dependency order
+     * @ac US-041-AC-5: Report merge decisions
+     */
+    mergeWaves(waves: Wave[], graph?: unknown): MergeResult;
+    /**
+     * Check if waves can be merged
+     */
+    private canMerge;
+    /**
+     * Create merged wave
+     */
+    private createMergedWave;
+    /**
+     * Generate merge report
+     */
+    generateReport(result: MergeResult): string;
+}