feat: enhance C ABI compatibility, type inference, and JSON serialization (#293)

This commit improves the robustness of the LLVM backend regarding type
resolution under opaque pointers, refines C ABI lowering for aggregates,
and introduces JSON serialization utilities.

Changes:
- **LLVM Codegen & ABI**:
  - **C ABI Refinement**: Updated `abi_c.rs` to pass small "mixed"
    aggregates as direct values, allowing LLVM to handle register
    assignment (INTEGER vs. SSE) more effectively for the C calling
    convention.
  - **Implicit Main Return**: Implemented implicit `return 0` for the
    `main` function. If `main` is defined as void-like in Wave, it is
    now lowered to an `i32` return in LLVM to satisfy standard
    execution environments.
  - **Symbol Resolution**: Fixed a bug in `gen_function_call` where
    extern C functions were being looked up by their Wave name instead
    of their redirected LLVM symbol name.
  - **Address Generation**: Introduced `generate_address_and_type_ir`
    to provide both the memory address and its corresponding LLVM type,
    simplifying indexing and field access logic.
- **Type System & Pointers**:
  - **Enhanced Inference**: Implemented `infer_wave_type_of_expr` and
    `basic_ty_to_wave_ty` to improve Wave-to-LLVM type mapping,
    especially for complex lvalues.
  - **Legacy Compatibility**: Updated `deref` handling to allow redundant
    dereferences on already-addressable lvalues (e.g., `deref array[i]`),
    maintaining compatibility with existing code.
- **Parser & Verification**:
  - **ABI Validation**: Added a verification pass to ensure only
    `extern(c)` is used, as other ABIs are not yet supported.
- **JSON Utilities**:
  - Added `write_pretty_to` and `write_compact_to` to the `Json` enum.
  - Implemented full JSON string escaping (handles newlines, quotes,
    slashes, and control characters).
- **CLI & Flags**:
  - Added support for `-Os` (optimize for size) and `-Ofast`
    (aggressive optimization) flags in the CLI and LLVM pass builder.

These updates stabilize the transition to opaque pointers and provide
a more predictable interface for system-level FFI and serialization.

Signed-off-by: LunaStev <luna@lunastev.org>

Author: LunaStev

front/parser/src/verification.rs

@@ -247,6 +247,15 @@ fn validate_node(
             scopes.pop();
         }
 
+        ASTNode::ExternFunction(ext) => {
+            if !ext.abi.eq_ignore_ascii_case("c") {
+                return Err(format!(
+                    "unsupported extern ABI '{}' for function '{}': only extern(c) is currently supported",
+                    ext.abi, ext.name
+                ));
+            }
+        }
+
         _ => {}
     }
 

llvm/src/codegen/abi_c.rs

@@ -38,6 +38,7 @@ pub enum RetLowering<'ctx> {
 
 #[derive(Clone)]
 pub struct ExternCInfo<'ctx> {
+    pub llvm_name: String,               // actual LLVM symbol name
     pub wave_ret: WaveType,              // Wave-level return type (needed when sret => llvm void)
     pub ret: RetLowering<'ctx>,
     pub params: Vec<ParamLowering<'ctx>>, // per-wave param
@@ -168,9 +169,9 @@ fn classify_param<'ctx>(
             return ParamLowering::Direct(it.as_basic_type_enum());
         }
 
-        // mixed small aggregate: safest is byval (conservative but correct)
-        let align = td.get_abi_alignment(&t) as u32;
-        return ParamLowering::ByVal { ty: t.as_any_type_enum(), align };
+        // mixed small aggregate: keep as direct aggregate value.
+        // Let LLVM's C ABI lowering split/register-assign correctly.
+        return ParamLowering::Direct(t);
     }
 
     // non-aggregate: direct
@@ -246,9 +247,9 @@ fn classify_ret<'ctx>(
             }
         }
 
-        // mixed small aggregate ret: safest sret
-        let align = td.get_abi_alignment(&t) as u32;
-        return RetLowering::SRet { ty: t.as_any_type_enum(), align };
+        // mixed small aggregate ret: keep direct aggregate value.
+        // Let LLVM's C ABI lowering pick mixed INTEGER/SSE return registers.
+        return RetLowering::Direct(t);
     }
 
     RetLowering::Direct(t)
@@ -261,6 +262,7 @@ pub fn lower_extern_c<'ctx>(
     struct_types: &HashMap<String, inkwell::types::StructType<'ctx>>,
 ) -> LoweredExtern<'ctx> {
     let llvm_name = ext.symbol.as_deref().unwrap_or(ext.name.as_str()).to_string();
+    let info_llvm_name = llvm_name.clone();
 
     // wave types -> layout types
     let wave_param_layout: Vec<BasicTypeEnum<'ctx>> = ext.params.iter()
@@ -311,6 +313,7 @@ pub fn lower_extern_c<'ctx>(
         llvm_name,
         fn_type,
         info: ExternCInfo {
+            llvm_name: info_llvm_name,
             wave_ret: ext.return_type.clone(),
             ret,
             params,

llvm/src/codegen/address.rs

@@ -198,7 +198,10 @@ fn addr_and_ty<'ctx>(
             );
 
             if !slot_ty.is_pointer_type() {
-                panic!("Cannot deref non-pointer lvalue: {:?}", inner);
+                // Legacy compatibility:
+                // allow redundant `deref` on already-addressable lvalues
+                // like `deref q.rear` and `deref visited[x]`.
+                return (slot_ptr, slot_ty);
             }
 
             let pv = load_ptr_from_slot(context, builder, slot_ptr, "deref_target");
@@ -383,3 +386,23 @@ pub fn generate_address_ir<'ctx>(
     )
         .0
 }
+
+pub fn generate_address_and_type_ir<'ctx>(
+    context: &'ctx Context,
+    builder: &'ctx Builder<'ctx>,
+    expr: &Expression,
+    variables: &mut HashMap<String, VariableInfo<'ctx>>,
+    module: &'ctx Module<'ctx>,
+    struct_types: &HashMap<String, StructType<'ctx>>,
+    struct_field_indices: &HashMap<String, HashMap<String, u32>>,
+) -> (PointerValue<'ctx>, BasicTypeEnum<'ctx>) {
+    addr_and_ty(
+        context,
+        builder,
+        expr,
+        variables,
+        module,
+        struct_types,
+        struct_field_indices,
+    )
+}

llvm/src/codegen/ir.rs

@@ -28,6 +28,14 @@ use crate::codegen::abi_c::{
     ExternCInfo, lower_extern_c, apply_extern_c_attrs,
 };
 
+fn is_implicit_i32_main(name: &str, return_type: &Option<WaveType>) -> bool {
+    name == "main" && matches!(return_type, None | Some(WaveType::Void))
+}
+
+fn is_supported_extern_abi(abi: &str) -> bool {
+    abi.eq_ignore_ascii_case("c")
+}
+
 pub unsafe fn generate_ir(ast_nodes: &[ASTNode], opt_flag: &str) -> String {
     let context: &'static Context = Box::leak(Box::new(Context::create()));
     let module: &'static _ = Box::leak(Box::new(context.create_module("main")));
@@ -189,11 +197,15 @@ pub unsafe fn generate_ir(ast_nodes: &[ASTNode], opt_flag: &str) -> String {
             .map(|p| wave_type_to_llvm_type(context, &p.param_type, &struct_types, TypeFlavor::AbiC).into())
             .collect();
 
-        let fn_type = match return_type {
-            None | Some(WaveType::Void) => context.void_type().fn_type(&param_types, false),
-            Some(wave_ret_ty) => {
-                let llvm_ret_type = wave_type_to_llvm_type(context, wave_ret_ty, &struct_types, TypeFlavor::AbiC);
-                llvm_ret_type.fn_type(&param_types, false)
+        let fn_type = if is_implicit_i32_main(name, return_type) {
+            context.i32_type().fn_type(&param_types, false)
+        } else {
+            match return_type {
+                None | Some(WaveType::Void) => context.void_type().fn_type(&param_types, false),
+                Some(wave_ret_ty) => {
+                    let llvm_ret_type = wave_type_to_llvm_type(context, wave_ret_ty, &struct_types, TypeFlavor::AbiC);
+                    llvm_ret_type.fn_type(&param_types, false)
+                }
             }
         };
 
@@ -202,6 +214,13 @@ pub unsafe fn generate_ir(ast_nodes: &[ASTNode], opt_flag: &str) -> String {
     }
 
     for ext in &extern_functions {
+        if !is_supported_extern_abi(&ext.abi) {
+            panic!(
+                "unsupported extern ABI '{}' for function '{}': only extern(c) is currently supported",
+                ext.abi, ext.name
+            );
+        }
+
         let lowered = lower_extern_c(context, td, ext, &struct_types);
 
         let f = module.add_function(&lowered.llvm_name, lowered.fn_type, None);
@@ -263,13 +282,17 @@ pub unsafe fn generate_ir(ast_nodes: &[ASTNode], opt_flag: &str) -> String {
 
         let current_block = builder.get_insert_block().unwrap();
         if current_block.get_terminator().is_none() {
+            let implicit_i32_main = is_implicit_i32_main(&func_node.name, &func_node.return_type);
             let is_void_like = match &func_node.return_type {
                 None => true,
                 Some(WaveType::Void) => true,
                 _ => false,
             };
 
-            if is_void_like {
+            if implicit_i32_main {
+                let zero = context.i32_type().const_zero();
+                builder.build_return(Some(&zero)).unwrap();
+            } else if is_void_like {
                 builder.build_return(None).unwrap();
             } else {
                 panic!("Non-void function '{}' is missing a return statement", func_node.name);
@@ -295,6 +318,7 @@ fn pipeline_from_opt_flag(opt_flag: &str) -> &'static str {
         "-O3" => "default<O3>",
         "-Os" => "default<Os>",
         "-Oz" => "default<Oz>",
+        "-Ofast" => "default<O3>",
         other => panic!("unknown opt flag for LLVM passes: {}", other),
     }
 }
@@ -522,4 +546,4 @@ fn add_enum_consts_to_globals(
 
         next += 1;
     }
-}
+}

llvm/src/codegen/mod.rs

@@ -18,7 +18,7 @@ pub mod legacy;
 pub mod plan;
 pub mod abi_c;
 
-pub use address::generate_address_ir;
+pub use address::{generate_address_and_type_ir, generate_address_ir};
 pub use format::{wave_format_to_c, wave_format_to_scanf};
 pub use ir::generate_ir;
 pub use types::{wave_type_to_llvm_type, VariableInfo};

llvm/src/expression/rvalue/assign.rs

@@ -43,6 +43,27 @@ fn wave_to_basic<'ctx, 'a>(env: &ExprGenEnv<'ctx, 'a>, wt: &WaveType) -> BasicTy
     wave_type_to_llvm_type(env.context, wt, env.struct_types, TypeFlavor::Value)
 }
 
+fn basic_to_wave<'ctx, 'a>(env: &ExprGenEnv<'ctx, 'a>, bt: BasicTypeEnum<'ctx>) -> Option<WaveType> {
+    match bt {
+        BasicTypeEnum::IntType(it) => {
+            let bw = it.get_bit_width() as u16;
+            if bw == 1 {
+                Some(WaveType::Bool)
+            } else {
+                Some(WaveType::Int(bw))
+            }
+        }
+        BasicTypeEnum::FloatType(ft) => Some(WaveType::Float(ft.get_bit_width() as u16)),
+        BasicTypeEnum::PointerType(_) => Some(WaveType::Pointer(Box::new(WaveType::Byte))),
+        BasicTypeEnum::ArrayType(at) => {
+            let elem = basic_to_wave(env, at.get_element_type())?;
+            Some(WaveType::Array(Box::new(elem), at.len()))
+        }
+        BasicTypeEnum::StructType(st) => Some(WaveType::Struct(resolve_struct_key(env, st))),
+        _ => None,
+    }
+}
+
 fn wave_type_of_lvalue<'ctx, 'a>(env: &ExprGenEnv<'ctx, 'a>, e: &Expression) -> Option<WaveType> {
     match e {
         Expression::Variable(name) => env.variables.get(name).map(|vi| vi.ty.clone()),
@@ -54,7 +75,7 @@ fn wave_type_of_lvalue<'ctx, 'a>(env: &ExprGenEnv<'ctx, 'a>, e: &Expression) ->
             match inner_ty {
                 WaveType::Pointer(t) => Some(*t),
                 WaveType::String => Some(WaveType::Byte),
-                _ => None,
+                other => Some(other),
             }
         }
         Expression::IndexAccess { target, .. } => {
@@ -66,6 +87,26 @@ fn wave_type_of_lvalue<'ctx, 'a>(env: &ExprGenEnv<'ctx, 'a>, e: &Expression) ->
                 _ => None,
             }
         }
+        Expression::FieldAccess { object, field } => {
+            let object_ty = wave_type_of_lvalue(env, object)?;
+            let struct_name = match object_ty {
+                WaveType::Struct(name) => name,
+                WaveType::Pointer(inner) => match *inner {
+                    WaveType::Struct(name) => name,
+                    _ => return None,
+                },
+                _ => return None,
+            };
+
+            let st = *env.struct_types.get(&struct_name)?;
+            let field_index = env
+                .struct_field_indices
+                .get(&struct_name)
+                .and_then(|m| m.get(field))
+                .copied()?;
+            let field_bt = st.get_field_type_at_index(field_index)?;
+            basic_to_wave(env, field_bt)
+        }
         _ => None,
     }
 }

llvm/src/expression/rvalue/calls.rs

@@ -336,7 +336,7 @@ pub(crate) fn gen_function_call<'ctx, 'a>(
 
     if let Some(info) = env.extern_c_info.get(name) {
         let function = env.module
-            .get_function(name)
+            .get_function(&info.llvm_name)
             .unwrap_or_else(|| panic!("Extern function '{}' not found in module (symbol alias?)", name));
 
         if args.len() != info.params.len() {