Migrate from Luacheck to Selene

[carlos-algms]

Selene vs Luacheck

Benefits

Aspect	Luacheck	Selene
Maintenance	Last commit Oct 2018 ❌	Actively maintained ✅
Performance	Lua, single-threaded	Rust, multithreaded 🚀
Config format	.luacheckrc (Lua, numeric codes)	selene.toml (TOML, human-readable names)
Severity levels	All warnings equal	deny vs warn distinction
Type checking	Field existence only	Argument types, counts, stdlib validation

Strictness Comparison

Selene is generally MORE strict - catches things luacheck misses:

• Incorrect function argument usage
• Type mismatches in stdlib functions
• Better inline filtering (block-level, not just line-level)

Luacheck has some features selene lacks:

• Long line detection (631)
• Unreachable code detection
• Unused labels/uninitialized variables

Neovim Diagnostics Integration

Via none-ls.nvim (active fork of null-ls):

local null_ls = require("null-ls")
null_ls.setup({
  sources = {
    null_ls.builtins.diagnostics.selene,
  },
})

Example selene.toml

std = "lua51+vim"  -- or std = "vim"
exclude = ["lazy_repro/", "deps/", ".local/"]

[lints]
mixed_table = "allow"
unused_variable = "warn"
shadowing = "allow"

For busted tests, need a custom vim.yml stdlib that includes describe, it, before_each, etc.

Sources

• Selene vs Luacheck comparison
• Selene documentation
• none-ls.nvim
• mason.nvim selene config
• plenary.nvim selene discussion

[carlos-algms]

Additional Discoveries

Why Luacheck is Unmaintained

Sadly, Peter Melnichenko, the original author and maintainer of luacheck, passed away (Issue #198). The original repository (mpeterv/luacheck) became unmaintained, though the community forked it under Lunar Modules to continue maintenance. However, even the community fork has limited activity since October 2018.

Custom Standard Library Definitions (TOML Format)

When using selene with custom globals or methods, define them in your stdlib TOML file:

For file handle methods like io.stderr:write():

[io.stderr.write]
method = true
[[io.stderr.write.args]]
type = "string"

[io.stdout.write]
method = true
[[io.stdout.write.args]]
type = "string"

Key points:

• method = true indicates the function should be called with : syntax (e.g., io.stderr:write(...))
• Without method = true, selene expects . syntax (e.g., io.stderr.write(...))
• Use [[object.method.args]] to define argument types for better validation

Note: The TOML standard library format is deprecated in favor of YAML, but still fully supported. Use selene upgrade-std library.toml to convert to YAML if needed.

Sources

• Peter Melnichenko passing - GitHub Issue #198
• TOML Standard Library Format - selene Documentation
• Standard Library Format - selene Documentation
• Using the GraphQL API for Discussions - GitHub Docs