auto-cr-cmd 2.0.78 → 2.0.80

package/README.md

@@ -22,7 +22,7 @@
 
 ## Feature Highlights (Automated Code Review & Static Analysis)
 
-- **Built-in Rule Library**: Ships with SWC AST static analysis rules out of the box, such as `no-deep-relative-imports`.
+- **Built-in Rule Library**: Ships with SWC AST static analysis rules out of the box, such as `no-deep-relative-imports`, `no-circular-dependencies`, and `no-swallowed-errors`.
 - **Extensible SDK**: `auto-cr-rules` exposes helpers like `defineRule` and `helpers.imports`, reducing the friction of authoring custom TypeScript / JavaScript rules.
 - **Workspace Friendly**: Manage both the CLI and rule package via pnpm workspaces and validate the full pipeline with a single build.
 - **Publishing Toolkit**: Version bump scripts and npm publish commands keep both packages in sync.
@@ -43,6 +43,7 @@ Common flags:
 - `--language <zh|en>`: Switch CLI output language (defaults to auto-detection).
 - `--rule-dir <directory>`: Load additional custom rules from a directory or package.
 - `--output <text|json>`: Choose between human-friendly text logs or structured JSON results (defaults to `text`).
+- `--progress [stdout|stderr]`: Force progress display (text output only); use `stderr` to keep stdout clean for piping.
 - `--config <path>`: Point to a `.autocrrc.json` or `.autocrrc.js` file to enable/disable rules.
 - `--ignore-path <path>`: Point to a `.autocrignore.json` or `.autocrignore.js` file to exclude files/directories from scanning.
 - `--tsconfig <path>`: Use a custom `tsconfig.json` (defaults to `<cwd>/tsconfig.json`).
@@ -121,6 +122,7 @@ npx auto-cr-cmd --output json -- ./src | jq
 {
   "rules": {
     "no-deep-relative-imports": "error",
+    "no-circular-dependencies": "warning",
     "no-swallowed-errors": "off"
   }
 }

package/README.zh-CN.md

@@ -22,7 +22,7 @@
 
 ## 特性亮点（自动化代码审查 & 静态代码分析）
 
-- **内置规则库**：默认集成 SWC AST 静态分析规则，例如 `no-deep-relative-imports`。
+- **内置规则库**：默认集成 SWC AST 静态分析规则，例如 `no-deep-relative-imports`、`no-circular-dependencies`、`no-swallowed-errors`。
 - **可扩展 SDK**：`auto-cr-rules` 暴露 `defineRule`、`helpers.imports` 等工具，降低编写 TypeScript / JavaScript 自定义规则的复杂度。
 - **工作区管理**：使用 pnpm workspace 同时管理 CLI 与规则包，一次构建即可验证完整流程。
 - **发布友好**：内置版本递增脚本与 npm 发布命令，保持两个包的版本同步。
@@ -43,6 +43,7 @@ npx auto-cr-cmd --language zh [需要扫描的代码目录]
 - `--language <zh|en>`：切换 CLI 输出语言（默认为自动检测）。
 - `--rule-dir <directory>`：加载额外的自定义规则目录或包。
 - `--output <text|json>`：选择输出格式，`text` 为友好的终端日志，`json` 用于集成脚本（默认为 `text`）。
+- `--progress [stdout|stderr]`：强制显示扫描进度（仅 text 输出），可选输出到 stdout/stderr，使用 stderr 可避免影响 stdout 管道。
 - `--config <path>`：指定 `.autocrrc.json` 或 `.autocrrc.js` 配置文件路径，用于开启/关闭规则。
 - `--ignore-path <path>`：指定 `.autocrignore.json` 或 `.autocrignore.js` 忽略文件路径，用于排除扫描。
 - `--tsconfig <path>`：指定自定义 `tsconfig.json` 路径（默认读取 `<cwd>/tsconfig.json`）。
@@ -121,6 +122,7 @@ npx auto-cr-cmd --output json -- ./src | jq
 {
   "rules": {
     "no-deep-relative-imports": "error",
+    "no-circular-dependencies": "warning",
     "no-swallowed-errors": "off"
   }
 }

package/dist/config/autocrrc.js

@@ -20,7 +20,9 @@ var fs_1 = __importDefault(require("fs"));
 var path_1 = __importDefault(require("path"));
 var auto_cr_rules_1 = require("auto-cr-rules");
 var i18n_1 = require("../i18n");
+// 支持的配置文件候选名（从当前工作目录开始查找）。
 var RC_CANDIDATES = ['.autocrrc.json', '.autocrrc.js'];
+// 读取 .autocrrc 并校验结构；任何解析失败都转成 warning 不中断扫描。
 function loadAutoCrRc(configPath) {
     var warnings = [];
     var t = (0, i18n_1.getTranslator)();
@@ -55,6 +57,7 @@ function loadAutoCrRc(configPath) {
         return { warnings: warnings };
     }
 }
+// 将 rules 配置应用到内置/自定义规则上，支持关闭与调整 severity。
 function applyRuleConfig(rules, ruleSettings, onWarning) {
     if (!ruleSettings || Object.keys(ruleSettings).length === 0) {
         return rules;
@@ -86,6 +89,7 @@ function applyRuleConfig(rules, ruleSettings, onWarning) {
     }
     return configured;
 }
+// 优先使用显式路径，否则在工作目录内按候选名查找。
 function resolveConfigPath(explicitPath) {
     if (explicitPath) {
         return path_1.default.isAbsolute(explicitPath) ? explicitPath : path_1.default.resolve(process.cwd(), explicitPath);
@@ -99,6 +103,7 @@ function resolveConfigPath(explicitPath) {
     }
     return null;
 }
+// 读取配置文件：支持 JSON 与 JS 导出。
 function readConfigFile(filePath) {
     if (filePath.endsWith('.json')) {
         var raw = fs_1.default.readFileSync(filePath, 'utf-8');
@@ -110,6 +115,7 @@ function readConfigFile(filePath) {
     }
     return {};
 }
+// 兼容 default 导出（CommonJS/ESM）。
 function unwrapDefault(value) {
     var _a;
     if (isRecord(value) && 'default' in value) {
@@ -120,6 +126,7 @@ function unwrapDefault(value) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+// 统一配置格式：支持字符串/数字/布尔值等多种简写形式。
 function normalizeRuleSetting(input) {
     if (input === undefined) {
         return undefined;

package/dist/config/ignore.js

@@ -9,7 +9,9 @@ var fs_1 = __importDefault(require("fs"));
 var path_1 = __importDefault(require("path"));
 var picomatch_1 = __importDefault(require("picomatch"));
 var i18n_1 = require("../i18n");
+// 忽略文件候选名（从当前工作目录开始查找）。
 var IGNORE_CANDIDATES = ['.autocrignore.json', '.autocrignore.js'];
+// 加载忽略配置：支持 JSON/JS/文本多种形式，失败仅输出 warning。
 function loadIgnoreConfig(configPath) {
     var warnings = [];
     var t = (0, i18n_1.getTranslator)();
@@ -36,6 +38,7 @@ function loadIgnoreConfig(configPath) {
         return { patterns: [], warnings: warnings, baseDir: baseDir };
     }
 }
+// 构建忽略匹配器，匹配绝对路径与相对路径两种形式。
 function createIgnoreMatcher(patterns, baseDir) {
     if (baseDir === void 0) { baseDir = process.cwd(); }
     if (!patterns.length) {
@@ -51,6 +54,7 @@ function createIgnoreMatcher(patterns, baseDir) {
         return matchers.some(function (matcher) { return matcher(normalized) || matcher(relative); });
     };
 }
+// 解析忽略配置路径：显式传入优先，其次按候选名查找。
 function resolveConfigPath(explicitPath) {
     if (explicitPath) {
         return path_1.default.isAbsolute(explicitPath) ? explicitPath : path_1.default.resolve(process.cwd(), explicitPath);
@@ -64,6 +68,7 @@ function resolveConfigPath(explicitPath) {
     }
     return null;
 }
+// 读取忽略文件：JSON/JS 导出均可。
 function readIgnoreFile(filePath) {
     if (filePath.endsWith('.json')) {
         var raw = fs_1.default.readFileSync(filePath, 'utf-8');
@@ -75,6 +80,8 @@ function readIgnoreFile(filePath) {
     }
     return [];
 }
+// 规范化 ignore 内容：
+// - 支持字符串数组 / 单个字符串（按行拆分）/ { ignore } / { default }。
 function normalizeIgnorePayload(payload) {
     var values = [];
     if (Array.isArray(payload)) {
@@ -97,6 +104,7 @@ function normalizeIgnorePayload(payload) {
     }
     return values;
 }
+// 过滤空行与注释行。
 function normalizeEntry(entry) {
     if (typeof entry !== 'string') {
         return null;
@@ -110,6 +118,7 @@ function normalizeEntry(entry) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+// 统一路径分隔符为 POSIX，保证跨平台匹配一致。
 function toPosix(p) {
     return p.split(path_1.default.sep).join('/');
 }

package/dist/config.js

@@ -21,6 +21,7 @@ var path_1 = __importDefault(require("path"));
 var jsonc_parser_1 = require("jsonc-parser");
 var i18n_1 = require("./i18n");
 var consola_1 = __importDefault(require("consola"));
+// 缓存 tsconfig 解析结果，避免每个文件都重复读取与解析。
 var cachedTsConfig;
 var tsConfigPathOverride = null;
 function setTsConfigPath(path) {
@@ -43,6 +44,7 @@ function formatParseErrors(errors, content) {
     })
         .join('; ');
 }
+// 读取并解析 tsconfig；失败时只记录警告，不中断扫描流程。
 function readTsConfig() {
     if (cachedTsConfig !== undefined) {
         return cachedTsConfig;
@@ -128,6 +130,7 @@ function createEsParserConfig(extension, options, enableDecorators) {
         importAttributes: true,
     };
 }
+// 按文件扩展名推导 SWC 的 parser 选项，并结合 tsconfig 的 target/decorators。
 function loadParseOptions(filePath) {
     var extension = path_1.default.extname(filePath).toLowerCase();
     var tsConfig = readTsConfig();

package/dist/i18n/index.js

@@ -4,6 +4,7 @@ exports.normalizeLanguage = normalizeLanguage;
 exports.setLanguage = setLanguage;
 exports.getLanguage = getLanguage;
 exports.getTranslator = getTranslator;
+// 中英文文案表：CLI 与 reporter 统一从这里取文案，避免散落硬编码。
 var translations = {
     zh: {
         noPathsProvided: function () { return '未提供文件或目录路径，跳过代码扫描'; },
@@ -18,6 +19,10 @@ var translations = {
             var file = _a.file;
             return "\u626B\u63CF\u6587\u4EF6: ".concat(file);
         },
+        scanProgress: function (_a) {
+            var percent = _a.percent, current = _a.current, total = _a.total;
+            return "auto-cr-cmd \u626B\u63CF\u8FDB\u5EA6: ".concat(percent, "% (").concat(current, "/").concat(total, ")");
+        },
         scanComplete: function () { return '代码扫描完成'; },
         scanError: function () { return '代码扫描过程中发生错误:'; },
         parseFileFailed: function (_a) {
@@ -131,6 +136,10 @@ var translations = {
             var file = _a.file;
             return "Scanning file: ".concat(file);
         },
+        scanProgress: function (_a) {
+            var percent = _a.percent, current = _a.current, total = _a.total;
+            return "auto-cr-cmd scan progress: ".concat(percent, "% (").concat(current, "/").concat(total, ")");
+        },
         scanComplete: function () { return 'Code scan complete'; },
         scanError: function () { return 'An error occurred during code scanning:'; },
         parseFileFailed: function (_a) {
@@ -232,8 +241,10 @@ var translations = {
         },
     },
 };
+// 当前语言与翻译器为全局单例，方便在各处同步使用。
 var currentLanguage = 'zh';
 var currentTranslator = translations.zh;
+// 对输入语言进行归一化，未知语言回退到中文。
 function normalizeLanguage(input) {
     if (!input) {
         return 'zh';
@@ -253,9 +264,11 @@ function setLanguage(language) {
     currentTranslator = translations[normalized];
     return currentTranslator;
 }
+// 获取当前语言标识（用于 reporter 输出与规则文案）。
 function getLanguage() {
     return currentLanguage;
 }
+// 获取当前翻译器（用于 CLI/报错/提示文案）。
 function getTranslator() {
     return currentTranslator;
 }

package/dist/index.js

@@ -95,14 +95,112 @@ var isScannableFile = function (filePath) {
  * 4. 逐文件扫描并汇总输出。
  */
 function run() {
-    return __awaiter(this, arguments, void 0, function (filePaths, ruleDir, format, configPath, ignorePath) {
-        var t, notifications, log, validPaths, ignoreConfig, isIgnored_1, allFiles, _i, validPaths_1, targetPath, stat, directoryFiles, scannableFiles, customRules, rcConfig, rules, filesWithErrors, filesWithWarnings, filesWithOptimizing, totalViolations, totalErrorViolations, totalWarningViolations, totalOptimizingViolations, fileSummaries, _a, scannableFiles_1, file, summary, error_1;
+    return __awaiter(this, arguments, void 0, function (filePaths, ruleDir, format, configPath, ignorePath, progressOption) {
+        var t, notifications, progressStream, runningUnderPnpm, forceProgress, progressStreamHasTty, progressEnabled, progressPinned, progressFlushLine, progressStyle, progressTotal, progressCurrent, progressLastPercent, clearProgressLine, renderProgress, startProgress, advanceProgress, finishProgress, reporterHooks, log, validPaths, ignoreConfig, isIgnored_1, allFiles, _i, validPaths_1, targetPath, stat, directoryFiles, scannableFiles, customRules, rcConfig, rules, filesWithErrors, filesWithWarnings, filesWithOptimizing, totalViolations, totalErrorViolations, totalWarningViolations, totalOptimizingViolations, fileSummaries, _a, scannableFiles_1, file, summary, error_1;
+        var _b;
         if (filePaths === void 0) { filePaths = []; }
-        return __generator(this, function (_b) {
-            switch (_b.label) {
+        return __generator(this, function (_c) {
+            switch (_c.label) {
                 case 0:
                     t = (0, i18n_1.getTranslator)();
                     notifications = [];
+                    progressStream = (progressOption === null || progressOption === void 0 ? void 0 : progressOption.stream) === 'stderr' ? process.stderr : process.stdout;
+                    runningUnderPnpm = /pnpm\//.test((_b = process.env.npm_config_user_agent) !== null && _b !== void 0 ? _b : '');
+                    forceProgress = Boolean(progressOption === null || progressOption === void 0 ? void 0 : progressOption.force);
+                    progressStreamHasTty = Boolean(progressStream.isTTY);
+                    progressEnabled = format === 'text' && (forceProgress || progressStreamHasTty || runningUnderPnpm);
+                    progressPinned = progressEnabled;
+                    progressFlushLine = progressEnabled && !progressStreamHasTty;
+                    progressStyle = progressStreamHasTty
+                        ? { prefix: '\x1b[44m\x1b[97m', reset: '\x1b[0m' }
+                        : { prefix: '', reset: '' };
+                    progressTotal = 0;
+                    progressCurrent = 0;
+                    progressLastPercent = -1;
+                    clearProgressLine = function () {
+                        if (!progressEnabled) {
+                            return;
+                        }
+                        if (progressPinned) {
+                            progressStream.write('\x1b7');
+                            progressStream.write('\x1b[1;1H');
+                            progressStream.write('\x1b[2K');
+                            progressStream.write('\x1b8');
+                        }
+                        else {
+                            progressStream.write('\r\x1b[2K');
+                        }
+                    };
+                    renderProgress = function (force) {
+                        if (force === void 0) { force = false; }
+                        if (!progressEnabled || progressTotal === 0) {
+                            return;
+                        }
+                        var percent = Math.min(100, Math.floor((progressCurrent / progressTotal) * 100));
+                        if (!force && percent === progressLastPercent) {
+                            return;
+                        }
+                        progressLastPercent = percent;
+                        var message = t.scanProgress({ percent: percent, current: progressCurrent, total: progressTotal });
+                        var styledMessage = progressStyle.prefix ? "".concat(progressStyle.prefix).concat(message) : message;
+                        if (progressPinned) {
+                            progressStream.write('\x1b7');
+                            progressStream.write('\x1b[1;1H');
+                            progressStream.write('\x1b[2K');
+                            progressStream.write(styledMessage);
+                            if (progressStyle.prefix) {
+                                progressStream.write('\x1b[K');
+                                progressStream.write(progressStyle.reset);
+                            }
+                            if (progressFlushLine) {
+                                progressStream.write('\n');
+                            }
+                            progressStream.write('\x1b8');
+                        }
+                        else {
+                            progressStream.write("\r".concat(styledMessage));
+                            if (progressStyle.prefix) {
+                                progressStream.write('\x1b[K');
+                                progressStream.write(progressStyle.reset);
+                            }
+                            else {
+                                progressStream.write('\x1b[K');
+                            }
+                        }
+                    };
+                    startProgress = function (total) {
+                        if (!progressEnabled) {
+                            return;
+                        }
+                        progressTotal = total;
+                        progressCurrent = 0;
+                        progressLastPercent = -1;
+                        renderProgress(true);
+                    };
+                    advanceProgress = function () {
+                        if (!progressEnabled || progressTotal === 0) {
+                            return;
+                        }
+                        progressCurrent = Math.min(progressCurrent + 1, progressTotal);
+                        renderProgress();
+                    };
+                    finishProgress = function () {
+                        if (!progressEnabled) {
+                            return;
+                        }
+                        if (progressTotal > 0) {
+                            progressCurrent = progressTotal;
+                            progressLastPercent = -1;
+                            renderProgress();
+                            clearProgressLine();
+                        }
+                        progressTotal = 0;
+                        progressCurrent = 0;
+                        progressLastPercent = -1;
+                    };
+                    reporterHooks = {
+                        onAfterReport: function () { return renderProgress(true); },
+                    };
                     log = function (level, message, detail) {
                         var detailText;
                         if (detail !== undefined) {
@@ -130,11 +228,12 @@ function run() {
                             else {
                                 logger(message, detail);
                             }
+                            renderProgress(true);
                         }
                     };
-                    _b.label = 1;
+                    _c.label = 1;
                 case 1:
-                    _b.trys.push([1, 6, , 7]);
+                    _c.trys.push([1, 6, , 7]);
                     if (filePaths.length === 0) {
                         log('info', t.noPathsProvided());
                         return [2 /*return*/, {
@@ -221,14 +320,15 @@ function run() {
                     totalWarningViolations = 0;
                     totalOptimizingViolations = 0;
                     fileSummaries = [];
+                    startProgress(scannableFiles.length);
                     _a = 0, scannableFiles_1 = scannableFiles;
-                    _b.label = 2;
+                    _c.label = 2;
                 case 2:
                     if (!(_a < scannableFiles_1.length)) return [3 /*break*/, 5];
                     file = scannableFiles_1[_a];
-                    return [4 /*yield*/, analyzeFile(file, rules, format, log)];
+                    return [4 /*yield*/, analyzeFile(file, rules, format, log, reporterHooks)];
                 case 3:
-                    summary = _b.sent();
+                    summary = _c.sent();
                     if (summary.severityCounts.error > 0) {
                         filesWithErrors += 1;
                     }
@@ -249,26 +349,29 @@ function run() {
                         errorViolations: summary.errorViolations,
                         violations: summary.violations,
                     });
-                    _b.label = 4;
+                    advanceProgress();
+                    _c.label = 4;
                 case 4:
                     _a++;
                     return [3 /*break*/, 2];
-                case 5: return [2 /*return*/, {
-                        scannedFiles: scannableFiles.length,
-                        filesWithErrors: filesWithErrors,
-                        filesWithWarnings: filesWithWarnings,
-                        filesWithOptimizing: filesWithOptimizing,
-                        violationTotals: {
-                            total: totalViolations,
-                            error: totalErrorViolations,
-                            warning: totalWarningViolations,
-                            optimizing: totalOptimizingViolations,
-                        },
-                        files: fileSummaries,
-                        notifications: notifications,
-                    }];
+                case 5:
+                    finishProgress();
+                    return [2 /*return*/, {
+                            scannedFiles: scannableFiles.length,
+                            filesWithErrors: filesWithErrors,
+                            filesWithWarnings: filesWithWarnings,
+                            filesWithOptimizing: filesWithOptimizing,
+                            violationTotals: {
+                                total: totalViolations,
+                                error: totalErrorViolations,
+                                warning: totalWarningViolations,
+                                optimizing: totalOptimizingViolations,
+                            },
+                            files: fileSummaries,
+                            notifications: notifications,
+                        }];
                 case 6:
-                    error_1 = _b.sent();
+                    error_1 = _c.sent();
                     throw error_1 instanceof Error ? error_1 : new Error(String(error_1));
                 case 7: return [2 /*return*/];
             }
@@ -282,14 +385,14 @@ function run() {
  * - 逐条执行规则，收集 reporter 输出；
  * - 汇总为文件级统计。
  */
-function analyzeFile(file, rules, format, log) {
+function analyzeFile(file, rules, format, log, reporterHooks) {
     return __awaiter(this, void 0, void 0, function () {
         var source, reporter, t, ast, parseOptions, language, baseContext, sharedHelpers, _loop_1, _i, rules_1, rule, summary;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
                     source = (0, file_1.readFile)(file);
-                    reporter = (0, report_1.createReporter)(file, source, { format: format });
+                    reporter = (0, report_1.createReporter)(file, source, __assign({ format: format }, reporterHooks));
                     t = (0, i18n_1.getTranslator)();
                     try {
                         parseOptions = (0, config_1.loadParseOptions)(file);
@@ -386,6 +489,7 @@ function analyzeFile(file, rules, format, log) {
 }
 function normalizeViolationInput(input, spanArg) {
     var _a;
+    // 规则既可以直接输出字符串，也可以输出结构化对象；这里统一为标准格式。
     if (typeof input === 'string') {
         return {
             message: input,
@@ -436,6 +540,7 @@ function normalizeViolationInput(input, spanArg) {
         span: spanArg,
     };
 }
+// CLI 输出格式解析：仅允许 text/json。
 function parseOutputFormat(value) {
     if (!value) {
         return 'text';
@@ -446,6 +551,22 @@ function parseOutputFormat(value) {
     }
     throw new Error("Unsupported output format: ".concat(value, ". Use \"text\" or \"json\"."));
 }
+function parseProgressOption(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (value === true) {
+        return { force: true, stream: 'stdout' };
+    }
+    if (typeof value === 'string') {
+        var normalized = value.toLowerCase();
+        if (normalized === 'stdout' || normalized === 'stderr') {
+            return { force: true, stream: normalized };
+        }
+        throw new Error("Unsupported progress output: ".concat(value, ". Use \"stdout\" or \"stderr\"."));
+    }
+    return undefined;
+}
 function severityToLabel(severity) {
     switch (severity) {
         case auto_cr_rules_1.RuleSeverity.Warning:
@@ -477,6 +598,7 @@ function formatViolationForJson(violation) {
     return payload;
 }
 function formatJsonOutput(result) {
+    // JSON 输出用于 CI/脚本解析，保持结构稳定。
     return {
         summary: {
             scannedFiles: result.scannedFiles,
@@ -503,13 +625,15 @@ commander_1.program
     .option('-c, --config <path>', '配置文件路径 (.autocrrc.json|.autocrrc.js) / Config file path (.autocrrc.json|.autocrrc.js)')
     .option('--ignore-path <path>', '忽略文件列表路径 (.autocrignore.json|.autocrignore.js) / Ignore file path (.autocrignore.json|.autocrignore.js)')
     .option('--tsconfig <path>', '自定义 tsconfig 路径 / Custom tsconfig path')
+    .option('--progress [stream]', '强制显示扫描进度，可选 stdout/stderr / Force showing scan progress (stdout/stderr)')
     .option('--stdin', '从标准输入读取扫描路径 / Read file paths from STDIN')
-    .parse(process.argv);
+    .parse(process.argv.filter(function (arg) { return arg !== '--'; }));
 var options = commander_1.program.opts();
 var cliArguments = commander_1.program.args;
 (0, i18n_1.setLanguage)((_a = options.language) !== null && _a !== void 0 ? _a : process.env.LANG);
 (0, config_1.setTsConfigPath)(options.tsconfig ? path_1.default.resolve(process.cwd(), options.tsconfig) : undefined);
 var outputFormat;
+var progressOption;
 try {
     outputFormat = parseOutputFormat(options.output);
 }
@@ -518,6 +642,14 @@ catch (error) {
     consola_1.consola.error(message);
     process.exit(1);
 }
+try {
+    progressOption = parseProgressOption(options.progress);
+}
+catch (error) {
+    var message = error instanceof Error ? error.message : String(error);
+    consola_1.consola.error(message);
+    process.exit(1);
+}
 ;
 (function () { return __awaiter(void 0, void 0, void 0, function () {
     var stdinTargets, combinedTargets, filePaths, result, t, payload, exitCode, language, resultMessage, exitCode, error_3, t, detail, payload;
@@ -530,7 +662,7 @@ catch (error) {
                 stdinTargets = _a.sent();
                 combinedTargets = __spreadArray(__spreadArray([], cliArguments, true), stdinTargets, true);
                 filePaths = combinedTargets.map(function (target) { return path_1.default.resolve(process.cwd(), target); });
-                return [4 /*yield*/, run(filePaths, options.ruleDir, outputFormat, options.config, options.ignorePath)];
+                return [4 /*yield*/, run(filePaths, options.ruleDir, outputFormat, options.config, options.ignorePath, progressOption)];
             case 2:
                 result = _a.sent();
                 t = (0, i18n_1.getTranslator)();

package/dist/report/index.js

@@ -30,6 +30,7 @@ var consola_1 = __importDefault(require("consola"));
 var i18n_1 = require("../i18n");
 var UNTAGGED_TAG = 'untagged';
 var DEFAULT_FORMAT = 'text';
+// 不同严重级别映射到不同日志级别。
 var severityLoggers = (_a = {},
     _a[auto_cr_rules_1.RuleSeverity.Error] = consola_1.default.error,
     _a[auto_cr_rules_1.RuleSeverity.Warning] = consola_1.default.warn,
@@ -43,6 +44,9 @@ function createReporter(filePath, source, options) {
     var language = (0, i18n_1.getLanguage)();
     var records = [];
     var format = (_a = options.format) !== null && _a !== void 0 ? _a : DEFAULT_FORMAT;
+    var onBeforeReport = options.onBeforeReport;
+    var onAfterReport = options.onAfterReport;
+    // 累计单文件的违规统计，便于输出文件级 summary。
     var totalViolations = 0;
     var errorViolations = 0;
     var severityCounts = {
@@ -94,6 +98,7 @@ function createReporter(filePath, source, options) {
         var _a, _b;
         var tag = (_a = rule.tag) !== null && _a !== void 0 ? _a : UNTAGGED_TAG;
         var severity = (_b = rule.severity) !== null && _b !== void 0 ? _b : auto_cr_rules_1.RuleSeverity.Error;
+        // 规则级 reporter 会把具体信息写入 records。
         var store = function (payload) {
             pushRecord({
                 tag: tag,
@@ -137,6 +142,7 @@ function createReporter(filePath, source, options) {
         };
         return reporterWithRecord;
     };
+    // flush 会输出（text 模式）并返回结构化 summary，同时重置内部状态。
     var flush = function () {
         var violationSnapshot = records.map(function (record) { return (__assign(__assign({}, record), { suggestions: record.suggestions ? __spreadArray([], record.suggestions, true) : undefined })); });
         var summary = {
@@ -150,6 +156,7 @@ function createReporter(filePath, source, options) {
             violations: violationSnapshot,
         };
         if (violationSnapshot.length > 0 && format === 'text') {
+            onBeforeReport === null || onBeforeReport === void 0 ? void 0 : onBeforeReport();
             var locale = language === 'zh' ? 'zh-CN' : 'en-US';
             var formatter_1 = new Intl.DateTimeFormat(locale, {
                 hour: '2-digit',
@@ -181,11 +188,13 @@ function createReporter(filePath, source, options) {
                     consola_1.default.log("".concat(indent_1).concat(t.reporterSuggestionLabel(), ": ").concat(suggestionLine));
                 }
             });
+            onAfterReport === null || onAfterReport === void 0 ? void 0 : onAfterReport();
         }
         records.length = 0;
         resetCounters();
         return summary;
     };
+    // 每次 flush 后清零，避免跨文件混淆统计。
     var resetCounters = function () {
         totalViolations = 0;
         errorViolations = 0;

package/dist/rules/loader.js

@@ -10,7 +10,9 @@ var consola_1 = require("consola");
 var file_1 = require("../utils/file");
 var i18n_1 = require("../i18n");
 var auto_cr_rules_1 = require("auto-cr-rules");
+// 自定义规则加载器：只解析 JS/CJS/MJS 文件，便于在运行时动态引入。
 var SUPPORTED_EXTENSIONS = ['.js', '.cjs', '.mjs'];
+// 从指定目录读取规则文件，并转换为 Rule 列表。
 function loadCustomRules(ruleDir) {
     var t = (0, i18n_1.getTranslator)();
     if (!ruleDir) {
@@ -30,6 +32,7 @@ function loadCustomRules(ruleDir) {
         try {
             // eslint-disable-next-line @typescript-eslint/no-require-imports
             var moduleExports = require(file);
+            // 支持模块直接导出 rule / rules / default / 数组。
             var rules = extractRules(moduleExports, file);
             if (!rules.length) {
                 consola_1.consola.warn(t.customRuleNoExport({ file: file }));
@@ -43,6 +46,7 @@ function loadCustomRules(ruleDir) {
     }
     return loaded;
 }
+// 兼容多种导出形态：默认导出、命名导出或数组。
 function extractRules(moduleExports, origin) {
     var collected = [];
     collected.push.apply(collected, normalizeCandidate(moduleExports, origin));
@@ -60,6 +64,7 @@ function extractRules(moduleExports, origin) {
     }
     return collected;
 }
+// 把候选导出统一转为 Rule；无法识别的会被忽略。
 function normalizeCandidate(candidate, origin) {
     if (!candidate) {
         return [];

package/dist/types/i18n/index.d.ts

@@ -10,6 +10,11 @@ interface Translator {
     scanningFile(params: {
         file: string;
     }): string;
+    scanProgress(params: {
+        percent: number;
+        current: number;
+        total: number;
+    }): string;
     scanComplete(): string;
     scanError(): string;
     parseFileFailed(params: {

package/dist/types/report/index.d.ts

@@ -3,6 +3,8 @@ import type { Rule, RuleReporter } from 'auto-cr-rules';
 export type ReporterFormat = 'text' | 'json';
 interface ReporterOptions {
     format?: ReporterFormat;
+    onBeforeReport?: () => void;
+    onAfterReport?: () => void;
 }
 export interface Reporter extends RuleReporter {
     forRule(rule: Pick<Rule, 'name' | 'tag' | 'severity'>): RuleReporter;

package/dist/types/utils/file.d.ts

@@ -1,6 +1,8 @@
 export declare const readFile: (path: string) => string;
 /**
  * 递归获取目录下所有 TypeScript 和 JavaScript 文件
+ * - 默认跳过 node_modules
+ * - 可通过 shouldIgnore 进一步过滤路径
  */
 export declare function getAllFiles(dirPath: string, arrayOfFiles?: string[], extensions?: string[], options?: {
     skipNodeModules?: boolean;

package/dist/utils/file.js

@@ -10,12 +10,15 @@ var fs_1 = __importDefault(require("fs"));
 var path_1 = __importDefault(require("path"));
 var consola_1 = require("consola");
 var i18n_1 = require("../i18n");
+// 统一读取文本文件（UTF-8），供解析与规则执行使用。
 var readFile = function (path) {
     return fs_1.default.readFileSync(path, 'utf-8');
 };
 exports.readFile = readFile;
 /**
  * 递归获取目录下所有 TypeScript 和 JavaScript 文件
+ * - 默认跳过 node_modules
+ * - 可通过 shouldIgnore 进一步过滤路径
  */
 function getAllFiles(dirPath, arrayOfFiles, extensions, options) {
     if (arrayOfFiles === void 0) { arrayOfFiles = []; }

package/dist/utils/stdin.js

@@ -37,6 +37,10 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readPathsFromStdin = readPathsFromStdin;
+// 从 STDIN 读取路径列表：
+// - 默认仅在非 TTY 时读取；
+// - 支持 NUL 分隔与换行分隔两种格式；
+// - 保留空格，仅移除空行与 CR。
 function readPathsFromStdin(shouldForceRead) {
     return __awaiter(this, void 0, void 0, function () {
         var shouldRead;
@@ -75,11 +79,11 @@ function readPathsFromStdin(shouldForceRead) {
                             if (buf.length === 0) {
                                 return finish([]);
                             }
-                            // Prefer NUL-delimited when present; else fall back to newline.
+                            // 优先使用 NUL 分隔（适配 xargs -0 等工具），否则按换行切分。
                             var hasNul = buf.includes(0); // 0x00
                             var payload = buf.toString('utf8');
                             var parts = hasNul ? payload.split('\0') : payload.split(/\r?\n/);
-                            // Preserve spaces in filenames; only strip stray CR and drop empties.
+                            // 保留文件名中的空格，只去掉末尾 CR 并过滤空行。
                             var lines = parts
                                 .map(function (s) { return (s.endsWith('\r') ? s.slice(0, -1) : s); })
                                 .filter(function (s) { return s.length > 0; });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-cr-cmd",
-  "version": "2.0.78",
+  "version": "2.0.80",
   "description": "Fast automated code review CLI powered by SWC-based static analysis",
   "main": "./dist/index.js",
   "types": "./dist/types/index.d.ts",