runemark 0.1.1

Opinionated terminal presentation for Rust command-line tools
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

//! Structured diagnostic and error/prerequisite presentation blocks.

use crate::color::{Console, Tone};
use crate::verdict::Verdict;
use std::io::Write;

/// A structured error or prerequisite block providing actionable remedies.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ErrorBlock {
    /// Heading or summary of the prerequisite / error.
    pub heading: String,
    /// Explanation of why the error occurred.
    pub explanation: Option<String>,
    /// Step-by-step remedy or action to resolve the issue.
    pub remedy: Option<String>,
    /// Copyable shell commands or code snippets.
    pub commands: Vec<String>,
}

impl ErrorBlock {
    /// Creates a new error block with a heading.
    pub fn new(heading: impl Into<String>) -> Self {
        Self {
            heading: heading.into(),
            explanation: None,
            remedy: None,
            commands: Vec::new(),
        }
    }

    /// Sets the detailed explanation text.
    pub fn with_explanation(mut self, text: impl Into<String>) -> Self {
        self.explanation = Some(text.into());
        self
    }

    /// Sets the remedy guidance text.
    pub fn with_remedy(mut self, text: impl Into<String>) -> Self {
        self.remedy = Some(text.into());
        self
    }

    /// Adds a copyable command snippet.
    pub fn add_command(mut self, command: impl Into<String>) -> Self {
        self.commands.push(command.into());
        self
    }

    /// Writes the error block directly to a writer.
    pub fn write_to(
        &self,
        console: Console,
        writer: &mut (impl Write + ?Sized),
    ) -> std::io::Result<()> {
        Verdict::Failed.write_to(console, &self.heading, writer)?;
        writeln!(writer)?;

        if let Some(ref exp) = self.explanation {
            write!(writer, "  ")?;
            console.write_paint(Tone::Muted, exp, writer)?;
            writeln!(writer)?;
        }

        if let Some(ref remedy) = self.remedy {
            writeln!(writer)?;
            write!(writer, "  ")?;
            console.write_paint(Tone::Warning, "Remedy:", writer)?;
            writeln!(writer, " {remedy}")?;
        }

        if !self.commands.is_empty() {
            writeln!(writer)?;
            for cmd in &self.commands {
                write!(writer, "  ")?;
                console.write_paint(Tone::Info, format!("$ {cmd}"), writer)?;
                writeln!(writer)?;
            }
        }

        Ok(())
    }

    /// Renders the error block as a formatted String.
    pub fn render(&self, console: Console) -> String {
        let mut buf = Vec::new();
        let _ = self.write_to(console, &mut buf);
        String::from_utf8(buf).unwrap_or_default()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::color::ColorMode;

    #[test]
    fn error_block_rendering() {
        let block = ErrorBlock::new("Required toolchain is unavailable")
            .with_explanation("The configured version is not installed.")
            .with_remedy("Install the required toolchain:")
            .add_command("toolchain install stable");

        let console = Console::new(ColorMode::Never, false);
        let output = block.render(console);
        assert!(output.contains("[FAIL] Required toolchain is unavailable"));
        assert!(output.contains("The configured version is not installed."));
        assert!(output.contains("Remedy: Install the required toolchain:"));
        assert!(output.contains("$ toolchain install stable"));
    }
}