test cartridge for lua and js

This commit is contained in:
Nilton Constantino
2026-01-23 15:15:05 +00:00
parent b3a6d22e2f
commit a56dbadb9e
37 changed files with 400 additions and 2713 deletions
@@ -1,3 +1,12 @@
//! # Bytecode Emitter
//!
//! This module is responsible for the final stage of the compilation process:
//! converting the Intermediate Representation (IR) into the binary Prometeu ByteCode (PBC) format.
//!
//! It performs two main tasks:
//! 1. **Instruction Lowering**: Translates `ir::Instruction` into `prometeu_bytecode::asm::Asm` ops.
//! 2. **Symbol Mapping**: Associates bytecode offsets (Program Counter) with source code locations.
use crate::common::files::FileManager;
use crate::common::symbols::Symbol;
use crate::ir;
@@ -7,29 +16,38 @@ use prometeu_bytecode::asm::{assemble, update_pc_by_operand, Asm, Operand};
use prometeu_bytecode::opcode::OpCode;
use prometeu_bytecode::pbc::{write_pbc, ConstantPoolEntry, PbcFile};
/// The final output of the code generation phase.
pub struct EmitResult {
/// The serialized binary data of the PBC file.
pub rom: Vec<u8>,
/// Metadata mapping bytecode offsets to source code positions.
pub symbols: Vec<Symbol>,
}
/// Entry point for emitting a bytecode module from the IR.
pub fn emit_module(module: &ir::Module, file_manager: &FileManager) -> Result<EmitResult> {
let mut emitter = BytecodeEmitter::new(file_manager);
emitter.emit(module)
}
/// Internal helper for managing the bytecode emission state.
struct BytecodeEmitter<'a> {
/// Stores constant values (like strings) that are referenced by instructions.
constant_pool: Vec<ConstantPoolEntry>,
/// Used to look up source code positions for symbol generation.
file_manager: &'a FileManager,
}
impl<'a> BytecodeEmitter<'a> {
fn new(file_manager: &'a FileManager) -> Self {
Self {
// Index 0 is traditionally reserved for Null in many VMs
constant_pool: vec![ConstantPoolEntry::Null],
file_manager,
}
}
/// Adds a value to the constant pool if it doesn't exist, returning its unique index.
fn add_constant(&mut self, entry: ConstantPoolEntry) -> u32 {
if let Some(pos) = self.constant_pool.iter().position(|e| e == &entry) {
pos as u32
@@ -40,16 +58,22 @@ impl<'a> BytecodeEmitter<'a> {
}
}
/// Transforms an IR module into a binary PBC file.
fn emit(&mut self, module: &ir::Module) -> Result<EmitResult> {
let mut asm_instrs = Vec::new();
let mut ir_instr_map = Vec::new(); // Maps Asm index to IR instruction (for symbols)
// --- PHASE 1: Lowering IR to Assembly-like structures ---
for function in &module.functions {
// Each function starts with a label for its entry point.
asm_instrs.push(Asm::Label(function.name.clone()));
ir_instr_map.push(None);
for instr in &function.body {
let start_idx = asm_instrs.len();
// Translate each IR instruction to its equivalent Bytecode OpCode.
// Note: IR instructions are high-level, while Bytecode is low-level.
match &instr.kind {
InstrKind::Nop => asm_instrs.push(Asm::Op(OpCode::Nop, vec![])),
InstrKind::Halt => asm_instrs.push(Asm::Op(OpCode::Halt, vec![])),
@@ -63,6 +87,7 @@ impl<'a> BytecodeEmitter<'a> {
asm_instrs.push(Asm::Op(OpCode::PushBool, vec![Operand::Bool(*v)]));
}
InstrKind::PushString(s) => {
// Strings are stored in the constant pool.
let id = self.add_constant(ConstantPoolEntry::String(s.clone()));
asm_instrs.push(Asm::Op(OpCode::PushConst, vec![Operand::U32(id)]));
}
@@ -131,9 +156,12 @@ impl<'a> BytecodeEmitter<'a> {
}
}
// --- PHASE 2: Assembly (Label Resolution) ---
// Converts the list of Ops and Labels into raw bytes, calculating jump offsets.
let bytecode = assemble(&asm_instrs).map_err(|e| anyhow!(e))?;
// Resolve symbols
// --- PHASE 3: Symbol Generation ---
// Associates each bytecode offset with a line/column in the source file.
let mut symbols = Vec::new();
let mut current_pc = 0u32;
for (i, asm) in asm_instrs.iter().enumerate() {
@@ -153,15 +181,20 @@ impl<'a> BytecodeEmitter<'a> {
}
}
// Track the Program Counter (PC) as we iterate through instructions.
match asm {
Asm::Label(_) => {}
Asm::Op(_opcode, operands) => {
// Each OpCode takes 2 bytes (1 for opcode, 1 for padding/metadata)
current_pc += 2;
// Operands take additional space depending on their type.
current_pc = update_pc_by_operand(current_pc, operands);
}
}
}
// --- PHASE 4: Serialization ---
// Packages the constant pool and bytecode into the final PBC format.
let pbc = PbcFile {
cp: self.constant_pool.clone(),
rom: bytecode,
+41 -4
View File
@@ -1,3 +1,8 @@
//! # Compiler Orchestration
//!
//! This module provides the high-level API for triggering the compilation process.
//! It handles the transition between different compiler phases: Frontend -> IR -> Backend.
use crate::backend;
use crate::common::files::FileManager;
use crate::common::symbols::Symbol;
@@ -10,14 +15,22 @@ use std::path::Path;
/// The result of a successful compilation process.
/// It contains the final binary and the metadata needed for debugging.
pub struct CompilationUnit {
/// The raw binary data (PBC format).
/// The raw binary data formatted as Prometeu ByteCode (PBC).
/// This is what gets written to a `.pbc` file.
pub rom: Vec<u8>,
/// The list of debug symbols for source mapping.
/// The list of debug symbols discovered during compilation.
/// These are used to map bytecode offsets back to source code locations.
pub symbols: Vec<Symbol>,
}
impl CompilationUnit {
/// Writes the compilation results to the disk.
/// Writes the compilation results (PBC binary, disassembly, and symbols) to the disk.
///
/// # Arguments
/// * `out` - The base path for the output `.pbc` file.
/// * `emit_disasm` - If true, a `.disasm` file will be created next to the output.
/// * `emit_symbols` - If true, a `.json` symbols file will be created next to the output.
pub fn export(&self, out: &Path, emit_disasm: bool, emit_symbols: bool) -> Result<()> {
let artifacts = backend::artifacts::Artifacts::new(self.rom.clone(), self.symbols.clone());
artifacts.export(out, emit_disasm, emit_symbols)
@@ -25,21 +38,45 @@ impl CompilationUnit {
}
/// Orchestrates the compilation of a Prometeu project starting from an entry file.
///
/// This function executes the full compiler pipeline:
/// 1. **Frontend**: Loads and parses the entry file (and its dependencies).
/// Currently, it uses the `TypescriptFrontend`.
/// 2. **IR Generation**: The frontend produces a high-level Intermediate Representation (IR).
/// 3. **Validation**: Checks the IR for consistency and VM compatibility.
/// 4. **Backend**: Lowers the IR into final Prometeu ByteCode.
///
/// # Errors
/// Returns an error if parsing fails, validation finds issues, or code generation fails.
///
/// # Example
/// ```no_run
/// use std::path::Path;
/// let entry = Path::new("src/main.ts");
/// let unit = prometeu_compiler::compiler::compile(entry).expect("Failed to compile");
/// unit.export(Path::new("build/program.pbc"), true, true).unwrap();
/// ```
pub fn compile(entry: &Path) -> Result<CompilationUnit> {
let mut file_manager = FileManager::new();
// 1. Select Frontend (Currently only TS is supported)
// The frontend is responsible for parsing source code and producing the IR.
let frontend = TypescriptFrontend;
// 2. Compile to IR
// 2. Compile to IR (Intermediate Representation)
// This step abstracts away source-specific syntax (like TypeScript) into a
// generic set of instructions that the backend can understand.
let ir_module = frontend.compile_to_ir(entry, &mut file_manager)
.map_err(|bundle| anyhow::anyhow!("Compilation failed with {} errors", bundle.diagnostics.len()))?;
// 3. IR Validation
// Ensures the generated IR is sound and doesn't violate any VM constraints
// before we spend time generating bytecode.
ir::validate::validate_module(&ir_module)
.map_err(|bundle| anyhow::anyhow!("IR Validation failed: {:?}", bundle))?;
// 4. Emit Bytecode
// The backend takes the validated IR and produces the final binary executable.
let result = backend::emit_module(&ir_module, &file_manager)?;
Ok(CompilationUnit {
@@ -1,3 +1,12 @@
//! # TypeScript Frontend
//!
//! This module implements the TypeScript/JavaScript frontend for the Prometeu Compiler.
//! It is responsible for:
//! 1. Parsing `.ts` files into an Abstract Syntax Tree (AST).
//! 2. Resolving imports and building a dependency graph.
//! 3. Validating that the source code uses only supported VM features.
//! 4. Lowering the high-level AST into the generic Intermediate Representation (IR).
pub mod parse;
pub mod resolve;
pub mod validate;
@@ -14,6 +23,7 @@ use std::collections::{HashMap, VecDeque};
use std::fs;
use std::path::Path;
/// The main entry point for the TypeScript compiler frontend.
pub struct TypescriptFrontend;
impl Frontend for TypescriptFrontend {
@@ -21,6 +31,21 @@ impl Frontend for TypescriptFrontend {
"typescript"
}
/// Compiles a TypeScript entry file (and all its dependencies) into an IR Module.
///
/// # The Compilation Pipeline:
///
/// 1. **Discovery & Parsing**:
/// Starting from the `entry` file, it reads, parses, and discovers imports recursively.
/// It uses the `oxc` parser for high-performance AST generation.
///
/// 2. **Semantic Validation**:
/// Each parsed module is checked against the `Validator`. Since Prometeu is a
/// specialized VM, it doesn't support the full range of TS/JS features (e.g., no `try/catch` yet).
///
/// 3. **IR Lowering**:
/// Once all modules are parsed and validated, the `ToIR` engine traverses the ASTs
/// and emits equivalent IR instructions.
fn compile_to_ir(
&self,
entry: &Path,
@@ -35,6 +60,7 @@ impl Frontend for TypescriptFrontend {
queue.push_back(entry_abs.clone());
// --- PHASE 1: Dependency Resolution and Parsing ---
// We traverse the dependency graph breadth-first to ensure all files are loaded.
while let Some(path) = queue.pop_front() {
let path_str: String = path.to_string_lossy().into_owned();
if modules.contains_key(&path_str) {
@@ -45,12 +71,14 @@ impl Frontend for TypescriptFrontend {
let file_id = file_manager.add(path.clone(), source_text.clone());
let source_text_ptr = allocator.alloc_str(&source_text);
// Parse the source into an AST
let program = parse::parse_file(&allocator, &path).map_err(|e| DiagnosticBundle::error(format!("Failed to parse module: {}", e), None))?;
// --- PHASE 2: Individual Module Validation ---
// Ensure the code adheres to Prometeu's restricted subset of TypeScript.
validate::Validator::validate(&program).map_err(|e| DiagnosticBundle::error(format!("Validation error: {}", e), None))?;
// Discover new imports
// Discover new imports and add them to the queue
for item in &program.body {
if let oxc_ast::ast::Statement::ImportDeclaration(decl) = item {
let import_path = decl.source.value.as_str();
@@ -63,6 +91,7 @@ impl Frontend for TypescriptFrontend {
}
// --- PHASE 3: To IR ---
// Collect all parsed modules and feed them into the IR generator.
let entry_str = entry_abs.to_string_lossy().to_string();
let mut program_list = Vec::new();
@@ -1,3 +1,34 @@
//! # To IR Lowering
//!
//! This module implements the core translation logic from the TypeScript AST (Abstract Syntax Tree)
//! into the Prometeu Intermediate Representation (IR).
//!
//! ## How it works:
//!
//! The `ToIR` engine traverses the AST and for each node (expression, statement, etc.),
//! it emits equivalent stack-based IR instructions.
//!
//! ### Symbol Resolution
//! It maintains a scoped symbol table to track local variables and their assigned slots.
//! It also manages global variables, which are mapped to permanent memory slots in the VM.
//!
//! ### Control Flow
//! High-level control flow (like `if`, `while`, `for`) is lowered into jumps and labels.
//! Unique labels are generated for each branch to avoid collisions.
//!
//! ### Example Translation:
//! **TS Source:**
//! ```typescript
//! let x = 10 + 20;
//! ```
//! **Generated IR:**
//! ```text
//! PushInt(10)
//! PushInt(20)
//! Add
//! SetLocal(0)
//! ```
use crate::frontends::ts::syscall_map;
use crate::common::spans::Span as IRSpan;
use crate::frontends::ts::ast_util;
@@ -14,11 +45,15 @@ use prometeu_core::model::Color;
use std::collections::HashMap;
/// Helper to count local variables and hoisted functions in a function body.
///
/// This is used to determine how many slots need to be reserved on the stack frame
/// before executing a function.
struct LocalCounter {
count: u32,
}
impl<'a> Visit<'a> for LocalCounter {
/// Discovers function declarations which also occupy a slot in the current frame.
fn visit_statement(&mut self, stmt: &Statement<'a>) {
match stmt {
Statement::FunctionDeclaration(f) => {
@@ -28,6 +63,7 @@ impl<'a> Visit<'a> for LocalCounter {
}
}
/// Discovers variable declarations (let/const/var) and increments the local count.
fn visit_variable_declaration(&mut self, decl: &VariableDeclaration<'a>) {
self.count += decl.declarations.len() as u32;
walk::walk_variable_declaration(self, decl);
@@ -43,8 +79,11 @@ impl<'a> Visit<'a> for LocalCounter {
/// Metadata for a symbol (variable or function) in the symbol table.
struct SymbolEntry {
/// The unique index assigned to this variable in the current frame or global memory.
slot_index: u32,
/// Whether the variable was declared with `const`.
is_const: bool,
/// Tracks if the variable has been assigned a value (used for Temporal Dead Zone checks).
is_initialized: bool,
}
@@ -59,12 +98,13 @@ pub struct ToIR {
/// The stream of generated IR instructions.
pub instructions: Vec<ir::Instruction>,
/// Scoped symbol table. Each element is a scope level containing a map of symbols.
/// This allows for variable shadowing and block scope resolution.
symbol_table: Vec<HashMap<String, SymbolEntry>>,
/// Current depth of the scope (0 is global/function top-level).
scope_depth: usize,
/// Mapping of global variable names to their slots in the VM's global memory.
globals: HashMap<String, u32>,
/// Counter for the next available local variable ID.
/// Counter for the next available local variable ID in the current function.
next_local: u32,
/// Counter for the next available global variable ID.
next_global: u32,
+77 -8
View File
@@ -1,78 +1,147 @@
//! # IR Instructions
//!
//! This module defines the set of instructions used in the Intermediate Representation (IR).
//! These instructions are designed to be easy to generate from a high-level AST and
//! easy to lower into VM-specific bytecode.
use crate::common::spans::Span;
/// An `Instruction` combines an instruction's behavior (`kind`) with its
/// source code location (`span`) for debugging and error reporting.
#[derive(Debug, Clone)]
pub struct Instruction {
pub kind: InstrKind,
/// The location in the original source code that generated this instruction.
pub span: Option<Span>,
}
impl Instruction {
/// Creates a new instruction with an optional source span.
pub fn new(kind: InstrKind, span: Option<Span>) -> Self {
Self { kind, span }
}
}
/// A `Label` represents a destination for a jump instruction.
/// During the assembly phase, labels are resolved into actual memory offsets.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Label(pub String);
/// The various types of operations that can be performed in the IR.
///
/// The IR uses a stack-based model, similar to the final Prometeu ByteCode.
#[derive(Debug, Clone)]
pub enum InstrKind {
/// Does nothing.
Nop,
/// Terminates program execution.
Halt,
// Literals
// --- Literals ---
// These instructions push a constant value onto the stack.
/// Pushes a 64-bit integer onto the stack.
PushInt(i64),
/// Pushes a 64-bit float onto the stack.
PushFloat(f64),
/// Pushes a boolean onto the stack.
PushBool(bool),
/// Pushes a string literal onto the stack.
PushString(String),
/// Pushes a `null` value onto the stack.
PushNull,
// Stack Ops
// --- Stack Operations ---
/// Removes the top value from the stack.
Pop,
/// Duplicates the top value on the stack.
Dup,
/// Swaps the top two values on the stack.
Swap,
// Arithmetic
// --- Arithmetic ---
// These take two values from the stack and push the result.
/// Addition: `a + b`
Add,
/// Subtraction: `a - b`
Sub,
/// Multiplication: `a * b`
Mul,
/// Division: `a / b`
Div,
/// Negation: `-a` (takes one value)
Neg,
// Logical/Comparison
// --- Logical/Comparison ---
/// Equality: `a == b`
Eq,
/// Inequality: `a != b`
Neq,
/// Less than: `a < b`
Lt,
/// Greater than: `a > b`
Gt,
/// Less than or equal: `a <= b`
Lte,
/// Greater than or equal: `a >= b`
Gte,
/// Logical AND: `a && b`
And,
/// Logical OR: `a || b`
Or,
/// Logical NOT: `!a`
Not,
// Bitwise
// --- Bitwise Operations ---
/// Bitwise AND: `a & b`
BitAnd,
/// Bitwise OR: `a | b`
BitOr,
/// Bitwise XOR: `a ^ b`
BitXor,
/// Shift Left: `a << b`
Shl,
/// Shift Right: `a >> b`
Shr,
// Variables
// --- Variable Access ---
/// Retrieves a value from a local variable slot and pushes it onto the stack.
GetLocal(u32),
/// Pops a value from the stack and stores it in a local variable slot.
SetLocal(u32),
/// Retrieves a value from a global variable slot and pushes it onto the stack.
GetGlobal(u32),
/// Pops a value from the stack and stores it in a global variable slot.
SetGlobal(u32),
// Control Flow
// --- Control Flow ---
/// Unconditionally jumps to the specified label.
Jmp(Label),
/// Pops a boolean from the stack. If false, jumps to the specified label.
JmpIfFalse(Label),
/// Defines a location that can be jumped to. Does not emit code by itself.
Label(Label),
/// Calls a function by name with the specified number of arguments.
/// Arguments should be pushed onto the stack before calling.
Call { name: String, arg_count: u32 },
/// Returns from the current function. The return value (if any) should be on top of the stack.
Ret,
// OS / System
// --- OS / System ---
/// Triggers a system call (e.g., drawing to the screen, reading input).
Syscall(u32),
/// Special instruction to synchronize with the hardware frame clock.
FrameSync,
/// Internal: Pushes a new lexical scope (used for variable resolution).
PushScope,
/// Internal: Pops the current lexical scope.
PopScope,
}
+27
View File
@@ -1,35 +1,62 @@
//! # IR Module Structure
//!
//! This module defines the structure of the Intermediate Representation (IR).
//! The IR is a higher-level representation of the program than bytecode, but lower
//! than the source code AST. It is organized into Modules, Functions, and Globals.
use crate::ir::instr::Instruction;
use crate::ir::types::Type;
/// A `Module` is the top-level container for a compiled program or library.
/// It contains a collection of global variables and functions.
#[derive(Debug, Clone)]
pub struct Module {
/// The name of the module (usually derived from the project name).
pub name: String,
/// List of all functions defined in this module.
pub functions: Vec<Function>,
/// List of all global variables available in this module.
pub globals: Vec<Global>,
}
/// Represents a function in the IR.
///
/// Functions consist of a signature (name, parameters, return type) and a body
/// which is a flat list of IR instructions.
#[derive(Debug, Clone)]
pub struct Function {
/// The unique name of the function.
pub name: String,
/// The list of input parameters.
pub params: Vec<Param>,
/// The type of value this function returns.
pub return_type: Type,
/// The sequence of instructions that make up the function's logic.
pub body: Vec<Instruction>,
}
/// A parameter passed to a function.
#[derive(Debug, Clone)]
pub struct Param {
/// The name of the parameter (useful for debugging and symbols).
pub name: String,
/// The data type of the parameter.
pub r#type: Type,
}
/// A global variable accessible by any function in the module.
#[derive(Debug, Clone)]
pub struct Global {
/// The name of the global variable.
pub name: String,
/// The data type of the variable.
pub r#type: Type,
/// The unique memory slot index assigned to this global variable.
pub slot: u32,
}
impl Module {
/// Creates a new, empty module with the given name.
pub fn new(name: String) -> Self {
Self {
name,
+30 -8
View File
@@ -1,19 +1,41 @@
//! # Prometeu Compiler
//!
//! This crate provides the official compiler for the Prometeu ecosystem.
//! It translates TypeScript/JavaScript source code into Prometeu ByteCode (.pbc).
//! It translates high-level source code (primarily TypeScript/JavaScript) into
//! Prometeu ByteCode (.pbc), which runs on the Prometeu Virtual Machine.
//!
//! ## Workflow:
//! 1. **Parsing**: Uses the `oxc` parser to generate an Abstract Syntax Tree (AST).
//! 2. **Validation**: Checks for unsupported features and ensures ABI compliance.
//! 3. **Codegen**: Traverses the AST and emits `prometeu-bytecode` instructions.
//! 4. **Assembly**: Resolves labels and serializes the program into the binary PBC format.
//! ## Architecture Overview:
//!
//! The compiler follows a multi-stage pipeline:
//!
//! 1. **Frontend (Parsing & Analysis)**:
//! - Uses the `oxc` parser to generate an Abstract Syntax Tree (AST).
//! - Performs semantic analysis and validation (e.g., ensuring only supported TS features are used).
//! - Lowers the AST into the **Intermediate Representation (IR)**.
//! - *Example*: Converting a `a + b` expression into IR instructions like `Push(a)`, `Push(b)`, `Add`.
//!
//! 2. **IR Optimization (Optional/Planned)**:
//! - Simplifies the IR to improve performance or reduce bytecode size.
//!
//! 3. **Backend (Code Generation)**:
//! - **Lowering**: Converts the high-level IR into a flat list of ByteCode instructions.
//! - **Assembly**: Resolves branch labels into actual memory offsets.
//! - **Serialization**: Encodes the instructions into the binary PBC format.
//!
//! 4. **Artifact Export**:
//! - Generates the `.pbc` binary file.
//! - Optionally produces `.disasm` (disassembly for debugging) and `.json` (symbol maps).
//!
//! ## Example Usage (CLI):
//!
//! ## Example Usage:
//! ```bash
//! # Build a project
//! # Build a project from a directory
//! prometeu-compiler build ./my-game --entry ./src/main.ts --out ./game.pbc
//! ```
//!
//! ## Programmatic Entry Point:
//!
//! See the [`compiler`] module for the main entry point to trigger a compilation programmatically.
pub mod common;
pub mod ir;