beads/engdocs/LINTING.md
Julian Knutsen b8e6ba1791
fix(bazel): one nogo-validating lane per race configuration (F5 S1) (#7479)
* fix(bazel): one nogo-validating lane per race configuration (F5 S1)

The race configuration (--@rules_go//go/config:race) is built by five
lanes that duplicate the same RunNogo/ValidateNogo work: bazel-test
(--config=ci), bazel-embedded, bazel-doltserver, bazel-proxied, and
the advisory bazel-dolt-race shadow, plus the package-mcp/package-npm
gates' explicit race build. --norun_validations is a build-request
option, not a configuration flag (proven here by aquery: GoCompilePkg/
GoLink/RunNogo/ValidateNogo action keys are byte-identical with and
without it), so passing it on every lane but bazel-test removes the
duplicate work without touching a single action key or dropping any
lint coverage: bazel-test's --config=ci already validates every file
any of the others compiles.

scripts/nogo_lint_policy_test.go replaces the old blanket
"--norun_validations never appears in .bazelrc" check with
TestNogoConfigurationsHaveOneValidatingLane (T1: one owner per
configuration fingerprint), TestNogoOwnersAreRequired (T2: the owner
is a required CI Gate check whose `if:` covers every non-owner's),
TestNogoRaceOwnerBuildsEverything (T3: the owner builds //... whole,
no exclusions) and TestNoUnconditionalValidationOff (T5: nothing else
may disable validation). tools/bazel/nogo_ownership.py (make
nogo-ownership) is a dynamic, advisory aquery cross-check of the same
property, run on demand rather than from inside a Bazel action.

Verified locally: aquery shows identical action keys for the affected
lanes with/without --norun_validations; a planted printf-format vet
finding in internal/idgen/hash.go failed the owner build and passed
the non-owner build (then reverted, never committed);
scripts/bazel_dolt_race_shadow_test.go and the full //scripts suite
stay green.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(bazel): close S1 nogo-ownership review gaps (allowlist, owner pin, real aquery)

Addresses maintainer-city-c3's review of #7479:

1. T6 TestRunValidationsOnlyOnAllowlistedLines replaces the coverage gap
   left when main's blanket run_validations ban was dropped: only the four
   race-group non-owners' "test:<cfg> --norun_validations" lines in
   .bazelrc, and the two package-gate bazel-build steps in bazel.yml, are
   permitted. A later test:integration/doltserver-cmd --norun_validations
   (out of T1's table, S2) now fails here instead of landing silently.
   Verified by mutation: adding test:integration --norun_validations fails
   the new test; reverting passes.

3. TestNogoRaceOwnerBuildsEverything (T3) now also pins that the race
   owner's "bazel test //... --config=ci" step has no step-level if: or
   continue-on-error, and that its job has none either. Verified by
   mutation: adding if: ${{ always() }} to that step fails; reverting
   passes.

2. tools/bazel/nogo_ownership.py's aquery comparison was querying the
   identical mnemonic("RunNogo", //...) for the owner and every non-owner,
   so `missing` could never be non-empty. It now derives each non-owner's
   actual built target set the way --build_tests_only + --test_tag_filters
   does: the deps closure of tests(//...) filtered to targets carrying one
   of the lane's tags, read exactly from `query --output=xml` (not attr()'s
   substring regex match, which would wrongly fold "dolt-server-proxied"
   and "dolt-server-cmd" into a "dolt-server" filter). Confirmed against a
   real (offline, --nohome_rc) bazel run: reports OK at head, and reports
   100+ missing targets when the owner's query is artificially narrowed to
   a subpackage -- it can now actually fail.

Also: refreshed a stale .bazelrc comment claiming nogo runs beside every
lane's compile, which S1 made untrue for race-group non-owners.

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

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-10 18:05:17 +00:00

5.6 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 release cross-compile lane (bazel-release-cross, required): 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.
  • The race configuration's nogo validations run once, owned by the test lane above: embedded, doltserver, doltserver-proxied, dolt-race (shadow) and the package gates (package-mcp, package-npm) all pass --norun_validations, since each compiles a strict subset of what test already validates on that configuration (scripts/nogo_lint_policy_test.go's TestNogoConfigurationsHaveOneValidatingLane pins this).
  • Every other Bazel lane (integration) still 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.