feat: rename, references, and go-to-definition for locals (#141)

* feat: add rename support for locals, dependency labels, and include labels

Add LSP textDocument/rename and textDocument/prepareRename for three kinds
of identifiers in Terragrunt configs:

- Local variables (`locals { name = ... }` and `local.name` references)
- Dependency block labels (`dependency "name" {}` and `dependency.name.outputs.X`)
- Include block labels (`include "name" {}` and `include.name.X`)

Rename is module-aware: edits propagate across all `.hcl` files in the
same folder, honoring unsaved editor buffers via `s.Configs`. Stack and
values files are excluded.

Implementation is AST-based via `hclsyntax.VisitAll` over `ScopeTraversalExpr`
and `IndexedAST.Locals`/`Body.Blocks` for definitions. Prepare-rename returns
a range covering only the bare identifier (placeholder excludes `local.`
prefix and label quotes). New names are validated against the HCL identifier
grammar.

* feat: add textDocument/references for locals, dependency labels, and include labels

Reuse the AST walker and target-resolution introduced for rename to power
find-all-references on the same three identifier kinds. Honors the LSP
`includeDeclaration` flag.

The `rename.Occurrence` type gains an `IsDefinition` flag so references can
filter out the declaration site when the client requests references only.

* feat: extend go-to-definition to local, dependency, and include traversal references

`textDocument/definition` previously only fired when the cursor was on an
`include "X" {}` label or a `dependency "X" { config_path = ... }` attribute.
Extend it to also fire on traversal references:

- `local.X` jumps to the `X = ...` declaration in the locals block (same
  file or any sibling .hcl file in the module folder).
- `include.X.Y` jumps to the file referenced by `include "X" { path = ... }`
  (existing path-resolution behavior, now reachable from references too).
- `dependency.X.outputs.Y` jumps to the dependent unit's `terragrunt.hcl`
  (existing path-resolution behavior, now reachable from references too).

Implementation reuses `ast.MinReferenceTraversalLen` and the rename package's
`FindAllOccurrences` for the local-declaration lookup. The Unit-only file-type
guard is replaced with `canRename` so go-to-definition also works on auxiliary
HCL files (e.g., `common.hcl`).

* chore: defer include-block support to a follow-up PR

Remove rename, references, and go-to-definition support for include block
labels and `include.X.Y` traversal references. Keeping this PR focused on
locals and dependency labels.

Include support has additional complexity worth landing in a dedicated PR:
- The Terragrunt parser emits "Unsupported attribute" / "Unknown variable"
  diagnostics for `include.X` traversals at LS time, which need a separate
  diagnostic-filter change in `internal/tg/parse.go`.
- `find_in_parent_folders` failures cascade into multiple diagnostic kinds,
  expanding the filter scope.
- Include label rename also requires updating the `path` attribute that
  references the parent file, which is out of scope for the symmetric
  identifier-rename pattern this PR ships.

* chore: defer dependency-label support to a follow-up PR

Remove rename, references, and go-to-definition support for
`dependency "X" {}` block labels and `dependency.X.outputs.Y`
traversal references. Keeping this PR focused on locals.

Existing dependency support (cursor on `dependency` block label or on
`config_path` attribute jumping to the dependent unit) is unaffected
and continues to work via `ast.GetNodeDependencyLabel`.

* chore: drop dependency-specific test from shared walker tests

* chore: fix stale doc comment and use t.Context() in tests

- traversalDefinitionTarget now only handles `local`; comment updated.
- Switch test code from context.Background() to t.Context() so the
  context is automatically canceled when the test ends.

* removing sibling references

Signed-off-by: Diogenes Fernandes <diofeher@gmail.com>

* bump to v0.0.5

Signed-off-by: Diogenes Fernandes <diofeher@gmail.com>

---------

Signed-off-by: Diogenes Fernandes <diofeher@gmail.com>

Author: diofeher

internal/ast/walk.go

@@ -0,0 +1,58 @@
+package ast
+
+import (
+	"github.com/hashicorp/hcl/v2"
+	"github.com/hashicorp/hcl/v2/hclsyntax"
+)
+
+// MinReferenceTraversalLen is the minimum number of steps a ScopeTraversalExpr
+// must have to be a `<root>.<name>` reference (one root + one attribute).
+const MinReferenceTraversalLen = 2
+
+// ReferenceVisitor is invoked for each `<root>.<name>` reference found.
+// r is the source range of the attribute step (just `<name>`, not the root).
+type ReferenceVisitor func(expr *hclsyntax.ScopeTraversalExpr, r hcl.Range)
+
+// WalkReferences walks body and invokes visitor for each ScopeTraversalExpr
+// whose first traversal step is a TraverseRoot named root and whose second
+// step is a TraverseAttr named name.
+func WalkReferences(body *hclsyntax.Body, root, name string, visitor ReferenceVisitor) {
+	if body == nil {
+		return
+	}
+
+	_ = hclsyntax.VisitAll(body, func(node hclsyntax.Node) hcl.Diagnostics {
+		expr, ok := node.(*hclsyntax.ScopeTraversalExpr)
+		if !ok {
+			return nil
+		}
+
+		if len(expr.Traversal) < MinReferenceTraversalLen {
+			return nil
+		}
+
+		rootStep, ok := expr.Traversal[0].(hcl.TraverseRoot)
+		if !ok || rootStep.Name != root {
+			return nil
+		}
+
+		attrStep, ok := expr.Traversal[1].(hcl.TraverseAttr)
+		if !ok || attrStep.Name != name {
+			return nil
+		}
+
+		visitor(expr, TraverseAttrIdentRange(attrStep))
+
+		return nil
+	})
+}
+
+// TraverseAttrIdentRange returns the range of the attribute identifier alone,
+// excluding the leading dot included in TraverseAttr.SrcRange.
+func TraverseAttrIdentRange(step hcl.TraverseAttr) hcl.Range {
+	r := step.SrcRange
+	r.Start.Column++
+	r.Start.Byte++
+
+	return r
+}

internal/ast/walk_test.go

@@ -0,0 +1,92 @@
+package ast_test
+
+import (
+	"terragrunt-ls/internal/ast"
+	"testing"
+
+	"github.com/hashicorp/hcl/v2"
+	"github.com/hashicorp/hcl/v2/hclsyntax"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestWalkReferences(t *testing.T) {
+	t.Parallel()
+
+	tc := []struct {
+		name     string
+		contents string
+		root     string
+		ident    string
+		expected []hcl.Range
+	}{
+		{
+			name: "single local reference",
+			contents: `locals {
+  foo = "bar"
+}
+
+inputs = {
+  v = local.foo
+}
+`,
+			root:  "local",
+			ident: "foo",
+			expected: []hcl.Range{
+				{Start: hcl.Pos{Line: 6, Column: 13}, End: hcl.Pos{Line: 6, Column: 16}},
+			},
+		},
+		{
+			name: "multiple references and unrelated traversals",
+			contents: `inputs = {
+  a = local.foo
+  b = local.bar
+  c = local.foo
+  d = path.module
+}
+`,
+			root:  "local",
+			ident: "foo",
+			expected: []hcl.Range{
+				{Start: hcl.Pos{Line: 2, Column: 13}, End: hcl.Pos{Line: 2, Column: 16}},
+				{Start: hcl.Pos{Line: 4, Column: 13}, End: hcl.Pos{Line: 4, Column: 16}},
+			},
+		},
+		{
+			name: "no matches",
+			contents: `inputs = {
+  v = local.bar
+}
+`,
+			root:     "local",
+			ident:    "foo",
+			expected: nil,
+		},
+	}
+
+	for _, tt := range tc {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			iast, err := ast.ParseHCLFile("test.hcl", []byte(tt.contents))
+			require.NoError(t, err)
+			require.NotNil(t, iast.HCLFile)
+
+			body, ok := iast.HCLFile.Body.(*hclsyntax.Body)
+			require.True(t, ok)
+
+			var got []hcl.Range
+			ast.WalkReferences(body, tt.root, tt.ident, func(_ *hclsyntax.ScopeTraversalExpr, r hcl.Range) {
+				got = append(got, r)
+			})
+
+			require.Len(t, got, len(tt.expected))
+			for i := range tt.expected {
+				assert.Equal(t, tt.expected[i].Start.Line, got[i].Start.Line, "start line %d", i)
+				assert.Equal(t, tt.expected[i].Start.Column, got[i].Start.Column, "start col %d", i)
+				assert.Equal(t, tt.expected[i].End.Line, got[i].End.Line, "end line %d", i)
+				assert.Equal(t, tt.expected[i].End.Column, got[i].End.Column, "end col %d", i)
+			}
+		})
+	}
+}

internal/lsp/initialize.go

@@ -28,8 +28,12 @@ func NewInitializeResponse(id int) InitializeResponse {
 				TextDocumentSync:           1,
 				HoverProvider:              true,
 				DefinitionProvider:         true,
+				ReferencesProvider:         true,
 				CompletionProvider:         &protocol.CompletionOptions{},
 				DocumentFormattingProvider: true,
+				RenameProvider: &protocol.RenameOptions{
+					PrepareProvider: true,
+				},
 			},
 			ServerInfo: &protocol.ServerInfo{
 				Name:    name,

internal/lsp/rename.go

@@ -0,0 +1,29 @@
+package lsp
+
+import "go.lsp.dev/protocol"
+
+type PrepareRenameRequest struct {
+	Request
+	Params protocol.PrepareRenameParams `json:"params"`
+}
+
+// PrepareRenameResult mirrors the LSP `{ range, placeholder }` response shape.
+type PrepareRenameResult struct {
+	Placeholder string         `json:"placeholder"`
+	Range       protocol.Range `json:"range"`
+}
+
+type PrepareRenameResponse struct {
+	Result *PrepareRenameResult `json:"result"`
+	Response
+}
+
+type RenameRequest struct {
+	Params protocol.RenameParams `json:"params"`
+	Request
+}
+
+type RenameResponse struct {
+	Result *protocol.WorkspaceEdit `json:"result"`
+	Response
+}

internal/lsp/textdocument_references.go

@@ -0,0 +1,13 @@
+package lsp
+
+import "go.lsp.dev/protocol"
+
+type ReferencesRequest struct {
+	Params protocol.ReferenceParams `json:"params"`
+	Request
+}
+
+type ReferencesResponse struct {
+	Response
+	Result []protocol.Location `json:"result"`
+}

internal/tg/definition/definition.go

@@ -7,10 +7,18 @@ import (
 	"terragrunt-ls/internal/logger"
 	"terragrunt-ls/internal/tg/store"
 
+	"github.com/hashicorp/hcl/v2"
+	"github.com/hashicorp/hcl/v2/hclsyntax"
 	"go.lsp.dev/protocol"
 )
 
 const (
+	// DefinitionContextLocal is the context for a local variable definition.
+	// This means that the user is trying to find the definition of a `local.X`
+	// reference, which resolves to a `locals { X = ... }` declaration in the
+	// current file or a sibling file in the same module folder.
+	DefinitionContextLocal = "local"
+
 	// DefinitionContextInclude is the context for an include definition.
 	// This means that the user is trying to find the definition of an include.
 	DefinitionContextInclude = "include"
@@ -46,7 +54,38 @@ func GetDefinitionTargetWithContext(l logger.Logger, store store.Store, position
 		return dep, DefinitionContextDependency
 	}
 
+	if expr, ok := node.Node.(*hclsyntax.ScopeTraversalExpr); ok {
+		if name, context, ok := traversalDefinitionTarget(expr); ok {
+			l.Debug("Found traversal target", "name", name, "context", context)
+			return name, context
+		}
+	}
+
 	l.Debug("No definition found at", "line", position.Line, "character", position.Character)
 
 	return "", DefinitionContextNull
 }
+
+// traversalDefinitionTarget extracts a (name, context) pair from a
+// `local.<name>` traversal.
+func traversalDefinitionTarget(expr *hclsyntax.ScopeTraversalExpr) (string, string, bool) {
+	if len(expr.Traversal) < ast.MinReferenceTraversalLen {
+		return "", "", false
+	}
+
+	rootStep, ok := expr.Traversal[0].(hcl.TraverseRoot)
+	if !ok {
+		return "", "", false
+	}
+
+	attrStep, ok := expr.Traversal[1].(hcl.TraverseAttr)
+	if !ok {
+		return "", "", false
+	}
+
+	if rootStep.Name == "local" {
+		return attrStep.Name, DefinitionContextLocal, true
+	}
+
+	return "", "", false
+}

internal/tg/references/references.go

@@ -0,0 +1,42 @@
+// Package references provides the logic for finding all references of an
+// identifier within a Terragrunt unit.
+package references
+
+import (
+	"terragrunt-ls/internal/logger"
+	"terragrunt-ls/internal/tg/rename"
+	"terragrunt-ls/internal/tg/store"
+
+	"go.lsp.dev/protocol"
+	"go.lsp.dev/uri"
+)
+
+// GetReferences returns LSP locations for every reference (and optionally the
+// declaration) of the renameable symbol at position. Returns nil if the cursor
+// is not on a renameable identifier.
+func GetReferences(l logger.Logger, st store.Store, position protocol.Position, file string, includeDeclaration bool) []protocol.Location {
+	target := rename.GetRenameTarget(l, st, position)
+	if target.Context == rename.RenameContextNull {
+		return nil
+	}
+
+	occurrences := rename.FindAllOccurrences(target, file, st)
+	if len(occurrences) == 0 {
+		return nil
+	}
+
+	locations := make([]protocol.Location, 0, len(occurrences))
+
+	for _, occ := range occurrences {
+		if occ.IsDefinition && !includeDeclaration {
+			continue
+		}
+
+		locations = append(locations, protocol.Location{
+			URI:   uri.File(occ.File),
+			Range: occ.Range,
+		})
+	}
+
+	return locations
+}

internal/tg/references/references_test.go

@@ -0,0 +1,65 @@
+package references_test
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.lsp.dev/protocol"
+	"go.lsp.dev/uri"
+
+	"terragrunt-ls/internal/testutils"
+	"terragrunt-ls/internal/tg"
+	"terragrunt-ls/internal/tg/references"
+)
+
+func TestGetReferences(t *testing.T) {
+	t.Parallel()
+
+	tmpDir := t.TempDir()
+
+	content := `locals {
+  shared = "value"
+}
+
+inputs = {
+  v = local.shared
+}
+`
+	_, err := testutils.CreateFile(tmpDir, "terragrunt.hcl", content)
+	require.NoError(t, err)
+
+	tgPath := filepath.Join(tmpDir, "terragrunt.hcl")
+
+	l := testutils.NewTestLogger(t)
+	s := tg.NewState()
+	s.OpenDocument(t.Context(), l, uri.File(tgPath), content)
+
+	t.Run("includes declaration when requested", func(t *testing.T) {
+		t.Parallel()
+
+		locs := references.GetReferences(l, s.Configs[tgPath], protocol.Position{Line: 5, Character: 14}, tgPath, true)
+		require.Len(t, locs, 2, "definition + reference")
+
+		for _, loc := range locs {
+			assert.Equal(t, uri.File(tgPath), loc.URI)
+		}
+	})
+
+	t.Run("excludes declaration when requested", func(t *testing.T) {
+		t.Parallel()
+
+		locs := references.GetReferences(l, s.Configs[tgPath], protocol.Position{Line: 5, Character: 14}, tgPath, false)
+		require.Len(t, locs, 1, "only the reference, not the definition")
+
+		assert.Equal(t, uri.File(tgPath), locs[0].URI)
+	})
+
+	t.Run("returns nil for non-renameable position", func(t *testing.T) {
+		t.Parallel()
+
+		locs := references.GetReferences(l, s.Configs[tgPath], protocol.Position{Line: 0, Character: 0}, tgPath, true)
+		assert.Nil(t, locs)
+	})
+}