eslint-plugin-better-codes 1.0.0

package/README.md

@@ -0,0 +1,57 @@
+# eslint-plugin-better-codes
+
+<!-- <p align="center">
+  <img src="./icon.svg" alt="eslint-plugin-better-codes icon" width="120" />
+</p> -->
+
+简体中文
+
+## 简介
+
+`eslint-plugin-better-codes` 是一组自定义的 ESLint 插件规则集合，其中包含用于检测并禁止被注释掉的代码的规则 `eslint-no-commented-code`。帮助团队保持代码库清洁，避免大量被注释的冗余代码。
+
+## 安装
+
+使用 npm:
+
+```bash
+npm install --save-dev eslint-plugin-better-codes
+```
+
+或使用 yarn:
+
+```bash
+yarn add -D eslint-plugin-better-codes
+```
+
+## 使用方式
+
+在你的 ESLint 配置文件中启用插件并打开规则。例如 `.eslintrc.js`：
+
+```javascript
+module.exports = {
+  plugins: ["better-codes"],
+  rules: {
+    "better-codes/no-commented-code": "error",
+  },
+};
+```
+
+规则名：`no-commented-code`（导出于 `index.js` 中）。
+
+## 主要功能
+
+### no-commented-code
+
+禁止提交注释掉的代码：
+
+- 对于单行注释：累计行数大于等于minLines时报错。对于第一个字符为中文、大写英文字母、数字，不进行校验。如果最后面包含ignore-eslint，不进行校验（最多可以忽略minLines - 1次）
+- 对于多行注释：累计行数大于等于minLines时报错，空格行、只包含\*的行、空行不计数。如果内容包含@param、@returns(函数注释)，@D(d)escription（文件头注释），@C(c)omment（块状功能注释）不进行校验
+
+### function-with-try-catch
+
+强制函数必须包含 try-catch 语句块
+
+## 许可证
+
+MIT

package/index.js

@@ -0,0 +1,9 @@
+const noCommentedCode = require("./libs/no-commented-code.js");
+const functionWithTryCatch = require("./libs/function-with-try-catch-code.js");
+const plugin = {
+  rules: {
+    "no-commented-code": noCommentedCode,
+    "function-with-try-catch": functionWithTryCatch,
+  },
+};
+module.exports = plugin;

package/libs/function-with-try-catch-code.js

@@ -0,0 +1,86 @@
+/**
+ * 检查函数体中是否包含 try...catch
+ * 对于有函数体且包含语句的函数，如果没有 try/catch 报警
+ */
+function containsTryStatement(node) {
+	let found = false;
+	const seen = new Set();
+	function traverse(n) {
+		if (!n || found) return;
+		if (seen.has(n)) return;
+		if (Array.isArray(n)) {
+			for (const item of n) {
+				traverse(item);
+				if (found) return;
+			}
+			return;
+		}
+		if (typeof n !== "object") return;
+		seen.add(n);
+		if (n.type === "TryStatement") {
+			found = true;
+			return;
+		}
+		for (const key of Object.keys(n)) {
+			if (found) break;
+			const child = n[key];
+			if (child && typeof child === "object") {
+				traverse(child);
+			}
+		}
+	}
+	traverse(node);
+	return found;
+}
+
+module.exports = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "提醒函数内部应包含 try...catch 以便处理异常",
+			category: "Best Practices",
+			recommended: false,
+		},
+		schema: [],
+	},
+	create(context) {
+		function reportIfMissingTry(node, name) {
+			// 箭头函数表达式且为表达式体，跳过
+			if (node.type === "ArrowFunctionExpression" && node.body && node.body.type !== "BlockStatement") {
+				return;
+			}
+			const body = node.body;
+			if (!body || body.type !== "BlockStatement") return;
+			const stmts = body.body || [];
+			// 如果函数体为空或只有注释/空，则跳过
+			if (stmts.length === 0) return;
+			// 如果函数体中包含 TryStatement，说明已处理，跳过
+			if (containsTryStatement(body)) return;
+			context.report({
+				node,
+				message: `${name || '函数'} 未包含 try...catch，建议添加错误处理`,
+			});
+		}
+
+		return {
+			FunctionDeclaration(node) {
+				const name = node.id && node.id.name;
+				reportIfMissingTry(node, name);
+			},
+			FunctionExpression(node) {
+				const name = node.id && node.id.name;
+				reportIfMissingTry(node, name);
+			},
+			ArrowFunctionExpression(node) {
+				reportIfMissingTry(node, '箭头函数');
+			},
+			MethodDefinition(node) {
+				// 跳过 constructor/get/set
+				if (node.kind === 'constructor' || node.kind === 'get' || node.kind === 'set') return;
+				const key = node.key && (node.key.name || (node.key.value && String(node.key.value)));
+				if (node.value) reportIfMissingTry(node.value, key || '方法');
+			},
+		};
+	},
+};
+

package/libs/no-commented-code.js

@@ -0,0 +1,166 @@
+/**
+ * 区分功能注释和代码注释
+ * @param {String} comment - 注释的内容
+ * @param {Boolean} isBlock - 是否为块注释
+ * @returns {Boolean} 是否为功能注释
+ */
+function isFunctionComment(comment, isBlock = false) {
+  try {
+    // 去除前后空格
+    comment = comment.trim();
+    // 取第一个字符
+    const firstStr = comment[0];
+    // 判断第一个字符是否为中文
+    const isChinese = /^[\u4e00-\u9fa5]+$/.test(firstStr);
+    // 判断第一个字符是否为大写英文字母
+    const isCapitalEnglish = /^[A-Z]+$/.test(firstStr);
+    // 判断第一个字符是否为数字
+    const isNum = /^[0-9]+$/.test(firstStr);
+    if (
+      isChinese ||
+      isCapitalEnglish ||
+      isFuncComment(comment, isBlock) ||
+      isNum
+    ) {
+      return true;
+    }
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+/**
+ * 区分函数的功能注释
+ * 例如
+ * /**
+ * Function description
+ * @param {type} paramName - Parameter description
+ * @returns {type} Return description
+ *
+ * @param {String} comment - 注释的内容
+ * @param {Boolean} isBlock - 是否为块注释
+ * @returns {Boolean} 是否为函数的功能注释
+ */
+function isFuncComment(comment) {
+  if (
+    comment.includes("@param") ||
+    comment.includes("@returns") ||
+    comment.includes("@Description") ||
+    comment.includes("@description") ||
+    comment.includes("@comment") ||
+    comment.includes("@Comment")
+  ) {
+    return true;
+  }
+}
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "禁止提交注释掉的代码块",
+      category: "Best Practices",
+      recommended: true,
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          minLines: {
+            type: "integer",
+            minimum: 1,
+            default: 3,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const sourceCode = context.getSourceCode();
+    const options = context.options[0] || {};
+    const minLines = options.minLines || 5;
+    let ignoredCount = 0; // 忽略次数
+    let singleLineCount = 0; // 单行注释行数 只计算最终实际校验生效的
+    return {
+      Program() {
+        const comments = sourceCode.getAllComments();
+        comments.forEach(comment => {
+          if (comment.loc) {
+            // 单行注释
+            if (comment.type === "Line") {
+              if (isFunctionComment(comment.value)) {
+                return;
+              }
+              singleLineCount++;
+
+              const lines = comment.value.split("\n");
+              // 过滤空行，只计算有实际内容的行
+              const codeLines = lines.filter(line => {
+                const trimmed = line.trim();
+                return trimmed.length > 0;
+              });
+              const isIgnored = codeLines[0].endsWith("ignore-eslint"); // 因默认添加了ignore-eslint，进行忽略校验
+              if (isIgnored && ignoredCount < minLines) {
+                ignoredCount++;
+                singleLineCount--;
+              }
+              // 优先检查忽略次数：当忽略累计次数达到阈值时，优先提示并禁止继续忽略
+              if (ignoredCount >= minLines) {
+                context.report({
+                  node: comment,
+                  message: `总忽略次数大于等于${minLines}次，请删除或保留为有效代码`,
+                  data: {
+                    lines: ignoredCount,
+                  },
+                });
+                return;
+              }
+              // 其次检查单行注释总数
+              if (singleLineCount >= minLines) {
+                context.report({
+                  node: comment,
+                  message: `单行注释大于等于 ${minLines} 行代码，请删除或保留为有效代码`,
+                  data: {
+                    lines: singleLineCount,
+                  },
+                });
+                return;
+              }
+              // 如果注释块包含多行代码逻辑
+              if (codeLines.length >= minLines) {
+                context.report({
+                  node: comment,
+                  message: `注释掉了 ${codeLines.length} 行代码，请删除或保留为有效代码`,
+                  data: {
+                    lines: codeLines.length,
+                  },
+                });
+              }
+            }
+            // 多行注释
+            if (comment.type === "Block") {
+              if (isFunctionComment(comment.value, true)) {
+                return;
+              }
+              const lines = comment.value.split("\n");
+              const codeLines = lines.filter(line => {
+                const trimmed = line.trim();
+                return trimmed !== "*" && trimmed.length > 0 && trimmed; // 过滤掉空行和只包含*的行
+              });
+              if (codeLines.length >= minLines) {
+                context.report({
+                  node: comment,
+                  message: `注释掉了 ${codeLines.length} 行代码，请删除或保留为有效代码`,
+                  data: {
+                    lines: codeLines.length,
+                  },
+                });
+              }
+            }
+          }
+        });
+      },
+    };
+  },
+};

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "eslint-plugin-better-codes",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "npx eslint ./test.js"
+  },
+  "keywords": [
+    "eslint",
+    "eslint-plugin"
+  ],
+  "author": "",
+  "license": "MIT",
+  "description": "eslint代码规范校验自定义插件合集,提升代码质量"
+}