Enhanced Visitor Pattern with Lifecycle Hooks and Composition

[magic-akari]

Summary

This RFC proposes a redesigned Visitor pattern with composable enter/exit hooks.
Key changes include:

• enter_node/exit_node/enter_mut_node/exit_mut_node in a single trait
• Explicit manual control of visitor execution order
• Backward-compatible migration path with safety guarantees
• Context-aware child traversal management (TBD)

Motivation

1. Runtime Efficiency: Reduce overhead from multiple AST traversal passes

Design Details

• A new Visitor pattern that exposes enter and exit methods for visiting elements. This will help us compose Visitors by exposing methods in child Visitors and invoking them through parent Visitors to achieve composition.
• This is based on our consensus: even no-op Visitors have non-negligible runtime overhead. Therefore, we need a Visitor composer to combine multiple Visitors and execute them in a single pass, which is expected to outperform sequential invocations of individual Visitors.
• The ideal design requires four hooks: immutable enter/exit and mutable enter/exit. Immutable hooks should be used for information collection, while mutable hooks handle AST modifications.
• Unlike OXC's complete rewrite approach, we need to migrate existing Visitors with additional compatibility considerations to prevent regressions.
• Special attention must be paid to child node skipping patterns. After transitioning to composed enter/exit` handlers, we should generally avoid skipping child nodes. Performance-driven skips can be deprecated, but correctness-critical skips require explicit handling.

Lifecycle Hooks

trait VisitorHook {
    // Immutable observation phase
    fn enter_expr(&mut self, node: &Expr, ctx: &mut Ctx) {}
    fn exit_expr(&mut self, node: &Expr, ctx: &mut Ctx) {}

    // Mutable transformation phase 
    fn enter_mut_expr(&mut self, node: &mut Expr, ctx: &mut Ctx) {}
    fn exit_mut_expr(&mut self, node: &mut Expr, ctx: &mut Ctx) {}

    // Repeating for other node types...
}

Visitor Composition Example

struct TypeScript {
    // child visitors
    r#enum: TypeScriptEnum,
    module: TypeScriptModule,

    // Other fields...
}

impl VisitorHook for TypeScript {
    fn enter_mut_stmt(&mut self, stmt: &mut Stmt, ctx: &mut Ctx) {
        self.r#enum.enter_mut_stmt(stmt, ctx);
        self.module.enter_mut_stmt(stmt, ctx);
    }
}

Appendix: State Management Example

Before:

fn visit_mut_expr(&mut self, e: &mut Expr) {
    let prev_prepend_exprs = take(&mut self.prepend_exprs);
    e.visit_mut_children_with(self);
    let mut prepend_exprs = replace(&mut self.prepend_exprs, prev_prepend_exprs);
}

After (TBD):

fn enter_mut_expr(&mut self, e: &mut Expr, ctx: &mut Ctx) {
    ctx.push_state(self.state.take());
}

fn exit_mut_expr(&mut self, e: &mut Expr, ctx: &mut Ctx) {
    self.state = ctx.pop_state();
}