* fix(lint): suppress two darwin-only gosec findings and cross-lint the darwin build in CI scripts/ci/pr-lint.sh lints natively on the ubuntu runner plus one GOOS=windows CGO_ENABLED=0 cross-lint, so files behind //go:build darwin (and the !windows && !linux fallbacks) were never linted in CI. Linting the darwin build reports two gosec findings that are clean on linux: - internal/config/permissions_open_nonlinux.go: G304 on os.Open(path). The file comment already explains why it is safe (fixBeadsDirPermissions re-checks descriptor identity before chmod); it just had no directive. - internal/utils/path_case_darwin.go: G103 on unsafe.Pointer. A directive existed but sat on the first line of a multi-line unix.Syscall call, while gosec reports the argument line four lines down, so it never covered the finding. It now sits on its own line above the statement, the placement cmd/bd/nocow_linux.go already uses. Add a GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 cross-lint block to pr-lint.sh mirroring the windows block (same flags, same lane scoping, skipped when the native target already matches), and update the three places that described the wrapper as two passes: engdocs/LINTING.md, engdocs/CI_CLEANUP_PLAN.md and the comment in main.yml. The darwin pass is compile-only on the Linux runner: no macOS runner, no change to the pr-lint platform column. Like the windows pass it is CGO_ENABLED=0, so darwin+cgo code stays outside its reach. * docs(linting): bump the Last reviewed marker alongside the pr-lint change
3 KiB
Linting Policy
Last reviewed: 2026-09-03
Freshness source: .golangci.yml, scripts/ci/pr-lint.sh, 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, and it runs in TWO LANES over the same pinned
golangci-lint v2.10.1 release and the same .golangci.yml. Each must pass with
zero issues in its own scope.
- The PR lane reports only what the PR introduces. Both of its jobs are
scoped to the diff against the merge base with
main: thelintjob passesonly-new-issues, andpr-lint-wrapperruns the repository-ownedci-pr-lintwrapper withBD_LINT_NEW_FROM_MERGE_BASE. A finding in code the PR did not touch does not block it. - The main lane sweeps the whole tree. Both jobs run unscoped on every push
to
main, so a finding that lands there reds main's own run rather than every open PR.
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:
make fmt-check;- golangci-lint with
.golangci.yml, readonly module downloads, a five-minute timeout, thegms_pure_gobuild tag, and--new-from-merge-basewhenBD_LINT_NEW_FROM_MERGE_BASEnames a ref; and - a second non-CGO Windows cross-lint pass, on the same scope, when the native host does not already cover that target; and
- a third non-CGO darwin (arm64) cross-lint pass, on the same scope, under the
same rule, so
//go:build darwinfiles are linted from the Linux runner.
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.ymlexclusion 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.
See CI_CLEANUP_PLAN.md for the full CI tier policy.
Future Work
- Periodically audit
.golangci.ymlexclusions and remove entries that are no longer needed.