From 115b2b471390d24c84a9ee25d4b379508914c38a Mon Sep 17 00:00:00 2001
From: TangoEnSkai <21152231+TangoEnSkai@users.noreply.github.com>
Date: Sat, 22 Aug 2026 12:59:53 +0900
Subject: [PATCH] fix: keep the module root a single package (tools.go ->
 go.mod tool directive)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

tools.go pinned gotestsum with a //go:build tools file that declared
`package tools` next to `package dbsql` in the module root. Tooling that
resolves a directory's package without honoring build constraints
(bazel/gazelle) — or that deliberately enables the `tools` tag
(golangci-lint on a project that uses one internally) — then sees two
package names in one directory and fails to load the driver.

Go 1.24 added the go.mod `tool` directive, which keeps a build-time tool
in the module graph without a placeholder package, so the file is no
longer needed. `go build -o bin/gotestsum gotest.tools/gotestsum` (the
Makefile's bin/gotestsum target) resolves exactly as before, and the
pinned version is unchanged at v1.8.2, so no Makefile or CI change is
required.

Add a tripwire test that loads the module root with the `tools` tag
enabled and fails if the directory ever declares more than one package.

Signed-off-by: TangoEnSkai <21152231+TangoEnSkai@users.noreply.github.com>
---
 go.mod        | 10 +++++++++-
 tools.go      |  7 -------
 tools_test.go | 30 ++++++++++++++++++++++++++++++
 3 files changed, 39 insertions(+), 8 deletions(-)
 delete mode 100644 tools.go
 create mode 100644 tools_test.go

diff --git a/go.mod b/go.mod
index b2cea939..c7555ba6 100644
--- a/go.mod
+++ b/go.mod
@@ -2,6 +2,14 @@ module github.com/databricks/databricks-sql-go
 
 go 1.25.0
 
+// gotestsum is a build-time test runner (see the Makefile's test/coverage
+// targets), not a library the driver imports. The tool directive (Go 1.24+)
+// keeps it in the module graph — the job the old //go:build tools file did —
+// without declaring a second package in the module root.
+//
+// See https://github.com/databricks/databricks-sql-go/issues/162.
+tool gotest.tools/gotestsum
+
 require (
 	github.com/apache/arrow/go/v12 v12.0.1
 	github.com/apache/thrift v0.23.0
@@ -12,7 +20,6 @@ require (
 	github.com/pierrec/lz4/v4 v4.1.15
 	github.com/stretchr/testify v1.8.1
 	golang.org/x/oauth2 v0.27.0
-	gotest.tools/gotestsum v1.8.2
 )
 
 require (
@@ -43,6 +50,7 @@ require (
 	golang.org/x/tools v0.6.0 // indirect
 	golang.org/x/xerrors v0.0.0-20220609144429-65e65417b02f // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
+	gotest.tools/gotestsum v1.8.2 // indirect
 )
 
 require (
diff --git a/tools.go b/tools.go
deleted file mode 100644
index bcd0f475..00000000
--- a/tools.go
+++ /dev/null
@@ -1,7 +0,0 @@
-//go:build tools
-
-package tools
-
-import (
-	_ "gotest.tools/gotestsum"
-)
diff --git a/tools_test.go b/tools_test.go
new file mode 100644
index 00000000..ae1ea676
--- /dev/null
+++ b/tools_test.go
@@ -0,0 +1,30 @@
+package dbsql
+
+import (
+	"go/build"
+	"testing"
+)
+
+// TestModuleRootIsASinglePackage guards the fix for #162: the module root must
+// declare exactly one package no matter which build tags are in play.
+//
+// The build-time test runner used to be pinned by a `//go:build tools` file
+// declaring `package tools` next to `package dbsql`. Tooling that resolves a
+// directory's package without honoring build constraints (bazel/gazelle) — or
+// that deliberately enables the `tools` tag (golangci-lint) — then saw two
+// package names in one directory and failed to load the driver. gotestsum is
+// pinned by the go.mod `tool` directive instead, so nothing but `dbsql` lives
+// here.
+func TestModuleRootIsASinglePackage(t *testing.T) {
+	ctx := build.Default
+	// Any tag a consumer might enable must not conjure a second package; "tools"
+	// is the one that historically did.
+	ctx.BuildTags = append(ctx.BuildTags, "tools")
+
+	if _, err := ctx.ImportDir(".", 0); err != nil {
+		if _, multiple := err.(*build.MultiplePackageError); multiple {
+			t.Fatalf("module root declares more than one package: %v", err)
+		}
+		t.Fatalf("could not load the module root: %v", err)
+	}
+}