@jterrats/smart-deployment 1.0.3

package/lib/waves/wave-merger.js

@@ -0,0 +1,181 @@
+/**
+ * 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 { getLogger } from '../utils/logger.js';
+const logger = getLogger('WaveMerger');
+/**
+ * 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 class WaveMerger {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            minComponentsForMerge: options.minComponentsForMerge ?? 50,
+            maxComponentsAfterMerge: options.maxComponentsAfterMerge ?? 300,
+            respectTestRequirements: options.respectTestRequirements ?? true,
+            allowUserOverride: options.allowUserOverride ?? false,
+        };
+        logger.debug('Initialized WaveMerger', {
+            minComponentsForMerge: this.options.minComponentsForMerge,
+            maxComponentsAfterMerge: this.options.maxComponentsAfterMerge,
+        });
+    }
+    /**
+     * @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, graph) {
+        const startTime = Date.now();
+        void graph;
+        const decisions = [];
+        const mergedWaves = [];
+        let i = 0;
+        while (i < waves.length) {
+            const currentWave = waves[i];
+            // Check if current wave is small
+            if (currentWave.components.length >= this.options.minComponentsForMerge) {
+                mergedWaves.push({ ...currentWave, number: mergedWaves.length + 1 });
+                i++;
+                continue;
+            }
+            // Try to merge with next wave
+            if (i + 1 < waves.length) {
+                const nextWave = waves[i + 1];
+                const combined = currentWave.components.length + nextWave.components.length;
+                if (this.canMerge(currentWave, nextWave, combined)) {
+                    // Merge waves
+                    const merged = this.createMergedWave(currentWave, nextWave, mergedWaves.length + 1);
+                    mergedWaves.push(merged);
+                    decisions.push({
+                        mergedWaves: [currentWave.number, nextWave.number],
+                        resultWaveNumber: merged.number,
+                        reason: `Small waves combined (${currentWave.components.length} + ${nextWave.components.length} = ${combined})`,
+                        originalCount: [currentWave.components.length, nextWave.components.length],
+                        mergedCount: combined,
+                    });
+                    i += 2; // Skip both waves
+                    continue;
+                }
+            }
+            // Cannot merge, keep as is
+            mergedWaves.push({ ...currentWave, number: mergedWaves.length + 1 });
+            i++;
+        }
+        const stats = {
+            originalWaveCount: waves.length,
+            mergedWaveCount: mergedWaves.length,
+            wavesSaved: waves.length - mergedWaves.length,
+            componentsAffected: decisions.reduce((sum, d) => sum + d.mergedCount, 0),
+        };
+        const duration = Date.now() - startTime;
+        logger.info('Wave merge completed', {
+            originalWaves: stats.originalWaveCount,
+            mergedWaves: stats.mergedWaveCount,
+            wavesSaved: stats.wavesSaved,
+            durationMs: duration,
+        });
+        return {
+            originalWaves: waves,
+            mergedWaves,
+            decisions,
+            stats,
+        };
+    }
+    /**
+     * Check if waves can be merged
+     */
+    canMerge(wave1, wave2, combinedSize) {
+        // Check size limit
+        if (combinedSize > this.options.maxComponentsAfterMerge) {
+            return false;
+        }
+        // Check test requirements if configured
+        if (this.options.respectTestRequirements) {
+            if (wave1.metadata.hasCircularDeps !== wave2.metadata.hasCircularDeps) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Create merged wave
+     */
+    createMergedWave(wave1, wave2, newNumber) {
+        const components = [...wave1.components, ...wave2.components];
+        const types = Array.from(new Set([...wave1.metadata.types, ...wave2.metadata.types]));
+        return {
+            number: newNumber,
+            components,
+            metadata: {
+                componentCount: components.length,
+                types,
+                maxDepth: Math.max(wave1.metadata.maxDepth, wave2.metadata.maxDepth),
+                hasCircularDeps: wave1.metadata.hasCircularDeps || wave2.metadata.hasCircularDeps,
+                estimatedTime: wave1.metadata.estimatedTime + wave2.metadata.estimatedTime,
+            },
+        };
+    }
+    /**
+     * Generate merge report
+     */
+    generateReport(result) {
+        const lines = [];
+        lines.push('# Wave Merge Report');
+        lines.push('');
+        lines.push('## Statistics');
+        lines.push(`- Original Waves: ${result.stats.originalWaveCount}`);
+        lines.push(`- Merged Waves: ${result.stats.mergedWaveCount}`);
+        lines.push(`- Waves Saved: ${result.stats.wavesSaved}`);
+        lines.push(`- Components Affected: ${result.stats.componentsAffected}`);
+        lines.push('');
+        if (result.decisions.length > 0) {
+            lines.push('## Merge Decisions');
+            lines.push('');
+            for (const decision of result.decisions) {
+                lines.push(`### Merged Waves ${decision.mergedWaves.join(' + ')} → Wave ${decision.resultWaveNumber}`);
+                lines.push(`- Reason: ${decision.reason}`);
+                lines.push(`- Original Counts: ${decision.originalCount.join(', ')}`);
+                lines.push(`- Merged Count: ${decision.mergedCount}`);
+                lines.push('');
+            }
+        }
+        else {
+            lines.push('## No Merges Performed');
+            lines.push('All waves are optimally sized.');
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=wave-merger.js.map

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

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

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

@@ -0,0 +1,13 @@
+/**
+ * Wave Metadata Generator - US-044
+ *
+ * @ac US-044-AC-1: Generate wave_metadata.json
+ * @ac US-044-AC-2: Include component list per wave
+ * @ac US-044-AC-3: Include dependency information
+ * @ac US-044-AC-4: Include test requirements
+ * @issue #44
+ */
+import type { Wave } from './wave-builder.js';
+export declare class WaveMetadataGenerator {
+    generateMetadata(waves: Wave[]): string;
+}

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

@@ -0,0 +1,12 @@
+export class WaveMetadataGenerator {
+    generateMetadata(waves) {
+        return JSON.stringify({
+            waves: waves.map((w) => ({
+                number: w.number,
+                components: w.components,
+                metadata: w.metadata,
+            })),
+        }, null, 2);
+    }
+}
+//# sourceMappingURL=wave-metadata-generator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wave-metadata-generator.js","sourceRoot":"","sources":["../../src/waves/wave-metadata-generator.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,qBAAqB;IACzB,gBAAgB,CAAC,KAAa;QACnC,OAAO,IAAI,CAAC,SAAS,CACnB;YACE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACvB,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,QAAQ,EAAE,CAAC,CAAC,QAAQ;aACrB,CAAC,CAAC;SACJ,EACD,IAAI,EACJ,CAAC,CACF,CAAC;IACJ,CAAC;CACF"}

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

@@ -0,0 +1,154 @@
+/**
+ * Wave Splitter
+ * Splits large waves to respect Salesforce deployment limits
+ *
+ * @ac US-039-AC-1: Split waves with >300 components
+ * @ac US-039-AC-2: Maintain dependency order within split waves
+ * @ac US-039-AC-3: Generate sub-waves (1a, 1b, etc.)
+ * @ac US-039-AC-4: Split CMT waves at 200 records
+ * @ac US-039-AC-5: Report split decisions
+ * @ac US-039-AC-6: Ensure no dependency violations
+ *
+ * @issue #39
+ */
+import type { DependencyGraph } from '../types/dependency.js';
+import type { Wave, WaveResult } from './wave-builder.js';
+/**
+ * Sub-wave (split wave)
+ */
+export type SubWave = Wave & {
+    /** Parent wave number */
+    parentWave: number;
+    /** Sub-wave letter (a, b, c, ...) */
+    subWaveLetter: string;
+    /** Full wave identifier (e.g., "1a", "1b") */
+    fullWaveId: string;
+};
+/**
+ * Split result
+ */
+export type SplitResult = {
+    /** Original waves (unsplit) */
+    originalWaves: Wave[];
+    /** Split waves with sub-waves */
+    splitWaves: SubWave[];
+    /** Split decisions made */
+    decisions: SplitDecision[];
+    /** Statistics */
+    stats: SplitStats;
+};
+/**
+ * Split decision record
+ */
+export type SplitDecision = {
+    /** Original wave number */
+    waveNumber: number;
+    /** Reason for split */
+    reason: string;
+    /** Original component count */
+    originalCount: number;
+    /** Number of sub-waves created */
+    subWaveCount: number;
+    /** Components per sub-wave */
+    componentsPerSubWave: number[];
+};
+/**
+ * Split statistics
+ */
+export type SplitStats = {
+    /** Total original waves */
+    originalWaveCount: number;
+    /** Total sub-waves after split */
+    finalWaveCount: number;
+    /** Number of waves that were split */
+    splitWaveCount: number;
+    /** Total components */
+    totalComponents: number;
+};
+/**
+ * Splitter options
+ */
+export type SplitterOptions = {
+    /** Max components per wave (default: 300) */
+    maxComponentsPerWave?: number;
+    /** Max Custom Metadata records per wave (default: 200) */
+    maxCustomMetadataPerWave?: number;
+    /** Maintain dependency order within splits */
+    maintainDependencyOrder?: boolean;
+};
+/**
+ * Wave Splitter
+ *
+ * Splits large waves to respect Salesforce limits:
+ * - General metadata: 300 components per deploy
+ * - Custom Metadata Type records: 200 per deploy
+ *
+ * Algorithm:
+ * 1. Identify waves exceeding limits
+ * 2. Split while maintaining dependency order
+ * 3. Generate sub-waves (1a, 1b, 1c, ...)
+ * 4. Validate no cross-sub-wave dependencies
+ *
+ * Performance: O(V)
+ *
+ * @example
+ * const splitter = new WaveSplitter({
+ *   maxComponentsPerWave: 300,
+ *   maxCustomMetadataPerWave: 200
+ * });
+ *
+ * const result = splitter.splitWaves(waveResult, graph);
+ * console.log(`Split ${result.decisions.length} waves`);
+ */
+export declare class WaveSplitter {
+    private options;
+    constructor(options?: SplitterOptions);
+    /**
+     * @ac US-039-AC-1: Split waves with >300 components
+     * @ac US-039-AC-2: Maintain dependency order within split waves
+     * @ac US-039-AC-3: Generate sub-waves (1a, 1b, etc.)
+     * @ac US-039-AC-5: Report split decisions
+     */
+    splitWaves(waveResult: WaveResult, graph: DependencyGraph): SplitResult;
+    /**
+     * Check if wave needs to be split
+     */
+    private needsSplit;
+    /**
+     * Get reason for split
+     */
+    private getSplitReason;
+    /**
+     * @ac US-039-AC-4: Split CMT waves at 200 records
+     * @ac US-039-AC-6: Ensure no dependency violations
+     */
+    private splitWave;
+    /**
+     * Sort components by dependency order
+     */
+    private sortByDependencyOrder;
+    /**
+     * Chunk components into smaller arrays
+     */
+    private chunkComponents;
+    /**
+     * Get sub-wave letter (a, b, c, ...)
+     */
+    private getSubWaveLetter;
+    /**
+     * Create sub-wave from wave and components
+     */
+    private createSubWave;
+    /**
+     * Convert wave to sub-wave format
+     */
+    private toSubWave;
+    /**
+     * Validate split result (no dependency violations)
+     */
+    validateSplit(result: SplitResult, graph: DependencyGraph): boolean;
+    /**
+     * Generate split report
+     */
+    generateReport(result: SplitResult): string;
+}

package/lib/waves/wave-splitter.js

@@ -0,0 +1,307 @@
+/**
+ * Wave Splitter
+ * Splits large waves to respect Salesforce deployment limits
+ *
+ * @ac US-039-AC-1: Split waves with >300 components
+ * @ac US-039-AC-2: Maintain dependency order within split waves
+ * @ac US-039-AC-3: Generate sub-waves (1a, 1b, etc.)
+ * @ac US-039-AC-4: Split CMT waves at 200 records
+ * @ac US-039-AC-5: Report split decisions
+ * @ac US-039-AC-6: Ensure no dependency violations
+ *
+ * @issue #39
+ */
+import { getLogger } from '../utils/logger.js';
+const logger = getLogger('WaveSplitter');
+/**
+ * Wave Splitter
+ *
+ * Splits large waves to respect Salesforce limits:
+ * - General metadata: 300 components per deploy
+ * - Custom Metadata Type records: 200 per deploy
+ *
+ * Algorithm:
+ * 1. Identify waves exceeding limits
+ * 2. Split while maintaining dependency order
+ * 3. Generate sub-waves (1a, 1b, 1c, ...)
+ * 4. Validate no cross-sub-wave dependencies
+ *
+ * Performance: O(V)
+ *
+ * @example
+ * const splitter = new WaveSplitter({
+ *   maxComponentsPerWave: 300,
+ *   maxCustomMetadataPerWave: 200
+ * });
+ *
+ * const result = splitter.splitWaves(waveResult, graph);
+ * console.log(`Split ${result.decisions.length} waves`);
+ */
+export class WaveSplitter {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            maxComponentsPerWave: options.maxComponentsPerWave ?? 300,
+            maxCustomMetadataPerWave: options.maxCustomMetadataPerWave ?? 200,
+            maintainDependencyOrder: options.maintainDependencyOrder ?? true,
+        };
+        logger.debug('Initialized WaveSplitter', {
+            maxComponentsPerWave: this.options.maxComponentsPerWave,
+            maxCustomMetadataPerWave: this.options.maxCustomMetadataPerWave,
+        });
+    }
+    /**
+     * @ac US-039-AC-1: Split waves with >300 components
+     * @ac US-039-AC-2: Maintain dependency order within split waves
+     * @ac US-039-AC-3: Generate sub-waves (1a, 1b, etc.)
+     * @ac US-039-AC-5: Report split decisions
+     */
+    splitWaves(waveResult, graph) {
+        const startTime = Date.now();
+        const decisions = [];
+        const splitWaves = [];
+        for (const wave of waveResult.waves) {
+            const needsSplit = this.needsSplit(wave);
+            if (!needsSplit) {
+                // No split needed, convert to sub-wave format
+                splitWaves.push(this.toSubWave(wave, 'a'));
+            }
+            else {
+                // Split the wave
+                const subWaves = this.splitWave(wave, graph);
+                splitWaves.push(...subWaves);
+                // Record decision
+                decisions.push({
+                    waveNumber: wave.number,
+                    reason: this.getSplitReason(wave),
+                    originalCount: wave.components.length,
+                    subWaveCount: subWaves.length,
+                    componentsPerSubWave: subWaves.map((sw) => sw.components.length),
+                });
+                logger.info('Split wave', {
+                    wave: wave.number,
+                    originalCount: wave.components.length,
+                    subWaves: subWaves.length,
+                });
+            }
+        }
+        // Calculate statistics
+        const stats = {
+            originalWaveCount: waveResult.waves.length,
+            finalWaveCount: splitWaves.length,
+            splitWaveCount: decisions.length,
+            totalComponents: waveResult.totalComponents,
+        };
+        const duration = Date.now() - startTime;
+        logger.info('Wave splitting completed', {
+            originalWaves: stats.originalWaveCount,
+            finalWaves: stats.finalWaveCount,
+            splits: stats.splitWaveCount,
+            durationMs: duration,
+        });
+        return {
+            originalWaves: waveResult.waves,
+            splitWaves,
+            decisions,
+            stats,
+        };
+    }
+    /**
+     * Check if wave needs to be split
+     */
+    needsSplit(wave) {
+        // Check general component limit
+        if (wave.components.length > this.options.maxComponentsPerWave) {
+            return true;
+        }
+        // Check Custom Metadata limit
+        const cmtCount = wave.components.filter((c) => c.startsWith('CustomMetadata:')).length;
+        if (cmtCount > this.options.maxCustomMetadataPerWave) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get reason for split
+     */
+    getSplitReason(wave) {
+        const cmtCount = wave.components.filter((c) => c.startsWith('CustomMetadata:')).length;
+        if (cmtCount > this.options.maxCustomMetadataPerWave) {
+            return `Exceeded Custom Metadata limit (${cmtCount} > ${this.options.maxCustomMetadataPerWave})`;
+        }
+        return `Exceeded component limit (${wave.components.length} > ${this.options.maxComponentsPerWave})`;
+    }
+    /**
+     * @ac US-039-AC-4: Split CMT waves at 200 records
+     * @ac US-039-AC-6: Ensure no dependency violations
+     */
+    splitWave(wave, graph) {
+        const subWaves = [];
+        const components = [...wave.components];
+        // Sort to maintain dependency order if configured
+        if (this.options.maintainDependencyOrder) {
+            this.sortByDependencyOrder(components, graph);
+        }
+        // Check if we need special CMT handling
+        const cmtComponents = components.filter((c) => c.startsWith('CustomMetadata:'));
+        const needsCmtSplit = cmtComponents.length > this.options.maxCustomMetadataPerWave;
+        if (needsCmtSplit) {
+            // Split CMT and non-CMT separately but maintain order
+            const cmtChunks = this.chunkComponents(cmtComponents, this.options.maxCustomMetadataPerWave);
+            const nonCmtComponents = components.filter((c) => !c.startsWith('CustomMetadata:'));
+            // Add CMT sub-waves first
+            for (const chunk of cmtChunks) {
+                const letter = this.getSubWaveLetter(subWaves.length);
+                subWaves.push(this.createSubWave(wave, chunk, letter));
+            }
+            // Add non-CMT components
+            if (nonCmtComponents.length > 0) {
+                const nonCmtChunks = this.chunkComponents(nonCmtComponents, this.options.maxComponentsPerWave);
+                for (const chunk of nonCmtChunks) {
+                    const letter = this.getSubWaveLetter(subWaves.length);
+                    subWaves.push(this.createSubWave(wave, chunk, letter));
+                }
+            }
+        }
+        else {
+            // Simple component-based splitting
+            const chunks = this.chunkComponents(components, this.options.maxComponentsPerWave);
+            for (const chunk of chunks) {
+                const letter = this.getSubWaveLetter(subWaves.length);
+                subWaves.push(this.createSubWave(wave, chunk, letter));
+            }
+        }
+        // If no components were added, create at least one sub-wave
+        if (subWaves.length === 0) {
+            subWaves.push(this.toSubWave(wave, 'a'));
+        }
+        return subWaves;
+    }
+    /**
+     * Sort components by dependency order
+     */
+    sortByDependencyOrder(components, graph) {
+        // Simple topological sort within the component list
+        const inDegree = new Map();
+        const componentSet = new Set(components);
+        // Calculate in-degree within this subset
+        for (const component of components) {
+            let degree = 0;
+            const deps = graph.get(component) ?? new Set();
+            for (const dep of deps) {
+                if (componentSet.has(dep)) {
+                    degree++;
+                }
+            }
+            inDegree.set(component, degree);
+        }
+        // Sort by in-degree (lower degree = fewer dependencies = deploy first)
+        components.sort((a, b) => {
+            const degreeA = inDegree.get(a) ?? 0;
+            const degreeB = inDegree.get(b) ?? 0;
+            return degreeA - degreeB;
+        });
+    }
+    /**
+     * Chunk components into smaller arrays
+     */
+    chunkComponents(components, chunkSize) {
+        const chunks = [];
+        for (let i = 0; i < components.length; i += chunkSize) {
+            chunks.push(components.slice(i, i + chunkSize));
+        }
+        return chunks;
+    }
+    /**
+     * Get sub-wave letter (a, b, c, ...)
+     */
+    getSubWaveLetter(index) {
+        return String.fromCharCode(97 + index); // 97 = 'a'
+    }
+    /**
+     * Create sub-wave from wave and components
+     */
+    createSubWave(wave, components, letter) {
+        return {
+            ...wave,
+            components,
+            parentWave: wave.number,
+            subWaveLetter: letter,
+            fullWaveId: `${wave.number}${letter}`,
+            metadata: {
+                ...wave.metadata,
+                componentCount: components.length,
+                estimatedTime: Math.ceil(components.length * 0.1),
+            },
+        };
+    }
+    /**
+     * Convert wave to sub-wave format
+     */
+    toSubWave(wave, letter) {
+        return {
+            ...wave,
+            parentWave: wave.number,
+            subWaveLetter: letter,
+            fullWaveId: `${wave.number}${letter}`,
+        };
+    }
+    /**
+     * Validate split result (no dependency violations)
+     */
+    validateSplit(result, graph) {
+        // Check that components in sub-wave N don't depend on sub-wave N+1
+        for (let i = 0; i < result.splitWaves.length - 1; i++) {
+            const currentWave = result.splitWaves[i];
+            const laterWaves = result.splitWaves.slice(i + 1);
+            const laterComponents = new Set(laterWaves.flatMap((w) => w.components));
+            for (const component of currentWave.components) {
+                const deps = graph.get(component) ?? new Set();
+                for (const dep of deps) {
+                    if (laterComponents.has(dep)) {
+                        logger.error('Dependency violation detected', {
+                            component,
+                            dependsOn: dep,
+                            currentWave: currentWave.fullWaveId,
+                        });
+                        return false;
+                    }
+                }
+            }
+        }
+        return true;
+    }
+    /**
+     * Generate split report
+     */
+    generateReport(result) {
+        const lines = [];
+        lines.push('# Wave Split Report');
+        lines.push('');
+        lines.push('## Statistics');
+        lines.push(`- Original Waves: ${result.stats.originalWaveCount}`);
+        lines.push(`- Final Waves: ${result.stats.finalWaveCount}`);
+        lines.push(`- Waves Split: ${result.stats.splitWaveCount}`);
+        lines.push(`- Total Components: ${result.stats.totalComponents}`);
+        lines.push('');
+        if (result.decisions.length > 0) {
+            lines.push('## Split Decisions');
+            lines.push('');
+            for (const decision of result.decisions) {
+                lines.push(`### Wave ${decision.waveNumber}`);
+                lines.push(`- Reason: ${decision.reason}`);
+                lines.push(`- Original Count: ${decision.originalCount}`);
+                lines.push(`- Split Into: ${decision.subWaveCount} sub-waves`);
+                lines.push(`- Distribution: ${decision.componentsPerSubWave.join(', ')}`);
+                lines.push('');
+            }
+        }
+        else {
+            lines.push('## No Splits Required');
+            lines.push('All waves are within limits.');
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=wave-splitter.js.map