Terraform Standards

terraform-<provider>-<resource-name>/
├── main.tf           # Resource definitions only. No variable or output declarations.
├── variables.tf      # All input variable declarations.
├── outputs.tf        # All output declarations.
├── terraform.tf      # terraform {} block: required_version + required_providers.
├── README.md         # Required for registry publish. Generated by terraform-docs.
└── examples/
    └── complete/
        ├── main.tf   # A working end-to-end example calling the module.
        ├── variables.tf
        └── outputs.tf

├── locals.tf         # Local value definitions when they are substantial enough to split out.
├── data.tf           # data source lookups that inform resource configuration.
├── moved.tf          # moved {} blocks when refactoring resource addresses without destroy.
├── CHANGELOG.md      # Semantic version history. Required for registry uploads.
└── tests/
    └── *.tftest.hcl  # Native terraform test files.

infra/
├── main.tf           # Module calls and any top-level resource definitions.
├── variables.tf
├── outputs.tf
├── terraform.tf      # required_version + required_providers only.
├── providers.tf      # provider {} blocks with auth and feature flags.
├── backend.tf        # Remote state backend - kept separate for easy override.
├── override.tf       # LOCAL DEV ONLY. Never commit. Add to .gitignore.
└── env/
    ├── dev.tfvars
    ├── staging.tfvars
    └── prod.tfvars   # Non-sensitive defaults only. Never commit secrets.

# terraform.tf
terraform {
  required_version = ">= 1.9.0, < 2.0.0"
 
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 4.0.0, < 5.0.0"
    }
    random = {
      source  = "hashicorp/random"
      version = ">= 3.6.0, < 4.0.0"
    }
  }
}

# Example: using azurerm for all resources except one new service only in azapi
terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
    azapi = {
      source  = "azure/azapi"
      version = "~> 2.0"
    }
  }
}
 
# Standard resources with azurerm
resource "azurerm_resource_group" "this" {
  name     = "rg-ldo-uks-prd"
  location = "uksouth"
}
 
# New resource only available in azapi - document why
resource "azapi_resource" "new_service" {
  # This service is not yet available in the azurerm provider (v4.x)
  type = "Microsoft.NewService/services@2024-01-01"
  name = "new-service-instance"
  # ...
}

# Install (macOS)
brew install tenv
 
# Install (Linux - adjust arch as needed)
TENV_VERSION=$(curl -s https://api.github.com/repos/tofuutils/tenv/releases/latest | grep tag_name | cut -d'"' -f4)
curl -Lo /usr/local/bin/tenv \
    "https://github.com/tofuutils/tenv/releases/download/${TENV_VERSION}/tenv_${TENV_VERSION}_linux_amd64"
chmod +x /usr/local/bin/tenv
 
# Install a specific Terraform version
tenv terraform install 1.9.8
 
# Pin globally
tenv terraform use 1.9.8
 
# Pin to the current directory only (writes .terraform-version)
tenv terraform use 1.9.8 local
 
# Auto-detect: reads required_version from terraform.tf and installs if missing
tenv terraform detect

# .terraform-version
1.9.8

# providers.tf - provider config in root module only, never in reusable modules
provider "azurerm" {
  features {}
 
  # OIDC auth - ARM_CLIENT_ID, ARM_TENANT_ID, ARM_SUBSCRIPTION_ID set via env vars.
  # ARM_USE_OIDC=true set in the pipeline environment.
  # No client secret, no certificate, no ARM_CLIENT_SECRET.
  use_oidc = true
}

ARM_USE_OIDC=true
ARM_CLIENT_ID=<app-registration-client-id>
ARM_TENANT_ID=<tenant-id>
ARM_SUBSCRIPTION_ID=<subscription-id>
# ARM_OIDC_TOKEN is injected automatically by the runner (GitHub, Azure DevOps)

permissions:
  id-token: write   # Required for OIDC token request
  contents: read
 
steps:
  - name: Azure login (OIDC - no secrets)
    uses: azure/login@v2
    with:
      client-id: ${{ vars.AZURE_CLIENT_ID }}       # non-secret - use vars not secrets
      tenant-id: ${{ vars.AZURE_TENANT_ID }}
      subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

# providers.tf
 
provider "azurerm" {
  features {
    # Prevent accidental resource group deletion when it still has resources
    resource_group {
      prevent_deletion_if_contains_resources = true
    }
    # Never purge Key Vaults on destroy - allows recovery from accidental deletes
    key_vault {
      purge_soft_delete_on_destroy    = false
      recover_soft_deleted_key_vaults = true
    }
    # Prevent accidental VM deletion through the API
    virtual_machine {
      delete_os_disk_on_deletion     = true
      graceful_shutdown              = false
      skip_shutdown_and_force_delete = false
    }
  }
 
  subscription_id = var.subscription_id
  use_oidc        = true
}
 
provider "azapi" {
  subscription_id = var.subscription_id
  use_oidc        = true
}
 
provider "azuread" {
  use_oidc = true
}
 
# Multi-subscription alias - reference with provider = azurerm.secondary
provider "azurerm" {
  alias           = "secondary"
  subscription_id = var.secondary_subscription_id
  use_oidc        = true
  features {}
}

# .gitignore - Terraform override files
override.tf
override.tf.json
*_override.tf
*_override.tf.json

# override.tf - LOCAL DEV ONLY - gitignored
# Replaces the OIDC provider config in providers.tf with CLI auth.
# Run `az login` and `az account set --subscription <id>` before applying.
 
provider "azurerm" {
  features {}
  subscription_id = "00000000-0000-0000-0000-000000000000"  # your dev subscription
  # use_oidc omitted - azurerm falls back to CLI / environment auth
}
 
provider "azapi" {
  subscription_id = "00000000-0000-0000-0000-000000000000"
}

# backend_override.tf - LOCAL DEV ONLY - gitignored
# Switches to local state so you can plan/apply without remote backend access.
# WARNING: do not mix local and remote state for the same environment.
 
terraform {
  backend "local" {
    path = "terraform.tfstate.local"
  }
}

# Required input - no default
variable "name" {
  description = "The name of the Logic App Standard instance."
  type        = string
}
 
variable "location" {
  description = "Azure region in which to deploy all resources. Example: uksouth."
  type        = string
}
 
# Optional input - sensible default provided
variable "https_only" {
  description = "When true, only HTTPS connections are accepted. Strongly recommended."
  type        = bool
  default     = true
}
 
variable "tags" {
  description = "A map of tags to assign to all resources created by this module."
  type        = map(string)
  default     = {}
}

variable "environment" {
  description = "Short environment code used in resource naming."
  type        = string
 
  validation {
    condition     = contains(["dev", "tst", "uat", "ppd", "prd"], var.environment)
    error_message = "environment must be one of: dev, tst, uat, ppd, prd."
  }
}
 
variable "min_tls_version" {
  description = "Minimum TLS version for the Logic App. Must be 1.2 or 1.3."
  type        = string
  default     = "1.2"
 
  validation {
    condition     = contains(["1.2", "1.3"], var.min_tls_version)
    error_message = "min_tls_version must be 1.2 or 1.3."
  }
}
 
variable "sku_name" {
  description = "App Service Plan SKU for the Logic App Standard."
  type        = string
 
  validation {
    condition     = can(regex("^(WS[123]|EP[123]|Y1)$", var.sku_name))
    error_message = "sku_name must be a valid Logic App SKU: WS1, WS2, WS3, EP1, EP2, EP3, or Y1."
  }
}

variable "logic_apps" {
  description = "List of Logic App Standard instances to create."
  type = list(object({
    # Required
    name                       = string
    sku_name                   = string
    storage_account_name       = string
    storage_account_access_key = string
 
    # Optional - all have defaults declared here
    enabled       = optional(bool, true)
    https_only    = optional(bool, true)
    identity_type = optional(string, "SystemAssigned")
    identity_ids  = optional(list(string), [])
    app_settings  = optional(map(string), {})
    tags          = optional(map(string), {})
 
    site_config = optional(object({
      always_on       = optional(bool, false)
      http2_enabled   = optional(bool, false)
      min_tls_version = optional(string, "1.2")
      ftps_state      = optional(string, "Disabled")
 
      ip_restriction = optional(list(object({
        name                      = string
        action                    = string
        priority                  = number
        ip_address                = optional(string)
        service_tag               = optional(string)
        virtual_network_subnet_id = optional(string)
      })), [])
    }), {})
  }))
 
  # Validate nested attributes of every element. This is what the
  # `expect_failures = [var.logic_apps]` test below asserts against.
  validation {
    condition = alltrue([
      for app in var.logic_apps : can(regex("^(WS[123]|EP[123]|Y1)$", app.sku_name))
    ])
    error_message = "Each logic_apps[*].sku_name must be a valid Logic App SKU: WS1, WS2, WS3, EP1, EP2, EP3, or Y1."
  }
}

# locals.tf (or inline in main.tf if small)
locals {
  # Convert the list to a map keyed by name - the canonical for_each input
  logic_app_map = { for app in var.logic_apps : app.name => app }
 
  # Merge module-managed labels into every resource's tags
  common_tags = merge(var.tags, {
    managed-by = "terraform"
    module     = "terraform-azurerm-logic-app"
  })
}

# ✅ Single resource of this type - use "this"
resource "azurerm_logic_app_standard" "this" { ... }
resource "azurerm_service_plan" "this" { ... }
 
# ✅ Multiple resources of the same type in the same module - qualify by role
resource "azurerm_role_assignment" "storage_contributor" { ... }
resource "azurerm_role_assignment" "keyvault_reader" { ... }
 
# ❌ Do not echo the resource type in the label
resource "azurerm_logic_app_standard" "logic_app_standard" { ... }
resource "azurerm_service_plan" "azurerm_service_plan" { ... }

# ✅ for_each - removing "app-b" does not affect "app-a" or "app-c"
resource "azurerm_logic_app_standard" "this" {
  for_each = local.logic_app_map   # map keyed by app name
 
  name                = each.key
  resource_group_name = var.rg_name
  location            = var.location
}
 
# ❌ count - removing index 1 shifts index 2 → 1, triggering a replace of app-c
resource "azurerm_logic_app_standard" "this" {
  count = length(var.logic_apps)
  name  = var.logic_apps[count.index].name
}

locals {
  logic_app_map = { for app in var.logic_apps : app.name => app }
}
 
resource "azurerm_logic_app_standard" "this" {
  for_each = local.logic_app_map
  # Reference values via each.key (name) and each.value (the full object)
}

resource "azurerm_logic_app_standard" "this" {
  # 1. Meta-arguments first, separated by a blank line from the rest
  for_each = local.logic_app_map
 
  # 2. Required arguments
  name                       = each.key
  location                   = var.location
  resource_group_name        = var.rg_name
  app_service_plan_id        = azurerm_service_plan.this[each.key].id
  storage_account_name       = each.value.storage_account_name
  storage_account_access_key = each.value.storage_account_access_key
 
  # 3. Optional arguments
  enabled    = each.value.enabled
  https_only = each.value.https_only
  tags       = each.value.tags
 
  # 4. Nested dynamic blocks
  dynamic "site_config" { ... }
  dynamic "identity" { ... }
 
  # 5. Meta-argument blocks last, separated by blank line
  lifecycle {
    ignore_changes = [app_settings["WEBSITE_RUN_FROM_PACKAGE"]]
  }
}

# ❌ Redundant - optional(bool, true) cannot be null
https_only = each.value.https_only != null ? each.value.https_only : true
 
# ✅ Direct - the default is already enforced in the variable declaration
https_only = each.value.https_only

# ✅ site_config is optional - skip the block entirely when not provided
dynamic "site_config" {
  for_each = each.value.site_config != null ? [each.value.site_config] : []
  content {
    always_on       = site_config.value.always_on
    http2_enabled   = site_config.value.http2_enabled
    min_tls_version = site_config.value.min_tls_version
    ftps_state      = site_config.value.ftps_state
 
    # Nested dynamic for a repeated sub-block
    dynamic "ip_restriction" {
      for_each = site_config.value.ip_restriction
      content {
        name                      = ip_restriction.value.name
        action                    = ip_restriction.value.action
        priority                  = ip_restriction.value.priority
        ip_address                = ip_restriction.value.ip_address
        service_tag               = ip_restriction.value.service_tag
        virtual_network_subnet_id = ip_restriction.value.virtual_network_subnet_id
      }
    }
  }
}

# ❌ Three separate dynamic blocks - verbose, harder to read, harder to extend
dynamic "identity" {
  for_each = each.value.identity_type == "SystemAssigned" ? [1] : []
  content { type = "SystemAssigned" }
}
dynamic "identity" {
  for_each = each.value.identity_type == "UserAssigned" ? [1] : []
  content {
    type         = "UserAssigned"
    identity_ids = each.value.identity_ids
  }
}
dynamic "identity" {
  for_each = each.value.identity_type == "SystemAssigned, UserAssigned" ? [1] : []
  content {
    type         = "SystemAssigned, UserAssigned"
    identity_ids = each.value.identity_ids
  }
}
 
# ✅ Single block - identity_type drives all variation
dynamic "identity" {
  for_each = each.value.identity_type != null ? [each.value.identity_type] : []
  content {
    type = identity.value
    identity_ids = contains(
      ["UserAssigned", "SystemAssigned, UserAssigned"],
      identity.value
    ) ? each.value.identity_ids : []
  }
}

# ✅ Map output preserving the for_each key structure
output "logic_app_ids" {
  description = "Map of Logic App name to resource ID."
  value       = { for k, v in azurerm_logic_app_standard.this : k => v.id }
}
 
output "logic_app_identities" {
  description = "Map of Logic App name to managed identity block (object_id, tenant_id, etc.)."
  value       = { for k, v in azurerm_logic_app_standard.this : k => v.identity }
}
 
# Credentials must be marked sensitive
output "logic_app_site_credentials" {
  description = "Map of Logic App name to site-level publishing credentials."
  sensitive   = true
  value       = { for k, v in azurerm_logic_app_standard.this : k => v.site_credential }
}

# Verify the deployed Logic App health endpoint responds
check "logic_app_healthy" {
  data "http" "health" {
    url = "https://${azurerm_logic_app_standard.this["my-app"].default_hostname}/api/health"
  }
 
  assert {
    condition     = data.http.health.status_code == 200
    error_message = "Logic App health endpoint returned ${data.http.health.status_code}, expected 200."
  }
}
 
# Warn when a certificate is within 30 days of expiry
check "cert_not_expiring" {
  assert {
    condition     = timecmp(azurerm_app_service_certificate.this.expiration_date, timeadd(timestamp(), "720h")) > 0
    error_message = "TLS certificate expires within 30 days - renew immediately."
  }
}
 
# Confirm a DNS record resolves to the expected value after provisioning
check "dns_resolves" {
  data "dns_a_record_set" "app" {
    host = "myapp.example.com"
  }
 
  assert {
    condition     = contains(data.dns_a_record_set.app.addrs, azurerm_public_ip.this.ip_address)
    error_message = "DNS A record for myapp.example.com does not resolve to ${azurerm_public_ip.this.ip_address}."
  }
}

resource "azurerm_logic_app_standard" "this" {
  for_each = local.logic_app_map
 
  lifecycle {
    precondition {
      condition     = each.value.https_only == true
      error_message = "Logic App '${each.key}' must have https_only = true in production."
    }
 
    postcondition {
      condition     = self.enabled == true
      error_message = "Logic App '${each.key}' was not enabled after creation."
    }
  }
}

# backend.tf
terraform {
  backend "azurerm" {
    resource_group_name  = "rg-tfstate-uks-prd"
    storage_account_name = "satfstateldouksprd01"
    container_name       = "tfstate"
    key                  = "myapp/prod/terraform.tfstate"
    use_azuread_auth     = true   # Prefer Entra ID auth - no storage key in CI
  }
}

tfstate/
├── platform/prod/terraform.tfstate       # Shared networking, DNS, platform RBAC
├── platform/dev/terraform.tfstate
├── myapp/prod/terraform.tfstate          # Application stack - production
├── myapp/staging/terraform.tfstate
└── myapp/dev/terraform.tfstate

terraform state list                                          # list all managed resources
terraform state show 'azurerm_logic_app_standard.this["logic-ldo-uks-prd-01"]'  # inspect one resource
terraform plan                                               # always the first diagnostic step

# moved.tf - rename a resource address without destroying it
moved {
  from = azurerm_logic_app_standard.logic_app["logic-ldo-uks-prd-01"]
  to   = azurerm_logic_app_standard.this["logic-ldo-uks-prd-01"]
}
 
# import block (Terraform 1.5+) - bring an existing resource under management
import {
  to = azurerm_logic_app_standard.this["logic-ldo-uks-prd-01"]
  id = "/subscriptions/.../resourceGroups/.../providers/Microsoft.Web/sites/logic-ldo-uks-prd-01"
}

infrastructure-stack/
├── providers.tfcomponent.hcl     # required_providers + provider config (OIDC)
├── variables.tfcomponent.hcl     # stack-level variable declarations
├── components.tfcomponent.hcl    # component blocks (each sources a module)
├── outputs.tfcomponent.hcl       # stack outputs (type is mandatory)
├── deployments.tfdeploy.hcl      # deployment blocks: production, staging, ...
└── modules/                      # the modules the components reference
    ├── networking/   # main.tf, variables.tf, outputs.tf
    └── platform/     # main.tf, variables.tf, outputs.tf

# providers.tfcomponent.hcl
required_providers {
  azurerm = {
    source  = "hashicorp/azurerm"
    version = "~> 4.0"
  }
}
 
# OIDC token is injected per-deployment (see deployments.tfdeploy.hcl) and is
# marked ephemeral so it is never written to state.
variable "identity_token" {
  type      = string
  ephemeral = true
}
variable "azure_client_id"       { type = string }
variable "azure_tenant_id"       { type = string }
variable "azure_subscription_id" { type = string }
 
provider "azurerm" "this" {
  config {
    features {}
    use_cli         = false
    use_oidc        = true
    oidc_token      = var.identity_token
    client_id       = var.azure_client_id
    tenant_id       = var.azure_tenant_id
    subscription_id = var.azure_subscription_id
  }
}

# variables.tfcomponent.hcl
variable "environment" { type = string }
variable "location"    { type = string }
variable "cidr_block"  { type = string }

# components.tfcomponent.hcl - each component sources a module and is handed the provider
component "networking" {
  source = "./modules/networking"
 
  inputs = {
    environment = var.environment
    location    = var.location
    cidr_block  = var.cidr_block
  }
 
  providers = {
    azurerm = provider.azurerm.this
  }
}

# outputs.tfcomponent.hcl - reference component outputs as component.<name>.<output> (no .outputs)
output "vnet_id" {
  type  = string
  value = component.networking.vnet_id
}
 
output "subnet_ids" {
  type  = map(string)
  value = component.networking.subnet_ids
}

# deployments.tfdeploy.hcl
identity_token "azurerm" {
  audience = ["api://AzureADTokenExchange"]
}
 
# Pull ARM_* identifiers from an HCP Terraform variable set
store "varset" "azure" {
  id       = "varset-xxxxxxxxxxxxxxxx"
  category = "env"
}
 
deployment "production" {
  inputs = {
    environment = "production"
    location    = "uksouth"
    cidr_block  = "10.0.0.0/16"
 
    # OIDC: short-lived, never persisted to state
    identity_token        = identity_token.azurerm.jwt
    azure_client_id       = store.varset.azure.ARM_CLIENT_ID
    azure_tenant_id       = store.varset.azure.ARM_TENANT_ID
    azure_subscription_id = store.varset.azure.ARM_SUBSCRIPTION_ID
  }
}
 
deployment "staging" {
  inputs = {
    environment = "staging"
    location    = "ukwest"
    cidr_block  = "10.1.0.0/16"
 
    identity_token        = identity_token.azurerm.jwt
    azure_client_id       = store.varset.azure.ARM_CLIENT_ID
    azure_tenant_id       = store.varset.azure.ARM_TENANT_ID
    azure_subscription_id = store.varset.azure.ARM_SUBSCRIPTION_ID
  }
}

# networking stack - deployments.tfdeploy.hcl: publish outputs for downstream stacks
publish_output "vnet_id" {
  value = deployment.production.vnet_id
}
 
publish_output "subnet_ids" {
  value = deployment.production.subnet_ids
}

# application stack - deployments.tfdeploy.hcl: consume the networking stack
upstream_input "networking" {
  type   = "stack"
  source = "app.terraform.io/myorg/myproject/networking"
}
 
deployment "production" {
  inputs = {
    environment = "production"
    vnet_id     = upstream_input.networking.vnet_id
    subnet_ids  = upstream_input.networking.subnet_ids
 
    identity_token        = identity_token.azurerm.jwt
    azure_client_id       = store.varset.azure.ARM_CLIENT_ID
    azure_tenant_id       = store.varset.azure.ARM_TENANT_ID
    azure_subscription_id = store.varset.azure.ARM_SUBSCRIPTION_ID
  }
}

data "terraform_remote_state" "networking" {
  backend = "remote"
  config = {
    organization = var.tfe_organization
    workspaces = {
      name = "networking-${var.environment}"
    }
  }
}
 
resource "azurerm_app_service_plan" "this" {
  name = "plan-${var.environment}"
  # ... reference the remote output
  tags = {
    networking_workspace = data.terraform_remote_state.networking.outputs.workspace_id
  }
}

# tests/defaults.tftest.hcl
 
variables {
  location = "uksouth"
  rg_name  = "rg-test"
  tags     = {}
  logic_apps = [{
    name                       = "logic-test-01"
    sku_name                   = "WS1"
    storage_account_name       = "satestldoukstst01"
    storage_account_access_key = "placeholder"
  }]
}
 
# Plan-only - no real resources created
run "defaults_are_applied" {
  command = plan
 
  assert {
    condition     = azurerm_logic_app_standard.this["logic-test-01"].https_only == true
    error_message = "https_only should default to true."
  }
 
  assert {
    condition     = azurerm_logic_app_standard.this["logic-test-01"].enabled == true
    error_message = "enabled should default to true."
  }
}
 
run "invalid_sku_rejected" {
  command = plan
 
  variables {
    logic_apps = [{
      name                       = "logic-bad-sku"
      sku_name                   = "INVALID"
      storage_account_name       = "satestldoukstst01"
      storage_account_access_key = "placeholder"
    }]
  }
 
  expect_failures = [var.logic_apps]
}

terraform test                              # Run all .tftest.hcl files
terraform test -filter=defaults_are_applied # Run one named test

// test/logic_app_test.go
package test
 
import (
    "testing"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)
 
func TestLogicAppModuleComplete(t *testing.T) {
    t.Parallel()
 
    opts := &terraform.Options{
        TerraformDir: "../examples/complete",
        Vars: map[string]interface{}{
            "location": "uksouth",
        },
    }
 
    // Always defer destroy before apply - ensures cleanup on test failure
    defer terraform.Destroy(t, opts)
    terraform.InitAndApply(t, opts)
 
    ids := terraform.OutputMap(t, opts, "logic_app_ids")
    assert.NotEmpty(t, ids, "logic_app_ids output should not be empty")
    assert.Contains(t, ids, "logic-test-complete")
}

fmt-check → validate → tflint → security-scan → test → plan → [approval gate] → apply

name: Terraform
 
on:
  push:
    branches: [main]
  pull_request:
 
permissions:
  id-token: write   # Required for OIDC
  contents: read
 
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "~1.9"
 
      - name: Format check
        run: terraform fmt -check -recursive
 
      - name: Init (no backend)
        run: terraform init -backend=false
 
      - name: Validate
        run: terraform validate
 
      - name: TFLint
        uses: terraform-linters/setup-tflint@v4
      - run: tflint --recursive
 
      - name: Trivy security scan
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: config
          scan-ref: .
 
  plan:
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
 
      - name: Azure login (OIDC - no secrets stored)
        uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}         # not a secret - store as a var
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
 
      - name: Init
        run: terraform init
 
      - name: Plan
        run: |
          terraform plan \
            -out=tfplan \
            -var-file=env/${{ github.ref == 'refs/heads/main' && 'prod' || 'dev' }}.tfvars
 
      - name: Upload plan artifact
        uses: actions/upload-artifact@v4
        with:
          name: tfplan
          path: tfplan
          retention-days: 1
 
  apply:
    needs: plan
    runs-on: ubuntu-latest
    environment: production   # Requires a manual approval gate configured in GitHub
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
 
      - name: Azure login (OIDC)
        uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
 
      - name: Init
        run: terraform init
 
      - name: Download plan artifact
        uses: actions/download-artifact@v4
        with:
          name: tfplan
 
      - name: Apply
        run: terraform apply -auto-approve tfplan

terraform-<PROVIDER>-<MODULE_NAME>

terraform-azurerm-logic-app
terraform-azurerm-key-vault
terraform-aws-s3-bucket
terraform-github-repository

brew install terraform-docs                                        # macOS
go install github.com/terraform-docs/terraform-docs@latest        # cross-platform

# .terraform-docs.yml
# https://terraform-docs.io/user-guide/configuration/
 
formatter: "markdown table"
 
# Minimum terraform-docs version required to process this config.
version: ">=0.19.0"
 
# Read the module description from the first comment block in main.tf.
# Write /**/ or # comments at the top of main.tf and they appear in the README header.
header-from: main.tf
footer-from: ""
 
recursive:
  enabled: false   # set true + path: modules to also document submodules
 
output:
  file: README.md
  mode: inject     # inject between markers, leave surrounding content untouched
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->
 
output-values:
  enabled: false   # set true + from: path/to/terraform.tfstate to show real output values
  from: ""
 
sort:
  enabled: true
  by: name         # "name" | "required" | "type"
 
settings:
  anchor: true         # generate HTML anchors for every input/output row
  color: true
  default: true        # show the default column
  description: true    # show the description column
  escape: true         # escape Markdown special characters in cells
  hide-empty: false    # show sections even when they have no entries
  html: true           # use HTML table syntax (better rendering on GitHub)
  indent: 2            # heading level for sections (## = 2)
  lockfile: true       # read .terraform.lock.hcl to populate the providers section
  read-comments: true  # read variable/output descriptions from inline source comments
  required: true       # show the required column
  sensitive: true      # show the sensitive column
  type: true           # show the type column
 
sections:
  hide: []
  show: []
  # To hide specific sections uncomment and list them:
  # hide:
  #   - modules      # hide if the module calls no child modules
  #   - resources    # hide if callers don't need to know what's provisioned

<!-- BEGIN_TF_DOCS -->
<!-- END_TF_DOCS -->

terraform-docs .          # uses .terraform-docs.yml automatically

- name: terraform-docs
  uses: terraform-docs/gh-actions@v1
  with:
    working-dir: .
    config-file: .terraform-docs.yml
    output-file: README.md
    output-method: inject
    git-push: true
    git-commit-message: "docs: regenerate README via terraform-docs"

[Your title, description, usage example - maintained by hand]

<!-- BEGIN_TF_DOCS -->
## Requirements ...  <- auto-generated by terraform-docs
## Inputs ...
## Outputs ...
<!-- END_TF_DOCS -->

# Sort, format, generate README with a header file
./Terraform-Sort.ps1 -SortVariables -SortOutputs -FormatTerraform -GenerateReadme -ReadmeHeaderFile HEADER.md
 
# Sort and format only (no README generation)
./Terraform-Sort.ps1 -SortVariables -SortOutputs -FormatTerraform
 
# Also process ./examples/module-dev before the root module
./Terraform-Sort.ps1 -SortVariables -SortOutputs -FormatTerraform -GenerateReadme -IncludeExampleDir
 
# Preview what would change without writing any files
./Terraform-Sort.ps1 -SortVariables -SortOutputs -FormatTerraform -GenerateReadme -WhatIf

#Requires -Version 7.2
# .SYNOPSIS
#     Sorts Terraform variable and output blocks, runs terraform fmt, writes a
#     custom README header, and regenerates the terraform-docs section of README.md.
#
# .DESCRIPTION
#     Designed for libre-devops Terraform module repositories. No Git operations -
#     releases are handled separately in CI. Uses a brace-depth parser that handles
#     nested object types and default maps correctly.
#
# .PARAMETER VariablesFile    Path to variables.tf (default: ./variables.tf)
# .PARAMETER OutputsFile      Path to outputs.tf   (default: ./outputs.tf)
# .PARAMETER SortVariables    Sort variable blocks alphabetically
# .PARAMETER SortOutputs      Sort output blocks alphabetically
# .PARAMETER FormatTerraform  Run terraform fmt -recursive
# .PARAMETER GenerateReadme   Regenerate terraform-docs section of README.md
# .PARAMETER ReadmeHeader     Custom markdown header written above terraform-docs output
# .PARAMETER ReadmeHeaderFile Path to a markdown file used as README header
# .PARAMETER IncludeExampleDir Also process ./examples/module-dev
#
# .EXAMPLE
#     ./Terraform-Sort.ps1 -SortVariables -SortOutputs -FormatTerraform
#
# .EXAMPLE
#     ./Terraform-Sort.ps1 -SortVariables -SortOutputs -GenerateReadme -ReadmeHeaderFile HEADER.md
 
[CmdletBinding(SupportsShouldProcess)]
param(
    [string] $VariablesFile    = './variables.tf',
    [string] $OutputsFile      = './outputs.tf',
    [string] $ReadmeHeader     = '',
    [string] $ReadmeHeaderFile = '',
 
    [switch] $SortVariables,
    [switch] $SortOutputs,
    [switch] $FormatTerraform,
    [switch] $GenerateReadme,
    [switch] $IncludeExampleDir
)
 
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
 
$script:Errors  = [System.Collections.Generic.List[string]]::new()
$script:RootDir = (Get-Location).Path
 
# ── Logging helpers ───────────────────────────────────────────────────────────
 
function Write-Step ([string]$Msg) { Write-Host "  >> $Msg"    -ForegroundColor Cyan  }
function Write-Ok   ([string]$Msg) { Write-Host "  OK  $Msg"   -ForegroundColor Green }
function Write-Fail ([string]$Msg) {
    Write-Host "  FAIL  $Msg" -ForegroundColor Red
    $script:Errors.Add($Msg)
}
 
function Assert-Tool ([string]$Name) {
    if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
        throw "$Name not found in PATH"
    }
}
 
# ── HCL block parser (brace-depth) ───────────────────────────────────────────
 
function Get-TerraformBlocks {
    # Extracts complete top-level HCL blocks using brace-depth tracking.
    # Correctly handles nested object types, default maps, and validation blocks.
    param(
        [string] $Content,
        [ValidateSet('variable','output')]
        [string] $Keyword
    )
 
    $blocks = [System.Collections.Generic.List[string]]::new()
    $lines  = $Content -split '\r?\n'
    $i      = 0
 
    while ($i -lt $lines.Count) {
        if ($lines[$i] -match "^${Keyword}\s+`"[^`"]+`"\s*\{") {
            $depth  = 0
            $buffer = [System.Text.StringBuilder]::new()
 
            while ($i -lt $lines.Count) {
                $line = $lines[$i]
                $null = $buffer.AppendLine($line)
                foreach ($ch in $line.ToCharArray()) {
                    if   ($ch -eq '{') { $depth++ }
                    elseif ($ch -eq '}') { $depth-- }
                }
                $i++
                if ($depth -eq 0) { break }
            }
 
            $blocks.Add($buffer.ToString().TrimEnd())
        }
        else { $i++ }
    }
 
    return $blocks
}
 
function Get-BlockName ([string]$Block, [string]$Keyword) {
    if ($Block -match "${Keyword}\s+`"([^`"]+)`"") { return $Matches[1] }
    return [string]::Empty
}
 
# ── Core operations ───────────────────────────────────────────────────────────
 
function Invoke-TerraformFmt {
    Assert-Tool 'terraform'
    Write-Step 'terraform fmt -recursive'
    & terraform fmt -recursive
    if ($LASTEXITCODE -ne 0) { throw "terraform fmt failed (exit $LASTEXITCODE)" }
    Write-Ok 'terraform fmt'
}
 
function Invoke-SortFile {
    param(
        [string] $FilePath,
        [ValidateSet('variable','output')]
        [string] $Keyword
    )
 
    if (-not (Test-Path $FilePath -PathType Leaf)) {
        Write-Fail "Not found: $FilePath"
        return
    }
 
    Write-Step "Sorting ${Keyword} blocks in $FilePath"
    $content = Get-Content $FilePath -Raw -Encoding UTF8
    $blocks  = Get-TerraformBlocks -Content $content -Keyword $Keyword
 
    if ($blocks.Count -eq 0) {
        Write-Fail "No ${Keyword} blocks found in $FilePath"
        return
    }
 
    $sorted = ($blocks |
        Sort-Object { Get-BlockName -Block $_ -Keyword $Keyword } |
        ForEach-Object { $_.TrimEnd() }) -join "`n`n"
 
    if ($PSCmdlet.ShouldProcess($FilePath, "Write sorted ${Keyword} blocks")) {
        Set-Content -Path $FilePath -Value ($sorted.TrimEnd() + "`n") -Encoding UTF8 -NoNewline
        Write-Ok "Sorted $($blocks.Count) ${Keyword} block(s) -> $FilePath"
    }
}
 
function Set-ReadmeHeader {
    # Writes a custom markdown header to README.md and appends the terraform-docs
    # injection markers below it. Run Invoke-ReadmeUpdate afterwards to populate
    # the section between the markers.
    #
    # Resulting README.md structure:
    #   [Your custom header - title, description, usage example, etc.]
    #
    #   <!-- BEGIN_TF_DOCS -->
    #   <!-- END_TF_DOCS -->
    #
    # terraform-docs injects Requirements/Inputs/Outputs between the markers
    # without touching the header above.
    #
    # Header: markdown content to place above the markers.
    #         Pass an empty string to write markers-only.
    param([string]$Header)
 
    Write-Step 'Writing README header'
 
    $markers = "<!-- BEGIN_TF_DOCS -->`n<!-- END_TF_DOCS -->`n"
    $body    = if ($Header.Trim()) {
        $Header.TrimEnd() + "`n`n" + $markers
    }
    else {
        $markers
    }
 
    if ($PSCmdlet.ShouldProcess('README.md', 'Write README header')) {
        Set-Content -Path 'README.md' -Value $body -Encoding UTF8 -NoNewline
        Write-Ok 'README.md header written'
    }
}
 
function Invoke-ReadmeUpdate {
    Assert-Tool 'terraform-docs'
 
    if (Test-Path '.terraform-docs.yml') {
        Write-Step 'terraform-docs . (using .terraform-docs.yml)'
        & terraform-docs .
    }
    else {
        # No config file - ensure markers exist then inject markdown table
        if (-not (Test-Path 'README.md')) {
            Set-Content 'README.md' `
                -Value "<!-- BEGIN_TF_DOCS -->`n<!-- END_TF_DOCS -->`n" `
                -Encoding UTF8 -NoNewline
        }
        Write-Step 'terraform-docs markdown table --output-mode inject'
        & terraform-docs markdown table --output-file README.md --output-mode inject .
    }
 
    if ($LASTEXITCODE -ne 0) { throw "terraform-docs failed (exit $LASTEXITCODE)" }
    Write-Ok 'README.md docs section updated'
}
 
# ── Directory processor ───────────────────────────────────────────────────────
 
function Invoke-ModuleDirectory {
    param(
        [string] $Directory,
        [string] $HeaderText = ''
    )
 
    if (-not (Test-Path $Directory -PathType Container)) {
        Write-Warning "Directory not found, skipping: $Directory"
        return
    }
 
    Write-Host "`nProcessing: $(Resolve-Path $Directory)" -ForegroundColor White
    Push-Location $Directory
    try {
        if ($FormatTerraform) {
            try   { Invoke-TerraformFmt }
            catch { Write-Fail $_.Exception.Message }
        }
 
        if ($SortVariables) {
            try   { Invoke-SortFile -FilePath './variables.tf' -Keyword 'variable' }
            catch { Write-Fail $_.Exception.Message }
        }
 
        if ($SortOutputs) {
            try   { Invoke-SortFile -FilePath './outputs.tf' -Keyword 'output' }
            catch { Write-Fail $_.Exception.Message }
        }
 
        if ($GenerateReadme) {
            # Set-ReadmeHeader writes the custom header + markers.
            # Invoke-ReadmeUpdate injects the terraform-docs content between the markers.
            if ($HeaderText) {
                try   { Set-ReadmeHeader -Header $HeaderText }
                catch { Write-Fail $_.Exception.Message }
            }
            try   { Invoke-ReadmeUpdate }
            catch { Write-Fail $_.Exception.Message }
        }
    }
    finally {
        Pop-Location
    }
}
 
# ── Resolve header ────────────────────────────────────────────────────────────
 
$resolvedHeader = ''
 
if ($ReadmeHeaderFile) {
    if (-not (Test-Path $ReadmeHeaderFile -PathType Leaf)) {
        Write-Error "ReadmeHeaderFile not found: $ReadmeHeaderFile"
        exit 1
    }
    $resolvedHeader = Get-Content $ReadmeHeaderFile -Raw -Encoding UTF8
    Write-Host "README header source: $ReadmeHeaderFile" -ForegroundColor Cyan
}
elseif ($ReadmeHeader) {
    $resolvedHeader = $ReadmeHeader
    Write-Host 'README header source: -ReadmeHeader parameter' -ForegroundColor Cyan
}
 
# ── Entry point ───────────────────────────────────────────────────────────────
 
if ($IncludeExampleDir) {
    Invoke-ModuleDirectory `
        -Directory   (Join-Path $script:RootDir 'examples/module-dev') `
        -HeaderText  $resolvedHeader
}
 
Invoke-ModuleDirectory -Directory $script:RootDir -HeaderText $resolvedHeader
 
# ── Summary ───────────────────────────────────────────────────────────────────
 
Write-Host ''
if ($script:Errors.Count -gt 0) {
    Write-Host "Completed with $($script:Errors.Count) error(s):" -ForegroundColor Red
    $script:Errors | ForEach-Object { Write-Host "  - $_" -ForegroundColor Red }
    exit 1
}
 
Write-Host 'Done.' -ForegroundColor Green

# Sort, format, generate README with a header file
./terraform-sort.sh --sort-variables --sort-outputs --format-terraform --generate-readme --readme-header-file HEADER.md
 
# Sort and format only (no README generation)
./terraform-sort.sh --sort-variables --sort-outputs --format-terraform
 
# Also process ./examples/module-dev before the root module
./terraform-sort.sh --sort-variables --sort-outputs --format-terraform --generate-readme --include-example-dir
 
# Show help
./terraform-sort.sh --help

#!/usr/bin/env bash
# terraform-sort.sh - Sort Terraform blocks, run fmt, write README header,
# regenerate terraform-docs. No git operations.
set -euo pipefail
 
# ── Defaults ──────────────────────────────────────────────────────────────────
 
VARIABLES_FILE='./variables.tf'
OUTPUTS_FILE='./outputs.tf'
README_HEADER=''
README_HEADER_FILE=''
SORT_VARIABLES=false
SORT_OUTPUTS=false
FORMAT_TERRAFORM=false
GENERATE_README=false
INCLUDE_EXAMPLE_DIR=false
 
# ── Usage ─────────────────────────────────────────────────────────────────────
 
usage() {
    cat <<EOF
Usage: $(basename "$0") [OPTIONS]
 
  --variables-file FILE     Path to variables.tf (default: $VARIABLES_FILE)
  --outputs-file FILE       Path to outputs.tf   (default: $OUTPUTS_FILE)
  --sort-variables          Sort variable blocks alphabetically
  --sort-outputs            Sort output blocks alphabetically
  --format-terraform        Run terraform fmt -recursive
  --generate-readme         Regenerate terraform-docs section of README.md
  --readme-header TEXT      Custom markdown header above terraform-docs output
  --readme-header-file FILE Path to a markdown file used as README header
  --include-example-dir     Also process ./examples/module-dev
  -h, --help                Show this help
EOF
}
 
# ── Argument parsing ──────────────────────────────────────────────────────────
 
while [[ $# -gt 0 ]]; do
    case "$1" in
        --variables-file)      VARIABLES_FILE="$2";    shift 2 ;;
        --outputs-file)        OUTPUTS_FILE="$2";      shift 2 ;;
        --sort-variables)      SORT_VARIABLES=true;    shift   ;;
        --sort-outputs)        SORT_OUTPUTS=true;      shift   ;;
        --format-terraform)    FORMAT_TERRAFORM=true;  shift   ;;
        --generate-readme)     GENERATE_README=true;   shift   ;;
        --readme-header)       README_HEADER="$2";     shift 2 ;;
        --readme-header-file)  README_HEADER_FILE="$2";shift 2 ;;
        --include-example-dir) INCLUDE_EXAMPLE_DIR=true; shift ;;
        -h|--help)             usage; exit 0 ;;
        *) printf 'Unknown option: %s\n' "$1" >&2; usage; exit 1 ;;
    esac
done
 
ROOT_DIR="$(pwd)"
ERRORS=()
 
# ── Logging ───────────────────────────────────────────────────────────────────
 
step() { printf '  \033[36m>> %s\033[0m\n' "$*";       }
ok()   { printf '  \033[32mOK  %s\033[0m\n' "$*";      }
fail() { printf '  \033[31mFAIL  %s\033[0m\n' "$*" >&2; ERRORS+=("$*"); }
 
assert_tool() {
    command -v "$1" &>/dev/null || { fail "$1 not found in PATH"; return 1; }
}
 
# ── HCL block parser (gawk brace-depth) ──────────────────────────────────────
 
sort_terraform_blocks() {
    local file="$1" keyword="$2" tmp_dir count=0
 
    [[ -f "$file" ]] || { fail "Not found: $file"; return 1; }
 
    step "Sorting ${keyword} blocks in $file"
    tmp_dir="$(mktemp -d)"
 
    # Extract each block into its own file named by block name.
    # gawk is required for the 3-argument match() form used here.
    gawk -v kw="$keyword" -v tmpdir="$tmp_dir" '
    BEGIN { in_block=0; depth=0; block=""; name="" }
 
    !in_block && match($0, "^" kw " \"([^\"]+)\" \\{", arr) {
        name = arr[1]; in_block = 1; depth = 0; block = $0 "\n"
        for (i=1; i<=length($0); i++) {
            c = substr($0,i,1)
            if (c=="{") depth++; else if (c=="}") depth--
        }
        if (depth==0) {
            sub(/\n$/,"",block); print block > (tmpdir "/" name ".tf")
            close(tmpdir "/" name ".tf"); in_block=0; block=""; name=""
        }
        next
    }
 
    in_block {
        block = block $0 "\n"
        for (i=1; i<=length($0); i++) {
            c = substr($0,i,1)
            if (c=="{") depth++; else if (c=="}") depth--
        }
        if (depth==0) {
            sub(/\n$/,"",block); print block > (tmpdir "/" name ".tf")
            close(tmpdir "/" name ".tf"); in_block=0; block=""; name=""
        }
    }
    ' "$file"
 
    # Sort by filename (block name) and join with double newlines
    local output='' first=true
    while IFS= read -r -d $'\0' bf; do
        $first && output="$(cat "$bf")" && first=false \
               || output="$output"$'\n\n'"$(cat "$bf")"
        count=$((count + 1))
    done < <(find "$tmp_dir" -name '*.tf' -print0 | sort -z)
 
    rm -rf "$tmp_dir"
 
    if [[ $count -eq 0 ]]; then
        fail "No ${keyword} blocks found in $file"; return 1
    fi
 
    printf '%s\n' "$output" > "$file"
    ok "Sorted $count ${keyword} block(s) -> $file"
}
 
# ── Core operations ───────────────────────────────────────────────────────────
 
run_terraform_fmt() {
    assert_tool terraform || return
    step 'terraform fmt -recursive'
    terraform fmt -recursive && ok 'terraform fmt' || fail 'terraform fmt failed'
}
 
set_readme_header() {
    local header="$1"
    step 'Writing README header'
    local markers=$'<!-- BEGIN_TF_DOCS -->\n<!-- END_TF_DOCS -->'
    if [[ -n "$header" ]]; then
        printf '%s\n\n%s\n' "$header" "$markers" > README.md
    else
        printf '%s\n' "$markers" > README.md
    fi
    ok 'README header written'
}
 
run_terraform_docs() {
    assert_tool terraform-docs || return
    if [[ -f '.terraform-docs.yml' ]]; then
        step 'terraform-docs . (using .terraform-docs.yml)'
        terraform-docs . && ok 'README.md docs section updated' \
                         || fail 'terraform-docs failed'
    else
        [[ -f 'README.md' ]] \
            || printf '<!-- BEGIN_TF_DOCS -->\n<!-- END_TF_DOCS -->\n' > README.md
        step 'terraform-docs markdown table --output-mode inject'
        terraform-docs markdown table \
            --output-file README.md --output-mode inject . \
            && ok 'README.md docs section updated' \
            || fail 'terraform-docs failed'
    fi
}
 
# ── Directory processor ───────────────────────────────────────────────────────
 
process_directory() {
    local dir="$1" header="$2"
    [[ -d "$dir" ]] || { printf 'WARNING: Not found, skipping: %s\n' "$dir"; return; }
 
    printf '\nProcessing: %s\n' "$(cd "$dir" && pwd)"
    pushd "$dir" > /dev/null
 
    $FORMAT_TERRAFORM  && { run_terraform_fmt || true; }
    $SORT_VARIABLES    && { sort_terraform_blocks "$VARIABLES_FILE" 'variable' || true; }
    $SORT_OUTPUTS      && { sort_terraform_blocks "$OUTPUTS_FILE"   'output'   || true; }
 
    if $GENERATE_README; then
        [[ -n "$header" ]] && { set_readme_header "$header" || true; }
        run_terraform_docs || true
    fi
 
    popd > /dev/null
}
 
# ── Resolve header ────────────────────────────────────────────────────────────
 
resolved_header=''
if [[ -n "$README_HEADER_FILE" ]]; then
    [[ -f "$README_HEADER_FILE" ]] \
        || { printf 'ERROR: --readme-header-file not found: %s\n' "$README_HEADER_FILE" >&2; exit 1; }
    resolved_header="$(cat "$README_HEADER_FILE")"
    printf 'README header source: %s\n' "$README_HEADER_FILE"
elif [[ -n "$README_HEADER" ]]; then
    resolved_header="$README_HEADER"
    printf 'README header source: --readme-header parameter\n'
fi
 
# ── Entry point ───────────────────────────────────────────────────────────────
 
$INCLUDE_EXAMPLE_DIR && process_directory "$ROOT_DIR/examples/module-dev" "$resolved_header"
process_directory "$ROOT_DIR" "$resolved_header"
 
# ── Summary ───────────────────────────────────────────────────────────────────
 
printf '\n'
if [[ ${#ERRORS[@]} -gt 0 ]]; then
    printf '\033[31mCompleted with %d error(s):\033[0m\n' "${#ERRORS[@]}" >&2
    printf '  \033[31m- %s\033[0m\n' "${ERRORS[@]}" >&2
    exit 1
fi
printf '\033[32mDone.\033[0m\n'

# Sort, format, generate README with a header file
python terraform_sort.py --sort-variables --sort-outputs --format-terraform --generate-readme --readme-header-file HEADER.md
 
# Sort and format only (no README generation)
python terraform_sort.py --sort-variables --sort-outputs --format-terraform
 
# Also process ./examples/module-dev before the root module
python terraform_sort.py --sort-variables --sort-outputs --format-terraform --generate-readme --include-example-dir
 
# Show help
python terraform_sort.py --help

#!/usr/bin/env python3
"""
terraform_sort.py
 
Sort Terraform variable/output blocks, run terraform fmt, write a custom README
header, and regenerate terraform-docs output.
 
Standard library only. Requires Python 3.12+.
"""
 
from __future__ import annotations
 
import argparse
import os
import shutil
import subprocess
import sys
import textwrap
from pathlib import Path
 
# ── Logging ───────────────────────────────────────────────────────────────────
 
def _step(msg: str) -> None:
    print(f'  \033[36m>> {msg}\033[0m', flush=True)
 
def _ok(msg: str) -> None:
    print(f'  \033[32mOK  {msg}\033[0m', flush=True)
 
def _fail(msg: str, errors: list[str]) -> None:
    print(f'  \033[31mFAIL  {msg}\033[0m', file=sys.stderr, flush=True)
    errors.append(msg)
 
# ── HCL block parser (brace-depth) ───────────────────────────────────────────
 
def extract_blocks(content: str, keyword: str) -> list[tuple[str, str]]:
    """
    Extract complete top-level HCL blocks using brace-depth tracking.
    Returns (name, block_text) tuples in source order.
    Handles nested object types, default maps, and validation blocks.
    A known limitation shared with all text-based HCL parsers: brace characters
    inside string literals are counted, which can miscount depth in pathological
    inputs. This does not affect standard Terraform variable/output definitions.
    """
    blocks: list[tuple[str, str]] = []
    lines = content.splitlines(keepends=True)
    i = 0
    prefix = f'{keyword} "'
 
    while i < len(lines):
        stripped = lines[i].lstrip()
        if stripped.startswith(prefix):
            after = stripped[len(prefix):]
            name = after[: after.index('"')]
            depth, buf = 0, []
            while i < len(lines):
                buf.append(lines[i])
                for ch in lines[i]:
                    if ch == '{':
                        depth += 1
                    elif ch == '}':
                        depth -= 1
                i += 1
                if depth == 0:
                    break
            blocks.append((name, ''.join(buf).rstrip('\n')))
        else:
            i += 1
 
    return blocks
 
# ── Core operations ───────────────────────────────────────────────────────────
 
def assert_tool(name: str) -> None:
    if not shutil.which(name):
        raise RuntimeError(f'{name} not found in PATH')
 
 
def _run(cmd: list[str], errors: list[str]) -> bool:
    rc = subprocess.run(cmd).returncode
    if rc != 0:
        errors.append(f'{" ".join(cmd)} exited {rc}')
        return False
    return True
 
 
def sort_file(path: Path, keyword: str, errors: list[str]) -> None:
    if not path.exists():
        _fail(f'Not found: {path}', errors)
        return
 
    _step(f'Sorting {keyword} blocks in {path}')
    blocks = extract_blocks(path.read_text(encoding='utf-8'), keyword)
 
    if not blocks:
        _fail(f'No {keyword} blocks found in {path}', errors)
        return
 
    sorted_blocks = sorted(blocks, key=lambda b: b[0])
    path.write_text(
        '\n\n'.join(text for _, text in sorted_blocks) + '\n',
        encoding='utf-8',
    )
    _ok(f'Sorted {len(blocks)} {keyword} block(s) -> {path}')
 
 
def run_terraform_fmt(errors: list[str]) -> None:
    try:
        assert_tool('terraform')
    except RuntimeError as exc:
        _fail(str(exc), errors)
        return
    _step('terraform fmt -recursive')
    if _run(['terraform', 'fmt', '-recursive'], errors):
        _ok('terraform fmt')
 
 
def set_readme_header(header: str, errors: list[str]) -> None:
    _step('Writing README header')
    markers = '<!-- BEGIN_TF_DOCS -->\n<!-- END_TF_DOCS -->\n'
    body = f'{header.rstrip()}\n\n{markers}' if header.strip() else markers
    try:
        Path('README.md').write_text(body, encoding='utf-8')
        _ok('README header written')
    except OSError as exc:
        _fail(str(exc), errors)
 
 
def run_terraform_docs(errors: list[str]) -> None:
    try:
        assert_tool('terraform-docs')
    except RuntimeError as exc:
        _fail(str(exc), errors)
        return
 
    if Path('.terraform-docs.yml').exists():
        _step('terraform-docs . (using .terraform-docs.yml)')
        if _run(['terraform-docs', '.'], errors):
            _ok('README.md docs section updated')
    else:
        readme = Path('README.md')
        if not readme.exists():
            readme.write_text(
                '<!-- BEGIN_TF_DOCS -->\n<!-- END_TF_DOCS -->\n',
                encoding='utf-8',
            )
        _step('terraform-docs markdown table --output-mode inject')
        if _run(
            ['terraform-docs', 'markdown', 'table',
             '--output-file', 'README.md', '--output-mode', 'inject', '.'],
            errors,
        ):
            _ok('README.md docs section updated')
 
 
def process_directory(
    directory: Path,
    header: str,
    args: argparse.Namespace,
    errors: list[str],
) -> None:
    if not directory.is_dir():
        print(f'WARNING: Not found, skipping: {directory}')
        return
 
    print(f'\nProcessing: {directory.resolve()}', flush=True)
    original = Path.cwd()
    os.chdir(directory)
    try:
        if args.format_terraform:
            run_terraform_fmt(errors)
        if args.sort_variables:
            sort_file(Path(args.variables_file), 'variable', errors)
        if args.sort_outputs:
            sort_file(Path(args.outputs_file), 'output', errors)
        if args.generate_readme:
            if header:
                set_readme_header(header, errors)
            run_terraform_docs(errors)
    finally:
        os.chdir(original)
 
# ── CLI ───────────────────────────────────────────────────────────────────────
 
def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        prog='terraform_sort.py',
        description='Sort Terraform blocks, run fmt, write README header, regenerate docs.',
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=textwrap.dedent('''\
            Examples:
              python terraform_sort.py --sort-variables --sort-outputs --format-terraform
              python terraform_sort.py --sort-variables --sort-outputs \\
                  --generate-readme --readme-header-file HEADER.md
        '''),
    )
    p.add_argument('--variables-file',    default='./variables.tf')
    p.add_argument('--outputs-file',      default='./outputs.tf')
    p.add_argument('--readme-header',     default='')
    p.add_argument('--readme-header-file',default='')
    p.add_argument('--sort-variables',    action='store_true')
    p.add_argument('--sort-outputs',      action='store_true')
    p.add_argument('--format-terraform',  action='store_true')
    p.add_argument('--generate-readme',   action='store_true')
    p.add_argument('--include-example-dir', action='store_true')
    return p
 
 
def main() -> None:
    args = build_parser().parse_args()
    errors: list[str] = []
    root = Path.cwd()
 
    header = ''
    if args.readme_header_file:
        hf = Path(args.readme_header_file)
        if not hf.is_file():
            print(f'ERROR: --readme-header-file not found: {hf}', file=sys.stderr)
            sys.exit(1)
        header = hf.read_text(encoding='utf-8')
        print(f'README header source: {hf}')
    elif args.readme_header:
        header = args.readme_header
        print('README header source: --readme-header parameter')
 
    if args.include_example_dir:
        process_directory(root / 'examples/module-dev', header, args, errors)
 
    process_directory(root, header, args, errors)
 
    print()
    if errors:
        print(f'\033[31mCompleted with {len(errors)} error(s):\033[0m', file=sys.stderr)
        for e in errors:
            print(f'  \033[31m- {e}\033[0m', file=sys.stderr)
        sys.exit(1)
 
    print('\033[32mDone.\033[0m')
 
 
if __name__ == '__main__':
    main()