qa360 2.1.7 → 2.2.0

package/dist/commands/explain.js

@@ -1,630 +0,0 @@
-/**
- * QA360 Explain Command
- *
- * Advanced error and failure explanations with:
- * - Static error code database
- * - AI-powered explanations
- * - Vault-based historical context
- * - Flakiness insights
- *
- * Usage:
- *   qa360 explain QX001              # Static error code
- *   qa360 explain --ai "my test failed"  # AI explanation
- *   qa360 explain --run run-xxx      # Explain run results
- *   qa360 explain --gate api_smoke   # Explain gate failure
- */
-import chalk from 'chalk';
-import ora from 'ora';
-import { join } from 'path';
-import { existsSync } from 'fs';
-import { createBest, createLLMProvider } from '../core/index.js';
-import { EvidenceVault } from '../core/index.js';
-/**
- * Static error code database
- */
-const ERROR_CODES = {
-    'QX001': {
-        title: 'Node.js Version Incompatible',
-        cause: 'QA360 Core requires Node.js 18.0.0 or higher. You are running an older version.',
-        solution: 'Update Node.js: https://nodejs.org/ or use nvm/fnm: `nvm install 20`',
-        category: 'prerequisite'
-    },
-    'QX002': {
-        title: 'QA360 Directory Structure Missing',
-        cause: 'Required .qa360 directories not found in the current project.',
-        solution: 'Run "qa360 doctor --fix" to create missing directories automatically',
-        category: 'setup'
-    },
-    'QX003': {
-        title: 'Playwright Not Available',
-        cause: 'Playwright is not installed or not in PATH. Required for API and UI tests.',
-        solution: 'Install: "npx playwright install" or use --docker flag for containerized execution',
-        category: 'prerequisite'
-    },
-    'QX004': {
-        title: 'Puppeteer Not Available',
-        cause: 'Puppeteer is not installed (required for PDF report generation).',
-        solution: 'Install: "npm install puppeteer" or use --format json to skip PDF generation',
-        category: 'prerequisite'
-    },
-    'QX005': {
-        title: 'Network Connectivity Issues',
-        cause: 'Cannot reach external services (API, website). Check proxy/firewall settings.',
-        solution: 'Check network, configure proxy (export HTTP_PROXY), or test with local endpoints',
-        category: 'network'
-    },
-    'QX006': {
-        title: 'Secrets Configuration Missing',
-        cause: 'No secrets.enc file configured. Required for encrypted credential storage.',
-        solution: 'Run "qa360 doctor --fix" to create default secrets file',
-        category: 'setup'
-    },
-    'QX007': {
-        title: 'Cryptographic Keys Missing',
-        cause: 'Ed25519 key pair not found for signing proofs. Required for proof generation.',
-        solution: 'Run "qa360 doctor --fix" to generate new key pair automatically',
-        category: 'setup'
-    },
-    'QP100': {
-        title: 'Pack Validation Failed',
-        cause: 'The pack.yml file does not conform to the required schema or has invalid values.',
-        solution: 'Check pack.yml syntax with "qa360 pack validate". Ensure required fields (version, name, gates) are present.',
-        category: 'pack'
-    },
-    'QP200': {
-        title: 'Pack Version Not Supported',
-        cause: 'The pack version specified is not supported by this version of QA360.',
-        solution: 'Update QA360: "npm install -g qa360@latest" or use pack v1 format',
-        category: 'pack'
-    },
-    'QG200': {
-        title: 'Gate Execution Failed',
-        cause: 'A quality gate failed during execution. Check gate-specific error messages.',
-        solution: 'Review gate logs in .qa360/runs/ directory. Run with verbose mode for details.',
-        category: 'execution'
-    },
-    'QG300': {
-        title: 'Adapter Not Found',
-        cause: 'The required adapter for a gate is not available or not installed.',
-        solution: 'Ensure dependencies are installed. Run "qa360 doctor" to check prerequisites.',
-        category: 'execution'
-    },
-    'QV100': {
-        title: 'Proof Verification Failed',
-        cause: 'The proof signature is invalid or the proof has been tampered with.',
-        solution: 'Ensure the proof file has not been modified. Check the public key matches the signer.',
-        category: 'verification'
-    },
-    'QV200': {
-        title: 'Vault Corruption Detected',
-        cause: 'The evidence vault database (.qa360/vault.db) is corrupted or invalid.',
-        solution: 'Run "qa360 doctor --fix" to repair the vault. Restore from backup if available.',
-        category: 'vault'
-    },
-    'QT000': {
-        title: 'Test Timeout',
-        cause: 'A test exceeded the maximum allowed execution time.',
-        solution: 'Increase timeout in pack.yml (execution.timeout) or optimize the test',
-        category: 'execution'
-    },
-    'QT001': {
-        title: 'Flaky Test Detected',
-        cause: 'A test is showing inconsistent results across runs (flakiness score < 75).',
-        solution: 'Review "qa360 flakiness history" for patterns. Consider quarantining: "qa360 flakiness quarantine <testId>"',
-        category: 'flakiness'
-    },
-    'QD500': {
-        title: 'Dashboard Start Failed',
-        cause: 'The dashboard server cannot start (port in use or permission denied).',
-        solution: 'Use --port to specify a different port, or check if another instance is running.',
-        category: 'dashboard'
-    }
-};
-/**
- * Gate-specific explanations
- */
-const GATE_EXPLANATIONS = {
-    'api_smoke': {
-        title: 'API Smoke Tests',
-        commonFailures: [
-            'Endpoint not reachable (404, connection refused)',
-            'Unexpected response status (expected 200, got 500)',
-            'Response format mismatch',
-            'Authentication failure (401, 403)'
-        ],
-        tips: [
-            'Verify API is running: curl -I <apiUrl>',
-            'Check authentication tokens are valid',
-            'Review CORS settings for cross-origin requests',
-            'Ensure test environment matches expected configuration'
-        ]
-    },
-    'ui': {
-        title: 'UI/E2E Tests',
-        commonFailures: [
-            'Page load timeout',
-            'Element not found (selector changed)',
-            'JavaScript errors in browser console',
-            'Viewport/responsive issues'
-        ],
-        tips: [
-            'Use data-testid attributes for stable selectors',
-            'Add explicit waits for dynamic content',
-            'Check browser console for JavaScript errors',
-            'Test in headless mode matches real browser behavior'
-        ]
-    },
-    'a11y': {
-        title: 'Accessibility Tests',
-        commonFailures: [
-            'Missing alt text on images',
-            'Low color contrast ratio',
-            'Missing ARIA labels on interactive elements',
-            'Keyboard navigation issues'
-        ],
-        tips: [
-            'Use axe DevTools browser extension for debugging',
-            'Test with keyboard only (no mouse)',
-            'Run screen reader simulation to verify experience',
-            'Check contrast ratios with WCAG tools'
-        ]
-    },
-    'perf': {
-        title: 'Performance Tests',
-        commonFailures: [
-            'Response time exceeds budget',
-            'Error rate too high under load',
-            'Resource exhaustion (memory, CPU)',
-            'Timeouts during peak load'
-        ],
-        tips: [
-            'Start with low load and gradually increase',
-            'Monitor server resources during tests',
-            'Profile slow endpoints with performance tools',
-            'Consider caching and optimization strategies'
-        ]
-    },
-    'sast': {
-        title: 'Static Application Security Testing',
-        commonFailures: [
-            'Hardcoded secrets or passwords',
-            'SQL injection vulnerabilities',
-            'Unsafe function usage',
-            'Dependency vulnerabilities'
-        ],
-        tips: [
-            'Use environment variables for secrets',
-            'Parameterize all database queries',
-            'Keep dependencies updated',
-            'Review and understand each security finding'
-        ]
-    },
-    'dast': {
-        title: 'Dynamic Application Security Testing',
-        commonFailures: [
-            'Injection vulnerabilities (SQL, XSS)',
-            'Authentication/authorization bypass',
-            'Sensitive data exposure',
-            'Misconfigurations'
-        ],
-        tips: [
-            'Run against test environment only',
-            'DAST may trigger security alerts - inform your team',
-            'Review false positives carefully',
-            'Fix critical findings before production'
-        ]
-    },
-    'secrets': {
-        title: 'Secrets Scanning',
-        commonFailures: [
-            'API keys in source code',
-            'Passwords in config files',
-            'Certificates committed to repo',
-            'Tokens in logs'
-        ],
-        tips: [
-            'Use git-secrets or similar pre-commit hooks',
-            'Rotate any leaked credentials immediately',
-            'Use .env files with gitignore',
-            'Enable branch protection rules'
-        ]
-    },
-    'deps': {
-        title: 'Dependency Vulnerability Scanning',
-        commonFailures: [
-            'Known CVEs in dependencies',
-            'Outdated packages with security fixes',
-            'Transitive dependency issues',
-            'License violations'
-        ],
-        tips: [
-            'Run "npm audit fix" for automatic fixes',
-            'Review dependabot PRs promptly',
-            'Pin dependency versions where appropriate',
-            'Understand your dependency tree'
-        ]
-    }
-};
-/**
- * Explain an error code
- */
-async function explainErrorCode(code, json = false) {
-    const error = ERROR_CODES[code];
-    if (!error) {
-        console.log(chalk.red(`\n[X] Unknown error code: ${code}`));
-        console.log(chalk.blue('\nAvailable error codes:'));
-        const grouped = groupErrorCodes();
-        for (const [category, codes] of Object.entries(grouped)) {
-            console.log(chalk.yellow(`\n  ${category.toUpperCase()}:`));
-            console.log(chalk.gray(`    ${codes.join(', ')}`));
-        }
-        return;
-    }
-    if (json) {
-        console.log(JSON.stringify({ code, ...error }, null, 2));
-        return;
-    }
-    console.log(chalk.red(`\n[X] ${error.title}`));
-    console.log(chalk.gray(`   Code: ${code}`));
-    console.log(chalk.gray(`   Category: ${error.category}\n`));
-    console.log(chalk.yellow('Cause:'));
-    console.log(chalk.white(`   ${error.cause}\n`));
-    console.log(chalk.green('Solution:'));
-    console.log(chalk.white(`   ${error.solution}\n`));
-    // Show related commands
-    const relatedCommands = {
-        prerequisite: ['qa360 doctor', 'qa360 doctor --fix'],
-        setup: ['qa360 doctor --fix', 'qa360 secrets add'],
-        execution: ['qa360 run --verbose', 'qa360 history show <run-id>'],
-        pack: ['qa360 pack validate', 'qa360 init'],
-        vault: ['qa360 doctor --fix', 'qa360 history list'],
-        verification: ['qa360 verify --verbose'],
-        flakiness: ['qa360 flakiness history', 'qa360 flakiness quarantine'],
-        network: ['curl -I <url>', 'ping <host>'],
-        dashboard: ['qa360 dashboard --port 8081']
-    };
-    const commands = relatedCommands[error.category];
-    if (commands) {
-        console.log(chalk.cyan('Related commands:'));
-        commands.forEach(cmd => console.log(chalk.gray(`   ${cmd}`)));
-        console.log('');
-    }
-}
-/**
- * Group error codes by category
- */
-function groupErrorCodes() {
-    const grouped = {};
-    for (const [code, error] of Object.entries(ERROR_CODES)) {
-        if (!grouped[error.category]) {
-            grouped[error.category] = [];
-        }
-        grouped[error.category].push(code);
-    }
-    return grouped;
-}
-/**
- * Explain gate failure with context
- */
-async function explainGate(gateName, runId, json = false) {
-    const info = GATE_EXPLANATIONS[gateName];
-    if (!info) {
-        console.log(chalk.yellow(`\n[!] No specific information available for gate: ${gateName}`));
-        console.log(chalk.gray('Available gates: ' + Object.keys(GATE_EXPLANATIONS).join(', ')));
-        return;
-    }
-    if (json) {
-        console.log(JSON.stringify({ gate: gateName, ...info }, null, 2));
-        return;
-    }
-    console.log(chalk.bold(`\n${info.title} (${gateName})\n`));
-    console.log(chalk.yellow('Common failures:'));
-    info.commonFailures.forEach(f => console.log(chalk.gray(`  - ${f}`)));
-    console.log(chalk.cyan('\nTips:'));
-    info.tips.forEach(t => console.log(chalk.gray(`  - ${t}`)));
-    // Load from vault if runId provided
-    if (runId) {
-        await explainGateFromVault(gateName, runId);
-    }
-}
-/**
- * Load and display gate-specific data from vault
- */
-async function explainGateFromVault(gateName, runId) {
-    const vaultDir = join(process.cwd(), '.qa360');
-    if (!existsSync(vaultDir)) {
-        console.log(chalk.yellow('\n[!] Vault not found in current directory'));
-        return;
-    }
-    try {
-        const vault = new EvidenceVault({ baseDir: vaultDir });
-        // Get gate results from the run
-        const runInfo = await vault.getRun(runId);
-        if (!runInfo) {
-            console.log(chalk.yellow(`\n[!] Run ${runId} not found in vault`));
-            await vault.close();
-            return;
-        }
-        const gateResults = await vault.getGates(runId);
-        const gateResult = gateResults.find((g) => g.name === gateName);
-        if (gateResult) {
-            console.log(chalk.bold('\nRun Results:'));
-            console.log(chalk.gray(`  Status: ${gateResult.status}`));
-            console.log(chalk.gray(`  Duration: ${gateResult.duration_ms}ms`));
-            if (gateResult.metrics_json) {
-                const metrics = JSON.parse(gateResult.metrics_json);
-                if (metrics.total || metrics.passed || metrics.failed) {
-                    console.log(chalk.gray(`  Tests: ${metrics.passed || 0}/${metrics.total || 0} passed`));
-                }
-            }
-            // Get findings for this gate
-            const findings = await vault.getFindings(runId);
-            const gateFindings = findings.filter((f) => f.gate === gateName);
-            if (gateFindings.length > 0) {
-                console.log(chalk.yellow('\nFindings:'));
-                gateFindings.slice(0, 10).forEach((f) => {
-                    console.log(chalk.gray(`  - [${f.severity}] ${f.rule}: ${f.message}`));
-                });
-                if (gateFindings.length > 10) {
-                    console.log(chalk.gray(`  ... and ${gateFindings.length - 10} more`));
-                }
-            }
-        }
-        await vault.close();
-    }
-    catch (error) {
-        console.log(chalk.yellow(`\n[!] Could not load vault data: ${error.message}`));
-    }
-}
-/**
- * AI-powered explanation
- */
-async function explainWithAI(query, provider, runId, json = false) {
-    const spinner = ora('Connecting to AI provider...').start();
-    try {
-        // Get the AI provider
-        const aiProvider = provider
-            ? await createLLMProvider({ preferred: provider })
-            : await createBest();
-        if (!aiProvider) {
-            spinner.fail('No AI provider available');
-            console.log(chalk.yellow('\nSet up an AI provider:'));
-            console.log(chalk.gray('  qa360 ai list'));
-            console.log(chalk.gray('  export DEEPSEEK_API_KEY=your_key\n'));
-            return;
-        }
-        spinner.text = `Using ${aiProvider.getProviderType()}...`;
-        // Build context from vault if available
-        let context = '';
-        if (runId) {
-            const vaultDir = join(process.cwd(), '.qa360');
-            if (existsSync(vaultDir)) {
-                try {
-                    const vault = new EvidenceVault({ baseDir: vaultDir });
-                    const runInfo = await vault.getRun(runId);
-                    if (runInfo) {
-                        const duration = runInfo.ended_at && runInfo.started_at
-                            ? runInfo.ended_at - runInfo.started_at
-                            : undefined;
-                        context = `\n\nContext from run ${runId}:
-- Status: ${runInfo.status}
-- Trust Score: ${runInfo.trust_score ?? 'N/A'}
-- Pack: ${runInfo.pack_path || 'unknown'}
-- Duration: ${duration ? `${duration}ms` : 'N/A'}
-- Started: ${new Date(runInfo.started_at).toISOString()}`;
-                    }
-                    await vault.close();
-                }
-                catch {
-                    // Vault access failed, continue without context
-                }
-            }
-        }
-        // Build the explanation prompt
-        const systemPrompt = `You are QA360 Explain, an expert QA assistant.
-Explain test failures, errors, and quality issues in clear, actionable terms.
-
-Structure your response:
-1. **Summary**: What happened in one sentence
-2. **Root Cause**: Why it happened (technical explanation)
-3. **Impact**: What this means for the project
-4. **Solutions**: Specific steps to fix it (numbered list)
-5. **Prevention**: How to avoid this in the future
-
-Be concise but thorough. Use simple language but accurate technical terms.`;
-        const userPrompt = `Explain this QA issue:${context}\n\n${query}`;
-        const response = await aiProvider.generate({
-            prompt: userPrompt,
-            systemPrompt,
-            maxTokens: 2048,
-            temperature: 0.3
-        });
-        spinner.succeed(`Explanation using ${chalk.cyan(aiProvider.getProviderType())}\n`);
-        if (json) {
-            console.log(JSON.stringify({
-                provider: aiProvider.getProviderType(),
-                query,
-                explanation: response.content,
-                usage: response.usage
-            }, null, 2));
-        }
-        else {
-            console.log(chalk.bold('Explanation:\n'));
-            console.log(chalk.gray('-'.repeat(70)));
-            console.log(response.content);
-            console.log(chalk.gray('-'.repeat(70)));
-            console.log(chalk.gray(`\nTokens: ${response.usage.totalTokens}`));
-            console.log(chalk.gray(`  Prompt: ${response.usage.promptTokens}`));
-            console.log(chalk.gray(`  Completion: ${response.usage.completionTokens}\n`));
-        }
-    }
-    catch (error) {
-        spinner.fail('AI explanation failed');
-        console.log(chalk.red(`Error: ${error.message}`));
-        // Fallback to static explanation
-        console.log(chalk.yellow('\nYou can also try static explanations:'));
-        console.log(chalk.gray('  qa360 explain QX001    # List error codes'));
-        console.log(chalk.gray('  qa360 explain --gate api_smoke\n'));
-    }
-}
-/**
- * Explain a run result
- */
-async function explainRun(runId, options) {
-    const vaultDir = join(process.cwd(), '.qa360');
-    if (!existsSync(vaultDir)) {
-        console.log(chalk.red('\n[X] Vault not found in current directory'));
-        console.log(chalk.yellow('Run "qa360 run" first to generate test results.\n'));
-        return;
-    }
-    const spinner = ora('Loading run data...').start();
-    try {
-        const vault = new EvidenceVault({ baseDir: vaultDir });
-        const runInfo = await vault.getRun(runId);
-        if (!runInfo) {
-            spinner.fail(`Run ${runId} not found`);
-            console.log(chalk.yellow('\nAvailable runs:'));
-            const runs = await vault.listRuns({ limit: 20 });
-            runs.forEach((r) => console.log(chalk.gray(`  ${r.id} - ${r.status}`)));
-            await vault.close();
-            return;
-        }
-        spinner.succeed('Run loaded\n');
-        if (options.json) {
-            console.log(JSON.stringify(runInfo, null, 2));
-            await vault.close();
-            return;
-        }
-        // Calculate duration
-        const duration = runInfo.ended_at && runInfo.started_at
-            ? runInfo.ended_at - runInfo.started_at
-            : undefined;
-        // Display run summary
-        console.log(chalk.bold(`Run: ${runId}`));
-        console.log(chalk.gray(`   Status: ${runInfo.status}`));
-        console.log(chalk.gray(`   Trust Score: ${runInfo.trust_score ?? 'N/A'}/100`));
-        console.log(chalk.gray(`   Started: ${new Date(runInfo.started_at).toISOString()}`));
-        if (duration) {
-            console.log(chalk.gray(`   Duration: ${duration}ms\n`));
-        }
-        else {
-            console.log('');
-        }
-        // Get gate results
-        const gates = await vault.getGates(runId);
-        if (gates.length > 0) {
-            console.log(chalk.bold('Gates:'));
-            gates.forEach((g) => {
-                const icon = g.status === 'passed' ? '[OK]' : g.status === 'failed' ? '[FAIL]' : '[SKIP]';
-                const color = g.status === 'passed' ? chalk.green : g.status === 'failed' ? chalk.red : chalk.gray;
-                console.log(`  ${icon} ${color(g.name)} (${g.duration_ms || 'N/A'}ms)`);
-            });
-        }
-        // Get findings
-        const findings = await vault.getFindings(runId);
-        if (findings.length > 0) {
-            console.log(chalk.bold('\nFindings:'));
-            const bySeverity = {};
-            findings.forEach((f) => {
-                if (!bySeverity[f.severity])
-                    bySeverity[f.severity] = [];
-                bySeverity[f.severity].push(f);
-            });
-            ['critical', 'high', 'medium', 'low', 'info'].forEach(sev => {
-                if (bySeverity[sev]?.length) {
-                    console.log(chalk.red(`  ${sev.toUpperCase()}: ${bySeverity[sev].length}`));
-                    bySeverity[sev].slice(0, 5).forEach((f) => {
-                        const msg = f.message.length > 60 ? f.message.substring(0, 60) + '...' : f.message;
-                        console.log(chalk.gray(`    - ${f.rule}: ${msg}`));
-                    });
-                }
-            });
-        }
-        // Get flakiness data (may fail if vault doesn't have flakiness tables)
-        try {
-            const flakiness = await vault.getRunFlakiness(runId);
-            if (flakiness.length > 0) {
-                console.log(chalk.bold('\nFlakiness:'));
-                const unstable = flakiness.filter((f) => f.score < 75);
-                if (unstable.length > 0) {
-                    console.log(chalk.yellow(`  ${unstable.length} unstable tests detected`));
-                    unstable.forEach((f) => {
-                        console.log(chalk.gray(`    - ${f.test_name}: score ${f.score}`));
-                    });
-                }
-                else {
-                    console.log(chalk.green('  All tests are stable!'));
-                }
-            }
-        }
-        catch {
-            // Flakiness tables not available in this vault version
-        }
-        await vault.close();
-        // Offer AI explanation if requested
-        if (options.ai) {
-            console.log(chalk.cyan('\nGetting AI explanation...\n'));
-            await explainWithAI(`Explain this test run: ${runId} with status ${runInfo.status} and ${gates.length} gates`, options.provider, runId, options.json);
-        }
-    }
-    catch (error) {
-        spinner.fail('Failed to load run data');
-        console.log(chalk.red(`Error: ${error.message}`));
-    }
-}
-/**
- * Main explain command
- */
-export async function explainCommand(input, options = {}) {
-    // No input - show help
-    if (!input && !options.run && !options.gate) {
-        console.log(chalk.bold.cyan('\nQA360 Explain - Error and Failure Explanations\n'));
-        console.log(chalk.yellow('Usage:\n'));
-        console.log(chalk.gray('  qa360 explain QX001              # Explain error code'));
-        console.log(chalk.gray('  qa360 explain --ai "query"        # AI-powered explanation'));
-        console.log(chalk.gray('  qa360 explain --run run-xxx      # Explain test run'));
-        console.log(chalk.gray('  qa360 explain --gate api_smoke   # Explain gate failures\n'));
-        console.log(chalk.yellow('Available Error Codes:\n'));
-        const grouped = groupErrorCodes();
-        for (const [category, codes] of Object.entries(grouped)) {
-            console.log(chalk.cyan(`  ${category.toUpperCase()}:`));
-            codes.slice(0, 5).forEach(code => {
-                const error = ERROR_CODES[code];
-                console.log(chalk.gray(`    ${code} - ${error?.title}`));
-            });
-            if (codes.length > 5) {
-                console.log(chalk.gray(`    ... and ${codes.length - 5} more`));
-            }
-        }
-        console.log(chalk.yellow('\nAvailable Gates:\n'));
-        console.log(chalk.gray('  ' + Object.keys(GATE_EXPLANATIONS).join(', ') + '\n'));
-        return;
-    }
-    // Run mode
-    if (options.run) {
-        await explainRun(options.run, options);
-        return;
-    }
-    // Gate mode
-    if (options.gate) {
-        await explainGate(options.gate, options.run, options.json);
-        return;
-    }
-    // AI mode
-    if (options.ai) {
-        await explainWithAI(input || '', options.provider, options.run, options.json);
-        return;
-    }
-    // Error code mode (default)
-    if (input) {
-        // Check if it looks like an error code
-        if (/^Q[A-Z]\d{3}$/.test(input)) {
-            await explainErrorCode(input, options.json);
-        }
-        else {
-            // Treat as AI query
-            await explainWithAI(input, options.provider, options.run, options.json);
-        }
-    }
-}
-export default explainCommand;