react-hcl 0.1.0

package/README.md

@@ -0,0 +1,266 @@
+# react-hcl
+
+A transpiler that converts TSX into Terraform `.tf` files. Write Terraform configurations using JSX/TSX syntax with a custom JSX runtime (no React dependency).
+
+## Why React for IaC?
+
+This project starts from a readability problem in IaC.
+In HCL, reference direction and state flow are hard to constrain at the notation level, so causality tends to spread across the config.
+That makes end-to-end reasoning from input to output expensive.
+We use React because component boundaries and data flow provide structure for understanding first.
+The goal is not to rewrite Terraform in JS, but to structurally improve IaC comprehensibility.
+
+## Usage
+
+Use the CLI to print Terraform to stdout or write it to a file.
+
+```bash
+react-hcl infra.tsx                  # output to stdout
+react-hcl infra.tsx -o ./tf/main.tf   # write to file
+```
+
+## Example
+
+`main.tsx` — A VPC with a web server, using a verified module and a custom component:
+
+```tsx
+import { DataSource, Module, Output, Provider, raw, useRef } from "react-hcl";
+import { WebServer } from "./web-server";
+
+function Main({ region, instanceType }) {
+  const azRef = useRef();
+  const vpcRef = useRef();
+
+  return (
+    <>
+      <Provider type="aws" region={region} />
+      <DataSource type="aws_availability_zones" name="available" ref={azRef} />
+
+      <Module
+        name="vpc"
+        ref={vpcRef}
+        source="terraform-aws-modules/vpc/aws"
+        cidr="10.0.0.0/16"
+        azs={raw(`${azRef.names}`)}
+        public_subnets={["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]}
+        enable_dns_hostnames={true}
+      />
+
+      <WebServer
+        vpcId={vpcRef.vpc_id}
+        subnetId={raw(`${vpcRef.public_subnets}[0]`)}
+        instanceType={instanceType}
+      />
+
+      <Output name="vpc_id" value={vpcRef.vpc_id} />
+    </>
+  );
+}
+
+export default <Main region="us-east-1" instanceType="t3.micro" />;
+```
+
+`web-server.tsx`
+
+Component implementation for AMI lookup, security group rules, and EC2 instance creation.
+
+```tsx
+import { DataSource, Resource, useRef } from "react-hcl";
+
+export function WebServer({ vpcId, subnetId, instanceType }) {
+  const amiRef = useRef();
+  const sgRef = useRef();
+
+  return (
+    <>
+      <DataSource
+        type="aws_ami"
+        name="ubuntu"
+        ref={amiRef}
+        most_recent={true}
+        owners={["099720109477"]}
+        filter={[
+          { name: "name", values: ["ubuntu/images/hvm-ssd/ubuntu-*-amd64-server-*"] },
+        ]}
+      />
+      <Resource
+        type="aws_security_group"
+        name="web"
+        ref={sgRef}
+        vpc_id={vpcId}
+      />
+      <Resource
+        type="aws_vpc_security_group_ingress_rule"
+        name="web_http"
+        security_group_id={sgRef.id}
+        from_port={80}
+        to_port={80}
+        ip_protocol="tcp"
+        cidr_ipv4="0.0.0.0/0"
+      />
+      <Resource
+        type="aws_vpc_security_group_egress_rule"
+        name="web_all"
+        security_group_id={sgRef.id}
+        ip_protocol="-1"
+        cidr_ipv4="0.0.0.0/0"
+      />
+      <Resource
+        type="aws_instance"
+        name="web"
+        ami={amiRef.id}
+        instance_type={instanceType}
+        subnet_id={subnetId}
+        vpc_security_group_ids={[sgRef.id]}
+      />
+    </>
+  );
+}
+```
+
+Run the transpiler for `main.tsx`:
+
+```bash
+$ react-hcl main.tsx
+```
+
+<details>
+<summary>Generated <code>.tf</code> — refs resolve to Terraform references, component boundaries dissolve into a flat file</summary>
+
+Generated Terraform output:
+
+```hcl
+provider "aws" {
+  region = "us-east-1"
+}
+
+data "aws_availability_zones" "available" {
+}
+
+module "vpc" {
+  source               = "terraform-aws-modules/vpc/aws"
+  cidr                 = "10.0.0.0/16"
+  azs                  = data.aws_availability_zones.available.names
+  public_subnets       = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
+  enable_dns_hostnames = true
+}
+
+data "aws_ami" "ubuntu" {
+  most_recent = true
+  owners      = ["099720109477"]
+
+  filter {
+    name   = "name"
+    values = ["ubuntu/images/hvm-ssd/ubuntu-*-amd64-server-*"]
+  }
+}
+
+resource "aws_security_group" "web" {
+  vpc_id = module.vpc.vpc_id
+}
+
+resource "aws_vpc_security_group_ingress_rule" "web_http" {
+  security_group_id = aws_security_group.web.id
+  from_port         = 80
+  to_port           = 80
+  ip_protocol       = "tcp"
+  cidr_ipv4         = "0.0.0.0/0"
+}
+
+resource "aws_vpc_security_group_egress_rule" "web_all" {
+  security_group_id = aws_security_group.web.id
+  ip_protocol       = "-1"
+  cidr_ipv4         = "0.0.0.0/0"
+}
+
+resource "aws_instance" "web" {
+  ami                    = data.aws_ami.ubuntu.id
+  instance_type          = "t3.micro"
+  subnet_id              = module.vpc.public_subnets[0]
+  vpc_security_group_ids = [aws_security_group.web.id]
+}
+
+output "vpc_id" {
+  value = module.vpc.vpc_id
+}
+```
+
+</details>
+
+See [`samples/`](samples/) for more examples including ECS Fargate and S3+CloudFront.
+
+## Components
+
+| Component | HCL block |
+|---|---|
+| `<Resource>` | `resource "type" "name" { ... }` |
+| `<DataSource>` | `data "type" "name" { ... }` |
+| `<Variable>` | `variable "name" { ... }` |
+| `<Output>` | `output "name" { ... }` |
+| `<Locals>` | `locals { ... }` |
+| `<Provider>` | `provider "type" { ... }` |
+| `<Terraform>` | `terraform { ... }` |
+
+## Hooks & Helpers
+
+- `useRef()` - Create a reference to a resource/data source (`ref.id`, `ref.arn`, etc.)
+- `tf.var("name")` - Reference a variable (`var.name`)
+- `tf.local("name")` - Reference a local value (`local.name`)
+
+## Installation
+
+### From npm
+
+Install the published CLI globally from npm.
+
+```bash
+npm install -g react-hcl
+```
+
+### Manual install from source
+
+Clone, build, and link the CLI from source.
+
+```bash
+git clone https://github.com/jugyo/react-hcl.git
+cd react-hcl
+bun install
+bun run build
+npm link
+```
+
+After this, the `react-hcl` command is available globally.
+
+## Development
+
+Set up a local development environment.
+
+```bash
+git clone https://github.com/jugyo/react-hcl.git
+cd react-hcl
+bun install
+```
+
+Run the CLI directly without building.
+
+```bash
+bun src/cli.ts infra.tsx
+bun src/cli.ts infra.tsx -o ./tf/main.tf
+```
+
+Run the test suite.
+
+```bash
+bun test
+```
+
+Build distributable output.
+
+```bash
+bun run build
+```
+
+## Documentation
+
+- [Design Document](docs/design-doc.md)
+- [Implementation Plan](docs/plan.md)

package/dist/blocks.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Intermediate representation (IR) types for HCL blocks.
+ *
+ * These types serve as the bridge between JSX component evaluation and HCL code generation.
+ * The JSX components (Resource, Data, Variable, etc.) produce Block objects,
+ * and the generator (generator.ts) consumes them to emit valid HCL/Terraform source code.
+ *
+ * Each block type corresponds to a top-level Terraform construct and carries:
+ *   - `blockType`: discriminant tag for the union type (used in switch/case dispatch)
+ *   - `attributes`: key-value pairs serialized into the block body via serializeHCLAttributes()
+ *   - `innerText` (optional): pre-formatted HCL string that replaces attribute serialization.
+ *     When present, the generator outputs innerText as-is instead of serializing attributes.
+ *     This is used for cases where children provide raw HCL content.
+ *     With 2-pass rendering, template literals in children are resolved automatically.
+ *
+ * Supported HCL output forms:
+ *   resource "type" "name" { ... }   — ResourceBlock
+ *   data "type" "name" { ... }       — DataSourceBlock
+ *   variable "name" { ... }          — VariableBlock
+ *   output "name" { ... }            — OutputBlock
+ *   locals { ... }                   — LocalsBlock (no name label)
+ *   provider "type" { ... }          — ProviderBlock
+ *   terraform { ... }                — TerraformBlock (no name label)
+ *   module "name" { ... }            — ModuleBlock
+ */
+/**
+ * Represents a Terraform resource block.
+ * Output: resource "<type>" "<name>" { <attributes> }
+ *
+ * Example:
+ *   { blockType: "resource", type: "aws_vpc", name: "main", attributes: { cidr_block: "10.0.0.0/16" } }
+ *   → resource "aws_vpc" "main" { cidr_block = "10.0.0.0/16" }
+ */
+export type ResourceBlock = {
+    blockType: "resource";
+    type: string;
+    name: string;
+    attributes: Record<string, any>;
+    innerText?: string;
+};
+/**
+ * Represents a Terraform data source block.
+ * Output: data "<type>" "<name>" { <attributes> }
+ *
+ * Example:
+ *   { blockType: "data", type: "aws_ami", name: "latest", attributes: { most_recent: true } }
+ *   → data "aws_ami" "latest" { most_recent = true }
+ */
+export type DataSourceBlock = {
+    blockType: "data";
+    type: string;
+    name: string;
+    attributes: Record<string, any>;
+    innerText?: string;
+};
+/**
+ * Represents a Terraform variable block.
+ * Output: variable "<name>" { <attributes> }
+ * Attributes typically include: type, default, description, validation, sensitive, nullable
+ */
+export type VariableBlock = {
+    blockType: "variable";
+    name: string;
+    attributes: Record<string, any>;
+};
+/**
+ * Represents a Terraform output block.
+ * Output: output "<name>" { <attributes> }
+ * Attributes typically include: value, description, sensitive
+ */
+export type OutputBlock = {
+    blockType: "output";
+    name: string;
+    attributes: Record<string, any>;
+};
+/**
+ * Represents a Terraform locals block.
+ * Output: locals { <attributes> }
+ * Unlike most blocks, locals has no name label — there is only one locals block per scope.
+ */
+export type LocalsBlock = {
+    blockType: "locals";
+    attributes: Record<string, any>;
+};
+/**
+ * Represents a Terraform provider block.
+ * Output: provider "<type>" { <attributes> }
+ * Attributes typically include: region, access_key, alias, etc.
+ */
+export type ProviderBlock = {
+    blockType: "provider";
+    type: string;
+    attributes: Record<string, any>;
+};
+/**
+ * Represents the top-level terraform {} configuration block.
+ * Output: terraform { <attributes> }
+ * Typically contains: required_version, required_providers, backend config.
+ * Uses innerText for nested blocks like `backend "s3" { ... }` that need raw HCL.
+ */
+export type TerraformBlock = {
+    blockType: "terraform";
+    attributes: Record<string, any>;
+    innerText?: string;
+};
+/**
+ * Represents a Terraform module block.
+ * Output: module "<name>" { <attributes> }
+ *
+ * Example:
+ *   { blockType: "module", name: "vpc", attributes: { source: "terraform-aws-modules/vpc/aws", cidr: "10.0.0.0/16" } }
+ *   → module "vpc" { source = "terraform-aws-modules/vpc/aws" cidr = "10.0.0.0/16" }
+ */
+export type ModuleBlock = {
+    blockType: "module";
+    name: string;
+    attributes: Record<string, any>;
+    innerText?: string;
+};
+/**
+ * Union type of all supported HCL block types.
+ * Used as the input to the generate() function in generator.ts.
+ * The `blockType` field acts as a discriminated union tag.
+ */
+export type Block = ResourceBlock | DataSourceBlock | VariableBlock | OutputBlock | LocalsBlock | ProviderBlock | TerraformBlock | ModuleBlock;

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CLI entry point for react-hcl.
+ *
+ * Usage: bun src/cli.ts <input.tsx> [-o <file>]
+ *
+ * Pipeline:
+ *   1. Takes a user-authored .tsx file as input
+ *   2. Transpiles and bundles it with esbuild (JSX → custom runtime calls)
+ *   3. Writes the bundled ESM code to a temp file and dynamically imports it
+ *   4. render() evaluates the JSXElement tree into Block[] IR
+ *   5. generate() converts Block[] into HCL string
+ *   6. Outputs to stdout, or writes to a file if -o / --output is given
+ *
+ * esbuild configuration:
+ *   - jsx: "automatic" — uses the new JSX transform (no manual import needed)
+ *   - jsxImportSource: "react-hcl" — resolves jsx/jsxs from our custom runtime
+ *   - alias: maps "react-hcl" and "react-hcl/jsx-runtime" to local source
+ *   - format: "esm" — output as ES modules for dynamic import() compatibility
+ *   - bundle: true — inline all imports so the temp file is self-contained
+ *   - write: false — keep output in memory (outputFiles) instead of writing to disk
+ */
+export {};