gopls: automatically insert package clause for new go files

This CL introduces a new feature in gopls to handle didCreateFiles requests from the client. When a new Go file is created, gopls will automatically insert the appropriate package clause at the beginning of the file, streamlining the file initialization process.

Updates golang/go#72930

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

Author: xieyuschen

gopls/doc/release/v0.19.0.md

@@ -39,3 +39,10 @@ TODO: implement global.
 This code action, available on a dotted import, will offer to replace
 the import with a regular one and qualify each use of the package
 with its name.
+
+### Auto-complete package clause for new Go files
+
+Gopls now automatically adds the appropriate `package` clause to newly created Go files,
+so that you can immediately get started writing the interesting part.
+
+It requires client support for `workspace/didCreateFiles`

gopls/internal/cmd/cmd.go

@@ -343,15 +343,16 @@ func (c *connection) initialize(ctx context.Context, options func(*settings.Opti
 
 	// Make sure to respect configured options when sending initialize request.
 	opts := settings.DefaultOptions(options)
-	// If you add an additional option here, you must update the map key in connect.
+	// If you add an additional option here,
+	// you must update the map key of settings.DefaultOptions called in (*Application).connect.
 	params.Capabilities.TextDocument.Hover = &protocol.HoverClientCapabilities{
 		ContentFormat: []protocol.MarkupKind{opts.PreferredContentFormat},
 	}
 	params.Capabilities.TextDocument.DocumentSymbol.HierarchicalDocumentSymbolSupport = opts.HierarchicalDocumentSymbolSupport
 	params.Capabilities.TextDocument.SemanticTokens = protocol.SemanticTokensClientCapabilities{}
 	params.Capabilities.TextDocument.SemanticTokens.Formats = []protocol.TokenFormat{"relative"}
 	params.Capabilities.TextDocument.SemanticTokens.Requests.Range = &protocol.Or_ClientSemanticTokensRequestOptions_range{Value: true}
-	//params.Capabilities.TextDocument.SemanticTokens.Requests.Range.Value = true
+	// params.Capabilities.TextDocument.SemanticTokens.Requests.Range.Value = true
 	params.Capabilities.TextDocument.SemanticTokens.Requests.Full = &protocol.Or_ClientSemanticTokensRequestOptions_full{Value: true}
 	params.Capabilities.TextDocument.SemanticTokens.TokenTypes = moreslices.ConvertStrings[string](semtok.TokenTypes)
 	params.Capabilities.TextDocument.SemanticTokens.TokenModifiers = moreslices.ConvertStrings[string](semtok.TokenModifiers)
@@ -363,6 +364,9 @@ func (c *connection) initialize(ctx context.Context, options func(*settings.Opti
 		},
 	}
 	params.Capabilities.Window.WorkDoneProgress = true
+	params.Capabilities.Workspace.FileOperations = &protocol.FileOperationClientCapabilities{
+		DidCreate: true,
+	}
 
 	params.InitializationOptions = map[string]any{
 		"symbolMatcher": string(opts.SymbolMatcher),
@@ -817,10 +821,10 @@ func (c *connection) diagnoseFiles(ctx context.Context, files []protocol.Documen
 }
 
 func (c *connection) terminate(ctx context.Context) {
-	//TODO: do we need to handle errors on these calls?
+	// TODO: do we need to handle errors on these calls?
 	c.Shutdown(ctx)
-	//TODO: right now calling exit terminates the process, we should rethink that
-	//server.Exit(ctx)
+	// TODO: right now calling exit terminates the process, we should rethink that
+	// server.Exit(ctx)
 }
 
 // Implement io.Closer.

gopls/internal/golang/addtest.go

@@ -319,7 +319,7 @@ func AddTestForFunc(ctx context.Context, snapshot *cache.Snapshot, loc protocol.
 		// package decl based on the originating file.
 		// Search for something that looks like a copyright header, to replicate
 		// in the new file.
-		if c := copyrightComment(pgf.File); c != nil {
+		if c := CopyrightComment(pgf.File); c != nil {
 			start, end, err := pgf.NodeOffsets(c)
 			if err != nil {
 				return nil, err

gopls/internal/golang/completion/newfile.go

@@ -0,0 +1,65 @@
+// 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 completion
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+
+	"golang.org/x/tools/gopls/internal/cache"
+	"golang.org/x/tools/gopls/internal/cache/parsego"
+	"golang.org/x/tools/gopls/internal/file"
+	"golang.org/x/tools/gopls/internal/golang"
+	"golang.org/x/tools/gopls/internal/protocol"
+)
+
+// NewFile returns a document change to complete an empty go file.
+func NewFile(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle) (*protocol.DocumentChange, error) {
+	if bs, err := fh.Content(); err != nil || len(bs) != 0 {
+		return nil, err
+	}
+	meta, err := golang.NarrowestMetadataForFile(ctx, snapshot, fh.URI())
+	if err != nil {
+		return nil, err
+	}
+	var buf bytes.Buffer
+	// Copy the copyright header from the first existing file that has one.
+	for _, fileURI := range meta.GoFiles {
+		if fileURI == fh.URI() {
+			continue
+		}
+		fh, err := snapshot.ReadFile(ctx, fileURI)
+		if err != nil {
+			continue
+		}
+		pgf, err := snapshot.ParseGo(ctx, fh, parsego.Header)
+		if err != nil {
+			continue
+		}
+		if group := golang.CopyrightComment(pgf.File); group != nil {
+			start, end, err := pgf.NodeOffsets(group)
+			if err != nil {
+				continue
+			}
+			buf.Write(pgf.Src[start:end])
+			buf.WriteString("\n\n")
+			break
+		}
+	}
+
+	pkgName, err := bestPackage(ctx, snapshot, fh.URI())
+	if err != nil {
+		return nil, err
+	}
+
+	fmt.Fprintf(&buf, "package %s\n", pkgName)
+	change := protocol.DocumentChangeEdit(fh, []protocol.TextEdit{{
+		Range:   protocol.Range{}, // insert at start of file
+		NewText: buf.String(),
+	}})
+
+	return &change, nil
+}

gopls/internal/golang/completion/package.go

@@ -15,6 +15,7 @@ import (
 	"go/token"
 	"go/types"
 	"path/filepath"
+	"sort"
 	"strings"
 	"unicode"
 
@@ -27,6 +28,24 @@ import (
 	"golang.org/x/tools/gopls/internal/util/safetoken"
 )
 
+// bestPackage offers the best package name for a package declaration when
+// one is not present in the given file.
+func bestPackage(ctx context.Context, snapshot *cache.Snapshot, uri protocol.DocumentURI) (string, error) {
+	suggestions, err := packageSuggestions(ctx, snapshot, uri, "")
+	if err != nil {
+		return "", err
+	}
+	// sort with the same way of sortItems.
+	sort.SliceStable(suggestions, func(i, j int) bool {
+		if suggestions[i].score != suggestions[j].score {
+			return suggestions[i].score > suggestions[j].score
+		}
+		return suggestions[i].name < suggestions[j].name
+	})
+
+	return suggestions[0].name, nil
+}
+
 // packageClauseCompletions offers completions for a package declaration when
 // one is not present in the given file.
 func packageClauseCompletions(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle, position protocol.Position) ([]CompletionItem, *Selection, error) {

gopls/internal/golang/extracttofile.go

@@ -138,7 +138,7 @@ func ExtractToNewFile(ctx context.Context, snapshot *cache.Snapshot, fh file.Han
 	}
 
 	var buf bytes.Buffer
-	if c := copyrightComment(pgf.File); c != nil {
+	if c := CopyrightComment(pgf.File); c != nil {
 		start, end, err := pgf.NodeOffsets(c)
 		if err != nil {
 			return nil, err

gopls/internal/golang/util.go

@@ -361,9 +361,9 @@ func AbbreviateVarName(s string) string {
 	return b.String()
 }
 
-// copyrightComment returns the copyright comment group from the input file, or
+// CopyrightComment returns the copyright comment group from the input file, or
 // nil if not found.
-func copyrightComment(file *ast.File) *ast.CommentGroup {
+func CopyrightComment(file *ast.File) *ast.CommentGroup {
 	if len(file.Comments) == 0 {
 		return nil
 	}

gopls/internal/server/general.go

@@ -189,6 +189,15 @@ func (s *server) Initialize(ctx context.Context, params *protocol.ParamInitializ
 					Supported:           true,
 					ChangeNotifications: "workspace/didChangeWorkspaceFolders",
 				},
+				FileOperations: &protocol.FileOperationOptions{
+					DidCreate: &protocol.FileOperationRegistrationOptions{
+						Filters: []protocol.FileOperationFilter{{
+							Scheme: "file",
+							// gopls is only interested with files in .go extension.
+							Pattern: protocol.FileOperationPattern{Glob: "**/*.go"},
+						}},
+					},
+				},
 			},
 		},
 		ServerInfo: &protocol.ServerInfo{

gopls/internal/server/unimplemented.go

@@ -34,10 +34,6 @@ func (s *server) DidCloseNotebookDocument(context.Context, *protocol.DidCloseNot
 	return notImplemented("DidCloseNotebookDocument")
 }
 
-func (s *server) DidCreateFiles(context.Context, *protocol.CreateFilesParams) error {
-	return notImplemented("DidCreateFiles")
-}
-
 func (s *server) DidDeleteFiles(context.Context, *protocol.DeleteFilesParams) error {
 	return notImplemented("DidDeleteFiles")
 }

gopls/internal/server/workspace.go

@@ -12,6 +12,8 @@ import (
 	"sync"
 
 	"golang.org/x/tools/gopls/internal/cache"
+	"golang.org/x/tools/gopls/internal/file"
+	"golang.org/x/tools/gopls/internal/golang/completion"
 	"golang.org/x/tools/gopls/internal/protocol"
 	"golang.org/x/tools/gopls/internal/settings"
 	"golang.org/x/tools/internal/event"
@@ -139,3 +141,31 @@ func (s *server) DidChangeConfiguration(ctx context.Context, _ *protocol.DidChan
 
 	return nil
 }
+
+func (s *server) DidCreateFiles(ctx context.Context, params *protocol.CreateFilesParams) error {
+	ctx, done := event.Start(ctx, "lsp.Server.didCreateFiles")
+	defer done()
+
+	var allChanges []protocol.DocumentChange
+	for _, createdFile := range params.Files {
+		uri := protocol.DocumentURI(createdFile.URI)
+		fh, snapshot, release, err := s.fileOf(ctx, uri)
+		if err != nil {
+			event.Error(ctx, "fail to call fileOf", err)
+			continue
+		}
+		defer release()
+
+		switch snapshot.FileKind(fh) {
+		case file.Go:
+			change, err := completion.NewFile(ctx, snapshot, fh)
+			if err != nil {
+				continue
+			}
+			allChanges = append(allChanges, *change)
+		default:
+		}
+	}
+
+	return applyChanges(ctx, s.client, allChanges)
+}

gopls/internal/test/integration/fake/editor.go

@@ -1309,6 +1309,19 @@ func (e *Editor) Completion(ctx context.Context, loc protocol.Location) (*protoc
 	return completions, nil
 }
 
+func (e *Editor) DidCreateFiles(ctx context.Context, files ...protocol.DocumentURI) error {
+	if e.Server == nil {
+		return nil
+	}
+	params := &protocol.CreateFilesParams{}
+	for _, file := range files {
+		params.Files = append(params.Files, protocol.FileCreate{
+			URI: string(file),
+		})
+	}
+	return e.Server.DidCreateFiles(ctx, params)
+}
+
 func (e *Editor) SetSuggestionInsertReplaceMode(_ context.Context, useReplaceMode bool) {
 	e.mu.Lock()
 	defer e.mu.Unlock()