@mocoto/mahoraga 0.14.0 → 0.14.2

package/dist/core/messages/zh/log/log.js

@@ -1,7 +1,9 @@
 import { chalk, config } from '../../../config/index.js';
 import { isJsonMode } from '../../../../shared/helpers/index.js';
+// Reexport for tests to configure flags without importing cosmos directly
 export { config } from '../../../config/index.js';
 export const LOG_SIMBOLOS = {
+    // Severity level prefixes with ANSI colors
     info: '[INFO]',
     sucesso: '[OK]',
     erro: '[ERROR]',
@@ -14,18 +16,26 @@ export const LOG_SIMBOLOS = {
     pasta: '[DIR]'
 };
 function shouldSilence() {
-    if (isJsonMode())
+    // JSON mode always silences visual logs
+    if (isJsonMode()) {
         return true;
-    if (process.env.MAHORAGA_FORCE_SILENT_JSON === '1')
+    }
+    if (process.env.SUKUNA_FORCE_SILENT_JSON === '1') {
         return true;
+    }
     return config.REPORT_SILENCE_LOGS;
 }
 function shouldSuppressParcial(msg) {
     try {
-        if (!config.SUPPRESS_PARCIAL_LOGS && process.env.MAHORAGA_SUPPRESS_PARCIAL !== '1')
+        // Allows quick override via short env variable SUKUNA_SUPPRESS_PARCIAL=1
+        if (!config.SUPPRESS_PARCIAL_LOGS && process.env.SUKUNA_SUPPRESS_PARCIAL !== '1') {
             return false;
-        if (!msg || typeof msg !== 'string')
+        }
+        if (!msg || typeof msg !== 'string') {
             return false;
+        }
+        // Suppresses when substring 'partial' (case-insensitive) appears anywhere.
+        // This covers 'partial' and variations like 'partially'.
         return /parcial/i.test(msg);
     }
     catch {
@@ -33,16 +43,21 @@ function shouldSuppressParcial(msg) {
     }
 }
 function isDebugMode() {
-    return config.DEV_MODE || process.env.MAHORAGA_DEBUG === 'true';
+    return config.DEV_MODE || process.env.SUKUNA_DEBUG === 'true';
 }
 function shouldLogLevel(nivel) {
     const niveis = ['erro', 'aviso', 'info', 'debug'];
     const nivelAtual = niveis.indexOf(config.LOG_LEVEL);
     const nivelMensagem = niveis.indexOf(nivel);
-    if (nivel === 'erro' || nivel === 'sucesso')
+    // Error and success are always displayed (high priority)
+    if (nivel === 'erro' || nivel === 'sucesso') {
         return true;
-    if (nivel === 'debug')
+    }
+    // Debug is only displayed in debug mode or if LOG_LEVEL=debug
+    if (nivel === 'debug') {
         return isDebugMode() || config.LOG_LEVEL === 'debug';
+    }
+    // For other levels, checks if within threshold
     return nivelMensagem <= nivelAtual;
 }
 function getTimestamp() {
@@ -55,11 +70,15 @@ function getTimestamp() {
     return `[${now}]`;
 }
 function stripLeadingSimbolos(msg) {
-    if (!msg)
+    if (!msg) {
         return msg;
+    }
     const ansiRegex = /[\u001B\u009B][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g;
+    // Remove ANSI to evaluate beginning; we will keep output without styles
     let plain = msg.replace(ansiRegex, '');
+    // Normalizes line breaks and leading spaces
     plain = plain.replace(/^\s+/, '');
+    // candidates: symbols from map + frequent extras used in messages
     const extras = [];
     const candidatos = Array.from(new Set([...Object.values(LOG_SIMBOLOS), ...extras])).filter(Boolean);
     let mudou = true;
@@ -74,18 +93,23 @@ function stripLeadingSimbolos(msg) {
             }
         }
     }
+    // Remaining spaces after removal
     return plain.trimStart();
 }
+// Exported for formatting tests; internal use in logger.
 export function formatarLinha({ nivel, mensagem, sanitize = true }) {
     const ts = getTimestamp();
     const colNivelRaw = nivel.toUpperCase().padEnd(7);
+    // Resolve possible 'chalk' forms (function or mocked object with .bold)
     const hasBold = (valor) => !!valor && typeof valor.bold === 'function';
     const resolveStyle = (valor) => {
-        if (typeof valor === 'function')
+        if (typeof valor === 'function') {
             return valor;
-        if (hasBold(valor))
+        }
+        if (hasBold(valor)) {
             return valor.bold;
-        return (string) => String(string);
+        }
+        return (string) => string;
     };
     let cor = (string) => string;
     switch (nivel) {
@@ -108,46 +132,60 @@ export function formatarLinha({ nivel, mensagem, sanitize = true }) {
     const boldFn = resolveStyle(chalk.bold);
     const colNivel = boldFn(colNivelRaw);
     const corpo = sanitize ? stripLeadingSimbolos(mensagem) : mensagem;
+    // We highlight messages (error/warning/success) to reinforce visibility.
     const corpoFmt = nivel === 'info' || nivel === 'debug' ? corpo : cor(corpo);
-    const grayFn = typeof chalk.gray === 'function' ? chalk.gray : (string) => String(string);
+    const grayFn = typeof chalk.gray === 'function' ? chalk.gray : (string) => string;
     const linha = `${grayFn(ts)} ${colNivel} ${corpoFmt}`;
-    if (!process.env.VITEST && process.env.MAHORAGA_CENTER === '1') {
+    // Centers loose lines only with explicit opt-in (SUKUNA_CENTER=1)
+    if (!process.env.VITEST && process.env.SUKUNA_CENTER === '1') {
         try {
             const cols = obterColunasTerm();
-            const out = process.stdout && typeof process.stdout.isTTY !== 'undefined' ? process.stdout : undefined;
-            const isTty = !!out && out.isTTY !== false;
+            const out = typeof process.stdout.isTTY !== 'undefined' ? process.stdout : undefined;
+            const isTty = !!out && out.isTTY;
             if (isTty && cols && cols > 0) {
                 const ANSI_REGEX = /[\u001B\u009B][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g;
                 const visLen = (string) => (string || '').replace(ANSI_REGEX, '').length;
                 const pad = Math.floor(Math.max(0, cols - visLen(linha)) / 2);
-                if (pad > 0)
+                if (pad > 0) {
                     return ' '.repeat(pad) + linha;
+                }
             }
         }
         catch {
+            // If centering fails, return normal line
         }
     }
     return linha;
 }
+/**
+ * Formats a multi-line block with consistent indentation and light frame.
+ * Useful for sections (phases) or compact summaries.
+ */
 function obterColunasTerm() {
+    // Tries to get terminal width safely
     try {
-        const out = process.stdout && typeof process.stdout.columns !== 'undefined' ? process.stdout : undefined;
+        const out = typeof process.stdout.columns !== 'undefined' ? process.stdout : undefined;
         const cols = out?.columns;
-        if (typeof cols === 'number' && cols > 0)
+        if (typeof cols === 'number' && cols > 0) {
             return cols;
+        }
     }
     catch { }
-    const envOverride = Number(process.env.MAHORAGA_FRAME_MAX_COLS || '0');
-    if (Number.isFinite(envOverride) && envOverride > 0)
+    // Allows explicit override via env and fallback of common variables
+    const envOverride = Number(process.env.SUKUNA_FRAME_MAX_COLS ?? '0');
+    if (Number.isFinite(envOverride) && envOverride > 0) {
         return envOverride;
-    const envCols = Number(process.env.COLUMNS || process.env.TERM_COLUMNS || '0');
+    }
+    const envCols = Number((process.env.COLUMNS ?? process.env.TERM_COLUMNS) ?? '0');
     return Number.isFinite(envCols) && envCols > 0 ? envCols : undefined;
 }
 function calcularLarguraInterna(titulo, linhas, larguraMax) {
     const ANSI_REGEX = /[\u001B\u009B][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g;
     const visLen = (string) => (string || '').replace(ANSI_REGEX, '').length;
+    // Desired width by content, with standard ceiling (100) if not specified
     const desejada = Math.min(100, Math.max(visLen(titulo) + 4, ...linhas.map(linha => visLen(linha) + 4), 20));
     const preferida = typeof larguraMax === 'number' ? Math.max(20, Math.min(larguraMax, 120)) : desejada;
+    // Upper limit by terminal width (responsive)
     const cols = obterColunasTerm();
     const tetoTela = typeof cols === 'number' && cols > 0 ? Math.max(20, Math.min(cols, 120)) : 120;
     const width = Math.max(20, Math.min(preferida, tetoTela));
@@ -160,23 +198,27 @@ function calcularLarguraInterna(titulo, linhas, larguraMax) {
         ANSI_REGEX
     };
 }
-export function formatarBloco(titulo, linhas, corTitulo = typeof chalk.bold === 'function' ? chalk.bold : (string) => String(string), larguraMax) {
+export function formatarBloco(titulo, linhas, corTitulo = typeof chalk.bold === 'function' ? chalk.bold : (string) => string, larguraMax) {
+    // ANSI-aware utilities to measure/compose by visible width
     const { width, maxInner, visLen, ANSI_REGEX } = calcularLarguraInterna(titulo, linhas, larguraMax);
     const padFimVisible = (string, target) => {
         const diff = target - visLen(string);
         return diff > 0 ? string + ' '.repeat(diff) : string;
     };
     const truncateVisible = (string, max) => {
-        if (visLen(string) <= max)
+        if (visLen(string) <= max) {
             return string;
+        }
+        // Preserves ANSI sequences, counting only visible width
         let out = '';
         let count = 0;
         let indice = 0;
         while (indice < string.length && count < max - 1) {
             const ch = string[indice];
             if (ch === '\u001B' || ch === '\u009B') {
+                // Copies entire ANSI sequence
                 const metrica = string.slice(indice).match(ANSI_REGEX);
-                if (metrica && metrica.index === 0) {
+                if (metrica?.index === 0) {
                     out += metrica[0];
                     indice += metrica[0].length;
                     continue;
@@ -194,23 +236,27 @@ export function formatarBloco(titulo, linhas, corTitulo = typeof chalk.bold ===
     const normalizar = (string) => truncateVisible(string, maxInner);
     const corpo = linhas.map(linha => `│ ${padFimVisible(normalizar(linha), maxInner)}│`).join('\n');
     const headTxt = `│ ${padFimVisible(normalizar(titulo), maxInner)}│`;
-    const corTituloFn = typeof corTitulo === 'function' ? corTitulo : (string) => String(string);
-    const gray = typeof chalk.gray === 'function' ? chalk.gray : (x) => String(x);
+    // Ensures corTitulo works even when mocked as object
+    const corTituloFn = typeof corTitulo === 'function' ? corTitulo : (string) => string;
+    const gray = typeof chalk.gray === 'function' ? chalk.gray : (x) => x;
     return [gray(topo), corTituloFn(headTxt), gray(corpo), gray(base)].filter(Boolean).join('\n');
 }
+// Optional ASCII frame fallback (avoids mojibake on Windows redirects)
 function deveUsarAsciiFrames() {
-    return process.env.MAHORAGA_ASCII_FRAMES === '1';
+    return process.env.SUKUNA_ASCII_FRAMES === '1';
 }
 function converterMolduraParaAscii(bloco) {
     return bloco.replaceAll('┌', '+').replaceAll('┐', '+').replaceAll('└', '+').replaceAll('┘', '+').replaceAll('─', '-').replaceAll('│', '|');
 }
 export function fase(titulo) {
-    if (shouldSilence())
+    if (shouldSilence()) {
         return;
-    if (!shouldLogLevel('info'))
+    }
+    if (!shouldLogLevel('info')) {
         return;
-    const bold = typeof chalk.bold === 'function' ? chalk.bold : (string) => String(string);
-    const cyan = typeof chalk.cyan === 'function' ? chalk.cyan : (string) => String(string);
+    }
+    const bold = typeof chalk.bold === 'function' ? chalk.bold : (string) => string;
+    const cyan = typeof chalk.cyan === 'function' ? chalk.cyan : (string) => string;
     console.log(formatarLinha({
         nivel: 'info',
         mensagem: bold(cyan(`${LOG_SIMBOLOS.fase} ${titulo}`)),
@@ -218,10 +264,12 @@ export function fase(titulo) {
     }));
 }
 export function passo(descricao) {
-    if (shouldSilence())
+    if (shouldSilence()) {
         return;
-    if (!shouldLogLevel('info'))
+    }
+    if (!shouldLogLevel('info')) {
         return;
+    }
     console.log(formatarLinha({
         nivel: 'info',
         mensagem: `${LOG_SIMBOLOS.passo} ${descricao}`,
@@ -230,39 +278,52 @@ export function passo(descricao) {
 }
 export const log = {
     info(msg) {
-        if (shouldSilence())
+        if (shouldSilence()) {
             return;
-        if (shouldSuppressParcial(msg))
+        }
+        if (shouldSuppressParcial(msg)) {
             return;
-        if (!shouldLogLevel('info'))
+        }
+        if (!shouldLogLevel('info')) {
             return;
+        }
         console.log(formatarLinha({
             nivel: 'info',
             mensagem: msg
         }));
     },
+    // INFO variant that preserves inline styles/colors (no symbol sanitization),
+    // useful for aligning columns while keeping colored numbers.
     infoSemSanitizar(msg) {
-        if (shouldSilence())
+        if (shouldSilence()) {
             return;
-        if (shouldSuppressParcial(msg))
+        }
+        if (shouldSuppressParcial(msg)) {
             return;
-        if (!shouldLogLevel('info'))
+        }
+        if (!shouldLogLevel('info')) {
             return;
+        }
         console.log(formatarLinha({
             nivel: 'info',
             mensagem: msg,
             sanitize: false
         }));
     },
+    // INFO message with styled body (bold + blue) and no sanitization,
+    // preserving colors within the body. Useful for short titles and summaries.
     infoDestaque(msg) {
-        if (shouldSilence())
+        if (shouldSilence()) {
             return;
-        if (shouldSuppressParcial(msg))
+        }
+        if (shouldSuppressParcial(msg)) {
             return;
-        if (!shouldLogLevel('info'))
+        }
+        if (!shouldLogLevel('info')) {
             return;
-        const bold = typeof chalk.bold === 'function' ? chalk.bold : (string) => String(string);
-        const cyan = typeof chalk.cyan === 'function' ? chalk.cyan : (string) => String(string);
+        }
+        const bold = typeof chalk.bold === 'function' ? chalk.bold : (string) => string;
+        const cyan = typeof chalk.cyan === 'function' ? chalk.cyan : (string) => string;
         console.log(formatarLinha({
             nivel: 'info',
             mensagem: bold(cyan(msg)),
@@ -270,12 +331,15 @@ export const log = {
         }));
     },
     sucesso(msg) {
-        if (shouldSilence())
+        if (shouldSilence()) {
             return;
-        if (shouldSuppressParcial(msg))
+        }
+        if (shouldSuppressParcial(msg)) {
             return;
-        if (!shouldLogLevel('sucesso'))
+        }
+        if (!shouldLogLevel('sucesso')) {
             return;
+        }
         console.log(formatarLinha({
             nivel: 'sucesso',
             mensagem: msg
@@ -288,22 +352,27 @@ export const log = {
         }));
     },
     aviso(msg) {
-        if (shouldSilence())
+        if (shouldSilence()) {
             return;
-        if (shouldSuppressParcial(msg))
+        }
+        if (shouldSuppressParcial(msg)) {
             return;
-        if (!shouldLogLevel('aviso'))
+        }
+        if (!shouldLogLevel('aviso')) {
             return;
+        }
         console.log(formatarLinha({
             nivel: 'aviso',
             mensagem: msg
         }));
     },
     debug(msg) {
-        if (!shouldLogLevel('debug'))
+        if (!shouldLogLevel('debug')) {
             return;
-        if (shouldSuppressParcial(msg))
+        }
+        if (shouldSuppressParcial(msg)) {
             return;
+        }
         console.log(formatarLinha({
             nivel: 'debug',
             mensagem: msg
@@ -315,42 +384,49 @@ export const log = {
     calcularLargura(titulo, linhas, larguraMax) {
         return calcularLarguraInterna(titulo, linhas, larguraMax).width;
     },
-    imprimirBloco(titulo, linhas, corTitulo = typeof chalk.bold === 'function' ? chalk.bold : (string) => String(string), larguraMax) {
-        if (shouldSilence())
+    // Prints a framed block directly (without logger prefix) with optional ASCII fallback
+    imprimirBloco(titulo, linhas, corTitulo = typeof chalk.bold === 'function' ? chalk.bold : (string) => string, larguraMax) {
+        if (shouldSilence()) {
             return;
+        }
+        // Suppresses blocks containing the word 'partial' when configured
         if (config.SUPPRESS_PARCIAL_LOGS) {
-            if (shouldSuppressParcial(titulo))
+            if (shouldSuppressParcial(titulo)) {
                 return;
-            for (const linha of linhas)
-                if (shouldSuppressParcial(linha))
+            }
+            for (const linha of linhas) {
+                if (shouldSuppressParcial(linha)) {
                     return;
+                }
+            }
         }
         const bloco = formatarBloco(titulo, linhas, corTitulo, larguraMax);
         const out = deveUsarAsciiFrames() ? converterMolduraParaAscii(bloco) : bloco;
-        if (!process.env.VITEST && process.env.MAHORAGA_CENTER === '1') {
+        // Centers block only with explicit opt-in (SUKUNA_CENTER=1)
+        if (!process.env.VITEST && process.env.SUKUNA_CENTER === '1') {
             try {
                 const lines = out.split('\n');
                 if (!lines.length) {
                     return;
                 }
+                // measures visible width of frame (top line)
                 const ANSI_REGEX = /[\u001B\u009B][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g;
                 const visibleLen = (string) => string.replace(ANSI_REGEX, '').length;
                 const frameWidth = Math.max(...lines.map(linha => visibleLen(linha)));
-                const cols = obterColunasTerm() || 0;
-                const outStream = process.stdout && typeof process.stdout.isTTY !== 'undefined' ? process.stdout : undefined;
-                const isTty = !!outStream && outStream.isTTY !== false;
+                const cols = obterColunasTerm() ?? 0;
+                const outStream = typeof process.stdout.isTTY !== 'undefined' ? process.stdout : undefined;
+                const isTty = !!outStream && outStream.isTTY;
                 if (isTty) {
                     const pad = Math.floor(Math.max(0, cols - frameWidth) / 2);
                     if (pad > 0) {
                         const pref = ' '.repeat(pad);
                         console.log(lines.map(linha => pref + linha).join('\n'));
-                        return;
                     }
                 }
             }
             catch {
+                // If centering fails, print normally
             }
         }
     }
 };
-//# sourceMappingURL=log.js.map

package/dist/core/messages/zh/reports/index.js

@@ -1,7 +1,10 @@
+// SPDX-License-Identifier: MIT
+/**
+ * MD/JSON 报告消息
+ */
 export * from './json-messages.js';
 export * from './report-async-patterns-messages.js';
 export * from './report-caretaker-health-messages.js';
 export * from './report-messages.js';
 export * from './report-templates.js';
 export * from './streaming-report-messages.js';
-//# sourceMappingURL=index.js.map

package/dist/core/messages/zh/reports/json-messages.js

@@ -1,4 +1,10 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Centralized messages and descriptions for JSON export
+ * Defines explanatory texts, labels and metadata for JSON fields
+ */
 export const JsonMensagens = {
+    // ─── COMMON FIELDS ────────────────────────────────────────────
     comum: {
         timestamp: {
             label: 'timestamp',
@@ -17,6 +23,7 @@ export const JsonMensagens = {
             descricao: '总执行时长(毫秒)'
         }
     },
+    // ─── DIAGNOSTICS ──────────────────────────────────────────────
     diagnostico: {
         root: {
             label: 'diagnostico',
@@ -67,6 +74,7 @@ export const JsonMensagens = {
             }
         }
     },
+    // ─── STRUCTURE / ARCHETYPES ───────────────────────────────────
     estrutura: {
         root: {
             label: 'estruturaIdentificada',
@@ -106,6 +114,7 @@ export const JsonMensagens = {
             }
         }
     },
+    // ─── GUARDIAN ─────────────────────────────────────────────────
     guardian: {
         root: {
             label: 'guardian',
@@ -136,6 +145,7 @@ export const JsonMensagens = {
             }
         }
     },
+    // ─── PRUNING ──────────────────────────────────────────────────
     poda: {
         root: {
             label: 'poda',
@@ -166,6 +176,7 @@ export const JsonMensagens = {
             }
         }
     },
+    // ─── RESTRUCTURING ────────────────────────────────────────────
     reestruturar: {
         root: {
             label: 'reestruturacao',
@@ -204,6 +215,7 @@ export const JsonMensagens = {
             }
         }
     },
+    // ─── SMART FILTER ─────────────────────────────────────────────
     filtroInteligente: {
         root: {
             label: 'relatorioResumo',
@@ -233,6 +245,9 @@ export const JsonMensagens = {
         }
     }
 };
+/**
+ * Wraps JSON data with explanatory metadata
+ */
 export function wrapComMetadados(data, schema, versao, descricao) {
     return {
         _metadata: {
@@ -244,6 +259,9 @@ export function wrapComMetadados(data, schema, versao, descricao) {
         dados: data
     };
 }
+/**
+ * JSON 字段标签映射 (葡萄牙语 → 中文)
+ */
 export const CAMPO_ROTULOS = {
     modo: '模式',
     projectNome: '项目名称',
@@ -275,8 +293,12 @@ export const CAMPO_ROTULOS = {
     estruturaIdentificada: '已识别结构',
     metricas: '指标',
 };
+/**
+ * Helper to generate JSON field description with type safety
+ */
 export function getDescricaoCampo(caminho) {
     const parts = caminho.split('.');
+    // Type-safe navigation through the messages object
     let current = JsonMensagens;
     for (const part of parts) {
         if (typeof current === 'object' && current !== null && part in current) {
@@ -286,9 +308,9 @@ export function getDescricaoCampo(caminho) {
             return `字段: ${caminho}`;
         }
     }
-    if (typeof current === 'object' && current !== null && 'descricao' in current && typeof current.descricao === 'string') {
+    // Type guard to check if it has a description
+    if (typeof current === 'object' && current !== null && 'descricao' in current && typeof (current).descricao === 'string') {
         return current.descricao;
     }
     return `字段: ${caminho}`;
 }
-//# sourceMappingURL=json-messages.js.map

package/dist/core/messages/zh/reports/report-async-patterns-messages.js

@@ -1,3 +1,6 @@
+/**
+ * Messages for async patterns report (Chinese).
+ */
 export const RelatorioAsyncPatternsMensagens = {
     totalOcorrencias: '未处理异步的出现项总计: {total}',
     topArquivos: '\n[RED] 未处理 Promise 最多的前 {total} 个文件:\n',
@@ -19,4 +22,3 @@ export const RelatorioAsyncPatternsMensagens = {
         ],
     },
 };
-//# sourceMappingURL=report-async-patterns-messages.js.map

package/dist/core/messages/zh/reports/report-caretaker-health-messages.js

@@ -1,3 +1,6 @@
+/**
+ * Messages for health keeper report (Chinese).
+ */
 export const RelatorioZeladorSaudeMensagens = {
     headerArquivos: '文件',
     headerQuantidade: '数量',
@@ -9,4 +12,3 @@ export const RelatorioZeladorSaudeMensagens = {
     itemLista: '  - {nome}: {qtd} 次',
     mandouBem: '干得好!',
 };
-//# sourceMappingURL=report-caretaker-health-messages.js.map

package/dist/core/messages/zh/reports/report-messages.js

@@ -1,5 +1,12 @@
+// SPDX-License-Identifier: MIT
+/**
+ * 报告集中化消息 (Markdown 和 JSON)
+ * 所有标题、头部、描述和解释性文本
+ * 必须在此定义以便于维护和未来国际化。
+ */
 import { ICONES_ACAO, ICONES_COMANDO, ICONES_DIAGNOSTICO, ICONES_RELATORIO } from '../../shared/icons.js';
 export const RelatorioMensagens = {
+    // ─── 主报告 (gerador-relatorio.ts) ───────────────────────────────
     principal: {
         titulo: `${ICONES_RELATORIO.resumo} Mahoraga 报告`,
         secoes: {
@@ -40,6 +47,7 @@ export const RelatorioMensagens = {
             }
         }
     },
+    // ─── 摘要报告 / 智能过滤 ──────────────────────────────────────────────
     resumo: {
         titulo: `${ICONES_RELATORIO.resumo} 摘要报告 - 优先问题`,
         introducao: '本报告将相似问题分组并按影响优先级排序,以方便分析。',
@@ -77,6 +85,7 @@ export const RelatorioMensagens = {
             erroSalvar: (mensagem) => `保存摘要报告错误: ${mensagem}`
         }
     },
+    // ─── 代码健康报告 (zelador-saude.ts) ────────────────────────────────
     saude: {
         titulo: `${ICONES_ACAO.limpeza} 代码健康报告`,
         introducao: `${ICONES_DIAGNOSTICO.stats} 代码使用模式`,
@@ -104,15 +113,18 @@ export const RelatorioMensagens = {
             tabelasVerbosas: '要在终端查看框线表格 (非常详细),请使用: --debug'
         }
     },
+    // ─── 使用模式报告 ───────────────────────────────────────────────────
     padroesUso: {
         titulo: `${ICONES_DIAGNOSTICO.stats} 代码使用模式`
     },
+    // ─── 结构报告 (report-structure.ts) ──────────────────────────────────
     estrutura: {
         tituloVerificada: '# ?? 结构已验证',
         tudoIdeal: '? 一切都在理想的层级中。',
         tituloDiagnostico: '# ?? 结构诊断',
         foraCamada: (total) => `?? 发现 ${total} 个文件不在预期的层级中:\\n`
     },
+    // ─── 原型报告 ─────────────────────────────────────────────────────
     arquetipos: {
         titulo: `${ICONES_DIAGNOSTICO.arquetipos} 原型报告`,
         secoes: {
@@ -142,6 +154,7 @@ export const RelatorioMensagens = {
             executarNpmAudit: '在 exportarRelatorioArquetiposMarkdown 中执行 npm audit 时出错: {erro}'
         }
     },
+    // ─── 修剪报告 ─────────────────────────────────────────────────────
     poda: {
         titulo: `${ICONES_COMANDO.podar} Mahoraga 修剪报告`,
         secoes: {
@@ -193,6 +206,7 @@ export const RelatorioMensagens = {
             }
         }
     },
+    // ─── 重构报告 ─────────────────────────────────────────────────────
     reestruturar: {
         titulo: `${ICONES_COMANDO.reestruturar} Mahoraga 重构报告`,
         secoes: {
@@ -231,6 +245,7 @@ export const RelatorioMensagens = {
             }
         }
     },
+    // ─── 通用消息 ─────────────────────────────────────────────────────
     comum: {
         separadores: {
             secao: '---',
@@ -249,6 +264,12 @@ export const RelatorioMensagens = {
         }
     }
 };
+/**
+ * 格式化带变量的消息
+ * @example
+ * formatMessage(RelatorioMessages.principal.secoes.metadados.arquivos, { count: 42 })
+ * // => "已扫描文件: 42"
+ */
 export function formatMessage(template, vars) {
     let result = template;
     for (const [key, value] of Object.entries(vars)) {
@@ -256,11 +277,16 @@ export function formatMessage(template, vars) {
     }
     return result;
 }
+/**
+ * 简单复数化辅助函数
+ */
 export function pluralize(count, singular, plural, showCount = true) {
     const word = count === 1 ? singular : plural;
     return showCount ? `${count} ${word}` : word;
 }
+/**
+ * 创建分隔行
+ */
 export function separator(char = '-', length = 80) {
     return char.repeat(length);
 }
-//# sourceMappingURL=report-messages.js.map