elint 0.0.3

Erlang code linter
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

# Rules

Each lint lives under `rules/<name>/` and `src/rules/<name>.rs`.
`<name>` is a `lower_snake_case` atom. Do not use hyphens.

Lint rules assume Erlang/OTP 29.0 or later. A rule may rely on syntax
introduced in OTP 29.0 without documenting a version restriction.

## Layout

| Path | Role |
|---|---|
| `rules/<name>/rule.md` | Description of the rule |
| `rules/<name>/ng.erl` | Fixture that must produce one or more findings for `<name>` |
| `rules/<name>/ok.erl` | Fixture that must produce zero findings for `<name>` |
| `src/rules/<name>.rs` | Implementation |
| `src/rules.rs` | `RULES` registration |

`ng` / `ok` name the expected finding counts (at least one / zero), not whether
the Erlang code is good or bad. `-module` must match the file stem (`ng` /
`ok`). Fixtures are linted one file at a time, so duplicate module names across
rules are fine.

## `rule.md` template

```markdown
# `<name>`

One-sentence summary.

## What it does

The exact conditions under which the rule reports a finding, including nearby
conditions that are not reported.

## Why restrict this?

Why the construct is generally discouraged, without claiming that every use is
incorrect.

## Example

An example that is reported (self-contained for `elint explain`).

Use instead:

An example of the preferred alternative.

## Known limitations

Acceptable uses that are still reported and therefore require suppression.
```

Omit `Known limitations` when the rule has none.

## Adding a rule

1. Create `rules/<name>/rule.md` from the template.
2. Implement `src/rules/<name>.rs` and register it in `RULES`.
3. Add `ng.erl` and `ok.erl`.
4. Check with the linter:

```text
elint --lint <name> rules/<name>/ng.erl
elint --lint <name> rules/<name>/ok.erl
```

`ng.erl` must produce findings and a non-zero exit.
`ok.erl` must produce no findings and a zero exit.

`elint explain <name>` prints `rules/<name>/rule.md`.

Project-wide documents (the `-elint_expect` notation, diagnostics, the
preprocessing pipeline) are available with `elint doc <name>`; run `elint doc`
for the list.