GO — Healthy across the board

• Last commit 6d ago
• 25+ active contributors
• Distributed ownership (top contributor 12% of recent commits)
• MPL-2.0 licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

HCL (HashiCorp Configuration Language) is a Go-based toolkit for building structured configuration languages that are human-readable and machine-parseable. It provides both a native syntax (inspired by libucl and nginx config) and JSON variants, with support for expressions, variables, and functions. Version 2 (this repo) is the current production implementation used by Terraform, Consul, Nomad, and other HashiCorp tools. Monolithic single-package architecture: core parsing/lexing in root (Ragel-based lexer in .l files, expr_*.go for expression AST nodes), eval_context.go and diagnostic.go for evaluation and error reporting, cmd/ subdir contains three CLI tools (hcldec decoder, hclfmt formatter, hclspecsuite test runner), and ext/ contains optional extensions (dynblock, customdecode) that layer on top.

DevOps engineers and tool developers building infrastructure-as-code platforms, CLI tools, and configuration management systems who need a flexible DSL that balances human readability with programmatic generation (e.g., Terraform users extending HCL, HashiCorp product developers embedding config parsing).

Highly mature and production-ready. HCL v2 has been battle-tested across all HashiCorp products since ~2019, has comprehensive test coverage (mixed with CLI tools in cmd/), strong CI via .github/workflows/checks.yml, and Go 1.24 support in go.mod. This is not a cutting-edge experimental project but the stable, widely-deployed core of multiple commercial platforms.

Low risk for stability but moderate API surface to maintain. Dependency count is lean (~10 direct), anchored on stable packages like zclconf/go-cty for type system and agext/levenshtein for diagnostics. Main risk: Go's evolving type parameter support (generic constraints in diagnostic_typeparams.go suggests ongoing adaptation) and the broad API surface across parsing, decoding, and expression evaluation means breaking changes ripple widely.

Active maintenance with incremental improvements: .go-version pinned to 1.24.0, golangci.yaml configured for modern linting (checks.yml runs CI), CHANGELOG.md tracks changes, and the repo supports go-cty v1.16.3+ and go-textseg v15+ indicating recent dependency updates. Likely focus areas: maintaining compatibility with latest Go versions and supporting evolving HashiCorp products.

git clone https://github.com/hashicorp/hcl.git
cd hcl
go mod download
go build ./cmd/hclfmt
go test ./...

Daily commands: Not a runnable service, but CLI tools: go run ./cmd/hclfmt <file> formats HCL, go run ./cmd/hcldec <spec-file> decodes config with a schema, go run ./cmd/hclspecsuite <test-dir> runs compatibility tests. For library use, see cmd/hcldec/main.go and examples in cmd/hcldec/examples/.

• diagnostic.go — Core diagnostic type system for error reporting; foundational to all HCL parsing and evaluation error messages
• eval_context.go — Defines EvalContext which carries variables and functions into expression evaluation; essential for understanding how HCL executes dynamic content
• gohcl/decode.go — Primary API for decoding HCL into Go structs; the most common integration point for users of the library
• ext/dynblock/expand_body.go — Implements dynamic block expansion (for_each, for loops in HCL); core extension mechanism for the language
• ext/typeexpr/get_type.go — Type inference and schema validation system; handles type expressions that are central to HCL's static typing story
• cmd/hcldec/spec.go — Specification-driven decoder that powers hcldec CLI; demonstrates advanced usage patterns for the HCL library
• go.mod — Project module definition; shows that HCL v2 targets Go 1.24.0 and depends critically on go-cty for value representation

Add a new HCL extension (e.g., new function or language feature)

1. Create a new subdirectory under ext/ with a public.go file defining your public API (ext/yourfeature/public.go)
2. Implement core logic in separate files (e.g., ext/yourfeature/implementation.go) (ext/yourfeature/implementation.go)
3. Add tests alongside your implementation (e.g., ext/yourfeature/implementation_test.go) (ext/yourfeature/implementation_test.go)
4. Update ext/yourfeature/README.md with usage examples and motivation (ext/yourfeature/README.md)
5. If adding a function, register it in eval_context.go's Functions map or as part of a module you provide to users (eval_context.go)

Add support for decoding a new Go type in gohcl

1. Add a type conversion case in gohcl/schema.go's schemaForType() function (gohcl/schema.go)
2. Implement the corresponding decode logic in gohcl/decode.go's decodeBody() or a helper function (gohcl/decode.go)
3. Add test cases to gohcl/decode_test.go showing HCL input and expected Go struct output (gohcl/decode_test.go)

Add a new command-line tool (like hclfmt or hcldec)

1. Create cmd/yourcommand/main.go with your CLI entry point (cmd/yourcommand/main.go)
2. Use the parsing and evaluation APIs (eval_context.go, expression types) to implement logic (cmd/yourcommand/logic.go)
3. Add a README.md explaining usage, examples, and any custom specification formats (cmd/yourcommand/README.md)
4. Update the Makefile to build your tool (Makefile)

Improve error messages and diagnostics

1. Review diagnostic.go and diagnostic_text.go to understand the Diagnostic type and rendering (diagnostic.go)
2. Add or improve Diag() calls in the component where the error occurs (e.g., expr_call.go for function errors) (expr_call.go)
3. Use didyoumean.go's Levenshtein distance for typo suggestions where applicable (didyoumean.go)
4. Test your message with diagnostic_text_test.go patterns and validate formatting (diagnostic_text_test.go)

• go-cty — Universal dynamic type system that bridges Go's static types and HCL's dynamically-typed expressions; enables type coercion, function evaluation, and JSON marshaling of arbitrary values
• go-textseg — Unicode-aware text segmentation for proper source location tracking and error message positioning across multi-byte characters
• Levenshtein distance (agext/levenshtein) — Typo recovery in error messages to guide users toward correct syntax without cluttering the language grammar
• Struct tags (gohcl) — Familiar Go idiom for declarative schema mapping, reducing boilerplate in type bindings

• Separate native syntax parser from JSON support rather than unified AST

  • Why: Native syntax has different lexical rules (unquoted keys, heredoc) and prettier error messages than JSON
  • Consequence: Two parsing paths to maintain but cleaner UX for native HCL users

• Extensions (dynblock, tryfunc, userfunc) are opt-in rather than built into core

  • Why: Keeps core parser minimal and allows applications to pick only needed features
  • Consequence: Applications must explicitly register extensions; more flexibility but requires integration work

• gohcl struct tag schema inference instead of explicit schema builders

  • Why: Go idiomatic and fast prototyping; reduces boilerplate
  • Consequence: Struct-driven design; harder to decode into dynamic/map-based shapes without custom logic

• Diagnostics include source range and context, not just line numbers

  • Why: Enables rich error rendering (red squiggles, suggestions) in tools and IDEs
  • Consequence: Parser must track byte offsets carefully; larger Diagnostic objects

Ragel lexer regeneration: scanner.l is the source of truth; hand-editing scanner.go will be overwritten. Run make before committing lexer changes. Type constraints in generic decoding: diagnostic_typeparams.go hints that type parameter handling varies by Go version; test on 1.24.0 as pinned in .go-version. Expression evaluation vs. parsing are separate: expr_*.go evaluate an already-parsed AST; parsing happens in parser.go first. Confusing the two is a common mistake. cty type system: all values evaluated within HCL are cty.Value, not native Go types; understand zclconf/go-cty's value semantics before working with expressions. Extension ordering: ext/dynblock and ext/customdecode are post-processing steps on the parsed Body; they transform content after initial parse, not during lexing.

• Recursive Descent Parsing — HCL parser (parser.go) uses hand-written recursive descent rather than parser generators; understanding call stack semantics and operator precedence handling in expr_*.go is key to modifying grammar
• Lexical Analysis with Ragel — scanner.l is compiled by Ragel into scanner.go; Ragel's state machine approach differs from regex-based lexers, affecting how HCL tokenizes raw input before parser.go sees it
• Abstract Syntax Tree (AST) Evaluation — HCL separates parsing (AST construction in parser.go) from evaluation (expr_*.go, eval_context.go); this two-phase design allows schema validation and deferred evaluation, crucial for Terraform's lazy evaluation of variables
• Source Range Tracking — diagnostic.go and diagnostic_text.go track hcl.Range for every token and expression; this enables HCL's trademark human-friendly error messages with file:line:col annotations
• Type Coercion and Capsule Types — All evaluated HCL values are cty.Value (from go-cty); expr_*.go must handle dynamic type negotiation and capsule types (opaque objects like database credentials), not just primitives
• Dynamic Block Expansion — ext/dynblock/ implements for_each and for loop semantics by rewriting parsed AST nodes before decoding; this is how Terraform achieves iterative config generation without changing the core HCL grammar
• Schema-Driven Decoding — cmd/hcldec demonstrates schema specification (spec.go, spec_funcs.go) to convert raw HCL into Go structs; this two-stage (parse → validate+decode) design decouples grammar from application semantics

• zclconf/go-cty — Type system and value semantics that HCL uses for expression evaluation; understanding go-cty's Value, Type, and Capsule types is essential to extending HCL
• hashicorp/terraform — Largest consumer of HCL v2; reference for real-world usage patterns, custom functions, and dynamic block extensions
• hashicorp/nomad — Another major HashiCorp product using HCL v2 for job specifications; examples of schema validation and decoding patterns
• apparentlymart/go-textseg — Text segmentation library HCL depends on for source range tracking and Unicode-aware string operations in diagnostics
• hashicorp/hcl — HCL v1 (legacy); reference for migration patterns and syntax changes between major versions

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for ext/dynblock with complex nested scenarios

The ext/dynblock package handles dynamic block expansion, which is a complex feature. While there are some tests (expand_body_test.go, variables_test.go), there's no test file covering edge cases like deeply nested dynamic blocks, dynamic blocks with computed iteration values, and interactions with other extensions. This would catch regressions in a critical subsystem.

• [ ] Create ext/dynblock/integration_test.go with test cases for nested dynamic blocks
• [ ] Add tests for dynamic blocks combined with ext/transform and ext/customdecode
• [ ] Test error handling when iteration produces invalid values
• [ ] Add benchmarks for performance of expand_body.go with large block counts
• [ ] Run against cmd/hclspecsuite to verify spec compliance

Add GitHub Actions workflow for Go version matrix testing

The .go-version file specifies 1.24.0, but go.mod declares 'go 1.24.0'. The repo lacks a CI workflow testing multiple Go versions to catch compatibility regressions early. Currently only checks.yml exists without visibility into whether it tests multiple Go versions. This is critical for a widely-used library.

• [ ] Review .github/workflows/checks.yml to identify current Go version testing
• [ ] Create or extend .github/workflows/matrix-test.yml with Go versions: 1.21.x, 1.22.x, 1.23.x, 1.24.x
• [ ] Add test runs for all cmd/* tools (hcldec, hclfmt, hclspecsuite)
• [ ] Add matrix testing for Linux, macOS, Windows platforms
• [ ] Document minimum supported Go version in README.md if not already present

Create missing unit tests for diagnostic_text.go formatting edge cases

The diagnostic_text.go file handles human-readable diagnostic output formatting (colors, line numbers, context), but diagnostic_text_test.go appears to have minimal coverage based on the file structure. This is user-facing and critical for good error reporting. Missing tests for multi-line diagnostics, special characters, and wide characters (given the go-textseg dependency).

• [ ] Expand diagnostic_text_test.go with test cases for Unicode/wide characters in source code
• [ ] Add tests for multi-line error spans with proper line number alignment
• [ ] Test ANSI color output formatting (verify colors only when tty is detected)
• [ ] Add tests for diagnostic context with different file encodings
• [ ] Test edge case: diagnostics at file start/end boundaries

• Add end-to-end tests for error message formatting in diagnostic_text_test.go; currently covers some branches but missing coverage for multi-line attribute values with syntax errors (similar pattern to existing tests in the file).
• Document the Expression type hierarchy in a dedicated file or package comments; expr_unwrap.go exists but the interface contract between expr_call.go, expr_list.go, expr_map.go, and the Expr interface is implicit (review Type() method contracts across these files and write godoc comments).
• Implement a linter rule detector in cmd/hclspecsuite or as a new cmd/ tool that flags deprecated HCL 1 syntax (e.g., list = [...] vs. list = […]) by comparing parse trees; hclspecsuite has test infrastructure, but no lint-like tool exists yet.

The hashicorp/hcl repository demonstrates a generally secure posture with no critical vulnerabilities identified. The codebase uses well-maintained, reputable dependencies from the Go standard library ecosystem. Key strengths include active use of Dependabot for dependency management and standard HashiCorp quality practices. Primary recommendations focus on maintenance: establishing a formal security policy, keeping Go updated, and regularly monitoring transitive dependencies. The parser-focused nature of the project minimizes exposure to common web vulnerabilities (SQLi, XSS) as it operates on configuration DSL rather than handling web requests or HTML rendering.

• Medium · Outdated Go Version — .go-version. The project specifies Go 1.24.0 in .go-version, which may contain unpatched security vulnerabilities. Go releases security patches regularly, and using the latest stable version ensures exposure fixes are included. Fix: Update to the latest stable Go version and regularly monitor Go security advisories at https://golang.org/doc/security. Consider implementing automated dependency updates.
• Low · Missing Security Policy — Repository root. No SECURITY.md file is present in the repository. This makes it unclear how users should report security vulnerabilities responsibly, potentially leading to public disclosure of unpatched issues. Fix: Create a SECURITY.md file following the GitHub security policy template, defining responsible disclosure procedures and supported versions receiving security updates.
• Low · Indirect Dependency Risk — go.mod. Multiple transitive dependencies are present (golang.org/x/mod, golang.org/x/sync, golang.org/x/sys, golang.org/x/text). While these are from reputable sources, they increase the attack surface and should be monitored. Fix: Regularly run 'go mod tidy' and 'go list -u -m all' to identify outdated dependencies. Consider using Dependabot (already configured) to automate security updates. Monitor golang.org/x/ packages for CVEs.
• Low · No Input Validation Documentation — diagnostic.go, expr_* files. The HCL parser handles configuration language parsing. Without explicit documentation on input validation and injection prevention, users may inadvertently create unsafe configurations. Fix: Document security best practices for HCL usage, including validation patterns and any known limitations regarding injection attacks or untrusted input handling.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/hashicorp/hcl shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live hashicorp/hcl repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hashicorp/hcl.

What it runs against: a local clone of hashicorp/hcl — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in hashicorp/hcl | Confirms the artifact applies here, not a fork | | 2 | License is still MPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hashicorp/hcl. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hashicorp/hcl.git
#   cd hcl
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of hashicorp/hcl and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hashicorp/hcl(\\.git)?\\b" \\
  && ok "origin remote is hashicorp/hcl" \\
  || miss "origin remote is not hashicorp/hcl (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "diagnostic.go" \\
  && ok "diagnostic.go" \\
  || miss "missing critical file: diagnostic.go"
test -f "eval_context.go" \\
  && ok "eval_context.go" \\
  || miss "missing critical file: eval_context.go"
test -f "gohcl/decode.go" \\
  && ok "gohcl/decode.go" \\
  || miss "missing critical file: gohcl/decode.go"
test -f "ext/dynblock/expand_body.go" \\
  && ok "ext/dynblock/expand_body.go" \\
  || miss "missing critical file: ext/dynblock/expand_body.go"
test -f "ext/typeexpr/get_type.go" \\
  && ok "ext/typeexpr/get_type.go" \\
  || miss "missing critical file: ext/typeexpr/get_type.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/hashicorp/hcl"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.