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.

Examples found in repository

examples/diagnostic_collector.rs (line 30)

    fn error(&mut self, message: impl Into<String>) {
        self.add(DiagnosticMessage::error(message.into()));
    }

examples/basic_error.rs (line 9)

fn main() {
    // Create a simple error message
    let error = DiagnosticMessage::error("File not found");

    // Render to text
    println!("{}", error.to_text(None));
    println!();

    // Create a warning
    let warning = DiagnosticMessage::warning("Deprecated feature used");
    println!("{}", warning.to_text(None));
    println!();

    // Create an info message
    let info = DiagnosticMessage::info("Processing 42 files");
    println!("{}", info.to_text(None));
}

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

Create a warning diagnostic.

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

Examples found in repository

examples/diagnostic_collector.rs (line 34)

    fn warn(&mut self, message: impl Into<String>) {
        self.add(DiagnosticMessage::warning(message.into()));
    }

examples/basic_error.rs (line 16)

fn main() {
    // Create a simple error message
    let error = DiagnosticMessage::error("File not found");

    // Render to text
    println!("{}", error.to_text(None));
    println!();

    // Create a warning
    let warning = DiagnosticMessage::warning("Deprecated feature used");
    println!("{}", warning.to_text(None));
    println!();

    // Create an info message
    let info = DiagnosticMessage::info("Processing 42 files");
    println!("{}", info.to_text(None));
}

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

Create an info diagnostic.

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

Examples found in repository

examples/basic_error.rs (line 21)

fn main() {
    // Create a simple error message
    let error = DiagnosticMessage::error("File not found");

    // Render to text
    println!("{}", error.to_text(None));
    println!();

    // Create a warning
    let warning = DiagnosticMessage::warning("Deprecated feature used");
    println!("{}", warning.to_text(None));
    println!();

    // Create an info message
    let info = DiagnosticMessage::info("Processing 42 files");
    println!("{}", info.to_text(None));
}

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"));

Examples found in repository

examples/diagnostic_collector.rs (line 56)

    fn to_text(&self, ctx: Option<&SourceContext>) -> Vec<String> {
        self.diagnostics.iter().map(|d| d.to_text(ctx)).collect()
    }

examples/basic_error.rs (line 12)

fn main() {
    // Create a simple error message
    let error = DiagnosticMessage::error("File not found");

    // Render to text
    println!("{}", error.to_text(None));
    println!();

    // Create a warning
    let warning = DiagnosticMessage::warning("Deprecated feature used");
    println!("{}", warning.to_text(None));
    println!();

    // Create an info message
    let info = DiagnosticMessage::info("Processing 42 files");
    println!("{}", info.to_text(None));
}

examples/builder_api.rs (line 17)

fn main() {
    println!("=== Example 1: Simple builder usage ===\n");

    let error1 = DiagnosticMessageBuilder::error("Invalid input")
        .problem("Value must be numeric")
        .add_detail("Found text in column 3")
        .add_hint("Check the input file format")
        .build();

    println!("{}", error1.to_text(None));

    println!("\n=== Example 2: Tidyverse four-part structure ===\n");

    let error2 = DiagnosticMessageBuilder::error("Incompatible types")
        .problem("Cannot combine date and datetime types")
        .add_detail("`x` has type `date`")
        .add_detail("`y` has type `datetime`")
        .add_info("Both values come from the same data source")
        .add_hint("Convert both to the same type first?")
        .build();

    println!("{}", error2.to_text(None));

    println!("\n=== Example 3: Multiple details and hints ===\n");

    let error3 = DiagnosticMessageBuilder::error("Schema validation failed")
        .problem("Configuration does not match expected schema")
        .add_detail("Property `title` has type `number`")
        .add_detail("Expected type is `string`")
        .add_detail("Property `author` is missing")
        .add_info("Schema is defined in `_quarto.yml`")
        .add_hint("Did you forget quotes around the title?")
        .add_hint("Add an `author` field to the configuration")
        .build();

    println!("{}", error3.to_text(None));

    println!("\n=== Example 4: Builder validation ===\n");

    // This will trigger validation warnings
    let (msg, warnings) = DiagnosticMessageBuilder::error("Validation test")
        .add_detail("Detail 1")
        .add_detail("Detail 2")
        .add_detail("Detail 3")
        .add_detail("Detail 4")
        .add_detail("Detail 5")
        .add_detail("Detail 6") // Too many!
        .build_with_validation();

    println!("{}", msg.to_text(None));

    if !warnings.is_empty() {
        println!("\nValidation warnings:");
        for warning in warnings {
            println!("  ⚠ {}", warning);
        }
    }
}

examples/with_location.rs (line 32)

fn main() {
    println!("=== Example 1: Error with source location ===\n");

    // Create a source context
    let mut ctx = SourceContext::new();
    let file_id = ctx.add_file(
        "example.qmd".to_string(),
        Some("title: My Document\nauthor: John Doe\ndate: 2024-01-01\n".to_string()),
    );

    // Create a location (let's say there's an error in "My Document" - offsets 7 to 18)
    let location = SourceInfo::original(file_id, 7, 18);

    let error = DiagnosticMessageBuilder::error("Invalid title format")
        .with_code("Q-1-10")
        .with_location(location)
        .problem("Title must be a string, not a complex object")
        .add_detail("Title value starts at this location")
        .add_hint("Ensure the title is a simple quoted string")
        .build();

    // Render WITHOUT context - shows offset
    println!("Without context:");
    println!("{}", error.to_text(None));

    println!("\n---\n");

    // Render WITH context - shows file path and line:column
    println!("With context:");
    println!("{}", error.to_text(Some(&ctx)));

    println!("\n=== Example 2: Multiple locations ===\n");

    let another_ctx = SourceContext::new();

    // Note: This example shows the API, but without actual file content,
    // the rendering will still show offsets. In real usage with proper
    // SourceContext, this would show rich source snippets via ariadne.

    let location2 = SourceInfo::original(quarto_source_map::FileId(0), 100, 110);

    let error2 = DiagnosticMessageBuilder::error("Unclosed code block")
        .with_code("Q-2-301")
        .with_location(location2)
        .problem("Code block started but never closed")
        .add_detail("The opening ``` was found but no closing ``` before end of block")
        .add_hint("Add a closing ``` on a new line")
        .build();

    println!("{}", error2.to_text(Some(&another_ctx)));

    println!("\n=== Example 3: JSON output with location ===\n");

    let json = error.to_json();
    println!("{}", serde_json::to_string_pretty(&json).unwrap());
}

examples/migration_helpers.rs (line 18)

fn main() {
    println!("=== Example 1: Using generic_error! macro ===\n");

    // The generic_error! macro creates a DiagnosticMessage with:
    // - Code: Q-0-99 (generic migration error)
    // - File and line number where the macro was invoked
    // - The provided message
    let error = generic_error!("Something went wrong during migration");

    println!("{}", error.to_text(None));
    println!();

    // Check the error code
    println!("Error code: {:?}", error.code);
    println!();

    println!("=== Example 2: Using generic_warning! macro ===\n");

    let warning = generic_warning!("This feature is not yet fully migrated");

    println!("{}", warning.to_text(None));
    println!();

    println!("=== Example 3: Migration pattern in practice ===\n");

    // During migration, you might replace old error handling like this:
    //
    // OLD CODE:
    //   eprintln!("Error: File not found: {}", path);
    //   return Err(...);
    //
    // NEW CODE (migration phase):
    //   let error = generic_error!(format!("File not found: {}", path));
    //   eprintln!("{}", error.to_text(None));
    //   return Err(...);
    //
    // FINAL CODE:
    //   let error = DiagnosticMessageBuilder::error("File not found")
    //       .with_code("Q-X-Y")  // Proper error code
    //       .problem(format!("Could not open file: {}", path))
    //       .add_hint("Check that the file exists and you have permission")
    //       .build();

    let path = "/nonexistent/file.qmd";
    let migration_error = generic_error!(format!("File not found: {}", path));

    println!("Migration-style error:");
    println!("{}", migration_error.to_text(None));
    println!();

    println!("=== Example 4: JSON output shows file/line info ===\n");

    let error_with_location = generic_error!("Error with source tracking");
    let json = error_with_location.to_json();

    println!("{}", serde_json::to_string_pretty(&json).unwrap());
    println!();

    println!("Note: The generic_error! and generic_warning! macros are intended");
    println!("for migration purposes only. New code should use DiagnosticMessageBuilder");
    println!("with proper error codes (Q-X-Y) instead of Q-0-99.");
}

examples/custom_rendering.rs (line 28)

fn main() {
    println!("=== Example 1: Default rendering (with hyperlinks) ===\n");

    let mut ctx = SourceContext::new();
    let file_id = ctx.add_file(
        "document.qmd".to_string(),
        Some("# My Document\n\nSome content here.\n".to_string()),
    );

    let location = SourceInfo::original(file_id, 15, 27);

    let error = DiagnosticMessageBuilder::error("Parse error")
        .with_code("Q-2-100")
        .with_location(location)
        .problem("Invalid markdown syntax")
        .add_hint("Check the markdown formatting")
        .build();

    // Default rendering includes OSC 8 hyperlinks for file paths
    let default_text = error.to_text(Some(&ctx));
    println!("{}", default_text);

    println!("\n=== Example 2: Rendering without hyperlinks (for tests) ===\n");

    // Disable hyperlinks - useful for snapshot testing where absolute paths
    // would cause differences between machines
    let options = TextRenderOptions {
        enable_hyperlinks: false,
    };

    let no_hyperlink_text = error.to_text_with_options(Some(&ctx), &options);
    println!("{}", no_hyperlink_text);

    println!("\n=== Example 3: Comparing outputs ===\n");

    // Show the difference in output
    println!("With hyperlinks enabled:");
    println!("  Length: {} bytes", default_text.len());
    println!(
        "  Contains OSC 8 codes: {}",
        default_text.contains("\x1b]8;")
    );

    println!("\nWith hyperlinks disabled:");
    println!("  Length: {} bytes", no_hyperlink_text.len());
    println!(
        "  Contains OSC 8 codes: {}",
        no_hyperlink_text.contains("\x1b]8;")
    );

    println!("\n=== Example 4: JSON output (no hyperlinks) ===\n");

    let json = error.to_json();
    println!("{}", serde_json::to_string_pretty(&json).unwrap());

    println!("\n=== Example 5: Multiple diagnostics with custom rendering ===\n");

    let error2 = DiagnosticMessageBuilder::error("Type mismatch")
        .with_code("Q-1-15")
        .problem("Expected string, found number")
        .add_detail("Value: 42")
        .add_detail("Expected type: string")
        .build();

    let error3 = DiagnosticMessageBuilder::error("Missing field")
        .with_code("Q-1-20")
        .problem("Required field 'author' not found")
        .add_hint("Add an 'author' field to your configuration")
        .build();

    let errors = [error, error2, error3];

    // Render all with consistent options
    let no_hyperlinks = TextRenderOptions {
        enable_hyperlinks: false,
    };

    for (i, err) in errors.iter().enumerate() {
        println!("Error {}:", i + 1);
        println!("{}", err.to_text_with_options(Some(&ctx), &no_hyperlinks));
        println!();
    }
}

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"));

Examples found in repository

examples/custom_rendering.rs (line 39)

fn main() {
    println!("=== Example 1: Default rendering (with hyperlinks) ===\n");

    let mut ctx = SourceContext::new();
    let file_id = ctx.add_file(
        "document.qmd".to_string(),
        Some("# My Document\n\nSome content here.\n".to_string()),
    );

    let location = SourceInfo::original(file_id, 15, 27);

    let error = DiagnosticMessageBuilder::error("Parse error")
        .with_code("Q-2-100")
        .with_location(location)
        .problem("Invalid markdown syntax")
        .add_hint("Check the markdown formatting")
        .build();

    // Default rendering includes OSC 8 hyperlinks for file paths
    let default_text = error.to_text(Some(&ctx));
    println!("{}", default_text);

    println!("\n=== Example 2: Rendering without hyperlinks (for tests) ===\n");

    // Disable hyperlinks - useful for snapshot testing where absolute paths
    // would cause differences between machines
    let options = TextRenderOptions {
        enable_hyperlinks: false,
    };

    let no_hyperlink_text = error.to_text_with_options(Some(&ctx), &options);
    println!("{}", no_hyperlink_text);

    println!("\n=== Example 3: Comparing outputs ===\n");

    // Show the difference in output
    println!("With hyperlinks enabled:");
    println!("  Length: {} bytes", default_text.len());
    println!(
        "  Contains OSC 8 codes: {}",
        default_text.contains("\x1b]8;")
    );

    println!("\nWith hyperlinks disabled:");
    println!("  Length: {} bytes", no_hyperlink_text.len());
    println!(
        "  Contains OSC 8 codes: {}",
        no_hyperlink_text.contains("\x1b]8;")
    );

    println!("\n=== Example 4: JSON output (no hyperlinks) ===\n");

    let json = error.to_json();
    println!("{}", serde_json::to_string_pretty(&json).unwrap());

    println!("\n=== Example 5: Multiple diagnostics with custom rendering ===\n");

    let error2 = DiagnosticMessageBuilder::error("Type mismatch")
        .with_code("Q-1-15")
        .problem("Expected string, found number")
        .add_detail("Value: 42")
        .add_detail("Expected type: string")
        .build();

    let error3 = DiagnosticMessageBuilder::error("Missing field")
        .with_code("Q-1-20")
        .problem("Required field 'author' not found")
        .add_hint("Add an 'author' field to your configuration")
        .build();

    let errors = [error, error2, error3];

    // Render all with consistent options
    let no_hyperlinks = TextRenderOptions {
        enable_hyperlinks: false,
    };

    for (i, err) in errors.iter().enumerate() {
        println!("Error {}:", i + 1);
        println!("{}", err.to_text_with_options(Some(&ctx), &no_hyperlinks));
        println!();
    }
}

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"));

Examples found in repository

examples/renderer_selection.rs (line 41)

fn main() {
    let mut ctx = SourceContext::new();
    let source = "title: My Document\nformat:\n  html:\n    theme: nosuchtheme\n";
    let file_id = ctx.add_file("_quarto.yml".to_string(), Some(source.to_string()));

    // Point at `nosuchtheme` on line 4 (byte offsets into `source`).
    let start = source.find("nosuchtheme").unwrap();
    let location = SourceInfo::original(file_id, start, start + "nosuchtheme".len());

    let diag = DiagnosticMessageBuilder::error("Unknown theme")
        .with_code("Q-14-1")
        .with_location(location)
        .problem("`nosuchtheme` is not a known Quarto theme")
        .add_hint("Did you mean `cosmo`, `darkly`, or `flatly`?")
        .build();

    // Disable hyperlinks so the output is path-stable in a demo.
    let opts = TextRenderOptions {
        enable_hyperlinks: false,
    };

    // `None` uses the default renderer for the enabled features.
    println!("=== default renderer (None) ===\n");
    println!("{}", diag.to_text_with_renderer(Some(&ctx), &opts, None));

    #[cfg(feature = "ariadne")]
    {
        println!("=== SourceRenderer::Ariadne ===\n");
        println!(
            "{}",
            diag.to_text_with_renderer(Some(&ctx), &opts, Some(SourceRenderer::Ariadne))
        );
    }

    #[cfg(feature = "annotate-snippets")]
    {
        println!("=== SourceRenderer::AnnotateSnippets ===\n");
        println!(
            "{}",
            diag.to_text_with_renderer(Some(&ctx), &opts, Some(SourceRenderer::AnnotateSnippets),)
        );
    }
}

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");

Examples found in repository

examples/with_location.rs (line 62)

fn main() {
    println!("=== Example 1: Error with source location ===\n");

    // Create a source context
    let mut ctx = SourceContext::new();
    let file_id = ctx.add_file(
        "example.qmd".to_string(),
        Some("title: My Document\nauthor: John Doe\ndate: 2024-01-01\n".to_string()),
    );

    // Create a location (let's say there's an error in "My Document" - offsets 7 to 18)
    let location = SourceInfo::original(file_id, 7, 18);

    let error = DiagnosticMessageBuilder::error("Invalid title format")
        .with_code("Q-1-10")
        .with_location(location)
        .problem("Title must be a string, not a complex object")
        .add_detail("Title value starts at this location")
        .add_hint("Ensure the title is a simple quoted string")
        .build();

    // Render WITHOUT context - shows offset
    println!("Without context:");
    println!("{}", error.to_text(None));

    println!("\n---\n");

    // Render WITH context - shows file path and line:column
    println!("With context:");
    println!("{}", error.to_text(Some(&ctx)));

    println!("\n=== Example 2: Multiple locations ===\n");

    let another_ctx = SourceContext::new();

    // Note: This example shows the API, but without actual file content,
    // the rendering will still show offsets. In real usage with proper
    // SourceContext, this would show rich source snippets via ariadne.

    let location2 = SourceInfo::original(quarto_source_map::FileId(0), 100, 110);

    let error2 = DiagnosticMessageBuilder::error("Unclosed code block")
        .with_code("Q-2-301")
        .with_location(location2)
        .problem("Code block started but never closed")
        .add_detail("The opening ``` was found but no closing ``` before end of block")
        .add_hint("Add a closing ``` on a new line")
        .build();

    println!("{}", error2.to_text(Some(&another_ctx)));

    println!("\n=== Example 3: JSON output with location ===\n");

    let json = error.to_json();
    println!("{}", serde_json::to_string_pretty(&json).unwrap());
}

examples/migration_helpers.rs (line 62)

fn main() {
    println!("=== Example 1: Using generic_error! macro ===\n");

    // The generic_error! macro creates a DiagnosticMessage with:
    // - Code: Q-0-99 (generic migration error)
    // - File and line number where the macro was invoked
    // - The provided message
    let error = generic_error!("Something went wrong during migration");

    println!("{}", error.to_text(None));
    println!();

    // Check the error code
    println!("Error code: {:?}", error.code);
    println!();

    println!("=== Example 2: Using generic_warning! macro ===\n");

    let warning = generic_warning!("This feature is not yet fully migrated");

    println!("{}", warning.to_text(None));
    println!();

    println!("=== Example 3: Migration pattern in practice ===\n");

    // During migration, you might replace old error handling like this:
    //
    // OLD CODE:
    //   eprintln!("Error: File not found: {}", path);
    //   return Err(...);
    //
    // NEW CODE (migration phase):
    //   let error = generic_error!(format!("File not found: {}", path));
    //   eprintln!("{}", error.to_text(None));
    //   return Err(...);
    //
    // FINAL CODE:
    //   let error = DiagnosticMessageBuilder::error("File not found")
    //       .with_code("Q-X-Y")  // Proper error code
    //       .problem(format!("Could not open file: {}", path))
    //       .add_hint("Check that the file exists and you have permission")
    //       .build();

    let path = "/nonexistent/file.qmd";
    let migration_error = generic_error!(format!("File not found: {}", path));

    println!("Migration-style error:");
    println!("{}", migration_error.to_text(None));
    println!();

    println!("=== Example 4: JSON output shows file/line info ===\n");

    let error_with_location = generic_error!("Error with source tracking");
    let json = error_with_location.to_json();

    println!("{}", serde_json::to_string_pretty(&json).unwrap());
    println!();

    println!("Note: The generic_error! and generic_warning! macros are intended");
    println!("for migration purposes only. New code should use DiagnosticMessageBuilder");
    println!("with proper error codes (Q-X-Y) instead of Q-0-99.");
}

examples/diagnostic_collector.rs (line 113)

fn main() {
    println!("=== Example 1: Accumulating multiple errors ===\n");

    let mut collector = SimpleCollector::new();

    // Simulate validating a YAML file
    collector.error("Missing required field 'title'");
    collector.warn("Field 'description' is deprecated");
    collector.error("Invalid value for 'format': expected string, got number");

    if collector.has_errors() {
        println!(
            "Validation failed with {} diagnostics:",
            collector.diagnostics().len()
        );
        for text in collector.to_text(None) {
            println!("{}", text);
        }
    }

    println!("\n=== Example 2: Errors with source locations ===\n");

    let mut ctx = SourceContext::new();
    let file_id = ctx.add_file(
        "config.yml".to_string(),
        Some("title: 123\nformat: html\nauthor: John\n".to_string()),
    );

    let mut collector2 = SimpleCollector::new();

    // Error in "title: 123" (offsets 7-10)
    let loc1 = SourceInfo::original(file_id, 7, 10);
    collector2.error_at("Title must be a string", loc1);

    // Warning at "John" (offsets 33-37)
    let loc2 = SourceInfo::original(file_id, 33, 37);
    let warning = DiagnosticMessageBuilder::warning("Author field should include email")
        .with_location(loc2)
        .add_hint("Use format: 'Name <email@example.com>'")
        .build();
    collector2.add(warning);

    println!("Collected diagnostics:");
    for text in collector2.to_text(Some(&ctx)) {
        println!("{}", text);
        println!();
    }

    println!("=== Example 3: JSON output for all diagnostics ===\n");

    let json_array: Vec<_> = collector2
        .diagnostics()
        .iter()
        .map(|d| d.to_json())
        .collect();

    println!("{}", serde_json::to_string_pretty(&json_array).unwrap());

    println!("\n=== Example 4: Continuing vs. failing fast ===\n");

    let mut collector3 = SimpleCollector::new();

    // In some subsystems, we collect all errors before failing
    for i in 1..=3 {
        collector3.error(format!("Error in item {}", i));
    }

    // Check at the end
    if collector3.has_errors() {
        eprintln!(
            "Processing failed with {} errors",
            collector3.diagnostics().len()
        );
        eprintln!("\nErrors:");
        for diag in collector3.diagnostics() {
            eprintln!("  - {}", diag.title);
        }
    }
}

examples/custom_rendering.rs (line 61)

fn main() {
    println!("=== Example 1: Default rendering (with hyperlinks) ===\n");

    let mut ctx = SourceContext::new();
    let file_id = ctx.add_file(
        "document.qmd".to_string(),
        Some("# My Document\n\nSome content here.\n".to_string()),
    );

    let location = SourceInfo::original(file_id, 15, 27);

    let error = DiagnosticMessageBuilder::error("Parse error")
        .with_code("Q-2-100")
        .with_location(location)
        .problem("Invalid markdown syntax")
        .add_hint("Check the markdown formatting")
        .build();

    // Default rendering includes OSC 8 hyperlinks for file paths
    let default_text = error.to_text(Some(&ctx));
    println!("{}", default_text);

    println!("\n=== Example 2: Rendering without hyperlinks (for tests) ===\n");

    // Disable hyperlinks - useful for snapshot testing where absolute paths
    // would cause differences between machines
    let options = TextRenderOptions {
        enable_hyperlinks: false,
    };

    let no_hyperlink_text = error.to_text_with_options(Some(&ctx), &options);
    println!("{}", no_hyperlink_text);

    println!("\n=== Example 3: Comparing outputs ===\n");

    // Show the difference in output
    println!("With hyperlinks enabled:");
    println!("  Length: {} bytes", default_text.len());
    println!(
        "  Contains OSC 8 codes: {}",
        default_text.contains("\x1b]8;")
    );

    println!("\nWith hyperlinks disabled:");
    println!("  Length: {} bytes", no_hyperlink_text.len());
    println!(
        "  Contains OSC 8 codes: {}",
        no_hyperlink_text.contains("\x1b]8;")
    );

    println!("\n=== Example 4: JSON output (no hyperlinks) ===\n");

    let json = error.to_json();
    println!("{}", serde_json::to_string_pretty(&json).unwrap());

    println!("\n=== Example 5: Multiple diagnostics with custom rendering ===\n");

    let error2 = DiagnosticMessageBuilder::error("Type mismatch")
        .with_code("Q-1-15")
        .problem("Expected string, found number")
        .add_detail("Value: 42")
        .add_detail("Expected type: string")
        .build();

    let error3 = DiagnosticMessageBuilder::error("Missing field")
        .with_code("Q-1-20")
        .problem("Required field 'author' not found")
        .add_hint("Add an 'author' field to your configuration")
        .build();

    let errors = [error, error2, error3];

    // Render all with consistent options
    let no_hyperlinks = TextRenderOptions {
        enable_hyperlinks: false,
    };

    for (i, err) in errors.iter().enumerate() {
        println!("Error {}:", i + 1);
        println!("{}", err.to_text_with_options(Some(&ctx), &no_hyperlinks));
        println!();
    }
}

Trait Implementations

impl Clone for DiagnosticMessage

fn clone(&self) -> DiagnosticMessage

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: &DiagnosticMessage) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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