gopls/internal/golang: add web-based "split package" tool

This CL contains a prototype of an interactive tool to help
you split a package into two or more independent
components whose dependency graph is acyclic.

The "source.splitPackage" code action opens a web browser
on a page that displays all the declarations in the current
package, grouped by file. You can create two or more
components, then assign declarations to components by
clicking checkboxes. As the assignment (or code) changes,
the tool displays the component dependency graph, along
with the symbol references that create that graph.
If there is a cycle in the dependency graph, it is flagged.

It doesn't actually move the declarations yet, but IMHO
that's actually a lesser problem than the analysis.

The component names and their assignments for each package
are saved persistently in the filecache.

+ integration test (using a Go client in lieu of JS+DOM),
  docs, relnote

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

Author: adonovan

gopls/doc/assets/splitpkg-deps.png

@@ -56,10 +56,11 @@ when making significant changes to existing features or when adding new ones.
   - [Package documentation](web.md#doc): browse documentation for current Go package
   - [Free symbols](web.md#freesymbols): show symbols used by a selected block of code
   - [Assembly](web.md#assembly): show listing of assembly code for selected function
+  - [Split package](web.md#splitpkg): split a package into two or more components
 - Support for non-Go files:
   - [Template files](templates.md): files parsed by `text/template` and `html/template`
   - [go.mod and go.work files](modfiles.md): Go module and workspace manifests
-  - [Go *.s assembly files](assembly.ms): Go assembly files
+  - [Go *.s assembly files](assembly.md): Go assembly files
 - [Command-line interface](../command-line.md): CLI for debugging and scripting (unstable)
 
 You can find this page from within your editor by executing the

gopls/doc/assets/splitpkg.png

@@ -149,3 +149,35 @@ Client support:
 - **VS Code**: Use the "Source Action... > Browse GOARCH assembly for f" menu.
 - **Emacs + eglot**: Use `M-x go-browse-assembly` in [go-mode](https://github.com/dominikh/go-mode.el).
 - **Vim + coc.nvim**: ??
+
+
+<a name='splitpkg'></a>
+## `source.splitPackage`: Split package into components
+
+The web-based "Split package" tool can help you split a complex
+package into two or more components, ensuring that the dependencies
+among those components are acyclic.
+
+Follow the instructions on the page to choose a set of named components,
+assign each declaration to the most appropriate component, and then
+visualize the dependencies between those components created by references
+from one symbol to another.
+
+The figure below shows the tool operating on the `fmt` package, which
+could (in principle) be split into three subpackages, one for
+formatting (`Printf` and friends), one for scanning (`Scanf`), and one
+for their common dependencies.
+
+<img title="Split package 'fmt'" src="../assets/splitpkg.png">
+
+(Try playing with the tool on this package: it's an instructive
+exercise. The figure below shows the solution.)
+
+<img title="Split package 'fmt'" src="../assets/splitpkg-deps.png">
+
+The tool does not currently perform the code transformation (moving
+declarations to new packages, renaming symbols to export them as
+needed), but we hope to add that in a future release.
+
+Client support:
+- **VS Code**: Use the "Source Action... > Split package P" menu.

gopls/doc/features/README.md

@@ -2,6 +2,27 @@
 
 # Navigation features
 
+# Web-based features
+
+## "Split package" tool
+
+The `source.splitPackage` code action opens a web-based tool that
+helps you split a package into two or more components whose
+dependencies are acyclic.
+
+To use it, name a set of components, assign each declaration to a
+component, then visualize the dependencies among the components
+(including whether they form a cycle).
+Refresh the page each time you edit your code to see the latest
+information.
+
+<img title="Split package 'fmt'" src="../assets/splitpkg.png">
+
+The tool makes it easy to iterate over potential decompositions
+until you find one you are happy with. A future version of
+the tool will automate the code transformation, but for now
+you must do that step by hand.
+
 ## $feature
 
 <!-- golang/go#$issue -->

gopls/doc/features/web.md

@@ -1024,6 +1024,8 @@ type C struct{}
 		res.checkExit(true)
 		got := res.stdout
 		want := `command	"Browse documentation for package a" [source.doc]` +
+			"\n" +
+			`command	"Split package \"a\"" [source.splitPackage]` +
 			"\n" +
 			`command	"Show compiler optimization details for \"a\"" [source.toggleCompilerOptDetails]` +
 			"\n"

gopls/doc/release/v0.20.0.md

@@ -57,19 +57,19 @@ func AssemblyHTML(ctx context.Context, snapshot *cache.Snapshot, w http.Response
 	escape := html.EscapeString
 
 	// Emit the start of the report.
-	title := fmt.Sprintf("%s assembly for %s",
+	titleHTML := fmt.Sprintf("%s assembly for %s",
 		escape(snapshot.View().GOARCH()),
 		escape(symbol))
 	io.WriteString(w, `<!DOCTYPE html>
 <html>
 <head>
   <meta charset="UTF-8">
-  <title>`+escape(title)+`</title>
+  <title>`+titleHTML+`</title>
   <link rel="stylesheet" href="/assets/common.css">
   <script src="/assets/common.js"></script>
 </head>
 <body>
-<h1>`+title+`</h1>
+<h1>`+titleHTML+`</h1>
 <p>
   <a href='https://go.dev/doc/asm'>A Quick Guide to Go's Assembler</a>
 </p>

gopls/internal/cmd/integration_test.go

@@ -242,6 +242,7 @@ var codeActionProducers = [...]codeActionProducer{
 	{kind: settings.GoAssembly, fn: goAssembly, needPkg: true},
 	{kind: settings.GoDoc, fn: goDoc, needPkg: true},
 	{kind: settings.GoFreeSymbols, fn: goFreeSymbols},
+	{kind: settings.GoSplitPackage, fn: goSplitPackage, needPkg: true},
 	{kind: settings.GoTest, fn: goTest, needPkg: true},
 	{kind: settings.GoToggleCompilerOptDetails, fn: toggleCompilerOptDetails},
 	{kind: settings.RefactorExtractFunction, fn: refactorExtractFunction},
@@ -440,6 +441,23 @@ func goFreeSymbols(ctx context.Context, req *codeActionsRequest) error {
 	return nil
 }
 
+// goSplitPackage produces "Split package p" code actions.
+// See [server.commandHandler.SplitPackage] for command implementation.
+func goSplitPackage(ctx context.Context, req *codeActionsRequest) error {
+	// TODO(adonovan): ideally we would key by the package path,
+	// or the ID of the widest package for the current file,
+	// so that we don't see different results when toggling
+	// between p.go and p_test.go.
+	//
+	// TODO(adonovan): opt: req should always provide metadata so
+	// that we don't have to request type checking (needPkg=true).
+	meta := req.pkg.Metadata()
+	title := fmt.Sprintf("Split package %q", meta.Name)
+	cmd := command.NewSplitPackageCommand(title, req.snapshot.View().ID(), string(meta.ID))
+	req.addCommandAction(cmd, false)
+	return nil
+}
+
 // goplsDocFeatures produces "Browse gopls feature documentation" code actions.
 // See [server.commandHandler.ClientOpenURL] for command implementation.
 func goplsDocFeatures(ctx context.Context, req *codeActionsRequest) error {

gopls/internal/golang/assembly.go

@@ -0,0 +1,101 @@
+// 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 splitpkg
+
+// SCC algorithm stolen from cmd/digraph.
+
+type (
+	graph    = map[int]map[int]bool
+	nodeList = []int
+	nodeSet  = map[int]bool
+)
+
+// addNode ensures a node exists in the graph with an initialized edge set.
+func addNode(g graph, node int) map[int]bool {
+	edges := g[node]
+	if edges == nil {
+		edges = make(map[int]bool)
+		g[node] = edges
+	}
+	return edges
+}
+
+// addEdges adds one or more edges from a 'from' node.
+func addEdges(g graph, from int, to ...int) {
+	edges := addNode(g, from)
+	for _, toNode := range to {
+		addNode(g, toNode)
+		edges[toNode] = true
+	}
+}
+
+// transpose creates the transpose (reverse) of the graph.
+func transpose(g graph) graph {
+	rev := make(graph)
+	for node, edges := range g {
+		addNode(rev, node) // Ensure all nodes exist in the transposed graph
+		for succ := range edges {
+			addEdges(rev, succ, node)
+		}
+	}
+	return rev
+}
+
+// sccs returns the non-trivial strongly connected components of the graph.
+func sccs(g graph) []nodeSet {
+	// Kosaraju's algorithm---Tarjan is overkill here.
+	//
+	// TODO(adonovan): factor with Tarjan's algorithms from
+	// go/ssa/dom.go,
+	// go/callgraph/vta/propagation.go,
+	// ../../cache/typerefs/refs.go,
+	// ../../cache/metadata/graph.go.
+
+	// Forward pass.
+	S := make(nodeList, 0, len(g)) // postorder stack
+	seen := make(nodeSet)
+	var visit func(node int)
+	visit = func(node int) {
+		if !seen[node] {
+			seen[node] = true
+			for e := range g[node] {
+				visit(e)
+			}
+			S = append(S, node)
+		}
+	}
+	for node := range g {
+		visit(node)
+	}
+
+	// Reverse pass.
+	rev := transpose(g)
+	var scc nodeSet
+	seen = make(nodeSet)
+	var rvisit func(node int)
+	rvisit = func(node int) {
+		if !seen[node] {
+			seen[node] = true
+			scc[node] = true
+			for e := range rev[node] {
+				rvisit(e)
+			}
+		}
+	}
+	var sccs []nodeSet
+	for len(S) > 0 {
+		top := S[len(S)-1]
+		S = S[:len(S)-1] // pop
+		if !seen[top] {
+			scc = make(nodeSet)
+			rvisit(top)
+			if len(scc) == 1 && !g[top][top] {
+				continue
+			}
+			sccs = append(sccs, scc)
+		}
+	}
+	return sccs
+}