biujs 0.1.0-alpha.0

A lightweight, embeddable JavaScript engine with ES6 support
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
# 异常处理架构设计

## 概述

biujs 实现了 JavaScript 的 SEH(Structured Exception Handling,结构化异常处理)模型,支持 `try`/`catch`/`finally` 以及 `throw` 语句。设计采用**多层抽象**:AST → IR → Bytecode → VM,每层职责清晰。

---

## 1. 架构层次

```
┌─────────────────────────────────────────────────────┐
│  AST (oxc)                                          │
│  TryStatement { block, handler?, finalizer? }       │
│  ThrowStatement { argument }                         │
└────────────────────┬────────────────────────────────┘
                     │ lowering
┌────────────────────▼────────────────────────────────┐
│  IR (Control Flow Graph + SSA)                      │
│  PushSeh / PopSeh / Throw / LoadException /         │
│  ResumeException                                     │
└────────────────────┬────────────────────────────────┘
                     │ codegen
┌────────────────────▼────────────────────────────────┐
│  Bytecode                                           │
│  Try / EndTry / ThrowExc / LoadException /          │
│  ResumeExc                                          │
└────────────────────┬────────────────────────────────┘
                     │ VM execution
┌────────────────────▼────────────────────────────────┐
│  VM                                                 │
│  SehRecord 栈,handle_throw(), jump()                │
└─────────────────────────────────────────────────────┘
```

---

## 2. Bytecode 指令

| 指令 | 操作数 | 语义 |
|------|--------|------|
| `Try` | `catch_offset, finally_offset, _` | 向 SEH 栈压入一个 handler 记录。`catch_offset` 和 `finally_offset` 是相对于当前 PC 的跳转偏移。 |
| `EndTry` | `_, _, _` | 弹出栈顶 SEH 记录(正常退出 try 块时调用)。 |
| `ThrowExc` | `src, _, _` | 抛出异常(支持 `Immd` 常量池索引或寄存器/栈值)。 |
| `LoadException` | `dst, _, _` | 将 `Rv` 寄存器中的异常值加载到 `dst`。 |
| `ResumeExc` | `_, _, _` | finally 块结束时调用。检查是否有待处理的异常,若有则决定跳转到 catch 或向外传播。 |

---

## 3. IR 指令

### PushSeh
```rust
PushSeh {
    handler: BlockId,       // catch 块(无 catch 时指向 finally)
    finally: Option<BlockId>, // finally 块
}
```

### PopSeh
```rust
PopSeh
```
在 IR 层面,`PopSeh` 出现在两个位置:
- try 体正常结束时(在跳转到 finally 之前)
- catch 体正常结束时(在跳转到 finally 或 after_finally 之前)

### Throw
```rust
Throw {
    value: Value,    // 异常值(支持 Variable / Constant / Primitive)
    args: Vec<Value>, // phi 参数(传递给 catch 块的参数值)
}
```
`Throw` 是终结指令,其后代码为死代码。`args` 用于 SSA phi 节点:catch 块的参数需要从 throw 块传递过来。

### LoadException
```rust
LoadException { dst: Value }
```
从 VM 的 `Rv` 寄存器读取异常值并存入 IR 变量。只在 catch 块内部使用。

### ResumeException
```rust
ResumeException { args: Vec<Value> }
```
finally 块结束时的"终结"指令。检查 `SehRecord.pending_exception`:
- **有异常且有未被执行的 catch** → 跳转到 catch(传递 args)
- **有异常但没有 catch** → 弹出 SEH,向外传播异常
- **无异常** → 继续执行(不弹出 SEH)

---

## 4. VM 执行

### SehRecord 结构
```rust
struct SehRecord {
    handler_pc: usize,              // catch 处理程序 PC(0 表示无 catch)
    finally_pc: usize,              // finally 处理程序 PC(0 表示无 finally)
    saved_rsp: usize,               // try 入口时的栈指针
    saved_rbp: usize,               // try 入口时的帧指针
    in_finally: bool,               // 是否正在执行 finally
    pending_exception: Option<Value>, // 进入 finally 时暂存的异常
    catch_executed: bool,           // catch 是否已执行过(防止重复捕获)
}
```

### handle_throw 逻辑

```
handle_throw(exc_val):
  1. 弹出栈顶 SehRecord
  2. 恢复 rsp, rbp 到 try 入口状态
  3. 如果有 finally 且未在执行 finally 中:
     → 标记 in_finally=true,暂存 pending_exception
     → 将 record 重新压栈
     → jump 到 finally_pc
  4. 否则如果有 catch:
     → 将 exc_val 写入 Rv 寄存器
     → jump 到 handler_pc
  5. 否则(无 catch,无 finally):
     → 递归 handle_throw(向外层传播)
  6. 如果 SEH 栈为空:
     → 返回 RuntimeError::Thrown(exc_val)
```

### ResumeExc 逻辑

```
ResumeExc:
  1. 如果栈顶 record 处于 in_finally 状态且有 pending_exception:
     a. 如果有真正的 catch(handler_pc ≠ 0 且 handler_pc ≠ finally_pc)
        且 catch 尚未执行过(!catch_executed):
        → 标记 catch_executed=true,清除 in_finally/pending_exception
        → 将异常写入 Rv,jump 到 handler_pc
     b. 否则:
        → 弹出 SEH record,递归 handle_throw(向外传播)
  2. 否则如果 in_finally 但无 pending_exception:
     → 清除 in_finally 标志(正常结束,不弹出 SEH)
```

### 设计要点

1. **handler_pc == finally_pc 的情况**:当 `try-finally`(无 catch)时,lowering 会将 `handler` 设为 `finally`,此时 handler_pc == finally_pc。`ResumeExc` 通过 `has_real_catch = handler_pc != 0 && handler_pc != finally_pc` 区分这种情况,避免异常被"捕获"到 finally 自身。

2. **catch_executed 标志**:防止 `catch` 块中抛出新异常后又回到同一 catch 的循环。这是嵌套 `try/catch/finally` 正确性的关键。

3. **栈帧恢复**:进入异常处理时,rsp/rbp 恢复到 try 入口点,这意味着 finally 和 catch 块在 try 的"栈帧上下文"中执行。

---

## 5. Control Flow 设计

### 正常流(无异常)

```
    PushSeh
    ┌─────────────────────┐
    │  try body           │
    └─────────┬───────────┘
              │ (正常结束)
              ▼
         PopSeh
              │
    ┌─────────▼───────────┐
    │  finally (如果存在)  │──ResumeExc(无待处理异常)──▶ after_finally
    └─────────────────────┘
```

### 异常流(try 体抛异常,有 catch + finally)

```
    throw "error"
         │
    ┌────▼─────────────────────────────┐
    │ handle_throw:                    │
    │   1. 发现 finally,暂存异常       │
    │   2. jump → finally              │
    └────┬─────────────────────────────┘
         ▼
    ┌─────────────────────┐
    │  finally body       │
    └─────────┬───────────┘
              │ ResumeExc(有 pending exception,catch 未执行)
              ▼
    ┌─────────────────────┐
    │  catch body         │──LoadException 读取 Rv
    └─────────┬───────────┘
              │ (正常结束)
              ▼
         PopSeh
              │
    ┌─────────▼───────────┐
    │  finally (再次执行)  │──ResumeExc(无待处理异常)──▶ after_finally
    └─────────────────────┘
```

### 异常流(catch 体抛异常,嵌套场景)

```
    inner throw "inner"
         │
    ┌────▼─────────────────────────────────────────┐
    │ handle_throw → finally → ResumeExc            │
    │ (有 catch 且未执行) → jump to inner catch     │
    └────┬──────────────────────────────────────────┘
         ▼
    inner catch: result = 1; throw "outer"
         │
    ┌────▼──────────────────────────────────────────┐
    │ handle_throw:                                 │
    │   内层 SehRecord.catch_executed 被 ResumeExc   │
    │   设为 true(第1次),但当前是新的异常           │
    │   发现 finally → jump to finally              │
    └────┬──────────────────────────────────────────┘
         ▼
    inner finally (再次执行,result += 10)
         │
    ┌────▼──────────────────────────────────────────┐
    │ ResumeExc:                                    │
    │   pending="outer", catch_executed=true        │
    │   → 弹出内层 SEH,handle_throw("outer")       │
    └────┬──────────────────────────────────────────┘
         ▼
    outer catch: result += 100
         │
    result = 111 ✓
```

---

## 6. Lowering 策略

[`lower_try`](src/compiler/lowering/mod.rs#L411) 生成以下控制流结构:

```rust
fn lower_try(try_stmt):
    // 创建基本块
    try_body    = create_block("try_body")
    catch_blk   = create_block("catch")
    finally_blk = create_block("finally")
    after_finally = create_block("after_finally")

    // SEH 处理器:catch 优先,否则 finally
    seh_handler = has_catch ? catch_blk : finally_blk
    seh_finally = has_finally ? Some(finally_blk) : None

    // 1. 注册 SEH handler + 添加异常边
    push_seh(seh_handler, seh_finally)
    add_exception_edge(try_body, seh_handler)
    if has_finally: add_exception_edge(try_body, finally_blk)
    jump(try_body)

    // 2. Try 体
    switch_to_block(try_body)
    lower_statements(try_stmt.block.body)
    if not terminated:
        pop_seh()                    // 正常退出,注销 SEH
        if has_finally: jump(finally_blk)
        else: jump(after_finally)

    // 3. Catch 块(如果有)
    if has_catch:
        switch_to_block(catch_blk)
        exc_val = load_exception()   // 从 Rv 读取异常值
        lower_statements(catch_clause.body)
        if not terminated:
            pop_seh()                // 正常退出 catch
            if has_finally: jump(finally_blk)
            else: jump(after_finally)

    // 4. Finally 块(如果有)
    if has_finally:
        switch_to_block(finally_blk)
        lower_statements(finalizer.body)
        if not terminated:
            resume_exception()       // 检查待处理异常
            jump(after_finally)

    switch_to_block(after_finally)
```

**关键设计决策**:
- `PopSeh` 不在 catch 入口执行,而是由 **ResumeExc** 在 finally 结束后处理 SEH 弹出
- `add_exception_edge` 为 SSA builder 提供 CFG 边,确保异常路径上的变量可见性

---

## 7. SSA 异常边处理

[`SSABuilder::add_exception_edges_for_throws`](src/compiler/ir/ssabuilder.rs#L74) 负责为所有异常路径建立 CFG 边:

1. **Throw 指令**:扫描当前 SEH 作用域栈,为每个 `(catch_handler, finally_handler)` 添加异常边
2. **ResumeException 指令**:使用预记录的外层 SEH 作用域(`finally_outer_scope`)为 finally 块的 ResumeException 添加向外层 catch 的边

```
finally_outer_scope[finally_blk] = seh_scope_before_push
  ↑ 在 PushSeh 时记录

ResumeException 出现时:
  for (catch_handler, _) in finally_outer_scope[block]:
      add_edge(block, catch_handler)
```

这确保了 finally 中写入的变量通过 SSA phi 节点正确传递到外层 catch。

---

## 8. 测试覆盖

### 单元测试(13个核心场景)

**基本异常处理(8个)**

| 测试 | 场景 | 预期 |
|------|------|------|
| `try_catch` | 基本 throw → catch | result = 1 |
| `try_catch_finally` | throw → catch → finally | result = 11 |
| `try_finally_no_throw` | 正常执行 + finally | result = 11 |
| `try_catch_finally_no_throw` | 正常 try(无 throw)+ finally | result = 11 |
| `try_finally_with_throw` | 内层 try-finally + 外层 catch | result = 11 |
| `nested_try_catch_finally` | 嵌套 try/catch/finally,catch 中再次 throw | result = 111 |
| `try_finally_propagate` | finally 后异常传播到外层 catch | result = 11 |
| `try_finally_propagate_no_catch_body` | finally 后传播,外层 catch 无操作 | result = 1 |

**break/continue + finally(2个)**

| 测试 | 场景 | 预期 |
|------|------|------|
| `break_in_try_finally` | break 在 try-finally 中执行 | result = 20 |
| `continue_in_try_finally` | continue 在 try-finally 中执行 | result = 3 |

**return + finally(5个)**

| 测试 | 场景 | 预期 |
|------|------|------|
| `return_in_try_finally` | return 在 try-finally 中执行 | 返回值 = 1 |
| `return_in_try_finally_with_result_modification` | finally 修改变量不影响返回值 | 返回值 = 5 |
| `return_in_try_finally_nested` | 嵌套 try-finally 中的 return | 返回值 = 1 |
| `return_in_catch_finally` | return 在 catch-finally 中执行 | 返回值 = 2 |
| `return_in_try_catch_finally_no_throw` | 无异常时的 return | 返回值 = 3 |

### test262 测试套件

| 测试套件 | 数量 | 说明 |
|----------|------|------|
| `language/statements/try` | 54 | try-catch-finally 语句测试 |
| `built-ins/Error` | 93 | Error 构造器和原型测试 |
| `built-ins/NativeErrors` | 94 | TypeError, ReferenceError, RangeError 等测试 |

**测试状态**:
- 大部分 test262 测试被跳过(使用 `var`、`eval`、`arguments` 等不支持特性)
- 核心异常处理逻辑测试通过
- Error 对象原型链测试通过(支持 `instanceof`)

---

## 9. 实现状态更新

### ✅ 已实现的特性

| 特性 | 状态 | 说明 |
|------|------|------|
| Error 类型对象 | ✅ | 所有标准 Error 类型已实现:Error, TypeError, ReferenceError, RangeError, URIError, EvalError |
| 异常对象原型链 | ✅ | Error.prototype 及子类型原型链已建立,支持 `instanceof` 检测 |
| break/continue 与 finally | ✅ | 通过 DelayedJump 机制实现,break/continue 会先执行所有 pending 的 finally 块 |
| return 与 finally | ✅ | 通过 `delayed_return` 标志实现,return 会先执行所有 pending 的 finally 块 |

### 🚧 待实现的特性

无。异常处理核心功能已全部实现。

### 实现细节:DelayedJump 机制(break/continue)

`break`/`continue` 在 try-finally 中的处理流程:

```
break/continue 目标
       │
       ▼
┌─────────────────────┐
│ DelayedJump         │  检查当前 SEH 栈中是否有未执行的 finally
│   - target: 偏移量   │  
│   - seh_depth: 深度  │
└─────────┬───────────┘
          │
    ┌─────┴─────┐
    ▼           ▼
有 finally    无 finally
    │           │
    ▼           ▼
执行 finally   直接跳转
    │
    ▼
ResumeExc 检查 delayed_jump_target
    │
    ▼
跳转到原始目标
```

### 实现细节:DelayedReturn 机制(return)

`return` 在 try-finally 中的处理流程:

```
return 语句
       │
       ▼
┌─────────────────────┐
│ Ret 指令            │  检查当前 SEH 栈中是否有未执行的 finally
│   - 返回值在 Rv 寄存器 │
└─────────┬───────────┘
          │
    ┌─────┴─────┐
    ▼           ▼
有 finally    无 finally
    │           │
    ▼           ▼
执行 finally   正常返回
    │
    ▼
ResumeExc 检查 delayed_return
    │
    ▼
弹出 SEH,继续返回(Rv 值保持不变)
```

**关键代码**(`src/vm/mod.rs:56-85`):

```rust
Opcode::Ret => {
    // Check if we need to execute any finally blocks before returning
    let mut finally_to_execute = None;
    for (idx, record) in self.state.seh_stack.iter().enumerate() {
        if record.finally_pc != 0 && !record.in_finally {
            finally_to_execute = Some(idx);
            break;
        }
    }

    if let Some(idx) = finally_to_execute {
        // Mark the record as in_finally and set delayed return flag
        if let Some(record) = self.state.seh_stack.get_mut(idx) {
            record.in_finally = true;
            record.delayed_return = true;
        }
        let finally_pc = self.state.seh_stack[idx].finally_pc;
        self.state.jump(finally_pc);
    } else {
        // No pending finally blocks, proceed with normal return
        // ... normal return logic
    }
}
```

**ResumeExc 处理 delayed_return**(`src/vm/mod.rs:1010-1016`):

```rust
} else if delayed_return {
    // Delayed return after finally execution
    self.state.seh_stack.pop();
    // Continue to normal return flow - re-execute Ret opcode
    // The return value is already in Rv
    return Ok(());
}
```

```rust
Opcode::DelayedJump => {
    let offset = operands[0].as_immd();
    let seh_depth = operands[1].as_immd() as usize;

    // 检查是否需要执行 finally 块
    let mut finally_to_execute = None;
    let stack_len = self.state.seh_stack.len();
    let start_idx = stack_len.saturating_sub(seh_depth);
    
    for idx in start_idx..stack_len {
        if let Some(record) = self.state.seh_stack.get(idx) {
            if record.finally_pc != 0 && !record.in_finally {
                finally_to_execute = Some((idx, record.finally_pc));
                break;
            }
        }
    }

    if let Some((idx, finally_pc)) = finally_to_execute {
        // 标记 in_finally 并设置延迟跳转目标
        if let Some(record) = self.state.seh_stack.get_mut(idx) {
            record.in_finally = true;
            record.delayed_jump_target = Some(offset);
        }
        self.state.jump(finally_pc);
    } else {
        // 所有 finally 执行完毕,直接跳转
        self.state.jump_offset(offset);
    }
}
```

### return + finally 的实现计划

需要修改 `Opcode::Ret` 的处理逻辑:

```rust
Opcode::Ret => {
    // 1. 检查是否有 pending 的 finally 块
    // 2. 如果有,保存返回值到特殊寄存器
    // 3. 执行 finally 链
    // 4. finally 结束后恢复返回值并真正返回
}
```

这需要:
- 新增 `ReturnValue` 寄存器或栈槽保存延迟返回值
- 修改 `ResumeExc` 处理 return 场景(无异常但有延迟返回值)
- Lowering 阶段生成不同的 return 路径(在 SEH 作用域内 vs 外)