# 项目概述

<cite>
**本文档引用的文件**
- [Cargo.toml](file://Cargo.toml)
- [README.md](file://README.md)
- [架构设计.md](file://docs/架构设计/架构设计.md)
- [系统边界设计.md](file://docs/架构设计/系统边界设计.md)
- [组件交互关系.md](file://docs/架构设计/组件交互关系.md)
- [NODE_MODULE_SUPPORT_PROPOSAL.md](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md)
- [src/main.rs](file://src/main.rs)
- [src/lib.rs](file://src/lib.rs)
- [src/codegen.rs](file://src/codegen.rs)
- [src/swc_transform.rs](file://src/swc_transform.rs)
- [src/coff.rs](file://src/coff.rs)
- [src/project.rs](file://src/project.rs)
- [src/standalone_gen.rs](file://src/standalone_gen.rs)
- [loader/src/main.rs](file://loader/src/main.rs)
- [runtime/Cargo.toml](file://runtime/Cargo.toml)
- [runtime/src/lib.rs](file://runtime/src/lib.rs)
- [test_multi_entry/src/main.ts](file://test_multi_entry/src/main.ts)
- [test_multi_entry/src/cli.ts](file://test_multi_entry/src/cli.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [Node.js 模块兼容性方案](#node.js-模块兼容性方案)
7. [依赖分析](#依赖分析)
8. [性能考虑](#性能考虑)
9. [故障排除指南](#故障排除指南)
10. [结论](#结论)
11. [附录](#附录)

## 简介

ts-native 是一个革命性的 TypeScript 到原生代码编译器，采用 Ahead-of-Time (AOT) 编译方式，将 TypeScript 源码直接编译为高性能的原生可执行文件。该项目的核心价值主张在于：

### 核心优势
- **极致性能**：通过 AOT 编译消除了运行时解释开销，实现接近 C/C++ 的执行速度
- **零运行时依赖**：生成独立的原生可执行文件，无需安装 Node.js 或其他运行时环境
- **现代开发体验**：保持 TypeScript 的开发便利性，同时获得原生性能
- **跨平台兼容**：基于 Cranelift JIT 引擎，支持多种目标架构

### 技术创新
项目采用先进的 NaN-boxing 值表示技术，在 64 位空间中统一表示所有 JavaScript 值，实现了内存效率和性能的完美平衡。

### Node.js 生态兼容性
**新增** 项目正在规划全面的 Node.js 模块兼容性支持，通过分阶段的兼容方案逐步实现对 npm 包的原生支持，包括：
- **Shim 机制**：为常用 npm 包提供原生替代实现
- **源码级编译**：支持解析 node_modules 并编译纯 JS 包
- **FFI 桥接**：为 C++ Addon 提供原生桥接
- **QuickJS 嵌入**：为复杂包提供 JS 引擎回退支持

## 项目结构

ts-native 采用模块化的 Rust 项目结构，主要包含以下核心模块：

```mermaid
graph TB
subgraph "核心编译器"
A[src/main.rs - CLI入口]
B[src/lib.rs - 库入口]
C[src/codegen.rs - 代码生成]
D[src/swc_transform.rs - AST转换]
E[src/coff.rs - COFF生成]
end
subgraph "运行时系统"
F[runtime/src/lib.rs - 运行时库]
G[runtime/Cargo.toml - 运行时配置]
end
subgraph "加载器"
H[loader/src/main.rs - 加载器]
end
subgraph "项目管理"
I[src/project.rs - 项目发现]
J[src/standalone_gen.rs - 独立生成]
end
subgraph "Node.js兼容层"
K[Shim机制 - 内置包支持]
L[CJS/ESM转换 - 源码编译]
M[FFI桥接 - C++ Addon]
N[QuickJS回退 - 复杂包]
end
A --> C
B --> C
C --> E
D --> C
E --> H
F --> H
I --> B
J --> B
K --> I
L --> D
M --> J
N --> F
```

**图表来源**
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [runtime/src/lib.rs:1-800](file://runtime/src/lib.rs#L1-L800)
- [docs/NODE_MODULE_SUPPORT_PROPOSAL.md:31-356](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L31-L356)

**章节来源**
- [Cargo.toml:1-57](file://Cargo.toml#L1-L57)
- [README.md:39-62](file://README.md#L39-L62)

## 核心组件

### 编译器核心
编译器采用分层架构，每层都有明确的职责分工：

| 组件 | 职责 | 关键特性 |
|------|------|----------|
| **SWC 解析器** | TypeScript 语法分析 | 支持最新 TS 特性，高性能解析 |
| **HIR 生成器** | 中间表示构建 | 类型安全的抽象语法树 |
| **Cranelift 代码生成** | 机器码生成 | 现代 JIT 引擎，优化编译 |
| **COFF 链接器** | 目标文件生成 | 标准 Windows 目标格式 |

### 运行时系统
运行时采用 C 语言实现，提供完整的 JavaScript 生态系统支持：

- **值管理系统**：基于 NaN-boxing 的统一值表示
- **内存管理**：高效的字符串、数组、对象池
- **内置 API**：完整的 JavaScript 标准库实现
- **模块系统**：支持 ES 模块和 CommonJS

### Node.js 兼容层
**新增** 为实现对 Node.js 生态的全面支持，系统设计了四阶段兼容方案：

- **阶段1：Shim 机制** - 为常用包提供原生替代实现
- **阶段2：源码编译** - 支持 node_modules 解析和 CJS/ESM 编译
- **阶段3：FFI 桥接** - 为 C++ Addon 提供原生桥接
- **阶段4：QuickJS 回退** - 为复杂包提供 JS 引擎支持

**章节来源**
- [src/codegen.rs:1-800](file://src/codegen.rs#L1-L800)
- [runtime/src/lib.rs:1-800](file://runtime/src/lib.rs#L1-L800)
- [docs/NODE_MODULE_SUPPORT_PROPOSAL.md:31-356](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L31-L356)

## 架构概览

ts-native 的编译架构体现了现代编译器设计的最佳实践：

```mermaid
sequenceDiagram
participant TS as TypeScript源码
participant SWC as SWC解析器
participant HIR as HIR生成器
participant CR as Cranelift代码生成
participant COFF as COFF生成器
participant EXE as 可执行文件
TS->>SWC : 解析TypeScript
SWC->>HIR : 生成AST
HIR->>CR : 转换为中间表示
CR->>COFF : 生成机器码
COFF->>EXE : 输出可执行文件
Note over TS,EXE : AOT编译流程
```

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

### 设计原则
1. **模块化设计**：每个组件职责单一，易于维护和扩展
2. **性能优先**：采用编译时优化，避免运行时开销
3. **类型安全**：利用 Rust 的类型系统确保内存安全
4. **可移植性**：支持多种目标平台和架构
5. **生态兼容**：通过分阶段方案实现对 Node.js 生态的渐进式支持

## 详细组件分析

### 编译管线组件

#### SWC AST 转换器
负责将 TypeScript AST 转换为内部 HIR 表示：

```mermaid
flowchart TD
A[TypeScript AST] --> B[模块声明处理]
B --> C[函数声明转换]
C --> D[表达式转换]
D --> E[语句转换]
E --> F[导入绑定处理]
F --> G[生成HIR]
B --> H[导入声明解析]
H --> I[模块路径解析]
I --> J[导入绑定生成]
```

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

#### Cranelift 代码生成器
实现从 HIR 到机器码的高效转换：

```mermaid
classDiagram
class CodeGen {
+builder_context : FunctionBuilderContext
+function_ids : HashMap~String, FuncId~
+string_pool : HashSet~String~
+compile_coff(exprs) Vec~u8~
+compile_to_raw_data(exprs) RawModuleData
+set_current_line(line : u32)
}
class HirExpr {
<<enumeration>>
Number(f64)
String(String)
BinaryOp(BinOp, HirExpr, HirExpr)
Call(HirExpr, Vec~HirExpr~)
Function(String, Vec~String~, Vec~HirExpr~)
}
class CompileStats {
+parse_time_ms : u64
+codegen_time_ms : u64
+code_size : usize
+function_count : usize
}
CodeGen --> HirExpr : generates
CodeGen --> CompileStats : collects
```

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

**章节来源**
- [src/swc_transform.rs:1-800](file://src/swc_transform.rs#L1-L800)
- [src/codegen.rs:1-800](file://src/codegen.rs#L1-L800)

### 运行时系统组件

#### NaN-boxing 值系统
实现高效的值表示和内存管理：

```mermaid
graph LR
subgraph "64位值空间"
A[Tag位<br/>4位]
B[Payload位<br/>60位]
end
subgraph "值类型"
C[Number<br/>IEEE 754]
D[String<br/>堆指针]
E[Object<br/>堆指针]
F[Boolean<br/>0/1]
G[Undefined<br/>特殊标记]
H[Null<br/>特殊标记]
end
A --> C
B --> C
A --> D
B --> D
A --> E
B --> E
A --> F
B --> F
A --> G
B --> G
A --> H
B --> H
```

**图表来源**
- [runtime/src/lib.rs:7-24](file://runtime/src/lib.rs#L7-L24)

#### 运行时 API 系统
提供完整的 JavaScript 标准库实现：

| 模块类别 | 关键函数 | 功能描述 |
|----------|----------|----------|
| **基础类型** | js_string_from_static, js_strict_equals | 字符串和比较操作 |
| **数组操作** | js_array_new, js_array_push, js_array_set | 动态数组管理 |
| **对象操作** | js_object_new, js_object_set, js_object_get | 属性访问和管理 |
| **数学函数** | js_math_sin, js_math_cos, js_math_sqrt | 数学运算支持 |
| **文件系统** | js_fs_read_file_sync, js_fs_write_file_sync | 文件操作支持 |

**章节来源**
- [runtime/src/lib.rs:135-800](file://runtime/src/lib.rs#L135-L800)

### 加载器组件

#### tsn-loader 执行引擎
提供灵活的执行模式和插件系统：

```mermaid
flowchart TD
A[输入文件] --> B{文件类型判断}
B --> |.ts文件| C[编译模式]
B --> |.obj文件| D[加载模式]
C --> E[调用ts-native.dll]
E --> F[编译TypeScript]
F --> G[生成COFF]
G --> H[执行代码]
D --> I[解析COFF文件]
I --> J[应用重定位]
J --> K[执行代码]
H --> L[输出结果]
K --> L
```

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

**章节来源**
- [loader/src/main.rs:1-800](file://loader/src/main.rs#L1-L800)

## Node.js 模块兼容性方案

**新增** 为解决 ts-native 与 Node.js 生态的兼容性问题，项目制定了分阶段的兼容性提案：

### 核心挑战分析
- **ABI 不兼容**：ts-native 使用 NaN-tagged f64 表示值，而 Node.js 使用 V8 对象
- **模块系统差异**：ts-native 无 node_modules 解析、无 require/exports 机制
- **运行时差异**：ts-native 运行在 bare-metal，无 Node.js 事件循环/Buffer/Stream
- **包类型多样**：npm 包分为纯 JS、C++ Addon、WASM 三类，处理方式完全不同

### 分阶段兼容方案

#### 阶段1：Shim 机制（短期，1-2周）
**思路**：为常用的纯算法 npm 包提供 native shim，在编译期替换为等价的 native 实现。

**实现要点**：
- 通过 `tsn-project.toml` 配置包映射
- 编译时将 import 语句替换为对应的 shim 函数
- 运行时调用原生实现，无运行时开销

#### 阶段2：node_modules 解析 + CJS/ESM 转 HIR（中期，3-4周）
**思路**：支持解析 node_modules 目录，将纯 JS npm 包的源码作为 ts-native 编译输入。

**实现要点**：
- 解析 package.json 的 "main" / "exports" 字段
- 支持 CommonJS require/module.exports 到 HIR 的转换
- 递归解析依赖关系，构建完整的依赖图

#### 阶段3：FFI 桥接 Node.js C++ Addon（中期，2-3周）
**思路**：对于包含 C/C++ 原生代码的 npm 包，通过 FFI 直接调用其编译后的 DLL。

**实现要点**：
- 配置 DLL 路径和函数签名
- 实现值转换层，处理 NaN-tagged f64 与原生类型的互转
- 支持回调函数和复杂数据结构

#### 阶段4：嵌入 QuickJS 运行时（长期，4-6周）
**思路**：在 runtime 中嵌入轻量 JS 引擎，将无法原生化的 npm 包调用委托给 JS 引擎执行。

**实现要点**：
- 支持 ES2020 语法和 ESM 规范
- 实现与 ts-native 值系统的双向转换
- 提供渐进式回退机制

**章节来源**
- [docs/NODE_MODULE_SUPPORT_PROPOSAL.md:1-497](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L1-L497)

## 依赖分析

### 外部依赖关系

```mermaid
graph TB
subgraph "编译期依赖"
A[Cargo.toml - 项目配置]
B[anyhow - 错误处理]
C[log/env_logger - 日志系统]
D[clap - 命令行解析]
end
subgraph "SWC生态"
E[swc_common - 通用工具]
F[swc_ecma_ast - AST定义]
G[swc_ecma_parser - 解析器]
H[swc_ecma_visit - 访问器]
end
subgraph "Cranelift生态"
I[cranelift-frontend - 前端]
J[cranelift-module - 模块管理]
K[cranelift-native - 本机后端]
L[cranelift-object - 对象生成]
end
subgraph "工具链"
M[object - COFF解析]
N[cc - 构建工具]
end
subgraph "Node.js兼容依赖"
O[serde/serde_json - 配置解析]
P[quickjs - JS引擎]
Q[sha2/rand - 加密/随机数]
end
A --> B
A --> C
A --> D
A --> E
A --> F
A --> G
A --> H
A --> I
A --> J
A --> K
A --> L
A --> M
A --> N
A --> O
A --> P
A --> Q
```

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

### 内部模块依赖

```mermaid
graph LR
subgraph "核心模块"
A[src/lib.rs]
B[src/codegen.rs]
C[src/swc_transform.rs]
D[src/coff.rs]
end
subgraph "运行时模块"
E[runtime/src/lib.rs]
F[loader/src/main.rs]
end
subgraph "项目管理"
G[src/project.rs]
H[src/standalone_gen.rs]
end
subgraph "兼容层模块"
I[Shim机制]
J[CJS转换]
K[FFI桥接]
L[QuickJS集成]
end
A --> B
A --> C
A --> D
A --> G
A --> H
B --> E
C --> B
D --> F
G --> A
H --> A
I --> G
J --> C
K --> H
L --> E
```

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

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

## 性能考虑

### 编译时优化
- **增量编译**：支持部分编译，提高开发效率
- **并行编译**：多线程处理多个源文件
- **内存优化**：使用 Arena 分配器减少内存碎片
- **缓存机制**：缓存中间结果，避免重复计算

### 运行时优化
- **NaN-boxing**：统一值表示，减少分支预测失败
- **内联缓存**：热点方法的快速路径
- **逃逸分析**：减少不必要的堆分配
- **SIMD 支持**：利用现代 CPU 指令集

### 内存管理策略
- **垃圾回收**：精确的引用计数
- **对象池**：复用临时对象
- **内存映射**：大文件的高效处理
- **延迟初始化**：按需创建昂贵对象

## 故障排除指南

### 常见编译错误

| 错误类型 | 症状 | 解决方案 |
|----------|------|----------|
| **语法错误** | 编译失败，显示语法错误 | 检查 TypeScript 语法，参考 SWC 错误消息 |
| **类型错误** | 编译警告，类型不匹配 | 修正类型注解，遵循 TypeScript 类型系统 |
| **链接错误** | 运行时符号未解析 | 检查导入模块，确保运行时库可用 |
| **内存错误** | 运行时崩溃 | 检查数组边界，验证字符串长度 |

### 性能问题诊断

```mermaid
flowchart TD
A[性能问题] --> B{编译时还是运行时}
B --> |编译时| C[检查编译标志]
B --> |运行时| D[分析运行时行为]
C --> E[启用详细日志]
E --> F[分析编译时间]
F --> G[优化热点代码]
D --> H[启用性能分析]
H --> I[识别瓶颈]
I --> J[应用优化策略]
```

### 调试技巧
- **启用详细日志**：使用 `--verbose` 或 `--debug` 标志
- **查看中间表示**：输出 HIR 和 Cranelift IR
- **性能分析**：使用内置的编译报告功能
- **内存监控**：跟踪内存使用情况

**章节来源**
- [loader/src/main.rs:156-222](file://loader/src/main.rs#L156-L222)

## 结论

ts-native 代表了 TypeScript 编译技术的重大突破，通过 AOT 编译实现了性能和开发体验的完美平衡。项目采用的技术架构具有以下特点：

### 技术成就
- **创新的 NaN-boxing 值系统**：在 64 位空间中统一表示所有 JavaScript 值
- **高效的编译管线**：从 TypeScript 到原生代码的完整链路
- **灵活的运行时系统**：支持丰富的 JavaScript 生态系统
- **强大的工具链**：提供完整的开发和部署解决方案
- **渐进式 Node.js 兼容**：通过四阶段方案实现生态兼容

### 应用前景
- **高性能计算**：科学计算和数据分析应用
- **WebAssembly 替代**：更直接的原生性能
- **边缘计算**：低延迟和高吞吐量场景
- **嵌入式系统**：资源受限环境下的脚本执行
- **企业应用**：需要高性能和可控性的商业应用

### 发展方向
- **多平台支持**：扩展到 Linux 和 macOS
- **Web 平台**：支持浏览器环境
- **云原生**：容器化和微服务集成
- **AI/ML 集成**：机器学习模型的高效执行
- **生态完善**：持续扩展对 Node.js 包的支持

## 附录

### 快速开始指南

#### 基本编译命令
```bash
# 构建项目
cargo build --release

# 编译单个 TypeScript 文件
ts-native main.ts -o output.obj

# 编译整个项目
ts-native build ./my-project

# 使用 tsn-loader 执行
tsn-loader main.ts -p runtime.dll
```

#### 开发环境设置
1. **安装 Rust 工具链**：使用 rustup 安装最新稳定版本
2. **安装构建工具**：确保安装了必要的系统依赖
3. **克隆项目**：获取源码并进行编译
4. **运行测试**：验证编译器功能正常

#### 示例项目结构
```typescript
// main.ts - 主入口文件
import { calculate } from "./utils/math";
import { log } from "./lib/core";

function main(): number {
    return calculate(10, 20);
}
```

**章节来源**
- [README.md:5-16](file://README.md#L5-L16)
- [test_multi_entry/src/main.ts:1-15](file://test_multi_entry/src/main.ts#L1-L15)
- [test_multi_entry/src/cli.ts:1-15](file://test_multi_entry/src/cli.ts#L1-L15)