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:
1 parent
509bdb1bf6
commit
55dcb57553
11 files changed
+581
-32
No files matched your search
+89
-12
@@ -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
|
||||
|
||||
@@ -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
@@ -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())
|
||||
}
|
||||
Reference in new issue
Block a user