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

Document Anchors

A Diagnostic can carry two independent “where” anchors, both optional:

• Diagnostic::location — a source-text anchor (file:line:column). Produced by parsers and backend compilers that operate on raw text.
• Diagnostic::path — a document-model anchor pointing into the typed crate::document::Document. Produced by schema validation and coercion, which run on the typed model after line spans are gone.

Path grammar

path        := segment ( "." field_name | "[" index "]" )*
field_name  := [a-z_][a-z0-9_]*       // same charset enforced for fields/tags
index       := [0-9]+

Because field and leaf tag names are validated to that charset (no ., [, ], or whitespace can appear in any segment), the dotted form round-trips unambiguously.

Path conventions

Anchor	Path
Main frontmatter field	title
Nested in array of objects	recipients[0].name
Main leaf body	main.body
Typed leaf (whole)	leaves.indorsement[0]
Field on typed leaf	leaves.indorsement[0].signature_block
Body on typed leaf	leaves.indorsement[0].body
Leaf with unknown tag	leaves[0]

The leaves.<tag>[<index>] form fuses the leaf tag and the document array index into one segment so consumers receive both pieces of information without a second lookup.

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_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_LEAF_COUNT

Maximum number of KIND blocks allowed per document Prevents memory exhaustion from documents with excessive leaf blocks

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