hub_codegen/

ir.rs

//! Intermediate Representation types
//!
//! These types match Synapse's IR output format exactly for deserialization.

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

/// Generator tool version information
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct GeneratorInfo {
    /// Tool name (e.g., "synapse", "synapse-cc")
    pub gi_tool: String,
    /// Version string (e.g., "0.2.0.0")
    pub gi_version: String,
}

/// Generation metadata tracking the full toolchain
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct GenerationMetadata {
    /// All tools in the generation chain
    pub gm_generators: Vec<GeneratorInfo>,
    /// ISO 8601 timestamp of generation
    pub gm_timestamp: String,
    /// IR format version
    pub gm_ir_version: String,
}

/// Top-level IR structure (matches Synapse output)
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct IR {
    /// IR format version
    pub ir_version: String,
    /// Backend name (e.g., "substrate", "plexus")
    pub ir_backend: String,
    /// Plexus hash for versioning (optional, computed from schema tree)
    #[serde(default)]
    pub ir_hash: Option<String>,
    /// Generation toolchain metadata
    #[serde(default)]
    pub ir_metadata: Option<GenerationMetadata>,
    /// Named type definitions (structs, enums, aliases)
    pub ir_types: HashMap<String, TypeDef>,
    /// Method definitions keyed by full path (e.g., "cone.chat")
    pub ir_methods: HashMap<String, MethodDef>,
    /// Plugin -> method names mapping
    pub ir_plugins: HashMap<String, Vec<String>>,
}

/// Type definition
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TypeDef {
    pub td_name: String,
    pub td_namespace: String,
    #[serde(default)]
    pub td_description: Option<String>,
    pub td_kind: TypeKind,
}

impl TypeDef {
    /// Compute the fully qualified type name
    pub fn full_name(&self) -> String {
        format!("{}.{}", self.td_namespace, self.td_name)
    }
}

/// Kind of type (Haskell-style tagged union)
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "tag")]
pub enum TypeKind {
    /// Struct with named fields
    KindStruct {
        #[serde(rename = "ksFields")]
        ks_fields: Vec<FieldDef>,
    },
    /// Tagged union (discriminated by "type" field)
    KindEnum {
        /// Field that discriminates (e.g., "type")
        #[serde(rename = "keDiscriminator")]
        ke_discriminator: String,
        #[serde(rename = "keVariants")]
        ke_variants: Vec<VariantDef>,
    },
    /// Type alias
    KindAlias {
        #[serde(rename = "kaTarget")]
        ka_target: TypeRef,
    },
    /// Primitive type
    KindPrimitive {
        #[serde(rename = "kpType")]
        kp_type: String,
        #[serde(rename = "kpFormat")]
        kp_format: Option<String>,
    },
    /// String enum (simple enum with string values)
    KindStringEnum {
        #[serde(rename = "kseValues")]
        kse_values: Vec<String>,
    },
}

/// Field in a struct
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FieldDef {
    pub fd_name: String,
    pub fd_type: TypeRef,
    #[serde(default)]
    pub fd_description: Option<String>,
    #[serde(default)]
    pub fd_required: bool,
    #[serde(default)]
    pub fd_default: Option<serde_json::Value>,
}

/// Variant in an enum
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct VariantDef {
    pub vd_name: String,
    #[serde(default)]
    pub vd_description: Option<String>,
    #[serde(default)]
    pub vd_fields: Vec<FieldDef>,
}

/// Qualified name for type references (namespace.localName)
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct QualifiedName {
    pub qn_namespace: String,
    pub qn_local_name: String,
}

impl QualifiedName {
    /// Get the full qualified name as "namespace.localName" or just "localName" if namespace is empty
    pub fn full_name(&self) -> String {
        if self.qn_namespace.is_empty() {
            self.qn_local_name.clone()
        } else {
            format!("{}.{}", self.qn_namespace, self.qn_local_name)
        }
    }

    /// Get the namespace, returning None if empty
    pub fn namespace(&self) -> Option<&str> {
        if self.qn_namespace.is_empty() {
            None
        } else {
            Some(&self.qn_namespace)
        }
    }

    /// Get the local name
    pub fn local_name(&self) -> &str {
        &self.qn_local_name
    }
}

/// Reference to a type (Haskell-style tagged union with contents)
///
/// Haskell Aeson emits:
/// - Variants with data: {"tag": "RefNamed", "contents": {...}}
/// - Unit variants: {"tag": "RefAny"} (no contents field)
///
/// We use a custom deserializer to handle both cases.
#[derive(Debug, Clone, Serialize)]
pub enum TypeRef {
    /// Named type reference
    RefNamed(QualifiedName),
    /// Primitive type with optional format
    RefPrimitive(String, Option<String>),
    /// Array type
    RefArray(Box<TypeRef>),
    /// Optional type
    RefOptional(Box<TypeRef>),
    /// Intentionally dynamic (serde_json::Value) - accepts any JSON, no warning
    RefAny,
    /// Unknown type (schema gap) - should warn
    RefUnknown,
}

impl<'de> serde::Deserialize<'de> for TypeRef {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        use serde::de::Error;

        let value = serde_json::Value::deserialize(deserializer)?;
        let obj = value.as_object().ok_or_else(|| D::Error::custom("expected object"))?;

        let tag = obj.get("tag")
            .and_then(|v| v.as_str())
            .ok_or_else(|| D::Error::custom("missing tag field"))?;

        match tag {
            "RefNamed" => {
                let contents = obj.get("contents")
                    .ok_or_else(|| D::Error::custom("RefNamed requires contents"))?;
                let qname: QualifiedName = serde_json::from_value(contents.clone())
                    .map_err(|e| D::Error::custom(format!("RefNamed contents must be QualifiedName: {}", e)))?;
                Ok(TypeRef::RefNamed(qname))
            }
            "RefPrimitive" => {
                let contents = obj.get("contents")
                    .and_then(|v| v.as_array())
                    .ok_or_else(|| D::Error::custom("RefPrimitive requires array contents"))?;
                let prim = contents.get(0)
                    .and_then(|v| v.as_str())
                    .ok_or_else(|| D::Error::custom("RefPrimitive[0] must be string"))?;
                let format = contents.get(1)
                    .and_then(|v| v.as_str())
                    .map(|s| s.to_string());
                Ok(TypeRef::RefPrimitive(prim.to_string(), format))
            }
            "RefArray" => {
                let contents = obj.get("contents")
                    .ok_or_else(|| D::Error::custom("RefArray requires contents"))?;
                let inner: TypeRef = serde_json::from_value(contents.clone())
                    .map_err(|e| D::Error::custom(format!("RefArray inner: {}", e)))?;
                Ok(TypeRef::RefArray(Box::new(inner)))
            }
            "RefOptional" => {
                let contents = obj.get("contents")
                    .ok_or_else(|| D::Error::custom("RefOptional requires contents"))?;
                let inner: TypeRef = serde_json::from_value(contents.clone())
                    .map_err(|e| D::Error::custom(format!("RefOptional inner: {}", e)))?;
                Ok(TypeRef::RefOptional(Box::new(inner)))
            }
            "RefAny" => Ok(TypeRef::RefAny),
            "RefUnknown" => Ok(TypeRef::RefUnknown),
            other => Err(D::Error::custom(format!("unknown TypeRef tag: {}", other))),
        }
    }
}

/// Method definition
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MethodDef {
    pub md_name: String,
    pub md_full_path: String,
    pub md_namespace: String,
    #[serde(default)]
    pub md_description: Option<String>,
    #[serde(default)]
    pub md_streaming: bool,
    #[serde(default)]
    pub md_params: Vec<ParamDef>,
    pub md_returns: TypeRef,
    /// Bidirectional channel type parameter T.
    ///
    /// When a method uses `BidirChannel<StandardRequest<T>, StandardResponse<T>>` or
    /// `Arc<StandardBidirChannel>` (the T=Value default), this field describes T.
    ///
    /// - `None`  → the method is not bidirectional, OR it uses the default
    ///             `T = serde_json::Value` (i.e., `StandardBidirChannel`)
    /// - `Some(TypeRef::RefAny)` → bidirectional with T=Value (explicit marker)
    /// - `Some(TypeRef::RefNamed(...))` → bidirectional with a specific T type
    ///
    /// # Schema field
    ///
    /// The synapse IR builder populates this from the `"bidirType"` field in the
    /// method schema JSON (emitted when `bidirectional: true` in `MethodSchema`
    /// with a non-Value `request_type`).  When the schema only has
    /// `bidirectional: true` but no `bidir_type` field, `None` is emitted.
    #[serde(default)]
    pub md_bidir_type: Option<TypeRef>,
}

/// Parameter definition
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ParamDef {
    pub pd_name: String,
    pub pd_type: TypeRef,
    #[serde(default)]
    pub pd_description: Option<String>,
    #[serde(default)]
    pub pd_required: bool,
    #[serde(default)]
    pub pd_default: Option<serde_json::Value>,
}

// === Helper methods for code generation ===

impl TypeRef {
    /// Convert to TypeScript type string (fully qualified - joins namespace.Name as NamespaceName)
    pub fn to_ts(&self) -> String {
        match self {
            TypeRef::RefNamed(qname) => to_upper_camel(&qname.full_name()),
            TypeRef::RefPrimitive(prim, format) => primitive_to_ts(prim, format.as_deref()),
            TypeRef::RefArray(inner) => format!("{}[]", inner.to_ts()),
            TypeRef::RefOptional(inner) => format!("{} | null", inner.to_ts()),
            TypeRef::RefAny => "unknown".to_string(),     // Intentionally dynamic
            TypeRef::RefUnknown => "unknown".to_string(), // Schema gap (will warn)
        }
    }

    /// Convert to TypeScript type string within a namespace context
    /// Always uses local name - cross-namespace types are handled via imports
    pub fn to_ts_in_namespace(&self, current_namespace: &str) -> String {
        match self {
            TypeRef::RefNamed(qname) => {
                // Always use local name - imports handle cross-namespace references
                to_upper_camel(qname.local_name())
            }
            TypeRef::RefPrimitive(prim, format) => primitive_to_ts(prim, format.as_deref()),
            TypeRef::RefArray(inner) => format!("{}[]", inner.to_ts_in_namespace(current_namespace)),
            TypeRef::RefOptional(inner) => format!("{} | null", inner.to_ts_in_namespace(current_namespace)),
            TypeRef::RefAny => "unknown".to_string(),
            TypeRef::RefUnknown => "unknown".to_string(),
        }
    }

    /// Get the namespace from a RefNamed, if qualified
    pub fn get_namespace(&self) -> Option<&str> {
        match self {
            TypeRef::RefNamed(qname) => qname.namespace(),
            _ => None,
        }
    }

    /// Check if this is an unknown type (schema gap that should warn)
    pub fn is_unknown(&self) -> bool {
        matches!(self, TypeRef::RefUnknown)
    }

    /// Check if this contains an unknown type anywhere
    pub fn contains_unknown(&self) -> bool {
        match self {
            TypeRef::RefUnknown => true,
            TypeRef::RefArray(inner) => inner.contains_unknown(),
            TypeRef::RefOptional(inner) => inner.contains_unknown(),
            _ => false,
        }
    }
}

fn primitive_to_ts(prim: &str, format: Option<&str>) -> String {
    match (prim, format) {
        ("string", Some("uuid")) => "string".to_string(), // UUID as string
        ("string", _) => "string".to_string(),
        ("integer", _) | ("number", _) => "number".to_string(),
        ("boolean", _) => "boolean".to_string(),
        ("array", _) => "unknown[]".to_string(),
        ("object", _) => "Record<string, unknown>".to_string(),
        _ => "unknown".to_string(),
    }
}

fn to_upper_camel(s: &str) -> String {
    // Handle namespace-qualified types like "cone.ListResult" → "ConeListResult"
    s.split('.')
        .map(|part| {
            let mut result = String::new();
            let mut capitalize = true;
            for c in part.chars() {
                if c == '_' || c == '-' {
                    capitalize = true;
                } else if capitalize {
                    result.push(c.to_ascii_uppercase());
                    capitalize = false;
                } else {
                    result.push(c);
                }
            }
            result
        })
        .collect::<Vec<_>>()
        .join("")
}

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

    #[test]
    fn test_qualified_name() {
        // Test with namespace
        let qn = QualifiedName {
            qn_namespace: "cone".to_string(),
            qn_local_name: "UUID".to_string(),
        };
        assert_eq!(qn.full_name(), "cone.UUID");
        assert_eq!(qn.namespace(), Some("cone"));
        assert_eq!(qn.local_name(), "UUID");

        // Test without namespace (empty)
        let qn_no_ns = QualifiedName {
            qn_namespace: "".to_string(),
            qn_local_name: "LocalType".to_string(),
        };
        assert_eq!(qn_no_ns.full_name(), "LocalType");
        assert_eq!(qn_no_ns.namespace(), None);
        assert_eq!(qn_no_ns.local_name(), "LocalType");
    }

    #[test]
    fn test_qualified_name_deserialization() {
        // Test deserializing v2.0 format with QualifiedName
        let json = r#"{
            "tag": "RefNamed",
            "contents": {
                "qnNamespace": "cone",
                "qnLocalName": "UUID"
            }
        }"#;
        let type_ref: TypeRef = serde_json::from_str(json).unwrap();

        if let TypeRef::RefNamed(qname) = type_ref {
            assert_eq!(qname.qn_namespace, "cone");
            assert_eq!(qname.qn_local_name, "UUID");
            assert_eq!(qname.full_name(), "cone.UUID");
        } else {
            panic!("Expected RefNamed variant");
        }
    }

    #[test]
    fn test_type_ref_to_ts() {
        let chat_event = TypeRef::RefNamed(QualifiedName {
            qn_namespace: "".to_string(),
            qn_local_name: "ChatEvent".to_string(),
        });
        assert_eq!(chat_event.to_ts(), "ChatEvent");

        assert_eq!(TypeRef::RefPrimitive("string".to_string(), None).to_ts(), "string");
        assert_eq!(TypeRef::RefPrimitive("string".to_string(), Some("uuid".to_string())).to_ts(), "string");
        assert_eq!(TypeRef::RefPrimitive("integer".to_string(), Some("int64".to_string())).to_ts(), "number");

        let node = TypeRef::RefNamed(QualifiedName {
            qn_namespace: "".to_string(),
            qn_local_name: "Node".to_string(),
        });
        assert_eq!(TypeRef::RefArray(Box::new(node)).to_ts(), "Node[]");

        let pos = TypeRef::RefNamed(QualifiedName {
            qn_namespace: "".to_string(),
            qn_local_name: "Pos".to_string(),
        });
        assert_eq!(TypeRef::RefOptional(Box::new(pos)).to_ts(), "Pos | null");

        assert_eq!(TypeRef::RefAny.to_ts(), "unknown");     // Intentional - no warning
        assert_eq!(TypeRef::RefUnknown.to_ts(), "unknown"); // Schema gap - will warn
    }

    #[test]
    fn test_unknown_detection() {
        assert!(!TypeRef::RefAny.is_unknown());
        assert!(TypeRef::RefUnknown.is_unknown());

        let foo = TypeRef::RefNamed(QualifiedName {
            qn_namespace: "".to_string(),
            qn_local_name: "Foo".to_string(),
        });
        assert!(!foo.is_unknown());

        // contains_unknown
        assert!(!TypeRef::RefAny.contains_unknown());
        assert!(TypeRef::RefUnknown.contains_unknown());
        assert!(TypeRef::RefArray(Box::new(TypeRef::RefUnknown)).contains_unknown());
        assert!(!TypeRef::RefArray(Box::new(TypeRef::RefAny)).contains_unknown());
    }

    /// Test that `md_bidir_type` is correctly deserialized from IR JSON.
    ///
    /// Verifies three cases:
    /// 1. Field absent       → `None` (legacy IR / non-bidir method)
    /// 2. `null`             → `None` (explicit null from synapse)
    /// 3. `{"tag":"RefAny"}` → `Some(TypeRef::RefAny)` (T=Value bidir)
    /// 4. `{"tag":"RefNamed",...}` → `Some(TypeRef::RefNamed(...))` (specific T)
    #[test]
    fn test_method_def_bidir_type_deserialization() {
        // 1. Field absent → None (backward compatibility)
        let json_no_field = r#"{
            "mdName": "wizard",
            "mdFullPath": "interactive.wizard",
            "mdNamespace": "interactive",
            "mdStreaming": true,
            "mdParams": [],
            "mdReturns": {"tag": "RefAny"}
        }"#;
        let method: MethodDef = serde_json::from_str(json_no_field).unwrap();
        assert!(method.md_bidir_type.is_none(), "absent field should default to None");

        // 2. Explicit null → None
        let json_null = r#"{
            "mdName": "wizard",
            "mdFullPath": "interactive.wizard",
            "mdNamespace": "interactive",
            "mdStreaming": true,
            "mdParams": [],
            "mdReturns": {"tag": "RefAny"},
            "mdBidirType": null
        }"#;
        let method: MethodDef = serde_json::from_str(json_null).unwrap();
        assert!(method.md_bidir_type.is_none(), "null should deserialize to None");

        // 3. RefAny → Some(TypeRef::RefAny)  (standard bidirectional, T=Value)
        let json_ref_any = r#"{
            "mdName": "wizard",
            "mdFullPath": "interactive.wizard",
            "mdNamespace": "interactive",
            "mdStreaming": true,
            "mdParams": [],
            "mdReturns": {"tag": "RefAny"},
            "mdBidirType": {"tag": "RefAny"}
        }"#;
        let method: MethodDef = serde_json::from_str(json_ref_any).unwrap();
        assert!(
            matches!(method.md_bidir_type, Some(TypeRef::RefAny)),
            "RefAny tag should deserialize to Some(RefAny)"
        );

        // 4. RefNamed → Some(TypeRef::RefNamed(...))  (typed bidirectional)
        let json_ref_named = r#"{
            "mdName": "wizard",
            "mdFullPath": "interactive.wizard",
            "mdNamespace": "interactive",
            "mdStreaming": true,
            "mdParams": [],
            "mdReturns": {"tag": "RefAny"},
            "mdBidirType": {
                "tag": "RefNamed",
                "contents": {
                    "qnNamespace": "interactive",
                    "qnLocalName": "WizardRequest"
                }
            }
        }"#;
        let method: MethodDef = serde_json::from_str(json_ref_named).unwrap();
        if let Some(TypeRef::RefNamed(qn)) = method.md_bidir_type {
            assert_eq!(qn.qn_namespace, "interactive");
            assert_eq!(qn.qn_local_name, "WizardRequest");
        } else {
            panic!("Expected Some(RefNamed(...)) for typed bidirectional");
        }
    }
}