feat(cli): marqdo init/run/call/check/inspect/fmt/plugin/lock/sync

Composition root wiring the frontend, runtime, host and package layers:

- Project loader: deterministic project-root discovery, explicit front-matter
  imports only (`@dependency` or relative `.mq.md`), recursive module loading
  with cycle diagnostics, resolved import edges and cross-module call checks.
  Loading never executes anything.
- run/call: sandbox mode enforcement (strict refuses when unavailable),
  explicit capability grants, fuel/stack/output/timeout overrides, typed
  `--arg name=value` constants, program stdout separated from diagnostics, and
  machine-readable JSON output that embeds program output without mixing.
- check: static diagnostics only, human-readable locations with source lines
  and stable machine codes in JSON.
- inspect: canonical AST, heading units, signatures (explicit/inferred),
  executable IR, static reference edges (including cross-file links analysed
  without execution) and platform capability report.
- fmt: conservative, AST-preserving normalisation of line endings and trailing
  newlines; --check mode.
- plugin inspect: manifest/ABI/artifact validation and hash verification,
  never loading plugin code.
- init: minimal project (manifest, entry document, .gitignore).
- lock/sync --locked: deterministic path-dependency lockfile, stale lock or
  changed dependency content is an error (no silent upgrades).
- examples: hello, factorial, math formula, Python foreign call, static
  references and a two-module project with an explicit import.
This commit is contained in:
cflmy committed 2026-11-20 10:44:03 +08:00
1 parent 2e49c7b855
commit e1ba630068
18 files changed
+1803 -28

No files matched your search

+3 -1
View File
@@ -25,7 +25,9 @@ marqdo-sandbox = { workspace = true }
clap = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
walkdir = { workspace = true }
hex = { workspace = true }
sha2 = { workspace = true }
[[bin]]
name = "marqdo"
+97
View File
@@ -0,0 +1,97 @@
//! Conversion of `--arg name=value` CLI arguments into typed values.
//!
//! Arguments use the expression grammar restricted to compile-time constants:
//! `--arg n=3`, `--arg name="小明"`, `--arg flags=[1, 2]`. There is no implicit
//! text fallback: invalid values are usage errors.
use marqdo_expression::{parse_expression, Expr, UnaryOp};
use marqdo_value::Value;
/// Parse one `name=value` argument pair.
pub fn parse_named_arg(raw: &str) -> Result<(String, Value), String> {
let Some((name, value)) = raw.split_once('=') else {
return Err(format!("argument `{raw}` must be `name=value`"));
};
let name = name.trim();
if name.is_empty() {
return Err(format!("argument `{raw}` has an empty name"));
}
let value = parse_const_value(value.trim())?;
Ok((name.to_string(), value))
}
/// Parse a constant expression into a value.
pub fn parse_const_value(text: &str) -> Result<Value, String> {
let expr = parse_expression(text).map_err(|error| {
format!(
"invalid argument value `{text}`: {} (strings need double quotes)",
error.message
)
})?;
const_value(&expr).ok_or_else(|| {
format!("argument value `{text}` must be a literal constant (no calls or variables)")
})
}
fn const_value(expr: &Expr) -> Option<Value> {
match expr {
Expr::Int(value) => Some(Value::Int(value.clone())),
Expr::Float(value) => Some(Value::Float(*value)),
Expr::Text(value) => Some(Value::Text(value.clone())),
Expr::Bool(value) => Some(Value::Bool(*value)),
Expr::None => Some(Value::None),
Expr::List(items) => items
.iter()
.map(const_value)
.collect::<Option<Vec<Value>>>()
.map(Value::List),
Expr::Record(entries) => {
let mut map = std::collections::BTreeMap::new();
for entry in entries {
map.insert(entry.key.clone(), const_value(&entry.value)?);
}
Some(Value::Map(map))
}
Expr::Unary {
op: UnaryOp::Neg,
operand,
..
} => match const_value(operand)? {
Value::Int(value) => Some(Value::Int(-value)),
Value::Float(value) => Some(Value::Float(-value)),
_ => None,
},
Expr::Unary {
op: UnaryOp::Pos,
operand,
..
} => const_value(operand),
_ => None,
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_typed_arguments() {
assert_eq!(parse_named_arg("n=3").unwrap().1, Value::int(3));
assert_eq!(
parse_named_arg("s=\"你好\"").unwrap().1,
Value::text("你好")
);
assert_eq!(parse_named_arg("f=-1.5").unwrap().1, Value::Float(-1.5));
assert!(matches!(
parse_named_arg("l=[1, 2]").unwrap().1,
Value::List(_)
));
}
#[test]
fn rejects_non_constant_and_malformed_arguments() {
assert!(parse_named_arg("n=f(1)").is_err());
assert!(parse_named_arg("n=裸文本").is_err());
assert!(parse_named_arg("plain").is_err());
}
}
+926
View File
@@ -0,0 +1,926 @@
//! Command implementations.
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
use marqdo_host::{Capabilities, Host, StdHost};
use marqdo_ir::ModuleId;
use marqdo_runtime::{run, EvaluatedArg, RuntimeError, Value};
use marqdo_sandbox::{PlatformCapabilities, SandboxMode};
use marqdo_span::Span;
use serde_json::json;
use sha2::{Digest, Sha256};
use crate::args;
use crate::loader::{self, LoadedProject};
use crate::output;
/// Effective sandbox settings from the command line.
#[derive(Debug, Clone, Default)]
pub struct SandboxSettings {
/// Mode name.
pub mode: String,
/// Read grants.
pub allow_read: Vec<String>,
/// Write grants.
pub allow_write: Vec<String>,
/// Foreign execution grant.
pub allow_foreign: bool,
/// Plugin grants.
pub allow_plugin: Vec<String>,
/// Fuel override.
pub fuel: Option<u64>,
/// Stack depth override.
pub stack: Option<usize>,
/// Output limit override.
pub max_output: Option<usize>,
/// Wall-clock timeout in seconds.
pub timeout: Option<u64>,
}
impl SandboxSettings {
/// Parse the mode string.
pub fn sandbox_mode(&self) -> Result<SandboxMode, String> {
SandboxMode::parse(&self.mode).ok_or_else(|| {
format!(
"unknown sandbox mode `{}` (expected pure, project or strict)",
self.mode
)
})
}
/// Build the effective capability set.
pub fn capabilities(&self) -> Result<Capabilities, String> {
let mode = self.sandbox_mode()?;
match mode {
SandboxMode::Pure => {
if !self.allow_read.is_empty()
|| !self.allow_write.is_empty()
|| self.allow_foreign
|| !self.allow_plugin.is_empty()
{
return Err(
"pure mode prohibits external I/O grants; use --mode project".to_string(),
);
}
Ok(Capabilities::pure())
}
SandboxMode::Project => {
let mut capabilities = Capabilities::project();
for pattern in &self.allow_read {
capabilities = capabilities.allow_read(pattern.clone());
}
for pattern in &self.allow_write {
capabilities = capabilities.allow_write(pattern.clone());
}
if self.allow_foreign {
capabilities = capabilities.allow_foreign();
}
for plugin in &self.allow_plugin {
capabilities = capabilities.allow_plugin(plugin.clone());
}
Ok(capabilities)
}
SandboxMode::Strict => Ok(Capabilities::project()),
}
}
}
/// `marqdo init`.
pub fn init(dir: Option<&Path>) -> i32 {
let dir = dir.unwrap_or_else(|| Path::new("."));
if dir.join(marqdo_package::MANIFEST_FILE).exists() {
eprintln!(
"error: `{}` already contains {}",
dir.display(),
marqdo_package::MANIFEST_FILE
);
return 1;
}
let name = dir
.canonicalize()
.ok()
.and_then(|path| {
path.file_name()
.map(|name| name.to_string_lossy().to_string())
})
.unwrap_or_else(|| "example".to_string());
if let Err(error) = std::fs::create_dir_all(dir) {
eprintln!("error: cannot create {}: {error}", dir.display());
return 1;
}
let manifest = marqdo_package::Manifest::template(&name);
if let Err(error) = std::fs::write(dir.join(marqdo_package::MANIFEST_FILE), manifest.to_yaml())
{
eprintln!("error: cannot write manifest: {error}");
return 1;
}
let entry = dir.join("index.mq.md");
if let Err(error) = std::fs::write(&entry, INIT_TEMPLATE) {
eprintln!("error: cannot write {}: {error}", entry.display());
return 1;
}
let _ = std::fs::write(dir.join(".gitignore"), ".marqdo/\n");
println!("Initialized Marqdo project `{name}` in {}", dir.display());
println!("Next: marqdo check index.mq.md && marqdo run index.mq.md");
0
}
const INIT_TEMPLATE: &str = "## main\n\n**问候 = \"你好,Marqdo\"**\n\n> 打印(问候)\n\n*问候*\n";
fn load_project(file: Option<&Path>, json: bool) -> Result<LoadedProject, i32> {
let file = file.unwrap_or_else(|| Path::new("index.mq.md"));
match loader::load(file) {
Ok(project) => Ok(project),
Err(error) => {
if json {
output::print_json(&json!({"success": false, "error": error}));
} else {
eprintln!("error: {error}");
}
Err(2)
}
}
}
/// `marqdo check`.
pub fn check(file: Option<&Path>, json: bool) -> i32 {
let project = match load_project(file, json) {
Ok(project) => project,
Err(code) => return code,
};
let errors = output::error_count(&project.diagnostics);
if json {
output::print_json(&json!({
"command": "check",
"success": errors == 0,
"errors": errors,
"diagnostics": output::diagnostics_json(&project.diagnostics),
}));
} else {
let text = output::render_text(&project.diagnostics);
eprint!("{text}");
if errors == 0 {
println!("checked {} module(s): ok", project.program.modules.len());
} else {
eprintln!(
"check failed: {} error(s), {} warning(s)",
errors,
project.diagnostics.len() - errors
);
}
}
if errors == 0 {
0
} else {
1
}
}
/// Options for `marqdo inspect`.
#[derive(Debug, Clone, Default)]
pub struct InspectFlags {
/// Show the Markdown AST.
pub ast: bool,
/// Show heading units.
pub units: bool,
/// Show inferred/explicit signatures.
pub signature: bool,
/// Show executable IR.
pub ir: bool,
/// Show link reference edges.
pub refs: bool,
/// Show platform capability report.
pub platform: bool,
}
/// `marqdo inspect`.
pub fn inspect(file: Option<&Path>, flags: &InspectFlags, json: bool) -> i32 {
let project = match load_project(file, json) {
Ok(project) => project,
Err(code) => return code,
};
let entry = project.entry_file();
let module = &entry.analysis.module;
let selected_any =
flags.ast || flags.units || flags.signature || flags.ir || flags.refs || flags.platform;
if json {
let mut object = serde_json::Map::new();
object.insert("command".into(), json!("inspect"));
object.insert("module".into(), json!(entry.module_id.0));
if !selected_any {
object.insert("summary".into(), summary_json(&project));
}
if flags.ast {
object.insert(
"ast".into(),
serde_json::to_value(&entry.analysis.document.root).unwrap_or_default(),
);
}
if flags.units {
object.insert(
"units".into(),
serde_json::to_value(&entry.analysis.units.units).unwrap_or_default(),
);
}
if flags.signature {
object.insert("signatures".into(), signatures_json(module));
}
if flags.ir {
object.insert(
"ir".into(),
serde_json::to_value(&module.functions).unwrap_or_default(),
);
}
if flags.refs {
object.insert("refs".into(), json!(refs_json(&project)));
}
if flags.platform {
object.insert(
"platform".into(),
serde_json::to_value(PlatformCapabilities::detect()).unwrap_or_default(),
);
}
output::print_json(&serde_json::Value::Object(object));
return 0;
}
if !selected_any {
println!("module: {}", entry.module_id.0);
println!("path: {}", entry.path.display());
println!("project root: {}", project.root.display());
println!("functions:");
for function in &module.functions {
let params = function
.params
.iter()
.map(|param| param.name.as_str())
.collect::<Vec<_>>()
.join(", ");
let kind = match function.signature {
marqdo_ir::SignatureKind::Explicit => "explicit",
marqdo_ir::SignatureKind::Inferred => "inferred",
};
println!(" {} ({params}) [{kind}]", function.id.name);
}
println!(
"resources: {} formula/code block(s)",
module.resources.len()
);
return 0;
}
if flags.ast {
println!(
"{}",
serde_json::to_string_pretty(&entry.analysis.document.root).unwrap_or_default()
);
}
if flags.units {
println!(
"{}",
serde_json::to_string_pretty(&entry.analysis.units.units).unwrap_or_default()
);
}
if flags.signature {
println!(
"{}",
serde_json::to_string_pretty(&signatures_json(module)).unwrap_or_default()
);
}
if flags.ir {
println!(
"{}",
serde_json::to_string_pretty(&module.functions).unwrap_or_default()
);
}
if flags.refs {
println!(
"{}",
serde_json::to_string_pretty(&refs_json(&project)).unwrap_or_default()
);
}
if flags.platform {
println!(
"{}",
serde_json::to_string_pretty(&PlatformCapabilities::detect()).unwrap_or_default()
);
}
0
}
fn summary_json(project: &LoadedProject) -> serde_json::Value {
let entry = project.entry_file();
json!({
"modules": project.program.modules.len(),
"functions": entry.analysis.module.functions.len(),
"units": entry.analysis.units.units.len(),
"resources": entry.analysis.module.resources.len(),
})
}
fn signatures_json(module: &marqdo_ir::Module) -> serde_json::Value {
serde_json::Value::Array(
module
.functions
.iter()
.map(|function| {
json!({
"name": function.id.name,
"local_name": function.local_name,
"signature": match function.signature {
marqdo_ir::SignatureKind::Explicit => "explicit",
marqdo_ir::SignatureKind::Inferred => "inferred",
},
"params": function.params.iter().map(|param| json!({
"name": param.name,
"type": param.type_annotation,
"has_default": param.default.is_some(),
})).collect::<Vec<_>>(),
})
})
.collect(),
)
}
fn refs_json(project: &LoadedProject) -> serde_json::Value {
let entry = project.entry_file();
let parent = entry.path.parent().unwrap_or_else(|| Path::new("."));
let mut edges = Vec::new();
entry.analysis.document.root.walk(&mut |node| {
let marqdo_markdown::MdKind::Link { url, .. } = &node.kind else {
return;
};
let (resolved, target_module, target_unit) =
resolve_link(project, &entry.analysis.units, parent, url);
edges.push(json!({
"source": entry.module_id.0,
"url": url,
"span": node.span,
"resolved": resolved,
"target_module": target_module,
"target_unit": target_unit,
}));
});
serde_json::Value::Array(edges)
}
fn resolve_link(
project: &LoadedProject,
units: &marqdo_frontend::UnitIndex,
parent: &Path,
url: &str,
) -> (bool, Option<String>, Option<String>) {
if let Some(fragment) = url.strip_prefix('#') {
let unit = units.anchors.get(fragment).or_else(|| {
units
.units
.iter()
.find(|unit| unit.name == fragment)
.map(|unit| &unit.id)
});
return match unit {
Some(unit) => (true, Some(project.entry.0.clone()), Some(unit.to_string())),
None => (false, None, None),
};
}
if url.starts_with("http://") || url.starts_with("https://") {
return (true, None, None);
}
let (path_part, fragment) = match url.split_once('#') {
Some((path, fragment)) => (path, Some(fragment)),
None => (url, None),
};
let candidate = parent.join(path_part);
let Ok(candidate) = candidate.canonicalize() else {
return (false, None, None);
};
let Ok(relative) = candidate.strip_prefix(&project.root) else {
return (false, None, None);
};
let module_id = ModuleId(
relative
.components()
.map(|component| component.as_os_str().to_string_lossy().to_string())
.collect::<Vec<_>>()
.join("/"),
);
let analyzed;
let target_units = match project.files.get(&module_id) {
Some(target_file) => &target_file.analysis.units,
None => {
// Links may reference documents that are not imported. Analyse the
// target statically for reference checking; nothing executes.
let Ok(source) = std::fs::read_to_string(&candidate) else {
return (false, None, None);
};
analyzed = marqdo_frontend::analyze_source(&module_id.0, &source);
&analyzed.units
}
};
let Some(fragment) = fragment else {
return (true, Some(module_id.0), None);
};
let resolved = target_units.anchors.get(fragment).or_else(|| {
target_units
.units
.iter()
.find(|unit| unit.name == fragment)
.map(|unit| &unit.id)
});
match resolved {
Some(unit) => (true, Some(module_id.0), Some(unit.to_string())),
None => (false, Some(module_id.0), None),
}
}
/// `marqdo run` / `marqdo call`.
pub fn execute(
file: Option<&Path>,
function: Option<&str>,
named_args: &[(String, Value)],
settings: &SandboxSettings,
json: bool,
trace: bool,
) -> i32 {
let project = match load_project(file, json) {
Ok(project) => project,
Err(code) => return code,
};
if project.has_errors() {
if json {
output::print_json(&json!({
"command": "run",
"success": false,
"diagnostics": output::diagnostics_json(&project.diagnostics),
}));
} else {
eprint!("{}", output::render_text(&project.diagnostics));
eprintln!("error: refusing to run a project with compile errors");
}
return 1;
}
let mode = match settings.sandbox_mode() {
Ok(mode) => mode,
Err(error) => {
eprintln!("error: {error}");
return 2;
}
};
let platform = PlatformCapabilities::detect();
if let Err(error) = marqdo_sandbox::enforce(mode, &platform) {
if json {
output::print_json(&json!({"success": false, "error": error.to_string()}));
} else {
eprintln!("error: {error}");
}
return 1;
}
let capabilities = match settings.capabilities() {
Ok(capabilities) => capabilities,
Err(error) => {
eprintln!("error: {error}");
return 2;
}
};
let mut host = StdHost::new(mode, capabilities, project.root.clone());
if trace || json {
host = host.with_trace();
}
if let Some(fuel) = settings.fuel {
host.budget.fuel = fuel;
}
if let Some(stack) = settings.stack {
host.budget.stack_limit = stack;
}
if let Some(max_output) = settings.max_output {
host.budget.max_output_bytes = max_output;
}
if let Some(timeout) = settings.timeout {
host.budget.deadline = Some(Instant::now() + Duration::from_secs(timeout));
}
let function_name = function.unwrap_or("main").to_string();
let entry_module = &project.program.modules[&project.entry];
if entry_module.function(&function_name).is_none() {
eprintln!(
"error: no function named `{function_name}` in {}",
project.entry_file().path.display()
);
return 1;
}
let runtime_args: Vec<EvaluatedArg> = named_args
.iter()
.map(|(name, value)| EvaluatedArg::named(name.clone(), value.clone(), Span::default()))
.collect();
let result = run(
&project.program,
&mut host,
&project.entry,
&function_name,
runtime_args,
);
let stdout = host.take_output();
let stdout_text = String::from_utf8_lossy(&stdout).to_string();
let trace_entries = host.trace().to_vec();
match result {
Ok(outcome) => {
if json {
output::print_json(&json!({
"command": "run",
"success": true,
"value": marqdo_value::to_wire(&outcome.value),
"stdout": stdout_text,
"trace": trace_entries,
}));
} else {
use std::io::Write;
let _ = std::io::stdout().write_all(&stdout);
if function.is_some() && outcome.value != Value::Unit {
println!("{}", outcome.value.display());
}
if trace {
for entry in &trace_entries {
eprintln!(
"trace: {} {} {}us {}",
entry.op, entry.module, entry.duration_micros, entry.result
);
}
}
}
0
}
Err(error) => {
if json {
output::print_json(&json!({
"command": "run",
"success": false,
"stdout": stdout_text,
"error": runtime_error_json(&error, &project),
"trace": trace_entries,
}));
} else {
use std::io::Write;
let _ = std::io::stdout().write_all(&stdout);
eprint!("{}", render_runtime_error(&error, &project));
}
1
}
}
}
fn runtime_error_json(error: &RuntimeError, project: &LoadedProject) -> serde_json::Value {
let entry = project.entry_file();
let span = error.span.map(|span| {
let position = marqdo_span::LineIndex::new(&entry.source).line_col(span.start);
json!({"line": position.line, "column": position.column, "file": entry.path.display().to_string()})
});
json!({
"code": error.code(),
"message": error.message,
"span": span,
"frames": error.frames,
})
}
fn render_runtime_error(error: &RuntimeError, project: &LoadedProject) -> String {
let entry = project.entry_file();
let mut out = String::new();
out.push_str(&format!(
"runtime error[{}]: {}\n",
error.code(),
error.message
));
if let Some(span) = error.span {
let position = marqdo_span::LineIndex::new(&entry.source).line_col(span.start);
out.push_str(&format!(
" at {}:{}:{}\n",
entry.path.display(),
position.line,
position.column
));
}
for frame in &error.frames {
out.push_str(&format!(" in function `{}`\n", frame.function));
}
out
}
/// `marqdo fmt`.
pub fn fmt(file: Option<&Path>, check_only: bool) -> i32 {
let file = file.unwrap_or_else(|| Path::new("index.mq.md"));
let Ok(source) = std::fs::read_to_string(file) else {
eprintln!("error: cannot read `{}`", file.display());
return 2;
};
let mut formatted = source.replace("\r\n", "\n");
while formatted.ends_with("\n\n") {
formatted.pop();
}
if !formatted.ends_with('\n') {
formatted.push('\n');
}
if formatted == source {
return 0;
}
if check_only {
eprintln!(
"error: `{}` is not formatted (trailing whitespace/newlines or CRLF)",
file.display()
);
return 1;
}
if let Err(error) = std::fs::write(file, formatted) {
eprintln!("error: cannot write `{}`: {error}", file.display());
return 1;
}
0
}
/// `marqdo plugin inspect`.
pub fn plugin_inspect(target: &Path, json: bool) -> i32 {
let manifest_path = if target.is_dir() {
target.join("plugin.yaml")
} else {
target.to_path_buf()
};
let base_dir = manifest_path
.parent()
.map(|parent| parent.to_path_buf())
.unwrap_or_else(|| PathBuf::from("."));
let manifest = match marqdo_plugin_abi::PluginManifest::load(&manifest_path) {
Ok(manifest) => manifest,
Err(error) => {
report_plugin_error(&error, json);
return 1;
}
};
if let Err(error) = manifest.validate() {
report_plugin_error(&error, json);
return 1;
}
let host_target = marqdo_plugin_abi::HostTarget::current();
let artifact = match manifest.verify_artifact(&base_dir, &host_target) {
Ok((path, artifact)) => {
let abi = match manifest.abi_requirement() {
Ok(requirement) => {
if requirement.is_compatible_with(marqdo_plugin_abi::AbiVersion::current()) {
"compatible"
} else {
"incompatible"
}
}
Err(error) => {
report_plugin_error(&error, json);
return 1;
}
};
(path, artifact, abi)
}
Err(error) => {
report_plugin_error(&error, json);
return 1;
}
};
let (artifact_path, artifact_info, abi) = artifact;
if json {
output::print_json(&json!({
"command": "plugin.inspect",
"success": true,
"plugin": manifest.plugin.name,
"version": manifest.plugin.version,
"abi": manifest.plugin.abi,
"abi_compatibility": abi,
"target": host_target.triple().as_str(),
"artifact": {
"file": artifact_info.file,
"path": artifact_path.display().to_string(),
"sha256": artifact_info.sha256,
"verified": true,
},
"exports": manifest.plugin.exports.iter().map(|export| json!({
"name": export.name,
"signature": export.signature,
})).collect::<Vec<_>>(),
"loaded": false,
}));
} else {
println!(
"plugin: {} {}",
manifest.plugin.name, manifest.plugin.version
);
println!("abi: {} ({abi})", manifest.plugin.abi);
println!("target: {}", host_target.triple().as_str());
println!(
"artifact: {} (sha256 verified: {})",
artifact_path.display(),
artifact_info.sha256
);
println!("exports:");
for export in &manifest.plugin.exports {
println!(" {} {}", export.name, export.signature);
}
println!("loaded: false (inspection never executes plugin code)");
}
0
}
fn report_plugin_error(error: &marqdo_plugin_abi::PluginError, json: bool) {
if json {
output::print_json(&json!({
"command": "plugin.inspect",
"success": false,
"error": {
"kind": error.kind,
"code": error.code,
"message": error.message,
}
}));
} else {
eprintln!("error[{}]: {}", error.code, error.message);
}
}
/// `marqdo lock`.
pub fn lock(json: bool) -> i32 {
let root = match discover_project_root() {
Ok(root) => root,
Err(error) => {
eprintln!("error: {error}");
return 2;
}
};
let manifest = match marqdo_package::Manifest::load(&root.join(marqdo_package::MANIFEST_FILE)) {
Ok(manifest) => manifest,
Err(error) => {
eprintln!("error: {error}");
return 2;
}
};
let lockfile = match build_lockfile(&root, &manifest) {
Ok(lockfile) => lockfile,
Err(error) => {
eprintln!("error: {error}");
return 1;
}
};
let path = root.join(marqdo_package::LOCK_FILE);
if let Err(error) = std::fs::write(&path, lockfile.to_yaml()) {
eprintln!("error: cannot write {}: {error}", path.display());
return 1;
}
if json {
output::print_json(&json!({
"command": "lock",
"success": true,
"packages": lockfile.packages,
}));
} else {
println!(
"locked {} package(s) in {}",
lockfile.packages.len(),
path.display()
);
}
0
}
/// `marqdo sync [--locked]`.
pub fn sync(locked: bool, json: bool) -> i32 {
let root = match discover_project_root() {
Ok(root) => root,
Err(error) => {
eprintln!("error: {error}");
return 2;
}
};
let manifest = match marqdo_package::Manifest::load(&root.join(marqdo_package::MANIFEST_FILE)) {
Ok(manifest) => manifest,
Err(error) => {
eprintln!("error: {error}");
return 2;
}
};
let lock_path = root.join(marqdo_package::LOCK_FILE);
if !lock_path.is_file() {
eprintln!(
"error: {} is missing; run `marqdo lock` first",
lock_path.display()
);
return 1;
}
let lockfile = match marqdo_package::LockFile::load(&lock_path) {
Ok(lockfile) => lockfile,
Err(error) => {
eprintln!("error: {error}");
return 1;
}
};
let expected = match build_lockfile(&root, &manifest) {
Ok(lockfile) => lockfile,
Err(error) => {
eprintln!("error: {error}");
return 1;
}
};
if locked && expected != lockfile {
eprintln!(
"error: lockfile is out of date or dependency contents changed; run `marqdo lock`"
);
return 1;
}
if json {
output::print_json(&json!({
"command": "sync",
"success": true,
"locked": locked,
"packages": expected.packages,
}));
} else {
println!(
"synchronized {} package(s){}",
expected.packages.len(),
if locked { " (locked)" } else { "" }
);
}
0
}
fn discover_project_root() -> Result<PathBuf, String> {
let cwd = std::env::current_dir().map_err(|error| error.to_string())?;
marqdo_package::discover_root(&cwd).ok_or_else(|| {
format!(
"no {} found in {} or any parent",
marqdo_package::MANIFEST_FILE,
cwd.display()
)
})
}
fn build_lockfile(
root: &Path,
manifest: &marqdo_package::Manifest,
) -> Result<marqdo_package::LockFile, String> {
let mut packages = Vec::new();
for (name, dependency) in &manifest.dependencies {
if dependency.git.is_some() {
return Err(format!(
"dependency `{name}` uses a git source; git dependencies are not supported by this build (path dependencies only)"
));
}
let Some(path) = &dependency.path else {
return Err(format!("dependency `{name}` has no path source"));
};
let dependency_root = root.join(path);
let hash = hash_tree(&dependency_root)?;
packages.push(marqdo_package::LockedPackage {
name: name.clone(),
source: format!("path:{}", path.display()),
sha256: Some(hash),
});
}
packages.sort_by(|a, b| a.name.cmp(&b.name));
Ok(marqdo_package::LockFile {
lock_version: 1,
packages,
})
}
fn hash_tree(root: &Path) -> Result<String, String> {
if !root.exists() {
return Err(format!(
"dependency path `{}` does not exist",
root.display()
));
}
let mut files = Vec::new();
for entry in walkdir::WalkDir::new(root)
.sort_by_file_name()
.into_iter()
.filter_map(Result::ok)
{
if entry.file_type().is_file() {
let relative = entry
.path()
.strip_prefix(root)
.map(|path| path.to_string_lossy().replace('\\', "/"))
.unwrap_or_default();
files.push((relative, entry.path().to_path_buf()));
}
}
files.sort_by(|a, b| a.0.cmp(&b.0));
let mut hasher = Sha256::new();
for (relative, path) in files {
hasher.update(relative.as_bytes());
hasher.update([0u8]);
let bytes = std::fs::read(&path)
.map_err(|error| format!("cannot read `{}`: {error}", path.display()))?;
hasher.update(&bytes);
hasher.update([0u8]);
}
Ok(hex::encode(hasher.finalize()))
}
/// Resolve `--arg` strings into typed arguments.
pub fn parse_named_args(raw: &[String]) -> Result<Vec<(String, Value)>, String> {
raw.iter()
.map(|entry| args::parse_named_arg(entry))
.collect()
}
+296
View File
@@ -0,0 +1,296 @@
//! Project and module loading for the CLI.
//!
//! Loading is static: files are parsed and analysed, never executed. Imports
//! come only from explicit YAML front matter and are resolved exactly as
//! declared (`@dependency` or a relative `.mq.md` path); nothing is searched
//! implicitly.
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use marqdo_frontend::{analyze_source, AnalysisResult};
use marqdo_ir::{ModuleId, Program, ResolvedImport};
use marqdo_package::{discover_root, Manifest, MANIFEST_FILE};
use marqdo_value::{codes, Diagnostic};
/// One analysed source file.
pub struct LoadedFile {
/// Canonical module identity (project-relative path).
pub module_id: ModuleId,
/// Absolute path on disk.
pub path: PathBuf,
/// Source text.
pub source: String,
/// Frontend analysis.
pub analysis: AnalysisResult,
}
/// A diagnostic tied to its file for rendering.
#[derive(Debug, Clone)]
pub struct FileDiagnostic {
/// Module that produced it.
pub module_id: ModuleId,
/// Absolute file path.
pub path: PathBuf,
/// Source text (needed for line/column rendering).
pub source: String,
/// The structured diagnostic.
pub diagnostic: Diagnostic,
}
impl FileDiagnostic {
/// 1-based line/column of the diagnostic span.
pub fn line_col(&self) -> Option<(usize, usize)> {
let span = self.diagnostic.span?;
let index = marqdo_span::LineIndex::new(&self.source);
let position = index.line_col(span.start);
Some((position.line, position.column))
}
/// Source text of the diagnostic's line.
pub fn line_text(&self) -> Option<&str> {
let span = self.diagnostic.span?;
let index = marqdo_span::LineIndex::new(&self.source);
let position = index.line_col(span.start);
self.source.lines().nth(position.line.saturating_sub(1))
}
}
/// A fully loaded project ready for checking or running.
pub struct LoadedProject {
/// Project root.
pub root: PathBuf,
/// Entry module.
pub entry: ModuleId,
/// All modules.
pub program: Program,
/// Analysed files keyed by module id.
pub files: BTreeMap<ModuleId, LoadedFile>,
/// All diagnostics in deterministic order.
pub diagnostics: Vec<FileDiagnostic>,
}
impl LoadedProject {
/// Whether any diagnostic is an error.
pub fn has_errors(&self) -> bool {
self.diagnostics
.iter()
.any(|diag| diag.diagnostic.is_error())
}
/// The entry file.
pub fn entry_file(&self) -> &LoadedFile {
&self.files[&self.entry]
}
}
struct Loader {
root: PathBuf,
manifest: Option<Manifest>,
files: BTreeMap<ModuleId, LoadedFile>,
program: Program,
diagnostics: Vec<FileDiagnostic>,
stack: Vec<PathBuf>,
}
/// Load the entry file and its explicitly imported modules.
pub fn load(entry: &Path) -> Result<LoadedProject, String> {
let entry = entry
.canonicalize()
.map_err(|error| format!("cannot open `{}`: {error}", entry.display()))?;
if !entry.is_file() {
return Err(format!("`{}` is not a file", entry.display()));
}
let root = match discover_root(&entry) {
Some(root) => root.canonicalize().unwrap_or(root),
None => entry
.parent()
.map(|parent| parent.to_path_buf())
.unwrap_or_else(|| PathBuf::from(".")),
};
let manifest = if root.join(MANIFEST_FILE).is_file() {
Some(Manifest::load(&root.join(MANIFEST_FILE))?)
} else {
None
};
let mut loader = Loader {
root,
manifest,
files: BTreeMap::new(),
program: Program::default(),
diagnostics: Vec::new(),
stack: Vec::new(),
};
let entry_id = loader.load_module(&entry)?;
loader.program.main_module = Some(entry_id.clone());
for (module_id, diagnostic) in marqdo_frontend::calls::validate_program(&loader.program) {
if let Some(file) = loader.files.get(&module_id) {
loader.diagnostics.push(FileDiagnostic {
module_id,
path: file.path.clone(),
source: file.source.clone(),
diagnostic,
});
}
}
Ok(LoadedProject {
root: loader.root,
entry: entry_id,
program: loader.program,
files: loader.files,
diagnostics: loader.diagnostics,
})
}
impl Loader {
fn module_id_for(&self, path: &Path) -> Option<ModuleId> {
let relative = path.strip_prefix(&self.root).ok()?;
let mut parts = Vec::new();
for component in relative.components() {
parts.push(component.as_os_str().to_string_lossy().to_string());
}
Some(ModuleId(parts.join("/")))
}
fn load_module(&mut self, path: &Path) -> Result<ModuleId, String> {
let path = path
.canonicalize()
.map_err(|error| format!("cannot open `{}`: {error}", path.display()))?;
let module_id = self
.module_id_for(&path)
.ok_or_else(|| format!("`{}` is outside the project root", path.display()))?;
if self.files.contains_key(&module_id) {
return Ok(module_id);
}
if self.stack.contains(&path) {
return Err(format!(
"module import cycle detected at `{}`",
path.display()
));
}
self.stack.push(path.clone());
let source = std::fs::read_to_string(&path)
.map_err(|error| format!("cannot read `{}`: {error}", path.display()))?;
let analysis = analyze_source(&module_id.0, &source);
let imports: Vec<(String, String, marqdo_span::Span)> = analysis
.document
.frontmatter()
.and_then(|frontmatter| frontmatter.imports().ok())
.map(|mapping| {
mapping
.into_iter()
.map(|(alias, target)| {
(
alias,
target,
analysis
.document
.frontmatter()
.map(|f| f.span)
.unwrap_or_default(),
)
})
.collect()
})
.unwrap_or_default();
for (alias, target, span) in imports {
match self.resolve_import(&path, &target) {
Some(target_path) => {
if self.stack.contains(&target_path) {
self.diagnostics.push(FileDiagnostic {
module_id: module_id.clone(),
path: path.clone(),
source: source.clone(),
diagnostic: Diagnostic::error(
codes::MODULE_CYCLE,
Some(span),
format!("import `{alias}` -> `{target}` creates an import cycle"),
)
.with_hint("remove the cycle; modules register definitions only"),
});
continue;
}
match self.load_module(&target_path) {
Ok(target_id) => {
self.program.resolved_imports.push(ResolvedImport {
from: module_id.clone(),
alias,
to: target_id,
});
}
Err(error) => self.diagnostics.push(FileDiagnostic {
module_id: module_id.clone(),
path: path.clone(),
source: source.clone(),
diagnostic: Diagnostic::error(
codes::MODULE_UNRESOLVED,
Some(span),
error,
),
}),
}
}
None => {
self.diagnostics.push(FileDiagnostic {
module_id: module_id.clone(),
path: path.clone(),
source: source.clone(),
diagnostic: Diagnostic::error(
codes::MODULE_UNRESOLVED,
Some(span),
format!("cannot resolve imported module `{target}`"),
)
.with_hint(
"use `@dependency` for marqdo.yaml dependencies or `./file.mq.md` for project files",
),
});
}
}
}
for diagnostic in &analysis.diagnostics {
self.diagnostics.push(FileDiagnostic {
module_id: module_id.clone(),
path: path.clone(),
source: source.clone(),
diagnostic: diagnostic.clone(),
});
}
self.stack.pop();
self.files.insert(
module_id.clone(),
LoadedFile {
module_id: module_id.clone(),
path,
source,
analysis,
},
);
// Move the analysed module into the program.
if let Some(file) = self.files.get(&module_id) {
self.program
.modules
.insert(module_id.clone(), file.analysis.module.clone());
}
Ok(module_id)
}
fn resolve_import(&self, importing: &Path, target: &str) -> Option<PathBuf> {
if let Some(alias) = target.strip_prefix('@') {
let manifest = self.manifest.as_ref()?;
let dependency = manifest.dependencies.get(alias)?;
let path = dependency.path.as_ref()?;
let dependency_path = self.root.join(path);
let candidate = if dependency_path.is_dir() {
dependency_path.join("index.mq.md")
} else {
dependency_path
};
return candidate.canonicalize().ok();
}
let base = importing.parent()?;
let candidate = base.join(target);
candidate.canonicalize().ok()
}
}
+263 -1
View File
@@ -1,3 +1,265 @@
//! Marqdo command line interface: the composition root.
//!
//! The CLI loads Markdown modules, runs the frontend, and either reports
//! diagnostics (`check`/`inspect`) or executes through the runtime and
//! capability host (`run`/`call`). It never holds a second interpreter.
mod args;
mod commands;
mod loader;
mod output;
use std::path::PathBuf;
use clap::{Args, Parser, Subcommand};
#[derive(Parser)]
#[command(
name = "marqdo",
version,
about = "Markdown-native programming language (independent Rust interpreter)",
long_about = "Marqdo executes Markdown documents whose AST structures carry program meaning. `check` and `inspect` never execute project code; `run` and `call` execute through the capability host."
)]
struct Cli {
#[command(subcommand)]
command: Command,
}
#[derive(Subcommand)]
enum Command {
/// Initialise a new Marqdo project.
Init(InitArgs),
/// Run the entry function (`main` by default) of a document.
Run(RunArgs),
/// Call a named function with typed arguments.
Call(CallArgs),
/// Statically check a document without executing it.
Check(CheckArgs),
/// Inspect AST, units, signatures, IR, references or platform support.
Inspect(InspectArgs),
/// Conservative formatting: normalises line endings and trailing newlines.
Fmt(FmtArgs),
/// Plugin artifact inspection (never loads plugin code).
Plugin(PluginArgs),
/// Generate a deterministic marqdo.lock for the current project.
Lock(LockArgs),
/// Verify that path dependencies match the lockfile.
Sync(SyncArgs),
}
#[derive(Args)]
struct InitArgs {
/// Directory to initialise (defaults to the current directory).
dir: Option<PathBuf>,
}
#[derive(Args, Clone)]
struct SandboxArgs {
/// Sandbox mode: pure, project or strict.
#[arg(long, default_value = "project")]
mode: String,
/// Grant read access to a project-relative glob (repeatable).
#[arg(long = "allow-read", value_name = "GLOB")]
allow_read: Vec<String>,
/// Grant write access to a project-relative glob (repeatable).
#[arg(long = "allow-write", value_name = "GLOB")]
allow_write: Vec<String>,
/// Grant explicit foreign kernel execution.
#[arg(long = "allow-foreign")]
allow_foreign: bool,
/// Grant a plugin name execution permission (repeatable).
#[arg(long = "allow-plugin", value_name = "NAME")]
allow_plugin: Vec<String>,
/// Override the evaluation fuel budget.
#[arg(long)]
fuel: Option<u64>,
/// Override the call stack depth limit.
#[arg(long)]
stack: Option<usize>,
/// Override the program output byte limit.
#[arg(long = "max-output")]
max_output: Option<usize>,
/// Wall-clock timeout in seconds.
#[arg(long)]
timeout: Option<u64>,
}
impl SandboxArgs {
fn settings(&self) -> commands::SandboxSettings {
commands::SandboxSettings {
mode: self.mode.clone(),
allow_read: self.allow_read.clone(),
allow_write: self.allow_write.clone(),
allow_foreign: self.allow_foreign,
allow_plugin: self.allow_plugin.clone(),
fuel: self.fuel,
stack: self.stack,
max_output: self.max_output,
timeout: self.timeout,
}
}
}
#[derive(Args)]
struct RunArgs {
/// Entry document (defaults to index.mq.md).
file: Option<PathBuf>,
#[command(flatten)]
sandbox: SandboxArgs,
/// Machine readable JSON output; program stdout is embedded, never mixed.
#[arg(long)]
json: bool,
/// Include the host effect trace.
#[arg(long)]
trace: bool,
}
#[derive(Args)]
struct CallArgs {
/// Entry document.
file: PathBuf,
/// Function name (canonical or namespace-qualified).
function: String,
/// Named argument as `name=value` with a constant expression value.
#[arg(long = "arg", value_name = "NAME=VALUE")]
args: Vec<String>,
#[command(flatten)]
sandbox: SandboxArgs,
/// Machine readable JSON output.
#[arg(long)]
json: bool,
/// Include the host effect trace.
#[arg(long)]
trace: bool,
}
#[derive(Args)]
struct CheckArgs {
/// Document to check (defaults to index.mq.md).
file: Option<PathBuf>,
/// Machine readable JSON output.
#[arg(long)]
json: bool,
}
#[derive(Args)]
struct InspectArgs {
/// Document to inspect (defaults to index.mq.md).
file: Option<PathBuf>,
/// Print the canonical Markdown AST.
#[arg(long)]
ast: bool,
/// Print heading units and function scopes.
#[arg(long)]
units: bool,
/// Print function signatures.
#[arg(long)]
signature: bool,
/// Print executable IR.
#[arg(long)]
ir: bool,
/// Print static reference edges.
#[arg(long)]
refs: bool,
/// Print sandbox/platform capability report.
#[arg(long)]
platform: bool,
/// Machine readable JSON output.
#[arg(long)]
json: bool,
}
#[derive(Args)]
struct FmtArgs {
/// Document to format (defaults to index.mq.md).
file: Option<PathBuf>,
/// Check whether formatting is needed without writing.
#[arg(long = "check")]
check: bool,
}
#[derive(Args)]
struct PluginArgs {
#[command(subcommand)]
command: PluginCommand,
}
#[derive(Subcommand)]
enum PluginCommand {
/// Inspect a plugin manifest/artifact without loading it.
Inspect(PluginInspectArgs),
}
#[derive(Args)]
struct PluginInspectArgs {
/// Plugin directory or plugin.yaml path.
target: PathBuf,
/// Machine readable JSON output.
#[arg(long)]
json: bool,
}
#[derive(Args)]
struct LockArgs {
/// Machine readable JSON output.
#[arg(long)]
json: bool,
}
#[derive(Args)]
struct SyncArgs {
/// Fail instead of silently updating when the lockfile is stale.
#[arg(long)]
locked: bool,
/// Machine readable JSON output.
#[arg(long)]
json: bool,
}
fn main() {
println!("marqdo {}", env!("CARGO_PKG_VERSION"));
let cli = Cli::parse();
let code = match cli.command {
Command::Init(args) => commands::init(args.dir.as_deref()),
Command::Check(args) => commands::check(args.file.as_deref(), args.json),
Command::Inspect(args) => {
let flags = commands::InspectFlags {
ast: args.ast,
units: args.units,
signature: args.signature,
ir: args.ir,
refs: args.refs,
platform: args.platform,
};
commands::inspect(args.file.as_deref(), &flags, args.json)
}
Command::Run(args) => commands::execute(
args.file.as_deref(),
None,
&[],
&args.sandbox.settings(),
args.json,
args.trace,
),
Command::Call(args) => match commands::parse_named_args(&args.args) {
Ok(named) => commands::execute(
Some(&args.file),
Some(&args.function),
&named,
&args.sandbox.settings(),
args.json,
args.trace,
),
Err(error) => {
eprintln!("error: {error}");
2
}
},
Command::Fmt(args) => commands::fmt(args.file.as_deref(), args.check),
Command::Plugin(args) => match args.command {
PluginCommand::Inspect(args) => commands::plugin_inspect(&args.target, args.json),
},
Command::Lock(args) => commands::lock(args.json),
Command::Sync(args) => commands::sync(args.locked, args.json),
};
std::process::exit(code);
}
+98
View File
@@ -0,0 +1,98 @@
//! Diagnostic rendering and JSON envelopes.
use serde_json::{json, Value as Json};
use crate::loader::FileDiagnostic;
/// Severity name.
fn severity_name(diagnostic: &marqdo_value::Diagnostic) -> &'static str {
match diagnostic.severity {
marqdo_value::Severity::Error => "error",
marqdo_value::Severity::Warning => "warning",
marqdo_value::Severity::Info => "info",
}
}
/// Render diagnostics as human readable text (stderr).
pub fn render_text(diagnostics: &[FileDiagnostic]) -> String {
let mut out = String::new();
for item in diagnostics {
let diagnostic = &item.diagnostic;
let location = match item.line_col() {
Some((line, column)) => format!("{}:{line}:{column}", item.path.display()),
None => item.path.display().to_string(),
};
out.push_str(&format!(
"{}[{}]: {}: {}\n",
severity_name(diagnostic),
diagnostic.code,
location,
diagnostic.message
));
if let Some(line_text) = item.line_text() {
let index = marqdo_span::LineIndex::new(&item.source);
if let Some(span) = diagnostic.span {
let position = index.line_col(span.start);
let caret_offset = position.column.saturating_sub(1);
out.push_str(&format!(" {}\n", line_text.trim_end()));
out.push_str(&format!(
" {}^\n",
" ".repeat(caret_offset.min(line_text.len()))
));
}
}
for related in &diagnostic.related {
let mut message = related.message.clone();
if let Some(span) = related.span {
let index = marqdo_span::LineIndex::new(&item.source);
let position = index.line_col(span.start);
message = format!("{}:{}: {}", position.line, position.column, message);
}
out.push_str(&format!(" note: {message}\n"));
}
for hint in &diagnostic.hints {
out.push_str(&format!(" hint: {hint}\n"));
}
}
out
}
/// Serialize one diagnostic with file/line/column metadata.
pub fn diagnostic_json(item: &FileDiagnostic) -> Json {
let diagnostic = &item.diagnostic;
let (line, column) = item
.line_col()
.map(|(line, column)| (Json::from(line), Json::from(column)))
.unwrap_or((Json::Null, Json::Null));
json!({
"file": item.path.display().to_string(),
"module": item.module_id.0,
"line": line,
"column": column,
"severity": severity_name(diagnostic),
"code": diagnostic.code,
"message": diagnostic.message,
"hints": diagnostic.hints,
})
}
/// Serialize diagnostics.
pub fn diagnostics_json(diagnostics: &[FileDiagnostic]) -> Json {
Json::Array(diagnostics.iter().map(diagnostic_json).collect())
}
/// Print a JSON value to stdout.
pub fn print_json(value: &Json) {
println!(
"{}",
serde_json::to_string_pretty(value).unwrap_or_default()
);
}
/// Count errors.
pub fn error_count(diagnostics: &[FileDiagnostic]) -> usize {
diagnostics
.iter()
.filter(|item| item.diagnostic.is_error())
.count()
}