Files
marqdo-cli/spec/analysis-v1.md
T
cflmy b5a28a9825 feat(m0.6-r4): public Analysis v1 and Trace v1
- add check --emit with a deterministic, read-only semantic projection:
  package-aware modules, signatures, normalized bodies, refs, calls,
  diagnostics and source digests
- remove stale analysis artifacts on compile errors; atomic writes
- add run/call --trace-file with interpreter call/branch/loop/return events
  and host effect events under one sequence; redact values and record error
  status
- add Analysis/Trace v1 specs, ADR-0015 and an independent Python consumer
- add contract tests for determinism, stale artifacts, trace ordering/status
  and secret redaction
2026-11-20 11:46:37 +08:00

139 lines
4.7 KiB
Markdown

# 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`.
## 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 a stale file at the target path;
* writes atomically (temporary file + rename) only after a successful check;
* is deterministic: the same source, tool version and project path produce
byte-identical JSON (no timestamps, no random ids);
* exposes no private Rust layout, optimization instruction or host pointer.
## 2. Top-level shape
```json
{
"schema": "marqdo.analysis",
"schema_version": 1,
"producer": {"name": "marqdo", "version": "0.1.0", "markdown_profile": "marqdo.md.v1"},
"project": {"root_id": "sha256:...", "lock_digest": "sha256:..."},
"modules": [],
"diagnostics": []
}
```
* `root_id` is a digest of the normalized project root used for this run.
* `lock_digest` is a digest of `marqdo.lock`, or `""` when absent.
* Modules are sorted by canonical `id`; arrays keep source order.
* `schema_version` is a major version. Additive optional fields are allowed;
removing/renaming fields or changing units/types requires a major bump.
## 3. Modules
```json
{
"id": "root:default::index.mq.md",
"package_instance_id": "root:default",
"relative_path": "index.mq.md",
"source_digest": "<sha256 hex>",
"units": [],
"functions": [],
"imports": [],
"references": [],
"calls": [],
"resources": 0
}
```
Module identity is the package-aware `ModuleId` from
`spec/references.md` §2.1. `source_digest` hashes the exact source bytes.
### 3.1 Units
Each unit has `id`, `kind` (`root`/`namespace`/`function`/`section`), `name`,
`level`, `span` (`{start,end}` byte offsets) and optionally `function`.
### 3.2 Functions and signatures
```json
{
"id": "root:default::index.mq.md::数学.阶乘",
"unit_id": "root:default::index.mq.md#数学/阶乘",
"local_name": "阶乘",
"namespace": "数学",
"span": {"start": 0, "end": 100},
"heading_span": {"start": 0, "end": 10},
"signature": {
"kind": "inferred",
"params": [{"name": "n", "required": true, "type": null, "default": null, "span": {"start": 0, "end": 0}}]
},
"effects": ["unknown"],
"body": []
}
```
`kind` is `explicit` or `inferred`. Inferred signatures only accept named
arguments. `effects` is a **conservative** summary; `unknown` is not a proof of
purity. Dynamic ABI/Foreign targets remain unknown unless a descriptor says
otherwise.
### 3.3 Normalized body nodes
Body nodes use a small stable language, never internal IR serialization:
* `literal` (`type`: `int`/`float`/`text`/`bool`/`none`, `value` when present);
* `variable`, `list`, `record`, `member`, `index`;
* `unary` (`not`/`neg`/`pos`) and `binary` (`or`, `and`, `eq`, `ne`, `lt`,
`le`, `gt`, `ge`, `add`, `sub`, `mul`, `div`, `floor_div`, `mod`, `pow`);
* `call` with `callee` and `args`;
* `assign`, `expression`, `call_site`, `branch` (ordered arms), `loop`,
`return`.
Every node carries a byte `span`. Nodes outside the supported public subset
must be marked `unsupported` (future extension), never silently given invented
semantics.
### 3.4 Imports, references and calls
* `imports[]`: `{alias, target, span, resolved}`; `resolved` is a module id or
null. Imports stay explicit.
* `references[]`: Markdown link edges with `{source, url, span, state,
target_module, target_unit}`. `state` is `resolved`, `unresolved` or
`external`; a failed resolution is never disguised as bound.
* `calls[]`: `{function, span, callee, state, target}` where `state` is
`function`, `builtin`, `plugin` or `unresolved`.
Reference edges never execute anything and grant no capability.
## 4. Diagnostics
`diagnostics[]` uses the same stable codes/JSON shape as `marqdo check --json`.
An analysis emitted after a successful check normally has no error diagnostics
(warnings may remain).
## 5. Consumer contract
An independent consumer (Python/Go/JavaScript, without linking Rust crates)
must be able to:
* find a function by `id` and read its signature/body;
* find recursive/forward calls and `ref` edges;
* map every body node back to `source_digest` + byte span;
* reject `schema_version` it does not understand.
`tests/consumers/analysis_consumer.py` is one such black-box consumer and
`crates/cli/tests/analysis_trace.rs` runs it when Python is available.
## 6. Not included
Internal optimization IR, host pointers, plugin handles, proof status and
execution results are deliberately absent. Analysis does not claim that a
document runs successfully or that any function is proved.