schema: Introduce Extensions to BodySchema

[radeksimko]

Background

There is a number of "extensions" to HCL. Features which are not natively supported, or rather implemented by the tool such as Terraform.

• Terraform language features
  • count meta-attribute + count.index refs
  • for_each meta-attribute + each.* refs
  • self.* refs within provisioner, connection or lifecycle's precondition/postcondition inside resource
• dynamic "block-name" + block-name.* refs
  • Product-side implementation mostly contained in https://pkg.go.dev/github.com/hashicorp/hcl/v2@v2.12.0/ext/dynblock
  • Terraform dynamic blocks
  • Packer dynamic blocks
  • Nomad dynamic blocks

Three of the above features are Terraform specific, but it would be likely difficult to try to express how these features work via schema alone. It seems more sensible to introduce them as features to hcl-lang and then have individual servers just opt in via schema.

Proposal

The proposal is based on a prototype available https://github.com/hashicorp/hcl-lang/compare/f-local-refs and https://github.com/hashicorp/terraform-schema/compare/f-local-refs

• Introduce BodyExtensions to BodySchema to allow any body such as provisioner to opt into any extension
• Introduce LocalAddr to reference.Target
• Ensure that LocalAddr is filled as part of CollectReferenceTargets
• Reflect BodyExtensions in CandidatesAtPos()
• Reflect BodyExtensions in HoverAtPos()
• Reflect BodyExtensions in SemanticTokensInFile()

type BodySchema struct {
// ...
	// Extensions represents any HCL extensions supported in this body
	Extensions *BodyExtensions
}

type BodyExtensions struct {
	Count         bool // count attribute + count.index refs
	ForEach       bool // for_each attribute + each.* refs
	DynamicBlocks bool // dynamic "block-name" w/ content & for_each inside
	SelfRefs      bool // self.* refs which refer to outermost parent block body
}

Unknowns

Once supported per hashicorp/terraform-schema#92 Terraform's precondition/postcondition blocks may need some minor adjustments as these are more than 1 level away from the relevant block they refer to.

[radeksimko]

This was implemented as part of the following PRs:

• Use local ref. targets for count.index #160
• Use local ref. targets for each.* references #162
• Introduce support for self.* references #163
• Enable dynamic label completions #154
• Enable for_each, count, self.* and dynamic support terraform-ls#1115
• Add dynamic to provisioner and provider block terraform-schema#165
• Fix dynamic block for_each description #164
• Avoid completing static block inside a dynamic label #165
• Fix missing hover for count and for_each expression #166
• fix: support of deeper nesting of dynamic block #167
• Change dynamic block type to default #168

Therefore I am going to close this.

A few follow-up issues were created to track some future fixes and enhancements which can be addressed individually.

• Duplicate completion candidates for for_each & for collections #170
• Display block details on dynamic label hover #171
• Recognise local references in dynamic blocks #172