auto-cr-rules 2.0.76 → 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/imports.js

@@ -10,6 +10,7 @@ var isSwcNode = function (value) {
     }
     return typeof value.type === 'string';
 };
+// 递归遍历 AST，遇到带 type 的节点就回调。
 var traverse = function (value, visitor) {
     if (Array.isArray(value)) {
         for (var _i = 0, value_1 = value; _i < value_1.length; _i++) {
@@ -34,6 +35,7 @@ var traverse = function (value, visitor) {
 };
 var isImportDeclaration = function (node) { return node.type === 'ImportDeclaration'; };
 var isCallExpression = function (node) { return node.type === 'CallExpression'; };
+// 收集模块中的所有导入引用（包含动态 import 与 require）。
 var collectImportReferences = function (module) {
     var results = [];
     traverse(module, function (node) {
@@ -55,6 +57,7 @@ var collectImportReferences = function (module) {
     return results;
 };
 exports.collectImportReferences = collectImportReferences;
+// 从调用表达式中提取 import/require 的字符串字面量参数。
 var extractFromCallExpression = function (node) {
     if (!node.arguments.length) {
         return null;

package/dist/messages.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRuleMessages = void 0;
+// 规则文案多语言表（由 rules 通过 messages 接口访问）。
 var ruleTranslations = {
     zh: {
         noDeepRelativeImports: function (_a) {
@@ -25,7 +26,9 @@ var ruleTranslations = {
         },
     },
 };
+// 固定文案对象，避免运行期被意外修改。
 Object.values(ruleTranslations).forEach(function (messages) { return Object.freeze(messages); });
+// 根据语言返回对应的规则文案实现。
 var createRuleMessages = function (language) {
     var _a;
     return (_a = ruleTranslations[language]) !== null && _a !== void 0 ? _a : ruleTranslations.zh;

package/dist/rules/index.js

@@ -7,4 +7,5 @@ var noCircularDependencies_1 = require("./noCircularDependencies");
 Object.defineProperty(exports, "noCircularDependencies", { enumerable: true, get: function () { return noCircularDependencies_1.noCircularDependencies; } });
 var noSwallowedErrors_1 = require("./noSwallowedErrors");
 Object.defineProperty(exports, "noSwallowedErrors", { enumerable: true, get: function () { return noSwallowedErrors_1.noSwallowedErrors; } });
+// 内置规则列表，按默认顺序执行。
 exports.builtinRules = [noDeepRelativeImports_1.noDeepRelativeImports, noCircularDependencies_1.noCircularDependencies, noSwallowedErrors_1.noSwallowedErrors];

package/dist/rules/noCircularDependencies.js

@@ -16,10 +16,19 @@ exports.noCircularDependencies = void 0;
 var fs_1 = __importDefault(require("fs"));
 var path_1 = __importDefault(require("path"));
 var types_1 = require("../types");
+/**
+ * 检测相对路径形成的循环依赖：
+ * - 仅解析 .ts/.tsx/.js/.jsx/.mjs/.cjs；
+ * - 从当前文件的 import 出发，沿依赖图寻找回到自身的路径；
+ * - 输出完整环路链路，便于定位循环发生的文件。
+ */
 var SUPPORTED_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+// 避免在大型仓库里构图过深或过大导致卡顿。
 var MAX_GRAPH_NODES = 2000;
 var MAX_GRAPH_DEPTH = 80;
+// 跨文件缓存解析结果，减少重复 IO 与正则扫描。
 var resolvedImportCache = new Map();
+// 记录已上报的环路（做规范化），避免同一环路重复报错。
 var reportedCycles = new Set();
 exports.noCircularDependencies = (0, types_1.defineRule)('no-circular-dependencies', { tag: 'base', severity: types_1.RuleSeverity.Warning }, function (_a) {
     var _b, _c;
@@ -28,7 +37,7 @@ exports.noCircularDependencies = (0, types_1.defineRule)('no-circular-dependenci
     var root = resolveProjectRoot(origin);
     var moduleStart = (_c = (_b = ast.span) === null || _b === void 0 ? void 0 : _b.start) !== null && _c !== void 0 ? _c : 0;
     var lineIndex = buildLineIndex(source);
-    // Seed cache with SWC-collected imports for the current file.
+    // 先用 SWC 提供的 import 列表初始化当前文件的依赖，保证准确性与性能。
     resolvedImportCache.set(origin, resolveFromReferences(origin, helpers.imports, root));
     for (var _i = 0, _d = helpers.imports; _i < _d.length; _i++) {
         var reference = _d[_i];
@@ -39,6 +48,7 @@ exports.noCircularDependencies = (0, types_1.defineRule)('no-circular-dependenci
         if (!target) {
             continue;
         }
+        // 从目标模块回溯，如果能再次回到 origin，即存在环路。
         var pathToOrigin = findPathToOrigin(target, origin, root);
         if (!pathToOrigin) {
             continue;
@@ -49,6 +59,7 @@ exports.noCircularDependencies = (0, types_1.defineRule)('no-circular-dependenci
             continue;
         }
         reportedCycles.add(cycleKey);
+        // 统一输出相对路径，便于直接定位到仓库内文件。
         var displayChain = formatCycle(cycle, root);
         var description = messages.circularDependency({ chain: displayChain });
         var suggestions = language === 'zh'
@@ -60,6 +71,7 @@ exports.noCircularDependencies = (0, types_1.defineRule)('no-circular-dependenci
                 { text: 'Split modules to avoid mutual dependencies.' },
                 { text: 'Extract shared logic into a dedicated module to break the cycle.' },
             ];
+        // 优先使用 SWC 的 span 计算行号，作为高可信位置；失败时再用文本匹配兜底。
         var computedLine = reference.span
             ? resolveLine(lineIndex, bytePosToCharIndex(source, moduleStart, reference.span.start))
             : undefined;
@@ -74,6 +86,7 @@ exports.noCircularDependencies = (0, types_1.defineRule)('no-circular-dependenci
         }, reference.span);
     }
 });
+// 选择项目根目录：优先使用当前工作目录，找不到则向上寻找最近的 package.json。
 var resolveProjectRoot = function (filePath) {
     var cwd = path_1.default.resolve(process.cwd());
     if (isWithinRoot(filePath, cwd)) {
@@ -90,10 +103,12 @@ var resolveProjectRoot = function (filePath) {
     }
     return cwd;
 };
+// 防止解析路径逃逸到仓库外，避免跨项目误报。
 var isWithinRoot = function (filePath, root) {
     var relative = path_1.default.relative(root, filePath);
     return relative === '' || (!relative.startsWith('..') && !path_1.default.isAbsolute(relative));
 };
+// 将当前文件的 import 列表解析为真实文件路径（只处理相对路径）。
 var resolveFromReferences = function (origin, references, root) {
     var resolved = new Set();
     for (var _i = 0, references_1 = references; _i < references_1.length; _i++) {
@@ -108,6 +123,8 @@ var resolveFromReferences = function (origin, references, root) {
     }
     return Array.from(resolved);
 };
+// DFS 搜索依赖图中是否存在一条从 start 回到 origin 的路径。
+// 通过节点数与深度上限，避免超大项目中搜索失控。
 var findPathToOrigin = function (start, origin, root) {
     var nodesVisited = 0;
     var visiting = new Set();
@@ -145,6 +162,8 @@ var findPathToOrigin = function (start, origin, root) {
     };
     return walk(start, 0);
 };
+// 读取文件并通过简单正则抽取 import/require/export-from。
+// 这里不重新解析 AST，成本低但可能漏掉非常规写法。
 var getResolvedImports = function (filePath, root) {
     var cached = resolvedImportCache.get(filePath);
     if (cached) {
@@ -179,6 +198,7 @@ var readFileSafe = function (filePath) {
         return null;
     }
 };
+// 用正则匹配常见的导入写法，覆盖 import / dynamic import / require / export-from。
 var extractImportSpecifiers = function (source) {
     var results = [];
     var patterns = [
@@ -196,6 +216,8 @@ var extractImportSpecifiers = function (source) {
     }
     return results;
 };
+// 解析相对路径到真实文件：支持自动补全扩展名与目录 index。
+// 并确保解析结果在项目根目录内。
 var resolveImportFile = function (fromFile, specifier, root) {
     if (!specifier.startsWith('.')) {
         return null;
@@ -267,6 +289,7 @@ var resolveFromDirectory = function (basePath) {
     }
     return null;
 };
+// 将环路规范化为稳定 key，避免同一环路从不同入口重复报错。
 var buildCycleKey = function (cycle) {
     if (cycle.length <= 2) {
         return cycle.join('->');
@@ -282,6 +305,7 @@ var buildCycleKey = function (cycle) {
     }
     return best;
 };
+// 输出尽量相对路径，便于直接定位文件。
 var formatCycle = function (cycle, root) {
     var formatted = cycle.map(function (entry) {
         var relative = path_1.default.relative(root, entry);
@@ -373,6 +397,11 @@ var selectLineNumber = function (computed, fallback) {
     if (computed === undefined) {
         return fallback;
     }
+    // 当两者只差一行时，优先使用文本匹配结果，避免出现 +1 的偏移问题。
+    if (Math.abs(computed - fallback) <= 1) {
+        return fallback;
+    }
+    // 若 span 指向了更早的注释块，则回退到更靠后的文本行。
     if (computed < fallback) {
         return fallback;
     }

package/dist/rules/noDeepRelativeImports.js

@@ -3,10 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.noDeepRelativeImports = void 0;
 var types_1 = require("../types");
 var MAX_DEPTH = 2;
+// 检测相对路径过深的导入，避免维护困难与重构风险。
 exports.noDeepRelativeImports = (0, types_1.defineRule)('no-deep-relative-imports', { tag: 'base', severity: types_1.RuleSeverity.Warning }, function (_a) {
     var _b, _c;
     var ast = _a.ast, helpers = _a.helpers, messages = _a.messages, language = _a.language, source = _a.source;
-    // Build a per-file line index so we can convert byte offsets emitted by SWC back to line numbers.
+    // 构建行号索引，方便将 SWC 的 byte offset 转为行号。
     var moduleStart = (_c = (_b = ast.span) === null || _b === void 0 ? void 0 : _b.start) !== null && _c !== void 0 ? _c : 0;
     var lineIndex = buildLineIndex(source);
     for (var _i = 0, _d = helpers.imports; _i < _d.length; _i++) {
@@ -26,11 +27,12 @@ exports.noDeepRelativeImports = (0, types_1.defineRule)('no-deep-relative-import
                     { text: 'Use a path alias (for example: @shared/deep/utils).' },
                     { text: 'Create an index file at a higher level to re-export the module and shorten the import.' },
                 ];
+            // 优先使用 span 计算行号，若异常则退回到文本匹配。
             var computedLine = reference.span
                 ? resolveLine(lineIndex, bytePosToCharIndex(source, moduleStart, reference.span.start))
                 : undefined;
             var fallbackLine = findImportLine(source, reference.value);
-            // Prefer the larger value so we never point at leading block comments when the byte offset is truncated.
+            // 取更大的行号，避免 span 截断时指向注释块。
             var line = selectLineNumber(computedLine, fallbackLine);
             helpers.reportViolation({
                 description: description,

package/dist/rules/noSwallowedErrors.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.noSwallowedErrors = void 0;
 var types_1 = require("../types");
+// 检测 try/catch/finally 中未处理任何可执行语句的情况（吞掉异常）。
 exports.noSwallowedErrors = (0, types_1.defineRule)('no-swallowed-errors', { tag: 'base', severity: types_1.RuleSeverity.Warning }, function (_a) {
     var _b, _c;
     var ast = _a.ast, helpers = _a.helpers, messages = _a.messages, source = _a.source;
@@ -13,9 +14,11 @@ exports.noSwallowedErrors = (0, types_1.defineRule)('no-swallowed-errors', { tag
         var finallyBlock = (_c = tryStatement.finalizer) !== null && _c !== void 0 ? _c : null;
         var catchHasExecutable = catchBlock ? hasExecutableStatements(catchBlock.stmts) : false;
         var finallyHasExecutable = finallyBlock ? hasExecutableStatements(finallyBlock.stmts) : false;
+        // 任意一段有真实逻辑，则认为异常被处理或至少被记录。
         if (catchHasExecutable || finallyHasExecutable) {
             return;
         }
+        // 尽量指向 catch/finally 块本身，保证定位直观。
         var reportSpan = (_e = (_d = catchBlock === null || catchBlock === void 0 ? void 0 : catchBlock.span) !== null && _d !== void 0 ? _d : finallyBlock === null || finallyBlock === void 0 ? void 0 : finallyBlock.span) !== null && _e !== void 0 ? _e : tryStatement.span;
         var charIndex = bytePosToCharIndex(source, moduleStart, reportSpan.start);
         var computedLine = resolveLine(lineIndex, charIndex);

package/dist/runtime.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRuleContext = void 0;
 var imports_1 = require("./imports");
 var messages_1 = require("./messages");
+// 构建规则执行所需的上下文：包含 AST、imports、文案与统一的 helper 方法。
 var createRuleContext = function (_a) {
     var ast = _a.ast, filePath = _a.filePath, source = _a.source, reporter = _a.reporter, language = _a.language;
     var imports = (0, imports_1.collectImportReferences)(ast);
@@ -19,11 +20,13 @@ var createRuleContext = function (_a) {
     });
 };
 exports.createRuleContext = createRuleContext;
+// 规则 helper：统一封装路径判断、相对深度与违规上报逻辑。
 var createRuleHelpers = function (reporter, imports) {
     var isRelativePath = function (value) { return value.startsWith('.'); };
     var relativeDepth = function (value) {
         return (value.match(/\.\.\//g) || []).length;
     };
+    // reportViolation 可兼容 string 或结构化对象，并自动选择合适的 reporter 方法。
     var reportViolation = function (input, spanArg) {
         var normalized = normalizeViolationInput(input, spanArg);
         if (typeof reporter.record === 'function') {
@@ -48,6 +51,7 @@ var createRuleHelpers = function (reporter, imports) {
         reportViolation: reportViolation,
     };
 };
+// 统一规则输出结构，便于 reporter 处理 span/line/suggestions。
 function normalizeViolationInput(input, fallbackSpan) {
     var _a, _b;
     if (typeof input === 'string') {

package/dist/types.js

@@ -13,6 +13,7 @@ var __assign = (this && this.__assign) || function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toRule = exports.isRule = exports.RuleSeverity = void 0;
 exports.defineRule = defineRule;
+// 规则严重级别，决定 reporter 的输出样式与统计。
 var RuleSeverity;
 (function (RuleSeverity) {
     RuleSeverity["Error"] = "error";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-cr-rules",
-  "version": "2.0.76",
+  "version": "2.0.79",
   "description": "Extensible static analysis rule set for the auto-cr automated code review toolkit",
   "main": "dist/index.js",
   "types": "dist/types/index.d.ts",