fix(project): resolve Go pins past unrelated tool manifests - #44

Summary

In a multi-language repository, .tool-versions often lists only Ruby, Node or Python, next to a valid go.mod. The resolver used to stop at that file and report no project version, and a child directory's unrelated .tool-versions hid a parent's Go pin. Fixing only the resolver would have left a second bug: Bash/Zsh auto-switching cached the first manifest it found, so edits to the real fallback go.mod or the parent pin never refreshed PATH.

What changed

• Resolver (_gos_read_tool_versions_file / _gos_resolve_project_version) uses a three-way status:
  • 0: a Go pin was found;
  • 1: the file is readable but has no go/golang entry, so resolution continues to go.mod and then parent directories;
  • 2: the file is unreadable, or an explicit go/golang entry has no version, so resolution fails closed.
• Auto-switch hook (__gos_auto_switch): the pure-shell prompt snapshot includes every manifest consulted until the effective Go pin is found. Edits to the unrelated file, the go.mod or the parent pin all invalidate the cache, and the subprocess-free fast path for an unchanged prompt is kept.
• Field splitting of .tool-versions lines now uses parameter expansion (no globbing; see follow-ups).
• README precedence docs, a CHANGELOG entry, and regressions in tests/project-env.bash covering:
  • same-directory and parent fallback;
  • explicit precedence;
  • a missing version and an unreadable file;
  • a glob entry;
  • in-place edits in Bash and Zsh;
  • preservation of the user's regex match.

Behavior change (documented)

• A golang (or go) line without a version used to be skipped, so a later golang X line in the same file could still win. Now the first go/golang entry decides, and a bare one fails closed instead of silently picking another toolchain. This matches asdf's first-match semantics.
• A .tool-versions file with no Go entry no longer makes gos use / gos run -- fail. Resolution continues to go.mod and then parent directories.

Why

Repositories that pin other runtimes with asdf/mise would otherwise get "no version found" despite a valid go.mod, and their prompt would keep a stale PATH.

How it was tested

• tests/project-env.bash: the fallback regression fails against the original gos.sh. Both new follow-up regressions also fail without their fixes.
• Full suite on head 4362759, as a non-root user with zsh 5.9 installed (so the Zsh hook path runs): 31/31 passed.
• ShellCheck 0.11.0, shfmt 3.13.1, bash -n, scripts/sync-command-surfaces.bash --check and git diff --check are clean.
• Manual checks of the new splitting:
  • golang 1.22.1 → 1.22.1;
  • golang<TAB>1.21.0 extra → 1.21.0;
  • go go1.20.3 → 1.20.3;
  • nodejs 20 → no pin;
  • bare golang → fails;
  • golang * → rejected as '*' instead of being expanded.
• Hosted CI on 4362759: all 10 jobs and all 11 checks green, including native macOS Bash 3.2, Linux Fish and Windows Bash/PowerShell. Previous qualification: run 37359410297 on d46d0e2.

Review follow-ups

• bd13b8d fix(env): keep the auto-switch hook from clobbering regex matches. The hook runs in the user's interactive shell on every prompt. Detecting a Go line with [[ =~ ]] overwrote the user's BASH_REMATCH (and Zsh's MATCH/match, and needed zsh/pcre under RE_MATCH_PCRE). It now uses an equivalent case on the left-trimmed line. The test asserts the user's match survives in Bash and Zsh.
• 4362759 fix(project): split .tool-versions fields without pathname expansion. The unquoted set -- $line also globbed, so with golang * and a stray file named 1.21.6 in the caller's working directory, gos selected go1.21.6. Fields are now split with parameter expansion, which is subprocess-free and safe on Bash 3.2 (this resolver always runs under Bash). The regression uses that exact decoy file.

Decisions taken

• Fail closed on an unreadable file or an incomplete explicit Go entry, rather than falling through to another manifest.
• The prompt snapshot errs toward over-invalidation: treating a line as a Go pin when the resolver wouldn't can only cause an extra re-resolve, never a stale PATH.

Known limitations & follow-ups

• The "unreadable manifest" case is skipped on hosts where mode 000 is still readable (for example when running as root). Once test(runner): distinguish skipped assertions from passed suites #47 lands, that skip can go through skip_assertion like the others.

Merge order

Independent of the other open PRs. It merges cleanly with #45, #46, #47, #48 and #49. Builds on the already merged #42 and #43.