agent-master-devsecops 0.0.0-stage → 3.9.0

package/scripts/confluence_sync.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/**
+ * scripts/confluence_sync.js
+ * 
+ * Sincronizador Automático Universal de ADRs, SPECs e Governança no Confluence em Tempo Real.
+ * Lê arquivos Markdown em docs/adr/*.md, docs/specs/*.md e docs/governance/*.md,
+ * converte para Confluence Storage Format (XHTML) e cria/atualiza páginas hierarquicamente.
+ * 
+ * 100% Desacoplado: detecta dinamicamente credenciais, Space Key e pastas pai.
+ * Governança: Tríade Git + Jira + Confluence (Regra 11 e Regra 15).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { getAtlassianCredentials, requestAtlassian } = require('./atlassian_client.js');
+
+const CONFLUENCE_CONFIG = {
+  spaceKey: process.env.CONFLUENCE_SPACE_KEY || process.env.ATLASSIAN_SPACE_KEY || 'DOCS',
+  adrParentId: process.env.CONFLUENCE_ADR_PARENT_ID || null,
+  specParentId: process.env.CONFLUENCE_SPEC_PARENT_ID || null,
+  govParentId: process.env.CONFLUENCE_GOV_PARENT_ID || null
+};
+
+function escapeHtml(text) {
+  return text
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+function parseLinks(text) {
+  let result = '';
+  let i = 0;
+  while (i < text.length) {
+    const openBracket = text.indexOf('[', i);
+    if (openBracket === -1) {
+      result += text.slice(i);
+      break;
+    }
+    result += text.slice(i, openBracket);
+    const closeBracket = text.indexOf(']', openBracket + 1);
+    if (closeBracket !== -1 && text[closeBracket + 1] === '(') {
+      const closeParen = text.indexOf(')', closeBracket + 2);
+      if (closeParen !== -1) {
+        const label = text.slice(openBracket + 1, closeBracket);
+        const url = text.slice(closeBracket + 2, closeParen);
+        result += `<a href="${url}">${label}</a>`;
+        i = closeParen + 1;
+        continue;
+      }
+    }
+    result += '[';
+    i = openBracket + 1;
+  }
+  return result;
+}
+
+function markdownToConfluenceStorage(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const elements = [];
+  let inCodeBlock = false;
+  let codeBuffer = [];
+  let codeLanguage = 'text';
+  let inList = false;
+
+  for (let idx = 0; idx < lines.length; idx++) {
+    const rawLine = lines[idx];
+
+    // Fenced Code Blocks
+    if (rawLine.trim().startsWith('```')) {
+      if (inCodeBlock) {
+        inCodeBlock = false;
+        const codeContent = escapeHtml(codeBuffer.join('\n'));
+        elements.push(
+          `<ac:structured-macro ac:name="code" ac:schema-version="1">` +
+          `<ac:parameter ac:name="language">${codeLanguage}</ac:parameter>` +
+          `<ac:parameter ac:name="linenumbers">true</ac:parameter>` +
+          `<ac:plain-text-body><![CDATA[${codeContent}]]></ac:plain-text-body>` +
+          `</ac:structured-macro>`
+        );
+        codeBuffer = [];
+        codeLanguage = 'text';
+      } else {
+        if (inList) {
+          elements.push('</ul>');
+          inList = false;
+        }
+        inCodeBlock = true;
+        const match = rawLine.trim().match(/^```([a-zA-Z0-9_-]*)/);
+        codeLanguage = match && match[1] ? match[1] : 'text';
+      }
+      continue;
+    }
+
+    if (inCodeBlock) {
+      codeBuffer.push(rawLine);
+      continue;
+    }
+
+    const trimmed = rawLine.trim();
+
+    // Linha vazia
+    if (!trimmed) {
+      if (inList) {
+        elements.push('</ul>');
+        inList = false;
+      }
+      continue;
+    }
+
+    // Separador horizontal
+    if (/^(\-{3,}|\*{3,}|_{3,})$/.test(trimmed)) {
+      if (inList) { elements.push('</ul>'); inList = false; }
+      elements.push('<hr />');
+      continue;
+    }
+
+    // Blockquote
+    if (trimmed.startsWith('>')) {
+      if (inList) { elements.push('</ul>'); inList = false; }
+      const quoteText = escapeHtml(trimmed.replace(/^>\s*/, ''));
+      elements.push(`<blockquote><p>${parseLinks(quoteText)}</p></blockquote>`);
+      continue;
+    }
+
+    // Cabeçalhos (h1 - h6)
+    const headerMatch = trimmed.match(/^(#{1,6})\s+(.*)$/);
+    if (headerMatch) {
+      if (inList) { elements.push('</ul>'); inList = false; }
+      const level = headerMatch[1].length;
+      const text = escapeHtml(headerMatch[2]);
+      elements.push(`<h${level}>${parseLinks(text)}</h${level}>`);
+      continue;
+    }
+
+    // Itens de lista com marcadores (* ou -)
+    const listMatch = trimmed.match(/^[-*]\s+(.*)$/);
+    if (listMatch) {
+      if (!inList) {
+        elements.push('<ul>');
+        inList = true;
+      }
+      const itemText = escapeHtml(listMatch[1]);
+      const formatted = itemText
+        .replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>')
+        .replace(/`([^`]+)`/g, '<code>$1</code>');
+      elements.push(`<li>${parseLinks(formatted)}</li>`);
+      continue;
+    }
+
+    // Parágrafo comum
+    if (inList) {
+      elements.push('</ul>');
+      inList = false;
+    }
+
+    const formattedPara = escapeHtml(trimmed)
+      .replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>')
+      .replace(/\*(.*?)\*/g, '<em>$1</em>')
+      .replace(/`([^`]+)`/g, '<code>$1</code>');
+
+    elements.push(`<p>${parseLinks(formattedPara)}</p>`);
+  }
+
+  if (inList) {
+    elements.push('</ul>');
+  }
+
+  return elements.join('');
+}
+
+function extractTitle(markdown, fallback) {
+  const lines = markdown.split(/\r?\n/);
+  for (const line of lines) {
+    const match = line.match(/^#\s+(.*)$/);
+    if (match) {
+      return match[1].trim();
+    }
+  }
+  return fallback;
+}
+
+async function findOrCreatePage(creds, spaceKey, title, parentId = null) {
+  const encodedTitle = encodeURIComponent(title);
+  const pathUrl = `/wiki/rest/api/content?spaceKey=${spaceKey}&title=${encodedTitle}&expand=version,ancestors`;
+  const searchRes = await requestAtlassian(creds, 'GET', pathUrl);
+
+  if (searchRes.status === 200 && searchRes.body.results && searchRes.body.results.length > 0) {
+    return searchRes.body.results[0];
+  }
+
+  // Se não existir e for pasta estrutural, cria
+  if (parentId !== undefined) {
+    const createPayload = {
+      type: 'page',
+      title,
+      space: { key: spaceKey },
+      body: {
+        storage: {
+          value: `<p>Seção de documentação gerada automaticamente pela Tríade Multiagente.</p>`,
+          representation: 'storage'
+        }
+      },
+      ...(parentId ? { ancestors: [{ id: parentId }] } : {})
+    };
+
+    const createRes = await requestAtlassian(creds, 'POST', '/wiki/rest/api/content', createPayload);
+    if (createRes.status === 200 || createRes.status === 201) {
+      return createRes.body;
+    }
+  }
+
+  return null;
+}
+
+async function syncDocument(creds, filePath, parentId) {
+  const rawMarkdown = fs.readFileSync(filePath, 'utf8');
+  const filename = path.basename(filePath, '.md');
+  const title = extractTitle(rawMarkdown, filename);
+  const storageHtml = markdownToConfluenceStorage(rawMarkdown);
+
+  const existingPage = await findOrCreatePage(creds, CONFLUENCE_CONFIG.spaceKey, title);
+
+  if (existingPage) {
+    const nextVersion = existingPage.version.number + 1;
+    const updatePayload = {
+      version: { number: nextVersion },
+      title: title,
+      type: 'page',
+      space: { key: CONFLUENCE_CONFIG.spaceKey },
+      body: {
+        storage: {
+          value: storageHtml,
+          representation: 'storage'
+        }
+      },
+      ...(parentId ? { ancestors: [{ id: parentId }] } : {})
+    };
+
+    const updateRes = await requestAtlassian(creds, 'PUT', `/wiki/rest/api/content/${existingPage.id}`, updatePayload);
+    if (updateRes.status === 200) {
+      console.log(`[Confluence Sync] ✔ Atualizada: "${title}" (ID: ${existingPage.id}, v${nextVersion})`);
+      return { success: true, id: existingPage.id, action: 'updated' };
+    } else {
+      console.error(`[Confluence Sync] ✖ Falha ao atualizar "${title}": HTTP ${updateRes.status}`);
+      return { success: false, error: updateRes.body };
+    }
+  } else {
+    const createPayload = {
+      type: 'page',
+      title: title,
+      space: { key: CONFLUENCE_CONFIG.spaceKey },
+      body: {
+        storage: {
+          value: storageHtml,
+          representation: 'storage'
+        }
+      },
+      ...(parentId ? { ancestors: [{ id: parentId }] } : {})
+    };
+
+    const createRes = await requestAtlassian(creds, 'POST', '/wiki/rest/api/content', createPayload);
+    if (createRes.status === 200 || createRes.status === 201) {
+      console.log(`[Confluence Sync] 🚀 Criada: "${title}" (ID: ${createRes.body.id})`);
+      return { success: true, id: createRes.body.id, action: 'created' };
+    } else {
+      console.error(`[Confluence Sync] ✖ Falha ao criar "${title}": HTTP ${createRes.status}`);
+      return { success: false, error: createRes.body };
+    }
+  }
+}
+
+async function runSync() {
+  const creds = getAtlassianCredentials();
+  if (!creds) {
+    console.error('[Confluence Sync] ✖ Credenciais Atlassian não configuradas. Sincronização ignorada.');
+    return;
+  }
+
+  console.log(`[Confluence Sync] Espaço alvo: "${CONFLUENCE_CONFIG.spaceKey}".`);
+
+  // Descoberta dinâmica de pastas estruturais
+  let adrParent = CONFLUENCE_CONFIG.adrParentId;
+  let specParent = CONFLUENCE_CONFIG.specParentId;
+  let govParent = CONFLUENCE_CONFIG.govParentId;
+
+  if (!adrParent) {
+    const p = await findOrCreatePage(creds, CONFLUENCE_CONFIG.spaceKey, 'Decisões de Arquitetura (ADRs)');
+    if (p) adrParent = p.id;
+  }
+  if (!specParent) {
+    const p = await findOrCreatePage(creds, CONFLUENCE_CONFIG.spaceKey, 'Especificações Técnicas (SPECs)');
+    if (p) specParent = p.id;
+  }
+  if (!govParent) {
+    const p = await findOrCreatePage(creds, CONFLUENCE_CONFIG.spaceKey, 'Governança & Padrões Multiagente');
+    if (p) govParent = p.id;
+  }
+
+  const targets = [
+    { dir: path.resolve('docs/adr'), parentId: adrParent },
+    { dir: path.resolve('docs/specs'), parentId: specParent },
+    { dir: path.resolve('docs/governance'), parentId: govParent }
+  ];
+
+  let total = 0;
+  for (const target of targets) {
+    if (fs.existsSync(target.dir)) {
+      const files = fs.readdirSync(target.dir).filter(f => f.endsWith('.md'));
+      for (const f of files) {
+        await syncDocument(creds, path.join(target.dir, f), target.parentId);
+        total++;
+      }
+    }
+  }
+
+  console.log(`[Confluence Sync] Finalizado: ${total} documentos processados com sucesso.`);
+}
+
+if (require.main === module) {
+  runSync().catch(err => {
+    console.error('[Confluence Sync] Erro fatal:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  escapeHtml,
+  parseLinks,
+  markdownToConfluenceStorage,
+  extractTitle,
+  syncDocument,
+  runSync
+};

package/scripts/context_compressor.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * scripts/context_compressor.js
+ * 
+ * Compactador Semântico de Contexto para Modelos Locais (AGDEV-22 / I-6).
+ * Destila o prompt canônico e regras do Agent Master em menos de 1.500 tokens (~6.000 chars),
+ * preservando 100% da autoridade normativa, as 15 Regras de Ouro, os 5 Modos e o Tríplice Registro.
+ * 
+ * Otimizado para execução com baixa latência em Ollama (Llama 3.1 8B, Qwen 2.5 Coder, Mistral 7B).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.resolve(__dirname, '..');
+
+function estimateTokens(text) {
+  if (!text) return 0;
+  // Estimativa padrão da indústria para modelos baseados em BPE/WordPiece (~4 caracteres por token em média)
+  return Math.ceil(text.trim().length / 4);
+}
+
+function generateCompactPrompt() {
+  return `=== AGENT ORCHESTRATOR & SUÍTE MULTI-AGENTE (LOCAL HIGH-DENSITY EDITION v3.2) ===
+[DIRETIVA SUPREMA]: Você é o AGENT ORCHESTRATOR da Suíte Multi-Agente (Orchestrator, DevSecOps, QA, Scrum e SRE). Atue como Arquiteto, Engenheiro Sênior, Especialista em Segurança e Auditor Cético.
+[COMPATIBILIDADE]: Otimizado para modelos locais (Ollama, vLLM, LM Studio). Siga rigorosamente sem desvios.
+
+[15 REGRAS DE OURO NORMATIVAS]:
+R1. TDD Obrigatório: Escreva ou valide testes unitários ANTES de modificar código de produção.
+R2. Branching por Ticket: Trabalhe sempre em branch dedicada exclusivamente com o identificador <TICKET> (ex: PROJ-065878). Nunca comite direto em main.
+R3. Pull Request & CI: Todo merge exige PR formal no GitHub com 100% dos checks de CI (TruffleHog, testes e validação) verdes.
+R4. Zero Segredos (TruffleHog): NUNCA comite credenciais, arquivos .env, tokens de API ou chaves privadas.
+R5. Defesa DevSecOps & OWASP: Imunidade a CWE-78 (Cmd Injection), CWE-79 (XSS), CWE-89 (SQLi), CWE-116 (Sanitização) e CWE-1333 (ReDoS).
+R6. Observabilidade Nativa: Exponha /metrics no padrão Prometheus 0.0.4 (CPU, Heap/RSS, latências).
+R7. Protocolo Dual-Layer: Chat curto e objetivo com tópicos separados por LINHA EM BRANCO DUPLA (\\n\\n) e links markdown clicáveis.
+R8. Bíblia Confluence: Toda decisão arquitetural exige novo ADR canônico no Confluence.
+R9. Governança Jira: Mova cards para 'Em andamento' antes de iniciar; finalize com relatório técnico denso de 15 seções.
+R10. Zero Suposições: Se os requisitos forem ambíguos, esclareça com o usuário ou inspecione o código antes de agir.
+R11. Integridade de Documentação: Preserve comentários, docstrings e contratos de API pré-existentes.
+R12. Segurança Operacional: NUNCA execute comandos destrutivos (rm -rf, git reset --hard não planejado, drop database).
+R13. Ceticismo Adversário (AGENT_QA.md): Audite diffs com frieza cética; forneça testes de quebra e nunca aprove código sem testes.
+R14. Filtro de Sanidade de Ideias: Ideias em docs/IDEAS.md devem ter conexão 100% direta com o domínio e stack real do projeto.
+R15. Imutabilidade & Segredos Compulsórios: Requisitos do fluxo são imutáveis e inquebráveis. Valide e obtenha ativamente todas as credenciais (GitHub, Jira, Confluence) com zero falhas silenciosas.
+
+[TRÍPLICE REGISTRO]:
+1. Git: Branch dedicada -> Testes locais -> Commit no formato [<TICKET>] - <Ações breves em português> -> PR formal -> CI verde -> Merge.
+2. Jira: 'A fazer' -> 'Em andamento' -> Comentário Canônico (15 seções) -> 'Concluído'.
+3. Confluence: Registro contínuo de novos ADRs na Bíblia do Projeto.
+
+[MODOS DE OPERAÇÃO]:
+- modo: orchestrator: Coordenação central, triagem e despacho de tarefas.
+- modo: devsecops: Implementação de código robusto, arquitetura limpa e esteiras CI/CD.
+- modo: qa: Auditoria adversária independente de PR e emissão de parecer canônico.
+- modo: scrum: Gestão ágil, melhoria contínua (PDCA/Ishikawa) e backlog recursivo.
+- modo: sre: Observabilidade contínua (/metrics), telemetria e auto-remediação.
+- modo: full-dev: Loop autônomo contínuo: estuda ideia -> implementa -> testa -> registra -> avança sem parar.
+
+[PROTOCOLO DE SAÍDA NO CHAT]:
+• **Feito 1** ([Jira TICKET](url) · [Commit abc](url))
+  Descrição direta do feito.
+
+• **Feito 2** ([Confluence ADR](url) · [PR #X](url))
+  Detalhe objetivo do teste ou entrega.
+(Obrigatória linha em branco dupla entre tópicos)`;
+}
+
+function compressCustomText(text, maxTokens = 1500) {
+  if (!text) return '';
+  
+  // 1. Remove comentários de cabeçalho prolixos e tags html vazias
+  let cleaned = text
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<[^>]+>/g, '')
+    .replace(/\r\n/g, '\n');
+
+  // 2. Remove emojis e caracteres decorativos excessivos
+  cleaned = cleaned.replace(/[\u{1F600}-\u{1F64F}\u{1F300}-\u{1F5FF}\u{1F680}-\u{1F6FF}\u{1F1E0}-\u{1F1FF}\u{2700}-\u{27BF}\u{2600}-\u{26FF}]/gu, '');
+
+  // 3. Compactação de linhas em branco consecutivas
+  cleaned = cleaned.replace(/\n{3,}/g, '\n\n');
+
+  // 4. Se ainda ultrapassar maxTokens, aplica sumarização imperativa
+  const currentTokens = estimateTokens(cleaned);
+  if (currentTokens > maxTokens) {
+    const compactBase = generateCompactPrompt();
+    return compactBase;
+  }
+
+  return cleaned.trim();
+}
+
+function exportCompactAgent(targetDir = ROOT_DIR) {
+  const compactDir = path.join(targetDir, 'agents', 'compact');
+  if (!fs.existsSync(compactDir)) {
+    fs.mkdirSync(compactDir, { recursive: true });
+  }
+
+  const promptContent = generateCompactPrompt();
+  const filePath = path.join(compactDir, 'AGENT_ORCHESTRATOR_COMPACTO.md');
+  fs.writeFileSync(filePath, promptContent, 'utf8');
+
+  const tokens = estimateTokens(promptContent);
+  return {
+    filePath,
+    tokenCount: tokens,
+    charCount: promptContent.length,
+    underBudget: tokens <= 1500
+  };
+}
+
+async function runCli() {
+  const args = process.argv.slice(2);
+  const result = exportCompactAgent(ROOT_DIR);
+
+  console.log('=== Compactador Semântico de Contexto para Modelos Locais (I-6) ===');
+  console.log(`Arquivo Gerado: ${result.filePath}`);
+  console.log(`Caracteres: ${result.charCount}`);
+  console.log(`Tokens Estimados: ${result.tokenCount} (Orçamento máximo: 1.500)`);
+  console.log(`Status de Conformidade: ${result.underBudget ? 'DENTRO DO ORÇAMENTO (APROVADO)' : 'ULTRA-PASSADO'}`);
+
+  if (args.includes('--print')) {
+    console.log('\n--- Conteúdo Destilado ---\n');
+    console.log(fs.readFileSync(result.filePath, 'utf8'));
+  }
+}
+
+if (require.main === module) {
+  runCli().catch(err => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  estimateTokens,
+  generateCompactPrompt,
+  compressCustomText,
+  exportCompactAgent
+};

package/scripts/contract_test_validator.js

@@ -0,0 +1,166 @@
+/**
+ * scripts/contract_test_validator.js
+ * Auditor de Contratos OpenAPI / Swagger & Detecção de Drift de API (Loop 2)
+ * 
+ * Implementa validação arquitetural de contratos de dados:
+ * - Validação sintática e estrutural de especificações OpenAPI 3.x / Swagger 2.0
+ * - Verificação de completude (operações sem summary, responses ou operationId)
+ * - Detecção bidirecional de Drift entre contrato e código:
+ *   a) Shadow APIs (rotas implementadas sem documentação no contrato)
+ *   b) Unimplemented Endpoints (rotas prometidas no contrato mas ausentes no código)
+ * - Cálculo de cobertura de conformidade do contrato de dados.
+ */
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Normaliza caminho de rota para comparação ignorando parâmetros de template ({id} vs :id)
+ * @param {string} routePath 
+ * @returns {string}
+ */
+function normalizeRoutePath(routePath) {
+  if (!routePath || typeof routePath !== 'string') return '/';
+  return routePath
+    .trim()
+    .replace(/\/+$/, '')
+    .replace(/\{[^}]+\}/g, ':param')
+    .replace(/:[a-zA-Z0-9_]+/g, ':param')
+    .toLowerCase();
+}
+
+/**
+ * Valida especificação OpenAPI e audita contra rotas implementadas.
+ * @param {string|object} specInput 
+ * @param {Array<{method: string, path: string}>} [implementedRoutes=[]] 
+ * @returns {object}
+ */
+function validateOpenApiContract(specInput, implementedRoutes = []) {
+  let spec;
+  try {
+    if (typeof specInput === 'string') {
+      if (fs.existsSync(specInput)) {
+        spec = JSON.parse(fs.readFileSync(specInput, 'utf8'));
+      } else {
+        spec = JSON.parse(specInput);
+      }
+    } else if (typeof specInput === 'object' && specInput !== null) {
+      spec = specInput;
+    } else {
+      throw new Error('Entrada da especificação inválida.');
+    }
+  } catch (err) {
+    return {
+      valid: false,
+      compliant: false,
+      error: `Erro ao processar contrato OpenAPI: ${err.message}`,
+      drifts: []
+    };
+  }
+
+  // 1. Validação Estrutural Básica
+  const isOpenApi = Boolean(spec.openapi || spec.swagger);
+  const paths = spec.paths || {};
+  const pathsList = Object.keys(paths);
+
+  const missingSummaries = [];
+  const missingResponses = [];
+  const documentedOperations = [];
+
+  const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head'];
+
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== 'object') continue;
+
+    for (const method of HTTP_METHODS) {
+      const op = pathItem[method];
+      if (!op) continue;
+
+      const opInfo = {
+        method: method.toUpperCase(),
+        path: pathStr,
+        normalizedPath: normalizeRoutePath(pathStr),
+        operationId: op.operationId || null,
+        summary: op.summary || null
+      };
+      documentedOperations.push(opInfo);
+
+      if (!op.summary) {
+        missingSummaries.push(`${opInfo.method} ${pathStr}`);
+      }
+      if (!op.responses || Object.keys(op.responses).length === 0) {
+        missingResponses.push(`${opInfo.method} ${pathStr}`);
+      }
+    }
+  }
+
+  // 2. Detecção de Drift com Código Implementado (se fornecido)
+  const normalizedImplemented = (implementedRoutes || []).map(r => ({
+    method: String(r.method || 'GET').toUpperCase(),
+    path: r.path,
+    normalizedPath: normalizeRoutePath(r.path)
+  }));
+
+  const shadowApis = [];
+  const unimplementedEndpoints = [];
+
+  // Checar Shadow APIs (código tem rota não declarada na spec)
+  for (const imp of normalizedImplemented) {
+    const foundInDoc = documentedOperations.some(
+      doc => doc.method === imp.method && doc.normalizedPath === imp.normalizedPath
+    );
+    if (!foundInDoc) {
+      shadowApis.push({
+        method: imp.method,
+        path: imp.path,
+        reason: 'Rota implementada em código porém ausente na especificação OpenAPI (Shadow API / Risco de Segurança)'
+      });
+    }
+  }
+
+  // Checar Unimplemented Endpoints (spec declara rota ausente no código)
+  if (normalizedImplemented.length > 0) {
+    for (const doc of documentedOperations) {
+      const foundInCode = normalizedImplemented.some(
+        imp => imp.method === doc.method && imp.normalizedPath === doc.normalizedPath
+      );
+      if (!foundInCode) {
+        unimplementedEndpoints.push({
+          method: doc.method,
+          path: doc.path,
+          reason: 'Rota declarada no contrato OpenAPI porém ainda não implementada no código'
+        });
+      }
+    }
+  }
+
+  const structuralIssues = missingResponses.length + (isOpenApi ? 0 : 1);
+  const valid = structuralIssues === 0 && Boolean(spec.info);
+  const compliant = valid && shadowApis.length === 0;
+
+  const totalEvaluated = documentedOperations.length;
+  const coveragePercent = totalEvaluated > 0
+    ? Math.round(((totalEvaluated - unimplementedEndpoints.length) / totalEvaluated) * 100)
+    : 100;
+
+  return {
+    valid,
+    compliant,
+    version: spec.openapi || spec.swagger || 'Desconhecida',
+    title: (spec.info && spec.info.title) || 'Sem título',
+    totalPaths: pathsList.length,
+    totalOperations: documentedOperations.length,
+    missingSummaries,
+    missingResponses,
+    shadowApis,
+    unimplementedEndpoints,
+    coveragePercent,
+    driftsCount: shadowApis.length + unimplementedEndpoints.length,
+    verdict: compliant ? 'CONFORME' : 'DRIFT_DETECTADO'
+  };
+}
+
+module.exports = {
+  validateOpenApiContract,
+  normalizeRoutePath
+};