Go to references

[radeksimko]

Problem Statement

Terraform allows referencing other pieces of config, or the data the config is referring to.

For example a variable can be referenced via var.name:

variable "test" {
  default = "blah"
}

resource "aws_alb" "name" {
  count = var.test
}

Users would benefit from:

• knowing how many references there are throughout the module to a given block (variable, local, resource, data source etc.)
• being able to navigate to these references easily, e.g. from variable "test" block to any var.test occurrences.

Technical Details

Code Lens (annotation w/ number of references)

This should be achievable via Code Lens which are part of the LSP:
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeLens

This allows us to associate an "annotation" with a range of code and a command to be executed when the user clicks on the "annotation". In this case the code range may include the block header (block type + any labels).

Go To References

This is also part of LSP:
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references

User Impact

Referencing is an essential part of Terraform language that many users use, and so most users would likely benefit from this feature.

This feature was also part of the VS Code extension v1 version.

Users reported this via GitHub:

• Reference count and go to definition terraform-ls#254

Expected User Experience

Code Lens

User will see N references annotation above any block that is referenced at least once anywhere else in the module.

For more than 1 reference, user will be able to pick which reference to navigate to.

Go To References

User will be able to right-click to a block header and pick "Go to references", which will bring the IDE-native dialog for references.

Proposal

• Introduce CollectReferenceOrigins(filename string) (ReferenceOrigins, error) to hcl-lang decoder
• Persist reference origins in LS module state
• Refactor lang.Reference to lang.ReferenceTarget
• Introduce ReferenceTargetAtPos(filename string, pos hcl.Pos) lang.ReferenceTarget
• Introduce ReferenceOrigins.MatchingAddress(addr lang.Address) lang.ReferenceOrigins
• implement textDocument/references which will call ReferenceTargetAtPos and use the obtained ReferenceTarget.Address to filter out persisted reference origins in module state via ReferenceOrigins.MatchingAddress

type ReferenceOrigin struct {
  Address lang.Address
  TraversalRange hcl.Range
}

Blocking Questions

• How do we implement the "quick-pick" dialog for the code lens, so that most of the logic can stay on the language server?

[radeksimko]

The "Go To References" part (where you can bring up a list of references via context menu) was implemented in language server 0.19.0 (released today) as part of hashicorp/terraform-ls#572 and hashicorp/terraform-ls#580

Code lens is currently being worked on.

[radeksimko]

This was implemented as part of #686 which was shipped in extension version 2.14.0 and hashicorp/terraform-ls#584 which was shipped in language server version 0.20.0 (yesterday's release).

There are further planned improvements in this area - feel free to subscribe to any of these issues

• Go to module output declaration from reference #706
• Go to variable definition (from local module arg) #670
• Go to (local) module implementation from source terraform-ls#558 / Go to (local) module implementation from source #669
• Go to definition of variable value in tfvars terraform-ls#581
• Reflect convertible types in type comparison terraform-ls#583

or open a new one if the problem/feature isn't described in any of them.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.