diff --git a/README.md b/README.md index 1254d32..ce249de 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/crates/cli/src/analysis.rs b/crates/cli/src/analysis.rs index f39055c..55c8c26 100644 --- a/crates/cli/src/analysis.rs +++ b/crates/cli/src/analysis.rs @@ -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::>(), "references": reference_edges(project, module_id), "calls": module.functions.iter().flat_map(|function| calls_json(project, module, function)).collect::>(), - "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, 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 { + 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 { + 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 { module .units diff --git a/crates/cli/src/loader.rs b/crates/cli/src/loader.rs index 8ec19fd..f0b0ae8 100644 --- a/crates/cli/src/loader.rs +++ b/crates/cli/src/loader.rs @@ -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:@`. + 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) -> 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 { } 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 { }); } } + 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, diff --git a/crates/cli/src/trace.rs b/crates/cli/src/trace.rs index ee82f9d..cac0dff 100644 --- a/crates/cli/src/trace.rs +++ b/crates/cli/src/trace.rs @@ -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 = 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()) -} diff --git a/crates/cli/tests/analysis_trace.rs b/crates/cli/tests/analysis_trace.rs index 0baeb61..ca667d7 100644 --- a/crates/cli/tests/analysis_trace.rs +++ b/crates/cli/tests/analysis_trace.rs @@ -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"); diff --git a/docs/STATUS.md b/docs/STATUS.md index a2142b9..be1e3bf 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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:@`) 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 | diff --git a/docs/contributor-guide.md b/docs/contributor-guide.md index 6906413..411b713 100644 --- a/docs/contributor-guide.md +++ b/docs/contributor-guide.md @@ -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) diff --git a/spec/analysis-v1.md b/spec/analysis-v1.md index 5f904e3..88f11d2 100644 --- a/spec/analysis-v1.md +++ b/spec/analysis-v1.md @@ -1,7 +1,8 @@ # Marqdo Analysis v1 -Status: **implemented by `marqdo check --emit ` (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 diff --git a/spec/analysis-v2.md b/spec/analysis-v2.md new file mode 100644 index 0000000..f3ac688 --- /dev/null +++ b/spec/analysis-v2.md @@ -0,0 +1,162 @@ +# Marqdo Analysis v2 + +Status: **implemented by `marqdo check --emit ` (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": "", + "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:@` | 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 `::` (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` | `#resource:-`; `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) diff --git a/spec/schemas/analysis-v2.schema.json b/spec/schemas/analysis-v2.schema.json new file mode 100644 index 0000000..f29c5f7 --- /dev/null +++ b/spec/schemas/analysis-v2.schema.json @@ -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 +} diff --git a/tests/consumers/analysis_consumer.py b/tests/consumers/analysis_consumer.py index 15d4bc9..809d53f 100644 --- a/tests/consumers/analysis_consumer.py +++ b/tests/consumers/analysis_consumer.py @@ -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))