proc-macro2-diagnostics
Ergonomic compiler diagnostics for Rust proc-macros on both stable and nightly.
Repository Health
Technical Analysis
proc-macro2-diagnostics is a Rust library that brings rich compiler diagnostics to procedural macros on both stable and nightly toolchains. It extends proc_macro2 spans with a SpanDiagnosticExt trait so macro authors can attach errors, warnings, notes, and help messages to specific spans and emit them as tokens.
On nightly it uses the real diagnostics API for full fidelity, while on stable it degrades gracefully by emitting diagnostics as compiler errors, with colorized output by default. This lets proc-macro authors write one diagnostic path that produces helpful, well-located messages regardless of the user’s toolchain.
What You Get
- A SpanDiagnosticExt trait adding error/warning/note/help methods to proc_macro2 spans
- A Diagnostic type that emits as tokens, working on both stable and nightly toolchains
- Colorized diagnostic output by default, toggleable via a Cargo feature
Common Use Cases
- Reporting precise, span-located errors from a custom derive or attribute macro
- Providing helpful notes and suggestions to users of a proc-macro
- Writing one diagnostics path that behaves well on stable and nightly Rust
Under The Hood
Architecture
The crate defines a Diagnostic type carrying a level, message, and span, plus child notes, and a SpanDiagnosticExt trait implemented for proc_macro2::Span that constructs diagnostics fluently. A build script (build.rs) uses version_check to detect nightly and conditionally compile against the real diagnostics API; on stable, diagnostics render as errors, optionally colorized via yansi.
Tech Stack
Rust (edition 2018) depending on quote, proc-macro2, and syn (parsing+printing), with optional yansi for colors and version_check as a build dependency. trybuild drives compile-fail tests.
Code Quality
Small, stable, and mature: the API has been steady for years and is depended on transitively by a very large share of the proc-macro ecosystem. trybuild UI tests cover the emitted output.
API Design
The extension-trait approach makes diagnostics read naturally (span.error("...")), and the emit_as_*_tokens helpers give macro authors a clear, minimal path from diagnostic to output tokens.
