beads/engdocs/LINTING.md
Julian Knutsen 38c0f24adb
ci: F5 S2 Variant A — nogo ownership for the integration configuration group (#7486)
* ci: F5 S2 Variant A nogo ownership for the integration configuration group

No full Bazel lane validates the integration / doltserver-integration /
doltserver-cmd configurations anymore (all three now pass
--norun_validations). Instead bazel-integration gains a narrow "Nogo:
integration library files" step that keeps full nogo (vet + golangci-lint)
on the configuration's one non-test library package,
//internal/testutil/integration, via
`bazel build --config=integration --@rules_go//go/config:race --keep_going
--output_groups=nogo_fix -- //internal/testutil/integration:integration`.

This accepts a scoped coverage loss (f5-spec.md §3/§5 S2, Variant A): the 56
integration-tagged _test.go files (listed in
tools/nogo/unvalidated_integration_tests.txt, derived from source by the new
T4 test) no longer get a vet pass in any lane, since golangci-lint already
skips all _test.go files repo-wide (.golangci.yml's run.tests: false) and no
lane builds those test binaries with validations on. Verified directly with
real `bazel build` runs: a planted vet finding in the library package still
fails the new step; the same finding in an integration-tagged _test.go file
no longer fails anything; a planted finding in a plain race-configuration
library still fails bazel-test; and GoCompilePkg action keys for the
integration configuration are identical with and without
--norun_validations (it is a build-request option, not a configuration
flag, so no farm cache invalidation).

scripts/nogo_lint_policy_test.go: the nogoConfigurations table gains a
"integ" row with an ownerIsNogoOnlyStep flag and a dedicated
checkNogoOnlyStepRow, generalizing T1/T2/T5/T6 to cover an owner that is a
narrow build step rather than a full lane; adds T4
(TestNogoIntegrationStepCoversItsConfiguration), which derives the step's
expected target set from source via go/build's own tag matching instead of
a hardcoded list.

Also fixes four should-fix items from julianknutsen's review of #7482:
1. expandBazelrcConfig now follows `common:` lines and --config= tokens
   anywhere on a line, not just a first-position `build:`/`test:` one.
2. TestNogoRaceOwnerBuildsEverything now expands every config the owner job
   can reach (including shell-variable-gated ones like sole-run), not just
   the statically-named "ci".
3. The package-gate check now compares full key-flag fingerprints instead
   of substring-matching --@rules_go//go/config:race / --norun_validations.
4. tools/bazel/nogo_ownership.py now fails loudly (exit 2) when both the
   owner's and non-owners' action-key sets are empty, instead of reporting
   a vacuous pass.

Each fix has new mutation-test coverage in TestNogoPolicyRejectsMutations
(should-fixes 1-3) or nogo_ownership_test.py (should-fix 4).

engdocs/LINTING.md and engdocs/CI_REQUIRED_CHECK_TOPOLOGY.md updated to
remove the stale "integration still validates in all three lanes" claim and
document the Variant A trade-off.

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

* fix(ci): make T4's source scan work under Bazel, not just plain go test

scripts:scripts_test only declares //:repo_other_files as data (every
tracked file but Go and Markdown source, by design: a Go-only change
should not re-run the CI/workflow policy tests). TestNogoIntegrationStep
CoversItsConfiguration's source scan needs every non-test .go file, so
under `bazel test //scripts:scripts_test` its runfiles tree had none and
the scan always came back empty.

Fixes:
- scripts/BUILD.bazel: add //:repo_go_srcs to scripts_test's data, with a
  comment explaining why (this is the one test in the target that needs it).
- integrationOnlyLibraryPackages: use bazelPolicyRoot(t) + repoFiles(t, ...)
  (the existing Bazel-safe, runfiles-aware file listing other policy tests
  in this package already use) instead of sourceRepoRoot(t) +
  filepath.WalkDir, which only sees what //scripts's own go_test target
  declares.

Verified with real `bazel test --config=integration --@rules_go//go/config:race`
and `--config=ci --@rules_go//go/config:race` runs of //scripts:scripts_test
(both pass); CI caught the original gap (PR #7486's first push failed
Bazel / integration and Bazel / test with exactly this).

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

* fix(bazel): address independent review + bee-ghosttrack findings on F5 S2 Variant A

Independent review of #7486, must-fixes 1-7: pipefail on the nogo-only
step's tee pipeline; exact source-scan equality check for
tools/nogo/unvalidated_integration_tests.txt; expandBazelrcConfig
follows common:-lines and non-first-position --config= tokens in both
the Go policy test and nogo_ownership.py; mirrored
nogo_ownership.py should-fix guarding against a non-owner action-key
query silently matching nothing.

Cost fix: split T4/T6's whole-repo .go source scan into its own
go_test target (//scripts:nogo_integration_scan_test) so a Go-only
change no longer re-runs all of scripts_test; extracted the shared
bazelInvocations and ciWorkflow helpers into helper-only files so
both targets can depend on them without violating the
one-target-per-test-file partition rule.

bee-ghosttrack review: checkNogoOnlyStepRow's own fingerprint now
excludes test:-sourced .bazelrc lines pulled in via --config=X
(buildOrCommonLines), since the nogo-only step is a `bazel build`
invocation that never reads a test: line; added mutation s2i
reproducing the gap this closes.

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

* fix(nogo): pin integration nogo-only step's target, fingerprint its lane, add behavioral test

Addresses the remaining should-fixes from the independent review of #7486:

1. TestNogoIntegrationStepScriptFailsWithoutMaskingBazelsExitCode
   (scripts/nogo_integration_step_script_test.go) extracts the real
   "Nogo: integration library files" step script from bazel.yml and runs it
   under plain `bash -e` (GitHub's actual run: semantics, no pipefail added)
   against a stub bazel, closing the gap a text-only pin can't: it catches
   rc=0 before `exit "$rc"`, `|| :`/`|| true` on the tee pipeline, or a
   missing/negated `set -o pipefail`, regardless of how the mutation is
   spelled.

2. The nogo-only step's target set is now pinned by exact go_library
   label, not just package: nogo_integration_scan_test.go derives the
   label(s) from source + BUILD.bazel and nogo_lint_policy_test.go pins
   them literally (its own go_test target has no //:repo_go_srcs). Both
   reject a `-//` exclusion pattern outright.

3. checkNonOwnerCommandLineAddsNoKeyFlag is now also applied to the
   integ row's owner's own full lane: under Variant A that lane validates
   nothing, so it is effectively a non-owner for this check's purpose, and
   must not override a key-affecting flag on its command line either.

4. Latent items: TestNoUnconditionalValidationOff now also scans
   .github/actions/setup-bazel/write-bazelrc.sh for run_validations (every
   line it emits lacks a :config suffix, so any occurrence would turn
   validation off everywhere with no owner lane to catch it).
   tools/bazel/nogo_ownership.py's docstring is corrected: it had said S2
   was simply "out of scope," which is now stale since S2 has its own
   validating lane (the nogo-only step, checked statically); the script's
   dynamic aquery-based cross-check remains S1-only because S2's owner has
   no non-owner test lane building the same configuration to compare
   actions against.

Skipped (not cheap / not reachable):
- bazel-server-storage's `if:` not modeling an "integration" input: no such
  input exists to model; the gate is RBE-enabled-only by design, and
  resolving this requires understanding pr.yml's broader gating semantics,
  not a textual fix.
- defaults.run.shell parsing: bazel.yml has no `defaults:` block today
  (confirmed by grep), so there is nothing to parse; the gap is latent only
  for a future change, not a live bug.
- race-off scan's future-wrong-fix edge case: the review itself
  characterizes this as not reachable with today's file set.

New mutation cases s2j/s2k/s2l in TestNogoPolicyRejectsMutations cover
items 2 and 3. All mutation-verifications performed by hand-editing the
real files, confirming FAIL, and reverting via Edit (never git
stash/checkout).

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

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-10 23:19:16 +00:00

6.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).
  • The integration, doltserver-integration and doltserver-cmd configurations (owned by bazel-integration, bazel-server-storage and bazel-cmd-dolt) all pass --norun_validations: none of their full bazel test lanes validates nogo. Instead bazel-integration runs a narrow extra step, Nogo: integration library files, that builds only //internal/testutil/integration under --config=integration --@rules_go//go/config:race --output_groups=nogo_fix, so the one non-test library package these configurations add (selected by the integration build tag) still gets vet+golangci-lint coverage. This is a deliberate, narrower scope than the other groups above: the 56 integration-tagged _test.go files (listed in tools/nogo/unvalidated_integration_tests.txt) are no longer analyzed by nogo in any lane, because bazel test //... --config=integration never builds with validations and no lane builds those test binaries outside of bazel test. scripts/nogo_lint_policy_test.go's TestNogoConfigurationsHaveOneValidatingLane (the integ row) and TestNogoIntegrationStepCoversItsConfiguration pin this trade-off.

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.