beads/engdocs/LINTING.md
Julian Knutsen 143c418148
ci(bazel): cut per-lane fixed cost — LLVM .tar.zst slice, release cross-compile lane, no protoc build (#7379)
* ci(bazel): fetch the LLVM toolchain as a 149 MB slice; re-key the runner cache

Port of gascity #7279. @llvm_dist_linux_x86_64 downloaded the 1.94 GB
LLVM-22.1.8-Linux-X64.tar.xz and ran a single-threaded `tar -xJf` over
11 GiB to keep a 688 MB slice. That took 94-147 s in every Bazel lane,
and every cgo, race and stdlib action waits on it.

- llvm_dist.bzl gains `sliced`: download_and_extract of a members-only
  .tar.zst, plus a missing-member check. The xz path stays.
- MODULE.bazel pins the toolchain-llvm-22.1.8-slice-1 asset by sha256
  (de614777...6bec5). The URL is gascity's release asset for now; the
  list form leaves room for a beads mirror of the same bytes.
- tools/cc_toolchain/repack_llvm.sh and llvm_members.txt rebuild the slice
  from the pinned upstream release.
- Runner cache v4, keyed on MODULE.bazel too. MODULE.bazel.lock does not
  record llvm_dist, so the v3 key never changed and kept restoring the
  2.9 GB entry that holds the xz archive.
- bazel_hermetic_cc_test: a sliced llvm_dist may only download from a
  gastownhall/beads or gastownhall/gascity release, and its members must
  equal llvm_members.txt.

Verified locally:
- Every file in the extracted slice (2009 entries: types, modes,
  symlink targets, sha256) is identical to the xz extraction.
- aquery action keys are identical, base vs head, at the same workspace
  path: 7565/7565 over deps(//cmd/bd:bd_for_tests) and 7146/7146 over
  the race deps(//internal/storage/embeddeddolt:embeddeddolt_test).
- Extraction time: 178 s (xz) vs 1.9 s (zstd).

Agent-Signature: claude-code-claude-opus-5-5-medium on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* ci(bazel): run the release cross-compile as its own lane

After the LLVM slice, bazel-pure is the longest cached Bazel lane (about
170 s). Its "Cross-compile every release target" step takes 54-58 s of
that (78.9k configured targets, 25k cache-hit lookups) and shares no
analysis with the pure invocations, because release_cross is a split
transition.

The step moves, unchanged, into a new job, bazel-release-cross ("release
cross-compile"). The job uses bazel-pure's runner, `needs: rbe` and skip
rule, so it runs in every mode except skip. It reports job.status like
every lane: the workflow_call output is bazel-release-cross, and pr.yml's
CI Gate requires it as BAZEL_RELEASE_CROSS. bazel-gate.sh skips it only in
mode skip, as it does BAZEL_PURE. Merge groups use the same pr.yml gate.
Push and dispatch runs gate nothing. Existing gate ids are unchanged.

The policy test now pins the step to bazel-release-cross, requires the new
gate id, and rejects any other job that runs the script (no double runs).
The new job is listed as having no CI analytics step. It captured no BEP as
a bazel-pure step either, and the analytics steps are unchanged. Docs:
LINTING.md, TESTING.md, CI_REQUIRED_CHECK_TOPOLOGY.md.

Expected: bazel-pure about 110 s on cached runs; the new lane about 85 s,
in parallel. Cost: one more 2-vCPU Blacksmith runner per run.

Agent-Signature: claude-code-claude-opus-5-5-medium on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* build(bazel): stop building protoc for protoc-gen-validate

github.com/envoyproxy/protoc-gen-validate ships validate/validate.pb.go,
but its own validate/BUILD makes the Go library a go_proto_library. So
every lane built protoc from source just to regenerate that file. The
module reaches the graph only through grpc xds and the cloud SDKs.

A gazelle_override now regenerates the module's BUILD files with
`gazelle:proto disable`. It sets build_file_generation = "on" and adds
`gazelle:build_file_name BUILD.bazel`, so gazelle writes BUILD.bazel
(which Bazel prefers) instead of keeping the upstream BUILD. The proto
directive alone changes nothing, because the upstream BUILD files win.
validate is now a plain go_library over validate.pb.go.

Measured locally with aquery:
- //... minus the manual release_cross target: base has 2096 CppCompile,
  612 CppArchive, 314 CppLink and 1 GoProtocGen action; head has 0.
- cquery somepath(//..., @protobuf//:protoc): base goes through
  grpc xds -> envoy core/v3 -> validate_go_proto -> protoc; head is
  empty.
- deps(//cmd/bd:bd_for_tests): 7565 actions become 3077. The race
  deps(//internal/storage/embeddeddolt:embeddeddolt_test): 7146 become
  2658.

MODULE.bazel.lock does not change. The v4 runner cache key includes
MODULE.bazel, so it still moves. Expect one cold compile of the Go
packages above validate on the first run after merge.

Agent-Signature: claude-code-claude-opus-5-5-medium on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* build(bazel): bazel mod tidy formatting

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-08 03:13:34 +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 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.
  • 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.