gopls/mod: find references to required modules

With this CL, users will be able to click on a required module in a
go.mod file, and see the import statements that reference its
packages.

In addition to integrating with LSP clients, this code avoids
reporting imports of nested modules.

Testing: there are marker tests, but self-contained. A lot
of natural uses will be to find modules from the module cache.
I tested by hand getting references from a go.mod file in
the tools repository. For instance, when searching for references to
golang/x/tools in gopls/go.mod, for marker_test.go it finds
the 8 imports of packages in golang.org/x/tools,
but none of the many golang.go/x/tools/gopls imports.

Fixes golang/go#75810

Change-Id: I08022dd29173a6d4ea8c728c7eb8e54a462a5889
Reviewed-on: https://go-review.googlesource.com/c/tools/+/713160
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

Author: pjweinbgo

gopls/doc/features/navigation.md

@@ -66,6 +66,9 @@ The references algorithm handles various parts of syntax as follows:
   definition (of a field).
   The `references` operation reports only the references to it [as a field](https://go.dev/issue/63521).
   To find references to the type, jump to the type declararation first.
+- The references to a module in a **require** directive in a **go.mod** file are
+  the **import** statements in packages of the main module (defined by the go.mod file) that
+  import packages of the required module.
 
 Be aware that a references query returns information only about the
 build configuration used to analyze the selected file, so if you ask

gopls/doc/release/v0.22.0.md

@@ -3,6 +3,11 @@ title: "Gopls release v0.22.0 (forthcoming)"
 ---
 
 ## Configuration changes
+## Navigation features
+<!-- golang/go#75810 -->
+
+- Asking for references while hovering over the name of a required module in a `go.mod` file
+  will show all the imports of that module in the main module (the go.mod's module).
 ## Web-based features
 ## Editing features
 ## Analysis features

gopls/internal/cache/mod.go

@@ -25,7 +25,7 @@ import (
 // A ParsedModule contains the results of parsing a go.mod file.
 type ParsedModule struct {
 	URI         protocol.DocumentURI
-	File        *modfile.File
+	File        *modfile.File // maybe absent in case of error
 	ReplaceMap  map[module.Version]module.Version
 	Mapper      *protocol.Mapper
 	ParseErrors []*Diagnostic

gopls/internal/mod/references.go

@@ -0,0 +1,131 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package mod
+
+import (
+	"context"
+	"fmt"
+	"maps"
+	"slices"
+
+	"golang.org/x/tools/gopls/internal/cache"
+	"golang.org/x/tools/gopls/internal/cache/metadata"
+	"golang.org/x/tools/gopls/internal/cache/parsego"
+	"golang.org/x/tools/gopls/internal/file"
+	"golang.org/x/tools/gopls/internal/protocol"
+)
+
+// References returns the locations of imports referenced by a required module
+func References(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle, params *protocol.ReferenceParams) ([]protocol.Location, error) {
+	// Th go.mod file will contain a module name (e.g., golang.org/x/tools)
+	// but the import statements contain package names
+	// (e.g., golang.org/x/tools/internal/astutil).
+	// The code has to avoid imports from submodules, like golang.org/x/tools/gopls/internal/file
+	// so simple string matching would not work.
+
+	// find modpath, the module path the user wants the references for
+	gomod, err := snapshot.ParseMod(ctx, fh)
+	if err != nil {
+		return nil, err
+	}
+	if gomod.File == nil {
+		return nil, fmt.Errorf("mysterious parse failure %s", fh.URI().Path())
+	}
+	// protocol.ReferenceParams contains both a Position and a Range.
+	// The Range would contain the Position, so use Position.
+	offset, err := gomod.Mapper.PositionOffset(params.Position)
+	if err != nil {
+		return nil, err
+	}
+	var modpath string
+	for _, req := range gomod.File.Require {
+		if req.Syntax.Start.Byte <= offset && offset <= req.Syntax.End.Byte {
+			modpath = req.Mod.Path
+			break
+		}
+	}
+	if modpath == "" {
+		// nothing to report
+		return nil, nil
+	}
+
+	locs := make(map[protocol.Location]bool)
+
+	includeDecl := params.Context.IncludeDeclaration
+	// A. find the IDs of all packages in the module that was required
+	ids := make(map[metadata.PackageID]bool)
+	g := snapshot.MetadataGraph()
+	for _, pkg := range g.Packages {
+		if pkg.Module != nil && pkg.Module.Path == modpath {
+			ids[pkg.ID] = true
+			// once, if the definition is needed
+			if includeDecl {
+				fh, err := snapshot.ReadFile(ctx, protocol.URIFromPath(pkg.Module.GoMod))
+				if err != nil {
+					return nil, err
+				}
+				parsed, err := snapshot.ParseMod(ctx, fh)
+				if err != nil {
+					return nil, err
+				}
+				if parsed.File != nil && parsed.File.Module != nil {
+					start, end := parsed.File.Module.Syntax.Span()
+					loc, err := parsed.Mapper.OffsetLocation(start.Byte, end.Byte)
+					if err != nil {
+						return nil, err
+					}
+					locs[loc] = true
+					includeDecl = false // no need to do this again
+				}
+			}
+		}
+	}
+	// B. find all the importers of these packages that are in the go.mod's module
+	uris := make(map[protocol.DocumentURI]*metadata.Package)
+	for id := range ids {
+		for _, importer := range g.ImportedBy[id] {
+			if importer.Module.GoMod != gomod.URI.Path() {
+				continue
+			}
+			// files to be read.
+			// at least one of them has an import to be reported.
+			for _, uri := range importer.CompiledGoFiles {
+				upkgs := g.ForFile[uri]
+				for _, upkg := range upkgs {
+					if upkg.ID == importer.ID {
+						uris[uri] = importer // may overwrite, but it doesn't matter
+						break
+					}
+				}
+			}
+		}
+	}
+	// C. for each of the uris, pick out the locs of imports from the requested module
+	for uri := range uris {
+		fh, err := snapshot.ReadFile(ctx, uri)
+		if err != nil {
+			return nil, err
+		}
+		pgf, err := snapshot.ParseGo(ctx, fh, parsego.Header) // Header promotes cache hits
+		if err != nil {
+			return nil, err
+		}
+		xpkg := uris[uri]
+		for _, spec := range pgf.File.Imports {
+			importPath := metadata.UnquoteImportPath(spec)
+			if ids[xpkg.DepsByImpPath[importPath]] {
+				loc, err := pgf.NodeLocation(spec.Path)
+				if err != nil {
+					return nil, err
+				}
+				locs[loc] = true
+				continue
+			}
+		}
+	}
+
+	ans := slices.SortedFunc(maps.Keys(locs), protocol.CompareLocation)
+	return ans, nil
+}

gopls/internal/server/references.go

@@ -10,6 +10,7 @@ import (
 	"golang.org/x/tools/gopls/internal/file"
 	"golang.org/x/tools/gopls/internal/golang"
 	"golang.org/x/tools/gopls/internal/label"
+	"golang.org/x/tools/gopls/internal/mod"
 	"golang.org/x/tools/gopls/internal/protocol"
 	"golang.org/x/tools/gopls/internal/telemetry"
 	"golang.org/x/tools/gopls/internal/template"
@@ -35,6 +36,8 @@ func (s *server) References(ctx context.Context, params *protocol.ReferenceParam
 		return template.References(ctx, snapshot, fh, params)
 	case file.Go:
 		return golang.References(ctx, snapshot, fh, params.Position, params.Context.IncludeDeclaration)
+	case file.Mod:
+		return mod.References(ctx, snapshot, fh, params)
 	}
 	return nil, nil // empty result
 }

gopls/internal/test/marker/testdata/references/issue75810.txt

@@ -0,0 +1,58 @@
+-- go.work --
+go 1.22
+
+use ./a
+use ./b
+use ./c
+
+-- a/go.mod --
+module example.com/a
+
+go 1.22
+
+require example.com/b v0.0.1 //@ refs("/b", bmod, a_b, a2_b, a3_b)
+
+-- a/a.go --
+package a
+
+import "example.com/b" //@ loc(a_b, `"example.com/b"`)
+
+var _ = b.B
+
+-- a/a2.go --
+package a
+
+import "example.com/b" //@ loc(a2_b, `"example.com/b"`)
+
+var _ = b.B
+
+-- a/a3/a3.go --
+package a
+
+import "example.com/b" //@ loc(a3_b, `"example.com/b"`)
+
+var _ = b.B
+
+-- b/go.mod --
+module example.com/b //@ loc(bmod, re"^.*?b")
+
+go 1.22
+
+-- b/b.go --
+package b
+
+var B int
+
+-- c/go.mod --
+module example.com/c
+
+go 1.22
+
+require example.com/a v0.0.1
+require example.com/b v0.0.1 //@ refs("/b",bmod, c_b)
+-- c/c.go --
+package c
+
+import "example.com/b" //@ loc(c_b, `"example.com/b"`)
+
+var _ = b.B

gopls/internal/test/marker/testdata/references/issue75810A.txt

@@ -0,0 +1,74 @@
+Find references to example.com/b, but not to example.com/b/x
+-- go.work --
+go 1.22
+
+use ./a
+use ./b
+use ./b/x
+use ./c
+
+-- a/go.mod --
+module example.com/a
+
+go 1.22
+
+require example.com/b v0.0.1 //@ refs("/b", bmod, a_b, a2_b, a3_b)
+-- a/a.go --
+package a
+
+import "example.com/b" //@ loc(a_b, `"example.com/b"`)
+import "example.com/b/x" //@ loc(a4_x, `"example.com/b/x"`)
+
+var _ = b.B
+var _ = x.X
+
+-- a/a2.go --
+package a
+
+import "example.com/b" //@ loc(a2_b, `"example.com/b"`)
+
+var _ = b.B
+
+-- a/a3/a3.go --
+package a
+
+import "example.com/b" //@ loc(a3_b, `"example.com/b"`)
+import "example.com/b/x" //@ loc(a3_x, `"example.com/b/x"`)
+
+
+var _ = b.B
+var _ = x.X
+
+-- b/go.mod --
+module example.com/b //@ loc(bmod, re"^.*?b")
+
+go 1.22
+
+-- b/b.go --
+package b
+
+var B int
+
+-- b/x/go.mod --
+module example.com/b/x
+
+go 1.22
+
+-- b/x/x.go --
+package x
+
+var X int
+-- c/go.mod --
+module example.com/c
+
+go 1.22
+
+require example.com/a v0.0.1
+require example.com/b v0.0.1 //@ refs("/b", bmod, c_b)
+-- c/c.go --
+package c
+
+import "example.com/b" //@ loc(c_b, `"example.com/b"`)
+
+var _ = b.B
+