feat: compile executable knowledge semantic artifacts

This commit is contained in:
cflmy committed 2026-10-23 09:16:52 +00:00
1 parent 74b298e80d
commit eac9b45263
9 files changed
+1033 -2

No files matched your search

+14
View File
@@ -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
View File
@@ -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
View File
@@ -57,17 +57,152 @@ fn dispatch(req: &Value) -> Result<Value, Value> {
Some("repair_targets") => repair_targets(&params),
Some("repair_apply") => repair_apply(&params),
Some("schema") => schema(&params),
Some("artifact.find") => artifact_find(&params),
Some("artifact.inspect") => artifact_inspect(&params),
Some("link.resolve") => link_resolve(&params),
Some("artifact.verify") => artifact_verify(&params),
Some("artifact.impact") => artifact_impact(&params),
Some("artifact.bind") => artifact_bind(&params),
Some("artifact.execute") => artifact_execute(&params),
// `<TAB>` M9: occlusion label search (two-tier vocabulary).
Some("labels.search") => labels_search(&params),
// `<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
View File
@@ -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();
}
}
+164
View File
@@ -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(&current) {
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();
}
}
+7
View File
@@ -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};
+2
View File
@@ -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
View File
@@ -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,
})
}
+26
View File
@@ -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).