test(infrastructure): add Go output contract tests for root Terraform module

[bindsi]

This PR completes the final sub-issue of the Go/Terratest umbrella (#290) by adding a fast, credential-free contract test that catches drift between the root Terraform module's declared output blocks and the typed InfraOutputs struct end-to-end tests rely on. The test runs in under one second, requires no terraform init and no Azure credentials, and uses terraform-docs to extract declared outputs at test time.

It also closes #335 by adding go to the CodeQL language matrix so the new Go code is scanned alongside JavaScript/TypeScript and Python from day one.

Description

The new contract pattern lives under infrastructure/terraform/e2e/ and has three layers. A reusable testutil package shells out to terraform-docs json to discover declared outputs, then validates them against a required-key set produced by reflection over output:"..." struct tags. A typed InfraOutputs struct in outputs.go defines that contract for the root module's 27 outputs. A thin TestTerraformOutputsContract entry point wires the two together and is the first real test in the previously placeholder e2e package.

CI wiring lives in .github/workflows/go-tests.yml: a pinned Install terraform-docs step (v0.21.0, SHA256 verified) runs between Setup Go and Run Go tests. A small developer helper, run-contract-tests.sh, provides a one-command local entry point with preflight checks for go and terraform-docs. The *.go row in .github/copilot-instructions.md now cites the helper alongside the existing lint and test commands.

Test infrastructure

The contract is intentionally required-subset-of-declared. Adding a new output to outputs.tf without updating InfraOutputs leaves the test green; removing a declared output that the struct still references fails with an actionable message naming outputs.tf. Both directions were probed during validation.

• New testutil package exposing GetTerraformDeclaredOutputs, ValidateOutputContract, ValidateTerraformContract, and GetOutputKeysFromStruct — reused unchanged by future per-deployment contracts.
• New InfraOutputs struct mirroring the root module's 27 outputs, each tagged with output:"<name>"; RequiredOutputKeys() extracts the tag set via reflection.
• New TestTerraformOutputsContract in contract_test.go — replaces the placeholder e2e.go file as the package's anchor.
• Unit tests in testutil/contract_test.go cover value/pointer receivers, empty struct, untagged struct, and contract-validation success paths so the Codecov go flag reports meaningful coverage on the helper.
• go.mod / go.sum now require github.com/stretchr/testify v1.11.1.

CI and tooling

• New Install terraform-docs step in go-tests.yml, pinned to v0.21.0 with explicit SHA256 verification matching the literal already used by terraform-docs-check.yml. Installs to /usr/local/bin/ via sudo mv on ubuntu-latest.
• New executable run-contract-tests.sh with set -euo pipefail, a -v/--verbose flag, and clear preflight messages when go or terraform-docs is missing.
• .github/copilot-instructions.md *.go Quick Reference row updated to list the new helper and call out the terraform-docs dependency.
• .github/workflows/codeql-analysis.yml matrix gains go (closes ci(security): add Go to CodeQL language matrix #335); CodeQL autobuild discovers infrastructure/terraform/e2e/go.mod automatically.

Documentation table-alignment catch-up

A pre-existing format:tables drift in six markdown files (data-pipeline/arc/README.md, data-pipeline/setup/README.md, docs/data-pipeline/acsa-setup.md, docs/security/README.md, docs/security/workflow-permissions.md, scripts/README.md) is included as whitespace-only edits, balanced 101 insertions / 101 deletions. No content change.

Type of Change

• ✨ New feature (non-breaking change adding functionality)
• 📚 Documentation update
• 🐛 Bug fix (non-breaking change fixing an issue)
• 💥 Breaking change (fix or feature causing existing functionality to change)
• 🏗️ Infrastructure change (Terraform/IaC)
• ♻️ Refactoring (no functional changes)

Component(s) Affected

• infrastructure/terraform/prerequisites/ - Azure subscription setup
• infrastructure/terraform/ - Terraform infrastructure
• infrastructure/setup/ - OSMO control plane / Helm
• workflows/ - Training and evaluation workflows
• training/ - Training pipelines and scripts
• docs/ - Documentation

Testing Performed

• Terraform plan reviewed (no unexpected changes)
• Terraform apply tested in dev environment
• Training scripts tested locally with Isaac Sim
• OSMO workflow submitted successfully
• Smoke tests passed (smoke_test_azure.py)

Additional validation specific to this PR (all passed locally):

• npm run test:go — 10/10 tests pass across e2e and testutil packages
• ./infrastructure/terraform/e2e/run-contract-tests.sh — end-to-end helper exercise green in <1s
• npm run lint:yaml, npm run lint:md, npm run spell-check — all clean
• shellcheck infrastructure/terraform/e2e/run-contract-tests.sh — clean
• Contract drift probes — extra declared outputs tolerated; missing declared output fails with the expected outputs.tf pointer

Documentation Impact

• No documentation changes needed
• Documentation updated in this PR
• Documentation issue filed

Bug Fix Checklist

Not applicable — this is a feature PR adding new tests.

• Linked to issue being fixed
• Regression test included, OR
• Justification for no regression test:

Checklist

• My code follows the project conventions
• Commit messages follow conventional commit format
• I have performed a self-review
• Documentation impact assessed above
• No new linting warnings introduced

Related Issues

Closes #290
Closes #335 (CodeQL Go language matrix)

Notes

The single commit on this branch has a malformed message (no newlines between body bullets, so the entire body collapses into the subject line). Recommend amending to the conventional-commit format before push:

test(infrastructure): add Go contract tests for root Terraform outputs (#290)

* add testutil package with terraform-docs-driven contract validation
* add InfraOutputs struct with 27 tagged fields mirroring outputs.tf
* add TestTerraformOutputsContract entry point (<1s, zero Azure creds)
* wire pinned terraform-docs install into go-tests.yml
* include whitespace-only table-alignment catch-up in 6 docs READMEs

🤖 - Generated by Copilot

Follow-up

Tracked in the implementation plan's Planning Log:

• WI-01 — G-005 deployment tests (real terraform apply against Azure)
• WI-02 — Contract tests for Terraform submodules
• WI-03 — Per-deployment contract tests (VPN, DNS, automation)
• WI-04 — Flip go-tests.yml soft-fail to hard-fail once stable on CI
• WI-05 — Composite action for Install terraform-docs to dedupe with terraform-docs-check.yml
• WI-06 / ci(security): add Go to CodeQL language matrix #335 — Add go to the CodeQL language matrix once Go LOC exceeds ~500

[github-actions]

Dependency Review

The following issues were found:

• ✅ 0 vulnerable package(s)
• ✅ 0 package(s) with incompatible licenses
• ✅ 0 package(s) with invalid SPDX license definitions
• ⚠️ 4 package(s) with unknown licenses.

See the Details below.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA a4ce5ee.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

License Issues

infrastructure/terraform/e2e/go.mod

Package	Version	License	Issue Type
github.com/davecgh/go-spew	1.1.1	Null	Unknown License
github.com/pmezard/go-difflib	1.0.0	Null	Unknown License
github.com/stretchr/testify	1.11.1	Null	Unknown License
gopkg.in/yaml.v3	3.0.1	Null	Unknown License

OpenSSF Scorecard

Package	Version	Score	Details
gomod/github.com/davecgh/go-spew	1.1.1	Unknown	Unknown
gomod/github.com/pmezard/go-difflib	1.0.0	Unknown	Unknown
gomod/github.com/stretchr/testify	1.11.1	Unknown	Unknown
gomod/gopkg.in/yaml.v3	3.0.1	Unknown	Unknown

Scanned Files

• infrastructure/terraform/e2e/go.mod

[codecov-commenter]

Codecov Report

❌ Patch coverage is 93.75000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.67%. Comparing base (6141db4) to head (a4ce5ee).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
infrastructure/terraform/e2e/testutil/contract.go	93.47%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #571      +/-   ##
==========================================
+ Coverage   65.16%   66.67%   +1.50%     
==========================================
  Files         251      264      +13     
  Lines       15597    16659    +1062     
  Branches     2152     2294     +142     
==========================================
+ Hits        10164    11107     +943     
- Misses       5142     5264     +122     
+ Partials      291      288       -3     

Flag	Coverage Δ		*Carryforward flag
go	93.75% <93.75%> (?)
pester	83.13% <ø> (ø)		Carriedforward from 0ca5df9
pytest-data-pipeline	100.00% <ø> (ø)		Carriedforward from 0ca5df9
pytest-dataviewer	65.21% <ø> (-1.72%)	⬇️	Carriedforward from 0ca5df9
pytest-dm-tools	100.00% <ø> (ø)		Carriedforward from 0ca5df9
pytest-evaluation	99.83% <ø> (?)
pytest-fuzz	4.99% <ø> (+0.09%)	⬆️	Carriedforward from 0ca5df9
pytest-inference	0.00% <ø> (ø)		Carriedforward from 0ca5df9
pytest-training	82.14% <ø> (ø)		Carriedforward from 0ca5df9
vitest	51.06% <ø> (-1.96%)	⬇️	Carriedforward from 0ca5df9

*This pull request uses carry forward flags. Click here to find out more.

Files with missing lines	Coverage Δ
infrastructure/terraform/e2e/outputs.go	100.00% <100.00%> (ø)
infrastructure/terraform/e2e/testutil/contract.go	93.47% <93.47%> (ø)

... and 30 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

[katriendg]

This is looking fantastic — solid contract testing pattern, clean CI wiring, and the terraform-docs SHA verification is a nice touch. A few items to tighten up before merge, mostly around test coverage and documentation cross-references.

---

Additional documentation cross-references (files not in this diff)

⚠️ docs/contributing/contribution-workflow.md — Terraform modules row (line ~170)

The Terraform modules validation row lists terraform fmt, terraform validate, and terraform plan but doesn't mention that output changes also require npm run test:go to validate the contract. Suggest:

| Terraform modules | `terraform fmt`, `terraform validate`, `terraform plan` output attached to PR, `npm run test:go` (output contract) |

⚠️ docs/contributing/prerequisites.md — Go validation section (line ~190)

The Go block lists lint and test commands but doesn't explain that contract tests validate Terraform outputs or that terraform-docs is required. Suggest adding after the existing Go block:

# Contract tests (validates Terraform outputs against Go struct — requires terraform-docs)
# Run after adding/removing/renaming Terraform outputs
./infrastructure/terraform/e2e/run-contract-tests.sh

💡 docs/contributing/contribution-workflow.md — Go modules row (line ~173)

Contributors who run npm run test:go without terraform-docs installed will get a failure with no guidance from this table. Suggest:

| Go modules | `npm run lint:go` (golangci-lint), `npm run test:go` (`go test`, requires `terraform-docs`) |

[rezatnoMsirhC]

Thanks for a well-structured PR. The contract pattern is clean, the testutil package is reusable, and the CI wiring is correct. Left two comments.

[rezatnoMsirhC]

The testutil fixture tests (TestGetTerraformDeclaredOutputs, TestValidateTerraformContract) both guard with exec.LookPath("terraform-docs") and call t.Skip() when the tool is absent. This test has no such guard, so running go test ./... on a machine without terraform-docs installed produces a hard failure with an opaque require.NoError message rather than a clean skip. Suggest adding the same guard for consistency:

func TestTerraformOutputsContract(t *testing.T) {
    if _, err := exec.LookPath("terraform-docs"); err != nil {
        t.Skip("terraform-docs not installed; skipping contract test")
    }
    testutil.ValidateTerraformContract(t, "..", InfraOutputs{}.RequiredOutputKeys())
}

[rezatnoMsirhC]

Two t.Errorf calls (non-fatal) followed by require.Empty (fatal) report the same condition. The final "output contract validation failed" message is less informative than the preceding errors and adds noise to test output. Suggest consolidating into a single require.Empty with the full actionable message:

func ValidateOutputContract(t *testing.T, declared, required []string) {
    t.Helper()

    t.Logf("Declared outputs: %v", declared)
    t.Logf("Required outputs: %v", required)

    missing := findMissingOutputs(declared, required)
    require.Empty(t, missing,
        "missing %d required outputs: %v -- declare these in infrastructure/terraform/outputs.tf or remove from InfraOutputs struct",
        len(missing), missing)
}