smix-error 25.0.0

#![doc = include_str!("../README.md")]
#![deny(missing_docs)]
#![deny(rustdoc::broken_intra_doc_links)]

//! smix-error — ExpectationFailure + FailureCode + AI-readable
//! `to_prompt()` + `build_suggestions` (stone, cold path).
//!
//! `build_suggestions` behavior: threshold > 0.5, top 3, sort by score
//! descending → field (name > id > text) → DFS index ascending.
//!
//! # Why a separate stone
//!
//! The canonical failure type, in a leaf crate every layer can depend on;
//! `to_prompt()` is its AI-readable render.

#![doc(html_root_url = "https://docs.smix.dev/smix-error")]

mod redact;
pub use redact::{MASK, mask as mask_secret};
use serde::{Deserialize, Serialize};
use smix_screen::{ElementSummary, ScreenFacts, WindowInfo, WindowKind};
use smix_selector::{Selector, describe_selector};
use std::fmt;

/// All failure codes smix surfaces back to the SDK / MCP / CLI
/// (SCREAMING_SNAKE_CASE wire).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
// non_exhaustive so a new code is additive rather than a major; the guard
// that makes one fail to compile until it is thought about lives inside
// this crate (`the_vocabulary_is_pinned`), where the match stays exhaustive.
#[non_exhaustive]
pub enum FailureCode {
    /// Selector matched zero elements in the visible tree.
    ElementNotFound,
    /// Element matched but failed the visibility filter.
    NotVisible,
    /// Element matched but `enabled = false`.
    NotEnabled,
    /// Selector matched multiple elements (when uniqueness was required).
    Ambiguous,
    /// Operation exceeded the implicit-wait budget.
    Timeout,
    /// `expect` assertion (e.g. `toHaveText`) did not hold.
    AssertionFailed,
    /// Target app exited or never launched.
    AppNotRunning,
    /// Simulator device is not booted.
    SimulatorNotBooted,
    /// The touch was synthesised, and it did not land inside the
    /// element the selector matched.
    ///
    /// Distinct from `ElementNotFound` because the two send a reader
    /// somewhere different: not-found means fix the selector, missed
    /// means the element was there and the touch went elsewhere — a
    /// stale frame, or something moved between the tree fetch and the
    /// tap.
    TapMissed,
    /// The screen is described in one coordinate space and the touch
    /// would be delivered in another, so no aim can land where the tree
    /// says the element is.
    ///
    /// Distinct from `TapMissed`, and the distinction is the whole
    /// point: a miss says the element was there and the touch went
    /// elsewhere, which invites another attempt with a better point.
    /// There is no better point here — whatever is passed gets
    /// recomputed against the app's frame and then read against the
    /// device's. Retrying is the trap, and the consumer who found this
    /// spent an afternoon in it.
    CoordinateSpaceMismatch,
    /// Catch-all for runner / driver / IO failures.
    DriverError,
    /// The device's capture path is under load and refusing frames for a
    /// stated window — the screenshot pacer's circuit is open.
    ///
    /// Separate from [`Self::DriverError`] because the two want opposite
    /// responses and only one of them is a defect. A driver error means
    /// something is broken; this means "not now, try again shortly", and
    /// a caller with time left can simply keep waiting. It arrived as a
    /// `DriverError` until 7.1, which is how a consumer's release gate
    /// met it: `FAIL [DRIVER_ERROR]` from `waitForAnimationToEnd`, a
    /// verb whose entire meaning is to wait.
    CaptureBackpressure,
    /// The app has no window in front — another app or the home screen is
    /// there — so its elements cannot be read. Unlike [`Self::AppNotRunning`]
    /// nothing crashed: bring it back with launchApp or its notification.
    AppNotInForeground,
}

/// Structured failure thrown by SDK matchers and driver calls. Shape
/// is AI-feed-back-ready.
///
/// `selector` is the typed `Selector` rather than the wire
/// `serde_json::Value` — callers raising failures from the driver / SDK
/// side already have the typed selector, and `to_prompt` invokes
/// `describe_selector` for stable rendering.
///
/// Serializes as `{ ok: false, code, message, selector, suggestions,
/// visibleElements, hint, screenshot, deviceLog }`; the `ok = false`
/// discriminant identifies the failure branch of a `Result` wire.
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ExpectationFailure {
    /// Always `false` for failures. Round-trip discriminator for
    /// `Result<T, ExpectationFailure>` wire.
    pub ok: False,
    /// Failure code discriminator.
    pub code: FailureCode,
    /// Human-readable summary (and AI-readable when fed into `to_prompt`).
    pub message: String,
    /// Originating selector, when one is available.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub selector: Option<Selector>,
    /// Ranked near-miss suggestions (edit-distance to label / id / etc.).
    #[serde(default)]
    pub suggestions: Vec<String>,
    /// Snapshot of visible+enabled elements at failure time.
    #[serde(default)]
    pub visible_elements: Vec<ElementSummary>,
    /// Optional one-line hint (e.g. "try `app.wait_for(...)` first").
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
    /// The smix that produced this failure.
    ///
    /// Not decoration. A consumer wrote up two defects against smix
    /// behaviour that had been fixed hours earlier, quoting an error
    /// message the current build no longer emits — they had no way to
    /// tell whether the smix in front of them contained the fix for
    /// the thing they had just hit. A failure that names its version
    /// makes that answerable from the failure itself.
    ///
    /// Set by [`ExpectationFailure::new`] from the crate version, so no
    /// call site can forget it.
    #[serde(default)]
    pub smix_version: String,
    /// base64-encoded PNG; omitted from default rendering to keep logs lean.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub screenshot: Option<String>,
    /// Last-N-lines of captured device log, folded into AI-readable
    /// output for failure-window system context.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub device_log: Vec<String>,
    /// How many elements `visible_elements` was cut from.
    ///
    /// A list of ten read as the whole screen: a consumer built a
    /// detector on it that called every Android failure blind, because
    /// the ten were always the status bar. The total says it is a
    /// sample.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub visible_total: Option<usize>,
    /// The windows the screen held when this failed, focused app first.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub windows: Vec<WindowInfo>,
    /// Windows the reader could not read. "The app is not in the tree"
    /// and "the app's window could not be read" are different failures.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub unreadable_windows: Option<u32>,
}

/// Newtype around `false` — used as the [`ExpectationFailure::ok`]
/// discriminator. Serializes/deserializes as the JSON literal `false`.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(transparent)]
pub struct False(pub bool);

/// Builder/Init form for ergonomic construction.
#[derive(Default)]
pub struct FailureInit {
    /// Optional failure code (defaults to `DriverError` if `None`).
    pub code: Option<FailureCode>,
    /// Human-readable / AI-readable message.
    pub message: String,
    /// Originating selector, when one is available.
    pub selector: Option<Selector>,
    /// Pre-built ranked near-miss suggestions.
    pub suggestions: Vec<String>,
    /// Captured visible+enabled elements at failure time.
    pub visible_elements: Vec<ElementSummary>,
    /// Optional one-line hint string.
    pub hint: Option<String>,
    /// Optional base64 PNG screenshot at failure time.
    pub screenshot: Option<String>,
    /// Optional captured device log tail.
    pub device_log: Vec<String>,
    /// See [`ExpectationFailure::visible_total`].
    pub visible_total: Option<usize>,
    /// See [`ExpectationFailure::windows`].
    pub windows: Vec<WindowInfo>,
    /// See [`ExpectationFailure::unreadable_windows`].
    pub unreadable_windows: Option<u32>,
}

impl FailureInit {
    /// The screen the failure happened on: its elements (already in the
    /// order a reader should meet them), how many there were, whose
    /// windows they sat in, and how many windows could not be read.
    ///
    /// One entry point, so a call site cannot hand over the list and
    /// forget the count that says it is a sample.
    #[must_use]
    pub fn with_screen(mut self, facts: ScreenFacts) -> Self {
        self.visible_elements = facts.elements;
        self.visible_total = Some(facts.total);
        self.windows = facts.windows;
        self.unreadable_windows = (facts.unreadable > 0).then_some(facts.unreadable);
        self
    }

    /// The screen an earlier failure described, carried into a new one.
    ///
    /// For a failure that re-states another (a timeout reported as "not
    /// visible"): copying `visible_elements` by hand left the count and
    /// the windows behind, and the next field added would be left behind
    /// the same way.
    #[must_use]
    pub fn with_screen_from(mut self, earlier: &ExpectationFailure) -> Self {
        self.visible_elements = earlier.visible_elements.clone();
        self.visible_total = earlier.visible_total;
        self.windows = earlier.windows.clone();
        self.unreadable_windows = earlier.unreadable_windows;
        self
    }
}

impl ExpectationFailure {
    /// Construct from an init struct. `code` defaults to `DriverError`
    /// if `init.code` was None (defensive; SDK callers should always
    /// set it).
    pub fn new(init: FailureInit) -> Self {
        ExpectationFailure {
            ok: False(false),
            code: init.code.unwrap_or(FailureCode::DriverError),
            message: init.message,
            selector: init.selector,
            suggestions: init.suggestions,
            visible_elements: init.visible_elements,
            hint: init.hint,
            smix_version: env!("CARGO_PKG_VERSION").to_string(),
            screenshot: init.screenshot,
            device_log: init.device_log,
            visible_total: init.visible_total,
            windows: init.windows,
            unreadable_windows: init.unreadable_windows,
        }
    }

    /// AI-facing rendering. Designed so the output can be pasted back
    /// as a user message into a coding agent.
    #[must_use]
    pub fn to_prompt(&self) -> String {
        let mut lines: Vec<String> = Vec::new();
        lines.push(format!(
            "FAIL [{}]: {}",
            format_code(self.code),
            self.message
        ));
        // The version, on every failure, because the reader's next
        // question after "what went wrong" is often "is my smix old".
        // A consumer once wrote up two defects that had been fixed
        // hours earlier, quoting a message this build no longer emits.
        if !self.smix_version.is_empty() {
            lines.push(format!("  smix: {}", self.smix_version));
        }
        if let Some(sel) = &self.selector {
            lines.push(format!("  selector: {}", describe_selector(sel)));
        }
        if !self.suggestions.is_empty() {
            lines.push("  suggestions:".into());
            for s in &self.suggestions {
                lines.push(format!("    - {}", s));
            }
        }
        if let Some(line) = on_screen_line(&self.windows, self.unreadable_windows) {
            lines.push(line);
        }
        if !self.visible_elements.is_empty() {
            let n = self.visible_elements.len().min(10);
            lines.push(match self.visible_total {
                Some(total) if self.windows.iter().any(|w| w.focused) => {
                    format!("  visible elements ({n} of {total}, the focused app's first):")
                }
                Some(total) => format!("  visible elements ({n} of {total}):"),
                None => format!("  visible elements (top {n}):"),
            });
            for el in self.visible_elements.iter().take(10) {
                lines.push(format!("    - {}", render_element(el)));
            }
            let rest: Vec<String> = self.visible_elements[n..]
                .iter()
                .filter_map(|e| e.name.as_ref().or(e.text.as_ref()))
                .map(|t| format!("{t:?}"))
                .collect();
            if !rest.is_empty() {
                lines.push(format!(
                    "  the rest of the screen's text: {}",
                    rest.join(", ")
                ));
            }
        }
        if let Some(h) = &self.hint {
            lines.push(format!("  hint: {}", h));
        }
        if !self.device_log.is_empty() {
            // LOG_PROMPT_CAP — defensive ceiling for AI prompt size.
            const LOG_PROMPT_CAP: usize = 200;
            let n = self.device_log.len();
            lines.push(format!("  device log (last {} lines):", n));
            let start = n.saturating_sub(LOG_PROMPT_CAP);
            for dl in &self.device_log[start..] {
                lines.push(format!("    - {}", dl));
            }
        }
        lines.join("\n")
    }
}

impl fmt::Display for ExpectationFailure {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.to_prompt())
    }
}

impl std::error::Error for ExpectationFailure {}

/// One line naming the windows a failure's screen held.
///
/// Repeats collapse (`×2`) because a status bar and a navigation bar are
/// both `com.android.systemui`, and listing it twice says nothing the
/// count does not. `None` when there is nothing to say — a tree that
/// carries no window information gets no line rather than an empty one.
fn on_screen_line(windows: &[WindowInfo], unreadable: Option<u32>) -> Option<String> {
    let mut parts: Vec<(String, usize)> = Vec::new();
    for w in windows {
        let who = w.package.as_deref().unwrap_or("(package not reported)");
        let kind = match w.kind {
            WindowKind::Application => "application",
            WindowKind::InputMethod => "keyboard",
            WindowKind::System => "system",
            WindowKind::Other => "other",
        };
        let label = if w.focused {
            format!("{who} ({kind}, focused)")
        } else {
            format!("{who} ({kind})")
        };
        match parts.last_mut() {
            Some((last, n)) if *last == label => *n += 1,
            _ => parts.push((label, 1)),
        }
    }
    let mut bits: Vec<String> = parts
        .into_iter()
        .map(|(l, n)| if n > 1 { format!("{l} ×{n}") } else { l })
        .collect();
    match unreadable {
        Some(1) => bits.push("1 window unreadable".into()),
        Some(n) if n > 1 => bits.push(format!("{n} windows unreadable")),
        _ => {}
    }
    (!bits.is_empty()).then(|| format!("  on screen: {}", bits.join(" · ")))
}

fn format_code(c: FailureCode) -> &'static str {
    match c {
        FailureCode::ElementNotFound => "ELEMENT_NOT_FOUND",
        FailureCode::NotVisible => "NOT_VISIBLE",
        FailureCode::NotEnabled => "NOT_ENABLED",
        FailureCode::Ambiguous => "AMBIGUOUS",
        FailureCode::Timeout => "TIMEOUT",
        FailureCode::AssertionFailed => "ASSERTION_FAILED",
        FailureCode::AppNotRunning => "APP_NOT_RUNNING",
        FailureCode::SimulatorNotBooted => "SIMULATOR_NOT_BOOTED",
        FailureCode::TapMissed => "TAP_MISSED",
        FailureCode::CoordinateSpaceMismatch => "COORDINATE_SPACE_MISMATCH",
        FailureCode::DriverError => "DRIVER_ERROR",
        FailureCode::CaptureBackpressure => "CAPTURE_BACKPRESSURE",
        FailureCode::AppNotInForeground => "APP_NOT_IN_FOREGROUND",
    }
}

fn render_element(el: &ElementSummary) -> String {
    let role_str = el.role.map(|r| r.as_str()).unwrap_or("unknown");
    let mut bits: Vec<String> = vec![role_str.to_string()];
    if let Some(n) = &el.name {
        bits.push(format!("name={:?}", n));
    }
    if let Some(i) = &el.id {
        bits.push(format!("id=\"{}\"", i));
    }
    if let Some(t) = &el.text
        && Some(t) != el.name.as_ref()
    {
        bits.push(format!("text={:?}", t));
    }
    if !el.enabled {
        bits.push("disabled".into());
    }
    bits.join(" ")
}

mod suggest;
pub use suggest::{build_suggestions, edit_distance, similarity};

impl FailureCode {
    /// Every code, once.
    ///
    /// The one list: the SDK parity test and the errors guide read it
    /// rather than keeping their own (a copy outside this crate let
    /// `CaptureBackpressure` ship in 7.1 with no SDK declaring it, since
    /// `#[non_exhaustive]` makes an outside `match` accept anything).
    /// `the_vocabulary_is_pinned` guards it with an exhaustive match here.
    pub const ALL: &'static [FailureCode] = &[
        FailureCode::ElementNotFound,
        FailureCode::NotVisible,
        FailureCode::NotEnabled,
        FailureCode::Ambiguous,
        FailureCode::Timeout,
        FailureCode::AssertionFailed,
        FailureCode::AppNotRunning,
        FailureCode::SimulatorNotBooted,
        FailureCode::TapMissed,
        FailureCode::CoordinateSpaceMismatch,
        FailureCode::DriverError,
        FailureCode::CaptureBackpressure,
        FailureCode::AppNotInForeground,
    ];

    /// Whether the target may be outside the app's tree altogether — on a
    /// system popup or a notification banner — so those are worth a look.
    pub fn may_be_outside_the_app(self) -> bool {
        match self {
            FailureCode::ElementNotFound
            | FailureCode::NotVisible
            | FailureCode::AppNotInForeground => true,
            FailureCode::NotEnabled
            | FailureCode::Ambiguous
            | FailureCode::Timeout
            | FailureCode::AssertionFailed
            | FailureCode::AppNotRunning
            | FailureCode::SimulatorNotBooted
            | FailureCode::TapMissed
            | FailureCode::CoordinateSpaceMismatch
            | FailureCode::DriverError
            | FailureCode::CaptureBackpressure => false,
        }
    }

    /// Whether this code is a verdict about the screen, as opposed to
    /// smix being unable to look at it. An `optional` step skips only a
    /// verdict, and an end-to-end check judges a flow by its own rule only
    /// on one — a runner answering garbage once read as "the scroll stopped
    /// in the wrong place". Exhaustive, so a new code must pick a side.
    pub fn judges_the_screen(self) -> bool {
        match self {
            FailureCode::ElementNotFound
            | FailureCode::NotVisible
            | FailureCode::NotEnabled
            | FailureCode::Ambiguous
            | FailureCode::Timeout
            | FailureCode::AssertionFailed
            | FailureCode::TapMissed
            | FailureCode::CoordinateSpaceMismatch => true,
            FailureCode::AppNotRunning
            | FailureCode::SimulatorNotBooted
            | FailureCode::DriverError
            | FailureCode::CaptureBackpressure
            | FailureCode::AppNotInForeground => false,
        }
    }
}

#[cfg(test)]
mod what_a_code_is_about {
    use super::*;

    /// The eight codes that say something about the screen, and the five
    /// that say smix could not look. Named rather than counted: a code
    /// moved from one side to the other has to be moved here too.
    #[test]
    fn a_verdict_is_about_the_screen_and_a_driver_failure_is_not() {
        let about_the_screen = [
            FailureCode::ElementNotFound,
            FailureCode::NotVisible,
            FailureCode::NotEnabled,
            FailureCode::Ambiguous,
            FailureCode::Timeout,
            FailureCode::AssertionFailed,
            FailureCode::TapMissed,
            FailureCode::CoordinateSpaceMismatch,
        ];
        let could_not_look = [
            FailureCode::AppNotRunning,
            FailureCode::SimulatorNotBooted,
            FailureCode::DriverError,
            FailureCode::CaptureBackpressure,
            FailureCode::AppNotInForeground,
        ];
        for c in about_the_screen {
            assert!(c.judges_the_screen(), "{c:?} is a verdict about the screen");
        }
        for c in could_not_look {
            assert!(
                !c.judges_the_screen(),
                "{c:?} says smix could not look, not what it saw"
            );
        }
        assert_eq!(
            about_the_screen.len() + could_not_look.len(),
            FailureCode::ALL.len(),
            "every code is on one side or the other"
        );
    }
}

#[cfg(test)]
mod vocabulary {
    use super::*;

    /// A new `FailureCode` must not compile until it has been thought
    /// about everywhere.
    ///
    /// This match is exhaustive on purpose and lives inside the crate on
    /// purpose: `#[non_exhaustive]` makes an outside `match` accept
    /// anything, so the guard that used to sit in
    /// `tests/it/sdk_failure_code_parity.rs` would have started passing for
    /// every future variant. Adding a code should break this line, then
    /// the wire-string arm below it, then the three SDK declarations the
    /// parity test reads, then the errors guide.
    #[test]
    fn the_vocabulary_is_pinned() {
        let every = FailureCode::ALL;
        for &code in every {
            match code {
                FailureCode::ElementNotFound
                | FailureCode::NotVisible
                | FailureCode::NotEnabled
                | FailureCode::Ambiguous
                | FailureCode::Timeout
                | FailureCode::AssertionFailed
                | FailureCode::AppNotRunning
                | FailureCode::SimulatorNotBooted
                | FailureCode::TapMissed
                | FailureCode::CoordinateSpaceMismatch
                | FailureCode::DriverError
                | FailureCode::CaptureBackpressure
                | FailureCode::AppNotInForeground => {}
            }
            // Every code renders as a wire string, and a code whose
            // string nobody wrote would reach a consumer as whatever
            // the formatter defaults to.
            assert!(!format_code(code).is_empty(), "{code:?} has no wire string");
        }
        assert_eq!(
            every.len(),
            13,
            "counted off the list above, not remembered"
        );
    }
}