auto-cr-rules 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/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

@@ -397,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.78",
+  "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",