- 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
139 lines
4.7 KiB
Markdown
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.
|