Struct FailureReport 

pub struct FailureReport {
    pub operation: Operation,
    pub shell: Shell,
    pub target_path: Option<PathBuf>,
    pub affected_locations: Vec<PathBuf>,
    pub kind: FailureKind,
    pub file_change: Option<FileChange>,
    pub activation: Option<ActivationReport>,
    pub cleanup: Option<CleanupReport>,
    pub reason: String,
    pub next_step: Option<String>,
    pub trace_id: u64,
}

Structured failure report for recoverable operational errors.

shellcomp uses this report to preserve partial state like completion file changes or manual recovery instructions. It is wrapped by crate::Error::Failure.

Examples

use std::path::PathBuf;

use shellcomp::{Error, FailureKind, InstallRequest, Shell, install};

let error = install(InstallRequest {
    shell: Shell::Fish,
    program_name: "demo",
    script: b"complete -c demo\n",
    path_override: Some(PathBuf::from("/")),
})
.expect_err("path without parent should fail");

let report = error
    .as_failure()
    .expect("path without parent should fail");
assert_eq!(report.kind, FailureKind::InvalidTargetPath);
assert!(report.reason.contains("does not have a parent directory"));

Fields

operation: Operation

Operation that failed.

shell: Shell

Target shell.

target_path: Option<PathBuf>

Path involved in the failure when known.

This is usually the completion file target path, not necessarily the shell startup file that caused the failure.

affected_locations: Vec<PathBuf>

Related locations inspected or mutated before the failure.

This may include both the completion target path and shell-specific locations such as ~/.bashrc or ~/.zshrc.

kind: FailureKind

Stable failure kind for programmatic branching.

file_change: Option<FileChange>

Outcome of the completion file change before the failure occurred, when available.

This is especially useful during install failures where the completion file may already have been written successfully before shell activation wiring failed.

activation: Option<ActivationReport>

Activation state or fallback guidance known at failure time, when available.

For example, a failed Bash/Zsh install may still return a manual activation recommendation.

cleanup: Option<CleanupReport>

Cleanup state known at failure time, when available.

reason: String

Human-readable failure reason.

next_step: Option<String>

Suggested next step for recovery or manual completion.

trace_id: u64

Invocation-scoped id generated for error correlation.

Implementations

impl FailureReport

pub const fn error_code(&self) -> &'static str

Stable machine-readable error code for structured telemetry.

pub const fn is_retryable(&self) -> bool

Returns whether the failure may succeed after environment correction or retry.

Trait Implementations

impl Clone for FailureReport

fn clone(&self) -> FailureReport

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FailureReport

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

Formats the value using the given formatter.

impl PartialEq for FailureReport

fn eq(&self, other: &FailureReport) -> 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 Eq for FailureReport

impl StructuralPartialEq for FailureReport