TerraForetell

TerraForetell is a Go CLI for forecasting Terraform provider and module upgrade impact. It uses HashiCorp's official HCL parser and Terraform JSON libraries for Terraform-aware analysis.

Install From Source

go install github.com/ydah/terraforetell/cmd/terraforetell@latest

For local development:

make build
./dist/terraforetell help

Commands

terraforetell analyze \
  --base-plan-json old.tfplan.json \
  --head-plan-json new.tfplan.json \
  --old-schema-json old.providers.schema.json \
  --new-schema-json new.providers.schema.json \
  --out-dir .terraforetell/out \
  --format json,markdown,sarif

Useful focused commands:

terraforetell schema-diff --old old.providers.schema.json --new new.providers.schema.json --hcl-root envs/prod/network
terraforetell module-diff --old-root /tmp/module-v2 --new-root /tmp/module-v3 --consumer-root envs/prod/network --module-call module.vpc
terraforetell render-pr-comment --report .terraforetell/out/report.json
terraforetell github-comment --report .terraforetell/out/report.json --repo owner/repo --pr 123
terraforetell release-notes --provider registry.terraform.io/hashicorp/aws --from 5.72.1 --to 6.0.0
terraforetell suggest-fixes --report .terraforetell/out/report.json --rulepack rulepacks/aws.yaml --hcl-root .

The Go CLI supports candidate detection from Git diffs, artifact-based and Terraform-runner plan/schema analysis, local and remote module API diffing, SARIF output, GitHub PR comments, provider release notes, and codemod patch suggestions.

Implemented

• Candidate detection for provider lockfiles, provider requirements, module source changes, local module content changes, and Terraform/OpenTofu version files.
• Plan JSON normalization with sensitive and unknown value redaction.
• Baseline vs target plan impact detection for create/update/delete/replace/read.
• Provider schema diff with HCL usage locations.
• Module API diff for variables, outputs, provider requirements, and Terraform version constraints.
• Local, Git, and Terraform Registry module source resolution.
• JSON, Markdown, and SARIF report rendering.
• GitHub PR comment upsert, provider release note lookup, and rulepack-based patch suggestions.

See docs/github-integration.md for CI usage.

Development

go test ./...
make build
make test
make check