diff options
author | Akshay <[email protected]> | 2021-10-24 13:25:57 +0100 |
---|---|---|
committer | Akshay <[email protected]> | 2021-10-24 13:39:28 +0100 |
commit | 781c42cc9ce2e6a3f1024ea1f4e3f071cc8f2dd4 (patch) | |
tree | 14f7956797530bfef15595a6743be108a7bed8e3 /readme.md | |
parent | b09f1f958423dee8c235f2eeb9c148b73936830f (diff) |
flake build with json feature, add better usage docs
Diffstat (limited to 'readme.md')
-rw-r--r-- | readme.md | 86 |
1 files changed, 63 insertions, 23 deletions
@@ -2,50 +2,82 @@ | |||
2 | 2 | ||
3 | > Lints and suggestions for the Nix programming language. | 3 | > Lints and suggestions for the Nix programming language. |
4 | 4 | ||
5 | `statix` highlights antipatterns in Nix code. `statix fix` | 5 | `statix` highlights antipatterns in Nix code. `statix --fix` |
6 | can fix several such occurrences. | 6 | can fix several such occurrences. |
7 | 7 | ||
8 | For the time-being, `statix` works only with ASTs | 8 | For the time-being, `statix` works only with ASTs |
9 | produced by the `rnix-parser` crate and does not evaluate | 9 | produced by the `rnix-parser` crate and does not evaluate |
10 | any nix code (imports, attr sets etc.). | 10 | any nix code (imports, attr sets etc.). |
11 | 11 | ||
12 | ## Examples | ||
13 | |||
14 | ```shell | ||
15 | $ statix tests/c.nix | ||
16 | [W04] Warning: Assignment instead of inherit from | ||
17 | ╭─[tests/c.nix:2:3] | ||
18 | │ | ||
19 | 2 │ mtl = pkgs.haskellPackages.mtl; | ||
20 | · ───────────────┬─────────────── | ||
21 | · ╰───────────────── This assignment is better written with inherit | ||
22 | ───╯ | ||
23 | |||
24 | $ statix --fix --dry-run tests/c.nix | ||
25 | --- tests/c.nix | ||
26 | +++ tests/c.nix [fixed] | ||
27 | @@ -1,6 +1,6 @@ | ||
28 | let | ||
29 | - mtl = pkgs.haskellPackages.mtl; | ||
30 | + inherit (pkgs.haskellPackages) mtl; | ||
31 | in | ||
32 | null | ||
33 | ``` | ||
34 | |||
12 | ## Installation | 35 | ## Installation |
13 | 36 | ||
14 | `statix` is available via a nix flake: | 37 | `statix` is available via a nix flake: |
15 | 38 | ||
16 | ``` | 39 | ```shell |
17 | nix run git+https://git.peppe.rs/languages/statix | 40 | # build from source |
18 | |||
19 | # or | ||
20 | |||
21 | nix build git+https://git.peppe.rs/languages/statix | 41 | nix build git+https://git.peppe.rs/languages/statix |
22 | ./result/bin/statix --help | 42 | ./result/bin/statix --help |
43 | |||
44 | # statix also provides a flake app | ||
45 | nix run git+https://git.peppe.rs/languages/statix -- --help | ||
46 | |||
47 | # save time on builds using cachix | ||
48 | cachix use statix | ||
23 | ``` | 49 | ``` |
24 | 50 | ||
25 | ## Usage | 51 | ## Usage |
26 | 52 | ||
27 | ``` | 53 | Basic usage is as simple as: |
28 | statix 0.1.0 | ||
29 | 54 | ||
30 | Akshay <[email protected]> | 55 | ```shell |
56 | # recursively finds nix files and raises lints | ||
57 | statix /path/to/dir | ||
31 | 58 | ||
32 | Lints and suggestions for the Nix programming language | 59 | # ignore generated files, such as Cargo.nix |
60 | statix /path/to/dir -i '*Cargo.nix' | ||
33 | 61 | ||
34 | USAGE: | 62 | # see `statix -h` for a full list of options |
35 | statix [FLAGS] [OPTIONS] [--] [TARGET] | 63 | ``` |
36 | 64 | ||
37 | ARGS: | 65 | Certain lints have suggestions. Apply suggestions back to |
38 | <TARGET> File or directory to run statix on [default: .] | 66 | the source with: |
39 | 67 | ||
40 | FLAGS: | 68 | ```shell |
41 | -d, --dry-run Do not fix files in place, display a diff instead | 69 | statix --fix /path/to/file |
42 | -f, --fix Find and fix issues raised by statix | ||
43 | -h, --help Print help information | ||
44 | -V, --version Print version information | ||
45 | 70 | ||
46 | OPTIONS: | 71 | # show diff, do not write to file |
47 | -i, --ignore <IGNORE>... Globs of file patterns to skip | 72 | statix --fix --dry-run /path/to/file |
48 | -o, --format <FORMAT> Output format. Supported values: errfmt, json (on feature flag only) | 73 | ``` |
74 | |||
75 | `statix` supports a variety of output formats; standard, | ||
76 | json and errfmt: | ||
77 | |||
78 | ```shell | ||
79 | statix /path/to/dir -o json | ||
80 | statix /path/to/dir -o errfmt # singleline, easy to integrate with vim | ||
49 | ``` | 81 | ``` |
50 | 82 | ||
51 | ## Architecture | 83 | ## Architecture |
@@ -55,6 +87,7 @@ OPTIONS: | |||
55 | - `bin`: the CLI/entrypoint | 87 | - `bin`: the CLI/entrypoint |
56 | - `lib`: library of lints and utilities to define these | 88 | - `lib`: library of lints and utilities to define these |
57 | lints | 89 | lints |
90 | - `vfs`: virtual filesystem | ||
58 | - `macros`: procedural macros to help define a lint | 91 | - `macros`: procedural macros to help define a lint |
59 | 92 | ||
60 | ### `bin` | 93 | ### `bin` |
@@ -70,6 +103,11 @@ A library of AST-based lints and utilities to help write | |||
70 | those lints. It should be easy for newcomers to write lints | 103 | those lints. It should be easy for newcomers to write lints |
71 | without being familiar with the rest of the codebase. | 104 | without being familiar with the rest of the codebase. |
72 | 105 | ||
106 | ### `vfs` | ||
107 | |||
108 | VFS is an in-memory filesystem. It provides cheap-to-copy | ||
109 | handles (`FileId`s) to access paths and file contents. | ||
110 | |||
73 | ### `macros` | 111 | ### `macros` |
74 | 112 | ||
75 | This crate intends to be a helper layer to declare lints and | 113 | This crate intends to be a helper layer to declare lints and |
@@ -79,4 +117,6 @@ their metadata. | |||
79 | 117 | ||
80 | - Offline documentation for each lint | 118 | - Offline documentation for each lint |
81 | - Test suite for lints and suggestions | 119 | - Test suite for lints and suggestions |
82 | - Output singleline/errfmt + vim plugin | 120 | - Vim plugin (qf list population, apply suggestions) |
121 | - Resolve imports and scopes for better lints | ||
122 | - Add silent flag that exits with status | ||