Crate espforge_diagnostics 

One diagnostic model for the whole pipeline.

Before this crate there were five error conventions: espf::diag::EspfError (a title, one label, one span), String returns in the element wrappers, Invalid::{Spans, Message} in the CLI, anyhow at the boundaries and bare exit codes. A problem could be a sentence with no location, a snippet with no code, or a ❌ line from a library module.

This crate is the destination of extreme.md §3.4: one Diagnostic with a stable code, a severity, a primary span, any number of labels, optional help and machine-applicable fixes. Renderers live here too, so the CLI prints and the library never does: to_human reproduces today’s snippet output exactly, to_json is what CI and editors consume.

Codes

Codes are five characters: E or W followed by four digits. The ranges are reserved by stage so two producers cannot pick the same number:

Range	Stage
E01xx	syntax (parser junk, section headers)
E02xx	# espforge core and meta
E03xx	options and their answers
E04xx	$ graph resolution
E05xx	peripherals (<gpio>, <i2c>, <spi>, <uart>)
E06xx	components (<led>, <button>, <*_component>)
E07xx	ownership and conflicts
E08xx	services and driver routing
W0xxx	warnings

E0999 is the sentinel for a message missing from the table; it is a bug if it reaches output, and the JSON contract test rejects it.

Every diagnostic carries a code. The table lives in codes, one entry per message, so a stage cannot invent a number another stage already uses. The human renderer ignores the code; to_json is where it is a contract.

Re-exports

pub use codes::for_message;

pub use json::to_json;

pub use render::to_human;

Modules

codes

The stable diagnostic codes, one per message.

json

The machine format: one JSON document per run, stable field names.

render

The human renderer: rustc-style snippets, exactly the output the CLI had before the diagnostic model moved here.

Structs

DiagCode

A stable diagnostic code (E0701).

Diagnostic

One located problem.

Edit

One text replacement. Spans are byte offsets into the original source.

Fix

A suggested edit, shown as one action (espforge fix, an LSP quick-fix).

Label

One underline and its explanation.

Enums

Severity

How loudly a diagnostic is reported. Only errors make a command fail.

Type Aliases

Diagnostics

The whole set of problems from one stage, in render order.

Span

A byte range into the original source.