GSoC/DMP 2025 Week 9: feat(Program): Add Compiler Module

[sa-fw-an]

This PR implements the complete AST-to-IR Compiler Module for the Music Blocks 4 Program Engine, as outlined in Week 9 of the GSoC project.

What's Implemented

Complete AST-to-IR Compilation Pipeline

• Full compiler architecture with generic AST node translation to IR instructions
• Stack-based AST traversal using explicit node stack to avoid recursion and handle deeply nested structures
• Control flow flattening converting compound statements (if/while) into basic blocks with jumps
• Expression compilation with temporary variable generation for complex operations and assignments

Core Compiler Components

• Compiler: Main orchestration class taking Program AST and producing complete IRProgram
• Parser: Unified AST traversal and IR generation engine with explicit node stack management
• BasicBlockManager: Utility for creating, labeling, and linking control flow basic blocks
• Integration with SymbolManager: Leverages existing symbol table for variable declarations and lookups

Supported AST Node Compilation

• Variable Operations: VariableDeclarationStatement → sym_declare, VariableAssignmentStatement → sym_assign/sym_query
• Expression Handling: IdentifierExpression, OperatorExpression with temporary variable generation
• Control Flow: BranchStatement (if/else) and ConditionLoopStatement (while) → basic blocks with compare_jump/jump
• Function Calls: FunctionCallStatement/FunctionCallExpression → call with argument compilation

IR Instruction Generation

The compiler generates only the 6 allowed IR instructions:

• sym_declare: Variable declarations in symbol table
• sym_assign: Value assignments with complex expression support
• sym_query: Variable lookups for expressions and temporary storage
• call: Function invocations with compiled arguments
• compare_jump: Conditional branching for if/while statements
• jump: Unconditional control flow between basic blocks

Testing Implementation

Comprehensive Test Suite

Located in modules/program/src/compiler/:

• Unit tests for each compiler component (Compiler, Parser, BasicBlockManager)
• AST node compilation tests verifying correct IR instruction generation
• Control flow tests ensuring proper basic block creation and jump logic
• Integration tests compiling the complete example program from MusicBlocksProgram.ts

How to Test

Run Compiler Tests

npm run test
# or for specific compiler tests
npm run test compiler/

Test Full Program Compilation

npm run test compiler/compiler.spec.ts
# Tests compilation of complete MusicBlocksProgram.ts example

This compiler serves as the critical bridge between the visual programming AST and the executable IR, enabling the complete Music Blocks v4 execution pipeline.