@mocoto/mahoraga 0.14.0 → 0.14.2

package/dist/core/execution/ast-cache.js

@@ -1,5 +1,18 @@
 import { decifrarSintaxe, TEM_PARSER } from '../parsing/parser.js';
 const AST_SENTINEL = {};
+/**
+ * Cache de AST com escopo de execução.
+ *
+ * Compartilha ASTs entre analistas que processam o mesmo arquivo
+ * durante uma única execução de análise. Elimina re-parsing
+ * desnecessário quando múltiplas técnicas atuam sobre o mesmo arquivo.
+ *
+ * Funciona em conjunto com o cache global (process-level) mantido
+ * pelo inquisidor, mas adiciona uma camada por escopo que:
+ * - Garante consistência dentro da mesma execução
+ * - Prepara o terreno para parsing lazy (parsear sob demanda)
+ * - Coleta métricas granulares por escopo
+ */
 export class ScopeAstCache {
     cache = new Map();
     metrics = {
@@ -8,25 +21,34 @@ export class ScopeAstCache {
         parseTimeMs: 0,
         cachedFiles: 0,
     };
+    /**
+     * Obtém ou faz parse do AST para um arquivo.
+     * Primeiro verifica o cache do escopo, depois o cache global
+     * (process-level), e por fim faz o parsing do conteúdo.
+     */
     async getOrParse(entry, ext) {
         const key = entry.relPath;
+        // 1) Cache do escopo atual
         const cached = this.cache.get(key);
         if (cached !== undefined) {
             this.metrics.hits++;
             return cached;
         }
+        // Pula extensões sem parser registrado
         if (!TEM_PARSER(ext)) {
             this.cache.set(key, null);
             return null;
         }
+        // 2) Cache global (process-level) do inquisidor
         const globalStore = globalThis;
-        const globalCache = globalStore.__MAHORAGA_AST_CACHE__;
+        const globalCache = globalStore.__SUKUNA_AST_CACHE__;
         const globalEntry = globalCache?.get(key);
         if (globalEntry?.ast) {
             this.cache.set(key, globalEntry.ast);
             this.metrics.hits++;
             return globalEntry.ast;
         }
+        // 3) Parsing sob demanda
         this.metrics.misses++;
         const inicio = performance.now();
         let ast = null;
@@ -45,15 +67,23 @@ export class ScopeAstCache {
         this.metrics.cachedFiles = this.cache.size;
         return ast;
     }
+    /**
+     * Verifica se um arquivo já está em cache neste escopo
+     */
     has(relPath) {
         return this.cache.has(relPath);
     }
+    /**
+     * Retorna métricas acumuladas do escopo atual
+     */
     getMetrics() {
         return { ...this.metrics };
     }
+    /**
+     * Limpa o cache do escopo
+     */
     clear() {
         this.cache.clear();
         this.metrics = { hits: 0, misses: 0, parseTimeMs: 0, cachedFiles: 0 };
     }
 }
-//# sourceMappingURL=ast-cache.js.map

package/dist/core/execution/executor.js

@@ -1,28 +1,30 @@
+// SPDX-License-Identifier: MIT
 import crypto from 'node:crypto';
 import path from 'node:path';
+import XXH from 'xxhashjs';
 import { config, formatMs, traverse } from '../config/index.js';
 import { messages } from '../messages/index.js';
 import { createDefaultReporter } from '../reporting/index.js';
 import { WorkerPool } from '../workers/index.js';
 import { calcularHashEstrutural } from '../../shared/helpers/index.js';
 import { lerEstado, salvarEstado } from '../../shared/persistence/index.js';
-import XXH from 'xxhashjs';
-import { ocorrenciaErroAnalista } from '../../types/index.js';
 import { analysisCache } from './analysis-cache.js';
 import { ScopeAstCache } from './ast-cache.js';
+import { ocorrenciaErroAnalista } from '../../types/index.js';
 async function withTimeout(value, timeoutMs, errorMessage) {
-    let timer = null;
+    let timer = undefined;
     try {
         return await Promise.race([
             Promise.resolve(value),
             new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error(errorMessage)), timeoutMs);
+                timer = setTimeout(() => { reject(new Error(errorMessage)); }, timeoutMs);
             })
         ]);
     }
     finally {
-        if (timer)
+        if (timer !== undefined) {
             clearTimeout(timer);
+        }
     }
 }
 function getGlobalExec() {
@@ -30,8 +32,9 @@ function getGlobalExec() {
 }
 async function persistMetricHistory(metricas) {
     const historicoCaminho = config.ANALISE_METRICAS_HISTORICO_PATH;
-    if (!historicoCaminho)
+    if (!historicoCaminho) {
         return;
+    }
     const anterior = await lerEstado(historicoCaminho).catch(() => []);
     const lista = Array.isArray(anterior) ? anterior : [];
     lista.push({ ...metricas, timestamp: Date.now() });
@@ -50,11 +53,10 @@ function infoDestaque(msg) {
 function combinarVisitors(tecnicas) {
     const visitantes = tecnicas.filter((t) => 'visitor' in t);
     const visitorCombinado = {};
-    if (visitantes.length === 0)
+    if (visitantes.length === 0) {
         return visitorCombinado;
+    }
     for (const item of visitantes) {
-        if (!item.visitor)
-            continue;
         for (const [key, val] of Object.entries(item.visitor)) {
             if (!visitorCombinado[key]) {
                 visitorCombinado[key] = val;
@@ -65,7 +67,7 @@ function combinarVisitors(tecnicas) {
                     if (typeof prev === 'function') {
                         prev(path, state);
                     }
-                    else if (prev && typeof prev === 'object' && 'enter' in prev && typeof prev.enter === 'function') {
+                    else if (typeof prev === 'object' && 'enter' in prev && typeof prev.enter === 'function') {
                         prev.enter(path, state);
                     }
                     if (typeof val === 'function') {
@@ -104,38 +106,45 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
     };
     const reporter = createDefaultReporter();
     const inicioExecucao = performance.now();
+    // Cache de AST compartilhado entre analistas no mesmo escopo
+    // Parsing lazy: ASTs são parseados sob demanda via getOrParse
     const scopeAstCache = new ScopeAstCache();
     function hasNodeType(x) {
-        if (typeof x !== 'object' || x === null)
+        if (typeof x !== 'object' || x === null) {
             return false;
+        }
         const maybe = x;
-        if (!maybe.node || typeof maybe.node !== 'object')
+        if (!maybe.node || typeof maybe.node !== 'object') {
             return false;
+        }
         return 'type' in maybe.node;
     }
     async function processGlobalTechniques(tecnicas, ctx, pushFn, metricaList, opts) {
         const timeoutMs = config.ANALISE_TIMEOUT_POR_ANALISTA_MS;
         for (const tecnica of tecnicas) {
-            if (!tecnica.global)
+            if (!tecnica.global) {
                 continue;
+            }
             try {
                 const inicioAnalista = performance.now();
                 const result = timeoutMs > 0
-                    ? await withTimeout(tecnica.aplicar('', '', null, undefined, ctx), timeoutMs, messages.ExecutorExtraMensagens.timeoutGlobal.replace('{nome}', tecnica.nome || 'desconhecido').replace('{timeout}', String(timeoutMs)))
+                    ? await withTimeout(tecnica.aplicar('', '', null, undefined, ctx), timeoutMs, messages.ExecutorExtraMensagens.timeoutGlobal.replace('{nome}', tecnica.nome ?? 'desconhecido').replace('{timeout}', String(timeoutMs)))
                     : await tecnica.aplicar('', '', null, undefined, ctx);
-                if (Array.isArray(result))
+                if (Array.isArray(result)) {
                     pushFn(...result);
+                }
                 const duracaoMs = performance.now() - inicioAnalista;
                 if (config.ANALISE_METRICAS_ENABLED) {
                     metricaList.push({
-                        nome: tecnica.nome || 'desconhecido',
+                        nome: tecnica.nome ?? 'desconhecido',
                         duracaoMs,
                         ocorrencias: Array.isArray(result) ? result.length : result ? 1 : 0,
                         global: true
                     });
                 }
-                if (opts?.verbose)
-                    messages.log.sucesso(messages.ExecutorExtraMensagens.tecnicaGlobal.replace('{nome}', tecnica.nome || 'desconhecido'));
+                if (opts?.verbose) {
+                    messages.log.sucesso(messages.ExecutorExtraMensagens.tecnicaGlobal.replace('{nome}', tecnica.nome ?? 'desconhecido'));
+                }
                 if (config.LOG_ESTRUTURADO) {
                     messages.log.info(JSON.stringify({ tipo: 'analista', escopo: 'global', nome: tecnica.nome, duracaoMs, ocorrencias: metricaList.at(-1)?.ocorrencias }));
                 }
@@ -149,7 +158,7 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
                     messages.log.aviso(`${prefixo} ${err.message}`);
                 }
                 else {
-                    messages.log.erro(`${prefixo} ${messages.ExecutorExtraMensagens.erroTecnicaGlobal.replace('{prefixo}', prefixo).replace('{nome}', tecnica.nome || 'desconhecido').replace('{erro}', err.message)}`);
+                    messages.log.erro(`${prefixo} ${messages.ExecutorExtraMensagens.erroTecnicaGlobal.replace('{prefixo}', prefixo).replace('{nome}', tecnica.nome ?? 'desconhecido').replace('{erro}', err.message)}`);
                     if (err.stack && (opts?.verbose || config.DEV_MODE)) {
                         messages.log.info(messages.ExecutorExtraMensagens.stackTrace);
                         messages.log.info(err.stack);
@@ -164,11 +173,13 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
             }
         }
     }
+    // Incremental: carregar estado anterior (tipo importado de @types)
     let estadoIncremental = null;
     if (config.ANALISE_INCREMENTAL_ENABLED) {
         const lido = await lerEstado(config.ANALISE_INCREMENTAL_STATE_PATH).catch(() => null);
-        if (lido && lido.versao === config.ANALISE_INCREMENTAL_VERSION)
+        if (lido?.versao === config.ANALISE_INCREMENTAL_VERSION) {
             estadoIncremental = lido;
+        }
     }
     const novoEstado = {
         versao: config.ANALISE_INCREMENTAL_VERSION,
@@ -181,9 +192,13 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
     };
     function hashConteudo(elem) {
         try {
+            // Usa xxhash64 (seed arbitrária) para performance
             return XXH.h64(elem, 0xabcd).toString(16);
         }
         catch {
+            // Fallback para SHA1 se algo der errado
+            // SHA1 usado apenas para cache de AST (fingerprinting de conteúdo)
+            // Não é usado para segurança/criptografia - contexto: deduplicação de parsing
             return crypto.createHash('sha1').update(elem).digest('hex');
         }
     }
@@ -207,13 +222,11 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
                     const hash = hashConteudo(entry.content ?? '');
                     novoEstado.arquivos[entry.relPath] = { hash, ocorrencias: [], reaproveitadoCount: 0 };
                 }
-                if (novoEstado.estatisticas) {
-                    novoEstado.estatisticas.totalArquivosProcessados = fileEntriesComAst.length;
-                    novoEstado.estatisticas.ultimaDuracaoMs = duracao;
-                }
+                novoEstado.estatisticas.totalArquivosProcessados = fileEntriesComAst.length;
+                novoEstado.estatisticas.ultimaDuracaoMs = duracao;
                 await salvarEstado(config.ANALISE_INCREMENTAL_STATE_PATH, novoEstado);
             }
-            catch { }
+            catch { /* Ignora erro ao salvar cache */ }
         }
         const metricasExecucao = {
             totalArquivos: fileEntriesComAst.length,
@@ -230,20 +243,24 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
             duracaoMs: duracao,
             metricas: metricasExecucao
         };
-        if (emitter)
+        if (emitter) {
             emitter.emit('analysis:complete', resultadoFast);
+        }
         return resultadoFast;
     }
     const usarWorkerPool = (() => {
-        if (opts?.sequential)
+        if (opts?.sequential) {
             return false;
-        if (opts?.fast !== undefined)
+        }
+        if (opts?.fast !== undefined) {
             return opts.fast;
+        }
         return config.WORKER_POOL_ENABLED && fileEntriesComAst.length > config.WORKER_POOL_AUTO_THRESHOLD;
     })();
     if (usarWorkerPool && fileEntriesComAst.length > 0) {
         return processarWorkerPool();
     }
+    // Técnicas por arquivo (modo sequencial padrão)
     const contextoGlobal = {
         ...contextoGlobalBase,
         report: event => {
@@ -251,9 +268,10 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
                 pushOcorrencia(reporter(event));
             }
             catch (erro) {
+                // Reporter nunca deve quebrar a análise; se falhar, emite ocorrência genérica.
                 pushOcorrencia(ocorrenciaErroAnalista({
                     mensagem: messages.ExecutorExtraMensagens.falhaReporter(erro instanceof Error ? erro.message : String(erro)),
-                    relPath: event?.relPath || '[report]',
+                    relPath: event.relPath || '[report]',
                     origem: 'reporter'
                 }));
             }
@@ -262,22 +280,30 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
     const visitorCombinado = combinarVisitors(tecnicas);
     let arquivoAtual = 0;
     const totalArquivos = fileEntriesComAst.length;
-    const LIMIAR_DETALHE_TOTAL = 100;
-    const LIMIAR_DETALHE_LIMITADO_MAX = 250;
+    // Limiar para logs detalhados por arquivo
+    const LIMIAR_DETALHE_TOTAL = 100; // até aqui permite detalhar por arquivo
+    const LIMIAR_DETALHE_LIMITADO_MAX = 250; // até aqui permite "Arquivo X/Y" com throttle
+    // Define passo de logging quando em modo verbose para evitar spam massivo
     function passoDeLog(total) {
-        if (total <= 100)
+        // Assumimos faixas: até 100 => cada arquivo; 101-250 => a cada 10; 251-500 => a cada 25; >500 => a cada 100
+        if (total <= 100) {
             return 1;
-        if (total <= 250)
+        }
+        if (total <= 250) {
             return 10;
-        if (total <= 500)
+        }
+        if (total <= 500) {
             return 25;
+        }
         return 100;
     }
     const frames = ['->', '=>', '>>', '=>'];
     const stepVerbose = passoDeLog(totalArquivos);
     const detalharPorArquivo = (opts?.verbose ?? false) && totalArquivos <= LIMIAR_DETALHE_TOTAL;
     const permitirArquivoXY = (opts?.verbose ?? false) && totalArquivos <= LIMIAR_DETALHE_LIMITADO_MAX;
+    // Inicializa sistema de logs inteligente
     messages.logAnalistas.iniciarBatch(totalArquivos);
+    // Pool de objetos reutilizáveis entre arquivos (reduz GC pressure)
     const resultadosOtimizados = new Map();
     for (const entry of fileEntriesComAst) {
         arquivoAtual++;
@@ -288,6 +314,7 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
             }
         }
         else if (opts?.verbose) {
+            // Em verbose: detalha por arquivo somente até o limiar; entre 101-250 mostra "Arquivo X/Y" com throttle; acima disso, só resumo de progresso.
             if (permitirArquivoXY) {
                 if (arquivoAtual === 1 || arquivoAtual % stepVerbose === 0 || arquivoAtual === totalArquivos) {
                     const seta = frames[arquivoAtual % frames.length];
@@ -301,22 +328,27 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
             }
         }
         else if (arquivoAtual % 50 === 0 || arquivoAtual === totalArquivos) {
+            // Modo padrão: log apenas a cada 50 arquivos para reduzir ruído
             if (arquivoAtual === totalArquivos) {
                 infoDestaque(messages.ExecutorExtraMensagens.progresso.replace('{atual}', String(arquivoAtual)).replace('{total}', String(totalArquivos)));
             }
         }
+        // Resolve AST via cache compartilhado do escopo
         const ext = path.extname(entry.relPath);
         const astDoCache = await scopeAstCache.getOrParse(entry, ext);
         const astParaUso = astDoCache ?? entry.ast;
+        // Verifica incremento com fallback para diff estrutural
         const conteudo = entry.content ?? '';
         const hash = hashConteudo(conteudo);
         const cacheAnterior = estadoIncremental?.arquivos[entry.relPath];
         let reaproveitou = false;
         if (config.ANALISE_INCREMENTAL_ENABLED && cacheAnterior) {
             if (cacheAnterior.hash === hash) {
+                // Conteúdo exato igual → reuso total
                 reaproveitou = true;
             }
             else if (cacheAnterior.hashEstrutural) {
+                // Conteúdo mudou, verifica se apenas formatação/comentários mudaram
                 const hashEstrutural = calcularHashEstrutural(astParaUso, conteudo);
                 if (hashEstrutural && hashEstrutural === cacheAnterior.hashEstrutural) {
                     reaproveitou = true;
@@ -326,25 +358,26 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
                 }
             }
             if (reaproveitou) {
-                pushOcorrencia(...cacheAnterior.ocorrencias);
+                pushOcorrencia(...(cacheAnterior.ocorrencias ?? []));
                 novoEstado.arquivos[entry.relPath] = { ...cacheAnterior, hash, hashEstrutural: cacheAnterior.hashEstrutural };
-                novoEstado.arquivos[entry.relPath].reaproveitadoCount = (cacheAnterior.reaproveitadoCount || 0) + 1;
-                if (novoEstado.estatisticas) {
-                    novoEstado.estatisticas.totalReaproveitamentos = (novoEstado.estatisticas.totalReaproveitamentos || 0) + 1;
-                }
-                if (detalharPorArquivo)
+                novoEstado.arquivos[entry.relPath].reaproveitadoCount = (cacheAnterior.reaproveitadoCount ?? 0) + 1;
+                novoEstado.estatisticas.totalReaproveitamentos = (novoEstado.estatisticas.totalReaproveitamentos || 0) + 1;
+                if (detalharPorArquivo) {
                     messages.logCore.reaproveitadoIncremental(entry.relPath);
+                }
                 if (config.LOG_ESTRUTURADO) {
                     messages.log.info(JSON.stringify({
                         tipo: 'incremental-reuse',
                         arquivo: entry.relPath,
-                        ocorrencias: cacheAnterior.ocorrencias.length
+                        ocorrencias: cacheAnterior.ocorrencias?.length ?? 0
                     }));
                 }
             }
         }
-        if (reaproveitou)
+        if (reaproveitou) {
             continue;
+        } // pula analistas
+        // Cache de análise entre execuções
         if (config.ANALISE_CACHE_ENABLED) {
             const cached = await analysisCache.get(entry.relPath, entry.content ?? '');
             if (cached !== null) {
@@ -354,21 +387,23 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
                     ocorrencias: cached,
                     reaproveitadoCount: 1
                 };
-                if (detalharPorArquivo)
+                if (detalharPorArquivo) {
                     messages.logCore.reaproveitadoIncremental(`${entry.relPath} (analysis cache)`);
+                }
                 if (config.LOG_ESTRUTURADO) {
                     messages.log.info(JSON.stringify({ tipo: 'cache-reuse', arquivo: entry.relPath, ocorrencias: cached.length }));
                 }
                 continue;
             }
         }
+        // Otimização: Travessia única para analistas com visitor
         if (Object.keys(visitorCombinado).length > 0 && astParaUso) {
             try {
                 const astParam = hasNodeType(astParaUso) ? astParaUso.node : astParaUso;
                 traverse(astParam, visitorCombinado, undefined, {
                     relPath: entry.relPath,
                     contexto: contextoGlobal,
-                    resultados: resultadosOtimizados
+                    resultados: resultadosOtimizados // Mapa de analista -> achados
                 });
             }
             catch (err) {
@@ -376,25 +411,29 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
             }
         }
         for (const tecnica of tecnicas) {
-            if (tecnica.global)
+            if (tecnica.global) {
                 continue;
-            if (tecnica.test && !tecnica.test(entry.relPath))
+            }
+            if (tecnica.test && !tecnica.test(entry.relPath)) {
                 continue;
+            }
+            // início medido apenas por analista específico (inicioAnalista)
             const timeoutMs = config.ANALISE_TIMEOUT_POR_ANALISTA_MS;
             try {
                 const inicioAnalista = performance.now();
+                // Log adaptativo: início da análise
                 const tamanhoArquivo = entry.content ? Math.round(entry.content.length / 1024) : 0;
-                messages.logAnalistas.iniciandoAnalista(tecnica.nome || 'analista-desconhecido', entry.relPath, tamanhoArquivo);
+                messages.logAnalistas.iniciandoAnalista(tecnica.nome ?? 'analista-desconhecido', entry.relPath, tamanhoArquivo);
                 let resultado;
                 const astNode = hasNodeType(astParaUso) ? astParaUso.node : null;
                 const temVisitor = 'visitor' in tecnica;
                 const astParam = temVisitor ? {
                     node: astNode,
-                    preColetado: resultadosOtimizados.get(tecnica.nome || '')
+                    preColetado: resultadosOtimizados.get(tecnica.nome ?? '')
                 } : null;
                 const execPromise = tecnica.aplicar(entry.content ?? '', entry.relPath, astParam, entry.fullCaminho, contextoGlobal);
                 if (timeoutMs > 0) {
-                    resultado = await withTimeout(execPromise, timeoutMs, messages.ExecutorExtraMensagens.timeoutAnalista.replace('{nome}', tecnica.nome || 'desconhecido').replace('{timeout}', String(timeoutMs)).replace('{arquivo}', entry.relPath));
+                    resultado = await withTimeout(execPromise, timeoutMs, messages.ExecutorExtraMensagens.timeoutAnalista.replace('{nome}', tecnica.nome ?? 'desconhecido').replace('{timeout}', String(timeoutMs)).replace('{arquivo}', entry.relPath));
                 }
                 else {
                     resultado = await execPromise;
@@ -405,14 +444,15 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
                 const duracaoMs = performance.now() - inicioAnalista;
                 if (config.ANALISE_METRICAS_ENABLED) {
                     metricasAnalistas.push({
-                        nome: tecnica.nome || 'desconhecido',
+                        nome: tecnica.nome ?? 'desconhecido',
                         duracaoMs,
                         ocorrencias: Array.isArray(resultado) ? resultado.length : resultado ? 1 : 0,
                         global: false
                     });
                 }
+                // Log adaptativo: conclusão da análise
                 const ocorrenciasContagem = Array.isArray(resultado) ? resultado.length : resultado ? 1 : 0;
-                messages.logAnalistas.concluido(tecnica.nome || 'analista-desconhecido', entry.relPath, ocorrenciasContagem, duracaoMs);
+                messages.logAnalistas.concluido(tecnica.nome ?? 'analista-desconhecido', entry.relPath, ocorrenciasContagem, duracaoMs);
                 if (detalharPorArquivo) {
                     messages.log.info(`[FILE] '${tecnica.nome}' analisou ${entry.relPath} em ${formatMs(duracaoMs)}`);
                 }
@@ -431,18 +471,21 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
                 const isTempoLimite = err.message.includes('Timeout: analista');
                 const nivelLog = isTempoLimite ? 'aviso' : 'erro';
                 const prefixo = isTempoLimite ? '[CLOCK]' : '[ERRO]';
+                // Log adaptativo para erros e timeouts
                 if (isTempoLimite) {
                     const duracaoEstimada = config.ANALISE_TIMEOUT_POR_ANALISTA_MS || 30000;
-                    messages.logAnalistas.timeout(tecnica.nome || 'analista-desconhecido', duracaoEstimada);
+                    messages.logAnalistas.timeout(tecnica.nome ?? 'analista-desconhecido', duracaoEstimada);
                 }
                 else {
-                    messages.logAnalistas.erro(tecnica.nome || 'analista-desconhecido', err.message);
+                    messages.logAnalistas.erro(tecnica.nome ?? 'analista-desconhecido', err.message);
                 }
+                // Log apropriado baseado no tipo de erro
                 if (nivelLog === 'aviso') {
                     messages.log.aviso(`${prefixo} ${err.message}`);
                 }
                 else {
                     messages.log.erro(`${prefixo} Erro em '${tecnica.nome}' para ${entry.relPath}: ${err.message}`);
+                    // Exibe stack trace em modo verbose ou debug
                     if (err.stack) {
                         if (opts?.verbose || config.DEV_MODE) {
                             messages.log.info(messages.ExecutorExtraMensagens.stackTrace);
@@ -450,6 +493,7 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
                         }
                     }
                 }
+                // Registra ocorrência de erro/timeout com stack trace
                 pushOcorrencia(ocorrenciaErroAnalista({
                     mensagem: isTempoLimite ? `Timeout na técnica '${tecnica.nome}' para ${entry.relPath}: ${timeoutMs}ms excedido` : `Falha na técnica '${tecnica.nome}' para ${entry.relPath}: ${err.message}`,
                     relPath: entry.relPath,
@@ -458,12 +502,15 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
                 }));
             }
         }
+        // Salva no cache de análise entre execuções
         if (config.ANALISE_CACHE_ENABLED) {
             const ocorrArquivoCache = ocorrencias.filter(o => o.relPath === entry.relPath);
             await analysisCache.set(entry.relPath, entry.content ?? '', ocorrArquivoCache);
         }
+        // Salva estado incremental do arquivo processado
         if (config.ANALISE_INCREMENTAL_ENABLED) {
             const ocorrArq = ocorrencias.filter(ocorrencia => ocorrencia.relPath === entry.relPath);
+            // Extrai métricas por analista específicas do arquivo
             const analistasArquivo = {};
             for (const metrica of metricasAnalistas.filter(metrica => !metrica.global)) {
                 analistasArquivo[metrica.nome] = {
@@ -480,10 +527,9 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
                 ultimaExecucaoMs: Date.now(),
                 reaproveitadoCount: 0
             };
-            if (novoEstado.estatisticas) {
-                novoEstado.estatisticas.totalArquivosProcessados = (novoEstado.estatisticas.totalArquivosProcessados || 0) + 1;
-            }
+            novoEstado.estatisticas.totalArquivosProcessados = (novoEstado.estatisticas.totalArquivosProcessados || 0) + 1;
         }
+        // NOVO: Atualiza progresso por arquivo (não por analista)
         messages.logAnalistas.arquivoProcessado();
         if (emitter) {
             const ocorrArquivo = ocorrencias.filter(ocorrencia => ocorrencia.relPath === entry.relPath);
@@ -498,7 +544,7 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
     messages.logAnalistas.finalizarBatch(ocorrencias.length, duracaoMs);
     let metricasExecucao = null;
     if (config.ANALISE_METRICAS_ENABLED) {
-        const metricasGlobais = getGlobalExec().__MAHORAGA_METRICAS__ || { parsingTimeMs: 0, cacheHits: 0, cacheMiss: 0 };
+        const metricasGlobais = getGlobalExec().__SUKUNA_METRICAS__ ?? { parsingTimeMs: 0, cacheHits: 0, cacheMiss: 0 };
         const astCacheMetrics = scopeAstCache.getMetrics();
         metricasExecucao = {
             totalArquivos: fileEntriesComAst.length,
@@ -528,16 +574,14 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
         await analysisCache.persistir().catch(() => { });
     }
     if (config.ANALISE_INCREMENTAL_ENABLED) {
-        if (novoEstado.estatisticas) {
-            novoEstado.estatisticas.ultimaDuracaoMs = duracaoMs;
-        }
+        novoEstado.estatisticas.ultimaDuracaoMs = duracaoMs;
         await salvarEstado(config.ANALISE_INCREMENTAL_STATE_PATH, novoEstado);
         if (config.LOG_ESTRUTURADO) {
             messages.log.info(JSON.stringify({
                 tipo: 'incremental-salvo',
                 arquivos: Object.keys(novoEstado.arquivos).length,
-                totalReaproveitamentos: novoEstado.estatisticas?.totalReaproveitamentos,
-                processados: novoEstado.estatisticas?.totalArquivosProcessados
+                totalReaproveitamentos: novoEstado.estatisticas.totalReaproveitamentos,
+                processados: novoEstado.estatisticas.totalArquivosProcessados
             }));
         }
     }
@@ -547,7 +591,7 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
         ocorrencias,
         timestamp: Date.now(),
         duracaoMs,
-        metricas: metricasExecucao || undefined
+        metricas: metricasExecucao ?? undefined
     };
     if (emitter) {
         emitter.emit('analysis:complete', resultado);
@@ -556,9 +600,9 @@ export async function executarInquisicao(fileEntriesComAst, tecnicas, baseDir, g
 }
 export function registrarUltimasMetricas(metricas) {
     try {
-        getGlobalExec().__ULTIMAS_METRICAS_MAHORAGA__ = metricas || null;
+        getGlobalExec().__ULTIMAS_METRICAS_SUKUNA__ = metricas ?? null;
     }
     catch {
+        /* ignore */
     }
 }
-//# sourceMappingURL=executor.js.map

package/dist/core/execution/fix-001.js

@@ -1,17 +1,29 @@
+// SPDX-License-Identifier: MIT
+/**
+ * [CHAVE-INGLESA] Módulo de Autofix
+ *
+ * Aplica correções sugeridas automaticamente aos arquivos suportados.
+ */
 import fs from 'node:fs';
 import { splitLines } from '../../shared/helpers/index.js';
+/**
+ * Aplica correções estruturadas no conteúdo do arquivo.
+ */
 export function aplicarCorrecoes(conteudo, ocorrencias) {
     const ocorrenciasComFix = ocorrencias.filter(ocorrencia => !!ocorrencia.correcao && ocorrencia.linha);
-    if (ocorrenciasComFix.length === 0)
+    if (ocorrenciasComFix.length === 0) {
         return conteudo;
+    }
     const linhas = splitLines(conteudo);
     const modificadas = new Set();
     for (const oc of ocorrenciasComFix) {
         const fix = oc.correcao;
-        if (!fix || !oc.linha)
+        if (!fix || !oc.linha) {
             continue;
+        }
         const idx = oc.linha - 1;
         if (idx >= 0 && idx < linhas.length && !modificadas.has(idx)) {
+            // Garantir que a linha ainda possui o trecho original esperado (para segurança)
             if (linhas[idx].includes(fix.original)) {
                 linhas[idx] = linhas[idx].replace(fix.original, fix.novo);
                 modificadas.add(idx);
@@ -20,7 +32,9 @@ export function aplicarCorrecoes(conteudo, ocorrencias) {
     }
     return linhas.join('\n');
 }
+/**
+ * Grava o conteúdo corrigido no arquivo.
+ */
 export function salvarArquivoCorrigido(absolutePath, novoConteudo) {
     fs.writeFileSync(absolutePath, novoConteudo, 'utf-8');
 }
-//# sourceMappingURL=fix-001.js.map

package/dist/core/execution/index.js

@@ -1,7 +1,18 @@
+// SPDX-License-Identifier: MIT
+/**
+ * @fileoverview Core execution: executor, inquisidor, scanner
+ */
+export * from './ambiente.js';
 export * from './analysis-cache.js';
 export * from './ast-cache.js';
 export * from './executor.js';
 export * from './fix-001.js';
 export * from './inquisitor.js';
+export * from './linguagens.js';
+export * from './parse-errors.js';
+export * from './registry.js';
+export * from './results.js';
 export * from './scanner.js';
-//# sourceMappingURL=index.js.map
+export * from './schema.js';
+export * from './structure-json.js';
+export * from './workers.js';