gopls/internal/server: TypeHierarchy support

This CL adds basic support for the LSP Type Hierarchy feature.
There are three new RPCs:

- PrepareTypeHierarchy asks for a description of the currently
  selected text, which must be a reference to a type name.
- Supertypes and Subtypes ask for the items related by the
  subtyping relation, using the same machinery as
  Implementations by method sets, which has been factored
  to deliver a concurrent stream of results at a higher
  level then just protocol.Location.

Unlike Implementations, Type Hierarchy does not report
relationships between func types and FuncDecl/FuncLit/RangeStmt.

The names of types are now saved in the methodsets index.

The marker test framework has been extended with
@{super,sub}types markers.

This CL also sets us up to start reporting interface/interface
relationships (golang/go#68641), which are especially desirable
in the Type Hierarchy viewer; but that behavior change will be
left for a follow-up.

+ tests, docs, relnotes

Fixes golang/go#72142

Change-Id: Id60c9f447e938ac7e34262522ccd79bd54d90fc5
Reviewed-on: https://go-review.googlesource.com/c/tools/+/663055
Auto-Submit: Alan Donovan <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
Commit-Queue: Alan Donovan <[email protected]>
Reviewed-by: Jonathan Amsterdam <[email protected]>
Reviewed-by: Robert Findley <[email protected]>

Author: adonovan

gopls/doc/features/navigation.md

@@ -94,7 +94,7 @@ Interfaces and concrete types are matched using method sets:
   location of the declaration of each type that implements
   the interface.
 - When invoked on a **concrete type**,
-  it returns the locations of the matching interface types. 
+  it returns the locations of the matching interface types.
 - When invoked on an **interface method**, it returns the corresponding
   methods of the types that satisfy the interface.
 - When invoked on a **concrete method**,
@@ -282,3 +282,38 @@ Client support:
 - **VS Code**: `Show Call Hierarchy` menu item (`⌥⇧H`) opens [Call hierarchy view](https://code.visualstudio.com/docs/cpp/cpp-ide#_call-hierarchy) (note: docs refer to C++ but the idea is the same for Go).
 - **Emacs + eglot**: Not standard; install with `(package-vc-install "https://github.com/dolmens/eglot-hierarchy")`. Use `M-x eglot-hierarchy-call-hierarchy` to show the direct incoming calls to the selected function; use a prefix argument (`C-u`) to show the direct outgoing calls. There is no way to expand the tree.
 - **CLI**: `gopls call_hierarchy file.go:#offset` shows outgoing and incoming calls.
+
+
+## Type Hierarchy
+
+The LSP TypeHierarchy mechanism consists of three queries that
+together enable clients to present a hierarchical view of a portion of
+the subtyping relation over named types.
+
+- [`textDocument/prepareTypeHierarchy`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification#textDocument_prepareTypeHierarchy) returns an [item](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification#typeHierarchyItem) describing the named type at the current position;
+- [`typeHierarchyItem/subtypes`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification#typeHierarchy_subtypes) returns the set of subtypes of the selected (interface) type; and
+- [`typeHierarchy/supertypes`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification#typeHierarchy_supertypes) returns the set of supertypes (interface types) of the selected type.
+
+Invoke the command while selecting the name of a type.
+
+As with an Implementation query, a type hierarchy query reports
+function-local types only within the same package as the query type.
+Also the result does not include alias types, only defined types.
+
+<!--
+The screenshot below shows ...
+TODO: screenshot, but wait till #68641 is fixed.
+<img title="Subtypes of io.Reader" src="../assets/subtypes.png" width="640">
+-->
+
+Caveats:
+
+- The type hierarchy supports only named types and their assignability
+  relation. By contrast, the Implementations request also reports the
+  relation between unnamed `func` types and function declarations,
+  function literals, and dynamic calls of values of those types.
+
+Client support:
+- **VS Code**: `Show Type Hierarchy` menu item opens [Type hierarchy view](https://code.visualstudio.com/docs/java/java-editing#_type-hierarchy) (note: docs refer to Java but the idea is the same for Go).
+- **Emacs + eglot**: Support added in March 2025. Use `M-x eglot-show-call-hierarchy`.
+- **CLI**: not yet supported.

gopls/doc/release/v0.19.0.md

@@ -33,6 +33,20 @@ and queries using signatures should be invoked on a `func` or `(` token.
 Only the local (same-package) algorithm is currently supported.
 TODO: implement global.
 
+## Support for Type Hierarchy
+
+<!-- golang/go#72142 -->
+
+Gopls now implements the three LSP methods related to the Type
+Hierarchy viewer: `textDocument/prepareTypeHierarchy`,
+`typeHierarchy/supertypes`, `typeHierarchy/subtypes`.
+
+In VS Code, select "Show Type Hierarchy" from the context menu
+to see a tree widget displaying all the supertypes or subtypes
+of the selected named type.
+
+TODO: screenshot, but wait till #68641 is fixed.
+
 
 ## "Eliminate dot import" code action
 

gopls/internal/cache/methodsets/methodsets.go

@@ -51,6 +51,7 @@ import (
 	"sync/atomic"
 
 	"golang.org/x/tools/go/types/objectpath"
+	"golang.org/x/tools/gopls/internal/cache/metadata"
 	"golang.org/x/tools/gopls/internal/util/bug"
 	"golang.org/x/tools/gopls/internal/util/fingerprint"
 	"golang.org/x/tools/gopls/internal/util/frob"
@@ -62,14 +63,15 @@ import (
 // types in a package in a form that permits assignability queries
 // without the type checker.
 type Index struct {
-	pkg gobPackage
+	pkg     gobPackage
+	PkgPath metadata.PackagePath
 }
 
 // Decode decodes the given gob-encoded data as an Index.
-func Decode(data []byte) *Index {
+func Decode(pkgpath metadata.PackagePath, data []byte) *Index {
 	var pkg gobPackage
 	packageCodec.Decode(data, &pkg)
-	return &Index{pkg}
+	return &Index{pkg: pkg, PkgPath: pkgpath}
 }
 
 // Encode encodes the receiver as gob-encoded data.
@@ -110,36 +112,75 @@ func KeyOf(t types.Type) (Key, bool) {
 
 // A Result reports a matching type or method in a method-set search.
 type Result struct {
-	Location Location // location of the type or method
+	TypeName    string   // name of the named type
+	IsInterface bool     // matched type (or method) is abstract
+	Location    Location // location of the type or method
 
 	// methods only:
 	PkgPath    string          // path of declaring package (may differ due to embedding)
 	ObjectPath objectpath.Path // path of method within declaring package
 }
 
-// Search reports each type that implements (or is implemented by) the
-// type that produced the search key. If methodID is nonempty, only
-// that method of each type is reported.
+// TypeRelation indicates the direction of subtyping relation,
+// if any, between two types.
+//
+// It is a bitset, so that clients of Implementations may use
+// Supertype|Subtype to request an undirected match.
+type TypeRelation int8
+
+const (
+	Supertype TypeRelation = 0x1
+	Subtype   TypeRelation = 0x2
+)
+
+// Search reports each type that implements (Supertype ∈ want) or is
+// implemented by (Subtype ∈ want) the type that produced the search key.
+//
+// If method is non-nil, only that method of each type is reported.
 //
 // The result does not include the error.Error method.
 // TODO(adonovan): give this special case a more systematic treatment.
-func (index *Index) Search(key Key, method *types.Func) []Result {
+func (index *Index) Search(key Key, want TypeRelation, method *types.Func) []Result {
 	var results []Result
 	for _, candidate := range index.pkg.MethodSets {
-		// Traditionally this feature doesn't report
-		// interface/interface elements of the relation.
-		// I think that's a mistake.
-		// TODO(adonovan): UX: change it, here and in the local implementation.
+		// The historical behavior enshrined by this
+		// function rejects cases where both are
+		// (nontrivial) interface types, but this is
+		// useful information; see #68641 and CL 619719.
+		// TODO(adonovan): rescind this policy choice,
+		// and report I/I relationships,
+		// by deleting this continue statement.
+		// (It is also necessary to remove self-matches.)
+		//
+		// The same question appears in the local algorithm (implementations).
 		if candidate.IsInterface && key.mset.IsInterface {
 			continue
 		}
 
-		if !implements(candidate, key.mset) && !implements(key.mset, candidate) {
+		// Test the direction of the relation.
+		// The client may request either direction or both
+		// (e.g. when the client is References),
+		// and the Result reports each test independently;
+		// both tests succeed when comparing identical
+		// interface types.
+		var got TypeRelation
+		if want&Subtype != 0 && implements(candidate, key.mset) {
+			got |= Subtype
+		}
+		if want&Supertype != 0 && implements(key.mset, candidate) {
+			got |= Supertype
+		}
+		if got == 0 {
 			continue
 		}
 
+		typeName := index.pkg.Strings[candidate.TypeName]
 		if method == nil {
-			results = append(results, Result{Location: index.location(candidate.Posn)})
+			results = append(results, Result{
+				TypeName:    typeName,
+				IsInterface: candidate.IsInterface,
+				Location:    index.location(candidate.Posn),
+			})
 		} else {
 			for _, m := range candidate.Methods {
 				if m.ID == method.Id() {
@@ -154,9 +195,11 @@ func (index *Index) Search(key Key, method *types.Func) []Result {
 					}
 
 					results = append(results, Result{
-						Location:   index.location(m.Posn),
-						PkgPath:    index.pkg.Strings[m.PkgPath],
-						ObjectPath: objectpath.Path(index.pkg.Strings[m.ObjectPath]),
+						TypeName:    typeName,
+						IsInterface: candidate.IsInterface,
+						Location:    index.location(m.Posn),
+						PkgPath:     index.pkg.Strings[m.PkgPath],
+						ObjectPath:  objectpath.Path(index.pkg.Strings[m.ObjectPath]),
 					})
 					break
 				}
@@ -285,14 +328,18 @@ func (b *indexBuilder) build(fset *token.FileSet, pkg *types.Package) *Index {
 	for _, name := range scope.Names() {
 		if tname, ok := scope.Lookup(name).(*types.TypeName); ok && !tname.IsAlias() {
 			if mset := methodSetInfo(tname.Type(), setIndexInfo); mset.Mask != 0 {
+				mset.TypeName = b.string(name)
 				mset.Posn = objectPos(tname)
 				// Only record types with non-trivial method sets.
 				b.MethodSets = append(b.MethodSets, mset)
 			}
 		}
 	}
 
-	return &Index{pkg: b.gobPackage}
+	return &Index{
+		pkg:     b.gobPackage,
+		PkgPath: metadata.PackagePath(pkg.Path()),
+	}
 }
 
 // string returns a small integer that encodes the string.
@@ -370,6 +417,7 @@ type gobPackage struct {
 
 // A gobMethodSet records the method set of a single type.
 type gobMethodSet struct {
+	TypeName    int // name (string index) of the package-level type
 	Posn        gobPosition
 	IsInterface bool
 	Tricky      bool   // at least one method is tricky; fingerprint must be parsed + unified

gopls/internal/cache/snapshot.go

@@ -608,7 +608,7 @@ func (s *Snapshot) MethodSets(ctx context.Context, ids ...PackageID) ([]*methods
 	pre := func(i int, ph *packageHandle) bool {
 		data, err := filecache.Get(methodSetsKind, ph.key)
 		if err == nil { // hit
-			indexes[i] = methodsets.Decode(data)
+			indexes[i] = methodsets.Decode(ph.mp.PkgPath, data)
 			return false
 		} else if err != filecache.ErrNotFound {
 			event.Error(ctx, "reading methodsets from filecache", err)