Files
marqdo/src/call.rs
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

585 lines
18 KiB
Rust
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! `marqdo call`: run one already-bound function in a `.mq.md` file.
//!
//! Location, effects, and execution go through the existing compiler and runtime.
//! The command does not scan headings, and it does not run the program entry when
//! the named function cannot be compiled.
use std::path::Path;
use anyhow::Result;
use crate::ast::Function;
use crate::bytecode::{compile_for_call, Vm};
use crate::diagnostics::{Diagnostic, Span};
use crate::host::json::json_to_value;
use crate::host::{HostCaps, HostContext};
use crate::interp::Interpreter;
use crate::load::load_module;
use crate::sema::{compile_file_closure, SemanticArtifact, SemanticProject};
use crate::value::Value;
use crate::Backend;
/// Explicit effect grants. Writes imply reads; unrelated effects stay denied.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct CallEffects(u32);
impl CallEffects {
#[allow(non_upper_case_globals)]
pub const None: Self = Self(0);
#[allow(non_upper_case_globals)]
pub const Plugin: Self = Self((1 << 2) | (1 << 6) | (1 << 7) | (1 << 8) | (1 << 11));
const NAMES: &'static [&'static str] = &[
"fs.read",
"fs.write",
"plugin.call",
"network.read",
"network.write",
"process.exec",
"output.write",
"time.read",
"random.read",
"environment.read",
"environment.write",
"process.control",
"user.input",
];
pub fn parse(s: &str) -> Result<Self> {
let mut out = Self::None;
for name in s.split(',').map(str::trim) {
match name {
"none" | "" => {}
"plugin" => out.0 |= Self::Plugin.0,
"read" => out.0 |= 1,
"write" => out.0 |= 3,
_ => {
let index = Self::NAMES.iter().position(|v| *v == name)
.ok_or_else(|| call_diag(None, 0, "call.bad_effects",
format!("unknown effect `{name}`; use none, plugin or comma-separated effect names")))?;
out.0 |= 1 << index;
}
}
}
if out.0 & (1 << 1) != 0 {
out.0 |= 1;
}
if out.0 & (1 << 4) != 0 {
out.0 |= 1 << 3;
}
Ok(out)
}
pub fn as_str(self) -> String {
if self == Self::None {
return "none".into();
}
if self == Self::Plugin {
return "plugin".into();
}
Self::NAMES
.iter()
.enumerate()
.filter(|(i, _)| self.0 & (1 << i) != 0)
.map(|(_, name)| *name)
.collect::<Vec<_>>()
.join(",")
}
/// File/network/process writes must never be repeated to rebuild a handle.
pub(crate) fn needs_snapshot(self) -> bool {
[
"fs.write",
"network.write",
"process.exec",
"environment.write",
]
.iter()
.any(|effect| self.allows(effect))
}
fn host_caps(self) -> HostCaps {
HostCaps {
fs_write: self.allows("fs.write"),
exec: self.allows("process.exec"),
net: self.allows("network.read") || self.allows("network.write"),
plugin: self.allows("plugin.call"),
}
}
fn allows(self, effect: &str) -> bool {
effect == "pure"
|| Self::NAMES
.iter()
.position(|v| *v == effect)
.is_some_and(|i| self.0 & (1 << i) != 0)
}
}
/// Options for one external call.
#[derive(Debug, Clone, Default)]
pub struct CallOptions {
pub effects: CallEffects,
pub fs_root: Option<std::path::PathBuf>,
pub session: Option<String>,
pub toget: Option<String>,
/// JSON transport values are literal data, including leading $ and @.
pub literal_args: bool,
}
/// Call `function` in `path` with named arguments (pure-only, no session).
pub fn call_file(
path: &Path,
function: &str,
args: &[(String, Value)],
backend: Backend,
) -> Result<Value> {
call_file_with(path, function, args, backend, CallOptions::default())
}
/// Call with effects / session / toget.
pub fn call_file_with(
path: &Path,
function: &str,
args: &[(String, Value)],
backend: Backend,
opts: CallOptions,
) -> Result<Value> {
let path = path.canonicalize().map_err(|e| {
call_diag(
None,
1,
"call.compile",
format!("failed to read {}: {e}", path.display()),
)
})?;
let mut session = if opts.session.is_some() || opts.toget.is_some() || (!opts.literal_args && args_need_session(args)) {
let id = opts
.session
.clone()
.unwrap_or_else(crate::call_session::default_session_id);
Some(crate::call_session::load_session(&id)?)
} else {
None
};
let resolved = if opts.literal_args {
args.to_vec()
} else if let Some(ref mut sess) = session {
crate::call_session::resolve_args(sess, args, backend)?
} else {
args.to_vec()
};
// Record uses original arg texts (with $refs) so replay can re-resolve.
let record_args = args.to_vec();
let value = call_file_raw_with_root(
&path,
function,
&resolved,
opts.effects,
backend,
opts.fs_root.as_deref(),
)?;
if let Some(ref mut sess) = session {
crate::call_session::record_step(
sess,
&path,
function,
&record_args,
opts.effects,
opts.fs_root.as_deref(),
opts.toget.as_deref(),
&value,
)?;
if let Some(step) = sess.steps.last_mut() {
step.literal_args = opts.literal_args;
}
crate::call_session::save_session(sess)?;
}
Ok(value)
}
/// Execute without session bookkeeping (used by journal replay).
pub fn call_file_raw(
path: &Path,
function: &str,
args: &[(String, Value)],
effects: CallEffects,
backend: Backend,
) -> Result<Value> {
call_file_raw_with_root(path, function, args, effects, backend, None)
}
pub(crate) fn call_file_raw_with_root(
path: &Path,
function: &str,
args: &[(String, Value)],
effects: CallEffects,
backend: Backend,
fs_root: Option<&Path>,
) -> Result<Value> {
let path = if path.is_absolute() {
path.to_path_buf()
} else {
path.canonicalize().map_err(|e| {
call_diag(
None,
1,
"call.compile",
format!("failed to read {}: {e}", path.display()),
)
})?
};
let compilation = compile_file_closure(&path).map_err(|e| preserve_diag(&path, e))?;
let artifact = locate_artifact(&compilation.semantics, &path, function)?;
deny_unsafe(&path, artifact, effects)?;
execute_source_function_with_root(
&path,
artifact.source.line,
&artifact.display_name,
args,
effects.host_caps(),
backend,
true,
fs_root,
)
.map(|(value, _stdout)| value)
}
fn args_need_session(args: &[(String, Value)]) -> bool {
args.iter()
.any(|(_, v)| matches!(v, Value::Text(t) if t.starts_with('$') || t.starts_with('@')))
}
/// Run the function declared at `line` in `path`.
pub(crate) fn execute_source_function(
path: &Path,
line: u32,
display_name: &str,
args: &[(String, Value)],
caps: HostCaps,
backend: Backend,
strict_args: bool,
) -> Result<(Value, String)> {
execute_source_function_with_root(
path,
line,
display_name,
args,
caps,
backend,
strict_args,
None,
)
}
fn execute_source_function_with_root(
path: &Path,
line: u32,
display_name: &str,
args: &[(String, Value)],
caps: HostCaps,
backend: Backend,
strict_args: bool,
fs_root: Option<&Path>,
) -> Result<(Value, String)> {
let module = load_module(path)?;
let source = std::fs::read_to_string(path)?;
let fun = find_function_at_line(&module.functions, line).ok_or_else(|| {
call_diag(
Some(path),
line,
"artifact.unresolved",
format!("无法在 {}:{} 定位函数 {display_name}", path.display(), line),
)
})?;
let expected = display_name.rsplit('.').next().unwrap_or(display_name);
if fun.name != expected {
return Err(call_diag(
Some(path),
line,
"artifact.unresolved",
format!(
"源码行 {line} 上的函数是 `{}`,与 `{display_name}` 不一致",
fun.name
),
));
}
let mut host = HostContext::for_capture(Some(path), caps);
host.set_entry_source(Some(path), &source);
if let Some(root) = fs_root {
let root = root.canonicalize()?;
if !root.is_dir() {
anyhow::bail!("call.fs_root: root must be a directory");
}
host.cwd = root.clone();
host.fs_root = Some(root);
}
let mut interp = Interpreter::with_capture(Some(path), false).with_host(host);
let bound;
let invoke_args: &[(String, Value)] = if strict_args {
bound = interp.bind_external_args(&module, fun, args)?;
&bound
} else {
args
};
match backend {
Backend::Tree => {
let value = interp.invoke_bound_function(&module, fun, invoke_args)?;
Ok((value, interp.captured_stdout))
}
Backend::Bytecode => {
let program = compile_for_call(Some(path), &module)?;
let idx = program
.functions
.iter()
.position(|chunk| {
chunk.module_scope == 0
&& chunk.declaration_span == fun.span
&& chunk.name == fun.name
&& chunk.source.sha256 == module.source.sha256
})
.ok_or_else(|| {
call_diag(
Some(path),
line,
"artifact.unresolved",
format!("bytecode 没有编译出 `{display_name}`;拒绝改去执行程序入口"),
)
})?;
let mut host = HostContext::for_capture(Some(path), caps);
host.set_entry_source(Some(path), &source);
if let Some(root) = fs_root {
let root = root.canonicalize()?;
host.cwd = root.clone();
host.fs_root = Some(root);
}
let mut vm = Vm::with_capture(Some(path)).with_host(host);
let value = vm.call_function(&program, idx, invoke_args)?;
Ok((value, vm.captured_stdout))
}
}
}
/// Split trailing `toget <name>` from a clap `args` vector.
pub fn split_toget(tokens: &[String]) -> Result<(Vec<String>, Option<String>)> {
if tokens.len() >= 2 {
let n = tokens.len();
if tokens[n - 2] == "toget" {
let name = tokens[n - 1].clone();
if name.contains('=') {
return Err(call_diag(
None,
0,
"call.bad_toget",
"toget 名字不能含 `=`".into(),
));
}
return Ok((tokens[..n - 2].to_vec(), Some(name)));
}
}
Ok((tokens.to_vec(), None))
}
/// Parse `name=value` tokens. Values are integers, decimals, quoted text, True/False/None,
/// or JSON when the raw value starts with `[` or `{`.
pub fn parse_call_args(tokens: &[String]) -> Result<Vec<(String, Value)>> {
let mut out = Vec::new();
for token in tokens {
let Some((name, raw)) = token.split_once('=') else {
return Err(call_diag(
None,
0,
"call.bad_arg",
format!("参数 `{token}` 需要写成 名字=值"),
));
};
if name.is_empty() {
return Err(call_diag(
None,
0,
"call.bad_arg",
format!("参数 `{token}` 缺少名字"),
));
}
let value = parse_literal(raw).map_err(|message| {
call_diag(
None,
0,
"call.bad_value",
format!("参数 `{name}`: {message}"),
)
})?;
out.push((name.to_string(), value));
}
Ok(out)
}
/// Decode a JSON object of literal arguments with the standard safe-JSON domain.
/// Unlike command-line $name syntax, JSON strings remain data during replay.
pub fn parse_call_args_json(source: &str) -> Result<Vec<(String, Value)>> {
crate::host::json::decode_arguments(source)
.map_err(|message| call_diag(None, 0, "call.bad_value", message))
}
fn locate_artifact<'a>(
project: &'a SemanticProject,
entry: &Path,
query: &str,
) -> Result<&'a SemanticArtifact> {
let in_entry: Vec<&SemanticArtifact> = project
.artifacts
.iter()
.filter(|artifact| same_file(&project.root, &artifact.source.file, entry))
.collect();
let exact: Vec<&SemanticArtifact> = in_entry
.iter()
.copied()
.filter(|artifact| {
artifact.display_name == query
|| artifact
.symbol_id
.as_ref()
.is_some_and(|id| id.as_str() == query)
|| artifact.artifact_id.0 == query
})
.collect();
let hits = if !exact.is_empty() {
exact
} else if !query.contains('.') {
in_entry
.iter()
.copied()
.filter(|artifact| {
artifact.kind == "function"
&& artifact.display_name.rsplit('.').next() == Some(query)
})
.collect()
} else {
// Nested sub-tools: `outer.helper` matches display path `main.outer.helper`.
let suffix = format!(".{query}");
in_entry
.iter()
.copied()
.filter(|artifact| {
artifact.kind == "function"
&& (artifact.display_name.ends_with(&suffix) || artifact.display_name == query)
})
.collect()
};
match hits.len() {
1 => Ok(hits[0]),
0 => Err(call_diag(
Some(entry),
1,
"artifact.unresolved",
format!("无法唯一绑定 `{query}`"),
)),
_ => Err(call_diag(
Some(entry),
1,
"artifact.ambiguous",
format!("无法唯一绑定 `{query}`"),
)),
}
}
fn deny_unsafe(path: &Path, artifact: &SemanticArtifact, effects: CallEffects) -> Result<()> {
if artifact.kind != "function" || artifact.callable.as_deref() == Some("instance_method") {
return Err(call_diag(
Some(path),
artifact.source.line,
"artifact.not_executable",
"只有非实例函数可由 call 直接执行".to_string(),
));
}
let denied: Vec<String> = artifact
.effects
.values()
.into_iter()
.filter(|e| !effects.allows(e))
.collect();
if !denied.is_empty() {
return Err(call_diag(
Some(path),
artifact.source.line,
"artifact.effect_denied",
format!(
"call --effects {} 拒绝效应 {}",
effects.as_str(),
denied.join(", ")
),
));
}
Ok(())
}
fn same_file(root: &Path, rel: &str, entry: &Path) -> bool {
let abs = root.join(rel);
match (abs.canonicalize(), entry.canonicalize()) {
(Ok(left), Ok(right)) => left == right,
_ => false,
}
}
fn find_function_at_line(functions: &[Function], line: u32) -> Option<&Function> {
for fun in functions {
if fun.span.line == line {
return Some(fun);
}
if let Some(found) = find_function_at_line(&fun.children, line) {
return Some(found);
}
}
None
}
fn parse_literal(raw: &str) -> Result<Value, String> {
match raw {
"True" | "true" => return Ok(Value::Bool(true)),
"False" | "false" => return Ok(Value::Bool(false)),
"None" | "none" => return Ok(Value::None),
_ => {}
}
if raw.starts_with('$') || raw.starts_with('@') {
return Ok(Value::Text(raw.to_string()));
}
// Preserve the existing name=value raw-quoted text transport. Escaped,
// structured and multiline data uses the explicit --args-json channel.
if raw.len() >= 2 {
let bytes = raw.as_bytes();
if (bytes[0] == b'"' && bytes[raw.len() - 1] == b'"')
|| (bytes[0] == b'\'' && bytes[raw.len() - 1] == b'\'')
{
return Ok(Value::Text(raw[1..raw.len() - 1].to_string()));
}
}
if raw.starts_with('[') || raw.starts_with('{') {
let json: serde_json::Value =
serde_json::from_str(raw).map_err(|e| format!("JSON 解析失败: {e}"))?;
return json_to_value(&json);
}
if let Ok(n) = raw.parse::<i64>() {
return Ok(Value::Int(n));
}
if raw.contains('.') {
if let Ok(n) = raw.parse::<f64>() {
return Ok(Value::Num(n));
}
}
Err(format!(
"无法解析 `{raw}`(整数、小数、引号文本、True/False/None、JSON、`$name`)"
))
}
fn preserve_diag(path: &Path, err: anyhow::Error) -> anyhow::Error {
if Diagnostic::find(&err).is_some() {
err
} else {
call_diag(Some(path), 1, "call.compile", format!("{err:#}"))
}
}
fn call_diag(path: Option<&Path>, line: u32, code: &str, message: String) -> anyhow::Error {
anyhow::Error::new(Diagnostic::new(path, Span::new(line, 1), message).with_code(code))
}