gopls/internal/golang: "Show free symbols" code action

This change adds a new "Show free symbols" (source.freesymbols)
code action that reports the set of free symbols referenced by
the selected region of Go source. The HTML report, produced by
the /freerefs endpoint of gopls' web server, includes an
itemized list of symbols, and a color-annotated source listing.

Symbols are presented in three groups: imported symbols
(grouped by package); package-level symbols and local symbols.
Each symbol is a link to either the integrated doc viewer
(for imported symbols) or the declaration, for others.

The feature is visible in editors as:
- VS Code: Source actions... > Show free references
- Emacs+eglot: M-x go-freesymbols
  (Requires (eglot--code-action go-freerefs "source.freesymbols")
   until dominikh/go-mode.el#436 is resolved.)

There are a number of opportunities for factoring in common
with RenderPackageDoc; they will be dealt with in a follow-up.

Also:
- a unit test of the freeRefs algorithm;
- an integration test of the web interaction.
- release notes.

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

Author: adonovan

gopls/doc/commands.md

@@ -306,6 +306,35 @@ Result:
 map[golang.org/x/tools/gopls/internal/protocol.DocumentURI]*golang.org/x/tools/gopls/internal/vulncheck.Result
 ```
 
+### **report free symbols referenced by the selection.**
+Identifier: `gopls.free_symbols`
+
+This command is a query over a selected range of Go source
+code. It reports the set of "free" symbols of the
+selection: the set of symbols that are referenced within
+the selection but are declared outside of it. This
+information is useful for understanding at a glance what a
+block of code depends on, perhaps as a precursor to
+extracting it into a separate function.
+
+Args:
+
+```
+string,
+{
+	// The range's start position.
+	"start": {
+		"line": uint32,
+		"character": uint32,
+	},
+	// The range's end position.
+	"end": {
+		"line": uint32,
+		"character": uint32,
+	},
+}
+```
+
 ### **Toggle gc_details**
 Identifier: `gopls.gc_details`
 

gopls/doc/release/v0.16.0.md

@@ -54,6 +54,44 @@ Editor support:
 
 - TODO: test in vim, neovim, sublime, helix.
 
+### Free symbols
+
+Gopls offers another web-based code action, "Show free symbols",
+which displays the free symbols referenced by the selected code.
+
+A symbol is "free" if it is referenced within the selection but
+declared outside of it. The free symbols that are variables are, in
+effect, the set of parameters that would be needed if the block were
+extracted into its own function in the same package.
+
+Even when you don't intend to extract a block into a new function,
+this information can help you to tell at a glance what names a block
+of code depends on.
+
+Each dotted path of identifiers (such as `file.Name.Pos`) is reported
+as a separate item, so that you can see which parts of a complex
+type are actually needed.
+
+Viewing the free symbols of the body of a function may reveal that
+only a small part (a single field of a struct, say) of one of the
+function's parameters is used, allowing you to simplify and generalize
+the function by choosing a different type for that parameter.
+
+- TODO screenshot
+
+- VS Code: use the `Source action > View free symbols` menu item.
+
+- Emacs: requires eglot v1.17. You may find this `go-doc` function a
+  useful shortcut:
+
+```lisp
+(eglot--code-action eglot-code-action-freesymbols "source.freesymbols")
+
+(defalias 'go-freesymbols #'eglot-code-action-freesymbols
+  "View free symbols referred to by the current selection.")
+```
+TODO(dominikh/go-mode.el#436): add both of these to go-mode.el.
+
 ### `unusedwrite` analyzer
 
 The new

gopls/internal/doc/api.json

@@ -1002,6 +1002,13 @@
 			"ArgDoc": "{\n\t// The file URI.\n\t\"URI\": string,\n}",
 			"ResultDoc": "map[golang.org/x/tools/gopls/internal/protocol.DocumentURI]*golang.org/x/tools/gopls/internal/vulncheck.Result"
 		},
+		{
+			"Command": "gopls.free_symbols",
+			"Title": "report free symbols referenced by the selection.",
+			"Doc": "This command is a query over a selected range of Go source\ncode. It reports the set of \"free\" symbols of the\nselection: the set of symbols that are referenced within\nthe selection but are declared outside of it. This\ninformation is useful for understanding at a glance what a\nblock of code depends on, perhaps as a precursor to\nextracting it into a separate function.",
+			"ArgDoc": "string,\n{\n\t// The range's start position.\n\t\"start\": {\n\t\t\"line\": uint32,\n\t\t\"character\": uint32,\n\t},\n\t// The range's end position.\n\t\"end\": {\n\t\t\"line\": uint32,\n\t\t\"character\": uint32,\n\t},\n}",
+			"ResultDoc": ""
+		},
 		{
 			"Command": "gopls.gc_details",
 			"Title": "Toggle gc_details",

gopls/internal/golang/codeaction.go

@@ -36,8 +36,13 @@ func CodeActions(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle,
 	// when adding new query operations like GoTest and GoDoc that
 	// are permitted even in generated source files
 
-	// Code actions requiring syntax information alone.
-	if wantQuickFixes || want[protocol.SourceOrganizeImports] || want[protocol.RefactorExtract] {
+	// Code actions that can be offered based on syntax information alone.
+	if wantQuickFixes ||
+		want[protocol.SourceOrganizeImports] ||
+		want[protocol.RefactorExtract] ||
+		want[protocol.GoDoc] ||
+		want[protocol.GoFreeSymbols] {
+
 		pgf, err := snapshot.ParseGo(ctx, fh, parsego.Full)
 		if err != nil {
 			return nil, err
@@ -89,13 +94,38 @@ func CodeActions(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle,
 			}
 			actions = append(actions, extractions...)
 		}
+
+		if want[protocol.GoDoc] {
+			loc := protocol.Location{URI: pgf.URI, Range: rng}
+			cmd, err := command.NewDocCommand("View package documentation", loc)
+			if err != nil {
+				return nil, err
+			}
+			actions = append(actions, protocol.CodeAction{
+				Title:   cmd.Title,
+				Kind:    protocol.GoDoc,
+				Command: &cmd,
+			})
+		}
+
+		if want[protocol.GoFreeSymbols] && rng.End != rng.Start {
+			cmd, err := command.NewFreeSymbolsCommand("Show free symbols", pgf.URI, rng)
+			if err != nil {
+				return nil, err
+			}
+			// For implementation, see commandHandler.showFreeSymbols.
+			actions = append(actions, protocol.CodeAction{
+				Title:   cmd.Title,
+				Kind:    protocol.GoFreeSymbols,
+				Command: &cmd,
+			})
+		}
 	}
 
 	// Code actions requiring type information.
 	if want[protocol.RefactorRewrite] ||
 		want[protocol.RefactorInline] ||
-		want[protocol.GoTest] ||
-		want[protocol.GoDoc] {
+		want[protocol.GoTest] {
 		pkg, pgf, err := NarrowestPackageForFile(ctx, snapshot, fh.URI())
 		if err != nil {
 			return nil, err
@@ -123,19 +153,6 @@ func CodeActions(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle,
 			}
 			actions = append(actions, fixes...)
 		}
-
-		if want[protocol.GoDoc] {
-			loc := protocol.Location{URI: pgf.URI, Range: rng}
-			cmd, err := command.NewDocCommand("View package documentation", loc)
-			if err != nil {
-				return nil, err
-			}
-			actions = append(actions, protocol.CodeAction{
-				Title:   cmd.Title,
-				Kind:    protocol.GoDoc,
-				Command: &cmd,
-			})
-		}
 	}
 	return actions, nil
 }