dartmind 17.0.0

package/dist/gates/GoldenSnapshotGate.js

@@ -0,0 +1,734 @@
+/**
+ * DartMind V17 - Golden Snapshot Gate (G12)
+ * Day 10: Visual Regression Testing with Vision LLM
+ *
+ * Validates Flutter UI against golden baselines using:
+ * 1. Emulator/simulator screenshot capture
+ * 2. Vision LLM comparison (Claude)
+ * 3. Semantic difference detection
+ *
+ * @module gates/GoldenSnapshotGate
+ * @version 17.0.0
+ */
+import { EventEmitter } from 'events';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { createEmulatorCapture, } from './EmulatorCapture.js';
+import { DEFAULT_GOLDEN_SNAPSHOT_CONFIG, generateGoldenId, buildComparisonPrompt, parseVisionResponse, passesSimilarityThreshold, formatSimilarity, calculateOverallSeverity, } from './GoldenSnapshotTypes.js';
+/**
+ * Default Vision LLM provider using Anthropic Claude
+ */
+export class ClaudeVisionProvider {
+    apiKey;
+    model;
+    constructor(apiKey, model = 'claude-sonnet-4-20250514') {
+        this.apiKey = apiKey || process.env.ANTHROPIC_API_KEY || '';
+        this.model = model;
+    }
+    async compareImages(currentImagePath, goldenImagePath, prompt) {
+        if (!this.apiKey) {
+            // Return simulated response for testing
+            return this.simulateComparison(currentImagePath, goldenImagePath);
+        }
+        try {
+            // Read images as base64
+            const [currentImage, goldenImage] = await Promise.all([
+                fs.readFile(currentImagePath),
+                fs.readFile(goldenImagePath),
+            ]);
+            const currentBase64 = currentImage.toString('base64');
+            const goldenBase64 = goldenImage.toString('base64');
+            // Call Anthropic API with vision
+            const response = await fetch('https://api.anthropic.com/v1/messages', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify({
+                    model: this.model,
+                    max_tokens: 2048,
+                    messages: [
+                        {
+                            role: 'user',
+                            content: [
+                                {
+                                    type: 'image',
+                                    source: {
+                                        type: 'base64',
+                                        media_type: 'image/png',
+                                        data: currentBase64,
+                                    },
+                                },
+                                {
+                                    type: 'image',
+                                    source: {
+                                        type: 'base64',
+                                        media_type: 'image/png',
+                                        data: goldenBase64,
+                                    },
+                                },
+                                {
+                                    type: 'text',
+                                    text: prompt,
+                                },
+                            ],
+                        },
+                    ],
+                }),
+            });
+            if (!response.ok) {
+                throw new Error(`Vision API error: ${response.status} ${response.statusText}`);
+            }
+            const result = await response.json();
+            return {
+                response: result.content?.[0]?.text || '',
+                tokensUsed: {
+                    input: result.usage?.input_tokens || 0,
+                    output: result.usage?.output_tokens || 0,
+                },
+            };
+        }
+        catch (error) {
+            // Fall back to simulated comparison
+            console.warn('Vision API call failed, using simulated comparison:', error);
+            return this.simulateComparison(currentImagePath, goldenImagePath);
+        }
+    }
+    /**
+     * Simulate comparison for testing without API key
+     */
+    async simulateComparison(currentImagePath, goldenImagePath) {
+        // Compare file checksums for basic similarity
+        const [currentHash, goldenHash] = await Promise.all([
+            this.hashFile(currentImagePath),
+            this.hashFile(goldenImagePath),
+        ]);
+        const identical = currentHash === goldenHash;
+        const response = JSON.stringify({
+            similarity: identical ? 1.0 : 0.85,
+            differences: identical
+                ? []
+                : [
+                    {
+                        bounds: { x: 100, y: 100, width: 50, height: 30 },
+                        severity: 'minor',
+                        description: 'Possible visual difference detected',
+                        confidence: 0.7,
+                    },
+                ],
+            assessment: identical
+                ? 'Screenshots are identical'
+                : 'Minor visual differences detected (simulated comparison)',
+            suggestions: identical ? [] : ['Review the highlighted areas for changes'],
+            shouldUpdateGolden: false,
+        });
+        return {
+            response,
+            tokensUsed: { input: 0, output: 0 },
+        };
+    }
+    async hashFile(filePath) {
+        try {
+            const content = await fs.readFile(filePath);
+            return crypto.createHash('sha256').update(content).digest('hex');
+        }
+        catch {
+            return '';
+        }
+    }
+}
+// ============================================================================
+// Golden Snapshot Gate
+// ============================================================================
+/**
+ * Golden Snapshot Gate (G12)
+ * Validates Flutter UI against golden baselines using Vision LLM
+ */
+export class GoldenSnapshotGate extends EventEmitter {
+    id = 'G12';
+    name = 'Golden Snapshot Gate';
+    description = 'Visual regression testing using Vision LLM comparison';
+    required = false;
+    timeoutMs = 300000; // 5 minutes
+    config;
+    emulatorCapture;
+    visionProvider;
+    goldenIndex = null;
+    eventHandlers;
+    comparisonCache;
+    constructor(config = {}, visionProvider, emulatorConfig) {
+        super();
+        this.config = { ...DEFAULT_GOLDEN_SNAPSHOT_CONFIG, ...config };
+        this.visionProvider = visionProvider || new ClaudeVisionProvider(undefined, this.config.visionModel);
+        this.emulatorCapture = createEmulatorCapture(emulatorConfig);
+        this.eventHandlers = new Set();
+        this.comparisonCache = new Map();
+    }
+    // ============================================================================
+    // Event Handling
+    // ============================================================================
+    /**
+     * Subscribe to gate events
+     */
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    /**
+     * Emit event
+     */
+    emitEvent(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                console.error('Event handler error:', error);
+            }
+        }
+        this.emit(event.type, event);
+    }
+    // ============================================================================
+    // V16Gate Interface
+    // ============================================================================
+    /**
+     * Execute the golden snapshot gate
+     */
+    async execute(input) {
+        const startTime = Date.now();
+        const violations = [];
+        const warnings = [];
+        const infos = [];
+        try {
+            // Parse golden snapshot input
+            const goldenInput = this.parseInput(input);
+            // Run golden snapshot validation
+            const gateResult = await this.validate(goldenInput);
+            // Convert to V16 format
+            for (const validation of gateResult.validations) {
+                if (!validation.passed) {
+                    const severity = validation.comparison
+                        ? calculateOverallSeverity(validation.comparison.differences)
+                        : 'major';
+                    const violation = {
+                        id: `g12_${validation.widgetPath}_${validation.device.id}`,
+                        message: `Visual regression: ${validation.widgetPath}`,
+                        severity: severity === 'critical' || severity === 'major' ? 'BLOCK' : 'WARN',
+                        location: { file: validation.widgetPath },
+                        suggestion: validation.comparison?.suggestions?.[0] || 'Review visual changes',
+                        autoFixable: false,
+                    };
+                    if (violation.severity === 'BLOCK') {
+                        violations.push(violation);
+                    }
+                    else {
+                        warnings.push(violation);
+                    }
+                }
+                else {
+                    infos.push({
+                        id: `g12_${validation.widgetPath}_${validation.device.id}_pass`,
+                        message: `Visual validation passed: ${validation.widgetPath}`,
+                        severity: 'INFO',
+                        location: { file: validation.widgetPath },
+                    });
+                }
+            }
+            // Add info for missing goldens
+            for (const missing of gateResult.missingGoldens) {
+                infos.push({
+                    id: `g12_${missing}_missing`,
+                    message: `Golden created: ${missing}`,
+                    severity: 'INFO',
+                    location: { file: missing },
+                });
+            }
+            return {
+                gateId: 'G12',
+                passed: violations.length === 0,
+                executionTimeMs: Date.now() - startTime,
+                violations,
+                warnings,
+                infos,
+                summary: gateResult.summary,
+                metadata: {
+                    validations: gateResult.validations.length,
+                    passed: gateResult.passedWidgets.length,
+                    failed: gateResult.failedWidgets.length,
+                    missingGoldens: gateResult.missingGoldens.length,
+                    tokensUsed: gateResult.totalTokensUsed,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                gateId: 'G12',
+                passed: false,
+                executionTimeMs: Date.now() - startTime,
+                violations: [
+                    {
+                        id: 'g12_error',
+                        message: `Golden snapshot gate error: ${error instanceof Error ? error.message : String(error)}`,
+                        severity: 'BLOCK',
+                        autoFixable: false,
+                    },
+                ],
+                warnings: [],
+                infos: [],
+                summary: 'Gate execution failed',
+            };
+        }
+    }
+    /**
+     * Parse V16 input to golden snapshot input
+     */
+    parseInput(input) {
+        const metadata = input.metadata;
+        return {
+            widgetPath: metadata?.widgetPath || 'lib/main.dart',
+            code: input.code,
+            devices: metadata?.devices || this.config.defaultDevices,
+            threshold: metadata?.threshold || this.config.defaultThreshold,
+            updateGolden: metadata?.updateGolden || false,
+            context: metadata?.context,
+        };
+    }
+    // ============================================================================
+    // Core Validation
+    // ============================================================================
+    /**
+     * Validate widget against golden snapshots
+     */
+    async validate(input) {
+        const startTime = Date.now();
+        const widgetPaths = [input.widgetPath];
+        const devices = input.devices || this.config.defaultDevices;
+        this.emitEvent({
+            type: 'gate:started',
+            widgetPaths,
+            timestamp: Date.now(),
+        });
+        // Load golden index
+        await this.loadGoldenIndex();
+        const validations = [];
+        const failedWidgets = [];
+        const passedWidgets = [];
+        const missingGoldens = [];
+        const updatedGoldens = [];
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        // Process each widget/device combination
+        for (const widgetPath of widgetPaths) {
+            for (const device of devices) {
+                try {
+                    const result = await this.validateWidget(widgetPath, device, input);
+                    validations.push(result);
+                    if (result.passed) {
+                        if (!passedWidgets.includes(widgetPath)) {
+                            passedWidgets.push(widgetPath);
+                        }
+                    }
+                    else {
+                        if (!failedWidgets.includes(widgetPath)) {
+                            failedWidgets.push(widgetPath);
+                        }
+                    }
+                    if (result.goldenUpdated) {
+                        updatedGoldens.push(`${widgetPath}/${device.id}`);
+                    }
+                    if (result.comparison?.tokensUsed) {
+                        totalInputTokens += result.comparison.tokensUsed.input;
+                        totalOutputTokens += result.comparison.tokensUsed.output;
+                    }
+                }
+                catch (error) {
+                    validations.push({
+                        widgetPath,
+                        device,
+                        passed: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    if (!failedWidgets.includes(widgetPath)) {
+                        failedWidgets.push(widgetPath);
+                    }
+                }
+            }
+        }
+        const result = {
+            gateId: 'G12',
+            passed: failedWidgets.length === 0,
+            executionTimeMs: Date.now() - startTime,
+            validations,
+            summary: this.buildSummary(validations, failedWidgets, passedWidgets),
+            failedWidgets,
+            passedWidgets,
+            missingGoldens,
+            updatedGoldens,
+            totalTokensUsed: {
+                input: totalInputTokens,
+                output: totalOutputTokens,
+            },
+        };
+        this.emitEvent({
+            type: 'gate:complete',
+            result,
+            timestamp: Date.now(),
+        });
+        return result;
+    }
+    /**
+     * Validate a single widget on a device
+     */
+    async validateWidget(widgetPath, device, input) {
+        const goldenId = generateGoldenId(widgetPath, device.id);
+        const golden = this.goldenIndex?.goldens.get(goldenId);
+        // Capture current screenshot
+        const screenshot = await this.captureScreenshot(widgetPath, device);
+        if (!screenshot.success || !screenshot.filePath) {
+            return {
+                widgetPath,
+                device,
+                passed: false,
+                screenshot,
+                error: screenshot.error || 'Screenshot capture failed',
+            };
+        }
+        // Handle missing golden
+        if (!golden) {
+            this.emitEvent({
+                type: 'golden:missing',
+                widgetPath,
+                device,
+                timestamp: Date.now(),
+            });
+            if (this.config.autoCreateMissing || input.updateGolden) {
+                const newGolden = await this.createGolden(widgetPath, device, screenshot.filePath);
+                return {
+                    widgetPath,
+                    device,
+                    passed: true,
+                    screenshot,
+                    golden: newGolden,
+                    goldenUpdated: true,
+                };
+            }
+            if (this.config.failOnMissing) {
+                return {
+                    widgetPath,
+                    device,
+                    passed: false,
+                    screenshot,
+                    error: 'Golden baseline not found',
+                };
+            }
+            return {
+                widgetPath,
+                device,
+                passed: true, // Pass with warning
+                screenshot,
+            };
+        }
+        // Update golden if requested
+        if (input.updateGolden) {
+            const updatedGolden = await this.updateGolden(golden, screenshot.filePath);
+            return {
+                widgetPath,
+                device,
+                passed: true,
+                screenshot,
+                golden: updatedGolden,
+                goldenUpdated: true,
+            };
+        }
+        // Compare with golden
+        const comparison = await this.compareWithGolden(screenshot.filePath, golden, device, input.threshold || this.config.defaultThreshold, input.context);
+        const passed = comparison.passed;
+        if (passed) {
+            this.emitEvent({
+                type: 'validation:passed',
+                result: { widgetPath, device, passed, screenshot, golden, comparison },
+                timestamp: Date.now(),
+            });
+        }
+        else {
+            this.emitEvent({
+                type: 'validation:failed',
+                result: { widgetPath, device, passed, screenshot, golden, comparison },
+                timestamp: Date.now(),
+            });
+        }
+        return {
+            widgetPath,
+            device,
+            passed,
+            screenshot,
+            golden,
+            comparison,
+        };
+    }
+    // ============================================================================
+    // Screenshot Capture
+    // ============================================================================
+    /**
+     * Capture screenshot for widget
+     */
+    async captureScreenshot(widgetPath, device) {
+        const startTime = Date.now();
+        // Check if we can capture (display available)
+        if (this.config.skipWithoutDisplay && !this.hasDisplay()) {
+            return {
+                success: false,
+                duration: Date.now() - startTime,
+                error: 'No display available for screenshot capture',
+            };
+        }
+        try {
+            const result = await this.emulatorCapture.captureWithIntegrationTest(widgetPath, device);
+            return result;
+        }
+        catch (error) {
+            return {
+                success: false,
+                duration: Date.now() - startTime,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Check if display is available
+     */
+    hasDisplay() {
+        // On macOS/Windows, display is typically available
+        if (process.platform !== 'linux')
+            return true;
+        // On Linux, check for DISPLAY environment variable
+        return !!process.env.DISPLAY;
+    }
+    // ============================================================================
+    // Golden Management
+    // ============================================================================
+    /**
+     * Load golden index
+     */
+    async loadGoldenIndex() {
+        if (this.goldenIndex)
+            return;
+        const indexPath = path.join(this.config.goldenBaseDir, 'golden-index.json');
+        try {
+            const content = await fs.readFile(indexPath, 'utf-8');
+            const data = JSON.parse(content);
+            this.goldenIndex = {
+                version: data.version || '1.0',
+                projectId: data.projectId || 'unknown',
+                baseDir: this.config.goldenBaseDir,
+                goldens: new Map(Object.entries(data.goldens || {})),
+                updatedAt: data.updatedAt || Date.now(),
+            };
+        }
+        catch {
+            // Create new index
+            this.goldenIndex = {
+                version: '1.0',
+                projectId: 'unknown',
+                baseDir: this.config.goldenBaseDir,
+                goldens: new Map(),
+                updatedAt: Date.now(),
+            };
+        }
+    }
+    /**
+     * Save golden index
+     */
+    async saveGoldenIndex() {
+        if (!this.goldenIndex)
+            return;
+        const indexPath = path.join(this.config.goldenBaseDir, 'golden-index.json');
+        await fs.mkdir(path.dirname(indexPath), { recursive: true });
+        const data = {
+            version: this.goldenIndex.version,
+            projectId: this.goldenIndex.projectId,
+            goldens: Object.fromEntries(this.goldenIndex.goldens),
+            updatedAt: Date.now(),
+        };
+        await fs.writeFile(indexPath, JSON.stringify(data, null, 2));
+    }
+    /**
+     * Create a new golden
+     */
+    async createGolden(widgetPath, device, screenshotPath) {
+        const goldenId = generateGoldenId(widgetPath, device.id);
+        const goldenPath = path.join(this.config.goldenBaseDir, 'images', `${goldenId}.png`);
+        // Copy screenshot to golden location
+        await fs.mkdir(path.dirname(goldenPath), { recursive: true });
+        await fs.copyFile(screenshotPath, goldenPath);
+        // Get image dimensions and checksum
+        const checksum = await this.calculateChecksum(goldenPath);
+        const golden = {
+            id: goldenId,
+            widgetPath,
+            device,
+            imagePath: goldenPath,
+            dimensions: { width: device.width, height: device.height },
+            checksum,
+            capturedAt: Date.now(),
+        };
+        // Save to index
+        this.goldenIndex?.goldens.set(goldenId, golden);
+        await this.saveGoldenIndex();
+        this.emitEvent({
+            type: 'golden:created',
+            widgetPath,
+            golden,
+            timestamp: Date.now(),
+        });
+        return golden;
+    }
+    /**
+     * Update an existing golden
+     */
+    async updateGolden(golden, screenshotPath) {
+        // Copy new screenshot over golden
+        await fs.copyFile(screenshotPath, golden.imagePath);
+        // Update checksum
+        golden.checksum = await this.calculateChecksum(golden.imagePath);
+        golden.capturedAt = Date.now();
+        // Save to index
+        this.goldenIndex?.goldens.set(golden.id, golden);
+        await this.saveGoldenIndex();
+        this.emitEvent({
+            type: 'golden:updated',
+            widgetPath: golden.widgetPath,
+            golden,
+            timestamp: Date.now(),
+        });
+        return golden;
+    }
+    // ============================================================================
+    // Vision Comparison
+    // ============================================================================
+    /**
+     * Compare screenshot with golden using Vision LLM
+     */
+    async compareWithGolden(screenshotPath, golden, device, threshold, context) {
+        const startTime = Date.now();
+        // Check cache
+        const cacheKey = `${screenshotPath}_${golden.id}_${threshold}`;
+        const cached = this.comparisonCache.get(cacheKey);
+        if (cached && Date.now() - cached.duration < this.config.cacheMaxAge) {
+            return cached;
+        }
+        this.emitEvent({
+            type: 'comparison:starting',
+            widgetPath: golden.widgetPath,
+            timestamp: Date.now(),
+        });
+        try {
+            const prompt = buildComparisonPrompt(golden.widgetPath, device, context);
+            const { response, tokensUsed } = await this.visionProvider.compareImages(screenshotPath, golden.imagePath, prompt);
+            const parsed = parseVisionResponse(response);
+            const result = {
+                passed: passesSimilarityThreshold(parsed.similarity || 0, threshold),
+                similarity: parsed.similarity || 0,
+                threshold,
+                differences: parsed.differences || [],
+                assessment: parsed.assessment || 'No assessment',
+                suggestions: parsed.suggestions,
+                shouldUpdateGolden: parsed.shouldUpdateGolden,
+                rawResponse: response,
+                duration: Date.now() - startTime,
+                tokensUsed,
+            };
+            // Cache result
+            this.comparisonCache.set(cacheKey, result);
+            this.emitEvent({
+                type: 'comparison:complete',
+                widgetPath: golden.widgetPath,
+                result,
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+        catch (error) {
+            const result = {
+                passed: false,
+                similarity: 0,
+                threshold,
+                differences: [],
+                assessment: `Comparison failed: ${error instanceof Error ? error.message : String(error)}`,
+                duration: Date.now() - startTime,
+            };
+            this.emitEvent({
+                type: 'comparison:complete',
+                widgetPath: golden.widgetPath,
+                result,
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+    }
+    // ============================================================================
+    // Utility Methods
+    // ============================================================================
+    /**
+     * Calculate file checksum
+     */
+    async calculateChecksum(filePath) {
+        const content = await fs.readFile(filePath);
+        return crypto.createHash('sha256').update(content).digest('hex');
+    }
+    /**
+     * Build summary message
+     */
+    buildSummary(validations, failed, passed) {
+        const total = validations.length;
+        const passedCount = validations.filter((v) => v.passed).length;
+        if (failed.length === 0) {
+            return `Golden snapshot validation passed (${passedCount}/${total} checks)`;
+        }
+        const avgSimilarity = validations
+            .filter((v) => v.comparison)
+            .reduce((sum, v) => sum + (v.comparison?.similarity || 0), 0) /
+            validations.filter((v) => v.comparison).length;
+        return (`Golden snapshot validation failed: ${failed.length} widget(s) with visual regressions. ` +
+            `Average similarity: ${formatSimilarity(avgSimilarity || 0)}`);
+    }
+    /**
+     * Clear comparison cache
+     */
+    clearCache() {
+        this.comparisonCache.clear();
+    }
+    /**
+     * Get configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Cleanup resources
+     */
+    async cleanup() {
+        await this.emulatorCapture.cleanup();
+        this.comparisonCache.clear();
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create golden snapshot gate
+ */
+export function createGoldenSnapshotGate(config, visionProvider) {
+    return new GoldenSnapshotGate(config, visionProvider);
+}
+export default GoldenSnapshotGate;
+//# sourceMappingURL=GoldenSnapshotGate.js.map