Terraform Configuration Validator

A fast, cross-platform Terraform configuration validator powered by WebAssembly (WASI). Validates Terraform files and provides detailed error information in JSON format.

Features

• ✅ Validates single Terraform files or entire directories
• ✅ Detects syntax errors and duplicate resources
• ✅ Provides detailed error information (file path, line/column numbers)
• ✅ Cross-platform support via WebAssembly
• ✅ Zero native dependencies required
• ✅ Fast validation using native Go parser
• ✅ JSON output for easy integration

Installation

Via npm (Recommended)

npm install tfvalidator

Or use directly with npx (no installation needed):

npx tfvalidator ./path/to/terraform/files

From Source

git clone <repository>
cd tf-validator
./build-wasi.sh

Usage

Command Line

# Validate a single file
npx tfvalidator main.tf

# Validate a directory
npx tfvalidator ./infrastructure

# Use globally installed package
npm install -g tfvalidator
tfvalidator ./terraform

Programmatic Usage

import { validateTerraform } from 'tfvalidator';

const result = await validateTerraform('./path/to/terraform');

console.log(result);
// Output:
// {
//   "errors": [
//     {
//       "filePath": "/path/to/file.tf",
//       "lineStart": 10,
//       "lineEnd": 10,
//       "columnStart": 5,
//       "columnEnd": 10,
//       "message": "Duplicate resource found: aws_instance.example",
//       "severity": "ERROR"
//     }
//   ]
// }

Exit Codes

• 0 - Validation passed (no errors or only warnings)
• 1 - Validation failed (errors found)

Output Format

The validator outputs JSON with the following structure:

{
  "errors": [
    {
      "filePath": "string",
      "lineStart": number,
      "lineEnd": number,
      "columnStart": number,
      "columnEnd": number,
      "message": "string",
      "severity": "ERROR" | "WARNING" | "INFO"
    }
  ]
}

Error Types Detected

• Syntax Errors: Invalid HCL syntax, unclosed blocks, etc.
• Duplicate Resources: Same resource defined multiple times
• File Access Errors: Missing files, permission issues

Development

Prerequisites

• Go 1.24+ (for building WASM)
• Node.js 18+ (for running and testing)

Building

# Install Go dependencies
go mod vendor

# Build WASM binary
./build-wasi.sh

Testing

# Install npm dependencies
npm install

# Run tests
npm test

Project Structure

.
├── main.go           # Go source code
├── cli.js            # Node.js CLI wrapper
├── index.js          # Programmatic API
├── tfvalidator.wasm  # Compiled WASM binary
├── build-wasi.sh     # Build script
└── test/             # Test files
    ├── test.js       # Test suite
    └── fixtures/     # Test Terraform files

How It Works

1. Written in Go using HashiCorp's HCL parser
2. Compiled to WebAssembly using GOOS=wasip1
3. Runs via Node.js's built-in WASI support
4. Works on any platform with Node.js (Linux, macOS, Windows, etc.)

Technical Details

• Language: Go
• Parser: HashiCorp HCL v2
• Runtime: WebAssembly System Interface (WASI)
• Binary Size: ~8MB (compressed ~2MB)
• Node.js Version: >=18.0.0 (WASI support required)

License

Apache-2.0

Contributing

Contributions welcome! Please ensure:

• Go dependencies are up to date
• Tests pass (npm test)
• Code follows existing patterns