@mocoto/mahoraga 0.14.0 → 0.14.1

package/dist/core/registry/file-registry.js

@@ -1,7 +1,24 @@
+// SPDX-License-Identifier: MIT
+/**
+ * @fileoverview Registry centralizado para operações de leitura/escrita de arquivos JSON
+ *
+ * Este módulo fornece uma camada de abstração sobre a persistência,
+ * gerenciando migrações automáticas de arquivos legados e garantindo
+ * que todos os arquivos sejam salvos nos locais corretos.
+ *
+ * Features:
+ * - Migração automática de arquivos legados
+ * - Validação de integridade de JSONs
+ * - Logging de operações de I/O
+ * - Fallback para configurações seguras
+ */
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { messages } from '../messages/index.js';
-import { MAHORAGA_ARQUIVOS, MAHORAGA_DIRS, MIGRACAO_MAPA } from './paths.js';
+import { MIGRACAO_MAPA, SUKUNA_ARQUIVOS, SUKUNA_DIRS } from './paths.js';
+/**
+ * Verifica se arquivo existe
+ */
 async function fileExists(fileCaminho) {
     try {
         await fs.stat(fileCaminho);
@@ -11,12 +28,18 @@ async function fileExists(fileCaminho) {
         return false;
     }
 }
+/**
+ * Cria diretórios pai se não existirem
+ */
 async function ensureDir(fileCaminho) {
     const dir = path.dirname(fileCaminho);
     await fs.mkdir(dir, {
         recursive: true
     });
 }
+/**
+ * Tenta migrar arquivo legado para novo local
+ */
 async function tryMigrate(targetPath) {
     const legacyCaminho = Object.entries(MIGRACAO_MAPA).find(([_, target]) => target === targetPath)?.[0];
     if (!legacyCaminho) {
@@ -25,14 +48,18 @@ async function tryMigrate(targetPath) {
         };
     }
     try {
+        // Ler arquivo legado (falha se não existir, evitando TOCTOU)
         const content = await fs.readFile(legacyCaminho, 'utf-8');
+        // Garantir diretório de destino
         await ensureDir(targetPath);
+        // Escrever no novo local com flag 'wx' para evitar condição de corrida TOCTOU
         try {
             await fs.writeFile(targetPath, content, { encoding: 'utf-8', flag: 'wx' });
         }
         catch (err) {
             const code = err.code;
             if (code === 'EEXIST') {
+                // Arquivo já foi migrado concorrentemente
                 return {
                     migrated: true,
                     from: legacyCaminho,
@@ -41,8 +68,10 @@ async function tryMigrate(targetPath) {
             }
             throw err;
         }
+        // Renomear arquivo legado (não deletar para segurança)
         const backupCaminho = `${legacyCaminho}.migrated`;
         await fs.rename(legacyCaminho, backupCaminho).catch(() => {
+            // Se falhar ao renomear, o arquivo legado permanece - não é fatal
         });
         messages.log.info(`Migração automática: ${path.basename(legacyCaminho)} → ${path.basename(targetPath)}`);
         return {
@@ -64,19 +93,37 @@ async function tryMigrate(targetPath) {
         };
     }
 }
+/**
+ * Lê arquivo JSON do registry
+ *
+ * @param filePath Caminho do arquivo (use SUKUNA_FILES.*)
+ * @param options Opções de leitura
+ * @returns Conteúdo parseado do JSON
+ *
+ * @example
+ * ```ts
+ * const config = await readJSON(SUKUNA_FILES.CONFIG, {
+ *   default: {}
+ * });
+ * ```
+ */
 export async function readJSON(fileCaminho, options = {}) {
     const { default: defaultValue, migrate = true, validate } = options;
     try {
+        // Tentar migração se habilitado
         if (migrate) {
             const migration = await tryMigrate(fileCaminho);
             if (migration.migrated && migration.to) {
+                // Usar arquivo migrado
                 fileCaminho = migration.to;
             }
         }
+        // Ler e parsear diretamente (sem check de existência separado para evitar TOCTOU)
         const content = await fs.readFile(fileCaminho, 'utf-8');
         const parsed = JSON.parse(content);
+        // Validar se fornecido
         if (validate && !validate(parsed)) {
-            throw new Error(messages.ExcecoesMensagens.validacaoFalhouPara(String(fileCaminho)));
+            throw new Error(messages.ExcecoesMensagens.validacaoFalhouPara(fileCaminho));
         }
         return parsed;
     }
@@ -89,29 +136,55 @@ export async function readJSON(fileCaminho, options = {}) {
             return defaultValue;
         }
         if (code === 'ENOENT') {
-            throw new Error(messages.ExcecoesMensagens.arquivoNaoEncontrado(String(fileCaminho)));
+            throw new Error(messages.ExcecoesMensagens.arquivoNaoEncontrado(fileCaminho));
         }
-        throw new Error(messages.ExcecoesMensagens.erroAoLer(String(fileCaminho), erro.message));
+        throw new Error(messages.ExcecoesMensagens.erroAoLer(fileCaminho, erro.message));
     }
 }
+/**
+ * Escreve arquivo JSON no registry
+ *
+ * @param filePath Caminho do arquivo (use SUKUNA_FILES.*)
+ * @param data Dados a serem salvos
+ * @param options Opções de escrita
+ *
+ * @example
+ * ```ts
+ * await writeJSON(SUKUNA_FILES.GUARDIAN_BASELINE, snapshot, {
+ *   createDirs: true,
+ *   backup: true
+ * });
+ * ```
+ */
 export async function writeJSON(fileCaminho, data, options = {}) {
     const { createDirs = true, backup = false, pretty = true } = options;
     try {
+        // Criar diretórios se necessário
         if (createDirs) {
             await ensureDir(fileCaminho);
         }
+        // Fazer backup se solicitado (copyFile falha com ENOENT se o arquivo não existir, o que é ok)
         if (backup) {
             const backupCaminho = `${fileCaminho}.backup`;
             await fs.copyFile(fileCaminho, backupCaminho).catch(() => {
+                // Se o arquivo não existir, não há backup a fazer
             });
         }
+        // Serializar JSON
         const content = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+        // Escrever arquivo
         await fs.writeFile(fileCaminho, content, 'utf-8');
     }
     catch (erro) {
-        throw new Error(messages.ExcecoesMensagens.erroAoEscrever(String(fileCaminho), erro.message));
+        throw new Error(messages.ExcecoesMensagens.erroAoEscrever(fileCaminho, erro.message));
     }
 }
+/**
+ * Deleta arquivo do registry
+ *
+ * @param filePath Caminho do arquivo (use SUKUNA_FILES.*)
+ * @param options Opções de deleção
+ */
 export async function deleteJSON(fileCaminho, options = {}) {
     const { backup = true } = options;
     try {
@@ -126,11 +199,17 @@ export async function deleteJSON(fileCaminho, options = {}) {
     catch (erro) {
         const code = erro.code;
         if (code === 'ENOENT') {
-            return;
+            return; // Já deletado
         }
-        throw new Error(messages.ExcecoesMensagens.erroAoDeletar(String(fileCaminho), erro.message));
+        throw new Error(messages.ExcecoesMensagens.erroAoDeletar(fileCaminho, erro.message));
     }
 }
+/**
+ * Lista todos os arquivos JSON em um diretório do registry
+ *
+ * @param dirPath Caminho do diretório (use SUKUNA_DIRS.*)
+ * @returns Lista de caminhos completos
+ */
 export async function listJSONFiles(dirPath) {
     try {
         const exists = await fileExists(dirPath);
@@ -148,12 +227,14 @@ export async function listJSONFiles(dirPath) {
         return [];
     }
 }
+/**
+ * Exporta funções auxiliares para compatibilidade com código existente
+ */
 export const ArquivoRegistro = {
     read: readJSON,
     write: writeJSON,
     delete: deleteJSON,
     list: listJSONFiles,
-    paths: MAHORAGA_ARQUIVOS,
-    dirs: MAHORAGA_DIRS
+    paths: SUKUNA_ARQUIVOS,
+    dirs: SUKUNA_DIRS
 };
-//# sourceMappingURL=file-registry.js.map

package/dist/core/registry/index.js

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: MIT
+/**
+ * @fileoverview Core registry: file registry and paths
+ */
 export * from './file-registry.js';
 export * from './paths.js';
-//# sourceMappingURL=index.js.map

package/dist/core/registry/paths.js

@@ -1,40 +1,105 @@
+// SPDX-License-Identifier: MIT
+/**
+ * @fileoverview Gerenciamento centralizado de caminhos para arquivos do Mahoraga
+ *
+ * Este módulo define todos os caminhos de arquivos usados pelo sistema,
+ * evitando hardcoding espalhado e permitindo evolução consistente.
+ *
+ * Convenção de nomes:
+ * - guardian.baseline.json: Baseline de assinaturas GPG do Guardian
+ * - guardian.chave-publica.asc: Chave pública GPG do Guardian
+ * - guardian.chave-privada.asc: Chave privada GPG do Guardian
+ * - estrutura.baseline.json: Baseline da estrutura de diretórios
+ * - estrutura.arquetipo.json: Arquétipo personalizado do repositório
+ * - mahoraga.config.json: Configuração do usuário (raiz do projeto)
+ */
 import path from 'node:path';
+// Diretório base do projeto (raiz) - usa CWD quando executado pelo CLI
 export const PROJETO_RAIZ = process.cwd();
-export const MAHORAGA_DIRS = {
+/**
+ * Diretórios principais do Mahoraga
+ */
+export const SUKUNA_DIRS = {
+    /** Diretório de estado interno (.mahoraga/) */
     STATE: path.join(PROJETO_RAIZ, '.mahoraga'),
+    /** Diretório de histórico de métricas (.mahoraga/historico-metricas/) */
     METRICS_HISTORY: path.join(PROJETO_RAIZ, '.mahoraga', 'historico-metricas'),
+    /** Diretório de relatórios (reports/) */
     REPORTS: path.join(PROJETO_RAIZ, 'reports'),
+    /** Diretório de performance baselines (docs/perf/) */
     PERF: path.join(PROJETO_RAIZ, 'docs', 'perf')
 };
-export const MAHORAGA_ARQUIVOS = {
+/**
+ * Arquivos JSON do sistema
+ *
+ * Categoria 1: Configuração (leitura usuário)
+ * Categoria 2: Estado interno (leitura/escrita sistema)
+ * Categoria 3: Relatórios (escrita sistema)
+ */
+export const SUKUNA_ARQUIVOS = {
+    // ─── CONFIGURAÇÃO (raiz do projeto) ───────────────────────────
+    /** Configuração principal do usuário (mahoraga.config.json) */
     CONFIG: path.join(PROJETO_RAIZ, 'mahoraga.config.json'),
+    /** Configuração segura/alternativa (mahoraga.config.safe.json) */
     CONFIG_SAFE: path.join(PROJETO_RAIZ, 'mahoraga.config.safe.json'),
-    GUARDIAN_BASELINE: path.join(MAHORAGA_DIRS.STATE, 'guardian.baseline.json'),
-    ESTRUTURA_BASELINE: path.join(MAHORAGA_DIRS.STATE, 'estrutura.baseline.json'),
-    ESTRUTURA_ARQUETIPO: path.join(MAHORAGA_DIRS.STATE, 'estrutura.arquetipo.json'),
-    MAPA_REVERSAO: path.join(MAHORAGA_DIRS.STATE, 'mapa-reversao.json'),
-    REGISTRO_VIGIA: path.join(MAHORAGA_DIRS.STATE, 'integridade.json'),
-    GUARDIAN_CHAVE_PUBLICA: path.join(MAHORAGA_DIRS.STATE, 'guardian.chave-publica.asc'),
-    GUARDIAN_CHAVE_PRIVADA: path.join(MAHORAGA_DIRS.STATE, 'guardian.chave-privada.asc'),
-    METRICAS_HISTORICO: path.join(MAHORAGA_DIRS.METRICS_HISTORY, 'metricas-historico.json'),
-    GUARDIAN_BASELINE_LEGACY: path.join(MAHORAGA_DIRS.STATE, 'baseline.json'),
-    ESTRUTURA_BASELINE_LEGACY: path.join(MAHORAGA_DIRS.STATE, 'baseline-estrutura.json'),
+    // ─── ESTADO INTERNO (.mahoraga/) ────────────────────────────
+    /** Baseline de assinaturas GPG do Guardian (.mahoraga/guardian.baseline.json) */
+    GUARDIAN_BASELINE: path.join(SUKUNA_DIRS.STATE, 'guardian.baseline.json'),
+    /** Baseline de estrutura de diretórios (.mahoraga/estrutura.baseline.json) */
+    ESTRUTURA_BASELINE: path.join(SUKUNA_DIRS.STATE, 'estrutura.baseline.json'),
+    /** Arquétipo personalizado do repo (.mahoraga/estrutura.arquetipo.json) */
+    ESTRUTURA_ARQUETIPO: path.join(SUKUNA_DIRS.STATE, 'estrutura.arquetipo.json'),
+    /** Mapa de reversão de estrutura (.mahoraga/mapa-reversao.json) */
+    MAPA_REVERSAO: path.join(SUKUNA_DIRS.STATE, 'mapa-reversao.json'),
+    /** Registros da Vigia Oculta (.mahoraga/integridade.json) */
+    REGISTRO_VIGIA: path.join(SUKUNA_DIRS.STATE, 'integridade.json'),
+    /** Chave pública GPG do Guardian (.mahoraga/guardian.chave-publica.asc) */
+    GUARDIAN_CHAVE_PUBLICA: path.join(SUKUNA_DIRS.STATE, 'guardian.chave-publica.asc'),
+    /** Chave privada GPG do Guardian (.mahoraga/guardian.chave-privada.asc) */
+    GUARDIAN_CHAVE_PRIVADA: path.join(SUKUNA_DIRS.STATE, 'guardian.chave-privada.asc'),
+    /** Histórico de métricas (.mahoraga/historico-metricas/metricas-historico.json) */
+    METRICAS_HISTORICO: path.join(SUKUNA_DIRS.METRICS_HISTORY, 'metricas-historico.json'),
+    // ─── ARQUIVOS LEGADOS (compatibilidade) ───────────────────────
+    /** @deprecated Use GUARDIAN_BASELINE - baseline.json antigo */
+    GUARDIAN_BASELINE_LEGACY: path.join(SUKUNA_DIRS.STATE, 'baseline.json'),
+    /** @deprecated Use ESTRUTURA_BASELINE - baseline-estrutura.json antigo */
+    ESTRUTURA_BASELINE_LEGACY: path.join(SUKUNA_DIRS.STATE, 'baseline-estrutura.json'),
+    /** @deprecated Movido para .mahoraga/ - mahoraga.repo.arquetipo.json na raiz */
     ESTRUTURA_ARQUETIPO_LEGACY_ROOT: path.join(PROJETO_RAIZ, 'mahoraga.repo.arquetipo.json')
 };
+/**
+ * Padrões de nomenclatura para relatórios dinâmicos
+ */
 export const REPORT_PADROES = {
-    DIAGNOSTICO: (timestamp) => path.join(MAHORAGA_DIRS.REPORTS, `mahoraga-diagnostico-${timestamp}.md`),
-    SUMMARY_JSON: (timestamp) => path.join(MAHORAGA_DIRS.REPORTS, `mahoraga-relatorio-summary-${timestamp}.json`),
-    ASYNC_ANALYSIS: path.join(MAHORAGA_DIRS.REPORTS, 'async-analysis-report.json'),
-    PERF_BASELINE: (timestamp) => path.join(MAHORAGA_DIRS.PERF, `baseline-${timestamp}.json`),
-    PERF_DIFF: path.join(MAHORAGA_DIRS.PERF, 'ultimo-diff.json')
+    /** Relatório de diagnóstico (mahoraga-diagnostico-{timestamp}.md) */
+    DIAGNOSTICO: (timestamp) => path.join(SUKUNA_DIRS.REPORTS, `mahoraga-diagnostico-${timestamp}.md`),
+    /** Relatório JSON resumo (mahoraga-relatorio-summary-{timestamp}.json) */
+    SUMMARY_JSON: (timestamp) => path.join(SUKUNA_DIRS.REPORTS, `mahoraga-relatorio-summary-${timestamp}.json`),
+    /** Relatório de análise async (async-analysis-report.json) */
+    ASYNC_ANALYSIS: path.join(SUKUNA_DIRS.REPORTS, 'async-analysis-report.json'),
+    /** Baseline de performance (docs/perf/baseline-{timestamp}.json) */
+    PERF_BASELINE: (timestamp) => path.join(SUKUNA_DIRS.PERF, `baseline-${timestamp}.json`),
+    /** Diff de performance (docs/perf/ultimo-diff.json) */
+    PERF_DIFF: path.join(SUKUNA_DIRS.PERF, 'ultimo-diff.json')
 };
+/**
+ * Mapeia nomes legados para novos caminhos (migração automática)
+ */
 export const MIGRACAO_MAPA = {
-    [MAHORAGA_ARQUIVOS.GUARDIAN_BASELINE_LEGACY]: MAHORAGA_ARQUIVOS.GUARDIAN_BASELINE,
-    [MAHORAGA_ARQUIVOS.ESTRUTURA_BASELINE_LEGACY]: MAHORAGA_ARQUIVOS.ESTRUTURA_BASELINE,
-    [MAHORAGA_ARQUIVOS.ESTRUTURA_ARQUETIPO_LEGACY_ROOT]: MAHORAGA_ARQUIVOS.ESTRUTURA_ARQUETIPO
+    // Guardian: baseline.json → guardian.baseline.json
+    [SUKUNA_ARQUIVOS.GUARDIAN_BASELINE_LEGACY]: SUKUNA_ARQUIVOS.GUARDIAN_BASELINE,
+    // Estrutura: baseline-estrutura.json → estrutura.baseline.json
+    [SUKUNA_ARQUIVOS.ESTRUTURA_BASELINE_LEGACY]: SUKUNA_ARQUIVOS.ESTRUTURA_BASELINE,
+    // Arquétipo: mahoraga.repo.arquetipo.json (raiz) → .mahoraga/estrutura.arquetipo.json
+    [SUKUNA_ARQUIVOS.ESTRUTURA_ARQUETIPO_LEGACY_ROOT]: SUKUNA_ARQUIVOS.ESTRUTURA_ARQUETIPO
 };
+/**
+ * Retorna o caminho legado (se existir) ou o novo
+ * @param newPath Caminho novo desejado
+ * @returns Caminho do arquivo (prioriza legado se existir)
+ */
 export function resolveFilePath(newPath) {
+    // Verifica se há entrada no mapa de migração reverso
     const legacyCaminho = Object.entries(MIGRACAO_MAPA).find(([_, target]) => target === newPath)?.[0];
-    return legacyCaminho || newPath;
+    return legacyCaminho ?? newPath;
 }
-//# sourceMappingURL=paths.js.map

package/dist/core/reporting/default-reporter.js

@@ -1,8 +1,15 @@
+// SPDX-License-Identifier: MIT
+/**
+ * @fileoverview Reporter padrão que converte eventos de relatório em ocorrências.
+ * Mapeia códigos de evento (como ARQ_PADRAO, ARQ_VIOLACAO, etc.) para mensagens
+ * formatadas usando os templates de mensagens dos detectores correspondentes.
+ */
 import { messages } from '../messages/index.js';
 import { criarOcorrencia } from '../../types/index.js';
 export function createDefaultReporter() {
     return (event) => {
         const { code, tipo, nivel = 'info', mensagem, data, relPath, linha = 1, coluna, origem, } = event;
+        // Se a mensagem já veio formatada, apenas encaminha
         if (mensagem && typeof mensagem === 'string') {
             return criarOcorrencia({
                 tipo,
@@ -14,9 +21,10 @@ export function createDefaultReporter() {
                 origem,
             });
         }
+        // Mapeamentos mínimos (incrementais) por code
         if (code === 'ARQ_PADRAO') {
-            const padrao = String(data?.padraoIdentificado ?? '');
-            const confianca = Number(data?.confianca ?? 0);
+            const padrao = String((data?.padraoIdentificado) ?? '');
+            const confianca = Number((data?.confianca) ?? 0);
             return criarOcorrencia({
                 tipo,
                 nivel,
@@ -29,7 +37,7 @@ export function createDefaultReporter() {
         }
         if (code === 'ARQ_CARACTERISTICAS') {
             const items = Array.isArray(data?.caracteristicas)
-                ? data?.caracteristicas
+                ? data.caracteristicas
                 : [];
             return criarOcorrencia({
                 tipo,
@@ -42,7 +50,7 @@ export function createDefaultReporter() {
             });
         }
         if (code === 'ARQ_VIOLACAO') {
-            const violacao = String(data?.violacao ?? '');
+            const violacao = String((data?.violacao) ?? '');
             return criarOcorrencia({
                 tipo,
                 nivel,
@@ -54,8 +62,8 @@ export function createDefaultReporter() {
             });
         }
         if (code === 'ARQ_METRICAS') {
-            const acoplamento = Number(data?.acoplamento ?? 0);
-            const coesao = Number(data?.coesao ?? 0);
+            const acoplamento = Number((data?.acoplamento) ?? 0);
+            const coesao = Number((data?.coesao) ?? 0);
             return criarOcorrencia({
                 tipo,
                 nivel,
@@ -77,6 +85,7 @@ export function createDefaultReporter() {
                 origem,
             });
         }
+        // Fallback: mantém sinal útil mesmo sem template
         const fallbackMsg = code
             ? `${code}${data ? ` ${JSON.stringify(data)}` : ''}`
             : data
@@ -93,4 +102,3 @@ export function createDefaultReporter() {
         });
     };
 }
-//# sourceMappingURL=default-reporter.js.map

package/dist/core/reporting/index.js

@@ -1,2 +1,5 @@
+// SPDX-License-Identifier: MIT
+/**
+ * @fileoverview Core reporting: default reporter
+ */
 export * from './default-reporter.js';
-//# sourceMappingURL=index.js.map

package/dist/core/runtime/index.js

@@ -1,3 +1,7 @@
+// SPDX-License-Identifier: MIT
+/**
+ * @fileoverview Gerenciamento de runtime (Node, Deno, Bun)
+ */
 import { criarAdapterNode } from './node-adapter.js';
 let adapterAtual = criarAdapterNode();
 export function obterRuntime() {
@@ -7,4 +11,3 @@ export function definirRuntime(adapter) {
     adapterAtual = adapter;
 }
 export { criarAdapterNode } from './node-adapter.js';
-//# sourceMappingURL=index.js.map

package/dist/core/runtime/node-adapter.js

@@ -1,10 +1,14 @@
+// SPDX-License-Identifier: MIT
+/**
+ * @fileoverview Adaptador de runtime para Node.js
+ */
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 function detectarRuntime() {
     const globalAny = globalThis;
     const proc = globalAny.process;
-    if (typeof proc !== 'undefined' && proc?.versions?.node) {
+    if (proc?.versions?.node) {
         return { tipo: 'node', versao: proc.versions.node };
     }
     if (typeof globalAny.Deno !== 'undefined') {
@@ -20,7 +24,7 @@ function criarFileSystem() {
         readFile: (caminho, encoding) => fs.promises.readFile(caminho, encoding),
         readFileSync: (caminho, encoding) => fs.readFileSync(caminho, encoding),
         writeFile: (caminho, conteudo) => fs.promises.writeFile(caminho, conteudo, 'utf-8'),
-        writeFileSync: (caminho, conteudo) => fs.writeFileSync(caminho, conteudo, 'utf-8'),
+        writeFileSync: (caminho, conteudo) => { fs.writeFileSync(caminho, conteudo, 'utf-8'); },
         readdir: caminho => fs.promises.readdir(caminho),
         readdirSync: caminho => fs.readdirSync(caminho),
         mkdir: (caminho, opcoes) => fs.promises.mkdir(caminho, { recursive: opcoes?.recursive }).then(() => undefined),
@@ -44,7 +48,7 @@ function criarPath() {
 function criarProcess() {
     return {
         cwd: () => process.cwd(),
-        chdir: dir => process.chdir(dir),
+        chdir: dir => { process.chdir(dir); },
         env: process.env,
         exit: (code) => process.exit(code),
         argv: process.argv,
@@ -63,4 +67,3 @@ export function criarAdapterNode() {
         process: criarProcess(),
     };
 }
-//# sourceMappingURL=node-adapter.js.map

package/dist/core/runtime.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: MIT
+export {};

package/dist/core/schema/index.js

@@ -1,2 +1,5 @@
+// SPDX-License-Identifier: MIT
+/**
+ * @fileoverview Core schema versioning
+ */
 export * from './version.js';
-//# sourceMappingURL=index.js.map

package/dist/core/schema/version.js

@@ -1,5 +1,14 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Sistema de Versionamento de Schema para Relatórios JSON
+ *
+ * Este módulo gerencia versões de schema para relatórios JSON do Mahoraga,
+ * garantindo compatibilidade futura e evolução controlada dos formatos.
+ */
 import { messages } from '../messages/index.js';
+/** Versão atual do schema */
 export const VERSAO_ATUAL = '1.0.0';
+/** Histórico de versões do schema */
 export const HISTORICO_VERSOES = {
     '1.0.0': {
         versao: '1.0.0',
@@ -10,6 +19,9 @@ export const HISTORICO_VERSOES = {
         camposOpcionais: ['_schema.compatibilidade', '_schema.camposObrigatorios', '_schema.camposOpcionais']
     }
 };
+/**
+ * Cria metadados de schema para a versão atual
+ */
 export function criarSchemaMetadata(versao = VERSAO_ATUAL, descricaoPersonalizada) {
     const base = HISTORICO_VERSOES[versao];
     if (!base) {
@@ -22,8 +34,12 @@ export function criarSchemaMetadata(versao = VERSAO_ATUAL, descricaoPersonalizad
         })
     };
 }
+/**
+ * Valida se um relatório tem schema válido
+ */
 export function validarSchema(relatorio) {
     const erros = [];
+    // Verificar estrutura básica
     if (!relatorio || typeof relatorio !== 'object') {
         erros.push('Relatório deve ser um objeto');
         return {
@@ -31,6 +47,7 @@ export function validarSchema(relatorio) {
             erros
         };
     }
+    // Verificar presença do schema
     if (!('_schema' in relatorio) || !relatorio._schema) {
         erros.push('Campo _schema é obrigatório');
         return {
@@ -39,15 +56,18 @@ export function validarSchema(relatorio) {
         };
     }
     const schema = relatorio._schema;
+    // Verificar campos obrigatórios do schema
     const camposObrigatorios = ['versao', 'criadoEm', 'descricao'];
     for (const campo of camposObrigatorios) {
         if (!(campo in schema)) {
             erros.push(`Campo _schema.${campo} é obrigatório`);
         }
     }
+    // Verificar se a versão existe no histórico
     if (schema.versao && typeof schema.versao === 'string' && !HISTORICO_VERSOES[schema.versao]) {
         erros.push(`Versão de schema desconhecida: ${schema.versao}`);
     }
+    // Verificar presença dos dados
     if (!('dados' in relatorio)) {
         erros.push('Campo dados é obrigatório');
     }
@@ -56,32 +76,52 @@ export function validarSchema(relatorio) {
         erros
     };
 }
+/**
+ * Migra um relatório para a versão atual se necessário
+ */
 export function migrarParaVersaoAtual(relatorio) {
+    // Se já tem schema válido, retornar como está
     const validacao = validarSchema(relatorio);
     if (validacao.valido && relatorio._schema) {
         return relatorio;
     }
+    // Se não tem schema, rejeitar: relatórios sem `_schema` são considerados formatos antigos
+    // e devem ser migrados explicitamente pelo consumidor antes de chamar esta função.
+    // Se não tem schema, considerar que é um relatório legado e migrar explicitamente
+    // Chamadas a esta função são a migração explícita, então embrulhamos o relatório
+    // antigo com os metadados de versão atuais.
     if (!('_schema' in relatorio) || !relatorio._schema) {
         return criarRelatorioComVersao(relatorio);
     }
+    // Para futuras migrações, implementar lógica aqui
+    // Por enquanto, apenas revalidar
     if (!validacao.valido) {
         throw new Error(messages.ExcecoesMensagens.relatorioSchemaInvalido(validacao.erros.join(', ')));
     }
     return relatorio;
 }
+/**
+ * Cria um relatório com versão atual
+ */
 export function criarRelatorioComVersao(dados, versao = VERSAO_ATUAL, descricao) {
     return {
         _schema: criarSchemaMetadata(versao, descricao),
         dados
     };
 }
+/**
+ * Extrai apenas os dados de um relatório versionado
+ */
 export function extrairDados(relatorio) {
     return relatorio.dados;
 }
+/**
+ * Verifica se uma versão é compatível com a atual
+ */
 export function versaoCompativel(versao) {
     const metadata = HISTORICO_VERSOES[versao];
-    if (!metadata)
+    if (!metadata) {
         return false;
+    }
     return metadata.compatibilidade.includes(VERSAO_ATUAL);
 }
-//# sourceMappingURL=version.js.map

package/dist/core/utils/chalk.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: MIT
+export {};

package/dist/core/utils/exec-safe.js

@@ -1,13 +1,31 @@
+// SPDX-License-Identifier: MIT
 import { execSync } from 'node:child_process';
 import { config } from '../config/index.js';
 import { getMessages } from '../messages/index.js';
+/**
+ * Executa um comando shell de forma segura.
+ * Bloqueia a execução quando SAFE_MODE está ativo e ALLOW_EXEC não está habilitado.
+ * @param cmd - Comando shell a executar
+ * @param opts - Opções do execSync do Node.js
+ * @returns Buffer ou string com a saída do comando
+ * @throws Error se SAFE_MODE estiver ativo sem ALLOW_EXEC
+ */
 export function executarShellSeguro(cmd, opts = {}) {
-    if (config.SAFE_MODE === true && !config.ALLOW_EXEC) {
+    // only block if SAFE_MODE is explicitly true and ALLOW_EXEC is falsy
+    if (config.SAFE_MODE && !config.ALLOW_EXEC) {
         throw new Error(getMessages().ExecSafeMensagens.safeModeBloqueado);
     }
     return execSync(cmd, opts);
 }
-export async function executarShellSeguroAsync(cmd, opts = {}) {
+/**
+ * Versão assíncrona do `executarShellSeguro`.
+ * Wrapper async que delega ao sync, útil em contextos que já utilizam await.
+ * @param cmd - Comando shell a executar
+ * @param opts - Opções do execSync do Node.js
+ * @returns Promise resolvida com Buffer ou string da saída do comando
+ * @throws Error se SAFE_MODE estiver ativo sem ALLOW_EXEC
+ */
+export function executarShellSeguroAsync(cmd, opts = {}) {
+    // wrapper assíncrono que delega ao sync (usado onde já há await)
     return executarShellSeguro(cmd, opts);
 }
-//# sourceMappingURL=exec-safe.js.map

package/dist/core/utils/import-safe.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 import { config, resolverPluginSeguro } from '../config/index.js';
 import { messages } from '../messages/index.js';
 export async function importarModuloSeguro(baseDir, pluginRel) {
@@ -5,10 +6,12 @@ export async function importarModuloSeguro(baseDir, pluginRel) {
         throw new Error(messages.ExcecoesMensagens.pluginsDesabilitadosSafeMode);
     }
     const resolvido = resolverPluginSeguro(baseDir, pluginRel);
-    if (resolvido.erro)
+    if (resolvido.erro) {
         throw new Error(messages.ExcecoesMensagens.pluginBloqueado(resolvido.erro));
-    if (!resolvido.caminho)
+    }
+    if (!resolvido.caminho) {
         throw new Error(messages.ExcecoesMensagens.caminhoPluginNaoResolvido);
+    }
+    // permite que o chamador capture exceções do plugin
     return import(resolvido.caminho);
 }
-//# sourceMappingURL=import-safe.js.map