beads/scripts/internal/testbash/resolver.go
ecuthiell 4183fa0509
test(scripts): resolve Git Bash explicitly on Windows (#5727) (#5730)
* test(scripts): resolve Git Bash explicitly on Windows

Add one test-only resolver that positively identifies Git Bash on Windows and use it in the doc-freshness and PR-preflight fixtures. Preserve ordinary PATH resolution on non-Windows hosts and leave the remaining #5727 callers for follow-up.

Part of #5727.

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>

* docs(testbash): state exact probe completion requirements

Document that capability scripts must be silent on both streams and reach
the sentinel epilogue without exiting the shell. Remove redundant startup
environment entries already stripped by the shared resolver.

Bead: saa-cgh.13
Agent-Signature: unknown-model/unknown-reasoning

* chore(bazel): sync BUILD files for scripts/internal/testbash

`make bazel-sync` output for the new `scripts/internal/testbash` package,
regenerated with `bazel run //:gazelle`:

- add the generated `scripts/internal/testbash/BUILD.bazel`
  (`go_library testbash` + `go_test testbash_test`)
- add `//scripts/internal/testbash` to `//scripts:scripts_test` deps

Without this, `bazel.yml` fails two ways:

1. `bazel test //... --config=integration` (bazel.yml:592) is a hard compile
   failure — `compilepkg: missing strict dependencies` for the
   `scripts/internal/testbash` import in both `check_doc_freshness_test.go`
   and `pr_preflight_test.go`. The default config builds clean because both
   files are `//go:build integration`, so only the integration lane sees it.
2. The `BUILD files in sync` step (bazel.yml:310) exits 1 on the
   `make bazel-sync` drift.

`make bazel-sync-check` (go_srcs globs only) and the repo's own
`TestBazel*` policy tests are both blind to this and pass either way.

* fix(testbash): pin the sanitization contract and split probe diagnostics

Maintainer review fixups for the adopt-pr review of PR #5730 (iteration 1,
synthesis approve / no blocker or major; all items were non-gating).

Finding 1 (minor, Test Evidence Quality) — the sanitization test's oracle was
the predicate under test. TestSanitizedEnvironmentRemovesBashAuthorityControls
validated the sanitized result by calling isBashAuthorityControl, the very
predicate sanitizedEnvironment filters with, so filter and oracle weakened in
lockstep and the assertion could not fail for any definition of the predicate.
It now asserts against the test's own controls literal and checks the
BASH_FUNC_ prefix class separately, pinning both the filter plumbing and the
key list. Proven with a three-arm control: fixed test + real predicate passes;
fixed test + a full `return false` neuter of isBashAuthorityControl now FAILS
(it previously passed); the original test + the same neuter still passes, so the
new failure is caused by this change and not by the mutation itself.

Finding 4 (nit, Debuggability) — a chatty-but-successful probe reported the
sentinel as unreached while its own quoted payload contained it. runProbe now
branches on strings.HasSuffix and emits a distinct "completed but wrote
unexpected output before the execution sentinel" message quoting only the stray
payload. The three existing assertions on "without the exact execution
sentinel" all cover cases whose output is empty (early exit, noexec), so none
of them can take the new branch; verified by execution.

Finding 3 (nit, Debuggability) — Probe's doc comment named only the three Bash
control classes while the implementation also strips GIT_EXEC_PATH. The comment
now documents Bash and Git authority controls explicitly.

Finding 2 (minor, Test Evidence Quality) is deliberately NOT taken here and
remains a non-gating follow-up. Its primary remedy — adding
./scripts/internal/testbash to the windows-latest leg — would execute four
//go:build windows tests that have never run on any lane, and the synthesis's
own Unresolved Uncertainty concerns MSYS2 PATH handling in exactly this
package's validateCandidate, which is not verifiable from Linux; a first-ever
execution that reds pr-preflight-platforms is not the "nearby, cheap, low-risk"
cleanup the operator contract allows. Its fallback arm only typechecks and
would edit repo-wide CI outside this PR's payload. Note that finding 1 reduces
finding 2's severity: the sanitization contract is now pinned on every Linux
lane instead of only incidentally on Windows.

Validation: go test ./scripts/internal/testbash ok; go test -run
'^TestDocFreshness|^TestPRPreflight' ./scripts ok, and ok again with
-tags=integration,gms_pure_go; gofmt clean; go vet clean; CGO_ENABLED=0
GOOS=windows go vet ./scripts/... and go build ./scripts/... both rc=0;
git diff --check clean. No files added or removed, so the generated
BUILD.bazel srcs are unchanged.

Contributor commits are untouched.

---------

Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
2026-09-30 15:50:28 -07:00

142 lines
4.4 KiB
Go

// Package testbash resolves the Bash interpreter used by repository script
// tests. On Windows, callers receive a positively identified Git Bash rather
// than whichever bash launcher happens to appear first on PATH.
package testbash
import (
"errors"
"fmt"
"os/exec"
"runtime"
"strings"
)
// OverrideEnv names the optional absolute Git Bash override used on Windows.
const OverrideEnv = "BEADS_TEST_GIT_BASH"
const probeSuccess = "BEADS_TEST_BASH_PROBE_SUCCESS_7B75D507"
// ConfigurationError reports an invalid explicit test configuration. Callers
// may distinguish it from an unavailable optional prerequisite.
type ConfigurationError struct {
err error
}
func (e *ConfigurationError) Error() string {
return e.err.Error()
}
func (e *ConfigurationError) Unwrap() error {
return e.err
}
// IsConfigurationError reports whether err was caused by an invalid explicit
// test configuration.
func IsConfigurationError(err error) bool {
var configurationError *ConfigurationError
return errors.As(err, &configurationError)
}
func configurationErrorf(format string, args ...any) error {
return &ConfigurationError{err: fmt.Errorf(format, args...)}
}
// Resolve returns the Bash interpreter for a repository script test.
func Resolve() (string, error) {
return resolve()
}
// Probe verifies a caller-specific Bash capability under an environment
// derived from the supplied entries. Bash and Git authority controls are
// removed before the probe runs: Bash startup, option, and exported-function
// controls, and GIT_EXEC_PATH.
// The script must produce no stdout or stderr and must not exit the shell,
// even with status zero: successful probes must reach the sentinel epilogue.
func Probe(path, capability, script string, environment []string) error {
return runProbe(path, capability, script, sanitizedEnvironment(environment))
}
func runProbe(path, capability, script string, environment []string) error {
probeScript := script + `
beads_testbash_probe_status=$?
if [ "$beads_testbash_probe_status" -eq 0 ]; then
builtin printf '%s' '` + probeSuccess + `'
fi
exit "$beads_testbash_probe_status"
`
//nolint:gosec // G702: this test-only API intentionally executes its caller-selected Bash interpreter.
cmd := exec.Command(path, "--noprofile", "--norc", "-c", probeScript)
cmd.Env = environment
output, err := cmd.CombinedOutput()
if err != nil {
return fmt.Errorf("%s probe: %w: %s", capability, err, strings.TrimSpace(string(output)))
}
if rendered := string(output); rendered != probeSuccess {
// The body did reach the sentinel epilogue but wrote something first;
// reporting that as "sentinel not reached" misdirects the reader, whose
// own quoted payload visibly contains the sentinel.
if strings.HasSuffix(rendered, probeSuccess) {
return fmt.Errorf(
"%s probe completed but wrote unexpected output before the execution sentinel: %q",
capability,
strings.TrimSuffix(rendered, probeSuccess),
)
}
return fmt.Errorf(
"%s probe exited successfully without the exact execution sentinel: %q",
capability,
rendered,
)
}
return nil
}
func sanitizedEnvironment(entries []string, overrides ...string) []string {
overrideKeys := make(map[string]struct{}, len(overrides))
safeOverrides := make([]string, 0, len(overrides))
for _, entry := range overrides {
key, _, ok := strings.Cut(entry, "=")
if !ok {
continue
}
normalizedKey := environmentKey(key)
if isBashAuthorityControl(normalizedKey) {
continue
}
overrideKeys[normalizedKey] = struct{}{}
safeOverrides = append(safeOverrides, entry)
}
environment := make([]string, 0, len(entries)+len(safeOverrides))
for _, entry := range entries {
key, _, ok := strings.Cut(entry, "=")
if !ok {
continue
}
normalizedKey := environmentKey(key)
if isBashAuthorityControl(normalizedKey) {
continue
}
if _, overridden := overrideKeys[normalizedKey]; overridden {
continue
}
environment = append(environment, entry)
}
return append(environment, safeOverrides...)
}
func isBashAuthorityControl(normalizedKey string) bool {
return normalizedKey == environmentKey("BASH_ENV") ||
normalizedKey == environmentKey("ENV") ||
normalizedKey == environmentKey("SHELLOPTS") ||
normalizedKey == environmentKey("BASHOPTS") ||
normalizedKey == environmentKey("GIT_EXEC_PATH") ||
strings.HasPrefix(normalizedKey, environmentKey("BASH_FUNC_"))
}
func environmentKey(key string) string {
if runtime.GOOS == "windows" {
return strings.ToUpper(key)
}
return key
}