Lint 插件
这是一个实验性功能,需要 Deno 2.2.0
或更高版本。
插件 API 当前标记为“不稳定”,因为它将来可能会发生更改。
内置 linter 可以通过插件扩展以添加自定义 lint 规则。
虽然 Deno 默认附带了许多 lint 规则,但在某些情况下,您需要针对您的项目定制自定义规则 - 无论是为了捕获特定于上下文的问题还是强制执行公司范围的约定。
这就是 lint 插件 API 的用武之地。
lint 插件 API 有意模仿了 ESLint API。虽然此 API 未提供 100% 兼容性,但如果您过去编写过自定义 ESLint 规则,则可以最大程度地重用编写 ESLint 插件的现有知识。
插件通过 deno.json
中的 lint.plugins
设置加载。
该值是插件说明符的数组。这些可以是路径、npm:
或 jsr:
说明符。
{
"lint": {
"plugins": ["./my-plugin.ts"]
}
}
插件示例 跳转到标题
插件始终具有相同的形状。它具有默认导出,即您的插件对象。
Deno 为 lint 插件 API 提供了类型声明。
所有类型都可以在 Deno.lint
命名空间下找到。
export default {
// The name of your plugin. Will be shown in error output
name: "my-plugin",
// Object with rules. The property name is the rule name and
// will be shown in the error output as well.
rules: {
"my-rule": {
// Inside the `create(context)` method is where you'll put your logic.
// It's called when a file is being linted.
create(context) {
// Return an AST visitor object
return {
// Here in this example we forbid any identifiers being named `_a`
Identifier(node) {
if (node.name === "_a") {
// Report a lint error with a custom message
context.report({
node,
message: "should be _b",
// Optional: Provide a fix, which can be applied when
// the user runs `deno lint --fix`
fix(fixer) {
return fixer.replaceText(node, "_b");
},
});
}
},
};
},
},
},
} satisfies Deno.lint.Plugin;
使用选择器匹配节点 跳转到标题
如果用纯 JavaScript 编写代码来匹配特定节点,有时会变得有点乏味。有时,这种匹配逻辑通过选择器(类似于 CSS 选择器)更容易表达。使用字符串作为返回的 visitor 对象中的属性名称,我们可以指定自定义选择器。
export default {
name: "my-plugin",
rules: {
"my-rule": {
create(context) {
return {
// Selectors can be used too. Here we check for
// `require("...") calls.
'CallExpression[callee.name="require"]'(node) {
context.report({
node,
message: "Don't use require() calls to load modules",
});
},
};
},
},
},
} satisfies Deno.lint.Plugin;
请注意,如果匹配逻辑过于复杂而无法单独表示为选择器,我们始终可以在 JavaScript 中进一步完善我们的匹配。选择器支持的完整语法列表是
语法 | 描述 |
---|---|
Foo + Foo |
下一个兄弟选择器 |
Foo > Bar |
子组合符 |
Foo ~ Bar |
后续兄弟组合符 |
Foo Bar |
后代组合符 |
Foo[attr] |
属性存在 |
Foo[attr.length < 2] |
属性值比较 |
:first-child |
第一个子伪类 |
:last-child |
最后一个子伪类 |
:nth-child(2n + 1) |
第 n 个子伪类 |
:not(> Bar) |
否定伪类 |
:is(> Bar) |
Is 伪类 |
应用修复 跳转到标题
自定义 lint 规则可以提供一个函数,用于在报告问题时应用修复。当运行 deno lint --fix
或从编辑器内部通过 Deno LSP 应用修复时,将调用可选的 fix()
方法。
fix()
方法接收一个 fixer
实例,其中包含使创建修复更容易的辅助方法。修复包括起始位置、结束位置和应放在此范围内的新文本。
context.report({
node,
message: "should be _b",
fix(fixer) {
return fixer.replaceText(node, "_b");
},
});
fixer
对象具有以下方法
insertTextAfter(node, text)
:在给定节点后插入文本。insertTextAfterRange(range, text)
:在给定范围后插入文本。insertTextBefore(node, text)
:在给定节点前插入文本。insertTextBeforeRange(range, text)
:在给定范围前插入文本。remove(node)
:移除给定节点。removeRange(range)
:移除给定范围内的文本。replaceText(node, text)
:替换给定节点中的文本。replaceTextRange(range, text)
:替换给定范围内的文本。
fix()
方法还可以返回修复数组,或者如果它是生成器函数,则可以生成多个修复。
有时,创建修复需要节点的原始源文本。要获取任何节点的源代码,请使用 context.sourceCode.getText()
context.report({
node,
message: "should be _b",
fix(fixer) {
const original = context.sourceCode.getText(node);
const newText = `{ ${original} }`;
return fixer.replaceText(node, newText);
},
});
运行清理代码 跳转到标题
如果您的插件需要在文件 lint 完成后运行清理代码,您可以通过 destroy()
钩子挂接到 linter。它在文件 lint 完成后以及插件上下文被销毁之前调用。
export default {
name: "my-plugin",
rules: {
"my-rule": {
create(context) {
// ...
},
// Optional: Run code after a linting for a file is completed
// and each rule context is destroyed.
destroy() {
// do some cleanup stuff if you need to
},
},
},
} satisfies Deno.lint.Plugin;
假设您的插件代码将针对每个 lint 的文件再次执行是不安全的。
尽量不要保持全局状态,并在 destroy
钩子中进行清理,以防 deno lint
决定重用现有的插件实例。
排除自定义规则 跳转到标题
与内置规则类似,您可以禁用插件提供的自定义规则。为此,请将其添加到 deno.json
中的 lint.rules.exclude
键。自定义 lint 规则的格式始终为 <plugin-name>/<rule-name>
。
{
"lint": {
"plugins": ["./my-plugin.ts"],
"rules": {
"exclude": ["my-plugin/my-rule"]
}
}
}
测试插件 跳转到标题
Deno.lint.runPlugin
API 提供了一种方便的方式来测试您的插件。它允许您断言插件针对特定输入产生预期的诊断结果。
让我们使用上面定义的示例插件
import { assert, assertEquals } from "jsr:@std/assert";
import myPlugin from "./my-plugin.ts";
Deno.test("my-plugin", () => {
const diagnostics = Deno.lint.runPlugin(plugin, "main.ts", "const _a = 'a';");
assertEquals(diagnostics.length, 1);
const d = diagnostics[0];
assertEquals(d.id, "my-plugin/my-rule");
assertEquals(d.message, "should be _b");
assert(typeof d.fix === "function");
});
Deno.lint.runPlugin
API 仅在 deno test
和 deno bench
子命令中可用。
尝试将其与任何其他子命令一起使用将导致抛出错误。
有关 Deno.lint.runPlugin
和 Deno.lint.Diagnostic
的更多信息,请参阅 API 参考。