> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Compilation

> How ubx compiles .iac files to Pulumi TypeScript.

ubx is a compiler. Your `.iac` files go through a multi-stage pipeline before Pulumi ever runs.

## Pipeline Stages

### Stage 1 — Lexer

Tokenizes the `.iac` source into keywords, identifiers, strings, numbers, and punctuation. Recognises ubx-specific tokens: `~` (pending sigil), block keywords (`unit`, `component`, `deploy`, `sync`, `input`, `output`, `local`, `data`, `extend`, `import`, `moved`, `policy`, `remote`, `interface`, `workspace`, `test`, `provider`).

### Stage 2 — Parser

Builds a typed Abstract Syntax Tree (AST). Each block type has its own AST node:

* `UnitBlock` — `unit "type" "name" { ... }`
* `OutputBlock` — `output "name" { value = expr }`
* `DataBlock` — `data "type" "name" { ... }`
* `PolicyBlock` — `policy "name" { rule { ... } }`
* etc.

Expressions are typed as `StringLiteral`, `NumberLiteral`, `BoolLiteral`, `ObjectExpr`, `ListExpr`, `PendingRef`, `ResolvedRef`, `Interpolation`, `FunctionCall`, or `ConditionalExpr`.

### Stage 3 — Merger

Applies `extend` block overrides for the target environment (`--env` flag). Merges override attributes into base blocks. Extend blocks for environments other than the target are discarded.

### Stage 4a — Schema Validation

Checks all `unit` block attributes against the provider schema registry:

* Required attributes must be present
* Unknown attributes produce warnings
* Type mismatches produce errors

### Stage 4b — Policy Evaluation

Evaluates all `policy` block rules against matching `unit` blocks. Violations produce errors (`severity = "error"`) or warnings (`severity = "warn"`).

### Stage 4c — Type Checker

* Resolves all symbol references (`input.name`, `local.name`, `~unit.type.name.attr`)
* Classifies every expression as `Resolved<T>` or `Pending<T>`
* Detects circular dependencies
* Validates `depends_on` references
* Validates `data` block references
* Validates cross-stack `~@name.output` references

### Stage 5 — Code Generator

Emits valid Pulumi TypeScript:

* `unit` blocks → `new Provider.ResourceName("name", { ... })`
* `input` blocks → `new pulumi.Config().get("name") ?? default`
* `output` blocks → `export const name = value`
* `data` blocks → `pulumi.output(provider.getResource({ ... }))`
* `Pending<T>` refs → `.apply()` chains or `pulumi.all([]).apply()`
* `secret()` calls → helper functions + `pulumi.secret()`

## Generated File Structure

```
.ubx/
  index.ts       # generated Pulumi TypeScript (do not edit)
  Pulumi.yaml    # Pulumi project metadata
  package.json   # npm dependencies (provider packages)
  node_modules/  # installed packages
  state/         # local state (if using file backend)
```

## Viewing Generated TypeScript

```bash theme={null}
ubx apply --dry-run
cat .ubx/index.ts
```

Or validate with TypeScript compiler:

```bash theme={null}
ubx validate --compile
```