# nitpick

URL: https://tuios.dev/docs/libraries/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](https://pkg.go.dev/golang.org/x/tools/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

```bash
go install tuios.dev/nitpick/cmd/nitpick@latest
```

The command needs Go 1.26 or later. The library requires only `golang.org/x/tools`. The API reference is on [pkg.go.dev](https://pkg.go.dev/tuios.dev/nitpick).

## Check a change

```bash
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 more
```

`nitpick 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:

```text
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

```bash
nitpick check ./...                 # every finding in the packages
nitpick rules                       # the rules and their precision
```

`nitpick 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](https://github.com/Gaurav-Gosain/tuios/blob/main/nitpick/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.

```json
{
  "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:

```bash
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:

```go
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:

```go
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`](https://pkg.go.dev/tuios.dev/nitpick#Analyzers)                                              | The analyzers of the default rules.                               |
| [`Rules`](https://pkg.go.dev/tuios.dev/nitpick#Rules), [`Rule`](https://pkg.go.dev/tuios.dev/nitpick#Rule) | Every rule with its analyzer, default, precision and sample size. |
| [`Lookup`](https://pkg.go.dev/tuios.dev/nitpick#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](https://github.com/Gaurav-Gosain/tuios/tree/main/nitpick) of the tuios repository, under the MIT licence.

The idea of a diff-scoped hygiene check with a measured precision comes from [nits](https://github.com/jkomyno/nits). nitpick shares no code with it.
