Compilation Phases

Detailed walkthrough of each phase. For overview, see Architecture Overview.

Phase 1: Discover ✅

Validate tsconfig.json and glob for input files matching the config pattern.

Phase 2: Load ✅

Read files from disk, create TypeScript SourceFile AST objects.

Phase 3: Build IR ✅

Parse decorators and metadata into immutable IR: components, props, events, methods.

Phase 4: Sync AST ⚠️

Update AST nodes to reflect IR state. Resolve cross-file dependencies.

Phase 5: Generate ⚠️

Run generators (always fully rebuild). Examples: ir.json, components.d.ts.

Phase 6: Derive ⚠️

Run derivatives (per-source framework adapters). Examples: component.react.tsx, component.angular.ts.

Phase 7: Write ✅

Final write phase with multiple sub-stages:

1. Preprocess – Collect referenced symbols, inject missing imports (see Symbol Resolution)
2. Print – Convert AST to source code
3. Postprocess – Format, validate, post-emit steps
4. Flush – Write to disk

File Organization

During compilation:

sourceFiles.loadSource()        // Read project *.pen.ts files
sourceFiles.clearGenerated()    // Clear stale outputs
sourceFiles.newFile(name)       // Create a generated file
sourceFiles.getAll()            // Get both source + generated

Project source files persist across passes. Generated files are cleared at startup to prevent stale outputs.