LSP add autocompletion for basic keywords, syntax, package and imports (#4067)

Author: emcfarlane

go.mod

@@ -16,7 +16,7 @@ require (
 	buf.build/go/standard v0.1.0
 	connectrpc.com/connect v1.19.1
 	connectrpc.com/otelconnect v0.8.0
-	github.com/bufbuild/protocompile v0.14.2-0.20251016020322-1e423fd4469c
+	github.com/bufbuild/protocompile v0.14.2-0.20251017100351-4264d1ccf8d2
 	github.com/bufbuild/protoplugin v0.0.0-20250218205857-750e09ce93e1
 	github.com/docker/docker v28.5.1+incompatible
 	github.com/go-chi/chi/v5 v5.2.3

go.sum

@@ -40,8 +40,8 @@ github.com/antlr4-go/antlr/v4 v4.13.1 h1:SqQKkuVZ+zWkMMNkjy5FZe5mr5WURWnlpmOuzYW
 github.com/antlr4-go/antlr/v4 v4.13.1/go.mod h1:GKmUxMtwp6ZgGwZSva4eWPC5mS6vUAmOABFgjdkM7Nw=
 github.com/bmatcuk/doublestar/v4 v4.9.1 h1:X8jg9rRZmJd4yRy7ZeNDRnM+T3ZfHv15JiBJ/avrEXE=
 github.com/bmatcuk/doublestar/v4 v4.9.1/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=
-github.com/bufbuild/protocompile v0.14.2-0.20251016020322-1e423fd4469c h1:tUqu5Z1NlNlyZvd9DhGeoTM9v2FPR90BRaz7kqf+Cc4=
-github.com/bufbuild/protocompile v0.14.2-0.20251016020322-1e423fd4469c/go.mod h1:HKN246DRQwavs64sr2xYmSL+RFOFxmLti+WGCZ2jh9U=
+github.com/bufbuild/protocompile v0.14.2-0.20251017100351-4264d1ccf8d2 h1:7z/G5WYy7lwnK8WmRywHxr3kKGCU3zHEjz3mTykycA8=
+github.com/bufbuild/protocompile v0.14.2-0.20251017100351-4264d1ccf8d2/go.mod h1:HKN246DRQwavs64sr2xYmSL+RFOFxmLti+WGCZ2jh9U=
 github.com/bufbuild/protoplugin v0.0.0-20250218205857-750e09ce93e1 h1:V1xulAoqLqVg44rY97xOR+mQpD2N+GzhMHVwJ030WEU=
 github.com/bufbuild/protoplugin v0.0.0-20250218205857-750e09ce93e1/go.mod h1:c5D8gWRIZ2HLWO3gXYTtUfw/hbJyD8xikv2ooPxnklQ=
 github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=

private/buf/buflsp/completion.go

@@ -0,0 +1,308 @@
+// Copyright 2020-2025 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// This file implements code completion support for the LSP.
+
+package buflsp
+
+import (
+	"context"
+	"fmt"
+	"iter"
+	"log/slog"
+	"slices"
+	"strings"
+
+	"github.com/bufbuild/buf/private/pkg/normalpath"
+	"github.com/bufbuild/protocompile/experimental/ast"
+	"github.com/bufbuild/protocompile/experimental/ast/syntax"
+	"github.com/bufbuild/protocompile/experimental/seq"
+	"github.com/bufbuild/protocompile/experimental/token/keyword"
+	"go.lsp.dev/protocol"
+)
+
+// getCompletionItems returns completion items for the given position in the file.
+//
+// This function is called by the Completion handler in server.go.
+func getCompletionItems(
+	ctx context.Context,
+	file *file,
+	position protocol.Position,
+) []protocol.CompletionItem {
+	if file.ir.AST().IsZero() {
+		file.lsp.logger.DebugContext(
+			ctx,
+			"no AST found for completion",
+			slog.String("file", file.uri.Filename()),
+		)
+		return nil
+	}
+
+	declPath := getDeclForPosition(file.ir.AST().DeclBody, position)
+	if len(declPath) > 0 {
+		decl := declPath[len(declPath)-1]
+		file.lsp.logger.DebugContext(
+			ctx,
+			"completion: found declaration",
+			slog.String("decl_kind", decl.Kind().String()),
+			slog.Any("decl_span_start", decl.Span().StartLoc()),
+			slog.Any("decl_span_end", decl.Span().EndLoc()),
+			slog.Int("path_depth", len(declPath)),
+		)
+	} else {
+		file.lsp.logger.DebugContext(ctx, "completion: no declaration found at position")
+		return nil
+	}
+
+	// Return context-aware completions based on the declaration type.
+	return completionItemsForDeclPath(ctx, file, declPath, position)
+}
+
+// completionItemsForDeclPath returns completion items based on the AST declaration path at the cursor.
+// The declPath is a slice from parent to smallest declaration, where [0] is the top-level and [len-1] is the innermost.
+func completionItemsForDeclPath(ctx context.Context, file *file, declPath []ast.DeclAny, position protocol.Position) []protocol.CompletionItem {
+	if len(declPath) == 0 {
+		return nil
+	}
+
+	// Get the innermost (smallest) declaration.
+	decl := declPath[len(declPath)-1]
+	file.lsp.logger.DebugContext(
+		ctx,
+		"completion: processing declaration",
+		slog.String("kind", decl.Kind().String()),
+	)
+
+	// Return context-specific completions based on declaration type.
+	switch decl.Kind() {
+	case ast.DeclKindInvalid:
+		file.lsp.logger.DebugContext(ctx, "completion: ignoring invalid declaration")
+		return nil
+	case ast.DeclKindDef:
+		return completionItemsForDef(ctx, file, declPath, decl.AsDef(), position)
+	case ast.DeclKindSyntax:
+		return completionItemsForSyntax(ctx, file, decl.AsSyntax())
+	case ast.DeclKindPackage:
+		return completionItemsForPackage(ctx, file, decl.AsPackage())
+	case ast.DeclKindImport:
+		return completionItemsForImport(ctx, file)
+	default:
+		file.lsp.logger.DebugContext(ctx, "completion: unknown declaration type", slog.String("kind", decl.Kind().String()))
+		return nil
+	}
+}
+
+// completionItemsForSyntax returns the completion items for the files syntax.
+func completionItemsForSyntax(ctx context.Context, file *file, syntaxDecl ast.DeclSyntax) []protocol.CompletionItem {
+	file.lsp.logger.DebugContext(ctx, "completion: syntax declaration", slog.Bool("is_edition", syntaxDecl.IsEdition()))
+
+	var prefix string
+	if syntaxDecl.Equals().IsZero() {
+		prefix += "= "
+	}
+	var syntaxes iter.Seq[syntax.Syntax]
+	if syntaxDecl.IsEdition() {
+		syntaxes = syntax.Editions()
+	} else {
+		syntaxes = func(yield func(syntax.Syntax) bool) {
+			_ = yield(syntax.Proto2) &&
+				yield(syntax.Proto3)
+		}
+	}
+	var items []protocol.CompletionItem
+	for syntax := range syntaxes {
+		items = append(items, protocol.CompletionItem{
+			Label: fmt.Sprintf("%s%q;", prefix, syntax),
+			Kind:  protocol.CompletionItemKindValue,
+		})
+	}
+	return items
+}
+
+// completionItemsForPackage returns the completion items for the package name.
+//
+// Suggest the package name based on the filepath.
+func completionItemsForPackage(ctx context.Context, file *file, syntaxPackage ast.DeclPackage) []protocol.CompletionItem {
+	components := normalpath.Components(file.objectInfo.Path())
+	suggested := components[:len(components)-1] // Strip the filename.
+	if len(suggested) == 0 {
+		file.lsp.logger.DebugContext(ctx, "completion: package at root, no suggestions")
+		return nil // File is at root, return no suggestions.
+	}
+	file.lsp.logger.DebugContext(ctx, "completion: package suggestion", slog.String("package", strings.Join(suggested, ".")))
+	return []protocol.CompletionItem{{
+		Label: strings.Join(suggested, ".") + ";",
+		Kind:  protocol.CompletionItemKindSnippet,
+	}}
+}
+
+// completionItemsForDef returns completion items for definition declarations (message, enum, service, etc.).
+func completionItemsForDef(ctx context.Context, file *file, declPath []ast.DeclAny, def ast.DeclDef, position protocol.Position) []protocol.CompletionItem {
+	file.lsp.logger.DebugContext(
+		ctx,
+		"completion: definition",
+		slog.String("type", def.Type().Span().String()),
+		slog.String("name", def.Name().Span().String()),
+		slog.String("def_kind", def.Classify().String()),
+		slog.Int("path_depth", len(declPath)),
+		slog.Any("decl_span_start", def.Span().StartLoc()),
+		slog.Any("decl_span_end", def.Span().EndLoc()),
+	)
+
+	// Check if cursor is in the name of the definition, if so ignore.
+	if !def.Name().IsZero() {
+		nameSpan := def.Name().Span()
+		within := reportSpanToProtocolRange(nameSpan)
+		if positionInRange(position, within) == 0 {
+			file.lsp.logger.DebugContext(
+				ctx,
+				"completion: ignoring definition name",
+				slog.String("def_kind", def.Classify().String()),
+			)
+			return nil
+		}
+	}
+	// Check if the cursor is outside the type, if so ignore.
+	if !def.Type().IsZero() {
+		typeSpan := def.Type().Span()
+		within := reportSpanToProtocolRange(typeSpan)
+		if positionInRange(position, within) > 0 {
+			file.lsp.logger.DebugContext(
+				ctx,
+				"completion: ignoring definition passed type",
+				slog.String("def_kind", def.Classify().String()),
+			)
+			return nil
+		}
+	}
+
+	switch def.Classify() {
+	case ast.DefKindMessage:
+		return nil
+	case ast.DefKindService:
+		return nil
+	case ast.DefKindEnum:
+		return nil
+	default:
+		// If this is an invalid definition at the top level, return top-level keywords.
+		if len(declPath) == 1 {
+			file.lsp.logger.DebugContext(ctx, "completion: unknown definition at top level, returning top-level keywords")
+			return slices.Collect(topLevelCompletionItems())
+		}
+		file.lsp.logger.DebugContext(ctx, "completion: unknown definition type (not at top level)")
+		return nil
+	}
+}
+
+// completionItemsForImport returns completion items for import declarations.
+//
+// Suggest all importable files.
+func completionItemsForImport(ctx context.Context, file *file) []protocol.CompletionItem {
+	file.lsp.logger.DebugContext(ctx, "completion: import declaration", slog.Int("importable_count", len(file.importToFile)))
+
+	items := make([]protocol.CompletionItem, 0, len(file.importToFile))
+	for importPath := range file.importToFile {
+		items = append(items, protocol.CompletionItem{
+			Label: " \"" + importPath + "\";",
+			Kind:  protocol.CompletionItemKindFile,
+		})
+	}
+	slices.SortFunc(items, func(a, b protocol.CompletionItem) int {
+		return strings.Compare(strings.ToLower(a.Label), strings.ToLower(b.Label))
+	})
+	return items
+}
+
+// topLevelCompletionItems returns completion items for top-level proto keywords.
+func topLevelCompletionItems() iter.Seq[protocol.CompletionItem] {
+	return func(yield func(protocol.CompletionItem) bool) {
+		_ = yield(keywordToCompletionItem(keyword.Syntax)) &&
+			yield(keywordToCompletionItem(keyword.Edition)) &&
+			yield(keywordToCompletionItem(keyword.Import)) &&
+			yield(keywordToCompletionItem(keyword.Package)) &&
+			yield(keywordToCompletionItem(keyword.Message)) &&
+			yield(keywordToCompletionItem(keyword.Service)) &&
+			yield(keywordToCompletionItem(keyword.Option)) &&
+			yield(keywordToCompletionItem(keyword.Enum)) &&
+			yield(keywordToCompletionItem(keyword.Extend))
+	}
+}
+
+// keywordToCompletionItem converts a keyword to a completion item.
+func keywordToCompletionItem(kw keyword.Keyword) protocol.CompletionItem {
+	return protocol.CompletionItem{
+		Label: kw.String(),
+		Kind:  protocol.CompletionItemKindKeyword,
+	}
+}
+
+// getDeclForPosition finds the path of AST declarations from parent to smallest that contains the given protocol position.
+// Returns a slice where [0] is the top-level declaration and [len-1] is the smallest/innermost declaration.
+// Returns nil if no declaration contains the position.
+func getDeclForPosition(body ast.DeclBody, position protocol.Position) []ast.DeclAny {
+	return getDeclForPositionHelper(body, position, nil)
+}
+
+// getDeclForPositionHelper is the recursive helper for getDeclForPosition.
+func getDeclForPositionHelper(body ast.DeclBody, position protocol.Position, path []ast.DeclAny) []ast.DeclAny {
+	smallestSize := -1
+	var bestPath []ast.DeclAny
+
+	for decl := range seq.Values(body.Decls()) {
+		if decl.IsZero() {
+			continue
+		}
+		span := decl.Span()
+		if span.IsZero() {
+			continue
+		}
+
+		// Check if the position is within this declaration's span.
+		within := reportSpanToProtocolRange(span)
+		if positionInRange(position, within) == 0 {
+			// Build the new path including this declaration.
+			newPath := append(append([]ast.DeclAny(nil), path...), decl)
+			size := span.End - span.Start
+			if smallestSize == -1 || size < smallestSize {
+				bestPath = newPath
+				smallestSize = size
+			}
+
+			// If this is a definition with a body, search recursively.
+			if decl.Kind() == ast.DeclKindDef && !decl.AsDef().Body().IsZero() {
+				childPath := getDeclForPositionHelper(decl.AsDef().Body(), position, newPath)
+				if len(childPath) > 0 {
+					childSize := childPath[len(childPath)-1].Span().End - childPath[len(childPath)-1].Span().Start
+					if childSize < smallestSize {
+						bestPath = childPath
+						smallestSize = childSize
+					}
+				}
+			}
+		}
+	}
+	return bestPath
+}
+
+// resolveCompletionItem resolves additional details for a completion item.
+//
+// This function is called by the CompletionResolve handler in server.go.
+func resolveCompletionItem(
+	ctx context.Context,
+	item *protocol.CompletionItem,
+) (*protocol.CompletionItem, error) {
+	// TODO: Implement completion resolution logic.
+	// For now, just return the item unchanged.
+	return item, nil
+}

private/buf/buflsp/server.go

@@ -123,6 +123,10 @@ func (s *server) Initialize(
 					IncludeText: false,
 				},
 			},
+			CompletionProvider: &protocol.CompletionOptions{
+				ResolveProvider:   true,
+				TriggerCharacters: []string{" ", ".", "("},
+			},
 			DefinitionProvider: &protocol.DefinitionOptions{
 				WorkDoneProgressOptions: protocol.WorkDoneProgressOptions{WorkDoneProgress: true},
 			},
@@ -418,6 +422,27 @@ func (s *server) References(
 	return symbol.References(), nil
 }
 
+// Completion is the entry point for code completion.
+func (s *server) Completion(
+	ctx context.Context,
+	params *protocol.CompletionParams,
+) (*protocol.CompletionList, error) {
+	file := s.fileManager.Get(params.TextDocument.URI)
+	if file == nil {
+		return nil, nil
+	}
+	items := getCompletionItems(ctx, file, params.Position)
+	return &protocol.CompletionList{Items: items}, nil
+}
+
+// CompletionResolve is the entry point for resolving additional details for a completion item.
+func (s *server) CompletionResolve(
+	ctx context.Context,
+	params *protocol.CompletionItem,
+) (*protocol.CompletionItem, error) {
+	return resolveCompletionItem(ctx, params)
+}
+
 // SemanticTokensFull is called to render semantic token information on the client.
 func (s *server) SemanticTokensFull(
 	ctx context.Context,

private/buf/buflsp/symbol.go

@@ -375,7 +375,7 @@ func commentToMarkdown(comment string) string {
 	return strings.TrimSuffix(strings.TrimPrefix(comment, "/*"), "*/")
 }
 
-// comparePositions compares two ranges for lexicographic ordering.
+// comparePositions compares two positions for lexicographic ordering.
 func comparePositions(a, b protocol.Position) int {
 	diff := int(a.Line) - int(b.Line)
 	if diff == 0 {
@@ -384,6 +384,17 @@ func comparePositions(a, b protocol.Position) int {
 	return diff
 }
 
+// positionInRange returns 0 if a position is within the range, else returns -1 before or 1 after.
+func positionInRange(position protocol.Position, within protocol.Range) int {
+	if comparePositions(position, within.Start) < 0 {
+		return -1
+	}
+	if comparePositions(position, within.End) > 0 {
+		return 1
+	}
+	return 0
+}
+
 func reportSpanToProtocolRange(span report.Span) protocol.Range {
 	startLocation := span.File.Location(span.Start, positionalEncoding)
 	endLocation := span.File.Location(span.End, positionalEncoding)