relux-runtime 0.8.0

use std::io::Write;
use std::path::Path;
use std::path::PathBuf;
use std::time::Duration;

use colored::Colorize;

use relux_core::diagnostics::IrSpan;
use relux_ir::IrTimeout;

use crate::cancel::CancelReason;
use crate::observe::structured::EventSeq;
use crate::observe::structured::MatchContext;
use crate::observe::structured::SpanId;
use crate::observe::structured::StackFrame;
use crate::observe::structured::StructuredLogBuilder;
use crate::observe::structured::log_sink::LogSink;

/// Diagnostic context captured at failure-construction time. Travels with
/// every `Failure` so that downstream consumers (structured-log artifact,
/// console error renderer) can render the call site, what arrived in the
/// shell, and which user vars were live - without needing to reach back
/// into a VM that is about to be dropped.
///
/// The variant makes the failure's provenance explicit. `Vm` carries the
/// full diagnostic picture; `PreVm` represents failures raised outside any
/// VM (effect resolution, shell-block lookup, cleanup-shell spawn,
/// pre-init PTY spawn) and carries only the surrounding span, when one is
/// known. The structured-log builder flattens both variants into a single
/// on-disk shape via the accessor methods.
#[derive(Debug, Clone)]
pub enum FailureContext {
    /// Captured by a running VM at failure-construction time.
    Vm {
        span: SpanId,
        event_seq: EventSeq,
        call_stack: Vec<StackFrame>,
        buffer_tail: String,
        vars_in_scope: Vec<(String, String)>,
    },
    /// Failure raised from pure evaluation at a pre-VM boundary (test/effect
    /// preamble, overlay, or a pure-fn body reached from one). Unlike
    /// `PreVm`, a pure-match failure always emitted its event trio and knows
    /// its scope vars, so `event_seq` and `vars_in_scope` are non-optional
    /// and real. No buffer (a pure match reads no shell).
    Pure {
        span: SpanId,
        event_seq: EventSeq,
        call_stack: Vec<StackFrame>,
        vars_in_scope: Vec<(String, String)>,
    },
    /// Failure raised before/around any VM. `span` points at the
    /// surrounding span when one is known (effect-setup span,
    /// shell-block span, cleanup-block span), `None` otherwise. The
    /// `call_stack` carries pure-fn frames when the failure came out of
    /// pure evaluation; empty for every other pre-VM failure.
    PreVm {
        span: Option<SpanId>,
        call_stack: Vec<StackFrame>,
    },
}

impl FailureContext {
    /// Construct a `PreVm` context with no surrounding span.
    pub fn pre_vm() -> Self {
        Self::PreVm {
            span: None,
            call_stack: vec![],
        }
    }

    /// Construct a `PreVm` context tied to a known surrounding span.
    pub fn pre_vm_with_span(span: SpanId) -> Self {
        Self::PreVm {
            span: Some(span),
            call_stack: vec![],
        }
    }

    /// Construct a `PreVm` context tied to a known surrounding span and a
    /// resolved call stack (pure-fn frames).
    pub fn pre_vm_with_frames(span: Option<SpanId>, call_stack: Vec<StackFrame>) -> Self {
        Self::PreVm { span, call_stack }
    }

    /// Construct a `Pure` context for a pre-VM pure-evaluation failure.
    pub fn pure(
        span: SpanId,
        event_seq: EventSeq,
        call_stack: Vec<StackFrame>,
        vars_in_scope: Vec<(String, String)>,
    ) -> Self {
        Self::Pure {
            span,
            event_seq,
            call_stack,
            vars_in_scope,
        }
    }

    pub fn span(&self) -> Option<SpanId> {
        match self {
            Self::Vm { span, .. } => Some(*span),
            Self::Pure { span, .. } => Some(*span),
            Self::PreVm { span, .. } => *span,
        }
    }

    pub fn event_seq(&self) -> Option<EventSeq> {
        match self {
            Self::Vm { event_seq, .. } => Some(*event_seq),
            Self::Pure { event_seq, .. } => Some(*event_seq),
            Self::PreVm { .. } => None,
        }
    }

    pub fn call_stack(&self) -> &[StackFrame] {
        match self {
            Self::Vm { call_stack, .. } => call_stack,
            Self::Pure { call_stack, .. } => call_stack,
            Self::PreVm { call_stack, .. } => call_stack,
        }
    }

    pub fn buffer_tail(&self) -> &str {
        match self {
            Self::Vm { buffer_tail, .. } => buffer_tail,
            Self::Pure { .. } | Self::PreVm { .. } => "",
        }
    }

    pub fn vars_in_scope(&self) -> &[(String, String)] {
        match self {
            Self::Vm { vars_in_scope, .. } => vars_in_scope,
            Self::Pure { vars_in_scope, .. } => vars_in_scope,
            Self::PreVm { .. } => &[],
        }
    }
}

#[derive(Debug, Clone, thiserror::Error)]
pub enum Failure {
    #[error("match timeout in shell '{shell}': timed out waiting for {pattern}")]
    MatchTimeout {
        pattern: String,
        span: IrSpan,
        shell: String,
        /// The timeout that fired. Boxed to keep `Failure`'s variant size
        /// comparable to the others (avoids `clippy::large_enum_variant`).
        effective: Box<IrTimeout>,
        context: FailureContext,
    },
    #[error(
        "fail pattern matched in shell '{shell}': pattern {pattern} triggered, matched: \"{matched_line}\""
    )]
    FailPatternMatched {
        pattern: String,
        matched_line: String,
        span: IrSpan,
        shell: String,
        context: FailureContext,
    },
    #[error(
        "shell '{shell}' exited unexpectedly{}",
        match exit_code {
            Some(code) => format!(" with exit code {code}"),
            None => " without an exit code".to_string(),
        }
    )]
    ShellExited {
        shell: String,
        exit_code: Option<i32>,
        span: IrSpan,
        context: FailureContext,
    },
    #[error(
        "{}",
        match shell {
            Some(s) => format!("runtime error in shell '{s}': {message}"),
            None => format!("runtime error: {message}"),
        }
    )]
    Runtime {
        message: String,
        span: IrSpan,
        shell: Option<String>,
        context: FailureContext,
    },
    #[error(
        "pure match in {match_context} did not satisfy pattern {pattern}: value {value:?} did not match"
    )]
    PureMatch {
        value: String,
        pattern: String,
        is_regex: bool,
        span: IrSpan,
        match_context: MatchContext,
        context: FailureContext,
    },
    #[error(
        "multimatch did not satisfy all patterns in shell '{shell}' ({matched_count}/{total} matched)",
        matched_count = matched.len(),
        total = patterns.len(),
    )]
    MultiMatch {
        shell: String,
        /// All patterns in source order.
        patterns: Vec<crate::observe::structured::event::MultiMatchPattern>,
        /// Indices into `patterns` that matched before the block timed out.
        matched: Vec<usize>,
        span: IrSpan,
        /// The block-level timeout that fired. Boxed to keep variant size in
        /// line with the other failures (see clippy::large_enum_variant).
        effective: Box<IrTimeout>,
        context: FailureContext,
    },
}

/// Resolve the pure-fn call chain from the innermost still-open pure-fn
/// span. On the pure-eval error path `leave_pure_fn` is skipped by `?`
/// propagation, so those spans stay open and carry the chain. Empty when
/// no pure fn is on the stack (a direct pure-match failure).
pub fn resolve_pure_stack(sink: &LogSink, log: &StructuredLogBuilder) -> Vec<StackFrame> {
    sink.deepest_open_span()
        .map(|leaf| log.resolve_stack(leaf))
        .unwrap_or_default()
}

/// Build the `ExecError` for a pure-eval failure at a pre-VM boundary
/// (test-level / effect-level `let` or pure-match, overlay). Resolves the
/// pure-fn chain and wraps it in a `Pure` failure context carrying the
/// real current seq and a snapshot of the scope vars. When the failure
/// surfaced from a pure-fn frame, the match context names that fn;
/// otherwise it is the caller-supplied enclosing context (test/effect
/// preamble or overlay).
pub fn pure_eval_failure(
    err: relux_ir::PureEvalError,
    span: SpanId,
    enclosing_context: MatchContext,
    vars_in_scope: Vec<(String, String)>,
    sink: &LogSink,
    log: &StructuredLogBuilder,
) -> ExecError {
    let call_stack = resolve_pure_stack(sink, log);
    let match_context = match call_stack.last() {
        Some(f) if f.is_fn_call() => MatchContext::Fn {
            name: f.name.clone().unwrap_or_default(),
        },
        _ => enclosing_context,
    };
    let event_seq = log.current_seq();
    Failure::from_pure_eval(
        err,
        match_context,
        FailureContext::pure(span, event_seq, call_stack, vars_in_scope),
    )
    .into()
}

/// The single authority for the malformed-pure-regex failure wording,
/// shared by the shell-body pure-match path (`vm`) and the pre-VM
/// `from_pure_eval` path.
pub(crate) fn invalid_regex_message(reason: &str) -> String {
    format!("invalid regex: {reason}")
}

impl Failure {
    /// Build a `Failure` from a pure-evaluation error. A failed pure match
    /// inside a `pure fn` body becomes `Failure::PureMatch`; a malformed
    /// interpolated regex becomes a runtime error naming the bad pattern.
    /// `match_context` names where the pure match ran (fn, test/effect
    /// preamble, overlay, or shell); a non-shell context carries no shell
    /// on the derived `Runtime` failure.
    pub fn from_pure_eval(
        err: relux_ir::PureEvalError,
        match_context: MatchContext,
        context: FailureContext,
    ) -> Self {
        match err {
            relux_ir::PureEvalError::PureMatchFailed {
                value,
                pattern,
                is_regex,
                span,
            } => Failure::PureMatch {
                value,
                pattern,
                is_regex,
                span,
                match_context,
                context,
            },
            relux_ir::PureEvalError::MalformedPattern {
                pattern: _,
                reason,
                span,
            } => Failure::Runtime {
                message: invalid_regex_message(&reason),
                span,
                shell: match_context.shell_name_ref().map(str::to_string),
                context,
            },
        }
    }

    pub fn summary(&self) -> String {
        self.to_string()
    }

    pub fn failure_type(&self) -> &'static str {
        match self {
            Failure::MatchTimeout { .. } => "MatchTimeout",
            Failure::FailPatternMatched { .. } => "FailPatternMatched",
            Failure::ShellExited { .. } => "ShellExited",
            Failure::Runtime { .. } => "Runtime",
            Failure::PureMatch { .. } => "PureMatch",
            Failure::MultiMatch { .. } => "MultiMatch",
        }
    }

    pub fn context(&self) -> &FailureContext {
        match self {
            Failure::MatchTimeout { context, .. }
            | Failure::FailPatternMatched { context, .. }
            | Failure::ShellExited { context, .. }
            | Failure::Runtime { context, .. }
            | Failure::PureMatch { context, .. }
            | Failure::MultiMatch { context, .. } => context,
        }
    }
}

impl From<&Failure> for relux_core::error::DiagnosticReport {
    fn from(failure: &Failure) -> Self {
        use relux_core::error::DiagnosticReport;
        use relux_core::error::Severity;
        match failure {
            Failure::MatchTimeout {
                pattern,
                span,
                shell,
                ..
            } => DiagnosticReport {
                severity: Severity::Error,
                message: format!("match timeout in shell `{shell}`"),
                labels: vec![(span.clone(), format!("timed out waiting for `{pattern}`")).into()],
                help: None,
                note: None,
            },
            Failure::FailPatternMatched {
                pattern,
                matched_line,
                span,
                shell,
                ..
            } => DiagnosticReport {
                severity: Severity::Error,
                message: format!("fail pattern matched in shell `{shell}`"),
                labels: vec![(span.clone(), format!("pattern `{pattern}` triggered here")).into()],
                help: None,
                note: Some(format!("matched output: {matched_line}")),
            },
            Failure::ShellExited {
                shell,
                exit_code,
                span,
                ..
            } => {
                let code_msg = match exit_code {
                    Some(c) => format!("with exit code {c}"),
                    None => "without an exit code".to_string(),
                };
                DiagnosticReport {
                    severity: Severity::Error,
                    message: format!("shell `{shell}` exited unexpectedly"),
                    labels: vec![(span.clone(), code_msg).into()],
                    help: None,
                    note: None,
                }
            }
            Failure::Runtime {
                message,
                span,
                shell,
                ..
            } => {
                let msg = match shell {
                    Some(s) => format!("runtime error in shell `{s}`"),
                    None => "runtime error".to_string(),
                };
                let first_line = message.lines().next().unwrap_or(message);
                let has_detail = message.contains('\n');
                DiagnosticReport {
                    severity: Severity::Error,
                    message: msg,
                    labels: vec![(span.clone(), first_line.to_string()).into()],
                    help: None,
                    note: if has_detail {
                        Some(message.clone())
                    } else {
                        None
                    },
                }
            }
            Failure::PureMatch {
                value,
                pattern,
                is_regex,
                span,
                match_context,
                ..
            } => {
                let op = if *is_regex { "?" } else { "=" };
                DiagnosticReport {
                    severity: Severity::Error,
                    message: format!(
                        "pure match in {} did not match",
                        match_context.backtick_label()
                    ),
                    labels: vec![
                        (
                            span.clone(),
                            format!("value did not satisfy `{op} {pattern}`"),
                        )
                            .into(),
                    ],
                    help: None,
                    note: Some(format!("value: {value}")),
                }
            }
            Failure::MultiMatch {
                shell,
                patterns,
                matched,
                span,
                ..
            } => {
                let matched_set: std::collections::HashSet<usize> =
                    matched.iter().copied().collect();
                let total = patterns.len();
                let hit_count = matched_set.len();
                let header = format!(
                    "multimatch did not satisfy all patterns ({hit_count} matched, {} timed out)",
                    total.saturating_sub(hit_count),
                );
                let mut lines = String::with_capacity(header.len() + patterns.len() * 48);
                lines.push_str(&header);
                lines.push('\n');
                for (i, p) in patterns.iter().enumerate() {
                    let label = if matched_set.contains(&i) {
                        "matched:"
                    } else {
                        "timed out:"
                    };
                    let kind = if p.is_regex { "?" } else { "=" };
                    let line = format!("{label:<13}{kind} {pat}", pat = p.pattern);
                    lines.push_str(&line);
                    lines.push('\n');
                }
                DiagnosticReport {
                    severity: Severity::Error,
                    message: format!("multimatch in shell `{shell}` did not satisfy all patterns"),
                    labels: vec![
                        (span.clone(), "multimatch block timed out here".to_string()).into(),
                    ],
                    help: None,
                    note: Some(lines.trim_end().to_string()),
                }
            }
        }
    }
}

pub fn log_link(run_dir: &Path, result: &TestResult) -> Option<String> {
    let log_dir = result.log_dir.as_ref()?;
    let relative = log_dir.strip_prefix(run_dir).ok()?;
    Some(format!("{}/event.html", relative.display()))
}

/// Companion to `log_link` for the canonical structured artifact.
/// Returns `<log_dir>/events.json` relative to `run_dir`. Machine
/// consumers (custom reporters, dashboards) prefer this over the
/// human-targeted `event.html`.
pub fn events_json_link(run_dir: &Path, result: &TestResult) -> Option<String> {
    let log_dir = result.log_dir.as_ref()?;
    let relative = log_dir.strip_prefix(run_dir).ok()?;
    Some(format!("{}/events.json", relative.display()))
}

/// Top-level marker that the test was interrupted before completing.
/// Distinct from `Failure` because the test did not misbehave - it was
/// stopped by an external event (the per-test watchdog, the suite-wide
/// watchdog, fail-fast, or SIGINT).
#[derive(Debug, Clone, thiserror::Error)]
#[error(
    "{}",
    match reason {
        CancelReason::TestTimeout { duration } => format!("cancelled: test timed out after {duration:?}"),
        CancelReason::SuiteTimeout { duration } => format!("cancelled: suite timed out after {duration:?}"),
        CancelReason::FailFast { trigger_test } => format!("cancelled: suite stopped after `{trigger_test}` failed (fail-fast)"),
        CancelReason::Sigint => "cancelled: interrupted (SIGINT)".to_string(),
    }
)]
pub struct Cancellation {
    pub reason: CancelReason,
    pub context: FailureContext,
}

impl Cancellation {
    pub fn summary(&self) -> String {
        self.to_string()
    }

    pub fn reason_tag(&self) -> &'static str {
        match &self.reason {
            CancelReason::TestTimeout { .. } => "test-timeout",
            CancelReason::SuiteTimeout { .. } => "suite-timeout",
            CancelReason::FailFast { .. } => "fail-fast",
            CancelReason::Sigint => "sigint",
        }
    }
}

impl From<&Cancellation> for relux_core::error::DiagnosticReport {
    fn from(c: &Cancellation) -> Self {
        relux_core::error::DiagnosticReport {
            severity: relux_core::error::Severity::Error,
            message: c.summary(),
            labels: vec![],
            help: None,
            note: None,
        }
    }
}

/// Internal error type used by the VM / BIF / effect machinery while a test
/// is running. `Failure` is "the test misbehaved"; `Cancelled` is "we were
/// stopped from the outside". `run_test` maps each variant onto the
/// corresponding `Outcome`.
#[derive(Debug, Clone, thiserror::Error)]
pub enum ExecError {
    #[error(transparent)]
    Failure(#[from] Failure),
    #[error(transparent)]
    Cancelled(#[from] Cancellation),
}

impl ExecError {
    pub fn summary(&self) -> String {
        self.to_string()
    }
}

#[derive(Debug, Clone)]
pub struct TestResult {
    pub test_name: String,
    pub test_path: String,
    pub outcome: Outcome,
    pub duration: Duration,
    pub progress: String,
    pub log_dir: Option<PathBuf>,
    pub warnings: Vec<crate::effect::Warning>,
    pub flaky_retries: u32,
}

impl TestResult {
    pub fn is_failure(&self) -> bool {
        matches!(self.outcome, Outcome::Fail(_))
    }

    pub fn is_cancelled(&self) -> bool {
        matches!(self.outcome, Outcome::Cancelled(_))
    }
}

#[derive(Debug, Clone)]
pub enum Outcome {
    Pass,
    Fail(Failure),
    Cancelled(Cancellation),
    Skipped(String),
    Invalid(String),
}

impl Outcome {
    pub fn is_failure(&self) -> bool {
        matches!(self, Outcome::Fail(_))
    }

    pub fn is_cancelled(&self) -> bool {
        matches!(self, Outcome::Cancelled(_))
    }

    pub fn is_nonzero_outcome(&self) -> bool {
        matches!(
            self,
            Outcome::Fail(_) | Outcome::Cancelled(_) | Outcome::Invalid(_)
        )
    }

    /// Whether the flaky-retry loop should retry on this outcome. Real
    /// failures and per-test-timeout cancellations are retryable (those are
    /// the test's own clock running out - exactly what flaky retries with
    /// scaled timeouts target). External cancellations (suite-timeout,
    /// fail-fast, SIGINT) are not retryable: rerunning the same test isn't
    /// going to make the external trigger disappear.
    pub fn is_retryable(&self) -> bool {
        match self {
            Outcome::Fail(_) => true,
            Outcome::Cancelled(c) => {
                matches!(c.reason, crate::cancel::CancelReason::TestTimeout { .. })
            }
            _ => false,
        }
    }
}

// --- Run Report ------------------------------------------

pub struct RunReport<'a> {
    pub results: &'a [TestResult],
    pub run_dir: &'a Path,
    pub wall_duration: Duration,
    pub jobs: usize,
}

impl RunReport<'_> {
    pub fn eprint(&self) {
        let mut passed = 0usize;
        let mut failed = 0usize;
        let mut cancelled = 0usize;
        let mut skipped = 0usize;
        let mut invalid = 0usize;
        let mut flaky_retries = 0u32;
        let mut total_duration = Duration::ZERO;

        for result in self.results {
            total_duration += result.duration;
            flaky_retries += result.flaky_retries;
            match &result.outcome {
                Outcome::Pass => passed += 1,
                Outcome::Fail(_) => failed += 1,
                Outcome::Cancelled(_) => cancelled += 1,
                Outcome::Skipped(_) => skipped += 1,
                Outcome::Invalid(_) => invalid += 1,
            }
        }

        let has_problems = failed > 0 || cancelled > 0 || invalid > 0;
        let status = if has_problems {
            "FAILED".red().to_string()
        } else {
            "ok".green().to_string()
        };

        let mut summary = format!("\ntest result: {status}. {passed} passed; {failed} failed");
        if cancelled > 0 {
            summary.push_str(&format!("; {cancelled} cancelled"));
        }
        if invalid > 0 {
            summary.push_str(&format!("; {invalid} invalid"));
        }
        if skipped > 0 {
            summary.push_str(&format!("; {skipped} skipped"));
        }
        if flaky_retries > 0 {
            summary.push_str(&format!("; {flaky_retries} flaky retries"));
        }
        if self.jobs > 1 {
            summary.push_str(&format!(
                "; finished in {} ({} cumulative)\n",
                format_duration(self.wall_duration),
                format_duration(total_duration)
            ));
        } else {
            summary.push_str(&format!(
                "; finished in {}\n",
                format_duration(self.wall_duration)
            ));
        }
        eprint!("{summary}");
        eprintln!(
            "  Test logs: file://{}",
            self.run_dir.join("index.html").display()
        );
        let _ = std::io::stderr().flush();
    }
}

pub fn format_duration(d: Duration) -> String {
    let total_ms = d.as_secs_f64() * 1000.0;
    if total_ms < 1000.0 {
        format!("{:.1} ms", total_ms)
    } else {
        format!("{:.1} s", total_ms / 1000.0)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::Path;

    fn dummy_span() -> IrSpan {
        IrSpan::synthetic()
    }

    #[test]
    fn invalid_regex_message_wording() {
        assert_eq!(
            super::invalid_regex_message("unclosed group"),
            "invalid regex: unclosed group"
        );
    }

    #[test]
    fn summary_match_timeout() {
        let f = Failure::MatchTimeout {
            pattern: "/ready/".into(),
            shell: "default".into(),
            span: dummy_span(),
            effective: Box::new(IrTimeout::tolerance(std::time::Duration::from_secs(5))),
            context: FailureContext::pre_vm(),
        };
        assert_eq!(
            f.summary(),
            "match timeout in shell 'default': timed out waiting for /ready/"
        );
    }

    #[test]
    fn summary_fail_pattern_matched() {
        let f = Failure::FailPatternMatched {
            pattern: "/error/".into(),
            matched_line: "error: connection refused".into(),
            shell: "default".into(),
            span: dummy_span(),
            context: FailureContext::pre_vm(),
        };
        assert_eq!(
            f.summary(),
            "fail pattern matched in shell 'default': pattern /error/ triggered, matched: \"error: connection refused\""
        );
    }

    #[test]
    fn summary_shell_exited_with_code() {
        let f = Failure::ShellExited {
            shell: "default".into(),
            exit_code: Some(1),
            span: dummy_span(),
            context: FailureContext::pre_vm(),
        };
        assert_eq!(
            f.summary(),
            "shell 'default' exited unexpectedly with exit code 1"
        );
    }

    #[test]
    fn summary_shell_exited_without_code() {
        let f = Failure::ShellExited {
            shell: "default".into(),
            exit_code: None,
            span: dummy_span(),
            context: FailureContext::pre_vm(),
        };
        assert_eq!(
            f.summary(),
            "shell 'default' exited unexpectedly without an exit code"
        );
    }

    #[test]
    fn diagnostic_report_runtime_renders_source_span_label() {
        use relux_core::error::DiagnosticReport;
        use relux_core::table::FileId;
        // A real (non-synthetic) source span pointing at the offending
        // identifier. Every `Failure::Runtime` now carries one, so the
        // rendered report must surface it as exactly one diagnostic label.
        let file = FileId::new(std::path::PathBuf::from("tests/auth/login.relux"));
        let span = IrSpan::new(file.clone(), relux_core::Span::new(12, 24));
        let f = Failure::Runtime {
            message: "effect alias `db` does not expose shell `psql`".into(),
            shell: None,
            span: span.clone(),
            context: FailureContext::pre_vm(),
        };
        let rep: DiagnosticReport = (&f).into();
        assert_eq!(
            rep.labels.len(),
            1,
            "a Runtime failure must render exactly one source label"
        );
        let label = &rep.labels[0];
        assert_eq!(label.span.file(), &file, "label points at the source file");
        assert_eq!(
            label.span.span(),
            span.span(),
            "label carries the exact byte span passed on the failure"
        );
    }

    #[test]
    fn summary_runtime_with_shell() {
        let f = Failure::Runtime {
            message: "something broke".into(),
            shell: Some("default".into()),
            span: IrSpan::synthetic(),
            context: FailureContext::pre_vm(),
        };
        assert_eq!(
            f.summary(),
            "runtime error in shell 'default': something broke"
        );
    }

    #[test]
    fn summary_runtime_without_shell() {
        let f = Failure::Runtime {
            message: "something broke".into(),
            shell: None,
            span: IrSpan::synthetic(),
            context: FailureContext::pre_vm(),
        };
        assert_eq!(f.summary(), "runtime error: something broke");
    }

    #[test]
    fn summary_multimatch() {
        use crate::observe::structured::event::MultiMatchPattern;
        let f = Failure::MultiMatch {
            shell: "default".into(),
            patterns: vec![
                MultiMatchPattern {
                    pattern: "^a$".into(),
                    is_regex: true,
                },
                MultiMatchPattern {
                    pattern: "b".into(),
                    is_regex: false,
                },
            ],
            matched: vec![0],
            span: dummy_span(),
            effective: Box::new(IrTimeout::tolerance(std::time::Duration::from_secs(5))),
            context: FailureContext::pre_vm(),
        };
        let summary = f.summary();
        assert!(
            summary.starts_with("multimatch did not satisfy all patterns"),
            "got: {summary}"
        );
    }

    #[test]
    fn failure_type_multimatch() {
        use crate::observe::structured::event::MultiMatchPattern;
        let f = Failure::MultiMatch {
            shell: "default".into(),
            patterns: vec![MultiMatchPattern {
                pattern: "^a$".into(),
                is_regex: true,
            }],
            matched: vec![],
            span: dummy_span(),
            effective: Box::new(IrTimeout::tolerance(std::time::Duration::from_secs(5))),
            context: FailureContext::pre_vm(),
        };
        assert_eq!(f.failure_type(), "MultiMatch");
    }

    #[test]
    fn diagnostic_report_multimatch_lists_per_pattern_status() {
        use crate::observe::structured::event::MultiMatchPattern;
        use relux_core::error::DiagnosticReport;
        let f = Failure::MultiMatch {
            shell: "default".into(),
            patterns: vec![
                MultiMatchPattern {
                    pattern: "^a$".into(),
                    is_regex: true,
                },
                MultiMatchPattern {
                    pattern: "^b$".into(),
                    is_regex: true,
                },
                MultiMatchPattern {
                    pattern: "^c$".into(),
                    is_regex: true,
                },
            ],
            matched: vec![0, 2],
            span: dummy_span(),
            effective: Box::new(IrTimeout::tolerance(std::time::Duration::from_secs(5))),
            context: FailureContext::pre_vm(),
        };
        let rep: DiagnosticReport = (&f).into();
        let note = rep
            .note
            .expect("multimatch DiagnosticReport must carry a per-pattern note");
        assert!(note.contains("matched:"), "matched label present: {note}");
        assert!(
            note.contains("timed out:"),
            "timed-out label present: {note}"
        );
        assert!(note.contains("^a$"), "pattern 0 listed");
        assert!(note.contains("^b$"), "pattern 1 listed");
        assert!(note.contains("^c$"), "pattern 2 listed");
        assert!(note.is_ascii(), "diagnostic note must be ASCII-only");
    }

    #[test]
    fn diagnostic_report_pure_match_carries_value_and_pattern() {
        use relux_core::error::DiagnosticReport;
        for (is_regex, op) in [(false, "="), (true, "?")] {
            let f = Failure::PureMatch {
                value: "hello world".into(),
                pattern: "goodbye".into(),
                is_regex,
                match_context: MatchContext::Shell {
                    name: "default".into(),
                },
                span: dummy_span(),
                context: FailureContext::pre_vm(),
            };
            let rep: DiagnosticReport = (&f).into();
            assert!(
                rep.message.contains("pure match"),
                "message names the failure: {}",
                rep.message
            );
            assert!(
                rep.message.contains("shell `default`"),
                "message names the match context: {}",
                rep.message
            );
            let label_text = rep
                .labels
                .first()
                .map(|l| l.message.clone())
                .expect("pure-match DiagnosticReport must carry a label");
            assert!(
                label_text.contains("goodbye"),
                "label carries the pattern: {label_text}"
            );
            assert!(
                label_text.contains(op),
                "label carries the `{op}` operator: {label_text}"
            );
            let note = rep
                .note
                .expect("pure-match DiagnosticReport must carry a value note");
            assert!(
                note.contains("hello world"),
                "note carries the value: {note}"
            );
            // A pure match has no shell buffer; the report must not fabricate
            // a buffer-tail section (DiagnosticReport has no buffer field, and
            // nothing should smuggle one into the note).
            assert!(
                !note.to_lowercase().contains("buffer"),
                "pure-match report must not carry a buffer tail: {note}"
            );
        }
    }

    #[test]
    fn from_pure_eval_malformed_pattern_non_shell_carries_no_shell() {
        // A malformed interpolated regex in a non-shell context (here a test
        // preamble) must produce a `Runtime` failure with `shell: None`:
        // the old empty-string special-case is gone, and only a real shell
        // context contributes a shell name.
        let err = relux_ir::PureEvalError::MalformedPattern {
            pattern: "(".into(),
            reason: "unclosed group".into(),
            span: dummy_span(),
        };
        let f = Failure::from_pure_eval(
            err,
            MatchContext::TestPreamble {
                name: "login".into(),
            },
            FailureContext::pure(1, 2, vec![], vec![]),
        );
        match f {
            Failure::Runtime { shell, message, .. } => {
                assert_eq!(shell, None, "non-shell context carries no shell");
                assert!(message.contains("invalid regex"), "message: {message}");
            }
            other => panic!("expected Runtime, got {other:?}"),
        }
    }

    #[test]
    fn from_pure_eval_malformed_pattern_shell_carries_shell() {
        // The shell context is the only one that surfaces a shell name.
        let err = relux_ir::PureEvalError::MalformedPattern {
            pattern: "(".into(),
            reason: "unclosed group".into(),
            span: dummy_span(),
        };
        let f = Failure::from_pure_eval(
            err,
            MatchContext::Shell {
                name: "default".into(),
            },
            FailureContext::pure(1, 2, vec![], vec![]),
        );
        match f {
            Failure::Runtime { shell, .. } => {
                assert_eq!(shell, Some("default".to_string()));
            }
            other => panic!("expected Runtime, got {other:?}"),
        }
    }

    #[test]
    fn pure_context_exposes_real_seq_and_vars() {
        let ctx = FailureContext::pure(7, 42, vec![], vec![("v".into(), "abc".into())]);
        assert_eq!(ctx.span(), Some(7));
        assert_eq!(ctx.event_seq(), Some(42));
        assert_eq!(ctx.buffer_tail(), "");
        assert_eq!(ctx.vars_in_scope(), &[("v".to_string(), "abc".to_string())]);
    }

    #[test]
    fn log_link_with_log_dir() {
        let run_dir = Path::new("/tmp/runs/run-001");
        let result = TestResult {
            test_name: "my_test".into(),
            test_path: "tests/my_test.relux".into(),
            outcome: Outcome::Pass,
            duration: Duration::from_millis(100),

            progress: String::new(),
            log_dir: Some(PathBuf::from("/tmp/runs/run-001/my_test")),
            warnings: Vec::new(),
            flaky_retries: 0,
        };
        assert_eq!(
            log_link(run_dir, &result),
            Some("my_test/event.html".to_string())
        );
    }

    #[test]
    fn cancellation_summary_test_timeout() {
        let c = Cancellation {
            reason: CancelReason::TestTimeout {
                duration: Duration::from_millis(300),
            },
            context: FailureContext::pre_vm(),
        };
        assert_eq!(c.reason_tag(), "test-timeout");
        assert!(c.summary().starts_with("cancelled: test timed out after"));
    }

    #[test]
    fn cancellation_summary_fail_fast() {
        let c = Cancellation {
            reason: CancelReason::FailFast {
                trigger_test: "foo".into(),
            },
            context: FailureContext::pre_vm(),
        };
        assert_eq!(c.reason_tag(), "fail-fast");
        assert!(c.summary().contains("`foo`"));
    }

    #[test]
    fn exec_error_from_conversions() {
        let f = Failure::Runtime {
            message: "x".into(),
            span: IrSpan::synthetic(),
            shell: None,
            context: FailureContext::pre_vm(),
        };
        let e: ExecError = f.into();
        assert!(matches!(e, ExecError::Failure(_)));

        let c = Cancellation {
            reason: CancelReason::Sigint,
            context: FailureContext::pre_vm(),
        };
        let e: ExecError = c.into();
        assert!(matches!(e, ExecError::Cancelled(_)));
    }

    #[test]
    fn log_link_without_log_dir() {
        let run_dir = Path::new("/tmp/runs/run-001");
        let result = TestResult {
            test_name: "my_test".into(),
            test_path: "tests/my_test.relux".into(),
            outcome: Outcome::Pass,
            duration: Duration::from_millis(100),

            progress: String::new(),
            log_dir: None,
            warnings: Vec::new(),
            flaky_retries: 0,
        };
        assert_eq!(log_link(run_dir, &result), None);
    }
}