@jterrats/smart-deployment 1.0.3

package/lib/waves/test-optimizer.js

@@ -0,0 +1,290 @@
+/**
+ * Test Optimizer
+ * Optimizes test execution per wave to reduce deployment time
+ *
+ * @ac US-040-AC-1: Identify waves with Apex/Trigger changes
+ * @ac US-040-AC-2: Include tests only in waves with code
+ * @ac US-040-AC-3: Sync test classes with production classes
+ * @ac US-040-AC-4: Ensure trigger tests are included
+ * @ac US-040-AC-5: Calculate test coverage per wave
+ * @ac US-040-AC-6: Report test optimization savings
+ *
+ * @issue #40
+ */
+import { getLogger } from '../utils/logger.js';
+const logger = getLogger('TestOptimizer');
+/**
+ * Test Optimizer
+ *
+ * Optimizes test execution by only including tests in waves
+ * that contain Apex classes or triggers.
+ *
+ * Strategy:
+ * 1. Identify waves with code changes (ApexClass, ApexTrigger)
+ * 2. Match test classes to production classes
+ * 3. Include only relevant tests per wave
+ * 4. Skip tests for metadata-only waves
+ *
+ * Performance: O(V)
+ *
+ * @example
+ * const optimizer = new TestOptimizer({
+ *   minCoverageRequired: 75,
+ *   includeRelatedTests: true
+ * });
+ *
+ * const result = optimizer.optimizeTests(waves);
+ * console.log(`Time saved: ${result.stats.timeSaved}s`);
+ */
+export class TestOptimizer {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            alwaysRunAllTests: options.alwaysRunAllTests ?? false,
+            minCoverageRequired: options.minCoverageRequired ?? 75,
+            includeRelatedTests: options.includeRelatedTests ?? false,
+        };
+        logger.debug('Initialized TestOptimizer', {
+            alwaysRunAllTests: this.options.alwaysRunAllTests,
+            minCoverageRequired: this.options.minCoverageRequired,
+        });
+    }
+    /**
+     * @ac US-040-AC-1: Identify waves with Apex/Trigger changes
+     * @ac US-040-AC-2: Include tests only in waves with code
+     * @ac US-040-AC-3: Sync test classes with production classes
+     */
+    optimizeTests(waves) {
+        const startTime = Date.now();
+        const decisions = [];
+        const optimizedWaves = [];
+        // Collect all test classes across all waves
+        const allTestClasses = this.collectAllTestClasses(waves);
+        for (const wave of waves) {
+            const codeClasses = this.getCodeClasses(wave);
+            const triggers = this.getTriggers(wave);
+            const needsTests = codeClasses.length > 0 || triggers.length > 0;
+            let testClasses = [];
+            let estimatedCoverage = 100;
+            if (this.options.alwaysRunAllTests) {
+                // Include all test classes in every wave
+                testClasses = allTestClasses;
+                decisions.push({
+                    waveNumber: wave.number,
+                    type: 'include-tests',
+                    reason: 'alwaysRunAllTests option enabled',
+                    testsAffected: allTestClasses.length,
+                });
+            }
+            else if (!needsTests) {
+                // No code changes, skip tests
+                testClasses = [];
+                decisions.push({
+                    waveNumber: wave.number,
+                    type: 'skip-tests',
+                    reason: 'No Apex classes or triggers in wave',
+                    testsAffected: 0,
+                });
+            }
+            else {
+                // Sync test classes with code classes
+                testClasses = this.syncTestClasses(codeClasses, triggers, allTestClasses);
+                estimatedCoverage = this.estimateCoverage(codeClasses.length, testClasses.length);
+                decisions.push({
+                    waveNumber: wave.number,
+                    type: 'sync-tests',
+                    reason: `Matched ${testClasses.length} tests to ${codeClasses.length} classes`,
+                    testsAffected: testClasses.length,
+                });
+            }
+            optimizedWaves.push({
+                ...wave,
+                testClasses,
+                codeClasses,
+                triggers,
+                needsTests,
+                estimatedCoverage,
+            });
+        }
+        // Calculate statistics
+        const stats = this.calculateStats(optimizedWaves, allTestClasses.length);
+        const duration = Date.now() - startTime;
+        logger.info('Test optimization completed', {
+            totalWaves: stats.totalWaves,
+            wavesWithTests: stats.wavesWithTests,
+            testsAdded: stats.totalTestsAdded,
+            timeSaved: stats.timeSaved,
+            durationMs: duration,
+        });
+        return {
+            originalWaves: waves,
+            optimizedWaves,
+            decisions,
+            stats,
+        };
+    }
+    /**
+     * Collect all test classes from all waves
+     */
+    collectAllTestClasses(waves) {
+        const testClasses = new Set();
+        for (const wave of waves) {
+            for (const component of wave.components) {
+                if (this.isTestClass(component)) {
+                    testClasses.add(component);
+                }
+            }
+        }
+        return Array.from(testClasses);
+    }
+    /**
+     * Get code classes (non-test Apex classes)
+     */
+    getCodeClasses(wave) {
+        return wave.components.filter((c) => c.startsWith('ApexClass:') && !this.isTestClass(c));
+    }
+    /**
+     * @ac US-040-AC-4: Ensure trigger tests are included
+     */
+    getTriggers(wave) {
+        return wave.components.filter((c) => c.startsWith('ApexTrigger:'));
+    }
+    /**
+     * Check if component is a test class
+     */
+    isTestClass(component) {
+        return (component.startsWith('ApexClass:') &&
+            (component.toLowerCase().includes('test') || component.toLowerCase().endsWith('_test')));
+    }
+    /**
+     * Sync test classes with production classes
+     */
+    syncTestClasses(codeClasses, triggers, allTestClasses) {
+        const matchedTests = new Set();
+        // Match tests to code classes
+        for (const codeClass of codeClasses) {
+            const className = codeClass.split(':')[1];
+            for (const testClass of allTestClasses) {
+                const testName = testClass.split(':')[1].toLowerCase();
+                const codeName = className.toLowerCase();
+                // Match patterns:
+                // - AccountService → AccountServiceTest
+                // - AccountService → TestAccountService
+                // - AccountService → AccountService_Test
+                if (testName.includes(codeName) || codeName.includes(testName.replace('test', ''))) {
+                    matchedTests.add(testClass);
+                }
+            }
+        }
+        // Match tests to triggers
+        for (const trigger of triggers) {
+            const triggerName = trigger.split(':')[1];
+            for (const testClass of allTestClasses) {
+                const testName = testClass.split(':')[1].toLowerCase();
+                const trgName = triggerName.toLowerCase();
+                // Match patterns:
+                // - AccountTrigger → AccountTriggerTest
+                // - AccountTrigger → TestAccountTrigger
+                if (testName.includes(trgName) || testName.includes('trigger')) {
+                    matchedTests.add(testClass);
+                }
+            }
+        }
+        // If no tests matched and we have code, include related tests
+        if (matchedTests.size === 0 && this.options.includeRelatedTests) {
+            // Include a reasonable subset (e.g., first 10 test classes)
+            for (let i = 0; i < Math.min(10, allTestClasses.length); i++) {
+                matchedTests.add(allTestClasses[i]);
+            }
+        }
+        return Array.from(matchedTests);
+    }
+    /**
+     * @ac US-040-AC-5: Calculate test coverage per wave
+     */
+    estimateCoverage(codeClassCount, testClassCount) {
+        if (codeClassCount === 0)
+            return 100;
+        if (testClassCount === 0)
+            return 0;
+        // Simple heuristic: assume each test class covers ~75% of one class
+        const coverage = Math.min(100, (testClassCount / codeClassCount) * 75);
+        return Math.round(coverage);
+    }
+    /**
+     * Calculate optimization statistics
+     */
+    calculateStats(optimizedWaves, totalAvailableTests) {
+        let wavesWithTests = 0;
+        let wavesWithoutTests = 0;
+        let totalTestsAdded = 0;
+        for (const wave of optimizedWaves) {
+            if (wave.testClasses.length > 0) {
+                wavesWithTests++;
+                totalTestsAdded += wave.testClasses.length;
+            }
+            else {
+                wavesWithoutTests++;
+            }
+        }
+        // Estimate time saved (assume 5s per test class skipped)
+        const testsSkipped = optimizedWaves.length * totalAvailableTests - totalTestsAdded;
+        const timeSaved = testsSkipped * 5;
+        return {
+            totalWaves: optimizedWaves.length,
+            wavesWithTests,
+            wavesWithoutTests,
+            totalTestsAdded,
+            timeSaved,
+        };
+    }
+    /**
+     * @ac US-040-AC-6: Report test optimization savings
+     */
+    generateReport(result) {
+        const lines = [];
+        lines.push('# Test Optimization Report');
+        lines.push('');
+        lines.push('## Statistics');
+        lines.push(`- Total Waves: ${result.stats.totalWaves}`);
+        lines.push(`- Waves with Tests: ${result.stats.wavesWithTests}`);
+        lines.push(`- Waves without Tests: ${result.stats.wavesWithoutTests}`);
+        lines.push(`- Total Test Classes Added: ${result.stats.totalTestsAdded}`);
+        lines.push(`- Estimated Time Saved: ${result.stats.timeSaved}s (${Math.round(result.stats.timeSaved / 60)}min)`);
+        lines.push('');
+        lines.push('## Optimization Decisions');
+        lines.push('');
+        for (const decision of result.decisions) {
+            lines.push(`### Wave ${decision.waveNumber}`);
+            lines.push(`- Type: ${decision.type}`);
+            lines.push(`- Reason: ${decision.reason}`);
+            lines.push(`- Tests Affected: ${decision.testsAffected}`);
+            lines.push('');
+        }
+        lines.push('## Wave Details');
+        lines.push('');
+        for (const wave of result.optimizedWaves) {
+            lines.push(`### Wave ${wave.number}`);
+            lines.push(`- Code Classes: ${wave.codeClasses.length}`);
+            lines.push(`- Triggers: ${wave.triggers.length}`);
+            lines.push(`- Test Classes: ${wave.testClasses.length}`);
+            lines.push(`- Needs Tests: ${wave.needsTests ? 'Yes' : 'No'}`);
+            lines.push(`- Estimated Coverage: ${wave.estimatedCoverage}%`);
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Get waves that need test execution
+     */
+    getWavesNeedingTests(result) {
+        return result.optimizedWaves.filter((w) => w.needsTests);
+    }
+    /**
+     * Get total test count across all waves
+     */
+    getTotalTestCount(result) {
+        return result.optimizedWaves.reduce((sum, wave) => sum + wave.testClasses.length, 0);
+    }
+}
+//# sourceMappingURL=test-optimizer.js.map

package/lib/waves/test-optimizer.js.map

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

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

@@ -0,0 +1,147 @@
+/**
+ * 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 type { NodeId, DependencyGraph, CircularDependency } from '../types/dependency.js';
+import type { MetadataType } from '../types/metadata.js';
+/**
+ * Wave of independent components
+ */
+export type Wave = {
+    /** Wave number (1-based) */
+    number: number;
+    /** Components in this wave */
+    components: NodeId[];
+    /** Metadata about the wave */
+    metadata: WaveMetadata;
+};
+/**
+ * Wave metadata
+ */
+export type WaveMetadata = {
+    /** Number of components */
+    componentCount: number;
+    /** Component types in this wave */
+    types: MetadataType[];
+    /** Maximum dependency depth in this wave */
+    maxDepth: number;
+    /** Whether this wave has circular dependencies */
+    hasCircularDeps: boolean;
+    /** Estimated deployment time (seconds) */
+    estimatedTime: number;
+};
+/**
+ * Wave generation result
+ */
+export type WaveResult = {
+    /** Generated waves */
+    waves: Wave[];
+    /** Total number of components */
+    totalComponents: number;
+    /** Components that couldn't be placed (circular deps) */
+    unplacedComponents: NodeId[];
+    /** Circular dependencies detected */
+    circularDependencies: CircularDependency[];
+    /** Statistics */
+    stats: WaveStats;
+};
+/**
+ * Wave statistics
+ */
+export type WaveStats = {
+    /** Total number of waves */
+    totalWaves: number;
+    /** Average components per wave */
+    avgComponentsPerWave: number;
+    /** Largest wave size */
+    largestWaveSize: number;
+    /** Smallest wave size */
+    smallestWaveSize: number;
+    /** Total estimated time (seconds) */
+    totalEstimatedTime: number;
+};
+/**
+ * Wave builder options
+ */
+export type WaveBuilderOptions = {
+    /** Maximum components per wave (0 = unlimited) */
+    maxComponentsPerWave?: number;
+    /** Respect metadata type deployment order */
+    respectTypeOrder?: boolean;
+    /** Handle circular dependencies */
+    handleCircularDeps?: boolean;
+};
+/**
+ * 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 declare class WaveBuilder {
+    private options;
+    constructor(options?: WaveBuilderOptions);
+    /**
+     * @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: DependencyGraph): WaveResult;
+    /**
+     * 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
+     */
+    private calculateInDegree;
+    private handleCircularWave;
+    private collectRemainingNodes;
+    /**
+     * @ac US-038-AC-6: Generate wave metadata
+     */
+    private generateWaveMetadata;
+    /**
+     * Compare nodes by type deployment order
+     */
+    private compareByTypeOrder;
+    /**
+     * Split array into chunks
+     */
+    private chunkArray;
+    /**
+     * Calculate wave statistics
+     */
+    private calculateStats;
+    /**
+     * Get wave by number
+     */
+    getWave(result: WaveResult, waveNumber: number): Wave | undefined;
+    /**
+     * Get component wave number
+     */
+    getComponentWave(result: WaveResult, componentId: NodeId): number | undefined;
+}