auto-cr-rules 2.0.76 → 2.0.78

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);

package/package.json

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