feat: add the validate-min-terraform action (ENG-8760)

[ENG-8760](https://stacklet.atlassian.net/browse/ENG-8760)

What
----

- Adds `validate-min-terraform`, a composite action that reads a module's
  Terraform floor out of `required_version` and runs `terraform validate` at
  that release.
- Sets the repository up for the tools that follow: one directory per tool,
  each with an `action.yml` and a `README.md`, plus a lint workflow, a prek
  config, a justfile and a README that records the layout.

Why
----

Five of the AWS and Azure onboarding module repositories need this job, and the
version of it that ENG-8760 wrote carries enough shell to be worth maintaining
in one place. Each repository validates at the release pinned in
`.tool-versions`, which sits near the top of the supported range, so nothing
covered the bottom of it. That is how `required_version = ">= 1"` survived in a
module that no release below 1.8 can even parse.

The action derives the floor rather than taking it as an input, so editing the
constraint moves what CI tests in the same commit. It runs terraform-docs to
parse the configuration instead of matching a regex against one file, which is
what the published actions do and what makes them wrong on a second `.tf`, a
`.tf.json`, or a constraint split across lines. The terraform-docs image is
pinned by digest because the project publishes no immutable releases, so both a
tag and a release checksum can change underneath us.

Callers pin by commit SHA. This repository publishes no release tags, and a
floating ref would put the module repositories' CI under whatever lands here
next.

Testing
----

- [x] Ran the floor derivation against a module carrying three constraints at
      once, one of them in a `.tf.json` and one split across lines: it reports
      the highest lower bound, where the regex-based action reports an empty
      string that `semver` then reads as "any version".
- [x] Ran it against all five onboarding modules, each of which resolves to the
      floor its `required_version` states.
- [x] Checked the operator handling across a matrix: `>= 1.14.0`,
      `>= 1.14.0, < 2.0.0` and `~> 1.14` resolve; `!=`, a bare version and `>`
      are rejected; an upper bound on its own reports that the constraint
      states no lower bound.
- [x] Checked that a container that fails to run prints docker's own error,
      rather than surfacing as an empty parse further down.
- [x] `just lint` clean, with zizmor re-run under a token to confirm the five
      online audits schedule rather than skip. zizmor audits `action.yml` as
      well as the workflow.
- [ ] Confirm the action runs end to end once this merges and the module
      repositories point at it.

Docs
----

`README.md` lists the tools and says how to add one. The action carries its own
`README.md` with usage, inputs, outputs and a note on the one case it cannot
catch: `terraform validate` never evaluates `validation` blocks, so a floor
that is only wrong inside one still passes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: johnsca

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions: {}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: j178/prek-action@4e14d07f9231acabce116ccfca13b13dd9755ece # v3.0.0
+        env:
+          # zizmor's five online audits skip silently without a token, and its
+          # summary line reads the same either way, so CI would look green with
+          # the supply-chain audits never having run.
+          GH_TOKEN: ${{ github.token }}

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/rhysd/actionlint
+    rev: 393031adb9afb225ee52ae2ccd7a5af5525e03e8  # frozen: v1.7.11
+    hooks:
+      - id: actionlint
+
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: ea2eb407b4cbce87cf0d502f36578950494f5ac9  # frozen: v1.23.1
+    hooks:
+    - id: zizmor
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a  # frozen: v2.4.2
+    hooks:
+      - id: codespell

.tool-versions

@@ -0,0 +1,2 @@
+just 1.40.0
+uv 0.8.14

README.md

@@ -1,2 +1,23 @@
 # github-tooling
-Reusable GitHub Actions and workflows shared across Stacklet repositories
+
+Reusable GitHub Actions and workflows shared across Stacklet repositories.
+
+Each tool lives in its own top-level directory with an `action.yml` and a `README.md`. Reference one by path:
+
+```yaml
+- uses: stacklet/github-tooling/<tool>@<commit-sha>
+```
+
+Pin by commit SHA. This repository publishes no release tags, so a SHA is the only reference that cannot move.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| [validate-min-terraform](validate-min-terraform/) | Runs `terraform validate` at the oldest release a module's `required_version` allows. |
+
+## Adding a tool
+
+1. Create a directory named for the tool.
+2. Add an `action.yml` and a `README.md` covering usage, inputs, and outputs.
+3. Add a row to the table above.

justfile

@@ -0,0 +1,3 @@
+# lint files
+lint:
+    uvx prek run --all-files

validate-min-terraform/README.md

@@ -0,0 +1,49 @@
+# validate-min-terraform
+
+Runs `terraform validate` against a module at the oldest Terraform release the module says it supports.
+
+A repository's lint job validates at the release pinned in `.tool-versions`, which is near the top of the supported range. Nothing covers the bottom of the range, so a module can declare `required_version = ">= 1.0"` and use syntax that no release below 1.8 parses. This action closes that gap.
+
+## Usage
+
+```yaml
+jobs:
+  validate-min-terraform:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: stacklet/github-tooling/validate-min-terraform@<commit-sha>
+```
+
+## Inputs
+
+| Name | Default | Description |
+| --- | --- | --- |
+| `working-directory` | `.` | Directory holding the module to validate. |
+| `terraform-docs-image` | a digest-pinned terraform-docs 0.20.0 | Image used to parse the configuration. |
+
+## Outputs
+
+| Name | Description |
+| --- | --- |
+| `version` | The Terraform release the module declares as its floor. |
+
+## How the floor is derived
+
+`terraform-docs` parses the configuration and reports every `required_version` in the module. Terraform applies all of them at once, so the effective floor is the highest lower bound among them. Only `>=` and `~>` state that bound literally, and `<` and `<=` cannot move it.
+
+The action fails rather than guessing on anything else. A constraint with no lower bound has no floor to test, and an operator such as `!=` or `=` can rule out the bound another term states, which would otherwise install a release the module excludes.
+
+Running a real parser matters. A regex over `*.tf` misses a constraint in a `.tf.json`, misses a second `.tf` file, and reads a constraint split across lines as empty, which several published actions then treat as "any version".
+
+The terraform-docs image is pinned by digest because the project publishes no immutable releases, so both a tag and a release checksum can change underneath us. Bumping the version means bumping the digest in `action.yml`.
+
+## Known limitation
+
+`terraform validate` run against a module directory treats every root variable as unknown, so it never evaluates `validation` blocks. A module whose floor is wrong only inside a variable validation still passes here. Closing that needs `terraform test` with `mock_provider`.

validate-min-terraform/action.yml

@@ -0,0 +1,107 @@
+name: Validate the declared Terraform floor
+description: >-
+  Reads the Terraform floor out of a module's required_version and runs
+  terraform validate at that release.
+
+inputs:
+  working-directory:
+    description: Directory holding the Terraform module to validate.
+    required: false
+    default: .
+  terraform-docs-image:
+    description: >-
+      Image used to parse the configuration. Pin by digest, not by tag.
+    required: false
+    # terraform-docs publishes no immutable releases, which leaves both a tag
+    # and a release checksum able to change underneath us. A digest is content
+    # addressed, so it cannot. This one is terraform-docs 0.20.0.
+    default: quay.io/terraform-docs/terraform-docs@sha256:37329e2dc2518e7f719a986a3954b10771c3fe000f50f83fd4d98d489df2eae2
+
+outputs:
+  version:
+    description: The Terraform release the module declares as its floor.
+    value: ${{ steps.floor.outputs.version }}
+
+runs:
+  using: composite
+  steps:
+    # The floor is read out of required_version rather than passed in, so that
+    # editing the constraint moves what CI tests in the same commit.
+    # terraform-docs parses the configuration instead of matching a regex
+    # against one file, so it reports every required_version in the module,
+    # including one in a .tf.json or split across lines.
+    - name: Read the declared Terraform floor
+      id: floor
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        TERRAFORM_DOCS_IMAGE: ${{ inputs.terraform-docs-image }}
+      run: |
+        # terraform-docs writes its own diagnostics to stderr, and merging those
+        # into the pipe below breaks the JSON parse. They are kept aside rather
+        # than discarded so that a failed pull or a parse error still says what
+        # went wrong instead of surfacing as empty output.
+        stderr=$(mktemp)
+        if ! parsed=$(docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/wd" -w /wd \
+          "$TERRAFORM_DOCS_IMAGE" json . --output-file '' 2>"$stderr"); then
+          echo "terraform-docs could not read this module:" >&2
+          cat "$stderr" >&2
+          exit 1
+        fi
+        constraints=$(printf '%s' "$parsed" \
+          | jq -r '.requirements[] | select(.name == "terraform") | .version')
+        if [ -z "$constraints" ]; then
+          echo "this module declares no required_version" >&2
+          exit 1
+        fi
+
+        # Terraform applies every required_version in the module at once, so the
+        # effective floor is the highest lower bound among them. Only >= and ~>
+        # state that bound literally, and an operator such as != or = can rule
+        # out the bound another term states. Resolving either needs the release
+        # list, so reject what this cannot read rather than guess at it.
+        bounds=""
+        while IFS= read -r term; do
+          term=$(printf '%s' "$term" | tr -d '[:space:]')
+          [ -n "$term" ] || continue
+          case "$term" in
+            '>='*|'~>'*) bound=${term#??} ;;
+            # An upper bound cannot move the floor, so it needs no reading.
+            '<'*) continue ;;
+            *)
+              echo "cannot resolve a Terraform floor from: $term" >&2
+              echo "required_version may use >=, ~>, < and <= only" >&2
+              exit 1
+              ;;
+          esac
+          if ! printf '%s' "$bound" | grep -qE '^[0-9]+\.[0-9]+(\.[0-9]+)?$'; then
+            echo "not a version this can resolve: $term" >&2
+            exit 1
+          fi
+          case "$bound" in *.*.*) ;; *) bound="$bound.0" ;; esac
+          bounds=$(printf '%s\n%s' "$bounds" "$bound")
+        done <<EOF
+        $(printf '%s' "$constraints" | tr ',' '\n')
+        EOF
+
+        # grep exits non-zero on no match, which under -e would end the step
+        # before the message below gets to say why.
+        floor=$(printf '%s' "$bounds" | grep -v '^$' | sort -V | tail -1) || true
+        if [ -z "$floor" ]; then
+          echo "required_version states no lower bound; found:" >&2
+          printf '  %s\n' "$constraints" >&2
+          exit 1
+        fi
+        echo "version=$floor" >> "$GITHUB_OUTPUT"
+
+    - name: Setup Terraform
+      uses: hashicorp/setup-terraform@dfe3c3f87815947d99a8997f908cb6525fc44e9e # v4.0.1
+      with:
+        terraform_version: ${{ steps.floor.outputs.version }}
+
+    - name: Validate at the declared floor
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: |
+        terraform init -backend=false
+        terraform validate