create-backlist 10.0.3 → 10.0.5

package/bin/qa.js

@@ -1,180 +1,131 @@
 #!/usr/bin/env node
-
-// ═══════════════════════════════════════════════════════════════════════════
-//  Backlist QA CLI — qa.js  v10.0
-//  Standalone QA entry point: `node bin/qa.js [mode] [--flags]`
-//  Copyright (c) W.A.H.ISHAN — MIT License
-//
-//  NEW in v10.0:
-//  ✦ --url=<localhost> --prod=<production> flags for HTTP-based QA
-//  ✦ URL QA mode — probe real running URLs (no browser required)
-//  ✦ HTTP security header scanner, SEO checker, a11y basics
-//  ✦ Route crawler & benchmark per endpoint
-//  ✦ Dual-URL diff report (localhost vs production)
-//  ✦ All v9.0 features retained (manual, auto, history, post-gen)
-// ═══════════════════════════════════════════════════════════════════════════
-
+// ── Backlist Enterprise QA CLI — qa.js v12.0 ─────────────────────────────
 import * as p    from '@clack/prompts';
 import chalk     from 'chalk';
 import fs        from 'fs-extra';
 import path      from 'node:path';
+import { URL }   from 'node:url';
 import {
-  runManualQA,
   runAutomatedQA,
   runUrlQA,
+  runManualQA,
   viewQAHistory,
   initQASystem,
   autoRunPostGeneration,
+  VERSION,
 } from '../src/qa/qa-engine.js';
 
-// ── Version ───────────────────────────────────────────────────────────────
-const VERSION = '10.0.0';
-
-// ── CLI flags ─────────────────────────────────────────────────────────────
-const argv     = process.argv.slice(2);
-const flags    = new Set(argv.filter(a => a.startsWith('--')));
-const posArgs  = argv.filter(a => !a.startsWith('--'));
-
-const isContinuous = flags.has('--continuous') || flags.has('--watch') || flags.has('-w');
-const isCI         = process.env.QA_CI === '1' || flags.has('--ci');
-const noColor      = flags.has('--no-color') || process.env.NO_COLOR;
-const isPostGen    = flags.has('--post-gen');
-const scope        = argv.find(a => a.startsWith('--scope='))?.split('=')[1] ?? 'all';
+const VERSION_DISPLAY = `12.0.0`;
+const argv    = process.argv.slice(2);
+const flags   = new Set(argv.filter(a => a.startsWith('--')));
+const posArgs = argv.filter(a => !a.startsWith('--'));
+const isCI    = process.env.QA_CI === '1' || flags.has('--ci');
+const modeArg = posArgs[0]?.toLowerCase();
 
-// v10.0: URL flags
-const localUrlFlag = argv.find(a => a.startsWith('--url='))?.split('=').slice(1).join('=') ?? '';
-const prodUrlFlag  = argv.find(a => a.startsWith('--prod='))?.split('=').slice(1).join('=') ?? '';
+const getFlag = (name) => argv.find(a => a.startsWith(`--${name}=`))?.split('=').slice(1).join('=') ?? '';
 
-if (noColor) chalk.level = 0;
-
-// ── Graceful shutdown ─────────────────────────────────────────────────────
 let shuttingDown = false;
+process.on('SIGINT',  () => { if (!shuttingDown) { shuttingDown = true; process.stdout.write('\x1b[?25h'); console.log(chalk.gray('\n  Shutting down...')); process.exit(0); } });
+process.on('SIGTERM', () => { if (!shuttingDown) { shuttingDown = true; process.exit(0); } });
 
-function registerShutdownHandlers() {
-  const shutdown = (signal) => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    process.stdout.write('\x1b[?25h');
-    console.log('\n' + chalk.gray(`  ${signal} received — shutting down gracefully…`));
-    p.cancel('QA session ended.');
-    process.exit(0);
-  };
-  process.on('SIGINT',  () => shutdown('SIGINT'));
-  process.on('SIGTERM', () => shutdown('SIGTERM'));
-}
-
-// ── Banner ────────────────────────────────────────────────────────────────
-function printQABanner() {
-  if (isCI) return;
-
-  const c1  = chalk.hex('#00F5FF');
-  const c2  = chalk.hex('#BF40FF');
-  const c3  = chalk.hex('#FF6B6B');
-  const c4  = chalk.hex('#00FF9F');
-  const dim = chalk.gray;
-
+function printBanner() {
+  const c1 = chalk.hex('#00F5FF');
+  const c2 = chalk.hex('#BF40FF');
   console.log('');
-  console.log(c1('  ╔══════════════════════════════════════════════════════════════╗'));
-  console.log(c1('  ║') + c2.bold('   ____    ___    ________ __    ____ ___________             ') + c1('║'));
-  console.log(c1('  ║') + c2.bold('  / __ )  /   |  / ____/ //_/   / /  /  _/ ___/_             ') + c1('║'));
-  console.log(c1('  ║') + c2.bold(' / __  | / /| | / /   / ,<     / /   / / \\__ \\              ') + c1('║'));
-  console.log(c1('  ║') + c2.bold('/ /_/ / / ___ |/ /___/ /| |   / /____/ / ___/ /              ') + c1('║'));
-  console.log(c1('  ║') + c2.bold('/_____/ /_/  |_|\\____/_/ |_|  /_____/___//____/             ') + c1('║'));
-  console.log(c1('  ║') + '                                                              ' + c1('║'));
-  console.log(c1('  ║') + c3.bold(`      🧪 Live QA Platform v${VERSION} — HTTP + File + E2E       `) + c1('║'));
-  console.log(c1('  ║') + dim('      URL Probe · Security · SEO · A11y · Performance · CI      ') + c1('║'));
-  console.log(c1('  ╚══════════════════════════════════════════════════════════════╝'));
+  console.log(c1('  ╔═══════════════════════════════════════════════════════════╗'));
+  console.log(c1('  ║') + c2.bold('   BACKLIST ENTERPRISE AI QA PLATFORM v12.0             ') + c1('║'));
+  console.log(c1('  ║') + chalk.gray('   Real Browser Testing · Zero Fake Data · AI Classifier ') + c1('║'));
+  console.log(c1('  ╚═══════════════════════════════════════════════════════════╝'));
   console.log('');
-
-  const mem    = process.memoryUsage();
-  const heapMB = (mem.heapUsed / 1024 / 1024).toFixed(0);
-
-  console.log(
-    dim('  ') +
-    c4('◉ LIVE') + dim(' │ ') +
-    dim('Node ')  + chalk.white(process.version)  + dim(' │ ') +
-    dim('Heap ')  + chalk.white(heapMB + 'MB')     + dim(' │ ') +
-    dim('Scope ') + chalk.white(scope)              + dim(' │ ') +
-    dim('Mode ')  + chalk.white(isContinuous ? 'watch' : 'single-run') + dim(' │ ') +
-    dim('v')      + chalk.white(VERSION)
-  );
-
-  if (localUrlFlag) console.log(dim('  URL   → ') + chalk.white(localUrlFlag));
-  if (prodUrlFlag)  console.log(dim('  Prod  → ') + chalk.white(prodUrlFlag));
-
-  console.log(dim('  Flags: --url=<localhost>  --prod=<production>  --continuous (-w)'));
-  console.log(dim('         --ci  --scope=<all|backend|frontend|security>  --post-gen  --no-color'));
-  console.log(dim('  CI:    QA_CI=1 node bin/qa.js auto --url=http://localhost:3000'));
-  console.log(dim('  ─────────────────────────────────────────────────────────────'));
+  console.log(chalk.gray(
+    `  Node ${process.version} · ` +
+    `Heap ${(process.memoryUsage().heapUsed/1024/1024).toFixed(0)}MB · ` +
+    `v${VERSION_DISPLAY}`
+  ));
+  console.log(chalk.gray('  Powered by Playwright · axe-core · Real HTTP probes'));
   console.log('');
 }
 
-// ── System health check ───────────────────────────────────────────────────
-async function systemHealthCheck() {
-  const checks = [
-    { name: 'Node.js ≥ 18', fn: () => {
-      const maj = parseInt(process.version.replace('v','').split('.')[0]);
-      if (maj < 18) throw new Error(`Node.js ${process.version} — requires v18+`);
-    }},
-    { name: 'QA directories', fn: async () => {
-      await fs.ensureDir(path.join(process.cwd(), '.backlist', 'qa', 'reports'));
-    }},
-  ];
-
-  const spin = p.spinner();
-  spin.start('System health check…');
-  for (const check of checks) {
-    try { await check.fn(); }
-    catch (err) { spin.stop(chalk.red(`✗ ${check.name}: ${err.message}`)); process.exit(1); }
-  }
-  spin.stop(chalk.green(`✓ System healthy — QA v${VERSION} ready`));
+function validateUrl(u) {
+  if (!u) return true; // optional
+  try { new URL(u); return true; }
+  catch { return false; }
 }
 
-// ── Main ──────────────────────────────────────────────────────────────────
-async function main() {
-  printQABanner();
-  registerShutdownHandlers();
+async function collectUrls() {
+  console.log(chalk.hex('#00F5FF').bold('\n  ── Target URLs ──────────────────────────────────────'));
+  console.log(chalk.gray('  Provide at least one URL. The QA engine will automatically'));
+  console.log(chalk.gray('  crawl routes, discover APIs, and test real interactions.\n'));
+
+  const localUrl = await p.text({
+    message    : 'Localhost URL:',
+    placeholder: 'http://localhost:3000',
+    validate   : (v) => {
+      if (!v?.trim()) return undefined; // optional
+      if (!validateUrl(v.trim())) return '❌ Invalid URL';
+    },
+  });
+  if (p.isCancel(localUrl)) { p.cancel('Cancelled.'); process.exit(0); }
+
+  const stagingUrl = await p.text({
+    message    : 'Staging URL (blank to skip):',
+    placeholder: 'https://staging.yoursite.com',
+    validate   : (v) => {
+      if (!v?.trim()) return undefined;
+      if (!validateUrl(v.trim())) return '❌ Invalid URL';
+    },
+  });
+  if (p.isCancel(stagingUrl)) { p.cancel('Cancelled.'); process.exit(0); }
+
+  const prodUrl = await p.text({
+    message    : 'Production URL (blank to skip):',
+    placeholder: 'https://yoursite.com',
+    validate   : (v) => {
+      if (!v?.trim()) return undefined;
+      if (!validateUrl(v.trim())) return '❌ Invalid URL';
+    },
+  });
+  if (p.isCancel(prodUrl)) { p.cancel('Cancelled.'); process.exit(0); }
 
-  await initQASystem();
-  await systemHealthCheck();
-
-  // ── Post-generation auto-run ─────────────────────────────────────────
-  if (isPostGen) {
-    const projectDir  = posArgs[0] ? path.resolve(posArgs[0]) : process.cwd();
-    const projectName = path.basename(projectDir);
-    await autoRunPostGeneration({ projectDir, projectName });
-    process.exit(0);
+  const urls = {
+    localUrl  : String(localUrl   || '').trim() || undefined,
+    stagingUrl: String(stagingUrl || '').trim() || undefined,
+    prodUrl   : String(prodUrl    || '').trim() || undefined,
+  };
+
+  if (!urls.localUrl && !urls.stagingUrl && !urls.prodUrl) {
+    console.log(chalk.red('  ❌ At least one URL is required for real testing.'));
+    process.exit(1);
   }
 
-  // ── CI / positional arg mode ─────────────────────────────────────────
-  const modeArg = posArgs[0]?.toLowerCase();
+  return urls;
+}
 
+async function main() {
+  printBanner();
+  await initQASystem();
+
+  // ── CI / flag mode ──────────────────────────────────────────────────
   if (isCI || modeArg) {
-    const mode = modeArg ?? 'auto';
-    if (!isCI) console.log(chalk.gray(`  Mode: ${mode}${isContinuous ? ' (continuous)' : ''}${localUrlFlag ? ` → ${localUrlFlag}` : ''}\n`));
+    const urls = {
+      localUrl  : getFlag('url')     || getFlag('local')   || undefined,
+      stagingUrl: getFlag('staging') || undefined,
+      prodUrl   : getFlag('prod')    || undefined,
+    };
+
+    const mode = modeArg || 'auto';
 
     switch (mode) {
-      case 'manual':
-        await runManualQA();
-        break;
-      case 'auto':
-        await runAutomatedQA({
-          continuous: isContinuous,
-          localUrl  : localUrlFlag || undefined,
-          prodUrl   : prodUrlFlag  || undefined,
-        });
-        break;
       case 'url':
-        if (!localUrlFlag && !prodUrlFlag) {
-          console.error(chalk.red('  --url or --prod flag required for url mode.'));
-          console.error(chalk.gray('  Example: node bin/qa.js url --url=http://localhost:3000 --prod=https://yoursite.com'));
-          process.exit(1);
-        }
-        await runUrlQA({
-          localUrl: localUrlFlag || undefined,
-          prodUrl : prodUrlFlag  || undefined,
-        });
+      case 'scan': {
+        const result = await runUrlQA(urls);
+        if (isCI) process.exit(result?.session.getSummary().failed > 0 ? 1 : 0);
+        break;
+      }
+      case 'auto': {
+        await runAutomatedQA({ ...urls, continuous: flags.has('--continuous') || flags.has('-w') });
         break;
+      }
       case 'history':
         await viewQAHistory();
         break;
@@ -182,69 +133,73 @@ async function main() {
         await autoRunPostGeneration();
         break;
       default:
-        console.error(chalk.red(`Unknown mode: ${mode}. Use: manual | auto | url | history | post-gen`));
+        console.error(chalk.red(`Unknown mode: ${mode}. Use: scan | auto | history | post-gen`));
         process.exit(1);
     }
-
-    // CI exit code: non-zero if any failures
-    if (isCI) process.exit(0);
     return;
   }
 
-  // ── Interactive mode ─────────────────────────────────────────────────
-  p.intro(chalk.hex('#00F5FF').bold(` Backlist QA Platform v${VERSION} — HTTP + File + E2E Testing `));
+  // ── Interactive mode ────────────────────────────────────────────────
+  p.intro(chalk.hex('#00F5FF').bold(' Backlist Enterprise QA Platform v12.0 '));
 
   const mode = await p.select({
     message: 'Select QA mode:',
     options: [
-      { value: 'url',      label: '🌐 URL-Based QA Scan',          hint: 'Probe localhost + production — HTTP, security, SEO, a11y' },
-      { value: 'manual',   label: '🧪 Manual QA Testing',          hint: 'Interactive test creation, custom cases, bug logging' },
-      { value: 'auto',     label: '🤖 Full Automated Scan',         hint: 'E2E, security, auth, DB, performance — all modules' },
-      { value: 'live',     label: '⚡ Live Continuous Monitoring',  hint: 'Reruns every 30s — Ctrl+C to stop' },
-      { value: 'post-gen', label: '🚀 Post-Generation Validation',  hint: 'Validate a freshly generated backend project' },
-      { value: 'history',  label: '📜 View QA History',             hint: 'Browse past runs, compare pass rates' },
+      { value: 'full-scan',  label: '🔬 Full Enterprise Scan',   hint: 'Browser + API + Security + Perf + A11y + SEO — real data only' },
+      { value: 'quick-scan', label: '⚡ Quick Scan',              hint: 'Fast connectivity + security + SEO check' },
+      { value: 'manual',     label: '🧪 Manual QA',              hint: 'Choose specific scan types interactively'  },
+      { value: 'continuous', label: '🔄 Continuous Monitoring',   hint: 'Re-runs every 60s — Ctrl+C to stop'       },
+      { value: 'post-gen',   label: '🚀 Post-Gen Validation',     hint: 'Validate freshly generated backend'       },
+      { value: 'history',    label: '📜 View History',            hint: 'Browse past real QA runs'                 },
     ],
   });
-  if (p.isCancel(mode)) { p.cancel('QA session cancelled.'); process.exit(0); }
+  if (p.isCancel(mode)) { p.cancel('Cancelled.'); process.exit(0); }
+
+  if (mode === 'history') { await viewQAHistory(); return; }
+  if (mode === 'post-gen') { await autoRunPostGeneration(); return; }
+
+  // All scan modes need URLs
+  const urls = await collectUrls();
+
+  console.log('');
+  console.log(chalk.hex('#BF40FF').bold('  ── QA Configuration ───────────────────────────────'));
+  if (urls.localUrl)   console.log(chalk.gray(`  Localhost:   ${urls.localUrl}`));
+  if (urls.stagingUrl) console.log(chalk.gray(`  Staging:     ${urls.stagingUrl}`));
+  if (urls.prodUrl)    console.log(chalk.gray(`  Production:  ${urls.prodUrl}`));
+  console.log('');
+
+  const confirm = await p.confirm({
+    message     : 'Start real browser-based QA scan?',
+    initialValue: true,
+  });
+  if (p.isCancel(confirm) || !confirm) { p.cancel('Aborted.'); process.exit(0); }
 
   switch (mode) {
-    case 'url': {
-      const localUrl = localUrlFlag || String(
-        await p.text({ message: 'Localhost URL:', placeholder: 'http://localhost:3000', defaultValue: 'http://localhost:3000' })
-      );
-      const prodUrl  = prodUrlFlag  || String(
-        await p.text({ message: 'Production URL (leave blank to skip):', placeholder: 'https://yoursite.com' }) || ''
-      );
-      if (p.isCancel(localUrl)) { p.cancel('Cancelled.'); process.exit(0); }
-      await runUrlQA({ localUrl: localUrl.trim() || undefined, prodUrl: prodUrl.trim() || undefined });
+    case 'full-scan':
+    case 'quick-scan': {
+      const result = await runUrlQA(urls);
+      if (result?.htmlPath) {
+        p.outro(chalk.hex('#00F5FF').bold('✓ Scan complete — real runtime data only'));
+        console.log(chalk.gray(`  📄 HTML Report: ${result.htmlPath}`));
+        console.log(chalk.gray(`  📋 JSON Report: ${result.jsonPath}`));
+      }
       break;
     }
     case 'manual':
       await runManualQA();
       break;
-    case 'auto':
-      await runAutomatedQA({ continuous: false, localUrl: localUrlFlag || undefined, prodUrl: prodUrlFlag || undefined });
-      break;
-    case 'live':
-      await runAutomatedQA({ continuous: true, localUrl: localUrlFlag || undefined, prodUrl: prodUrlFlag || undefined });
-      break;
-    case 'post-gen':
-      await autoRunPostGeneration();
+    case 'continuous':
+      await runAutomatedQA({ ...urls, continuous: true });
       break;
-    case 'history':
-      await viewQAHistory();
-      p.outro(chalk.hex('#00F5FF').bold('History viewed.'));
-      break;
-    default:
-      p.cancel('Unknown mode.');
-      process.exit(1);
   }
 }
 
 main().catch(err => {
   if (shuttingDown) return;
   process.stdout.write('\x1b[?25h');
-  console.error(chalk.red.bold(`\n  QA Fatal: ${err.message || err}`));
-  if (err.stack && !isCI) console.error(chalk.gray(err.stack.split('\n').slice(1, 5).join('\n')));
+  console.error(chalk.red.bold(`\n  Fatal: ${err.message || err}`));
+  if (err.stack && !isCI) {
+    console.error(chalk.gray(err.stack.split('\n').filter(l => !l.includes('node_modules')).slice(0, 5).join('\n')));
+  }
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-backlist",
-  "version": "10.0.3",
+  "version": "10.0.5",
   "description": "An advanced, multi-language backend generator based on frontend analysis. Smart Freemium SaaS CLI with Live QA.",
   "type": "module",
   "bin": {
@@ -12,9 +12,13 @@
     "src",
     "AiModuls"
   ],
+  
   "scripts": {
     "start"       : "node bin/index.js",
     "qa"          : "node bin/qa.js",
+      "qa:scan"    : "node bin/qa.js scan --url=http://localhost:3000",
+        
+    "qa:install" : "npx playwright install chromium",
     "qa:auto"     : "node bin/qa.js auto",
     "qa:live"     : "node bin/qa.js auto --continuous",
     "qa:manual"   : "node bin/qa.js manual",
@@ -26,6 +30,7 @@
   "author": "W.A.H.ISHAN",
   "license": "MIT",
   "dependencies": {
+     "playwright": "^1.45.0",
     "@babel/parser"   : "^7.22.7",
     "@babel/traverse" : "^7.22.8",
     "@clack/prompts"  : "^0.7.0",

package/src/qa/analyzers/accessibility.js

@@ -0,0 +1,199 @@
+// Accessibility checker with HTTP fallback
+import { getBrowserLaunchOptions } from '../browser/installer.js';
+
+export class AccessibilityChecker {
+  #playwright;
+  #session;
+
+  constructor(playwright, session) {
+    this.#playwright = playwright;
+    this.#session    = session;
+  }
+
+  async check(url) {
+    const launchOpts = await getBrowserLaunchOptions();
+
+    if (!launchOpts.available) {
+      return this.#httpFallback(url);
+    }
+
+    let playwright;
+    try { playwright = await import('playwright'); }
+    catch { return this.#httpFallback(url); }
+
+    const { executablePath, headless, args } = launchOpts;
+    let browser;
+
+    try {
+      browser = await playwright.chromium.launch({ executablePath, headless, args });
+    } catch {
+      return this.#httpFallback(url);
+    }
+
+    const context = await browser.newContext({ ignoreHTTPSErrors: true });
+    const page    = await context.newPage();
+
+    try {
+      await page.goto(url, { waitUntil: 'networkidle', timeout: 20_000 });
+
+      await page.addScriptTag({
+        url: 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.9.1/axe.min.js',
+      });
+
+      const axeResults = await page.evaluate(async () => {
+        return await window.axe.run(document, {
+          runOnly: { type: 'tag', values: ['wcag2a','wcag2aa','wcag21aa','best-practice'] },
+        });
+      });
+
+      const violations = axeResults.violations.map(v => ({
+        id         : v.id,
+        description: v.description,
+        help       : v.help,
+        helpUrl    : v.helpUrl,
+        impact     : v.impact,
+        tags       : v.tags,
+        category   : v.tags.find(t => t.startsWith('wcag')) || 'best-practice',
+        nodes      : v.nodes.length,
+        affectedNodes: v.nodes.slice(0, 3).map(n => ({ html: n.html, target: n.target, message: n.failureSummary })),
+      }));
+
+      const passes = axeResults.passes.map(p => ({
+        id: p.id, description: p.description, nodes: p.nodes.length,
+      }));
+
+      return {
+        pass      : violations.length === 0,
+        violations, passes,
+        incomplete: axeResults.incomplete.map(i => ({ id: i.id, description: i.description, nodes: i.nodes.length })),
+        score     : passes.length > 0 ? Math.round((passes.length / (passes.length + violations.length)) * 100) : 0,
+        url, mode : 'browser-axe',
+      };
+
+    } catch (err) {
+      return { pass: false, violations: [], passes: [], incomplete: [], error: err.message, url, mode: 'browser-error' };
+    } finally {
+      await page.close().catch(() => {});
+      await context.close().catch(() => {});
+      await browser.close().catch(() => {});
+    }
+  }
+
+  // HTTP fallback — parses raw HTML for common a11y issues
+  async #httpFallback(url) {
+    try {
+      const controller = new AbortController();
+      const timer      = setTimeout(() => controller.abort(), 12_000);
+      const res        = await fetch(url, { signal: controller.signal, redirect: 'follow' });
+      clearTimeout(timer);
+
+      if (!res.ok) {
+        return { pass: false, violations: [], passes: [], url, mode: 'http-fallback', error: `HTTP ${res.status}` };
+      }
+
+      const html       = await res.text();
+      const violations = [];
+      const passes     = [];
+
+      // Real HTML analysis checks
+      const checks = [
+        {
+          id        : 'html-lang',
+          desc      : 'HTML element must have a lang attribute',
+          help      : 'Ensures every HTML document has a lang attribute',
+          impact    : 'serious',
+          test      : () => !/<html[^>]+lang=["'][^"']+["']/i.test(html),
+          passMsg   : 'HTML lang attribute present',
+        },
+        {
+          id        : 'img-alt',
+          desc      : 'Images must have alternate text',
+          help      : 'Ensures <img> elements have alternate text or a role of none/presentation',
+          impact    : 'critical',
+          test      : () => /<img(?![^>]*\balt=)[^>]*>/i.test(html),
+          passMsg   : 'All images have alt attributes',
+        },
+        {
+          id        : 'document-title',
+          desc      : 'Documents must have <title>',
+          help      : 'Ensures every HTML document has a non-empty title element',
+          impact    : 'serious',
+          test      : () => !/<title[^>]*>[^<]+<\/title>/i.test(html),
+          passMsg   : 'Document has a title',
+        },
+        {
+          id        : 'viewport',
+          desc      : 'Zoom and scaling must not be disabled',
+          help      : 'Ensures the viewport meta does not disable text scaling',
+          impact    : 'critical',
+          test      : () => /user-scalable=no|maximum-scale=1/i.test(html),
+          passMsg   : 'Viewport allows scaling',
+        },
+        {
+          id        : 'region',
+          desc      : 'Page should have a main landmark',
+          help      : 'Ensures the page has a <main> element',
+          impact    : 'moderate',
+          test      : () => !/<main[^>]*>/i.test(html),
+          passMsg   : 'Main landmark found',
+        },
+        {
+          id        : 'heading-order',
+          desc      : 'Heading levels should not be skipped',
+          help      : 'Ensures the order of headings is semantically correct',
+          impact    : 'moderate',
+          test      : () => !/<h1[^>]*>/i.test(html),
+          passMsg   : 'H1 heading present',
+        },
+        {
+          id        : 'label',
+          desc      : 'Form elements must have labels',
+          help      : 'Ensures every form element has a label',
+          impact    : 'critical',
+          test      : () => /<input(?![^>]*(?:aria-label|aria-labelledby|id=))[^>]*type=(?!"hidden")[^>]*>/i.test(html),
+          passMsg   : 'Form inputs appear to have labels',
+        },
+        {
+          id        : 'link-name',
+          desc      : 'Links must have discernible text',
+          help      : 'Ensures links have discernible text',
+          impact    : 'serious',
+          test      : () => /<a[^>]*>\s*<\/a>/i.test(html),
+          passMsg   : 'Links appear to have text content',
+        },
+      ];
+
+      for (const check of checks) {
+        if (check.test()) {
+          violations.push({
+            id         : check.id,
+            description: check.desc,
+            help       : check.help,
+            impact     : check.impact,
+            tags       : ['wcag2a'],
+            category   : 'wcag2a',
+            nodes      : 1,
+            affectedNodes: [],
+            helpUrl    : `https://dequeuniversity.com/rules/axe/4.9/${check.id}`,
+          });
+        } else {
+          passes.push({ id: check.id, description: check.passMsg, nodes: 1 });
+        }
+      }
+
+      const score = passes.length > 0
+        ? Math.round((passes.length / (passes.length + violations.length)) * 100)
+        : 0;
+
+      return {
+        pass: violations.length === 0,
+        violations, passes, incomplete: [],
+        score, url, mode: 'http-html-analysis',
+        note: 'Full axe-core WCAG scan requires Playwright browser — run: npx playwright install chromium',
+      };
+
+    } catch (err) {
+      return { pass: false, violations: [], passes: [], url, mode: 'http-fallback', error: err.message };
+    }
+  }
+}