beads/engdocs/LINTING.md
Julian Knutsen bc19f6e478
ci: parallel PR Lint matrix with pinned golangci-lint, fold duplicate Lint, split scripts-go-checks (F5) (#7127)
* ci(lint,scripts): fold duplicate Lint job; matrix PR Lint and scripts-go-checks (F5)

Lint (golangci-lint-action, only-new-issues) was functionally identical to
pr-lint-wrapper's native leg (H7): same pinned binary, config, flags, and
diff scope. Fold it into the wrapper in both pr.yml and main.yml, and drop
LINT from pr.yml's ci-gate.

pr-lint-wrapper becomes a 3-leg matrix (native/windows/darwin, fail-fast:
false) under the same PR_LINT_WRAPPER gate id, installing golangci-lint
v2.10.1 from a pinned, sha256-verified release binary
(scripts/ci/install-golangci-lint.sh) instead of go install/the Action, with
a per-leg golangci-lint cache (pr.yml restores only; main.yml's matrix is
the sole saver). scripts-go-checks becomes a 3-leg matrix
(scripts-test/vet/allowlisted, fail-fast: false) under the same
SCRIPTS_GO_CHECKS gate id, giving go vet its own build cache instead of
sharing the race build cache. main.yml gains a go-vet-cache job to warm that
cache on push; build-artifacts remains the Go module cache's sole saver.

Splitting each job's previously-sequential passes into parallel matrix legs,
combined with removing the duplicate Lint job outright, takes wall-clock
time off the PR gate's critical path.

Updates scripts/ci_workflow_test.go and scripts/pr_lanes_bazel_coverage_test.go
for the new matrices, cache topology, and the removed LINT id; adds
TestGolangciLintInstallScriptPinned. Updates engdocs/LINTING.md and the live
prose in engdocs/CI_REQUIRED_CHECK_TOPOLOGY.md (its disclaimed "historical
snapshot" gate-wiring block is left as-is).

Verified: go test ./scripts/..., bazel --nohome_rc test //scripts:scripts_test
(after adding engdocs/LINTING.md and .githooks/pre-commit as scripts_test
data), actionlint, shellcheck, make ci-pr-policy, make bazel-sync-check.
Confirmed lint-leg parity against current main with the pinned binary (0
issues PR-scoped; the same two pre-existing unparam findings full-tree,
unchanged) and scripts-go-checks leg parity standalone. Mutation-tested the
new/updated policy assertions with six deliberate breaks (dropped matrix
leg, reintroduced LINT, corrupted the pinned sha256, removed a cache-save
step, dropped the vet leg, reintroduced the lint job); each was caught with
an on-target failure.

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

* fix(ci): review-fix pass on F5's lint/scripts-go-checks matrix (SF-1..SF-5, N-1..N-8)

Addresses all SHOULD-FIX and NIT findings from the review of 7e858e2714
(no BLOCKERs):

- SF-1: lint/vet cache saves now run on !cancelled() instead of bare
  cache-miss, so a red lint/vet run (main is currently lint-red on two
  pre-existing, unrelated unparam findings) still warms the cache for
  PR legs.
- SF-2: ci-measurements.yml now exports golangci-lint's install dir onto
  PATH in the same step, since $GITHUB_PATH only takes effect in later
  steps.
- SF-3: adds a behavioral test (fake curl/tar) proving the install
  script's sha256 verification fails closed.
- SF-4: drops the commit sha from the golangci-lint cache key (saves
  only on config/dependency change, not every push) and trims the
  windows/darwin legs to cache only the small golangci-lint result
  cache, not their large GOCACHE.
- SF-5: removes the vet cache's dead non-race-build-cache fallback
  restore key (different path list, can never hit) in both pr.yml and
  main.yml.
- N-1..N-8: doc/comment accuracy fixes, restores the "moved code reads
  as new" caveat, adds a module-cache restore step and timeout-minutes
  to pr-lint-wrapper/go-vet-cache, pins fetch-depth/GOCACHE via new
  policy-test assertions, and flags a superseded doc snapshot.

New commit on top of 7e858e2714; existing commit trailers are left
untouched per explicit instruction. Not pushed, no PR opened.

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

* build(bazel): auto-sync BUILD files

Applied from the bazel-sync-patch artifact of https://github.com/gastownhall/beads/actions/runs/37105481015
(`make bazel-sync`: gazelle, tools/bazel/go_srcs.py, bazel mod tidy).
Only BUILD.bazel, MODULE.bazel and MODULE.bazel.lock are ever pushed; see
scripts/bazel-autofix-push.sh.

---------

Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-10-03 09:36:20 -07:00

5.8 KiB

Linting Policy

Last reviewed: 2026-10-03

Freshness source: .golangci.yml, 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 gate for this codebase.

Current Status

Lint is a required CI gate: ONE job per lane (pr-lint-wrapper), over the same pinned golangci-lint v2.10.1 release and the same .golangci.yml. Each lane must pass with zero issues in its own scope.

  • The PR lane reports only what the PR introduces. pr-lint-wrapper runs the repository-owned ci-pr-lint wrapper with BD_LINT_NEW_FROM_MERGE_BASE set to the diff against the merge base with main. A finding in code the PR did not touch does not block it. "New" is measured off the diff, so MOVED CODE READS AS NEW: a pre-existing violation carried into a PR by a move or a rename is reported against that PR and blocks it. Fix it or //nolint it there — that is the accepted cost of the diff-scoped trade.
  • The main lane sweeps the whole tree. The same job runs on every push to main with BD_LINT_NEW_FROM_MERGE_BASE unset, so a finding that lands there reds main's own run rather than every open PR.

pr-lint-wrapper is a 3-leg matrix, matrix.target: [native, windows, darwin] (fail-fast: false), one leg per scripts/pr-lint pass (see below); the gate requires the matrix's aggregate result under the same PR_LINT_WRAPPER id as before. A former separate Lint job (the golangci-lint-action with only-new-issues) was functionally identical to this matrix's native leg (same binary, config, flags and diff scope) and was folded into it; see #5629.

Each leg installs golangci-lint from the pinned release binary (scripts/ci/install-golangci-lint.sh, sha256-verified) instead of go install, and restores a per-leg cache (~/.cache/golangci-lint plus a leg-specific GOCACHE) keyed on .golangci.yml, go.sum and the leg. A miss on the exact content key falls back to the leg's most recent entry; golangci-lint revalidates it against the current config and inputs, so a stale restore cannot mask an issue. pr.yml only ever restores; main.yml's matrix is the only saver, on an exact-key miss.

Run the wrapper locally with:

make ci-pr-lint

That is the MAIN lane's contract, not the PR lane's: with BD_LINT_NEW_FROM_MERGE_BASE unset it sweeps the whole tree, so it is deliberately STRICTER than the gate your PR has to clear and may report findings you are not required to fix. Fix the ones that are yours; the PR gate is the authority on what blocks a merge, and main's own run is where the rest is answered.

The wrapper runs:

  • the shared scripts/ci/fmt-check.sh formatting check; and
  • the checkout-owned scripts/pr-lint Go driver, which runs golangci-lint with .golangci.yml, readonly module downloads, a five-minute timeout, the gms_pure_go build tag, and --new-from-merge-base when BD_LINT_NEW_FROM_MERGE_BASE names a ref, then runs the same scope for the non-CGO Windows target and the non-CGO darwin (arm64) target when the native host does not already cover them, so //go:build windows && !cgo and //go:build darwin files are linted from the Linux runner.

The shell wrapper records one aggregate timing for the Go lint driver. The driver prints a heading and result for each native or cross-target pass so failures remain attributable without duplicating target-selection policy in Bash.

The shared driver owns the lint passes used by scripts/ci/pr-lint.sh and Beads-source bd preflight. The pre-commit hook does not call it: the hook uses changed-lines scope, adds --fix, and omits the Windows cross-lint pass. The driver honors BD_LINT_TARGETS (a comma list of native, windows and darwin; default all three) so each CI matrix leg can run just its own pass; make ci-pr-lint and bd preflight both leave it unset and keep running all three.

The driver matches .buildflags when preparing GOFLAGS: appending -tags=gms_pure_go can override an inherited bare-Go tags value; it does not merge tag lists. Each lint process has a six-minute context and a five-minute golangci-lint timeout. Cancelling preflight's outer go run command does not guarantee immediate descendant cleanup.

On Windows, the driver checks each pass's selected Go SDK and prefers its bin directory only in that linter child's PATH. This avoids an extra Go auto-selection process surviving cancellation. Discovery shares the existing 30-second probe budget; custom SDKs that cannot be verified retain the original PATH. Toolchain requests, formatting, and lint deadlines are unchanged. This does not guarantee cleanup of compiler descendants or fix slow package loading.

Policy

Treat new lint findings as defects to fix before merge. Do not add a tolerated failing baseline, and do not configure CI with --issues-exit-code=0.

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.

The current configuration already encodes accepted exclusions for intentional patterns such as deferred cleanup errors, controlled subprocess execution, test-fixture file reads, and documented security false positives.

CI Cleanup Decision

pr-lint stays separate from pr-policy and pr-core so failures are easy to identify and rerun. Its repository-owned wrapper is scripts/ci/pr-lint.sh, exposed as make ci-pr-lint; its lint policy is owned by the shell-free scripts/pr-lint Go driver.

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.