@c0x12c/ai-toolkit 1.15.0

package/rules/infrastructure/NAMING.md

@@ -0,0 +1,196 @@
+---
+paths:
+  - "**/*.tf"
+  - "**/*.hcl"
+  - "**/*.tfvars"
+---
+# Resource and File Naming Conventions
+
+## File Naming
+
+All Terraform files use `snake_case.tf`. Module call files may use the service/resource name.
+
+```
+# CORRECT
+variables.tf
+locals.tf
+outputs.tf
+provider.tf
+ecr.tf
+rds.tf
+service_api.tf
+
+# WRONG
+Variables.tf
+my-locals.tf
+serviceApi.tf
+```
+
+---
+
+## Variable Naming
+
+Variables use `snake_case` with descriptive prefixes matching the resource type.
+
+### WRONG -- Inconsistent or vague names
+
+```hcl
+variable "class" {
+  type = string
+}
+
+variable "dbSubnets" {
+  type = list(string)
+}
+
+variable "size" {
+  type = string
+}
+```
+
+### CORRECT -- Descriptive snake_case with resource prefix
+
+```hcl
+variable "rds_instance_class" {
+  description = "RDS instance class"
+  type        = string
+  default     = "db.t3.micro"
+}
+
+variable "private_subnet_ids" {
+  description = "Private subnet IDs for data stores"
+  type        = list(string)
+}
+
+variable "redis_node_type" {
+  description = "ElastiCache node type"
+  type        = string
+  default     = "cache.t3.micro"
+}
+```
+
+---
+
+## Resource Naming Patterns
+
+| Resource | Pattern | Example |
+|----------|---------|---------|
+| ECR repository | `{service}`, `{service}-worker` | `payment-api`, `payment-api-worker` |
+| RDS identifier | `{service}-{random}` | `payment-api-abc123` |
+| RDS database name | `{service_name}` (underscores) | `payment_api` |
+| RDS username | `{service_name}` (underscores) | `payment_api` |
+| S3 bucket | `{project}-{service}-{env}` | `myproject-payment-api-dev` |
+| K8s namespace | `{service}` | `payment-api` |
+| K8s service account | `{service}` | `payment-api` |
+| SQS queue | `{service}-{queue_type}-{env}` | `payment-api-durable-job-dev` |
+| Security group | `{service}-{purpose}-{env}` | `payment-api-redis-dev` |
+| IAM role (IRSA) | `{service}-{env}-irsa` | `payment-api-dev-irsa` |
+| S3 state bucket | `{project}-{region_short}-tf-{env}` | `myproject-uswest2-tf-dev` |
+
+### WRONG -- Inconsistent naming
+
+```hcl
+module "ecr" {
+  name = "MyServiceAPI"  # PascalCase
+}
+
+module "rds" {
+  identifier    = "prod_database"  # Underscores in identifier
+  database_name = "prod-db"        # Hyphens in database name
+}
+
+resource "aws_sqs_queue" "jobs" {
+  name = "jobs"  # No service or env context
+}
+```
+
+### CORRECT -- Consistent naming with context
+
+```hcl
+module "ecr" {
+  name = var.service_name  # "payment-api"
+}
+
+module "rds" {
+  identifier    = "${var.service_name}-${random_id.rds.hex}"  # "payment-api-abc123"
+  database_name = replace(var.service_name, "-", "_")          # "payment_api"
+  username      = replace(var.service_name, "-", "_")          # "payment_api"
+}
+
+resource "aws_sqs_queue" "durable_job" {
+  name = "${var.service_name}-durable-job-${var.environment}"  # "payment-api-durable-job-dev"
+}
+```
+
+---
+
+## Tagging Strategy
+
+Use provider-level `default_tags` instead of per-resource tags. Tags apply automatically to all AWS resources.
+
+### WRONG -- Per-resource tags
+
+```hcl
+resource "aws_s3_bucket" "assets" {
+  bucket = "{project}-assets-dev"
+  tags = {
+    ManagedBy   = "Terraform"
+    Environment = "dev"
+    Service     = "payment-api"
+  }
+}
+
+resource "aws_sqs_queue" "jobs" {
+  name = "payment-api-jobs-dev"
+  tags = {
+    ManagedBy   = "Terraform"
+    Environment = "dev"
+    Service     = "payment-api"
+  }
+}
+```
+
+### CORRECT -- Provider default_tags
+
+```hcl
+# provider.tf
+provider "aws" {
+  region = var.aws_region
+
+  default_tags {
+    tags = {
+      ManagedBy       = "Terraform"
+      Service         = var.service_name
+      Environment     = var.environment
+      TerraformSource = "${var.service_name}/terraform/live"
+    }
+  }
+}
+
+# Resources inherit tags automatically -- no per-resource tags needed
+resource "aws_s3_bucket" "assets" {
+  bucket = "${var.project}-assets-${var.environment}"
+}
+
+resource "aws_sqs_queue" "jobs" {
+  name = "${var.service_name}-jobs-${var.environment}"
+}
+```
+
+---
+
+## Quick Reference
+
+| Aspect | Rule |
+|--------|------|
+| File names | `snake_case.tf` |
+| Variables | `snake_case` with resource prefix (`rds_instance_class`) |
+| ECR | `{service}` or `{service}-{role}` |
+| RDS identifier | `{service}-{random}` (hyphens) |
+| RDS database/user | `{service_name}` (underscores) |
+| S3 buckets | `{project}-{service}-{env}` |
+| SQS queues | `{service}-{queue_type}-{env}` |
+| IAM roles | `{service}-{env}-irsa` |
+| State buckets | `{project}-{region_short}-tf-{env}` |
+| Tags | Provider `default_tags`, never per-resource |
+| K8s resources | `{service}` for namespace and service account |

package/rules/infrastructure/PROVIDERS.md

@@ -0,0 +1,309 @@
+---
+paths:
+  - "**/*.tf"
+  - "**/*.hcl"
+  - "**/*.tfvars"
+---
+# Provider Configuration
+
+## Providers Only in Live Layer
+
+Providers are declared ONLY in the `live/` layer. Modules inherit providers from the caller. Never declare providers inside modules.
+
+### WRONG -- Provider in module
+
+```hcl
+# modules/{service}/rds.tf
+provider "aws" {
+  region = "us-west-2"  # Provider inside a module
+}
+
+module "rds" {
+  source  = "c0x12c/rds/aws"
+  version = "~> 0.6.6"
+}
+```
+
+### CORRECT -- Provider in live layer only
+
+```hcl
+# live/provider.tf
+provider "aws" {
+  region = module.config_aws.region
+
+  default_tags {
+    tags = module.config_aws.default_tags
+  }
+}
+
+# modules/{service}/rds.tf -- no provider block, inherits from caller
+module "rds" {
+  source  = "c0x12c/rds/aws"
+  version = "~> 0.6.6"
+}
+```
+
+---
+
+## AWS Provider with Default Tags
+
+Always configure `default_tags` on the AWS provider. Tags apply automatically to all resources.
+
+### WRONG -- No default tags
+
+```hcl
+provider "aws" {
+  region = "us-west-2"
+  # No default_tags -- every resource needs manual tags
+}
+```
+
+### CORRECT -- Default tags from config module
+
+```hcl
+provider "aws" {
+  region = module.config_aws.region
+
+  default_tags {
+    tags = {
+      ManagedBy       = "Terraform"
+      Service         = var.service_name
+      Environment     = var.environment
+      TerraformSource = "${var.service_name}/terraform/live"
+    }
+  }
+}
+```
+
+---
+
+## Provider Aliases for Multi-Region
+
+Use aliases when resources must exist in a different region (e.g., ACM certificates in `us-east-1` for CloudFront).
+
+```hcl
+# live/provider.tf
+provider "aws" {
+  region = module.config_aws.region
+
+  default_tags {
+    tags = module.config_aws.default_tags
+  }
+}
+
+provider "aws" {
+  alias  = "global"
+  region = "us-east-1"
+
+  default_tags {
+    tags = module.config_aws.default_tags
+  }
+}
+```
+
+```hcl
+# Usage in resources
+resource "aws_acm_certificate" "cdn" {
+  provider          = aws.global
+  domain_name       = var.domain_name
+  validation_method = "DNS"
+}
+```
+
+---
+
+## GitHub Provider with App Auth
+
+Use GitHub App authentication with the `owner` field. Missing `owner` with App auth causes 403 errors on `/user` endpoint.
+
+### WRONG -- Missing owner with App auth
+
+```hcl
+provider "github" {
+  # No owner field -- causes 403 on /user endpoint
+  app_auth {
+    id              = var.github_app_id
+    pem_file        = var.github_app_pem_file
+    installation_id = var.github_app_installation_id
+  }
+}
+```
+
+### WRONG -- PAT-based authentication
+
+```hcl
+provider "github" {
+  token = var.github_token  # Personal Access Token -- security risk
+}
+```
+
+### CORRECT -- App auth with owner
+
+```hcl
+provider "github" {
+  owner = module.config_github.organization
+
+  app_auth {
+    id              = module.config_github.app_id
+    pem_file        = module.config_github.pem_file
+    installation_id = module.config_github.app_installation_id
+  }
+}
+```
+
+---
+
+## Kubernetes and Helm Providers
+
+Kubernetes and Helm providers depend on EKS cluster outputs. Configure them after the EKS module.
+
+```hcl
+# live/provider.tf
+data "aws_eks_cluster_auth" "cluster" {
+  name = module.eks.cluster_name
+}
+
+provider "kubernetes" {
+  host                   = module.eks.cluster_endpoint
+  token                  = data.aws_eks_cluster_auth.cluster.token
+  cluster_ca_certificate = base64decode(module.eks.cluster_certificate_authority_data)
+}
+
+provider "helm" {
+  kubernetes {
+    host                   = module.eks.cluster_endpoint
+    token                  = data.aws_eks_cluster_auth.cluster.token
+    cluster_ca_certificate = base64decode(module.eks.cluster_certificate_authority_data)
+  }
+}
+```
+
+---
+
+## Version Constraints
+
+Always specify `required_version` for Terraform and version constraints for all providers.
+
+### WRONG -- No version constraints
+
+```hcl
+terraform {
+  # No required_version -- any Terraform version accepted
+  required_providers {
+    aws = {
+      source = "hashicorp/aws"
+      # No version -- pulls latest, unpredictable
+    }
+  }
+}
+```
+
+### CORRECT -- Explicit version constraints
+
+```hcl
+terraform {
+  required_version = ">= 1.11"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+    github = {
+      source  = "integrations/github"
+      version = "~> 6.0"
+    }
+    kubernetes = {
+      source  = "hashicorp/kubernetes"
+      version = "~> 2.20"
+    }
+    helm = {
+      source  = "hashicorp/helm"
+      version = "~> 2.10"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "~> 3.5"
+    }
+  }
+}
+```
+
+---
+
+## Complete Provider File Example
+
+```hcl
+# live/provider.tf
+
+provider "aws" {
+  region = module.config_aws.region
+
+  default_tags {
+    tags = {
+      ManagedBy       = "Terraform"
+      Service         = var.service_name
+      Environment     = var.environment
+      TerraformSource = "${var.service_name}/terraform/live"
+    }
+  }
+}
+
+provider "aws" {
+  alias  = "global"
+  region = "us-east-1"
+
+  default_tags {
+    tags = {
+      ManagedBy       = "Terraform"
+      Service         = var.service_name
+      Environment     = var.environment
+      TerraformSource = "${var.service_name}/terraform/live"
+    }
+  }
+}
+
+provider "github" {
+  owner = module.config_github.organization
+
+  app_auth {
+    id              = module.config_github.app_id
+    pem_file        = module.config_github.pem_file
+    installation_id = module.config_github.app_installation_id
+  }
+}
+
+data "aws_eks_cluster_auth" "cluster" {
+  name = module.eks.cluster_name
+}
+
+provider "kubernetes" {
+  host                   = module.eks.cluster_endpoint
+  token                  = data.aws_eks_cluster_auth.cluster.token
+  cluster_ca_certificate = base64decode(module.eks.cluster_certificate_authority_data)
+}
+
+provider "helm" {
+  kubernetes {
+    host                   = module.eks.cluster_endpoint
+    token                  = data.aws_eks_cluster_auth.cluster.token
+    cluster_ca_certificate = base64decode(module.eks.cluster_certificate_authority_data)
+  }
+}
+```
+
+---
+
+## Quick Reference
+
+| Aspect | Rule |
+|--------|------|
+| Provider location | Only in `live/` layer, never in modules |
+| AWS default_tags | Always configured, applied to all resources |
+| Multi-region | Use `alias = "global"` for us-east-1 resources |
+| GitHub auth | App auth with `owner` field, never PATs |
+| GitHub owner | REQUIRED with App auth (403 without it) |
+| Kubernetes/Helm | Configured from EKS module outputs |
+| required_version | Always set (e.g., `>= 1.11`) |
+| Provider versions | Pessimistic pinning (`~> X.Y`) on all providers |
+| Module providers | Modules inherit, never declare their own |