[jsteinich]

Related issue

Fixes #392. Unblocked by #405, which landed the per-test runtime pinning this builds on.

Description

test/typescript/terraform-cloud/test.ts feeds TERRAFORM_VERSION — set from the matrix axis — into the terraformVersion attribute of an HCP Terraform workspace. If the matrix ever resolves that target to OpenTofu, the test asks HCP Terraform for a workspace pinned to a Terraform version that does not exist, and there is no correct value to pass: that API executes Terraform remotely and has no OpenTofu equivalent.

The target is declared Terraform-only in the matrix builder, and the builder throws if it ever resolves otherwise:

const terraformOnly = new Set([
  // HCP Terraform's workspace API pins a Terraform version and has no OpenTofu equivalent.
  "typescript/terraform-cloud/test.ts",
]);

The check runs against each target's resolved runtime rather than against pinnedRuntimes, so it catches both a pin and a hypothetical future non-Terraform default axis. Filtering the default axis instead would have silently dropped the target — the same class of quiet misconfiguration the issue is about.

Why not the other two options the issue lists

Skip inside the test trades a loud failure for a green job that asserted nothing. If someone later pinned this target to tofu, CI would read as OpenTofu coverage while proving nothing.

Hardcode terraformVersion to a fixed release is the one worth pushing back on. Today TERRAFORM_VERSION makes the workspace's remote Terraform version match the local CLI the matrix selected. Hardcoding one side introduces deliberate local/remote skew on every entry that isn't the hardcoded version, and collapses remote-version coverage to one version — so both matrix entries would create identical workspaces and half the jobs become redundant. It also would not settle a tofu pin: you would still be driving a remote-execution Terraform workspace with tofu, failing confusingly rather than loudly. terraform-cloud/test.ts is untouched.

Second commit: making the guard trustworthy

Both this guard and pinnedRuntimes from #405 are keyed by test path, and a key matching no discovered target makes them silently inert. Verified: with a typo'd terraformOnly key, a tofu-pinned terraform-cloud entry sails through exactly as if the guard were absent. That defeats the purpose of adding it, so the keys are now validated once against the discovered target list, after discovery, and both maps fail closed.

Testing

tools/build-test-matrix.mjs does not run natively on Windows (execFileSync("npx") needs .cmd; the testDir prefix strip assumes forward slashes), so the real logic was run against a stubbed discovery list — only the execFileSync block is replaced, with stubs built using the same `${testDir}/` prefix so the prefix-strip path is still exercised. Pins, guards, HCL detection and binary naming are untouched source.

case	result
default config	identical to baseline; terraform-cloud gets terraform1.5.7 + terraform1.16.1
tofu pin on terraform-cloud	Error: typescript/terraform-cloud/test.ts is Terraform-only, but the matrix resolved it to opentofu 1.12.6.
non-Terraform default axis, no pin	throws the same error — the claim in the code comment, proven rather than asserted
Terraform pin (1.5.5)	resolves normally; guard does not over-fire
typo'd terraformOnly key	Error: "…/tests.ts" is configured in pinnedRuntimes or terraformOnly but is not a discovered test target.
unrelated targets	identical before/after

prettier --check and node --check clean.

Latent coupling elsewhere: checked, this is the only one

A repo-wide sweep for TERRAFORM_VERSION found test/typescript/terraform-cloud/test.ts (lines 7 and 47) to be the only test consumer; every other hit is a producer (integration.yml, provider-integration.yml) or a Docker build arg. A sweep of every process.env read under test/ turned up only TF_EXECUTE_LOCAL, TF_VAR_myvar, SWITCH_STACK, USE_CONSTRAINED_FUNCTION and TERRAFORM_CLOUD_* — none version- or product-coupled. It is also the only target touching app.terraform.io.

Not verified

The test itself cannot be run here: it needs TERRAFORM_CLOUD_TOKEN and talks to HCP Terraform. The stubbed harness proves the selection logic, not jest's discovery — so that the real target list is unchanged, and that the path key matches what jest --listTests emits, are confirmed by the first CI run of prepare-integration-tests. The key format is the same one the existing provider-features pin uses, and that pin resolves correctly in these runs.

Adjacent, deliberately not changed

examples.yml:171, pr-unit.yml:173, unit.yml:80 and provider-integration.yml:102 still string-concatenate "terraform${{ … }}" for TERRAFORM_BINARY_NAME, where integration.yml now uses matrix.binary. Those workflows have no OpenTofu axis today, so it is latent rather than broken.

🤖 Generated with Claude Code

[so0k]

No blocking or non-blocking findings.

• tools/build-test-matrix.mjs validates both pinnedRuntimes and terraformOnly keys against Jest-discovered targets, preventing renamed or mistyped paths from silently disabling the configuration.
• The Terraform-only check runs after runtime resolution, so it catches both an explicit OpenTofu pin and any future non-Terraform default runtime.
• The designation is consistent with test/typescript/terraform-cloud/test.ts, which sends TERRAFORM_VERSION to HCP Terraform’s remote workspace API.
• No workflow files or security-sensitive execution paths changed.

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days. This helps our maintainers find and focus on the active issues. If you've found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.