From 781c42cc9ce2e6a3f1024ea1f4e3f071cc8f2dd4 Mon Sep 17 00:00:00 2001
From: Akshay <nerdy@peppe.rs>
Date: Sun, 24 Oct 2021 17:55:57 +0530
Subject: flake build with json feature, add better usage docs

---
 flake.nix | 22 ++++++++--------
 notes.txt |  3 +++
 readme.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++-----------------
 3 files changed, 77 insertions(+), 34 deletions(-)

diff --git a/flake.nix b/flake.nix
index a319266..2c1db03 100644
--- a/flake.nix
+++ b/flake.nix
@@ -60,8 +60,10 @@
               cargo
             ];
             buildPhase = ''
-              cargo build -p statix --release --offline
+              cargo build -p statix --all-features --release --offline
             '';
+            # statix does not have any tests currently
+            doCheck = false;
             installPhase = ''
               install -Dm775 ./target/release/statix $out/bin/statix
             '';
@@ -85,19 +87,17 @@
       devShell = forAllSystems (system:
         let
           pkgs = nixpkgsFor.${system};
-          inherit (rustChannel pkgs) rust rust-src;
+          inherit (rustChannel pkgs) rust rust-src rust-analysis;
         in
         with pkgs;
         mkShell rec {
-          buildInputs =
-            [
-              rust-analyzer
-              rustfmt
-              cargo
-              cargo-watch
-              rust
-              rust-src
-            ];
+          buildInputs = [
+            rustfmt
+            cargo
+            cargo-watch
+            rust
+            rust-src
+          ];
           RUST_SRC_PATH = "${rust-src}/lib/rustlib/src/rust/library";
           RUST_LOG = "info";
           RUST_BACKTRACE = 1;
diff --git a/notes.txt b/notes.txt
index 73d9439..071e502 100644
--- a/notes.txt
+++ b/notes.txt
@@ -37,6 +37,9 @@ Lint ideas
 - invalid or potentially risky string interpolations
 - useless parens in infix exprs
 - unused function params
+- manual map over list
+- merge inherit
+- merge inherit-from
 
 Extensions
 ----------
diff --git a/readme.md b/readme.md
index 68265cc..293b72e 100644
--- a/readme.md
+++ b/readme.md
@@ -2,50 +2,82 @@
 
 > Lints and suggestions for the Nix programming language.
 
-`statix` highlights antipatterns in Nix code. `statix fix`
+`statix` highlights antipatterns in Nix code. `statix --fix`
 can fix several such occurrences.
 
 For the time-being, `statix` works only with ASTs
 produced by the `rnix-parser` crate and does not evaluate
 any nix code (imports, attr sets etc.). 
 
+## 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
+```
+
 ## Installation
 
 `statix` is available via a nix flake:
 
-```
-nix run git+https://git.peppe.rs/languages/statix
-
-# or
-
+```shell
+# build from source
 nix build git+https://git.peppe.rs/languages/statix
 ./result/bin/statix --help
+
+# 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
 ```
 
 ## Usage
 
-```
-statix 0.1.0
+Basic usage is as simple as:
 
-Akshay <nerdy@peppe.rs>
+```shell
+# recursively finds nix files and raises lints
+statix /path/to/dir
 
-Lints and suggestions for the Nix programming language
+# ignore generated files, such as Cargo.nix
+statix /path/to/dir -i '*Cargo.nix'
 
-USAGE:
-    statix [FLAGS] [OPTIONS] [--] [TARGET]
+# see `statix -h` for a full list of options
+```
 
-ARGS:
-    <TARGET>    File or directory to run statix on [default: .]
+Certain lints have suggestions. Apply suggestions back to
+the source with:
 
-FLAGS:
-    -d, --dry-run    Do not fix files in place, display a diff instead
-    -f, --fix        Find and fix issues raised by statix
-    -h, --help       Print help information
-    -V, --version    Print version information
+```shell
+statix --fix /path/to/file
 
-OPTIONS:
-    -i, --ignore <IGNORE>...    Globs of file patterns to skip
-    -o, --format <FORMAT>       Output format. Supported values: errfmt, json (on feature flag only)
+# 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
 ```
 
 ## Architecture
@@ -55,6 +87,7 @@ OPTIONS:
 - `bin`: the CLI/entrypoint
 - `lib`: library of lints and utilities to define these
   lints
+- `vfs`: virtual filesystem
 - `macros`: procedural macros to help define a lint
 
 ### `bin`
@@ -70,6 +103,11 @@ 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.
 
+### `vfs`
+
+VFS is an in-memory filesystem. It provides cheap-to-copy
+handles (`FileId`s) to access paths and file contents.
+
 ### `macros`
 
 This crate intends to be a helper layer to declare lints and
@@ -79,4 +117,6 @@ their metadata.
 
 - Offline documentation for each lint
 - Test suite for lints and suggestions
-- Output singleline/errfmt + vim plugin
+- Vim plugin (qf list population, apply suggestions)
+- Resolve imports and scopes for better lints
+- Add silent flag that exits with status
-- 
cgit v1.2.3