Azure / Azure/azure-verified-modules-tools
Add a spell check step to the Terraform gauntlet
- Dominant language
- PowerShell
- Stars
- 2
- Forks
- 5
- Avg merge
- 12h 51m
- Merged PRs (30d)
- 30
Description
## Problem
Typos in `variable` / `output` descriptions reach `main` and then propagate into the generated `README.md`, because `README.md` is produced by terraform-docs from the `description` fields. Nothing in `avm pre-commit` or `avm pr-check` inspects prose today.
Recent example: [`Azure/terraform-azurerm-avm-res-containerregistry-registry#207`](https://github.com/Azure/terraform-azurerm-avm-res-containerregistry-registry/pull/207). `Requries` shipped in the `anonymous_pull_enabled` description, an external contributor spotted it months later, and their first instinct was to patch the generated `README.md` — which pre-commit would have reverted on the next docs run. The real fix was in `variables.containerregistry.tf`.
A spell check would have blocked this at the PR that introduced the description, and would have pointed the contributor at the source file rather than the artifact.
## Proposal
Add [`typos`](https://github.com/crate-ci/typos) as a managed tool and run it as a step in the pre-commit and pr-check gauntlets.
`typos` matches against a curated corpus of *known misspellings* rather than doing dictionary lookup, so it does not flag unknown identifiers. That is the property that makes it viable in a repo full of `azurerm`, `mptf`, `tfvars`, `privatelink`, and `sku`.
## Evidence
Run against `Azure/terraform-azurerm-avm-res-containerregistry-registry` at the commit before the fix:
```
error: `Requries` should be `Requires`
--> ./variables.containerregistry.tf:10:116
error: `Requries` should be `Requires`
--> ./README.md:117:112
```
Full-repo scan for false positives — one unique word, `CAF` (Cloud Adoption Framework, in the `module "naming"` comment carried by every example):
| | Result |
|---|---|
| Real typos | 0 (already fixed) |
| False positives | 18 hits, 1 unique word (`CAF`) |
A two-line config clears it, after which the repo exits 0:
```toml
[default.extend-words]
CAF = "CAF"
```
## Placement
`check convention` looks like the natural home but probably is not: `Invoke-AvmTerraformCheckConvention` states it "does not invoke any external tool", and its three primitives (`FileMustExist`, `FileMustNotExist`, `DirectoryMustExist`) are all existence checks with no content inspection. Adding a binary dependency there would change that guarantee.
Suggest instead following the `terraform-docs` / `mapotf` pattern:
- pin `typos` in `src/Avm.Authoring/Resources/avm.pins.jsonc` under `tools[]`
- add a gauntlet step wired into `Invoke-AvmPreCommit` and `Invoke-AvmPrCheck`
Happy to be redirected if a content-inspecting convention primitive is preferred — the outcome that matters is that it runs locally in `avm pre-commit` and in CI, so contributors see it before pushing.
## Notes
- **Scan the repo, not the diff.** `Azure/azure-sdk-for-cpp#2228` hit a diff-scoped spell check that silently passed on PRs touching 100+ files. Full-repo scans complete in well under a second, so there is no reason to scope.
- **Ramp severity.** Landing at `warning` first surfaces the existing backlog without blocking; promote to `error` once repos are clean. `Azure/azure-sdk-for-cpp#2222` is the counter-example — warnings nobody actioned.
- **Per-repo allowlist.** Modules need somewhere to record legitimate terms like `CAF`. A committed `.typos.toml`, or the existing `.avm/` override convention.
- **Platform gap.** `typos` publishes no `aarch64-pc-windows-msvc` asset (v1.49.0 ships linux musl x64/arm64, darwin x64/arm64, windows x64 only). Same gap `tflint` has, already modelled by `unsupportedPlatforms` / `AVM1012`. Worth deciding whether windows-arm64 falls back to the x64 build under emulation or is marked unsupported.
Contributor guide
Research direction
Start with src/Avm.Authoring/Resources/avm.pins.jsonc and trace the terraform-docs/mapotf wiring into Invoke-AvmPreCommit and Invoke-AvmPrCheck. Run avm pre-commit and avm pr-check before and after the change, and review the unsupportedPlatforms handling. Done means a pinned typos tool scans the full repository locally and in CI, with configuration for legitimate terms and an agreed warning or error severity.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- powershell
- Domain
- ci-cd, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 56/100