贡献核心规则
ESLint 核心规则是包含在 ESLint 包中的规则。
规则编写文档
有关编写规则的完整参考信息,请参阅自定义规则。自定义规则和核心规则具有相同的 API。核心规则和自定义规则之间的主要区别在于
- 核心规则包含在
eslint
包中。 - 核心规则必须遵守此页面上记录的约定。
文件结构
ESLint 中的每个核心规则都有三个文件,以其标识符命名(例如,no-extra-semi
)。
- 在
lib/rules
目录中:一个源文件(例如,no-extra-semi.js
)。 - 在
tests/lib/rules
目录中:一个测试文件(例如,no-extra-semi.js
)。 - 在
docs/src/rules
目录中:一个 Markdown 文档文件(例如,no-extra-semi.md
)。
重要提示: 如果您向 ESLint 存储库提交核心规则,则您必须遵循下面解释的约定。
以下是规则源文件的基本格式
/**
* @fileoverview Rule to disallow unnecessary semicolons
* @author Nicholas C. Zakas
*/
"use strict";
//------------------------------------------------------------------------------
// Rule Definition
//------------------------------------------------------------------------------
/** @type {import('../shared/types').Rule} */
module.exports = {
meta: {
type: "suggestion",
docs: {
description: "disallow unnecessary semicolons",
recommended: true,
url: "https://eslint.org.cn/docs/rules/no-extra-semi"
},
fixable: "code",
schema: [] // no options
},
create: function(context) {
return {
// callback functions
};
}
};
规则单元测试
ESLint 核心的每个捆绑规则都必须提交一组单元测试才能被接受。测试文件与源文件同名,但位于 tests/lib/
中。例如,如果规则源文件是 lib/rules/foo.js
,那么测试文件应该是 tests/lib/rules/foo.js
。
ESLint 提供了 RuleTester
实用程序,使编写规则测试变得容易。
性能测试
为了保持代码检查过程的高效和不唐突,验证新规则或对现有规则的修改的性能影响非常有用。
要了解如何分析单个规则的性能,请参阅自定义规则文档中的分析规则性能。
在 ESLint 核心存储库中开发时,npm run perf
命令提供了启用所有核心规则的 ESLint 运行时间的高级概述。
$ git checkout main
Switched to branch 'main'
$ npm run perf
CPU Speed is 2200 with multiplier 7500000
Performance Run #1: 1394.689313ms
Performance Run #2: 1423.295351ms
Performance Run #3: 1385.09515ms
Performance Run #4: 1382.406982ms
Performance Run #5: 1409.68566ms
Performance budget ok: 1394.689313ms (limit: 3409.090909090909ms)
$ git checkout my-rule-branch
Switched to branch 'my-rule-branch'
$ npm run perf
CPU Speed is 2200 with multiplier 7500000
Performance Run #1: 1443.736547ms
Performance Run #2: 1419.193291ms
Performance Run #3: 1436.018228ms
Performance Run #4: 1473.605485ms
Performance Run #5: 1457.455283ms
Performance budget ok: 1443.736547ms (limit: 3409.090909090909ms)
规则命名约定
ESLint 的规则命名约定如下
- 在单词之间使用破折号。
- 如果您的规则仅禁止某项,请以
no-
为前缀,例如禁止eval()
的no-eval
和禁止debugger
的no-debugger
。 - 如果您的规则是强制包含某项,请使用不带特殊前缀的短名称。
冻结规则
当规则功能完善时,它们会被标记为冻结(在文档中用 ❄️ 表示)。当规则的预期目的已完全实现,使其捕获 80% 或更多预期违规行为并涵盖大多数常见例外情况时,规则被认为是功能完善的。在那之后,我们希望用户在使用 禁用注释 时,找到未涵盖的边缘情况。
当规则被冻结时,这意味着
- 错误修复:我们仍将修复已确认的错误。
- 新的 ECMAScript 功能:我们将确保与新的 ECMAScript 功能兼容,这意味着规则不会在新语法上崩溃。
- 新选项:除非选项是修复错误或支持新添加的 ECMAScript 功能的唯一方法,否则我们不会添加任何新选项。
如果您发现冻结规则通过更改可以更好地为您工作,我们建议复制规则源代码并对其进行修改以适应您的需求。