Add token-based PEG frontend and CLI source parsing

docs/runtime/README.md

@@ -6,6 +6,7 @@
 | --- | --- |
 | [对象模型](objects.md) | EndorObject／ObjectHeader、代际句柄、操作协议、托管引用与循环回收 |
 | [基本对象与 Number](builtins.md) | 函数、原生函数、字典、Cell、异常数据、字符串与无损数字 |
+| [源码前端](frontend.md) | 手写 lexer、token PEG parser、AST、基础函数／表达式语法与诊断 |
 | [字节码 VM](bytecode.md) | 指令编码、代码校验、局部槽、执行帧、函数创建、调用／返回与边界 |
 | [文本编码](text-encoding.md) | UTF-8、日文、外部 Shift_JIS／CP932 与宿主解码边界 |
 | [数据库特殊类](database-objects.md) | 显式连接、调用方数据模型、未来类接入与资源生命周期 |

docs/runtime/builtins.md

@@ -119,7 +119,7 @@ fn main() -> Result<(), endor_core::VmError> {
 }
 ```
 
-当前已能通过字节码读取、写入和删除共享 Cell，并创建捕获参数的 Cell。LoadClosure 与 MakeFunction 可以在外围函数运行时创建共享这些 Cell 的嵌套函数，外围帧返回后 Cell 仍由闭包保活。上面的 Python 代码说明闭包语义；Endor 尚无源码解析器，代码对象仍由宿主准备。
+当前已能通过字节码读取、写入和删除共享 Cell，并创建捕获参数的 Cell。LoadClosure 与 MakeFunction 可以在外围函数运行时创建共享这些 Cell 的嵌套函数，外围帧返回后 Cell 仍由闭包保活。上面的 Python 代码说明闭包语义；独立 frontend 已能解析基础函数，但尚无源码闭包语法或字节码编译器，代码对象仍由宿主准备。
 
 ## 字符串与异常的准确含义
 

docs/runtime/bytecode.md

@@ -1,6 +1,6 @@
 # 小型字节码 VM
 
-当前提供指令与代码对象、内部执行帧、取指执行循环，语言函数已接入执行器。参考 CPython 3.14 的职责划分和栈式执行设计；不实现 lexer/parser，不读取 Python `.pyc`，不承诺 CPython 操作码编号、ABI 或完整语言兼容性。
+当前提供指令与代码对象、内部执行帧、取指执行循环，语言函数已接入执行器。参考 CPython 3.14 的职责划分和栈式执行设计；源码 lexer/parser 由独立 [frontend](frontend.md) 提供，尚无 AST 到字节码编译器；执行器不读取 Python `.pyc`，不承诺 CPython 操作码编号、ABI 或完整语言兼容性。
 
 ## 与 CPython 的对应
 
@@ -148,7 +148,7 @@ fn main() -> Result<(), endor_core::VmError> {
 }
 ```
 
-该示例直接提供指令，不表示已经支持 Endor 或 Python 源码解析。宿主仍负责准备代码对象和执行环境；函数既可由宿主 new_function 工厂创建，也可由上述 MakeFunction 在字节码运行期间创建。
+该示例直接提供指令，不经过源码前端；当前 Endor 前端可生成 AST，但尚不能从源码生成字节码，也不解析 Python 源码。宿主仍负责准备代码对象和执行环境；函数既可由宿主 new_function 工厂创建，也可由上述 MakeFunction 在字节码运行期间创建。
 
 ## 限额、诊断与边界
 
@@ -156,7 +156,7 @@ fn main() -> Result<(), endor_core::VmError> {
 
 运行错误仍返回 `VmError`。`last_traceback()` 另提供从外到内的函数名、文件、代码首行和出错指令偏移；它保存独立元数据，不保活已经清理的帧。首行是代码声明的 first_line，不是由行号表推导出的实际错误源码行。成功的新一次调用会清空旧记录。尚无语言异常对象传播、raise／try／except 或完整源码行号表。
 
-暂未实现：lexer/parser、源码编译器、关键字／可变参数、生成器／协程、迭代器专用指令、数值算术、自动方法绑定、指令特化和 JIT。
+暂未实现：源码编译器、关键字／可变参数、生成器／协程、迭代器专用指令、数值算术、自动方法绑定、指令特化和 JIT。
 
 ## 验证
 

docs/runtime/frontend.md

@@ -0,0 +1,58 @@
+# 源码词法与 PEG 语法前端
+
+frontend 包提供手写 Rust lexer 和 rust-peg 生成的 token parser。当前入口为 lex、parse、parse_expression，CLI 提供 parse 文件命令；结果是 AST，还没有 AST 到字节码的编译器、类型检查、名称解析或源码执行。Core 不依赖 frontend 或 peg，仍保持零外部依赖。
+
+首版以 Endorphin-Language 设计稿的基础词法、表达式与函数章节为起点，语法可以继续修改；设计稿中的未完成部分不作为阻塞前端实现的前置条件，也不被整体视作已经实现的语言能力。这里维护当前解析契约；源码位置见 [frontend](../../crates/frontend/README.md)。
+
+## 入口和所有权
+
+| API | 输入与结果 |
+| --- | --- |
+| lex(&str) | 产生 Vec<Token>；每个 token 只有种类和原始源码的字节范围，不复制文本 |
+| parse(&str) | 解析一个或多个完整函数定义，返回 Program；空输入和未消费的尾部内容报错 |
+| parse_expression(&str) | 解析一个完整表达式，不能忽略尾部 token |
+
+AST 的名称、数字原文和解码后的字符串均由 AST 自己持有，可以在释放输入后继续使用。Token／AST 的 Span 均为原始 UTF-8 源码的半开字节区间 start..end；节点跨度包含首尾 token 之间的空白及注释，不包含外侧 trivia。分组表达式的范围包括括号，Program 范围从第一个函数到最后一个函数。
+
+语法动作只构造 AST，不做 I/O、VM 分配或其他外部写入。PEG 回溯不会执行语言函数或产生宿主业务副作用。
+
+## 词法规则
+
+- 输入是有效 UTF-8 的 &str。CLI 使用严格的 read_to_string 读文件；其他编码由宿主先显式解码，不修改全局 locale。
+- 名称首字符为下划线或 Rust char::is_alphabetic，后续为下划线或 char::is_alphanumeric。这是当前明确采用的分类，不承诺 XID／NFKC 规则；没有自动规范化。中文、日文可用于名称，emoji 可以用于字符串。
+- 名称统一产生 Name token。function、let、return 只在相应语法位置按拼写识别，不预先固定全局保留字表；class、agent 等也仍可作为名称。
+- 数字为 ASCII 十进制数字，可带两边都有数字的小数部分；原文保留，不转换为 f64。负号单独分词；科学计数法、数字后缀、下划线分隔、前导正号、.5 和 1. 形式不在当前表达式语法中。
+- 双引号字符串允许 Unicode 文本，支持 `\n`、`\t`、`\"`、`\\`。token 范围包含引号，构造 AST 时解码转义。未闭合字符串、未知转义、裸换行和 NUL 报错；没有单引号、多行或插值字符串。
+- 空格、Tab、LF、CR 和 CRLF 分隔 token；缩进和换行不形成语句或代码块。`//` 到行末为注释，字符串内的 `//` 保持文本。没有块注释。
+- 支持 `(`、`)`、`{`、`}`、`:`、`,`、`.`、`=`、`+`、`-`、`*`、`/`；不接受分号和其他未支持字符。
+
+## 当前语法
+
+```text
+program   = function+
+function  = "function" name "(" parameters? ")" ":" name block
+parameter = name ":" name
+block     = "{" binding* "return" expression "}"
+binding   = "let" name "=" expression
+```
+
+parameters 和调用参数列表使用逗号分隔，不接受尾随逗号。函数体要求一个末尾 return；不支持独立表达式语句、重赋值、嵌套函数声明或默认参数源码写法。参数和返回类型目前只是名称节点；并不据此创建语言 type 对象或检查类型。
+
+表达式包括名称、数字、字符串、`.name` 符号、括号分组、成员访问与位置参数调用、一元负号以及四则运算。优先级从高到低为：
+
+1. 成员访问与调用，可任意连续组合，例如 factory(1).build(.title)("日文")。
+2. 一元负号，可嵌套。
+3. 乘除，从左到右结合。
+4. 加减，从左到右结合。
+
+符号字面量、名称与成员分别保留为独立 AST 结构。true、false、Nil 等词目前只是普通名称，没有额外的源码字面量或内建值绑定。
+
+use、namespace、class、agent、完整类型语法、条件／循环、比较／布尔运算和闭包声明等尚未加入首版。当前语法可修改；扩展时同步 AST、PEG 规则、样例和测试，不将旧草案视作不可修改的 ABI。
+
+## 诊断和命令
+
+词法和语法错误分别标记为 Lexical／Syntax。语法错误将 PEG 的 token 下标转换成原始源码 Span，保留期望项目列表；EOF 错误使用 source.len() 处的空区间。Diagnostic::location 返回一基行列，列按 Unicode 标量计数，CRLF 只算一次换行，不按字节列或字形簇计数。
+
+`cli parse <file>` 成功时输出 Rust Debug 格式的 AST，失败时在 stderr 输出文件／行／列和诊断并返回非零退出码。AST Debug 文本不是稳定的序列化协议。命令不执行源码、不初始化 VM、不连接数据库；具体运行与本地禁测约定见 [运行](../operations/README.md) 和 [验证](../operations/validation.md)。
+
+后续编译器应将 AST 经名称／闭包分析转换为现有字节码，不另设 AST 求值器；解析成功不表示表达式已有运行语义。VM 虽已支持 MakeFunction，但从源码创建函数仍需要编译器接入。解析器也不是不可信代码沙箱，当前没有通用输入大小或解析递归深度限额。

docs/runtime/text-encoding.md

@@ -20,10 +20,10 @@ Value::Text 与 EndorStringObject 使用 Rust String，始终是有效 UTF-8。
 
 String::from_utf8 验证字节；它不会自动识别 Shift_JIS，也不会自动转换编码。某些错误编码字节可能恰好仍是合法 UTF-8，因此“能通过 UTF-8 校验”也不能代替输入协议。[from_utf8 文档](https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8)。
 
-当前尚无通用文件／网络文本加载器、Shift_JIS 解码器或源码 parser；以上非 UTF-8 转换是未来宿主入口应遵守的边界，不是已经提供的内置转码能力。无需修改全局 locale 来处理单个文件。
+CLI parse 已有严格 UTF-8 文件读取，frontend 接收 &str 进行词法和语法解析。当前仍无通用文件／网络文本加载器或 Shift_JIS 解码器；以上非 UTF-8 转换由宿主显式提供，不是已有内置转码能力。无需修改全局 locale 来处理单个文件。
 
 ## 其他日文文本差异
 
-当前按 Unicode 标量值访问字符，不按人眼字形簇。预组合的“ガ”和“カ”加组合浊点可显示相似，但标量数量和序列不同；当前没有自动规范化或全角／半角转换。字符串和字典按当前内容语义处理，不为了所在地悄悄改写数据。源码标识符规则尚未定义。
+当前按 Unicode 标量值访问字符，不按人眼字形簇。预组合的“ガ”和“カ”加组合浊点可显示相似，但标量数量和序列不同；当前没有自动规范化或全角／半角转换。字符串和字典按当前内容语义处理，不为了所在地悄悄改写数据。前端当前采用的名称字符分类与源码位置规则见 [源码前端](frontend.md)，名称同样不自动规范化。
 
 宿主基础信息以 UTF-8 JSON 写入；控制键的 ASCII 命名限制属于文件信息协议，值可保存日文，详见 [宿主信息](../operations/host-information.md)。配置与 locale 见 [配置](../operations/configuration.md)，返回 [运行时索引](README.md)。