fix(cli): report an ambiguous ... path instead of skipping it silently

CHANGELOG.md

@@ -72,6 +72,13 @@ the same version in lockstep.
   saw nothing. `scan` and `explain` now write JSON to stdout; the console
   format and the summary lines stay on stderr. A clean run also emits `[]`
   instead of nothing, so a consumer is never handed an empty file to parse.
+- **CLI `scan` said nothing when a path argument was ambiguous.** A trailing
+  `...` is read as the package pattern, so a real directory of that name was
+  skipped and the run could exit clean without opening the tree that was
+  named. The pattern still wins — that is what the go command does, and
+  deciding by what is on disk would make `./q/...` stop being recursive the
+  day `q/...` appeared — but the ambiguity is now reported, and a trailing
+  slash (`./q/.../`) addresses the directory.
 - **CLI `scan` rejected the `./...` path every doc example uses**, failing with
   `scan failed: lstat ./...: no such file or directory`. The scan has always
   been recursive, so the pattern suffix is now trimmed and `./pkg/...` selects

cmd/sqlguard/scan.go

@@ -60,6 +60,7 @@ func runScan(cmd *cobra.Command, args []string) error {
 	dir := "."
 	if len(args) > 0 {
 		dir = trimPatternSuffix(args[0])
+		warnDotsDirectory(args[0], dir)
 	}
 
 	rep, writeErr, err := newReporter(formatFlag)
@@ -132,6 +133,34 @@ func trimPatternSuffixSep(path string, sep rune) string {
 	return trimmed
 }
 
+// warnDotsDirectory breaks the silence in the one case where reading `...` as
+// a pattern hides a real directory.
+//
+// `...` is a pattern in every Go tool, and the go command cannot address a
+// directory of that name at all — `go list ./q/...` never yields the package
+// in a literal `q/...`. So the pattern reading wins here too, unconditionally:
+// deciding by what happens to be on disk would make `scan ./q/...` stop being
+// recursive the day somebody created `q/...`, which is a worse surprise than
+// the one it avoids.
+//
+// The directory is still reachable, via a trailing separator (`./q/.../`),
+// which is more than the go command offers. What is not acceptable is doing
+// this silently: without the warning, a clean exit would look like the named
+// tree was examined.
+func warnDotsDirectory(arg, scanned string) {
+	if arg == scanned {
+		return
+	}
+	info, err := os.Stat(arg)
+	if err != nil || !info.IsDir() {
+		return
+	}
+	_, _ = fmt.Fprintf(os.Stderr,
+		"sqlguard: %q is both a package pattern and an existing directory; "+
+			"scanning %q recursively. Use %q to scan that directory itself.\n",
+		arg, scanned, arg+string(filepath.Separator))
+}
+
 // checkedWriter remembers the first write error. reporter.Reporter cannot
 // return one — Report has no error result — so the CLI records it here and
 // reports it as a non-zero exit instead of writing a truncated document and

cmd/sqlguard/scan_test.go

@@ -8,6 +8,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"sync"
 	"testing"
@@ -580,9 +581,8 @@ func captureScanStreams(t *testing.T, target, format string) (stdout, stderr str
 	// the package hangs until the go test timeout.
 	var bufOut, bufErr bytes.Buffer
 	var wg sync.WaitGroup
-	wg.Add(2)
-	go func() { defer wg.Done(); _, _ = bufOut.ReadFrom(rOut) }()
-	go func() { defer wg.Done(); _, _ = bufErr.ReadFrom(rErr) }()
+	wg.Go(func() { _, _ = bufOut.ReadFrom(rOut) })
+	wg.Go(func() { _, _ = bufErr.ReadFrom(rErr) })
 
 	err = runScan(&cobra.Command{}, []string{target})
 
@@ -922,9 +922,8 @@ func TestNewReporter_JSONTargetsStdout(t *testing.T) {
 
 	var bufOut, bufErr bytes.Buffer
 	var wg sync.WaitGroup
-	wg.Add(2)
-	go func() { defer wg.Done(); _, _ = bufOut.ReadFrom(rOut) }()
-	go func() { defer wg.Done(); _, _ = bufErr.ReadFrom(rErr) }()
+	wg.Go(func() { _, _ = bufOut.ReadFrom(rOut) })
+	wg.Go(func() { _, _ = bufErr.ReadFrom(rErr) })
 
 	jr.Report([]analyzer.Result{{RuleName: "select-star"}})
 
@@ -970,8 +969,7 @@ func TestNewReporter_EachCallGetsItsOwnWriteError(t *testing.T) {
 
 	var sink bytes.Buffer
 	var wg sync.WaitGroup
-	wg.Add(1)
-	go func() { defer wg.Done(); _, _ = sink.ReadFrom(rOK) }()
+	wg.Go(func() { _, _ = sink.ReadFrom(rOK) })
 
 	repBroken.Report([]analyzer.Result{{RuleName: "select-star"}})
 	repOK.Report([]analyzer.Result{{RuleName: "select-star"}})
@@ -991,3 +989,118 @@ func TestNewReporter_EachCallGetsItsOwnWriteError(t *testing.T) {
 		t.Errorf("the healthy reporter did not write its report:\n%s", sink.String())
 	}
 }
+
+// TestScan_DotsDirectoryWarns covers the one spelling where the pattern
+// reading hides a real directory. `...` stays a pattern — that is what every
+// Go tool does, and the go command cannot address such a directory at all —
+// but the run must say so, or a clean exit looks like the named tree was
+// examined when it was never opened.
+func TestScan_DotsDirectoryWarns(t *testing.T) {
+	root := t.TempDir()
+	queries := filepath.Join(root, "queries")
+	dots := filepath.Join(queries, "...")
+
+	requireDotsDirSupport(t)
+
+	if err := os.MkdirAll(dots, 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	createTestFile(t, dots, "hidden.go", `package dots
+import "database/sql"
+func f(db *sql.DB) {
+	db.Exec("DELETE FROM audit_log")
+}
+`)
+	createTestFile(t, queries, "sibling.go", `package queries
+import "database/sql"
+func g(db *sql.DB) {
+	db.Query("SELECT id FROM t WHERE id = ? LIMIT 1", 1)
+}
+`)
+	noConfigFlag = true
+	t.Cleanup(func() { noConfigFlag = false })
+
+	// The pattern reading wins, and says so.
+	_, stderr, err := captureScanStreams(t, filepath.Join(queries, "..."), "console")
+	if err != nil {
+		t.Fatalf("expected a clean scan of the parent, got %v", err)
+	}
+	if !strings.Contains(stderr, "both a package pattern and an existing directory") {
+		t.Errorf("ambiguity was not reported:\n%s", stderr)
+	}
+	if strings.Contains(stderr, "delete-without-where") {
+		t.Errorf("pattern reading should not have entered the dots directory:\n%s", stderr)
+	}
+
+	// The trailing separator reaches the directory itself.
+	_, stderr, err = captureScanStreams(t, dots+string(filepath.Separator), "console")
+	if !errors.Is(err, errIssuesFound) {
+		t.Fatalf("trailing-separator form should scan the directory, got %v", err)
+	}
+	if !strings.Contains(stderr, "delete-without-where") {
+		t.Errorf("trailing-separator form missed the finding:\n%s", stderr)
+	}
+	if strings.Contains(stderr, "both a package pattern") {
+		t.Errorf("unambiguous form should not warn:\n%s", stderr)
+	}
+}
+
+// TestScan_NoWarningWithoutDotsDirectory keeps the warning off the ordinary
+// path: `./pkg/...` where no such directory exists must stay silent.
+func TestScan_NoWarningWithoutDotsDirectory(t *testing.T) {
+	dir := t.TempDir()
+	createTestFile(t, dir, "a.go", `package example
+import "database/sql"
+func f(db *sql.DB) {
+	db.Query("SELECT id FROM t WHERE id = ? LIMIT 1", 1)
+}
+`)
+	noConfigFlag = true
+	t.Cleanup(func() { noConfigFlag = false })
+
+	_, stderr, err := captureScanStreams(t, filepath.Join(dir, "..."), "console")
+	if err != nil {
+		t.Fatalf("expected a clean scan, got %v", err)
+	}
+	if strings.Contains(stderr, "both a package pattern") {
+		t.Errorf("warned with no dots directory present:\n%s", stderr)
+	}
+}
+
+// requireDotsDirSupport skips when the filesystem cannot represent a directory
+// named "..." — Win32 strips trailing dots from a path component, so the name
+// does not survive there.
+//
+// It decides that on its own probe directory, and only after confirming an
+// ordinary name works in the same place. A permission, quota or disk error
+// would otherwise look identical to an unrepresentable name and skip the whole
+// test, letting the suite pass without checking the warning or the
+// trailing-separator scan at all. Those causes fail instead.
+//
+// Discriminating this way rather than by errno keeps it independent of how a
+// given platform reports an invalid name.
+func requireDotsDirSupport(t *testing.T) {
+	t.Helper()
+
+	base := t.TempDir()
+	dotsErr := os.Mkdir(filepath.Join(base, "..."), 0o755)
+
+	if dotsErr == nil {
+		entries, err := os.ReadDir(base)
+		if err != nil {
+			t.Fatalf("probing %s: %v", base, err)
+		}
+		if slices.ContainsFunc(entries, func(e os.DirEntry) bool { return e.Name() == "..." }) {
+			return
+		}
+		t.Skipf("this filesystem stored a directory named %q under another name", "...")
+	}
+
+	// The name failed. Only a filesystem that accepts an ordinary name in the
+	// same directory tells us the name itself was the problem.
+	if err := os.Mkdir(filepath.Join(base, "ordinary"), 0o755); err != nil {
+		t.Fatalf("cannot create directories under %s at all: %v (creating %q failed with %v)",
+			base, err, "...", dotsErr)
+	}
+	t.Skipf("this filesystem will not create a directory named %q: %v", "...", dotsErr)
+}

website/docs/scan.md

@@ -25,9 +25,16 @@ The scan is always recursive, so a path may be written plainly (`./internal`)
 or with the Go package-pattern suffix (`./internal/...`); both select the same
 files. With no path at all it scans the current directory.
 
-_Changed in 0.3._ In 0.2 the pattern spelling was rejected outright —
-`sqlguard scan ./...` failed with `lstat ./...: no such file or directory` —
-so the form used throughout these docs had to be written as `sqlguard scan .`.
+A trailing `...` is always read as the pattern, as it is in every Go tool. If
+you genuinely have a directory named `...`, add a trailing slash
+(`./queries/.../`) to address it — and sqlguard says so on stderr when the
+argument is ambiguous, rather than reporting a clean run for a tree it never
+opened.
+
+_Changed in 0.3._ Pattern handling as a whole is new, including that warning.
+In 0.2 the spelling was rejected outright — `sqlguard scan ./...` failed with
+`lstat ./...: no such file or directory` — so the form used throughout these
+docs had to be written as `sqlguard scan .`, and no path was ever ambiguous.
 
 | Flag | Default | Effect |
 | --- | --- | --- |