@mocoto/mahoraga 0.14.0 → 0.14.2

package/dist/analysts/detectors/detector-architecture.js

@@ -1,6 +1,6 @@
+import * as path from 'path';
 import { traverse } from '../../core/config/index.js';
 import { messages } from '../../core/messages/index.js';
-import * as path from 'path';
 import { criarOcorrencia } from '../../types/index.js';
 export const analistaArquitetura = {
     nome: 'arquitetura',
@@ -14,13 +14,16 @@ export const analistaArquitetura = {
             return [];
         }
         try {
+            // Analisar arquivo atual
             const estatisticasArquivo = analisarArquivo(ast, relPath, src);
+            // Analisar todo o contexto para entender a arquitetura
             let analiseCompleta;
             const ocorrencias = [];
             try {
-                analiseCompleta = await analisarArquiteturaCompleta(contexto, estatisticasArquivo);
+                analiseCompleta = analisarArquiteturaCompleta(contexto, estatisticasArquivo);
             }
             catch (erro) {
+                // Em caso de falha na análise contextual, registre ocorrência e continue sem travar
                 if (typeof contexto.report === 'function') {
                     contexto.report({
                         code: 'ARQ_ERRO',
@@ -44,6 +47,7 @@ export const analistaArquitetura = {
                         linha: 1
                     })];
             }
+            // Relatório principal da arquitetura
             if (typeof contexto.report === 'function') {
                 contexto.report({
                     code: 'ARQ_PADRAO',
@@ -68,6 +72,7 @@ export const analistaArquitetura = {
                     linha: 1
                 }));
             }
+            // Relatório de características
             if ((analiseCompleta.caracteristicas?.length ?? 0) > 0) {
                 if (typeof contexto.report === 'function') {
                     contexto.report({
@@ -77,7 +82,7 @@ export const analistaArquitetura = {
                         relPath,
                         linha: 1,
                         data: {
-                            caracteristicas: analiseCompleta.caracteristicas || []
+                            caracteristicas: analiseCompleta.caracteristicas ?? []
                         },
                         origem: 'arquitetura'
                     });
@@ -87,12 +92,13 @@ export const analistaArquitetura = {
                     ocorrencias.push(criarOcorrencia({
                         tipo: 'caracteristicas-arquitetura',
                         nivel: 'info',
-                        mensagem: DetectorArquiteturaMensagens.caracteristicas(analiseCompleta.caracteristicas || []),
+                        mensagem: DetectorArquiteturaMensagens.caracteristicas(analiseCompleta.caracteristicas ?? []),
                         relPath,
                         linha: 1
                     }));
                 }
             }
+            // Relatório de violações
             for (const violacao of (analiseCompleta.violacoes ?? []).slice(0, 3)) {
                 if (typeof contexto.report === 'function') {
                     contexto.report({
@@ -118,6 +124,7 @@ export const analistaArquitetura = {
                     }));
                 }
             }
+            // Métricas de qualidade
             const metricas = analiseCompleta.metricas;
             if (metricas && typeof metricas === 'object' && 'acoplamento' in metricas && 'coesao' in metricas) {
                 if ((metricas.acoplamento ?? 0) > 0.7 || (metricas.coesao ?? 1) < 0.3) {
@@ -186,10 +193,13 @@ function analisarArquivo(ast, relPath, _src) {
         ImportDeclaration(path) {
             const origem = path.node.source.value;
             const items = path.node.specifiers.map((spec) => {
-                if (spec.type === 'ImportDefaultSpecifier')
+                // Mixed import specifier types
+                if (spec.type === 'ImportDefaultSpecifier') {
                     return 'default';
-                if (spec.type === 'ImportNamespaceSpecifier')
+                }
+                if (spec.type === 'ImportNamespaceSpecifier') {
                     return '*';
+                }
                 return spec.local.name;
             });
             let tipo = 'external';
@@ -214,16 +224,18 @@ function analisarArquivo(ast, relPath, _src) {
         },
         ExportNamedDeclaration(path) {
             if (path.node.declaration) {
-                const decl = path.node.declaration;
+                // export const/function/class/etc
+                const decl = path.node.declaration; // ExportDeclaration node
                 if ('id' in decl && decl.id && 'name' in decl.id) {
                     exports.push({
                         nome: decl.id.name,
                         tipo: 'named'
                     });
                 }
-                else if ('declarations' in decl && decl.declarations) {
+                else if ('declarations' in decl) {
+                    // export const a = ..., b = ...
                     for (const declarator of decl.declarations) {
-                        if (declarator.id && 'name' in declarator.id) {
+                        if ('name' in declarator.id) {
                             exports.push({
                                 nome: declarator.id.name,
                                 tipo: 'named'
@@ -233,7 +245,9 @@ function analisarArquivo(ast, relPath, _src) {
                 }
             }
             else {
+                // export { a, b }
                 for (const spec of path.node.specifiers) {
+                    // ExportSpecifier nodes
                     const name = 'exported' in spec && spec.exported.type === 'Identifier' && 'name' in spec.exported ? spec.exported.name : 'exported';
                     exports.push({
                         nome: name,
@@ -248,6 +262,7 @@ function analisarArquivo(ast, relPath, _src) {
                 tipo: 'default'
             });
         },
+        // Calcular complexidade ciclomática básica
         'IfStatement|WhileStatement|ForStatement|DoWhileStatement|SwitchCase|CatchClause'() {
             complexidade++;
         },
@@ -265,10 +280,13 @@ function analisarArquivo(ast, relPath, _src) {
         complexidade: complexidade || 1
     };
 }
-async function analisarArquiteturaCompleta(contexto, arquivoAtual) {
+function analisarArquiteturaCompleta(contexto, arquivoAtual) {
+    // Analisar todos os arquivos para entender a arquitetura geral
     const todasEstatisticas = [];
     for (const arquivo of contexto.arquivos.slice(0, 50)) {
+        // Limitar para performance
         if (arquivo.ast && arquivo.content && arquivo.relPath.match(/\.(js|jsx|ts|tsx)$/)) {
+            // Verificar se o AST é do tipo correto (NodePath<Node>)
             if ('parent' in arquivo.ast && 'node' in arquivo.ast) {
                 const stats = analisarArquivo(arquivo.ast, arquivo.relPath, arquivo.content);
                 todasEstatisticas.push(stats);
@@ -276,17 +294,24 @@ async function analisarArquiteturaCompleta(contexto, arquivoAtual) {
         }
     }
     todasEstatisticas.push(arquivoAtual);
+    // Detectar padrão arquitetural
     const padraoDetectado = detectarPadraoArquitetural(todasEstatisticas);
+    // Detectar Clean Architecture
     const cleanArchResultado = detectarCleanArchitecture(contexto, todasEstatisticas, arquivoAtual);
+    // Detectar Arquitetura Distribuída
     const distributedArchResultado = detectarArquiteturaDistribuida(contexto, todasEstatisticas, arquivoAtual);
+    // Escolher o padrão com maior confiança
     const melhoresPadroes = [
         { tipo: cleanArchResultado.tipo, confianca: cleanArchResultado.confianca },
         { tipo: distributedArchResultado.tipo, confianca: distributedArchResultado.confianca },
         padraoDetectado
     ].sort((a, b) => b.confianca - a.confianca);
     const padraoFinal = melhoresPadroes[0];
+    // Calcular métricas
     const metricas = calcularMetricas(todasEstatisticas);
+    // Detectar violações
     const violacoes = detectarViolacoes(todasEstatisticas, padraoDetectado);
+    // Gerar características (combinadas)
     const caracteristicas = [
         ...gerarCaracteristicas(todasEstatisticas),
         ...cleanArchResultado.caracteristicas,
@@ -317,20 +342,27 @@ function detectarPadraoArquitetural(estatisticas) {
     let temAnalistas = false;
     let temShared = false;
     let temTipos = false;
+    // Analisar uso de aliases
     for (const stats of estatisticas) {
         if (stats.aliases) {
             Object.keys(stats.aliases).forEach(alias => aliases.add(alias));
-            if (stats.aliases['@nucleo'])
+            if (stats.aliases['@nucleo']) {
                 temNucleo = true;
-            if (stats.aliases['@analistas'])
+            }
+            if (stats.aliases['@analistas']) {
                 temAnalistas = true;
-            if (stats.aliases['@shared'])
+            }
+            if (stats.aliases['@shared']) {
                 temShared = true;
-            if (stats.aliases['@types'])
+            }
+            if (stats.aliases['@types']) {
                 temTipos = true;
+            }
         }
     }
+    // Detectar dependências circulares
     const temDependenciasCirculares = detectarDependenciasCirculares(estatisticas);
+    // Regras de detecção
     if (temNucleo && temAnalistas && !temDependenciasCirculares) {
         if (temShared && temTipos) {
             return {
@@ -375,6 +407,7 @@ function calcularMetricas(estatisticas) {
             complexidadeMedia: 0
         };
     }
+    // Modularidade = uso de aliases / total de imports
     const totalImports = estatisticas.reduce((sum, string) => {
         if (Array.isArray(string.imports)) {
             return sum + string.imports.length;
@@ -391,6 +424,7 @@ function calcularMetricas(estatisticas) {
         return sum;
     }, 0);
     const modularidade = totalImports > 0 ? importsAlias / totalImports : 0;
+    // Acoplamento = dependências externas / total de dependências
     const totalDeps = estatisticas.reduce((sum, string) => {
         const externas = string.dependenciasExternas?.length ?? 0;
         const internas = string.dependenciasInternas?.length ?? 0;
@@ -400,6 +434,8 @@ function calcularMetricas(estatisticas) {
         return sum + (string.dependenciasExternas?.length ?? 0);
     }, 0);
     const acoplamento = totalDeps > 0 ? depsExternas / totalDeps : 0;
+    // Coesão balanceada: penaliza tanto o excesso de exports (módulos "god")
+    // quanto o excesso de imports (módulos "cola"), buscando um equilíbrio saudável.
     const totalExports = estatisticas.reduce((sum, string) => {
         if (Array.isArray(string.exports)) {
             return sum + string.exports.length;
@@ -411,6 +447,7 @@ function calcularMetricas(estatisticas) {
     }, 0);
     const ratio = totalImports > 0 ? totalExports / totalImports : 0;
     const coesao = ratio > 0 ? Math.min(ratio, 1 / ratio) : 0;
+    // Complexidade média
     const complexidadeMedia = estatisticas.reduce((sum, string) => sum + (string.complexidade ?? 0), 0) / estatisticas.length;
     return {
         modularidade: Math.max(0, Math.min(1, modularidade)),
@@ -421,6 +458,7 @@ function calcularMetricas(estatisticas) {
 }
 function detectarViolacoes(estatisticas, _padrao) {
     const violacoes = [];
+    // Detectar imports relativos excessivos
     const totalImports = estatisticas.reduce((sum, string) => {
         if (Array.isArray(string.imports)) {
             return sum + string.imports.length;
@@ -439,6 +477,7 @@ function detectarViolacoes(estatisticas, _padrao) {
     if (totalImports > 0 && importsRelativos / totalImports > 0.3) {
         violacoes.push('Uso excessivo de imports relativos (>30%)');
     }
+    // Detectar arquivos com muitas dependências
     for (const stats of estatisticas) {
         const importsContagem = Array.isArray(stats.imports) ? stats.imports.length : typeof stats.imports === 'number' ? stats.imports : 0;
         if (importsContagem > 20) {
@@ -474,6 +513,7 @@ function gerarCaracteristicas(estatisticas) {
     return caracteristicas;
 }
 function detectarDependenciasCirculares(estatisticas) {
+    // Simplificado: detectar se há imports bidirecionais
     const dependencias = new Map();
     for (const stats of estatisticas) {
         const caminho = stats.caminho ?? 'arquivo-desconhecido';
@@ -483,6 +523,7 @@ function detectarDependenciasCirculares(estatisticas) {
         }
         dependencias.set(caminho, deps);
     }
+    // Verificar ciclos simples (A -> B -> A)
     for (const [arquivo, deps] of dependencias) {
         for (const dep of deps) {
             const depsDoDepdep = dependencias.get(dep);
@@ -493,12 +534,21 @@ function detectarDependenciasCirculares(estatisticas) {
     }
     return false;
 }
+/**
+ * Detecta padrões de Clean Architecture no projeto
+ * - Domínio: entities, value-objects, domain services, repository interfaces
+ * - Aplicação: use-cases, ports, DTOs
+ * - Infraestrutura: persistence, repositories (impl), HTTP clients
+ * - Apresentação: controllers, presenters, middlewares
+ */
 function detectarCleanArchitecture(contexto, _estatisticas, _arquivoAtual) {
     const caracteristicas = [];
     const recomendacoes = [];
     let pontuacao = 0;
     const totalChecagens = 10;
+    // Análise dos caminhos dos arquivos no contexto
     const caminhos = contexto.arquivos.map(a => a.relPath.toLowerCase());
+    // 1. Detecta camada de domínio (entities, value-objects)
     const temEntities = caminhos.some(c => c.includes('/domain/') || c.includes('/entities/') || c.endsWith('entity.ts') || c.endsWith('entity.js'));
     const temValueObjects = caminhos.some(c => c.includes('/value-object') || c.includes('value-object'));
     const temRepoInterfaces = caminhos.some(c => c.includes('/domain/') && (c.includes('repository') || c.includes('port')));
@@ -514,6 +564,7 @@ function detectarCleanArchitecture(contexto, _estatisticas, _arquivoAtual) {
         pontuacao++;
         caracteristicas.push('Interfaces de repositório no domínio');
     }
+    // 2. Detecta camada de aplicação (use-cases, ports, DTOs)
     const temUseCases = caminhos.some(c => c.includes('/use-case') || c.includes('/use-cases/') || c.includes('/application/'));
     const temDtos = caminhos.some(c => c.includes('/dto') || c.endsWith('.dto.ts') || c.endsWith('.dto.js'));
     const temPorts = caminhos.some(c => c.includes('/ports') || c.includes('/application/port'));
@@ -529,6 +580,7 @@ function detectarCleanArchitecture(contexto, _estatisticas, _arquivoAtual) {
         pontuacao++;
         caracteristicas.push('Ports de aplicação detectados');
     }
+    // 3. Detecta camada de infraestrutura
     const temInfra = caminhos.some(c => c.includes('/infrastructure/') || c.includes('/infra/'));
     const temReposImpl = caminhos.some(c => c.includes('/infrastructure/repositories') || c.includes('/infra/repositories'));
     if (temInfra) {
@@ -539,26 +591,30 @@ function detectarCleanArchitecture(contexto, _estatisticas, _arquivoAtual) {
         pontuacao++;
         caracteristicas.push('Implementações de repositórios na infra');
     }
+    // 4. Detecta camada de apresentação
     const temPresentation = caminhos.some(c => c.includes('/presentation/') || c.includes('/presenters/'));
     const temControllers = caminhos.some(c => c.includes('/presentation/controllers') || c.includes('/controllers'));
     if (temPresentation || temControllers) {
         pontuacao++;
         caracteristicas.push('Camada de apresentação/controllers detectada');
     }
+    // 5. Detecta inversão de dependência (domain não importa infra)
     const temDependencyInversion = caminhos.some(c => c.includes('/domain/') && (c.includes('repository') || c.includes('port') || c.includes('interface')));
     if (temDependencyInversion) {
         pontuacao++;
         caracteristicas.push('Princípio de Inversão de Dependência identificado');
     }
+    // 6. Verifica padrão de imports (domain não importa camadas externas)
     for (const stats of _estatisticas) {
         if (stats.caminho?.includes('/domain/') && stats.dependenciasInternas) {
             const importsParaInfra = stats.dependenciasInternas.filter(d => d.includes('infrastructure') || d.includes('infra') || d.includes('presentation'));
             if (importsParaInfra.length > 0) {
-                pontuacao -= 2;
+                pontuacao -= 2; // penalidade: domínio importando infra
                 recomendacoes.push('Domínio não deve importar camadas de infraestrutura (violação da Clean Architecture)');
             }
         }
     }
+    // Recomendações
     if (!temEntities && !temValueObjects) {
         recomendacoes.push('Considere criar uma camada de domínio com entidades e value-objects');
     }
@@ -579,13 +635,22 @@ function detectarCleanArchitecture(contexto, _estatisticas, _arquivoAtual) {
         recomendacoes
     };
 }
+/**
+ * Detecta padrões de Arquitetura Distribuída / Microsserviços
+ * - Boundaries de serviço
+ * - Mensageria / Eventos
+ * - API Gateway / Service Discovery
+ * - Comunicação assíncrona
+ */
 function detectarArquiteturaDistribuida(contexto, _estatisticas, _arquivoAtual) {
     const caracteristicas = [];
     const recomendacoes = [];
     let pontuacao = 0;
     const totalChecagens = 10;
+    // Análise dos caminhos e conteúdo
     const caminhos = contexto.arquivos.map(a => a.relPath.toLowerCase());
-    const conteudos = contexto.arquivos.map(a => a.content?.toLowerCase() || '');
+    const conteudos = contexto.arquivos.map(a => a.content?.toLowerCase() ?? '');
+    // 1. Detecta boundaries/serviços separados
     const temMultiplosServicos = caminhos.some(c => c.includes('/services/') || c.includes('/service-') || c.includes('/microservice'));
     const temServicosSeparados = new Set(caminhos.filter(c => c.includes('/services/'))
         .map(c => c.split('/services/')[1]?.split('/')[0])
@@ -598,6 +663,7 @@ function detectarArquiteturaDistribuida(contexto, _estatisticas, _arquivoAtual)
         pontuacao++;
         caracteristicas.push(`${temServicosSeparados} boundaries de serviço identificados`);
     }
+    // 2. Detecta mensageria / filas
     const temMensageria = caminhos.some(c => c.includes('message-queue') || c.includes('event-bus') || c.includes('rabbitmq') ||
         c.includes('kafka') || c.includes('nats') || c.includes('sqs') || c.includes('pub-sub'));
     const temMensageriaDeps = conteudos.some(c => c.includes('kafkajs') || c.includes('amqplib') || c.includes('ioredis') ||
@@ -606,16 +672,19 @@ function detectarArquiteturaDistribuida(contexto, _estatisticas, _arquivoAtual)
         pontuacao++;
         caracteristicas.push('Sistema de mensageria/eventos detectado');
     }
+    // 3. Detecta API Gateway
     const temGateway = caminhos.some(c => c.includes('/gateway') || c.includes('/api-gateway') || c.includes('gateway.ts') || c.includes('gateway.js'));
     if (temGateway) {
         pontuacao++;
         caracteristicas.push('API Gateway presente');
     }
+    // 4. Detecta Service Discovery
     const temDiscovery = caminhos.some(c => c.includes('/discovery') || c.includes('service-discovery') || c.includes('consul') || c.includes('eureka'));
     if (temDiscovery) {
         pontuacao++;
         caracteristicas.push('Service Discovery detectado');
     }
+    // 5. Detecta Docker/Kubernetes (orquestração)
     const temDocker = caminhos.some(c => c.endsWith('dockerfile') || c.includes('docker-compose'));
     const temK8s = caminhos.some(c => c.includes('kubernetes') || c.includes('k8s') || c.includes('.yaml') || c.includes('.yml'));
     if (temDocker) {
@@ -626,6 +695,7 @@ function detectarArquiteturaDistribuida(contexto, _estatisticas, _arquivoAtual)
         pontuacao++;
         caracteristicas.push('Kubernetes para orquestração');
     }
+    // 6. Detecta comunicação assíncrona (eventos, callbacks)
     const temEventos = caminhos.some(c => c.includes('/events/') || c.includes('/event-handlers') || c.includes('/handlers/'));
     const temAsyncPatterns = conteudos.filter(c => c.includes('eventemitter') || c.includes('observable') || c.includes('pubsub') ||
         c.includes('publish') || c.includes('subscribe') || c.includes('webhook')).length > 2;
@@ -633,15 +703,17 @@ function detectarArquiteturaDistribuida(contexto, _estatisticas, _arquivoAtual)
         pontuacao++;
         caracteristicas.push('Padrões de comunicação assíncrona detectados');
     }
+    // 7. Detecta shared/monitoring (bibliotecas compartilhadas)
     const temShared = caminhos.some(c => c.includes('/shared/'));
     const temMonitoring = caminhos.some(c => c.includes('/monitoring') || c.includes('/health') || c.includes('/metrics'));
     if (temShared) {
         pontuacao += 0;
-    }
+    } // neutro
     if (temMonitoring) {
         pontuacao++;
         caracteristicas.push('Monitoramento/health checks detectados');
     }
+    // Recomendações
     if (!temMensageria && !temMensageriaDeps && temMultiplosServicos) {
         recomendacoes.push('Considere adicionar mensageria (Kafka, RabbitMQ) para comunicação assíncrona entre serviços');
     }
@@ -662,4 +734,3 @@ function detectarArquiteturaDistribuida(contexto, _estatisticas, _arquivoAtual)
         recomendacoes
     };
 }
-//# sourceMappingURL=detector-architecture.js.map