Enum XCheckerError 

pub enum XCheckerError {
    Config(ConfigError),
    Phase(PhaseError),
    Claude(ClaudeError),
    Runner(RunnerError),
    Io(Error),
    SecretDetected {
        pattern: String,
        location: String,
    },
    PacketOverflow {
        used_bytes: usize,
        used_lines: usize,
        limit_bytes: usize,
        limit_lines: usize,
    },
    ConcurrentExecution {
        id: String,
    },
    PacketPreviewTooLarge {
        size: usize,
    },
    CanonicalizationFailed {
        phase: String,
        reason: String,
    },
    ReceiptWriteFailed {
        path: String,
        reason: String,
    },
    ModelResolutionError {
        alias: String,
        resolved: String,
        reason: String,
    },
    Source(SourceError),
    Fixup(FixupError),
    SpecId(SpecIdError),
    Lock(LockError),
    Llm(LlmError),
    ValidationFailed {
        phase: String,
        issues: Vec<ValidationError>,
        issue_count: usize,
    },
}

Library-level error type with rich context and user-friendly reporting.

XCheckerError is the primary error type returned by xchecker library operations. It provides:

• Detailed error information for programmatic handling
• User-friendly messages with context and suggestions
• Mapping to CLI exit codes for consistent error reporting

Error Categories

Errors are organized into categories for better handling:

Category	Description
Config	Configuration file or CLI argument errors
Phase	Phase execution failures
Claude	Claude CLI integration errors
Runner	Process execution errors
SecretDetected	Security: secrets found in content
PacketOverflow	Resource: packet size exceeded
Lock	Concurrency: lock already held

Exit Code Mapping

Use to_exit_code() to map errors to CLI exit codes:

Exit Code	Error Type
2	Configuration/CLI argument errors
7	Packet overflow
8	Secret detected
9	Lock held
10	Phase timeout
70	Claude CLI failure
1	Other errors

User-Friendly Messages

Use display_for_user() to get formatted error messages suitable for end users, including context and actionable suggestions.

Example

use xchecker_utils::error::XCheckerError;
use xchecker_utils::exit_codes::ExitCode;

fn handle_error(err: XCheckerError) {
    // Get user-friendly message
    eprintln!("{}", err.display_for_user());
     
    // Map to exit code for CLI
    let code = err.to_exit_code();
    std::process::exit(code.as_i32());
}

Library vs CLI Usage

• Library consumers: Handle XCheckerError directly, use to_exit_code() if needed
• CLI: Maps errors to exit codes and displays user-friendly messages

Library code returns XCheckerError and does NOT call std::process::exit().

Variants

Config(ConfigError)

Phase(PhaseError)

Claude(ClaudeError)

Runner(RunnerError)

Io(Error)

SecretDetected

Fields

pattern: String

location: String

PacketOverflow

Fields

used_bytes: usize

used_lines: usize

limit_bytes: usize

limit_lines: usize

ConcurrentExecution

Fields

id: String

PacketPreviewTooLarge

Fields

size: usize

CanonicalizationFailed

Fields

phase: String

reason: String

ReceiptWriteFailed

Fields

path: String

reason: String

ModelResolutionError

Fields

alias: String

resolved: String

reason: String

Source(SourceError)

Fixup(FixupError)

SpecId(SpecIdError)

Lock(LockError)

Llm(LlmError)

ValidationFailed

Fields

phase: String

issues: Vec<ValidationError>

issue_count: usize

Implementations

impl XCheckerError

pub fn display_for_user(&self) -> String

Get a user-friendly error message with context and actionable suggestions.

This method combines the error message, context, and suggestions into a single formatted string suitable for display to end users. The format is:

Error: <user message>

Context: <context if available>

Suggestions:
  • <suggestion 1>
  • <suggestion 2>
  ...

Example

use xchecker_utils::error::XCheckerError;

let err = XCheckerError::SecretDetected {
    pattern: "ghp_".to_string(),
    location: "test.txt".to_string(),
};
let message = err.display_for_user();
assert!(message.contains("Security issue"));
assert!(message.contains("Suggestions:"));

pub fn display_for_user_with_redactor( &self, redactor: &SecretRedactor, ) -> String

Get a user-friendly error message with context and actionable suggestions, applying a caller-provided redactor as a final safety net (FR-SEC-19).

pub fn to_exit_code(&self) -> ExitCode

Map this error to the appropriate CLI exit code.

This is the single source of truth for both CLI exit codes and receipt exit_code fields. The mapping follows the documented exit code table:

Exit Code	Name	Description
0	SUCCESS	Completed successfully
1	INTERNAL	General failure
2	CLI_ARGS	Invalid CLI arguments
7	PACKET_OVERFLOW	Packet size exceeded
8	SECRET_DETECTED	Secret found in content
9	LOCK_HELD	Lock already held
10	PHASE_TIMEOUT	Phase timed out
70	CLAUDE_FAILURE	Claude CLI failed

Example

use xchecker_utils::error::XCheckerError;
use xchecker_utils::exit_codes::ExitCode;

let err = XCheckerError::SecretDetected {
    pattern: "ghp_".to_string(),
    location: "test.txt".to_string(),
};
assert_eq!(err.to_exit_code(), ExitCode::SECRET_DETECTED);

Trait Implementations

impl Debug for XCheckerError

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

Formats the value using the given formatter.

impl Display for XCheckerError

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

Formats the value using the given formatter.

impl Error for XCheckerError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<ClaudeError> for XCheckerError

fn from(source: ClaudeError) -> XCheckerError

Converts to this type from the input type.

impl From<ConfigError> for XCheckerError

fn from(source: ConfigError) -> XCheckerError

Converts to this type from the input type.

impl From<Error> for XCheckerError

fn from(source: Error) -> XCheckerError

Converts to this type from the input type.

impl From<FixupError> for XCheckerError

fn from(source: FixupError) -> XCheckerError

Converts to this type from the input type.

impl From<LlmError> for XCheckerError

fn from(source: LlmError) -> XCheckerError

Converts to this type from the input type.

impl From<LockError> for XCheckerError

fn from(source: LockError) -> XCheckerError

Converts to this type from the input type.

impl From<PhaseError> for XCheckerError

fn from(source: PhaseError) -> XCheckerError

Converts to this type from the input type.

impl From<RunnerError> for XCheckerError

fn from(source: RunnerError) -> XCheckerError

Converts to this type from the input type.

impl From<SourceError> for XCheckerError

fn from(source: SourceError) -> XCheckerError

Converts to this type from the input type.

impl From<SpecIdError> for XCheckerError

fn from(source: SpecIdError) -> XCheckerError

Converts to this type from the input type.

impl UserFriendlyError for XCheckerError

fn user_message(&self) -> String

Get a user-friendly error message

fn context(&self) -> Option<String>

Get contextual information about the error

fn suggestions(&self) -> Vec<String>

Get suggested actions to resolve the error

fn category(&self) -> ErrorCategory

Get the error category for grouping similar errors