From 4db6e6afd6ca8a0654017b3193f118e60ca1e4da Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 10:35:49 +0800 Subject: [PATCH] feat(ir): executable IR, module/unit identities and builtin metadata Add the independent program IR from blueprint sections 7.1 and 11: - ModuleId, FunctionId and UnitId canonical identities; UnitInfo/UnitKind for heading scopes (root, namespace, function, section). - Function with explicit or inferred signature metadata, params and defaults; assignments, expression statements, link-form calls, branches, loops and returns, all carrying source spans. - CallTarget distinguishes same-module, import-alias-qualified and link-resolved calls. - ImportDecl from explicit front-matter imports; Resource records inert Formula/Code artifacts with SHA-256 content hashes and owning units. - Module anchors, resolved import edges and Program lookup helpers used by the runtime and CLI. - Builtin registry (names, aliases, arity, named-only/effect flags) shared by static validation and runtime dispatch; adding a builtin is a spec change. Prose is absent from the IR by construction, so narrative edits cannot change the executable projection. --- crates/marqdo-ir/Cargo.toml | 5 +- crates/marqdo-ir/src/builtins.rs | 277 ++++++++++++++++++ crates/marqdo-ir/src/lib.rs | 481 +++++++++++++++++++++++++++++++ 3 files changed, 761 insertions(+), 2 deletions(-) create mode 100644 crates/marqdo-ir/src/builtins.rs create mode 100644 crates/marqdo-ir/src/lib.rs diff --git a/crates/marqdo-ir/Cargo.toml b/crates/marqdo-ir/Cargo.toml index b73ef0c..e664692 100644 --- a/crates/marqdo-ir/Cargo.toml +++ b/crates/marqdo-ir/Cargo.toml @@ -10,8 +10,9 @@ authors.workspace = true [dependencies] marqdo-span = { workspace = true } -marqdo-value = { workspace = true } marqdo-expression = { workspace = true } serde = { workspace = true } -serde_json = { workspace = true } + +[dev-dependencies] +serde_json = { workspace = true } diff --git a/crates/marqdo-ir/src/builtins.rs b/crates/marqdo-ir/src/builtins.rs new file mode 100644 index 0000000..c0e4f27 --- /dev/null +++ b/crates/marqdo-ir/src/builtins.rs @@ -0,0 +1,277 @@ +//! Builtin function metadata shared by the frontend (static validation) and the +//! runtime (dispatch). Adding a builtin is a language change: update +//! `spec/evaluation.md` §8 together with this table. + +/// One builtin parameter. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct BuiltinParam { + /// Parameter name used in diagnostics. + pub name: &'static str, + /// Whether callers must provide it. + pub required: bool, +} + +const fn req(name: &'static str) -> BuiltinParam { + BuiltinParam { + name, + required: true, + } +} + +const fn opt(name: &'static str) -> BuiltinParam { + BuiltinParam { + name, + required: false, + } +} + +/// A builtin function or host operation. +#[derive(Debug, Clone, Copy)] +pub struct Builtin { + /// Canonical call name (may be namespaced, e.g. `math.eval`). + pub name: &'static str, + /// Alternative names (Chinese/English aliases). + pub aliases: &'static [&'static str], + /// Parameters in declaration order. + pub params: &'static [BuiltinParam], + /// Whether all arguments must be named (inferred-style API) rather than + /// positional. + pub named_only: bool, + /// Whether invoking it has an effect that requires host authorization. + pub effectful: bool, +} + +impl Builtin { + /// Whether `name` refers to this builtin. + pub fn matches(&self, name: &str) -> bool { + self.name == name || self.aliases.contains(&name) + } +} + +const PRINT: Builtin = Builtin { + name: "打印", + aliases: &["print"], + params: &[req("值")], + named_only: false, + effectful: true, +}; +const LEN: Builtin = Builtin { + name: "长度", + aliases: &["len"], + params: &[req("值")], + named_only: false, + effectful: false, +}; +const TYPE_OF: Builtin = Builtin { + name: "类型", + aliases: &["type"], + params: &[req("值")], + named_only: false, + effectful: false, +}; +const STR: Builtin = Builtin { + name: "文本", + aliases: &["str"], + params: &[req("值")], + named_only: false, + effectful: false, +}; +const INT: Builtin = Builtin { + name: "整数", + aliases: &["int"], + params: &[req("值")], + named_only: false, + effectful: false, +}; +const FLOAT: Builtin = Builtin { + name: "小数", + aliases: &["float"], + params: &[req("值")], + named_only: false, + effectful: false, +}; +const TABLE: Builtin = Builtin { + name: "表", + aliases: &["table"], + params: &[req("表头"), req("行")], + named_only: false, + effectful: false, +}; +const REF: Builtin = Builtin { + name: "ref", + aliases: &[], + params: &[req("目标")], + named_only: false, + effectful: false, +}; +const MATH_PARSE: Builtin = Builtin { + name: "math.parse", + aliases: &[], + params: &[req("formula")], + named_only: false, + effectful: false, +}; +const MATH_EVAL: Builtin = Builtin { + name: "math.eval", + aliases: &[], + params: &[req("formula"), req("bindings"), opt("target")], + named_only: true, + effectful: false, +}; +const MATH_SUBSTITUTE: Builtin = Builtin { + name: "math.substitute", + aliases: &[], + params: &[req("formula"), req("bindings")], + named_only: true, + effectful: false, +}; +const MATH_SIMPLIFY: Builtin = Builtin { + name: "math.simplify", + aliases: &[], + params: &[req("formula")], + named_only: false, + effectful: false, +}; +const MATH_DIFFERENTIATE: Builtin = Builtin { + name: "math.differentiate", + aliases: &[], + params: &[req("formula"), req("变量")], + named_only: true, + effectful: false, +}; +const FOREIGN_RUN: Builtin = Builtin { + name: "foreign.run", + aliases: &[], + params: &[req("ref"), opt("input")], + named_only: true, + effectful: true, +}; +const FOREIGN_CALL: Builtin = Builtin { + name: "foreign.call", + aliases: &[], + params: &[req("ref"), req("input")], + named_only: true, + effectful: true, +}; +const FS_READ: Builtin = Builtin { + name: "fs.read", + aliases: &[], + params: &[req("path")], + named_only: false, + effectful: true, +}; +const FS_WRITE: Builtin = Builtin { + name: "fs.write", + aliases: &[], + params: &[req("path"), req("contents")], + named_only: false, + effectful: true, +}; + +/// All builtins known to the language. Host availability is decided at call +/// time by the capability layer, not here. +pub const BUILTINS: &[Builtin] = &[ + PRINT, + LEN, + TYPE_OF, + STR, + INT, + FLOAT, + TABLE, + REF, + MATH_PARSE, + MATH_EVAL, + MATH_SUBSTITUTE, + MATH_SIMPLIFY, + MATH_DIFFERENTIATE, + FOREIGN_RUN, + FOREIGN_CALL, + FS_READ, + FS_WRITE, +]; + +/// Find a builtin by canonical name or alias. +pub fn find(name: &str) -> Option<&'static Builtin> { + BUILTINS.iter().find(|builtin| builtin.matches(name)) +} + +/// Validate an argument list against a builtin parameter list. +/// +/// Returns `Ok(())` when every required parameter is supplied and no unknown +/// name is used; positional arguments are matched by declaration order. +pub fn validate_args(builtin: &Builtin, args: &[marqdo_expression::Arg]) -> Result<(), String> { + if builtin.named_only && args.iter().any(|arg| arg.name.is_none()) { + return Err(format!("`{}` only accepts named arguments", builtin.name)); + } + let mut provided = Vec::new(); + let mut positional = 0usize; + for arg in args { + match &arg.name { + Some(name) => { + if !builtin.params.iter().any(|param| param.name == name) { + return Err(format!( + "`{}` has no parameter named `{name}`", + builtin.name + )); + } + if provided.contains(name) { + return Err(format!("duplicate argument `{name}`")); + } + provided.push(name.clone()); + } + None => { + let Some(param) = builtin.params.get(positional) else { + return Err(format!( + "`{}` accepts at most {} positional arguments", + builtin.name, + builtin.params.len() + )); + }; + if provided.contains(¶m.name.to_string()) { + return Err(format!("duplicate argument `{}`", param.name)); + } + provided.push(param.name.to_string()); + positional += 1; + } + } + } + for param in builtin.params { + if param.required && !provided.iter().any(|name| name == param.name) { + return Err(format!( + "`{}` is missing required argument `{}`", + builtin.name, param.name + )); + } + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn lookup_aliases() { + assert_eq!(find("print").unwrap().name, "打印"); + assert_eq!(find("打印").unwrap().name, "打印"); + assert!(find("math.eval").unwrap().named_only); + assert!(find("nope").is_none()); + } + + #[test] + fn arity_validation() { + use marqdo_expression::parse_arguments; + let print = find("打印").unwrap(); + assert!(validate_args(print, &parse_arguments("(1)").unwrap()).is_ok()); + assert!(validate_args(print, &parse_arguments("()").unwrap()).is_err()); + let eval = find("math.eval").unwrap(); + assert!(validate_args( + eval, + &parse_arguments("(formula=ref(\"#x\"), bindings={}, target=\"A\")").unwrap() + ) + .is_ok()); + // math.eval is named-only: positional arguments are rejected. + assert!(validate_args(eval, &parse_arguments("(ref(\"#x\"), {})").unwrap()).is_err()); + assert!(validate_args(eval, &parse_arguments("(1, 2)").unwrap()).is_err()); + } +} diff --git a/crates/marqdo-ir/src/lib.rs b/crates/marqdo-ir/src/lib.rs new file mode 100644 index 0000000..661d4e9 --- /dev/null +++ b/crates/marqdo-ir/src/lib.rs @@ -0,0 +1,481 @@ +//! Executable IR produced from the canonical Markdown AST. +//! +//! The IR is a *program* representation, never a second Markdown parser: it is +//! produced only by `marqdo-frontend` from `marqdo-markdown` nodes and carries +//! spans that point back into the original source. Prose nodes are deliberately +//! absent, so changing narrative text cannot change the IR (blueprint 14.2). +//! +//! Every executable construct keeps the source span of the Markdown node that +//! defined it, which is what diagnostics, `inspect --ir` and the interpreter +//! need. Values used at compile time (signature defaults) are explicit. + +use std::collections::BTreeMap; +use std::fmt; + +use marqdo_expression::{Arg, Expr}; +use marqdo_span::Span; +use serde::{Deserialize, Serialize}; + +pub mod builtins; + +/// Canonical identity of a module: project-relative path with `/` separators. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] +pub struct ModuleId(pub String); + +impl fmt::Display for ModuleId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.0) + } +} + +impl From<&str> for ModuleId { + fn from(value: &str) -> Self { + ModuleId(value.to_string()) + } +} + +/// Canonical identity of a function: module plus canonical function name. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] +pub struct FunctionId { + /// Owning module. + pub module: ModuleId, + /// Canonical (normalised) function name. + pub name: String, +} + +impl fmt::Display for FunctionId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "{}::{}", self.module, self.name) + } +} + +/// Identity of an addressable heading range. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] +pub struct UnitId { + /// Owning module. + pub module: ModuleId, + /// Canonical heading path, from the outermost heading to this unit. + pub path: Vec, +} + +impl fmt::Display for UnitId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "{}#", self.module)?; + for (index, part) in self.path.iter().enumerate() { + if index > 0 { + f.write_str("/")?; + } + f.write_str(part)?; + } + Ok(()) + } +} + +/// Role of a heading range. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum UnitKind { + /// Document root. + Root, + /// Level-1 heading: namespace / object domain. + Namespace, + /// Level-2 heading: function. + Function, + /// Level-3+ heading inside a function: named section, not a callable unit. + Section, +} + +/// One addressable heading range. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct UnitInfo { + /// Canonical unit identity. + pub id: UnitId, + /// Heading level (0 for the root). + pub level: u8, + /// Normalised heading name (empty for the root). + pub name: String, + /// Span of the heading node (empty span for the root). + pub span: Span, + /// Role of this unit. + pub kind: UnitKind, + /// Function defined by this unit, if any. + #[serde(skip_serializing_if = "Option::is_none")] + pub function: Option, +} + +/// How a function's parameter list was established. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum SignatureKind { + /// Declared by a signature paragraph after the heading. + Explicit, + /// Inferred from free variable reads by data-flow analysis. + Inferred, +} + +/// One function parameter. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct Param { + /// Parameter name. + pub name: String, + /// Span of the parameter occurrence (signature or first read). + pub span: Span, + /// Optional type annotation text (explicit signatures only). + #[serde(skip_serializing_if = "Option::is_none")] + pub type_annotation: Option, + /// Compile-time constant default expression, if declared. + #[serde(skip_serializing_if = "Option::is_none")] + pub default: Option, +} + +/// A function definition mapped from a level-2 heading range. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct Function { + /// Canonical function identity (namespace-qualified when namespaced). + pub id: FunctionId, + /// Function name as written in its own namespace. + pub local_name: String, + /// Enclosing level-1 namespace, if any. + #[serde(skip_serializing_if = "Option::is_none")] + pub namespace: Option, + /// Addressable unit defined by the heading. + pub unit: UnitId, + /// Heading span. + pub heading_span: Span, + /// Declaration span (heading through end of range). + pub span: Span, + /// Parameters in canonical (sorted) order for inferred signatures, in + /// declaration order for explicit ones. + pub params: Vec, + /// Whether the signature was explicit or inferred. + pub signature: SignatureKind, + /// Function body in executable order. + pub body: Vec, +} + +/// An executable statement. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(tag = "stmt", rename_all = "snake_case")] +pub enum Stmt { + /// Local assignment (`strong` node with `name = expr`). + Assign { + /// Target name. + name: String, + /// Span of the target name (approximated by the payload span). + name_span: Span, + /// Value expression. + value: Expr, + /// Span of the whole statement. + span: Span, + }, + /// Expression statement, e.g. a call whose result is discarded. + Eval { + /// Expression to evaluate. + expr: Expr, + /// Span of the whole statement. + span: Span, + }, + /// Markdown-link call form from a block quote. + Call { + /// Resolved call site. + call: CallSite, + /// Span of the whole statement. + span: Span, + }, + /// Ordered list: first matching condition wins. + Branch { + /// Arms in AST order. + arms: Vec, + /// Span of the list node. + span: Span, + }, + /// Bullet list item: a `while` loop. + Loop { + /// Loop condition. + condition: Expr, + /// Span of the condition payload. + condition_span: Span, + /// Loop body. + body: Vec, + /// Span of the list item. + span: Span, + }, + /// Return from the enclosing function (`emph` node). + Return { + /// Returned expression. + value: Expr, + /// Span of the whole return node. + span: Span, + }, +} + +impl Stmt { + /// Span of the statement. + pub fn span(&self) -> Span { + match self { + Stmt::Assign { span, .. } + | Stmt::Eval { span, .. } + | Stmt::Call { span, .. } + | Stmt::Branch { span, .. } + | Stmt::Loop { span, .. } + | Stmt::Return { span, .. } => *span, + } + } +} + +/// One arm of a branch (ordered list item). +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct BranchArm { + /// Boolean condition expression. + pub condition: Expr, + /// Span of the condition code span. + pub condition_span: Span, + /// Statements executed when the condition is true. + pub body: Vec, + /// Span of the whole list item. + pub span: Span, +} + +/// Target of a call statement. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(tag = "target", rename_all = "snake_case")] +pub enum CallTarget { + /// Unqualified function in the current module. + Function { + /// Canonical function name. + name: String, + }, + /// Function reached through an imported module alias. + Qualified { + /// Local import alias. + module_alias: String, + /// Canonical function name. + function: String, + }, + /// Function resolved from a Markdown link target. + Resolved { + /// Canonical module identity. + module: ModuleId, + /// Canonical function name. + function: String, + }, +} + +/// A call statement with evaluated arguments. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct CallSite { + /// Callee target. + pub target: CallTarget, + /// Arguments in source order. + pub args: Vec, + /// Span of the call. + pub span: Span, +} + +/// One explicit import declared in front matter. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ImportDecl { + /// Local alias used in expressions (`geometry.圆面积(...)`). + pub alias: String, + /// Declared module address as written. + pub target: String, + /// Span of the front matter. + pub span: Span, +} + +/// An inert document resource addressable through `ref`. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(tag = "resource", rename_all = "snake_case")] +pub enum Resource { + /// A math formula inside a unit range. + Formula { + /// Unit that contains the formula. + unit: UnitId, + /// Raw LaTeX without delimiters. + latex: String, + /// Display math flag. + display: bool, + /// Source span. + span: Span, + }, + /// A fenced code block inside a unit range. + Code { + /// Unit that contains the code block. + unit: UnitId, + /// Fence language (empty for plain fences). + language: String, + /// Fence source. + source: String, + /// SHA-256 of the source, for content integrity checks. + content_hash: String, + /// Source span. + span: Span, + }, +} + +/// A compiled module. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct Module { + /// Canonical module identity. + pub id: ModuleId, + /// Addressable units in document order. + pub units: Vec, + /// Functions in document order. + pub functions: Vec, + /// Explicit imports. + pub imports: Vec, + /// Inert resources (formulas, code fences) in document order. + pub resources: Vec, + /// GitHub-style anchors for `ref("#...")` lookups. Anchors are a separate + /// namespace from canonical unit ids. + #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] + pub anchors: BTreeMap, +} + +impl Module { + /// Find a function by canonical qualified name, local name or (when unique) + /// local name across namespaces. + pub fn function(&self, name: &str) -> Option<&Function> { + if let Some(found) = self.functions.iter().find(|f| f.id.name == name) { + return Some(found); + } + let mut matches = self.functions.iter().filter(|f| f.local_name == name); + let first = matches.next()?; + if matches.next().is_some() { + None + } else { + Some(first) + } + } + + /// Find a function declared in a specific namespace. + pub fn namespaced_function(&self, namespace: &str, name: &str) -> Option<&Function> { + self.functions + .iter() + .find(|f| f.namespace.as_deref() == Some(namespace) && f.local_name == name) + } + + /// All namespace names declared by level-1 headings. + pub fn namespaces(&self) -> impl Iterator { + self.units.iter().filter_map(|unit| match unit.kind { + UnitKind::Namespace => Some(unit.name.as_str()), + _ => None, + }) + } + + /// The default entry function, if defined. + pub fn entry(&self) -> Option<&Function> { + self.function("main") + } + + /// Find an import declaration by alias. + pub fn import(&self, alias: &str) -> Option<&ImportDecl> { + self.imports.iter().find(|import| import.alias == alias) + } + + /// All resources contained by a unit. + pub fn resources_of<'a>(&'a self, unit: &UnitId) -> impl Iterator + 'a { + let unit = unit.clone(); + self.resources + .iter() + .filter(move |resource| match resource { + Resource::Formula { unit: owner, .. } | Resource::Code { unit: owner, .. } => { + owner == &unit + } + }) + } +} + +/// One resolved import edge from the module loader. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ResolvedImport { + /// Importing module. + pub from: ModuleId, + /// Local alias. + pub alias: String, + /// Imported module identity. + pub to: ModuleId, +} + +/// A whole program: modules keyed by canonical id. +#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)] +pub struct Program { + /// Modules keyed by canonical module id. + pub modules: BTreeMap, + /// Canonical id of the module being run. + pub main_module: Option, + /// Resolved import edges. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub resolved_imports: Vec, +} + +impl Program { + /// Insert a module. + pub fn insert(&mut self, module: Module) { + self.modules.insert(module.id.clone(), module); + } + + /// Get a module. + pub fn module(&self, id: &ModuleId) -> Option<&Module> { + self.modules.get(id) + } + + /// Find a function by full identity. + pub fn function(&self, id: &FunctionId) -> Option<&Function> { + self.modules.get(&id.module)?.function(&id.name) + } + + /// Resolve an import alias to a module. + pub fn resolve_import(&self, from: &ModuleId, alias: &str) -> Option<&ModuleId> { + self.resolved_imports + .iter() + .find(|edge| &edge.from == from && edge.alias == alias) + .map(|edge| &edge.to) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use marqdo_expression::parse_expression; + + #[test] + fn stmt_keeps_spans() { + let expr = parse_expression("1 + 2").unwrap(); + let stmt = Stmt::Return { + value: expr, + span: Span::new(4, 12), + }; + assert_eq!(stmt.span(), Span::new(4, 12)); + } + + #[test] + fn module_lookup_helpers() { + let module = Module { + id: ModuleId::from("index.mq.md"), + units: vec![], + functions: vec![], + imports: vec![ImportDecl { + alias: "geometry".into(), + target: "@geometry".into(), + span: Span::new(0, 0), + }], + resources: vec![], + anchors: BTreeMap::new(), + }; + assert!(module.entry().is_none()); + assert_eq!(module.import("geometry").unwrap().target, "@geometry"); + assert_eq!(module.id.to_string(), "index.mq.md"); + } + + #[test] + fn ir_serializes_for_inspect() { + let stmt = Stmt::Return { + value: parse_expression("x ** 2").unwrap(), + span: Span::new(0, 6), + }; + let json = serde_json::to_value(&stmt).unwrap(); + assert_eq!(json["stmt"], "return"); + assert_eq!(json["span"]["start"], 0); + } +}