sea_core/projection/

protobuf.rs

//! Protobuf Projection Engine
//!
//! This module provides functionality to project SEA semantic graphs to Protocol Buffer
//! (`.proto`) files. It supports:
//!
//! - Entity and Resource projection to Protobuf messages
//! - Type mapping from SEA types to Protobuf scalar types
//! - Deterministic field numbering for schema stability
//! - Governance message generation
//!
//! # Example
//!
//! ```rust,ignore
//! use sea_core::projection::protobuf::ProtobufEngine;
//! use sea_core::graph::Graph;
//!
//! let graph = build_graph_from_model();
//! let proto_file = ProtobufEngine::project(&graph, "my_namespace", "my.package");
//! println!("{}", proto_file.to_proto_string());
//! ```

use crate::graph::Graph;
use crate::primitives::{Entity, Resource};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::{BTreeMap, HashMap, HashSet};
use std::path::PathBuf;

// ============================================================================
// Protobuf IR Types
// ============================================================================

/// Represents a complete `.proto` file.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProtoFile {
    /// The package name (e.g., "sea.example")
    pub package: String,
    /// Protobuf syntax version (always "proto3")
    pub syntax: String,
    /// Import statements
    pub imports: Vec<String>,
    /// File-level options
    pub options: ProtoOptions,
    /// Enum definitions
    pub enums: Vec<ProtoEnum>,
    /// Message definitions
    pub messages: Vec<ProtoMessage>,
    /// gRPC service definitions
    pub services: Vec<ProtoService>,
    /// Metadata about the projection
    pub metadata: ProtoMetadata,
}

impl ProtoFile {
    /// Create a new ProtoFile with the given package name.
    pub fn new(package: impl Into<String>) -> Self {
        Self {
            package: package.into(),
            syntax: "proto3".to_string(),
            imports: Vec::new(),
            options: ProtoOptions::default(),
            enums: Vec::new(),
            messages: Vec::new(),
            services: Vec::new(),
            metadata: ProtoMetadata::default(),
        }
    }

    /// Serialize the ProtoFile to `.proto` text format.
    pub fn to_proto_string(&self) -> String {
        let mut out = String::new();

        // Header comments
        out.push_str("// Generated by SEA Projection Framework\n");
        out.push_str(&format!(
            "// Projection: {}\n",
            self.metadata.projection_name
        ));
        out.push_str(&format!(
            "// Source Namespace: {}\n",
            self.metadata.source_namespace
        ));
        if let Some(ref version) = self.metadata.semantic_version {
            out.push_str(&format!("// Version: {}\n", version));
        }
        out.push_str(&format!(
            "// Generated At: {}\n",
            self.metadata.generated_at
        ));
        out.push_str("// DO NOT EDIT - This file is auto-generated\n\n");

        // Syntax
        out.push_str(&format!("syntax = \"{}\";\n\n", self.syntax));

        // Package
        out.push_str(&format!("package {};\n", self.package));

        // Options
        let options = &self.options;

        if let Some(ref pkg) = options.java_package {
            out.push_str(&format!("\noption java_package = \"{}\";", pkg));
        }
        if options.java_multiple_files {
            out.push_str("\noption java_multiple_files = true;");
        }
        if let Some(ref pkg) = options.go_package {
            out.push_str(&format!("\noption go_package = \"{}\";", pkg));
        }
        if let Some(ref ns) = options.csharp_namespace {
            out.push_str(&format!("\noption csharp_namespace = \"{}\";", ns));
        }
        if let Some(ref ns) = options.php_namespace {
            out.push_str(&format!("\noption php_namespace = \"{}\";", ns));
        }
        if let Some(ref pkg) = options.ruby_package {
            out.push_str(&format!("\noption ruby_package = \"{}\";", pkg));
        }
        if let Some(ref prefix) = options.swift_prefix {
            out.push_str(&format!("\noption swift_prefix = \"{}\";", prefix));
        }
        if let Some(ref prefix) = options.objc_class_prefix {
            out.push_str(&format!("\noption objc_class_prefix = \"{}\";", prefix));
        }
        if let Some(ref opt) = options.optimize_for {
            out.push_str(&format!("\noption optimize_for = {};", opt));
        }
        if options.deprecated {
            out.push_str("\noption deprecated = true;");
        }

        // Custom options
        for custom in &options.custom_options {
            out.push_str(&format!("\n{}", custom.to_proto_string()));
        }

        if options.java_package.is_some()
            || options.java_multiple_files
            || options.go_package.is_some()
            || options.csharp_namespace.is_some()
            || options.php_namespace.is_some()
            || options.ruby_package.is_some()
            || options.swift_prefix.is_some()
            || options.objc_class_prefix.is_some()
            || options.optimize_for.is_some()
            || options.deprecated
            || !options.custom_options.is_empty()
        {
            out.push('\n');
        }

        // Imports
        if !self.imports.is_empty() {
            out.push('\n');
            for import in &self.imports {
                out.push_str(&format!("import \"{}\";\n", import));
            }
        }

        // Enums
        for e in &self.enums {
            out.push('\n');
            out.push_str(&e.to_proto_string());
        }

        // Messages
        for m in &self.messages {
            out.push('\n');
            out.push_str(&m.to_proto_string());
        }

        // Services (gRPC)
        for s in &self.services {
            out.push('\n');
            out.push_str(&s.to_proto_string());
        }

        out
    }

    /// Scan all messages and automatically add required Well-Known Type imports.
    ///
    /// This method should be called after all messages are added to ensure
    /// proper imports are included for any WKT fields.
    pub fn add_wkt_imports(&mut self) {
        use std::collections::HashSet;
        let mut required_imports: HashSet<&'static str> = HashSet::new();

        // Scan all message fields for WKT references
        for msg in &self.messages {
            Self::collect_wkt_imports_from_message(msg, &mut required_imports);
        }

        // Add imports that aren't already present
        for import in required_imports {
            if !self.imports.contains(&import.to_string()) {
                self.imports.push(import.to_string());
            }
        }

        // Sort imports for deterministic output
        self.imports.sort();
    }

    fn collect_wkt_imports_from_message(
        msg: &ProtoMessage,
        imports: &mut std::collections::HashSet<&'static str>,
    ) {
        for field in &msg.fields {
            if let ProtoType::Message(ref type_name) = field.proto_type {
                if let Some(wkt) = WellKnownType::from_type_name(type_name) {
                    imports.insert(wkt.import_path());
                }
            }
        }

        // Recurse into nested messages
        for nested in &msg.nested_messages {
            Self::collect_wkt_imports_from_message(nested, imports);
        }
    }
}

/// File-level Protobuf options.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ProtoOptions {
    /// Java package for generated code
    pub java_package: Option<String>,
    /// Generate separate files for each message in Java
    pub java_multiple_files: bool,
    /// Go package path
    pub go_package: Option<String>,
    /// C# namespace
    pub csharp_namespace: Option<String>,
    /// PHP namespace
    pub php_namespace: Option<String>,
    /// Ruby package
    pub ruby_package: Option<String>,
    /// Swift prefix
    pub swift_prefix: Option<String>,
    /// Objective-C class prefix
    pub objc_class_prefix: Option<String>,
    /// Optimize for: SPEED, CODE_SIZE, or LITE_RUNTIME
    pub optimize_for: Option<String>,
    /// Mark all messages as deprecated
    pub deprecated: bool,
    /// Custom options (user-defined or extension options)
    pub custom_options: Vec<ProtoCustomOption>,
}

impl ProtoOptions {
    /// Set a standard option by name.
    pub fn set_option(&mut self, name: &str, value: ProtoOptionValue) {
        match name {
            "java_package" => {
                if let ProtoOptionValue::String(s) = value {
                    self.java_package = Some(s);
                }
            }
            "java_multiple_files" => {
                if let ProtoOptionValue::Bool(b) = value {
                    self.java_multiple_files = b;
                }
            }
            "go_package" => {
                if let ProtoOptionValue::String(s) = value {
                    self.go_package = Some(s);
                }
            }
            "csharp_namespace" => {
                if let ProtoOptionValue::String(s) = value {
                    self.csharp_namespace = Some(s);
                }
            }
            "php_namespace" => {
                if let ProtoOptionValue::String(s) = value {
                    self.php_namespace = Some(s);
                }
            }
            "ruby_package" => {
                if let ProtoOptionValue::String(s) = value {
                    self.ruby_package = Some(s);
                }
            }
            "swift_prefix" => {
                if let ProtoOptionValue::String(s) = value {
                    self.swift_prefix = Some(s);
                }
            }
            "objc_class_prefix" => {
                if let ProtoOptionValue::String(s) = value {
                    self.objc_class_prefix = Some(s);
                }
            }
            "optimize_for" => {
                if let ProtoOptionValue::String(s) = value {
                    self.optimize_for = Some(s);
                }
            }
            "deprecated" => {
                if let ProtoOptionValue::Bool(b) = value {
                    self.deprecated = b;
                }
            }
            _ => {
                // Unknown option, add as custom
                self.custom_options.push(ProtoCustomOption {
                    name: name.to_string(),
                    value,
                });
            }
        }
    }
}

/// A custom proto option (user-defined or extension).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ProtoCustomOption {
    /// Option name (e.g., "java_package" or "(myopt).field")
    pub name: String,
    /// Option value
    pub value: ProtoOptionValue,
}

impl ProtoCustomOption {
    /// Create a new custom option.
    pub fn new(name: impl Into<String>, value: ProtoOptionValue) -> Self {
        Self {
            name: name.into(),
            value,
        }
    }

    /// Serialize to proto option string.
    pub fn to_proto_string(&self) -> String {
        format!("option {} = {};", self.name, self.value.to_proto_string())
    }
}

/// Value for a proto option.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum ProtoOptionValue {
    /// String value
    String(String),
    /// Integer value
    Int(i64),
    /// Float value
    Float(f64),
    /// Boolean value
    Bool(bool),
    /// Identifier/enum value (unquoted)
    Identifier(String),
}

impl ProtoOptionValue {
    /// Parse option value from JSON Value.
    pub fn from_json(value: &serde_json::Value) -> Self {
        match value {
            serde_json::Value::String(s) => ProtoOptionValue::String(s.clone()),
            serde_json::Value::Bool(b) => ProtoOptionValue::Bool(*b),
            serde_json::Value::Number(n) => {
                if let Some(i) = n.as_i64() {
                    ProtoOptionValue::Int(i)
                } else if let Some(f) = n.as_f64() {
                    ProtoOptionValue::Float(f)
                } else {
                    ProtoOptionValue::String(n.to_string())
                }
            }
            _ => ProtoOptionValue::String(value.to_string()),
        }
    }

    /// Serialize to proto option value string.
    pub fn to_proto_string(&self) -> String {
        match self {
            ProtoOptionValue::String(s) => {
                format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\""))
            }
            ProtoOptionValue::Int(i) => i.to_string(),
            ProtoOptionValue::Float(f) => f.to_string(),
            ProtoOptionValue::Bool(b) => b.to_string(),
            ProtoOptionValue::Identifier(s) => s.clone(),
        }
    }
}

/// Metadata about the projection source.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ProtoMetadata {
    /// Name of the projection that generated this file
    pub projection_name: String,
    /// Semantic version if available
    pub semantic_version: Option<String>,
    /// Source namespace from the SEA model
    pub source_namespace: String,
    /// Timestamp of generation
    pub generated_at: String,
}

// ============================================================================
// gRPC Service Types
// ============================================================================

/// Represents a gRPC service definition.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProtoService {
    /// Service name (e.g., "PaymentProcessorService")
    pub name: String,
    /// RPC methods in this service
    pub methods: Vec<ProtoRpcMethod>,
    /// Documentation comments
    pub comments: Vec<String>,
}

impl ProtoService {
    /// Create a new ProtoService with the given name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            methods: Vec::new(),
            comments: Vec::new(),
        }
    }

    /// Serialize the service to `.proto` text format.
    pub fn to_proto_string(&self) -> String {
        let mut out = String::new();

        // Comments
        for comment in &self.comments {
            out.push_str(&format!("// {}\n", comment));
        }

        out.push_str(&format!("service {} {{\n", self.name));

        for method in &self.methods {
            out.push_str(&format!("  {}\n", method.to_proto_string()));
        }

        out.push_str("}\n");
        out
    }
}

/// Represents an RPC method in a gRPC service.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProtoRpcMethod {
    /// Method name (e.g., "ProcessPayment")
    pub name: String,
    /// Request message type
    pub request_type: String,
    /// Response message type
    pub response_type: String,
    /// Streaming mode
    pub streaming: StreamingMode,
    /// Documentation comments
    pub comments: Vec<String>,
}

impl ProtoRpcMethod {
    /// Create a new unary RPC method.
    pub fn new(
        name: impl Into<String>,
        request_type: impl Into<String>,
        response_type: impl Into<String>,
    ) -> Self {
        Self {
            name: name.into(),
            request_type: request_type.into(),
            response_type: response_type.into(),
            streaming: StreamingMode::Unary,
            comments: Vec::new(),
        }
    }

    /// Serialize the method to `.proto` text format.
    pub fn to_proto_string(&self) -> String {
        let request = match self.streaming {
            StreamingMode::ClientStreaming | StreamingMode::Bidirectional => {
                format!("stream {}", self.request_type)
            }
            _ => self.request_type.clone(),
        };

        let response = match self.streaming {
            StreamingMode::ServerStreaming | StreamingMode::Bidirectional => {
                format!("stream {}", self.response_type)
            }
            _ => self.response_type.clone(),
        };

        format!("rpc {}({}) returns ({});", self.name, request, response)
    }
}

/// gRPC streaming mode for RPC methods.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum StreamingMode {
    /// Unary RPC (default): single request, single response
    #[default]
    Unary,
    /// Server streaming: single request, stream of responses
    ServerStreaming,
    /// Client streaming: stream of requests, single response
    ClientStreaming,
    /// Bidirectional streaming: stream of requests, stream of responses
    Bidirectional,
}

impl StreamingMode {
    /// Parse streaming mode from a string (e.g., from Flow attributes).
    pub fn parse(s: &str) -> Self {
        match s.to_lowercase().as_str() {
            "streaming" | "server_streaming" | "serverstreaming" => StreamingMode::ServerStreaming,
            "client_streaming" | "clientstreaming" => StreamingMode::ClientStreaming,
            "bidirectional" | "bidi" | "duplex" => StreamingMode::Bidirectional,
            _ => StreamingMode::Unary,
        }
    }
}

impl std::fmt::Display for StreamingMode {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            StreamingMode::Unary => write!(f, "unary"),
            StreamingMode::ServerStreaming => write!(f, "server_streaming"),
            StreamingMode::ClientStreaming => write!(f, "client_streaming"),
            StreamingMode::Bidirectional => write!(f, "bidirectional"),
        }
    }
}

/// Represents a Protobuf message definition.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProtoMessage {
    /// Message name (PascalCase)
    pub name: String,
    /// Field definitions
    pub fields: Vec<ProtoField>,
    /// Nested message definitions
    pub nested_messages: Vec<ProtoMessage>,
    /// Nested enum definitions
    pub nested_enums: Vec<ProtoEnum>,
    /// Reserved field numbers
    pub reserved_numbers: Vec<u32>,
    /// Reserved field names
    pub reserved_names: Vec<String>,
    /// Documentation comments
    pub comments: Vec<String>,
}

impl ProtoMessage {
    /// Create a new empty ProtoMessage.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            fields: Vec::new(),
            nested_messages: Vec::new(),
            nested_enums: Vec::new(),
            reserved_numbers: Vec::new(),
            reserved_names: Vec::new(),
            comments: Vec::new(),
        }
    }

    /// Serialize the message to `.proto` text format.
    pub fn to_proto_string(&self) -> String {
        let mut out = String::new();

        // Comments
        for comment in &self.comments {
            out.push_str(&format!("// {}\n", comment));
        }

        out.push_str(&format!("message {} {{\n", self.name));

        // Reserved fields
        if !self.reserved_numbers.is_empty() {
            let nums: Vec<String> = self
                .reserved_numbers
                .iter()
                .map(|n| n.to_string())
                .collect();
            out.push_str(&format!("  reserved {};\n", nums.join(", ")));
        }
        if !self.reserved_names.is_empty() {
            let names: Vec<String> = self
                .reserved_names
                .iter()
                .map(|n| format!("\"{}\"", n))
                .collect();
            out.push_str(&format!("  reserved {};\n", names.join(", ")));
        }

        // Nested enums
        for e in &self.nested_enums {
            for line in e.to_proto_string().lines() {
                out.push_str(&format!("  {}\n", line));
            }
        }

        // Nested messages
        for m in &self.nested_messages {
            for line in m.to_proto_string().lines() {
                out.push_str(&format!("  {}\n", line));
            }
        }

        // Fields
        for field in &self.fields {
            out.push_str(&format!("  {}\n", field.to_proto_string()));
        }

        out.push_str("}\n");
        out
    }
}

/// Represents a Protobuf field definition.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProtoField {
    /// Field name (snake_case)
    pub name: String,
    /// Field number (must be unique within message)
    pub number: u32,
    /// Field type
    pub proto_type: ProtoType,
    /// Whether this is a repeated field
    pub repeated: bool,
    /// Whether this field is optional (proto3 optional)
    pub optional: bool,
    /// Documentation comments
    pub comments: Vec<String>,
}

impl ProtoField {
    /// Serialize the field to `.proto` text format.
    pub fn to_proto_string(&self) -> String {
        let mut parts = Vec::new();

        // Comments as inline
        if !self.comments.is_empty() {
            // We'll add comment at the end
        }

        if self.optional {
            parts.push("optional".to_string());
        }
        if self.repeated {
            parts.push("repeated".to_string());
        }

        parts.push(self.proto_type.to_proto_string());
        parts.push(self.name.clone());

        let mut line = format!("{} = {};", parts.join(" "), self.number);

        if !self.comments.is_empty() {
            line.push_str(&format!(" // {}", self.comments.join("; ")));
        }

        line
    }
}

/// Represents a Protobuf type reference.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum ProtoType {
    /// Scalar types (int32, string, etc.)
    Scalar(ScalarType),
    /// Reference to another message type
    Message(String),
    /// Reference to an enum type
    Enum(String),
    /// Map type (map<key, value>)
    Map {
        key: Box<ProtoType>,
        value: Box<ProtoType>,
    },
}

impl ProtoType {
    /// Serialize the type to `.proto` text format.
    pub fn to_proto_string(&self) -> String {
        match self {
            ProtoType::Scalar(s) => s.to_proto_string(),
            ProtoType::Message(name) => name.clone(),
            ProtoType::Enum(name) => name.clone(),
            ProtoType::Map { key, value } => {
                format!(
                    "map<{}, {}>",
                    key.to_proto_string(),
                    value.to_proto_string()
                )
            }
        }
    }
}

/// Protobuf scalar types.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
pub enum ScalarType {
    Double,
    Float,
    Int32,
    Int64,
    Uint32,
    Uint64,
    Sint32,
    Sint64,
    Fixed32,
    Fixed64,
    Sfixed32,
    Sfixed64,
    Bool,
    String,
    Bytes,
}

impl ScalarType {
    /// Serialize the scalar type to `.proto` text format.
    pub fn to_proto_string(&self) -> String {
        match self {
            ScalarType::Double => "double",
            ScalarType::Float => "float",
            ScalarType::Int32 => "int32",
            ScalarType::Int64 => "int64",
            ScalarType::Uint32 => "uint32",
            ScalarType::Uint64 => "uint64",
            ScalarType::Sint32 => "sint32",
            ScalarType::Sint64 => "sint64",
            ScalarType::Fixed32 => "fixed32",
            ScalarType::Fixed64 => "fixed64",
            ScalarType::Sfixed32 => "sfixed32",
            ScalarType::Sfixed64 => "sfixed64",
            ScalarType::Bool => "bool",
            ScalarType::String => "string",
            ScalarType::Bytes => "bytes",
        }
        .to_string()
    }
}

/// Represents a Protobuf enum definition.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProtoEnum {
    /// Enum name (PascalCase)
    pub name: String,
    /// Enum values
    pub values: Vec<ProtoEnumValue>,
    /// Documentation comments
    pub comments: Vec<String>,
}

impl ProtoEnum {
    /// Create a new ProtoEnum with default UNSPECIFIED value.
    pub fn new(name: impl Into<String>) -> Self {
        let name = name.into();
        Self {
            values: vec![ProtoEnumValue {
                name: format!("{}_UNSPECIFIED", to_screaming_snake_case(&name)),
                number: 0,
            }],
            name,
            comments: Vec::new(),
        }
    }

    /// Add a value to the enum.
    pub fn add_value(&mut self, name: impl Into<String>) {
        let number = self.values.len() as i32;
        self.values.push(ProtoEnumValue {
            name: name.into(),
            number,
        });
    }

    /// Serialize the enum to `.proto` text format.
    pub fn to_proto_string(&self) -> String {
        let mut out = String::new();

        for comment in &self.comments {
            out.push_str(&format!("// {}\n", comment));
        }

        out.push_str(&format!("enum {} {{\n", self.name));

        for value in &self.values {
            out.push_str(&format!("  {} = {};\n", value.name, value.number));
        }

        out.push_str("}\n");
        out
    }
}

/// Represents a Protobuf enum value.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProtoEnumValue {
    /// Value name (SCREAMING_SNAKE_CASE)
    pub name: String,
    /// Numeric value
    pub number: i32,
}

// ============================================================================
// Well-Known Types
// ============================================================================

/// Google Protobuf Well-Known Types.
///
/// These are standard types provided by Google that have special handling
/// in most Protobuf implementations.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum WellKnownType {
    /// google.protobuf.Timestamp - for date/time values
    Timestamp,
    /// google.protobuf.Duration - for time spans
    Duration,
    /// google.protobuf.Any - for dynamic typing
    Any,
    /// google.protobuf.Struct - for JSON-like structures
    Struct,
    /// google.protobuf.Value - for dynamic JSON values
    Value,
    /// google.protobuf.ListValue - for JSON arrays
    ListValue,
    /// google.protobuf.Empty - for empty messages
    Empty,
    /// Wrapper types for nullable primitives
    Int32Value,
    Int64Value,
    UInt32Value,
    UInt64Value,
    FloatValue,
    DoubleValue,
    BoolValue,
    StringValue,
    BytesValue,
}

impl WellKnownType {
    /// Get the fully qualified type name.
    pub fn type_name(&self) -> &'static str {
        match self {
            WellKnownType::Timestamp => "google.protobuf.Timestamp",
            WellKnownType::Duration => "google.protobuf.Duration",
            WellKnownType::Any => "google.protobuf.Any",
            WellKnownType::Struct => "google.protobuf.Struct",
            WellKnownType::Value => "google.protobuf.Value",
            WellKnownType::ListValue => "google.protobuf.ListValue",
            WellKnownType::Empty => "google.protobuf.Empty",
            WellKnownType::Int32Value => "google.protobuf.Int32Value",
            WellKnownType::Int64Value => "google.protobuf.Int64Value",
            WellKnownType::UInt32Value => "google.protobuf.UInt32Value",
            WellKnownType::UInt64Value => "google.protobuf.UInt64Value",
            WellKnownType::FloatValue => "google.protobuf.FloatValue",
            WellKnownType::DoubleValue => "google.protobuf.DoubleValue",
            WellKnownType::BoolValue => "google.protobuf.BoolValue",
            WellKnownType::StringValue => "google.protobuf.StringValue",
            WellKnownType::BytesValue => "google.protobuf.BytesValue",
        }
    }

    /// Get the import path for this type.
    pub fn import_path(&self) -> &'static str {
        match self {
            WellKnownType::Timestamp => "google/protobuf/timestamp.proto",
            WellKnownType::Duration => "google/protobuf/duration.proto",
            WellKnownType::Any => "google/protobuf/any.proto",
            WellKnownType::Struct | WellKnownType::Value | WellKnownType::ListValue => {
                "google/protobuf/struct.proto"
            }
            WellKnownType::Empty => "google/protobuf/empty.proto",
            WellKnownType::Int32Value
            | WellKnownType::Int64Value
            | WellKnownType::UInt32Value
            | WellKnownType::UInt64Value
            | WellKnownType::FloatValue
            | WellKnownType::DoubleValue
            | WellKnownType::BoolValue
            | WellKnownType::StringValue
            | WellKnownType::BytesValue => "google/protobuf/wrappers.proto",
        }
    }

    /// Try to parse a type name into a WellKnownType.
    pub fn from_type_name(name: &str) -> Option<Self> {
        match name {
            "google.protobuf.Timestamp" => Some(WellKnownType::Timestamp),
            "google.protobuf.Duration" => Some(WellKnownType::Duration),
            "google.protobuf.Any" => Some(WellKnownType::Any),
            "google.protobuf.Struct" => Some(WellKnownType::Struct),
            "google.protobuf.Value" => Some(WellKnownType::Value),
            "google.protobuf.ListValue" => Some(WellKnownType::ListValue),
            "google.protobuf.Empty" => Some(WellKnownType::Empty),
            "google.protobuf.Int32Value" => Some(WellKnownType::Int32Value),
            "google.protobuf.Int64Value" => Some(WellKnownType::Int64Value),
            "google.protobuf.UInt32Value" => Some(WellKnownType::UInt32Value),
            "google.protobuf.UInt64Value" => Some(WellKnownType::UInt64Value),
            "google.protobuf.FloatValue" => Some(WellKnownType::FloatValue),
            "google.protobuf.DoubleValue" => Some(WellKnownType::DoubleValue),
            "google.protobuf.BoolValue" => Some(WellKnownType::BoolValue),
            "google.protobuf.StringValue" => Some(WellKnownType::StringValue),
            "google.protobuf.BytesValue" => Some(WellKnownType::BytesValue),
            _ => None,
        }
    }
}

// ============================================================================
// Type Mapping
// ============================================================================

/// Map SEA type strings to Protobuf types.
///
/// This function handles the common type names used in SEA attributes,
/// including mapping to Google Well-Known Types where appropriate.
pub fn map_sea_type_to_proto(sea_type: &str) -> ProtoType {
    match sea_type.to_lowercase().as_str() {
        // Scalar types
        "string" | "text" | "varchar" => ProtoType::Scalar(ScalarType::String),
        "int" | "integer" | "int64" | "long" => ProtoType::Scalar(ScalarType::Int64),
        "int32" | "short" => ProtoType::Scalar(ScalarType::Int32),
        "uint32" => ProtoType::Scalar(ScalarType::Uint32),
        "uint64" | "ulong" => ProtoType::Scalar(ScalarType::Uint64),
        "float" | "double" | "decimal" | "number" => ProtoType::Scalar(ScalarType::Double),
        "float32" => ProtoType::Scalar(ScalarType::Float),
        "bool" | "boolean" => ProtoType::Scalar(ScalarType::Bool),
        "bytes" | "binary" | "blob" => ProtoType::Scalar(ScalarType::Bytes),
        "uuid" | "guid" => ProtoType::Scalar(ScalarType::String),

        // Well-Known Types
        "date" | "datetime" | "timestamp" => {
            ProtoType::Message(WellKnownType::Timestamp.type_name().to_string())
        }
        "duration" | "timespan" | "interval" => {
            ProtoType::Message(WellKnownType::Duration.type_name().to_string())
        }
        "any" | "dynamic" | "object" => {
            ProtoType::Message(WellKnownType::Any.type_name().to_string())
        }
        "struct" | "json" | "jsonobject" => {
            ProtoType::Message(WellKnownType::Struct.type_name().to_string())
        }
        "value" | "jsonvalue" => ProtoType::Message(WellKnownType::Value.type_name().to_string()),
        "empty" | "void" | "unit" => {
            ProtoType::Message(WellKnownType::Empty.type_name().to_string())
        }

        // Nullable wrapper types
        "optional_int" | "nullable_int" | "int?" => {
            ProtoType::Message(WellKnownType::Int64Value.type_name().to_string())
        }
        "optional_int32" | "nullable_int32" | "int32?" => {
            ProtoType::Message(WellKnownType::Int32Value.type_name().to_string())
        }
        "optional_string" | "nullable_string" | "string?" => {
            ProtoType::Message(WellKnownType::StringValue.type_name().to_string())
        }
        "optional_bool" | "nullable_bool" | "bool?" => {
            ProtoType::Message(WellKnownType::BoolValue.type_name().to_string())
        }
        "optional_double" | "nullable_double" | "double?" => {
            ProtoType::Message(WellKnownType::DoubleValue.type_name().to_string())
        }
        "optional_float" | "nullable_float" | "float?" => {
            ProtoType::Message(WellKnownType::FloatValue.type_name().to_string())
        }
        "optional_bytes" | "nullable_bytes" | "bytes?" => {
            ProtoType::Message(WellKnownType::BytesValue.type_name().to_string())
        }

        // Custom types become messages
        _ => ProtoType::Message(to_pascal_case(sea_type)),
    }
}

/// Infer a ProtoType from a serde_json::Value.
pub fn infer_proto_type_from_value(value: &Value) -> ProtoType {
    match value {
        Value::Null => ProtoType::Scalar(ScalarType::String),
        Value::Bool(_) => ProtoType::Scalar(ScalarType::Bool),
        Value::Number(n) => {
            if n.is_f64() {
                ProtoType::Scalar(ScalarType::Double)
            } else {
                ProtoType::Scalar(ScalarType::Int64)
            }
        }
        Value::String(_) => ProtoType::Scalar(ScalarType::String),
        Value::Array(_) => ProtoType::Scalar(ScalarType::String), // Arrays need special handling
        Value::Object(_) => ProtoType::Scalar(ScalarType::String), // Objects need special handling
    }
}

// ============================================================================
// Protobuf Engine
// ============================================================================

/// The Protobuf projection engine.
///
/// This struct provides methods to convert a SEA Graph into Protobuf IR
/// which can then be serialized to `.proto` text format.
pub struct ProtobufEngine;

impl ProtobufEngine {
    /// Project a SEA Graph to a ProtoFile.
    ///
    /// # Arguments
    ///
    /// * `graph` - The semantic graph to project
    /// * `namespace` - Filter to only include entities/resources from this namespace (empty = all)
    /// * `package` - The Protobuf package name to use
    ///
    /// # Returns
    ///
    /// A `ProtoFile` containing the generated Protobuf IR.
    pub fn project(graph: &Graph, namespace: &str, package: &str) -> ProtoFile {
        let mut proto = ProtoFile::new(package);
        proto.metadata.source_namespace = namespace.to_string();
        proto.metadata.generated_at = chrono::Utc::now().to_rfc3339();

        // Convert entities to messages
        for entity in graph.all_entities() {
            if namespace.is_empty() || entity.namespace() == namespace {
                proto.messages.push(Self::entity_to_message(entity));
            }
        }

        // Convert resources to messages
        for resource in graph.all_resources() {
            if namespace.is_empty() || resource.namespace() == namespace {
                proto.messages.push(Self::resource_to_message(resource));
            }
        }

        // Sort messages by name for deterministic output
        proto.messages.sort_by(|a, b| a.name.cmp(&b.name));

        // Auto-detect and add Well-Known Type imports
        proto.add_wkt_imports();

        proto
    }

    /// Project with options for a projection contract.
    pub fn project_with_options(
        graph: &Graph,
        namespace: &str,
        package: &str,
        projection_name: &str,
        include_governance: bool,
    ) -> ProtoFile {
        Self::project_with_full_options(
            graph,
            namespace,
            package,
            projection_name,
            include_governance,
            false, // include_services
        )
    }

    /// Project with all options including gRPC service generation.
    pub fn project_with_full_options(
        graph: &Graph,
        namespace: &str,
        package: &str,
        projection_name: &str,
        include_governance: bool,
        include_services: bool,
    ) -> ProtoFile {
        let mut proto = Self::project(graph, namespace, package);
        proto.metadata.projection_name = projection_name.to_string();

        if include_governance {
            proto.messages.extend(Self::generate_governance_messages());
        }

        if include_services {
            proto.services = Self::flows_to_services(graph, namespace);
        }

        // Re-add WKT imports in case governance messages need them
        proto.add_wkt_imports();

        proto
    }

    /// Project a SEA Graph to multiple ProtoFiles (one per namespace).
    ///
    /// This method partitions the graph by namespace, creating a separate `.proto` file
    /// for each. Cross-namespace references are automatically resolved by adding imports
    /// and fully qualifying type names.
    ///
    /// # Arguments
    ///
    /// * `graph` - The semantic graph to project
    /// * `base_package` - The root package name (e.g. "sea.generated")
    /// * `include_governance` - Whether to include governance messages
    /// * `include_services` - Whether to generate gRPC services
    ///
    /// # Returns
    ///
    /// A map of relative file paths to ProtoFile definitions.
    pub fn project_multi_file(
        graph: &Graph,
        base_package: &str,
        include_governance: bool,
        include_services: bool,
    ) -> BTreeMap<PathBuf, ProtoFile> {
        let mut files: BTreeMap<String, ProtoFile> = BTreeMap::new();
        // Index: TypeName -> (Namespace, FullPackage)
        let mut type_index: HashMap<String, (String, String)> = HashMap::new();

        // 1. Collect all namespaces and entities
        for entity in graph.all_entities() {
            let ns = entity.namespace();
            let package = if ns.is_empty() {
                base_package.to_string()
            } else {
                format!("{}.{}", base_package, ns)
            };

            type_index.insert(
                to_pascal_case(entity.name()),
                (ns.to_string(), package.clone()),
            );

            files
                .entry(ns.to_string())
                .or_insert_with(|| ProtoFile::new(package))
                .messages
                .push(Self::entity_to_message(entity));
        }

        for resource in graph.all_resources() {
            let ns = resource.namespace();
            let package = if ns.is_empty() {
                base_package.to_string()
            } else {
                format!("{}.{}", base_package, ns)
            };

            type_index.insert(
                to_pascal_case(resource.name()),
                (ns.to_string(), package.clone()),
            );

            files
                .entry(ns.to_string())
                .or_insert_with(|| ProtoFile::new(package))
                .messages
                .push(Self::resource_to_message(resource));
        }

        // 2. Add Services
        if include_services {
            // Iterate all flows to capture services
            let services = Self::flows_to_services(graph, "");
            for service in services {
                // Try to find the namespace of the service based on the destination entity name
                // Service name is {DestEntity}Service
                let entity_name = service
                    .name
                    .strip_suffix("Service")
                    .unwrap_or(&service.name);

                // Look up entity namespace in type_index
                if let Some((ns, package)) = type_index.get(entity_name) {
                    files
                        .entry(ns.clone())
                        .or_insert_with(|| ProtoFile::new(package.clone()))
                        .services
                        .push(service);
                } else {
                    // Default to base package if not found (e.g. flow to unknown entity)
                    let package = base_package.to_string();
                    files
                        .entry("".to_string())
                        .or_insert_with(|| ProtoFile::new(package))
                        .services
                        .push(service);
                }
            }
        }

        // 3. Add Governance (in root namespace usually)
        if include_governance {
            let root_file = files
                .entry("".to_string())
                .or_insert_with(|| ProtoFile::new(base_package.to_string()));

            let governance_msgs = Self::generate_governance_messages();
            for msg in &governance_msgs {
                type_index.insert(msg.name.clone(), ("".to_string(), base_package.to_string()));
            }
            root_file.messages.extend(governance_msgs);
        }

        // 4. Resolve Imports and Finalize
        for (ns, file) in files.iter_mut() {
            let mut imports_to_add = HashSet::new();

            // Check messages for cross-references
            for msg in &mut file.messages {
                Self::resolve_imports_in_message(msg, ns, &type_index, &mut imports_to_add);
            }

            // Check services
            for svc in &mut file.services {
                for method in &mut svc.methods {
                    // Check request types
                    if let Some((target_ns, target_pkg)) = type_index.get(&method.request_type) {
                        if target_ns != ns {
                            imports_to_add.insert(target_ns.clone());
                            method.request_type = format!("{}.{}", target_pkg, method.request_type);
                        }
                    }
                    // Check response types
                    if let Some((target_ns, target_pkg)) = type_index.get(&method.response_type) {
                        if target_ns != ns {
                            imports_to_add.insert(target_ns.clone());
                            method.response_type =
                                format!("{}.{}", target_pkg, method.response_type);
                        }
                    }
                }
            }

            // Add collected imports
            for target_ns in imports_to_add {
                // self-import is prevented by check above
                // root namespace usually doesn't need path prefix if files in same dir,
                // but assume we strictly follow directory structure.
                let import_path = if target_ns.is_empty() {
                    "projection.proto".to_string()
                } else {
                    format!("{}.proto", target_ns.replace('.', "/"))
                };
                file.imports.push(import_path);
            }

            // Sort and deduplicate imports (including WKTs)
            file.add_wkt_imports();
        }

        // Convert map to PathBuf keys
        let mut results = BTreeMap::new();
        for (ns, file) in files {
            let path = if ns.is_empty() {
                PathBuf::from("projection.proto")
            } else {
                PathBuf::from(format!("{}.proto", ns.replace('.', "/")))
            };
            results.insert(path, file);
        }

        results
    }

    /// Helper to resolve cross-namespace imports within a message.
    fn resolve_imports_in_message(
        msg: &mut ProtoMessage,
        current_ns: &str,
        index: &HashMap<String, (String, String)>,
        imports: &mut HashSet<String>,
    ) {
        for field in &mut msg.fields {
            match &mut field.proto_type {
                ProtoType::Message(name) | ProtoType::Enum(name) => {
                    // Ignore WKTs
                    if WellKnownType::from_type_name(name).is_some() {
                        continue;
                    }

                    if let Some((target_ns, target_pkg)) = index.get(name.as_str()) {
                        if target_ns != current_ns {
                            imports.insert(target_ns.clone());
                            *name = format!("{}.{}", target_pkg, name);
                        }
                    }
                }
                ProtoType::Map { key: _, value } => {
                    // Check recursively (simplified for now assuming only value can be message)
                    if let ProtoType::Message(name) = &mut **value {
                        if WellKnownType::from_type_name(name).is_some() {
                            continue;
                        }
                        if let Some((target_ns, target_pkg)) = index.get(name.as_str()) {
                            if target_ns != current_ns {
                                imports.insert(target_ns.clone());
                                *name = format!("{}.{}", target_pkg, name);
                            }
                        }
                    }
                }
                _ => {}
            }
        }

        // Recurse into nested messages
        for nested in &mut msg.nested_messages {
            Self::resolve_imports_in_message(nested, current_ns, index, imports);
        }
    }
    ///
    /// This method groups flows by their destination entity (service provider)
    /// and creates RPC methods for each flow. The naming convention follows
    /// gRPC best practices: `{DestinationEntity}Service`.
    ///
    /// # Example
    ///
    /// A flow `Customer -> PaymentProcessor of PaymentRequest` generates:
    /// ```protobuf
    /// service PaymentProcessorService {
    ///   rpc ProcessPaymentRequest(PaymentRequest) returns (PaymentRequestResponse);
    /// }
    /// ```
    pub fn flows_to_services(graph: &Graph, namespace: &str) -> Vec<ProtoService> {
        let mut services: BTreeMap<String, ProtoService> = BTreeMap::new();

        for flow in graph.all_flows() {
            // Filter by namespace if specified
            if !namespace.is_empty() && flow.namespace() != namespace {
                continue;
            }

            // Get the destination entity (service provider)
            let to_entity = match graph.get_entity(flow.to_id()) {
                Some(e) => e,
                None => continue, // Skip if entity not found
            };

            // Get the resource being transferred (becomes the request type)
            let resource = match graph.get_resource(flow.resource_id()) {
                Some(r) => r,
                None => continue, // Skip if resource not found
            };

            // Determine service name: {DestinationEntity}Service
            let service_name = format!("{}Service", to_pascal_case(to_entity.name()));

            // Determine method name: Process{Resource} or Send{Resource}
            let method_name = format!("Process{}", to_pascal_case(resource.name()));

            // Request type is the resource name
            let request_type = to_pascal_case(resource.name());

            // Response type is {Resource}Response
            let response_type = format!("{}Response", to_pascal_case(resource.name()));

            // Check for streaming mode in flow attributes
            let streaming = flow
                .get_attribute("streaming")
                .and_then(|v| v.as_str())
                .map(StreamingMode::parse)
                .unwrap_or(StreamingMode::Unary);

            // Create the RPC method
            let mut method = ProtoRpcMethod::new(&method_name, &request_type, &response_type);
            method.streaming = streaming;

            // Get the source entity for the comment
            if let Some(from_entity) = graph.get_entity(flow.from_id()) {
                method.comments.push(format!(
                    "Flow: {} -> {} of {}",
                    from_entity.name(),
                    to_entity.name(),
                    resource.name()
                ));
            }

            // Add to or create service
            services
                .entry(service_name.clone())
                .or_insert_with(|| {
                    let mut svc = ProtoService::new(&service_name);
                    svc.comments
                        .push(format!("gRPC service for {}", to_entity.name()));
                    svc
                })
                .methods
                .push(method);
        }

        // Also generate response messages for each service method
        // (This would normally be done, but we'll keep it simple for now)

        services.into_values().collect()
    }

    /// Convert an Entity to a ProtoMessage.
    fn entity_to_message(entity: &Entity) -> ProtoMessage {
        let mut msg = ProtoMessage::new(to_pascal_case(entity.name()));
        msg.comments.push(format!("SEA Entity: {}", entity.name()));
        msg.comments
            .push(format!("Namespace: {}", entity.namespace()));

        let mut field_number = 1u32;

        // Add id field (always first)
        msg.fields.push(ProtoField {
            name: "id".to_string(),
            number: field_number,
            proto_type: ProtoType::Scalar(ScalarType::String),
            repeated: false,
            optional: false,
            comments: vec!["Unique identifier".to_string()],
        });
        field_number += 1;

        // Add name field
        msg.fields.push(ProtoField {
            name: "name".to_string(),
            number: field_number,
            proto_type: ProtoType::Scalar(ScalarType::String),
            repeated: false,
            optional: false,
            comments: vec!["Entity name".to_string()],
        });
        field_number += 1;

        // Add attributes sorted alphabetically for deterministic output
        let mut sorted_attrs: BTreeMap<&String, &Value> = BTreeMap::new();
        for (key, value) in entity.attributes() {
            sorted_attrs.insert(key, value);
        }

        for (key, value) in sorted_attrs {
            msg.fields.push(ProtoField {
                name: to_snake_case(key),
                number: field_number,
                proto_type: infer_proto_type_from_value(value),
                repeated: matches!(value, Value::Array(_)),
                optional: true,
                comments: vec![],
            });
            field_number += 1;
        }

        msg
    }

    /// Convert a Resource to a ProtoMessage.
    fn resource_to_message(resource: &Resource) -> ProtoMessage {
        let mut msg = ProtoMessage::new(to_pascal_case(resource.name()));
        msg.comments
            .push(format!("SEA Resource: {}", resource.name()));
        msg.comments
            .push(format!("Unit: {}", resource.unit().symbol()));

        let mut field_number = 1u32;

        // Add id field
        msg.fields.push(ProtoField {
            name: "id".to_string(),
            number: field_number,
            proto_type: ProtoType::Scalar(ScalarType::String),
            repeated: false,
            optional: false,
            comments: vec!["Unique identifier".to_string()],
        });
        field_number += 1;

        // Add name field
        msg.fields.push(ProtoField {
            name: "name".to_string(),
            number: field_number,
            proto_type: ProtoType::Scalar(ScalarType::String),
            repeated: false,
            optional: false,
            comments: vec!["Resource name".to_string()],
        });
        field_number += 1;

        // Add quantity field with unit comment
        msg.fields.push(ProtoField {
            name: "quantity".to_string(),
            number: field_number,
            proto_type: ProtoType::Scalar(ScalarType::Double),
            repeated: false,
            optional: true,
            comments: vec![format!("Quantity in {}", resource.unit().symbol())],
        });
        field_number += 1;

        // Add unit field
        msg.fields.push(ProtoField {
            name: "unit".to_string(),
            number: field_number,
            proto_type: ProtoType::Scalar(ScalarType::String),
            repeated: false,
            optional: false,
            comments: vec!["Unit of measurement".to_string()],
        });
        field_number += 1;

        // Add attributes
        let mut sorted_attrs: BTreeMap<&String, &Value> = BTreeMap::new();
        for (key, value) in resource.attributes() {
            sorted_attrs.insert(key, value);
        }

        for (key, value) in sorted_attrs {
            msg.fields.push(ProtoField {
                name: to_snake_case(key),
                number: field_number,
                proto_type: infer_proto_type_from_value(value),
                repeated: matches!(value, Value::Array(_)),
                optional: true,
                comments: vec![],
            });
            field_number += 1;
        }

        msg
    }

    /// Generate standard governance messages.
    fn generate_governance_messages() -> Vec<ProtoMessage> {
        let mut messages = Vec::new();

        // PolicyViolation message
        let mut violation = ProtoMessage::new("PolicyViolation");
        violation
            .comments
            .push("Represents a policy violation event".to_string());
        violation.fields = vec![
            ProtoField {
                name: "policy_name".to_string(),
                number: 1,
                proto_type: ProtoType::Scalar(ScalarType::String),
                repeated: false,
                optional: false,
                comments: vec!["Name of the violated policy".to_string()],
            },
            ProtoField {
                name: "entity_id".to_string(),
                number: 2,
                proto_type: ProtoType::Scalar(ScalarType::String),
                repeated: false,
                optional: false,
                comments: vec!["ID of the entity that violated the policy".to_string()],
            },
            ProtoField {
                name: "severity".to_string(),
                number: 3,
                proto_type: ProtoType::Scalar(ScalarType::String),
                repeated: false,
                optional: false,
                comments: vec!["Severity level (error, warn, info)".to_string()],
            },
            ProtoField {
                name: "message".to_string(),
                number: 4,
                proto_type: ProtoType::Scalar(ScalarType::String),
                repeated: false,
                optional: false,
                comments: vec!["Human-readable violation message".to_string()],
            },
            ProtoField {
                name: "timestamp".to_string(),
                number: 5,
                proto_type: ProtoType::Scalar(ScalarType::String),
                repeated: false,
                optional: false,
                comments: vec!["When the violation occurred".to_string()],
            },
        ];
        messages.push(violation);

        // MetricEvent message
        let mut metric = ProtoMessage::new("MetricEvent");
        metric
            .comments
            .push("Represents a metric measurement event".to_string());
        metric.fields = vec![
            ProtoField {
                name: "metric_name".to_string(),
                number: 1,
                proto_type: ProtoType::Scalar(ScalarType::String),
                repeated: false,
                optional: false,
                comments: vec!["Name of the metric".to_string()],
            },
            ProtoField {
                name: "value".to_string(),
                number: 2,
                proto_type: ProtoType::Scalar(ScalarType::Double),
                repeated: false,
                optional: false,
                comments: vec!["Measured value".to_string()],
            },
            ProtoField {
                name: "unit".to_string(),
                number: 3,
                proto_type: ProtoType::Scalar(ScalarType::String),
                repeated: false,
                optional: true,
                comments: vec!["Unit of measurement".to_string()],
            },
            ProtoField {
                name: "timestamp".to_string(),
                number: 4,
                proto_type: ProtoType::Scalar(ScalarType::String),
                repeated: false,
                optional: false,
                comments: vec!["When the measurement was taken".to_string()],
            },
        ];
        messages.push(metric);

        messages
    }
}

// ============================================================================
// Helper Functions
// ============================================================================

/// Convert a string to PascalCase.
fn to_pascal_case(s: &str) -> String {
    s.split(|c: char| !c.is_alphanumeric())
        .filter(|part| !part.is_empty())
        .map(|part| {
            let mut chars = part.chars();
            match chars.next() {
                Some(first) => first.to_uppercase().to_string() + &chars.as_str().to_lowercase(),
                None => String::new(),
            }
        })
        .collect()
}

/// Convert a string to snake_case.
fn to_snake_case(s: &str) -> String {
    let mut result = String::new();
    let mut prev_is_uppercase = false;

    for (i, c) in s.chars().enumerate() {
        if c.is_uppercase() {
            if i > 0 && !prev_is_uppercase {
                result.push('_');
            }
            result.push(c.to_lowercase().next().unwrap_or(c));
            prev_is_uppercase = true;
        } else if c.is_alphanumeric() {
            result.push(c);
            prev_is_uppercase = false;
        } else {
            if !result.is_empty() && !result.ends_with('_') {
                result.push('_');
            }
            prev_is_uppercase = false;
        }
    }

    result.trim_matches('_').to_string()
}

/// Convert a string to SCREAMING_SNAKE_CASE.
fn to_screaming_snake_case(s: &str) -> String {
    to_snake_case(s).to_uppercase()
}

// ============================================================================
// Compatibility Enforcement
// ============================================================================

/// Compatibility mode for schema evolution.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
pub enum CompatibilityMode {
    /// Only additions allowed - strictest mode for public APIs
    Additive,
    /// Removals become reserved fields - default for internal APIs
    #[default]
    Backward,
    /// All changes allowed - for breaking releases
    Breaking,
}

impl std::fmt::Display for CompatibilityMode {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            CompatibilityMode::Additive => write!(f, "additive"),
            CompatibilityMode::Backward => write!(f, "backward"),
            CompatibilityMode::Breaking => write!(f, "breaking"),
        }
    }
}

impl std::str::FromStr for CompatibilityMode {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "additive" | "strict" => Ok(CompatibilityMode::Additive),
            "backward" | "backwards" | "default" => Ok(CompatibilityMode::Backward),
            "breaking" | "none" => Ok(CompatibilityMode::Breaking),
            _ => Err(format!("Unknown compatibility mode: {}", s)),
        }
    }
}

/// A compatibility violation found during schema comparison.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CompatibilityViolation {
    /// The message name where the violation occurred
    pub message_name: String,
    /// The field name involved (if applicable)
    pub field_name: Option<String>,
    /// The field number involved (if applicable)
    pub field_number: Option<u32>,
    /// Type of violation
    pub violation_type: ViolationType,
    /// Human-readable description
    pub description: String,
}

/// Types of compatibility violations.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ViolationType {
    /// A field was removed
    FieldRemoved,
    /// A field number was reused with a different name/type
    FieldNumberReused,
    /// A field type was changed
    FieldTypeChanged,
    /// A field was renamed (same number, different name)
    FieldRenamed,
    /// A message was removed
    MessageRemoved,
    /// A required field was added (breaking in proto3)
    RequiredFieldAdded,
}

impl std::fmt::Display for ViolationType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ViolationType::FieldRemoved => write!(f, "field_removed"),
            ViolationType::FieldNumberReused => write!(f, "field_number_reused"),
            ViolationType::FieldTypeChanged => write!(f, "field_type_changed"),
            ViolationType::FieldRenamed => write!(f, "field_renamed"),
            ViolationType::MessageRemoved => write!(f, "message_removed"),
            ViolationType::RequiredFieldAdded => write!(f, "required_field_added"),
        }
    }
}

/// Result of a compatibility check.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CompatibilityResult {
    /// Whether the schemas are compatible under the given mode
    pub is_compatible: bool,
    /// The mode used for checking
    pub mode: CompatibilityMode,
    /// List of violations found
    pub violations: Vec<CompatibilityViolation>,
    /// Suggested fixes (reserved fields to add)
    pub suggested_reserved_numbers: BTreeMap<String, Vec<u32>>,
    /// Suggested reserved names
    pub suggested_reserved_names: BTreeMap<String, Vec<String>>,
}

impl CompatibilityResult {
    /// Create a compatible (empty) result.
    pub fn compatible(mode: CompatibilityMode) -> Self {
        Self {
            is_compatible: true,
            mode,
            violations: Vec::new(),
            suggested_reserved_numbers: BTreeMap::new(),
            suggested_reserved_names: BTreeMap::new(),
        }
    }

    /// Check if there are any violations.
    pub fn has_violations(&self) -> bool {
        !self.violations.is_empty()
    }

    /// Format violations as a human-readable report.
    pub fn to_report(&self) -> String {
        let mut out = String::new();
        out.push_str(&format!("Compatibility Check (mode: {})\n", self.mode));
        out.push_str(&format!(
            "Result: {}\n",
            if self.is_compatible { "PASS" } else { "FAIL" }
        ));

        if !self.violations.is_empty() {
            out.push_str(&format!("\nViolations ({}):\n", self.violations.len()));
            for v in &self.violations {
                out.push_str(&format!(
                    "  - [{}] {}: {}\n",
                    v.violation_type, v.message_name, v.description
                ));
            }
        }

        if !self.suggested_reserved_numbers.is_empty() {
            out.push_str("\nSuggested Reserved Fields:\n");
            for (msg, nums) in &self.suggested_reserved_numbers {
                let nums_str: Vec<String> = nums.iter().map(|n| n.to_string()).collect();
                out.push_str(&format!(
                    "  message {}: reserved {};\n",
                    msg,
                    nums_str.join(", ")
                ));
            }
        }

        out
    }
}

/// Schema compatibility checker.
pub struct CompatibilityChecker;

impl CompatibilityChecker {
    /// Check compatibility between an old and new ProtoFile.
    ///
    /// # Arguments
    /// * `old` - The previous schema version
    /// * `new` - The new schema version  
    /// * `mode` - The compatibility mode to enforce
    ///
    /// # Returns
    /// A CompatibilityResult with violations and suggested fixes.
    pub fn check(old: &ProtoFile, new: &ProtoFile, mode: CompatibilityMode) -> CompatibilityResult {
        let mut result = CompatibilityResult::compatible(mode);

        // Build lookup maps for old schema
        let old_messages: BTreeMap<&str, &ProtoMessage> =
            old.messages.iter().map(|m| (m.name.as_str(), m)).collect();

        let new_messages: BTreeMap<&str, &ProtoMessage> =
            new.messages.iter().map(|m| (m.name.as_str(), m)).collect();

        // Check for removed messages
        for name in old_messages.keys() {
            if !new_messages.contains_key(name) {
                result.violations.push(CompatibilityViolation {
                    message_name: name.to_string(),
                    field_name: None,
                    field_number: None,
                    violation_type: ViolationType::MessageRemoved,
                    description: format!("Message '{}' was removed", name),
                });
            }
        }

        // Check each message that exists in both
        for (name, old_msg) in &old_messages {
            if let Some(new_msg) = new_messages.get(name) {
                Self::check_message(old_msg, new_msg, &mut result);
            }
        }

        // Determine if compatible based on mode
        result.is_compatible = match mode {
            CompatibilityMode::Breaking => true, // Always compatible in breaking mode
            CompatibilityMode::Backward => {
                // Compatible if no field number reuse or type changes
                !result.violations.iter().any(|v| {
                    matches!(
                        v.violation_type,
                        ViolationType::FieldNumberReused | ViolationType::FieldTypeChanged
                    )
                })
            }
            CompatibilityMode::Additive => {
                // Any removal or change is incompatible
                result.violations.is_empty()
            }
        };

        result
    }

    /// Check compatibility between two messages.
    fn check_message(old: &ProtoMessage, new: &ProtoMessage, result: &mut CompatibilityResult) {
        // Build field maps by number and by name
        let old_by_number: BTreeMap<u32, &ProtoField> =
            old.fields.iter().map(|f| (f.number, f)).collect();

        let new_by_number: BTreeMap<u32, &ProtoField> =
            new.fields.iter().map(|f| (f.number, f)).collect();

        let old_by_name: BTreeMap<&str, &ProtoField> =
            old.fields.iter().map(|f| (f.name.as_str(), f)).collect();

        // Check for removed fields
        for (number, old_field) in &old_by_number {
            if !new_by_number.contains_key(number) {
                result.violations.push(CompatibilityViolation {
                    message_name: old.name.clone(),
                    field_name: Some(old_field.name.clone()),
                    field_number: Some(*number),
                    violation_type: ViolationType::FieldRemoved,
                    description: format!(
                        "Field '{}' (number {}) was removed",
                        old_field.name, number
                    ),
                });

                // Suggest reserving this field number
                result
                    .suggested_reserved_numbers
                    .entry(old.name.clone())
                    .or_default()
                    .push(*number);

                result
                    .suggested_reserved_names
                    .entry(old.name.clone())
                    .or_default()
                    .push(old_field.name.clone());
            }
        }

        // Check for field number reuse with different name/type
        for (number, new_field) in &new_by_number {
            if let Some(old_field) = old_by_number.get(number) {
                // Check name change
                if old_field.name != new_field.name {
                    result.violations.push(CompatibilityViolation {
                        message_name: old.name.clone(),
                        field_name: Some(new_field.name.clone()),
                        field_number: Some(*number),
                        violation_type: ViolationType::FieldRenamed,
                        description: format!(
                            "Field number {} renamed from '{}' to '{}'",
                            number, old_field.name, new_field.name
                        ),
                    });
                }

                // Check type change
                if old_field.proto_type != new_field.proto_type {
                    result.violations.push(CompatibilityViolation {
                        message_name: old.name.clone(),
                        field_name: Some(new_field.name.clone()),
                        field_number: Some(*number),
                        violation_type: ViolationType::FieldTypeChanged,
                        description: format!(
                            "Field '{}' type changed from {} to {}",
                            new_field.name,
                            old_field.proto_type.to_proto_string(),
                            new_field.proto_type.to_proto_string()
                        ),
                    });
                }
            } else {
                // New field - check if it reuses a previously removed name
                if old_by_name.contains_key(new_field.name.as_str()) {
                    let old_field = old_by_name[new_field.name.as_str()];
                    if old_field.number != *number {
                        result.violations.push(CompatibilityViolation {
                            message_name: old.name.clone(),
                            field_name: Some(new_field.name.clone()),
                            field_number: Some(*number),
                            violation_type: ViolationType::FieldNumberReused,
                            description: format!(
                                "Field '{}' changed number from {} to {}",
                                new_field.name, old_field.number, number
                            ),
                        });
                    }
                }
            }
        }
    }

    /// Apply compatibility fixes to a new ProtoFile based on an old one.
    ///
    /// This adds reserved field numbers and names for removed fields.
    pub fn apply_backward_compatibility(old: &ProtoFile, new: &mut ProtoFile) {
        let result = Self::check(old, new, CompatibilityMode::Backward);

        // Apply suggested reserved numbers
        for msg in &mut new.messages {
            if let Some(reserved_nums) = result.suggested_reserved_numbers.get(&msg.name) {
                for num in reserved_nums {
                    if !msg.reserved_numbers.contains(num) {
                        msg.reserved_numbers.push(*num);
                    }
                }
                msg.reserved_numbers.sort();
            }

            if let Some(reserved_names) = result.suggested_reserved_names.get(&msg.name) {
                for name in reserved_names {
                    if !msg.reserved_names.contains(name) {
                        msg.reserved_names.push(name.clone());
                    }
                }
                msg.reserved_names.sort();
            }
        }
    }
}

/// File-based schema history storage.
pub struct SchemaHistory {
    /// Directory where schema history is stored
    history_dir: std::path::PathBuf,
}

impl SchemaHistory {
    /// Create a new SchemaHistory with the given directory.
    pub fn new(history_dir: impl Into<std::path::PathBuf>) -> Self {
        Self {
            history_dir: history_dir.into(),
        }
    }

    /// Get the path for a schema file.
    fn schema_path(&self, package: &str) -> std::path::PathBuf {
        let filename = format!("{}.json", package.replace('.', "_"));
        self.history_dir.join(filename)
    }

    /// Load the previous schema for a package.
    pub fn load(&self, package: &str) -> Result<Option<ProtoFile>, String> {
        let path = self.schema_path(package);
        if !path.exists() {
            return Ok(None);
        }

        let content = std::fs::read_to_string(&path)
            .map_err(|e| format!("Failed to read schema history: {}", e))?;

        let proto: ProtoFile = serde_json::from_str(&content)
            .map_err(|e| format!("Failed to parse schema history: {}", e))?;

        Ok(Some(proto))
    }

    /// Save a schema to history.
    pub fn save(&self, proto: &ProtoFile) -> Result<(), String> {
        // Ensure directory exists
        std::fs::create_dir_all(&self.history_dir)
            .map_err(|e| format!("Failed to create history directory: {}", e))?;

        let path = self.schema_path(&proto.package);
        let content = serde_json::to_string_pretty(proto)
            .map_err(|e| format!("Failed to serialize schema: {}", e))?;

        std::fs::write(&path, content)
            .map_err(|e| format!("Failed to write schema history: {}", e))?;

        Ok(())
    }

    /// Check compatibility and optionally apply fixes.
    pub fn check_and_update(
        &self,
        new: &mut ProtoFile,
        mode: CompatibilityMode,
        apply_fixes: bool,
    ) -> Result<CompatibilityResult, String> {
        let old = self.load(&new.package)?;

        let result = match old {
            Some(ref old_proto) => {
                if apply_fixes && mode == CompatibilityMode::Backward {
                    CompatibilityChecker::apply_backward_compatibility(old_proto, new);
                }
                CompatibilityChecker::check(old_proto, new, mode)
            }
            None => CompatibilityResult::compatible(mode),
        };

        // Save the new schema if compatible (or in breaking mode)
        if result.is_compatible || mode == CompatibilityMode::Breaking {
            self.save(new)?;
        }

        Ok(result)
    }
}

// ============================================================================
// Tests
// ============================================================================

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

    #[test]
    fn test_to_pascal_case() {
        assert_eq!(to_pascal_case("hello_world"), "HelloWorld");
        assert_eq!(to_pascal_case("my-entity"), "MyEntity");
        assert_eq!(to_pascal_case("already PascalCase"), "AlreadyPascalcase");
        assert_eq!(to_pascal_case("UPPERCASE"), "Uppercase");
    }

    #[test]
    fn test_to_snake_case() {
        assert_eq!(to_snake_case("HelloWorld"), "hello_world");
        assert_eq!(to_snake_case("myEntity"), "my_entity");
        assert_eq!(to_snake_case("already_snake"), "already_snake");
        // Consecutive uppercase chars become lowercase without underscore separation
        assert_eq!(to_snake_case("XMLParser"), "xmlparser");
        assert_eq!(to_snake_case("PaymentID"), "payment_id");
    }

    #[test]
    fn test_to_screaming_snake_case() {
        assert_eq!(to_screaming_snake_case("MyEnum"), "MY_ENUM");
        assert_eq!(to_screaming_snake_case("StatusCode"), "STATUS_CODE");
    }

    #[test]
    fn test_map_sea_type_to_proto() {
        assert_eq!(
            map_sea_type_to_proto("string"),
            ProtoType::Scalar(ScalarType::String)
        );
        assert_eq!(
            map_sea_type_to_proto("int"),
            ProtoType::Scalar(ScalarType::Int64)
        );
        assert_eq!(
            map_sea_type_to_proto("boolean"),
            ProtoType::Scalar(ScalarType::Bool)
        );
        assert_eq!(
            map_sea_type_to_proto("timestamp"),
            ProtoType::Message("google.protobuf.Timestamp".to_string())
        );
        assert_eq!(
            map_sea_type_to_proto("CustomType"),
            ProtoType::Message("Customtype".to_string())
        );
    }

    #[test]
    fn test_proto_field_to_string() {
        let field = ProtoField {
            name: "my_field".to_string(),
            number: 1,
            proto_type: ProtoType::Scalar(ScalarType::String),
            repeated: false,
            optional: false,
            comments: vec![],
        };
        assert_eq!(field.to_proto_string(), "string my_field = 1;");

        let optional_field = ProtoField {
            name: "optional_field".to_string(),
            number: 2,
            proto_type: ProtoType::Scalar(ScalarType::Int64),
            repeated: false,
            optional: true,
            comments: vec![],
        };
        assert_eq!(
            optional_field.to_proto_string(),
            "optional int64 optional_field = 2;"
        );

        let repeated_field = ProtoField {
            name: "items".to_string(),
            number: 3,
            proto_type: ProtoType::Scalar(ScalarType::String),
            repeated: true,
            optional: false,
            comments: vec![],
        };
        assert_eq!(
            repeated_field.to_proto_string(),
            "repeated string items = 3;"
        );
    }

    #[test]
    fn test_proto_enum_to_string() {
        let mut e = ProtoEnum::new("Status");
        e.add_value("STATUS_ACTIVE");
        e.add_value("STATUS_INACTIVE");

        let output = e.to_proto_string();
        assert!(output.contains("enum Status {"));
        assert!(output.contains("STATUS_UNSPECIFIED = 0;"));
        assert!(output.contains("STATUS_ACTIVE = 1;"));
        assert!(output.contains("STATUS_INACTIVE = 2;"));
    }

    #[test]
    fn test_proto_message_to_string() {
        let mut msg = ProtoMessage::new("Person");
        msg.fields.push(ProtoField {
            name: "name".to_string(),
            number: 1,
            proto_type: ProtoType::Scalar(ScalarType::String),
            repeated: false,
            optional: false,
            comments: vec![],
        });
        msg.fields.push(ProtoField {
            name: "age".to_string(),
            number: 2,
            proto_type: ProtoType::Scalar(ScalarType::Int32),
            repeated: false,
            optional: true,
            comments: vec![],
        });

        let output = msg.to_proto_string();
        assert!(output.contains("message Person {"));
        assert!(output.contains("string name = 1;"));
        assert!(output.contains("optional int32 age = 2;"));
    }

    #[test]
    fn test_proto_file_to_string() {
        let mut proto = ProtoFile::new("test.package");
        proto.metadata.projection_name = "TestProjection".to_string();
        proto.metadata.source_namespace = "test".to_string();

        let mut msg = ProtoMessage::new("TestMessage");
        msg.fields.push(ProtoField {
            name: "id".to_string(),
            number: 1,
            proto_type: ProtoType::Scalar(ScalarType::String),
            repeated: false,
            optional: false,
            comments: vec![],
        });
        proto.messages.push(msg);

        let output = proto.to_proto_string();
        assert!(output.contains("syntax = \"proto3\";"));
        assert!(output.contains("package test.package;"));
        assert!(output.contains("message TestMessage {"));
        assert!(output.contains("string id = 1;"));
    }

    #[test]
    fn test_entity_to_message() {
        use serde_json::json;

        let mut entity = Entity::new_with_namespace("Warehouse", "logistics");
        entity.set_attribute("capacity", json!(5000));
        entity.set_attribute("location", json!("Building A"));

        let msg = ProtobufEngine::entity_to_message(&entity);

        assert_eq!(msg.name, "Warehouse");
        assert!(msg.fields.iter().any(|f| f.name == "id"));
        assert!(msg.fields.iter().any(|f| f.name == "name"));
        assert!(msg.fields.iter().any(|f| f.name == "capacity"));
        assert!(msg.fields.iter().any(|f| f.name == "location"));

        // Check field numbers are sequential
        let numbers: Vec<u32> = msg.fields.iter().map(|f| f.number).collect();
        assert_eq!(numbers, vec![1, 2, 3, 4]); // id, name, capacity, location (sorted)
    }

    #[test]
    fn test_governance_messages() {
        let messages = ProtobufEngine::generate_governance_messages();
        assert_eq!(messages.len(), 2);

        let violation = messages.iter().find(|m| m.name == "PolicyViolation");
        assert!(violation.is_some());

        let metric = messages.iter().find(|m| m.name == "MetricEvent");
        assert!(metric.is_some());
    }

    // ========================================================================
    // Well-Known Type Tests
    // ========================================================================

    #[test]
    fn test_wkt_type_name() {
        assert_eq!(
            WellKnownType::Timestamp.type_name(),
            "google.protobuf.Timestamp"
        );
        assert_eq!(
            WellKnownType::Duration.type_name(),
            "google.protobuf.Duration"
        );
        assert_eq!(WellKnownType::Any.type_name(), "google.protobuf.Any");
        assert_eq!(WellKnownType::Struct.type_name(), "google.protobuf.Struct");
        assert_eq!(WellKnownType::Empty.type_name(), "google.protobuf.Empty");
        assert_eq!(
            WellKnownType::Int64Value.type_name(),
            "google.protobuf.Int64Value"
        );
    }

    #[test]
    fn test_wkt_import_path() {
        assert_eq!(
            WellKnownType::Timestamp.import_path(),
            "google/protobuf/timestamp.proto"
        );
        assert_eq!(
            WellKnownType::Duration.import_path(),
            "google/protobuf/duration.proto"
        );
        assert_eq!(
            WellKnownType::Any.import_path(),
            "google/protobuf/any.proto"
        );
        assert_eq!(
            WellKnownType::Struct.import_path(),
            "google/protobuf/struct.proto"
        );
        assert_eq!(
            WellKnownType::Value.import_path(),
            "google/protobuf/struct.proto"
        );
        assert_eq!(
            WellKnownType::Empty.import_path(),
            "google/protobuf/empty.proto"
        );
        assert_eq!(
            WellKnownType::Int64Value.import_path(),
            "google/protobuf/wrappers.proto"
        );
        assert_eq!(
            WellKnownType::StringValue.import_path(),
            "google/protobuf/wrappers.proto"
        );
    }

    #[test]
    fn test_wkt_from_type_name() {
        assert_eq!(
            WellKnownType::from_type_name("google.protobuf.Timestamp"),
            Some(WellKnownType::Timestamp)
        );
        assert_eq!(
            WellKnownType::from_type_name("google.protobuf.Duration"),
            Some(WellKnownType::Duration)
        );
        assert_eq!(
            WellKnownType::from_type_name("google.protobuf.Any"),
            Some(WellKnownType::Any)
        );
        assert_eq!(
            WellKnownType::from_type_name("google.protobuf.StringValue"),
            Some(WellKnownType::StringValue)
        );
        assert_eq!(WellKnownType::from_type_name("SomeOtherType"), None);
    }

    #[test]
    fn test_map_sea_type_to_wkt() {
        // Timestamp types
        assert_eq!(
            map_sea_type_to_proto("timestamp"),
            ProtoType::Message("google.protobuf.Timestamp".to_string())
        );
        assert_eq!(
            map_sea_type_to_proto("datetime"),
            ProtoType::Message("google.protobuf.Timestamp".to_string())
        );

        // Duration types
        assert_eq!(
            map_sea_type_to_proto("duration"),
            ProtoType::Message("google.protobuf.Duration".to_string())
        );
        assert_eq!(
            map_sea_type_to_proto("timespan"),
            ProtoType::Message("google.protobuf.Duration".to_string())
        );

        // Dynamic types
        assert_eq!(
            map_sea_type_to_proto("any"),
            ProtoType::Message("google.protobuf.Any".to_string())
        );
        assert_eq!(
            map_sea_type_to_proto("json"),
            ProtoType::Message("google.protobuf.Struct".to_string())
        );

        // Empty type
        assert_eq!(
            map_sea_type_to_proto("void"),
            ProtoType::Message("google.protobuf.Empty".to_string())
        );

        // Nullable/optional types
        assert_eq!(
            map_sea_type_to_proto("optional_string"),
            ProtoType::Message("google.protobuf.StringValue".to_string())
        );
        assert_eq!(
            map_sea_type_to_proto("nullable_int"),
            ProtoType::Message("google.protobuf.Int64Value".to_string())
        );
    }

    #[test]
    fn test_add_wkt_imports() {
        let mut proto = ProtoFile::new("test");

        // Add a message with a Timestamp field
        let mut msg = ProtoMessage::new("Event");
        msg.fields.push(ProtoField {
            name: "created_at".to_string(),
            number: 1,
            proto_type: ProtoType::Message("google.protobuf.Timestamp".to_string()),
            repeated: false,
            optional: false,
            comments: vec![],
        });
        msg.fields.push(ProtoField {
            name: "duration".to_string(),
            number: 2,
            proto_type: ProtoType::Message("google.protobuf.Duration".to_string()),
            repeated: false,
            optional: false,
            comments: vec![],
        });
        proto.messages.push(msg);

        proto.add_wkt_imports();

        assert!(proto
            .imports
            .contains(&"google/protobuf/timestamp.proto".to_string()));
        assert!(proto
            .imports
            .contains(&"google/protobuf/duration.proto".to_string()));
    }

    #[test]
    fn test_resolve_imports_in_message() {
        // Setup index with a target message
        let mut index = HashMap::new();
        index.insert(
            "TargetType".to_string(),
            ("other.ns".to_string(), "base.other.ns".to_string()),
        );

        let mut msg = ProtoMessage::new("SourceMessage");
        msg.fields.push(ProtoField {
            name: "field1".to_string(),
            number: 1,
            proto_type: ProtoType::Message("TargetType".to_string()),
            repeated: false,
            optional: false,
            comments: vec![],
        });

        let mut imports = HashSet::new();

        // Resolve imports
        ProtobufEngine::resolve_imports_in_message(&mut msg, "current.ns", &index, &mut imports);

        // Should find import for other.ns
        assert!(imports.contains("other.ns"));

        // Should update type name to fully qualified
        let field_type = if let ProtoType::Message(ref name) = msg.fields[0].proto_type {
            name.clone()
        } else {
            panic!("Wrong type");
        };
        assert_eq!(field_type, "base.other.ns.TargetType");
    }

    #[test]
    fn test_resolve_imports_in_nested_message() {
        let mut index = HashMap::new();
        index.insert(
            "NestedTarget".to_string(),
            ("other.ns".to_string(), "base.other.ns".to_string()),
        );

        let mut msg = ProtoMessage::new("Outer");
        let mut inner = ProtoMessage::new("Inner");
        inner.fields.push(ProtoField {
            name: "field".to_string(),
            number: 1,
            proto_type: ProtoType::Message("NestedTarget".to_string()),
            repeated: false,
            optional: false,
            comments: vec![],
        });
        msg.nested_messages.push(inner);

        let mut imports = HashSet::new();
        ProtobufEngine::resolve_imports_in_message(&mut msg, "current.ns", &index, &mut imports);

        assert!(imports.contains("other.ns"));
    }

    #[test]
    fn test_wkt_imports_in_proto_string() {
        let mut proto = ProtoFile::new("test.wkt");

        let mut msg = ProtoMessage::new("AuditLog");
        msg.fields.push(ProtoField {
            name: "timestamp".to_string(),
            number: 1,
            proto_type: ProtoType::Message("google.protobuf.Timestamp".to_string()),
            repeated: false,
            optional: false,
            comments: vec![],
        });
        proto.messages.push(msg);
        proto.add_wkt_imports();

        let output = proto.to_proto_string();
        assert!(output.contains("import \"google/protobuf/timestamp.proto\";"));
    }

    #[test]
    fn test_wkt_no_duplicate_imports() {
        let mut proto = ProtoFile::new("test");

        // Add multiple messages using the same WKT
        let mut msg1 = ProtoMessage::new("Event1");
        msg1.fields.push(ProtoField {
            name: "time1".to_string(),
            number: 1,
            proto_type: ProtoType::Message("google.protobuf.Timestamp".to_string()),
            repeated: false,
            optional: false,
            comments: vec![],
        });

        let mut msg2 = ProtoMessage::new("Event2");
        msg2.fields.push(ProtoField {
            name: "time2".to_string(),
            number: 1,
            proto_type: ProtoType::Message("google.protobuf.Timestamp".to_string()),
            repeated: false,
            optional: false,
            comments: vec![],
        });

        proto.messages.push(msg1);
        proto.messages.push(msg2);
        proto.add_wkt_imports();

        // Should only have one timestamp import
        let timestamp_count = proto
            .imports
            .iter()
            .filter(|i| i.contains("timestamp"))
            .count();
        assert_eq!(timestamp_count, 1);
    }

    // ========================================================================
    // Custom Options Tests
    // ========================================================================

    #[test]
    fn test_proto_option_value_string() {
        let val = ProtoOptionValue::String("com.example.api".to_string());
        assert_eq!(val.to_proto_string(), "\"com.example.api\"");
    }

    #[test]
    fn test_proto_option_value_string_escaping() {
        let val = ProtoOptionValue::String("path\\to\\file".to_string());
        assert_eq!(val.to_proto_string(), "\"path\\\\to\\\\file\"");

        let val2 = ProtoOptionValue::String("say \"hello\"".to_string());
        assert_eq!(val2.to_proto_string(), "\"say \\\"hello\\\"\"");
    }

    #[test]
    fn test_proto_option_value_int() {
        let val = ProtoOptionValue::Int(42);
        assert_eq!(val.to_proto_string(), "42");

        let neg = ProtoOptionValue::Int(-100);
        assert_eq!(neg.to_proto_string(), "-100");
    }

    #[test]
    fn test_proto_option_value_float() {
        let val = ProtoOptionValue::Float(3.15);
        assert_eq!(val.to_proto_string(), "3.15");
    }

    #[test]
    fn test_proto_option_value_bool() {
        assert_eq!(ProtoOptionValue::Bool(true).to_proto_string(), "true");
        assert_eq!(ProtoOptionValue::Bool(false).to_proto_string(), "false");
    }

    #[test]
    fn test_proto_option_value_identifier() {
        let val = ProtoOptionValue::Identifier("SPEED".to_string());
        assert_eq!(val.to_proto_string(), "SPEED");
    }

    #[test]
    fn test_proto_custom_option_to_string() {
        let opt = ProtoCustomOption::new(
            "java_package",
            ProtoOptionValue::String("com.example".to_string()),
        );
        assert_eq!(
            opt.to_proto_string(),
            "option java_package = \"com.example\";"
        );
    }

    #[test]
    fn test_proto_custom_option_extension() {
        // Extension option with parentheses
        let opt = ProtoCustomOption::new("(mycompany.api_version)", ProtoOptionValue::Int(2));
        assert_eq!(opt.to_proto_string(), "option (mycompany.api_version) = 2;");
    }

    #[test]
    fn test_proto_options_set_standard_options() {
        let mut opts = ProtoOptions::default();

        opts.set_option(
            "java_package",
            ProtoOptionValue::String("com.example".to_string()),
        );
        opts.set_option("java_multiple_files", ProtoOptionValue::Bool(true));
        opts.set_option(
            "go_package",
            ProtoOptionValue::String("github.com/example".to_string()),
        );
        opts.set_option(
            "csharp_namespace",
            ProtoOptionValue::String("Example.Api".to_string()),
        );
        opts.set_option("deprecated", ProtoOptionValue::Bool(true));

        assert_eq!(opts.java_package, Some("com.example".to_string()));
        assert!(opts.java_multiple_files);
        assert_eq!(opts.go_package, Some("github.com/example".to_string()));
        assert_eq!(opts.csharp_namespace, Some("Example.Api".to_string()));
        assert!(opts.deprecated);
    }

    #[test]
    fn test_proto_options_set_custom_option() {
        let mut opts = ProtoOptions::default();

        opts.set_option(
            "my_custom_option",
            ProtoOptionValue::String("custom_value".to_string()),
        );

        assert_eq!(opts.custom_options.len(), 1);
        assert_eq!(opts.custom_options[0].name, "my_custom_option");
    }

    #[test]
    fn test_proto_file_with_all_options() {
        let mut proto = ProtoFile::new("test.api");
        proto.options.java_package = Some("com.example.api".to_string());
        proto.options.java_multiple_files = true;
        proto.options.go_package = Some("github.com/example/api".to_string());
        proto.options.csharp_namespace = Some("Example.Api".to_string());
        proto.options.optimize_for = Some("SPEED".to_string());
        proto.options.custom_options.push(ProtoCustomOption::new(
            "(api.version)",
            ProtoOptionValue::Int(1),
        ));

        let output = proto.to_proto_string();
        assert!(output.contains("option java_package = \"com.example.api\";"));
        assert!(output.contains("option java_multiple_files = true;"));
        assert!(output.contains("option go_package = \"github.com/example/api\";"));
        assert!(output.contains("option csharp_namespace = \"Example.Api\";"));
        assert!(output.contains("option optimize_for = SPEED;"));
        assert!(output.contains("option (api.version) = 1;"));
    }

    #[test]
    fn test_proto_option_value_from_json() {
        use serde_json::json;

        assert_eq!(
            ProtoOptionValue::from_json(&json!("hello")),
            ProtoOptionValue::String("hello".to_string())
        );
        assert_eq!(
            ProtoOptionValue::from_json(&json!(true)),
            ProtoOptionValue::Bool(true)
        );
        assert_eq!(
            ProtoOptionValue::from_json(&json!(42)),
            ProtoOptionValue::Int(42)
        );
        assert_eq!(
            ProtoOptionValue::from_json(&json!(3.15)),
            ProtoOptionValue::Float(3.15)
        );
    }

    // ========================================================================
    // gRPC Service Tests
    // ========================================================================

    #[test]
    fn test_proto_service_to_string() {
        let mut service = ProtoService::new("PaymentService");
        service
            .comments
            .push("Payment processing service".to_string());

        service.methods.push(ProtoRpcMethod::new(
            "ProcessPayment",
            "PaymentRequest",
            "PaymentResponse",
        ));

        let output = service.to_proto_string();
        assert!(output.contains("service PaymentService {"));
        assert!(output.contains("rpc ProcessPayment(PaymentRequest) returns (PaymentResponse);"));
        assert!(output.contains("// Payment processing service"));
    }

    #[test]
    fn test_proto_rpc_method_unary() {
        let method = ProtoRpcMethod::new("GetUser", "GetUserRequest", "User");
        let output = method.to_proto_string();
        assert_eq!(output, "rpc GetUser(GetUserRequest) returns (User);");
    }

    #[test]
    fn test_proto_rpc_method_server_streaming() {
        let mut method = ProtoRpcMethod::new("ListEvents", "ListEventsRequest", "Event");
        method.streaming = StreamingMode::ServerStreaming;
        let output = method.to_proto_string();
        assert_eq!(
            output,
            "rpc ListEvents(ListEventsRequest) returns (stream Event);"
        );
    }

    #[test]
    fn test_proto_rpc_method_client_streaming() {
        let mut method = ProtoRpcMethod::new("UploadChunks", "DataChunk", "UploadResult");
        method.streaming = StreamingMode::ClientStreaming;
        let output = method.to_proto_string();
        assert_eq!(
            output,
            "rpc UploadChunks(stream DataChunk) returns (UploadResult);"
        );
    }

    #[test]
    fn test_proto_rpc_method_bidirectional() {
        let mut method = ProtoRpcMethod::new("Chat", "ChatMessage", "ChatMessage");
        method.streaming = StreamingMode::Bidirectional;
        let output = method.to_proto_string();
        assert_eq!(
            output,
            "rpc Chat(stream ChatMessage) returns (stream ChatMessage);"
        );
    }

    #[test]
    fn test_streaming_mode_from_str() {
        assert_eq!(
            StreamingMode::parse("streaming"),
            StreamingMode::ServerStreaming
        );
        assert_eq!(
            StreamingMode::parse("server_streaming"),
            StreamingMode::ServerStreaming
        );
        assert_eq!(
            StreamingMode::parse("client_streaming"),
            StreamingMode::ClientStreaming
        );
        assert_eq!(
            StreamingMode::parse("bidirectional"),
            StreamingMode::Bidirectional
        );
        assert_eq!(StreamingMode::parse("bidi"), StreamingMode::Bidirectional);
        assert_eq!(StreamingMode::parse("duplex"), StreamingMode::Bidirectional);
        assert_eq!(StreamingMode::parse("unary"), StreamingMode::Unary);
        assert_eq!(StreamingMode::parse(""), StreamingMode::Unary);
    }

    #[test]
    fn test_streaming_mode_display() {
        assert_eq!(format!("{}", StreamingMode::Unary), "unary");
        assert_eq!(
            format!("{}", StreamingMode::ServerStreaming),
            "server_streaming"
        );
        assert_eq!(
            format!("{}", StreamingMode::ClientStreaming),
            "client_streaming"
        );
        assert_eq!(format!("{}", StreamingMode::Bidirectional), "bidirectional");
    }

    #[test]
    fn test_proto_file_with_services() {
        let mut proto = ProtoFile::new("test.api");

        let mut service = ProtoService::new("GreeterService");
        service.methods.push(ProtoRpcMethod::new(
            "SayHello",
            "HelloRequest",
            "HelloResponse",
        ));
        proto.services.push(service);

        let output = proto.to_proto_string();
        assert!(output.contains("service GreeterService {"));
        assert!(output.contains("rpc SayHello(HelloRequest) returns (HelloResponse);"));
    }

    // ========================================================================
    // Compatibility Tests
    // ========================================================================

    fn make_test_proto(messages: Vec<ProtoMessage>) -> ProtoFile {
        ProtoFile {
            package: "test.package".to_string(),
            syntax: "proto3".to_string(),
            imports: vec![],
            options: ProtoOptions::default(),
            enums: vec![],
            messages,
            services: vec![],
            metadata: ProtoMetadata::default(),
        }
    }

    fn make_test_message(name: &str, fields: Vec<ProtoField>) -> ProtoMessage {
        ProtoMessage {
            name: name.to_string(),
            fields,
            nested_messages: vec![],
            nested_enums: vec![],
            reserved_numbers: vec![],
            reserved_names: vec![],
            comments: vec![],
        }
    }

    fn make_test_field(name: &str, number: u32, proto_type: ProtoType) -> ProtoField {
        ProtoField {
            name: name.to_string(),
            number,
            proto_type,
            repeated: false,
            optional: false,
            comments: vec![],
        }
    }

    #[test]
    fn test_compatibility_no_changes() {
        let old = make_test_proto(vec![make_test_message(
            "Person",
            vec![
                make_test_field("id", 1, ProtoType::Scalar(ScalarType::String)),
                make_test_field("name", 2, ProtoType::Scalar(ScalarType::String)),
            ],
        )]);

        let new = old.clone();

        let result = CompatibilityChecker::check(&old, &new, CompatibilityMode::Additive);
        assert!(result.is_compatible);
        assert!(result.violations.is_empty());
    }

    #[test]
    fn test_compatibility_field_added() {
        let old = make_test_proto(vec![make_test_message(
            "Person",
            vec![make_test_field(
                "id",
                1,
                ProtoType::Scalar(ScalarType::String),
            )],
        )]);

        let new = make_test_proto(vec![make_test_message(
            "Person",
            vec![
                make_test_field("id", 1, ProtoType::Scalar(ScalarType::String)),
                make_test_field("name", 2, ProtoType::Scalar(ScalarType::String)),
            ],
        )]);

        // Adding fields is compatible in all modes
        let result = CompatibilityChecker::check(&old, &new, CompatibilityMode::Additive);
        assert!(result.is_compatible);
        assert!(result.violations.is_empty());
    }

    #[test]
    fn test_compatibility_field_removed_additive() {
        let old = make_test_proto(vec![make_test_message(
            "Person",
            vec![
                make_test_field("id", 1, ProtoType::Scalar(ScalarType::String)),
                make_test_field("name", 2, ProtoType::Scalar(ScalarType::String)),
            ],
        )]);

        let new = make_test_proto(vec![make_test_message(
            "Person",
            vec![make_test_field(
                "id",
                1,
                ProtoType::Scalar(ScalarType::String),
            )],
        )]);

        // Removing fields is NOT compatible in additive mode
        let result = CompatibilityChecker::check(&old, &new, CompatibilityMode::Additive);
        assert!(!result.is_compatible);
        assert_eq!(result.violations.len(), 1);
        assert_eq!(
            result.violations[0].violation_type,
            ViolationType::FieldRemoved
        );
    }

    #[test]
    fn test_compatibility_field_removed_backward() {
        let old = make_test_proto(vec![make_test_message(
            "Person",
            vec![
                make_test_field("id", 1, ProtoType::Scalar(ScalarType::String)),
                make_test_field("name", 2, ProtoType::Scalar(ScalarType::String)),
            ],
        )]);

        let new = make_test_proto(vec![make_test_message(
            "Person",
            vec![make_test_field(
                "id",
                1,
                ProtoType::Scalar(ScalarType::String),
            )],
        )]);

        // Removing fields IS compatible in backward mode (with warnings)
        let result = CompatibilityChecker::check(&old, &new, CompatibilityMode::Backward);
        assert!(result.is_compatible); // Still compatible, just has violations
        assert!(!result.violations.is_empty());

        // Should suggest reserving the field
        assert!(result.suggested_reserved_numbers.contains_key("Person"));
        assert!(result.suggested_reserved_numbers["Person"].contains(&2));
    }

    #[test]
    fn test_compatibility_type_change() {
        let old = make_test_proto(vec![make_test_message(
            "Person",
            vec![make_test_field(
                "age",
                1,
                ProtoType::Scalar(ScalarType::Int32),
            )],
        )]);

        let new = make_test_proto(vec![make_test_message(
            "Person",
            vec![make_test_field(
                "age",
                1,
                ProtoType::Scalar(ScalarType::String),
            )],
        )]);

        // Type changes are NOT compatible in backward mode
        let result = CompatibilityChecker::check(&old, &new, CompatibilityMode::Backward);
        assert!(!result.is_compatible);
        assert!(result
            .violations
            .iter()
            .any(|v| v.violation_type == ViolationType::FieldTypeChanged));
    }

    #[test]
    fn test_compatibility_breaking_mode() {
        let old = make_test_proto(vec![make_test_message(
            "Person",
            vec![make_test_field(
                "id",
                1,
                ProtoType::Scalar(ScalarType::String),
            )],
        )]);

        let new = make_test_proto(vec![make_test_message(
            "Person",
            vec![make_test_field(
                "uuid",
                1,
                ProtoType::Scalar(ScalarType::Int64),
            )],
        )]);

        // Breaking mode allows everything
        let result = CompatibilityChecker::check(&old, &new, CompatibilityMode::Breaking);
        assert!(result.is_compatible);
        // Violations are still reported for informational purposes
        assert!(!result.violations.is_empty());
    }

    #[test]
    fn test_apply_backward_compatibility() {
        let old = make_test_proto(vec![make_test_message(
            "Person",
            vec![
                make_test_field("id", 1, ProtoType::Scalar(ScalarType::String)),
                make_test_field("name", 2, ProtoType::Scalar(ScalarType::String)),
                make_test_field("email", 3, ProtoType::Scalar(ScalarType::String)),
            ],
        )]);

        let mut new = make_test_proto(vec![make_test_message(
            "Person",
            vec![
                make_test_field("id", 1, ProtoType::Scalar(ScalarType::String)),
                // name (2) removed
                // email (3) removed
                make_test_field("phone", 4, ProtoType::Scalar(ScalarType::String)),
            ],
        )]);

        CompatibilityChecker::apply_backward_compatibility(&old, &mut new);

        // Should have added reserved numbers
        let person = &new.messages[0];
        assert!(person.reserved_numbers.contains(&2));
        assert!(person.reserved_numbers.contains(&3));
        assert!(person.reserved_names.contains(&"name".to_string()));
        assert!(person.reserved_names.contains(&"email".to_string()));
    }

    #[test]
    fn test_compatibility_message_removed() {
        let old = make_test_proto(vec![
            make_test_message("Person", vec![]),
            make_test_message("Address", vec![]),
        ]);

        let new = make_test_proto(vec![make_test_message("Person", vec![])]);

        let result = CompatibilityChecker::check(&old, &new, CompatibilityMode::Additive);
        assert!(!result.is_compatible);
        assert!(result.violations.iter().any(|v| {
            v.violation_type == ViolationType::MessageRemoved && v.message_name == "Address"
        }));
    }

    #[test]
    fn test_compatibility_result_report() {
        let old = make_test_proto(vec![make_test_message(
            "Person",
            vec![make_test_field(
                "name",
                1,
                ProtoType::Scalar(ScalarType::String),
            )],
        )]);

        let new = make_test_proto(vec![make_test_message("Person", vec![])]);

        let result = CompatibilityChecker::check(&old, &new, CompatibilityMode::Backward);
        let report = result.to_report();

        assert!(report.contains("Compatibility Check"));
        assert!(report.contains("field_removed"));
        assert!(report.contains("Person"));
    }

    #[test]
    fn test_compatibility_mode_parsing() {
        assert_eq!(
            "additive".parse::<CompatibilityMode>().unwrap(),
            CompatibilityMode::Additive
        );
        assert_eq!(
            "backward".parse::<CompatibilityMode>().unwrap(),
            CompatibilityMode::Backward
        );
        assert_eq!(
            "breaking".parse::<CompatibilityMode>().unwrap(),
            CompatibilityMode::Breaking
        );
        assert!("invalid".parse::<CompatibilityMode>().is_err());
    }
}