powerio_diag/lib.rs
1//! The diagnostic vocabulary shared by every PowerIO crate.
2//!
3//! A free-form `Vec<String>` warning is useful for a human and opaque to CI, an
4//! agent, or a downstream solver. Every finding a reader, a lowering pass, or a
5//! writer records carries a stable [`DiagnosticCode`], a [`DiagnosticSeverity`],
6//! a human message, and where known an element path, a [`SourceRef`], a details
7//! object, and a suggested action. The structured record is primary and the
8//! text lines are rendered from it by [`render_line`], so the two cannot
9//! disagree.
10//!
11//! A code reads `NAMESPACE.SCOPE.SPECIFIC`. The first segment names the stage
12//! ([`DiagnosticStage`]) and is the only segment a consumer parses; the rest is
13//! opaque identity. powerio never emits a code whose first segment is outside
14//! the ten, so a downstream producer picks any other first segment and its
15//! codes merge into one report without coordination.
16//!
17//! The crate is a leaf on purpose: the transmission model, the distribution
18//! model, and the `.pio.json` document model are peers, and a record that
19//! crosses between them needs a home below all three.
20//!
21//! ```
22//! use powerio_diag::{DiagnosticSeverity, DiagnosticStage, StructuredDiagnostic, render_line};
23//!
24//! let d = StructuredDiagnostic::new(
25//! "READ.DSS.INCLUDE_REFUSED",
26//! DiagnosticSeverity::Error,
27//! "redirect ../shared.dss: refused; the include escapes the case directory",
28//! );
29//! assert_eq!(d.stage(), Some(DiagnosticStage::Read));
30//! assert!(render_line(&d).starts_with("READ.DSS.INCLUDE_REFUSED: "));
31//! ```
32
33pub mod category;
34pub mod code;
35pub mod collect;
36pub mod nonfinite;
37pub mod record;
38pub mod registry;
39pub mod render;
40
41pub use category::ErrorCategory;
42pub use code::{DiagnosticCode, DiagnosticStage, code_is_well_formed};
43pub use collect::Diagnostics;
44pub use record::{DiagnosticSeverity, SourceRef, StructuredDiagnostic};
45pub use registry::{CodeStatus, DiagnosticInfo, check_registry, check_scope_ownership};
46pub use render::{render_line, render_lines};