feat: add GoInstallWithGoVersion for Go-version-aware tool caching

Author: alethenorio

sgtool/build.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
+	"runtime"
 	"strings"
 
 	"go.einride.tech/sage/sg"
@@ -45,6 +46,33 @@ func GoInstall(ctx context.Context, pkg, version string) (string, error) {
 	return symlink, nil
 }
 
+// GoInstallWithGoVersion is like GoInstall but includes the Go version in the
+// cache key. Use this for tools whose behavior depends on the Go runtime version,
+// such as go-licenses which uses build.Default.GOROOT to detect stdlib packages.
+func GoInstallWithGoVersion(ctx context.Context, pkg, version string) (string, error) {
+	executable := sg.FromToolsDir("go", pkg, version, runtime.Version(), filepath.Base(trimVersionSuffix(pkg)))
+	// Check if executable already exists
+	if _, err := os.Stat(executable); err == nil {
+		symlink, err := CreateSymlink(executable)
+		if err != nil {
+			return "", err
+		}
+		return symlink, nil
+	}
+	pkgVersion := fmt.Sprintf("%s@%s", pkg, version)
+	sg.Logger(ctx).Printf("building %s...", pkgVersion)
+	cmd := sg.Command(ctx, "go", "install", pkgVersion)
+	cmd.Env = append(cmd.Env, "GOBIN="+filepath.Dir(executable))
+	if err := cmd.Run(); err != nil {
+		return "", err
+	}
+	symlink, err := CreateSymlink(executable)
+	if err != nil {
+		return "", err
+	}
+	return symlink, nil
+}
+
 // GoInstallWithModfile builds and installs a go binary given the package and a path
 // to the local go.mod file.
 func GoInstallWithModfile(ctx context.Context, pkg, file string) (string, error) {

tools/sggolicenses/tools.go

@@ -1,3 +1,15 @@
+// Package sggolicenses provides sage integration for the go-licenses tool.
+//
+// Troubleshooting: If go-licenses fails with errors like "Package X does not
+// have module info", this is a known incompatibility between go-licenses and
+// Go toolchain version mismatches (https://github.com/google/go-licenses/pull/329).
+// The go-licenses binary uses build.Default.GOROOT at runtime to detect stdlib
+// packages — if your local Go version differs from the toolchain directive in
+// go.mod, the GOROOT path won't match and stdlib packages are misidentified.
+//
+// To fix this, update your local Go installation to match the version in go.mod,
+// or set GOTOOLCHAIN=go<version>+auto (e.g. GOTOOLCHAIN=go1.25.7+auto) to
+// ensure the correct toolchain is used consistently.
 package sggolicenses
 
 import (
@@ -93,7 +105,10 @@ func Check(ctx context.Context, disallowedTypes ...string) error {
 	return nil
 }
 
+// PrepareCommand installs go-licenses using Go-version-aware caching.
+// go-licenses uses build.Default.GOROOT at runtime to detect stdlib packages,
+// so the binary must be rebuilt when the Go version changes.
 func PrepareCommand(ctx context.Context) error {
-	_, err := sgtool.GoInstall(ctx, "github.com/google/go-licenses/v2", version)
+	_, err := sgtool.GoInstallWithGoVersion(ctx, "github.com/google/go-licenses/v2", version)
 	return err
 }

tools/sggovulncheck/tools.go

@@ -67,7 +67,17 @@ func RunAll(ctx context.Context, modulePaths ...string) error {
 	return nil
 }
 
+// PrepareCommand installs govulncheck using Go-version-aware caching.
+// govulncheck uses go/packages to load and analyze dependencies. When the
+// binary is built with an older Go version than what is currently installed,
+// package loading can fail with errors like:
+//
+//	file requires newer Go version go1.N (application built with go1.M)
+//
+// This happens because dependencies may have //go:build go1.N constraints
+// that are incompatible with the Go version embedded in a stale binary.
+// Rebuilding when the Go version changes ensures compatibility.
 func PrepareCommand(ctx context.Context) error {
-	_, err := sgtool.GoInstall(ctx, "golang.org/x/vuln/cmd/govulncheck", version)
+	_, err := sgtool.GoInstallWithGoVersion(ctx, "golang.org/x/vuln/cmd/govulncheck", version)
 	return err
 }