pixelactions 0.9.6

//! Verification — asking the sister tool whether a region is still there.
//!
//! `pixelcoords find` captures the screen fresh and re-locates every
//! selection by its saved crop. That is the only honest way to know an
//! action landed: `assert` never captures, so it can only answer
//! questions about the file.
//!
//! We shell out rather than link, because `find` needs a screen capture —
//! platform work pixelcoords already owns and this crate must not
//! duplicate (see AGENTS.md, the compatibility contract).

use std::path::Path;
use std::process::Command;
use std::time::Duration;

use anyhow::{Context, Result, bail};
use pixelcoords_core::geometry::Shape;
use serde::Deserialize;

/// The subset of `pixelcoords find --json` this tool reads. Deliberately
/// partial: unknown fields are ignored, so the report can grow upstream
/// without breaking us.
#[derive(Debug, Clone, Deserialize)]
pub struct FindReport {
    pub results: Vec<FindResult>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct FindResult {
    pub label: String,
    pub found: bool,
    #[serde(default)]
    pub ambiguous: bool,
    #[serde(default)]
    pub score: f64,
    #[serde(default)]
    pub delta: Option<Delta>,
    #[serde(default)]
    pub reason: Option<String>,
    /// Which monitor the region was re-found on.
    #[serde(default)]
    pub monitor: usize,
    /// Where the region is **now**, in that monitor's local pixels —
    /// parsed as the sister crate's own `Shape` so the corrected click
    /// point comes from its geometry, not a reimplementation here.
    #[serde(default)]
    pub new_px: Option<Shape>,
}

#[derive(Debug, Clone, Copy, Deserialize)]
pub struct Delta {
    pub dx: i32,
    pub dy: i32,
}

impl FindReport {
    /// The result for one label, matched case-insensitively as pixelcoords
    /// itself matches labels.
    pub fn result_for(&self, label: &str) -> Option<&FindResult> {
        self.results
            .iter()
            .find(|r| r.label.eq_ignore_ascii_case(label))
    }

    /// Whether a label is present, unambiguous, and therefore trustworthy.
    pub fn is_confirmed(&self, label: &str) -> bool {
        self.result_for(label)
            .is_some_and(|r| r.found && !r.ambiguous)
    }

    /// Every region was found **and unambiguous** — the aggregate that
    /// mirrors what the acting path will actually do.
    ///
    /// An empty result set is not success: `find` was asked about regions
    /// and answered about none. Same rule as the sister crate's
    /// `locate::all_relocated`, and stated here so a consumer cannot
    /// hand-roll a weaker one.
    #[must_use]
    pub fn all_confirmed(&self) -> bool {
        !self.results.is_empty() && self.results.iter().all(|r| r.found && !r.ambiguous)
    }

    /// How many regions are trustworthy, and how many matched in more
    /// than one place.
    #[must_use]
    pub fn tally(&self) -> (usize, usize) {
        let confirmed = self
            .results
            .iter()
            .filter(|r| r.found && !r.ambiguous)
            .count();
        let ambiguous = self.results.iter().filter(|r| r.ambiguous).count();
        (confirmed, ambiguous)
    }

    /// The region's current monitor-local click point, when it was found
    /// unambiguously and reported with geometry.
    ///
    /// `None` means "act on the saved coordinates" — either nothing
    /// moved, or the report carried no new shape.
    pub fn corrected_point(
        &self,
        label: &str,
    ) -> Option<(usize, pixelcoords_core::geometry::Point)> {
        let result = self.result_for(label)?;
        if !result.found || result.ambiguous {
            return None;
        }
        let shape = result.new_px.as_ref()?;
        Some((result.monitor, shape.click_point()))
    }
}

/// Run `pixelcoords find` against a session and parse its report.
///
/// A missing binary, a refusal (changed display), and a genuine
/// not-found are three different things, and the caller needs to tell
/// them apart — so only the first two are errors here.
pub fn find(session: &Path, label: Option<&str>) -> Result<FindReport> {
    let mut command = Command::new("pixelcoords");
    command.arg("find").arg("--session").arg(session);
    if let Some(label) = label {
        command.arg("--label").arg(label);
    }

    let output = command.output().context(
        "cannot run `pixelcoords` — it must be on PATH to relocate or verify \
         (cargo install pixelcoords)",
    )?;

    // Exit 2 means pixelcoords could not answer the question at all
    // (unreadable session, changed display). Exit 0 and 1 both produce a
    // report; 1 just means something was not found.
    if output.status.code() == Some(2) {
        let stderr = String::from_utf8_lossy(&output.stderr);
        bail!("pixelcoords find refused: {}", stderr.trim());
    }

    let stdout = String::from_utf8_lossy(&output.stdout);
    serde_json::from_str(&stdout).context("could not parse the report from pixelcoords find")
}

/// The subset of `pixelcoords wait --json` this tool reads. Partial for
/// the same reason `FindReport` is: the report may grow upstream.
#[derive(Debug, Clone, Deserialize)]
pub struct WaitReport {
    /// Whether the condition held before the budget ran out. This is the
    /// answer; the rows below are the evidence for it.
    pub ok: bool,
    #[serde(default)]
    pub polls: u32,
    #[serde(default)]
    pub elapsed_ms: u64,
    #[serde(default)]
    pub results: Vec<WaitResult>,
}

/// Only the score. `label` and `matching` are in the JSON and are
/// deliberately not parsed: a wait here always targets one label, so the
/// name adds nothing, and `matching` is the per-region form of the `ok`
/// this code already reads. Serde ignores what a struct does not name.
#[derive(Debug, Clone, Deserialize)]
pub struct WaitResult {
    #[serde(default)]
    pub score: f64,
}

impl WaitReport {
    /// The best score any watched region reached — what to say when the
    /// wait ran out and the caller wants to know how close it got.
    #[must_use]
    pub fn best_score(&self) -> f64 {
        self.results.iter().map(|r| r.score).fold(0.0_f64, f64::max)
    }
}

/// Block on `pixelcoords wait` until a region matches again, or stops.
///
/// **The polling lives there, not here.** `wait` scores each region at the
/// position the session recorded, in one process that parses the session
/// once; the loop this replaced spawned `pixelcoords find` per iteration,
/// and `find` searches the whole frame — hundreds of milliseconds to over
/// a second each, against microseconds for a score in place.
///
/// It also turns the timeout into a **poll budget** up front rather than
/// consulting a clock, which is the more honest primitive: a wall-clock
/// deadline gives the UI fewer chances exactly when the machine is
/// slowest.
///
/// Exit 1 is a timeout — an answer, carried in `ok`, not an error. Only
/// exit 2 means the question could not be asked.
pub fn wait(
    session: &Path,
    label: &str,
    want_present: bool,
    timeout: Duration,
    interval: Duration,
) -> Result<WaitReport> {
    let mut command = Command::new("pixelcoords");
    command
        .arg("wait")
        .arg("--session")
        .arg(session)
        .arg("--label")
        .arg(label)
        .arg("--for")
        .arg(if want_present { "match" } else { "change" })
        .arg("--timeout")
        .arg(millis(timeout))
        .arg("--interval")
        .arg(millis(interval));
    // `--min-score` is deliberately not passed. Its default there is 0.9,
    // which is the same floor `find` applies internally — so the threshold
    // a wait uses does not change by moving the loop. Making it tunable
    // would be a new flow-file field, and that is a feature, not this.

    let output = command.output().context(
        "cannot run `pixelcoords` — it must be on PATH to wait on a region \
         (cargo install pixelcoords)",
    )?;

    if output.status.code() == Some(2) {
        let stderr = String::from_utf8_lossy(&output.stderr);
        bail!("pixelcoords wait refused: {}", stderr.trim());
    }

    let stdout = String::from_utf8_lossy(&output.stdout);
    serde_json::from_str(&stdout).context("could not parse the report from pixelcoords wait")
}

/// The subset of `pixelcoords diff --json` this tool reads.
#[derive(Debug, Clone, Deserialize)]
pub struct DiffReport {
    /// Whether every region stayed **within** tolerance. `diff` answers
    /// "did this stay the same", so a `changed` step wants this false.
    pub ok: bool,
    #[serde(default)]
    pub results: Vec<DiffResult>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct DiffResult {
    #[serde(default)]
    pub changed_px: u64,
    #[serde(default)]
    pub masked_px: u64,
    #[serde(default)]
    pub changed_pct: f64,
}

impl DiffReport {
    /// How much the first watched region moved, for a step's detail line.
    #[must_use]
    pub fn first(&self) -> Option<&DiffResult> {
        self.results.first()
    }
}

/// Compare a region against the screen now, through `pixelcoords diff`.
///
/// **This is the comparison `verify` cannot make.** `find` and `wait` score
/// by normalized cross-correlation, which is brightness- and
/// contrast-normalized: a region that changes *uniformly* — a dimming
/// backdrop, a luminance-only theme switch — still scores ~1.0. `diff`
/// compares RGB directly, so it sees exactly that.
///
/// Shelled out rather than linked, for the same reason as `find`: it needs
/// a fresh screen capture.
pub fn diff(session: &Path, label: &str, tolerance: f64) -> Result<DiffReport> {
    let output = Command::new("pixelcoords")
        .arg("diff")
        .arg("--session")
        .arg(session)
        .arg("--label")
        .arg(label)
        .arg("--tolerance")
        .arg(format!("{tolerance}"))
        .output()
        .context(
            "cannot run `pixelcoords` — it must be on PATH to compare a region \
             (cargo install pixelcoords)",
        )?;

    // Exit 0 within tolerance, 1 outside it; both produce a report. Only 2
    // means the question could not be asked.
    if output.status.code() == Some(2) {
        let stderr = String::from_utf8_lossy(&output.stderr);
        bail!("pixelcoords diff refused: {}", stderr.trim());
    }

    let stdout = String::from_utf8_lossy(&output.stdout);
    serde_json::from_str(&stdout).context("could not parse the report from pixelcoords diff")
}

/// A duration in the grammar pixelcoords parses: one integer, one unit,
/// no decimals and no compounds. Milliseconds is the unit every value
/// this tool holds is already in.
fn millis(duration: Duration) -> String {
    format!("{}ms", duration.as_millis())
}

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

    fn parsed(json: &str) -> FindReport {
        serde_json::from_str(json).expect("fixture")
    }

    /// The rule the acting path enforces: a crop matching in three places
    /// yields no point worth acting on, so it is not "located".
    #[test]
    fn an_ambiguous_region_is_not_confirmed() {
        let r = parsed(r#"{"results":[{"label":"a","found":true,"ambiguous":true,"score":0.99}]}"#);
        assert!(!r.all_confirmed(), "ambiguous must not count as located");
        assert_eq!(r.tally(), (0, 1));
        assert!(!r.is_confirmed("a"), "consistent with is_confirmed");
    }

    #[test]
    fn every_region_found_and_unambiguous_is_confirmed() {
        let r = parsed(
            r#"{"results":[{"label":"a","found":true,"ambiguous":false,"score":0.99},
                           {"label":"b","found":true,"ambiguous":false,"score":0.98}]}"#,
        );
        assert!(r.all_confirmed());
        assert_eq!(r.tally(), (2, 0));
    }

    /// Asked about regions, answered about none — not success.
    #[test]
    fn an_empty_report_is_not_confirmed() {
        assert!(!parsed(r#"{"results":[]}"#).all_confirmed());
    }

    #[test]
    fn one_bad_region_sinks_the_aggregate() {
        let r = parsed(
            r#"{"results":[{"label":"a","found":true,"ambiguous":false,"score":0.99},
                           {"label":"b","found":false,"ambiguous":false,"score":0.10}]}"#,
        );
        assert!(!r.all_confirmed());
        assert_eq!(r.tally(), (1, 0));
    }

    const REPORT: &str = r#"{
      "schema": 1,
      "captured_utc": "2026-07-28T14:02:11Z",
      "all_relocated": false,
      "results": [
        { "index": 0, "label": "submit", "monitor": 0, "found": true,
          "ambiguous": false, "score": 0.998,
          "old_px": {"x":812,"y":440,"w":96,"h":40},
          "new_px": {"x":812,"y":320,"w":96,"h":40},
          "delta": {"dx":0,"dy":-120} },
        { "index": 1, "label": "gone", "monitor": 0, "found": false,
          "ambiguous": false, "score": 0.42 },
        { "index": 2, "label": "twins", "monitor": 0, "found": true,
          "ambiguous": true, "score": 0.97 }
      ]
    }"#;

    fn report() -> FindReport {
        serde_json::from_str(REPORT).expect("fixture parses")
    }

    #[test]
    fn a_found_unambiguous_region_is_confirmed() {
        assert!(report().is_confirmed("submit"));
    }

    #[test]
    fn a_missing_region_is_not_confirmed() {
        assert!(!report().is_confirmed("gone"));
    }

    #[test]
    fn an_ambiguous_match_is_not_confirmed_even_though_it_was_found() {
        // pixelcoords hands out no coordinates for an ambiguous match, so
        // neither do we — "found twice" is not "found".
        let report = report();
        assert!(report.result_for("twins").expect("present").found);
        assert!(!report.is_confirmed("twins"));
    }

    #[test]
    fn labels_match_case_insensitively() {
        assert!(report().is_confirmed("SUBMIT"));
    }

    #[test]
    fn drift_is_readable_from_the_report() {
        let delta = report()
            .result_for("submit")
            .expect("present")
            .delta
            .expect("moved");
        assert_eq!((delta.dx, delta.dy), (0, -120));
    }

    #[test]
    fn unknown_future_fields_in_the_report_are_ignored() {
        // The compatibility contract, verification side: pixelcoords may
        // add fields to its report at any time.
        let future = REPORT.replace(
            r#""all_relocated": false,"#,
            r#""all_relocated": false, "capture_ms": 680, "engine": "ncc-v2","#,
        );
        let parsed: FindReport = serde_json::from_str(&future).expect("still parses");
        assert!(parsed.is_confirmed("submit"));
    }

    #[test]
    fn a_moved_region_yields_a_corrected_click_point() {
        // submit moved up 120px; its new bbox is 812,320 96x40, whose
        // click point is its center — computed by pixelcoords-core, not
        // by arithmetic written here.
        let (monitor, point) = report()
            .corrected_point("submit")
            .expect("has new geometry");
        assert_eq!(monitor, 0);
        assert_eq!((point.x, point.y), (860, 340));
    }

    #[test]
    fn an_ambiguous_or_missing_region_yields_no_correction() {
        assert!(report().corrected_point("twins").is_none());
        assert!(report().corrected_point("gone").is_none());
    }

    #[test]
    fn a_report_without_optional_fields_still_parses() {
        let minimal = r#"{ "all_relocated": true,
          "results": [{ "label": "a", "found": true }] }"#;
        let parsed: FindReport = serde_json::from_str(minimal).expect("parses");
        assert!(parsed.is_confirmed("a"));
    }
}