diff --git a/.githooks/pre-commit b/.githooks/pre-commit index 4cc0d8586..b082d26f7 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -27,8 +27,12 @@ if [ -n "$staged_go_files" ]; then exit 1 fi - # Auto-format and re-stage - echo "$staged_go_files" | xargs gofmt -w + # Auto-format and re-stage, through the go.mod-pinned gofmt. A bare PATH + # gofmt belongs to the host toolchain, and on a host newer than the go + # directive it rewrites and re-stages files into a form CI's gofmt rejects + # -- silently, on every Go commit. See scripts/ci/gofmt-bin.sh. + gofmt_bin="$(./scripts/ci/gofmt-bin.sh)" + echo "$staged_go_files" | xargs "$gofmt_bin" -w echo "$staged_go_files" | xargs git add # Lint changed code with auto-fix; block on remaining issues. diff --git a/Makefile b/Makefile index 112447781..24b375ea2 100644 --- a/Makefile +++ b/Makefile @@ -367,10 +367,13 @@ endif install: check-up-to-date -# Format all Go files +# Format all Go files. +# Through the go.mod-pinned gofmt, never a bare PATH one: a newer local Go +# formats differently from CI, so a bare gofmt -w here rewrites files into a +# form CI's gofmt then rejects. See scripts/ci/gofmt-bin.sh. fmt: @echo "Formatting Go files..." - @gofmt -w . + @gofmt_bin="$$(./scripts/ci/gofmt-bin.sh)" && "$$gofmt_bin" -w . @echo "Done" # Check that all Go files are properly formatted (for CI) diff --git a/scripts/BUILD.bazel b/scripts/BUILD.bazel index f341b39e4..f65989465 100644 --- a/scripts/BUILD.bazel +++ b/scripts/BUILD.bazel @@ -86,3 +86,8 @@ exports_files( ["README.md"], visibility = ["//:__pkg__"], ) + +exports_files( + ["ci/gofmt-bin.sh"], + visibility = ["//scripts/prlintmake:__pkg__"], +) diff --git a/scripts/ci/fmt-check.sh b/scripts/ci/fmt-check.sh index b4a2626de..0a682a5a9 100755 --- a/scripts/ci/fmt-check.sh +++ b/scripts/ci/fmt-check.sh @@ -8,8 +8,27 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" cd "$REPO_ROOT" +# Which gofmt runs decides the verdict, so resolve it from go.mod instead of +# PATH and report it. Naming the binary here is what makes a toolchain skew +# legible as a skew, rather than as unformatted files in code no branch +# touched. See scripts/ci/gofmt-bin.sh. +GOFMT_BIN="$("$SCRIPT_DIR/gofmt-bin.sh")" + +describe_gofmt() { + local bin="$1" version="" + if command -v go >/dev/null 2>&1; then + version="$(go version "$bin" 2>/dev/null | awk '{ print $NF }')" + fi + if [[ -n "$version" ]]; then + printf '%s (%s)' "$version" "$bin" + else + printf '%s' "$bin" + fi +} + printf 'Checking Go formatting...\n' -if UNFORMATTED="$(gofmt -l .)"; then +printf 'Using gofmt %s\n' "$(describe_gofmt "$GOFMT_BIN")" +if UNFORMATTED="$("$GOFMT_BIN" -l .)"; then : else status=$? diff --git a/scripts/ci/gofmt-bin.sh b/scripts/ci/gofmt-bin.sh new file mode 100755 index 000000000..907cf1ad1 --- /dev/null +++ b/scripts/ci/gofmt-bin.sh @@ -0,0 +1,114 @@ +#!/usr/bin/env bash +# Resolve the gofmt that matches go.mod's pinned Go toolchain, and print its +# absolute path on stdout. +# +# gofmt's output is not stable across Go releases, so whichever binary runs +# decides the verdict. A bare `gofmt` on PATH belongs to whatever Go happens to +# be installed locally, and GOTOOLCHAIN=auto does not correct for that: the +# toolchain switch only ever moves UP to satisfy go.mod's requirements, never +# down. CI has no such freedom -- actions/setup-go installs exactly the go.mod +# version via go-version-file -- so a host running a newer Go formats +# differently from the gate that judges it. +# +# The failure is in the dangerous direction. The gate reds on files no branch +# touched, which reads as "main's lint is broken", and its own advice ("run +# make fmt") rewrites those files into a form CI's pinned gofmt then rejects. +# +# The repo's shell-side gofmt call sites resolve through here: +# scripts/ci/fmt-check.sh, the Makefile fmt target, and .githooks/pre-commit. +# Add new shell call sites to that list rather than reaching for a bare gofmt. +# +# One front door is deliberately not on that list, because it does not run from +# this repo's checkout: cmd/bd/preflight.go's "Formatting" doctor check execs a +# bare PATH `gofmt -l .` (and prescribes `gofmt -w .`) against whatever project +# the user points bd at, so it has no scripts/ci/ to call and is reporting on +# the developer's own environment rather than reproducing CI's verdict. Routing +# it through a resolver is a separate change. +# +# Set GOFMT to override the resolution entirely. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" + +warn() { + printf 'gofmt-bin: %s\n' "$*" >&2 +} + +# Falling back is safer than failing, but it must be LOUD: a silent fallback to +# the PATH binary is indistinguishable from a correct resolution, and it +# reintroduces exactly the skew this script exists to remove. +fallback() { + local reason="$1" path + if ! path="$(command -v gofmt 2>/dev/null)"; then + warn "$reason, and there is no gofmt on PATH either" + return 1 + fi + warn "$reason" + warn "falling back to $path, which may format differently from CI" + printf '%s\n' "$path" +} + +if [[ -n "${GOFMT:-}" ]]; then + # An override is honoured as given -- refusing it would defeat the escape + # hatch -- but say so here, or a typo surfaces as a "gofmt: not found" from + # whichever of the three call sites happened to run it. + if [[ ! -x "$GOFMT" ]]; then + warn "GOFMT is set to $GOFMT, which is not executable; using it anyway" + fi + printf '%s\n' "$GOFMT" + exit 0 +fi + +# The `toolchain` directive wins over the `go` directive when present: `go` is +# the floor promised to importers, `toolchain` is what this repo is actually +# built and formatted with. That precedence is not a choice made here -- it is +# the repo's, implemented at Makefile:85-90 (which exports GOTOOLCHAIN from the +# same pair for every make target) and in Go at scripts/bazel_policy_test.go's +# goModToolchainVersion. Reading `go` here would resolve a second, older +# toolchain than the one every other route formats with, and would miss the +# GOVERSION fast path below on every host that honours the directive. +# +# Match on the value, not just the field name: `toolchain default` is a legal +# directive meaning "no toolchain upgrade", and accepting it verbatim would set +# pinned=default, which is non-empty, so the `go` fallback below never fires and +# the resolution degrades to the bare PATH gofmt this script exists to replace. +# Requiring the literal `go` prefix is what the repo's other two readers of this +# pair do (Makefile:85's `s/^toolchain go//p`, scripts/bazel_policy_test.go's +# `^toolchain\s+go(\S+)\s*$`), so `default` falls through to the `go` directive. +pinned="$(awk '$1 == "toolchain" && $2 ~ /^go/ { sub(/^go/, "", $2); print $2; exit }' "$REPO_ROOT/go.mod")" +if [[ -z "$pinned" ]]; then + pinned="$(awk '$1 == "go" { print $2; exit }' "$REPO_ROOT/go.mod")" +fi +if [[ -z "$pinned" ]]; then + fallback "no toolchain or go directive in $REPO_ROOT/go.mod" + exit +fi + +# A "go 1.26" directive is legal; GOTOOLCHAIN names need the patch component. +if [[ "$pinned" =~ ^[0-9]+\.[0-9]+$ ]]; then + pinned="$pinned.0" +fi + +if ! command -v go >/dev/null 2>&1; then + fallback "go is not on PATH, so go.mod's go$pinned toolchain cannot be resolved" + exit +fi + +goroot="" +if [[ "$(go env GOVERSION 2>/dev/null)" == "go$pinned" ]]; then + # The CI case: the host go already is the pinned one. Read GOROOT directly + # rather than naming a GOTOOLCHAIN, so nothing is fetched on a machine that + # has nothing to fetch. + goroot="$(go env GOROOT 2>/dev/null || true)" +elif ! goroot="$(GOTOOLCHAIN="go$pinned" go env GOROOT 2>/dev/null)"; then + goroot="" +fi + +if [[ -z "$goroot" || ! -x "$goroot/bin/gofmt" ]]; then + fallback "could not resolve a gofmt from go.mod's go$pinned toolchain" + exit +fi + +printf '%s\n' "$goroot/bin/gofmt" diff --git a/scripts/prlintmake/BUILD.bazel b/scripts/prlintmake/BUILD.bazel index fe68f5879..b0817b761 100644 --- a/scripts/prlintmake/BUILD.bazel +++ b/scripts/prlintmake/BUILD.bazel @@ -2,7 +2,14 @@ load("@rules_go//go:def.bzl", "go_test") go_test( name = "prlintmake_test", - srcs = ["prlintmake_test.go"], - data = ["//scripts:ci/fmt-check.sh"], + srcs = [ + "gofmtbin_test.go", + "prlintmake_test.go", + ], + data = [ + "//:go.mod", + "//scripts:ci/fmt-check.sh", + "//scripts:ci/gofmt-bin.sh", + ], deps = ["//internal/testutil/bazeltest"], ) diff --git a/scripts/prlintmake/gofmtbin_test.go b/scripts/prlintmake/gofmtbin_test.go new file mode 100644 index 000000000..d9319842d --- /dev/null +++ b/scripts/prlintmake/gofmtbin_test.go @@ -0,0 +1,184 @@ +package prlintmake + +import ( + "bufio" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" +) + +// The regression tests for be-gx8. +// +// gofmt's output is not stable across Go releases, and the repo's formatting +// gate is judged by whichever binary runs. CI installs exactly go.mod's version +// (actions/setup-go with go-version-file), so any resolution that can land on a +// different Go silently disagrees with the gate that blocks merges -- and the +// gate's own advice, "run make fmt", then rewrites files into a form CI +// rejects. +// +// These pin the resolution itself rather than fmt-check.sh's reporting, because +// the shipped bug was in the resolution: a bare `gofmt` reached PATH, and every +// output assertion around it stayed green. + +func TestGofmtBinMatchesGoModToolchain(t *testing.T) { + goBin := testGo(t) + want := "go" + goModToolchainVersion(t) + + resolved, stderr := runGofmtBin(t, nil, nil) + + output, err := exec.Command(goBin, "version", resolved).CombinedOutput() + if err != nil { + t.Fatalf("go version %s: %v\n%s\nresolver stderr:\n%s", resolved, err, output, stderr) + } + fields := strings.Fields(string(output)) + if len(fields) == 0 { + t.Fatalf("go version %s printed no fields\nresolver stderr:\n%s", resolved, stderr) + } + got := fields[len(fields)-1] + if got != want { + t.Fatalf("gofmt-bin.sh resolved %s (built with %s), want a %s gofmt.\n"+ + "CI and every make target format with the toolchain go.mod selects, "+ + "so this host's `make fmt` would rewrite files CI then rejects.\n"+ + "resolver stderr:\n%s", + resolved, got, want, stderr) + } +} + +func TestGofmtBinIgnoresPathGofmt(t *testing.T) { + testGo(t) + bash := testBash(t) + shimDir := filepath.Join(t.TempDir(), "path shims") + if err := os.MkdirAll(shimDir, 0o755); err != nil { + t.Fatal(err) + } + shim := filepath.Join(shimDir, "gofmt") + writeShellExecutable(t, bash, shim, "#!/usr/bin/env bash\nexit 0\n") + + path := shimDir + string(os.PathListSeparator) + os.Getenv("PATH") + resolved, stderr := runGofmtBin(t, map[string]string{"PATH": path}, nil) + + if resolved == shellVisiblePath(shim) { + t.Fatalf("gofmt-bin.sh returned the PATH shim %s; it must resolve from "+ + "go.mod's toolchain instead.\nresolver stderr:\n%s", resolved, stderr) + } +} + +func TestGofmtBinHonorsGOFMTOverride(t *testing.T) { + want := shellVisiblePath(filepath.Join(t.TempDir(), "explicit gofmt")) + + resolved, stderr := runGofmtBin(t, map[string]string{"GOFMT": want}, nil) + + if resolved != want { + t.Fatalf("gofmt-bin.sh = %q, want the GOFMT override %q\nresolver stderr:\n%s", + resolved, want, stderr) + } +} + +// runGofmtBin runs scripts/ci/gofmt-bin.sh and returns its stdout (the resolved +// path) and stderr separately. Fallback warnings go to stderr, so keeping them +// apart is what lets a failure report why the resolution went the way it did. +func runGofmtBin(t *testing.T, overrides map[string]string, args []string) (string, string) { + t.Helper() + bash := testBash(t) + env := map[string]string{ + "BASH_ENV": "", + "BASHOPTS": "", + "ENV": "", + "GOFMT": "", + "LANG": "C", + "LC_ALL": "C", + "SHELLOPTS": "", + } + for key, value := range overrides { + env[key] = value + } + // GOFMT is exported empty rather than deleted from the map. environment() + // starts from the ambient environment, so deleting the key here would leave + // an ambient GOFMT in place -- and that short-circuits the very resolution + // these tests exist to pin, failing one of them with a message blaming the + // script and passing the other vacuously. gofmt-bin.sh reads GOFMT with + // [[ -n "${GOFMT:-}" ]], so empty already is its "not set" case, and the + // override test stays distinguishable by setting a non-empty value. + + script := shellVisiblePath(filepath.Join(sourceRepoRoot(), "scripts", "ci", "gofmt-bin.sh")) + cmd := exec.Command(bash, append([]string{"--noprofile", "--norc", "--", script}, args...)...) + cmd.Dir = sourceRepoRoot() + cmd.Env = environment(env) + var stderr strings.Builder + cmd.Stderr = &stderr + stdout, err := cmd.Output() + if err != nil { + t.Fatalf("gofmt-bin.sh failed: %v\nstdout:\n%s\nstderr:\n%s", err, stdout, stderr.String()) + } + return strings.TrimSpace(normalizeNewlines(string(stdout))), stderr.String() +} + +// goModToolchainVersion returns the Go version go.mod selects, in GOTOOLCHAIN +// form: the toolchain directive when present, otherwise the go directive, with +// the patch component a bare "go 1.26" directive omits. +// +// Toolchain-first is the repo's precedence, not this test's: Makefile:85-90 +// exports GOTOOLCHAIN from the same pair for every make target, and +// scripts/bazel_policy_test.go's goModToolchainVersion is the same rule in Go. +// `go` is the floor promised to importers; `toolchain` is what this repo is +// built and formatted with, so it is what the formatting gate must agree with. +func goModToolchainVersion(t *testing.T) string { + t.Helper() + file, err := os.Open(filepath.Join(sourceRepoRoot(), "go.mod")) + if err != nil { + t.Fatal(err) + } + defer file.Close() + + goDirective := "" + scanner := bufio.NewScanner(file) + for scanner.Scan() { + fields := strings.Fields(scanner.Text()) + if len(fields) != 2 { + continue + } + switch fields[0] { + case "toolchain": + // `toolchain default` is legal and names no version, so it must fall + // through to the `go` directive exactly as gofmt-bin.sh does -- the + // script's awk requires the same literal `go` prefix. Returning the + // bare value here would make this helper agree with a buggy resolver + // instead of detecting it. + if version, ok := strings.CutPrefix(fields[1], "go"); ok { + return withPatchComponent(version) + } + case "go": + if goDirective == "" { + goDirective = fields[1] + } + } + } + if err := scanner.Err(); err != nil { + t.Fatal(err) + } + if goDirective != "" { + return withPatchComponent(goDirective) + } + t.Fatal("no toolchain or go directive in go.mod") + return "" +} + +// withPatchComponent returns a GOTOOLCHAIN-shaped version: names there carry +// the patch component that a bare "go 1.26" directive is allowed to omit. +func withPatchComponent(version string) string { + if strings.Count(version, ".") == 1 { + return version + ".0" + } + return version +} + +func testGo(t *testing.T) string { + t.Helper() + path, err := exec.LookPath("go") + if err != nil { + t.Skipf("go is not on PATH: %v", err) + } + return path +} diff --git a/scripts/prlintmake/prlintmake_test.go b/scripts/prlintmake/prlintmake_test.go index 45e6bad3c..7385710c5 100644 --- a/scripts/prlintmake/prlintmake_test.go +++ b/scripts/prlintmake/prlintmake_test.go @@ -13,22 +13,23 @@ import ( ) func TestFmtCheckClean(t *testing.T) { - output, err := runFmtCheck(t, "exit 0\n") + gofmt, output, err := runFmtCheck(t, "exit 0\n") if err != nil { t.Fatalf("fmt-check failed: %v\n%s", err, output) } - want := "Checking Go formatting...\nAll Go files are properly formatted\n" + want := "Checking Go formatting...\nUsing gofmt " + gofmt + "\nAll Go files are properly formatted\n" if output != want { t.Fatalf("output = %q, want %q", output, want) } } func TestFmtCheckReportsUnformattedFiles(t *testing.T) { - output, err := runFmtCheck(t, "printf '%s\\n' cmd/bd/main.go internal/config/config.go\n") + gofmt, output, err := runFmtCheck(t, "printf '%s\\n' cmd/bd/main.go internal/config/config.go\n") if got := processExitCode(err); got != 1 { t.Fatalf("exit = %d, want 1; error=%v\n%s", got, err, output) } want := "Checking Go formatting...\n" + + "Using gofmt " + gofmt + "\n" + "The following files are not properly formatted:\n" + "cmd/bd/main.go\n" + "internal/config/config.go\n\n" + @@ -38,8 +39,31 @@ func TestFmtCheckReportsUnformattedFiles(t *testing.T) { } } +// TestFmtCheckReportsGofmtVersion pins describe_gofmt's version-bearing arm, +// the " ()" form. +// +// The cases above inject a bash script, for which `go version` errors and the +// version is always empty, so only the bare-path else arm is exercised there -- +// deleting the whole version block leaves all three of them green. The version +// is the half that makes a toolchain skew legible as a skew, which is the whole +// justification for the reporting change, so it needs a real Go-built binary. +func TestFmtCheckReportsGofmtVersion(t *testing.T) { + goBin := testGo(t) + shim := buildNoopGoBinary(t, goBin, "gofmt") + want := goBuildVersion(t, goBin, shim) + + output, err := runFmtCheckWithGofmt(t, shim) + if err != nil { + t.Fatalf("fmt-check failed: %v\n%s", err, output) + } + line := "Using gofmt " + want + " (" + shim + ")\n" + if !strings.Contains(output, line) { + t.Fatalf("missing %q in output:\n%s", line, output) + } +} + func TestFmtCheckPreservesGofmtFailure(t *testing.T) { - output, err := runFmtCheck(t, "printf 'synthetic gofmt failure\\n' >&2\nexit 42\n") + _, output, err := runFmtCheck(t, "printf 'synthetic gofmt failure\\n' >&2\nexit 42\n") if got := processExitCode(err); got != 42 { t.Fatalf("exit = %d, want 42; error=%v\n%s", got, err, output) } @@ -54,7 +78,14 @@ func TestFmtCheckPreservesGofmtFailure(t *testing.T) { } } -func runFmtCheck(t *testing.T, gofmtBody string) (string, error) { +// runFmtCheck runs scripts/ci/fmt-check.sh against a gofmt shim with the given +// body, and returns the shim path fmt-check.sh is expected to report. +// +// The shim is injected through GOFMT rather than PATH. fmt-check.sh deliberately +// ignores a PATH gofmt -- that is the whole of be-gx8 -- so a PATH shim would be +// silently bypassed and these tests would grade the real toolchain instead of +// the case they name. TestGofmtBinIgnoresPathGofmt covers the resolution itself. +func runFmtCheck(t *testing.T, gofmtBody string) (string, string, error) { t.Helper() bash := testBash(t) testRoot := t.TempDir() @@ -62,12 +93,19 @@ func runFmtCheck(t *testing.T, gofmtBody string) (string, error) { if err := os.MkdirAll(shimDir, 0o755); err != nil { t.Fatal(err) } - writeShellExecutable(t, bash, filepath.Join(shimDir, "gofmt"), "#!/usr/bin/env bash\nset -euo pipefail\n"+gofmtBody) + shim := filepath.Join(shimDir, "gofmt") + writeShellExecutable(t, bash, shim, "#!/usr/bin/env bash\nset -euo pipefail\n"+gofmtBody) + gofmt := shellVisiblePath(shim) - path := shimDir + string(os.PathListSeparator) + os.Getenv("PATH") - if runtime.GOOS == "windows" { - path = msysPath(shimDir) + ":/usr/bin:/bin" - } + output, err := runFmtCheckWithGofmt(t, gofmt) + return gofmt, output, err +} + +// runFmtCheckWithGofmt runs scripts/ci/fmt-check.sh with GOFMT pointing at an +// already-built binary, and returns its combined output. +func runFmtCheckWithGofmt(t *testing.T, gofmt string) (string, error) { + t.Helper() + bash := testBash(t) cmd := exec.Command( bash, "--noprofile", @@ -80,15 +118,55 @@ func runFmtCheck(t *testing.T, gofmtBody string) (string, error) { "BASH_ENV": "", "BASHOPTS": "", "ENV": "", + "GOFMT": gofmt, "LANG": "C", "LC_ALL": "C", - "PATH": path, "SHELLOPTS": "", }) output, err := cmd.CombinedOutput() return normalizeNewlines(string(output)), err } +// buildNoopGoBinary compiles a do-nothing program under the given name and +// returns its shell-visible path. `go version` reports the toolchain that built +// it, which is what the caller needs and what a shell shim can never provide. +func buildNoopGoBinary(t *testing.T, goBin, name string) string { + t.Helper() + dir := t.TempDir() + write := func(base, content string) { + if err := os.WriteFile(filepath.Join(dir, base), []byte(content), 0o644); err != nil { + t.Fatal(err) + } + } + write("go.mod", "module noopgobinary\n") + write("main.go", "package main\n\nfunc main() {}\n") + + if runtime.GOOS == "windows" { + name += ".exe" + } + binary := filepath.Join(dir, name) + cmd := exec.Command(goBin, "build", "-o", binary, ".") + cmd.Dir = dir + if output, err := cmd.CombinedOutput(); err != nil { + t.Fatalf("go build a no-op %s: %v\n%s", name, err, output) + } + return shellVisiblePath(binary) +} + +// goBuildVersion returns the "goX.Y.Z" that `go version ` reports. +func goBuildVersion(t *testing.T, goBin, binary string) string { + t.Helper() + output, err := exec.Command(goBin, "version", binary).CombinedOutput() + if err != nil { + t.Fatalf("go version %s: %v\n%s", binary, err, output) + } + fields := strings.Fields(string(output)) + if len(fields) == 0 { + t.Fatalf("go version %s printed no fields", binary) + } + return fields[len(fields)-1] +} + func writeShellExecutable(t *testing.T, bash, path, body string) { t.Helper() if err := os.WriteFile(path, []byte(strings.ReplaceAll(body, "\r\n", "\n")), 0o755); err != nil {