deflake 1.0.0

package/README.md

@@ -0,0 +1,34 @@
+# DeFlake (JavaScript Client) ❄️
+
+> **Stop Flaky Tests. Start Auto-Healing.**
+> Official Node.js client for DeFlake.
+
+## 🚀 Installation
+
+```bash
+npm install deflake --save-dev
+```
+
+## 🔧 Usage
+
+### Wrapper Mode (Zero Config)
+Simply prepend `npx deflake` to your test run command:
+
+```bash
+# Playwright
+export DEFLAKE_API_KEY="your-api-key"
+npx deflake npx playwright test
+
+# Cypress
+npx deflake npx cypress run
+```
+
+### Manual Mode
+Analyze an existing error log and HTML snapshot:
+
+```bash
+npx deflake --log error.log --html playwright-report/index.html
+```
+
+## 📄 License
+ISC

package/cli.js

@@ -0,0 +1,468 @@
+#!/usr/bin/env node
+const yargs = require('yargs/yargs');
+const { hideBin } = require('yargs/helpers');
+const DeFlakeClient = require('./client');
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const argv = yargs(hideBin(process.argv))
+    .option('log', {
+        alias: 'l',
+        type: 'string',
+        description: 'Path to the error log file',
+        demandOption: false // No longer strictly required if running in wrapper mode
+    })
+    .option('html', {
+        alias: 'h',
+        type: 'string',
+        description: 'Path to the HTML snapshot',
+        demandOption: false // No longer strictly required if auto-detected
+    })
+    .option('api-url', {
+        type: 'string',
+        description: 'Override Default API URL',
+    })
+    .help()
+    .argv;
+
+// Helper to auto-detect artifacts (Batch Mode)
+function detectAllArtifacts(providedLog, providedHtml) {
+    // If user provided explicit paths, use them as a single item list
+    if (providedHtml || providedLog) {
+        return [{
+            logPath: providedLog,
+            htmlPath: providedHtml,
+            id: 'manual-input',
+            name: 'Manual Input'
+        }];
+    }
+
+    const detected = [];
+
+    // 1. Scan test-results
+    if (fs.existsSync('test-results')) {
+        function findFiles(dir) {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const res = path.resolve(dir, entry.name);
+                if (entry.isDirectory()) {
+                    findFiles(res);
+                } else {
+                    // Unique ID for this test failure is the parent folder name
+                    const folderName = path.basename(path.dirname(res));
+
+                    // We only want ONE artifact per test folder.
+                    // Priority: error-context.md > index.html > trace.zip
+
+                    // But we can't easily dedup here without a map.
+                    // Let's just collect all candidates and filter later.
+                }
+            }
+        }
+
+        // Better approach: Iterate folders in test-results
+        const testFolders = fs.readdirSync('test-results', { withFileTypes: true })
+            .filter(dirent => dirent.isDirectory())
+            .map(dirent => path.resolve('test-results', dirent.name));
+
+        for (const folder of testFolders) {
+            let artifact = null;
+            let type = '';
+
+            const mdPath = path.join(folder, 'error-context.md');
+            const htmlPath = path.join(folder, 'trace.html'); // Some reporters use this
+
+            // Check for error-context.md (High Quality)
+            if (fs.existsSync(mdPath)) {
+                artifact = mdPath;
+                type = 'md';
+            }
+            // Else check for any HTML that isn't trace viewer boilerplate
+            else {
+                // simple fallback
+            }
+
+            if (artifact) {
+                detected.push({
+                    logPath: null, // Log is usually embedded or passed via stdout
+                    htmlPath: artifact,
+                    id: path.basename(folder),
+                    name: path.basename(folder)
+                });
+            }
+        }
+    }
+
+    // Fallback: If no granular results, check global report
+    if (detected.length === 0) {
+        if (fs.existsSync('playwright-report/index.html')) {
+            detected.push({
+                logPath: providedLog,
+                htmlPath: 'playwright-report/index.html',
+                id: 'global-report',
+                name: 'Global Report'
+            });
+        }
+    }
+
+    return detected;
+}
+
+function stripAnsi(str) {
+    return str.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '');
+}
+
+function parsePlaywrightLogs(fullLog) {
+    // Strip ANSI codes to reliable regex matching
+    const cleanLog = stripAnsi(fullLog);
+    const errorBlocks = [];
+
+    // Regex to find start of a test failure: "  1) [chromium] › ..."
+    const errorHeaderRegex = /^\s*(\d+)\)\s+\[(.*?)\]\s+/gm;
+    let match;
+
+    // Find all start indices
+    const indices = [];
+    while ((match = errorHeaderRegex.exec(cleanLog)) !== null) {
+        indices.push({ index: match.index, browser: match[2] }); // Group 2 is browser
+    }
+
+    // Slice log into blocks
+    for (let i = 0; i < indices.length; i++) {
+        const start = indices[i].index;
+        const end = (i + 1 < indices.length) ? indices[i + 1].index : cleanLog.length;
+        const content = cleanLog.slice(start, end);
+        errorBlocks.push({
+            browser: indices[i].browser, // e.g. 'chromium'
+            content: content
+        });
+    }
+
+    return errorBlocks;
+}
+
+async function runHealer(logContent, htmlPath, apiUrl, testName) {
+    // Check file size limit (Basic check to avoid 429s on huge files)
+    if (htmlPath && fs.existsSync(htmlPath)) {
+        const stats = fs.statSync(htmlPath);
+        if (stats.size > 5 * 1024 * 1024) { // 5MB limit warning
+            console.warn(`⚠️  Warning: Artifact for ${testName} is large (` + (stats.size / 1024 / 1024).toFixed(2) + "MB).");
+        }
+    }
+
+    const client = new DeFlakeClient(apiUrl);
+
+    // Pass log CONTENT (string) directly if it came from wrapper, or file path if from args
+    let finalLogPath = argv.log;
+    let effectiveLogContent = logContent;
+
+    // Robustness: If logContent is empty but we have an MD artifact, read it
+    if (!effectiveLogContent && htmlPath && htmlPath.endsWith('.md') && fs.existsSync(htmlPath)) {
+        try {
+            effectiveLogContent = fs.readFileSync(htmlPath, 'utf8');
+        } catch (e) { }
+    }
+
+    if (effectiveLogContent) {
+        // We have content (from stdio or artifact), write to temp file
+        finalLogPath = '.deflake-error.log';
+        fs.writeFileSync(finalLogPath, effectiveLogContent);
+    } else if (!finalLogPath && fs.existsSync('error.log')) {
+        // Fallback to auto-detected error.log if nothing else
+        finalLogPath = 'error.log';
+    }
+
+    // Validation before calling client
+    if (!finalLogPath) {
+        // Create a dummy log if we have HTML but absolutely no log, to prevent client crash
+        if (htmlPath) {
+            console.log("   (Creating temporary log from available context)");
+            finalLogPath = '.deflake-error.log';
+            fs.writeFileSync(finalLogPath, "Log missing. Refer to HTML/MD snapshot.");
+            effectiveLogContent = "Log missing.";
+        } else {
+            console.error(`❌ [${testName}] Error: No log file or content available.`);
+            return;
+        }
+    }
+
+    // 🧠 SMART CONTEXT: Extract the failing source code if possible
+    const failureLoc = extractFailureLocation(effectiveLogContent || fs.readFileSync(finalLogPath, 'utf8'));
+
+    let sourceCodeContent = null;
+    if (failureLoc && failureLoc.fullRootPath) {
+        try {
+            if (fs.existsSync(failureLoc.fullRootPath)) {
+                sourceCodeContent = fs.readFileSync(failureLoc.fullRootPath, 'utf8');
+            }
+        } catch (e) { }
+    }
+
+    if (!failureLoc) {
+        // Silent warning for batch mode - don't clutter output
+    }
+
+    try {
+        const result = await client.heal(finalLogPath, htmlPath, failureLoc, sourceCodeContent);
+
+        if (result && result.status === 'success') {
+            // Return structured object for grouping
+            return {
+                testName,
+                location: failureLoc,
+                sourceCode: sourceCodeContent,
+                fix: result.fix,
+                status: 'success'
+            };
+        }
+        // Return original result so main() can check for QUOTA_EXCEEDED
+        return result || { status: 'error', detail: 'UNKNOWN' };
+    } catch (error) {
+        return { status: 'error', detail: error.message };
+    }
+}
+
+// ... (extractFailureLocation and printDetailedFix remain mostly same, just slight tweaks for robustness) ...
+// Actually, I need to include them in the replace or user 'multi_replace' but this is 'replace_file' so I must provide full content or precise chunks.
+// To avoid massive token usage, I will use the existing helper functions but just update Main.
+
+// WAIT, I must provide the implementations of extractFailureLocation and printDetailedFix if I replace the whole file or large chunks.
+// The previous tool call view_file shows I have the whole content. I will rewrite the whole file to be safe and clean.
+
+function extractFailureLocation(logText) {
+    if (!logText) return null;
+    const loc = {
+        specFile: null,
+        testLine: null,
+        rootFile: null,
+        fullRootPath: null,
+        rootLine: null,
+        stepLine: null
+    };
+
+    const testMatch = logText.match(/^\s*\d+\)\s+\[.*?\]\s+›\s+(.*?.spec.ts):(\d+):\d+\s+›/m);
+    if (testMatch) {
+        loc.specFile = testMatch[1];
+        loc.testLine = testMatch[2];
+    }
+
+    const stackRegex = /at\s+(?:.*? \()?((?:[a-zA-Z]:\\|[\/~]|\.?\.\/|[\w_\-]+\/).*?):(\d+):(\d+)\)?/g;
+    let match;
+    let foundRoot = false;
+
+    while ((match = stackRegex.exec(logText)) !== null) {
+        const file = match[1];
+        const line = match[2];
+        if (!foundRoot && !file.includes('node_modules')) {
+            loc.rootFile = file.split('/').pop();
+            loc.fullRootPath = path.resolve(process.cwd(), file);
+            loc.rootLine = line;
+            foundRoot = true;
+        }
+        if (loc.specFile && file.endsWith(loc.specFile)) {
+            loc.stepLine = line;
+        }
+    }
+
+    // Fallback: If header regex failed but we found a root file that looks like a test
+    if (!loc.specFile && loc.rootFile && (loc.rootFile.includes('.spec.') || loc.rootFile.includes('.test.'))) {
+        loc.specFile = loc.rootFile;
+        loc.testLine = loc.rootLine;
+    }
+
+    if (loc.specFile || loc.rootFile) return loc;
+    return null;
+}
+
+function printDetailedFix(fixText, location, sourceCode = null) {
+    const C = {
+        RESET: "\x1b[0m",
+        BRIGHT: "\x1b[1m",
+        RED: "\x1b[31m",
+        GREEN: "\x1b[32m",
+        YELLOW: "\x1b[33m",
+        CYAN: "\x1b[36m",
+        BLUE: "\x1b[34m",
+        GRAY: "\x1b[90m",
+        WHITE: "\x1b[37m"
+    };
+
+    let fixCode = fixText;
+    let explanation = null;
+
+    try {
+        const parsed = JSON.parse(fixText);
+        if (parsed.code) {
+            fixCode = parsed.code;
+            explanation = parsed.reason;
+        }
+    } catch (e) { }
+
+    console.log("\n" + C.GRAY + "─".repeat(50) + C.RESET);
+    if (location) {
+        // Label is default color, Value is colored
+        if (location.rootFile && location.rootLine) {
+            console.log(`💥 Runtime Error:  ${C.RED}${location.rootFile}:${location.rootLine}${C.RESET}`);
+        }
+        if (location.specFile) {
+            // Calculate a nice label for the target
+            let targetLabel = location.specFile;
+            if (location.testLine) targetLabel += `:${location.testLine}`;
+            console.log(`🎯 Fix Target:    ${C.CYAN}${targetLabel} (Definition)${C.RESET}`);
+        }
+    }
+    console.log(C.GRAY + "─".repeat(50) + C.RESET);
+
+    console.log(`${C.GREEN}${C.BRIGHT}✨ DEFLAKE SUGGESTION:${C.RESET}`);
+    if (explanation) console.log(`${C.GRAY}// ${explanation}${C.RESET}`);
+
+    // Print code with simple coloring
+    fixCode.split('\n').forEach(line => {
+        let colored = line
+            .replace(/(\/\/.*)/g, `${C.GRAY}$1${C.RESET}`)
+            .replace(/\b(const|let|var|await|async|function|return)\b/g, `${C.YELLOW}$1${C.RESET}`)
+            .replace(/('.*?')|(".*?")|(`.*?`)/g, `${C.GREEN}$1${C.RESET}`)
+            .replace(/(\.click|\.fill|\.locator)/g, `${C.CYAN}$1${C.RESET}`);
+        console.log("  " + colored);
+    });
+    console.log(C.GRAY + "─".repeat(50) + C.RESET);
+}
+
+/**
+ * Core analysis engine for batch mode.
+ * Enforces tier limits and calculates deduplicated results.
+ */
+async function analyzeFailures(artifacts, fullLog, client) {
+    const C = {
+        RESET: "\x1b[0m",
+        YELLOW: "\x1b[33m",
+        RED: "\x1b[31m",
+        GRAY: "\x1b[90m"
+    };
+
+    if (artifacts.length === 0) {
+        console.log("⚠️  No error artifacts found.");
+        return;
+    }
+
+    // 1. Check Quota / Tier
+    const usage = await client.getUsage();
+    let limit = 100; // Default safety cap
+    let tier = 'unknown';
+
+    if (usage) {
+        tier = usage.tier || 'free';
+        if (tier === 'free') limit = 5;
+        else if (tier === 'pro') limit = 50;
+        else if (tier === 'master' || tier === 'byok') limit = 100;
+
+        console.log(`🎫 Subscription: ${tier.toUpperCase()} | Quota: ${usage.usage}/${usage.limit}`);
+    }
+
+    if (artifacts.length > limit) {
+        console.log(`${C.YELLOW}⚠️  Detected ${artifacts.length} failures, but your ${tier} plan limits batch analysis to ${limit} unique fixes.${C.RESET}`);
+        console.log(`   (Processing the first ${limit}...)\n`);
+    }
+
+    const errorBlocks = parsePlaywrightLogs(fullLog || "");
+    const results = [];
+    const processLimit = Math.min(artifacts.length, limit);
+    const batchArtifacts = artifacts.slice(0, processLimit);
+
+    console.log(`🔍 Analyzing ${batchArtifacts.length} failure(s)...`);
+
+    for (const art of batchArtifacts) {
+        let specificLog = fullLog;
+        if (art.htmlPath && art.htmlPath.endsWith('.md') && errorBlocks.length > 0) {
+            let bestMatch = null;
+            let bestScore = -1;
+            const artifactTokens = art.name.toLowerCase().replace(/[-_]/g, ' ').split(' ').filter(w => w.length > 3 && w !== 'chromium' && w !== 'firefox' && w !== 'webkit');
+            const browser = art.name.toLowerCase().includes('firefox') ? 'firefox' : art.name.toLowerCase().includes('webkit') ? 'webkit' : 'chromium';
+            const candidates = errorBlocks.filter(b => b.browser.toLowerCase().includes(browser));
+
+            for (const block of candidates) {
+                let score = 0;
+                const blockLower = block.content.toLowerCase();
+                for (const token of artifactTokens) { if (blockLower.includes(token)) score++; }
+                if (score > bestScore) { bestScore = score; bestMatch = block; }
+            }
+            if (bestMatch && bestScore > 0) {
+                specificLog = bestMatch.content;
+                const idx = errorBlocks.indexOf(bestMatch);
+                if (idx > -1) errorBlocks.splice(idx, 1);
+            }
+        }
+
+        process.stdout.write(`\r⏳ Analyzing ${art.name}...        `);
+        const result = await runHealer(specificLog, art.htmlPath, argv.apiUrl, art.name);
+
+        if (result && result.status === 'error' && result.detail === 'QUOTA_EXCEEDED') {
+            console.log(`\n${C.RED}🛑 Quota exceeded! Stopping.${C.RESET}`);
+            break;
+        }
+
+        if (result && result.status === 'success') {
+            results.push(result);
+        }
+    }
+    console.log("\r✅ Analysis complete.                        \n");
+
+    // GROUPING & PRINTING
+    const groups = {};
+    for (const res of results) {
+        if (!res.location) continue;
+        const key = `${res.location.rootFile}:${res.location.rootLine}|${JSON.stringify(res.fix)}`;
+        if (!groups[key]) {
+            groups[key] = { location: res.location, sourceCode: res.sourceCode, fix: res.fix, tests: [] };
+        }
+        groups[key].tests.push(res.testName);
+    }
+
+    const sortedKeys = Object.keys(groups).sort((a, b) => {
+        const lineA = parseInt(groups[a].location?.rootLine) || 0;
+        const lineB = parseInt(groups[b].location?.rootLine) || 0;
+        return lineA - lineB;
+    });
+
+    for (const key of sortedKeys) {
+        printDetailedFix(groups[key].fix, groups[key].location, groups[key].sourceCode);
+    }
+}
+
+async function main() {
+    console.log("🚑 DeFlake JS Client (Batch Mode)");
+    const client = new DeFlakeClient(argv.apiUrl);
+    const command = argv._;
+
+    if (command.length > 0) {
+        const cmd = command[0];
+        const args = command.slice(1);
+        console.log(`🚀 Running command: ${cmd} ${args.join(' ')}`);
+
+        const child = spawn(cmd, args, { shell: true, stdio: 'pipe' });
+        let stdout = '';
+        let stderr = '';
+
+        child.stdout.on('data', (data) => { process.stdout.write(data); stdout += data.toString(); });
+        child.stderr.on('data', (data) => { process.stderr.write(data); stderr += data.toString(); });
+
+        child.on('close', async (code) => {
+            if (code !== 0) {
+                console.log(`\n🔴 Command failed with code ${code}. Activating DeFlake...`);
+                const artifacts = detectAllArtifacts(null, argv.html);
+                await analyzeFailures(artifacts, stdout + "\n" + stderr, client);
+                process.exit(code);
+            } else {
+                console.log("\n🟢 Command passed successfully.");
+                process.exit(0);
+            }
+        });
+    } else {
+        const artifacts = detectAllArtifacts(argv.log, argv.html);
+        const fullLog = argv.log && fs.existsSync(argv.log) ? fs.readFileSync(argv.log, 'utf8') : null;
+        await analyzeFailures(artifacts, fullLog, client);
+    }
+}
+
+main();

package/client.js

@@ -0,0 +1,75 @@
+const axios = require('axios');
+const fs = require('fs');
+const path = require('path');
+require('dotenv').config();
+
+class DeFlakeClient {
+    constructor(apiUrl, apiKey) {
+        // Use environment variable first, then fallback to a placeholder production URL
+        // User can still pass a custom URL for local development/B2B setups
+        this.productionUrl = 'https://deflake-api.up.railway.app/api/deflake';
+        this.apiUrl = apiUrl || process.env.DEFLAKE_API_URL || this.productionUrl;
+        this.apiKey = apiKey || process.env.DEFLAKE_API_KEY;
+
+        if (!this.apiKey) {
+            console.error("❌ DeFlake Error: DEFLAKE_API_KEY is missing.");
+            console.error("   To get a free key, visit: http://deflake.com/register");
+            console.error("   Or set it in your environment: export DEFLAKE_API_KEY=your_key");
+            process.exit(1);
+        }
+    }
+
+    async getUsage() {
+        try {
+            const usageUrl = this.apiUrl.replace('/deflake', '/user/usage');
+            const response = await axios.get(usageUrl, {
+                headers: { 'X-API-KEY': this.apiKey }
+            });
+            return response.data;
+        } catch (error) {
+            return null; // Silent failure for usage check
+        }
+    }
+
+    async heal(logPath, htmlPath, failureLocation = null, sourceCode = null) {
+        try {
+            // ... (rest of the check logic) ...
+            if (!fs.existsSync(logPath)) throw new Error(`Log file not found: ${logPath}`);
+            if (!fs.existsSync(htmlPath)) throw new Error(`HTML file not found: ${htmlPath}`);
+
+            const logContent = fs.readFileSync(logPath, 'utf8');
+            const htmlContent = fs.readFileSync(htmlPath, 'utf8');
+
+            const payload = {
+                error_log: logContent,
+                html_snapshot: htmlContent,
+                failing_line: failureLocation ? `Line ${failureLocation.rootLine}` : null,
+                source_code: sourceCode
+            };
+
+            const response = await axios.post(this.apiUrl, payload, {
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-KEY': this.apiKey
+                }
+            });
+
+            return response.data;
+
+        } catch (error) {
+            if (error.response) {
+                if (error.response.status === 402) {
+                    return { status: 'error', detail: 'QUOTA_EXCEEDED' };
+                }
+                let detail = error.response.data.detail || error.response.statusText;
+                if (typeof detail === 'object') detail = JSON.stringify(detail);
+                console.error(`❌ API Error: ${error.response.status} - ${detail}`);
+            } else {
+                console.error(`❌ Client Error: ${error.message}`);
+            }
+            return null; // Return null instead of exiting process
+        }
+    }
+}
+
+module.exports = DeFlakeClient;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "deflake",
+  "version": "1.0.0",
+  "description": "AI-powered self-healing tool for Playwright, Cypress, and WebdriverIO tests.",
+  "main": "client.js",
+  "bin": {
+    "deflake": "cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "playwright",
+    "cypress",
+    "webdriverio",
+    "ai",
+    "self-healing",
+    "automation",
+    "testing"
+  ],
+  "author": "VicQA Automation Cloud",
+  "license": "ISC",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vicqaautomation-cloud/DeFlake.git"
+  },
+  "homepage": "https://github.com/vicqaautomation-cloud/DeFlake#readme",
+  "bugs": {
+    "url": "https://github.com/vicqaautomation-cloud/DeFlake/issues"
+  },
+  "dependencies": {
+    "axios": "^1.13.2",
+    "dotenv": "^17.2.3",
+    "yargs": "^18.0.0"
+  }
+}