hopinion: static analysis that enforces the code review standards
The whole repository as one commit on top of the empty initial one, so the diff
is everything there is to read.
## What it is
Static analysis that mechanically enforces the comment, style, testing and
process guides, plus a Nix layer that runs it over a repository as one check.
Three rules ship, one at each of the three levels, which is what makes the level
machinery real rather than designed. Adding a fourth is a module and one line.
## Where to start
`README.md`, then `plan/context.md` for what the current shape came from, the
invariants it stands on, and what is deliberately not built. `CLAUDE.md` has the
feedback loops in order of increasing coverage and cost.
`plan/` is scaffolding for the bootstrap and goes when the first version does.
The part to review hardest is `Hopinion.Extract`: it grows with every new fact
and never with a new rule, so a fact that is wrong there is wrong for every rule
that reads it. `Hopinion.Comment` is second, because comment attachment is what
twenty-one comment rules will stand on and it fails silently when wrong.
## What has been run
- `nix flake check`: passes, 69 checks including the end to end tests over the
derivations.
- `cabal test hopinion-test`: 308 tests.
- `scripts/corpus-run.sh` over nix-ci, sydtest, centjes and this repository.
- The consuming repository, on its adoption branch: the check builds green over
22 packages, with 818 modules answered for by the compiler and no complaints.
## Open, and yours to decide
- **No LICENSE.** The repository is private, so nothing forces the question yet,
but a consumer pinning it will want an answer.
- **Two corpus numbers are unexplained**, and `CLAUDE.md` says a number the
corpus run prints is either explained in `plan/context.md` or it is a bug.
sydtest reports 22 unmet obligations against a survey estimate of about one,
and centjes was in the corpus list with no numbers recorded at all. Both are
source-only counts and therefore a floor rather than an answer; running the
two under the Nix builders is what settles them. `plan/context.md` says so
rather than leaving the gap silent.
- **The open decisions in `plan/context.md`**, six of which turn on preference
or on things outside this repository.
## Known and deliberate
- Three rules is the whole shipped rule set. The value at first use is
regression prevention plus machinery that a fourth rule costs a module.
- `packages` is named rather than discovered, so a package a repository does not
name is not checked. That is a decision somebody writes down rather than a
directory a walk did not reach, and the error for a name that resolves to
nothing lists the directories that do hold a cabal file.
- `plan/modularity.md` predicted about 1,300 lines of infrastructure carrying 55
lines of rules. It is 6,542 carrying 599, over three rules. `plan/context.md`
says what that means and what would settle whether the per-rule cost is real.