quarto_error_reporting/
lib.rs

1//! Error reporting and diagnostic messages for Quarto.
2//!
3//! This crate provides a structured approach to error reporting, inspired by:
4//! - **ariadne**: Visual compiler-quality error messages with source context
5//! - **R cli package**: Semantic, structured text output
6//! - **Tidyverse style guide**: Best practices for error message content
7//!
8//! # Architecture
9//!
10//! The crate is organized into several phases:
11//!
12//! ## Phase 1: Core Types (Current)
13//! - [`DiagnosticMessage`]: The main error message structure
14//! - [`MessageContent`]: Content representation (Plain, Markdown, or Pandoc AST)
15//! - [`DetailItem`]: Individual detail bullets with error/info/note kinds
16//! - [`DiagnosticKind`]: Error, Warning, Info, etc.
17//!
18//! ## Phase 2: Rendering (Planned)
19//! - Integration with ariadne for visual terminal output
20//! - JSON serialization for machine-readable output
21//!
22//! ## Phase 3: Console Helpers (Planned)
23//! - High-level console output primitives
24//! - ANSI writer for Pandoc AST (requires discussion)
25//!
26//! ## Phase 4: Builder API (Planned)
27//! - Tidyverse-style builder methods (`.problem()`, `.add_detail()`, `.add_hint()`)
28//!
29//! # Design Decisions
30//!
31//! - **Markdown-first**: Messages use Markdown strings, converted to Pandoc AST internally
32//! - **Semantic markup**: Use Pandoc span syntax for semantic classes: `` `text`{.class} ``
33//! - **Multiple outputs**: ANSI terminal, HTML, and JSON formats
34//! - **Rust-idiomatic**: Designed for Rust ergonomics (WASM for cross-language if needed)
35//!
36//! # Example Usage (Future)
37//!
38//! ```ignore
39//! use quarto_error_reporting::DiagnosticMessage;
40//!
41//! let error = DiagnosticMessage::builder()
42//!     .error("Unclosed code block")
43//!     .problem("Code block started but never closed")
44//!     .add_detail("The code block starting with `` ```{python} `` was never closed")
45//!     .at_location(opening_span)
46//!     .add_hint("Did you forget the closing `` ``` ``?")
47//!     .build()?;
48//!
49//! console.error(&error);
50//! ```
51
52// Phase 1: Core error types
53pub mod diagnostic;
54
55// Error code catalog
56pub mod catalog;
57
58// Phase 4: Builder API
59pub mod builder;
60
61// JSON wire shape for diagnostics, shared by wasm-quarto-hub-client
62// (WASM render bridge) and quarto-preview (server-side diagnostics
63// endpoint). Lifted from wasm-quarto-hub-client under bd-b9kzg so
64// the q2-preview SPA can consume both feeds without a translation
65// layer. Behind the default-off `json` feature (carries `schemars`
66// and Quarto's `quarto.org` schema URLs) so the published crate stays
67// minimal for non-Quarto consumers.
68#[cfg(feature = "json")]
69pub mod json;
70
71// Macros for convenient error creation
72pub mod macros;
73
74// Cross-source diagnostic coalescing (bd-9hlja).
75//
76// When per-page diagnostics share a source location across many
77// pages, this module groups them into a single emission listing the
78// affected pages — used by the render summary printer in the CLI.
79pub mod coalesce;
80
81// Re-export main types for convenience
82pub use builder::DiagnosticMessageBuilder;
83pub use catalog::{
84    CatalogProvider, EmptyCatalog, ErrorCodeInfo, get_docs_url, get_error_info, get_subsystem,
85    install_catalog,
86};
87pub use coalesce::{CoalescedDiagnostic, coalesce_by_source};
88pub use diagnostic::{
89    DetailItem, DetailKind, DiagnosticKind, DiagnosticMessage, MessageContent, TextRenderOptions,
90};
91#[cfg(feature = "json")]
92pub use json::{
93    JsonDiagnostic, JsonDiagnosticDetail, JsonPass1Failure, diagnostic_to_json, with_source_file,
94};
quarto_error_reporting/lib.rs

quarto_error_reporting/
lib.rs
