agent-master-devsecops 3.9.0 → 5.1.0

package/scripts/core/architecture_advisor.js

@@ -0,0 +1,378 @@
+/**
+ * scripts/core/architecture_advisor.js
+ * 
+ * Motor de Consultoria Arquitetural Agnóstica & Avaliação de Engenharia de Valor.
+ * Implementa o Architecture Tradeoff Analysis Method (ATAM) e Architecture Fitness Functions.
+ * 
+ * Filosofia: "Linguagens são ferramentas. Pessoas são ideias."
+ * O Advisor atua como um Staff/Principal Architect independente: diagnostica requisitos
+ * funcionais e não-funcionais (Throughput, Consistência, Criticidade, Time-to-Market, TCO),
+ * avalia formalmente trade-offs de engenharia e recomenda o padrão arquitetural ideal,
+ * alertando friamente contra overengineering e complexidade acidental.
+ */
+
+'use strict';
+
+// Estilos Arquiteturais Canônicos
+const ARCHITECTURE_STYLES = Object.freeze({
+  ZERO_DEPENDENCY_WEB: 'Single-File Web App (Zero-Dependency Native Web)',
+  MODULAR_MONOLITH: 'Modular Monolith (DDD / Clean Core)',
+  HEXAGONAL_EVENT_SOURCED: 'Hexagonal / Ports & Adapters (Strict Transactional Ledger)',
+  EVENT_DRIVEN_PIPELINE: 'Event-Driven / Pipe & Filter (Reactive Stream Processing)',
+  DISTRIBUTED_MICROSERVICES: 'Distributed Microservices (Bounded Contexts with Event Mesh)'
+});
+
+// Perfis de Carga de Trabalho
+const WORKLOAD_PROFILES = Object.freeze({
+  CLIENT_INTERACTIVE: 'client_interactive',
+  TRANSACTIONAL_OLTP: 'transactional_oltp',
+  STREAM_PROCESSING: 'stream_processing',
+  BATCH_ANALYTICS: 'batch_analytics',
+  STANDALONE_UTILITY: 'standalone_utility'
+});
+
+const { getKnowledgeGateway } = require('./knowledge_gateway.js');
+
+class ArchitectureAdvisor {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.gateway = options.gateway || getKnowledgeGateway(options);
+  }
+
+  /**
+   * Diagnostica a disponibilidade real das toolchains e compiladores no host local.
+   */
+  detectHostToolchains() {
+    const { spawnSync } = require('node:child_process');
+    const isWin = process.platform === 'win32';
+    const checker = isWin ? 'where.exe' : 'which';
+    const toolchains = {};
+    const tools = ['node', 'npm', 'go', 'rustc', 'javac', 'python', 'docker'];
+
+    for (const tool of tools) {
+      try {
+        const res = spawnSync(checker, [tool], { encoding: 'utf8', timeout: 500 });
+        if (res.status === 0 && res.stdout && res.stdout.trim().length > 0) {
+          toolchains[tool] = { installed: true, path: res.stdout.trim().split('\r\n')[0].split('\n')[0] };
+        } else {
+          toolchains[tool] = { installed: false, error: 'not_found' };
+        }
+      } catch {
+        toolchains[tool] = { installed: false, error: 'exception' };
+      }
+    }
+    return toolchains;
+  }
+
+  /**
+   * Normaliza os requisitos brutos em dimensões formais de engenharia de software.
+   */
+  normalizeRequirements(spec = {}) {
+    const rawDesc = (spec.description || '').toLowerCase();
+    const rawDomain = (spec.domain || '').toLowerCase();
+    const rawScale = (spec.scale || '').toLowerCase();
+    const rawCriticality = (spec.criticality || '').toLowerCase();
+    const rawTeam = (spec.teamSize || '').toLowerCase();
+
+    // 1. Workload Profile
+    let workload = spec.workloadProfile || null;
+    if (!workload) {
+      if (rawScale === 'prototype' || rawDesc.includes('calculadora') || rawDesc.includes('aprend') || rawDesc.includes('didático') || rawDesc.includes('didatico') || rawDesc.includes('interface leve') || rawDesc.includes('landing page')) {
+        workload = WORKLOAD_PROFILES.CLIENT_INTERACTIVE;
+      } else if (rawDomain.includes('pagamento') || rawDomain.includes('banco') || rawDomain.includes('financeiro') || rawDomain.includes('checkout') || rawCriticality === 'critical' || rawDesc.includes('transa')) {
+        workload = WORKLOAD_PROFILES.TRANSACTIONAL_OLTP;
+      } else if (rawDomain.includes('telemetria') || rawDesc.includes('iot') || rawDesc.includes('tempo real') || rawDesc.includes('stream') || rawDesc.includes('latência')) {
+        workload = WORKLOAD_PROFILES.STREAM_PROCESSING;
+      } else if (rawDomain.includes('analytics') || rawDesc.includes('relatório pesado') || rawDesc.includes('batch')) {
+        workload = WORKLOAD_PROFILES.BATCH_ANALYTICS;
+      } else {
+        workload = WORKLOAD_PROFILES.TRANSACTIONAL_OLTP;
+      }
+    }
+
+    // 2. Concurrency Scale (RPS / Volume)
+    let concurrency = spec.concurrencyScale || null;
+    if (!concurrency) {
+      if (rawScale === 'extreme') concurrency = 'extreme_scale';
+      else if (rawScale === 'high') concurrency = 'high_concurrent';
+      else if (rawScale === 'medium') concurrency = 'medium_concurrent';
+      else if (rawScale === 'prototype') concurrency = 'single_user_local';
+      else concurrency = 'low_concurrent';
+    }
+
+    // 3. Consistency Requirement
+    let consistency = spec.consistencyRequirement || null;
+    if (!consistency) {
+      if (rawCriticality === 'critical' || rawDomain.includes('pagamento') || rawDomain.includes('financeiro') || rawDomain.includes('ledger')) {
+        consistency = 'strict_acid_ledger';
+      } else if (workload === WORKLOAD_PROFILES.STREAM_PROCESSING) {
+        consistency = 'eventual_consistency';
+      } else if (workload === WORKLOAD_PROFILES.CLIENT_INTERACTIVE) {
+        consistency = 'stateless_client';
+      } else {
+        consistency = 'standard_relational_acid';
+      }
+    }
+
+    // 4. Compliance & Audit Level
+    let compliance = spec.complianceLevel || null;
+    if (!compliance) {
+      if (rawCriticality === 'critical' || consistency === 'strict_acid_ledger') {
+        compliance = 'regulatory_pci_dss_sox';
+      } else if (rawCriticality === 'high') {
+        compliance = 'business_audit_trail';
+      } else {
+        compliance = 'standard_logging';
+      }
+    }
+
+    // 5. Team Topology
+    let team = spec.teamTopology || null;
+    if (!team) {
+      if (rawTeam.includes('enterprise') || rawTeam.includes('multi')) team = 'multi_team_org';
+      else if (rawTeam.includes('small') || rawTeam.includes('pequeno')) team = 'small_team';
+      else team = 'solo_engineer';
+    }
+
+    return {
+      workload,
+      concurrency,
+      consistency,
+      compliance,
+      team,
+      userPreference: spec.userPreference || {}
+    };
+  }
+
+  /**
+   * Avalia os requisitos contra uma função de aptidão arquitetural (Architecture Fitness Function).
+   */
+  evaluate(spec = {}) {
+    const req = this.normalizeRequirements(spec);
+    const pref = req.userPreference;
+
+    // Pontuação de Aptidão para cada estilo
+    const scores = {
+      [ARCHITECTURE_STYLES.ZERO_DEPENDENCY_WEB]: 0,
+      [ARCHITECTURE_STYLES.MODULAR_MONOLITH]: 0,
+      [ARCHITECTURE_STYLES.HEXAGONAL_EVENT_SOURCED]: 0,
+      [ARCHITECTURE_STYLES.EVENT_DRIVEN_PIPELINE]: 0,
+      [ARCHITECTURE_STYLES.DISTRIBUTED_MICROSERVICES]: 0
+    };
+
+    // Heurísticas formais de ATAM
+    if (req.workload === WORKLOAD_PROFILES.CLIENT_INTERACTIVE && req.concurrency === 'single_user_local') {
+      scores[ARCHITECTURE_STYLES.ZERO_DEPENDENCY_WEB] += 40;
+      scores[ARCHITECTURE_STYLES.MODULAR_MONOLITH] += 10;
+      scores[ARCHITECTURE_STYLES.DISTRIBUTED_MICROSERVICES] -= 50;
+    }
+
+    if (req.consistency === 'strict_acid_ledger' || req.compliance === 'regulatory_pci_dss_sox') {
+      scores[ARCHITECTURE_STYLES.HEXAGONAL_EVENT_SOURCED] += 60;
+      scores[ARCHITECTURE_STYLES.MODULAR_MONOLITH] += 15;
+      scores[ARCHITECTURE_STYLES.ZERO_DEPENDENCY_WEB] -= 30;
+    }
+
+    if (req.workload === WORKLOAD_PROFILES.STREAM_PROCESSING || req.concurrency === 'extreme_scale' || req.concurrency === 'high_concurrent') {
+      scores[ARCHITECTURE_STYLES.EVENT_DRIVEN_PIPELINE] += 40;
+      scores[ARCHITECTURE_STYLES.MODULAR_MONOLITH] += 15;
+    }
+
+    if (req.workload === WORKLOAD_PROFILES.TRANSACTIONAL_OLTP && req.consistency !== 'strict_acid_ledger') {
+      scores[ARCHITECTURE_STYLES.MODULAR_MONOLITH] += 35;
+      scores[ARCHITECTURE_STYLES.HEXAGONAL_EVENT_SOURCED] += 15;
+    }
+
+    // Penalidade severa de Conway: Equipes individuais ou pequenas perdem tração com microsserviços
+    if (req.team === 'solo_engineer' || req.team === 'small_team') {
+      scores[ARCHITECTURE_STYLES.DISTRIBUTED_MICROSERVICES] -= 40;
+      scores[ARCHITECTURE_STYLES.MODULAR_MONOLITH] += 10;
+    } else if (req.team === 'multi_team_org') {
+      scores[ARCHITECTURE_STYLES.DISTRIBUTED_MICROSERVICES] += 20;
+    }
+
+    // Encontra o estilo vencedor
+    let winningStyle = ARCHITECTURE_STYLES.MODULAR_MONOLITH;
+    let highestScore = -Infinity;
+    for (const [style, score] of Object.entries(scores)) {
+      if (score > highestScore) {
+        highestScore = score;
+        winningStyle = style;
+      }
+    }
+
+    // Determina a Stack e os Pilares recomendados
+    let recommendedStack = 'TypeScript / Node.js (Clean DDD)';
+    let runtimePillars = [];
+    let rationale = '';
+
+    switch (winningStyle) {
+      case ARCHITECTURE_STYLES.ZERO_DEPENDENCY_WEB:
+        recommendedStack = pref.stack || 'HTML5 + CSS Moderno + Vanilla JS';
+        rationale = 'Para ferramentas didáticas, interfaces interativas locais e protótipos de alta velocidade, a eliminação de runtimes pesados e fricção de build garante entrega de valor imediata e manutenção trivial.';
+        runtimePillars = [
+          'Acessibilidade e Semântica WAI-ARIA nativa',
+          'Zero dependências de build ou bundlers intermediários',
+          'Persistência local transparente (localStorage / Web Storage)',
+          'Feedback visual e sonoro nativo via Web Audio API'
+        ];
+        break;
+
+      case ARCHITECTURE_STYLES.HEXAGONAL_EVENT_SOURCED:
+        recommendedStack = pref.stack || 'Go (Golang 1.22+) ou TypeScript';
+        rationale = 'Sistemas de missão crítica regulatória exigem isolamento estrito entre o domínio e os adaptadores de I/O, garantindo integridade transacional ACID e trilha de auditoria criptográfica.';
+        runtimePillars = [
+          'Livro-razão criptográfico com encadeamento de hash SHA-256 (Anti-Tampering)',
+          'Idempotência durável fim a fim contra double-spending',
+          'Persistência relacional ACID com WAL mode e timeouts estritos',
+          'Conformidade técnica direta com PCI-DSS 4.0 e OWASP Top 10'
+        ];
+        break;
+
+      case ARCHITECTURE_STYLES.EVENT_DRIVEN_PIPELINE:
+        recommendedStack = pref.stack || 'Go (Golang 1.22+) ou Rust';
+        rationale = 'Workloads reativos e streaming exigem baixo overhead de memória, concorrência nativa (goroutines/threads seguras) e tratamento de backpressure para sustentar picos sem estourar custos de nuvem.';
+        runtimePillars = [
+          'Processamento de eventos não bloqueante com concorrência segura',
+          'Footprint de memória estável e ausência de pausas de Garbage Collector longas',
+          'Backpressure dinâmico contra sobrecarga de canais',
+          'Instrumentação de tracing distribuído via W3C TraceContext'
+        ];
+        break;
+
+      case ARCHITECTURE_STYLES.MODULAR_MONOLITH:
+      default:
+        recommendedStack = pref.stack || 'TypeScript / Node.js ou Python FastAPI';
+        rationale = 'O Monólito Modular oferece a melhor relação custo-benefício e velocidade de iteração do mercado, garantindo fronteiras coesas entre módulos sem o overhead de rede distribuída.';
+        runtimePillars = [
+          'Fronteiras explícitas de módulos com interfaces tipadas',
+          'Validação estrita de contratos de domínio em runtime (Type Guards)',
+          'Banco de dados relacional otimizado com isolamento ACID',
+          'Suíte de testes de integração TDD ponta a ponta com cobertura de casos de borda'
+        ];
+        break;
+    }
+
+    // Análise Crítica de Overengineering e Riscos
+    let overengineeringRisk = 'BAIXO';
+    let overengineeringAlert = null;
+
+    if (pref.architecture) {
+      const pArch = pref.architecture.toLowerCase();
+      if ((pArch.includes('micro') || pArch.includes('distribu')) && (req.team === 'solo_engineer' || req.workload === WORKLOAD_PROFILES.CLIENT_INTERACTIVE)) {
+        overengineeringRisk = 'CRÍTICO';
+        overengineeringAlert = `Aviso Formal de Engenharia: A adoção de ${pref.architecture} para este perfil de carga adicionará complexidade acidental extrema (orquestração de rede, falhas parciais, latência de barramento e custos de deploy) sem qualquer benefício tangível para o produto. Recomendamos iniciar com ${winningStyle}.`;
+      } else if (pArch.includes('clean') && req.workload === WORKLOAD_PROFILES.CLIENT_INTERACTIVE) {
+        overengineeringRisk = 'MÉDIO';
+        overengineeringAlert = `Aviso: A separação estrita de 5 camadas do Clean Architecture em uma interface interativa pontual pode gerar excesso de boilerplate sem ganho prático de isolamento.`;
+      }
+    }
+
+    // Diagnóstico Honesto do Host Environment (Reality Check de Toolchains)
+    const hostToolchains = this.detectHostToolchains();
+    let hostEnvironmentAlert = null;
+    const targetStack = (pref.stack || recommendedStack).toLowerCase();
+
+    if (targetStack.includes('go') && !hostToolchains.go?.installed) {
+      hostEnvironmentAlert = 'Compilador Go (go build) não detectado no PATH do host Windows. Código Go gerado necessitará de container Docker ou instalação prévia da toolchain para compilação e testes reais.';
+    } else if (targetStack.includes('rust') && !hostToolchains.rust?.installed) {
+      hostEnvironmentAlert = 'Compilador Rust (rustc/cargo) não detectado no PATH do host. A compilação nativa falhará até que a toolchain Rust seja instalada.';
+    } else if ((targetStack.includes('java') || targetStack.includes('spring')) && !hostToolchains.java?.installed) {
+      hostEnvironmentAlert = 'JDK / javac não detectado no PATH do host. A compilação Maven/Gradle falhará no ambiente local direto.';
+    }
+
+    // Feedback da Preferência do Usuário
+    let userPreferenceFeedback = null;
+    if (pref.stack || pref.architecture) {
+      const pStack = pref.stack || 'conforme especificado';
+      const pArch = pref.architecture || 'conforme especificado';
+      userPreferenceFeedback = {
+        declaredStack: pStack,
+        declaredArchitecture: pArch,
+        verdict: 'RESPEITADO COM BLINDAGEM TÉCNICA',
+        observation: `O Agent Master DevSecOps executará com excelência em ${pStack} usando ${pArch}.${hostEnvironmentAlert ? ' [REALITY-CHECK]: ' + hostEnvironmentAlert : ''}`
+      };
+    }
+
+    // Plano de Entrega de Valor Ponta a Ponta
+    const valueDeliveryPlan = [
+      { step: 1, phase: 'Análise de Requisitos & Invariantes', outcome: 'Especificação formal do domínio, contratos de dados e análise de trade-offs.' },
+      { step: 2, phase: 'Walking Skeleton & Arquitetura', outcome: 'Estrutura compilável executável de ponta a ponta com esteira CI/CD blindada.' },
+      { step: 3, phase: 'Desenvolvimento TDD com Testes de Borda', outcome: 'Implementação de regras de negócio com suíte de testes automatizada.' },
+      { step: 4, phase: 'Auditoria DevSecOps Shift-Left', outcome: 'Varredura SAST real, validação de segredos e checagem de dependências CVE.' },
+      { step: 5, phase: 'Deploy Seguro & Provisionamento', outcome: 'Entrega contínua em infraestrutura estável com menor privilégio.' },
+      { step: 6, phase: 'Observabilidade & Geração de Valor', outcome: 'Monitoramento OTel/Prometheus, garantindo estabilidade e valor real em produção.' }
+    ];
+
+    const reportMarkdown = [
+      `# 🏛️ PARECER TÉCNICO DE ARQUITETURA & ENGENHARIA DE VALOR`,
+      ``,
+      `> **Diagnóstico de Engenharia:** ${spec.description || 'Necessidade de software'}`,
+      `> **Workload:** \`${req.workload}\` | **Concorrência:** \`${req.concurrency}\` | **Consistência:** \`${req.consistency}\``,
+      ``,
+      `---`,
+      ``,
+      `## 1. ARQUITETURA & STACK RECOMENDADAS`,
+      `- **Padrão Arquitetural Ideal:** \`${winningStyle}\``,
+      `- **Stack Tecnológica Indicada:** \`${recommendedStack}\``,
+      `- **Justificativa Técnica:** ${rationale}`,
+      ``,
+      `### Pilares Técnicos de Confiabilidade:`,
+      ...runtimePillars.map(p => `- ✅ ${p}`),
+      ``,
+      `---`,
+      ``,
+      `## 2. AVALIAÇÃO DE RISCO & OVERENGINEERING`,
+      `- **Classificação de Risco de Overengineering:** \`${overengineeringRisk}\``,
+      overengineeringAlert ? `> ⚠️ **ALERTA CRÍTICO DE ENGENHARIA:** ${overengineeringAlert}\n` : `- Nenhuma complexidade acidental desnecessária detectada.\n`,
+      userPreferenceFeedback ? [
+        `### Avaliação da Preferência Declarada pelo Usuário:`,
+        `- **Pretensão:** Stack: \`${userPreferenceFeedback.declaredStack}\` | Arquitetura: \`${userPreferenceFeedback.declaredArchitecture}\``,
+        `- **Posicionamento:** ${userPreferenceFeedback.observation}`,
+        ``
+      ].join('\n') : '',
+      `---`,
+      ``,
+      `## 3. ROTEIRO DE GERAÇÃO DE VALOR (PONTA A PONTA)`,
+      ...valueDeliveryPlan.map(p => `${p.step}. **${p.phase}:** ${p.outcome}`),
+      ``,
+      `*Engenharia de software real: sem prejuízos, com segurança, modernidade e foco estrito no valor de quem usa.*`
+    ].join('\n');
+
+    // Enriquecimento e Grounding em Padrões Oficiais via KnowledgeGateway
+    const stackToCheck = pref.stack || recommendedStack;
+    const docGrounding = this.gateway ? this.gateway.lookupDoc(stackToCheck) : null;
+    const knowledgeGrounding = {
+      groundedInStandards: true,
+      authoritativeSource: docGrounding ? docGrounding.authoritativeSource : 'https://standards.ieee.org',
+      recommendedPractices: docGrounding ? docGrounding.recommendedPractices : null
+    };
+
+    return {
+      status: 'SUCCESS',
+      recommendedArchitecture: winningStyle,
+      recommendedStack,
+      overengineeringRisk,
+      overengineeringAlert,
+      hostEnvironmentAlert,
+      hostToolchains,
+      runtimePillars,
+      userPreferenceFeedback,
+      valueDeliveryPlan,
+      knowledgeGrounding,
+      reportMarkdown
+    };
+  }
+}
+
+function recommendArchitecture(spec) {
+  const advisor = new ArchitectureAdvisor();
+  return advisor.evaluate(spec);
+}
+
+module.exports = {
+  ArchitectureAdvisor,
+  recommendArchitecture,
+  ARCHITECTURE_STYLES,
+  WORKLOAD_PROFILES
+};