# Snow 语言现状和下一阶段开发路线图

> 日期: 2025-06-11

## 1. 代码结构与职责
| 层次     | 主要包/目录                   | 说明                                                     |
|--------|--------------------------|--------------------------------------------------------|
| 词法分析   | `snow/compiler/lexer`    | 扫描器（Scanner）+ `TokenFactory`，可识别关键字、运算符、数字/字符串字面量等     |
| 语法分析   | `snow/compiler/parser`   | Pratt 表达式解析器 + 各类语句解析器（声明、`if`、`loop`、`return`…）生成 AST |
| 语义分析   | `snow/compiler/semantic` | 符号表、类型系统（`BuiltinType`/`FunctionType`）与各节点分析器          |
| IR 构建  | `snow/compiler/ir`       | SSA-风格中间表示、指令集、构建器                                     |
| 后端生成   | `snow/compiler/backend`  | IR ➜ VM 指令的 `*Generator` 体系、寄存器分配                      |
| 运行时 VM | `snow/vm`                | 指令集实现（栈/寄存器/内存/控制流/函数）+ 启动器                            |

### 2 编译流程

1. **Lexer** 将源码映射为 `TokenStream`
2. **Parser** 生成 AST（19 种节点）
3. **Semantic**

    * 类型推断 / 兼容性校验
    * 符号绑定与引用解析
4. **IR**

    * 虚拟寄存器 + 基本块 + 统一指令（算术、比较、跳转、调用、返回…）
5. **Backend**

    * 线性扫描寄存器分配
    * 指令生成器把 IR 转为 VM 指令
6. **VM**

    * 栈-基 / 寄存器混合架构
    * 96 条已实现指令（按数据宽度泛化: B/S/I/L/F/D）
    * 运行时启动器 `VMLauncher`


## 3. 测试中存在的问题记录

| 模块             | 现状                                                            |
|----------------|---------------------------------------------------------------| 
| **布尔类型**       | 词法已识别 `bool`，但 `BuiltinType` 中缺失；比较运算目前回落为 `int` 0/1          |
| **一元/前缀运算**    | VM 与 IR 有 `UnaryOperationInstruction`，Parser 未注册 `-x`, `!x` 等 |
| **数组/切片/Map**  | 无 AST/Type/IR 支持                                              |
| **结构体 / 面向对象** | 无 结构体、对象 节点                                                   |
| **异常处理**       | 无 try/catch 指令或语义                                             |
| **优化 Pass**    | 未见常量折叠 / 死代码删除等                                               |
| **标准库 & I/O**  | 仅语言核心，无文件/网络/控制台 API                                          |
| **测试矩阵**       | 单元测试缺失，e2e 样例有限                                               |
| **CLI/包管理**    | 缺少 `snowc` 命令与包版本语义                                           |

## 4. 下一阶段开发路线图

> 优先级: P0 = 当前版本必须，P1 = 下一个小版本，P2 = 中长期

| 优先级    | 功能               | 关键任务                                                                                                                 |
|--------|------------------|----------------------------------------------------------------------------------------------------------------------|
| **P0** | **布尔类型落地**       | \* 在 `BuiltinType` 中补充 `BOOL`<br>\* 更新 `TokenFactory.TYPES` 映射<br>\* 比较/逻辑运算返回 `bool` 类型<br>\* VM 增加布尔专用指令或重用 `byte` |
| **P0** | **一元表达式解析**      | \* 实现 `UnaryOperatorParselet`（`-`, `+`, `!`)<br>\* 对应 `UnaryOpGenerator` 注册                                          |
| **P1** | **数组与切片**        | \* 设计 `ArrayType`（元素类型 + 维度）<br>\* 新增 `IndexExpressionNode`、`NewArrayNode`<br>\* VM 扩充 `ALOAD/ASTORE` 指令             |
| **P1** | **基础标准库**        | \* `print/println`, 文件读写<br>\* 编译期内置绑定到 VM calls                                                                     |
| **P1** | **测试与 CI**       | \* JUnit5 单测: Lexer / Parser / Semantic / VM<br>\* CI/CD 自动构建、示例编译运行                                                  |
| **P2** | **结构体 / 简单面向对象** | \* 结构体 语法、记录类型布局<br>\* 方法调度: 静态 or 虚表                                                                                 |
| **P2** | **优化管线**         | \* 常量折叠、公共子表达式消除<br>\* 简易死代码清除                                                                                       |
| **P2** | **错误与异常系统**      | \* 语法: `try … catch … end`<br>\* VM: 展开-收缩栈，异常表                                                                        |
| **P2** | **包管理 & CLI**    | \* `snowc` 命令: `build`, `run`, `test`<br>\* 本地缓存 `.snowpkg`与包版本语义                                                     |


## 5.1 里程碑排期

| 时间      | 目标                                     |
|---------|----------------------------------------|
| 2025-07 | 发布 **v0.2.0**: 布尔类型 + 一元运算、20+ 单元测试     |
| 2025-08 | 发布 **v0.3.0**: 数组/切片 & 基础标准库；引入 CLI     |
| 2025-10 | 发布 **v0.4.0**: 结构体支持、首批优化 Pass、>80% 覆盖率 |
| 2026-11 | 发布 **v1.0.0**: 异常系统、稳定包管理、文档完善          |