agent-master-devsecops 3.9.0 → 5.1.0

package/scripts/auditors/git_hygiene_linter.js

@@ -0,0 +1,391 @@
+/**
+ * scripts/auditors/git_hygiene_linter.js
+ * Auditor Local de Commits & Branches — Regra 11 de Engenharia & Princípio 3 (v5.1 Enterprise)
+ * 
+ * Implementa validação estrita de nomenclatura de branches e sintaxe de commits:
+ * - Commit Canônico: [<TICKET>] - <Ação em português>
+ * - Proibição total de Conventional Commits (feat:, fix:, chore:, etc.)
+ * - Proibição de prefixos legados em branches (feature/**, fix/**, hotfix/**)
+ * - Emissão de relatórios oficiais no padrão OASIS SARIF v2.1.0 (auditToSarif)
+ * - Instalação de hooks locais nativos (.git/hooks/commit-msg) sem dependências externas.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+const TICKET_REGEX = /^[A-Z][A-Z0-9_]+-\d+$/;
+const BRANCH_CANONICAL_REGEX = /^([A-Z][A-Z0-9_]+-\d+)(?:-[a-z0-9-]+)?$/;
+const COMMIT_REGEX = /^\[([A-Z][A-Z0-9_]+-\d+|GOV|CD|SETUP|RELEASE|INIT)\]\s*-\s*(.+)$/;
+const FORBIDDEN_COMMIT_PREFIXES = /^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|wip)(\(.*\))?:\s*/i;
+const FORBIDDEN_BRANCH_PREFIXES = /^(feature|feat|fix|bugfix|hotfix|chore|refactor)\//i;
+
+/**
+ * Classe principal do Auditor de Higiene de Git e Rastreabilidade.
+ */
+class GitHygieneLinter {
+  constructor(options = {}) {
+    this.options = options;
+  }
+
+  /**
+   * Valida sintaxe da mensagem de commit contra a Regra 11 e Princípio 3.
+   * 
+   * @param {string} message 
+   * @returns {{ valid: boolean, ticket?: string, action?: string, cleanMessage?: string, reason?: string }}
+   */
+  lintCommitMessage(message) {
+    if (!message || typeof message !== 'string') {
+      return { valid: false, reason: 'Mensagem de commit vazia ou indefinida.' };
+    }
+
+    const cleanMsg = message.trim().split('\n')[0].trim();
+    if (!cleanMsg) {
+      return { valid: false, reason: 'Mensagem de commit vazia ou em branco.' };
+    }
+
+    // 0. Permitir commits de Merge/Revert gerados pelo Git/GitHub
+    if (/^(Merge\b|Revert\b)/i.test(cleanMsg)) {
+      return { valid: true, ticket: 'MERGE', cleanMessage: cleanMsg };
+    }
+
+    // 1. Proibir Conventional Commits
+    if (FORBIDDEN_COMMIT_PREFIXES.test(cleanMsg)) {
+      return {
+        valid: false,
+        reason: 'Violação da Regra 11: Conventional Commits (feat:, fix:, chore:, etc.) são terminantemente proibidos. Use exclusivamente [<TICKET>] - <Ação em português>.'
+      };
+    }
+
+    // 2. Verificar formato canônico [<TICKET>] - <Ação>
+    const match = cleanMsg.match(COMMIT_REGEX);
+    if (!match) {
+      return {
+        valid: false,
+        reason: 'Violação da Regra 11: A mensagem de commit deve seguir estritamente o formato: [<TICKET>] - <Ação em português>. Ex: [PROJ-123] - Implementar rate limit defensivo'
+      };
+    }
+
+    const ticket = match[1];
+    const action = match[2].trim();
+
+    if (action.length < 3) {
+      return {
+        valid: false,
+        reason: 'Violação da Regra 11: A descrição da ação no commit deve conter pelo menos 3 caracteres substantivos.'
+      };
+    }
+
+    return {
+      valid: true,
+      ticket,
+      action,
+      cleanMessage: cleanMsg
+    };
+  }
+
+  /**
+   * Valida a nomenclatura de uma branch contra a Regra 11 e Princípio 3.
+   * 
+   * @param {string} branchName 
+   * @returns {{ valid: boolean, branch?: string, ticket?: string, reason?: string }}
+   */
+  lintBranchName(branchName) {
+    if (!branchName || typeof branchName !== 'string') {
+      return { valid: false, reason: 'Nome de branch vazio ou indefinido.' };
+    }
+
+    const branch = branchName.trim().replace(/^refs\/heads\//, '');
+    if (!branch) {
+      return { valid: false, reason: 'Nome de branch vazio após sanitização.' };
+    }
+
+    // Permitir branches primárias canônicas
+    if (['main', 'master', 'develop'].includes(branch)) {
+      return { valid: true, branch, ticket: null };
+    }
+
+    // Proibir prefixos legados
+    if (FORBIDDEN_BRANCH_PREFIXES.test(branch)) {
+      return {
+        valid: false,
+        reason: `Violação da Regra 11: Prefixos legados (feature/**, fix/**, etc.) são proibidos. A branch deve conter a chave do ticket (ex: PROJ-123 ou PROJ-123-descricao). Recebido: "${branch}".`
+      };
+    }
+
+    // A branch de tarefa deve se chamar o Ticket ou Ticket com slug descritivo
+    const match = branch.match(BRANCH_CANONICAL_REGEX);
+    if (!match) {
+      return {
+        valid: false,
+        reason: `Violação da Regra 11: O nome da branch de tarefa deve conter a chave do ticket (ex: PROJ-123 ou PROJ-123-descricao-semantica). Recebido: "${branch}".`
+      };
+    }
+
+    const ticket = match[1];
+    return {
+      valid: true,
+      branch,
+      ticket
+    };
+  }
+
+  /**
+   * Inspeciona o estado atual do repositório Git local com timeouts seguros.
+   * 
+   * @param {string} [repoDir=process.cwd()] 
+   * @returns {{ compliant: boolean, currentBranch: string, lastCommit: string, branchAudit: object, commitAudit: object }}
+   */
+  auditGitState(repoDir = process.cwd()) {
+    let currentBranch = 'unknown';
+    let lastCommit = '';
+
+    if (process.env.GITHUB_HEAD_REF) {
+      currentBranch = process.env.GITHUB_HEAD_REF;
+    } else {
+      try {
+        currentBranch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+          cwd: repoDir,
+          encoding: 'utf8',
+          timeout: 3000,
+          stdio: ['pipe', 'pipe', 'ignore']
+        }).trim();
+      } catch (_err) {
+        currentBranch = '';
+      }
+      if (currentBranch === 'HEAD' && process.env.GITHUB_REF_NAME) {
+        currentBranch = process.env.GITHUB_REF_NAME;
+      }
+    }
+
+    try {
+      lastCommit = execFileSync('git', ['log', '-1', '--pretty=%B'], {
+        cwd: repoDir,
+        encoding: 'utf8',
+        timeout: 3000,
+        stdio: ['pipe', 'pipe', 'ignore']
+      }).trim();
+    } catch (_err) {
+      lastCommit = '';
+    }
+
+    const branchAudit = this.lintBranchName(currentBranch);
+    const commitAudit = lastCommit ? this.lintCommitMessage(lastCommit) : { valid: true, reason: 'Nenhum commit encontrado no histórico.' };
+    const compliant = branchAudit.valid && commitAudit.valid;
+
+    return {
+      compliant,
+      currentBranch,
+      lastCommit,
+      branchAudit,
+      commitAudit
+    };
+  }
+
+  /**
+   * Exporta os apontamentos de higiene Git em OASIS SARIF v2.1.0 oficial.
+   * 
+   * @param {object} params 
+   * @param {string} [params.branchName]
+   * @param {string} [params.commitMessage]
+   * @param {string} [params.repoDir]
+   * @returns {object} SARIF v2.1.0 JSON object
+   */
+  auditToSarif(params = {}) {
+    const findings = [];
+    let branchAudit;
+    let commitAudit;
+
+    if (params.branchName) {
+      branchAudit = this.lintBranchName(params.branchName);
+      if (!branchAudit.valid) {
+        findings.push({
+          ruleId: 'GIT-HYGIENE-BRANCH',
+          name: 'Nome de Branch Fora do Padrão Canônico',
+          severity: 'HIGH',
+          filename: '.git/HEAD',
+          line: 1,
+          column: 1,
+          snippet: params.branchName,
+          message: branchAudit.reason,
+          remediation: 'Renomeie a branch para seguir o padrão: <TICKET> ou <TICKET>-slug (ex: git branch -m PROJ-123-descricao).'
+        });
+      }
+    }
+
+    if (params.commitMessage) {
+      commitAudit = this.lintCommitMessage(params.commitMessage);
+      if (!commitAudit.valid) {
+        findings.push({
+          ruleId: 'GIT-HYGIENE-COMMIT',
+          name: 'Mensagem de Commit Não Rastreável ou Conventional Commit Proibido',
+          severity: 'HIGH',
+          filename: '.git/COMMIT_EDITMSG',
+          line: 1,
+          column: 1,
+          snippet: params.commitMessage.split('\n')[0],
+          message: commitAudit.reason,
+          remediation: 'Formate a mensagem do commit seguindo estritamente: [<TICKET>] - <Ação em português>.'
+        });
+      }
+    }
+
+    if (!params.branchName && !params.commitMessage) {
+      const state = this.auditGitState(params.repoDir);
+      if (!state.branchAudit.valid) {
+        findings.push({
+          ruleId: 'GIT-HYGIENE-BRANCH',
+          name: 'Nome de Branch Atual Fora do Padrão Canônico',
+          severity: 'HIGH',
+          filename: '.git/HEAD',
+          line: 1,
+          column: 1,
+          snippet: state.currentBranch,
+          message: state.branchAudit.reason,
+          remediation: 'Renomeie a branch para o padrão: <TICKET> ou <TICKET>-slug.'
+        });
+      }
+      if (!state.commitAudit.valid) {
+        findings.push({
+          ruleId: 'GIT-HYGIENE-COMMIT',
+          name: 'Último Commit Fora do Padrão Canônico',
+          severity: 'HIGH',
+          filename: '.git/COMMIT_EDITMSG',
+          line: 1,
+          column: 1,
+          snippet: state.lastCommit.split('\n')[0],
+          message: state.commitAudit.reason,
+          remediation: 'Reescreva a mensagem com git commit --amend.'
+        });
+      }
+    }
+
+    return createSarifReport({
+      toolName: 'agent-master-git-hygiene-linter',
+      toolVersion: '5.1.0',
+      findings,
+      properties: {
+        compliant: findings.length === 0,
+        branchAudit: branchAudit || null,
+        commitAudit: commitAudit || null
+      }
+    });
+  }
+
+  /**
+   * Formata relatório executivo em Markdown para os Agentes e PR Reviewer.
+   * 
+   * @param {object} auditResult 
+   * @returns {string}
+   */
+  formatReport(auditResult) {
+    let md = `## 🌿 Relatório de Higiene de Git & Rastreabilidade (Regra 11 — Princípio 3)\n\n`;
+    const isCompliant = (auditResult.commitAudit ? auditResult.commitAudit.valid : true) &&
+                        (auditResult.branchAudit ? auditResult.branchAudit.valid : true) &&
+                        (auditResult.compliant !== false);
+
+    md += `**Status de Conformidade:** ${isCompliant ? '✅ CONFORME' : '❌ VIOLAÇÃO DETECTADA'}\n\n`;
+
+    if (auditResult.branchAudit) {
+      md += `### 📌 Auditoria de Branch\n`;
+      md += `- **Branch:** \`${auditResult.currentBranch || auditResult.branchAudit.branch || 'N/A'}\`\n`;
+      md += `- **Válida:** ${auditResult.branchAudit.valid ? '✅ SIM' : '❌ NÃO'}\n`;
+      if (!auditResult.branchAudit.valid) {
+        md += `- **Motivo:** ${auditResult.branchAudit.reason}\n`;
+      } else if (auditResult.branchAudit.ticket) {
+        md += `- **Ticket Vinculado:** \`${auditResult.branchAudit.ticket}\`\n`;
+      }
+      md += '\n';
+    }
+
+    if (auditResult.commitAudit) {
+      md += `### 📝 Auditoria de Commit\n`;
+      md += `- **Válido:** ${auditResult.commitAudit.valid ? '✅ SIM' : '❌ NÃO'}\n`;
+      if (!auditResult.commitAudit.valid) {
+        md += `- **Motivo:** ${auditResult.commitAudit.reason}\n`;
+      } else if (auditResult.commitAudit.ticket) {
+        md += `- **Ticket Vinculado:** \`${auditResult.commitAudit.ticket}\`\n`;
+        md += `- **Mensagem Limpa:** \`${auditResult.commitAudit.cleanMessage}\`\n`;
+      }
+      md += '\n';
+    }
+
+    return md;
+  }
+}
+
+const defaultLinter = new GitHygieneLinter();
+
+function lintCommitMessage(message) {
+  return defaultLinter.lintCommitMessage(message);
+}
+
+function lintBranchName(branchName) {
+  return defaultLinter.lintBranchName(branchName);
+}
+
+function auditGitState(repoDir) {
+  return defaultLinter.auditGitState(repoDir);
+}
+
+/**
+ * Instala hooks nativos de Git (.git/hooks/commit-msg) sem dependências externas.
+ * 
+ * @param {string} [repoDir=process.cwd()] 
+ * @returns {{ installed: boolean, hooksPath?: string, message: string }}
+ */
+function installGitHooks(repoDir = process.cwd()) {
+  const hooksDir = path.join(repoDir, '.git', 'hooks');
+  if (!fs.existsSync(path.join(repoDir, '.git'))) {
+    return { installed: false, message: 'Diretório .git não encontrado. Repositório não inicializado.' };
+  }
+
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+
+  const commitMsgHook = path.join(hooksDir, 'commit-msg');
+  const hookScript = `#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const msgFile = process.argv[2];
+if (!msgFile) process.exit(0);
+
+const msg = fs.readFileSync(msgFile, 'utf8');
+const COMMIT_REGEX = /^\\[([A-Z][A-Z0-9_]+-\\d+|GOV|CD|SETUP|RELEASE|INIT)\\]\\s*-\\s*.+$/;
+const FORBIDDEN = /^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|wip)(\\(.*\\))?:\\s*/i;
+
+const firstLine = msg.trim().split('\\n')[0].trim();
+if (FORBIDDEN.test(firstLine)) {
+  console.error('\\n❌ [REGRA 11] ERRO NO COMMIT: Conventional Commits são proibidos!');
+  console.error('Use estritamente: [<TICKET>] - <Ação em português>\\n');
+  process.exit(1);
+}
+
+if (!COMMIT_REGEX.test(firstLine)) {
+  console.error('\\n❌ [REGRA 11] ERRO NO COMMIT: Formato inválido!');
+  console.error('Esperado: [<TICKET>] - <Ação em português>');
+  console.error('Recebido: ' + firstLine + '\\n');
+  process.exit(1);
+}
+`;
+
+  fs.writeFileSync(commitMsgHook, hookScript, { mode: 0o755 });
+  return {
+    installed: true,
+    hooksPath: commitMsgHook,
+    message: 'Git hook commit-msg instalado com sucesso para conformidade da Regra 11.'
+  };
+}
+
+module.exports = {
+  GitHygieneLinter,
+  lintCommitMessage,
+  lintBranchName,
+  auditGitState,
+  installGitHooks,
+  TICKET_REGEX,
+  COMMIT_REGEX
+};