Files
marqdo-cli/crates/cli/tests/analysis_trace.rs
T
cflmy 55dcb57553 feat(analysis): Analysis v2 logical identity and resource projection (B-06 B-07)
- add ProjectIdentity (manifest root instance or workspace snapshot digest)
  and remove absolute-path root ids from Analysis bytes
- replace the resources count with an addressable array over the two real
  marqdo-ir resource kinds (formula, code), including unit/span/payload digest
  and code language
- project diagnostics by module/relative path/span, removing machine paths
- define the digest as SHA-256 of the exact emitted bytes so consumers can
  verify it; Trace binds to the same digest
- add analysis-v2 spec and JSON schema, supersede v1, update the independent
  Python consumer, schemas and docs
- tests: location-independent byte equality and resource addressing
2026-11-20 12:58:58 +08:00

318 lines
9.4 KiB
Rust

//! Public Analysis/Trace v1 black-box contract (spec/analysis-v1.md,
//! spec/trace-v1.md).
use std::path::{Path, PathBuf};
use std::process::{Command, Output};
use std::sync::atomic::{AtomicU32, Ordering};
static COUNTER: AtomicU32 = AtomicU32::new(0);
struct TempDir(PathBuf);
impl TempDir {
fn new(tag: &str) -> Self {
let id = COUNTER.fetch_add(1, Ordering::Relaxed);
let path = std::env::temp_dir().join(format!(
"marqdo-protocol-test-{}-{id}-{tag}",
std::process::id()
));
std::fs::create_dir_all(&path).unwrap();
Self(path)
}
fn path(&self) -> &Path {
&self.0
}
}
impl Drop for TempDir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
fn binary() -> &'static str {
env!("CARGO_BIN_EXE_marqdo")
}
fn cli(dir: &Path, args: &[&str]) -> Output {
Command::new(binary())
.args(args)
.current_dir(dir)
.output()
.expect("run marqdo")
}
fn write(dir: &Path, name: &str, source: &str) -> PathBuf {
let path = dir.join(name);
std::fs::write(&path, source).unwrap();
path
}
const PROGRAM: &str = r#"# 数学
## 加一
`(n)`
*n + 1*
## main
**结果 = 加一(41)**
> 打印("secret-value")
*结果*
"#;
#[test]
fn analysis_is_deterministic_and_has_stable_semantic_nodes() {
let dir = TempDir::new("analysis");
write(dir.path(), "index.mq.md", PROGRAM);
let first = dir.path().join("first.json");
let second = dir.path().join("second.json");
for path in [&first, &second] {
let output = cli(
dir.path(),
&[
"check",
"index.mq.md",
"--refs",
"--emit",
path.to_str().unwrap(),
],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
}
let first_bytes = std::fs::read(&first).unwrap();
let second_bytes = std::fs::read(&second).unwrap();
assert_eq!(first_bytes, second_bytes, "analysis must be deterministic");
let analysis: serde_json::Value = serde_json::from_slice(&first_bytes).unwrap();
assert_eq!(analysis["schema"], "marqdo.analysis");
assert_eq!(analysis["schema_version"], 2);
let module = &analysis["modules"][0];
assert_eq!(module["id"], "root:default::index.mq.md");
assert_eq!(module["package_instance_id"], "root:default");
assert!(
analysis["project"]["root_id"]
.as_str()
.unwrap_or_default()
.starts_with("sha256:"),
"standalone documents use a workspace snapshot identity"
);
assert_eq!(analysis["project"]["identity_kind"], "workspace_snapshot");
assert_eq!(module["functions"].as_array().unwrap().len(), 2);
let main = module["functions"]
.as_array()
.unwrap()
.iter()
.find(|function| function["local_name"] == "main")
.unwrap();
let body = main["body"].as_array().unwrap();
assert_eq!(body.last().unwrap()["kind"], "return");
let calls = module["calls"].as_array().unwrap();
assert!(calls.iter().any(|call| call["state"] == "function"
&& call["target"] == "root:default::index.mq.md::数学.加一"));
// Independent Python consumer, if available.
let consumer = Path::new(env!("CARGO_MANIFEST_DIR"))
.parent()
.unwrap()
.parent()
.unwrap()
.join("tests/consumers/analysis_consumer.py");
if let Ok(output) = Command::new("python3").arg(&consumer).arg(&first).output() {
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
assert!(String::from_utf8_lossy(&output.stdout).starts_with("functions="));
}
}
#[test]
fn analysis_v2_identity_is_location_independent() {
let first = TempDir::new("analysis-identity-a");
let second = TempDir::new("analysis-identity-b");
let source = "## main\n\n**x = 1**\n\n*x*\n";
for dir in [&first, &second] {
write(
dir.path(),
"marqdo.yaml",
"project:\n name: doc\n version: 0.1.0\n",
);
write(dir.path(), "index.mq.md", source);
}
let mut bytes = Vec::new();
for dir in [&first, &second] {
let target = dir.path().join("analysis.json");
let output = cli(
dir.path(),
&["check", "index.mq.md", "--emit", target.to_str().unwrap()],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
bytes.push(std::fs::read(&target).unwrap());
}
assert_eq!(
bytes[0], bytes[1],
"moving a project must not change Analysis bytes"
);
let text = String::from_utf8(bytes[0].clone()).unwrap();
assert!(
!text.contains(first.path().to_str().unwrap()),
"machine path leaked into Analysis"
);
let analysis: serde_json::Value = serde_json::from_slice(&bytes[0]).unwrap();
assert_eq!(analysis["project"]["root_id"], "root:doc@0.1.0");
assert_eq!(analysis["project"]["identity_kind"], "manifest");
}
#[test]
fn analysis_v2_projects_addressable_formula_and_code_resources() {
let dir = TempDir::new("analysis-resources");
let source = r#"## calc
`(x)`
$$A = x + 1$$
```python
print(1)
```
*x*
"#;
write(
dir.path(),
"marqdo.yaml",
"project:\n name: res\n version: 0.1.0\n",
);
write(dir.path(), "index.mq.md", source);
let target = dir.path().join("analysis.json");
let output = cli(
dir.path(),
&["check", "index.mq.md", "--emit", target.to_str().unwrap()],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let analysis: serde_json::Value =
serde_json::from_slice(&std::fs::read(&target).unwrap()).unwrap();
let resources = analysis["modules"][0]["resources"].as_array().unwrap();
assert_eq!(resources.len(), 2, "{resources:?}");
let formula = resources
.iter()
.find(|resource| resource["kind"] == "formula")
.unwrap();
let code = resources
.iter()
.find(|resource| resource["kind"] == "code")
.unwrap();
assert_eq!(
formula["id"],
"root:res@0.1.0::index.mq.md#resource:formula-1"
);
assert_eq!(code["id"], "root:res@0.1.0::index.mq.md#resource:code-1");
assert_eq!(formula["module_id"], "root:res@0.1.0::index.mq.md");
assert_eq!(formula["language"], serde_json::Value::Null);
assert_eq!(code["language"], "python");
assert_eq!(formula["content_digest"].as_str().unwrap().len(), 64);
assert_eq!(code["content_digest"].as_str().unwrap().len(), 64);
assert!(
!analysis.to_string().contains("A = x + 1"),
"resource payloads stay in source, not Analysis"
);
}
#[test]
fn failed_check_removes_stale_analysis() {
let dir = TempDir::new("analysis-error");
write(dir.path(), "bad.mq.md", "## main\n\n1. 没有条件\n");
let target = dir.path().join("analysis.json");
std::fs::write(&target, "stale").unwrap();
let output = cli(
dir.path(),
&["check", "bad.mq.md", "--emit", target.to_str().unwrap()],
);
assert_eq!(output.status.code(), Some(1));
assert!(!target.exists(), "stale success artifact must be removed");
}
#[test]
fn trace_records_calls_effects_and_status_without_secrets() {
let dir = TempDir::new("trace");
write(dir.path(), "index.mq.md", PROGRAM);
let trace_path = dir.path().join("trace.json");
let output = cli(
dir.path(),
&[
"run",
"index.mq.md",
"--trace-file",
trace_path.to_str().unwrap(),
],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let text = std::fs::read_to_string(&trace_path).unwrap();
assert!(
!text.contains("secret-value"),
"values must not be recorded"
);
let trace: serde_json::Value = serde_json::from_str(&text).unwrap();
assert_eq!(trace["schema"], "marqdo.trace");
assert_eq!(trace["schema_version"], 1);
assert_eq!(trace["run"]["status"], "ok");
assert_eq!(trace["run"]["entry"], "root:default::index.mq.md::main");
let events = trace["events"].as_array().unwrap();
assert!(events.iter().any(|event| event["kind"] == "call.enter"));
assert!(events.iter().any(|event| event["kind"] == "effect"));
assert!(events.iter().any(|event| event["kind"] == "call.exit"));
let mut previous = None;
for event in events {
let seq = event["seq"].as_u64().unwrap();
if let Some(previous) = previous {
assert!(seq > previous);
}
previous = Some(seq);
}
// Error runs still write a terminal trace.
write(dir.path(), "bad.mq.md", "## main\n\n**x = 1 // 0**\n");
let error_trace = dir.path().join("error-trace.json");
let output = cli(
dir.path(),
&[
"run",
"bad.mq.md",
"--trace-file",
error_trace.to_str().unwrap(),
],
);
assert_eq!(output.status.code(), Some(1));
let trace: serde_json::Value =
serde_json::from_slice(&std::fs::read(&error_trace).unwrap()).unwrap();
assert_eq!(trace["run"]["status"], "runtime.division_by_zero");
}