Module error 

Error types for mdbook-lint

This module provides a comprehensive error system that replaces the use of anyhow::Error with structured, programmatically-handleable error types. This enables better API design and error recovery for library consumers.

Architecture Overview

The error system is built around several key principles:

1. Structured Errors: Each error variant contains specific contextual information
2. Error Categories: Errors are grouped by domain (Rule, Document, Config, etc.)
3. Conversion Traits: Seamless conversion between specialized and general error types
4. Context Addition: Rich context can be added at any point in the error chain
5. Compatibility: Smooth migration path from anyhow with compatibility layers

Error Hierarchy

MdBookLintError (main error type)
├── Io(std::io::Error)              - File system operations
├── Parse { line, column, message } - Document parsing errors
├── Config(String)                  - Configuration issues
├── Rule { rule_id, message }       - Rule execution problems
├── Plugin(String)                  - Plugin system errors
├── Document(String)                - Document processing errors
├── Registry(String)                - Rule registry operations
├── Json(serde_json::Error)         - JSON serialization errors
├── Yaml(serde_yaml::Error)         - YAML serialization errors
└── Toml(toml::de::Error)           - TOML serialization errors

Usage Examples

Basic Error Creation

use mdbook_lint_core::error::{MdBookLintError, Result};

// Create specific errors
let parse_err = MdBookLintError::parse_error(10, 5, "Invalid syntax");
let rule_err = MdBookLintError::rule_error("MD001", "Heading increment violation");
let config_err = MdBookLintError::config_error("Invalid rule configuration");

Error Matching and Handling

use mdbook_lint_core::error::MdBookLintError;

fn handle_error(err: MdBookLintError) {
    match err {
        MdBookLintError::Parse { line, column, message } => {
            eprintln!("Parse error at {}:{}: {}", line, column, message);
        }
        MdBookLintError::Rule { rule_id, message } => {
            eprintln!("Rule {} failed: {}", rule_id, message);
        }
        MdBookLintError::Io(io_err) => {
            eprintln!("IO error: {}", io_err);
        }
        _ => eprintln!("Unknown error: {}", err),
    }
}

Adding Context

use mdbook_lint_core::error::{ErrorContext, Result};

fn process_rule() -> Result<()> {
    // ... some operation that might fail
}

let result = process_rule().with_rule_context("MD001");

Specialized Error Types

For domain-specific operations, use the specialized error types:

use mdbook_lint_core::error::{RuleError, DocumentError, IntoMdBookLintError};

// Create specialized errors
let rule_err = RuleError::not_found("MD999");
let doc_err = DocumentError::too_large(1000000, 500000);

// Convert to main error type
let result: std::result::Result<(), _> = Err(rule_err);
let main_result = result.into_mdbook_lint_error();

Migration from anyhow

This module provides compatibility layers to ease migration:

1. Fromanyhow::Error: Convert anyhow errors to MdBookLintError
2. Blanket conversion: MdBookLintError implements std::error::Error, so anyhow can convert it back
3. Result type alias: Drop-in replacement for anyhow::Result

Performance Considerations

• Zero-cost when successful: Error types only allocate when errors occur
• Structured data: No string parsing needed to extract error information
• Efficient matching: Enum variants enable efficient error handling
• Context preservation: Rich context without performance penalty in success cases

Enums

ConfigError

Specialized error type for configuration operations

DocumentError

Specialized error type for document-related operations

MdBookLintError

Main error type for mdbook-lint operations

PluginError

Specialized error type for plugin operations

RuleError

Specialized error type for rule-related operations

Traits

ErrorContext

Error context extension trait for adding contextual information to errors

IntoMdBookLintError

Extension trait for converting specialized errors to MdBookLintError

Type Aliases

MdlntError

Compatibility alias for the old error name

Result

Result type alias for mdbook-lint operations