bug(roles): dead-code verdicts emitted for parse-only languages (HCL) where call resolution is absent by design

[carlos-alm]

Summary

For languages where call resolution is intentionally absent, role classification still emits dead-unresolved for every symbol. The verdict is 100% false-positive by construction, and it invites destructive action — an agent or human reading "132 dead symbols" in a Terraform repo may try to delete live infrastructure.

This is not a request for HCL call resolution. The README support matrix is explicit and correct that Terraform/HCL is parse-only (✓ for symbols, —³ for heritage/type-inference/call-graph, footnoted "declarative — no functions, classes, or type system"), and resolution-benchmark.test.ts sets hcl: { precision: 0.0, recall: 0.0 } under the comment "New fixture languages — no parser or call resolution yet". Absence of call edges for HCL is by design. Emitting a dead-code verdict anyway is the defect.

Reproduction

Minimal Terraform file where every resource is actively referenced:

resource "aws_kms_key" "state" { description = "state encryption key" }
resource "aws_s3_bucket" "state" { bucket = "my-state-bucket" }

resource "aws_s3_bucket_server_side_encryption_configuration" "state" {
  bucket = aws_s3_bucket.state.id                      # references aws_s3_bucket.state
  rule {
    apply_server_side_encryption_by_default {
      kms_master_key_id = aws_kms_key.state.arn        # references aws_kms_key.state
    }
  }
}

output "bucket_name" { value = aws_s3_bucket.state.bucket }   # references aws_s3_bucket.state

$ codegraph build
Native build orchestrator completed: 6 nodes, 5 edges, 1 files

$ codegraph roles
Node roles (4 symbols):
  dead-unresolved: 4
## dead-unresolved (4)
  - aws_kms_key.state  main.tf:1
  - aws_s3_bucket.state  main.tf:5
  - aws_s3_bucket_server_side_encryption_configuration.state  main.tf:9
  - output.bucket_name  main.tf:18

All 4 flagged dead; aws_s3_bucket.state is referenced three times. All 5 edges are contains — there are zero reference edges, as expected for a parse-only language.

Confirmed independently on optave/tenant-optave-autopilot-svc during the org rollout: 129 of its 132 dead-unresolved symbols are .tf, including KMS keys and buckets wired together in the same file.

Also worth noting: the HCL fixture's expected edges never materialize

tests/benchmarks/resolution/fixtures/hcl/expected-edges.json declares 2 calls edges (module.user_service → module.repository, → module.validators). Building that fixture yields 31 nodes, 27 edges, all contains — 0 of 2 expected edges. The benchmark passes only because the HCL threshold is 0.0/0.0. That's self-consistent with parse-only support, but it means the fixture and its manifest currently encode an aspiration no test enforces. Either wire the module-reference edges up, or annotate the manifest as pending so it isn't mistaken for a passing capability.

Suggested fix

Gate dead-code classification on whether the language has call-resolution support. For parse-only languages, either omit dead-* roles entirely or emit a distinct, clearly non-actionable role (e.g. unanalyzed). The language capability is already known — LANGUAGE_REGISTRY in domain/parser.ts is the single source of truth, and the benchmark thresholds already encode which languages have no resolution.

Whatever shape is chosen, apply it to the mirrored Rust path in crates/codegraph-core/src/graph/classifiers/roles.rs so the engines don't diverge.

Why this matters now

The org-wide rollout writes a .codegraph/basics.md health baseline into every Optave repo, including Terraform ones. Right now those baselines have to carry an explicit "ignore this number, it's a false positive" caveat — which is exactly the "documenting a bug as expected behavior" pattern CLAUDE.md warns against.

Related

• False dead-code classifications from unresolved cross-directory calls #2177 — false dead-code classifications from unresolved cross-directory calls (different root cause, same user-visible symptom)
• bug(stats): roles map double-counts dead symbols — aggregate 'dead' key is a peer of its own sub-roles #2383, roles --role dead -T: hand-authored test fixture directories aren't excluded, causing reachability noise #2256 — other defects inflating dead-code figures

[carlos-alm]

Further verification from two more Terraform repos in the rollout, plus a correction and one new concrete gap.

Confirmed at 100% false-positive rate. On client-autopilot-scaffold-lib: all 424 edges are contains (411) or calls (13), and every one of the 13 calls edges originates in Bash scripts — not one comes from any of the 12 .tf/.hcl files. All 129 HCL blocks are flagged dead-unresolved. Manually cross-checked aws_kms_alias.state → aws_kms_key.state.key_id and var.project_name used across 5+ resources: no edge for any of them.

Also confirmed on core-orchestrator-svc (592 of 746 non-test dead symbols, 79%, are Terraform), interface-autopilot-web-app (468 of 793, 59%), data-analytics-pipeline-svc, tenant-optave-data-retrieval-svc, and client-data-retrieval-scaffold-lib (84 of 85).

Correction to something I said earlier in this rollout. I had noted that codegraph where works for HCL. That is too generous: it resolves only the module kind, and apparently by coincidence rather than support — module is already in the shared symbol-kind vocabulary. Everything else is invisible:

$ codegraph where "module.security"
… resolves

$ codegraph where "aws_kms_key.state"
No symbol matching "aws_kms_key.state" in graph

— despite that node existing in the DB (kind=resource, infra/terraform/bootstrap/main.tf:9). In that repo, 119 of 129 HCL blocks are unreachable by name.

New, concretely fixable gap: HCL kinds are missing from the --kind allowlist. There is currently no CLI workaround for the above, because the kind validator rejects HCL's own kinds outright:

$ codegraph context "aws_kms_key.state" -k resource -T
codegraph [CONFIG_INVALID]: Invalid kind "resource". Valid: function, method, class,
interface, type, struct, enum, trait, record, module, parameter, property, constant

resource, output, variable, data, locals, and provider are all extracted as node kinds — codegraph stats on this repo's self-build reports output 4, resource 2 — but they cannot be named on the command line. So symbols codegraph successfully extracted are unqueryable by kind.

That last point is worth separating from the larger "no reference edges" design question: adding the extracted HCL kinds to the --kind allowlist is a small, self-contained fix that would make the parse-only symbol inventory actually usable, independent of whether reference-edge extraction is ever implemented.