当前位置：首页 > news >正文

自定义luacheck校验规则

news 2025/8/6 3:27:09

安装运行环境

安装环境及源码解析，参考：LuaCheck校验原理解析

自定义校验规则

从代码中可以看出，定义一条规则有以下关键点：

需要定义告警信息：由键值对组成，key为告警编码（不一定为纯数字，只是这里使用的是纯数字），value为告警信息，告警信息中，message_format为消息模板，fields为消息中定义的字段，这两者用于模板文本传参，如果不需要传参，即只需要打印固定信息时，fields可以为空 {} 。此处定义在每个模块的stage.warnings对象中。
需要在模块中定义stage.run函数并将其return，stage.run函数即为此模块的主函数，在这里执行校验规则，函数接受chstate参数，作为被检查行的上下文对象；
当需要弹出告警时，需要使用chstate:warn_xx函数推送，可用函数有：
1. chstate:warn_range(code, range, warning)：
  - code为步骤1定义的告警信息对应告警编码，字符串形式，如"541"；
  - range为需要提示的代码块，以node节点形式传入;
  - warning为需要覆盖的告警信息，例如，已定义告警信息为 {["541"] = {message_format = "empty do..end block", fields = {}}} ，这里可以通过传参 {["541"] = {message_format = "nothing", fields = {}}} 来将其覆盖。通常不需要传这个参数。
2. chstate:warn_var(code, var, warning)：此处code、warning参数与chstate:warn_range函数一致，var参数顾名思义，传入的是一个变量对象，同样以node节点形式传入；
3. chstate:warn_value(code, value, warning)：此处value为一个被赋值的变量对象，可知其关系为value.var_node 即为这个值对应的变量（ast语法树中节点），value.var_node.node即为对应代码块；
需要将这个模块添加到stages.lua的执行列表中，即 stages.names ，注意，必须要添加到前置流程之后，即 resolve_locals 之后；

示例：自定义规则模块

接下来实现一条简单自定义规则：代码中不允许出现 HelloLua 字样，规则编码为 700 ;

步骤1：stages下新增模块

在 src/luacheck/stages/ 下，新建 HelloLua.lua 文件，其内容为：

local stage = {}stage.warnings = {}function stage.run(chstate)
endreturn stage

步骤2：编写规则及其校验方法

修改 HelloLua.lua 文件如下：

local stage = {}stage.warnings = {["700"] = {message_format = "do not show HelloLua", fields = {}},
}function stage.run(chstate)local num_lines = #chstate.line_offsetsfor line_number = 1, num_lines dolocal line_offset = chstate.line_offsets[line_number]local line_length = chstate.line_lengths[line_number]-- 若检查到此行代码中存在HelloLua，则打印对应告警if chstate.source:find("HelloLua", line_offset, true) thenchstate:warn("700", line_number, line_offset, line_offset + #("HelloLua") - 1)endend
endreturn stage

步骤3：将自定义模块添加到stages.lua中

修改stages.lua中stages.names如下：

stages.names = {"parse","unwrap_parens","linearize","parse_inline_options","name_functions","resolve_locals","detect_bad_whitespace","detect_cyclomatic_complexity","detect_empty_blocks","detect_empty_statements","detect_globals","detect_reversed_fornum_loops","detect_unbalanced_assignments","detect_uninit_accesses","detect_unreachable_code","detect_unused_fields","detect_unused_locals","HelloLua"
}
-- 添加到末尾

此时该规则已配置完成，接下来是验证其生效；

步骤4：验证

用于测试的lua文件 init.lua 内容如下：

local base_dir = vim.env.LUNARVIM_BASE_DIRor (function()local init_path = debug.getinfo(1, "HelloLua").source -- 此处修改字符串内容，检查是否告警return init_path:sub(2):match("(.*[/\\])"):sub(1, -2)end)()if not vim.tbl_contains(vim.opt.rtp:get(), base_dir) thenvim.opt.rtp:prepend(base_dir)
endrequire("lvim.bootstrap"):init(base_dir)require("lvim.config"):load()local plugins = require "lvim.plugins"require("lvim.plugin-loader").load { plugins, lvim.plugins }require("lvim.core.theme").setup()local Log = require "lvim.core.log"
Log:debug "Starting LunarVim"local commands = require "lvim.core.commands"
commands.load(commands.defaults)

执行检查：

root@979bc2a8a939:~/test/luacheck-0.23.0# lua -e 'package.path="/root/test/luacheck-0.23.0/src/?.lua;/root/test/luacheck-0.23.0/src/?/init.lua;"..package.path' /root/test/luacheck-0.23.0/bin/luacheck.lua --codes init.lua 
Checking init.lua                                 8 warningsinit.lua:1:1: (W700) do not show HelloLuainit.lua:1:18: (W113) accessing undefined variable viminit.lua:2:1: (W700) do not show HelloLuainit.lua:3:1: (W700) do not show HelloLuainit.lua:7:8: (W113) accessing undefined variable viminit.lua:7:25: (W113) accessing undefined variable viminit.lua:8:3: (W113) accessing undefined variable viminit.lua:17:47: (W113) accessing undefined variable lvimTotal: 8 warnings / 0 errors in 1 file