Automating HCL and Terragrunt Standards with hcl-linter 0.0.1-alpha

hcl-linter 0.0.1-alpha is out

Engineer Bartłomiej Danek has launched hcl-linter 0.0.1-alpha to address semantic drift in HCL files. The tool’s initial production run automatically corrected over 1,000 terragrunt.hcl files.

Why This Matters

Standard tools like ‘terraform fmt’ are limited to whitespace adjustments, allowing block order drift and naming inconsistencies to accumulate in large codebases with dozens of contributors. This technical debt leads to silent failures in CI and broken references when hyphens are used in block labels, which hcl-linter resolves through automated static analysis and remediation.

Key Insights

• Initial deployment corrected 1,000+ terragrunt.hcl files, Danek 2026
• Automated block ordering ensures ‘include’ and ‘locals’ precede ‘terraform’ and ‘inputs’ blocks for consistency
• Name validation pattern ’^[a-z][a-z0-9_]*$’ prevents broken references in dependency outputs by replacing hyphens with underscores
• Static validation of ‘dependency.x.outputs.y’ allows verifying references without requiring a terraform plan
• Deprecated Terragrunt hooks such as ‘before_hook’ are flagged for migration to the modern ‘before_hooks’ syntax

Working Examples

Configuration to enforce a consistent block hierarchy in HCL files.

rules {
  block_order {
    enabled = true
    order = ["include", "locals", "terraform", "dependency", "inputs"]
  }
}

Rule to prevent hyphens in block labels which can break local references.

rules {
  name_validation {
    enabled = true
    pattern = "^[a-z][a-z0-9_]*$"
    blocks = ["dependency", "include"]
  }
}

Enables static validation of dependency output references against target module source code.

rules {
  dependency_outputs {
    enabled = true
  }
}

Practical Applications

• CI/CD Integration: Use ‘hcl-linter check’ to fail builds on rule violations like missing ‘expose = true’ in include blocks.
• Project Scaffolding: Run ‘hcl-linter init’ to automatically generate a configuration based on existing project basenames.
• Environment Safety: Apply ‘hcl_functions’ rules to ensure ‘get_env’ calls have mandatory fallback defaults to prevent silent CI failures.
• Infrastructure Refactoring: Use ‘hcl-linter fix —format’ to apply opinionated defaults across legacy HCL repositories without manual editing.

References:

• https://dev.to/bard/hcl-linter-001-alpha-is-out-1k59
• https://bard.sh/posts/hcl-linter-release/