Terragrunt HCL Parser

Parser and language-service toolkit for the Terragrunt 1.x HCL language. Version 1 follows the current Terragrunt regime and intentionally does not accept removed or deprecated compatibility syntax.

It powers the Terragrunt HCL Language Server VS Code extension and is published as a standalone npm package.

Supported files

• terragrunt.hcl and named shared unit configurations such as root.hcl
• terragrunt.stack.hcl explicit stacks
• terragrunt.values.hcl generated stack values
• terragrunt.autoinclude.hcl and terragrunt.autoinclude.stack.hcl

The schema covers unit configuration, unit and stack declarations, component autoinclude blocks, feature flags, excludes, error policies, catalogs, IaC engines, CAS source controls, and Terragrunt functions. See the official HCL blocks, attributes, and functions references for the language contract.

Language-service features

• HCL parsing with source ranges and a navigable token tree
• File-kind-aware diagnostics and completion
• Reference completion for locals, includes, dependencies, features, values, units, and stacks
• Exact include resolution using the filename passed to find_in_parent_folders
• Workspace graphs for includes, dependencies, explicit stacks, and generated component targets
• Dependency output discovery from state
• Hover and document-link providers

Command line

The package provides the tghclp executable. Its validation command follows the Terragrunt command shape:

tghclp hcl validate --json --working-dir ./infrastructure

It recursively validates Terragrunt HCL files, returns a non-zero status when diagnostics are found, and supports JSON diagnostics for automation. Add --show-config-path to emit the invalid configuration paths instead of diagnostic objects.

Configuration discovery is also available without evaluating a configuration:

tghclp find --json --working-dir ./infrastructure
tghclp list --working-dir ./infrastructure
tghclp dag graph --working-dir ./infrastructure
tghclp info print --working-dir ./infrastructure
tghclp run --working-dir ./infrastructure -- plan

Discovery skips generated and dependency-cache directories and reports paths relative to the selected working directory. run validates the discovered configuration before invoking the selected OpenTofu/Terraform binary without a shell; use --tf-path to select the executable explicitly.

Experiment-gated language features must be enabled explicitly, for example --experiment deep-merge; the command fails when such a feature is used without its explicit switch.

Development

Install dependencies in this directory. The grammar source is grammar.peggy; src/parser.js is the checked-in generated parser used by consumers. The test suite contains behavior assertions for includes, completions, file-kind validation, stack references, autoincludes, and workspace graph construction.

License

MIT. See LICENSE.

This is a community-supported project and is not affiliated with Gruntworks, Inc. or the Terragrunt project. Contributions are welcome — bug reports, feature ideas, and pull requests all help.