@mocoto/mahoraga 0.14.0 → 0.14.1

package/dist/analysts/corrections/map-reversion.js

@@ -1,7 +1,8 @@
+// SPDX-License-Identifier: MIT
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { messages } from '../../core/messages/index.js';
-import { MAHORAGA_ARQUIVOS } from '../../core/registry/index.js';
+import { SUKUNA_ARQUIVOS } from '../../core/registry/index.js';
 import { lerEstado, salvarEstado } from '../../shared/persistence/index.js';
 const { log, logAuto, MapaReversaoExtraMensagens } = messages;
 const CONSTANTES_MAPA = {
@@ -14,7 +15,7 @@ export class GerenciadorMapaReversao {
     mapaPath;
     mapa;
     constructor(opts) {
-        this.mapaPath = opts?.mapaPath ?? MAHORAGA_ARQUIVOS.MAPA_REVERSAO;
+        this.mapaPath = opts?.mapaPath ?? SUKUNA_ARQUIVOS.MAPA_REVERSAO;
         this.mapa = {
             versao: CONSTANTES_MAPA.VERSAO,
             moves: [],
@@ -25,6 +26,9 @@ export class GerenciadorMapaReversao {
             }
         };
     }
+    /**
+     * Carrega o mapa de reversão do disco
+     */
     async carregar() {
         try {
             this.mapa = (await lerEstado(this.mapaPath, null)) ?? {
@@ -36,6 +40,7 @@ export class GerenciadorMapaReversao {
                     podeReverter: true
                 }
             };
+            // Validação básica
             if (!this.mapa.moves || !Array.isArray(this.mapa.moves)) {
                 throw new Error(messages.ExcecoesMensagens.mapaReversaoCorrompido);
             }
@@ -43,10 +48,13 @@ export class GerenciadorMapaReversao {
         }
         catch (error) {
             if (error.code === 'ENOENT') {
+                // Não persistimos automaticamente um mapa vazio ao carregar: evitar efeitos colaterais
+                // (ex.: chamada a fs.mkdir) durante operações que apenas consultam o mapa.
                 logAuto.mapaReversaoNenhumEncontrado();
             }
             else {
                 logAuto.mapaReversaoErroCarregar(error.message);
+                // Reinicia com mapa vazio em caso de erro
                 this.mapa = {
                     versao: CONSTANTES_MAPA.VERSAO,
                     moves: [],
@@ -59,6 +67,9 @@ export class GerenciadorMapaReversao {
             }
         }
     }
+    /**
+     * Salva o mapa de reversão no disco
+     */
     async salvar() {
         try {
             await fs.mkdir(path.dirname(this.mapaPath), {
@@ -71,7 +82,12 @@ export class GerenciadorMapaReversao {
             logAuto.mapaReversaoErroSalvar(error.message);
         }
     }
-    async registrarMove(origem, destino, motivo, conteudoOriginal, conteudoFinal, skipSalvar) {
+    /**
+     * Registra um novo move no mapa de reversão
+     */
+    async registrarMove(origem, destino, motivo, conteudoOriginal, conteudoFinal, 
+    // quando true, evita persistir o mapa no disco imediatamente (útil para chamadas em massa/tests)
+    skipSalvar) {
         try {
             const id = `move_${Date.now()}_${Math.random().toString(CONSTANTES_MAPA.RADIX_36).substr(CONSTANTES_MAPA.ID_OFFSET, CONSTANTES_MAPA.ID_LENGTH)}`;
             const move = {
@@ -80,6 +96,8 @@ export class GerenciadorMapaReversao {
                 origem,
                 destino,
                 motivo,
+                // Considera que imports foram reescritos se houver conteúdo original
+                // fornecido (testes esperam que passar conteudoOriginal permita restauração)
                 importsReescritos: !!conteudoOriginal || !!conteudoFinal && conteudoOriginal !== conteudoFinal,
                 conteudoOriginal,
                 conteudoFinal
@@ -87,6 +105,7 @@ export class GerenciadorMapaReversao {
             this.mapa.moves.push(move);
             this.mapa.metadata.totalMoves = this.mapa.moves.length;
             this.mapa.metadata.ultimoMove = move.timestamp;
+            // Persiste no disco por padrão; caller pode optar por adiar a persistência
             if (!skipSalvar) {
                 await this.salvar();
             }
@@ -98,6 +117,9 @@ export class GerenciadorMapaReversao {
             throw err;
         }
     }
+    /**
+     * Remove um move do mapa de reversão
+     */
     async removerMove(id) {
         try {
             const indice = this.mapa.moves.findIndex((move) => move.id === id);
@@ -115,16 +137,28 @@ export class GerenciadorMapaReversao {
             return false;
         }
     }
+    /**
+     * Obtém todos os moves registrados
+     */
     obterMoves() {
         return [...this.mapa.moves];
     }
+    /**
+     * Obtém moves por arquivo
+     */
     obterMovesPorArquivo(arquivo) {
         return this.mapa.moves.filter((move) => move.origem === arquivo || move.destino === arquivo);
     }
+    /**
+     * Verifica se um arquivo pode ser revertido
+     */
     podeReverterArquivo(arquivo) {
         const moves = this.obterMovesPorArquivo(arquivo);
         return moves.length > 0;
     }
+    /**
+     * Reverte um move específico
+     */
     async reverterMove(id, baseDir = process.cwd()) {
         const move = this.mapa.moves.find((metrica) => metrica.id === id);
         if (!move) {
@@ -137,7 +171,10 @@ export class GerenciadorMapaReversao {
             await fs.mkdir(path.dirname(origemCaminho), {
                 recursive: true
             });
+            // Move o arquivo de volta
             if (move.importsReescritos && move.conteudoOriginal) {
+                // Usa flag 'wx' para escrita exclusiva - falha se o arquivo já existir,
+                // eliminando a condição de corrida TOCTOU entre stat e write
                 try {
                     await fs.writeFile(origemCaminho, move.conteudoOriginal, {
                         encoding: 'utf-8',
@@ -150,7 +187,7 @@ export class GerenciadorMapaReversao {
                         logAuto.mapaReversaoArquivoExisteOrigem(move.origem);
                         return false;
                     }
-                    if (err?.code && err.code !== 'ENOENT') {
+                    if (err.code && err.code !== 'ENOENT') {
                         logAuto.mapaReversaoErroReverter(err.message);
                         return false;
                     }
@@ -160,7 +197,7 @@ export class GerenciadorMapaReversao {
                     await fs.unlink(destinoCaminho);
                 }
                 catch (err) {
-                    if (err?.code === 'ENOENT') {
+                    if (err.code === 'ENOENT') {
                         logAuto.mapaReversaoArquivoDestinoNaoEncontrado(move.destino);
                         return false;
                     }
@@ -169,6 +206,7 @@ export class GerenciadorMapaReversao {
                 log.sucesso(MapaReversaoExtraMensagens.arquivoRevertidoConteudo.replace('{destino}', move.destino).replace('{origem}', move.origem));
             }
             else {
+                // Usa rename atômico - se destino não existir, falha com ENOENT
                 try {
                     await fs.rename(destinoCaminho, origemCaminho);
                 }
@@ -186,6 +224,7 @@ export class GerenciadorMapaReversao {
                 }
                 log.sucesso(MapaReversaoExtraMensagens.arquivoRevertido.replace('{destino}', move.destino).replace('{origem}', move.origem));
             }
+            // Remove o move do mapa
             await this.removerMove(id);
             return true;
         }
@@ -194,19 +233,25 @@ export class GerenciadorMapaReversao {
             return false;
         }
     }
+    /**
+     * Reverte todos os moves de um arquivo
+     */
     async reverterArquivo(arquivo, baseDir = process.cwd()) {
         const moves = this.obterMovesPorArquivo(arquivo);
         if (moves.length === 0) {
             logAuto.mapaReversaoNenhumMove(arquivo);
             return false;
         }
+        // Reverte do mais recente para o mais antigo
         const movesOrdenados = moves.sort((arquivo, base) => new Date(base.timestamp).getTime() - new Date(arquivo.timestamp).getTime());
+        // Retorna true se pelo menos um move foi revertido com sucesso
         let revertedContagem = 0;
         try {
             for (const move of movesOrdenados) {
                 const resultado = await this.reverterMove(move.id, baseDir);
-                if (resultado)
+                if (resultado) {
                     revertedContagem += 1;
+                }
             }
         }
         catch (error) {
@@ -215,11 +260,15 @@ export class GerenciadorMapaReversao {
         }
         return revertedContagem > 0;
     }
+    /**
+     * Lista moves em formato legível
+     */
     listarMoves() {
         if (this.mapa.moves.length === 0) {
             return MapaReversaoExtraMensagens.nenhumMoveRegistrado;
         }
         let resultado = MapaReversaoExtraMensagens.tituloMapa.replace('{total}', String(this.mapa.moves.length));
+        // Ordena por timestamp (mais recente primeiro)
         const movesOrdenados = [...this.mapa.moves].sort((arquivo, base) => new Date(base.timestamp).getTime() - new Date(arquivo.timestamp).getTime());
         for (const move of movesOrdenados) {
             const dataFormatada = new Date(move.timestamp).toLocaleString('pt-BR');
@@ -231,6 +280,9 @@ export class GerenciadorMapaReversao {
         }
         return resultado;
     }
+    /**
+     * Limpa o mapa de reversão
+     */
     async limpar() {
         try {
             this.mapa.moves = [];
@@ -244,5 +296,5 @@ export class GerenciadorMapaReversao {
         }
     }
 }
+// Instância global
 export const mapaReversao = new GerenciadorMapaReversao();
-//# sourceMappingURL=map-reversion.js.map

package/dist/analysts/corrections/pruning.js

@@ -1,13 +1,14 @@
+// SPDX-License-Identifier: MIT
 import path from 'node:path';
-import { detectarFantasmas } from '../detectors/index.js';
+import { gerarRelatorioPodaJson, gerarRelatorioPodaMarkdown } from '../../reports/index.js';
+import pLimit from 'p-limit';
 import { config } from '../../core/config/index.js';
 import { getMessages } from '../../core/messages/index.js';
-import { gerarRelatorioPodaJson, gerarRelatorioPodaMarkdown } from '../../reports/index.js';
+import { detectarFantasmas } from '../detectors/index.js';
 import { ensureDir } from '../../shared/helpers/index.js';
 import { lerEstado, salvarEstado } from '../../shared/persistence/index.js';
-import pLimit from 'p-limit';
 const { log, logAuto } = getMessages();
-export async function removerArquivosOrfaos(_fileEntries) {
+export async function removerArquivosOrfaos(_fileEntries /* executarRealmente = false*/) {
     const { fantasmas } = await detectarFantasmas();
     return {
         arquivosOrfaos: fantasmas
@@ -23,10 +24,12 @@ function gerarPendencias(fantasmas, agora) {
 }
 function mesclarPendencias(anteriores, novos) {
     const mapa = new Map();
-    for (const caminho of anteriores)
+    for (const caminho of anteriores) {
         mapa.set(caminho.arquivo, caminho);
-    for (const caminho of novos)
+    }
+    for (const caminho of novos) {
         mapa.set(caminho.arquivo, caminho);
+    }
     return Array.from(mapa.values());
 }
 function dividirPendencias(pendencias, reativar, _agora) {
@@ -43,7 +46,7 @@ function dividirPendencias(pendencias, reativar, _agora) {
     }
     return [aManter, aPodar];
 }
-const { AUTOANALISE_CONCURRENCY: CONCORRENCIA = 5, ZELADOR_ABANDONED_DIR: DIR_ABANDONADOS, ZELADOR_PENDING_PATH: PATH_PENDENTES, ZELADOR_REACTIVATE_PATH: PATH_REATIVAR, ZELADOR_HISTORY_PATH: PATH_HISTORICO, ZELADOR_REPORT_PATH: PATH_RELATORIO } = config;
+const { AUTOANALISE_CONCURRENCY: CONCORRENCIA, ZELADOR_ABANDONED_DIR: DIR_ABANDONADOS, ZELADOR_PENDING_PATH: PATH_PENDENTES, ZELADOR_REACTIVATE_PATH: PATH_REATIVAR, ZELADOR_HISTORY_PATH: PATH_HISTORICO, ZELADOR_REPORT_PATH: PATH_RELATORIO } = config;
 export async function executarPodaCiclica(executarRealmente = false) {
     log.info('\n[HERB] Iniciando poda automática...\n');
     if (!executarRealmente) {
@@ -72,6 +75,7 @@ export async function executarPodaCiclica(executarRealmente = false) {
         log.sucesso('[BROOM] Podagem concluída.');
     }
     else {
+        // Mesmo em simulação, mostramos contagem para cobrir mensagem esperada
         logAuto.podaPodandoSimulado(aPodar.length);
         moverArquivosSimulado(aPodar, base);
     }
@@ -105,4 +109,3 @@ async function moverArquivos(lista, base, historico) {
         }
     })));
 }
-//# sourceMappingURL=pruning.js.map

package/dist/analysts/corrections/quick-fixes/fix-any-to-proper-type.js

@@ -1,3 +1,8 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Quick Fix: Replace any with proper types
+ * Analisa uso de `any` e infere/cria tipos corretos
+ */
 import { buildTypesRelPathPosix } from '../../../core/config/index.js';
 import { getMessages } from '../../../core/messages/index.js';
 import { isAnyInGenericFunction, isInStringOrComment, isLegacyOrVendorFile, isTypeScriptContext } from '../type-safety/context-analyzer.js';
@@ -16,35 +21,52 @@ export const fixAnyToProperTipo = {
     description: MENSAGENS_CORRECAO_TIPOS.fixAny.description,
     pattern: /:\s*any\b/g,
     category: 'style',
+    // Type safety é considerado 'style' pois não afeta execução
     confidence: CONFIANCA_NIVEIS.DEFAULT,
+    // Média - requer análise contextual
     shouldApply: (match, fullCode, lineContext, fileCaminho) => {
-        if (isInStringOrComment(fullCode, match.index || 0)) {
+        // 1. Verificar contexto básico
+        if (isInStringOrComment(fullCode, match.index ?? 0)) {
             return false;
         }
-        if (isTypeScriptContext(fullCode, match.index || 0)) {
+        // 2. Verificar contexto TypeScript (type assertion, etc)
+        if (isTypeScriptContext(fullCode, match.index ?? 0)) {
             return false;
         }
+        // 3. Não modificar arquivos de definição de tipos
         if (fileCaminho?.includes('.d.ts') || fileCaminho?.includes('/@types/')) {
             return false;
         }
+        // 4. Não modificar vendor/node_modules
         if (isLegacyOrVendorFile(fileCaminho)) {
             return false;
         }
-        if (isAnyInGenericFunction(fullCode, match.index || 0)) {
-            return false;
+        // 5. Verificar se any está em função genérica apropriada
+        if (isAnyInGenericFunction(fullCode, match.index ?? 0)) {
+            return false; // any pode ser apropriado aqui
         }
         return true;
     },
     fix: (match, fullCode) => {
+        // Retornar código sem modificação por padrão
+        // A aplicação real deve ser feita via fixAsync
         return fullCode;
     }
 };
+/**
+ * Versão assíncrona do fix que faz análise completa
+ */
 export async function fixAnyToProperTypeAsync(match, fullCode, fileCaminho, ast) {
     try {
-        const typeAnalise = await analyzeTypeUsage(match, fullCode, fileCaminho, ast);
+        // 1. Analisar uso do tipo
+        const typeAnalise = analyzeTypeUsage(match, fullCode, fileCaminho, ast);
+        // 2. Estratégia baseada em confiança
         if (typeAnalise.confidence >= CONFIANCA_NIVEIS.HIGH) {
+            // ALTA CONFIANÇA: Aplicar tipo automaticamente
             if (typeAnalise.isSimpleType) {
+                // Tipo primitivo: substituir diretamente
                 const fixedCodigo = fullCode.replace(match[0], `: ${typeAnalise.inferredTipo}`);
+                // Validar resultado
                 const validation = await validateTypeReplacement(fullCode, fixedCodigo, typeAnalise);
                 if (!validation.isCompatible) {
                     return {
@@ -69,13 +91,16 @@ export async function fixAnyToProperTypeAsync(match, fullCode, fileCaminho, ast)
                 };
             }
             else {
+                // Tipo complexo: criar interface
                 const typeCaminho = await createTypeDefinition(typeAnalise, fileCaminho);
                 const importStatement = `import type { ${typeAnalise.typeName} } from '${typeCaminho}';\n`;
+                // Adicionar import no topo e substituir any
                 const lines = fullCode.split('\n');
                 const importIndex = findImportInsertionPoint(lines);
                 lines.splice(importIndex, 0, importStatement);
                 let fixedCodigo = lines.join('\n');
                 fixedCodigo = fixedCodigo.replace(match[0], `: ${typeAnalise.typeName}`);
+                // Validar resultado
                 const validation = await validateTypeReplacement(fullCode, fixedCodigo, typeAnalise);
                 if (!validation.isCompatible) {
                     return {
@@ -99,6 +124,7 @@ export async function fixAnyToProperTypeAsync(match, fullCode, fileCaminho, ast)
             }
         }
         else if (typeAnalise.confidence >= CONFIANCA_NIVEIS.MEDIUM) {
+            // MÉDIA CONFIANÇA: Sugerir mas não aplicar
             const warning = {
                 type: 'type-suggestion',
                 message: MENSAGENS_CORRECAO_TIPOS.warnings.confiancaMedia(typeAnalise.confidence, typeAnalise.inferredTipo),
@@ -113,6 +139,7 @@ export async function fixAnyToProperTypeAsync(match, fullCode, fileCaminho, ast)
             };
         }
         else {
+            // BAIXA CONFIANÇA: Apenas avisar
             const warning = {
                 type: 'unsafe-type',
                 message: MENSAGENS_CORRECAO_TIPOS.warnings.confiancaBaixa(typeAnalise.confidence),
@@ -135,20 +162,26 @@ export async function fixAnyToProperTypeAsync(match, fullCode, fileCaminho, ast)
         };
     }
 }
+/**
+ * Encontra ponto de inserção para import
+ */
 function findImportInsertionPoint(lines) {
     let lastImportIndex = -1;
     for (let indice = 0; indice < lines.length; indice++) {
         const line = lines[indice].trim();
+        // Pular comentários no topo
         if (line.startsWith('//') || line.startsWith('/*') || line.startsWith('*')) {
             continue;
         }
+        // Encontrar último import
         if (line.startsWith('import ')) {
             lastImportIndex = indice;
         }
+        // Se encontrou código não-import, parar
         if (line && !line.startsWith('import ') && lastImportIndex !== -1) {
             break;
         }
     }
+    // Inserir após último import ou no topo
     return lastImportIndex + 1;
 }
-//# sourceMappingURL=fix-any-to-proper-type.js.map

package/dist/analysts/corrections/quick-fixes/fix-unknown-to-specific-type.js

@@ -1,3 +1,8 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Quick Fix: Replace unknown with specific types
+ * Mais conservador que fix-any - requer confiança >= 90%
+ */
 import { buildTypesRelPathPosix, getTypesDirectoryDisplay } from '../../../core/config/index.js';
 import { getMessages } from '../../../core/messages/index.js';
 import { isInStringOrComment, isLegacyOrVendorFile, isUnknownInGenericContext } from '../type-safety/context-analyzer.js';
@@ -12,36 +17,50 @@ export const fixUnknownToSpecificTipo = {
     pattern: /:\s*unknown\b/g,
     category: 'style',
     confidence: 75,
+    // Mais conservador que any
     shouldApply: (match, fullCode, lineContext, fileCaminho) => {
-        if (isInStringOrComment(fullCode, match.index || 0)) {
+        // 1. Verificar contexto básico
+        if (isInStringOrComment(fullCode, match.index ?? 0)) {
             return false;
         }
+        // 2. Não modificar arquivos de definição
         if (fileCaminho?.includes('.d.ts') || fileCaminho?.includes('/@types/')) {
             return false;
         }
+        // 3. Não modificar legado/vendor
         if (isLegacyOrVendorFile(fileCaminho)) {
             return false;
         }
-        if (isUnknownInGenericContext(fullCode, match.index || 0)) {
-            return false;
+        // 4. Verificar se unknown está em contexto genérico apropriado
+        if (isUnknownInGenericContext(fullCode, match.index ?? 0)) {
+            return false; // unknown é apropriado aqui (entrada genérica, deserialização, etc)
         }
         return true;
     },
     fix: (match, fullCode) => {
+        // Retornar código sem modificação por padrão
         return fullCode;
     }
 };
+/**
+ * Versão assíncrona com análise completa (conservador)
+ */
 export async function fixUnknownToSpecificTypeAsync(match, fullCode, fileCaminho, ast) {
     try {
+        // 1. Analisar uso (mais conservador que any)
         const typeAnalise = await analyzeUnknownUsage(match, fullCode, fileCaminho, ast);
+        // 2. Estratégia mais conservadora (requer >= 90% confiança)
         if (typeAnalise.confidence >= 90) {
+            // ALTA CONFIANÇA: Criar interface dedicada
             const typeCaminho = await createTypeDefinition(typeAnalise, fileCaminho);
             const importStatement = `import type { ${typeAnalise.typeName} } from '${typeCaminho}';\n`;
+            // Adicionar import e substituir unknown
             const lines = fullCode.split('\n');
             const importIndex = findImportInsertionPoint(lines);
             lines.splice(importIndex, 0, importStatement);
             let fixedCodigo = lines.join('\n');
             fixedCodigo = fixedCodigo.replace(match[0], `: ${typeAnalise.typeName}`);
+            // Validar
             const validation = await validateTypeReplacement(fullCode, fixedCodigo, typeAnalise);
             if (!validation.isCompatible) {
                 return {
@@ -64,6 +83,7 @@ export async function fixUnknownToSpecificTypeAsync(match, fullCode, fileCaminho
             };
         }
         else if (typeAnalise.confidence >= 70) {
+            // MÉDIA CONFIANÇA: Sugerir tipo
             const warning = {
                 type: 'type-suggestion',
                 message: `unknown pode ser substituído por tipo específico: ${typeAnalise.inferredTipo}`,
@@ -78,6 +98,7 @@ export async function fixUnknownToSpecificTypeAsync(match, fullCode, fileCaminho
             };
         }
         else {
+            // BAIXA CONFIANÇA: Manter unknown
             const warning = {
                 type: 'keep-unknown',
                 message: 'unknown apropriado aqui (entrada genérica ou baixa confiança)',
@@ -99,6 +120,9 @@ export async function fixUnknownToSpecificTypeAsync(match, fullCode, fileCaminho
         };
     }
 }
+/**
+ * Encontra ponto de inserção para import
+ */
 function findImportInsertionPoint(lines) {
     let lastImportIndex = -1;
     for (let indice = 0; indice < lines.length; indice++) {
@@ -115,4 +139,3 @@ function findImportInsertionPoint(lines) {
     }
     return lastImportIndex + 1;
 }
-//# sourceMappingURL=fix-unknown-to-specific-type.js.map

package/dist/analysts/corrections/quick-fixes/index.js

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Quick Fixes para Type Safety
+ */
 export * from './fix-any-to-proper-type.js';
 export * from './fix-unknown-to-specific-type.js';
-//# sourceMappingURL=index.js.map