@mocoto/mahoraga 0.14.0 → 0.14.1

package/dist/cli/diagnostic/exporters/markdown-exporter.js

@@ -1,3 +1,9 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2025 Mahoraga Contributors
+// ─── Função Principal ─────────────────────────────────────────
+/**
+ * Gera relatório Markdown formatado
+ */
 export function gerarRelatorioMarkdown(dados, options = {}) {
     const opts = {
         includeToc: options.includeToc ?? true,
@@ -12,31 +18,41 @@ export function gerarRelatorioMarkdown(dados, options = {}) {
         subtitulo: options.subtitulo
     };
     const secoes = [];
+    // Cabeçalho
     secoes.push(gerarCabecalho(opts.titulo ?? 'Relatório de Diagnóstico', opts.subtitulo, dados.metadata));
+    // Índice
     if (opts.includeToc) {
         secoes.push(gerarIndice(opts, dados));
     }
+    // Estatísticas
     if (opts.includeStats && dados.stats) {
         secoes.push(gerarSecaoStats(dados.stats, dados.linguagens));
     }
+    // Guardian
     if (opts.includeGuardian && dados.guardian?.executado) {
         secoes.push(gerarSecaoGuardian(dados.guardian));
     }
+    // Arquetipos
     if (opts.includeArquetipos && dados.arquetipos?.executado) {
         secoes.push(gerarSecaoArquetipos(dados.arquetipos));
     }
+    // Auto-fix
     if (opts.includeAutoFix && dados.autoFix?.executado) {
         secoes.push(gerarSecaoAutoFix(dados.autoFix));
     }
+    // Ocorrências
     if (opts.includeOcorrencias && dados.ocorrencias && dados.ocorrencias.length > 0) {
         secoes.push(gerarSecaoOcorrencias(dados.ocorrencias, opts));
     }
+    // Sugestões
     if (dados.sugestoes && dados.sugestoes.length > 0) {
         secoes.push(gerarSecaoSugestoes(dados.sugestoes));
     }
+    // Rodapé
     secoes.push(gerarRodape());
     return secoes.join('\n\n---\n\n');
 }
+// ─── Seções do Relatório ──────────────────────────────────────
 function gerarCabecalho(titulo, subtitulo, metadata) {
     let md = `# ${titulo}\n\n`;
     if (subtitulo) {
@@ -75,6 +91,7 @@ function gerarIndice(opts, dados) {
 }
 function gerarSecaoStats(stats, linguagens) {
     let md = '## [GRAFICO] Estatísticas\n\n';
+    // Tabela principal
     md += '| Métrica | Valor |\n';
     md += '|---|---|\n';
     md += `| Arquivos analisados | ${stats.arquivosAnalisados} |\n`;
@@ -84,26 +101,29 @@ function gerarSecaoStats(stats, linguagens) {
         const tempoSeg = (stats.tempoExecucao / 1000).toFixed(2);
         md += `| Tempo de execução | ${tempoSeg}s |\n`;
     }
+    // Breakdown por nível
     md += '\n### Por Nível\n\n';
     md += '| Nível | Quantidade |\n';
     md += '|---|---|\n';
     md += `| [ERRO] Erro | ${stats.porNivel.erro} |\n`;
     md += `| [AVISO] Aviso | ${stats.porNivel.aviso} |\n`;
     md += `| [INFO] Info | ${stats.porNivel.info} |\n`;
+    // Breakdown por categoria
     if (Object.keys(stats.porCategoria).length > 0) {
         md += '\n### Por Categoria\n\n';
         md += '| Categoria | Quantidade |\n';
         md += '|---|---|\n';
-        const categorias = Object.entries(stats.porCategoria).sort((arquivo, base) => base[1] - arquivo[1]).slice(0, 10);
+        const categorias = Object.entries(stats.porCategoria).sort((arquivo, base) => base[1] - arquivo[1]).slice(0, 10); // Top 10
         for (const [categoria, count] of categorias) {
             md += `| ${categoria} | ${count} |\n`;
         }
     }
+    // Linguagens
     if (linguagens && Object.keys(linguagens.extensoes).length > 0) {
         md += '\n### Linguagens Detectadas\n\n';
         md += '| Extensão | Arquivos |\n';
         md += '|---|---|\n';
-        const extensoes = Object.entries(linguagens.extensoes).sort((arquivo, base) => base[1] - arquivo[1]).slice(0, 10);
+        const extensoes = Object.entries(linguagens.extensoes).sort((arquivo, base) => base[1] - arquivo[1]).slice(0, 10); // Top 10
         for (const [ext, count] of extensoes) {
             md += `| .${ext} | ${count} |\n`;
         }
@@ -171,6 +191,7 @@ function gerarSecaoAutoFix(autoFix) {
 }
 function gerarSecaoOcorrencias(ocorrencias, opts) {
     let md = '## [BUSCA] Ocorrências\n\n';
+    // Limitar se necessário
     let lista = ocorrencias;
     if (opts.maxOcorrencias && lista.length > opts.maxOcorrencias) {
         lista = lista.slice(0, opts.maxOcorrencias);
@@ -190,8 +211,8 @@ function gerarTabelaOcorrencias(ocorrencias) {
     for (const ocorrencia of ocorrencias) {
         const arquivo = ocorrencia.relPath || 'desconhecido';
         const linha = ocorrencia.linha ?? '-';
-        const nivel = getNivelIcon(ocorrencia.nivel || 'info');
-        const tipo = ocorrencia.tipo || 'outros';
+        const nivel = getNivelIcon(ocorrencia.nivel ?? 'info');
+        const tipo = ocorrencia.tipo ?? 'outros';
         const rawMensagem = ocorrencia.mensagem;
         const mensagemEscapada = rawMensagem.replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
         const mensagem = mensagemEscapada.slice(0, 80);
@@ -215,7 +236,7 @@ function gerarOcorrenciasPorArquivo(ocorrencias) {
     for (const [arquivo, lista] of porArquivo) {
         md += `### [FILE] ${arquivo}\n\n`;
         for (const ocorrencia of lista) {
-            const nivel = getNivelIcon(ocorrencia.nivel || 'info');
+            const nivel = getNivelIcon(ocorrencia.nivel ?? 'info');
             const linha = ocorrencia.linha ? `:${ocorrencia.linha}` : '';
             md += `- ${nivel} **${ocorrencia.tipo}**${linha}: ${ocorrencia.mensagem}\n`;
         }
@@ -233,6 +254,7 @@ function gerarSecaoSugestoes(sugestoes) {
 function gerarRodape() {
     return `---\n\n*Gerado por Mahoraga v0.2.0 em ${new Date().toLocaleString('pt-BR')}*`;
 }
+// ─── Helpers ──────────────────────────────────────────────────
 function getNivelIcon(nivel) {
     switch (nivel) {
         case 'erro':
@@ -245,7 +267,9 @@ function getNivelIcon(nivel) {
             return '•';
     }
 }
+/**
+ * Escapa caracteres especiais do Markdown
+ */
 export function escaparMarkdown(texto) {
     return texto.replace(/\\/g, '\\\\').replace(/\*/g, '\\*').replace(/_/g, '\\_').replace(/\[/g, '\\[').replace(/\]/g, '\\]').replace(/\(/g, '\\(').replace(/\)/g, '\\)').replace(/`/g, '\\`');
 }
-//# sourceMappingURL=markdown-exporter.js.map

package/dist/cli/diagnostic/exporters/sharded-exporter.js

@@ -1,7 +1,20 @@
-export async function fragmentarRelatorio(dados, options) {
-    const ocorrencias = dados.ocorrencias || [];
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2025 Mahoraga Contributors
+// @mahoraga-disable tipo-literal-inline-complexo
+// Justificativa: tipos locais para manipulação de shards
+// ─── Função Principal ─────────────────────────────────────────
+/**
+ * Fragmenta relatório em múltiplos arquivos
+ *
+ * Esta função é um placeholder para implementação futura.
+ * Por enquanto, retorna estrutura básica sem criar arquivos reais.
+ */
+export function fragmentarRelatorio(dados, options) {
+    const ocorrencias = dados.ocorrencias ?? [];
     const totalOcorrencias = ocorrencias.length;
+    // Calcular número de shards necessários
     const numShards = Math.ceil(totalOcorrencias / options.ocorrenciasPorShard);
+    // Se não precisa fragmentar, retornar shard único
     if (numShards <= 1) {
         return {
             sucesso: true,
@@ -19,6 +32,7 @@ export async function fragmentarRelatorio(dados, options) {
             }
         };
     }
+    // Gerar informações dos shards
     const shards = [];
     for (let indice = 0; indice < numShards; indice++) {
         const inicio = indice * options.ocorrenciasPorShard;
@@ -48,6 +62,10 @@ export async function fragmentarRelatorio(dados, options) {
         }
     };
 }
+// ─── Helpers de Fragmentação ──────────────────────────────────
+/**
+ * Divide array de ocorrências em chunks
+ */
 export function dividirOcorrencias(ocorrencias, tamanhoChunk) {
     const chunks = [];
     for (let indice = 0; indice < ocorrencias.length; indice += tamanhoChunk) {
@@ -55,6 +73,9 @@ export function dividirOcorrencias(ocorrencias, tamanhoChunk) {
     }
     return chunks;
 }
+/**
+ * Calcula estatísticas de fragmentação
+ */
 export function calcularEstatisticasFragmentacao(ocorrencias, tamanhoShard) {
     const numShards = Math.ceil(ocorrencias.length / tamanhoShard);
     const tamanhoMedio = ocorrencias.length / numShards;
@@ -65,12 +86,18 @@ export function calcularEstatisticasFragmentacao(ocorrencias, tamanhoShard) {
         ultimoShardTamanho
     };
 }
+/**
+ * Gera nome de arquivo para shard
+ */
 export function gerarNomeShard(prefixo, indice, total, formato) {
     const padding = total.toString().length;
     const numeroFormatado = (indice + 1).toString().padStart(padding, '0');
     const extensao = formato === 'json' ? 'json' : 'md';
     return `${prefixo}-parte${numeroFormatado}-de${total}.${extensao}`;
 }
+/**
+ * Gera conteúdo do índice consolidado
+ */
 export function gerarIndiceConsolidado(shards, formato) {
     if (formato === 'json') {
         return JSON.stringify({
@@ -85,6 +112,7 @@ export function gerarIndiceConsolidado(shards, formato) {
             total: shards.reduce((sum, string) => sum + string.ocorrencias, 0)
         }, null, 2);
     }
+    // Markdown
     let md = '# Índice de Relatório Fragmentado\n\n';
     md += `*Gerado em: ${new Date().toLocaleString('pt-BR')}*\n\n`;
     md += '## Fragmentos\n\n';
@@ -97,6 +125,10 @@ export function gerarIndiceConsolidado(shards, formato) {
     md += `\n**Total**: ${shards.reduce((sum, string) => sum + string.ocorrencias, 0)} ocorrências\n`;
     return md;
 }
+// ─── Validação ────────────────────────────────────────────────
+/**
+ * Valida options de fragmentação
+ */
 export function validarOptionsSharding(options) {
     const erros = [];
     if (!options.formato) {
@@ -119,6 +151,9 @@ export function validarOptionsSharding(options) {
         erros
     };
 }
+/**
+ * Cria options padrão para fragmentação
+ */
 export function criarOptionsShardingPadrao(overrides = {}) {
     return {
         formato: 'json',
@@ -130,4 +165,3 @@ export function criarOptionsShardingPadrao(overrides = {}) {
         ...overrides
     };
 }
-//# sourceMappingURL=sharded-exporter.js.map

package/dist/cli/diagnostic/exporters/svg-optimization-exporter.js

@@ -1,34 +1,46 @@
+// SPDX-License-Identifier: MIT
 import path from 'node:path';
 import { otimizarSvgLikeSvgo, shouldSugerirOtimizacaoSvg } from '../../../shared/formatters/index.js';
 function formatBytes(bytes) {
-    if (!Number.isFinite(bytes) || bytes < 0)
+    if (!Number.isFinite(bytes) || bytes < 0) {
         return String(bytes);
-    if (bytes < 1024)
+    }
+    if (bytes < 1024) {
         return `${bytes}B`;
+    }
     const kb = bytes / 1024;
-    if (kb < 1024)
+    if (kb < 1024) {
         return `${kb.toFixed(1)}KB`;
+    }
     const mb = kb / 1024;
     return `${mb.toFixed(1)}MB`;
 }
+/**
+* Gera e escreve o relatório de otimização de SVG no diretório de relatórios
+*/
 export async function exportarRelatorioSvgOtimizacao(params) {
     const { entries, relatoriosDir, ts } = params;
     const candidatos = [];
     for (const erro of entries) {
-        if (!erro || typeof erro.relPath !== 'string')
+        if (!erro || typeof erro.relPath !== 'string') {
             continue;
-        if (!/\.svg$/i.test(erro.relPath))
+        }
+        if (!/\.svg$/i.test(erro.relPath)) {
             continue;
-        if (typeof erro.content !== 'string')
+        }
+        if (typeof erro.content !== 'string') {
             continue;
-        if (!/<svg\b/i.test(erro.content))
+        }
+        if (!/<svg\b/i.test(erro.content)) {
             continue;
+        }
         const opt = otimizarSvgLikeSvgo({
             svg: erro.content
         });
         const shouldSuggest = opt.changed && opt.originalBytes > opt.optimizedBytes && shouldSugerirOtimizacaoSvg(opt.originalBytes, opt.optimizedBytes);
-        if (!shouldSuggest)
+        if (!shouldSuggest) {
             continue;
+        }
         const savedBytes = opt.originalBytes - opt.optimizedBytes;
         candidatos.push({
             relPath: erro.relPath,
@@ -55,8 +67,9 @@ export async function exportarRelatorioSvgOtimizacao(params) {
         else {
             existing.count += 1;
             existing.totalSaved += elem.savedBytes;
-            if (existing.exemplos.length < 10)
+            if (existing.exemplos.length < 10) {
                 existing.exemplos.push(elem);
+            }
         }
     }
     const outputCaminho = path.join(relatoriosDir, `mahoraga-svg-otimizacao-${ts}.md`);
@@ -92,4 +105,3 @@ export async function exportarRelatorioSvgOtimizacao(params) {
         totalEconomiaBytes
     };
 }
-//# sourceMappingURL=svg-optimization-exporter.js.map

package/dist/cli/diagnostic/filters.js

@@ -1,23 +1,65 @@
+// SPDX-License-Identifier: MIT
+/**
+ * [ALVO] Sistema de Filtros para Diagnóstico
+ *
+ * Gerencia inclusão/exclusão de arquivos para análise
+ * - Processa padrões glob
+ * - Expande diretórios automaticamente
+ * - Gerencia node_modules e outros padrões especiais
+ * - Aplica precedência correta (CLI > config > defaults)
+ */
 import fs from 'node:fs';
 import { config, mesclarConfigExcludes } from '../../core/config/index.js';
+// ─── PROCESSAMENTO DE PADRÕES ─────────────────────────────────
+/**
+ * Processa lista de padrões achatada (vírgulas, espaços)
+ *
+ * @example
+ * processPatternListAchatado(['src/**', 'tests, lib'])
+ * // => ['src/**', 'tests', 'lib']
+ */
 export function processPatternListAchatado(raw) {
-    if (!raw || raw.length === 0)
+    if (!raw || raw.length === 0) {
         return [];
+    }
     return Array.from(new Set(raw.flatMap(raiz => raiz.split(/[\s,]+/)).map(string => string.trim()).filter(Boolean)));
 }
+/**
+ * Processa padrões em grupos (cada elemento da lista é um grupo)
+ *
+ * @example
+ * processPatternGroups(['src/** tests/**', 'lib/**'])
+ * // => [['src/**', 'tests/**'], ['lib/**']]
+ */
 export function processPatternGroups(raw) {
-    if (!raw || raw.length === 0)
+    if (!raw || raw.length === 0) {
         return [];
+    }
     return raw.map(grupo => grupo.split(/[\s,]+/).map(string => string.trim()).filter(Boolean)).filter(grupo => grupo.length > 0);
 }
+/**
+ * Expande padrões de inclusão (adiciona variantes recursivas)
+ *
+ * Para padrões sem metacaracteres glob, adiciona:
+ * - `pattern/**` (recursivo)
+ * - `** /pattern/**` (se não tiver barra)
+ *
+ * @example
+ * expandIncludes(['src', 'lib/*.ts'])
+ * // => ['src', 'src/**', '** /src/**', 'lib/*.ts']
+ */
 export function expandIncludes(list) {
-    const META = /[\\*\?\{\}\[\]]/;
+    const META = /[\\*\?\{\}\[\]]/; // metacaracteres glob
     const out = new Set();
     for (const caminho of list) {
         out.add(caminho);
+        // Se não tem metacaracteres, é um diretório literal
         if (!META.test(caminho)) {
+            // Remove barras terminais
             const normalized = caminho.replace(/[\\\/]+$/, '');
+            // Adiciona variante recursiva
             out.add(`${normalized}/**`);
+            // Se é nome simples (sem barra), adiciona busca em qualquer nível
             if (!caminho.includes('/') && !caminho.includes('\\')) {
                 out.add(`**/${normalized}/**`);
             }
@@ -25,6 +67,10 @@ export function expandIncludes(list) {
     }
     return Array.from(out);
 }
+// ─── DETECÇÃO DE TIPO DE PROJETO ──────────────────────────────
+/**
+ * Detecta tipo de projeto baseado em arquivos presentes
+ */
 export function detectarTipoProjeto(baseDir = process.cwd()) {
     try {
         const files = fs.readdirSync(baseDir);
@@ -47,36 +93,59 @@ export function detectarTipoProjeto(baseDir = process.cwd()) {
         return 'generico';
     }
 }
+// ─── PADRÕES DE EXCLUSÃO ──────────────────────────────────────
+/**
+ * Obtém padrões de exclusão padrão baseados em configuração e tipo de projeto
+ */
 export function getDefaultExcludes(tipoProjeto) {
+    // Tenta obter do mahoraga.config.json
     const configIncluirExcluir = config.INCLUDE_EXCLUDE_RULES;
-    if (configIncluirExcluir?.globalExcludeGlob) {
+    if (configIncluirExcluir.globalExcludeGlob) {
         if (Array.isArray(configIncluirExcluir.globalExcludeGlob) && configIncluirExcluir.globalExcludeGlob.length > 0) {
             return Array.from(new Set(configIncluirExcluir.globalExcludeGlob));
         }
     }
-    const tipo = tipoProjeto || detectarTipoProjeto();
+    // Fallback: usa padrões do sistema baseado no tipo de projeto
+    const tipo = tipoProjeto ?? detectarTipoProjeto();
     return mesclarConfigExcludes(null, tipo);
 }
+// ─── CONFIGURAÇÃO DE FILTROS ──────────────────────────────────
+/**
+ * Processa e aplica filtros CLI
+ *
+ * Precedência:
+ * 1. CLI --exclude (máxima)
+ * 2. mahoraga.config.json
+ * 3. Padrões do sistema (fallback)
+ */
 export function processarFiltros(opcoes) {
     const tipoProjeto = detectarTipoProjeto();
+    // Processar includes
     const includeGroups = processPatternGroups(opcoes.include);
     const includeFlat = includeGroups.flat();
     const includeExpanded = expandIncludes(includeFlat);
+    // Processar excludes
     const excludeFlat = processPatternListAchatado(opcoes.exclude);
+    // Determinar padrões de exclusão finais
     let excludePadroes;
     if (excludeFlat.length > 0) {
+        // CLI tem precedência
         excludePadroes = excludeFlat;
     }
     else {
+        // Usar defaults do config ou sistema
         excludePadroes = getDefaultExcludes(tipoProjeto);
     }
-    let incluiNodeModules = opcoes.forceIncludeNodeModules || false;
+    // Verificar se node_modules deve ser incluído
+    let incluiNodeModules = opcoes.forceIncludeNodeModules ?? false;
     if (includeFlat.some(caminho => /node_modules/.test(caminho))) {
         incluiNodeModules = true;
     }
+    // Remover node_modules dos excludes se explicitamente incluído
     if (incluiNodeModules) {
         excludePadroes = excludePadroes.filter(caminho => !/node_modules/.test(caminho));
     }
+    // Processar flag de testes
     if (opcoes.forceIncludeTests && !includeFlat.some(caminho => /tests?/.test(caminho))) {
         includeExpanded.push('tests/**', 'test/**', '**/*.test.*', '**/*.spec.*');
     }
@@ -88,7 +157,11 @@ export function processarFiltros(opcoes) {
         tipoProjeto
     };
 }
+/**
+ * Aplica filtros processados ao config global
+ */
 export function aplicarFiltrosAoConfig(filtros) {
+    // Configurar includes
     if (filtros.includeFlat.length > 0) {
         config.CLI_INCLUDE_GROUPS = filtros.includeGroups;
         config.CLI_INCLUDE_PATTERNS = filtros.includeFlat;
@@ -97,11 +170,14 @@ export function aplicarFiltrosAoConfig(filtros) {
         config.CLI_INCLUDE_GROUPS = [];
         config.CLI_INCLUDE_PATTERNS = [];
     }
+    // Configurar excludes
     config.CLI_EXCLUDE_PATTERNS = filtros.excludePadroes;
 }
+/**
+ * API simplificada: processa e aplica filtros em uma única chamada
+ */
 export function configurarFiltros(opcoes) {
     const filtros = processarFiltros(opcoes);
     aplicarFiltrosAoConfig(filtros);
     return filtros;
 }
-//# sourceMappingURL=filters.js.map

package/dist/cli/diagnostic/handlers/archetype-handler.js

@@ -1,24 +1,45 @@
-import { detectarArquetipos } from '../../../analysts/architects/index.js';
+// SPDX-License-Identifier: MIT
+/**
+ * [BUILD] Arquetipo Handler
+ *
+ * Gerencia detecção e análise de estrutura do projeto
+ * - Detecta arquetipos com timeout
+ * - Identifica padrões de projeto
+ * - Salva arquetipos personalizados
+ * - Formata resultados
+ */
 import { config } from '../../../core/config/index.js';
 import { messages } from '../../../core/messages/index.js';
+import { detectarArquetipos } from '../../../analysts/architects/index.js';
 const log = messages.log;
+/**
+ * Timeout padrão para detecção (em ms)
+ */
 const PADRAO_TEMPO_LIMITE_MS = process.env.VITEST ? 1000 : 30000;
+/**
+ * Executa detecção de arquetipos com timeout
+ */
 export async function executarDeteccaoArquetipos(entries, baseDir, options) {
+    // Se desabilitado, retorna resultado vazio
     if (!options.enabled) {
         return {
             executado: false
         };
     }
     try {
+        // Log de início (se não silencioso)
         if (!options.silent) {
             log.info(messages.MENSAGENS_ARQUETIPOS.detectando);
         }
+        // Preparar contexto
         const ctx = {
             arquivos: entries,
             baseDir
         };
-        const timeoutMs = options.timeout || PADRAO_TEMPO_LIMITE_MS;
+        // Executar detecção com timeout
+        const timeoutMs = options.timeout ?? PADRAO_TEMPO_LIMITE_MS;
         const resultado = await executarComTimeout(detectarArquetipos(ctx, baseDir), timeoutMs);
+        // Se timeout ou erro, retorna resultado parcial
         if (!resultado) {
             if (!options.silent) {
                 log.aviso(messages.CliArquetipoHandlerMensagens.timeoutDeteccao);
@@ -28,14 +49,16 @@ export async function executarDeteccaoArquetipos(entries, baseDir, options) {
                 erro: 'timeout'
             };
         }
+        // Processar resultado
         const arquetipos = resultado.candidatos || [];
-        const principal = arquetipos.length > 0 ? arquetipos[0] : undefined;
+        const principal = arquetipos.length > 0 ? arquetipos[0] : undefined; // Log de resultado (se não silencioso)
         if (!options.silent && principal) {
             log.info(messages.MENSAGENS_ARQUETIPOS.identificado(principal.nome, principal.confidence));
             if (arquetipos.length > 1) {
                 log.info(messages.MENSAGENS_ARQUETIPOS.multiplos(arquetipos.length));
             }
         }
+        // Salvar se solicitado
         let salvo = false;
         if (options.salvar && resultado) {
             salvo = await salvarArquetipo(resultado, baseDir, options.silent);
@@ -59,6 +82,7 @@ export async function executarDeteccaoArquetipos(entries, baseDir, options) {
         if (!options.silent) {
             log.aviso(messages.CliArquetipoHandlerMensagens.erroDeteccao(mensagem));
         }
+        // Em DEV_MODE, log mais detalhado
         if (config.DEV_MODE) {
             console.error(messages.CliArquetipoHandlerMensagens.devErroPrefixo, erro);
         }
@@ -68,22 +92,30 @@ export async function executarDeteccaoArquetipos(entries, baseDir, options) {
         };
     }
 }
+/**
+ * Executa função com timeout
+ */
 async function executarComTimeout(promise, timeoutMs) {
     try {
-        const timeoutPromise = new Promise(resolve => setTimeout(() => resolve(undefined), timeoutMs));
+        const timeoutPromise = new Promise(resolve => setTimeout(() => { resolve(undefined); }, timeoutMs));
         return await Promise.race([promise, timeoutPromise]);
     }
     catch {
         return undefined;
     }
 }
+/**
+ * Salva arquetipo personalizado
+ */
 async function salvarArquetipo(resultado, baseDir, silent) {
     try {
         if (!silent) {
             log.info(messages.MENSAGENS_ARQUETIPOS.salvando);
         }
+        // Importação dinâmica para evitar dependências circulares
         const fs = await import('node:fs/promises');
         const path = await import('node:path');
+        // Preparar dados do arquetipo
         const arquetipo = {
             timestamp: new Date().toISOString(),
             projeto: path.basename(baseDir),
@@ -91,6 +123,7 @@ async function salvarArquetipo(resultado, baseDir, silent) {
             baseline: resultado.baseline,
             drift: resultado.drift
         };
+        // Salvar em arquivo
         const outputCaminho = path.join(baseDir, 'mahoraga.repo.arquetipo.json');
         await fs.writeFile(outputCaminho, JSON.stringify(arquetipo, null, 2), 'utf-8');
         if (!silent) {
@@ -106,6 +139,9 @@ async function salvarArquetipo(resultado, baseDir, silent) {
         return false;
     }
 }
+/**
+ * Formata resultado de arquetipos para JSON
+ */
 export function formatarArquetiposParaJson(result) {
     if (!result.executado) {
         return {
@@ -120,17 +156,21 @@ export function formatarArquetiposParaJson(result) {
     }
     return {
         executado: true,
-        arquetipos: result.arquetipos || [],
-        principal: result.principal || null,
-        salvo: result.salvo || false
+        arquetipos: result.arquetipos ?? [],
+        principal: result.principal ?? null,
+        salvo: result.salvo ?? false
     };
 }
+/**
+ * Gera sugestões baseadas no arquetipo detectado
+ */
 export function gerarSugestoesArquetipo(result) {
     const sugestoes = [];
     if (!result.executado || !result.principal) {
         return sugestoes;
     }
     const { tipo, confianca } = result.principal;
+    // Sugestões baseadas no tipo de projeto
     switch (tipo.toLowerCase()) {
         case 'monorepo':
             sugestoes.push('[IDEIA] Monorepo detectado: considere usar filtros por workspace');
@@ -156,10 +196,10 @@ export function gerarSugestoesArquetipo(result) {
             sugestoes.push('[IDEIA] Frontend detectado: priorize componentes e state management');
             break;
     }
+    // Sugestão baseada em confiança
     if (confianca < 70) {
         sugestoes.push('[AVISO]  Confiança baixa na detecção: estrutura pode ser híbrida');
         sugestoes.push('[IDEIA] Use --criar-arquetipo --salvar-arquetipo para personalizar');
     }
     return sugestoes;
 }
-//# sourceMappingURL=archetype-handler.js.map