Module error 

Error Handling

Structured error handling with diagnostics and source location tracking.

Overview

The error module provides error types and diagnostic types for actionable error reporting with source location tracking.

Key Types

• RenderError: Main error enum for rendering operations
• Diagnostic: Structured diagnostic information
• Location: Source file location (file, line, column)
• Severity: Error severity levels (Error, Warning, Note)
• RenderResult: Result type with artifacts and warnings

Error Hierarchy

RenderError Variants

• RenderError::EngineCreation: Failed to create rendering engine
• RenderError::InvalidFrontmatter: Malformed YAML frontmatter
• RenderError::CompilationFailed: Backend compilation errors
• RenderError::FormatNotSupported: Requested format not supported
• RenderError::UnsupportedBackend: Backend not registered
• RenderError::ValidationFailed: Field coercion/validation failure
• RenderError::QuillConfig: Quill configuration error

Examples

Creating Diagnostics

use quillmark_core::{Diagnostic, Location, Severity};

let diag = Diagnostic::new(Severity::Error, "Undefined variable".to_string())
    .with_code("E001".to_string())
    .with_location(Location {
        file: "template.typ".to_string(),
        line: 10,
        column: 5,
    })
    .with_hint("Check variable spelling".to_string());

println!("{}", diag.fmt_pretty());

Example output:

[ERROR] Undefined variable (E001) at template.typ:10:5
  hint: Check variable spelling

Result with Warnings

let result = RenderResult::new(artifacts, OutputFormat::Pdf)
    .with_warning(Diagnostic::new(
        Severity::Warning,
        "Deprecated field used".to_string(),
    ));

Pretty Printing

The Diagnostic type provides Diagnostic::fmt_pretty() for human-readable output with error code, location, and hints.

Machine-Readable Output

All diagnostic types implement serde::Serialize for JSON export:

let json = serde_json::to_string(&diagnostic).unwrap();

Re-exports

pub use crate::document::limits::MAX_YAML_DEPTH;

Structs

Diagnostic

Structured diagnostic information.

Location

Location information for diagnostics

RenderResult

Result type containing artifacts and warnings

Enums

ParseError

Error type for parsing operations

RenderError

Main error type for rendering operations.

Severity

Error severity levels

Constants

MAX_CARD_COUNT

Maximum number of CARD blocks allowed per document Prevents memory exhaustion from documents with excessive card blocks

MAX_FIELD_COUNT

Maximum number of fields allowed per document Prevents memory exhaustion from documents with excessive fields

MAX_INPUT_SIZE

Maximum input size for markdown (10 MB)

MAX_NESTING_DEPTH

Maximum nesting depth for markdown structures (100 levels)

MAX_YAML_SIZE

Maximum YAML size (1 MB)

Functions

print_errors

Helper to print structured errors