# 核心组件

<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/coff.rs](file://src/coff.rs)
- [src/project_compiler.rs](file://src/project_compiler.rs)
- [src/dep_graph.rs](file://src/dep_graph.rs)
- [src/project.rs](file://src/project.rs)
- [src/standalone_gen.rs](file://src/standalone_gen.rs)
- [src/standalone_loader.rs](file://src/standalone_loader.rs)
- [src/native_linker.rs](file://src/native_linker.rs)
- [Cargo.toml](file://Cargo.toml)
</cite>

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

## 简介
本文档面向 ts-native 编译器的核心组件，系统性梳理 TypeScript 解析器、中间表示生成器、代码生成器、COFF 对象文件处理器以及项目编译器等关键模块的职责、实现细节与协作方式。文档既提供面向初学者的循序讲解，也为有经验的开发者提供深入的技术细节与优化建议。

## 项目结构
仓库采用以"模块"为中心的组织方式，核心编译流程由命令行入口驱动，解析 TypeScript 源码，生成中间表示，再通过 Cranelift 生成 COFF 对象；随后可选择直接输出 .obj，或进一步生成独立可执行文件（内嵌 loader）。

```mermaid
graph TB
A["命令行入口<br/>src/main.rs"] --> B["SWC 解析器<br/>src/swc_transform.rs"]
B --> C["中间表示(HIR)<br/>src/codegen.rs"]
C --> D["Cranelift 代码生成<br/>src/codegen.rs"]
D --> E["COFF 对象输出<br/>src/codegen.rs"]
E --> F["COFF 解析器<br/>src/coff.rs"]
A --> G["项目编译器<br/>src/project_compiler.rs"]
G --> H["依赖图构建<br/>src/dep_graph.rs"]
G --> I["项目结构管理<br/>src/project.rs"]
G --> J["独立可执行生成<br/>src/standalone_gen.rs"]
J --> K["独立加载器<br/>src/standalone_loader.rs"]
G --> L["原生链接器(可选)<br/>src/native_linker.rs"]
```

**图表来源**
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)
- [src/coff.rs:72-208](file://src/coff.rs#L72-L208)
- [src/project_compiler.rs:248-332](file://src/project_compiler.rs#L248-L332)
- [src/dep_graph.rs:43-132](file://src/dep_graph.rs#L43-L132)
- [src/project.rs:58-153](file://src/project.rs#L58-L153)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)
- [src/standalone_loader.rs:127-302](file://src/standalone_loader.rs#L127-L302)
- [src/native_linker.rs:308-382](file://src/native_linker.rs#L308-L382)

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

## 核心组件
- TypeScript 解析器（SWC）：负责将 TypeScript 源码解析为 AST，并转换为内部 HIR 表达式树，支持模块导入、类、装饰器、异步/生成器等特性。
- 中间表示生成器（HIR）：定义表达式、语句、函数、类、模块导入绑定等节点类型，用于承载语义信息以便后续代码生成。
- 代码生成器（Cranelift）：基于 HIR 生成 Cranelift IR，再编译为 COFF 对象文件；支持字符串池、源码映射、外部函数导入等。
- COFF 对象文件处理器：解析/生成 COFF 文件，提取节区、符号、重定位，支持 AMD64。
- 项目编译器：协调多模块编译、依赖图构建、入口闭包合并、独立可执行生成与原生链接（可选）。
- 独立可执行生成与加载：将模块数据序列化为 .tsnobj，配套独立加载器动态分配内存、应用重定位并执行入口。
- 原生链接器（可选）：解析多个 .obj，合并节区、构建符号表、处理重定位、生成 PE 可执行文件。

**章节来源**
- [src/swc_transform.rs:10-176](file://src/swc_transform.rs#L10-L176)
- [src/codegen.rs:80-196](file://src/codegen.rs#L80-L196)
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)
- [src/coff.rs:72-208](file://src/coff.rs#L72-L208)
- [src/project_compiler.rs:248-332](file://src/project_compiler.rs#L248-L332)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)
- [src/standalone_loader.rs:127-302](file://src/standalone_loader.rs#L127-L302)
- [src/native_linker.rs:308-382](file://src/native_linker.rs#L308-L382)

## 架构总览
下图展示从命令行到最终产物的端到端流程，以及关键组件之间的依赖关系。

```mermaid
sequenceDiagram
participant CLI as "命令行入口<br/>src/main.rs"
participant SWC as "SWC 解析器<br/>src/swc_transform.rs"
participant CG as "代码生成器<br/>src/codegen.rs"
participant COFF as "COFF 处理器<br/>src/coff.rs"
participant PC as "项目编译器<br/>src/project_compiler.rs"
participant SG as "独立生成器<br/>src/standalone_gen.rs"
participant SL as "独立加载器<br/>src/standalone_loader.rs"
CLI->>SWC : 读取输入 TS 源码并解析
SWC-->>CLI : 返回 HIR 表达式列表
CLI->>CG : 传入 HIR 进行编译
CG-->>CLI : 生成 COFF 字节流
CLI->>COFF : 可选解析 COFF 以提取数据
CLI-->>CLI : 输出 .obj 文件
CLI->>PC : 多模块项目编译入口
PC->>SWC : 逐模块解析 HIR
PC->>CG : 逐模块编译为 .obj
PC->>SG : 合并模块数据并序列化为 .tsnobj
SG-->>PC : 生成 .tsnobj
SL-->>PC : 可选使用独立加载器执行
```

**图表来源**
- [src/main.rs:55-73](file://src/main.rs#L55-L73)
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)
- [src/coff.rs:72-208](file://src/coff.rs#L72-L208)
- [src/project_compiler.rs:248-332](file://src/project_compiler.rs#L248-L332)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)
- [src/standalone_loader.rs:127-302](file://src/standalone_loader.rs#L127-L302)

## 详细组件分析

### TypeScript 解析器（SWC）
- 职责：将 TypeScript 源码解析为 AST，再转换为内部 HIR 表达式树，支持模块导入、函数、类、控制流、表达式、装饰器、异步/生成器等。
- 关键点：
  - 使用 SWC 5.x API，开启 TS 语法、装饰器、默认导出等特性。
  - 将模块声明、导入、导出、顶层语句转换为 HIR，分离 ImportBinding 与普通语句，保证 main 函数的存在性。
  - 支持 for-in/for-of、switch、try-catch、throw、typeof、一元/二元/三元表达式、数组/对象字面量、属性访问/索引、New/This/SuperMethod 等。
- 典型流程：解析模块 -> 转换为 HIR -> 返回表达式列表供后续编译。

**章节来源**
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/swc_transform.rs:36-176](file://src/swc_transform.rs#L36-L176)
- [src/swc_transform.rs:178-800](file://src/swc_transform.rs#L178-L800)

### 中间表示生成器（HIR）
- 职责：定义 HIR 表达式类型体系，承载语义信息，供代码生成器消费。
- 关键类型：
  - 基础表达式：数字、布尔、字符串、null/undefined、标识符、二元/一元/三元运算、类型判断、赋值、数组/对象字面量、属性/索引访问、函数/返回/变量声明、控制流（if/while/for/break/continue）、块、表达式语句、序列。
  - 模块导入绑定：记录本地名、模块名、导入的符号。
  - 函数/类/方法：函数声明、参数默认值、rest 参数、类定义、构造函数、静态/实例方法、属性、super 方法调用。
  - 异步/生成器：async 函数、await、generator、yield/yield*。
  - 装饰器：装饰器节点与装饰后的类/方法。
  - 正则：正则字面量及测试/匹配/执行。
  - 异常：try/catch/finally、throw。
- 设计要点：
  - 使用枚举与结构体组合表达不同语法节点，便于模式匹配与生成。
  - 支持字符串池、源码映射、外部函数导入等，为后续代码生成与调试提供支撑。

**章节来源**
- [src/codegen.rs:80-196](file://src/codegen.rs#L80-L196)
- [src/codegen.rs:198-228](file://src/codegen.rs#L198-L228)
- [src/codegen.rs:230-252](file://src/codegen.rs#L230-L252)

### 代码生成器（Cranelift）
- 职责：将 HIR 编译为 Cranelift IR，再生成 COFF 对象文件；支持字符串常量、源码映射、外部函数导入、重定位提取等。
- 关键能力：
  - 两阶段编译：第一遍收集函数签名、字符串常量、导入绑定；第二遍编译函数体。
  - 字符串池：将字符串去重并生成只读数据段。
  - 外部函数导入：声明导入函数并生成调用 IR，支持多种参数/返回类型。
  - 源码映射：记录代码偏移与源码位置，便于调试。
  - COFF 输出：直接输出 .obj 字节流，或提取为原始模块数据（供 JIT/FFI 路径使用）。
- 性能统计：记录解析、代码生成、COFF 输出、提取耗时与函数/字符串/大小统计。

```mermaid
flowchart TD
Start(["开始编译"]) --> Pass1["第一遍：收集函数签名/字符串/导入绑定"]
Pass1 --> Strings["生成字符串数据段"]
Strings --> Pass2["第二遍：编译函数体为 IR"]
Pass2 --> Finish["生成 ObjectProduct 并输出 COFF 字节流"]
Finish --> End(["结束"])
```

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

**章节来源**
- [src/codegen.rs:288-350](file://src/codegen.rs#L288-L350)
- [src/codegen.rs:350-450](file://src/codegen.rs#L350-L450)
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)
- [src/codegen.rs:606-707](file://src/codegen.rs#L606-L707)

### COFF 对象文件处理器
- 职责：解析/生成 COFF 对象文件，支持节区、符号表、字符串表、重定位等。
- 关键能力：
  - 解析：支持 AMD64，读取文件头、节区头、符号表、字符串表、重定位项。
  - 查询：提供未定义符号、已定义全局符号、按名查找符号等。
  - 生成：将 COFF 字节流解析为模块数据（代码/数据/rdata、符号、重定位）。
- 适用场景：项目编译器合并模块时的 COFF 解析、独立可执行生成的数据准备。

**章节来源**
- [src/coff.rs:72-208](file://src/coff.rs#L72-L208)
- [src/coff.rs:210-231](file://src/coff.rs#L210-L231)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)

### 项目编译器
- 职责：协调多模块项目的编译流程，构建依赖图，按拓扑顺序编译模块，为每个入口生成独立可执行文件（内嵌 loader）。
- 关键流程：
  - 项目发现与配置：扫描 .ts 文件，识别入口与模块，构建 SourceFile 列表。
  - 依赖图构建：解析 import/export，构建节点与边，进行拓扑排序与层级计算，计算入口闭包。
  - 模块编译：逐模块解析 HIR、编译为 .obj，统计函数覆盖率与编译耗时。
  - 独立可执行生成：合并入口闭包内的模块，重命名非入口模块符号，序列化为 .tsnobj，复制预编译 loader 并注入 tsn_runtime.dll。
  - 报告输出：汇总阶段耗时、内存使用、模块/入口统计。
- 优化建议：
  - 并行编译：在模块间无强依赖时可并行执行（注意线程安全与共享资源）。
  - 缓存：对未变更模块的编译结果进行缓存，增量编译。
  - 对齐与压缩：合并节区时注意对齐，减少冗余节区。

```mermaid
sequenceDiagram
participant PC as "项目编译器<br/>src/project_compiler.rs"
participant DG as "依赖图<br/>src/dep_graph.rs"
participant PJ as "项目结构<br/>src/project.rs"
participant CG as "代码生成器<br/>src/codegen.rs"
participant SG as "独立生成器<br/>src/standalone_gen.rs"
PC->>PJ : 从目录构建项目结构
PC->>DG : 从项目构建依赖图
loop 按拓扑顺序
PC->>CG : 编译单个模块为 .obj
end
PC->>SG : 合并入口闭包模块并序列化为 .tsnobj
PC-->>PC : 生成编译报告
```

**图表来源**
- [src/project_compiler.rs:248-332](file://src/project_compiler.rs#L248-L332)
- [src/dep_graph.rs:43-132](file://src/dep_graph.rs#L43-L132)
- [src/project.rs:58-153](file://src/project.rs#L58-L153)
- [src/standalone_gen.rs:489-605](file://src/standalone_gen.rs#L489-L605)

**章节来源**
- [src/project_compiler.rs:248-332](file://src/project_compiler.rs#L248-L332)
- [src/project_compiler.rs:334-382](file://src/project_compiler.rs#L334-L382)
- [src/project_compiler.rs:384-567](file://src/project_compiler.rs#L384-L567)
- [src/project_compiler.rs:569-727](file://src/project_compiler.rs#L569-L727)

### 独立可执行生成与加载
- 独立可执行生成（standalone_gen）：
  - 将模块数据（代码/数据/rdata、符号、重定位）序列化为 .tsnobj。
  - 提供从 COFF 解析模块数据的能力，用于项目编译器合并阶段。
- 独立加载器（standalone_loader）：
  - 从 .tsnobj 加载模块数据，动态分配可执行/数据内存，应用重定位，解析外部符号（通过 tsn_runtime.dll），执行入口 main 并清理资源。

```mermaid
sequenceDiagram
participant SG as "独立生成器<br/>src/standalone_gen.rs"
participant SL as "独立加载器<br/>src/standalone_loader.rs"
SG-->>SG : 从 COFF 解析模块数据
SG-->>SG : 序列化为 .tsnobj
SL->>SL : 读取 .tsnobj 并解析头部/数据
SL->>SL : 分配可执行/数据内存
SL->>SL : 应用重定位内部/外部
SL->>SL : 查找入口 main 并执行
SL-->>SL : 清理资源并返回结果
```

**图表来源**
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)
- [src/standalone_gen.rs:489-605](file://src/standalone_gen.rs#L489-L605)
- [src/standalone_loader.rs:127-302](file://src/standalone_loader.rs#L127-L302)

**章节来源**
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)
- [src/standalone_gen.rs:489-605](file://src/standalone_gen.rs#L489-L605)
- [src/standalone_loader.rs:127-302](file://src/standalone_loader.rs#L127-L302)

### 原生链接器（可选）
- 职责：解析多个 COFF .obj，合并节区，构建符号表，处理外部符号与重定位，生成 PE 可执行文件。
- 关键能力：
  - 合并节区：按名称合并，对齐到 16 字节，清理对齐标志与 LINK_COMDAT 标志。
  - 符号表：建立全局符号映射，区分外部与静态符号。
  - 导入解析：根据配置将未定义符号映射到 DLL 导入，必要时注入简单实现（如 memcpy/memset 等）。
  - 重定位：应用 REL32/ADDR64 等重定位，生成重定位表。
  - PE 输出：构建 DOS 头、NT 头、节区表、导入表、重定位表等，输出完整 PE。
- 诊断反馈：提供节区特征、导入表、入口点、SizeOfHeaders 等诊断与建议。

**章节来源**
- [src/native_linker.rs:308-382](file://src/native_linker.rs#L308-L382)
- [src/native_linker.rs:384-489](file://src/native_linker.rs#L384-L489)
- [src/native_linker.rs:518-553](file://src/native_linker.rs#L518-L553)
- [src/native_linker.rs:555-700](file://src/native_linker.rs#L555-L700)
- [src/native_linker.rs:789-800](file://src/native_linker.rs#L789-L800)

## 依赖关系分析
- 模块耦合：
  - 项目编译器依赖 SWC 解析器、代码生成器、依赖图与项目结构管理。
  - 代码生成器依赖 Cranelift 生态（frontend/module/object/codegen）与 object crate。
  - 独立生成器依赖 COFF 解析能力与二进制序列化。
  - 原生链接器依赖 COFF 解析器与 PE 生成逻辑。
- 外部依赖：
  - SWC 5.x、Cranelift 0.93.x、object crate、anyhow/log/env_logger 等。

```mermaid
graph LR
SWC["SWC 解析器<br/>src/swc_transform.rs"] --> HIR["HIR 表达式<br/>src/codegen.rs"]
HIR --> CG["代码生成器<br/>src/codegen.rs"]
CG --> OBJ["COFF 对象<br/>src/codegen.rs"]
OBJ --> COFF["COFF 解析器<br/>src/coff.rs"]
PJ["项目结构<br/>src/project.rs"] --> DG["依赖图<br/>src/dep_graph.rs"]
DG --> PC["项目编译器<br/>src/project_compiler.rs"]
PC --> CG
PC --> SG["独立生成器<br/>src/standalone_gen.rs"]
SG --> SL["独立加载器<br/>src/standalone_loader.rs"]
PC --> NL["原生链接器<br/>src/native_linker.rs"]
```

**图表来源**
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)
- [src/coff.rs:72-208](file://src/coff.rs#L72-L208)
- [src/project.rs:58-153](file://src/project.rs#L58-L153)
- [src/dep_graph.rs:43-132](file://src/dep_graph.rs#L43-L132)
- [src/project_compiler.rs:248-332](file://src/project_compiler.rs#L248-L332)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)
- [src/standalone_loader.rs:127-302](file://src/standalone_loader.rs#L127-L302)
- [src/native_linker.rs:308-382](file://src/native_linker.rs#L308-L382)

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

## 性能考量
- 解析与编译阶段：
  - SWC 解析与 HIR 转换：关注大型模块的解析时间，必要时拆分模块或启用增量解析。
  - 代码生成：Cranelift 编译开销较大，可通过减少不必要的字符串常量、避免复杂嵌套作用域来降低 IR 复杂度。
- 内存与对齐：
  - 合并节区时注意对齐（16 字节），避免冗余零填充。
  - 数据段与只读数据段的合理布局，减少运行时内存占用。
- 并发与缓存：
  - 模块编译阶段可并行执行（无依赖模块），结合缓存提升增量编译效率。
- 诊断与统计：
  - 利用编译器内置统计字段（函数数、字符串数、代码/数据大小）监控性能变化。

## 故障排查指南
- 常见问题与解决：
  - 未定义符号：确认导入配置与外部符号解析是否正确，检查符号名大小写与前缀（如 __imp_）。
  - 重定位失败：检查重定位类型与目标符号是否存在，确保 .rdata 节区具备可写权限。
  - 入口点缺失：确保 main 函数存在且位于 .text 节区，或配置正确的入口点。
  - 运行时 DLL 未找到：独立加载器需要 tsn_runtime.dll，确保其与 .exe 同目录或可搜索路径存在。
- 诊断工具：
  - 项目编译器输出阶段耗时、内存使用、模块/入口统计。
  - 原生链接器提供诊断反馈（节区特征、导入表、入口点、SizeOfHeaders 等）。

**章节来源**
- [src/project_compiler.rs:662-701](file://src/project_compiler.rs#L662-L701)
- [src/native_linker.rs:204-283](file://src/native_linker.rs#L204-L283)
- [src/standalone_loader.rs:127-302](file://src/standalone_loader.rs#L127-L302)

## 结论
ts-native 通过 SWC 解析、自定义 HIR、Cranelift 代码生成与 COFF 处理，形成完整的 TypeScript 到本地机器码的编译链路。项目编译器与独立可执行生成进一步提升了工程化能力，原生链接器提供了可选的 PE 输出路径。整体设计强调模块化、可扩展与可观测性，适合在多模块项目中稳定落地。

## 附录
- 命令行用法（命令行入口）：
  - 输入：ts-native <输入.ts> [-o 输出.obj]
  - 输出：生成 .obj 文件，提示使用 tsn-loader 执行。
- 配置与特性：
  - Cargo.toml 中定义了 SWC、Cranelift、object 等依赖，以及可选的 native-linker 特性。
  - 代码生成器支持字符串池、源码映射、外部函数导入、COFF 输出与原始模块数据提取。

**章节来源**
- [src/main.rs:7-78](file://src/main.rs#L7-L78)
- [Cargo.toml:22-57](file://Cargo.toml#L22-L57)