nitpick
Find Go hygiene problems that a compiler and most linters let through. Report only the lines that a change touched, with a measured precision for each rule.
tuios.dev/nitpick finds Go hygiene problems: errors that are dropped, development defaults read from the environment, comments that say what the next line says, deep nesting and code kept in comments. Each rule is a plain go/analysis analyzer. The nitpick command runs the rules and can report only the lines that a change touched.
Each rule has a precision. The precision is the share of its findings that a labeller judged worth a change, on a labelled sample of real Go code. Each finding shows it, and --gate uses it.
Install
go install tuios.dev/nitpick/cmd/nitpick@latestThe command needs Go 1.26 or later. The library requires only golang.org/x/tools. The API reference is on pkg.go.dev.
Check a change
nitpick diff # findings on the lines changed since HEAD
nitpick diff --base origin/main # findings on the lines this branch changed
nitpick diff --staged --gate 90% # exit 1 when a staged finding has a precision of 90% or morenitpick diff reads git diff. Without --staged, it uses the working tree, and an untracked Go file counts as new. With --base REF, it starts at the merge base of REF and HEAD. Without packages, it checks the packages of the changed files.
Each finding shows the precision of its rule:
store/load.go:42:3: error_to_empty_success: the err != nil branch returns empty values and a nil error, so the caller sees a success (precision 55%)Check packages
nitpick check ./... # every finding in the packages
nitpick rules # the rules and their precisionnitpick check checks ./... when you give no packages.
Rules
| Rule | Default | Precision | What it reports |
|---|---|---|---|
swallowed_error | off | 10% | _ = f() that drops an error in a function that returns an error, and an empty if err != nil {} |
error_to_empty_success | on | 55% | if err != nil { return nil, nil } and other empty returns with a nil error |
config_fallback | off | 0% | An environment variable that falls back to a development value, such as localhost |
narrator_comment | on | 85% | A comment that says what the next line says |
deep_nesting | on | 65% | Control nesting of 5 or more in one function |
elision_comment | off | 75% | A comment that stands in for missing code, such as "rest of implementation" |
junk_identifier | off | 33% | A name such as foo, stuff or data2 |
commented_out_code | on | 61% | Go code kept in a comment |
nolint_without_reason | off | 20% | A //nolint directive with no reason |
A rule is on by default when its precision is 50% or more on a sample of 10 or more. A sample under 20 gives a wide interval, so read those numbers as a first estimate. PRECISION.md gives the method, the sample sizes and the intervals.
A comment with a reason silences most rules. Write why the error is dropped, and the finding goes away.
Flags
| Flag | Meaning |
|---|---|
--json | Write JSON: findings (file, line, column, rule, message, precision), errors, gate_failed. |
--gate P | Exit with 1 when a finding has a precision of P or more. P is 0.9 or 90%. |
--enable LIST | Turn on more rules. LIST is rule names with commas, or all. |
--disable LIST | Turn off rules. |
--tests=false | Do not check _test.go files. |
--base REF | Compare with REF. The default is HEAD. Only nitpick diff reads it. |
--staged | Use the staged changes only. Only nitpick diff reads it. |
In JSON, precision is a fraction from 0 to 1. The exit status is 0 when the gate passes, 1 when it fails, and 2 on an error, such as a package that does not compile.
{
"findings": [
{
"file": "store/load.go",
"line": 42,
"column": 3,
"rule": "error_to_empty_success",
"message": "the err != nil branch returns empty values and a nil error, so the caller sees a success",
"precision": 0.5454545454545454
}
],
"gate": 0.5,
"gate_failed": true
}A pre-commit hook or a CI step can use the gate. This step fails when the branch adds a finding with a precision of 60% or more:
nitpick diff --base origin/main --gate 60%Use the analyzers in your own driver
nitpick.Analyzers() returns the analyzers of the default rules. Any go/analysis driver can run them. This program is a vet tool with the default rules:
package main
import (
"golang.org/x/tools/go/analysis/multichecker"
"tuios.dev/nitpick"
)
func main() {
multichecker.Main(nitpick.Analyzers()...)
}Each analyzer is also a variable of its own, such as nitpick.SwallowedError or nitpick.DeepNesting. Add one to the list to turn on a rule that is off by default. nitpick.Rules lists every rule with its default, precision and sample size:
for _, r := range nitpick.Rules {
fmt.Println(r.Name(), r.Default, r.Precision, r.Sample)
}A driver reports every finding in the packages. Only the nitpick command limits the report to changed lines.
API overview
| Name | Does |
|---|---|
Analyzers | The analyzers of the default rules. |
Rules, Rule | Every rule with its analyzer, default, precision and sample size. |
Lookup | The rule with a given name. |
Versions
The module is at v0 and has no tag yet. The rules, their precision and their defaults can change before v1. Its tags will have the folder name as a prefix, such as nitpick/v0.1.0. The source is in the nitpick folder of the tuios repository, under the MIT licence.
The idea of a diff-scoped hygiene check with a measured precision comes from nits. nitpick shares no code with it.
harness
Recognise coding-agent CLIs and read their state from the screen. One TOML manifest per agent, and a reason for every answer.
Library Usage
Embed TUIOS in your own Bubble Tea program with the pkg/tuios Go package, or serve it over SSH or in the browser.
tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.