Feature: Add Terraform/HCL language support

[vnz]

Summary

I'd like to contribute HCL (HashiCorp Configuration Language) support to AiDex, covering .tf, .tfvars, and .hcl files. This would make AiDex useful for Terraform/OpenTofu codebases — a common use case for AI-assisted infrastructure work.

What I've scoped out

The language plugin architecture makes this straightforward. The changes would be:

• New file: src/parser/languages/hcl.ts — keyword filter + tree-sitter node type sets (~90 lines)
• Modified: languages/index.ts, tree-sitter.ts — register the new language (~30 lines)
• Docs: CHANGELOG.md, README.md, MCP-API-REFERENCE.md — update language count and list

The npm package @tree-sitter-grammars/tree-sitter-hcl (v1.2.0) has 100% parse success on 1,892 real-world HCL files from HashiCorp, CoreOS, and Oracle repos.

Design question: Semantic mapping

HCL is structurally different from the 11 languages currently supported. It has no classes, functions, or interfaces — everything is blocks and attributes:

resource "aws_instance" "web" {   # block with type + labels
  ami           = "abc-123"        # attribute
  instance_type = lookup(var.sizes, "default")  # attribute with function call
}

My proposed mapping to AiDex's extraction model:

HCL concept	AiDex concept	Example
block (resource, module, variable, output, data, locals, provider)	type (kind: 'type')	resource "aws_instance" "web"
function_call (built-in functions)	method	lookup(...), merge(...)
attribute	property	ami = "..."
identifier / variable_expr	identifier (search terms)	aws_instance, web, var.sizes

This means aidex_query({ term: "aws_instance" }) would find the resource, and aidex_signature would show blocks and their attributes — which seems like the most useful behavior for IaC files.

Open to other ideas here — especially if there's a preferred way to handle languages without traditional methods/types.

Blocker: tree-sitter version mismatch

@tree-sitter-grammars/tree-sitter-hcl requires tree-sitter ^0.25.0. AiDex currently pins tree-sitter ^0.21.0.

This isn't unique to HCL — several existing grammar packages have also moved forward:

Package	AiDex version constraint	Latest peerDependencies
tree-sitter-go	^0.21.0	^0.25.0
tree-sitter-python	^0.21.0	^0.25.0
tree-sitter-c	^0.21.0	^0.22.4
tree-sitter-rust	^0.21.0	^0.22.1
tree-sitter-php	^0.22.0	^0.22.4

So the ecosystem is pulling ahead of AiDex's pinned version regardless of HCL.

Proposed approach: 2 PRs

1. PR 1 — Bump tree-sitter to 0.25 + update all grammar packages

   • Updates tree-sitter and all 10 grammar dependencies to their latest compatible versions
   • Validates that all 11 existing languages still parse correctly
   • This is the riskier PR — there's no test suite to catch regressions, so manual validation would be needed

2. PR 2 — Add HCL/Terraform support (on top of PR 1)

   • The actual language addition (~130 lines)
   • Clean, focused, easy to review

Alternatively, if a tree-sitter bump is not desired right now, I could investigate building the HCL grammar against 0.21 from source — but that seems like fighting the tide.

Questions for maintainers

1. Is the 2-PR split the right approach, or would you prefer everything in one?
2. Any concerns about the tree-sitter 0.21 → 0.25 bump?
3. Does the semantic mapping (blocks → types, function_calls → methods) feel right?

Happy to start with either PR once we're aligned.

[CSCSoftware]

Hey, thanks for the incredibly thorough scoping — this is exactly the kind of contribution we love to see. You've clearly studied the architecture and the mapping makes a lot of sense. Let me answer your three questions:

1. Two PRs — yes, absolutely

The split is the right call. The tree-sitter 0.21 → 0.25 bump touches all 11 existing languages and has regression potential, so keeping it isolated from the HCL feature makes review and debugging much cleaner.

2. Tree-sitter bump — welcome

We've been aware that we're falling behind the ecosystem. Several grammars already have newer peerDependencies and we've just been kicking the can. Your PR would force us to deal with it — that's a good thing. Since we don't have a test suite (yet), manual validation against a few real-world files per language would be appreciated in the PR description.

3. Semantic mapping — looks right

Blocks → type, function_calls → method, attributes → property fits the AiDex extraction model well. Two notes:

• propertyNodes already exists as an optional field in LanguageConfig (currently used by C#) — so HCL attributes can plug right into that without any schema changes.
• The mapping means aidex_signature will show blocks and their attributes, which is exactly what a Terraform user would want to see. 👍

Next steps

Go ahead with PR 1 (tree-sitter bump) whenever you're ready. We'll review and merge, then you can stack PR 2 (HCL) on top.

Looking forward to it!