Crate shape_diagnostics 

LLM-Structured Diagnostic Schema (LSDS).

Per ADR-006 §9, LSDS is the primary compiler diagnostic format. Renderers (terminal, LSP, MCP) consume LSDS and produce human-readable / machine- readable output. LSDS is the source of truth — text strings, LSP Diagnostic payloads, and MCP tool responses are all derived from it.

Crate layout

• Diagnostic — the canonical struct. JSON-serializable. Stable across versions per the ADR.
• Severity, Location, TypeWitness, SuggestedFix, ContextWindow — sub-structures referenced from Diagnostic.
• render — built-in renderers. Currently:
  • render::terminal — human-readable text output. LSP and MCP renderers are reserved for subsequent Phase 2 sessions.

Stability contract

Field names in Diagnostic (and nested types) are part of the public wire format. They must not be renamed or reordered without bumping the schema version. Add new optional fields only; never remove or rename existing ones.

The schema version is exposed as SCHEMA_VERSION.

Cross-references

• ADR-006 §9 (docs/adr/006-value-and-memory-model.md) — binding spec.
• ADR-006 §13.5 success metric — average payload ≤500 cl100k tokens.
• crates/shape-vm/src/mir/analysis.rs — BorrowError / BorrowErrorKind / BorrowErrorCode, the source for the B-series diagnostics.

Modules

render

Renderers for crate::Diagnostic.

Structs

ContextSpan

A span of source — a file plus an inclusive line range.

ContextWindow

A token-budgeted context window — the smallest set of source spans needed to understand the diagnostic, with a token count.

Diagnostic

The canonical LSDS diagnostic.

DiagnosticBuilder

Builder for Diagnostic. Use this rather than struct literal at emission sites so future schema evolution doesn’t ripple through.

DiagnosticNote

Auxiliary note attached to a diagnostic — e.g. “borrow originates here”, “binding declared here”. Mirrors the existing ErrorNote structure used by ShapeError::SemanticError.location.notes.

Location

Source location of a diagnostic — a 1-based line/column plus an absolute byte span.

SuggestedFix

A suggested fix — a ranked, optionally-diff-bearing proposal that a renderer (LSP code action, MCP apply_fix tool call) can apply.

TypeWitness

A type witness — a concrete value that satisfies (expected) or violates (found) the type constraint at the diagnostic site, per ADR-006 §9.3.

Enums

Severity

Severity of a diagnostic.

Constants

SCHEMA_VERSION

Wire-format schema version. Bumped on breaking changes.