react/compiler/docs/rust-port/rust-port-notes.md

Input/Output Format: JSON AST and Scope Tree

• Define a Rust representation of the Babel AST format using serde with custom serialization/deserialization in order to ensure that we always produce the "type" field, even outside of enum positions. Include full information from Babel, including source locations.
• Define a Scope type that encodes the tree of scope information, mapping to the information that babel represents in its own scope tree

The main public API is roughly compile(BabelAst, Scope) -> Option<BabelAst> returning None if no changes, or Some with the updated ast.

Arenas

Use arenas and Copy-able "id" values that index into the arenas in order to migrate "shared" mutable references.

• Identifier:
  • Table on Environment, stores actual Identifier values
  • Place.identifier references indirectly via IdentifierId
• ReactiveScope:
  • Table on Environment, stores actual ReactiveScope values
  • Identifier, scope terminals, etc reference indirectly via ScopeID
• Function:
  • Table on Environment, stores the inner HirFunction values
  • InstructionValue::FunctionExpression and ::ObjectMethod reference indirectly via FunctionId
• Type:
  • Table on Environment, stores actual types
  • Identifier types and other type values use TypeId to index into

Instructions Table

Store instructions indirectly. This allows passes that need to cache or remember an instruction's location (to work around borrowing issues) to have a single id to use to reference that instruction. Do not use (BlockId, usize) or similar.

• Rename InstructionId to EvaluationOrder - this type is actually about representing the evaluation order, and is not even instruction-specific: it is also present on terminals.
• HirFunction stores instructions: Vec<InstructionId>
• BasicBlock.instructions becomes Vec<InstructionId>, indexing into the HirFunction.instructions vec

AliasingEffect

• Place values are cloned
• Call variant args array is cloned
• CreateFunction variant uses FunctionId referencing the function arena

Environment

Pass a single mutable environment reference separately from the HIR.

• Remove HIRFunction.env, pass the environment as env: &mut Environment instead
• Maintain the existing fields/types of Environment type (don't group them)
• Use direct field access of Environment properties, rather than via methods, to allow precise sliced borrows of portions of the environment

Error Handling

In general there are two categories of errors:

• Anything that would have thrown, or would have short-circuited, should return an Err(...) with the single diagnosstic
• Otherwise, accumulate errors directly onto the environment.
• Error handling must preserve the full details of the errors: reason, description, location, details, suggestions, category, etc

Specific Error Patterns and Approaches

• TypeScript non-null assertions:
  • Example: !
  • Approach: panic via .unwrap() or similar.
• Throwing expressions:
  • Example: throw ... (latent bugs, should have been invariant)
  • Example: CompilerError.invariant()
  • Example: CompilerError.throwTodo()
  • Example: CompilerError.throw* (other "throw-" methods)
  • Approach: Make the function return a Result<_, CompilerDiagnostic>, and return Err(...) with the appropriate compiler error value.
• Non-throwing expressions (Invariant):
  • Example: local error object and error.pushDiagnostic() (where the error is an invariant)
  • Approach: Make the function return a Result<_, CompilerDiagnostic>, and change the pushDiagnostic() with return Err(...) to return with the invariant error.
• Non-throwing expressions (excluding Invariant):
  • Example: local error object and error.pushDiagnostic() (where the error is not an invariant)
  • Example: env.recordError() (where the error is not an invariant)
  • Approach: keep as-is

Pass and Pipeline Structure

Structure the pipeline and passes along these lines to align with the above error handling guidelines:

// pipeline.rs
fn compile(
    ast: Ast, 
    scope: Scope,
    env: &mut Environment,
) -> Result<CompileResult, CompilerDiagnostic>> {
    // "?" to handle cases that would have thrown or produced an invariant
    let mut hir = lower(ast, scope, env)?;
    some_compiler_pass(&mut hir, env)?;
    ...
    let ast = codegen(...)?;

    if (env.has_errors()) {
        // result with errors
        Ok(CompileResult::Failure(env.take_errors()))
    } else {
        // result with 
        Ok(CompileResult::Success(ast))
    }
}

// <compilerpasss>.rs
fn passname(
    func: &mut HirFunction,
    env: &mut Environment
) -> Result<_, CompilerDiagnostic>;