2021-10-24 10:56:37 +03:00
|
|
|
# statix
|
2021-09-11 18:48:09 +03:00
|
|
|
|
2021-10-24 10:56:37 +03:00
|
|
|
> Lints and suggestions for the Nix programming language.
|
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
`statix` highlights antipatterns in Nix code. `statix --fix`
|
2021-10-24 10:56:37 +03:00
|
|
|
can fix several such occurrences.
|
2021-09-11 18:48:09 +03:00
|
|
|
|
2021-10-02 08:22:22 +03:00
|
|
|
For the time-being, `statix` works only with ASTs
|
2021-09-11 18:48:09 +03:00
|
|
|
produced by the `rnix-parser` crate and does not evaluate
|
2021-10-02 08:22:22 +03:00
|
|
|
any nix code (imports, attr sets etc.).
|
2021-09-11 18:48:09 +03:00
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
## Examples
|
|
|
|
|
|
|
|
```shell
|
|
|
|
$ statix tests/c.nix
|
|
|
|
[W04] Warning: Assignment instead of inherit from
|
|
|
|
╭─[tests/c.nix:2:3]
|
|
|
|
│
|
|
|
|
2 │ mtl = pkgs.haskellPackages.mtl;
|
|
|
|
· ───────────────┬───────────────
|
|
|
|
· ╰───────────────── This assignment is better written with inherit
|
|
|
|
───╯
|
|
|
|
|
|
|
|
$ statix --fix --dry-run tests/c.nix
|
|
|
|
--- tests/c.nix
|
|
|
|
+++ tests/c.nix [fixed]
|
|
|
|
@@ -1,6 +1,6 @@
|
|
|
|
let
|
|
|
|
- mtl = pkgs.haskellPackages.mtl;
|
|
|
|
+ inherit (pkgs.haskellPackages) mtl;
|
|
|
|
in
|
|
|
|
null
|
|
|
|
```
|
|
|
|
|
2021-10-24 10:56:37 +03:00
|
|
|
## Installation
|
|
|
|
|
|
|
|
`statix` is available via a nix flake:
|
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
```shell
|
|
|
|
# build from source
|
2021-10-24 10:56:37 +03:00
|
|
|
nix build git+https://git.peppe.rs/languages/statix
|
|
|
|
./result/bin/statix --help
|
2021-10-24 15:25:57 +03:00
|
|
|
|
|
|
|
# statix also provides a flake app
|
|
|
|
nix run git+https://git.peppe.rs/languages/statix -- --help
|
|
|
|
|
|
|
|
# save time on builds using cachix
|
|
|
|
cachix use statix
|
2021-10-24 10:56:37 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
Basic usage is as simple as:
|
2021-10-24 10:56:37 +03:00
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
```shell
|
|
|
|
# recursively finds nix files and raises lints
|
|
|
|
statix /path/to/dir
|
2021-10-24 10:56:37 +03:00
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
# ignore generated files, such as Cargo.nix
|
|
|
|
statix /path/to/dir -i '*Cargo.nix'
|
2021-10-24 10:56:37 +03:00
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
# see `statix -h` for a full list of options
|
|
|
|
```
|
2021-10-24 10:56:37 +03:00
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
Certain lints have suggestions. Apply suggestions back to
|
|
|
|
the source with:
|
2021-10-24 10:56:37 +03:00
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
```shell
|
|
|
|
statix --fix /path/to/file
|
2021-10-24 10:56:37 +03:00
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
# show diff, do not write to file
|
|
|
|
statix --fix --dry-run /path/to/file
|
|
|
|
```
|
|
|
|
|
|
|
|
`statix` supports a variety of output formats; standard,
|
|
|
|
json and errfmt:
|
|
|
|
|
|
|
|
```shell
|
|
|
|
statix /path/to/dir -o json
|
|
|
|
statix /path/to/dir -o errfmt # singleline, easy to integrate with vim
|
2021-10-24 10:56:37 +03:00
|
|
|
```
|
|
|
|
|
2021-09-11 18:48:09 +03:00
|
|
|
## Architecture
|
|
|
|
|
2021-10-02 08:22:22 +03:00
|
|
|
`statix` has the following components:
|
2021-09-11 18:48:09 +03:00
|
|
|
|
|
|
|
- `bin`: the CLI/entrypoint
|
|
|
|
- `lib`: library of lints and utilities to define these
|
|
|
|
lints
|
2021-10-24 15:25:57 +03:00
|
|
|
- `vfs`: virtual filesystem
|
2021-09-11 18:48:09 +03:00
|
|
|
- `macros`: procedural macros to help define a lint
|
|
|
|
|
|
|
|
### `bin`
|
|
|
|
|
2021-10-02 08:22:22 +03:00
|
|
|
This is the main point of interaction between `statix`
|
2021-09-11 18:48:09 +03:00
|
|
|
and the end user. It's output is human-readable and should
|
|
|
|
also support JSON/errorfmt outputs for external tools to
|
|
|
|
use.
|
|
|
|
|
|
|
|
### `lib`
|
|
|
|
|
|
|
|
A library of AST-based lints and utilities to help write
|
|
|
|
those lints. It should be easy for newcomers to write lints
|
|
|
|
without being familiar with the rest of the codebase.
|
|
|
|
|
2021-10-24 15:25:57 +03:00
|
|
|
### `vfs`
|
|
|
|
|
|
|
|
VFS is an in-memory filesystem. It provides cheap-to-copy
|
|
|
|
handles (`FileId`s) to access paths and file contents.
|
|
|
|
|
2021-09-11 18:48:09 +03:00
|
|
|
### `macros`
|
|
|
|
|
|
|
|
This crate intends to be a helper layer to declare lints and
|
|
|
|
their metadata.
|
2021-10-15 10:37:08 +03:00
|
|
|
|
|
|
|
## TODO
|
|
|
|
|
|
|
|
- Offline documentation for each lint
|
|
|
|
- Test suite for lints and suggestions
|
2021-10-24 15:25:57 +03:00
|
|
|
- Vim plugin (qf list population, apply suggestions)
|
|
|
|
- Resolve imports and scopes for better lints
|
|
|
|
- Add silent flag that exits with status
|