Proposal: Generalize the idea of using [*] in traversals to describe "traversal patterns"

[apparentlymart]

The earlier PR #673 introduced hclsyntax.ParseTraversalPartial that is a variant of hclsyntax.ParseTraversalAbs which additionally accepts [*] steps representing placeholders for arbitrary indices. It introduced a new use of the previously-vestigial hcl.TraverseSplat type¹ as the representation of those placeholders.

However, that idea wasn't generalized to the other main way callers can produce hcl.Traversal values: asking HCL to perform static analysis of an already-parsed expression, like Terraform does when it's analyzing references in parts of its language like depends_on and the from/to expressions in moved, removed, and import blocks.

This PR is proposing to generalize this idea of "traversals with wildcards" into a new first-class concept that I've called "traversal patterns". This new idea extends the idea of "traversal" to include the possibility of hcl.TraverseSplat steps, and makes it possible to turn both source code and certain already-parsed expressions into traversal patterns.

Of course I have my own reasons to propose this, but as a "closer-to-home" motivation consider that Terraform could hypothetically use this to support wildcard patterns in removed blocks:

removed {
  # Forget rather than destroy the database object in _any_ instance of
  # this module call, rather than having to name each one individually.
  from = module.example[*].aws_db_instance.example

  lifecycle {
    destroy = false
  }
}

...or for wildcard index steps in ignore_changes for list-based blocks, without having to write out every possible index explicitly (hashicorp/terraform#5666):

  lifecycle {
    ignore_changes = [
      # Ignore changes to the last_updated attribute in all blocks
      # of type "listy_thing", regardless of how many there are.
      listy_thing[*].last_updated,
    ]
  }

I understand that there'd be a lot more work to do in Terraform to do these things than just merging this PR, but this changeset would create a new building block in the HCL grammar for languages like Terraform's to use.

The ParseTraversalPartial function was already producing traversals that can't support Traversal.Value, and that remains true for the concept of "traversal pattern" introduced here. However, calls to Value now return an error diagnostic instead of panicking as before.

Turning an AST that includes a mixture of absolute traversals, relative traversals, and splat expressions into a flat hcl.Traversal is kinda annoying to achieve and so the code I wrote for it here is honestly quite dense and tricky to follow, but I tried to write a good suite of unit tests covering it, both at the parser level (to make sure the parser generates the AST that the flattening code expects) and at the "as traversal pattern" level.

Footnotes

1. That TraverseSplat type originated from a much earlier implementation of splat expressions in the ZCL library that HCL 2 was forked from, where they were treated as a special kind of traversal step instead of as the separate expression type hclsyntax.SplatExpr.

   I forgot to actually remove the TraverseSplat type after rewriting the implementation of splat expressions and so it ended up surviving into the first stable release of HCL 2 but without any uses until hclsyntax.ParseTraversalPartial came along and gave it a new purpose. ↩

[apparentlymart]

I see that the "copyright headers" check is failing but I'm not sure what exactly it's wanting me to do, since the files it mentioned do seem to have the "Copyright IBM Corp" headers in them. 🤔

[mildwonkey]

It was complaining because the modified files should get updated with 2026 - I don't know if you want me pushing a commit to your branch but I can do it, or you can. (Hi Martin!!! 👋🏻 ❤️ )

[apparentlymart]

Hello! 👋😀

Thanks for explaining what that check is looking for. I've pushed an additional commit to meet its expectations. ✔️