feat: generate unified AST and editor contracts from ASDL

docs/runtime/README.md

@@ -8,6 +8,7 @@
 | [基本对象与 Number](builtins.md) | 函数、原生函数、字典、Cell、异常数据、字符串与无损数字 |
 | [Endor 阅读器](reader.md) | SourceUnit、来源／修订标签、字符串／流／文件和宿主 URI provider |
 | [源码前端](frontend.md) | 字符 PEG lexer、token PEG parser、AST、基础函数／表达式语法与诊断 |
+| [AST 模型与 ASDL](ast.md) | 统一根、声明／语句／表达式、生成器、Visitor、位置和 JSON／编辑器接口 |
 | [字节码 VM](bytecode.md) | 指令编码、代码校验、局部槽、执行帧、函数创建、调用／返回与边界 |
 | [文本编码](text-encoding.md) | UTF-8、日文、外部 Shift_JIS／CP932 与宿主解码边界 |
 | [数据库特殊类](database-objects.md) | 显式连接、调用方数据模型、未来类接入与资源生命周期 |

docs/runtime/ast.md

@@ -0,0 +1,74 @@
+# AST 模型、ASDL 与跨工具接口
+
+Endor 的 AST 节点统一由 [Endor.asdl](../../crates/frontend/Endor.asdl) 定义。它描述节点及字段；lexer.peg 描述字符识别，grammar.peg 描述语法与节点构造。ASDL 与语法各自维护一个职责，不引入 CST 或 Python type／元类；AST 位于 frontend，运行时对象位于 objects。
+
+## 生成关系
+
+```text
+Endor.asdl → scripts/generate_ast.py
+           ├─ src/ast/generated.rs：Rust 节点、Serde 与 Spanned
+           ├─ src/ast/visitor.rs：Rust Visitor／walk_*
+           ├─ editor/ast.ts：TypeScript 类型、Visitor／walk*
+           └─ editor/ast.schema.json：JSON Schema 2020-12
+```
+
+路径均相对 crates/frontend。生成器使用 Python 标准库和 rustfmt，无额外 Python 包、build.rs 或构建时网络访问。产物提交到 Git，普通 Cargo 构建直接使用它们。开发修改 schema 后，在仓库根执行：
+
+```sh
+python3 scripts/generate_ast.py --write
+python3 scripts/generate_ast.py --check
+```
+
+这两条命令是源码生成／静态检查，可在本地使用；行为测试仍仅在指定远端执行。CI 检查生成同步，并运行生成器回归检查与工作区测试。
+
+ASDL 支持 module、产品类型 `(Type field, ...)`、构造器联合 `A(...) | B(...)`、`*` 序列、`?` 可选字段、`--` 行注释。内建 string 是拥有文本的 String，span 对应共享的 UTF-8 Span，schema_id 是交换契约标识。生成器检查重复名称、字段、未知类型和不支持的语法；这是项目使用的 ASDL 子集，不声称兼容 CPython ASDL 的全部扩展。
+
+Rust 用 struct／enum、Vec／Option 表达结构；生成器在按值依赖图的回边放置 Box，Vec 已经断开按值递归。增加节点后，Rust 类型、两种语言的遍历接口和 JSON Schema 由同一次生成更新。
+
+## 根、声明、语句、表达式
+
+| 层级 | 当前数据模型 |
+| --- | --- |
+| AstRoot | Module(Program)、Expression(Expr)、Interactive(InteractiveInput) |
+| Program | declarations: Vec<Decl> 与 span；当前声明种类为 Function |
+| Decl／DeclKind | 声明的位置及其具体种类；Function 保存参数、返回类型名称和 Block |
+| Block | statements: Vec<Stmt> 与 span，不再用固定的 bindings／result 字段表示 |
+| Stmt／StmtKind | Binding、Return、Expression、Declaration；每条语句有自身范围 |
+| ReturnStatement | 可选表达式与范围；当前源码中的 return 仍要求表达式 |
+| Expr／ExprKind | 名称、数字原文、字符串、符号、一元／二元运算、成员和调用 |
+
+参数与返回类型仍为 Name，只保留语法，不实施类型或名称检查。Program::functions() 提供函数迭代便捷接口。旧的 Program.functions、Block.bindings／result／return_span 字段已移除；源码构造和使用方改为声明／语句列表。ExprKind 的既有表达式结构保留。
+
+AST 数据模型允许一般语句列表，不代表 parser 接受了所有组合。模块仍要求一个或多个函数；函数体仍接受 let* 后跟一个带值 return。Interactive 模式接受一次函数声明、let 绑定或表达式，必须消费完整输入；不创建交互会话，不处理续行提示，不执行语言代码。多条交互提交由宿主分别解析。条件、循环、导入、类等尚未实现，也不加入 FunctionType 这种 Python 专用入口。
+
+## 解析与位置
+
+parse_ast(&str, ParseMode) 和 parse_source_ast(&SourceUnit, ParseMode) 返回 AstRoot；ParseMode 包含 Module、Expression、Interactive。原有 parse／parse_expression／parse_source／parse_source_expression 保留对应的具体返回类型。带来源入口的诊断仍记录名称／URI／修订和行列。
+
+Spanned 为有位置的节点提供 span()、source_text(&str)、location(&str)。Span::slice／location 拒绝反向、越界或截断 UTF-8 字符的范围；行列是一基 Unicode 标量列，CRLF 算一次换行。Span 不携带源码身份，调用方需关联原始 SourceUnit；AST JSON 本身不含源码、文件路径、URI 或资源修订。
+
+## 遍历与分析
+
+生成的 Rust Visitor 有每个节点／种类的 visit_* 方法、默认 walk_* 函数，以及 enter_node／leave_node 钩子。Error 为关联类型，子节点失败时默认遍历返回错误，并配对调用已进入节点的离开钩子。可在 visit_function、visit_binding、visit_expr 等位置实现名称分析或字节码生成。
+
+覆盖 visit_* 后，调用 walk_* 可继续访问子节点；覆盖方法自身的钩子管理由实现者决定，直接调用 walk_* 不会重复调用当前节点的 visit_*。这些接口只提供遍历，尚未实现名称绑定、闭包捕获分析或字节码生成。TypeScript Visitor 对应编辑器使用，回调返回 false 可跳过子树。
+
+## JSON 交换
+
+frontend 使用工作区已有的 serde／serde_json。AstDocument 是带 schema 和 root 的交换外壳，提供 new、to_json、from_json、validate、validate_source。构造／读取／写出时检查 schema 标识、位置顺序、父子范围包含关系及 JS 安全整数范围；validate_source 额外检查给定原文的长度和 UTF-8 字符边界，不比较原文与节点的程序含义。
+
+构造器联合按 `{"kind":"Variant","data":...}` 编码，无字段的运算符联合使用字符串。产品类型使用字段对象；未知字段和未知构造器拒绝。可选字段可省略或为 null，标准写出为 null。数字保留源码拼写字符串，不经浮点转换。
+
+AST_SCHEMA_ID 从 Endor.asdl 的 UTF-8 文本计算 SHA-256，包含注释与空白；生成器读取时使用 Python 的统一换行规则。它标识这套 AST 接口定义，区别于用户资源修订、编译器或 VM 版本。修改 schema 后旧标识被拒绝，尚无历史格式迁移。改变生成器的交换编码或内建位置类型契约时，也必须更新 ASDL 顶部的 Wire contract 版本说明，使标识随之变化。直接调用 Serde 是结构编解码，跨边界应使用 AstDocument 方法执行完整校验；JSON Schema 不表达所有位置约束。
+
+CLI 可提供具体的交换输出：
+
+```sh
+cli parse --json source.endor
+cli parse --mode expression --json -
+cli parse --mode interactive --json -
+```
+
+文件／stdin 阅读保持原有 UTF-8 和错误来源规则，stdin 到 EOF 后才解析。普通 cli parse 输出 AstRoot 的 Debug 文本，稳定交换使用带 schema 的 JSON；所有入口均不执行源码。命令在指定远端运行。
+
+检查源码见 [frontend/tests](../../crates/frontend/tests/README.md) 和 [生成器检查](../../scripts/test_generate_ast.py)，边界见 [验证](../operations/validation.md)。返回 [运行时索引](README.md)。

docs/runtime/frontend.md

@@ -13,7 +13,7 @@ frontend 包提供 [Endor 阅读器](reader.md)、rust-peg 生成的字符 lexer
 | [lexer.peg](../../crates/frontend/src/lexer.peg) | str 字符输入，识别名称、数字、字符串／转义、标点、空白／注释及词法错误，生成 Token | [lexer.rs](../../crates/frontend/src/lexer.rs) 保留 lex／lex_source、游标、位置换算和字符串解码 |
 | [grammar.peg](../../crates/frontend/src/grammar.peg) | [Token] 输入，匹配函数／绑定／return、表达式优先级并构造 AST | [parser.rs](../../crates/frontend/src/parser.rs) 保留解析入口、诊断转换和 AST 辅助函数 |
 
-lexer.rs 与 parser.rs 分别通过 include! 在编译期引入对应规则；两份 .peg 文件保留 peg::parser! 外层声明，直接参与编译，不新增 build.rs、生成脚本或依赖。远端检查脚本单独对两份规则执行 rustfmt。
+lexer.rs 与 parser.rs 分别通过 include! 在编译期引入对应规则；两份 .peg 文件保留 peg::parser! 外层声明，直接参与编译，自身不需要 build.rs 或生成脚本。AST 类型另由 Endor.asdl 离线生成，交换接口使用 serde／serde_json，见 [AST 模型](ast.md)。远端检查脚本单独对两份规则执行 rustfmt。
 
 字符 PEG 的内部 next 规则使用 #[no_eof] 每次识别一个前缀，跳过空白／注释并返回一个 Token 或输入结束。Lexer 保存 source／offset，循环调用该规则，直到全输入结束或首个错误；公开 lex 仍扫描整份输入，不是增量／可恢复输入接口。规则中的 position! 相对本次输入切片，lexer.rs 将 Token 和诊断位置统一换算为原始源码 UTF-8 字节范围。
 
@@ -29,8 +29,10 @@ lexer.rs 与 parser.rs 分别通过 include! 在编译期引入对应规则；
 | lex(&str) | 产生 Vec<Token>；每个 token 只有种类和原始源码的字节范围，不复制文本 |
 | parse(&str) | 解析一个或多个完整函数定义，返回 Program；空输入和未消费的尾部内容报错 |
 | parse_expression(&str) | 解析一个完整表达式，不能忽略尾部 token |
+| parse_ast(&str, ParseMode) | 返回 Module／Expression／Interactive 三类 AstRoot，模式独立于输入来源 |
+| parse_source_ast(&SourceUnit, ParseMode) | 同一统一入口，失败保留来源、修订和行列 |
 
-AST 的名称、数字原文和解码后的字符串均由 AST 自己持有，可以在释放输入后继续使用。Token／AST 的 Span 均为原始 UTF-8 源码的半开字节区间 start..end；节点跨度包含首尾 token 之间的空白及注释，不包含外侧 trivia。分组表达式的范围包括括号，Program 范围从第一个函数到最后一个函数。
+AST 结构及 Visitor、Spanned 和跨工具 JSON 契约见 [AST 模型](ast.md)。Program 使用 declarations，Block 使用 statements；ExprKind 保留既有表达式形状。AST 的名称、数字原文和解码后的字符串均由 AST 自己持有，可以在释放输入后继续使用。Token／AST 的 Span 均为原始 UTF-8 源码的半开字节区间 start..end；节点跨度包含首尾 token 之间的空白及注释，不包含外侧 trivia。分组表达式的范围包括括号，Program 范围从第一个函数到最后一个函数。
 
 词法动作只返回 Token／诊断，语法动作只构造 AST；两者均不做 I/O、VM 分配或其他外部写入。PEG 回溯不会执行语言函数或产生宿主业务副作用。
 
@@ -54,7 +56,7 @@ block     = "{" binding* "return" expression "}"
 binding   = "let" name "=" expression
 ```
 
-parameters 和调用参数列表使用逗号分隔，不接受尾随逗号。函数体要求一个末尾 return；不支持独立表达式语句、重赋值、嵌套函数声明或默认参数源码写法。参数和返回类型目前只是名称节点；并不据此创建语言 type 对象或检查类型。
+parameters 和调用参数列表使用逗号分隔，不接受尾随逗号。函数体要求一个末尾 return；函数体尚不支持独立表达式语句、重赋值、嵌套函数声明或默认参数源码写法。新增 Interactive 解析模式接受一次函数声明、let 绑定或表达式，完整消费输入，但不创建 REPL 或执行代码；AST 可表示的语句组合比当前源码子集更广。参数和返回类型目前只是名称节点；并不据此创建语言 type 对象或检查类型。
 
 表达式包括名称、数字、字符串、`.name` 符号、括号分组、成员访问与位置参数调用、一元负号以及四则运算。优先级从高到低为：
 
@@ -71,6 +73,6 @@ use、namespace、class、agent、完整类型语法、条件／循环、比较
 
 词法和语法错误分别标记为 Lexical／Syntax。语法错误将 PEG 的 token 下标转换成原始源码 Span，保留期望项目列表；EOF 错误使用 source.len() 处的空区间。Diagnostic::location 返回一基行列，列按 Unicode 标量计数，CRLF 只算一次换行，不按字节列或字形簇计数。
 
-`cli parse <file>` 与 `cli parse -` 成功时输出 Rust Debug 格式的 AST，失败时在 stderr 输出来源／行／列和诊断并返回非零退出码；`-` 表示从 stdin 读到 EOF，不是 REPL。阅读与来源包装规则见 [阅读器](reader.md)。AST Debug 文本不是稳定的序列化协议。命令不执行源码、不初始化 VM、不连接数据库；具体运行与本地禁测约定见 [运行](../operations/README.md) 和 [验证](../operations/validation.md)。
+`cli parse <file>` 与 `cli parse -` 成功时输出 Rust Debug 格式的 AST，失败时在 stderr 输出来源／行／列和诊断并返回非零退出码；`-` 表示从 stdin 读到 EOF，不是 REPL。阅读与来源包装规则见 [阅读器](reader.md)。可用 --mode 选择 module／expression／interactive，用 --json 输出带 schema 标识的 AstDocument；普通输出为 AstRoot Debug 文本，稳定交换格式见 [AST 模型](ast.md)。命令不执行源码、不初始化 VM、不连接数据库；具体运行与本地禁测约定见 [运行](../operations/README.md) 和 [验证](../operations/validation.md)。
 
 后续需要将 AST 经名称／闭包分析转换为现有字节码，再交给 VM 解释执行。这是解释器内部的编译／执行准备步骤，不要求使用者先构建程序，见 [执行与版本模型](../architecture/execution-and-versions.md)。这条连接尚未实现；解析成功不表示表达式已有运行语义。VM 虽已支持 MakeFunction，但从源码创建函数仍需要字节码生成接入。解析器也不是不可信代码沙箱，当前没有通用输入大小或解析递归深度限额。