add document highlight for template control flow keywords

Implement textDocument/documentHighlight LSP capability to highlight matching
template control flow keywords (if/else/end, range/end, with/end, etc.).

When the cursor is on a template keyword like {{if}}, {{else}}, or {{end}},
all related keywords in the same control flow block are highlighted together.
This leverages the existing NextLinkedSibling circular list that the parser
already creates for control flow nodes.

Author: Jason-Abbott

.beans/gozer-w0ax--add-document-highlight-for-template-brace-matching.md

@@ -0,0 +1,26 @@
+---
+# gozer-w0ax
+title: Add document highlight for template brace matching
+status: completed
+type: feature
+priority: normal
+created_at: 2026-01-19T02:56:39Z
+updated_at: 2026-01-19T03:00:40Z
+---
+
+Implement textDocument/documentHighlight LSP capability to highlight matching template control flow keywords (e.g., clicking {{end}} highlights its corresponding {{if}}/{{range}}/etc.).
+
+## Background
+The parser already links matching template blocks via `NextLinkedSibling` pointers in `GroupStatementNode`. This creates a linked list connecting related control flow statements:
+```
+{{if .foo}} → {{else if .bar}} → {{else}} → {{end}}
+```
+
+## Checklist
+- [ ] Add DocumentHighlightProvider capability to server initialization
+- [ ] Add textDocument/documentHighlight method registration in protocol.go
+- [ ] Implement ProcessDocumentHighlightRequest in methods.go
+- [ ] Create helper to find GroupStatementNode at cursor position
+- [ ] Traverse NextLinkedSibling chain to collect all related keywords
+- [ ] Return highlight ranges for all matched keywords
+- [ ] Add tests for document highlight functionality

cmd/go-template-lsp/lsp/methods.go

@@ -87,10 +87,11 @@ type InitializeParams struct {
 
 // ServerCapabilities describes the capabilities this server supports.
 type ServerCapabilities struct {
-	TextDocumentSync     int  `json:"textDocumentSync"`
-	HoverProvider        bool `json:"hoverProvider"`
-	DefinitionProvider   bool `json:"definitionProvider"`
-	FoldingRangeProvider bool `json:"foldingRangeProvider"`
+	TextDocumentSync          int  `json:"textDocumentSync"`
+	HoverProvider             bool `json:"hoverProvider"`
+	DefinitionProvider        bool `json:"definitionProvider"`
+	FoldingRangeProvider      bool `json:"foldingRangeProvider"`
+	DocumentHighlightProvider bool `json:"documentHighlightProvider"`
 }
 
 // InitializeResult is the response to the initialize request.
@@ -217,10 +218,11 @@ func ProcessInitializeRequest(
 		Id:      req.Id,
 		Result: InitializeResult{
 			Capabilities: ServerCapabilities{
-				TextDocumentSync:     TextDocumentSyncFull,
-				HoverProvider:        true,
-				DefinitionProvider:   true,
-				FoldingRangeProvider: true,
+				TextDocumentSync:          TextDocumentSyncFull,
+				HoverProvider:             true,
+				DefinitionProvider:        true,
+				FoldingRangeProvider:      true,
+				DocumentHighlightProvider: true,
 			},
 		},
 	}
@@ -682,3 +684,109 @@ func ProcessFoldingRangeRequest(
 
 	return responseData, fileName
 }
+
+// DocumentHighlightKind represents the kind of document highlight.
+type DocumentHighlightKind int
+
+const (
+	// DocumentHighlightText is a textual highlight (default).
+	DocumentHighlightText DocumentHighlightKind = 1
+	// DocumentHighlightRead is a read-access highlight.
+	DocumentHighlightRead DocumentHighlightKind = 2
+	// DocumentHighlightWrite is a write-access highlight.
+	DocumentHighlightWrite DocumentHighlightKind = 3
+)
+
+// DocumentHighlightParams holds parameters for textDocument/documentHighlight.
+type DocumentHighlightParams struct {
+	TextDocument TextDocumentIdentifier `json:"textDocument"`
+	Position     Position               `json:"position"`
+}
+
+// DocumentHighlightResult represents a document highlight.
+type DocumentHighlightResult struct {
+	Range Range                 `json:"range"`
+	Kind  DocumentHighlightKind `json:"kind"`
+}
+
+// ProcessDocumentHighlightRequest handles textDocument/documentHighlight.
+func ProcessDocumentHighlightRequest(
+	data []byte,
+	parsedFiles map[string]*parser.GroupStatementNode,
+	textFromClient map[string][]byte,
+	muTextFromClient *sync.Mutex,
+) (response []byte, fileName string) {
+	req := RequestMessage[DocumentHighlightParams]{}
+
+	err := json.Unmarshal(data, &req)
+	if err != nil {
+		slog.Warn("Error unmarshalling document highlight request: " + err.Error())
+		return nil, ""
+	}
+
+	var rootNode *parser.GroupStatementNode
+	fileUri := req.Params.TextDocument.Uri
+
+	muTextFromClient.Lock()
+	fileContent := textFromClient[fileUri]
+
+	if fileContent != nil {
+		rootNode, _ = tmpl.ParseSingleFile(fileContent)
+	}
+
+	if rootNode == nil {
+		rootNode = parsedFiles[fileUri]
+	}
+
+	muTextFromClient.Unlock()
+
+	defer func() {
+		if r := recover(); r != nil {
+			msg := r.(string)
+			slog.Error(msg,
+				slog.Group("details",
+					slog.String("file_uri", fileUri),
+					slog.String("file_content", string(fileContent)),
+				),
+			)
+			panic(msg)
+		}
+	}()
+
+	var res ResponseMessage[[]DocumentHighlightResult]
+	res.Id = req.Id
+	res.JsonRpc = req.JsonRpc
+
+	if rootNode == nil {
+		// Return empty result if file not found
+		responseData, err := json.Marshal(res)
+		if err != nil {
+			slog.Warn("Error marshalling document highlight response: " + err.Error())
+			return nil, fileName
+		}
+		return responseData, fileName
+	}
+
+	position := lexer.Position{
+		Line:      uintToInt(req.Params.Position.Line),
+		Character: uintToInt(req.Params.Position.Character),
+	}
+
+	ranges := tmpl.DocumentHighlight(rootNode, position)
+
+	for _, rng := range ranges {
+		highlight := DocumentHighlightResult{
+			Range: ConvertParserRangeToLspRange(rng),
+			Kind:  DocumentHighlightText,
+		}
+		res.Result = append(res.Result, highlight)
+	}
+
+	responseData, err := json.Marshal(res)
+	if err != nil {
+		slog.Warn("Error marshalling document highlight response: " + err.Error())
+		return nil, fileName
+	}
+
+	return responseData, fileName
+}

cmd/go-template-lsp/lsp/protocol.go

@@ -30,6 +30,7 @@ const (
 	MethodHover              = "textDocument/hover"
 	MethodDefinition         = "textDocument/definition"
 	MethodFoldingRange       = "textDocument/foldingRange"
+	MethodDocumentHighlight  = "textDocument/documentHighlight"
 	MethodPublishDiagnostics = "textDocument/publishDiagnostics"
 )
 

cmd/go-template-lsp/main.go

@@ -46,10 +46,11 @@ type requestCounter struct {
 		DidOpen   int
 		DidChange int
 	}
-	FoldingRange int
-	Definition   int
-	Hover        int
-	Other        int
+	FoldingRange      int
+	DocumentHighlight int
+	Definition        int
+	Hover             int
+	Other             int
 }
 
 // TargetFileExtensions lists the file extensions this LSP supports.
@@ -201,6 +202,16 @@ func main() {
 				muTextFromClient,
 			)
 
+		case lsp.MethodDocumentHighlight:
+			serverCounter.DocumentHighlight++
+			isRequestResponse = true
+			response, _ = lsp.ProcessDocumentHighlightRequest(
+				data,
+				storage.ParsedFiles,
+				textFromClient,
+				muTextFromClient,
+			)
+
 		default:
 			serverCounter.Other++
 		}

internal/template/template.go

@@ -471,6 +471,68 @@ func FoldingRange(
 	return foldingGroups, foldingComments
 }
 
+// DocumentHighlight returns the keyword ranges of all linked control flow keywords
+// when the cursor is on one of them. For example, if the cursor is on {{if}}, {{else}},
+// or {{end}}, all related keywords in the same control flow block are highlighted.
+func DocumentHighlight(
+	rootNode *parser.GroupStatementNode,
+	position lexer.Position,
+) []lexer.Range {
+	// Find the GroupStatementNode whose KeywordRange contains the position
+	var foundNode *parser.GroupStatementNode
+	queue := make([]*parser.GroupStatementNode, 0, 10)
+	queue = append(queue, rootNode)
+	counter := 0
+
+	for len(queue) > 0 {
+		if counter++; counter > 10_000 {
+			panic("infinite loop while computing 'DocumentHighlight()'")
+		}
+
+		node := queue[0]
+		queue = queue[1:]
+
+		// Check if position is within this node's keyword range
+		if !node.KeywordRange.IsEmpty() && node.KeywordRange.Contains(position) {
+			foundNode = node
+			break
+		}
+
+		// Add children to queue
+		for _, statement := range node.Statements {
+			if groupNode, ok := statement.(*parser.GroupStatementNode); ok {
+				queue = append(queue, groupNode)
+			}
+		}
+	}
+
+	if foundNode == nil {
+		return nil
+	}
+
+	// Collect all keyword ranges by walking the NextLinkedSibling circular list
+	ranges := make([]lexer.Range, 0, 4)
+	startNode := foundNode
+	current := foundNode
+
+	for {
+		if !current.KeywordRange.IsEmpty() {
+			ranges = append(ranges, current.KeywordRange)
+		}
+
+		current = current.NextLinkedSibling
+		if current == nil || current == startNode {
+			break
+		}
+
+		if len(ranges) > 100 {
+			panic("too many linked siblings while computing 'DocumentHighlight()'")
+		}
+	}
+
+	return ranges
+}
+
 // HasFileExtension reports whether fileName's extension is found within extensions.
 func HasFileExtension(fileName string, extensions []string) bool {
 	for _, ext := range extensions {

zed-ext/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "go-template-lsp"
-version = "0.5.1"
+version = "0.6.0"
 edition = "2021"
 license = "MIT"
 

zed-ext/extension.toml

@@ -1,6 +1,6 @@
 id = "go-template-lsp"
 name = "Go Template LSP"
-version = "0.5.1"
+version = "0.6.0"
 schema_version = 1
 authors = ["Jason Abbott", "yayolande", "Nikita Galaiko", "Mahmud Ridwan"]
 description = "Go template support with LSP (hover, diagnostics, go-to-definition)"