gopls: add WorkspaceFiles option

WorkspaceFiles allows an end-user to specify a set of files which, when
modified, will trigger a full reload of any views currently open in a
session. This is especially important for users who use custom
GOPACKAGESDRIVERS, as previously, you were forced to restart the
language server in order to get up-to-date diagnostics in some certain
instances.

For golang/go#59625

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

Author: rv32ima

gopls/doc/settings.md

@@ -143,6 +143,16 @@ This setting is only supported when gopls is built with Go 1.16 or later.
 
 Default: `["ignore"]`.
 
+<a id='workspaceFiles'></a>
+### `workspaceFiles []string`
+
+workspaceFiles configures the set of globs that match files defining the logical build of the current workspace.
+Any on-disk changes to any files matching a glob specified here will trigger a reload of the workspace.
+
+This setting need only be customized in environments with a custom GOPACKAGESDRIVER.
+
+Default: `[]`.
+
 <a id='formatting'></a>
 ## Formatting
 

gopls/internal/cache/session.go

@@ -775,6 +775,25 @@ func (s *Session) DidModifyFiles(ctx context.Context, modifications []file.Modif
 	// changed on disk.
 	checkViews := false
 
+	// Hack: collect folders from existing views.
+	// TODO(golang/go#57979): we really should track folders independent of
+	// Views, but since we always have a default View for each folder, this
+	// works for now.
+	var folders []*Folder // preserve folder order
+	workspaceFileGlobsSet := make(map[string]bool)
+	seen := make(map[*Folder]unit)
+	for _, v := range s.views {
+		if _, ok := seen[v.folder]; ok {
+			continue
+		}
+		seen[v.folder] = unit{}
+		folders = append(folders, v.folder)
+		for _, glob := range v.folder.Options.WorkspaceFiles {
+			workspaceFileGlobsSet[glob] = true
+		}
+	}
+	workspaceFileGlobs := slices.Collect(maps.Keys(workspaceFileGlobsSet))
+
 	changed := make(map[protocol.DocumentURI]file.Handle)
 	for _, c := range modifications {
 		fh := mustReadFile(ctx, s, c.URI)
@@ -790,7 +809,7 @@ func (s *Session) DidModifyFiles(ctx context.Context, modifications []file.Modif
 		// TODO(rfindley): go.work files need not be named "go.work" -- we need to
 		// check each view's source to handle the case of an explicit GOWORK value.
 		// Write a test that fails, and fix this.
-		if (isGoWork(c.URI) || isGoMod(c.URI)) && (c.Action == file.Save || c.OnDisk) {
+		if (isGoWork(c.URI) || isGoMod(c.URI) || isWorkspaceFile(c.URI, workspaceFileGlobs)) && (c.Action == file.Save || c.OnDisk) {
 			checkViews = true
 		}
 
@@ -817,20 +836,6 @@ func (s *Session) DidModifyFiles(ctx context.Context, modifications []file.Modif
 	}
 
 	if checkViews {
-		// Hack: collect folders from existing views.
-		// TODO(golang/go#57979): we really should track folders independent of
-		// Views, but since we always have a default View for each folder, this
-		// works for now.
-		var folders []*Folder // preserve folder order
-		seen := make(map[*Folder]unit)
-		for _, v := range s.views {
-			if _, ok := seen[v.folder]; ok {
-				continue
-			}
-			seen[v.folder] = unit{}
-			folders = append(folders, v.folder)
-		}
-
 		var openFiles []protocol.DocumentURI
 		for _, o := range s.Overlays() {
 			openFiles = append(openFiles, o.URI())
@@ -1085,11 +1090,12 @@ func (b brokenFile) Content() ([]byte, error)  { return nil, b.err }
 //
 // This set includes
 //  1. all go.mod and go.work files in the workspace; and
-//  2. for each Snapshot, its modules (or directory for ad-hoc views). In
+//  2. all files defined by the WorkspaceFiles option in BuildOptions (to support custom GOPACKAGESDRIVERS); and
+//  3. for each Snapshot, its modules (or directory for ad-hoc views). In
 //     module mode, this is the set of active modules (and for VS Code, all
 //     workspace directories within them, due to golang/go#42348).
 //
-// The watch for workspace go.work and go.mod files in (1) is sufficient to
+// The watch for workspace files in (1) is sufficient to
 // capture changes to the repo structure that may affect the set of views.
 // Whenever this set changes, we reload the workspace and invalidate memoized
 // files.

gopls/internal/cache/snapshot.go

@@ -799,6 +799,10 @@ func (s *Snapshot) fileWatchingGlobPatterns() map[protocol.RelativePattern]unit
 		patterns[workPattern] = unit{}
 	}
 
+	for _, glob := range s.Options().WorkspaceFiles {
+		patterns[protocol.RelativePattern{Pattern: glob}] = unit{}
+	}
+
 	extensions := "go,mod,sum,work"
 	for _, ext := range s.Options().TemplateExtensions {
 		extensions += "," + ext
@@ -1540,24 +1544,31 @@ func (s *Snapshot) clone(ctx, bgCtx context.Context, changed StateChange, done f
 	}
 
 	reinit := false
-
-	// Changes to vendor tree may require reinitialization,
-	// either because of an initialization error
-	// (e.g. "inconsistent vendoring detected"), or because
-	// one or more modules may have moved into or out of the
-	// vendor tree after 'go mod vendor' or 'rm -fr vendor/'.
-	//
-	// In this case, we consider the actual modification to see if was a creation
-	// or deletion.
-	//
-	// TODO(rfindley): revisit the location of this check.
 	for _, mod := range changed.Modifications {
+		// Changes to vendor tree may require reinitialization,
+		// either because of an initialization error
+		// (e.g. "inconsistent vendoring detected"), or because
+		// one or more modules may have moved into or out of the
+		// vendor tree after 'go mod vendor' or 'rm -fr vendor/'.
+		//
+		// In this case, we consider the actual modification to see if was a creation
+		// or deletion.
+		//
+		// TODO(rfindley): revisit the location of this check.
 		if inVendor(mod.URI) && (mod.Action == file.Create || mod.Action == file.Delete) ||
 			strings.HasSuffix(string(mod.URI), "/vendor/modules.txt") {
 
 			reinit = true
 			break
 		}
+
+		// Changes to workspace files, as a rule of thumb, should require reinitialization. Since their behavior
+		// is generally user-defined, we want to do something sensible by re-triggering a query to the active GOPACKAGESDRIVER,
+		// and reloading the state of the workspace.
+		if isWorkspaceFile(mod.URI, s.view.folder.Options.WorkspaceFiles) && (mod.Action == file.Save || mod.OnDisk) {
+			reinit = true
+			break
+		}
 	}
 
 	// Collect observed file handles for changed URIs from the old snapshot, if

gopls/internal/cache/workspace.go

@@ -13,6 +13,7 @@ import (
 	"golang.org/x/mod/modfile"
 	"golang.org/x/tools/gopls/internal/file"
 	"golang.org/x/tools/gopls/internal/protocol"
+	"golang.org/x/tools/gopls/internal/test/integration/fake/glob"
 )
 
 // isGoWork reports if uri is a go.work file.
@@ -65,6 +66,21 @@ func isGoMod(uri protocol.DocumentURI) bool {
 	return filepath.Base(uri.Path()) == "go.mod"
 }
 
+// isWorkspaceFile reports if uri matches a set of globs defined in workspaceFiles
+func isWorkspaceFile(uri protocol.DocumentURI, workspaceFiles []string) bool {
+	for _, workspaceFile := range workspaceFiles {
+		g, err := glob.Parse(workspaceFile)
+		if err != nil {
+			continue
+		}
+
+		if g.Match(uri.Path()) {
+			return true
+		}
+	}
+	return false
+}
+
 // goModModules returns the URIs of "workspace" go.mod files defined by a
 // go.mod file. This set is defined to be the given go.mod file itself, as well
 // as the modfiles of any locally replaced modules in the go.mod file.

gopls/internal/doc/api.json

@@ -99,6 +99,19 @@
 				"Hierarchy": "build",
 				"DeprecationMessage": ""
 			},
+			{
+				"Name": "workspaceFiles",
+				"Type": "[]string",
+				"Doc": "workspaceFiles configures the set of globs that match files defining the logical build of the current workspace.\nAny on-disk changes to any files matching a glob specified here will trigger a reload of the workspace.\n\nThis setting need only be customized in environments with a custom GOPACKAGESDRIVER.\n",
+				"EnumKeys": {
+					"ValueType": "",
+					"Keys": null
+				},
+				"EnumValues": null,
+				"Default": "[]",
+				"Status": "",
+				"Hierarchy": "build"
+			},
 			{
 				"Name": "hoverKind",
 				"Type": "enum",

gopls/internal/settings/default.go

@@ -87,6 +87,7 @@ func DefaultOptions(overrides ...func(*Options)) *Options {
 					DirectoryFilters:        []string{"-**/node_modules"},
 					TemplateExtensions:      []string{},
 					StandaloneTags:          []string{"ignore"},
+					WorkspaceFiles:          []string{},
 				},
 				UIOptions: UIOptions{
 					DiagnosticOptions: DiagnosticOptions{

gopls/internal/settings/settings.go

@@ -141,6 +141,12 @@ type BuildOptions struct {
 	//
 	// This setting is only supported when gopls is built with Go 1.16 or later.
 	StandaloneTags []string
+
+	// WorkspaceFiles configures the set of globs that match files defining the logical build of the current workspace.
+	// Any on-disk changes to any files matching a glob specified here will trigger a reload of the workspace.
+	//
+	// This setting need only be customized in environments with a custom GOPACKAGESDRIVER.
+	WorkspaceFiles []string
 }
 
 // Note: UIOptions must be comparable with reflect.DeepEqual.
@@ -970,6 +976,8 @@ func (o *Options) setOne(name string, value any) error {
 		}
 		o.DirectoryFilters = filters
 
+	case "workspaceFiles":
+		return setStringSlice(&o.WorkspaceFiles, value)
 	case "completionDocumentation":
 		return setBool(&o.CompletionDocumentation, value)
 	case "usePlaceholders":