auto-cr-cmd 2.0.78 → 2.0.79

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.
@@ -121,6 +121,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 发布命令，保持两个包的版本同步。
@@ -121,6 +121,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 '未提供文件或目录路径，跳过代码扫描'; },
@@ -232,8 +233,10 @@ var translations = {
         },
     },
 };
+// 当前语言与翻译器为全局单例，方便在各处同步使用。
 var currentLanguage = 'zh';
 var currentTranslator = translations.zh;
+// 对输入语言进行归一化，未知语言回退到中文。
 function normalizeLanguage(input) {
     if (!input) {
         return 'zh';
@@ -253,9 +256,11 @@ function setLanguage(language) {
     currentTranslator = translations[normalized];
     return currentTranslator;
 }
+// 获取当前语言标识（用于 reporter 输出与规则文案）。
 function getLanguage() {
     return currentLanguage;
 }
+// 获取当前翻译器（用于 CLI/报错/提示文案）。
 function getTranslator() {
     return currentTranslator;
 }

package/dist/index.js

@@ -386,6 +386,7 @@ function analyzeFile(file, rules, format, log) {
 }
 function normalizeViolationInput(input, spanArg) {
     var _a;
+    // 规则既可以直接输出字符串，也可以输出结构化对象；这里统一为标准格式。
     if (typeof input === 'string') {
         return {
             message: input,
@@ -436,6 +437,7 @@ function normalizeViolationInput(input, spanArg) {
         span: spanArg,
     };
 }
+// CLI 输出格式解析：仅允许 text/json。
 function parseOutputFormat(value) {
     if (!value) {
         return 'text';
@@ -477,6 +479,7 @@ function formatViolationForJson(violation) {
     return payload;
 }
 function formatJsonOutput(result) {
+    // JSON 输出用于 CI/脚本解析，保持结构稳定。
     return {
         summary: {
             scannedFiles: result.scannedFiles,

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,7 @@ 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;
+    // 累计单文件的违规统计，便于输出文件级 summary。
     var totalViolations = 0;
     var errorViolations = 0;
     var severityCounts = {
@@ -94,6 +96,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 +140,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 = {
@@ -186,6 +190,7 @@ function createReporter(filePath, source, options) {
         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/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.79",
   "description": "Fast automated code review CLI powered by SWC-based static analysis",
   "main": "./dist/index.js",
   "types": "./dist/types/index.d.ts",