Struct DiagnosticMessage 

pub struct DiagnosticMessage {
    pub code: Option<String>,
    pub title: String,
    pub kind: DiagnosticKind,
    pub problem: Option<MessageContent>,
    pub details: Vec<DetailItem>,
    pub hints: Vec<MessageContent>,
    pub location: Option<SourceInfo>,
}

A diagnostic message following tidyverse-style structure.

Structure:

1. Code: Optional error code (e.g., “Q-1-1”) for searchability
2. Title: Brief error message
3. Kind: Error, Warning, Info
4. Problem: What went wrong (the “must” or “can’t” statement)
5. Details: Specific information (bulleted, max 5 per tidyverse)
6. Hints: Optional guidance for fixing (ends with ?)

Example

let msg = DiagnosticMessage {
    code: Some("Q-1-2".to_string()), // quarto-error-code-audit-ignore
    title: "Incompatible types".to_string(),
    kind: DiagnosticKind::Error,
    problem: Some("Cannot combine date and datetime types".into()),
    details: vec![
        DetailItem {
            kind: DetailKind::Error,
            content: "`x`{.arg} has type `date`{.type}".into(),
        },
        DetailItem {
            kind: DetailKind::Error,
            content: "`y`{.arg} has type `datetime`{.type}".into(),
        },
    ],
    hints: vec!["Convert both to the same type?".into()],
    source_spans: vec![],
};

Fields

code: Option<String>

Optional error code (e.g., “Q-1-1”)

Error codes are optional but encouraged. They provide:

• Searchability (users can Google “Q-1-1”)
• Stability (codes don’t change even if message wording improves)
• Documentation (each code maps to a detailed explanation)

title: String

Brief title for the error

kind: DiagnosticKind

The kind of diagnostic (Error, Warning, Info)

problem: Option<MessageContent>

The problem statement (the “what” - using “must” or “can’t”)

details: Vec<DetailItem>

Specific error details (the “where/why” - max 5 per tidyverse)

hints: Vec<MessageContent>

Optional hints for fixing (ends with ?)

location: Option<SourceInfo>

Source location for this diagnostic

When present, this identifies where in the source code the issue occurred. The location may track transformation history, allowing the error to be mapped back through multiple processing steps to the original source file.

Implementations

impl DiagnosticMessage

pub fn builder() -> DiagnosticMessageBuilder

Access the diagnostic message builder API.

This is the recommended way to create diagnostic messages, as the builder API encodes tidyverse-style guidelines and makes it easy to construct well-structured error messages.

Example

use quarto_error_reporting::{DiagnosticMessage, DiagnosticMessageBuilder};

let error = DiagnosticMessageBuilder::error("Incompatible types")
    .with_code("Q-1-2") // quarto-error-code-audit-ignore
    .problem("Cannot combine date and datetime types")
    .add_detail("`x` has type `date`")
    .add_detail("`y` has type `datetime`")
    .add_hint("Convert both to the same type?")
    .build();

pub fn new(kind: DiagnosticKind, title: impl Into<String>) -> Self

Create a new diagnostic message with just a title and kind.

Note: Consider using DiagnosticMessage::builder() instead for better structure.

pub fn error(title: impl Into<String>) -> Self

Create an error diagnostic.

Note: Consider using DiagnosticMessage::builder().error() instead for better structure.

pub fn warning(title: impl Into<String>) -> Self

Create a warning diagnostic.

Note: Consider using DiagnosticMessage::builder().warning() instead for better structure.

pub fn info(title: impl Into<String>) -> Self

Create an info diagnostic.

Note: Consider using DiagnosticMessage::builder().info() instead for better structure.

pub fn with_code(self, code: impl Into<String>) -> Self

Set the error code.

Error codes follow the format Q-<subsystem>-<number> (e.g., “Q-1-1”).

Example

use quarto_error_reporting::DiagnosticMessage;

let msg = DiagnosticMessage::error("YAML Syntax Error")
    .with_code("Q-1-1");

pub fn docs_url(&self) -> Option<&str>

Get the documentation URL for this error, if it has an error code.

Example

Resolves the code against the installed [CatalogProvider] (crate::catalog); returns None when no catalog is installed, the code is unknown, or the entry has no docs URL.

use quarto_error_reporting::DiagnosticMessage;

let msg = DiagnosticMessage::error("Internal Error")
    .with_code("Q-0-1");

// `Some(url)` iff a catalog mapping "Q-0-1" (with a docs URL) is installed.
let _ = msg.docs_url();

pub fn to_text(&self, ctx: Option<&SourceContext>) -> String

Render this diagnostic message as text following tidyverse style.

This is a convenience method that uses default rendering options. For more control over rendering, use Self::to_text_with_options.

Example

use quarto_error_reporting::DiagnosticMessageBuilder;

let msg = DiagnosticMessageBuilder::error("Invalid input")
    .problem("Values must be numeric")
    .add_detail("Found text in column 3")
    .add_hint("Convert to numbers first?")
    .build();
let text = msg.to_text(None);
assert!(text.contains("Error: Invalid input"));
assert!(text.contains("Values must be numeric"));

pub fn to_text_with_options( &self, ctx: Option<&SourceContext>, options: &TextRenderOptions, ) -> String

Render this diagnostic message as text following tidyverse style with custom options.

Format:

Error: title
Problem statement here
✖ Error detail 1
✖ Error detail 2
ℹ Info detail
• Note detail
? Hint 1
? Hint 2

Example

use quarto_error_reporting::{DiagnosticMessageBuilder, TextRenderOptions};

let msg = DiagnosticMessageBuilder::error("Invalid input")
    .problem("Values must be numeric")
    .add_detail("Found text in column 3")
    .add_hint("Convert to numbers first?")
    .build();

// Disable hyperlinks for snapshot testing
let options = TextRenderOptions { enable_hyperlinks: false };
let text = msg.to_text_with_options(None, &options);
assert!(text.contains("Error: Invalid input"));

pub fn to_text_with_renderer( &self, ctx: Option<&SourceContext>, options: &TextRenderOptions, renderer: Option<SourceRenderer>, ) -> String

Like Self::to_text_with_options, but explicitly selects which source-context snippet renderer draws the visual code excerpt.

Pass Some(SourceRenderer::Ariadne) or Some(SourceRenderer::AnnotateSnippets) to force a specific renderer (the corresponding feature must be enabled), or None to use SourceRenderer::default_for_features. This is the seam for experimenting with diagnostic rendering styles without changing the rest of the API: only the source-excerpt block differs between renderers; the surrounding structured text (unlocated details, hints) is identical.

When no renderer feature is enabled — or the diagnostic has no location / source context — this falls back to the structured tidyverse-style text block, exactly as Self::to_text_with_options.

Example

use quarto_error_reporting::{DiagnosticMessageBuilder, TextRenderOptions};

let msg = DiagnosticMessageBuilder::error("Invalid input")
    .problem("Values must be numeric")
    .build();

// `None` picks the default renderer for the enabled features.
let text = msg.to_text_with_renderer(None, &TextRenderOptions::default(), None);
assert!(text.contains("Invalid input"));

pub fn to_json(&self) -> Value

Render this diagnostic message as a JSON value.

Returns a structured JSON object with all fields:

{
  "kind": "error",
  "title": "Invalid input",
  "code": "Q-1-2", // quarto-error-code-audit-ignore
  "problem": "Values must be numeric",
  "details": [{"kind": "error", "content": "Found text in column 3"}],
  "hints": ["Convert to numbers first?"]
}

Example

use quarto_error_reporting::DiagnosticMessage;

let msg = DiagnosticMessage::error("Something went wrong");
let json = msg.to_json();
assert_eq!(json["kind"], "error");
assert_eq!(json["title"], "Something went wrong");

Trait Implementations

impl Clone for DiagnosticMessage

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DiagnosticMessage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for DiagnosticMessage

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for DiagnosticMessage

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for DiagnosticMessage

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for DiagnosticMessage