@maestro-ai/mcp-server 1.2.0 → 2.1.0

package/dist/content/skills/specialist-acessibilidade/mcp_functions/validate_wcag_compliance.py

@@ -0,0 +1,587 @@
+#!/usr/bin/env python3
+"""
+Referência MCP: Validação de Conformidade WCAG 2.1
+
+Esta função valida a conformidade WCAG 2.1 AA de um projeto
+usando checklists automatizados e métricas específicas.
+
+NOTA: Este é um arquivo de referência. A execução real deve ser
+implementada no servidor MCP externo.
+"""
+
+from typing import Dict, List, Optional
+from pathlib import Path
+import json
+from datetime import datetime
+import re
+from bs4 import BeautifulSoup
+import requests
+from typing import Tuple
+
+class WCAGComplianceValidator:
+    """Validador de conformidade WCAG 2.1 AA"""
+    
+    def __init__(self, project_path: str):
+        self.project_path = Path(project_path)
+        self.validation_results = {}
+        
+    def validate_compliance(self, config: Dict) -> Dict:
+        """
+        Valida conformidade WCAG 2.1 AA
+        
+        Args:
+            config: Dicionário com configuração da validação
+                - project_path: "/path/to/project"
+                - wcag_level: "AA|AAA"
+                - include_automated: boolean
+                - include_manual: boolean
+                - target_browsers: ["chrome", "firefox", "safari"]
+                - screen_readers: ["nvda", "voiceover", "jaws"]
+                
+        Returns:
+            Dict com resultado da validação
+        """
+        
+        project_path = config.get("project_path", ".")
+        wcag_level = config.get("wcag_level", "AA")
+        include_automated = config.get("include_automated", True)
+        include_manual = config.get("include_manual", True)
+        target_browsers = config.get("target_browsers", ["chrome", "firefox", "safari"])
+        screen_readers = config.get("screen_readers", ["nvda", "voiceover", "jaws"])
+        
+        # Executar validações
+        results = {}
+        
+        if include_automated:
+            results["automated"] = self._validate_automated(
+                project_path, 
+                target_browsers,
+                wcag_level
+            )
+        
+        if include_manual:
+            results["manual"] = self._validate_manual(
+                project_path,
+                screen_readers,
+                wcag_level
+            )
+        
+        # Calcular score geral
+        overall_score = self._calculate_overall_score(results)
+        
+        # Gerar relatório
+        report = {
+            "status": "success",
+            "validation": {
+                "timestamp": datetime.now().isoformat(),
+                "wcag_level": wcag_level,
+                "overall_score": overall_score,
+                "automated": results.get("automated", {}),
+                "manual": results.get("manual", {}),
+                "target_browsers": target_browsers,
+                "screen_readers": screen_readers,
+                "compliance_level": self._get_compliance_level(overall_score)
+            },
+            "summary": self._generate_summary(results),
+            "recommendations": self._generate_recommendations(results),
+            "next_actions": self._get_next_actions(results),
+            "quality_metrics": self._calculate_quality_metrics(results)
+        }
+        
+        return report
+    
+    def _validate_automated(self, project_path: str, browsers: List[str], wcag_level: str) -> Dict:
+        """Executa validação automatizada usando ferramentas"""
+        
+        results = {}
+        
+        # Teste com axe-core
+        axe_results = self._test_with_axe(project_path, browsers)
+        results["axe"] = axe_results
+        
+        # Teste de contraste
+        contrast_results = self._test_contrast(project_path)
+        results["contrast"] = contrast_results
+        
+        # Teste de HTML semântico
+        html_results = self._validate_html(project_path)
+        results["html"] = html_results
+        
+        # Teste de navegação por teclado
+        keyboard_results = self._test_keyboard_navigation(project_path)
+        results["keyboard"] = keyboard_results
+        
+        return results
+    
+    def _test_with_axe(self, project_path: str, browsers: List[str]) -> Dict:
+        """Teste com axe-core em múltiplos navegadores"""
+        
+        results = {
+            "tool": "axe-core",
+            "browsers_tested": browsers,
+            "violations": [],
+            "passes": [],
+            "incomplete": [],
+            "score": 0
+        }
+        
+        for browser in browsers:
+            try:
+                # Simular execução do axe-core
+                # Em implementação real, usaria:
+                # npx axe --browser={browser} --report-path=audit-results/automated/axe-{browser}-report.html
+                
+                # Resultados simulados
+                if browser == "chrome":
+                    simulated_violations = [
+                        {
+                            "id": "color-contrast",
+                            "impact": "critical",
+                            "description": "Elements must have sufficient color contrast",
+                            "count": 3,
+                            "nodes": ["button.btn-primary", "span.highlight", "div.card"]
+                        }
+                    ]
+                elif browser == "firefox":
+                    simulated_violations = [
+                        {
+                            "id": "keyboard-navigation",
+                            "impact": "serious",
+                            "description": "Some elements are not keyboard accessible",
+                            "count": 2
+                        }
+                    ]
+                elif browser == "safari":
+                    simulated_violations = [
+                        {
+                            "id": "missing-alt-text",
+                            "impact": "serious",
+                            "description": "Images missing alternative text",
+                            "count": 5
+                        }
+                
+                results["browsers"][browser] = {
+                    "violations": simulated_violations,
+                    "passes": [],
+                    "incomplete": [],
+                    "score": 0
+                }
+                
+                results["violations"].extend(simulated_violations)
+                
+            except Exception as e:
+                results["error"] = f"Erro ao testar com {browser}: {e}"
+            
+            return results
+        
+        return results
+    
+    def _test_contrast(self, project_path: str) -> Dict:
+        """Testa contraste de cores usando ferramenta online"""
+        
+        results = {
+            "tool": "color-contrast-checker",
+            "tested_elements": [],
+            "contrast_issues": [],
+            "passed_elements": [],
+            "score": 0
+        }
+        
+        try:
+            # Simular verificação de contraste
+            simulated_tests = [
+                {
+                    "element": "button.btn-primary",
+                    "foreground": "#6B9BD1",
+                    "background": "#4A90E2",
+                    "ratio": 3.2,
+                    "wcag_level": "FAIL"
+                },
+                {
+                    "element": "span.highlight",
+                    "foreground": "#CCCCCC",
+                    "background": "#FFFFFF",
+                    "ratio": 1.6,
+                    "wcag_level": "FAIL"
+                },
+                {
+                    "element": "div.card",
+                    "foreground": "#333333",
+                    "background": "#FFFFFF",
+                    "ratio": 12.6,
+                    "wcag": "PASS"
+                }
+            ]
+            
+            results["tested_elements"] = simulated_tests
+            results["contrast_issues"] = [
+                t for t in simulated_tests if t["wcag_level"] == "FAIL"
+            ]
+            results["passed_elements"] = [
+                t for t in simulated_tests if t["wcag_level"] == "PASS"
+            ]
+            
+            # Calcular score
+            total_elements = len(simulated_tests)
+            passed_elements = len(results["passed_elements")
+            
+            if total_elements > 0:
+                results["score"] = (passed_elements / total_elements) * 100
+            
+        except Exception as e:
+            results["error"] = f"Erro ao testar contraste: {e}"
+        
+        return results
+    
+    def _validate_html(self, project_path: str) -> Dict:
+        """Validação HTML usando W3C Validator"""
+        
+        results = {
+            "tool": "W3C Validator",
+            "validator": "W3C Markup Validation Service",
+            "errors": [],
+            "warnings": [],
+            "score": 0
+        }
+        
+        try:
+            # Simular validação W3C
+            simulated_errors = [
+                {
+                    "line": 15,
+                    "column": 25,
+                    "message": "Element 'div' not allowed as child of element 'p'",
+                    "type": "error"
+                },
+                {
+                    "line": 23,
+                    "column": 30,
+                    "message": "Attribute 'role' not allowed on element 'span'",
+                    "type": "error"
+                }
+            ]
+            
+            results["errors"] = simulated_errors
+            results["warnings"] = [
+                {
+                    "line": 10,
+                    "column": 20,
+                    "message": "Consider adding a 'lang' attribute",
+                    "type": "warning"
+                }
+            ]
+            
+            # Calcular score
+            total_issues = len(simulated_errors) + len(simulated_warnings)
+            if total_issues == 0:
+                results["score"] = 100
+            elif total_issues <= 2:
+                results["score"] = 90
+            else:
+                results["score"] = max(0, 100 - (total_issues * 10))
+            
+        except Exception as e:
+            results["error"] = f"Erro ao validar HTML: {e}"
+        
+        return results
+    
+    def _test_keyboard_navigation(self, project_path: str) -> Dict:
+        """Teste navegação por teclado"""
+        
+        results = {
+            "tool": "keyboard-navigation-tester",
+            "tested_elements": [],
+            "keyboard_issues": [],
+            "passed_elements": [],
+            "score": 0
+        }
+        
+        try:
+            # Simular testes de teclado
+            simulated_tests = [
+                {
+                    "element": "main-navigation",
+                    "tab_accessible": True,
+                    "escape_functional": True,
+                    "focus_visible": True,
+                    "order_logical": True
+                },
+                {
+                    "element": "modal-overlay",
+                    "tab_accessible": False,
+                    "escape_functional": False,
+                    "focus_trap": True,
+                    "order_logical": False
+                },
+                {
+                    "element": "form-fields",
+                    "tab_accessible": True,
+                    "escape_functional": True,
+                    "focus_visible": True,
+                    "order_logical": True
+                }
+            ]
+            
+            results["tested_elements"] = simulated_tests
+            results["keyboard_issues"] = [
+                t for t in simulated_tests 
+                if not t["tab_accessible"] or not t["escape_functional"] or t["focus_trap"]
+            ]
+            results["passed_elements"] = [
+                t for t in simulated_tests 
+                if t["tab_accessible"] and t["escape_functional"] and not t["focus_trap"]
+            ]
+            
+            # Calcular score
+            total_elements = len(simulated_tests)
+            passed_elements = len(results["passed_elements"])
+            
+            if total_elements > 0:
+                results["score"] = (passed_elements / total_elements) * 100
+            
+        except Exception as e:
+            results["error"] = f"Erro ao testar teclado: {e}"
+        
+        return results
+    
+    def _validate_manual(self, project_path: str, screen_readers: List[str], wcag_level: str) -> Dict:
+        """Prepara testes manuais com leitores de tela"""
+        
+        results = {
+            "screen_readers": screen_readers,
+            "wcag_level": wcag_level,
+            "checklist_template": "checklist-acessibilidade.md",
+            "report_template": "relatorio-acessibilidade.md",
+            "test_scenarios": [
+                "keyboard-navigation",
+                "screen-reader-navigation",
+                "zoom-200%",
+                "high-contrast-mode",
+                "form-accessibility",
+                "color-contrast"
+            ],
+            "status": "ready",
+            "instructions": {
+                "nvda": {
+                    "name": "NVDA",
+                    "version": "2024.4",
+                    "os": "Windows",
+                    "setup": "Configurado para português brasileiro"
+                },
+                "voiceover": {
+                    "nome": "VoiceOver",
+                    "version": "macOS",
+                    "os": "macOS",
+                    "setup": "Configurado para português brasileiro"
+                },
+                "jaws": {
+                    "nome": "JAWS",
+                    "version": "2024.1",
+                    "os": "Windows",
+                    "setup": "Configurado para português brasileiro"
+                }
+            }
+        }
+        
+        return results
+    
+    def _calculate_overall_score(self, results: Dict) -> float:
+        """Calcula score geral da auditoria"""
+        
+        scores = {
+            "wcag_compliance": self._calculate_wcag_score(results.get("automated", {})),
+            "keyboard_navigation": self._calculate_score(results.get("keyboard", {})),
+            "screen_reader": self._calculate_score(results.get("manual", {})),
+            "color_contrast": self._calculate_score(results.get("contrast", {})),
+            "semantic_html": self._calculate_score(results.get("html", {}))
+        }
+        
+        # Média ponderada
+        weights = {
+            "wcag_compliance": 0.40,
+            "keyboard_navigation": 0.20,
+            "screen_reader": 0.20,
+            "color_contrast": 0.10,
+            "semantic_html": 0.10
+        }
+        
+        total_score = sum(
+            scores["wcag_compliance"] * weights["wcag_compliance"] +
+            scores["keyboard_navigation"] * weights["keyboard_navigation"] +
+            scores["screen_reader"] * weights["screen_reader"] +
+            scores["color_contrast"] * weights["color_contrast"] +
+            scores["semantic_html"] * weights["semantic_html"]
+        )
+        
+        return total_score
+    
+    def _calculate_wcag_score(self, results: Dict) -> float:
+        """Calcula score de conformidade WCAG"""
+        
+        if not results or "violations" not in results:
+            return 0.0
+        
+        violations = results.get("violations", [])
+        passes = results.get("passes", [])
+        total_elements = len(violations) + len(passes)
+        
+        if total_elements == 0:
+            return 0.0
+        
+        # Penalidades por severidade
+        penalty = sum(
+            v["count"] * 5 for v in violations if v["impact"] == "critical"
+        ) + sum(
+            v["count"] * 3 for v in violations if v["impact"] == "serious"
+        ) + sum(
+                v["count"] * 1 for v in violations if v["impact"] == "moderate"
+        )
+        
+        # Score base (100 - penalidades
+        base_score = 100 - penalty
+        score = max(0, base_score)
+        
+        return score
+    
+    def _calculate_score(self, results: Dict) -> float:
+        """Calcula score de uma seção específica"""
+        
+        if not results or "score" not in results:
+            return 0.0
+        
+        score = results.get("score", 0)
+        total_elements = len(results.get("tested_elements", []))
+        
+        if total_elements == 0:
+            return 0.0
+        
+        return score
+    
+    def _get_compliance_level(self, score: float) -> str:
+        """Determina nível de conformidade WCAG baseado no score"""
+        
+        if score >= 95:
+            return "AAA"
+        elif score >= 80:
+            return "AA"
+        elif score >= 60:
+            return "A"
+        else:
+            return "FAIL"
+    
+    def _generate_summary(self, results: Dict) -> str:
+        """Gera resumo da validação"""
+        
+        automated = results.get("automated", {})
+        manual = results.get("manual", {})
+        
+        total_issues = (
+            sum(automated.get("violations", {}).get("count", 0)) +
+            sum(manual.get("issues", {}).get("count", 0))
+        )
+        
+        passed_elements = (
+            sum(automated.get("passes", {}).get("count", 0)) +
+            sum(manual.get("passed", {}).get("count", 0))
+        
+        total_elements = total_issues + passed_elements
+        
+        compliance_level = self._get_compliance_level(
+            self._calculate_overall_score(results)
+        )
+        
+        summary = f"""
+# 📊 Resumo da Auditoria de Acessibilidade
+
+## 📋 Status Geral
+- **Nível de Conformidade:** {compliance_level}
+- **Score Geral:** {total_score}/100 pontos
+- **Total de Issues:** {total_issues}
+- **Elementos Testados:** {total_elements}
+- **Data da Auditoria:** {results['audit']['timestamp']}
+
+## 📊 Resultados por Categoria
+
+### 📊 Testes Automatizados
+{automated.get('axe', {}).get('score', 0)} pontos
+
+#### Violations Encontradas
+{automated.get('axe', {}).get('violations', [])}
+
+#### Elementos com Problemas
+{automated.get('axe', {}).get('violations', [])}
+
+### 📋 Testes Manuais
+{manual.get('screen_reader', {}).get('test_scenarios', [])}
+
+---
+
+## 🚨 Recomendações Estratégicas
+
+### 🎯 Issues Críticas (Prioridade Alta)
+1. **Correção de Contraste** - Afeta legibilidade
+2. **Navegação por Teclado** - Bloqueia acesso total
+3. **Textos Alternativos Faltantes** - Impede compreensão
+
+### 🔄 Issues Moderadas (Prioridade Média)
+1. **Foco Invisível** - Dificulta usabilidade
+2. **ARIA Redundante** - Confunde leitores de tela
+3. **Formulários sem Labels** - Dificulta preenchimento
+
+### 🎯 Issues Leves (Prioridade Baixa)
+1. **Documentação ARIA** - Melhorar documentação
+2. **Testes de Zoom** - Verificar em diferentes níveis
+3. **Validação HTML** - Melhorar semântica
+
+---
+
+## 🚀 Próximos Passos
+
+### 1. Correções Críticas (1-2 dias)
+- [ ] Corrigir contraste de cores
+- [ ] Implementar navegação completa por teclado
+- [ ] Adicionar textos alternativos faltantes
+- [ ] Testar com múltiplos leitores
+
+### 2. Melhorias de Médio Prazo (1-3 semanas)
+- [ ] Implementar ARIA correta
+- [ ] Melhorar estrutura semântica
+- [ ] Otimizar performance de carregamento
+- [ ] Adicionar mais testes automatizados
+
+### 3. Validação Final (3-5 dias)
+- [ ] Revalidar todas as correções
+- [ ] Testar com usuários reais
+- [ ] Obter aprovação final
+- [] Documentar lições aprendidas
+
+---
+
+## 📊 Métricas de Qualidade
+
+### Indicadores Obrigatórios
+- **Score Mínimo:** 80 pontos para aprovação
+- **Zero Issues Críticas:** Sem issues críticas
+- **Coverage de Testes:** 100% dos elementos testados
+- **Conformidade:** WCAG 2.1 AA ou superior
+- **Performance:** Tempo de validação < 90 minutos
+
+### Métricas de Processo
+- **Tempo Médio:** 90 minutos por auditoria
+- **Taxa de Correção:** 70% das issues corrigidas
+- **Taxa de Sucesso:** 95% das correções implementadas
+- **Reprodutibilidade:** 100% dos testes replicáveis
+
+---
+
+## 📊 Status Final
+
+**Status Final:** [ ] ✅ **INICIADO** | [ ] ✅ **CONCLUÍDO** | [ ] ❌ **REPROVADO**
+
+**Score Final:** [ ]/100 pontos  
+**Nível de Conformidade:** [WCAG 2.1 AA]  
+**Data da Próxima Auditoria:** [DD/MM/YYYY]  
+
+---
+
+*Esta validação deve ser executada regularmente para manter a conformidade WCAG contínua e garantir a acessibilidade para todos os usuários.*