docs(frontend): persist generated AST and visitor annotations

This commit is contained in:
2026-11-15 19:06:33 +08:00
parent 89f6aaecf7
commit 52e62d5839
4 changed files with 788 additions and 16 deletions
+136
View File
@@ -2,23 +2,33 @@
use super::Spanned;
use crate::Span;
/// wire/编辑器核对的协议身份,来自 ASDL 原文哈希;生成节点注释不参与此值。
pub const AST_SCHEMA_ID: &str =
"urn:endor:ast:sha256:21b0349ac295d9bc8cedcad8f07d8e2d45cf220e19e7c2fad10269555fcfd71a";
/// 宿主/编辑器传输的版本化语法文档,wire 校验后供 compiler 使用。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AstDocument {
/// 协议身份,wire 按 AST_SCHEMA_ID 核对;不是源码内容哈希。
pub schema: String,
/// 拥有的语法根,文档校验及编译从这里递归。
pub root: AstRoot,
}
/// parse_ast 按模式构造的模块、表达式或交互根,compiler 据此选择生成入口。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind", content = "data", deny_unknown_fields)]
pub enum AstRoot {
/// 模块根,包含函数/类声明。
Module(Program),
/// 表达式根,编译后直接返回求值结果。
Expression(Expr),
/// 交互根,包含一次完整提交。
Interactive(InteractiveInput),
}
impl Spanned for AstRoot {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
// 按实际构造器取得唯一可定位子节点的范围。
match self {
Self::Module(node) => node.span(),
Self::Expression(node) => node.span(),
@@ -26,129 +36,184 @@ impl Spanned for AstRoot {
}
}
}
/// parser 复制的名称文本与位置,用于声明、类型注解或属性名。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Name {
/// 拥有名称文本,不依赖输入缓冲存活。
pub text: String,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Name {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 模块声明序列,compiler 先注册全部顶层名称再分析各函数体。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Program {
/// 按源码顺序的声明;源码模块解析要求非空,文档结构本身不限制数量。
pub declarations: Vec<Decl>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Program {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 顶层/交互声明的种类及完整范围,compiler 按函数或类分派。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Decl {
/// 函数/类声明载荷,JSON 和类型采用 kind/data 标签。
pub kind: DeclKind,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Decl {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 函数与类声明的判别载荷,外层 Decl 另外保存完整跨度。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind", content = "data", deny_unknown_fields)]
pub enum DeclKind {
/// 显式参数/返回注解与函数体,compiler 生成独立模板及源码签名;解析本身不调用函数。
Function(Function),
/// 类名、可选基类、字段和方法,compiler 检查成员后生成构类指令。
Class(Class),
}
impl Spanned for DeclKind {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
// 按实际构造器取得唯一可定位子节点的范围。
match self {
Self::Function(node) => node.span(),
Self::Class(node) => node.span(),
}
}
}
/// 类名、可选基类、字段和方法,compiler 检查成员后生成构类指令。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Class {
/// 类声明名与精确位置。
pub name: Name,
/// 显式基类名,可省略;当前 compiler 对省略项使用 Object。
pub base: Option<Name>,
/// 按出现顺序的字段名称/类型注解,不含方法。
pub fields: Vec<Parameter>,
/// 按出现顺序的方法;显式 self 约束由 compiler 检查。
pub methods: Vec<Function>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Class {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 显式参数/返回注解与函数体,compiler 生成独立模板及源码签名;解析本身不调用函数。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Function {
/// 函数/方法名,代码模板沿用为诊断名称。
pub name: Name,
/// 位置参数列表,compiler 依次分配前部局部槽。
pub parameters: Vec<Parameter>,
/// 返回类型名,生成源码签名后由运行时解析。
pub return_type: Name,
/// 独立函数作用域的语句体,当前源码不支持嵌套声明闭包。
pub body: Block,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Function {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 函数参数或类字段共用的名称/类型注解,实际类型身份由运行时环境解析。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Parameter {
/// 参数/字段名,用于布局和重复检查。
pub name: Name,
/// 声明类型名,前端只保留文本与位置。
pub type_name: Name,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Parameter {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 顺序语句块,compiler 检查确定初始化并按语句生成指令。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Block {
/// 有序语句列表,不引入独立块级局部作用域。
pub statements: Vec<Stmt>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Block {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 语句种类及原文范围,compiler 处理副作用、控制流或返回。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Stmt {
/// 具体语句载荷,外层另存整句范围。
pub kind: StmtKind,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Stmt {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 语句判别载荷,parser 选择分支,compiler 按绑定、赋值、控制流等规则处理。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind", content = "data", deny_unknown_fields)]
pub enum StmtKind {
/// let 新绑定,compiler 检查重名并分析右值后才标记目标已初始化。
Binding(Binding),
/// 普通名称赋值,compiler 按作用域写局部槽或全局环境。
Assignment(Assignment),
/// 成员写入的对象、属性名与右值,compiler 生成 StoreAttr。
MemberAssignment(MemberAssignment),
/// 条件、then 和可选 else,compiler 合并继续路径的初始化集合并生成跳转。
If(IfStatement),
/// 循环条件与体,compiler 生成回边并处理循环可能零次执行。
While(WhileStatement),
/// 函数返回,compiler 对缺省值补 Nil;当前源码语法要求 return 后有表达式。
Return(ReturnStatement),
/// 表达式载荷及完整范围,compiler 生成留下一个结果的求值序列。
Expression(Expr),
/// 顶层/交互声明的种类及完整范围,compiler 按函数或类分派。
Declaration(Decl),
}
impl Spanned for StmtKind {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
// 按实际构造器取得唯一可定位子节点的范围。
match self {
Self::Binding(node) => node.span(),
Self::Assignment(node) => node.span(),
@@ -161,141 +226,212 @@ impl Spanned for StmtKind {
}
}
}
/// let 新绑定,compiler 检查重名并分析右值后才标记目标已初始化。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Binding {
/// let 目标名,重复声明由语义分析拒绝。
pub name: Name,
/// 绑定右值,本局部不能在初始化前读取自身。
pub value: Expr,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Binding {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 普通名称赋值,compiler 按作用域写局部槽或全局环境。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Assignment {
/// 普通赋值目标,函数内首次赋值可预分配局部槽。
pub name: Name,
/// 先求右值再更新目标。
pub value: Expr,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Assignment {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 成员写入的对象、属性名与右值,compiler 生成 StoreAttr。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MemberAssignment {
/// 属性写入接收对象表达式,前端不求值。
pub object: Expr,
/// 待写属性名,compiler 加入名字表。
pub name: Name,
/// 待写右值,当前 compiler 先于接收对象生成求值以匹配 VM 栈布局。
pub value: Expr,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for MemberAssignment {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 条件、then 和可选 else,compiler 合并继续路径的初始化集合并生成跳转。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct IfStatement {
/// 条件表达式,运行时按真值协议选择分支。
pub condition: Expr,
/// 条件为真的 then 块。
pub body: Block,
/// 可选 else 块,缺省时存在直接继续路径。
pub otherwise: Option<Block>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for IfStatement {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 循环条件与体,compiler 生成回边并处理循环可能零次执行。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WhileStatement {
/// 每轮重新求值的条件,假值退出。
pub condition: Expr,
/// 循环体,可能一次也不执行。
pub body: Block,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for WhileStatement {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 函数返回,compiler 对缺省值补 Nil;当前源码语法要求 return 后有表达式。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ReturnStatement {
/// 可选返回表达式,手工 AST 缺省时由 compiler 补 Nil。
pub value: Option<Expr>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for ReturnStatement {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 单次交互提交容器,parser 产生一条语句,compiler 也检查数量,不保存宿主会话环境。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InteractiveInput {
/// 当前 parse/compile 约定恰好一个完整提交的语句。
pub statements: Vec<Stmt>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for InteractiveInput {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 表达式载荷及完整范围,compiler 生成留下一个结果的求值序列。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Expr {
/// 求值形状,不缓存名称解析或运行时类型。
pub kind: ExprKind,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Expr {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 名称、字面量、等待、运算和调用等表达式载荷,范围由外层 Expr 提供。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind", content = "data", deny_unknown_fields)]
pub enum ExprKind {
/// 变量引用文本,compiler 决定局部槽或全局索引。
Name(String),
/// 原始十进制拼写,保留全部位数、前导零及尾零,不转浮点。
Number(String),
/// 已解码受支持转义的拥有文本,原引号范围在外层 Expr。
String(String),
/// 点开头的符号名,前端可表示,当前 compiler 拒绝生成运行时值。
Symbol(Name),
/// 等待子表达式,VM 执行上下文决定是否允许停放。
Await(Box<Expr>),
/// 一元取负,可在纯数值链上合并符号。
Unary {
/// 运算种类,决定算术、比较或取负指令。
operation: UnaryOp,
/// 一元子表达式,Rust 的递归回边间接存储。
operand: Box<Expr>,
},
/// 左右操作数及算术/比较种类,保留解析优先级树。
Binary {
/// 运算种类,决定算术、比较或取负指令。
operation: BinaryOp,
/// 二元左操作数,当前 compiler 先于右侧求值。
left: Box<Expr>,
/// 二元右操作数,与左侧一起被运行时运算消费。
right: Box<Expr>,
},
/// 接收对象及属性名的读取。
Member {
/// 成员读取接收对象。
object: Box<Expr>,
/// 成员或符号名,不是已解析的运行时属性句柄。
name: Name,
},
/// 被调用表达式与位置实参,由 VM 实际求值。
Call {
/// 调用目标,先于实参求值。
callee: Box<Expr>,
/// 有序位置实参,AST 不隐式添加接收者。
arguments: Vec<Expr>,
},
}
/// 一元运算种类,compiler 合并纯数值负号或生成运行时取负。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, Copy)]
pub enum UnaryOp {
/// 一元取负。
Negate,
}
/// 二元算术/比较种类,parser 保留优先级树,compiler 映射为对应 VM 操作。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, Copy)]
pub enum BinaryOp {
/// 加法。
Add,
/// 减法。
Subtract,
/// 乘法。
Multiply,
/// 除法。
Divide,
/// 相等比较。
Equal,
/// 不等比较。
NotEqual,
/// 小于比较。
Less,
/// 小于等于比较。
LessEqual,
/// 大于比较。
Greater,
/// 大于等于比较。
GreaterEqual,
}