masmlint 0.1.1

A linter for Miden Assembly
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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# MASM Linter

A linter for [Miden Assembly](https://0xmiden.github.io/miden-docs/imported/miden-vm/src/user_docs/assembly/main.html).

## Installation

Install via cargo:

```sh
cargo install masmlint
```

## Usage

The linter supports passing a single file or a directory which is searched for MASM files. An example usage looks like this:

```sh
masmlint miden-base/crates/miden-lib/asm/kernels/transaction/
```

The full `--help` message is:

```
A linter for Miden Assembly

Usage: lint [OPTIONS] <PATH>

Arguments:
  <PATH>  Path to a MASM file to lint or a directory of MASM files. If a directory is given, it is searched recursively and lints all MASM files that are found

Options:
  -e, --exclude <EXCLUDE>  Comma-separated list of lint names to exclude. These will be excluded from the default list of lints
  -s, --select <SELECT>    Comma-separated list of lint names to run. This list is exhaustive; no other lints will be run
  -h, --help               Print help
  -V, --version            Print version
```


## Lints

### `PushImmediate`

**What it does**

Checks if _immediate_ values are pushed before instructions that could take that immediate directly.

**Why is this bad?**

It is faster to read and understand `lt.2` than `push.2 lt`.

**Example**

```
Error:   x operand is pushed before an instruction that can take an immediate value
     ,-[lib/tx.masm:227:9]
 226 |     dup neq.0 assert.err=ERR_TX_INVALID_EXPIRATION_DELTA
 227 |     dup push.EXPIRY_UPPER_LIMIT lt assert.err=ERR_TX_INVALID_EXPIRATION_DELTA
     :         ^^^^^^^^^^^^^|^^^^^^^^^^^^
     :                      `-- instruction can be rewritten to take the immediate directly
 228 |     # => [block_height_delta]
     `----
  help: use the instruction in its immediate form `lt.EXPIRY_UPPER_LIMIT`
```

### `BareAssert`

**What it does**

Checks for assertions without error messages.

**Why is this bad?**

Without error messages, failed assertions will produce a message like "assertion failed at clock cycle 123 with error code: 0". This is an unhelpful start to finding the cause of that error.

**Example**

```
Error:   x assert without error message
     ,-[lib/prologue.masm:146:18]
 145 |     # assert that sequential hash matches the precomputed kernel commitment
 146 |     movup.4 drop assert_eqw
     :                  ^^^^^|^^^^
     :                       `-- does not include an error message
 147 |     # OS => [kernel_version]
     `----
  help: use the instruction with a helpful error message, e.g.
        `assert_eqw.err=helpful error message`
```

### Potential Lints

The following is a list of ideas of potential lints but are not currently implemented:
- Check for occurences of `eq not`, which should be written as `neq`.
- Check for occurences of `if.true push.0 assert end`, which should be written as `assert` directly. There are multiple variants of this using different assert instructions.
- Warn about a large number of instructions per line. If too many instructions are in the same line, the code becomes much harder to follow.