smix_verbs/

lib.rs

//! smix-verbs — canonical verb table.
//!
//! # Reviewer invariant
//!
//! Any new yaml verb supported by smix MUST land here first as a
//! [`VerbEntry`] in [`VERB_TABLE`]. Both `smix-adapter-maestro` parser
//! and `smix-migrate` codemod depend on this crate; adding an entry
//! automatically makes the parser accept both canonical forms and the
//! codemod handle the rename.
//!
//! # Design
//!
//! - **Pure data crate** — no runtime state, no async, no I/O.
//! - **Static table** — `&'static [VerbEntry]` for zero-alloc lookup.
//! - **Two names per entry** — `maestro_name` (the yaml surface maestro
//!   test authors know) and `smix_name` (the smix-canonical form). If
//!   they're identical (e.g. `runFlow`), the entry still appears with
//!   both fields set to the same string.
//! - **Category** — grouping for reviewer sanity checks + future
//!   auto-generated cross-platform parity tables.
//! - **Arg shape** — the verb's *primary* yaml shape, and only that.
//!   Informational, reserved for a future codemod arg-transform lookup.
//!
//! # What this table does and does not guarantee
//!
//! Membership is enforced: a test in `smix-adapter-maestro` fails if the
//! parser dispatches a verb with no [`VerbEntry`], so the table cannot
//! silently fall behind the parser again.
//!
//! `arg_shape` is **not** enforced, and cannot be. Many verbs accept more
//! than one shape — `waitForAnimationToEnd` takes bare, numeric, and
//! `{ timeout }` — while [`ArgShape`] holds a single value. Teaching it
//! unions would mean encoding the yaml grammar in an enum that exists to
//! label rows. So it names the shape a reader should expect first, and the
//! parser remains the authority on what actually parses.

#![forbid(unsafe_code)]

/// Keys a selector mapping may carry in yaml.
///
/// The parser refuses anything else, and `smix migrate` warns about it
/// before a user discovers the refusal at run time — so the two must
/// read one list. They did not: the parser owned it privately, migrate
/// knew only about verbs, and a flow with `enabled:` migrated cleanly,
/// exited 0, and then failed to parse.
///
/// Covers the selector discriminators, the spatial modifiers, and the
/// per-verb options that ride in the same mapping.
pub const SELECTOR_KEYS: &[&str] = &[
    // discriminators
    "text",
    "id",
    "label",
    "role",
    "name",
    "point",
    "localized_text",
    "localizedText",
    "ocrText",
    "anchored",
    "anchorRelative",
    "fallback",
    "focused",
    // spatial + positional modifiers
    "near",
    "below",
    "above",
    "leftOf",
    "rightOf",
    "inside",
    "ancestor",
    "nth",
    "index",
    "first",
    "last",
    // per-verb options sharing the mapping
    "optional",
    "dispatch",
    "pattern",
    "recognition_level",
    "locales",
    "timeout",
    "requireOnScreen",
    "duration",
    // repeatTap
    "times",
    "intervalMs",
    "holdMs",
    // longPressOn
    "captureDuring",
];

/// One verb in the canonical table.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct VerbEntry {
    /// Maestro yaml surface name (`tapOn`, `assertVisible`, ...).
    pub maestro_name: &'static str,
    /// smix-canonical surface name (`tap`, `expect`, ...).
    pub smix_name: &'static str,
    /// Grouping category. Used by the future cross-platform parity
    /// audit table.
    pub category: VerbCategory,
    /// Shape of the argument — informational; used by codemod's
    /// argument transform lookup + parser's shape validation.
    pub arg_shape: ArgShape,
}

/// Semantic grouping for a verb.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VerbCategory {
    /// Tap-family (tap, tapOn, doubleTap, longPress, tapByCoord).
    Tap,
    /// Text-input family (inputText / fill, eraseText / clear,
    /// pasteText, setClipboard).
    Input,
    /// Assertion / expectation (assertVisible / expect,
    /// assertNotVisible, assertTrue, extendedWaitUntil, expect.signal).
    Assert,
    /// Navigation / control flow (runFlow, retry, repeat,
    /// pressKey, back).
    ControlFlow,
    /// App lifecycle (launchApp, stopApp / terminate, killApp,
    /// clearState / reset, clearKeychain / resetKeychain).
    Lifecycle,
    /// Screen / media (takeScreenshot, assertScreenshot,
    /// startRecording, stopRecording, addMedia).
    Media,
    /// Gesture / motion (scroll, scrollUntilVisible, swipe,
    /// swipeOnce, hideKeyboard).
    Gesture,
    /// Device-level control (openLink / openUrl, setLocation,
    /// travel, setPermissions, setOrientation).
    Device,
    /// smix-native extensions (ocrText, anchorRelative, tapById,
    /// fixture, webviewEval).
    SmixNative,
    /// Utility / diagnostic (waitForAnimationToEnd, evalScript,
    /// copyTextFrom, assertWithAI).
    Utility,
}

/// A verb's primary yaml argument shape.
///
/// One value per verb, so a verb accepting several shapes is recorded by
/// its most common one — see the crate header. The parser decides what
/// actually parses.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ArgShape {
    /// No argument (`- back`, `- stopApp`, `- waitForAnimationToEnd`).
    None,
    /// Bare string (`- inputText: hello`, `- pressKey: enter`).
    BareString,
    /// Selector — short-form string OR long-form mapping
    /// (`{ text | id | label ... }`).
    Selector,
    /// Mapping with domain-specific keys (`launchApp`, `extendedWaitUntil`,
    /// `assertScreenshot`, `expect.signal`).
    Mapping,
    /// Path string (`- runFlow: path/to.yaml`).
    Path,
    /// Coordinate pair or normalized 0..1 point
    /// (`tapOn: { point: "X%,Y%" }`).
    Coord,
    /// Integer count (`eraseText: 5`).
    Integer,
}

/// Static canonical verb table. Ordering: category-alphabetized
/// for grep-ability; each row is `(maestro, smix, category, shape)`.
pub static VERB_TABLE: &[VerbEntry] = &[
    // ----- Tap family -----
    v("tapOn", "tap", VerbCategory::Tap, ArgShape::Selector),
    v(
        "doubleTapOn",
        "doubleTap",
        VerbCategory::Tap,
        ArgShape::Selector,
    ),
    v(
        "longPressOn",
        "longPress",
        VerbCategory::Tap,
        ArgShape::Selector,
    ),
    // No maestro counterpart: maestro drives repeated taps with
    // `repeat`, which sends one request per tap. That is the thing this
    // exists to stop doing.
    v(
        "repeatTap",
        "repeatTap",
        VerbCategory::Tap,
        ArgShape::Mapping,
    ),
    // ----- Input family -----
    v(
        "inputText",
        "fill",
        VerbCategory::Input,
        ArgShape::BareString,
    ),
    v("eraseText", "clear", VerbCategory::Input, ArgShape::Integer),
    v(
        "pasteText",
        "pasteText",
        VerbCategory::Input,
        ArgShape::None,
    ),
    v(
        "setClipboard",
        "setClipboard",
        VerbCategory::Input,
        ArgShape::BareString,
    ),
    v(
        "copyTextFrom",
        "copyTextFrom",
        VerbCategory::Input,
        ArgShape::Selector,
    ),
    // ----- Assert family -----
    v(
        "assertVisible",
        "expect",
        VerbCategory::Assert,
        ArgShape::Selector,
    ),
    v(
        "assertNotVisible",
        "expectNotVisible",
        VerbCategory::Assert,
        ArgShape::Selector,
    ),
    v(
        "extendedWaitUntil",
        "expect",
        VerbCategory::Assert,
        ArgShape::Mapping,
    ),
    v(
        "assertTrue",
        "assertTrue",
        VerbCategory::Assert,
        ArgShape::BareString,
    ),
    v(
        "assertScreenshot",
        "assertScreenshot",
        VerbCategory::Assert,
        ArgShape::Mapping,
    ),
    // The AI-assertion tier. Opt-in and non-deterministic: a verdict comes
    // from a local `claude` CLI judging a screenshot, so these two are the
    // only verbs in the table whose result is a judgement rather than a
    // measurement.
    v(
        "assertWithAI",
        "assertCondition",
        VerbCategory::Assert,
        ArgShape::BareString,
    ),
    v(
        "extractTextWithAI",
        "extractWithAI",
        VerbCategory::Assert,
        ArgShape::Mapping,
    ),
    // ----- Control flow -----
    v(
        "runFlow",
        "runFlow",
        VerbCategory::ControlFlow,
        ArgShape::Path,
    ),
    v(
        "retry",
        "retry",
        VerbCategory::ControlFlow,
        ArgShape::Mapping,
    ),
    v(
        "repeat",
        "repeat",
        VerbCategory::ControlFlow,
        ArgShape::Mapping,
    ),
    v(
        "pressKey",
        "pressKey",
        VerbCategory::ControlFlow,
        ArgShape::BareString,
    ),
    v(
        "back",
        "pressKey",
        VerbCategory::ControlFlow,
        ArgShape::None,
    ),
    // ----- Lifecycle -----
    v(
        "launchApp",
        "launchApp",
        VerbCategory::Lifecycle,
        ArgShape::Mapping,
    ),
    v(
        "stopApp",
        "terminate",
        VerbCategory::Lifecycle,
        ArgShape::None,
    ),
    v(
        "killApp",
        "terminate",
        VerbCategory::Lifecycle,
        ArgShape::BareString,
    ),
    v(
        "clearState",
        "reset",
        VerbCategory::Lifecycle,
        ArgShape::None,
    ),
    v(
        "clearKeychain",
        "resetKeychain",
        VerbCategory::Lifecycle,
        ArgShape::None,
    ),
    // ----- Media -----
    v(
        "takeScreenshot",
        "takeScreenshot",
        VerbCategory::Media,
        ArgShape::BareString,
    ),
    v(
        "startRecording",
        "startRecording",
        VerbCategory::Media,
        ArgShape::BareString,
    ),
    v(
        "stopRecording",
        "stopRecording",
        VerbCategory::Media,
        ArgShape::None,
    ),
    v(
        "addMedia",
        "addMedia",
        VerbCategory::Media,
        ArgShape::Mapping,
    ),
    // ----- Gesture -----
    v("scroll", "scroll", VerbCategory::Gesture, ArgShape::None),
    v(
        "scrollUntilVisible",
        "scroll",
        VerbCategory::Gesture,
        ArgShape::Mapping,
    ),
    v("swipe", "swipe", VerbCategory::Gesture, ArgShape::Mapping),
    v(
        "hideKeyboard",
        "hideKeyboard",
        VerbCategory::Gesture,
        ArgShape::None,
    ),
    // ----- Device -----
    v(
        "openLink",
        "openUrl",
        VerbCategory::Device,
        ArgShape::BareString,
    ),
    v(
        "setLocation",
        "setLocation",
        VerbCategory::Device,
        ArgShape::Mapping,
    ),
    v("travel", "travel", VerbCategory::Device, ArgShape::Mapping),
    v(
        "setPermissions",
        "setPermissions",
        VerbCategory::Device,
        ArgShape::Mapping,
    ),
    v(
        "setOrientation",
        "setOrientation",
        VerbCategory::Device,
        ArgShape::BareString,
    ),
    // ----- smix-native extensions (parity with parser dispatch_step) -----
    v(
        "webview_eval",
        "webviewEval",
        VerbCategory::SmixNative,
        ArgShape::BareString,
    ),
    // The spelling three of four guides use — WebView camelized as one
    // word. Same canonical name; the parser accepts all three.
    v(
        "webViewEval",
        "webviewEval",
        VerbCategory::SmixNative,
        ArgShape::BareString,
    ),
    v(
        "webviewEval",
        "webviewEval",
        VerbCategory::SmixNative,
        ArgShape::BareString,
    ),
    v(
        "fixture",
        "fixture",
        VerbCategory::SmixNative,
        ArgShape::Mapping,
    ),
    v(
        "expect",
        "expect",
        VerbCategory::SmixNative,
        ArgShape::Mapping,
    ),
    // ----- Utility -----
    v(
        "waitForAnimationToEnd",
        "waitForAnimationToEnd",
        VerbCategory::Utility,
        ArgShape::None,
    ),
    // ----- Lifecycle / Assert additions: parser-accepted verbs that
    // were absent from the table. VERB_TABLE is the enforced single
    // source of truth (a parser-dispatch ⊆ VERB_TABLE test guards it);
    // these have Step:: variants + parser dispatch but no entry until now.
    v(
        "clearAppData",
        "clearAppData",
        VerbCategory::Lifecycle,
        ArgShape::Mapping,
    ),
    v(
        "resetAppData",
        "resetAppData",
        VerbCategory::Lifecycle,
        ArgShape::Mapping,
    ),
    v(
        "clearUserDefaults",
        "clearUserDefaults",
        VerbCategory::Lifecycle,
        ArgShape::Mapping,
    ),
    v(
        "expectLogClean",
        "expectLogClean",
        VerbCategory::Assert,
        ArgShape::None,
    ),
    // Note: `evalScript` / `runScript` deliberately NOT in the table —
    // they're valid maestro verbs but flagged as unknown by migrate to
    // warn corpus maintainers that porting requires manual review
    // (typical case: script bodies contain maestro-specific APIs).
    // Consumers who want them silently preserved can add rows locally.
];

const fn v(
    maestro_name: &'static str,
    smix_name: &'static str,
    category: VerbCategory,
    arg_shape: ArgShape,
) -> VerbEntry {
    VerbEntry {
        maestro_name,
        smix_name,
        category,
        arg_shape,
    }
}

/// Look up a verb entry by its maestro-canonical name.
pub fn find_by_maestro(name: &str) -> Option<&'static VerbEntry> {
    VERB_TABLE.iter().find(|e| e.maestro_name == name)
}

/// Look up a verb entry by its smix-canonical name. May return
/// multiple different entries because smix names are not unique
/// (e.g. `pressKey` is the smix name for both `pressKey` and
/// `back`); we return the first match. Consumers that need
/// disambiguation should use [`find_by_maestro`] or scan
/// [`VERB_TABLE`] directly.
pub fn find_by_smix(name: &str) -> Option<&'static VerbEntry> {
    VERB_TABLE.iter().find(|e| e.smix_name == name)
}

/// True if `name` matches either the maestro or smix form of any
/// known verb.
pub fn is_known_verb(name: &str) -> bool {
    find_by_maestro(name).is_some() || find_by_smix(name).is_some()
}

/// Return every entry in a given category. Iteration order is the
/// insertion order in [`VERB_TABLE`].
pub fn verbs_in_category(category: VerbCategory) -> impl Iterator<Item = &'static VerbEntry> {
    VERB_TABLE.iter().filter(move |e| e.category == category)
}

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

    #[test]
    fn find_by_maestro_hits() {
        let e = find_by_maestro("tapOn").unwrap();
        assert_eq!(e.smix_name, "tap");
        assert_eq!(e.category, VerbCategory::Tap);
    }

    #[test]
    fn find_by_smix_hits() {
        let e = find_by_smix("tap").unwrap();
        assert_eq!(e.maestro_name, "tapOn");
    }

    #[test]
    fn find_by_smix_returns_first_when_multiple_match() {
        // `pressKey` is the smix name for both `pressKey` and `back`
        // entries. find_by_smix returns the FIRST hit — that's
        // documented behavior; consumers wanting disambiguation
        // must scan VERB_TABLE directly.
        let e = find_by_smix("pressKey").unwrap();
        assert!(e.maestro_name == "pressKey" || e.maestro_name == "back");
    }

    #[test]
    fn is_known_covers_both_forms() {
        assert!(is_known_verb("tapOn"));
        assert!(is_known_verb("tap"));
        assert!(is_known_verb("assertVisible"));
        assert!(is_known_verb("expect"));
        assert!(!is_known_verb("nonexistent"));
    }

    #[test]
    fn extendedwait_maps_to_expect() {
        let e = find_by_maestro("extendedWaitUntil").unwrap();
        assert_eq!(e.smix_name, "expect");
        assert_eq!(e.category, VerbCategory::Assert);
        assert_eq!(e.arg_shape, ArgShape::Mapping);
    }

    #[test]
    fn table_has_no_duplicate_maestro_names() {
        let mut seen = Vec::new();
        for e in VERB_TABLE {
            if seen.contains(&e.maestro_name) {
                panic!("duplicate maestro_name: {}", e.maestro_name);
            }
            seen.push(e.maestro_name);
        }
    }

    #[test]
    fn each_category_has_at_least_one_entry() {
        for cat in [
            VerbCategory::Tap,
            VerbCategory::Input,
            VerbCategory::Assert,
            VerbCategory::ControlFlow,
            VerbCategory::Lifecycle,
            VerbCategory::Media,
            VerbCategory::Gesture,
            VerbCategory::Device,
            VerbCategory::SmixNative,
            VerbCategory::Utility,
        ] {
            let count = verbs_in_category(cat).count();
            assert!(count > 0, "category {cat:?} has no entries");
        }
    }

    #[test]
    fn table_covers_v0_2_5_migrate_default_rules() {
        // Sanity: every maestro name from smix-migrate's original
        // DEFAULT_RULES table is present here.
        for name in [
            "tapOn",
            "assertVisible",
            "assertNotVisible",
            "extendedWaitUntil",
            "inputText",
            "eraseText",
            "clearState",
            "clearKeychain",
            "runFlow",
            "launchApp",
            "stopApp",
            "killApp",
            "openLink",
            "back",
            "hideKeyboard",
            "pressKey",
            "scroll",
            "scrollUntilVisible",
            "swipe",
            "retry",
        ] {
            assert!(
                find_by_maestro(name).is_some(),
                "v0.2.5 DEFAULT_RULES verb {name:?} missing from VERB_TABLE"
            );
        }
    }

    #[test]
    fn table_covers_smix_native_verbs() {
        for name in ["fixture", "webviewEval"] {
            assert!(
                find_by_smix(name).is_some() || find_by_maestro(name).is_some(),
                "smix-native verb {name:?} missing from VERB_TABLE"
            );
        }
    }
}