jaku.sh 1.0.0

package/src/cli.js

@@ -0,0 +1,423 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs';
+import { loadConfig } from './utils/config.js';
+import { createLogger } from './utils/logger.js';
+import { Orchestrator } from './agents/orchestrator.js';
+import { CrawlAgent } from './agents/crawl-agent.js';
+import { QAAgent } from './agents/qa-agent.js';
+import { SecurityAgent } from './agents/security-agent.js';
+import { AIAgent } from './agents/ai-agent.js';
+import { LogicAgent } from './agents/logic-agent.js';
+import { APIAgent } from './agents/api-agent.js';
+import { ReportGenerator } from './reporting/report-generator.js';
+import { AuthManager } from './core/auth-manager.js';
+
+const BANNER = `
+${chalk.hex('#00ff88').bold('  ╦╔═╗╦╔═╦ ╦')}
+${chalk.hex('#00ff88').bold('  ║╠═╣╠╩╗║ ║')}  ${chalk.dim('呪 Autonomous Security & Quality Intelligence')}
+${chalk.hex('#00ff88').bold(' ╚╝╩ ╩╩ ╩╚═╝')}  ${chalk.dim('v1.0.0 · Multi-Agent')}
+`;
+
+const program = new Command();
+
+program
+    .name('jaku')
+    .description('JAKU (呪) — Autonomous QA & Security scanning agent for vibe-coded apps')
+    .version('1.0.0');
+
+// ═══════════════════════════════════════════════
+// Multi-Agent Scan Runner
+// ═══════════════════════════════════════════════
+
+async function runScan(url, options, modulesToRun) {
+    console.log(BANNER);
+
+    const config = loadConfig({ ...options, targetUrl: url });
+    config.target_url = url;
+    config.crawler = {
+        ...config.crawler,
+        max_pages: parseInt(options.maxPages) || config.crawler?.max_pages || 50,
+        max_depth: parseInt(options.maxDepth) || config.crawler?.max_depth || 5,
+    };
+
+    // Propagate CLI flags to config
+    if (options.haltOnCritical) config.halt_on_critical = true;
+    if (options.webhook) config.notify_webhook = options.webhook;
+
+    // Propagate auth flags from CLI
+    if (options.username || options.password || options.loginUrl || options.authStrategy) {
+        config.auth = config.auth || {};
+        if (options.authStrategy) config.auth.strategy = options.authStrategy;
+        if (options.loginUrl) config.auth.login_url = options.loginUrl;
+        if (options.username && options.password) {
+            config.credentials = config.credentials || [];
+            // Add CLI credentials as a "cli" role if not already present
+            const hasCliRole = config.credentials.some(c => c.role === 'cli');
+            if (!hasCliRole) {
+                config.credentials.push({
+                    role: 'cli',
+                    username: options.username,
+                    password: options.password,
+                });
+            }
+        }
+    }
+
+    // ── prod_safe guard ──
+    const prodIndicators = /\b(prod|production|live|www\.)\b/i;
+    const isLikelyProd = prodIndicators.test(url) && !/\b(staging|dev|test|local|sandbox)\b/i.test(url);
+    if (isLikelyProd && !options.prodSafe && !config.prod_safe) {
+        console.error(chalk.red('\n  ⛔ PRODUCTION TARGET DETECTED'));
+        console.error(chalk.red(`  URL "${url}" looks like a production environment.`));
+        console.error(chalk.red('  Add --prod-safe flag to confirm you have authorization to test.'));
+        console.error(chalk.dim('  Example: jaku scan https://prod.example.com --prod-safe\n'));
+        process.exit(1);
+    }
+
+    const logger = createLogger({ verbose: options.verbose });
+    const startTime = Date.now();
+
+    const runQA = modulesToRun.includes('qa');
+    const runSecurity = modulesToRun.includes('security');
+    const runAI = modulesToRun.includes('ai');
+    const runLogic = modulesToRun.includes('logic');
+    const runAPI = modulesToRun.includes('api');
+    const moduleLabel = modulesToRun.join(' + ').toUpperCase();
+
+    console.log(chalk.hex('#00ff88')('  Target:  ') + chalk.white(url));
+    console.log(chalk.hex('#00ff88')('  Modules: ') + chalk.white(moduleLabel));
+    console.log(chalk.hex('#00ff88')('  Mode:    ') + chalk.white('Multi-Agent Orchestration'));
+    console.log(chalk.hex('#00ff88')('  Severity:') + chalk.white(` ≥ ${config.severity_threshold}`));
+    console.log();
+
+    // ═══════════════════════════════════════
+    // Phase 0: Authentication (before spinners)
+    // ═══════════════════════════════════════
+    const authManager = new AuthManager(config, logger);
+    const authSpinner = ora({ text: chalk.dim('Detecting login forms...'), color: 'yellow' }).start();
+
+    // Pause spinner before prompting (so readline works cleanly)
+    authManager._onBeforePrompt = () => authSpinner.stop();
+    authManager._onAfterPrompt = () => { }; // don't restart — prompt handles its own output
+
+    await authManager.authenticate();
+
+    if (authManager.isAuthenticated) {
+        authSpinner.succeed(chalk.dim('Authenticated: ') + authManager.roles.map(r => chalk.hex('#00ff88')(r)).join(', '));
+    } else {
+        authSpinner.info(chalk.dim('No credentials — scanning unauthenticated'));
+    }
+
+    // Inject auth manager into config for agents to access
+    config._authManager = authManager;
+
+    // ═══════════════════════════════════════
+    // Build the agent constellation
+    // ═══════════════════════════════════════
+    const orchestrator = new Orchestrator(config, logger);
+
+    // JAKU-CRAWL always runs (all modules depend on it)
+    orchestrator.register(new CrawlAgent());
+
+    // Register module agents
+    let qaAgent = null;
+    let secAgent = null;
+
+    if (runQA) {
+        qaAgent = new QAAgent();
+        orchestrator.register(qaAgent);
+    }
+    if (runSecurity) {
+        secAgent = new SecurityAgent();
+        orchestrator.register(secAgent);
+    }
+    if (runAI) {
+        orchestrator.register(new AIAgent());
+    }
+    if (runLogic) {
+        orchestrator.register(new LogicAgent());
+    }
+    if (runAPI) {
+        orchestrator.register(new APIAgent());
+    }
+
+    // ═══════════════════════════════════════
+    // Wire up CLI progress display
+    // ═══════════════════════════════════════
+    const spinners = {};
+    let activeAgentCount = 0;
+    const parallelIndicator = () => activeAgentCount > 1 ? chalk.cyan(' ⚡parallel') : '';
+
+    orchestrator.on('agent:started', ({ agentName }) => {
+        activeAgentCount++;
+        const color = agentName === 'JAKU-SEC' ? 'yellow' : agentName === 'JAKU-AI' ? 'magenta' : agentName === 'JAKU-LOGIC' ? 'cyan' : agentName === 'JAKU-API' ? 'red' : 'green';
+        spinners[agentName] = ora({
+            text: chalk.dim(`[${agentName}] `) + 'Starting...' + parallelIndicator(),
+            color,
+        }).start();
+    });
+
+    orchestrator.on('agent:progress', ({ agentName, phase, message }) => {
+        if (spinners[agentName]) {
+            spinners[agentName].text = chalk.dim(`[${agentName}] `) + message + parallelIndicator();
+        }
+    });
+
+    orchestrator.on('agent:completed', ({ agentName, duration, findingsCount }) => {
+        activeAgentCount--;
+        if (spinners[agentName]) {
+            spinners[agentName].succeed(
+                chalk.dim(`[${agentName}] `) +
+                `Complete — ${chalk.hex('#00ff88').bold(findingsCount)} findings in ${(duration / 1000).toFixed(1)}s`
+            );
+        }
+    });
+
+    orchestrator.on('agent:error', ({ agentName, error }) => {
+        activeAgentCount--;
+        if (spinners[agentName]) {
+            spinners[agentName].fail(chalk.dim(`[${agentName}] `) + chalk.red(`Error: ${error}`));
+        }
+    });
+
+    // ═══════════════════════════════════════
+    // Execute the multi-agent pipeline
+    // ═══════════════════════════════════════
+    let results;
+    try {
+        results = await orchestrator.run();
+    } catch (err) {
+        console.error(chalk.red(`\n  Orchestrator failed: ${err.message}`));
+        process.exit(1);
+    }
+
+    // ═══════════════════════════════════════
+    // Report Generation
+    // ═══════════════════════════════════════
+    const reportSpinner = ora({
+        text: 'Generating reports...',
+        color: 'green',
+    }).start();
+
+    try {
+        const duration = Date.now() - startTime;
+        const reporter = new ReportGenerator(config, logger);
+
+        const testSummary = qaAgent?.testSummary || {};
+
+        const { reportDir, summary, dedupSummary } = await reporter.generate({
+            findings: results.findings,
+            deduplicated: results.deduplicated,
+            dedupStats: results.dedupStats,
+            correlations: results.correlations || [],
+            modules: modulesToRun,
+            testSummary: { ...testSummary, duration },
+            surfaceInventory: results.surfaceInventory,
+            outputDir: config.output_dir,
+        });
+
+        reportSpinner.succeed(`Reports saved to ${chalk.underline(reportDir)}`);
+
+        // ═══════════════════════════════════════
+        // Final Summary
+        // ═══════════════════════════════════════
+        console.log();
+        console.log(chalk.hex('#00ff88').bold('  ═══ SCAN COMPLETE ═══'));
+        console.log();
+        console.log(`  ${chalk.dim('Duration:')}    ${(duration / 1000).toFixed(1)}s`);
+        console.log(`  ${chalk.dim('Modules:')}     ${moduleLabel}`);
+        console.log(`  ${chalk.dim('Agents:')}      ${Object.keys(results.agents).length} agents executed`);
+
+        // Agent breakdown
+        for (const [name, agent] of Object.entries(results.agents)) {
+            const statusIcon = agent.status === 'done' ? chalk.hex('#00ff88')('✔') : chalk.red('✘');
+            console.log(`  ${chalk.dim('  ' + name + ':')}  ${statusIcon} ${agent.findingsCount} findings (${(agent.duration / 1000).toFixed(1)}s)`);
+        }
+
+        console.log();
+        const displaySummary = dedupSummary || summary;
+        const dedupStats = results.dedupStats;
+        if (dedupStats && dedupStats.duplicatesRemoved > 0) {
+            console.log(`  ${chalk.dim('Findings:')}    ${displaySummary.total} unique ${chalk.dim(`(from ${dedupStats.rawCount} raw, ${dedupStats.reductionPercent}% deduped)`)}`);
+        } else {
+            console.log(`  ${chalk.dim('Findings:')}    ${summary.total}`);
+        }
+        if (displaySummary.critical > 0) console.log(`  ${chalk.red('  Critical:')}  ${displaySummary.critical}`);
+        if (displaySummary.high > 0) console.log(`  ${chalk.hex('#ff6d00')('  High:')}      ${displaySummary.high}`);
+        if (displaySummary.medium > 0) console.log(`  ${chalk.yellow('  Medium:')}    ${displaySummary.medium}`);
+        if (displaySummary.low > 0) console.log(`  ${chalk.blue('  Low:')}       ${displaySummary.low}`);
+        if (displaySummary.info > 0) console.log(`  ${chalk.gray('  Info:')}      ${displaySummary.info}`);
+
+        // Correlations
+        if (results.correlations?.length > 0) {
+            console.log();
+            console.log(chalk.hex('#ff6d00').bold('  ═══ CORRELATIONS ═══'));
+            for (const c of results.correlations) {
+                console.log(`  ${chalk.hex('#ff6d00')('⚡')} ${c.title}`);
+            }
+        }
+
+        console.log();
+
+        if (summary.critical > 0) {
+            console.log(chalk.red.bold('  ⚠ CRITICAL findings detected — immediate action required!'));
+            if (config.halt_on_critical) process.exit(1);
+        } else if (summary.high > 0) {
+            console.log(chalk.hex('#ff6d00')('  ⚠ HIGH severity findings detected — review recommended.'));
+        } else if (summary.total === 0) {
+            console.log(chalk.hex('#00ff88')('  ✔ No findings at the configured severity threshold. Clean scan!'));
+        }
+
+        console.log();
+    } catch (err) {
+        reportSpinner.fail('Report generation failed: ' + err.message);
+        logger.error('Report generation failed', err);
+        process.exit(1);
+    }
+}
+
+// ═══════════════════════════════════════════════
+// Fix 7: Multi-target URL resolver
+// ═══════════════════════════════════════════════
+
+/**
+ * Resolve target URLs from either a primary URL, a comma-separated list (--targets),
+ * or a file path (one URL per line).
+ */
+function _resolveTargets(primaryUrl, targetsOption) {
+    if (!targetsOption) return [primaryUrl];
+
+    // Check if it looks like a file path
+    if (fs.existsSync(targetsOption)) {
+        const lines = fs.readFileSync(targetsOption, 'utf-8')
+            .split('\n')
+            .map(l => l.trim())
+            .filter(l => l && l.startsWith('http'));
+        return lines.length > 0 ? lines : [primaryUrl];
+    }
+
+    // Comma-separated list
+    const targets = targetsOption.split(',').map(t => t.trim()).filter(t => t.startsWith('http'));
+    return targets.length > 0 ? targets : [primaryUrl];
+}
+
+// ═══════════════════════════════════════════════
+// Commands
+// ═══════════════════════════════════════════════
+
+program
+    .command('scan')
+    .description('Run JAKU scan with selected modules (default: qa + security)')
+    .argument('<url>', 'Target URL to scan')
+    .option('-c, --config <path>', 'Path to jaku.config.json')
+    .option('-o, --output <dir>', 'Output directory for reports')
+    .option('-m, --modules <list>', 'Comma-separated modules to run (qa,security,ai,logic,api)', 'qa,security,ai,logic,api')
+    .option('-s, --severity <level>', 'Minimum severity threshold (critical|high|medium|low)', 'low')
+    .option('--targets <urls-or-file>', 'Comma-separated target URLs or path to a file with one URL per line (multi-target mode)')
+    .option('--json', 'Output JSON report')
+    .option('--html', 'Output HTML report')
+    .option('--max-pages <n>', 'Maximum pages to crawl', '50')
+    .option('--max-depth <n>', 'Maximum crawl depth', '5')
+    .option('--halt-on-critical', 'Abort scan immediately on critical finding')
+    .option('--webhook <url>', 'POST findings to webhook URL on completion')
+    .option('--prod-safe', 'Confirm authorization to scan production targets')
+    .option('--auth-strategy <type>', 'Auth strategy: auto|form|api|cookie (default: auto)')
+    .option('--login-url <url>', 'Login page URL for form-based auth')
+    .option('--username <user>', 'Username/email for authenticated scanning')
+    .option('--password <pass>', 'Password for authenticated scanning')
+    .option('-v, --verbose', 'Enable verbose logging')
+    .action(async (url, options) => {
+        const modules = options.modules.split(',').map(m => m.trim().toLowerCase());
+
+        // Fix 7: Multi-target support — parse --targets flag
+        const targets = _resolveTargets(url, options.targets);
+
+        if (targets.length === 1) {
+            await runScan(targets[0], options, modules);
+        } else {
+            console.log(chalk.hex('#00ff88').bold(`\n  ═══ MULTI-TARGET SCAN: ${targets.length} targets ═══\n`));
+            for (let i = 0; i < targets.length; i++) {
+                const target = targets[i];
+                console.log(chalk.hex('#00ff88').bold(`\n  ── Target ${i + 1}/${targets.length}: ${target} ──\n`));
+                await runScan(target, options, modules).catch(err => {
+                    console.error(chalk.red(`  ✘ Scan failed for ${target}: ${err.message}`));
+                });
+            }
+            console.log(chalk.hex('#00ff88').bold(`\n  ═══ MULTI-TARGET SCAN COMPLETE ═══\n`));
+        }
+    });
+
+program
+    .command('qa')
+    .description('Run Module 01 only: Quality Assurance & Functional Testing')
+    .argument('<url>', 'Target URL to scan')
+    .option('-c, --config <path>', 'Path to jaku.config.json')
+    .option('-o, --output <dir>', 'Output directory for reports')
+    .option('-s, --severity <level>', 'Severity threshold', 'low')
+    .option('--max-pages <n>', 'Maximum pages to crawl', '50')
+    .option('--max-depth <n>', 'Maximum crawl depth', '5')
+    .option('-v, --verbose', 'Enable verbose logging')
+    .action(async (url, options) => {
+        await runScan(url, options, ['qa']);
+    });
+
+program
+    .command('security')
+    .description('Run Module 02 only: Security Vulnerability Scanning')
+    .argument('<url>', 'Target URL to scan')
+    .option('-c, --config <path>', 'Path to jaku.config.json')
+    .option('-o, --output <dir>', 'Output directory for reports')
+    .option('-s, --severity <level>', 'Severity threshold', 'low')
+    .option('--max-pages <n>', 'Maximum pages to crawl', '50')
+    .option('--max-depth <n>', 'Maximum crawl depth', '5')
+    .option('-v, --verbose', 'Enable verbose logging')
+    .action(async (url, options) => {
+        await runScan(url, options, ['security']);
+    });
+
+program
+    .command('ai')
+    .description('Run Module 04 only: Prompt Injection & AI Abuse Detection')
+    .argument('<url>', 'Target URL to scan')
+    .option('-c, --config <path>', 'Path to jaku.config.json')
+    .option('-o, --output <dir>', 'Output directory for reports')
+    .option('-s, --severity <level>', 'Severity threshold', 'low')
+    .option('--max-pages <n>', 'Maximum pages to crawl', '50')
+    .option('--max-depth <n>', 'Maximum crawl depth', '5')
+    .option('-v, --verbose', 'Enable verbose logging')
+    .action(async (url, options) => {
+        await runScan(url, options, ['ai']);
+    });
+
+program
+    .command('logic')
+    .description('Run Module 03 only: Business Logic Validation')
+    .argument('<url>', 'Target URL to scan')
+    .option('-c, --config <path>', 'Path to jaku.config.json')
+    .option('-o, --output <dir>', 'Output directory for reports')
+    .option('-s, --severity <level>', 'Severity threshold', 'low')
+    .option('--max-pages <n>', 'Maximum pages to crawl', '50')
+    .option('--max-depth <n>', 'Maximum crawl depth', '5')
+    .option('-v, --verbose', 'Enable verbose logging')
+    .action(async (url, options) => {
+        await runScan(url, options, ['logic']);
+    });
+
+program
+    .command('api')
+    .description('Run Module 05 only: API & Auth Flow Verification')
+    .argument('<url>', 'Target URL to scan')
+    .option('-c, --config <path>', 'Path to jaku.config.json')
+    .option('-o, --output <dir>', 'Output directory for reports')
+    .option('-s, --severity <level>', 'Severity threshold', 'low')
+    .option('--max-pages <n>', 'Maximum pages to crawl', '50')
+    .option('--max-depth <n>', 'Maximum crawl depth', '5')
+    .option('-v, --verbose', 'Enable verbose logging')
+    .action(async (url, options) => {
+        await runScan(url, options, ['api']);
+    });
+
+program.parse();

package/src/core/accessibility-checker.js

@@ -0,0 +1,171 @@
+import { chromium } from 'playwright';
+import { createFinding } from '../utils/finding.js';
+
+/**
+ * AccessibilityChecker — Checks WCAG 2.2 compliance using axe-core.
+ *
+ * Categories:
+ * - Critical: keyboard trap, missing form labels, missing alt text on interactive elements
+ * - Serious: color contrast, focus visible, duplicate IDs
+ * - Moderate: language attribute, skip navigation, heading order
+ *
+ * Uses axe-core injected via Playwright for accurate real-browser analysis.
+ */
+export class AccessibilityChecker {
+    // axe-core CDN version to inject
+    static AXE_CDN = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.9.1/axe.min.js';
+
+    // Severity mapping from axe-core impact levels
+    static SEVERITY_MAP = {
+        critical: 'critical',
+        serious: 'high',
+        moderate: 'medium',
+        minor: 'low',
+    };
+
+    // Categories to report (filter noise)
+    static INCLUDE_RULES = new Set([
+        'image-alt', 'label', 'label-content-name-mismatch', 'input-button-name',
+        'button-name', 'link-name', 'aria-required-attr', 'aria-valid-attr',
+        'color-contrast', 'color-contrast-enhanced',
+        'keyboard', 'focus-trap', 'focusable-disabled', 'focus-order-semantics',
+        'duplicate-id', 'duplicate-id-active', 'duplicate-id-aria',
+        'html-has-lang', 'html-lang-valid', 'document-title',
+        'heading-order', 'bypass', 'landmark-one-main',
+        'form-field-multiple-labels', 'autocomplete-valid',
+        'scrollable-region-focusable', 'select-name', 'textarea-label',
+    ]);
+
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+
+    async check(surfaceInventory) {
+        const findings = [];
+        const pages = surfaceInventory.pages.filter(p => p.status < 400).slice(0, 15);
+
+        if (pages.length === 0) return findings;
+
+        const browser = await chromium.launch({ headless: true });
+
+        try {
+            for (const pageData of pages) {
+                const results = await this._runAxe(browser, pageData.url);
+                if (!results) continue;
+
+                for (const violation of results) {
+                    // Skip rules not in our inclusion list (reduces noise)
+                    if (!AccessibilityChecker.INCLUDE_RULES.has(violation.id)) continue;
+
+                    const severity = AccessibilityChecker.SEVERITY_MAP[violation.impact] || 'low';
+                    const affectedCount = violation.nodes?.length || 1;
+
+                    findings.push(createFinding({
+                        module: 'qa',
+                        title: `Accessibility (WCAG 2.2): ${violation.help} on ${new URL(pageData.url).pathname}`,
+                        severity,
+                        affected_surface: pageData.url,
+                        description: `${violation.description} This violates WCAG 2.2 success criterion ${violation.helpUrl ? `(see reference)` : violation.id}. ${affectedCount} element${affectedCount > 1 ? 's are' : ' is'} affected on this page.\n\n${violation.help}.`,
+                        reproduction: [
+                            `1. Open ${pageData.url}`,
+                            '2. Run axe-core in DevTools: await axe.run()',
+                            `3. Look for violation: "${violation.id}"`,
+                            `4. Affected selectors: ${(violation.nodes || []).slice(0, 3).map(n => n.target?.[0] || 'unknown').join(', ')}`,
+                        ],
+                        evidence: JSON.stringify({
+                            rule: violation.id,
+                            impact: violation.impact,
+                            affectedCount,
+                            sampleNodes: (violation.nodes || []).slice(0, 2).map(n => ({
+                                target: n.target,
+                                html: n.html?.substring(0, 150),
+                                failureSummary: n.failureSummary,
+                            })),
+                        }, null, 2).substring(0, 800),
+                        remediation: violation.helpUrl
+                            ? `See axe-core guidance: ${violation.helpUrl}`
+                            : this._getGenericRemediation(violation.id),
+                        references: [
+                            'https://www.w3.org/WAI/WCAG22/quickref/',
+                            violation.helpUrl || 'https://dequeuniversity.com/rules/axe/',
+                        ],
+                    }));
+                }
+
+                this.logger?.debug?.(`Accessibility: ${pageData.url} — ${results.length} violations`);
+            }
+        } finally {
+            await browser.close();
+        }
+
+        this.logger?.info?.(`Accessibility Checker: found ${findings.length} issues`);
+        return findings;
+    }
+
+    async _runAxe(browser, url) {
+        const page = await browser.newPage({
+            viewport: { width: 1440, height: 900 },
+        });
+
+        try {
+            await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 });
+            await page.waitForTimeout(1500);
+
+            // Inject axe-core
+            await page.addScriptTag({ url: AccessibilityChecker.AXE_CDN }).catch(async () => {
+                // Fallback: try local CDN or skip
+                const axeSource = await this._fetchAxeCore().catch(() => null);
+                if (axeSource) await page.addScriptTag({ content: axeSource });
+            });
+
+            await page.waitForTimeout(500);
+
+            // Run axe
+            const results = await page.evaluate(async () => {
+                if (typeof axe === 'undefined') return null;
+                const result = await axe.run(document, {
+                    runOnly: {
+                        type: 'tag',
+                        values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'],
+                    },
+                });
+                return result.violations;
+            });
+
+            return results;
+        } catch (err) {
+            this.logger?.debug?.(`Axe run failed for ${url}: ${err.message}`);
+            return null;
+        } finally {
+            await page.close();
+        }
+    }
+
+    async _fetchAxeCore() {
+        try {
+            const res = await fetch(AccessibilityChecker.AXE_CDN);
+            return await res.text();
+        } catch {
+            return null;
+        }
+    }
+
+    _getGenericRemediation(ruleId) {
+        const remediations = {
+            'image-alt': 'Add descriptive alt attributes to all <img> elements. Use alt="" for decorative images.',
+            'label': 'Associate every form input with a visible <label> element using for/id pairing or aria-label.',
+            'color-contrast': 'Ensure text has a contrast ratio of at least 4.5:1 (3:1 for large text) against its background. Use a contrast checker tool.',
+            'keyboard': 'All interactive elements must be operable via keyboard alone. Test Tab, Enter, Space, Arrow keys.',
+            'focus-trap': 'Never trap keyboard focus permanently in a component. Modal dialogs should trap focus but provide an escape path (Escape key, close button).',
+            'duplicate-id': 'Each id attribute must be unique within the document. Duplicate IDs break ARIA relationships and cause accessibility failures.',
+            'html-has-lang': 'Add a lang attribute to the <html> element to identify the page language (e.g., <html lang="en">).',
+            'document-title': 'Every page must have a descriptive, unique <title> element.',
+            'heading-order': 'Heading levels must not be skipped (e.g., h1 → h3 without h2). Maintain proper hierarchy.',
+            'bypass': 'Provide a "Skip to main content" link as the first focusable element to allow keyboard users to bypass navigation.',
+        };
+        return remediations[ruleId] || 'Follow the WCAG 2.2 guidelines at https://www.w3.org/WAI/WCAG22/quickref/';
+    }
+}
+
+export default AccessibilityChecker;