agent-master-devsecops 3.9.0 → 5.1.0

package/scripts/auditors/code_quality_auditor.js

@@ -0,0 +1,444 @@
+/**
+ * scripts/auditors/code_quality_auditor.js
+ * Code Quality & Cyclomatic Complexity Auditor — Versão 5.1 Enterprise
+ * 
+ * Auditoria independente de qualidade de software, complexidade ciclomática de McCabe,
+ * profundidade de aninhamento e detecção de anti-patterns de código.
+ * Em conformidade com a Regra 13 (Estrutura de Código), Princípio 4 (Qualidade & DoD),
+ * Princípio 5 (DevSecOps) e padrão OASIS SARIF v2.1.0.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+/**
+ * Scanner léxico linear O(N) imune a ReDoS (CWE-1333).
+ * Sanitiza strings e comentários preservando exatamente todas as quebras de linha (\n)
+ * e delimitadores de controle de fluxo para cálculo determinístico de métricas.
+ * 
+ * @param {string} sourceCode 
+ * @returns {{ sanitized: string, comments: Array<{ line: number, text: string, isBlock: boolean }>, totalLines: number }}
+ */
+function lexicalScan(sourceCode) {
+  const code = String(sourceCode || '');
+  const len = code.length;
+  const sanitizedChars = [];
+  const comments = [];
+  
+  let state = 'CODE'; // CODE, LINE_COMMENT, BLOCK_COMMENT, SINGLE_QUOTE, DOUBLE_QUOTE, TEMPLATE
+  const templateStack = []; // pilha para balancear interpolações ${...} dentro de templates
+  let currentComment = '';
+  let commentStartLine = 1;
+  let currentLine = 1;
+
+  for (let i = 0; i < len; i++) {
+    const ch = code[i];
+    const next = i + 1 < len ? code[i + 1] : '';
+
+    if (ch === '\n') {
+      currentLine++;
+    }
+
+    if (state === 'CODE') {
+      if (ch === '/' && next === '/') {
+        state = 'LINE_COMMENT';
+        commentStartLine = currentLine;
+        currentComment = '//';
+        sanitizedChars.push(' ', ' ');
+        i++; // consome proximo caractere
+      } else if (ch === '/' && next === '*') {
+        state = 'BLOCK_COMMENT';
+        commentStartLine = currentLine;
+        currentComment = '/*';
+        sanitizedChars.push(' ', ' ');
+        i++; // consome proximo caractere
+      } else if (ch === "'") {
+        state = 'SINGLE_QUOTE';
+        sanitizedChars.push(' ');
+      } else if (ch === '"') {
+        state = 'DOUBLE_QUOTE';
+        sanitizedChars.push(' ');
+      } else if (ch === '`') {
+        state = 'TEMPLATE';
+        sanitizedChars.push(' ');
+      } else if (ch === '}' && templateStack.length > 0) {
+        templateStack[templateStack.length - 1]--;
+        if (templateStack[templateStack.length - 1] === 0) {
+          templateStack.pop();
+          state = 'TEMPLATE';
+          sanitizedChars.push(' ');
+        } else {
+          sanitizedChars.push(ch);
+        }
+      } else if (ch === '{' && templateStack.length > 0) {
+        templateStack[templateStack.length - 1]++;
+        sanitizedChars.push(ch);
+      } else {
+        sanitizedChars.push(ch);
+      }
+    } else if (state === 'LINE_COMMENT') {
+      if (ch === '\n') {
+        comments.push({ line: commentStartLine, text: currentComment.trim(), isBlock: false });
+        currentComment = '';
+        state = 'CODE';
+        sanitizedChars.push('\n');
+      } else {
+        currentComment += ch;
+        sanitizedChars.push(' ');
+      }
+    } else if (state === 'BLOCK_COMMENT') {
+      if (ch === '*' && next === '/') {
+        currentComment += '*/';
+        comments.push({ line: commentStartLine, text: currentComment.trim(), isBlock: true });
+        currentComment = '';
+        state = 'CODE';
+        sanitizedChars.push(' ', ' ');
+        i++; // consome proximo caractere
+      } else {
+        currentComment += ch;
+        sanitizedChars.push(ch === '\n' ? '\n' : ' ');
+      }
+    } else if (state === 'SINGLE_QUOTE') {
+      if (ch === '\\' && i + 1 < len) {
+        sanitizedChars.push(' ', ' ');
+        i++;
+      } else if (ch === "'") {
+        state = 'CODE';
+        sanitizedChars.push(' ');
+      } else {
+        sanitizedChars.push(ch === '\n' ? '\n' : ' ');
+      }
+    } else if (state === 'DOUBLE_QUOTE') {
+      if (ch === '\\' && i + 1 < len) {
+        sanitizedChars.push(' ', ' ');
+        i++;
+      } else if (ch === '"') {
+        state = 'CODE';
+        sanitizedChars.push(' ');
+      } else {
+        sanitizedChars.push(ch === '\n' ? '\n' : ' ');
+      }
+    } else if (state === 'TEMPLATE') {
+      if (ch === '\\' && i + 1 < len) {
+        sanitizedChars.push(' ', ' ');
+        i++;
+      } else if (ch === '$' && next === '{') {
+        templateStack.push(1);
+        state = 'CODE';
+        sanitizedChars.push(' ', ' ');
+        i++; // consome '{'
+      } else if (ch === '`') {
+        state = 'CODE';
+        sanitizedChars.push(' ');
+      } else {
+        sanitizedChars.push(ch === '\n' ? '\n' : ' ');
+      }
+    }
+  }
+
+  if (state === 'LINE_COMMENT' && currentComment) {
+    comments.push({ line: commentStartLine, text: currentComment.trim(), isBlock: false });
+  } else if (state === 'BLOCK_COMMENT' && currentComment) {
+    comments.push({ line: commentStartLine, text: currentComment.trim(), isBlock: true });
+  }
+
+  return {
+    sanitized: sanitizedChars.join(''),
+    comments,
+    totalLines: currentLine
+  };
+}
+
+/**
+ * Calcula a complexidade ciclomática de McCabe v(G) sobre código sanitizado.
+ * v(G) = 1 + número de pontos de decisão binária.
+ * 
+ * @param {string} sanitizedCode 
+ * @returns {number}
+ */
+function calculateCyclomaticComplexity(sanitizedCode) {
+  let complexity = 1;
+
+  // Pontos de decisão de controle de fluxo (sem dupla contagem de 'else if')
+  const decisionRules = [
+    /\b(?:if|for|while)\s*\(/g,
+    /\bcatch\s*(?:\([^\)]*\))?\s*\{/g,
+    /\bcase\s+[^:]+:/g,
+    /&&/g,
+    /\|\|/g,
+    /\?\?/g,
+    /\?[^:]+:/g
+  ];
+
+  for (const regex of decisionRules) {
+    const matches = sanitizedCode.match(regex);
+    if (matches) {
+      complexity += matches.length;
+    }
+  }
+
+  return complexity;
+}
+
+/**
+ * Calcula a profundidade máxima de aninhamento de blocos ({ ... }) no código sanitizado.
+ * 
+ * @param {string} sanitizedCode 
+ * @returns {number}
+ */
+function calculateMaxNestingDepth(sanitizedCode) {
+  let maxNesting = 0;
+  let currentNesting = 0;
+
+  for (const ch of sanitizedCode) {
+    if (ch === '{') {
+      currentNesting++;
+      if (currentNesting > maxNesting) {
+        maxNesting = currentNesting;
+      }
+    } else if (ch === '}') {
+      currentNesting = Math.max(0, currentNesting - 1);
+    }
+  }
+
+  return maxNesting;
+}
+
+/**
+ * Classe principal do Auditor de Qualidade de Código.
+ */
+class CodeQualityAuditor {
+  constructor(options = {}) {
+    this.maxComplexity = options.maxComplexity || 15;
+    this.maxNesting = options.maxNesting || 6;
+    this.maxFileLines = options.maxFileLines || 300;
+  }
+
+  auditFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Arquivo não encontrado para auditoria de qualidade: ${filePath}`);
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+    return this.auditCode(content, path.basename(filePath));
+  }
+
+  auditCode(code, filename = 'snippet.js') {
+    const scan = lexicalScan(code);
+    const rawLines = String(code || '').split('\n');
+    const totalLines = rawLines.length;
+
+    // Rastreamento das linhas de comentário
+    const commentLinesSet = new Set();
+    for (const c of scan.comments) {
+      const lineCount = c.text.split('\n').length;
+      for (let l = 0; l < lineCount; l++) {
+        commentLinesSet.add(c.line + l);
+      }
+    }
+
+    let blankLines = 0;
+    let commentLines = 0;
+
+    rawLines.forEach((line, idx) => {
+      const lineNum = idx + 1;
+      const trimmed = line.trim();
+      if (!trimmed) {
+        blankLines++;
+      } else if (commentLinesSet.has(lineNum)) {
+        // Se a linha contém apenas comentário
+        const sanitizedLine = scan.sanitized.split('\n')[idx] || '';
+        if (!sanitizedLine.trim()) {
+          commentLines++;
+        }
+      }
+    });
+
+    const issues = [];
+
+    // 1. Verificação de pendências em comentários (TODO, FIXME, HACK)
+    for (const c of scan.comments) {
+      const todoMatch = c.text.match(/\b(?:TODO|FIXME|HACK)\b[^\r\n]*/);
+      if (todoMatch) {
+        issues.push({
+          ruleId: 'QUALITY-TODO-001',
+          type: 'PENDING_TODO',
+          line: c.line,
+          severity: 'LOW',
+          message: `Marcação pendente detectada: "${todoMatch[0].trim()}". Código pronto não deve deixar TODOs (Regra 7).`,
+          remediation: 'Resolva a pendência técnica ou crie um ticket no backlog formal.'
+        });
+      }
+    }
+
+    // 2. Detecção de blocos catch vazios (anti-pattern de engolir exceções - Regra 5)
+    const emptyCatchRegex = /\bcatch\s*(?:\([^\)]*\))?\s*\{\s*\}/g;
+    let match;
+    while ((match = emptyCatchRegex.exec(scan.sanitized)) !== null) {
+      const upToMatch = scan.sanitized.slice(0, match.index);
+      const lineNum = upToMatch.split('\n').length;
+      issues.push({
+        ruleId: 'QUALITY-EMPTY-CATCH',
+        type: 'EMPTY_CATCH',
+        line: lineNum,
+        severity: 'HIGH',
+        message: 'Bloco catch vazio detectado: erros não devem ser suprimidos silenciosamente (Regra 5).',
+        remediation: 'Adicione tratamento do erro, logging com contexto ou propague a exceção.'
+      });
+    }
+
+    // 3. Detecção de blocos finally vazios
+    const emptyFinallyRegex = /\bfinally\s*\{\s*\}/g;
+    while ((match = emptyFinallyRegex.exec(scan.sanitized)) !== null) {
+      const upToMatch = scan.sanitized.slice(0, match.index);
+      const lineNum = upToMatch.split('\n').length;
+      issues.push({
+        ruleId: 'QUALITY-EMPTY-FINALLY',
+        type: 'EMPTY_FINALLY',
+        line: lineNum,
+        severity: 'MEDIUM',
+        message: 'Bloco finally vazio detectado: remova o bloco redundante ou implemente o cleanup apropriado.',
+        remediation: 'Remova o bloco finally vazio caso não execute fechamento de recursos.'
+      });
+    }
+
+    // 4. Detecção de declaração 'debugger' deixada para trás
+    const debuggerRegex = /\bdebugger\s*(?:;|$)/g;
+    while ((match = debuggerRegex.exec(scan.sanitized)) !== null) {
+      const upToMatch = scan.sanitized.slice(0, match.index);
+      const lineNum = upToMatch.split('\n').length;
+      issues.push({
+        ruleId: 'QUALITY-DEBUGGER-STMT',
+        type: 'DEBUGGER_STATEMENT',
+        line: lineNum,
+        severity: 'HIGH',
+        message: 'Instrução debugger detectada: código de depuração não deve ser commitado para produção.',
+        remediation: 'Remova a instrução debugger antes de prosseguir com o commit.'
+      });
+    }
+
+    // Métricas de Complexidade e Aninhamento
+    const cyclomaticComplexity = calculateCyclomaticComplexity(scan.sanitized);
+    const maxNestingDepth = calculateMaxNestingDepth(scan.sanitized);
+
+    // 5. Verificação de limites de tamanho e complexidade
+    if (totalLines > this.maxFileLines) {
+      issues.push({
+        ruleId: 'QUALITY-FILE-LINES',
+        type: 'FILE_TOO_LONG',
+        line: totalLines,
+        severity: 'MEDIUM',
+        message: `Arquivo possui ${totalLines} linhas (limite canônico recomendado: ${this.maxFileLines} linhas - Regra 13).`,
+        remediation: 'Divida o módulo em componentes menores com responsabilidade única (SRP).'
+      });
+    }
+
+    if (maxNestingDepth > this.maxNesting) {
+      issues.push({
+        ruleId: 'QUALITY-DEEP-NESTING',
+        type: 'DEEP_NESTING',
+        line: 1,
+        severity: 'MEDIUM',
+        message: `Nível máximo de aninhamento (${maxNestingDepth}) excede o limiar tolerado (${this.maxNesting}).`,
+        remediation: 'Aplique cláusulas de guarda (early return) e extraia métodos auxiliares.'
+      });
+    }
+
+    if (cyclomaticComplexity > this.maxComplexity) {
+      issues.push({
+        ruleId: 'QUALITY-HIGH-COMPLEXITY',
+        type: 'HIGH_CYCLOMATIC_COMPLEXITY',
+        line: 1,
+        severity: 'MEDIUM',
+        message: `Complexidade ciclomática (${cyclomaticComplexity}) excede o limite aceitável de ${this.maxComplexity}.`,
+        remediation: 'Decomponha funções complexas e substitua lógicas condicionais densas por polimorfismo ou tabelas de despacho.'
+      });
+    }
+
+    const isClean = issues.filter(i => i.severity === 'HIGH' || i.severity === 'CRITICAL').length === 0;
+
+    return {
+      filename,
+      status: isClean ? (issues.length === 0 ? 'OPTIMAL' : 'ACCEPTABLE_WITH_NOTES') : 'REFACTOR_REQUIRED',
+      metrics: {
+        totalLines,
+        codeLines: Math.max(0, totalLines - commentLines - blankLines),
+        commentLines,
+        blankLines,
+        cyclomaticComplexity,
+        maxNestingDepth
+      },
+      qualityScore: Math.max(0, 100 - (issues.length * 10) - (cyclomaticComplexity > this.maxComplexity ? 15 : 0)),
+      issues
+    };
+  }
+
+  /**
+   * Exporta a auditoria de qualidade em OASIS SARIF v2.1.0 oficial.
+   * @param {string} code 
+   * @param {string} [filename='snippet.js'] 
+   * @returns {object} SARIF v2.1.0 JSON object
+   */
+  auditToSarif(code, filename = 'snippet.js') {
+    const auditRes = this.auditCode(code, filename);
+    const findings = auditRes.issues.map(iss => ({
+      ruleId: iss.ruleId || iss.type,
+      name: iss.type,
+      severity: iss.severity,
+      filename: auditRes.filename,
+      line: iss.line || 1,
+      column: 1,
+      snippet: '',
+      message: iss.message,
+      remediation: iss.remediation || 'Refatore o código para eliminar a violação de qualidade.'
+    }));
+
+    return createSarifReport({
+      toolName: 'agent-master-code-quality-auditor',
+      toolVersion: '5.1.0',
+      findings,
+      properties: {
+        status: auditRes.status,
+        qualityScore: auditRes.qualityScore,
+        metrics: auditRes.metrics
+      }
+    });
+  }
+
+  /**
+   * Formata relatório executivo em Markdown para os Agentes e PR Reviewer.
+   * @param {object} audit 
+   * @returns {string}
+   */
+  formatReport(audit) {
+    let md = `## 🔬 Relatório de Qualidade de Código & Complexidade (AGENT DEVSECOPS & QA)\n\n`;
+    md += `**Alvo:** \`${audit.filename}\` | **Status:** ${audit.status === 'OPTIMAL' ? '✅ EXCELENTE (OPTIMAL)' : audit.status === 'ACCEPTABLE_WITH_NOTES' ? '⚠️ ACEITÁVEL COM NOTAS' : '❌ REFATORAÇÃO NECESSÁRIA'}\n\n`;
+    md += `### 📊 Métricas de Engenharia de Software (McCabe & Aninhamento)\n`;
+    md += `- **Complexidade Ciclomática v(G):** ${audit.metrics.cyclomaticComplexity} (Limite: ${this.maxComplexity})\n`;
+    md += `- **Profundidade Máxima de Aninhamento:** ${audit.metrics.maxNestingDepth} (Limite: ${this.maxNesting})\n`;
+    md += `- **Linhas de Código Efetivas:** ${audit.metrics.codeLines} / Total: ${audit.metrics.totalLines}\n`;
+    md += `- **Quality Score:** ${audit.qualityScore}/100\n\n`;
+
+    if (audit.issues.length > 0) {
+      md += `### ⚠️ Apontamentos de Qualidade & Débito Técnico\n\n`;
+      md += `| Linha | Tipo | Severidade | Mensagem | Remediação Recomendada |\n`;
+      md += `| :---: | :--- | :---: | :--- | :--- |\n`;
+      for (const iss of audit.issues) {
+        md += `| ${iss.line} | **${iss.type}** | **${iss.severity}** | ${iss.message} | ${iss.remediation || 'Refatoração requerida'} |\n`;
+      }
+      md += '\n';
+    } else {
+      md += `> 🌟 **Código Limpo:** Nenhuma violação ou anti-pattern detectado. Arquivo atende aos padrões de Clean Code.\n\n`;
+    }
+
+    return md;
+  }
+}
+
+module.exports = {
+  CodeQualityAuditor,
+  lexicalScan,
+  calculateCyclomaticComplexity,
+  calculateMaxNestingDepth
+};