Clarify deduplicating references and respect includeDeclaration param (#4138)

Author: doriable

private/buf/buflsp/server.go

@@ -412,9 +412,14 @@ func (s *server) References(
 	if symbol == nil {
 		return nil, nil
 	}
-	// TODO: Determine why we have duplicate references here, and fix that instead of deduplicating at
-	// this level.
-	return xslices.Deduplicate(symbol.References()), nil
+	// We deduplicate the references here in the case where a file's symbols have not yet
+	// been refreshed, but a new file with references to symbols in said file is opened. This
+	// can cause duplicate references to be appended and not all clients deduplicate the
+	// returned references.
+	//
+	// We also do not want to refresh all symbols in the workspace when a single file is
+	// interacted with, since that could be detrimental to performance.
+	return xslices.Deduplicate(symbol.References(params.Context.IncludeDeclaration)), nil
 }
 
 // Completion is the entry point for code completion.

private/buf/buflsp/symbol.go

@@ -124,7 +124,9 @@ func (s *symbol) Definition() protocol.Location {
 
 // References returns the locations of references to the symbol (including the definition), if
 // applicable. Otherwise, it just returns the location of the symbol itself.
-func (s *symbol) References() []protocol.Location {
+// It also accepts the includeDeclaration param from the client - if true, the declaration
+// of the symbol is included as a reference.
+func (s *symbol) References(includeDeclaration bool) []protocol.Location {
 	var references []protocol.Location
 	referenceableKind, ok := s.kind.(*referenceable)
 	if !ok && s.def != nil {
@@ -146,12 +148,14 @@ func (s *symbol) References() []protocol.Location {
 			Range: s.Range(),
 		})
 	}
-	// Add the definition of the symbol to the list of references.
-	if s.def != nil {
-		references = append(references, protocol.Location{
-			URI:   s.def.file.uri,
-			Range: s.def.Range(),
-		})
+	if includeDeclaration {
+		// Add the definition of the symbol to the list of references.
+		if s.def != nil {
+			references = append(references, protocol.Location{
+				URI:   s.def.file.uri,
+				Range: s.def.Range(),
+			})
+		}
 	}
 	return references
 }