feat(analysis): Analysis v2 logical identity and resource projection (B-06 B-07)

- add ProjectIdentity (manifest root instance or workspace snapshot digest)
  and remove absolute-path root ids from Analysis bytes
- replace the resources count with an addressable array over the two real
  marqdo-ir resource kinds (formula, code), including unit/span/payload digest
  and code language
- project diagnostics by module/relative path/span, removing machine paths
- define the digest as SHA-256 of the exact emitted bytes so consumers can
  verify it; Trace binds to the same digest
- add analysis-v2 spec and JSON schema, supersede v1, update the independent
  Python consumer, schemas and docs
- tests: location-independent byte equality and resource addressing
This commit is contained in:
cflmy committed 2026-11-20 12:58:58 +08:00
1 parent 509bdb1bf6
commit 55dcb57553
11 files changed
+581 -32

No files matched your search

+89 -12
View File
@@ -1,4 +1,4 @@
//! Public Analysis v1 projection (spec/analysis-v1.md).
//! Public Analysis v2 projection (spec/analysis-v2.md).
//!
//! This is deliberately not a serde dump of `marqdo-ir`: the schema and node
//! kinds are the public contract, while internal Rust types may change. The
@@ -8,7 +8,7 @@
use std::path::Path;
use marqdo_expression::{BinaryOp, Expr, UnaryOp};
use marqdo_ir::{CallTarget, Function, Module, SignatureKind, Stmt, UnitKind};
use marqdo_ir::{CallTarget, Function, Module, ModuleId, Resource, SignatureKind, Stmt, UnitKind};
use marqdo_span::Span;
use serde_json::{json, Value};
use sha2::{Digest, Sha256};
@@ -17,7 +17,7 @@ use crate::loader::LoadedProject;
/// Schema name and version.
pub const SCHEMA: &str = "marqdo.analysis";
pub const SCHEMA_VERSION: u32 = 1;
pub const SCHEMA_VERSION: u32 = 2;
/// Build the deterministic public projection.
pub fn build(project: &LoadedProject) -> Value {
@@ -39,7 +39,7 @@ pub fn build(project: &LoadedProject) -> Value {
})).collect::<Vec<_>>(),
"references": reference_edges(project, module_id),
"calls": module.functions.iter().flat_map(|function| calls_json(project, module, function)).collect::<Vec<_>>(),
"resources": module.resources.len(),
"resources": resources_json(module_id, module),
}));
}
modules.sort_by(|a, b| {
@@ -56,26 +56,32 @@ pub fn build(project: &LoadedProject) -> Value {
"markdown_profile": "marqdo.md.v1",
},
"project": {
"root_id": format!("sha256:{}", sha256_hex(project.root.to_string_lossy().as_bytes())),
"root_id": project.identity.root_id(),
"identity_kind": project.identity.kind(),
"lock_digest": lock_digest(project),
},
"modules": modules,
"diagnostics": crate::output::diagnostics_json(&project.diagnostics),
"diagnostics": diagnostics_json(project),
})
}
/// Digest of the serialized projection (used by Trace v1 to detect staleness).
/// Encode exactly the bytes written by `check --emit`.
fn encode(project: &LoadedProject) -> Result<Vec<u8>, String> {
serde_json::to_vec_pretty(&build(project))
.map_err(|error| format!("cannot encode analysis: {error}"))
}
/// SHA-256 of the exact emitted Analysis bytes (Trace binds to this digest).
pub fn digest(project: &LoadedProject) -> String {
let bytes = serde_json::to_vec(&build(project)).unwrap_or_default();
sha256_hex(&bytes)
encode(project)
.map(|bytes| sha256_hex(&bytes))
.unwrap_or_else(|_| sha256_hex(b""))
}
/// Atomically write the projection. An error must not leave a stale success
/// artifact behind.
pub fn write(project: &LoadedProject, path: &Path) -> Result<(), String> {
let value = build(project);
let bytes = serde_json::to_vec_pretty(&value)
.map_err(|error| format!("cannot encode analysis: {error}"))?;
let bytes = encode(project)?;
let parent = path
.parent()
.filter(|parent| !parent.as_os_str().is_empty())
@@ -106,6 +112,77 @@ fn lock_digest(project: &LoadedProject) -> Value {
}
}
fn resources_json(module_id: &ModuleId, module: &Module) -> Vec<Value> {
let mut formula_index = 0usize;
let mut code_index = 0usize;
module
.resources
.iter()
.map(|resource| match resource {
Resource::Formula {
unit,
latex,
display,
span,
} => {
formula_index += 1;
json!({
"id": format!("{module_id}#resource:formula-{formula_index}"),
"module_id": module_id.to_string(),
"unit_id": unit.to_string(),
"kind": "formula",
"span": span_json(*span),
"content_digest": sha256_hex(latex.as_bytes()),
"language": null,
"display": display,
})
}
Resource::Code {
unit,
language,
source: _,
content_hash,
span,
} => {
code_index += 1;
json!({
"id": format!("{module_id}#resource:code-{code_index}"),
"module_id": module_id.to_string(),
"unit_id": unit.to_string(),
"kind": "code",
"span": span_json(*span),
"content_digest": content_hash,
"language": language,
})
}
})
.collect()
}
fn diagnostics_json(project: &LoadedProject) -> Vec<Value> {
project
.diagnostics
.iter()
.map(|item| {
let (line, column) = item
.line_col()
.map(|(line, column)| (Value::from(line), Value::from(column)))
.unwrap_or((Value::Null, Value::Null));
json!({
"module": item.module_id.to_string(),
"relative_path": item.module_id.relative_path,
"span": item.diagnostic.span.map(span_json),
"line": line,
"column": column,
"severity": if item.diagnostic.is_error() { "error" } else { "warning" },
"code": item.diagnostic.code,
"message": item.diagnostic.message,
"hints": item.diagnostic.hints,
})
})
.collect()
}
fn units_json(module: &Module) -> Vec<Value> {
module
.units
+64 -1
View File
@@ -63,6 +63,58 @@ impl FileDiagnostic {
}
}
/// Logical project identity used by public Analysis/Trace artifacts.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProjectIdentity {
/// A project with `marqdo.yaml`: the logical root package instance.
Manifest {
/// `root:<name>@<version>`.
instance: String,
},
/// No manifest: a content-derived snapshot id with no rename guarantee.
WorkspaceSnapshot {
/// Lowercase hex digest of the sorted module/source pairs.
digest: String,
},
}
impl ProjectIdentity {
/// Canonical `root_id` string used in Analysis/Trace.
pub fn root_id(&self) -> String {
match self {
ProjectIdentity::Manifest { instance } => instance.clone(),
ProjectIdentity::WorkspaceSnapshot { digest } => format!("sha256:{digest}"),
}
}
/// Wire discriminator (`manifest` or `workspace_snapshot`).
pub fn kind(&self) -> &'static str {
match self {
ProjectIdentity::Manifest { .. } => "manifest",
ProjectIdentity::WorkspaceSnapshot { .. } => "workspace_snapshot",
}
}
}
fn workspace_snapshot_digest(files: &BTreeMap<ModuleId, LoadedFile>) -> String {
use sha2::{Digest, Sha256};
let mut hasher = Sha256::new();
for (module_id, file) in files {
hasher.update(module_id.canonical().as_bytes());
hasher.update(b"\n");
hasher.update(source_digest(&file.source).as_bytes());
hasher.update(b"\n");
}
hex::encode(hasher.finalize())
}
fn source_digest(source: &str) -> String {
use sha2::{Digest, Sha256};
let mut hasher = Sha256::new();
hasher.update(source.as_bytes());
hex::encode(hasher.finalize())
}
/// A resolved source location inside a loaded file.
pub struct LocatedSource<'a> {
/// The owning file.
@@ -79,6 +131,8 @@ pub struct LoadedProject {
pub root: PathBuf,
/// Entry module.
pub entry: ModuleId,
/// Logical project identity (path-independent).
pub identity: ProjectIdentity,
/// All modules.
pub program: Program,
/// Analysed files keyed by module id.
@@ -194,7 +248,7 @@ pub fn load(entry: &Path) -> Result<LoadedProject, String> {
}
None
};
let resolver = PackageResolver::new(root.clone(), manifest, lock);
let resolver = PackageResolver::new(root.clone(), manifest.clone(), lock);
let entry_module = resolver.resolve_entry(&entry)?;
let mut loader = Loader {
resolver,
@@ -216,9 +270,18 @@ pub fn load(entry: &Path) -> Result<LoadedProject, String> {
});
}
}
let identity = match &manifest {
Some(_) => ProjectIdentity::Manifest {
instance: entry_id.instance.clone(),
},
None => ProjectIdentity::WorkspaceSnapshot {
digest: workspace_snapshot_digest(&loader.files),
},
};
Ok(LoadedProject {
root: loader.resolver.root().to_path_buf(),
entry: entry_id,
identity,
program: loader.program,
files: loader.files,
packages: loader.packages,
+1 -11
View File
@@ -7,7 +7,6 @@ use std::path::Path;
use marqdo_host::{Host, SemanticEvent, StdHost, TraceEntry};
use serde_json::{json, Value};
use sha2::{Digest, Sha256};
use crate::loader::LoadedProject;
@@ -32,10 +31,7 @@ pub fn write(
.unwrap_or(0)
);
let analysis_digest = crate::analysis::digest(project);
let root_id = format!(
"sha256:{}",
sha256_hex(project.root.to_string_lossy().as_bytes())
);
let root_id = project.identity.root_id();
let mut events: Vec<Value> = host
.semantic_events()
.iter()
@@ -99,9 +95,3 @@ fn atomic_write(path: &Path, bytes: &[u8]) -> Result<(), String> {
}
Ok(())
}
fn sha256_hex(bytes: &[u8]) -> String {
let mut hasher = Sha256::new();
hasher.update(bytes);
hex::encode(hasher.finalize())
}
+111 -1
View File
@@ -96,10 +96,18 @@ fn analysis_is_deterministic_and_has_stable_semantic_nodes() {
let analysis: serde_json::Value = serde_json::from_slice(&first_bytes).unwrap();
assert_eq!(analysis["schema"], "marqdo.analysis");
assert_eq!(analysis["schema_version"], 1);
assert_eq!(analysis["schema_version"], 2);
let module = &analysis["modules"][0];
assert_eq!(module["id"], "root:default::index.mq.md");
assert_eq!(module["package_instance_id"], "root:default");
assert!(
analysis["project"]["root_id"]
.as_str()
.unwrap_or_default()
.starts_with("sha256:"),
"standalone documents use a workspace snapshot identity"
);
assert_eq!(analysis["project"]["identity_kind"], "workspace_snapshot");
assert_eq!(module["functions"].as_array().unwrap().len(), 2);
let main = module["functions"]
.as_array()
@@ -131,6 +139,108 @@ fn analysis_is_deterministic_and_has_stable_semantic_nodes() {
}
}
#[test]
fn analysis_v2_identity_is_location_independent() {
let first = TempDir::new("analysis-identity-a");
let second = TempDir::new("analysis-identity-b");
let source = "## main\n\n**x = 1**\n\n*x*\n";
for dir in [&first, &second] {
write(
dir.path(),
"marqdo.yaml",
"project:\n name: doc\n version: 0.1.0\n",
);
write(dir.path(), "index.mq.md", source);
}
let mut bytes = Vec::new();
for dir in [&first, &second] {
let target = dir.path().join("analysis.json");
let output = cli(
dir.path(),
&["check", "index.mq.md", "--emit", target.to_str().unwrap()],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
bytes.push(std::fs::read(&target).unwrap());
}
assert_eq!(
bytes[0], bytes[1],
"moving a project must not change Analysis bytes"
);
let text = String::from_utf8(bytes[0].clone()).unwrap();
assert!(
!text.contains(first.path().to_str().unwrap()),
"machine path leaked into Analysis"
);
let analysis: serde_json::Value = serde_json::from_slice(&bytes[0]).unwrap();
assert_eq!(analysis["project"]["root_id"], "root:doc@0.1.0");
assert_eq!(analysis["project"]["identity_kind"], "manifest");
}
#[test]
fn analysis_v2_projects_addressable_formula_and_code_resources() {
let dir = TempDir::new("analysis-resources");
let source = r#"## calc
`(x)`
$$A = x + 1$$
```python
print(1)
```
*x*
"#;
write(
dir.path(),
"marqdo.yaml",
"project:\n name: res\n version: 0.1.0\n",
);
write(dir.path(), "index.mq.md", source);
let target = dir.path().join("analysis.json");
let output = cli(
dir.path(),
&["check", "index.mq.md", "--emit", target.to_str().unwrap()],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let analysis: serde_json::Value =
serde_json::from_slice(&std::fs::read(&target).unwrap()).unwrap();
let resources = analysis["modules"][0]["resources"].as_array().unwrap();
assert_eq!(resources.len(), 2, "{resources:?}");
let formula = resources
.iter()
.find(|resource| resource["kind"] == "formula")
.unwrap();
let code = resources
.iter()
.find(|resource| resource["kind"] == "code")
.unwrap();
assert_eq!(
formula["id"],
"root:res@0.1.0::index.mq.md#resource:formula-1"
);
assert_eq!(code["id"], "root:res@0.1.0::index.mq.md#resource:code-1");
assert_eq!(formula["module_id"], "root:res@0.1.0::index.mq.md");
assert_eq!(formula["language"], serde_json::Value::Null);
assert_eq!(code["language"], "python");
assert_eq!(formula["content_digest"].as_str().unwrap().len(), 64);
assert_eq!(code["content_digest"].as_str().unwrap().len(), 64);
assert!(
!analysis.to_string().contains("A = x + 1"),
"resource payloads stay in source, not Analysis"
);
}
#[test]
fn failed_check_removes_stale_analysis() {
let dir = TempDir::new("analysis-error");