feat: implement terraform extractor

[chrislyons-dev]

🎯 Objective

Create a Terraform extractor (basic-terraform) that enables Archlette to analyze Terraform/OpenTofu
infrastructure-as-code, extracting resources, modules, and dependencies to map infrastructure architecture.

📋 Architecture Overview

The Terraform extractor will follow the same modular structure as basic-node:

src/extractors/builtin/basic-terraform/
├── index.ts # Entry point (orchestrator)
├── types.ts # Terraform-specific extraction types
├── file-finder.ts # Find .tf files with glob patterns
├── file-parser.ts # Parse HCL files → FileExtraction[]
├── component-detector.ts # Extract @component from comments/tags
├── resource-extractor.ts # Extract resources, data sources
├── module-extractor.ts # Extract module blocks and dependencies
├── variable-extractor.ts # Extract variables, locals, outputs
├── provider-extractor.ts # Extract provider configurations
├── doc-extractor.ts # Extract documentation comments
└── to-ir-mapper.ts # Map FileExtraction[] → ArchletteIR

🔧 Technology Approach

Recommended: HCL2 Parser (hcl-parser)

• Native HCL parsing via @evops/hcl-parser or hcl2-parser
• Accurate AST with full Terraform syntax support
• Handles expressions, functions, interpolations

Alternative: Terraform JSON output

• Use terraform show -json for parsed configuration
• Trade-off: Requires Terraform installed, slower
• Benefit: Guaranteed accuracy for complex expressions

📝 Implementation Tasks

Phase 1: Setup & Scaffolding

• Create src/extractors/builtin/basic-terraform/ directory structure
• Create types.ts with Terraform-specific types (resources, modules, blocks)
• Create entry point basic-terraform.ts and basic-terraform/index.ts
• Create file-finder.ts with Terraform file patterns (**/*.tf, exclude .terraform/)

Phase 2: HCL Parser Integration

• Integrate HCL2 parser library
• Create file-parser.ts to parse .tf files to AST
• Extract blocks: resource, data, module, variable, output, locals
• Implement error handling (syntax errors, invalid HCL)
• Support .tfvars file parsing

Phase 3: Component & Documentation

• Create component-detector.ts to parse comment tags
  • # @component ComponentName
  • # @actor Name {Person|System} {in|out|both} description
  • # @uses TargetComponent description
• Create doc-extractor.ts supporting Terraform documentation patterns:
  • Block-level comments (above resource/module)
  • Inline comments (within blocks)
  • Description fields in variables/outputs

Phase 4: Infrastructure Extraction

• Create resource-extractor.ts
  • Resources with provider and type (aws_s3_bucket)
  • Resource attributes and dependencies
  • Count/for_each meta-arguments
  • Lifecycle blocks
• Create module-extractor.ts
  • Module source (local, registry, git)
  • Module inputs (variables passed)
  • Module version constraints
  • Module dependencies (depends_on)
• Create variable-extractor.ts
  • Input variables with types and defaults
  • Local values (computed)
  • Output values with descriptions
• Create provider-extractor.ts
  • Provider configurations
  • Provider aliases
  • Required providers block

Phase 5: IR Mapping

• Create to-ir-mapper.ts
• Map components from @component tags and modules
• Map actors from @actor tags
• Map relationships from module dependencies and resource references
• Map code items from resources and variables
• Handle Terraform-specific structures (workspaces, backends)

Phase 6: Testing

• Create test fixtures in test/extractors/builtin/basic-terraform/fixtures/
  • Simple resources (AWS, Azure, GCP)
  • Module definitions and calls
  • Complex expressions (for_each, dynamic blocks)
  • Data sources and dependencies
  • Component annotations
• Create test suites:
  • resource-extraction.test.ts
  • module-extraction.test.ts
  • variable-extraction.test.ts
  • provider-extraction.test.ts
  • component-detection.test.ts
  • dependency-resolution.test.ts
  • integration.test.ts
• Achieve 90%+ test coverage
• Test against real Terraform modules (e.g., AWS VPC module)

Phase 7: Documentation & Polish

• Update README.md with Terraform extractor documentation
• Add Terraform annotation examples
• Document supported Terraform versions (0.13+)
• Create configuration example in aac.yaml
• Add comprehensive error messages
  • Invalid HCL syntax
  • Missing required attributes
  • Circular module dependencies
• Performance optimization (parallel file parsing)

🎯 Terraform-Specific Features

Feature	Implementation Notes
Resources	Extract type, provider, name, attributes
Modules	Track source, version, inputs, outputs
Data sources	External data dependencies
Variables	Input variables with types and constraints
Outputs	Module outputs and descriptions
Dependencies	Implicit (references) and explicit (depends_on)
Expressions	Interpolations, functions, conditionals

✅ Success Criteria

• Extracts resources, modules, variables, outputs, providers
• Parses HCL2 syntax including complex expressions
• Detects @component, @actor, @uses annotations in comments
• Handles module dependencies (local and remote)
• Maps to ArchletteIR compatible with existing pipeline
• 90%+ test coverage
• Works with Terraform 0.13+ / OpenTofu codebases
• Fully documented with examples

📦 Configuration Example

extractors:
  - use: builtin/basic-terraform
    inputs:
      include: ['infrastructure/**/*.tf', 'modules/**/*.tf']
      exclude: ['**/.terraform/**', '**/*.tfstate']

🔗 Related

- Mirrors basic-node extractor architecture
- Supports JSDoc-style annotations in HCL comments
- Integrates with existing Structurizr DSL generation pipeline
- Maps infrastructure components to architectural views

📚 References

- HCL2 specification: https://github.com/hashicorp/hcl
- Terraform configuration syntax: https://www.terraform.io/language/syntax/configuration
- Terraform module structure: https://www.terraform.io/language/modules/develop
- OpenTofu compatibility: https://opentofu.org/docs/