From eac9b45263440aedb8775f9d2d2f6f6a91c57a3c Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 23 Oct 2026 09:16:52 +0000 Subject: [PATCH] feat: compile executable knowledge semantic artifacts --- src/knowledge/compile.rs | 14 + src/main.rs | 43 +++ src/mlsp.rs | 174 +++++++++++- src/sema/ir.rs | 597 +++++++++++++++++++++++++++++++++++++++ src/sema/lock.rs | 164 +++++++++++ src/sema/mod.rs | 7 + src/view/html.rs | 2 + src/view/mod.rs | 8 +- src/view/render.rs | 26 ++ 9 files changed, 1033 insertions(+), 2 deletions(-) create mode 100644 src/sema/ir.rs create mode 100644 src/sema/lock.rs diff --git a/src/knowledge/compile.rs b/src/knowledge/compile.rs index 521be4c..eab7e69 100644 --- a/src/knowledge/compile.rs +++ b/src/knowledge/compile.rs @@ -17,6 +17,20 @@ pub struct KnowledgeOptions { } pub fn compile(opts: KnowledgeOptions) -> Result { + // 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(), diff --git a/src/main.rs b/src/main.rs index dc8be38..e08fe8a 100644 --- a/src/main.rs +++ b/src/main.rs @@ -377,6 +377,20 @@ enum KnowledgeAction { #[arg(long, value_name = "FILE")] from: Option, }, + /// 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 { } 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, diff --git a/src/mlsp.rs b/src/mlsp.rs index b9f50b8..b6ecff2 100644 --- a/src/mlsp.rs +++ b/src/mlsp.rs @@ -57,17 +57,152 @@ fn dispatch(req: &Value) -> Result { 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), // `` M9: occlusion label search (two-tier vocabulary). Some("labels.search") => labels_search(¶ms), // `` 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 { + 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 { + 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 = 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 { + 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::>() })); } + Ok(crate::sema::artifact_json(candidates[0])) +} + +fn link_resolve(params: &Value) -> Result { + 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::>() })) +} + +fn artifact_verify(params: &Value) -> Result { + 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 { + 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 { + 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 { + 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 = 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) -> 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(); + } +} diff --git a/src/sema/ir.rs b/src/sema/ir.rs new file mode 100644 index 0000000..53d7cba --- /dev/null +++ b/src/sema/ir.rs @@ -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, + pub lock_mode: LockMode, +} + +impl CompileOptions { + pub fn for_path(path: &Path) -> Result { + 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); + +impl EffectSet { + pub fn pure() -> Self { + Self(BTreeSet::from(["pure".to_string()])) + } + + pub fn add(&mut self, effect: impl Into) { + 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 { + 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, + pub unit: Option, +} + +#[derive(Debug, Clone)] +pub struct CanonicalSignature { + pub receiver: String, + pub params: Vec, + pub returns: String, + pub effects: EffectSet, +} + +#[derive(Debug, Clone)] +pub struct ContractSet { + pub params: Vec, + pub returns: Option, + pub fields: Vec, +} + +#[derive(Debug, Clone)] +pub struct SourceRef { + pub uri: String, + pub locator: Option, + pub content_digest: Option, + 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, +} + +#[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, + pub display_name: String, + pub kind: String, + pub callable: Option, + pub source: SourceLocation, + pub signature: Option, + pub contract: ContractSet, + pub effects: EffectSet, + pub dependencies: Vec, + pub provenance: Vec, + 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, +} + +#[derive(Debug, Clone)] +pub struct KnowledgeStep { + pub id: ArtifactId, + pub reference: String, + pub kind: String, + pub calls: Vec, + 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, + pub refs: Vec, + pub steps: Vec, +} + +#[derive(Debug, Clone)] +pub struct Compilation { + pub index: ProjectIndex, + pub semantics: SemanticProject, + pub diagnostics: Vec, +} + +/// 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 { + 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, Vec) { + 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, display_name: String, kind: String, + callable: Option, source: SourceLocation, signature: Option, + contract: ContractSet, effects: EffectSet, mut dependencies: Vec, + provenance: Vec, 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, effects: &EffectSet) -> (Option, 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::>(); + 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, out: &mut BTreeMap, &'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 { + 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::>().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::>().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::>(), + "refs": self.refs.iter().map(ref_json).collect::>(), + "steps": self.steps.iter().map(step_json).collect::>(), + }) + } +} + +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::>(),"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::>(), "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::>(), "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::>(),"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::>() }))?; + 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::>() }))?; + 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(); + } +} diff --git a/src/sema/lock.rs b/src/sema/lock.rs new file mode 100644 index 0000000..5d81bf2 --- /dev/null +++ b/src/sema/lock.rs @@ -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, + pub changed: Vec, + pub removed: Vec, +} + +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 { + 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> = 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 = 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::>(); + json!({"schema_version":SCHEMA_VERSION,"query":query,"resolved":!seeds.is_empty(),"seeds":seeds,"affected":entries}) +} + +fn artifact_lock_map(project: &SemanticProject) -> BTreeMap { + 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::>(), + })); + } + 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(); + } +} diff --git a/src/sema/mod.rs b/src/sema/mod.rs index 3a7b74d..aabc343 100644 --- a/src/sema/mod.rs +++ b/src/sema/mod.rs @@ -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}; diff --git a/src/view/html.rs b/src/view/html.rs index 289b54d..9ff87a3 100644 --- a/src/view/html.rs +++ b/src/view/html.rs @@ -4229,6 +4229,7 @@ window.MARQDO_AUTO_STREAM = {auto_stream};

{title}{status_label}

{rel}

{notebook} +{knowledge}

Structure

{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!("

Executable knowledge

{}
", vm.knowledge_html) }, exec_clear = exec_clear, structure_block = structure_block, stdin_panel = stdin_panel, diff --git a/src/view/mod.rs b/src/view/mod.rs index a869de0..243aa40 100644 --- a/src/view/mod.rs +++ b/src/view/mod.rs @@ -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, }) } diff --git a/src/view/render.rs b/src/view/render.rs index 01b7cfd..db70e78 100644 --- a/src/view/render.rs +++ b/src/view/render.rs @@ -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#"
"#); + 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::>().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::>().join(", ") }; + out.push_str(&format!( + r#"

{}

Target
{}
Kind
{}{}
Signature
{}
Effects
{}
Verification
parse: {}; resolve: {}; contract: {}; tests: {}; evidence: {}
Lock digest
{}
Depends on
{}
Execution
Not executed by knowledge preview.
"#, + 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("
"); + out } /// Collect prompt strings from every `input` / `输入` call in the module (pre-order).