beads/engdocs/LINTING.md
Julian Knutsen a4509deb2d
ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) (#7341)
* ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18)

Lint and vet now run as nogo inside the Bazel build, so they gate wherever
the Bazel lanes execute (rbe-west), and the golangci-lint and go vet jobs
leave pr.yml and main.yml.

- //tools/nogo (own go.mod, joined to beads' for go_deps only through
  gazelle.go.work): go test's vet checks (cmd/go's defaultVetFlags, the set
  scripts/ci/go-test-vet.sh ran) plus the eight linters .golangci.yml
  enables, each a wrapper over the library version golangci-lint v2.10.1
  uses (depguard, errcheck, forbidigo, gosec, misspell, sloglint, unconvert,
  unparam).
- .golangci.yml stays the single lint policy: Bazel embeds it and
  tools/nogo/internal/golangci applies it as golangci-lint does (enabled
  set, settings, run.tests: false as library-unit-only analysis, lax
  generated-file detection, path/path-except/text exclusion rules), with
  strict decoding so an unimplemented key fails the build.
- gascity's rules_go //nolint-range patch and x/tools ctrlflow patch,
  byte-identical.
- Windows/darwin: cross-configured, not a golangci leg. The pure lane's
  release cross-compile (//tools/bazel:release_cross, every library and
  binary for all eight release platforms, cgo off) runs nogo on every
  compile, a superset of golangci-lint's windows and darwin legs.
  scripts/pr-lint (make ci-pr-lint, bd preflight) runs `bazel build
  --config=nogo //...` plus release_cross for windows_amd64,darwin_arm64.
  release_cross skips tools/nogo, a separate Go module `go build ./...`
  never compiled.
- pr.yml: scripts-go-checks (vet) and pr-lint-wrapper (x3) are gone, with
  their ci-gate entries; main.yml: pr-lint-wrapper (x6) and go-vet-cache.
  scripts/ci/go-test-vet.sh and install-golangci-lint.sh are deleted.
- pre-commit hook and .pre-commit-config.yaml run `make lint-changed
  LINT_CHANGED_SCOPE=staged` (nogo over the staged packages); Makefile adds
  lint, vet and lint-changed. pr-lint.sh no longer runs gofmt
  (//scripts/repochecks:fmt_test owns it; ga-96smfk.41).
- internal/testutil/integration: five gosec findings in integration-tagged
  library files golangci-lint never built, now linted by the integration
  lanes, carry reasoned //nolint directives.

Parity: with the exclusion rules removed, golangci-lint and nogo report the
same 3,916 findings natively and 3,859 each for windows and darwin (file,
line, linter, text); with .golangci.yml as committed both report none.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* ci(bazel): equivalence.py leaves nested Go modules' tests out of go test's set

tools/nogo is its own Go module, so `go test ./...` in the root never runs
its tests; Bazel's unit lane does. Its packages are neither expected nor
extra.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-07 05:17:22 +00:00

5.2 KiB

Linting Policy

Last reviewed: 2026-10-07

Freshness source: .golangci.yml, tools/nogo/, scripts/ci/pr-lint.sh, scripts/pr-lint/, Makefile, .github/workflows/pr.yml, and .github/workflows/main.yml.

This document explains the required Go lint and vet gate for this codebase.

Current Status

Lint and vet run as nogo (//tools/nogo) inside the Bazel build. rules_go runs the analyzers beside every first-party Go compile, so any bazel build or bazel test, locally or on rbe-west, fails on a finding. The analyzers are:

  • go test's vet checks: the passes cmd/go's defaultVetFlags give go test (atomic, bools, buildtag, directive, errorsas, ifaceassert, nilfunc, printf, slog, stringintconv, tests). They see every file, tests included, as the former go vet ./... did.
  • The golangci-lint linters .golangci.yml enables (depguard, errcheck, forbidigo, gosec, misspell, sloglint, unconvert, unparam), each a thin wrapper in tools/nogo/analyzers/ over the same library version golangci-lint v2.10.1 uses.

.golangci.yml is still the one place lint policy lives. Bazel embeds it into the analyzers, and tools/nogo/internal/golangci applies it as golangci-lint did: which linters are enabled, their settings, run.tests: false (only the library compile unit of a package is linted, never its test unit), generated-file handling, and the path/text exclusion rules. Decoding is strict: a key the wrappers do not implement fails the build instead of being ignored. //nolint:<linter> directives keep working; a rules_go patch (third_party/patches/rules_go_nogo_golangci_nolint.patch, shared with gascity) gives them golangci-lint's line ranges.

Parity with golangci-lint was proved on the whole tree: with the exclusion rules removed, golangci-lint and nogo report the same 3,916 findings (file, line, linter and text) natively and the same 3,859 for windows/amd64 and darwin/arm64; with .golangci.yml as committed, both report none.

Where it gates:

  • bazel.yml's test lane (required through CI Gate / Required): bazel test //... --config=ci validates every package natively.
  • bazel.yml's pure lane (required): its release cross-compile (scripts/ci/bazel-release-cross-compile.sh) builds //tools/bazel:release_cross, every go_library and go_binary split-transitioned to each release platform without cgo, and nogo validates each of those compiles. So //go:build windows, darwin, !linux (and freebsd, android, arm64) files are analyzed from Linux: a superset of golangci-lint's former GOOS=windows/GOOS=darwin legs.
  • Every other Bazel lane (integration, embedded, dolt-server) validates what it compiles, including files only its build tags select.

Every PR is checked against the whole tree, not only its diff: the tree has no findings, so there is no baseline to scope against.

Run the gate locally with:

make ci-pr-lint      # native + windows + darwin (also: make lint, make vet)
make lint-changed    # native, only the Bazel packages of changed Go files

Both need bazel (or bazelisk) on PATH. With remote execution configured (.bazelrc.local or user.bazelrc), a warm run takes seconds: the native pass uses the race configuration of the CI test lane, so it reuses CI's remote cache. --config=nogo asks for the analysis output group alone, so nothing is linked.

make ci-pr-lint runs scripts/ci/pr-lint.sh, which times the checkout-owned scripts/pr-lint Go driver: bazel build --config=nogo //..., then //tools/bazel:release_cross for windows/amd64 and darwin/arm64 (--config=nogo-cross). The driver honors BD_LINT_TARGETS (a comma list of native, windows and darwin; default all three), prints a heading and result per pass, and is what Beads-source bd preflight runs. The pre-commit hook (and .pre-commit-config.yaml) runs make lint-changed LINT_CHANGED_SCOPE=staged. Formatting is not part of lint: //scripts/repochecks:fmt_test gates gofmt, and the hook formats staged files before linting them.

Policy

Treat lint findings as defects to fix before merge. Do not add a tolerated failing baseline.

When a linter reports an intentional or false-positive pattern:

  • Prefer a narrow .golangci.yml exclusion tied to a path, linter, and message.
  • Use //nolint:<linter> only when the reason is local to a specific line and the comment explains why the warning is not actionable.
  • Keep broad linter disables as a last resort.

To enable another golangci-lint linter, add it to .golangci.yml, add a wrapper under tools/nogo/analyzers/ (with its settings in tools/nogo/internal/golangci), and list it in tools/nogo/analyzers.bzl; //tools/nogo:nogo_test fails until the enabled list and the analyzer list agree.

CI Cleanup Decision

The former PR Lint (native|windows|darwin) and Go checks (vet) jobs, and main.yml's lint and vet cache seeders, are retired: nogo runs the same checks in the Bazel lanes on rbe-west. When the farm is switched off (bazel.yml mode skip), no lane runs, so neither does lint.

See CI_CLEANUP_PLAN.md for the full CI tier policy.

Future Work

  • Periodically audit .golangci.yml exclusions and remove entries that are no longer needed.