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
@@ -192,7 +192,7 @@ tests/ conformance/negative corpus (see tests/README.md)
|
||||
[`package-format.md`](spec/package-format.md),
|
||||
[`plugin-abi.md`](spec/plugin-abi.md), [`math.md`](spec/math.md),
|
||||
[`foreign.md`](spec/foreign.md), [`tool-v1.md`](spec/tool-v1.md),
|
||||
[`analysis-v1.md`](spec/analysis-v1.md), [`trace-v1.md`](spec/trace-v1.md);
|
||||
[`analysis-v2.md`](spec/analysis-v2.md), [`trace-v1.md`](spec/trace-v1.md);
|
||||
JSON Schemas in [`spec/schemas/`](spec/schemas/).
|
||||
* [`tests/README.md`](tests/README.md) — conformance corpus and `UPDATE_GOLDENS`
|
||||
workflow.
|
||||
|
||||
+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())
|
||||
}
|
||||
@@ -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");
|
||||
|
||||
+21
-1
@@ -106,6 +106,25 @@ Runtime errors now carry a logical source location (ADR-0017):
|
||||
* CLI test `runtime_error_in_imported_module_reports_that_module` reproduces
|
||||
B-08 end to end with the real binary.
|
||||
|
||||
### S2-B/H2-A record (current)
|
||||
|
||||
Analysis v2 (`spec/analysis-v2.md`, `spec/schemas/analysis-v2.schema.json`):
|
||||
|
||||
* `project.root_id` is a logical manifest identity (`root:<name>@<version>`) or
|
||||
a content-derived `workspace_snapshot` digest; physical paths are gone from
|
||||
Analysis bytes.
|
||||
* `modules[].resources` is an array covering the two real `marqdo-ir::Resource`
|
||||
kinds, with stable module/unit/span references, payload digests and code
|
||||
language. Payload text stays in the source.
|
||||
* Diagnostics project `module`, `relative_path`, `span`, `line`, `column`
|
||||
instead of absolute file paths.
|
||||
* `analysis_digest` is SHA-256 of the exact emitted (pretty) bytes, so a
|
||||
consumer can verify it; Trace binds to the same value.
|
||||
* The independent Python consumer validates v2, resources and identity, and
|
||||
rejects unknown versions.
|
||||
* Tests cover byte-identical output after moving a project and resource
|
||||
addressing for formulas/code fences.
|
||||
|
||||
### M0.6 implementation progress
|
||||
|
||||
| Step | State | Evidence |
|
||||
@@ -113,11 +132,12 @@ Runtime errors now carry a logical source location (ADR-0017):
|
||||
| S0/H0 CI baseline | **Done locally** | B-01 fixed in `crates/cli/tests/properties.rs`; fresh-clone path no longer needs an empty directory; full local gate green (see §S0/H0) |
|
||||
| S1/H1-A lock v3 graph | **Done** | ADR-0016; full-closure `marqdo.lock` v3; fail-closed edge lookup; strict non-rewriting `sync`; verified Git cache; unified file-set profile (see §S1/H1-A) |
|
||||
| S2-A/H1-B source locations | **Done** | ADR-0017; `RuntimeError`/`CallFrame` carry `module_id`; callsite origin; CLI module-aware resolution with no entry fallback (see §S2-A/H1-B) |
|
||||
| S2-B/H2-A Analysis v2 | **Done** | logical project identity, resources array, machine-path-free diagnostics, emitted-bytes digest, v2 schema + independent consumer (see §S2-B/H2-A) |
|
||||
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
|
||||
| R1 package-aware identity + callable registry | **Done for statics; superseded by S1 lock v3** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; lock v3 transitive graph (ADR-0016) replaces the flat v2 lock; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
|
||||
| R2 ABI/Kernel/Broker | **Done (worker = crash isolation)** | `KernelRegistry` external providers; complete-name export routing; `CapabilityBroker`; static `check --plugin`; multi-export C test; isolated worker with timeout/crash tests; host handle table. Native/worker are not an OS sandbox |
|
||||
| R3 Tool Protocol | **Done** | `tool install/list/remove`; unknown-command fallback; atomic local install; SHA/tamper checks; black-box tests for arbitrary names, Unicode args, conflicts, traversal and PATH hijacking |
|
||||
| R4 Analysis/Trace v1 | **Done** | `check --emit` Analysis v1; `run/call --trace-file` Trace v1; deterministic schema tests; independent Python consumer; stale-artifact removal; value redaction |
|
||||
| R4 Analysis v2 / Trace v1 | **Partial** | `check --emit` Analysis v2 (logical identity, resources, path-free diagnostics, emitted-bytes digest); `run/call --trace-file` still Trace v1 pending H2-B; independent Python consumer; stale-artifact removal; value redaction |
|
||||
| R5 environment/isolation | **Partial** | Pinned Git fetch with verified cache markers, transitive `@alias` resolution, full-closure atomic `.marqdo/env` materialization, foreign process-group cleanup. Strict OS isolation remains explicitly unavailable (fail-closed) |
|
||||
| R6 release/consumers | **Done for Linux** | examples for unknown-name Tool, multi-export plugin, external kernel and multi-version packages; Analysis/Trace/Tool JSON Schemas; CI Linux gate + Windows/macOS `cargo check`; R6 example tests |
|
||||
|
||||
|
||||
@@ -33,7 +33,7 @@ marqdo-cli/
|
||||
│ ├── math.md Formula subset and math.* semantics
|
||||
│ ├── foreign.md Python/Node kernel protocol
|
||||
│ ├── tool-v1.md generic external Tool Protocol v1
|
||||
│ ├── analysis-v1.md public Analysis v1 projection
|
||||
│ ├── analysis-v2.md public Analysis v2 projection (v1 historical)
|
||||
│ └── trace-v1.md public Trace v1 event stream
|
||||
├── crates/
|
||||
│ ├── marqdo-span/ Span, LineCol, LineIndex (leaf)
|
||||
|
||||
+3
-2
@@ -1,7 +1,8 @@
|
||||
# Marqdo Analysis v1
|
||||
|
||||
Status: **implemented by `marqdo check --emit <path>` (M0.6 R4).** This is a
|
||||
public, read-only projection; it is not a dump of `marqdo-ir`.
|
||||
Status: **superseded by [Analysis v2](analysis-v2.md); never released, do not
|
||||
write v1.** Kept as history. This was the M0.6 R4 read-only projection; it is
|
||||
not a dump of `marqdo-ir`.
|
||||
|
||||
## 1. Invariants
|
||||
|
||||
|
||||
@@ -0,0 +1,162 @@
|
||||
# Marqdo Analysis v2
|
||||
|
||||
Status: **implemented by `marqdo check --emit <path>` (S2).** Supersedes
|
||||
Analysis v1. v1 was never released; it is kept as history and is not written.
|
||||
|
||||
## 1. Invariants
|
||||
|
||||
`check --emit`:
|
||||
|
||||
* never executes the document, loads a plugin shared library, starts a foreign
|
||||
kernel or imports a module implicitly;
|
||||
* validates the loaded program first; on a compile error it writes no artifact
|
||||
and removes an existing artifact at the target path;
|
||||
* writes atomically through a temporary file and rename;
|
||||
* contains no absolute machine paths, timestamps, PIDs or other environmental
|
||||
data, so the same logical project emits byte-identical Analysis from
|
||||
different checkout directories and is safe to compare across machines.
|
||||
|
||||
## 2. Top-level shape
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "marqdo.analysis",
|
||||
"schema_version": 2,
|
||||
"producer": {
|
||||
"name": "marqdo",
|
||||
"version": "<crate version>",
|
||||
"markdown_profile": "marqdo.md.v1"
|
||||
},
|
||||
"project": {
|
||||
"root_id": "root:quantum@0.1.0",
|
||||
"identity_kind": "manifest",
|
||||
"lock_digest": "sha256:<64 hex>"
|
||||
},
|
||||
"modules": [],
|
||||
"diagnostics": []
|
||||
}
|
||||
```
|
||||
|
||||
`project.identity_kind` is:
|
||||
|
||||
| Kind | `root_id` | Meaning |
|
||||
|---|---|---|
|
||||
| `manifest` | `root:<project.name>@<project.version>` | Logical identity of a project with `marqdo.yaml`. Moving the checkout or a Git clone does not change it. |
|
||||
| `workspace_snapshot` | `sha256:<64 hex>` | No manifest. Digest of sorted `(module_id, source_digest)` pairs; identifies content, not a persistent project. |
|
||||
|
||||
`project.lock_digest` is the SHA-256 of the exact `marqdo.lock` bytes prefixed
|
||||
with `sha256:`, or `""` when there is no lock. It is not a logical identity.
|
||||
|
||||
`AnalysisDigest` is the lowercase hex SHA-256 of the exact UTF-8 bytes written
|
||||
by `check --emit` (pretty JSON). This is what Trace v2 binds to
|
||||
`source.analysis_digest`; an independent consumer can verify it by hashing the
|
||||
file. Diagnostics and any configuration options that change the projection are
|
||||
part of that digest.
|
||||
|
||||
Module ids are `<package instance>::<package-relative path>` (ADR-0008) and are
|
||||
scoped by `project.root_id`. A module id alone is not a cross-project symbol.
|
||||
|
||||
## 3. Modules
|
||||
|
||||
The module object is unchanged from Analysis v1 except for `resources`:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "root:res@0.1.0::index.mq.md",
|
||||
"package_instance_id": "root:res@0.1.0",
|
||||
"relative_path": "index.mq.md",
|
||||
"source_digest": "<64 hex of exact source bytes>",
|
||||
"units": [],
|
||||
"functions": [],
|
||||
"imports": [],
|
||||
"references": [],
|
||||
"calls": [],
|
||||
"resources": []
|
||||
}
|
||||
```
|
||||
|
||||
Modules are sorted by `id`; functions, units and calls keep document order and
|
||||
the v1 semantic node shapes (`assign`, `expression`, `call_site`, `branch`,
|
||||
`loop`, `return`; literals, variables, lists, records, unary/binary, member,
|
||||
index, call). `imports`, `references` and `calls` remain static facts; a
|
||||
Markdown reference is not a call. `effects` remains `["unknown"]` (a
|
||||
conservative summary, not a purity proof).
|
||||
|
||||
## 4. Resources
|
||||
|
||||
`resources` is an array, not a count. v2 projects exactly the two resource
|
||||
kinds represented by `marqdo-ir::Resource`; it does not invent table, HTML or
|
||||
link resources.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "root:res@0.1.0::index.mq.md#resource:formula-1",
|
||||
"module_id": "root:res@0.1.0::index.mq.md",
|
||||
"unit_id": "root:res@0.1.0::index.mq.md#calc",
|
||||
"kind": "formula",
|
||||
"span": {"start": 30, "end": 44},
|
||||
"content_digest": "<64 hex>",
|
||||
"language": null,
|
||||
"display": true
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Semantics |
|
||||
|---|---|
|
||||
| `id` | `<module_id>#resource:<kind>-<n>`; `n` is the 1-based ordinal among resources of that kind in the module, in document order |
|
||||
| `module_id` | redundant with the enclosing module, present for flattened consumers |
|
||||
| `unit_id` | innermost owning unit |
|
||||
| `kind` | `formula` or `code`; future kinds are additive and unknown kinds must be ignored |
|
||||
| `span` | Markdown node byte span, including math delimiters/fence, relative to that module's source |
|
||||
| `content_digest` | SHA-256 of the payload: formula LaTeX bytes without delimiters; exact code fence source bytes |
|
||||
| `language` | code fence info string (may be `""`); `null` for formulas |
|
||||
| `display` | formula only: block vs inline math |
|
||||
|
||||
Resource ids are Analysis-local ordinals, not persistent symbols and not `ref`
|
||||
anchors. Content identity is `(module_id, content_digest)`; location identity is
|
||||
`(module_id, span)`. Inserting an earlier resource renumbers later ordinals, but
|
||||
the content digest and span still let a consumer detect the change. Payloads
|
||||
are not copied into Analysis: consumers read the module source (via
|
||||
`relative_path`) and slice `span` or verify `content_digest`.
|
||||
|
||||
## 5. Diagnostics
|
||||
|
||||
Diagnostics no longer embed absolute physical paths:
|
||||
|
||||
```json
|
||||
{
|
||||
"module": "root:res@0.1.0::index.mq.md",
|
||||
"relative_path": "index.mq.md",
|
||||
"span": {"start": 10, "end": 20},
|
||||
"line": 2,
|
||||
"column": 3,
|
||||
"severity": "warning",
|
||||
"code": "markdown.inert_executable",
|
||||
"message": "...",
|
||||
"hints": []
|
||||
}
|
||||
```
|
||||
|
||||
`span` is the primary coordinate; `line`/`column` are presentation-derived from
|
||||
the owning module. `span`, `line` or `column` may be `null` when no precise
|
||||
location exists.
|
||||
|
||||
## 6. Compatibility
|
||||
|
||||
* Writers emit `schema_version: 2`. There is no v1 writer and no
|
||||
`--emit-version` flag; v1 was experimental.
|
||||
* Consumers must reject unknown `schema_version` values and unknown resource
|
||||
kinds rather than silently accepting them.
|
||||
* Changing `root_id`, resource fields, diagnostic fields or the digest
|
||||
definition is a protocol break requiring a new version and an ADR.
|
||||
* JSON Schema: `spec/schemas/analysis-v2.schema.json` (Draft 2020-12).
|
||||
Schema validation is structural; cross-record checks (span inside source,
|
||||
call targets, digest verification) remain semantic tests.
|
||||
|
||||
## 7. Tests
|
||||
|
||||
* `analysis_is_deterministic_and_has_stable_semantic_nodes`
|
||||
* `analysis_v2_identity_is_location_independent`
|
||||
* `analysis_v2_projects_addressable_formula_and_code_resources`
|
||||
* `failed_check_removes_stale_analysis`
|
||||
* `tests/consumers/analysis_consumer.py` (independent Python consumer)
|
||||
@@ -0,0 +1,103 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://marqdo.dev/schemas/analysis-v2.schema.json",
|
||||
"title": "Marqdo Analysis v2",
|
||||
"type": "object",
|
||||
"required": ["schema", "schema_version", "producer", "project", "modules", "diagnostics"],
|
||||
"properties": {
|
||||
"schema": {"const": "marqdo.analysis"},
|
||||
"schema_version": {"const": 2},
|
||||
"producer": {
|
||||
"type": "object",
|
||||
"required": ["name", "version", "markdown_profile"],
|
||||
"properties": {
|
||||
"name": {"type": "string"},
|
||||
"version": {"type": "string"},
|
||||
"markdown_profile": {"const": "marqdo.md.v1"}
|
||||
},
|
||||
"additionalProperties": true
|
||||
},
|
||||
"project": {
|
||||
"type": "object",
|
||||
"required": ["root_id", "identity_kind", "lock_digest"],
|
||||
"properties": {
|
||||
"root_id": {"type": "string", "minLength": 1, "pattern": "^(root:|sha256:[0-9a-f]{64}$)"},
|
||||
"identity_kind": {"enum": ["manifest", "workspace_snapshot"]},
|
||||
"lock_digest": {"type": "string", "pattern": "^(sha256:[0-9a-f]{64})?$"}
|
||||
},
|
||||
"additionalProperties": true
|
||||
},
|
||||
"modules": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["id", "package_instance_id", "relative_path", "source_digest", "units", "functions", "imports", "references", "calls", "resources"],
|
||||
"properties": {
|
||||
"id": {"type": "string", "pattern": "::"},
|
||||
"package_instance_id": {"type": "string", "minLength": 1},
|
||||
"relative_path": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*\\.\\.)"},
|
||||
"source_digest": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
|
||||
"units": {"type": "array"},
|
||||
"functions": {"type": "array"},
|
||||
"imports": {"type": "array"},
|
||||
"references": {"type": "array"},
|
||||
"calls": {"type": "array"},
|
||||
"resources": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["id", "module_id", "unit_id", "kind", "span", "content_digest"],
|
||||
"properties": {
|
||||
"id": {"type": "string", "pattern": "#resource:(formula|code)-[0-9]+$"},
|
||||
"module_id": {"type": "string", "pattern": "::"},
|
||||
"unit_id": {"type": "string", "minLength": 1},
|
||||
"kind": {"enum": ["formula", "code"]},
|
||||
"span": {
|
||||
"type": "object",
|
||||
"required": ["start", "end"],
|
||||
"properties": {
|
||||
"start": {"type": "integer", "minimum": 0},
|
||||
"end": {"type": "integer", "minimum": 0}
|
||||
},
|
||||
"additionalProperties": true
|
||||
},
|
||||
"content_digest": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
|
||||
"language": {"type": ["string", "null"]},
|
||||
"display": {"type": "boolean"}
|
||||
},
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"additionalProperties": true
|
||||
}
|
||||
},
|
||||
"diagnostics": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["module", "relative_path", "severity", "code", "message"],
|
||||
"properties": {
|
||||
"module": {"type": "string", "pattern": "::"},
|
||||
"relative_path": {"type": "string", "minLength": 1},
|
||||
"span": {
|
||||
"type": ["object", "null"],
|
||||
"required": ["start", "end"],
|
||||
"properties": {
|
||||
"start": {"type": "integer", "minimum": 0},
|
||||
"end": {"type": "integer", "minimum": 0}
|
||||
}
|
||||
},
|
||||
"line": {"type": ["integer", "null"], "minimum": 1},
|
||||
"column": {"type": ["integer", "null"], "minimum": 1},
|
||||
"severity": {"enum": ["error", "warning"]},
|
||||
"code": {"type": "string", "minLength": 1},
|
||||
"message": {"type": "string", "minLength": 1},
|
||||
"hints": {"type": "array", "items": {"type": "string"}}
|
||||
},
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"additionalProperties": true
|
||||
}
|
||||
@@ -1,5 +1,5 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Independent Analysis v1 consumer: no Marqdo/Rust imports."""
|
||||
"""Independent Analysis v2 consumer: no Marqdo/Rust imports."""
|
||||
import json
|
||||
import sys
|
||||
|
||||
@@ -11,15 +11,38 @@ with open(sys.argv[1], encoding="utf-8") as handle:
|
||||
|
||||
if analysis.get("schema") != "marqdo.analysis":
|
||||
raise SystemExit("unexpected schema")
|
||||
if analysis.get("schema_version") != 1:
|
||||
if analysis.get("schema_version") != 2:
|
||||
raise SystemExit("unsupported schema_version")
|
||||
|
||||
project = analysis["project"]
|
||||
if project.get("identity_kind") not in ("manifest", "workspace_snapshot"):
|
||||
raise SystemExit("bad project identity")
|
||||
if not isinstance(project.get("root_id"), str) or not project["root_id"]:
|
||||
raise SystemExit("bad root_id")
|
||||
|
||||
functions = []
|
||||
for module in analysis["modules"]:
|
||||
if not module["id"].startswith("root:"):
|
||||
raise SystemExit("unexpected module identity")
|
||||
if not isinstance(module["source_digest"], str) or len(module["source_digest"]) != 64:
|
||||
raise SystemExit("bad source digest")
|
||||
resources = module.get("resources")
|
||||
if not isinstance(resources, list):
|
||||
raise SystemExit("resources must be an array")
|
||||
seen = set()
|
||||
for resource in resources:
|
||||
if resource.get("id") in seen:
|
||||
raise SystemExit("duplicate resource id")
|
||||
seen.add(resource.get("id"))
|
||||
if resource.get("kind") not in ("formula", "code"):
|
||||
raise SystemExit("unknown resource kind")
|
||||
if resource.get("module_id") != module["id"]:
|
||||
raise SystemExit("resource module mismatch")
|
||||
if not isinstance(resource.get("content_digest"), str) or len(resource["content_digest"]) != 64:
|
||||
raise SystemExit("bad resource digest")
|
||||
span = resource.get("span") or {}
|
||||
if not isinstance(span.get("start"), int) or not isinstance(span.get("end"), int):
|
||||
raise SystemExit("bad resource span")
|
||||
for function in module["functions"]:
|
||||
body = json.dumps(function["body"], ensure_ascii=False)
|
||||
functions.append((function["id"], body))
|
||||
|
||||
Reference in new issue
Block a user