qontinui-types 0.6.0

//! IR (Intermediate Representation) + Legacy wire types for the Spec API.
//!
//! This module is the **single source of truth** for IR types shared across
//! the Qontinui stack. The runner (`qontinui-runner/src-tauri`), supervisor
//! (`qontinui-supervisor`), and any future matcher/projection crates all
//! consume these types via `qontinui_types::ir::*`.
//!
//! ## Two type families
//!
//! - **IR types** (`Ir*`) — authoring surface. The `state-machine.derived.json`
//!   files on disk match this shape (camelCase wire format). Hand-edited or
//!   plugin-generated; never auto-derived from the projection.
//! - **Legacy types** (`Legacy*`) — runtime/output surface. The
//!   `spec.uibridge.json` files match this shape. Auto-regenerated by the
//!   projection layer (`spec_api::projection`) every time the IR is rewritten.
//!
//! ## Conventions
//!
//! - Wire format is `camelCase` via `#[serde(rename_all = "camelCase")]`.
//! - Field-renaming exceptions use explicit `#[serde(rename = "...")]` (the
//!   `IrCrossRef::r#ref` field uses the Rust raw-identifier `r#ref` so the
//!   field name can match the reserved word `ref` on the wire).
//! - Types containing `f64` (e.g. `IrState::path_cost`) cannot derive `Eq`;
//!   the `Eq` vs `PartialEq` choice on each struct is deliberate.
//! - Free-form payload fields (like `IrTransitionAction::params`,
//!   `IrAssertionTarget::criteria`) are `serde_json::Value` so synthesis can
//!   emit partially-populated criteria without tripping the schema and so the
//!   projection passes the bytes through verbatim.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, HashMap};

// ---------------------------------------------------------------------------
// Element criteria
// ---------------------------------------------------------------------------

/// Mirror of `IRElementCriteria`
/// (`qontinui-schemas/ts/src/ui-bridge-ir/element-criteria.ts`).
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct IrElementCriteria {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub role: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tag_name: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub text: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub text_contains: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub aria_label: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub accessible_name: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,
    /// HTML attributes to check (exact string match). Stored as a `BTreeMap`
    /// so JSON serialization is deterministic (matters for byte-stable
    /// projection output).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub attributes: Option<BTreeMap<String, String>>,
}

// ---------------------------------------------------------------------------
// Primitives — IR-only fields (provenance, metadata, effect, cross-refs)
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct IrProvenance {
    /// "hand-authored" | "build-plugin" | "ai-generated" | "migrated"
    pub source: String,
    /// Owning app id (slug). Multi-tenant Spec API contract: every IR
    /// document is self-describing about which registered app it belongs
    /// to. `#[serde(default)]` allows pre-multi-app on-disk IRs (no
    /// `app_id` field) to deserialize as empty string; handlers and the
    /// `POST /apps/<id>/spec/author` adapter validate non-empty and fill
    /// from the URL path on read (Stream C safety-net). Stream F's bulk
    /// backfill rewrites every on-disk IR so empty values don't persist.
    /// TS / Python codegen promote serde defaults to required per the
    /// `qontinui-schemas` project convention.
    ///
    /// `skip_serializing_if = "String::is_empty"` preserves byte-identical
    /// round-trip for pre-multi-app on-disk IRs that lack the field.
    /// Post-Stream-F backfill, every IR has a non-empty `app_id` so the
    /// skip never fires.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub app_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub file: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub line: Option<u32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub column: Option<u32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub plugin_version: Option<String>,
    /// Lifecycle status for the flywheel coverage-growth loop. `None` =
    /// implicitly `Promoted` (legacy + on-disk specs that predate the field).
    /// Set to `Proposed` by `spec_authoring`, `Pending` when staged in
    /// `_pending/`, `Promoted` after the 2-green sweep moves the file to
    /// `pages/<id>/`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<ProposalStatus>,
}

/// Lifecycle status for spec proposals produced by the Stream E coverage-growth
/// flywheel. `None` on an existing `IrProvenance` means the spec predates the
/// flywheel and is implicitly `Promoted`.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
#[serde(rename_all = "kebab-case")]
pub enum ProposalStatus {
    /// Candidate emitted by `spec_authoring` but not yet validated.
    Proposed,
    /// Candidate landed in `_pending/`; awaiting consecutive greens.
    Pending,
    /// Candidate has been promoted to `pages/<id>/`. Default for legacy specs.
    Promoted,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct IrMetadata {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub purpose: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tags: Option<Vec<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub related_elements: Option<Vec<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub notes: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct IrCrossRef {
    pub doc: String,
    /// `ref` is reserved in Rust — serialize as `ref` for the wire while
    /// using `r#ref` as the Rust field name.
    #[serde(rename = "ref")]
    pub r#ref: String,
}

// ---------------------------------------------------------------------------
// Wait spec / transition action
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct IrWaitSpec {
    /// "idle" | "element" | "state" | "time" | "condition" | "vanish" | "change" | "stable"
    #[serde(rename = "type")]
    pub kind: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub query: Option<IrElementCriteria>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub state_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ms: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub property: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quiet_period_ms: Option<u64>,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct IrTransitionAction {
    #[serde(rename = "type")]
    pub kind: String,
    pub target: IrElementCriteria,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub params: Option<serde_json::Value>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wait_after: Option<IrWaitSpec>,
}

// ---------------------------------------------------------------------------
// State / transition / document
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct IrStateCondition {
    pub element: IrElementCriteria,
    /// "visible" | "enabled" | "checked" | "expanded" | "selected" | "text" | "value"
    pub property: String,
    pub expected: serde_json::Value,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub comparator: Option<String>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct IrState {
    pub id: String,
    pub name: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    pub assertions: Vec<IrAssertion>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub excluded_elements: Option<Vec<IrElementCriteria>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub conditions: Option<Vec<IrStateCondition>>,

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub is_initial: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub is_terminal: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub blocking: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub group: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path_cost: Option<f64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub precondition: Option<String>,

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub element_ids: Option<Vec<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub incoming_transitions: Option<Vec<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<IrMetadata>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provenance: Option<IrProvenance>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cross_refs: Option<Vec<IrCrossRef>>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct IrTransition {
    pub id: String,
    pub name: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    pub from_states: Vec<String>,
    pub activate_states: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub exit_states: Option<Vec<String>>,

    pub actions: Vec<IrTransitionAction>,

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path_cost: Option<f64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub bidirectional: Option<bool>,

    /// "read" | "write" | "destructive"
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub effect: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<IrMetadata>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provenance: Option<IrProvenance>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cross_refs: Option<Vec<IrCrossRef>>,
}

/// Top-level IR page specification (formerly `IrDocument`).
///
/// One `IrPageSpec` corresponds to one `state-machine.derived.json` file on
/// disk under `qontinui-runner/specs/pages/<id>/`. This is the authoring
/// surface — the projection layer derives the runtime `LegacySpec` from this.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct IrPageSpec {
    /// Schema version. Currently always `"1.0"`.
    pub version: String,
    pub id: String,
    pub name: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<IrMetadata>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provenance: Option<IrProvenance>,

    pub states: Vec<IrState>,
    pub transitions: Vec<IrTransition>,

    /// Groups produced by workflow-criteria synthesis (NOT derived from
    /// `IRState` annotations). Mirror of TS `IRDocument.synthesizedGroups`.
    /// The `rename = "synthesizedGroups"` is explicit (rather than relying on
    /// `rename_all = "camelCase"`) so the serialized name is unambiguous in
    /// snapshot tests + cross-language fixtures.
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        rename = "synthesizedGroups"
    )]
    pub synthesized_groups: Option<Vec<IrGroup>>,

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub initial_state: Option<String>,

    /// Per-page API-contract assertions evaluated by the Spec CI harness.
    /// Phase 1: value-level assertions (status_code, json_path, header,
    /// body_contains, response_time). Phase 2 will add schema conformance.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub api_assertions: Option<Vec<IrApiCheck>>,
}

// ---------------------------------------------------------------------------
// API-contract checks (evaluated by the Spec CI harness, not in-browser).
//
// Each `IrApiCheck` describes an HTTP request to issue against the running
// backend and a set of assertions to evaluate against the response. The
// harness uses Playwright's `APIRequestContext` so auth cookies are shared.
// ---------------------------------------------------------------------------

/// A single API-contract check: issue a request, validate the response.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct IrApiCheck {
    pub id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    pub request: IrApiRequest,
    #[serde(default = "default_read_effect")]
    pub effect: String,
    pub assertions: Vec<IrApiAssertion>,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct IrApiRequest {
    pub method: String,
    pub path: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub headers: Option<HashMap<String, String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub body: Option<serde_json::Value>,
}

/// API assertion: either a value-level assertion (status_code, json_path, etc.)
/// or a schema-conformance assertion (conforms_to — Phase 2 placeholder).
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
#[serde(tag = "type")]
pub enum IrApiAssertion {
    #[serde(rename = "status_code")]
    StatusCode {
        expected: serde_json::Value,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        operator: Option<String>,
    },
    #[serde(rename = "json_path")]
    JsonPath {
        json_path: String,
        expected: serde_json::Value,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        operator: Option<String>,
    },
    #[serde(rename = "header")]
    Header {
        header_name: String,
        expected: serde_json::Value,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        operator: Option<String>,
    },
    #[serde(rename = "body_contains")]
    BodyContains { expected: serde_json::Value },
    #[serde(rename = "response_time")]
    ResponseTime {
        expected: serde_json::Value,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        operator: Option<String>,
    },
    #[serde(rename = "conforms_to")]
    ConformsTo { schema: String },
}

fn default_read_effect() -> String {
    "read".to_string()
}

// ---------------------------------------------------------------------------
// IR-side groups + assertions (mirror of `qontinui-schemas/ts/src/ui-bridge-ir/group.ts`).
//
// These are NOT the legacy `*.spec.uibridge.json` shapes — those live below
// (`LegacyGroup`, `LegacyAssertion`). The IR carries a free-form group channel
// for synthesis output that the projection appends after state-derived groups.
// ---------------------------------------------------------------------------

/// Mirror of TS `IRAssertionTarget`. Always `type: "search"` for synthesis-
/// emitted assertions; the wider legacy schema also supports point/region
/// targets but the IR doesn't express those today.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
pub struct IrAssertionTarget {
    /// Always `"search"` for synthesis-emitted assertions.
    #[serde(rename = "type")]
    pub kind: String,
    /// Free-form criteria object — kept as `Value` so synthesis can emit
    /// partially-populated criteria without tripping the schema and so the
    /// projection can pass the bytes through verbatim.
    pub criteria: serde_json::Value,
    pub label: String,
}

/// Mirror of TS `IRAssertion`. Field shape matches `LegacyAssertion` one-to-one
/// (modulo the `target.criteria` looseness).
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct IrAssertion {
    pub id: String,
    pub description: String,
    pub category: String,
    pub severity: String,
    pub assertion_type: String,
    pub target: IrAssertionTarget,
    pub source: String,
    pub reviewed: bool,
    pub enabled: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub precondition: Option<String>,
}

/// Mirror of TS `IRGroup`. Synthesis-produced groups (NOT derived from IR
/// states). Mirrors the legacy `SpecGroup` shape so the projection can pass
/// it through to legacy `groups[]` without loss.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
pub struct IrGroup {
    pub id: String,
    pub name: String,
    pub description: String,
    pub category: String,
    pub assertions: Vec<IrAssertion>,
    /// Provenance of the group itself (typically `"ai-generated"` for
    /// synthesis output).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source: Option<String>,
    /// Free-form tags. Synthesis emits e.g.
    /// `["workflow-generated", "acceptance-criteria"]`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tags: Option<Vec<String>>,
}

// ---------------------------------------------------------------------------
// Legacy spec shapes — output of the projection (mirrors `LegacySpec` in
// `qontinui-schemas/ts/src/ui-bridge-ir/projection.ts`).
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
pub struct LegacyAssertionTarget {
    /// Always `"search"` for the projection — point/region targets aren't
    /// expressible in the IR.
    #[serde(rename = "type")]
    pub kind: String,
    /// Free-form criteria object — kept as `Value` so we don't lose any
    /// inverse-projection round-trip information.
    pub criteria: serde_json::Value,
    pub label: String,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct LegacyAssertion {
    pub id: String,
    pub description: String,
    pub category: String,
    pub severity: String,
    pub assertion_type: String,
    pub target: LegacyAssertionTarget,
    pub source: String,
    pub reviewed: bool,
    pub enabled: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub precondition: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
pub struct LegacyGroup {
    pub id: String,
    pub name: String,
    pub description: String,
    pub category: String,
    pub assertions: Vec<LegacyAssertion>,
    pub source: String,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct LegacyProcessStep {
    pub action: String,
    pub target: serde_json::Value,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wait_after: Option<IrWaitSpec>,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct LegacyTransition {
    pub id: String,
    pub name: String,
    pub activate_states: Vec<String>,
    pub deactivate_states: Vec<String>,
    pub stays_visible: bool,
    pub process: Vec<LegacyProcessStep>,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct LegacyStateMachineState {
    pub id: String,
    pub name: String,
    pub description: String,
    pub elements: Vec<serde_json::Value>,
    pub is_initial: bool,
    pub transitions: Vec<LegacyTransition>,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
pub struct LegacyStateMachine {
    pub states: Vec<LegacyStateMachineState>,
}

/// Top-level legacy spec output. Serialized via a `serde_json::Value` step
/// so the projection can apply lexicographic key sorting at the end (matches
/// the TS projection's `sortKeys` pass).
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct LegacySpec {
    pub version: String,
    pub description: String,
    pub groups: Vec<LegacyGroup>,
    pub state_machine: LegacyStateMachine,
    pub metadata: serde_json::Value,
}

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

    #[test]
    fn provenance_without_status_round_trips_byte_identical() {
        // Legacy spec on-disk shape: no `status` field. Must survive a
        // from_str -> to_string round trip without gaining one.
        let json = r#"{"source":"hand-authored","file":"a.tsx","line":12}"#;
        let parsed: IrProvenance = serde_json::from_str(json).unwrap();
        assert_eq!(parsed.status, None);
        let reserialized = serde_json::to_string(&parsed).unwrap();
        assert_eq!(reserialized, json);
    }

    #[test]
    fn provenance_with_proposed_status_round_trips() {
        let json = r#"{"source":"ai-generated","status":"proposed"}"#;
        let parsed: IrProvenance = serde_json::from_str(json).unwrap();
        assert_eq!(parsed.status, Some(ProposalStatus::Proposed));
        let reserialized = serde_json::to_string(&parsed).unwrap();
        assert_eq!(reserialized, json);
    }

    #[test]
    fn proposal_status_kebab_case_variants() {
        // Every variant deserializes from its kebab-case wire form and
        // round-trips back to it. Catches accidental rename_all drift.
        for (wire, variant) in [
            ("\"proposed\"", ProposalStatus::Proposed),
            ("\"pending\"", ProposalStatus::Pending),
            ("\"promoted\"", ProposalStatus::Promoted),
        ] {
            let parsed: ProposalStatus = serde_json::from_str(wire).unwrap();
            assert_eq!(parsed, variant);
            assert_eq!(serde_json::to_string(&parsed).unwrap(), wire);
        }
    }
}