rework docs and readme

3 files changed, 100 insertions, 0 deletions

diff --git a/docs/architecture.txt b/docs/architecture.txt
new file mode 100644
index 0000000..fb2d724
--- /dev/null
+++ b/docs/architecture.txt
@@ -0,0 +1,38 @@
+architecture
+============
+
+statix has the following components:
+  * 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
+---
+
+This is the main point of interaction between `statix` 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.
+
+
+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
+their metadata.
diff --git a/docs/notes.txt b/docs/notes.txt
new file mode 100644
index 0000000..bba644c
--- /dev/null
+++ b/docs/notes.txt
@@ -0,0 +1,55 @@
+VFS
+---
+- do all the IO in one place
+- pass file handles around
+
+Interface
+---------
+- load files to be read as VFS
+- path interner
+- traits to go from Report to text/errfmt
+- offline documentation/explaination for lints
+
+Fix
+---
+- multipass runner with hare & tortoise for cycle detection
+- fix all possible suggestions
+- work with a config generated by CLI
+- read data from VFS
+- produce a Report
+
+Analysis
+--------
+- work with a config generated by CLI
+- read data from VFS
+- produce a Report
+
+Tests
+-----
+- figure out a way to generate stable singleline output for
+  analysis tests
+- use stderr tests for fixes
+
+Lint ideas
+----------
+- unused let bindings
+- unused rec
+- invalid or potentially risky string interpolations
+- useless parens in infix exprs
+- unused function params
+- manual map over list
+- merge inherit
+- merge inherit-from
+- empty inherit
+- useless antiquote/splice (where is antiquote truly
+  required?)
+- useless variadic (things like `{...} : expr`, replace with
+  `_: expr`)
+- redundant pattern `{...} @ inputs : expr`, replace with
+  `inputs: expr`
+- useless hasAttr: `if x ? a then x.a else default` can be
+  replaced with `x.a or default`
+
+Extensions
+----------
+- vim plugin to populate location list with errors
diff --git a/docs/release.txt b/docs/release.txt
new file mode 100644
index 0000000..8cc56ef
--- /dev/null
+++ b/docs/release.txt
@@ -0,0 +1,7 @@
+Release checklist:
+
+- bump version in Cargo.toml
+- run `cargo build --release` to bump Cargo.lock
+- run nix-build and update cachix cache
+- tag commit with latest version
+- push tag and commit to all remotes