Diagnostics

Diagnostics are an API. Every diagnostic has a stable code, byte spans, structured expected and actual values, causal links, and fixes that declare their impact. The CLI, the LSP server, and the MCP server share one analysis library and one format.

sakura check --json
sakura test --json

--json writes JSON Lines: one record per line. Human-readable output is rendered from the same data.

Record kindsCopy Anchor Link

The diagnostic recordCopy Anchor Link

The program below omits Console from greet's effect row:

fn greet(name: String) -> Unit {
  Console.print("hello, {name}")
}

sakura check --json would report it as one line, shown here pretty-printed. Hashes and ids are shortened.

{
  "schema_version": "1.0",
  "kind": "diagnostic",
  "id": "d:7f3a",
  "code": "V3001",
  "severity": "error",
  "phase": "effect",
  "message": "function `greet` performs `Console`, which its signature does not allow",
  "snapshot": "sha256:91c0",
  "symbol_id": "hello::main::greet",
  "spans": [
    { "uri": "file:///work/hello/src/main.sakura", "content_hash": "sha256:4be2",
      "start_byte": 3, "end_byte": 8, "role": "primary", "label": "`greet` is declared pure" },
    { "uri": "file:///work/hello/src/main.sakura", "content_hash": "sha256:4be2",
      "start_byte": 35, "end_byte": 65, "role": "cause", "label": "`Console.print` introduces `Console` here" }
  ],
  "related_ids": [],
  "expected": { "render": "{}", "row": { "labels": [], "tail": null } },
  "actual": { "render": "{Console}", "row": { "labels": [{ "effect": "std::Console", "args": [] }], "tail": null } },
  "obligation": null,
  "counterexample": null,
  "explanation_uri": "sakura://explain/V3001",
  "fixes": [
    { "id": "f:01", "title": "Add `Console` to the signature of `greet`",
      "applicability": "suggested", "impact": "interface_change",
      "edits": [ { "span": { "uri": "file:///work/hello/src/main.sakura", "content_hash": "sha256:4be2",
                             "start_byte": 30, "end_byte": 30, "role": "primary", "label": "" },
                   "replacement": " ! {Console}" } ] }
  ]
}

For V3001, the design specifies two fixes: add the effect to the signature (interface_change) or handle it locally with with (local). Only the first is shown.

FieldsCopy Anchor Link

Span role is one of primary, cause, definition, or use.

RulesCopy Anchor Link

• Byte offsets are zero-based, half-open, and count UTF-8 bytes. There are no line or column numbers.
• content_hash must match the file before any edit is applied.
• The edits in one fix are applied atomically and rejected if they overlap.
• Records are ordered root causes first (empty related_ids), then by position.
• Output is capped at 200 diagnostics per run, with summary.truncated: true.

FixesCopy Anchor Link

Impact classesCopy Anchor Link

Compiler fixes with interface_change, contract_change, or authority_change impact are never machine_applicable. No fix ever widens authority or weakens a contract by itself.

sakura fix lists fixes with their impact class. It applies only machine_applicable fixes unless given ids with --apply id,…, and it never applies contract_change or authority_change. --preview shows the edits without writing.

Frozen specsCopy Anchor Link

sakura check --frozen-specs <symbols|all>, sakura fix, and the MCP apply_patch tool reject any patch that changes a frozen symbol's signature, effect row, error union, requires/ensures/where clauses, or any test/property body. The diagnostic is V8020 spec_frozen and names the clause. This stops an agent from passing a check by editing the spec.

Error codesCopy Anchor Link

Codes are V + a phase digit + three digits for errors, W for warnings, and D for runtime defects. Codes are never reused or renumbered; retired codes stay documented. Every code has an explain page with a minimal pair: wrong program, diagnostic, fixed program.

Warnings named in the design include W1002 (a local shadows an import), W4010 (catch-all _ on an open error union), W5005 (an O(n) contract on a hot path), W7001 (property generator discard budget exceeded), and W8001 (a collection update copies in a loop).

Runtime defects are not diagnostics from sakura check. They terminate the task; if main defects, the program writes one defect record to stderr and exits with status 70:

{"schema_version":"1.0","kind":"defect","code":"D002","message":"division by zero"}

Exit codesCopy Anchor Link

NextCopy Anchor Link

Typed holes: writing a program one ?hole at a time.