# 中间表示生成器

<cite>
**本文档引用的文件**
- [src/lib.rs](file://src/lib.rs)
- [src/codegen.rs](file://src/codegen.rs)
- [src/swc_transform.rs](file://src/swc_transform.rs)
- [runtime/src/lib.rs](file://runtime/src/lib.rs)
- [src/main.rs](file://src/main.rs)
- [src/project_compiler.rs](file://src/project_compiler.rs)
- [src/standalone_gen.rs](file://src/standalone_gen.rs)
- [Cargo.toml](file://Cargo.toml)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 ts-native 的中间表示生成器，系统性阐述 HIR（高阶中间表示）的数据结构设计、NaN-boxing 值系统与类型系统实现、表达式与语句的 HIR 表示及控制流处理、以及中间表示转换流程与性能优化策略。文档同时给出代码级可视化图示与路径引用，帮助读者快速定位实现细节。

## 项目结构
ts-native 采用模块化组织，核心编译管线分为三部分：
- 词法/语法解析与 HIR 构建：由 SWC AST 转换为 HIR
- 中间表示生成与优化：Cranelift IR 生成与链接
- 运行时支撑：基于 NaN-tagging 的值系统与内置运行时函数

```mermaid
graph TB
A["输入 TypeScript 源码"] --> B["SWC 解析器<br/>构建 AST"]
B --> C["SWC 转换器<br/>生成 HIR"]
C --> D["代码生成器<br/>Cranelift IR"]
D --> E["COFF 对象文件"]
E --> F["运行时库<br/>NaN-tagging 值系统"]
F --> G["独立可执行/动态库"]
```

图表来源
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:521-604](file://src/codegen.rs#L521-L604)
- [runtime/src/lib.rs:1-20](file://runtime/src/lib.rs#L1-L20)

章节来源
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [Cargo.toml:1-57](file://Cargo.toml#L1-L57)

## 核心组件
- HIR 数据结构：统一表达 TS/JS 语法树节点，涵盖字面量、标识符、二元/一元/三元表达式、调用、赋值、控制流、类/装饰器/生成器/异步等特性
- NaN-boxing 值系统：通过 IEEE 754 双精度浮点的 NaN payload 区域编码类型标签与指针，实现紧凑的统一值表示
- 类型系统与运行时：运行时提供类型判断、字符串池、数组/对象容器、Math/JSON/Object/RegExp 等内置函数
- 代码生成器：将 HIR 映射为 Cranelift IR，外层函数签名统一为 F64→F64，配合运行时函数完成复杂操作
- 独立可执行生成：将编译产物序列化为 .tsnobj，并在运行时通过重定位加载执行

章节来源
- [src/codegen.rs:80-196](file://src/codegen.rs#L80-L196)
- [runtime/src/lib.rs:7-24](file://runtime/src/lib.rs#L7-L24)
- [src/codegen.rs:451-520](file://src/codegen.rs#L451-L520)

## 架构总览
下图展示从 TypeScript 源码到最终可执行文件的关键步骤与模块交互。

```mermaid
sequenceDiagram
participant CLI as "命令行入口"
participant Parser as "SWC 转换器"
participant CG as "代码生成器"
participant RT as "运行时库"
participant EXE as "独立可执行"
CLI->>Parser : 读取并解析 TypeScript
Parser-->>CLI : 生成 HIR 列表
CLI->>CG : 传入 HIR 列表
CG->>CG : 收集函数签名/字符串常量
CG->>RT : 声明外部导入函数
CG-->>CLI : 生成 COFF 对象
CLI->>EXE : 生成独立可执行(.exe/.tsnobj)
EXE->>RT : 动态加载并重定位
EXE-->>CLI : 执行入口函数(main)
```

图表来源
- [src/main.rs:55-78](file://src/main.rs#L55-L78)
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:521-604](file://src/codegen.rs#L521-L604)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)

## 详细组件分析

### HIR 数据结构与表达式类型
HIR 使用枚举统一描述 TS/JS 语法节点，覆盖：
- 基础字面量：数字、布尔、字符串、null、undefined、正则
- 表达式：二元/一元/三元、调用、类型查询 typeof、赋值、索引/属性访问
- 控制流：函数、返回、变量声明、if/while/for、块、break/continue、序列表达式
- 复合结构：数组、对象、try/catch/finally、throw
- 类与装饰器：类定义、构造器、方法、属性、装饰器
- 生成器与异步：生成器函数、yield、异步函数、await

```mermaid
classDiagram
class HirExpr {
+Number(f64)
+Boolean(bool)
+String(String)
+Null
+Undefined
+Identifier(String)
+Binary(op, left, right)
+Unary(op, operand)
+Typeof(expr)
+Call(callee, args)
+Ternary(cond, then_expr, else_expr)
+Function(name, params, body)
+Return(opt)
+Var(name, init, is_mut)
+If(cond, then_body, else_body)
+While(cond, body)
+For(init, cond, update, body)
+Block(stmts)
+Break
+Continue
+Assign(target, value)
+Array(elements)
+Index(object, index)
+Object(props)
+Property(object, name)
+TryCatch(try_body, catch_param, catch_body, finally_body)
+Throw(opt)
+ExprStmt(expr)
+Seq(exprs)
+Regex(pattern, flags)
+RegexTest(regex, text)
+RegexExec(regex, text)
+RegexMatch(regex, text)
+Class(name, parent, constructor, methods, properties)
+New(class_name, args)
+This
+SuperMethod(method_name, args)
+Generator(name, params, body)
+Yield(value)
+YieldFrom(value)
+AsyncFunction(name, params, body)
+Await(promise)
+Decorator(target, target_type, name, args)
+DecoratedClass(...)
+DecoratedMethod(...)
}
```

图表来源
- [src/codegen.rs:80-196](file://src/codegen.rs#L80-L196)

章节来源
- [src/codegen.rs:80-196](file://src/codegen.rs#L80-L196)

### NaN-boxing 值系统与类型系统
- 值编码：使用 IEEE 754 双精度浮点的 NaN payload 区域存放类型标签与数据指针，实现统一 64 位值表示
- 标签定义：数字、字符串、对象、布尔、未定义、空、函数、数组等标签位
- 运行时函数：提供类型判断、字符串池、数组/对象容器、Math/JSON/Object/RegExp 等内置能力
- 编译期辅助：编译器通过 is_truthy 等辅助函数将 NaN-tagged 值转换为布尔条件

```mermaid
flowchart TD
Start(["进入 is_truthy"]) --> Cast["将 f64 值位宽转换为 i64"]
Cast --> ZeroCmp["与 0 比较"]
Cast --> FalseBits["与 FALSE 标签比较"]
ZeroCmp --> IsZero{"是否为 0"}
FalseBits --> IsFalse{"是否为 false 标签"}
IsZero --> Or["按位或得到 falsy 标识"]
IsFalse --> Or
Or --> Xor["与 1 异或得到 truthy 标识"]
Xor --> End(["返回 i8 布尔值"])
```

图表来源
- [src/codegen.rs:435-449](file://src/codegen.rs#L435-L449)
- [runtime/src/lib.rs:7-24](file://runtime/src/lib.rs#L7-L24)

章节来源
- [runtime/src/lib.rs:7-24](file://runtime/src/lib.rs#L7-L24)
- [src/codegen.rs:435-449](file://src/codegen.rs#L435-L449)

### 表达式与语句的 HIR 表示与控制流处理
- 表达式编译：递归编译子表达式，二元/一元/三元表达式映射到对应的运行时函数或 Cranelift 指令
- 控制流：if/else、while、for、for-in、for-of、switch、try/catch/finally、break/continue 等均转换为 Cranelift 基本块与分支指令
- 块与序列：块内最后语句返回值，序列表达式按顺序计算并返回最后一个值
- 赋值与属性：支持标识符、索引、属性三种目标，分别映射到不同的运行时函数

```mermaid
sequenceDiagram
participant C as "编译器"
participant B as "FunctionBuilder"
participant RT as "运行时函数"
C->>B : 创建 then/else/merge 基本块
C->>B : 计算条件值并转换为布尔
B-->>C : brif 分支
C->>B : 在 then 块编译 then 表达式
C->>B : jump 到 merge 块
C->>B : 在 else 块编译 else 表达式
C->>B : jump 到 merge 块
B-->>C : 合并 phi 值
```

图表来源
- [src/codegen.rs:2627-2652](file://src/codegen.rs#L2627-L2652)

章节来源
- [src/codegen.rs:1031-1105](file://src/codegen.rs#L1031-L1105)
- [src/codegen.rs:2627-2652](file://src/codegen.rs#L2627-L2652)

### 代码生成与 Cranelift IR
- 函数签名：统一为 F64 参数列表与返回值，便于与运行时函数对接
- 外部导入：通过 declare_import 声明并调用运行时函数，如数组/对象/字符串/数学/JSON/文件系统等
- 字符串常量：收集字符串并在数据段中定义，通过全局值引用
- 控制流：使用基本块与分支指令实现循环、条件与异常处理

```mermaid
sequenceDiagram
participant CG as "CodeGen"
participant OM as "ObjectModule"
participant FB as "FunctionBuilder"
participant RT as "运行时函数"
CG->>OM : 声明函数签名
CG->>FB : 初始化入口块
CG->>FB : 为参数创建变量
CG->>FB : 编译函数体
FB->>RT : 调用导入函数
RT-->>FB : 返回值
FB-->>CG : 返回 F64
```

图表来源
- [src/codegen.rs:896-950](file://src/codegen.rs#L896-L950)
- [src/codegen.rs:290-350](file://src/codegen.rs#L290-L350)

章节来源
- [src/codegen.rs:896-950](file://src/codegen.rs#L896-L950)
- [src/codegen.rs:290-350](file://src/codegen.rs#L290-L350)

### 从 AST 到 HIR 的转换规则
- 语句转换：块、if/else、while/for、try/catch/finally、switch、for-in/of 等转换为对应的 HIR 结构
- 表达式转换：二元/一元/三元、调用、索引/属性、typeof、赋值等转换为 HIR 表达式
- 类与装饰器：类定义、构造器、方法、属性、装饰器等转换为 HIR 的类/装饰器节点
- 默认参数与剩余参数：转换为 if 检查与数组切片等 HIR 序列

```mermaid
flowchart TD
A["AST 节点"] --> B{"节点类型？"}
B --> |语句| S["转换为 HIR 语句"]
B --> |表达式| E["转换为 HIR 表达式"]
B --> |声明| D["转换为 HIR 声明/类/装饰器"]
S --> C["收集 ImportBinding"]
E --> C
D --> C
C --> O["输出 HIR 列表"]
```

图表来源
- [src/swc_transform.rs:36-176](file://src/swc_transform.rs#L36-L176)
- [src/swc_transform.rs:182-349](file://src/swc_transform.rs#L182-L349)

章节来源
- [src/swc_transform.rs:36-176](file://src/swc_transform.rs#L36-L176)
- [src/swc_transform.rs:182-349](file://src/swc_transform.rs#L182-L349)

### 中间表示转换流程与性能考虑
- 流程概览：解析 → HIR → 代码生成 → COFF → 独立可执行
- 性能要点：
  - 统一 F64 ABI，减少 ABI 调用开销
  - 字符串池与对象池复用，降低 GC 压力
  - 外部导入函数按需声明，避免不必要的链接
  - 控制流优化：条件分支、循环展开与跳转优化
  - 重定位应用：在运行时进行，保证可移植性

章节来源
- [src/codegen.rs:521-604](file://src/codegen.rs#L521-L604)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)

## 依赖关系分析
- Cranelift 生态：cranelift-frontend/module/object/native 用于 IR 生成与对象文件输出
- SWC：swc_ecma_parser/ast/visit 用于 TypeScript/JavaScript 解析与 AST 遍历
- object：用于从 COFF 中解析节、符号与重定位
- 运行时：tsn_runtime.dll 提供值系统与内置函数

```mermaid
graph TB
A["ts-native"] --> B["cranelift-*"]
A --> C["swc-*"]
A --> D["object"]
A --> E["tsn_runtime.dll"]
```

图表来源
- [Cargo.toml:36-46](file://Cargo.toml#L36-L46)

章节来源
- [Cargo.toml:36-46](file://Cargo.toml#L36-L46)

## 性能考量
- NaN-boxing 值系统：以 64 位统一承载多种类型，减少装箱/拆箱成本
- 运行时函数：将复杂操作下沉至运行时，编译器保持轻量
- Cranelift 优化：利用寄存器分配与指令选择，减少分支与内存访问
- 字符串与对象池：共享字符串与对象，降低重复分配
- 外部导入缓存：避免重复声明导入函数

## 故障排查指南
- 未定义符号：确认运行时函数名称与签名一致，检查 declare_import 是否成功
- 类型错误：检查 is_truthy 与类型判断逻辑，确保 NaN-tagging 正确
- 控制流异常：核对基本块创建与分支指令，确保合并块的 phi 值正确
- 重定位失败：检查符号表与重定位目标名称，确认运行时 DLL 可加载

章节来源
- [src/codegen.rs:290-350](file://src/codegen.rs#L290-L350)
- [runtime/src/lib.rs:404-421](file://runtime/src/lib.rs#L404-L421)
- [src/standalone_gen.rs:175-240](file://src/standalone_gen.rs#L175-L240)

## 结论
ts-native 的中间表示生成器通过 HIR 统一表达 TS/JS 语法，结合 NaN-boxing 值系统与 Cranelift IR，实现了高效的本地代码生成与运行时支撑。其模块化设计与清晰的控制流映射，使得从 AST 到可执行文件的转换过程既可维护又具备良好的性能表现。

## 附录
- 示例路径参考（不含具体代码内容）：
  - HIR 表达式定义：[src/codegen.rs:80-196](file://src/codegen.rs#L80-L196)
  - 表达式编译主流程：[src/codegen.rs:1365-2952](file://src/codegen.rs#L1365-L2952)
  - 语句编译流程（控制流）：[src/codegen.rs:1031-1105](file://src/codegen.rs#L1031-L1105)
  - AST 到 HIR 转换：[src/swc_transform.rs:36-176](file://src/swc_transform.rs#L36-L176)
  - 运行时类型系统与值编码：[runtime/src/lib.rs:7-24](file://runtime/src/lib.rs#L7-L24)
  - 代码生成与 COFF 输出：[src/codegen.rs:521-604](file://src/codegen.rs#L521-L604)
  - 独立可执行生成与重定位：[src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)