agent-master-devsecops 3.9.0 → 5.1.0

package/scripts/auditors/a11y_auditor.js

@@ -0,0 +1,462 @@
+#!/usr/bin/env node
+/**
+ * scripts/auditors/a11y_auditor.js
+ * 
+ * Auditor Funcional de Acessibilidade Digital & Design Tokens — WCAG 2.1 AA (AGENT_UIUX / AGENT_QA)
+ * Inspeciona componentes HTML, JSX e TSX através de um Parser DOM/AST defensivo e determinístico,
+ * executando regras como predicados funcionais puros e gerando relatórios Markdown e OASIS SARIF v2.1.0.
+ * 
+ * Em conformidade com os 10 Princípios Canônicos, NIST SSDF e diretrizes de inclusão digital da W3C.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getKnowledgeGateway } = require('../core/knowledge_gateway.js');
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+/**
+ * Representação imutável de nó na árvore sintática (DOM/AST).
+ */
+class DomAstNode {
+  constructor(tag = '#root', attrs = {}, line = 1, raw = '') {
+    this.tag = String(tag || '').toLowerCase();
+    this.rawTag = tag;
+    const normalizedAttrs = {};
+    for (const [k, v] of Object.entries(attrs || {})) {
+      normalizedAttrs[k.toLowerCase()] = v;
+    }
+    this.attrs = Object.freeze(normalizedAttrs);
+    this.children = [];
+    this.parent = null;
+    this.line = Math.max(1, Number(line) || 1);
+    this.raw = raw || '';
+    this.textContent = '';
+  }
+
+  hasAttr(name) {
+    if (!name) return false;
+    const lower = name.toLowerCase();
+    return Object.prototype.hasOwnProperty.call(this.attrs, lower) ||
+           (lower === 'class' && Object.prototype.hasOwnProperty.call(this.attrs, 'classname')) ||
+           (lower === 'for' && Object.prototype.hasOwnProperty.call(this.attrs, 'htmlfor'));
+  }
+
+  getAttr(name) {
+    if (!name) return null;
+    const lower = name.toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(this.attrs, lower)) {
+      return this.attrs[lower];
+    }
+    if (lower === 'class' && this.attrs.classname) return this.attrs.classname;
+    if (lower === 'for' && this.attrs.htmlfor) return this.attrs.htmlfor;
+    return null;
+  }
+}
+
+const VOID_TAGS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr'
+]);
+
+const EXEMPT_INPUT_TYPES = new Set(['hidden', 'submit', 'button', 'image', 'reset']);
+
+const VAGUE_LINK_TEXTS = new Set([
+  'clique aqui', 'click here', 'saiba mais', 'read more', 'veja mais', 'link', 'aqui', 'here'
+]);
+
+/**
+ * Remove blocos de comentários e código executável de apoio sem alterar o alinhamento de linhas.
+ * @param {string} rawCode 
+ * @returns {string}
+ */
+function sanitizeMarkupPreservingLines(rawCode) {
+  if (typeof rawCode !== 'string') return '';
+  return rawCode
+    // Remove comentários HTML: <!-- ... --> preservando \n
+    .replace(/<!--[\s\S]*?-->/g, match => match.replace(/[^\r\n]/g, ' '))
+    // Remove comentários de bloco JSX: {/* ... */} preservando \n
+    .replace(/\{\/\*[\s\S]*?\*\/\}/g, match => match.replace(/[^\r\n]/g, ' '))
+    // Remove blocos de script e style internos preservando \n
+    .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, match => match.replace(/[^\r\n]/g, ' '));
+}
+
+/**
+ * Tokenizador linear O(N) imune a ReDoS (CWE-1333).
+ * Suporta arrow functions, URLs com barras e expressões JSX em atributos.
+ * @param {string} code 
+ * @returns {Array<{ tag: string, start: number, end: number }>}
+ */
+function tokenizeHtmlTags(code) {
+  const tags = [];
+  let i = 0;
+  const len = code.length;
+
+  while (i < len) {
+    if (code[i] === '<' && i + 1 < len) {
+      const nextChar = code[i + 1];
+      if (nextChar === '/' || /[a-zA-Z]/.test(nextChar)) {
+        const startIdx = i;
+        i++;
+        let inDoubleQuote = false;
+        let inSingleQuote = false;
+        let braceDepth = 0;
+
+        while (i < len) {
+          const char = code[i];
+          if (char === '"' && !inSingleQuote) {
+            inDoubleQuote = !inDoubleQuote;
+          } else if (char === "'" && !inDoubleQuote) {
+            inSingleQuote = !inSingleQuote;
+          } else if (char === '{' && !inDoubleQuote && !inSingleQuote) {
+            braceDepth++;
+          } else if (char === '}' && !inDoubleQuote && !inSingleQuote && braceDepth > 0) {
+            braceDepth--;
+          } else if (char === '>' && !inDoubleQuote && !inSingleQuote && braceDepth === 0) {
+            const fullTag = code.slice(startIdx, i + 1);
+            tags.push({ tag: fullTag, start: startIdx, end: i + 1 });
+            break;
+          }
+          i++;
+        }
+      }
+    }
+    i++;
+  }
+  return tags;
+}
+
+/**
+ * Parser de Árvore Sintática (AST / DOM Tree Lexer) para HTML, JSX e TSX.
+ * Executa tokenização linear defensiva imune a ReDoS (CWE-1333).
+ * @param {string} code
+ * @returns {DomAstNode} Raiz da árvore DOM
+ */
+function parseHtmlAst(code) {
+  const safeCode = sanitizeMarkupPreservingLines(code);
+  const root = new DomAstNode('#root', {}, 1, '');
+  let currentParent = root;
+  const stack = [root];
+
+  const tagTokens = tokenizeHtmlTags(safeCode);
+  let lastIndex = 0;
+
+  for (const token of tagTokens) {
+    const textBefore = safeCode.slice(lastIndex, token.start);
+    if (textBefore.trim().length > 0 && currentParent) {
+      currentParent.textContent += (currentParent.textContent ? ' ' : '') + textBefore.trim();
+    }
+    lastIndex = token.end;
+
+    const fullTag = token.tag;
+    const isClosing = fullTag.startsWith('</');
+    const lineNum = safeCode.slice(0, token.start).split('\n').length;
+
+    if (isClosing) {
+      const tagNameMatch = fullTag.match(/^<\/\s*([a-zA-Z0-9_\-:]+)/);
+      if (tagNameMatch) {
+        const targetTag = tagNameMatch[1].toLowerCase();
+        for (let i = stack.length - 1; i > 0; i--) {
+          if (stack[i].tag === targetTag) {
+            stack.length = i;
+            currentParent = stack[stack.length - 1];
+            break;
+          }
+        }
+      }
+    } else {
+      let tagInner = fullTag.slice(1, -1).trim();
+      let isSelfClosing = false;
+      if (tagInner.endsWith('/')) {
+        isSelfClosing = true;
+        tagInner = tagInner.slice(0, -1).trim();
+      }
+
+      const tagNameMatch = tagInner.match(/^([a-zA-Z0-9_\-:]+)/);
+      if (!tagNameMatch) continue;
+
+      const tagName = tagNameMatch[1];
+      const rawAttrs = tagInner.slice(tagName.length).trim();
+      if (VOID_TAGS.has(tagName.toLowerCase())) {
+        isSelfClosing = true;
+      }
+
+      const attrs = {};
+      const attrRegex = /([a-zA-Z0-9_\-:@]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|\{([^}]*)\}|([^>\s]+)))?/g;
+      let attrMatch;
+      while ((attrMatch = attrRegex.exec(rawAttrs)) !== null) {
+        const attrKey = attrMatch[1].toLowerCase();
+        const attrVal = attrMatch[2] ?? attrMatch[3] ?? attrMatch[4] ?? attrMatch[5] ?? 'true';
+        attrs[attrKey] = attrVal;
+      }
+
+      const node = new DomAstNode(tagName, attrs, lineNum, fullTag);
+      node.parent = currentParent;
+      currentParent.children.push(node);
+
+      if (!isSelfClosing) {
+        stack.push(node);
+        currentParent = node;
+      }
+    }
+  }
+
+  if (lastIndex < safeCode.length && currentParent) {
+    const trailingText = safeCode.slice(lastIndex).trim();
+    if (trailingText) {
+      currentParent.textContent += (currentParent.textContent ? ' ' : '') + trailingText;
+    }
+  }
+
+  // Agregação funcional de texto recursivo
+  function aggregateText(node) {
+    for (const child of node.children) {
+      aggregateText(child);
+      if (child.textContent) {
+        node.textContent += (node.textContent ? ' ' : '') + child.textContent;
+      }
+    }
+    node.textContent = node.textContent.trim();
+  }
+  aggregateText(root);
+
+  return root;
+}
+
+/**
+ * Catálogo Canônico de Regras WCAG 2.1 Nível AA com Predicados Puros.
+ */
+const WCAG_RULES = Object.freeze([
+  {
+    id: 'WCAG-1.1.1',
+    criterion: 'Non-text Content (Nível A)',
+    name: 'Imagem sem texto alternativo (alt)',
+    severity: 'CRÍTICA',
+    issue: 'Elemento de imagem não possui o atributo "alt" para tecnologias assistivas.',
+    remediation: 'Adicione alt="Descrição da imagem" ou alt="" acompanhado de role="presentation" para imagens puramente decorativas.',
+    check: (node) => (node.tag === 'img' || node.tag === 'image') && !node.hasAttr('alt')
+  },
+  {
+    id: 'WCAG-4.1.2-BTN',
+    criterion: 'Name, Role, Value (Nível A)',
+    name: 'Botão interativo sem rótulo acessível',
+    severity: 'ALTA',
+    issue: 'Botão contendo apenas ícone sem aria-label, aria-labelledby ou texto acessível.',
+    remediation: 'Inclua aria-label="Ação do botão" ou texto acessível visível/oculto via classe sr-only.',
+    check: (node) => {
+      if (node.tag !== 'button') return false;
+      const hasAccessibleLabel = node.hasAttr('aria-label') || node.hasAttr('aria-labelledby') || node.hasAttr('title');
+      const hasVisibleText = (node.textContent || '').trim().length > 0;
+      return !hasAccessibleLabel && !hasVisibleText;
+    }
+  },
+  {
+    id: 'WCAG-1.3.1-INPUT',
+    criterion: 'Info and Relationships (Nível A)',
+    name: 'Campo de entrada (input) sem rótulo associado',
+    severity: 'CRÍTICA',
+    issue: 'Elemento <input> não possui id para pareamento com <label htmlFor="..."> nem aria-label.',
+    remediation: 'Adicione um id único ao input pareado com <label htmlFor="id"> ou declare aria-label.',
+    check: (node) => {
+      if (node.tag !== 'input') return false;
+      const inputType = (node.getAttr('type') || 'text').toLowerCase();
+      if (EXEMPT_INPUT_TYPES.has(inputType)) return false;
+      const hasId = node.hasAttr('id');
+      const hasAria = node.hasAttr('aria-label') || node.hasAttr('aria-labelledby');
+      return !hasId && !hasAria;
+    }
+  },
+  {
+    id: 'WCAG-2.4.4-LINK',
+    criterion: 'Link Purpose (In Context) (Nível A)',
+    name: 'Link com texto vago ou não descritivo',
+    severity: 'MÉDIA',
+    issue: 'Texto de link ambíguo ("clique aqui", "saiba mais") que prejudica a navegação cega por links.',
+    remediation: 'Substitua por texto descritivo do destino (ex: "Consulte o catálogo de livros").',
+    check: (node) => {
+      if (node.tag !== 'a') return false;
+      const linkText = (node.textContent || '').trim().toLowerCase();
+      return VAGUE_LINK_TEXTS.has(linkText);
+    }
+  },
+  {
+    id: 'WCAG-2.4.7-FOCUS',
+    criterion: 'Focus Visible (Nível AA)',
+    name: 'Supressão de contorno de foco sem anel acessível',
+    severity: 'ALTA',
+    issue: 'Uso de outline-none sem definição de anel alternativo de foco (focus-visible / focus:ring).',
+    remediation: 'Mantenha o foco visível para usuários de teclado adicionando classes como "focus-visible:ring-2 focus-visible:ring-blue-500".',
+    check: (node) => {
+      const classNames = node.getAttr('class') || '';
+      if (!/\boutline-none\b/i.test(classNames)) return false;
+      const hasFocusRing = /\b(focus-visible:|focus:ring|focus:border|focus:outline)\b/i.test(classNames);
+      return !hasFocusRing;
+    }
+  },
+  {
+    id: 'WCAG-2.4.3-TABINDEX',
+    criterion: 'Focus Order (Nível A)',
+    name: 'Uso de tabindex positivo (anti-pattern)',
+    severity: 'MÉDIA',
+    issue: 'tabindex maior que zero altera a ordem natural de tabulação do DOM.',
+    remediation: 'Utilize tabindex="0" para incluir o elemento no fluxo natural ou reorganize a ordem dos elementos no DOM.',
+    check: (node) => {
+      if (!node.hasAttr('tabindex')) return false;
+      const tabVal = parseInt(node.getAttr('tabindex'), 10);
+      return !Number.isNaN(tabVal) && tabVal > 0;
+    }
+  },
+  {
+    id: 'WCAG-3.1.1-LANG',
+    criterion: 'Language of Page (Nível A)',
+    name: 'Documento HTML sem atributo de idioma (lang)',
+    severity: 'ALTA',
+    issue: 'Tag <html> sem atributo lang, impedindo sintetizadores de voz de carregar a pronúncia correta.',
+    remediation: 'Declare o idioma principal do documento: <html lang="pt-BR">.',
+    check: (node) => node.tag === 'html' && !node.hasAttr('lang')
+  }
+]);
+
+/**
+ * Coleta recursiva de todos os nós em array plano (Pipeline Funcional).
+ * @param {DomAstNode} rootNode
+ * @returns {Array<DomAstNode>}
+ */
+function flattenDomTree(rootNode) {
+  const nodes = [];
+  const collect = (node) => {
+    if (node.tag !== '#root') nodes.push(node);
+    for (const child of node.children) {
+      collect(child);
+    }
+  };
+  collect(rootNode);
+  return nodes;
+}
+
+class A11yAuditor {
+  constructor(rules = WCAG_RULES, options = {}) {
+    this.rules = rules;
+    this.gateway = options.gateway || getKnowledgeGateway(options);
+  }
+
+  /**
+   * Executa a auditoria funcional sobre a árvore sintática (DOM/AST).
+   * @param {string} code
+   * @param {string} [filename='component.tsx']
+   * @returns {object} Relatório canônico de acessibilidade
+   */
+  auditCode(code, filename = 'component.tsx') {
+    const ast = parseHtmlAst(code);
+    const nodes = flattenDomTree(ast);
+
+    // Avaliação Funcional Pura via FlatMap
+    const violations = nodes.flatMap(node => {
+      return this.rules
+        .filter(rule => typeof rule.check === 'function' && rule.check(node))
+        .map(rule => {
+          const spec = this.gateway ? this.gateway.getWcagSpec(rule.id) : null;
+          return {
+            ruleId: rule.id,
+            wcagCriterion: rule.criterion,
+            name: rule.name,
+            severity: rule.severity,
+            line: node.line,
+            snippet: (node.raw || `<${node.tag}>`).slice(0, 100),
+            issue: rule.issue,
+            remediation: rule.remediation,
+            authoritativeRef: spec?.authoritativeRef || null
+          };
+        });
+    });
+
+    const criticalCount = violations.filter(v => v.severity === 'CRÍTICA').length;
+    const highCount = violations.filter(v => v.severity === 'ALTA').length;
+    const mediumCount = violations.filter(v => v.severity === 'MÉDIA').length;
+
+    let verdict = 'APROVADO';
+    if (criticalCount > 0 || highCount > 0) {
+      verdict = 'REPROVADO';
+    } else if (mediumCount > 0) {
+      verdict = 'COM RESSALVAS';
+    }
+
+    return {
+      filename,
+      wcagTarget: 'WCAG 2.1 Nível AA',
+      verdict,
+      status: verdict === 'APROVADO' ? 'PASSED' : 'FAILED',
+      summary: {
+        totalViolations: violations.length,
+        criticalCount,
+        highCount,
+        mediumCount
+      },
+      violations
+    };
+  }
+
+  /**
+   * Exporta os apontamentos de acessibilidade em SARIF v2.1.0 oficial.
+   * @param {string} code
+   * @param {string} [filename='component.tsx']
+   * @returns {object} SARIF v2.1.0 JSON object
+   */
+  auditToSarif(code, filename = 'component.tsx') {
+    const auditRes = this.auditCode(code, filename);
+    const findings = auditRes.violations.map(v => ({
+      ruleId: v.ruleId,
+      name: v.name,
+      severity: v.severity,
+      filename: auditRes.filename,
+      line: v.line,
+      column: 1,
+      snippet: v.snippet,
+      message: `${v.wcagCriterion}: ${v.issue}`,
+      remediation: v.remediation
+    }));
+
+    return createSarifReport({
+      toolName: 'agent-master-a11y-auditor',
+      toolVersion: '5.1.0',
+      findings,
+      properties: {
+        wcagTarget: auditRes.wcagTarget,
+        verdict: auditRes.verdict,
+        status: auditRes.status,
+        summary: auditRes.summary
+      }
+    });
+  }
+
+  formatReport(audit) {
+    let md = `## ♿ Relatório de Auditoria de Acessibilidade (WCAG 2.1 AA — AGENT UI/UX)\n\n`;
+    md += `**Alvo:** \`${audit.filename}\` | **Veredito:** ${audit.verdict === 'APROVADO' ? '✅ APROVADO' : audit.verdict === 'REPROVADO' ? '❌ REPROVADO' : '⚠️ COM RESSALVAS'}\n\n`;
+    md += `### 📊 Sumário Executivo de Inclusão (DOM/AST Analysis)\n`;
+    md += `- **Violações Críticas (Impede Leitor de Tela):** ${audit.summary.criticalCount}\n`;
+    md += `- **Violações Altas (Navegação/Foco):** ${audit.summary.highCount}\n`;
+    md += `- **Ressalvas Médias:** ${audit.summary.mediumCount}\n\n`;
+
+    if (audit.violations.length > 0) {
+      md += `### ⚠️ Apontamentos de Acessibilidade Detectados\n\n`;
+      md += `| Linha | Critério WCAG | Severidade | Problema | Remediação Recomendada |\n`;
+      md += `| :---: | :--- | :---: | :--- | :--- |\n`;
+      for (const v of audit.violations) {
+        md += `| ${v.line} | **${v.wcagCriterion}** (${v.ruleId}) | **${v.severity}** | ${v.issue} | ${v.remediation} |\n`;
+      }
+      md += '\n';
+    } else {
+      md += `> 🌟 **Componente Acessível:** Nenhuma violação detectada. O componente atende às diretrizes WCAG 2.1 AA.\n\n`;
+    }
+
+    return md;
+  }
+}
+
+module.exports = {
+  A11yAuditor,
+  DomAstNode,
+  parseHtmlAst,
+  flattenDomTree,
+  WCAG_RULES
+};