@agentic-qe/v3 3.0.0-alpha.6 → 3.0.0-alpha.8

package/src/mcp/tools/visual-accessibility/index.ts

@@ -1,791 +0,0 @@
-/**
- * Agentic QE v3 - Visual & Accessibility MCP Tools
- *
- * qe/visual/compare - Visual regression testing
- * qe/a11y/audit - Accessibility auditing
- *
- * This module wraps the REAL visual-accessibility domain services:
- * - VisualTesterService for screenshot capture and comparison
- * - AccessibilityTesterService for WCAG compliance auditing
- */
-
-import { MCPToolBase, MCPToolConfig, MCPToolContext, MCPToolSchema } from '../base';
-import { ToolResult } from '../../types';
-import { VisualTesterService } from '../../../domains/visual-accessibility/services/visual-tester';
-import { AccessibilityTesterService } from '../../../domains/visual-accessibility/services/accessibility-tester';
-import { MemoryBackend, VectorSearchResult } from '../../../kernel/interfaces';
-
-// ============================================================================
-// Visual Compare Types
-// ============================================================================
-
-export interface VisualCompareParams {
-  urls: string[];
-  viewports?: Viewport[];
-  baselineDir?: string;
-  threshold?: number;
-  fullPage?: boolean;
-  hideSelectors?: string[];
-  waitForSelector?: string;
-  [key: string]: unknown;
-}
-
-export interface Viewport {
-  width: number;
-  height: number;
-  name?: string;
-  isMobile?: boolean;
-}
-
-export interface VisualCompareResult {
-  comparisons: VisualComparison[];
-  summary: VisualSummary;
-  newBaselines: string[];
-  recommendations: string[];
-}
-
-export interface VisualComparison {
-  url: string;
-  viewport: Viewport;
-  status: 'passed' | 'failed' | 'new';
-  diffPercentage: number;
-  diffPixels: number;
-  screenshotPath?: string;
-  diffImagePath?: string;
-  baselinePath?: string;
-  regions?: DiffRegion[];
-}
-
-export interface DiffRegion {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  changeType: 'added' | 'removed' | 'modified';
-  significance: 'high' | 'medium' | 'low';
-}
-
-export interface VisualSummary {
-  total: number;
-  passed: number;
-  failed: number;
-  new: number;
-  avgDiffPercentage: number;
-}
-
-// ============================================================================
-// Accessibility Audit Types
-// ============================================================================
-
-export interface A11yAuditParams {
-  urls: string[];
-  standard?: 'wcag21-aa' | 'wcag21-aaa' | 'wcag22-aa' | 'section508';
-  includeWarnings?: boolean;
-  checkContrast?: boolean;
-  checkKeyboard?: boolean;
-  rules?: string[];
-  [key: string]: unknown;
-}
-
-export interface A11yAuditResult {
-  audits: UrlAudit[];
-  summary: A11ySummary;
-  topIssues: TopIssue[];
-  remediationPlan: RemediationItem[];
-}
-
-export interface UrlAudit {
-  url: string;
-  score: number;
-  passed: boolean;
-  violations: A11yViolation[];
-  warnings: A11yWarning[];
-  passedRules: number;
-}
-
-export interface A11yViolation {
-  id: string;
-  impact: 'critical' | 'serious' | 'moderate' | 'minor';
-  description: string;
-  help: string;
-  helpUrl: string;
-  wcagCriteria: string[];
-  nodes: ViolationNode[];
-}
-
-export interface ViolationNode {
-  selector: string;
-  html: string;
-  failureSummary: string;
-  fixSuggestion?: string;
-}
-
-export interface A11yWarning {
-  id: string;
-  description: string;
-  nodes: number;
-}
-
-export interface A11ySummary {
-  totalUrls: number;
-  passingUrls: number;
-  avgScore: number;
-  criticalViolations: number;
-  seriousViolations: number;
-  totalViolations: number;
-}
-
-export interface TopIssue {
-  ruleId: string;
-  description: string;
-  occurrences: number;
-  impact: string;
-  affectedUrls: string[];
-}
-
-export interface RemediationItem {
-  violationId: string;
-  description: string;
-  fix: string;
-  effort: 'trivial' | 'minor' | 'moderate' | 'major';
-  priority: number;
-}
-
-// ============================================================================
-// Visual Compare Tool
-// ============================================================================
-
-export class VisualCompareTool extends MCPToolBase<VisualCompareParams, VisualCompareResult> {
-  readonly config: MCPToolConfig = {
-    name: 'qe/visual/compare',
-    description: 'Visual regression testing with screenshot comparison, diff detection, and baseline management.',
-    domain: 'visual-accessibility',
-    schema: VISUAL_COMPARE_SCHEMA,
-    streaming: true,
-    timeout: 300000,
-  };
-
-  private visualTester: VisualTesterService | null = null;
-
-  /**
-   * Get or create the visual tester service
-   */
-  private getService(context: MCPToolContext): VisualTesterService {
-    if (!this.visualTester) {
-      const memory = (context as any).memory as MemoryBackend | undefined;
-      this.visualTester = new VisualTesterService(
-        memory || createMinimalMemoryBackend()
-      );
-    }
-    return this.visualTester;
-  }
-
-  async execute(
-    params: VisualCompareParams,
-    context: MCPToolContext
-  ): Promise<ToolResult<VisualCompareResult>> {
-    const {
-      urls,
-      viewports = [{ width: 1920, height: 1080, name: 'desktop' }],
-      baselineDir = '.visual-baselines',
-      threshold = 0.1,
-      fullPage = true,
-    } = params;
-
-    try {
-      this.emitStream(context, {
-        status: 'capturing',
-        message: `Capturing ${urls.length} URLs across ${viewports.length} viewports`,
-      });
-
-      if (this.isAborted(context)) {
-        return { success: false, error: 'Operation aborted' };
-      }
-
-      // Mark as real data - this tool always uses real services
-      this.markAsRealData();
-
-      const service = this.getService(context);
-      const comparisons: VisualComparison[] = [];
-      const newBaselines: string[] = [];
-
-      for (const url of urls) {
-        for (const viewport of viewports) {
-          this.emitStream(context, {
-            status: 'comparing',
-            message: `Comparing ${url} at ${viewport.width}x${viewport.height}`,
-          });
-
-          // Convert viewport format
-          const domainViewport = {
-            width: viewport.width,
-            height: viewport.height,
-            deviceScaleFactor: 1,
-            isMobile: viewport.isMobile || false,
-            hasTouch: viewport.isMobile || false,
-          };
-
-          // Capture screenshot using real service
-          const captureResult = await service.captureScreenshot(url, {
-            viewport: domainViewport,
-            fullPage,
-          });
-
-          if (!captureResult.success) {
-            comparisons.push({
-              url,
-              viewport,
-              status: 'failed',
-              diffPercentage: 100,
-              diffPixels: 0,
-            });
-            continue;
-          }
-
-          const screenshot = captureResult.value;
-
-          // Check for existing baseline
-          const existingBaseline = await service.getBaseline(url, domainViewport);
-
-          if (!existingBaseline) {
-            // No baseline exists - set this as the new baseline
-            await service.setBaseline(screenshot);
-            newBaselines.push(screenshot.path.value);
-
-            comparisons.push({
-              url,
-              viewport,
-              status: 'new',
-              diffPercentage: 0,
-              diffPixels: 0,
-              screenshotPath: screenshot.path.value,
-            });
-          } else {
-            // Compare against baseline using real service
-            const diffResult = await service.compare(screenshot, existingBaseline.id);
-
-            if (!diffResult.success) {
-              comparisons.push({
-                url,
-                viewport,
-                status: 'failed',
-                diffPercentage: 100,
-                diffPixels: 0,
-              });
-              continue;
-            }
-
-            const diff = diffResult.value;
-            const passed = diff.diffPercentage <= threshold;
-
-            comparisons.push({
-              url,
-              viewport,
-              status: passed ? 'passed' : 'failed',
-              diffPercentage: diff.diffPercentage,
-              diffPixels: diff.diffPixels,
-              screenshotPath: screenshot.path.value,
-              baselinePath: existingBaseline.path.value,
-              diffImagePath: diff.diffImagePath?.value,
-              regions: diff.regions?.map((r) => ({
-                x: r.x,
-                y: r.y,
-                width: r.width,
-                height: r.height,
-                changeType: r.changeType,
-                significance: r.significance,
-              })),
-            });
-          }
-        }
-      }
-
-      const summary: VisualSummary = {
-        total: comparisons.length,
-        passed: comparisons.filter((c) => c.status === 'passed').length,
-        failed: comparisons.filter((c) => c.status === 'failed').length,
-        new: comparisons.filter((c) => c.status === 'new').length,
-        avgDiffPercentage:
-          comparisons.length > 0
-            ? comparisons.reduce((sum, c) => sum + c.diffPercentage, 0) / comparisons.length
-            : 0,
-      };
-
-      this.emitStream(context, {
-        status: 'complete',
-        message: `Visual comparison complete: ${summary.passed}/${summary.total} passed`,
-        progress: 100,
-      });
-
-      return {
-        success: true,
-        data: {
-          comparisons,
-          summary,
-          newBaselines,
-          recommendations: generateVisualRecommendations(comparisons, summary),
-        },
-      };
-    } catch (error) {
-      return {
-        success: false,
-        error: `Visual comparison failed: ${error instanceof Error ? error.message : String(error)}`,
-      };
-    }
-  }
-}
-
-// ============================================================================
-// Accessibility Audit Tool
-// ============================================================================
-
-export class A11yAuditTool extends MCPToolBase<A11yAuditParams, A11yAuditResult> {
-  readonly config: MCPToolConfig = {
-    name: 'qe/a11y/audit',
-    description: 'WCAG accessibility auditing with violation detection, contrast checking, and keyboard navigation testing.',
-    domain: 'visual-accessibility',
-    schema: A11Y_AUDIT_SCHEMA,
-    streaming: true,
-    timeout: 180000,
-  };
-
-  private accessibilityTester: AccessibilityTesterService | null = null;
-
-  /**
-   * Get or create the accessibility tester service
-   */
-  private getService(context: MCPToolContext): AccessibilityTesterService {
-    if (!this.accessibilityTester) {
-      const memory = (context as any).memory as MemoryBackend | undefined;
-      this.accessibilityTester = new AccessibilityTesterService(
-        memory || createMinimalMemoryBackend(),
-        {
-          enableColorContrastCheck: true,
-          enableKeyboardCheck: true,
-        }
-      );
-    }
-    return this.accessibilityTester;
-  }
-
-  async execute(
-    params: A11yAuditParams,
-    context: MCPToolContext
-  ): Promise<ToolResult<A11yAuditResult>> {
-    const {
-      urls,
-      standard = 'wcag21-aa',
-      includeWarnings = true,
-      checkContrast = true,
-      checkKeyboard = true,
-    } = params;
-
-    try {
-      this.emitStream(context, {
-        status: 'auditing',
-        message: `Auditing ${urls.length} URLs against ${standard}`,
-      });
-
-      if (this.isAborted(context)) {
-        return { success: false, error: 'Operation aborted' };
-      }
-
-      // Mark as real data - this tool always uses real services
-      this.markAsRealData();
-
-      const service = this.getService(context);
-      const audits: UrlAudit[] = [];
-
-      // Map standard to WCAG level
-      const wcagLevel = standardToWcagLevel(standard);
-
-      for (const url of urls) {
-        this.emitStream(context, {
-          status: 'scanning',
-          message: `Scanning ${url}`,
-        });
-
-        // Use real accessibility audit service
-        const auditResult = await service.audit(url, {
-          wcagLevel,
-          includeWarnings,
-        });
-
-        if (!auditResult.success) {
-          // Add failed audit with error info
-          audits.push({
-            url,
-            score: 0,
-            passed: false,
-            violations: [],
-            warnings: [],
-            passedRules: 0,
-          });
-          continue;
-        }
-
-        const report = auditResult.value;
-
-        // Optionally check contrast
-        let contrastViolations: A11yViolation[] = [];
-        if (checkContrast) {
-          const contrastResult = await service.checkContrast(url);
-          if (contrastResult.success) {
-            const failingContrast = contrastResult.value.filter((c) => !c.passes);
-            if (failingContrast.length > 0) {
-              contrastViolations = failingContrast.map((c) => ({
-                id: 'color-contrast',
-                impact: 'serious' as const,
-                description: 'Elements must have sufficient color contrast',
-                help: `Element ${c.element} has contrast ratio ${c.ratio}:1 but requires ${c.requiredRatio}:1`,
-                helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum',
-                wcagCriteria: ['1.4.3'],
-                nodes: [
-                  {
-                    selector: c.element,
-                    html: `<${c.element.replace('.', ' class="')}>...</${c.element.split('.')[0]}>`,
-                    failureSummary: `Contrast ratio ${c.ratio}:1 is below required ${c.requiredRatio}:1`,
-                    fixSuggestion: `Change foreground color to achieve at least ${c.requiredRatio}:1 contrast`,
-                  },
-                ],
-              }));
-            }
-          }
-        }
-
-        // Optionally check keyboard navigation
-        let keyboardViolations: A11yViolation[] = [];
-        if (checkKeyboard) {
-          const keyboardResult = await service.checkKeyboardNavigation(url);
-          if (keyboardResult.success) {
-            const kbReport = keyboardResult.value;
-
-            // Convert keyboard issues to violations
-            for (const issue of kbReport.issues) {
-              keyboardViolations.push({
-                id: issue.type,
-                impact: issue.type === 'no-focus-indicator' ? 'serious' : 'moderate',
-                description: issue.description,
-                help: 'Ensure keyboard navigation is fully supported',
-                helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-visible',
-                wcagCriteria: ['2.4.7'],
-                nodes: [
-                  {
-                    selector: issue.selector,
-                    html: `<element>${issue.selector}</element>`,
-                    failureSummary: issue.description,
-                    fixSuggestion: 'Add visible focus styles with :focus or :focus-visible',
-                  },
-                ],
-              });
-            }
-
-            // Add focus trap issues
-            for (const trap of kbReport.traps) {
-              keyboardViolations.push({
-                id: 'keyboard-trap',
-                impact: 'critical' as const,
-                description: trap.description,
-                help: trap.escapePath || 'No escape path available',
-                helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap',
-                wcagCriteria: ['2.1.2'],
-                nodes: [
-                  {
-                    selector: trap.selector,
-                    html: `<element>${trap.selector}</element>`,
-                    failureSummary: trap.description,
-                    fixSuggestion: trap.escapePath,
-                  },
-                ],
-              });
-            }
-          }
-        }
-
-        // Convert report violations to output format
-        const violations: A11yViolation[] = [
-          ...report.violations.map((v) => ({
-            id: v.id,
-            impact: v.impact,
-            description: v.description,
-            help: v.help,
-            helpUrl: v.helpUrl,
-            wcagCriteria: v.wcagCriteria.map((c) => c.id),
-            nodes: v.nodes.map((n) => ({
-              selector: n.selector,
-              html: n.html,
-              failureSummary: n.failureSummary,
-              fixSuggestion: n.fixSuggestion,
-            })),
-          })),
-          ...contrastViolations,
-          ...keyboardViolations,
-        ];
-
-        // Convert warnings (from incomplete checks)
-        const warnings: A11yWarning[] = report.incomplete.map((i) => ({
-          id: i.id,
-          description: i.description,
-          nodes: i.nodes.length,
-        }));
-
-        const hasCriticalOrSerious = violations.some(
-          (v) => v.impact === 'critical' || v.impact === 'serious'
-        );
-
-        audits.push({
-          url,
-          score: report.score,
-          passed: !hasCriticalOrSerious,
-          violations,
-          warnings,
-          passedRules: report.passes.length,
-        });
-      }
-
-      const summary: A11ySummary = {
-        totalUrls: audits.length,
-        passingUrls: audits.filter((a) => a.passed).length,
-        avgScore: audits.length > 0
-          ? Math.round(audits.reduce((sum, a) => sum + a.score, 0) / audits.length)
-          : 0,
-        criticalViolations: audits.reduce(
-          (sum, a) => sum + a.violations.filter((v) => v.impact === 'critical').length,
-          0
-        ),
-        seriousViolations: audits.reduce(
-          (sum, a) => sum + a.violations.filter((v) => v.impact === 'serious').length,
-          0
-        ),
-        totalViolations: audits.reduce((sum, a) => sum + a.violations.length, 0),
-      };
-
-      const topIssues = aggregateTopIssues(audits);
-      const remediationPlan = generateRemediationPlan(topIssues);
-
-      this.emitStream(context, {
-        status: 'complete',
-        message: `Audit complete: avg score ${summary.avgScore}%`,
-        progress: 100,
-      });
-
-      return {
-        success: true,
-        data: {
-          audits,
-          summary,
-          topIssues,
-          remediationPlan,
-        },
-      };
-    } catch (error) {
-      return {
-        success: false,
-        error: `Accessibility audit failed: ${error instanceof Error ? error.message : String(error)}`,
-      };
-    }
-  }
-}
-
-// ============================================================================
-// Schemas
-// ============================================================================
-
-const VISUAL_COMPARE_SCHEMA: MCPToolSchema = {
-  type: 'object',
-  properties: {
-    urls: {
-      type: 'array',
-      description: 'URLs to capture and compare',
-      items: { type: 'string', description: 'URL' },
-    },
-    viewports: {
-      type: 'array',
-      description: 'Viewport configurations',
-      items: {
-        type: 'object',
-        description: 'Viewport',
-        properties: {
-          width: { type: 'number', description: 'Width in pixels' },
-          height: { type: 'number', description: 'Height in pixels' },
-          name: { type: 'string', description: 'Viewport name' },
-        },
-      },
-    },
-    baselineDir: {
-      type: 'string',
-      description: 'Directory for baseline images',
-      default: '.visual-baselines',
-    },
-    threshold: {
-      type: 'number',
-      description: 'Acceptable diff percentage (0-1)',
-      minimum: 0,
-      maximum: 1,
-      default: 0.1,
-    },
-    fullPage: {
-      type: 'boolean',
-      description: 'Capture full page',
-      default: true,
-    },
-    hideSelectors: {
-      type: 'array',
-      description: 'CSS selectors to hide before capture',
-      items: { type: 'string', description: 'Selector' },
-    },
-    waitForSelector: {
-      type: 'string',
-      description: 'Wait for selector before capture',
-    },
-  },
-  required: ['urls'],
-};
-
-const A11Y_AUDIT_SCHEMA: MCPToolSchema = {
-  type: 'object',
-  properties: {
-    urls: {
-      type: 'array',
-      description: 'URLs to audit',
-      items: { type: 'string', description: 'URL' },
-    },
-    standard: {
-      type: 'string',
-      description: 'WCAG standard to validate against',
-      enum: ['wcag21-aa', 'wcag21-aaa', 'wcag22-aa', 'section508'],
-      default: 'wcag21-aa',
-    },
-    includeWarnings: {
-      type: 'boolean',
-      description: 'Include warnings in results',
-      default: true,
-    },
-    checkContrast: {
-      type: 'boolean',
-      description: 'Check color contrast',
-      default: true,
-    },
-    checkKeyboard: {
-      type: 'boolean',
-      description: 'Check keyboard navigation',
-      default: true,
-    },
-    rules: {
-      type: 'array',
-      description: 'Specific rules to check',
-      items: { type: 'string', description: 'Rule ID' },
-    },
-  },
-  required: ['urls'],
-};
-
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-function standardToWcagLevel(standard: string): 'A' | 'AA' | 'AAA' {
-  switch (standard) {
-    case 'wcag21-aaa':
-      return 'AAA';
-    case 'wcag21-aa':
-    case 'wcag22-aa':
-    case 'section508':
-    default:
-      return 'AA';
-  }
-}
-
-function generateVisualRecommendations(comparisons: VisualComparison[], summary: VisualSummary): string[] {
-  const recs: string[] = [];
-
-  if (summary.failed > 0) {
-    recs.push(`Review ${summary.failed} failed comparisons for intentional vs unintentional changes`);
-  }
-  if (summary.new > 0) {
-    recs.push(`${summary.new} new baselines created - review and approve if correct`);
-  }
-  if (summary.avgDiffPercentage > 1) {
-    recs.push('Consider increasing diff threshold or reviewing major changes');
-  }
-
-  return recs.length > 0 ? recs : ['All visual tests passed'];
-}
-
-function aggregateTopIssues(audits: UrlAudit[]): TopIssue[] {
-  const issueMap = new Map<string, TopIssue>();
-
-  for (const audit of audits) {
-    for (const v of audit.violations) {
-      const existing = issueMap.get(v.id);
-      if (existing) {
-        existing.occurrences++;
-        if (!existing.affectedUrls.includes(audit.url)) {
-          existing.affectedUrls.push(audit.url);
-        }
-      } else {
-        issueMap.set(v.id, {
-          ruleId: v.id,
-          description: v.description,
-          occurrences: 1,
-          impact: v.impact,
-          affectedUrls: [audit.url],
-        });
-      }
-    }
-  }
-
-  return Array.from(issueMap.values()).sort((a, b) => b.occurrences - a.occurrences);
-}
-
-function generateRemediationPlan(topIssues: TopIssue[]): RemediationItem[] {
-  return topIssues.map((issue, idx) => ({
-    violationId: issue.ruleId,
-    description: issue.description,
-    fix: `Fix ${issue.ruleId} across ${issue.occurrences} occurrences`,
-    effort: issue.occurrences > 10 ? 'moderate' : 'minor',
-    priority: idx + 1,
-  }));
-}
-
-/**
- * Create minimal memory backend for standalone operation
- */
-function createMinimalMemoryBackend(): MemoryBackend {
-  const store = new Map<string, { value: unknown; metadata?: unknown }>();
-  const vectors = new Map<string, { embedding: number[]; metadata?: unknown }>();
-
-  return {
-    async initialize(): Promise<void> {
-      // No initialization needed
-    },
-    async dispose(): Promise<void> {
-      store.clear();
-      vectors.clear();
-    },
-    async set(key: string, value: unknown, _options?: unknown): Promise<void> {
-      store.set(key, { value });
-    },
-    async get<T>(key: string): Promise<T | undefined> {
-      const entry = store.get(key);
-      return entry ? (entry.value as T) : undefined;
-    },
-    async delete(key: string): Promise<boolean> {
-      return store.delete(key);
-    },
-    async has(key: string): Promise<boolean> {
-      return store.has(key);
-    },
-    async search(pattern: string, limit?: number): Promise<string[]> {
-      const regex = new RegExp(pattern.replace(/\*/g, '.*'));
-      const matches = Array.from(store.keys()).filter((key) => regex.test(key));
-      return limit ? matches.slice(0, limit) : matches;
-    },
-    async vectorSearch(_embedding: number[], _k: number): Promise<VectorSearchResult[]> {
-      return [];
-    },
-    async storeVector(_key: string, _embedding: number[], _metadata?: unknown): Promise<void> {
-      // Minimal implementation
-    },
-  };
-}