beads/scripts/pr-lint/main.go
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

430 lines
13 KiB
Go

// pr-lint runs the repository's canonical Go lint passes without requiring
// Make or Bash. The supported scripts/ci/pr-lint.sh entrypoint delegates here,
// and bd preflight runs this checkout-owned command for the Beads source tree.
// The standalone workflow lint action and pre-commit hook do not call this
// driver; their scope and behavior still differ.
package main
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"time"
)
const (
beadsBuildTags = "gms_pure_go"
goEnvTimeout = 30 * time.Second
lintProcessTimeout = 6 * time.Minute
lintReportedTimeout = "5m"
)
// defaultLintTargets is BD_LINT_TARGETS' value when unset or empty: the
// no-argument usage contract (`make ci-pr-lint`, `bd preflight`) must keep
// running all three passes locally and from the pre-commit hook.
var defaultLintTargets = []string{"native", "windows", "darwin"}
type commandSpec struct {
name string
args []string
dir string
env []string
}
type processRunner interface {
lookPath(string) (string, error)
output(context.Context, commandSpec) ([]byte, []byte, error)
run(context.Context, commandSpec, io.Writer, io.Writer) error
}
type osProcessRunner struct{}
func (osProcessRunner) lookPath(name string) (string, error) {
return exec.LookPath(name)
}
func (osProcessRunner) output(ctx context.Context, spec commandSpec) ([]byte, []byte, error) {
cmd := exec.CommandContext(ctx, spec.name, spec.args...)
cmd.Dir = spec.dir
cmd.Env = spec.env
var stdout bytes.Buffer
var stderr bytes.Buffer
cmd.Stdout = &stdout
cmd.Stderr = &stderr
err := cmd.Run()
return stdout.Bytes(), stderr.Bytes(), err
}
func (osProcessRunner) run(ctx context.Context, spec commandSpec, stdout, stderr io.Writer) error {
cmd := exec.CommandContext(ctx, spec.name, spec.args...) //nolint:gosec // G702: executable is PATH-resolved; argv positions are assembled internally, and the env merge-base remains one unshelled argv value.
cmd.Dir = spec.dir
cmd.Env = spec.env
cmd.Stdout = stdout
cmd.Stderr = stderr
return cmd.Run()
}
type nativeGoEnvironment struct {
GOOS string `json:"GOOS"`
CGOEnabled string `json:"CGO_ENABLED"`
GOROOT string `json:"GOROOT"`
GOVERSION string `json:"GOVERSION"`
}
func main() {
dir, err := os.Getwd()
if err != nil {
fmt.Fprintf(os.Stderr, "determine repository root: %v\n", err)
os.Exit(1)
}
os.Exit(run(os.Args[1:], dir, os.Environ(), os.Stdout, os.Stderr, osProcessRunner{}))
}
func run(args []string, dir string, environ []string, stdout, stderr io.Writer, runner processRunner) int {
if len(args) != 0 {
fmt.Fprintln(stderr, "usage: go run -mod=readonly -tags=gms_pure_go ./scripts/pr-lint")
return 2
}
rawTargets, _ := environmentValue(environ, "BD_LINT_TARGETS", runtime.GOOS == "windows")
targets, err := parseLintTargets(rawTargets)
if err != nil {
fmt.Fprintln(stderr, err)
return 2
}
runNative := containsTarget(targets, "native")
runWindows := containsTarget(targets, "windows")
runDarwin := containsTarget(targets, "darwin")
goPath, err := runner.lookPath("go")
if err != nil {
fmt.Fprintf(stderr, "Go toolchain not found in PATH: %v\n", err)
return 1
}
lintPath, err := runner.lookPath("golangci-lint")
if err != nil {
fmt.Fprintf(stderr, "golangci-lint not found in PATH: %v\n", err)
return 1
}
effectiveEnv := buildEnvironment(environ, runtime.GOOS == "windows")
probeCtx, cancel := context.WithTimeout(context.Background(), goEnvTimeout)
defer cancel()
native, code := readNativeGoEnvironment(probeCtx, dir, effectiveEnv, goPath, stderr, runner)
if code != 0 {
return code
}
mergeBase, _ := environmentValue(effectiveEnv, "BD_LINT_NEW_FROM_MERGE_BASE", runtime.GOOS == "windows")
argsForLint := lintArgs(mergeBase)
skipWindows := native.GOOS == "windows" && native.CGOEnabled == "0"
windowsEnv := setEnvironment(effectiveEnv, map[string]string{
"CGO_ENABLED": "0",
"GOARCH": "amd64",
"GOOS": "windows",
"GOWORK": "off",
}, runtime.GOOS == "windows")
// Files guarded by //go:build darwin (and the !windows && !linux fallbacks)
// are invisible to the Linux runner too, so a darwin-only finding must fail
// the PR here instead of on the next maintainer's laptop.
skipDarwin := native.GOOS == "darwin" && native.CGOEnabled == "0"
darwinEnv := setEnvironment(effectiveEnv, map[string]string{
"CGO_ENABLED": "0",
"GOARCH": "arm64",
"GOOS": "darwin",
"GOWORK": "off",
}, runtime.GOOS == "windows")
nativeEnv := effectiveEnv
if runtime.GOOS == "windows" {
nativeEnv = preferSelectedGo(probeCtx, dir, effectiveEnv, native, stderr, runner)
if runWindows && !skipWindows {
// GOWORK=off can select a different toolchain. Probe the original
// Go executable and PATH again, before either lint pass starts.
selected, code := readNativeGoEnvironment(probeCtx, dir, windowsEnv, goPath, stderr, runner)
if code == 0 {
windowsEnv = preferSelectedGo(probeCtx, dir, windowsEnv, selected, stderr, runner)
}
}
if runDarwin && !skipDarwin {
selected, code := readNativeGoEnvironment(probeCtx, dir, darwinEnv, goPath, stderr, runner)
if code == 0 {
darwinEnv = preferSelectedGo(probeCtx, dir, darwinEnv, selected, stderr, runner)
}
}
}
cancel() // All discovery shares the existing 30-second probe budget.
if runNative {
if code := runLintPass(
"golangci-lint (native)",
commandSpec{name: lintPath, args: argsForLint, dir: dir, env: nativeEnv},
stdout,
stderr,
runner,
); code != 0 {
return code
}
}
if runWindows {
if skipWindows {
fmt.Fprintln(stdout, "==> golangci-lint (windows/amd64, non-CGO) already covered by native pass")
} else if code := runLintPass(
"golangci-lint (windows/amd64, non-CGO)",
commandSpec{name: lintPath, args: argsForLint, dir: dir, env: windowsEnv},
stdout,
stderr,
runner,
); code != 0 {
return code
}
}
if !runDarwin {
return 0
}
if skipDarwin {
fmt.Fprintln(stdout, "==> golangci-lint (darwin/arm64, non-CGO) already covered by native pass")
return 0
}
return runLintPass(
"golangci-lint (darwin/arm64, non-CGO)",
commandSpec{name: lintPath, args: argsForLint, dir: dir, env: darwinEnv},
stdout,
stderr,
runner,
)
}
// parseLintTargets parses BD_LINT_TARGETS: a comma-separated list of
// "native", "windows" and "darwin", in any order and with any repetition.
// An empty value (the variable unset, or set to only whitespace and commas)
// selects all three, so the no-argument usage contract is unchanged. Any
// other token is an error: callers exit 2, matching the usage-error exit
// code above.
func parseLintTargets(raw string) ([]string, error) {
var targets []string
for _, field := range strings.Split(raw, ",") {
target := strings.TrimSpace(field)
if target == "" {
continue
}
if !containsTarget(defaultLintTargets, target) {
return nil, fmt.Errorf("BD_LINT_TARGETS: unknown target %q (want a comma list of native, windows, darwin)", target)
}
targets = append(targets, target)
}
if len(targets) == 0 {
return defaultLintTargets, nil
}
return targets, nil
}
func containsTarget(targets []string, target string) bool {
for _, candidate := range targets {
if candidate == target {
return true
}
}
return false
}
func readNativeGoEnvironment(
ctx context.Context,
dir string,
environ []string,
goPath string,
stderr io.Writer,
runner processRunner,
) (nativeGoEnvironment, int) {
spec := commandSpec{
name: goPath,
args: []string{"env", "-json", "GOOS", "CGO_ENABLED", "GOROOT", "GOVERSION"},
dir: dir,
env: environ,
}
output, commandStderr, err := runner.output(ctx, spec)
writeDiagnostic(stderr, commandStderr)
if err != nil {
writeDiagnostic(stderr, output)
if errors.Is(ctx.Err(), context.DeadlineExceeded) {
fmt.Fprintf(stderr, "go env exceeded %s\n", goEnvTimeout)
return nativeGoEnvironment{}, 1
}
fmt.Fprintf(stderr, "inspect native Go target: %v\n", err)
return nativeGoEnvironment{}, processExitCode(err)
}
var native nativeGoEnvironment
if err := json.Unmarshal(output, &native); err != nil {
fmt.Fprintf(stderr, "parse native Go target: %v\n", err)
return nativeGoEnvironment{}, 1
}
if native.GOOS == "" || native.CGOEnabled == "" {
fmt.Fprintf(stderr, "go env returned an incomplete target: GOOS=%q CGO_ENABLED=%q\n", native.GOOS, native.CGOEnabled)
return nativeGoEnvironment{}, 1
}
return native, 0
}
// On Windows, Go auto-selection starts another process instead of replacing
// itself. Prefer the selected SDK for lint so cancellation reaches that Go
// process directly. This is not general descendant-process containment.
func preferSelectedGo(ctx context.Context, dir string, environ []string, selected nativeGoEnvironment, stderr io.Writer, runner processRunner) []string {
if !filepath.IsAbs(selected.GOROOT) || selected.GOVERSION == "" {
return environ
}
bin := filepath.Join(selected.GOROOT, "bin")
if strings.ContainsRune(bin, os.PathListSeparator) {
fmt.Fprintln(stderr, "Windows lint: retaining original Go PATH; selected SDK directory contains a PATH separator")
return environ
}
// GOROOT can describe a source-only or custom installation. Verify the
// candidate without allowing it to switch toolchains during this probe.
output, diagnostic, err := runner.output(ctx, commandSpec{
name: filepath.Join(bin, "go.exe"),
args: []string{"env", "-json", "GOROOT", "GOVERSION"},
dir: dir,
env: setEnvironment(environ, map[string]string{"GOTOOLCHAIN": "local"}, true),
})
writeDiagnostic(stderr, diagnostic)
var candidate nativeGoEnvironment
if err != nil || json.Unmarshal(output, &candidate) != nil ||
candidate.GOVERSION != selected.GOVERSION ||
!strings.EqualFold(filepath.Clean(candidate.GOROOT), filepath.Clean(selected.GOROOT)) {
fmt.Fprintln(stderr, "Windows lint: retaining original Go PATH; selected SDK could not be verified")
return environ
}
path, _ := environmentValue(environ, "PATH", true)
return setEnvironment(environ, map[string]string{"PATH": bin + string(os.PathListSeparator) + path}, true)
}
func writeDiagnostic(destination io.Writer, output []byte) {
if len(output) == 0 {
return
}
_, _ = destination.Write(output)
if output[len(output)-1] != '\n' {
fmt.Fprintln(destination)
}
}
func runLintPass(label string, spec commandSpec, stdout, stderr io.Writer, runner processRunner) int {
fmt.Fprintf(stdout, "==> %s\n", label)
ctx, cancel := context.WithTimeout(context.Background(), lintProcessTimeout)
defer cancel()
err := runner.run(ctx, spec, stdout, stderr)
if err == nil {
fmt.Fprintf(stdout, "<== %s succeeded\n", label)
return 0
}
if errors.Is(ctx.Err(), context.DeadlineExceeded) {
fmt.Fprintf(stderr, "<== %s exceeded %s\n", label, lintProcessTimeout)
return 1
}
fmt.Fprintf(stderr, "<== %s failed: %v\n", label, err)
return processExitCode(err)
}
func lintArgs(mergeBase string) []string {
args := []string{
"run",
"--config=.golangci.yml",
"--modules-download-mode=readonly",
"--timeout=" + lintReportedTimeout,
"--build-tags=" + beadsBuildTags,
}
if mergeBase != "" {
args = append(args, "--new-from-merge-base="+mergeBase)
}
return append(args, "./...")
}
func buildEnvironment(environ []string, caseInsensitive bool) []string {
cgoEnabled, found := environmentValue(environ, "CGO_ENABLED", caseInsensitive)
if !found || cgoEnabled == "" {
cgoEnabled = "1"
}
goFlags, _ := environmentValue(environ, "GOFLAGS", caseInsensitive)
// Match .buildflags: an appended -tags value overrides an inherited bare-Go
// -tags value rather than merging tag lists.
if !strings.Contains(goFlags, beadsBuildTags) {
if goFlags != "" {
goFlags += " "
}
goFlags += "-tags=" + beadsBuildTags
}
return setEnvironment(environ, map[string]string{
"BEADS_BUILD_TAGS": beadsBuildTags,
"CGO_ENABLED": cgoEnabled,
"GOFLAGS": goFlags,
}, caseInsensitive)
}
func setEnvironment(environ []string, overrides map[string]string, caseInsensitive bool) []string {
result := make([]string, 0, len(environ)+len(overrides))
for _, entry := range environ {
key, _, ok := strings.Cut(entry, "=")
if !ok {
result = append(result, entry)
continue
}
if containsEnvironmentKey(overrides, key, caseInsensitive) {
continue
}
result = append(result, entry)
}
for key, value := range overrides {
result = append(result, key+"="+value)
}
return result
}
func environmentValue(environ []string, wanted string, caseInsensitive bool) (string, bool) {
for index := len(environ) - 1; index >= 0; index-- {
key, value, ok := strings.Cut(environ[index], "=")
if ok && environmentKeysEqual(key, wanted, caseInsensitive) {
return value, true
}
}
return "", false
}
func containsEnvironmentKey(values map[string]string, wanted string, caseInsensitive bool) bool {
for key := range values {
if environmentKeysEqual(key, wanted, caseInsensitive) {
return true
}
}
return false
}
func environmentKeysEqual(left, right string, caseInsensitive bool) bool {
if caseInsensitive {
return strings.ToLower(left) == strings.ToLower(right)
}
return left == right
}
func processExitCode(err error) int {
if err == nil {
return 0
}
var exitErr interface{ ExitCode() int }
if errors.As(err, &exitErr) && exitErr.ExitCode() >= 0 {
return exitErr.ExitCode()
}
return 1
}