Creating a custom linter can be a great way to enforce coding standards and detect code smells. In this tutorial, we'll use Sylver's, a source code query engine to build a custom Golang linter in just a few lines of code.
Sylver's main interface is a REPL console, in which we can load the source code of our project to query it using a SQL-like query language called SYLQ. Once we'll have authored SYLQ queries expressing our linting rules, we'll be able to save them into a ruleset that can be run like a traditional linter.
Installation
If sylver --version doesn't output a version number >= 0.1.8, go to https://sylver.dev to download a fresh copy of the software.
Starting the REPL
Starting the REPL is as simple as invoking the following command at the root of your project:
sylver query --files="**/*.go" --spec=https:
The REPL can be exited by pressing Ctrl+C or typing :quit at the prompt.
We can now execute SYLQ queries by typing the code of the query, followed by a ;.
For instance: to retrieve all the struct declarations:
match StructType;
The results of the query will be formatted as follow:
[...]
$359 [StructType association.go:323:17-327:1]
$360 [StructType schema/index.go:10:12-18:1]
$361 [StructType schema/index.go:20:18-27:1]
$362 [StructType tests/group_by_test.go:70:12-73:2]
$363 [StructType schema/check.go:11:12-15:1]
The code of a given struct declaration can be displayed by typing :print followed by the node alias (for instance: :print $362). The parse tree can be displayed using the :print_ast command (for instance: :print_ast $362).
Rule1: detect struct declarations with too many fields
For our first rule, we'd like to flag struct declarations that have more than 10 fields.
The first step is to get familiar with the tree structure of struct declarations, so let's print a StructType along with its ast:
λ> :print $362
struct {
Name string
Total int64
}
λ> :print_ast $362
StructType {
. ● fields: List<FieldSpec> {
. . FieldSpec {
. . . ● names: List<Identifier> {
. . . . Identifier { Name }
. . . }
. . . ● type: TypeIdent {
. . . . ● name: Identifier { string }
. . . }
. . }
. . FieldSpec {
. . . ● names: List<Identifier> {
. . . . Identifier { Total }
. . . }
. . . ● type: TypeIdent {
. . . . ● name: Identifier { int64 }
. . . }
. . }
. }
}
The fields of the struct are stored in a field aptly named fields that holds a list of FieldSpec nodes. This means that the nodes violating our rule are all the StructType nodes for which the fields list has a length higher than 10.
This can be easily expressed in SYLQ:
match StructType s when s.fields.length > 10;
Rule2: suggest the usage of assignment operators
For our second linting rule, we'd like to identify assignments that could be simplified by using an assignment operator (like +=) such as:
x = x + 1
Let's explore the parse tree of a simple assignment:
λ> :print $5750
err = nil
λ> :print_ast $5750
AssignStmt {
. ● lhs: List<Expr> {
. . Identifier { err }
. }
. ● rhs: List<Expr> {
. . NilLit { nil }
. }
}
So we want to retrieve the AssignStmt nodes for which the rhs field contains a Binop that has lhs as its left operand. Also, the left-hand side of the assignment must contain a single expression. This can be written as:
match AssignStmt a when
a.lhs.length == 1
&& a.rhs[0] is { BinOp b when b.left.text == a.lhs[0].text };
Rule3: incorrect usage of the make builtin function
For our last linting rule, we want to identify incorrect usage of the make function, where the length is higher than the capacity, as this probably indicates a programming error.
Here is the parse tree of a call to make:
λ> :print $16991
make([]string, 0, len(value))
λ> :print_ast $16991
CallExpr {
. ● fun: Identifier { make }
. ● args: List<GoNode> {
. . SliceType {
. . . ● elemsType: TypeIdent {
. . . . ● name: Identifier { string }
. . . }
. . }
. . IntLit { 0 }
. . CallExpr {
. . . ● fun: Identifier { len }
. . . ● args: List<GoNode> {
. . . . Identifier { value }
. . . }
. . }
. }
}
Here are the conditions that violating nodes will meet:
- The test of
fun is make
- The args list contains 3 elements
- The last two arguments are int literals
- The third argument (capacity) is smaller than the second (length)
Let's encode this in SYLQ:
match CallExpr c when
c.fun.text == 'make'
&& c.args.length == 3
&& c.args[1] is IntLit
&& c.args[2] is IntLit
&& c.args[2].text.to_int() < c.args[1].text.to_int();
Creating the ruleset
The following ruleset uses our linting rules:
id: customLinter
language: "https://github.com/sylver-dev/golang.git#golang.yaml"
rules:
- id: largeStruct
message: struct has many fields
category: style
query: match StructType s when s.fields.length > 10
- id: assignOp
message: assignment should use an assignment operator
category: style
note: According to our style guide, assignment operators should be preferred.
query: >
match AssignStmt a when
a.lhs.length == 1
&& a.rhs[0] is { BinOp b when b.left.text == a.lhs[0].text }
- id: makeCapacityErr
message: capacity should be higher than length
category: bug
query: >
match CallExpr c when
c.fun.text == 'make'
&& c.args.length == 3
&& c.args[1] is IntLit
&& c.args[2] is IntLit
&& c.args[2].text.to_int() < c.args[1].text.to_int()
Assuming that it is stored in a file called custom_linter.yaml at the root of our project, we can run it with the following command:
sylver ruleset run --files="**/*.go" --rulesets=custom_linter.yaml
