V06-go-quality

Files (1)

• SKILL.md

SKILL.md (first lines)

# V06 — go-quality

> **Owner**: `hooks/validators/go_quality.py`
> **Tier**: 2 (PostToolUse) — `go vet` + `gofmt -l file` + `go build` (cheap, sub-second on cached). 3 (Stop) — adds `golangci-lint run` + `go test -race -count=1 ./...`.
> **File patterns**: `**/*.go`, `**/go.mod`, `**/go.sum`

## Rules

| Rule ID | Severity | When |
|---|---|---|
| `V06-GO-VET` | error | `go vet ./...` reported a finding (parsed `(.+\.go):(\d+):\d+: (.+)`). |
| `V06-GOFMT` | warning | `gofmt -l <file>` returned non-empty (file is not gofmt-formatted). |
| `V06-BUILD-FAIL` | error | `go build ./...` exited non-zero. |
| `V06-LINT-<linter>` | warning / error | `golangci-lint run --out-format json` reported an issue; the rule preserves the underlying linter name (`errcheck`, `gosec`, `unused`, ...). |
| `V06-TEST-FAIL` | error | `go test -race -count=1 ./...` produced `--- FAIL: (\S+)`. |

## Why this verifier exists

Go's standard toolchain is famously thorough — but only when invoked. The cost gradient is:

- **`go vet`** (sub-second, idiomatic checks) → run on every edit.
- **`gofmt -l`** (instant per file) → run on every edit.
- **`go build`** (incremental, ~1-3 s on a cached project) → run on every edit.
- **`golangci-lint run`** (10-60 s depending on linter set) → run only on Stop.
- **`go test -race ./...`** (project-dependent, can be minutes) → run only on Stop, with the 30 s per-validator timeout from `parallel_runner` as the upper bound.

V06's two-tier split is essential — running golangci-lint on every Edit would exceed the Tier 2 budget (~5 s soft target). Running only on Stop means the slower checks happen exactly once per turn, which matches the user's expectation: edit fast, verify thoroughly at the end.

## Design rationale

- **`go vet` as `error`, not `warning`.** Vet's checks are conservative — every `vet` finding has been observed to cause real bugs. False positives are rare enough that flagging them as errors is correct.
- **`gofmt` as `warning`, not `error`.** `gofmt` is mechanical — the fix is "run gofmt". Flagging as warning + including `Run 'gofmt -w <file>'` in the `fix` field gives the AI agent direct remediation.
- **`golangci-lint` rule name preserved (`V06-LINT-errcheck`).** This way users can disable specific noisy linters via `validators.disabled: ["V06-LINT-godox"]` without disabling all of V06.
- **`go test -race -count=1`** explicitly. `-race` catches concurrent-access bugs (which Go's runtime hides without it). `-count=1` defeats Go's test cache so results are reproducible. Without these, the test gate is theater.

## Performance (Option C parallelization)

`validate_project` (Tier 3) uses a 2-stage execution model when `golangci-lint` is available on PATH:

```
Stage 1 (sequential)          Stage 2 (parallel, max_workers=2)
─────────────────────         ──────────────────────────────────
go build ./...        ──────► golangci-lint run --out-format json
                              go test -race -count=1 ./...
```

- **Stage 1 is sequential** because `go build` writes to `$GOCACHE`; running lint and test before the cache is warm wastes CPU and can cause flaky race conditions.
- **Stage 2 is parallel** because `golangci-lint` and `go test` are read-only and independent; running them concurrently reduces wall-clock time from ~(lint_time + test_time) to ~max(lint_time, test_time).
- **`go vet` and `gofmt` are skipped in Tier 3 when golangci-lint is present** — golangci-lint integrates `govet` and `gofmt` by default, so calling them separately produces redundant work and duplicate findings. When golangci-lint is present, vet/fmt findings appear as `V06-LINT-govet` / `V06-LINT-gofmt` instead of `V06-GO-VET` / `V06-GOFMT`.
- **Fallback (golangci-lint absent)**: legacy sequential path — `go vet` → `go build` → `go test` (3 calls, no parallelism). Same behavior as pre-Option-C.

Detection: `shutil.which("golangci-lint")` at runtime. No config required.

Worst-case timing improvement (60 s lint + 120 s test):
- Before: ~370 s (vet 30 + fmt 10 + build 60 + lint 90 + test 180)
- After: ~240 s (build 60 + max(lint 90, test 180))

## How it checks (implementation)

Lives in `hooks/validators/go_quality.py`. Tier 2 entry runs `_has_go_project` short-circuit (no `.go` / `go.mod` → bail) then 3 cheap checks; Tier 3 runs the same plus 2 expensive ones.

### Tier 2 (`validate_file`)

```python
def validate_file(self, ctx, file_path):
    if not self._has_go_project(ctx):
        return []
    findings: list[Finding] = []
    findings.extend(self._check_go_vet(ctx))
    if file_path.endswith(".go"):
        findings.extend(self._check_gofmt(ctx, file_path))
    findings.extend(self._check_go_build(ctx))
    return findings
```

### `_check_go_vet(ctx)` — V06-GO-VET

```python
result = subprocess.run(
    ["go", "vet", "./..."],
    cwd=str(ctx.server_dir),
    capture_output=True, text=True, timeout=20,
)
LINE = re.compile(r'^(.+\.go):(\d+):\d+: (.+)$')
for line in result.stderr.splitlines():
    if (m := LINE.match(line)):
        yield Finding(
            severity="error",
            file=m.group(1),
            line=int(m.group(2)),
            rule="V06-GO-VET",
            message=m.group(3),
            ...
        )
```

### `_check_gofmt(ctx, file_path)` — V06-GOFMT

```python
# Single-file: gofmt -l <file> prints the path if it's unformatted, else nothing
result = subprocess.run(
    ["gofmt", "-l", file_path],
    cwd=str(ctx.server_dir),
    capture_output=True, text=True, timeout=5,
)
if result.stdout.strip():
    yield Finding(
        severity="warning",
        rule="V06-GOFMT",
        fix=f"Run 'gofmt -w {file_path}'",
        ...
    )
```

### `_check_go_build(ctx)` — V06-BUILD-FAIL

```python
result = subprocess.run(
    ["go", "build", "./..."],
    cwd=str(ctx.server_dir),

From HwangTaehyun/verifiers, MIT.

More from HwangTaehyun/verifiers