# TypeScript 解析器

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

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

## 简介

ts-native 是一个将 TypeScript 源代码直接编译为本地机器码的编译器。该项目采用 SWC 作为 TypeScript 解析器，结合 Cranelift JIT 编译器，将 TypeScript 代码转换为高效的本地可执行文件。

该编译器的核心特性包括：
- 基于 SWC 的 TypeScript 语法解析
- HIR（高层中间表示）转换
- Cranelift JIT 编译器生成本地代码
- 支持模块系统和依赖管理
- 提供多种执行模式（直接执行、独立可执行文件）

## 项目结构

项目采用模块化设计，主要包含以下核心模块：

```mermaid
graph TB
subgraph "核心编译器"
A[src/main.rs] --> B[src/swc_transform.rs]
B --> C[src/codegen.rs]
C --> D[src/coff.rs]
end
subgraph "项目管理"
E[src/project.rs] --> F[src/dep_graph.rs]
F --> G[src/project_compiler.rs]
end
subgraph "运行时支持"
H[runtime/src/lib.rs] --> I[loader/src/main.rs]
J[src/standalone_gen.rs] --> I
end
K[Cargo.toml] --> A
K --> E
K --> H
```

**图表来源**
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [src/swc_transform.rs:1-800](file://src/swc_transform.rs#L1-L800)
- [src/codegen.rs:1-800](file://src/codegen.rs#L1-L800)
- [src/project.rs:1-461](file://src/project.rs#L1-L461)

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

## 核心组件

### SWC 集成配置

项目使用 SWC 5.x API 进行 TypeScript 解析，配置如下：

```mermaid
classDiagram
class SyntaxConfig {
+bool tsx
+bool decorators
+bool dts
+bool no_early_errors
+bool disallow_ambiguous_jsx_like
}
class ParserConfig {
+Syntax syntax
+EsVersion version
+StringInput input
+Option<Module> module
}
class SWCIntegration {
+parse(source : &str) Result~Vec~HirExpr~~
+transform_module(module : &Module) Result~Vec~HirExpr~~
+transform_expr(expr : &Expr) Result~HirExpr~
}
SyntaxConfig --> ParserConfig : "配置"
ParserConfig --> SWCIntegration : "使用"
```

**图表来源**
- [src/swc_transform.rs:17-34](file://src/swc_transform.rs#L17-L34)

### HIR 转换机制

项目实现了完整的 HIR（高层中间表示）转换，支持以下语法结构：

```mermaid
classDiagram
class HirExpr {
<<enumeration>>
Number(f64)
Boolean(bool)
String(String)
Identifier(String)
Binary(BinOp, Box~HirExpr~, Box~HirExpr~)
Unary(UnaryOp, Box~HirExpr~)
Function(String, Vec~String~, Vec~HirExpr~)
Call(Box~HirExpr~, Vec~HirExpr~)
If(Box~HirExpr~, Vec~HirExpr~, Option~Vec~HirExpr~~)
For(Option~Box~HirExpr~~, Option~Box~HirExpr~~, Option~Box~HirExpr~~, Vec~HirExpr~)
While(Box~HirExpr~, Vec~HirExpr~)
Var(String, Option~Box~HirExpr~~, bool)
Assign(Box~HirExpr~, Box~HirExpr~)
Array(Vec~HirExpr~)
Object(Vec~(String, HirExpr)~)
ImportBinding(String, String, String)
}
class BinOp {
<<enumeration>>
Add, Sub, Mul, Div, Mod
Eq, Ne, Lt, Le, Gt, Ge
And, Or, BitAnd, BitOr, BitXor
Shl, Shr
}
class UnaryOp {
<<enumeration>>
Not, Neg, PreInc, PreDec, PostInc, PostDec
}
```

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

**章节来源**
- [src/swc_transform.rs:10-176](file://src/swc_transform.rs#L10-L176)
- [src/codegen.rs:80-196](file://src/codegen.rs#L80-L196)

## 架构概览

项目采用分层架构设计，从 TypeScript 源码到本地可执行文件的完整流程如下：

```mermaid
sequenceDiagram
participant TS as "TypeScript 源码"
participant SWC as "SWC 解析器"
participant HIR as "HIR 转换器"
participant CG as "Cranelift 代码生成器"
participant COFF as "COFF 对象文件"
participant RUNTIME as "运行时环境"
TS->>SWC : 读取并解析 TypeScript
SWC->>HIR : 生成 AST
HIR->>HIR : 转换为 HIR 表达式
HIR->>CG : 生成 IR
CG->>COFF : 编译为机器码
COFF->>RUNTIME : 加载并执行
Note over SWC,HIR : SWC 集成配置<br/>TS 语法支持
Note over CG,COFF : Cranelift JIT 编译<br/>本地代码生成
Note over RUNTIME : NaN-tagging 类型系统<br/>JavaScript 运行时函数
```

**图表来源**
- [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:520-604](file://src/codegen.rs#L520-L604)

## 详细组件分析

### SWC 解析器集成

#### TypeScript 语法支持范围

项目支持的 TypeScript 语法特性包括：

| 语法特性 | 支持状态 | 实现详情 |
|---------|---------|----------|
| 基本类型 | ✅ 完整支持 | number, string, boolean, null, undefined |
| 函数声明 | ✅ 完整支持 | function, arrow functions, async/await |
| 类声明 | ✅ 部分支持 | 构造函数、方法、属性 |
| 模块系统 | ✅ 完整支持 | import/export, default/named imports |
| 泛型 | ⚠️ 有限支持 | 基本泛型语法解析 |
| 装饰器 | ✅ 支持 | decorators: true 配置 |
| JSX | ❌ 不支持 | tsx: false 配置 |

#### 模块导入处理

```mermaid
flowchart TD
A["导入声明"] --> B{"导入类型"}
B --> |默认导入| C["ImportBinding<br/>local: 模块名<br/>module: 模块路径<br/>imported: 'default'"]
B --> |命名导入| D["ImportBinding<br/>local: 本地别名<br/>module: 模块路径<br/>imported: 导入名称"]
B --> |命名空间导入| E["ImportBinding<br/>local: 命名空间<br/>module: 模块路径<br/>imported: '*'"]
B --> |相对路径导入| F["相对路径解析<br/>基于项目根目录"]
B --> |绝对路径导入| G["用户模块优先<br/>项目内模块 > 内置模块"]
F --> H["路径规范化"]
G --> H
H --> I["模块解析完成"]
```

**图表来源**
- [src/swc_transform.rs:60-104](file://src/swc_transform.rs#L60-L104)
- [src/project.rs:204-257](file://src/project.rs#L204-L257)

#### 函数声明转换

```mermaid
sequenceDiagram
participant DECL as "函数声明"
participant TRANS as "转换器"
participant PARAM as "参数提取"
participant BODY as "主体转换"
participant FUNC as "函数表达式"
DECL->>TRANS : FnDecl/FnExpr
TRANS->>PARAM : extract_params()
PARAM->>PARAM : 处理默认参数
PARAM->>PARAM : 处理剩余参数
TRANS->>BODY : transform_block_stmts()
BODY->>FUNC : 创建 Function 表达式
FUNC->>TRANS : 返回函数定义
```

**图表来源**
- [src/swc_transform.rs:375-394](file://src/swc_transform.rs#L375-L394)
- [src/swc_transform.rs:510-561](file://src/swc_transform.rs#L510-L561)

**章节来源**
- [src/swc_transform.rs:17-176](file://src/swc_transform.rs#L17-L176)

### HIR 转换机制

#### 表达式解析

项目实现了完整的表达式解析器，支持以下操作：

```mermaid
classDiagram
class ExpressionTransformer {
+transform_expr(expr : &Expr) Result~HirExpr~
+transform_stmt(stmt : &Stmt) Result~Option~HirExpr~~
+transform_decl(decl : &Decl) Result~Option~HirExpr~~
}
class LiteralTransformer {
+transform_lit(lit : &Lit) HirExpr
+transform_number(n : f64) HirExpr
+transform_string(s : String) HirExpr
+transform_boolean(b : bool) HirExpr
}
class ControlFlowTransformer {
+transform_if(stmt : &IfStmt) HirExpr
+transform_while(stmt : &WhileStmt) HirExpr
+transform_for(stmt : &ForStmt) HirExpr
+transform_switch(stmt : &SwitchStmt) HirExpr
}
ExpressionTransformer --> LiteralTransformer : "委托"
ExpressionTransformer --> ControlFlowTransformer : "委托"
```

**图表来源**
- [src/swc_transform.rs:761-760](file://src/swc_transform.rs#L761-L760)
- [src/swc_transform.rs:182-349](file://src/swc_transform.rs#L182-L349)

#### 类型系统支持

项目采用 NaN-tagging 类型系统，支持以下 JavaScript 原生类型：

| 类型 | 标签值 | 用途 |
|------|--------|------|
| Number | 0x7FF0 | 数字类型 |
| String | 0x7FF1 | 字符串类型 |
| Object | 0x7FF2 | 对象类型 |
| Boolean | 0x7FF3 | 布尔类型 |
| Undefined | 0x7FF4 | 未定义类型 |
| Null | 0x7FF5 | 空类型 |
| Function | 0x7FF6 | 函数类型 |
| Array | 0x7FF7 | 数组类型 |

**章节来源**
- [src/codegen.rs:45-53](file://src/codegen.rs#L45-L53)
- [runtime/src/lib.rs:7-20](file://runtime/src/lib.rs#L7-L20)

### 代码生成器

#### Cranelift 集成

项目使用 Cranelift 0.93.2 JIT 编译器进行代码生成：

```mermaid
flowchart TD
A["HIR 表达式"] --> B["Cranelift Signature"]
B --> C["Function Builder"]
C --> D["Instruction Builder"]
D --> E["Machine Code"]
E --> F["COFF 对象文件"]
B --> G["参数类型检查"]
C --> H["变量分配"]
D --> I["指令优化"]
F --> J["重定位处理"]
```

**图表来源**
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)

#### 代码生成配置

```mermaid
classDiagram
class CodeGenConfig {
+settings : : builder() FlagBuilder
+cranelift_native : : builder() ISA
+ObjectBuilder : : new() ObjectModule
}
class CodeGen {
+compile_coff(exprs : &[HirExpr]) Result~Vec~u8~~
+compile_function(name : &str, params : &[String], body : &[HirExpr]) Result~Vec~u8~~
+collect_strings(expr : &HirExpr)
}
CodeGenConfig --> CodeGen : "配置"
```

**图表来源**
- [src/codegen.rs:520-537](file://src/codegen.rs#L520-L537)

**章节来源**
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)

### 项目编译器

#### 多模块支持

项目编译器支持复杂的多模块项目：

```mermaid
sequenceDiagram
participant PC as "项目编译器"
participant PJ as "项目发现"
participant DG as "依赖图"
participant MC as "模块编译"
participant SG as "独立生成器"
PC->>PJ : 从目录创建项目
PJ->>DG : 构建依赖图
DG->>MC : 按拓扑顺序编译
MC->>SG : 生成独立可执行文件
SG->>PC : 返回编译结果
```

**图表来源**
- [src/project_compiler.rs:205-332](file://src/project_compiler.rs#L205-L332)

#### 依赖管理

```mermaid
classDiagram
class DepGraph {
+nodes : HashMap~PathBuf, ModuleNode~
+entry_closures : HashMap~PathBuf, Vec~PathBuf~~
+compile_order : Vec~PathBuf~
+from_project(project : &mut Project) Result~DepGraph~
+topological_sort(nodes : &HashMap) Result~Vec~PathBuf~~
+compute_closure(start : &Path, nodes : &HashMap) Vec~PathBuf~
}
class ModuleNode {
+path : PathBuf
+module_name : String
+exports : HashSet~String~
+imports : HashMap~PathBuf, Vec~String~~
+deps : Vec~PathBuf~
+reverse_deps : Vec~PathBuf~
+level : usize
+is_entry : bool
}
DepGraph --> ModuleNode : "包含"
```

**图表来源**
- [src/dep_graph.rs:32-41](file://src/dep_graph.rs#L32-L41)
- [src/dep_graph.rs:11-30](file://src/dep_graph.rs#L11-L30)

**章节来源**
- [src/project_compiler.rs:205-332](file://src/project_compiler.rs#L205-L332)
- [src/dep_graph.rs:43-132](file://src/dep_graph.rs#L43-L132)

### 运行时环境

#### 加载器架构

```mermaid
flowchart TD
A["tsn-loader"] --> B{"执行模式"}
B --> |COFF 文件| C["load_and_run_coff_file"]
B --> |TypeScript 源码| D["调用 ts-native.dll"]
C --> E["解析 COFF 文件"]
E --> F["分配内存"]
F --> G["应用重定位"]
G --> H["执行入口函数"]
D --> I["编译 TypeScript"]
I --> J["生成 COFF"]
J --> K["执行代码"]
```

**图表来源**
- [loader/src/main.rs:42-127](file://loader/src/main.rs#L42-L127)

#### 运行时函数

项目提供了丰富的 JavaScript 运行时函数：

```mermaid
classDiagram
class RuntimeFunctions {
<<interface>>
+js_print(value : f64) f64
+js_add(a : f64, b : f64) f64
+js_array_new(capacity : f64) f64
+js_object_new() f64
+js_fs_read_file_sync(path : f64) f64
+js_json_stringify(value : f64) f64
}
class NanTagging {
+TAG_NUMBER : u64
+TAG_STRING : u64
+TAG_OBJECT : u64
+store_value(value : T) f64
+extract_value(bits : f64) T
}
RuntimeFunctions --> NanTagging : "使用"
```

**图表来源**
- [runtime/src/lib.rs:137-200](file://runtime/src/lib.rs#L137-L200)
- [runtime/src/lib.rs:41-60](file://runtime/src/lib.rs#L41-L60)

**章节来源**
- [loader/src/main.rs:42-127](file://loader/src/main.rs#L42-L127)
- [runtime/src/lib.rs:137-200](file://runtime/src/lib.rs#L137-L200)

## 依赖关系分析

### 外部依赖

项目的主要外部依赖包括：

```mermaid
graph TB
subgraph "核心依赖"
A[swc_common 5.0.1]
B[swc_ecma_ast 5.0.0]
C[swc_ecma_parser 7.0.0]
D[cranelift-frontend 0.93.2]
E[cranelift-object 0.93.2]
end
subgraph "工具链"
F[serde 1.0.197]
G[serde_json 1.0.114]
H[object 0.29]
I[clap 4.5]
end
subgraph "运行时"
J[tsn_runtime.dll]
K[Windows API]
end
A --> B
B --> C
D --> E
F --> G
H --> I
```

**图表来源**
- [Cargo.toml:22-57](file://Cargo.toml#L22-L57)

### 内部模块依赖

```mermaid
graph LR
A[src/main.rs] --> B[src/swc_transform.rs]
B --> C[src/codegen.rs]
C --> D[src/coff.rs]
E[src/project.rs] --> F[src/dep_graph.rs]
F --> G[src/project_compiler.rs]
H[src/standalone_gen.rs] --> I[loader/src/main.rs]
J[runtime/src/lib.rs] --> I
K[Cargo.toml] --> A
K --> E
K --> J
```

**图表来源**
- [src/lib.rs:4-16](file://src/lib.rs#L4-L16)

**章节来源**
- [Cargo.toml:22-57](file://Cargo.toml#L22-L57)
- [src/lib.rs:4-16](file://src/lib.rs#L4-L16)

## 性能考虑

### 编译性能优化

项目采用了多项性能优化策略：

1. **增量编译**：支持模块级别的增量编译，避免重复编译
2. **并行处理**：利用多核 CPU 进行并行编译
3. **内存池**：使用内存池减少垃圾回收开销
4. **JIT 优化**：Cranelift 编译器的即时优化

### 运行时性能

```mermaid
flowchart TD
A["编译时优化"] --> B["Cranelift IR 优化"]
B --> C["机器码生成"]
C --> D["运行时性能"]
E["NaN-tagging"] --> F["快速类型检查"]
F --> G["零成本抽象"]
H["内存管理"] --> I["栈分配"]
I --> J["寄存器优化"]
K["函数调用"] --> L["内联优化"]
L --> M["尾调用优化"]
```

**图表来源**
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)
- [runtime/src/lib.rs:21-35](file://runtime/src/lib.rs#L21-L35)

## 故障排除指南

### 常见问题及解决方案

#### 编译错误

| 错误类型 | 可能原因 | 解决方案 |
|---------|---------|----------|
| 语法错误 | TypeScript 语法不支持 | 检查 TypeScript 语法兼容性 |
| 依赖错误 | 模块导入失败 | 验证模块路径和导入语法 |
| 类型错误 | HIR 转换异常 | 检查类型推断和转换逻辑 |
| 运行时错误 | NaN-tagging 类型不匹配 | 验证类型标签和值转换 |

#### 性能问题

```mermaid
flowchart TD
A["性能问题"] --> B{"问题类型"}
B --> |编译慢| C["检查增量编译配置"]
B --> |内存高| D["优化内存池使用"]
B --> |运行慢| E["启用 JIT 优化"]
C --> F["清理未使用的模块"]
D --> G["减少对象分配"]
E --> H["启用 Cranelift 优化"]
```

**图表来源**
- [src/project_compiler.rs:54-121](file://src/project_compiler.rs#L54-L121)

#### 调试技巧

1. **启用详细日志**：使用 `-v` 或 `--verbose` 参数
2. **查看中间产物**：检查生成的 IR 和汇编代码
3. **性能分析**：使用编译统计信息分析瓶颈
4. **单元测试**：运行测试套件验证功能正确性

**章节来源**
- [loader/src/main.rs:17-40](file://loader/src/main.rs#L17-L40)
- [src/project_compiler.rs:54-121](file://src/project_compiler.rs#L54-L121)

## 结论

ts-native 提供了一个完整的 TypeScript 到本地代码的编译解决方案。通过 SWC 的高性能解析、HIR 的中间表示转换和 Cranelift 的 JIT 编译，项目实现了从 TypeScript 源码到高效本地可执行文件的完整流程。

主要优势包括：
- **高性能**：直接编译为本地机器码，避免解释执行开销
- **类型安全**：保持 TypeScript 的类型系统优势
- **模块化**：支持复杂的多模块项目管理
- **跨平台**：基于 Cranelift 的可移植性设计

未来发展方向：
- 扩展 TypeScript 语法支持
- 优化编译性能和内存使用
- 增强调试和诊断工具
- 支持更多运行时 API