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.
This commit is contained in:
cflmy committed 2026-11-20 10:35:54 +08:00
1 parent 9897ecc37f
commit 4db6e6afd6
3 files changed
+761 -2

No files matched your search

+3 -2
View File
@@ -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 }
+277
View File
@@ -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(&param.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());
}
}
+481
View File
@@ -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<String>,
}
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<FunctionId>,
}
/// 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<String>,
/// Compile-time constant default expression, if declared.
#[serde(skip_serializing_if = "Option::is_none")]
pub default: Option<Expr>,
}
/// 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<String>,
/// 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<Param>,
/// Whether the signature was explicit or inferred.
pub signature: SignatureKind,
/// Function body in executable order.
pub body: Vec<Stmt>,
}
/// 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<BranchArm>,
/// 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<Stmt>,
/// 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<Stmt>,
/// 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<Arg>,
/// 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<UnitInfo>,
/// Functions in document order.
pub functions: Vec<Function>,
/// Explicit imports.
pub imports: Vec<ImportDecl>,
/// Inert resources (formulas, code fences) in document order.
pub resources: Vec<Resource>,
/// 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<String, UnitId>,
}
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<Item = &str> {
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<Item = &'a Resource> + '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<ModuleId, Module>,
/// Canonical id of the module being run.
pub main_module: Option<ModuleId>,
/// Resolved import edges.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub resolved_imports: Vec<ResolvedImport>,
}
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);
}
}