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
+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
|
||||
}
|
||||
Reference in new issue
Block a user