feat: compile executable knowledge semantic artifacts
This commit is contained in:
1 parent
74b298e80d
commit
eac9b45263
9 files changed
+1033
-2
No files matched your search
@@ -17,6 +17,20 @@ pub struct KnowledgeOptions {
|
||||
}
|
||||
|
||||
pub fn compile(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
|
||||
// The semantic projection is the authoritative machine-facing graph. The
|
||||
// older EKC catalog below remains intentionally available as a compatible
|
||||
// human/retrieval projection, but never substitutes for semantic binding.
|
||||
let semantic_root = if opts.path.is_file() {
|
||||
opts.path.parent().unwrap_or_else(|| Path::new(".")).to_path_buf()
|
||||
} else {
|
||||
opts.path.clone()
|
||||
};
|
||||
let semantic = crate::sema::compile_project(&crate::sema::CompileOptions {
|
||||
project_root: semantic_root,
|
||||
entry: opts.path.is_file().then(|| opts.path.clone()),
|
||||
lock_mode: crate::sema::LockMode::Off,
|
||||
})?;
|
||||
crate::sema::write_semantic_projections(&opts.out_dir, &semantic)?;
|
||||
let extract_opts = ExtractOptions {
|
||||
path: opts.path.clone(),
|
||||
out_dir: opts.out_dir.clone(),
|
||||
|
||||
+43
@@ -377,6 +377,20 @@ enum KnowledgeAction {
|
||||
#[arg(long, value_name = "FILE")]
|
||||
from: Option<PathBuf>,
|
||||
},
|
||||
/// Check or update the reviewed semantic target lock (`links.lock.json`)
|
||||
Lock {
|
||||
/// Replace the lock with the current deterministic semantic graph
|
||||
#[arg(long)]
|
||||
update: bool,
|
||||
/// Return exit code 3 when the lock is missing or differs
|
||||
#[arg(long)]
|
||||
strict: bool,
|
||||
},
|
||||
/// Show transitive reverse dependencies of a symbol, artifact, or source path
|
||||
Impact {
|
||||
#[arg(value_name = "SYMBOL_OR_PATH")]
|
||||
query: String,
|
||||
},
|
||||
/// Run engineering preflight for a task
|
||||
Preflight {
|
||||
#[arg(value_name = "TASK")]
|
||||
@@ -1104,6 +1118,35 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
}
|
||||
Ok(if instance_only { 1 } else { 0 })
|
||||
}
|
||||
KnowledgeAction::Lock { update, strict } => {
|
||||
let semantic_root = if path.is_file() {
|
||||
path.parent().unwrap_or_else(|| std::path::Path::new(".")).to_path_buf()
|
||||
} else {
|
||||
path.clone()
|
||||
};
|
||||
let compilation = marqdo::sema::compile_project(&marqdo::sema::CompileOptions {
|
||||
project_root: semantic_root,
|
||||
entry: path.is_file().then(|| path.clone()),
|
||||
lock_mode: if strict { marqdo::sema::LockMode::Strict } else { marqdo::sema::LockMode::Check },
|
||||
})?;
|
||||
if update {
|
||||
marqdo::sema::update_links_lock(&out, &compilation.semantics)?;
|
||||
let body = serde_json::json!({"schema_version": 1, "status": "updated", "path": out.join("links.lock.json")});
|
||||
if json { println!("{body}"); } else { println!("knowledge lock updated: {}", out.join("links.lock.json").display()); }
|
||||
Ok(0)
|
||||
} else {
|
||||
let report = marqdo::sema::check_links_lock(&out, &compilation.semantics)?;
|
||||
if json { println!("{}", report.to_json()); } else { println!("knowledge lock: {}", report.status); for id in report.missing.iter().chain(report.changed.iter()).chain(report.removed.iter()) { println!(" {id}"); } }
|
||||
Ok(if strict && !report.is_clean() { 3 } else { 0 })
|
||||
}
|
||||
}
|
||||
KnowledgeAction::Impact { query } => {
|
||||
let semantic_root = if path.is_file() { path.parent().unwrap_or_else(|| std::path::Path::new(".")).to_path_buf() } else { path.clone() };
|
||||
let compilation = marqdo::sema::compile_project(&marqdo::sema::CompileOptions { project_root: semantic_root, entry: path.is_file().then(|| path.clone()), lock_mode: marqdo::sema::LockMode::Off })?;
|
||||
let report = marqdo::sema::semantic_impact(&compilation.semantics, &query);
|
||||
if json { println!("{report}"); } else { for item in report["affected"].as_array().into_iter().flatten() { println!("{} {}", item["artifact_id"].as_str().unwrap_or(""), item["display_name"].as_str().unwrap_or("")); } }
|
||||
Ok(if report["resolved"].as_bool() == Some(true) { 0 } else { 1 })
|
||||
}
|
||||
KnowledgeAction::Preflight {
|
||||
task,
|
||||
min_candidates,
|
||||
|
||||
+173
-1
@@ -57,17 +57,152 @@ fn dispatch(req: &Value) -> Result<Value, Value> {
|
||||
Some("repair_targets") => repair_targets(¶ms),
|
||||
Some("repair_apply") => repair_apply(¶ms),
|
||||
Some("schema") => schema(¶ms),
|
||||
Some("artifact.find") => artifact_find(¶ms),
|
||||
Some("artifact.inspect") => artifact_inspect(¶ms),
|
||||
Some("link.resolve") => link_resolve(¶ms),
|
||||
Some("artifact.verify") => artifact_verify(¶ms),
|
||||
Some("artifact.impact") => artifact_impact(¶ms),
|
||||
Some("artifact.bind") => artifact_bind(¶ms),
|
||||
Some("artifact.execute") => artifact_execute(¶ms),
|
||||
// `<TAB>` M9: occlusion label search (two-tier vocabulary).
|
||||
Some("labels.search") => labels_search(¶ms),
|
||||
// `<TAB>` M6: one-shot session summary (T1 staleness seen/fixed).
|
||||
Some("session.summary") => session_summary(),
|
||||
other => Err(err(
|
||||
"mlsp.unknown_method",
|
||||
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema"),
|
||||
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute"),
|
||||
)),
|
||||
}
|
||||
}
|
||||
|
||||
// ---------- Executable-knowledge artifact protocol ----------
|
||||
|
||||
/// All artifact methods compile the same semantic project as the CLI. They
|
||||
/// never fall back to EKC's lexical search when a binding decision is needed.
|
||||
fn semantic_project(params: &Value) -> Result<crate::sema::Compilation, Value> {
|
||||
if params.get("source").is_some() {
|
||||
return Err(err("mlsp.overlay_requires_path", "artifact 方法需要 params.project/path;内存 overlay 尚未持久化到项目边界"));
|
||||
}
|
||||
let root = params.get("project").or_else(|| params.get("path"))
|
||||
.and_then(Value::as_str).unwrap_or(".");
|
||||
let root = PathBuf::from(root);
|
||||
let project_root = if root.is_file() {
|
||||
root.parent().unwrap_or_else(|| Path::new(".")).to_path_buf()
|
||||
} else { root.clone() };
|
||||
crate::sema::compile_project(&crate::sema::CompileOptions {
|
||||
project_root,
|
||||
entry: root.is_file().then_some(root),
|
||||
lock_mode: crate::sema::LockMode::Off,
|
||||
}).map_err(|e| err("mlsp.semantic_compile", format!("{e:#}")))
|
||||
}
|
||||
|
||||
fn artifact_query<'a>(project: &'a crate::sema::SemanticProject, query: &str) -> Vec<&'a crate::sema::SemanticArtifact> {
|
||||
project.artifacts.iter().filter(|artifact| {
|
||||
artifact.artifact_id.0 == query || artifact.symbol_id.as_ref().is_some_and(|id| id.as_str() == query)
|
||||
|| artifact.display_name == query || artifact.artifact_id.0.ends_with(query)
|
||||
}).collect()
|
||||
}
|
||||
|
||||
fn artifact_find(params: &Value) -> Result<Value, Value> {
|
||||
let compilation = semantic_project(params)?;
|
||||
let query = params.get("query").and_then(Value::as_str).unwrap_or("").to_ascii_lowercase();
|
||||
let kind = params.get("kind").and_then(Value::as_str);
|
||||
let limit = params.get("limit").and_then(Value::as_u64).unwrap_or(20) as usize;
|
||||
let mut matches: Vec<Value> = compilation.semantics.artifacts.iter().filter(|artifact| {
|
||||
kind.map(|kind| kind == artifact.kind).unwrap_or(true) && (query.is_empty()
|
||||
|| artifact.display_name.to_ascii_lowercase().contains(&query)
|
||||
|| artifact.artifact_id.0.to_ascii_lowercase().contains(&query))
|
||||
}).take(limit).map(|artifact| json!({
|
||||
"artifact_id": artifact.artifact_id.0, "symbol_id": artifact.symbol_id.as_ref().map(|id| id.as_str()),
|
||||
"display_name": artifact.display_name, "kind": artifact.kind,
|
||||
"effects": artifact.effects.values(), "source": {"file":artifact.source.file,"line":artifact.source.line},
|
||||
})).collect();
|
||||
matches.sort_by(|a, b| a["artifact_id"].as_str().cmp(&b["artifact_id"].as_str()));
|
||||
Ok(json!({"schema_version":1,"discovery_only":true,"candidates":matches}))
|
||||
}
|
||||
|
||||
fn artifact_inspect(params: &Value) -> Result<Value, Value> {
|
||||
let compilation = semantic_project(params)?;
|
||||
let query = params.get("artifact_id").or_else(|| params.get("symbol_id")).or_else(|| params.get("id"))
|
||||
.and_then(Value::as_str).ok_or_else(|| err("mlsp.bad_request", "artifact.inspect 需要 artifact_id 或 symbol_id"))?;
|
||||
let candidates = artifact_query(&compilation.semantics, query);
|
||||
if candidates.is_empty() { return Err(err("artifact.unresolved", format!("没有制品 `{query}`"))); }
|
||||
if candidates.len() != 1 { return Err(json!({"code":"artifact.ambiguous","message":format!("制品 `{query}` 不唯一"),"candidates":candidates.iter().map(|a|&a.artifact_id.0).collect::<Vec<_>>() })); }
|
||||
Ok(crate::sema::artifact_json(candidates[0]))
|
||||
}
|
||||
|
||||
fn link_resolve(params: &Value) -> Result<Value, Value> {
|
||||
let compilation = semantic_project(params)?;
|
||||
let reference = params.get("payload").or_else(|| params.get("reference")).and_then(Value::as_str)
|
||||
.ok_or_else(|| err("mlsp.bad_request", "link.resolve 需要 payload/reference"))?;
|
||||
let candidates = artifact_query(&compilation.semantics, reference);
|
||||
let resolution = if candidates.is_empty() { "unresolved" } else if candidates.len() == 1 { "symbol" } else { "ambiguous" };
|
||||
Ok(json!({"schema_version":1,"reference":reference,"resolution":resolution,"candidates":candidates.iter().map(|a|json!({"artifact_id":a.artifact_id.0,"symbol_id":a.symbol_id.as_ref().map(|id|id.as_str()),"display_name":a.display_name,"effects":a.effects.values()})).collect::<Vec<_>>() }))
|
||||
}
|
||||
|
||||
fn artifact_verify(params: &Value) -> Result<Value, Value> {
|
||||
let compilation = semantic_project(params)?;
|
||||
let query = params.get("artifact_id").or_else(|| params.get("symbol_id")).and_then(Value::as_str)
|
||||
.ok_or_else(|| err("mlsp.bad_request", "artifact.verify 需要 artifact_id 或 symbol_id"))?;
|
||||
let candidates = artifact_query(&compilation.semantics, query);
|
||||
if candidates.len() != 1 { return Err(err(if candidates.is_empty() { "artifact.unresolved" } else { "artifact.ambiguous" }, format!("无法唯一验证 `{query}`"))); }
|
||||
let artifact = candidates[0];
|
||||
let mut record = crate::sema::artifact_json(artifact)["verification"].clone();
|
||||
record["policy"] = params.get("policy").cloned().unwrap_or_else(|| json!("static"));
|
||||
record["artifact_id"] = json!(artifact.artifact_id.0);
|
||||
Ok(record)
|
||||
}
|
||||
|
||||
fn artifact_impact(params: &Value) -> Result<Value, Value> {
|
||||
let compilation = semantic_project(params)?;
|
||||
let query = params.get("artifact_id").or_else(|| params.get("symbol_id")).or_else(|| params.get("path")).and_then(Value::as_str)
|
||||
.ok_or_else(|| err("mlsp.bad_request", "artifact.impact 需要 artifact_id、symbol_id 或 path"))?;
|
||||
Ok(crate::sema::semantic_impact(&compilation.semantics, query))
|
||||
}
|
||||
|
||||
fn artifact_bind(params: &Value) -> Result<Value, Value> {
|
||||
let compilation = semantic_project(params)?;
|
||||
let query = params.get("artifact_id").or_else(|| params.get("symbol_id")).and_then(Value::as_str)
|
||||
.ok_or_else(|| err("mlsp.bad_request", "artifact.bind 需要 artifact_id 或 symbol_id"))?;
|
||||
let candidates = artifact_query(&compilation.semantics, query);
|
||||
if candidates.len() != 1 { return Err(err(if candidates.is_empty() { "artifact.unresolved" } else { "artifact.ambiguous" }, format!("无法唯一绑定 `{query}`"))); }
|
||||
let artifact = candidates[0];
|
||||
let expected = params.get("expected_digest").and_then(Value::as_str);
|
||||
if expected.is_some() && expected != Some(artifact.hashes.artifact.0.as_str()) {
|
||||
return Err(json!({"code":"artifact.digest_mismatch","message":"目标摘要已变化,拒绝绑定","expected":expected,"actual":artifact.hashes.artifact.0}));
|
||||
}
|
||||
Ok(json!({"schema_version":1,"handle":{"artifact_id":artifact.artifact_id.0,"digest":artifact.hashes.artifact.0,"project":compilation.semantics.root,"policy":params.get("policy").cloned().unwrap_or_else(||json!("pure")),"effects":artifact.effects.values()}}))
|
||||
}
|
||||
|
||||
fn artifact_execute(params: &Value) -> Result<Value, Value> {
|
||||
let handle = params.get("handle").ok_or_else(|| err("mlsp.bad_request", "artifact.execute 需要 artifact.bind 返回的 handle"))?;
|
||||
let artifact_id = handle.get("artifact_id").and_then(Value::as_str).ok_or_else(|| err("mlsp.bad_handle", "handle 缺少 artifact_id"))?;
|
||||
let digest = handle.get("digest").and_then(Value::as_str).ok_or_else(|| err("mlsp.bad_handle", "handle 缺少 digest"))?;
|
||||
let project_path = handle.get("project").and_then(Value::as_str).or_else(|| params.get("project").and_then(Value::as_str)).ok_or_else(|| err("mlsp.bad_handle", "handle 缺少 project"))?;
|
||||
let compilation = semantic_project(&json!({"project":project_path}))?;
|
||||
let candidates = artifact_query(&compilation.semantics, artifact_id);
|
||||
if candidates.len() != 1 { return Err(err("artifact.stale_handle", "制品不再可唯一解析;请重新 bind")); }
|
||||
let artifact = candidates[0];
|
||||
if artifact.hashes.artifact.0 != digest { return Err(json!({"code":"artifact.stale_handle","message":"源码或契约已改变;拒绝执行过期 handle","expected":digest,"actual":artifact.hashes.artifact.0})); }
|
||||
if artifact.kind != "function" || artifact.callable.as_deref() == Some("instance_method") { return Err(err("artifact.not_executable", "只有非实例函数制品可由 artifact.execute 直接执行")); }
|
||||
let allowed: Vec<&str> = params.get("allow_effects").and_then(Value::as_array).map(|items| items.iter().filter_map(Value::as_str).collect()).unwrap_or_default();
|
||||
let denied: Vec<String> = artifact.effects.values().into_iter().filter(|effect| effect != "pure" && !allowed.contains(&effect.as_str())).collect();
|
||||
if !denied.is_empty() { return Err(json!({"code":"artifact.effect_denied","message":"效果策略拒绝执行","denied":denied,"effects":artifact.effects.values()})); }
|
||||
let path = compilation.semantics.root.join(&artifact.source.file);
|
||||
let module = load::load_module(&path).map_err(|e| diagnostic_err("artifact.load", &e))?;
|
||||
let input = params.get("inputs").cloned().unwrap_or_else(|| json!({}));
|
||||
let object = input.as_object().ok_or_else(|| err("mlsp.bad_request", "inputs 必须是 JSON 对象"))?;
|
||||
let mut args = Vec::new();
|
||||
for (name, value) in object { args.push((name.clone(), crate::host::json::json_to_value(value).map_err(|e| err("mlsp.bad_input", e))?)); }
|
||||
let caps = crate::host::HostCaps { fs_write: allowed.contains(&"fs.write"), exec: allowed.iter().any(|e| matches!(*e, "process.exec" | "plugin.call" | "llm.call")), net: allowed.iter().any(|e| matches!(*e, "network.read" | "network.write" | "llm.call")), plugin: allowed.contains(&"plugin.call") };
|
||||
let host = crate::host::HostContext::for_capture(Some(&path), caps);
|
||||
let mut interpreter = crate::interp::Interpreter::with_capture(Some(&path), false).with_host(host);
|
||||
let name = artifact.display_name.rsplit('.').next().unwrap_or(&artifact.display_name);
|
||||
let value = interpreter.invoke_function(&module, name, &args).map_err(|e| diagnostic_err("artifact.execution_failed", &e))?;
|
||||
let stdout = std::mem::take(&mut interpreter.captured_stdout);
|
||||
Ok(json!({"schema_version":1,"artifact_id":artifact.artifact_id.0,"digest":digest,"result":crate::value_as_json(&value).map_err(|e|err("artifact.serialization",e))?,"stdout":stdout,"effects":artifact.effects.values()}))
|
||||
}
|
||||
|
||||
fn err(code: &str, message: impl Into<String>) -> Value {
|
||||
json!({"code": code, "message": message.into()})
|
||||
}
|
||||
@@ -500,3 +635,40 @@ fn contract_json(c: &Contract, path: Option<&Path>) -> Value {
|
||||
"doc_anchor": c.anchor(path),
|
||||
})
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::fs;
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
|
||||
fn fixture() -> PathBuf {
|
||||
let stamp = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos();
|
||||
let root = std::env::temp_dir().join(format!("marqdo-mlsp-artifact-{stamp}"));
|
||||
fs::create_dir_all(&root).unwrap();
|
||||
fs::write(root.join("main.mq.md"), "# main\n\n## add\n\n*`x` + 1*").unwrap();
|
||||
root
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn artifact_protocol_binds_then_executes_a_digest_checked_function() {
|
||||
let root = fixture();
|
||||
let project = root.display().to_string();
|
||||
let found = dispatch(&json!({"method":"artifact.find","params":{"project":project,"query":"add"}})).unwrap();
|
||||
let candidate = found["candidates"].as_array().unwrap().iter().find(|v| v["kind"] == "function").unwrap();
|
||||
let id = candidate["artifact_id"].as_str().unwrap();
|
||||
let bound = dispatch(&json!({"method":"artifact.bind","params":{"project":root,"artifact_id":id}})).unwrap();
|
||||
let handle = bound["handle"].clone();
|
||||
let result = dispatch(&json!({"method":"artifact.execute","params":{"handle":handle,"inputs":{"x":4}}})).unwrap();
|
||||
assert_eq!(result["result"], 5);
|
||||
fs::remove_dir_all(root).unwrap();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn link_resolution_never_silently_selects_a_nonexistent_target() {
|
||||
let root = fixture();
|
||||
let result = dispatch(&json!({"method":"link.resolve","params":{"project":root,"payload":"does_not_exist"}})).unwrap();
|
||||
assert_eq!(result["resolution"], "unresolved");
|
||||
fs::remove_dir_all(root).unwrap();
|
||||
}
|
||||
}
|
||||
+597
@@ -0,0 +1,597 @@
|
||||
//! Versioned semantic artifacts for executable knowledge.
|
||||
//!
|
||||
//! This is deliberately a *projection* of the existing syntax AST. It gives
|
||||
//! every consumer one deterministic place to obtain identity, contracts,
|
||||
//! effects, provenance and hashes without changing the classic runtime AST.
|
||||
|
||||
use std::collections::{BTreeMap, BTreeSet};
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use anyhow::{Context, Result};
|
||||
use serde_json::{json, Value};
|
||||
use sha2::{Digest as _, Sha256};
|
||||
|
||||
use crate::ast::{Arg, CallExpr, Expr, Function, Stmt};
|
||||
use crate::contract::Ty;
|
||||
use crate::diagnostics::{Diagnostic, Severity, Span};
|
||||
use crate::project::ProjectRoot;
|
||||
|
||||
use super::{CallableKind, ModuleId, ProjectIndex, SymbolDecl, SymbolId, SymbolKind};
|
||||
|
||||
pub const SCHEMA_VERSION: u32 = 1;
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
|
||||
pub struct ArtifactId(pub String);
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
|
||||
pub struct Digest(pub String);
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum LockMode {
|
||||
Off,
|
||||
Check,
|
||||
Strict,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CompileOptions {
|
||||
pub project_root: PathBuf,
|
||||
pub entry: Option<PathBuf>,
|
||||
pub lock_mode: LockMode,
|
||||
}
|
||||
|
||||
impl CompileOptions {
|
||||
pub fn for_path(path: &Path) -> Result<Self> {
|
||||
let project = if path.is_dir() {
|
||||
ProjectRoot::new(path)?
|
||||
} else {
|
||||
ProjectRoot::discover(path)?
|
||||
};
|
||||
Ok(Self {
|
||||
project_root: project.path().to_path_buf(),
|
||||
entry: path.is_file().then(|| path.to_path_buf()),
|
||||
lock_mode: LockMode::Off,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Default, PartialEq, Eq)]
|
||||
pub struct EffectSet(BTreeSet<String>);
|
||||
|
||||
impl EffectSet {
|
||||
pub fn pure() -> Self {
|
||||
Self(BTreeSet::from(["pure".to_string()]))
|
||||
}
|
||||
|
||||
pub fn add(&mut self, effect: impl Into<String>) {
|
||||
let effect = effect.into();
|
||||
if effect != "pure" {
|
||||
self.0.remove("pure");
|
||||
}
|
||||
self.0.insert(effect);
|
||||
}
|
||||
|
||||
pub fn extend(&mut self, other: &Self) {
|
||||
for effect in &other.0 {
|
||||
self.add(effect.clone());
|
||||
}
|
||||
}
|
||||
|
||||
pub fn is_pure(&self) -> bool {
|
||||
self.0.len() == 1 && self.0.contains("pure")
|
||||
}
|
||||
|
||||
pub fn values(&self) -> Vec<String> {
|
||||
self.0.iter().cloned().collect()
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct SourceLocation {
|
||||
pub file: String,
|
||||
pub line: u32,
|
||||
pub end_line: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CanonicalParam {
|
||||
pub name: String,
|
||||
pub ty: String,
|
||||
pub required: bool,
|
||||
pub default_digest: Option<Digest>,
|
||||
pub unit: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CanonicalSignature {
|
||||
pub receiver: String,
|
||||
pub params: Vec<CanonicalParam>,
|
||||
pub returns: String,
|
||||
pub effects: EffectSet,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ContractSet {
|
||||
pub params: Vec<String>,
|
||||
pub returns: Option<String>,
|
||||
pub fields: Vec<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct SourceRef {
|
||||
pub uri: String,
|
||||
pub locator: Option<String>,
|
||||
pub content_digest: Option<Digest>,
|
||||
pub relation: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct VerificationRecord {
|
||||
pub parse: String,
|
||||
pub resolve: String,
|
||||
pub contract: String,
|
||||
pub execution: String,
|
||||
pub tests: String,
|
||||
pub evidence: String,
|
||||
pub domain: String,
|
||||
pub methods: Vec<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ArtifactHashes {
|
||||
pub interface: Digest,
|
||||
pub implementation: Digest,
|
||||
pub evidence: Digest,
|
||||
pub artifact: Digest,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct SemanticArtifact {
|
||||
pub artifact_id: ArtifactId,
|
||||
pub symbol_id: Option<SymbolId>,
|
||||
pub display_name: String,
|
||||
pub kind: String,
|
||||
pub callable: Option<String>,
|
||||
pub source: SourceLocation,
|
||||
pub signature: Option<CanonicalSignature>,
|
||||
pub contract: ContractSet,
|
||||
pub effects: EffectSet,
|
||||
pub dependencies: Vec<ArtifactId>,
|
||||
pub provenance: Vec<SourceRef>,
|
||||
pub applicability: String,
|
||||
pub hashes: ArtifactHashes,
|
||||
pub verification: VerificationRecord,
|
||||
pub lifecycle: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct KnowledgeRef {
|
||||
pub id: String,
|
||||
pub label: String,
|
||||
pub context: String,
|
||||
pub source: SourceLocation,
|
||||
pub resolution: String,
|
||||
pub target: Option<SymbolId>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct KnowledgeStep {
|
||||
pub id: ArtifactId,
|
||||
pub reference: String,
|
||||
pub kind: String,
|
||||
pub calls: Vec<SymbolId>,
|
||||
pub effects: EffectSet,
|
||||
pub source: SourceLocation,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct SemanticProject {
|
||||
pub schema_version: u32,
|
||||
pub project_id: String,
|
||||
pub root: PathBuf,
|
||||
pub artifacts: Vec<SemanticArtifact>,
|
||||
pub refs: Vec<KnowledgeRef>,
|
||||
pub steps: Vec<KnowledgeStep>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Compilation {
|
||||
pub index: ProjectIndex,
|
||||
pub semantics: SemanticProject,
|
||||
pub diagnostics: Vec<Diagnostic>,
|
||||
}
|
||||
|
||||
/// Compile every project source once into stable semantic facts. This is
|
||||
/// side-effect free: it never loads plugins, evaluates expressions or fetches
|
||||
/// sources.
|
||||
pub fn compile_project(options: &CompileOptions) -> Result<Compilation> {
|
||||
let root = ProjectRoot::new(&options.project_root)?;
|
||||
let index = ProjectIndex::build(root.clone())?;
|
||||
let mut files = BTreeMap::new();
|
||||
let mut diagnostics = Vec::new();
|
||||
for file in root.source_files()? {
|
||||
let text = fs::read_to_string(&file)
|
||||
.with_context(|| format!("read semantic source {}", file.display()))?;
|
||||
match crate::load::parse_source_auto(&text) {
|
||||
Ok(module) => {
|
||||
let module_id = index
|
||||
.modules()
|
||||
.iter()
|
||||
.find_map(|(id, path)| (path == &file).then(|| id.clone()));
|
||||
if let Some(module_id) = module_id {
|
||||
files.insert(module_id, (file, text, module));
|
||||
}
|
||||
}
|
||||
Err(error) => {
|
||||
diagnostics.push(
|
||||
Diagnostic::new(Some(&file), Span::new(1, 1), error.to_string())
|
||||
.with_code("parse.semantic")
|
||||
.with_severity(Severity::Error),
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let project_id = index.project_id().to_string();
|
||||
let mut artifacts = Vec::new();
|
||||
let mut refs = Vec::new();
|
||||
let mut steps = Vec::new();
|
||||
let mut local_by_name: BTreeMap<(ModuleId, String), SymbolId> = BTreeMap::new();
|
||||
for symbol in index.symbols() {
|
||||
local_by_name.insert((symbol.module.clone(), symbol.name.clone()), symbol.id.clone());
|
||||
}
|
||||
|
||||
for (module_id, (path, text, module)) in &files {
|
||||
artifacts.push(module_artifact(&index, module_id, path, text));
|
||||
let mut by_path = BTreeMap::new();
|
||||
collect_functions(&module.functions, &mut Vec::new(), &mut by_path);
|
||||
for symbol in index.symbols().iter().filter(|s| &s.module == module_id) {
|
||||
let function = by_path.get(&symbol.declaration_path).expect("symbol collected from module");
|
||||
let (artifact, mut artifact_refs, mut artifact_steps) = artifact_for_function(
|
||||
&index,
|
||||
module_id,
|
||||
path,
|
||||
function,
|
||||
symbol,
|
||||
&local_by_name,
|
||||
);
|
||||
refs.append(&mut artifact_refs);
|
||||
steps.append(&mut artifact_steps);
|
||||
artifacts.push(artifact);
|
||||
}
|
||||
}
|
||||
artifacts.sort_by(|a, b| a.artifact_id.0.cmp(&b.artifact_id.0));
|
||||
refs.sort_by(|a, b| a.id.cmp(&b.id));
|
||||
steps.sort_by(|a, b| a.id.0.cmp(&b.id.0));
|
||||
Ok(Compilation {
|
||||
index,
|
||||
semantics: SemanticProject {
|
||||
schema_version: SCHEMA_VERSION,
|
||||
project_id,
|
||||
root: root.path().to_path_buf(),
|
||||
artifacts,
|
||||
refs,
|
||||
steps,
|
||||
},
|
||||
diagnostics,
|
||||
})
|
||||
}
|
||||
|
||||
fn module_artifact(index: &ProjectIndex, module: &ModuleId, path: &Path, text: &str) -> SemanticArtifact {
|
||||
let implementation = digest(normalize_source(text));
|
||||
let interface = digest(module.as_str());
|
||||
let evidence = digest("");
|
||||
let artifact_id = ArtifactId(format!("mq://{}/{}/module", percent(index.project_id()), percent(module.as_str())));
|
||||
semantic_artifact(
|
||||
artifact_id,
|
||||
None,
|
||||
module.as_str().to_string(),
|
||||
"module".to_string(),
|
||||
None,
|
||||
source_location(index.root().path(), path, 1, text.lines().count() as u32),
|
||||
None,
|
||||
ContractSet { params: vec![], returns: None, fields: vec![] },
|
||||
EffectSet::pure(),
|
||||
vec![],
|
||||
vec![SourceRef { uri: rel_uri(index.root().path(), path), locator: None, content_digest: Some(implementation.clone()), relation: "defines".into() }],
|
||||
"project-local module".into(),
|
||||
interface,
|
||||
implementation,
|
||||
evidence,
|
||||
)
|
||||
}
|
||||
|
||||
fn artifact_for_function(
|
||||
index: &ProjectIndex,
|
||||
module: &ModuleId,
|
||||
path: &Path,
|
||||
function: &Function,
|
||||
symbol: &SymbolDecl,
|
||||
local_by_name: &BTreeMap<(ModuleId, String), SymbolId>,
|
||||
) -> (SemanticArtifact, Vec<KnowledgeRef>, Vec<KnowledgeStep>) {
|
||||
let calls = collect_call_sites(function);
|
||||
let mut effects = direct_effects(&calls);
|
||||
let mut dependencies = Vec::new();
|
||||
let mut refs = Vec::new();
|
||||
let mut steps = Vec::new();
|
||||
for (n, (_, call, line)) in calls.iter().enumerate() {
|
||||
let target = resolve_local_call(module, call, local_by_name);
|
||||
if let Some(target) = &target {
|
||||
dependencies.push(ArtifactId(target.as_str().to_string()));
|
||||
}
|
||||
let ref_id = format!("{}#ref-{}", symbol.id.as_str(), n + 1);
|
||||
refs.push(KnowledgeRef {
|
||||
id: ref_id.clone(),
|
||||
label: call_name(call),
|
||||
context: "executable".into(),
|
||||
source: source_location(index.root().path(), path, *line, *line),
|
||||
resolution: target.as_ref().map(|_| "symbol".to_string()).unwrap_or_else(|| "external_or_dynamic".to_string()),
|
||||
target: target.clone(),
|
||||
});
|
||||
steps.push(KnowledgeStep {
|
||||
id: ArtifactId(format!("{}#step-{}", symbol.id.as_str(), n + 1)),
|
||||
reference: ref_id,
|
||||
kind: "call".into(),
|
||||
calls: target.into_iter().collect(),
|
||||
effects: effects_for_call(call),
|
||||
source: source_location(index.root().path(), path, *line, *line),
|
||||
});
|
||||
}
|
||||
if effects.0.is_empty() {
|
||||
effects = EffectSet::pure();
|
||||
}
|
||||
let (signature, contract) = signature(function, symbol.callable, &effects);
|
||||
let interface = digest(signature_json(signature.as_ref()));
|
||||
let implementation = digest(format!("{:?}", function.body));
|
||||
let provenance = vec![SourceRef {
|
||||
uri: rel_uri(index.root().path(), path),
|
||||
locator: Some(format!("L{}", function.span.line)),
|
||||
content_digest: Some(implementation.clone()),
|
||||
relation: "defines".into(),
|
||||
}];
|
||||
let evidence = digest(contract_summary(&contract));
|
||||
let kind = match symbol.kind {
|
||||
SymbolKind::Type => "type",
|
||||
SymbolKind::Function => "function",
|
||||
}.to_string();
|
||||
let artifact = semantic_artifact(
|
||||
ArtifactId(symbol.id.as_str().to_string()),
|
||||
Some(symbol.id.clone()),
|
||||
symbol.declaration_path.join("."),
|
||||
kind,
|
||||
symbol.callable.map(|kind| kind.as_str().to_string()),
|
||||
source_location(index.root().path(), path, function.span.line, function.span.line),
|
||||
signature,
|
||||
contract,
|
||||
effects,
|
||||
dependencies,
|
||||
provenance,
|
||||
"no explicit applicability constraints".into(),
|
||||
interface,
|
||||
implementation,
|
||||
evidence,
|
||||
);
|
||||
(artifact, refs, steps)
|
||||
}
|
||||
|
||||
#[allow(clippy::too_many_arguments)]
|
||||
fn semantic_artifact(
|
||||
artifact_id: ArtifactId, symbol_id: Option<SymbolId>, display_name: String, kind: String,
|
||||
callable: Option<String>, source: SourceLocation, signature: Option<CanonicalSignature>,
|
||||
contract: ContractSet, effects: EffectSet, mut dependencies: Vec<ArtifactId>,
|
||||
provenance: Vec<SourceRef>, applicability: String, interface: Digest, implementation: Digest,
|
||||
evidence: Digest,
|
||||
) -> SemanticArtifact {
|
||||
dependencies.sort_by(|a, b| a.0.cmp(&b.0));
|
||||
dependencies.dedup();
|
||||
let artifact = digest(format!("{}:{}:{}", interface.0, implementation.0, evidence.0));
|
||||
SemanticArtifact {
|
||||
artifact_id, symbol_id, display_name, kind, callable, source, signature, contract,
|
||||
effects, dependencies, provenance, applicability, hashes: ArtifactHashes {
|
||||
interface, implementation, evidence, artifact,
|
||||
},
|
||||
verification: VerificationRecord {
|
||||
parse: "passed".into(), resolve: "passed".into(), contract: "unchecked".into(),
|
||||
execution: "not_run".into(), tests: "unknown".into(), evidence: "unverified".into(),
|
||||
domain: "unreviewed".into(), methods: vec!["static_project_compile".into()],
|
||||
},
|
||||
lifecycle: "draft".into(),
|
||||
}
|
||||
}
|
||||
|
||||
fn signature(function: &Function, callable: Option<CallableKind>, effects: &EffectSet) -> (Option<CanonicalSignature>, ContractSet) {
|
||||
if function.is_object() {
|
||||
let fields = function.contract.as_ref().map(|c| c.fields.iter().map(|f| format!("{}:{}", f.name, ty_name(&f.ty))).collect()).unwrap_or_default();
|
||||
return (None, ContractSet { params: vec![], returns: None, fields });
|
||||
}
|
||||
let contract = function.contract.as_ref();
|
||||
let params = function.params.iter().map(|param| {
|
||||
let cp = contract.and_then(|c| c.params.iter().find(|item| item.name == param.name));
|
||||
CanonicalParam {
|
||||
name: param.name.clone(), ty: cp.map(|p| ty_name(&p.ty)).unwrap_or_else(|| "any".into()),
|
||||
required: param.default.is_none(), default_digest: param.default.as_ref().map(|value| digest(format!("{:?}", value))), unit: None,
|
||||
}
|
||||
}).collect::<Vec<_>>();
|
||||
let set = ContractSet {
|
||||
params: contract.map(|c| c.params.iter().map(|p| format!("{}:{}", p.name, ty_name(&p.ty))).collect()).unwrap_or_default(),
|
||||
returns: contract.and_then(|c| c.returns.as_ref().map(|r| ty_name(&r.ty))),
|
||||
fields: contract.map(|c| c.fields.iter().map(|f| format!("{}:{}", f.name, ty_name(&f.ty))).collect()).unwrap_or_default(),
|
||||
};
|
||||
let receiver = match callable {
|
||||
Some(CallableKind::InstanceMethod) => "instance",
|
||||
Some(CallableKind::AssociatedFunction) => "none",
|
||||
_ => "none",
|
||||
}.to_string();
|
||||
(Some(CanonicalSignature {
|
||||
receiver, params, returns: set.returns.clone().unwrap_or_else(|| "any".into()), effects: effects.clone(),
|
||||
}), set)
|
||||
}
|
||||
|
||||
fn ty_name(ty: &Ty) -> String { ty.name() }
|
||||
|
||||
fn collect_functions<'a>(functions: &'a [Function], path: &mut Vec<String>, out: &mut BTreeMap<Vec<String>, &'a Function>) {
|
||||
for function in functions {
|
||||
path.push(function.name.clone());
|
||||
out.insert(path.clone(), function);
|
||||
collect_functions(&function.children, path, out);
|
||||
path.pop();
|
||||
}
|
||||
}
|
||||
|
||||
fn collect_call_sites(function: &Function) -> Vec<(usize, CallExpr, u32)> {
|
||||
let mut calls = Vec::new();
|
||||
fn expr(value: &Expr, line: u32, calls: &mut Vec<(usize, CallExpr, u32)>) {
|
||||
match value {
|
||||
Expr::Call(call) => {
|
||||
calls.push((calls.len(), call.clone(), line));
|
||||
for arg in &call.args { match arg { Arg::Positional(value) | Arg::Named { value, .. } => expr(value, line, calls) } }
|
||||
}
|
||||
Expr::Unary { expr: value, .. } => expr(value, line, calls),
|
||||
Expr::Binary { left, right, .. } => { expr(left, line, calls); expr(right, line, calls); }
|
||||
Expr::List(items) => for item in items { expr(item, line, calls); },
|
||||
Expr::Map(items) => for (_, item) in items { expr(item, line, calls); },
|
||||
Expr::Index { base, .. } => expr(base, line, calls),
|
||||
Expr::Occluded { payload: Some(payload), .. } => expr(payload, line, calls),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
fn statements(items: &[Stmt], calls: &mut Vec<(usize, CallExpr, u32)>) {
|
||||
for item in items {
|
||||
match item {
|
||||
Stmt::Call { call, span } => { calls.push((calls.len(), call.clone(), span.line)); for arg in &call.args { match arg { Arg::Positional(value) | Arg::Named { value, .. } => expr(value, span.line, calls) } } }
|
||||
Stmt::Assign { value, span, .. } | Stmt::Return { value, span } | Stmt::Expr { value, span } => expr(value, span.line, calls),
|
||||
Stmt::Branch { arms, .. } => for arm in arms { if let Some(condition) = &arm.condition { expr(condition, 0, calls) }; statements(&arm.body, calls); },
|
||||
Stmt::While { condition, body, .. } => { expr(condition, 0, calls); statements(body, calls); }
|
||||
Stmt::ForEach { body, .. } => statements(body, calls),
|
||||
}
|
||||
}
|
||||
}
|
||||
statements(&function.body, &mut calls);
|
||||
calls
|
||||
}
|
||||
|
||||
fn call_name(call: &CallExpr) -> String {
|
||||
call.path.as_ref().map(|path| path.join(".")).or_else(|| call.receiver.as_ref().map(|receiver| format!("{receiver}.{}", call.callee))).unwrap_or_else(|| call.callee.clone())
|
||||
}
|
||||
|
||||
fn resolve_local_call(module: &ModuleId, call: &CallExpr, symbols: &BTreeMap<(ModuleId, String), SymbolId>) -> Option<SymbolId> {
|
||||
if call.path.is_none() && call.receiver.is_none() { symbols.get(&(module.clone(), call.callee.clone())).cloned() } else { None }
|
||||
}
|
||||
|
||||
fn effects_for_call(call: &CallExpr) -> EffectSet {
|
||||
let name = call_name(call).to_ascii_lowercase();
|
||||
let mut effects = EffectSet::default();
|
||||
let effect = if name.starts_with("fs.") || name.contains("writeback") { if name.contains("write") || name.contains("remove") || name.contains("move") || name.contains("mkdir") { "fs.write" } else { "fs.read" } }
|
||||
else if name.starts_with("http.") || name.starts_with("net.") { if name.contains("post") || name.contains("put") || name.contains("delete") { "network.write" } else { "network.read" } }
|
||||
else if name.starts_with("foreign.") || name.starts_with("subtask.") || name == "exec" { "process.exec" }
|
||||
else if name.starts_with("plugin.") { "plugin.call" }
|
||||
else if name.starts_with("llm.") || name.starts_with("openai.") { "llm.call" }
|
||||
else if name.starts_with("time.") || name.starts_with("datetime.") { "time.read" }
|
||||
else if name.starts_with("random.") || name.starts_with("uuid.") { "random.read" }
|
||||
else if name.starts_with("input") { "user.input" }
|
||||
else if name.starts_with("print") || name.starts_with("log.") { "output.write" }
|
||||
else { return EffectSet::pure() };
|
||||
effects.add(effect);
|
||||
effects
|
||||
}
|
||||
|
||||
fn direct_effects(calls: &[(usize, CallExpr, u32)]) -> EffectSet {
|
||||
let mut effects = EffectSet::default();
|
||||
for (_, call, _) in calls { effects.extend(&effects_for_call(call)); }
|
||||
effects
|
||||
}
|
||||
|
||||
fn source_location(root: &Path, path: &Path, line: u32, end_line: u32) -> SourceLocation {
|
||||
SourceLocation { file: rel_uri(root, path), line, end_line }
|
||||
}
|
||||
|
||||
fn rel_uri(root: &Path, path: &Path) -> String { path.strip_prefix(root).unwrap_or(path).to_string_lossy().replace('\\', "/") }
|
||||
fn digest(value: impl AsRef<[u8]>) -> Digest { let mut hash = Sha256::new(); hash.update(value.as_ref()); Digest(format!("sha256:{:x}", hash.finalize())) }
|
||||
fn normalize_source(source: &str) -> String { source.lines().map(str::trim).filter(|line| !line.is_empty()).collect::<Vec<_>>().join("\n") }
|
||||
fn percent(value: &str) -> String { value.bytes().map(|byte| match byte { b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' => (byte as char).to_string(), _ => format!("%{byte:02X}") }).collect() }
|
||||
fn contract_summary(contract: &ContractSet) -> String { format!("{}|{:?}|{}", contract.params.join(","), contract.returns, contract.fields.join(",")) }
|
||||
|
||||
fn signature_json(signature: Option<&CanonicalSignature>) -> String {
|
||||
match signature { Some(signature) => format!("{}|{}|{}|{}", signature.receiver, signature.params.iter().map(|p| format!("{}:{}:{}", p.name, p.ty, p.required)).collect::<Vec<_>>().join(","), signature.returns, signature.effects.values().join(",")), None => "type".into() }
|
||||
}
|
||||
|
||||
impl SemanticProject {
|
||||
pub fn to_json(&self) -> Value {
|
||||
json!({
|
||||
"schema_version": self.schema_version, "project": {"id": self.project_id, "root": self.root},
|
||||
"artifacts": self.artifacts.iter().map(artifact_json).collect::<Vec<_>>(),
|
||||
"refs": self.refs.iter().map(ref_json).collect::<Vec<_>>(),
|
||||
"steps": self.steps.iter().map(step_json).collect::<Vec<_>>(),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
pub fn artifact_json(artifact: &SemanticArtifact) -> Value {
|
||||
json!({"schema_version": SCHEMA_VERSION, "artifact_id": artifact.artifact_id.0, "symbol_id": artifact.symbol_id.as_ref().map(SymbolId::as_str), "display_name": artifact.display_name, "kind": artifact.kind, "callable": artifact.callable, "source": {"file": artifact.source.file, "line": artifact.source.line, "end_line": artifact.source.end_line}, "signature": artifact.signature.as_ref().map(|s| json!({"receiver":s.receiver,"params":s.params.iter().map(|p|json!({"name":p.name,"type":p.ty,"required":p.required,"default_digest":p.default_digest.as_ref().map(|d|&d.0),"unit":p.unit})).collect::<Vec<_>>(),"returns":s.returns,"effects":s.effects.values()})), "contract":{"params":artifact.contract.params,"returns":artifact.contract.returns,"fields":artifact.contract.fields}, "effects":artifact.effects.values(), "dependencies":artifact.dependencies.iter().map(|d|&d.0).collect::<Vec<_>>(), "provenance":artifact.provenance.iter().map(|p|json!({"uri":p.uri,"locator":p.locator,"content_digest":p.content_digest.as_ref().map(|d|&d.0),"relation":p.relation})).collect::<Vec<_>>(), "applicability":artifact.applicability, "hashes":{"interface":artifact.hashes.interface.0,"implementation":artifact.hashes.implementation.0,"evidence":artifact.hashes.evidence.0,"artifact":artifact.hashes.artifact.0}, "verification":{"parse":artifact.verification.parse,"resolve":artifact.verification.resolve,"contract":artifact.verification.contract,"execution":artifact.verification.execution,"tests":artifact.verification.tests,"evidence":artifact.verification.evidence,"domain":artifact.verification.domain,"methods":artifact.verification.methods}, "lifecycle":artifact.lifecycle})
|
||||
}
|
||||
fn ref_json(reference: &KnowledgeRef) -> Value { json!({"id":reference.id,"label":reference.label,"context":reference.context,"source":{"file":reference.source.file,"line":reference.source.line,"end_line":reference.source.end_line},"resolution":reference.resolution,"target":reference.target.as_ref().map(SymbolId::as_str)}) }
|
||||
fn step_json(step: &KnowledgeStep) -> Value { json!({"id":step.id.0,"reference":step.reference,"kind":step.kind,"calls":step.calls.iter().map(SymbolId::as_str).collect::<Vec<_>>(),"effects":step.effects.values(),"source":{"file":step.source.file,"line":step.source.line,"end_line":step.source.end_line}}) }
|
||||
|
||||
/// Atomically write the semantic portion of `.marqdo/`. A reader therefore
|
||||
/// sees either the previous graph or the complete next graph, never a mix.
|
||||
pub fn write_semantic_projections(out_dir: &Path, compilation: &Compilation) -> Result<()> {
|
||||
let stage = out_dir.with_extension("tmp-sema");
|
||||
if stage.exists() { fs::remove_dir_all(&stage).with_context(|| format!("clear {}", stage.display()))?; }
|
||||
fs::create_dir_all(stage.join("artifacts"))?;
|
||||
fs::create_dir_all(stage.join("graph"))?;
|
||||
fs::create_dir_all(stage.join("verification"))?;
|
||||
let project = compilation.semantics.to_json();
|
||||
write_json(&stage.join("project.json"), &json!({"schema_version":SCHEMA_VERSION,"project":project["project"],"artifact_count":compilation.semantics.artifacts.len()}))?;
|
||||
write_json(&stage.join("symbols.json"), &json!({"schema_version":SCHEMA_VERSION,"symbols":compilation.index.symbols().iter().map(|s|json!({"id":s.id.as_str(),"module":s.module.as_str(),"kind":s.kind.as_str(),"callable":s.callable.map(|c|c.as_str()),"name":s.name,"declaration_path":s.declaration_path,"source":{"file":rel_uri(compilation.index.root().path(),&s.source),"line":s.line}})).collect::<Vec<_>>() }))?;
|
||||
write_json(&stage.join("refs.json"), &json!({"schema_version":SCHEMA_VERSION,"refs":project["refs"]}))?;
|
||||
write_json(&stage.join("graph/nodes.json"), &json!({"schema_version":SCHEMA_VERSION,"nodes":project["artifacts"]}))?;
|
||||
write_json(&stage.join("graph/edges.json"), &json!({"schema_version":SCHEMA_VERSION,"edges":compilation.semantics.artifacts.iter().flat_map(|a|a.dependencies.iter().map(move |d|json!({"from":a.artifact_id.0,"to":d.0,"kind":"calls"}))).collect::<Vec<_>>() }))?;
|
||||
for artifact in &compilation.semantics.artifacts {
|
||||
let name = hex_name(&artifact.artifact_id.0);
|
||||
write_json(&stage.join("artifacts").join(format!("{name}.json")), &artifact_json(artifact))?;
|
||||
write_json(&stage.join("verification").join(format!("{name}.json")), &artifact_json(artifact)["verification"])?;
|
||||
}
|
||||
if out_dir.exists() {
|
||||
for name in ["project.json", "symbols.json", "refs.json", "artifacts", "graph", "verification"] { let target = out_dir.join(name); if target.exists() { if target.is_dir() { fs::remove_dir_all(&target)?; } else { fs::remove_file(&target)?; } } }
|
||||
} else { fs::create_dir_all(out_dir)?; }
|
||||
for name in ["project.json", "symbols.json", "refs.json", "artifacts", "graph", "verification"] { fs::rename(stage.join(name), out_dir.join(name))?; }
|
||||
fs::remove_dir_all(stage)?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn write_json(path: &Path, value: &Value) -> Result<()> { fs::write(path, serde_json::to_vec_pretty(value)?).with_context(|| format!("write {}", path.display())) }
|
||||
fn hex_name(value: &str) -> String { digest(value).0.trim_start_matches("sha256:").to_string() }
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
|
||||
fn root() -> PathBuf { let id = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos(); let root = std::env::temp_dir().join(format!("marqdo-sema-ir-{id}")); fs::create_dir_all(&root).unwrap(); root }
|
||||
|
||||
#[test]
|
||||
fn compilation_is_deterministic_and_preserves_contract_effects() {
|
||||
let root = root();
|
||||
fs::write(root.join("main.mq.md"), "# main\n\n| 参数 | 类型 |\n| --- | --- |\n| path | text |\n\n## save\n\n> fs.write_text `path` ok\n\n*1*").unwrap();
|
||||
let options = CompileOptions::for_path(&root).unwrap();
|
||||
let first = compile_project(&options).unwrap();
|
||||
let second = compile_project(&options).unwrap();
|
||||
assert_eq!(first.semantics.to_json(), second.semantics.to_json());
|
||||
let save = first.semantics.artifacts.iter().find(|a| a.display_name.ends_with("save")).unwrap();
|
||||
assert!(save.effects.values().contains(&"fs.write".to_string()));
|
||||
assert_eq!(save.hashes.implementation.0, first.semantics.artifacts.iter().find(|a| a.display_name.ends_with("save")).unwrap().hashes.implementation.0);
|
||||
fs::remove_dir_all(root).unwrap();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn semantic_files_have_schema_versions() {
|
||||
let root = root(); fs::write(root.join("a.mq.md"), "# a\n\n*1*").unwrap();
|
||||
let out = root.join(".marqdo"); let compilation = compile_project(&CompileOptions::for_path(&root).unwrap()).unwrap();
|
||||
write_semantic_projections(&out, &compilation).unwrap();
|
||||
let project: Value = serde_json::from_str(&fs::read_to_string(out.join("project.json")).unwrap()).unwrap();
|
||||
assert_eq!(project["schema_version"], SCHEMA_VERSION);
|
||||
assert!(out.join("artifacts").read_dir().unwrap().next().is_some());
|
||||
fs::remove_dir_all(root).unwrap();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,164 @@
|
||||
//! Reviewable semantic link lock and reverse-impact queries.
|
||||
|
||||
use std::collections::{BTreeMap, BTreeSet, VecDeque};
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
|
||||
use anyhow::{Context, Result};
|
||||
use serde_json::{json, Value};
|
||||
|
||||
use super::ir::{SemanticProject, SCHEMA_VERSION};
|
||||
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct LockReport {
|
||||
pub status: String,
|
||||
pub missing: Vec<String>,
|
||||
pub changed: Vec<String>,
|
||||
pub removed: Vec<String>,
|
||||
}
|
||||
|
||||
impl LockReport {
|
||||
pub fn is_clean(&self) -> bool {
|
||||
self.status == "clean"
|
||||
}
|
||||
|
||||
pub fn to_json(&self) -> Value {
|
||||
json!({
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"status": self.status,
|
||||
"missing": self.missing,
|
||||
"changed": self.changed,
|
||||
"removed": self.removed,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
pub fn update_links_lock(out_dir: &Path, project: &SemanticProject) -> Result<()> {
|
||||
fs::create_dir_all(out_dir)?;
|
||||
let target = out_dir.join("links.lock.json");
|
||||
let staged = out_dir.join(".links.lock.json.tmp");
|
||||
fs::write(&staged, serde_json::to_vec_pretty(&lock_json(project))?)
|
||||
.with_context(|| format!("write {}", staged.display()))?;
|
||||
fs::rename(&staged, &target)
|
||||
.with_context(|| format!("replace {}", target.display()))?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn check_links_lock(out_dir: &Path, project: &SemanticProject) -> Result<LockReport> {
|
||||
let path = out_dir.join("links.lock.json");
|
||||
if !path.exists() {
|
||||
return Ok(LockReport {
|
||||
status: "missing".into(),
|
||||
missing: project.artifacts.iter().map(|a| a.artifact_id.0.clone()).collect(),
|
||||
..LockReport::default()
|
||||
});
|
||||
}
|
||||
let raw: Value = serde_json::from_str(&fs::read_to_string(&path)
|
||||
.with_context(|| format!("read {}", path.display()))?)
|
||||
.with_context(|| format!("parse {}", path.display()))?;
|
||||
if raw.get("schema_version").and_then(Value::as_u64) != Some(SCHEMA_VERSION as u64) {
|
||||
return Ok(LockReport {
|
||||
status: "schema_mismatch".into(),
|
||||
changed: vec!["schema_version".into()],
|
||||
..LockReport::default()
|
||||
});
|
||||
}
|
||||
let expected = artifact_lock_map(project);
|
||||
let actual = raw.get("artifacts").and_then(Value::as_object).cloned().unwrap_or_default();
|
||||
let mut report = LockReport::default();
|
||||
for (id, digest) in &expected {
|
||||
match actual.get(id).and_then(Value::as_object) {
|
||||
None => report.missing.push(id.clone()),
|
||||
Some(found) if found.get("artifact").and_then(Value::as_str) != Some(digest.as_str()) => report.changed.push(id.clone()),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
for id in actual.keys() {
|
||||
if !expected.contains_key(id) { report.removed.push(id.clone()); }
|
||||
}
|
||||
report.missing.sort(); report.changed.sort(); report.removed.sort();
|
||||
report.status = if report.missing.is_empty() && report.changed.is_empty() && report.removed.is_empty() { "clean".into() } else { "outdated".into() };
|
||||
Ok(report)
|
||||
}
|
||||
|
||||
/// Static reverse dependency closure. Queries can be an artifact/symbol URI,
|
||||
/// a declaration suffix, or a project-relative source filename.
|
||||
pub fn impact(project: &SemanticProject, query: &str) -> Value {
|
||||
let mut seeds = BTreeSet::new();
|
||||
for artifact in &project.artifacts {
|
||||
if artifact.artifact_id.0 == query
|
||||
|| artifact.symbol_id.as_ref().is_some_and(|id| id.as_str() == query)
|
||||
|| artifact.display_name == query
|
||||
|| artifact.source.file == query
|
||||
|| artifact.artifact_id.0.ends_with(query)
|
||||
{
|
||||
seeds.insert(artifact.artifact_id.0.clone());
|
||||
}
|
||||
}
|
||||
let mut reverse: BTreeMap<String, Vec<String>> = BTreeMap::new();
|
||||
for artifact in &project.artifacts {
|
||||
for dependency in &artifact.dependencies {
|
||||
reverse.entry(dependency.0.clone()).or_default().push(artifact.artifact_id.0.clone());
|
||||
}
|
||||
}
|
||||
let mut queue: VecDeque<String> = seeds.iter().cloned().collect();
|
||||
let mut affected = BTreeSet::new();
|
||||
while let Some(current) = queue.pop_front() {
|
||||
if !affected.insert(current.clone()) { continue; }
|
||||
if let Some(users) = reverse.get(¤t) {
|
||||
for user in users { queue.push_back(user.clone()); }
|
||||
}
|
||||
}
|
||||
let entries = affected.iter().filter_map(|id| project.artifacts.iter().find(|a| &a.artifact_id.0 == id)).map(|artifact| json!({
|
||||
"artifact_id": artifact.artifact_id.0,
|
||||
"symbol_id": artifact.symbol_id.as_ref().map(|id| id.as_str()),
|
||||
"display_name": artifact.display_name,
|
||||
"kind": artifact.kind,
|
||||
"source": {"file": artifact.source.file, "line": artifact.source.line},
|
||||
})).collect::<Vec<_>>();
|
||||
json!({"schema_version":SCHEMA_VERSION,"query":query,"resolved":!seeds.is_empty(),"seeds":seeds,"affected":entries})
|
||||
}
|
||||
|
||||
fn artifact_lock_map(project: &SemanticProject) -> BTreeMap<String, String> {
|
||||
project.artifacts.iter().map(|artifact| (artifact.artifact_id.0.clone(), artifact.hashes.artifact.0.clone())).collect()
|
||||
}
|
||||
|
||||
fn lock_json(project: &SemanticProject) -> Value {
|
||||
let mut artifacts = serde_json::Map::new();
|
||||
for artifact in &project.artifacts {
|
||||
artifacts.insert(artifact.artifact_id.0.clone(), json!({
|
||||
"interface": artifact.hashes.interface.0,
|
||||
"implementation": artifact.hashes.implementation.0,
|
||||
"evidence": artifact.hashes.evidence.0,
|
||||
"artifact": artifact.hashes.artifact.0,
|
||||
"dependencies": artifact.dependencies.iter().map(|item| &item.0).collect::<Vec<_>>(),
|
||||
}));
|
||||
}
|
||||
json!({"schema_version":SCHEMA_VERSION,"project":project.project_id,"artifacts":artifacts})
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::sema::{compile_project, CompileOptions};
|
||||
use std::path::PathBuf;
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
|
||||
fn root() -> PathBuf { let id = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos(); let path = std::env::temp_dir().join(format!("marqdo-lock-{id}")); fs::create_dir_all(&path).unwrap(); path }
|
||||
|
||||
#[test]
|
||||
fn lock_detects_semantic_change_and_impact_is_reverse_closed() {
|
||||
let root = root();
|
||||
fs::write(root.join("main.mq.md"), "# add\n\n*1*\n\n# use\n\n*add()*").unwrap();
|
||||
let options = CompileOptions::for_path(&root).unwrap();
|
||||
let first = compile_project(&options).unwrap();
|
||||
let out = root.join(".marqdo"); update_links_lock(&out, &first.semantics).unwrap();
|
||||
assert!(check_links_lock(&out, &first.semantics).unwrap().is_clean());
|
||||
let response = impact(&first.semantics, "add");
|
||||
assert!(response["affected"].as_array().unwrap().len() >= 1);
|
||||
fs::write(root.join("main.mq.md"), "# add\n\n*2*\n\n# use\n\n*add()*").unwrap();
|
||||
let second = compile_project(&options).unwrap();
|
||||
assert_eq!(check_links_lock(&out, &second.semantics).unwrap().status, "outdated");
|
||||
fs::remove_dir_all(root).unwrap();
|
||||
}
|
||||
}
|
||||
@@ -4,6 +4,13 @@
|
||||
//! binding facts so runtime, EKC, view, and agents do not independently infer
|
||||
//! the meaning of the same source text.
|
||||
|
||||
pub mod ir;
|
||||
pub mod lock;
|
||||
pub mod symbols;
|
||||
|
||||
pub use ir::{
|
||||
artifact_json, compile_project, write_semantic_projections, ArtifactId, CompileOptions, Compilation,
|
||||
Digest, EffectSet, LockMode, SemanticArtifact, SemanticProject,
|
||||
};
|
||||
pub use lock::{check_links_lock, impact as semantic_impact, update_links_lock, LockReport};
|
||||
pub use symbols::{CallableKind, ModuleId, ProjectIndex, SymbolDecl, SymbolId, SymbolKind};
|
||||
@@ -4229,6 +4229,7 @@ window.MARQDO_AUTO_STREAM = {auto_stream};
|
||||
<h1 class="page">{title}<span class="status-pill {status}">{status_label}</span></h1>
|
||||
<p class="meta">{rel}</p>
|
||||
{notebook}
|
||||
{knowledge}
|
||||
<section class="block structure-block">
|
||||
<h2>Structure</h2>
|
||||
{structure_block}
|
||||
@@ -4259,6 +4260,7 @@ window.MARQDO_AUTO_STREAM = {auto_stream};
|
||||
status_label = status_label,
|
||||
rel = escape(rel),
|
||||
notebook = notebook,
|
||||
knowledge = if vm.knowledge_html.is_empty() { String::new() } else { format!("<section class=\"block knowledge-block\"><h2>Executable knowledge</h2>{}</section>", vm.knowledge_html) },
|
||||
exec_clear = exec_clear,
|
||||
structure_block = structure_block,
|
||||
stdin_panel = stdin_panel,
|
||||
|
||||
+7
-1
@@ -32,7 +32,7 @@ use crate::view::html::{escape, page_file, page_index, LinkMode};
|
||||
use crate::view::annot::{build_view_annots, view_execution_report_json};
|
||||
use crate::view::render::{
|
||||
collect_input_prompts, render_bindings_html, render_module_structure,
|
||||
render_module_structure_with_annots, render_right_rail, uses_stream_panel, FileViewModel,
|
||||
render_knowledge_html, render_module_structure_with_annots, render_right_rail, uses_stream_panel, FileViewModel,
|
||||
};
|
||||
use crate::{run_file_capture, RunOptions};
|
||||
|
||||
@@ -478,6 +478,11 @@ pub(crate) fn build_file_view(
|
||||
Some(cap) => view_execution_report_json(rel, ok, cap),
|
||||
None => String::new(),
|
||||
};
|
||||
// Analysis is intentionally independent from capture/run. If a document
|
||||
// has side effects, its facts remain visible while its values stay absent.
|
||||
let knowledge_html = crate::sema::compile_project(&crate::sema::CompileOptions {
|
||||
project_root: root.root.clone(), entry: Some(abs.to_path_buf()), lock_mode: crate::sema::LockMode::Off,
|
||||
}).map(|compilation| render_knowledge_html(&compilation.semantics, rel)).unwrap_or_default();
|
||||
Ok(FileViewModel {
|
||||
rel_path: rel.to_string(),
|
||||
source,
|
||||
@@ -494,6 +499,7 @@ pub(crate) fn build_file_view(
|
||||
plots,
|
||||
bindings_html: std::mem::take(&mut bindings_html),
|
||||
trace_json,
|
||||
knowledge_html,
|
||||
})
|
||||
}
|
||||
|
||||
|
||||
@@ -47,6 +47,32 @@ pub struct FileViewModel {
|
||||
pub bindings_html: String,
|
||||
/// ViewExecutionReport JSON for AI / call-picker (empty if no run).
|
||||
pub trace_json: String,
|
||||
/// Static semantic facts; generated without evaluating the document.
|
||||
pub knowledge_html: String,
|
||||
}
|
||||
|
||||
/// A compact, textual (not colour-only) explanation of executable knowledge.
|
||||
/// View deliberately compiles semantics without running the target, so a page
|
||||
/// can show binding/effect/verification facts even in `--no-exec` exports.
|
||||
pub fn render_knowledge_html(project: &crate::sema::SemanticProject, rel: &str) -> String {
|
||||
let artifacts: Vec<_> = project.artifacts.iter().filter(|artifact| artifact.source.file == rel).collect();
|
||||
if artifacts.is_empty() { return String::new(); }
|
||||
let mut out = String::from(r#"<div class="knowledge-panel" aria-label="Executable knowledge">"#);
|
||||
for artifact in artifacts {
|
||||
let target = artifact.symbol_id.as_ref().map(|id| id.as_str()).unwrap_or(artifact.artifact_id.0.as_str());
|
||||
let signature = artifact.signature.as_ref().map(|sig| {
|
||||
let params = sig.params.iter().map(|param| format!("{}: {}{}", param.name, param.ty, if param.required { "" } else { "?" })).collect::<Vec<_>>().join(", ");
|
||||
format!("({params}) → {}", sig.returns)
|
||||
}).unwrap_or_else(|| "module/type declaration".into());
|
||||
let effects = artifact.effects.values().join(", ");
|
||||
let deps = if artifact.dependencies.is_empty() { "none".to_string() } else { artifact.dependencies.iter().map(|id| id.0.as_str()).collect::<Vec<_>>().join(", ") };
|
||||
out.push_str(&format!(
|
||||
r#"<article class="knowledge-card"><h3>{}</h3><dl><dt>Target</dt><dd><code>{}</code></dd><dt>Kind</dt><dd>{}{}</dd><dt>Signature</dt><dd><code>{}</code></dd><dt>Effects</dt><dd>{}</dd><dt>Verification</dt><dd>parse: {}; resolve: {}; contract: {}; tests: {}; evidence: {}</dd><dt>Lock digest</dt><dd><code>{}</code></dd><dt>Depends on</dt><dd><code>{}</code></dd><dt>Execution</dt><dd>Not executed by knowledge preview.</dd></dl></article>"#,
|
||||
escape(&artifact.display_name), escape(target), escape(&artifact.kind), artifact.callable.as_ref().map(|callable| format!(" ({})", escape(callable))).unwrap_or_default(), escape(&signature), escape(&effects), escape(&artifact.verification.parse), escape(&artifact.verification.resolve), escape(&artifact.verification.contract), escape(&artifact.verification.tests), escape(&artifact.verification.evidence), escape(&artifact.hashes.artifact.0), escape(&deps),
|
||||
));
|
||||
}
|
||||
out.push_str("</div>");
|
||||
out
|
||||
}
|
||||
|
||||
/// Collect prompt strings from every `input` / `输入` call in the module (pre-order).
|
||||
|
||||
Reference in new issue
Block a user