Files
marqdo-cli/crates/marqdo-ir/src/lib.rs
T
cflmy 4ecf537141 feat(m0.6-r1): unified callable registry
- add CallableId/Descriptor/Origin and CallableRegistry in marqdo-ir
- include builtins, Marqdo functions and declared ABI exports in one static
  lookup model with deterministic conflict rules
- validate declared plugin export signatures in the frontend without loading
  any shared library
- add registry and frontend static-plugin-signature tests
2026-11-20 11:38:04 +08:00

569 lines
18 KiB
Rust

//! 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;
pub mod callable;
/// Canonical logical identity of a module: package instance plus a path
/// relative to that package's module root.
///
/// The instance prefix is **not** a physical cache path (ADR-0008). The display
/// and wire form is `<instance>::<relative_path>`; a bare path is accepted for
/// standalone tests and documents as `root:default`.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ModuleId {
/// Logical package instance (`root:...` or `dep:...`).
pub instance: String,
/// Path relative to the package module root, with `/` separators.
pub relative_path: String,
}
impl ModuleId {
/// Construct a module id from an explicit instance and relative path.
pub fn new(instance: impl Into<String>, relative_path: impl Into<String>) -> Self {
Self {
instance: instance.into(),
relative_path: relative_path.into(),
}
}
/// Construct a module id for the default/root package.
pub fn root_default(relative_path: impl Into<String>) -> Self {
Self::new("root:default", relative_path)
}
/// Parse the canonical `<instance>::<path>` form, accepting a bare path as
/// `root:default` for compatibility with standalone documents/tests.
pub fn parse(value: &str) -> Result<Self, String> {
if value.is_empty() {
return Err("module id must not be empty".to_string());
}
match value.split_once("::") {
Some((instance, path)) if !instance.is_empty() && !path.is_empty() => {
Ok(Self::new(instance, path))
}
Some(_) => Err(format!("invalid module id `{value}`")),
None => Ok(Self::root_default(value)),
}
}
/// The canonical string form.
pub fn canonical(&self) -> String {
format!("{}::{}", self.instance, self.relative_path)
}
}
impl fmt::Display for ModuleId {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}::{}", self.instance, self.relative_path)
}
}
impl From<&str> for ModuleId {
fn from(value: &str) -> Self {
ModuleId::parse(value).unwrap_or_else(|_| ModuleId::root_default(value))
}
}
impl From<String> for ModuleId {
fn from(value: String) -> Self {
ModuleId::from(value.as_str())
}
}
impl Serialize for ModuleId {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
serializer.serialize_str(&self.canonical())
}
}
impl<'de> Deserialize<'de> for ModuleId {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
let value = String::deserialize(deserializer)?;
ModuleId::parse(&value).map_err(serde::de::Error::custom)
}
}
/// 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>,
/// Explicit external callable descriptors (plugin manifests). They are
/// metadata only: `check` never loads a library.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub external_callables: Vec<callable::CallableDescriptor>,
}
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)
}
/// Static external callable descriptor by complete dotted name.
pub fn external_callable(&self, name: &str) -> Option<&callable::CallableDescriptor> {
self.external_callables
.iter()
.find(|descriptor| descriptor.public_name == name)
}
/// Build the unified callable registry for this program.
pub fn callable_registry(&self) -> callable::CallableRegistry {
callable::CallableRegistry::from_program(self)
}
}
#[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(), "root:default::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);
}
}