Skip to main content

Crate quarto_error_reporting

Crate quarto_error_reporting 

Source
Expand description

Error reporting and diagnostic messages for Quarto.

This crate provides a structured approach to error reporting, inspired by:

  • ariadne: Visual compiler-quality error messages with source context
  • R cli package: Semantic, structured text output
  • Tidyverse style guide: Best practices for error message content

§Architecture

The crate is organized into several phases:

§Phase 1: Core Types (Current)

§Phase 2: Rendering (Planned)

  • Integration with ariadne for visual terminal output
  • JSON serialization for machine-readable output

§Phase 3: Console Helpers (Planned)

  • High-level console output primitives
  • ANSI writer for Pandoc AST (requires discussion)

§Phase 4: Builder API (Planned)

  • Tidyverse-style builder methods (.problem(), .add_detail(), .add_hint())

§Design Decisions

  • Markdown-first: Messages use Markdown strings, converted to Pandoc AST internally
  • Semantic markup: Use Pandoc span syntax for semantic classes: `text`{.class}
  • Multiple outputs: ANSI terminal, HTML, and JSON formats
  • Rust-idiomatic: Designed for Rust ergonomics (WASM for cross-language if needed)

§Example Usage (Future)

ⓘ
use quarto_error_reporting::DiagnosticMessage;

let error = DiagnosticMessage::builder()
    .error("Unclosed code block")
    .problem("Code block started but never closed")
    .add_detail("The code block starting with `` ```{python} `` was never closed")
    .at_location(opening_span)
    .add_hint("Did you forget the closing `` ``` ``?")
    .build()?;

console.error(&error);

Re-exports§

pub use builder::DiagnosticMessageBuilder;
pub use catalog::CatalogProvider;
pub use catalog::EmptyCatalog;
pub use catalog::ErrorCodeInfo;
pub use catalog::get_docs_url;
pub use catalog::get_error_info;
pub use catalog::get_subsystem;
pub use catalog::install_catalog;
pub use coalesce::CoalescedDiagnostic;
pub use coalesce::coalesce_by_source;
pub use diagnostic::DetailItem;
pub use diagnostic::DetailKind;
pub use diagnostic::DiagnosticKind;
pub use diagnostic::DiagnosticMessage;
pub use diagnostic::MessageContent;
pub use diagnostic::SourceRenderer;
pub use diagnostic::TextRenderOptions;

Modules§

builder
Builder API for diagnostic messages.
catalog
Pluggable error-code catalog.
coalesce
Cross-source diagnostic coalescing.
diagnostic
Core diagnostic message types.
macros
Macros for creating diagnostic messages.

Macros§

generic_error
Create a generic error with automatic file and line information.
generic_warning
Create a generic warning with automatic file and line information.