selene

selene is a command line tool designed to help write correct and idiomatic Lua code.

New to selene? Read the motivation behind its creation and the CLI guide. If you already use Luacheck, you can read the Luacheck comparison and migration guide.
Don't know what a linter is? Check out the wiki on linters about what a linter does and how it's beneficial.
Existing user? Read the changelog to learn about any new features or bug fixes.
Interested in what selene lints for? Read the list of lints.
Interested in contributing to selene's codebase? Read the contribution guide.
Want to discuss selene or get help? Join the Roblox OS Community Discord. Note: selene is not Roblox exclusive, but it started its life for Roblox development.

License

selene and all its source code are licensed under the Mozilla Public License 2.0.

Motivation

Because bugs

When writing any code, it's very easy to make silly mistakes that end up introducing bugs. A lot of the time, these bugs are hard to track down and debug, and sometimes are even harder to replicate.

This risk is made ever more real because of the generally lax nature of Lua. Incorrect code is regularly passed off and isn't noticed until something breaks at runtime. Sometimes you'll get a clear error message, and will have to spend time going back, fixing the code, and making sure you actually fixed it. Other times, the effects are more hidden, and instead of getting an error your code will just pass through along, in an incorrect state.

Take, for example, this code:

function Player:SwapWeapons()
    self.CurrentWeapon = self.SideWeapon
    self.SideWeapon = self.CurrentWeapon
end

This is code that is technically correct, but is absolutely not what you wanted to write. However, because it is technically correct, Lua will do exactly what you tell it to do, and so...

Player wants to swap their weapons
Your code calls player:SwapWeapons()
Their current weapon is set to their side weapon...
...but their side weapon is set to their current weapon afterwards, which is what they just equipped!

Uh oh! After debugging this, you realize that you actually meant to write was...

function Player:SwapWeapons()
    self.CurrentWeapon, self.SideWeapon = self.SideWeapon, self.CurrentWeapon
end

If you were using selene, you would've been alerted right away that your original code looked like an almost_swapped.

error[almost_swapped]: this looks like you are trying to swap `self.CurrentWeapon` and `self.SideWeapon`

   ┌── fail.lua:4:5 ───
   │
 4 │ ╭     self.CurrentWeapon = self.SideWeapon
 5 │ │     self.SideWeapon = self.CurrentWeapon
   │ ╰────────────────────────────────────────^
   │
   = try: `self.CurrentWeapon, self.SideWeapon = self.SideWeapon, self.CurrentWeapon`

Other bugs arise because of Lua's lack of typing. While it can feel freeing to developers to not have to specify types everywhere, it makes it easier to mess up and write broken code. For example, take the following code:

for _, shop in pairs(GoldShop, ItemShop, MedicineShop) do

This code is yet again technically correct, but not what we wanted to do. pairs will take the first argument, GoldShop, and ignore the rest. Worse, the shop variable will now be the values of the contents of GoldShop, not the shop itself. This can cause massive headaches, since although you're likely to get an error later down the line, it's more likely it'll be in the vein of "attempt to index a nil value items" than something more helpful. If you used ipairs instead of pairs, your code inside might just not run, and won't produce an error at all.

Yet again, selene saves us.

error[incorrect_standard_library_use]: standard library function `pairs` requires 1 parameters, 3 passed

   ┌── fail.lua:1:16 ───
   │
 1 │ for _, shop in pairs(GoldShop, ItemShop, MedicineShop) do
   │                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   │

This clues the developer into writing the code they meant to write:

for _, shop in pairs({ GoldShop, ItemShop, MedicineShop }) do

Because idiomatic Lua

While it's nice to write code however you want to, issues can arise when you are working with other people, or plan on open sourcing your work for others to contribute to. It's best for everyone involved if they stuck to the same way of writing Lua.

Consider this contrived example:

call(1 / 0)

The person who wrote this code might have known that 1 / 0 evaluates to math.huge. However, anyone working on that code will likely see it and spend some time figuring out why they wrote the code that way.

If the developer was using selene, this code would be denied:

warning[divide_by_zero]: dividing by zero is not allowed, use math.huge instead

   ┌── fail.lua:1:6 ───
   │
 1 │ call(1 / 0)
   │      ^^^^^
   │

Furthermore, selene is meant to be easy for developers to add their own lints to. You could create your own lints for your team to prevent behavior that is non-idiomatic to the codebase. For example, let's say you're working on a Roblox codebase, and you don't want your developers using the data storage methods directly. You could create your own lint so that this code:

local DataStoreService = game:GetService("DataStoreService")

...creates a warning, discouraging its use. For more information on how to create your own lints, check out the contribution guide.

Luacheck Comparison

selene vs. luacheck

selene is not the first Lua linter. The main inspiration behind selene is luacheck. However, the two have very little in common besides inception.

selene is actively maintained, while at the time of writing luacheck's last commit was in October 2018.
selene is written in Rust, while luacheck is written in Lua. In practice, this means that selene is much faster than luacheck while also being able to easily take advantage of features luacheck cannot because of the difficulty of using dependencies in Lua.
selene is multithreaded, again leading to significantly better performance.
selene has rich output, while luacheck has basic output.

selene:

error[suspicious_reverse_loop]: this loop will only ever run once at most

   ┌── fail.lua:1:9 ───
   │
 1 │ for _ = #x, 1 do
   │         ^^^^^
   │
   = help: try adding `, -1` after `1`

luacheck:

Checking fail.lua                                 2 warnings

    fail.lua:1:1: numeric for loop goes from #(expr) down to 1 but loop step is not negative

selene uses TOML files for configuration, while luacheck uses .luacheckrc, which runs Lua.
selene allows for standard library configuration such as argument types, argument counts, etc, while luacheck only allows knowing that fields exist and can be written to. In practice, this means that selene catches:

for _, shop in pairs(GoldShop, ItemShop, MedicineShop) do

math.pi()

...while luacheck does not.

selene has English names for lints instead of arbitrary numbers. In luacheck, you ignore "211", while in selene you ignore "unbalanced_assignments".
selene has distinctions for "deny" and "warn", while every luacheck lint is the same.
selene has a much simpler codebase, and is much easier to add your own lints to.
selene has optional support and large focus specifically for Roblox development.
selene will only show you files that lint, luacheck only does this with the -q option (quiet).
selene filters specific lints and applies over code rather than lines, luacheck does not.
selene has significantly more lints.

This is not to say selene is objectively better than luacheck, at least not yet.

luacheck has lints for long lines and whitespace issues, selene does not as it is unclear whether style issues like these are fit for a linter or better under the scope of a Lua beautifier.
luacheck officially supports versions past Lua 5.1, selene does not yet as there is not much demand.
luacheck supports the following lints that selene does not yet:
- Unreachable code
- Unused labels (selene does not officially support Lua 5.2 yet)
- Detecting variables that are only ever mutated, but not read
- Using uninitialized variables

Migration

luacheck does not require much configuration to begin with, so migration should be easy.

You can configure what lints are allowed in the configuration.
Do you have a custom standard library (custom globals, functions, etc)? Read the standard library guide.
- Are you a Roblox developer using something like luacheck-roblox? A featureful standard library for Roblox is generated with every commit on GitHub. TODO: Have a flag in the selene CLI to generate a Roblox standard library a la generate-roblox-std? Should generate-roblox-std be uploaded to crates.io?

Command Line Interface

selene is mostly intended for use as a command line tool.

In this section, you will learn how to use selene in this manner.

Installation

selene is written in Rust, and the recommended installation method is through the Cargo package manager.

To use Cargo, you must first install Rust. rustup.rs is a tool that makes this very easy.

Once you have Rust installed, use either command:

If you want the most stable version of selene

cargo install selene

If you want the most up to date version of selene

cargo install --branch main --git https://github.com/Kampfkarren/selene selene

Disabling Roblox features

selene is built with Roblox specific lints by default. If you don't want these, then pass --no-default-features to the cargo install command.

CLI Usage

If you want to get a quick understanding of the interface, simply type selene --help.

USAGE:
    selene [FLAGS] [OPTIONS] <files>...
    selene <SUBCOMMAND>

FLAGS:
        --allow-warnings    Pass when only warnings occur
        --no-exclude        Ignore excludes defined in config
    -h, --help              Prints help information
    -n, --no-summary        Suppress summary information
    -q, --quiet             Display only the necessary information. Equivalent to --display-style="quiet"
    -V, --version           Prints version information

OPTIONS:
        --color <color>                     [default: auto]  [possible values: Always, Auto, Never]
        --config <config>                  A toml file to configure the behavior of selene [default: selene.toml]
        --display-style <display-style>    Sets the display method [possible values: Json, Json2, Rich, Quiet]
        --num-threads <num-threads>        Number of threads to run on, default to the numbers of logical cores on your
                                           system [default: your system's cores]
        --pattern <pattern>                A glob to match files with to check

ARGS:
    <files>...

SUBCOMMANDS:
    generate-roblox-std
    help                   Prints this message or the help of the given subcommand(s)
    update-roblox-std
    upgrade-std

Basic usage

All unnamed inputs you give to selene will be treated as files to check for.

If you want to check a folder of files: selene files

If you just want to check one file: selene code.lua

If you want to check multiple files/folders: selene file1 file2 file3 ...

If you want to pipe code to selene using stdin: cat code.lua | selene -

Advanced options

-q

--quiet

Instead of the rich format, only necessary information will be displayed.

~# selene code.lua
warning[divide_by_zero]: dividing by zero is not allowed, use math.huge instead

   ┌── code.lua:1:6 ───
   │
 1 │ call(1 / 0)
   │      ^^^^^
   │

Results:
0 errors
1 warnings
0 parse errors

~# selene code.lua -q
code.lua:1:6: warning[divide_by_zero]: dividing by zero is not allowed, use math.huge instead

Results:
0 errors
1 warnings
0 parse errors

--num-threads num-threads

Specifies the number of threads for selene to use. Defaults to however many cores your CPU has. If you type selene --help, you can see this number because it will show as the default for you.

--pattern pattern

A glob to match what files selene should check for. For example, if you only wanted to check files that end with .spec.lua, you would input --pattern **/*.spec.lua. Defaults to **/*.lua, meaning "any lua file", or **/*.lua and **/*.luau with the roblox feature flag, meaning "any lua/luau file".

Usage

In this section, you will learn how to interact with selene from your code and how to fit it to your liking.

Configuration

selene is meant to be easily configurable. You can specify configurations for the entire project as well as for individual lints.

Configuration files are placed in the directory you are running selene in and are named selene.toml. As the name suggests, the configurations use the Tom's Obvious, Minimal Language (TOML) format. It is recommended you quickly brush up on the syntax, though it is very easy.

Changing the severity of lints

You can change the severity of lints by entering the following into selene.toml:

[lints]
lint_1 = "severity"
lint_2 = "severity"
...

Where "severity" is one of the following:

"allow" - Don't check for this lint
"warn" - Warn for this lint
"deny" - Error for this lint

Note that "deny" and "warn" are effectively the same, only warn will give orange text while error gives red text, and they both have different counters.

Configuring specific lints

You can configure specific lints by entering the following into selene.toml:

[config]
lint1 = ...
lint2 = ...
...

Where the value is whatever the special configuration of that lint is. You can learn these on the lints specific page in the list of lints. For example, if we wanted to allow empty if branches if the contents contain comments, then we would write:

[config]
empty_if = { comments_count = true }

Setting the standard library

Many lints use standard libraries for either verifying their correct usage or for knowing that variables exist where they otherwise wouldn't.

By default, selene uses Lua 5.1, though if we wanted to use the Lua 5.2 standard library, we would write:

std = "lua52"

...at the top of selene.toml. You can learn more about the standard library format on the standard library guide. The standard library given can either be one of the builtin ones (currently only lua51 and lua52) or the filename of a standard library file in this format. For example, if we had a file named special.toml, we would write:

std = "special"

Chaining the standard library

We can chain together multiple standard libraries by simply using a plus sign (+) in between the names.

For example, if we had game.toml and engine.toml standard libraries, we could chain them together like so:

std = "game+engine"

Excluding files from being linted

It is possible to exclude files from being linted using the exclude option:

exclude = ["external/*", "*.spec.lua"]

Filtering

Lints can be toggled on and off in the middle of code when necessary through the use of special comments.

Allowing/denying lints for a piece of code

Suppose we have the following code:

local something = 1

selene will correctly attribute this as an unused variable:

warning[unused_variable]: something is assigned a value, but never used

   ┌── code.lua:1:7 ───
   │
 1 │ local something = 1
   │       ^^^^^^^^^
   │

However, perhaps we as the programmer have some reason for leaving this unused (and not renaming it to _something). This would be where inline lint filtering comes into play. In this case, we would simply write:

-- selene: allow(unused_variable)
local something = 1

This also works with settings other than allow--you can warn or deny lints in the same fashion. For example, you can have a project with the following selene.toml configuration:

[lints]
unused_variable = "allow" # I'm fine with unused variables in code

...and have this in a separate file:

-- I'm usually okay with unused variables, but not this one
-- selene: deny(unused_variable)
local something = 1

This is applied to the entire piece of code its near, not just the next line. For example:

-- selene: allow(unused_variable)
do
    local foo = 1
    local bar = 2
end

...will silence the unused variable warning for both foo and bar.

Allowing/denying lints for an entire file

If you want to allow/deny a lint for an entire file, you can do this by attaching the following code to the beginning:

--# selene: allow(lint_name)

The # tells selene that you want to apply these globally.

These must be before any code, otherwise selene will deny it. For example, the following code:

local x = 1
--# selene: allow(unused_variable)

...will cause selene to error:

warning[unused_variable]: x is assigned a value, but never used
  ┌─ -:1:7
  │
1 │ local x = 1
  │       ^

error[invalid_lint_filter]: global filters must come before any code
  ┌─ -:1:1
  │
1 │ local x = 1
  │ ----------- global filter must be before this
2 │ --# selene: allow(unused_variable)

Combining multiple lints

You can filter multiple lints in two ways:

-- selene: allow(lint_one)
-- selene: allow(lint_two)

-- or...

-- selene: allow(lint_one, lint_two)

Standard Library Format

selene provides a robust standard library format to allow for use with environments other than vanilla Lua. Standard libraries are defined in the form of YAML files.

Examples

For examples of the standard library format, see:

lua51.yml - The default standard library for Lua 5.1
lua52.yml - A standard library for Lua 5.2's additions and removals. Reference this if your standard library is based off another (it most likely is).
roblox.yml - A standard library for Roblox that incorporates all the advanced features of the format. If you are a Roblox developer, don't use this as anything other than reference--an up to date version of this library is automatically generated.

base

Used for specifying what standard library to be based off of. This supports both builtin libraries (lua51, lua52, lua53, lua54, roblox), as well as any standard libraries that can be found in the current directory.

--- # This begins a YAML file
base: lua51 # We will be extending off of Lua 5.1.

lua_versions

Used for specifying the versions of Lua you support for the purpose of supporting the syntax of those dialects. If empty, will default to 5.1.

Supports the following options:

lua51 - Lua 5.1
lua52 - Lua 5.2
lua53 - Lua 5.3
lua54 - Lua 5.4
luau - Luau
luajit - LuaJIT

Usually you only need to specify one--for example, lua54 will give Lua 5.4 syntax and all versions prior. That means that if you specify it, it will look something like:

lua_versions:
- luajit

If you are extending off a library that specifies it (like lua51, etc) then you do not need this. If you specify it while overriding a library, it will override it.

globals

This is where the magic happens. The globals field is a dictionary where the keys are the globals you want to define. The value you give tells selene what the value can be, do, and provide.

If your standard library is based off another, overriding something defined there will use your implementation over the original.

Any

---
globals:
  foo:
    any: true

This specifies that the field can be used in any possible way, meaning that foo.x, foo:y(), etc will all validate.

Functions

---
globals:
  tonumber:
    args:
      - type: any
      - type: number
        required: false

A field is a function if it contains an args and/or method field.

If method is specified as true and the function is inside a table, then it will require the function be called in the form of Table:FunctionName(), instead of Table.FunctionName().

args is an array of arguments, in order of how they're used in the function. An argument is in the form of:

required?: false | true | string;
type: "any" | "bool" | "function" | "nil"
    | "number" | "string" | "table" | "..."
    | string[] | { "display": string }

"required"

true - The default, this argument is required.
false - This argument is optional.
A string - This argument is required, and not using it will give this as the reason why.

"observes"

This field is used for allowing smarter introspection of how the argument given is used.

"read-write" - The default. This argument is potentially both written to and read from.
"read" - This argument is only read from. Currently unused.
"write" - This argument is only written to. Used by unused_variable to assist in detecting a variable only being written to, even if passed into a function.

Example:

 table.insert:
  args:
    - type: table
      observes: write # This way, `table.insert(x, 1)` doesn't count as a read to `x`
    - type: any
    - required: false
      type: any

"must_use"

This field is used for checking if the return value of a function is used.

false - The default. The return value of this function does not need to be used.
true - The return value of this function must be used.

Example:

  tostring:
    args:
      - type: any
    must_use: true

Argument types

"any" - Allows any value.
"bool", "function", "nil", "number", "string", "table" - Expects a value of the respective type.
"..." - Allows any number of variables after this one. If required is true (it is by default), then this will lint if no additional arguments are given. It is incorrect to have this in the middle.
Constant list of strings - Will check if the value provided is one of the strings in the list. For example, collectgarbage only takes one of a few exact string arguments--doing collectgarbage("count") will work, but collectgarbage("whoops") won't.
{ "display": string } - Used when no constant could possibly be correct. If a constant is used, selene will tell the user that an argument of the type (display) is required. For an example, the Roblox method Color3.toHSV expects a Color3 object--no constant inside it could be correct, so this is defined as:

---
globals:
  Color3.toHSV:
    args:
      - type:
          display: Color3

Properties

---
globals:
  _VERSION:
    property: read-only

Specifies that a property exists. For example, _VERSION is available as a global and doesn't have any fields of its own, so it is just defined as a property.

The same goes for _G, which is defined as:

_G:
  property: new-fields

The value of property tells selene how it can be mutated and used:

"read-only" - New fields cannot be added or set, and the variable itself cannot be redefined.
"new-fields" - New fields can be added and set, but variable itself cannot be redefined. In the case of _G, it means that _G = "foo" is linted against.
"override-fields" - New fields can't be added, but entire variable can be overridden. In the case of Roblox's Instance.Name, it means we can do Instance.Name = "Hello", but not Instance.Name.Call().
"full-write" - New fields can be added and entire variable can be overridden.

Struct

---
globals:
  game:
    struct: DataModel

Specifies that the field is an instance of a struct. The value is the name of the struct.

Tables

---
globals:
  math.huge:
    property: read-only
  math.pi:
    property: read-only

A field is understood as a table if it has fields of its own. Notice that math is not defined anywhere, but its fields are. This will create an implicit math with the property writability of read-only.

Deprecated

Any field or arg can have a deprecation notice added to it, which will then be read by the deprecated lint.

---
globals:
  table.getn:
    args:
      - type: table
      - type: number
    deprecated:
      message: "`table.getn` has been superseded by #."
      replace:
        - "#%1"

The deprecated field consists of two subfields.

message is required, and is a human readable explanation of what the deprecation is, and potentially why.

replace is an optional array of replacements. The most relevant replacement is suggested to the user. If used with a function, then every parameter of the function will be provided.

For instance, since table.getn's top replacement is #%1:

table.getn(x) will suggest #x
table.getn() will not suggest anything, as there is no relevant suggestion

You can also use %... to list every argument, separated by commas.

The following:

---
globals:
  call:
    deprecated:
      message: "call will be removed in the next version"
      replace:
        - "newcall(%...)"
    args:
      - type: "..."
        required: false

...will suggest newcall(1, 2, 3) for call(1, 2, 3), and newcall() for call().

You can also use %% to write a raw %.

Removed

---
globals:
  getfenv:
    removed: true

Used when your standard library is based off another, and your library removes something from the original.

Structs

Structs are used in places such as Roblox Instances. Every Instance in Roblox, for example, declares a :GetChildren() method. We don't want to have to define this everywhere an Instance is declared globally, so instead we just define it once in a struct.

Structs are defined as fields of structs. Any fields they have will be used for instances of that struct. For example, the Roblox standard library has the struct:

---
structs:
  Event:
    Connect:
      method: true
      args:
        - type: function

From there, it can define:

globals:
  workspace.Changed:
    struct: Event

...and selene will know that workspace.Changed:Connect(callback) is valid, but workspace.Changed:RandomNameHere() is not.

Wildcards

Fields can specify requirements if a field is referenced that is not explicitly named. For example, in Roblox, instances can have arbitrary fields of other instances (workspace.Baseplate indexes an instance named Baseplate inside workspace, but Baseplate is nowhere in the Roblox API).

We can specify this behavior by using the special "*" field.

workspace.*:
  struct: Instance

This will tell selene "any field accessed from workspace that doesn't exist must be an Instance struct".

Wildcards can even be used in succession. For example, consider the following:

script.Name:
  property: override-fields

script.*.*:
  property: full-write

Ignoring the wildcard, so far this means:

script.Name = "Hello" will work.
script = nil will not work, because the writability of script is not specified.
script.Name.UhOh will not work, because script.Name does not have fields.

However, with the wildcard, this adds extra meaning:

script.Foo = 3 will not work, because the writability of script.* is not specified.
script.Foo.Bar = 3 will work, because script.*.* has full writability.
script.Foo.Bar.Baz = 3 will work for the same reason as above.

Internal properties

There are some properties that exist in standard library YAMLs that exist specifically for internal purposes. This is merely a reference, but these are not guaranteed to be stable.

name

This specifies the name of the standard library. This is used internally for cases such as only giving Roblox lints if the standard library is named "roblox".

last_updated

A timestamp of when the standard library was last updated. This is used by the Roblox standard library generator to update when it gets too old.

last_selene_version

A timestamp of the last selene version that generated this standard library. This is used by the Roblox standard library generator to update when it gets too old.

roblox_classes

A map of every Roblox class and their properties, for roblox_incorrect_roact_usage.

Roblox Guide

selene is built with Roblox development in mind, and has special features for Roblox developers.

If you try to run selene on a Roblox codebase, you'll get a bunch of errors saying things such as "game is not defined". This is because these are Roblox specific globals that selene does not know about. You'll need to install the Roblox standard library in order to fix these issues, as well as get Roblox specific lints.

Installation

Thankfully, this process is very simple. All you need to do is edit your selene.toml (or create one) and add the following:

std = "roblox"

The next time you run selene, or if you use the Visual Studio Code extension and start typing Lua code, a Roblox standard library will be automatically generated and used. This is an automatic process that occurs whenever you don't have a cached standard library file and your selene.toml has std = "roblox".

Updating definitions

The Roblox standard library file is updated automatically every 6 hours. If you need an update faster than that, you can run selene update-roblox-std manually.

TestEZ Support

Roblox has provided an open source testing utility called TestEZ, which allows you to write unit tests for your code. Writing unit tests is good practice, but selene will get angry at you if you don't include a testez.yml file and set the standard library to the following:

std = "roblox+testez"

But first you'll need to create a testez.yml file, which you can do so with this template.

Pinned standard library

There may be cases where you would rather not have selene automatically update the Roblox standard library, such as if speed is critically important and you want to limit potential internet access (generating the standard library requires an active internet connection).

selene supports "pinning" the standard library to a specific version.

Add the following to your selene.toml configuration:

# `floating` by default, meaning it is stored in a cache folder on your system
roblox-std-source = "pinned"

This will generate the standard library file into roblox.yml where it is run.

You can also create a roblox.yml file manually with selene generate-roblox-std.

Contributing

selene is written in Rust, so knowledge of the ecosystem is expected.

selene uses Full Moon to parse the Lua code losslessly, meaning whitespace and comments are preserved. You can read the full documentation for full-moon on its docs.rs page.

TODO: Upload selene-lib on crates.io and link the docs.rs page for that as well as throughout the rest of this article.

Writing a lint

In selene, lints are created in isolated modules. To start, create a file in selene-lib/src/lints with the name of your lint. In this example, we're going to call the lint cool_lint.rs.

Let's now understand what a lint consists of. selene takes lints in the form of structs that implement the Lint trait. The Lint trait expects:

A Config associated type that defines what the configuration format is expected to be. Whatever you pass must be deserializable.
An Error associated type that implements std::error::Error. This is used if configurations can be invalid (such as a parameter only being a number within a range). Most of the time, configurations cannot be invalid (other than deserializing errors, which are handled by selene), and so you can set this to std::convert::Infallible.
A SEVERITY constant which is either Severity::Error or Severity::Warning. Use Error if the code is positively impossible to be correct.
A LINT_TYPE constant which is either Complexity, Correctness, Performance, or Style. So far not used for anything.
A new function with the signature fn new(config: Self::Config) -> Result<Self, Self::Error>. With the selene CLI, this is called once.
A pass function with the signature fn pass(&self, ast: &full_moon::ast::Ast, context: &Context, ast_context: &AstContext) -> Vec<Diagnostic>. The ast argument is the full-moon representation of the code. The context argument provides optional additional information, such as the standard library being used. The ast_context argument provides context specific to that AST, such as its scopes. Any Diagnostic structs returned here are displayed to the user.

For our purposes, we're going to write:

use super::*;
use std::convert::Infallible;

struct CoolLint;

impl Lint for CoolLint {
    type Config = ();
    type Error = Infallible;

    const SEVERITY: Severity = Severity::Warning;
    const LINT_TYPE: LintType = LintType::Style;

    fn new(_: Self::Config) -> Result<Self, Self::Error> {
        Ok(CoolLint)
    }

    fn pass(&self, ast: &Ast, _: &Context, _: &AstContext) -> Vec<Diagnostic> {
        unimplemented!()
    }
}

The implementation of pass is completely up to you, but there are a few common patterns.

Creating a visitor over the ast provided and creating diagnostics based off of that. See divide_by_zero and suspicious_reverse_loop for straight forward examples.
Using the ScopeManager struct to lint based off of usage of variables and references. See shadowing and global_usage.

Getting selene to recognize the new lint

Now that we have our lint, we have to make sure selene actually knows to use it. There are two places you need to update.

In selene-lib/src/lib.rs, search for use_lints!. You will see something such as:

use_lints! {
    almost_swapped: lints::almost_swapped::AlmostSwappedLint,
    divide_by_zero: lints::divide_by_zero::DivideByZeroLint,
    empty_if: lints::empty_if::EmptyIfLint,
    ...
}

Put your lint in this list (alphabetical order) as the following format:

lint_name: lints::module_name::LintObject,

For us, this would be:

cool_lint: lints::cool_lint::CoolLint,

Next, in selene-lib/src/lints.rs, search for pub mod, and you will see:

pub mod almost_swapped;
pub mod divide_by_zero;
pub mod empty_if;
...

Put your module name in this list, also in alphabetical order.

pub mod almost_swapped;
pub mod cool_lint;
pub mod divide_by_zero;
pub mod empty_if;
...

And we're done! You should be able to cargo build --bin selene and be able to use your new lint.

Writing tests

The selene codebase uses tests extensively for lints. It means we never have to actually build the CLI tool in order to test, and we can make sure we don't have any regressions. Testing is required if you want to submit your lint to the selene codebase.

To write a simple test, create a folder in selene-lib/tests with the name of your lint. Then, create as many .lua files as you want to test. These should contain both cases that do and do not lint. For our cases, we're going to assume our test is called cool_lint.lua.

Then, in your lint module, add at the bottom:

#[cfg(test)]
mod tests {
    use super::{super::test_util::test_lint, *};

    #[test]
    fn test_cool_lint() {
        test_lint(
            CoolLint::new(()).unwrap(),
            "cool_lint",
            "cool_lint",
        );
    }
}

Let's discuss what this code means, assuming you're familiar with the way tests are written and performed in Rust.

The test_lint function is the easiest way to test that a lint works. It'll search the source code we made before, run selene on it (only your lint), and check its results with the existing [filename].stderr file, or create one if it does not yet exist.

The first argument is the lint object to use. CoolLint::new(()) just means "create CoolLint with a configuration of ()". If your lint specifies a configuration, this will instead be something such as CoolLintConfig::default() or whatever you're specifically testing.

The .unwrap() is just because CoolLint::new returns a Result. If you want to test configuration errors, you can avoid test_lint altogether and just test CoolLint::new(...).is_err() directly.

The first "cool_lint" is the name of the folder we created. The second "cool_lint" is the name of the Lua file we created.

Now, just run cargo test, and a .stderr file will be automatically generated! You can manipulate it however you see fit as well as modifying your lint, and so long as the file is there, selene will make sure that its accurate.

Optionally, you can add a .std.toml with the same name as the test next to the lua file, where you can specify a custom standard library to use. If you do not, the Lua 5.1 standard library will be used.

Documenting it

This step is only if you are contributing to the selene codebase, and not just writing personal lints (though I'm sure your other programmers would love if you did this).

To document a new lint, edit docs/src/SUMMARY.md, and add your lint to the table of contents along the rest. As with everything else, make sure it's in alphabetical order.

Then, edit the markdown file it creates (if you have mdbook serve on, it'll create it for you), and write it in this format:

# lint_name
## What it does
Explain what your lint does, simply.

## Why this is bad
Explain why a user would want to lint this.

## Configuration
Specify any configuration if it exists.

## Example
```lua
-- Bad code here
```

...should be written as...

```lua
-- Good code here
```

## Remarks
If there's anything else a user should know when using this lint, write it here.

This isn't a strict format, and you can mess with it as appropriate. For example, standard_library does not have a "Why this is bad" section as not only is it a very encompassing lint, but it should be fairly obvious. Many lints don't specify a "...should be written as..." as it is either something with various potential fixes (such as global_usage) or because the "good code" is just removing parts entirely (such as unbalanced_assignments).

Lints

The following is the list of lints that selene will check for in your code.

selene Documentation