ryo_app/api/

types.rs

//! Request/Response types for the Api.
//!
//! These types are used both for direct API calls and for RPC transport (tarpc).

use crate::intent::Goal;
use ryo_analysis::SymbolKind;
use ryo_suggest::EnhancedSuggestion;
use serde::{Deserialize, Serialize};
use std::path::PathBuf;

// Re-export from ryo-query-language for unified types
pub use ryo_query_language::{QueryResponse, ViewMode};

// ============================================================================
// Execution Status (HTTP-inspired status codes for CLI results)
// ============================================================================

/// Status code for execution results, inspired by HTTP status codes.
///
/// Provides a systematic categorization of execution outcomes:
/// - 2xx: Success (operation completed as intended)
/// - 4xx: Client Error (invalid input, not found, conflicts)
///
/// # Example
///
/// ```ignore
/// match status.code {
///     StatusCode::Ok => println!("Changes applied successfully"),
///     StatusCode::NoChange => println!("No changes needed"),
///     StatusCode::Conflict => println!("Conflicts require resolution"),
///     _ => {}
/// }
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum StatusCode {
    // ---- Success (2xx) ----
    /// 200: Operation succeeded with changes applied.
    Ok,
    /// 204: Operation succeeded but no changes were made (target already in desired state).
    NoChange,
    /// 206: Operation succeeded with automatic conflict resolution.
    Resolved,

    // ---- Client Error (4xx) ----
    /// 400: Invalid goal or planning failed.
    Invalid,
    /// 404: Target symbol or file not found.
    NotFound,
    /// 409: Conflicts detected that require manual resolution.
    Conflict,
    /// 422: Syntax validation failed after mutation.
    SyntaxError,
}

impl StatusCode {
    /// Returns true if this is a success status (2xx equivalent).
    pub fn is_success(&self) -> bool {
        matches!(self, Self::Ok | Self::NoChange | Self::Resolved)
    }

    /// Returns true if this is an error status (4xx equivalent).
    pub fn is_error(&self) -> bool {
        !self.is_success()
    }

    /// Returns the HTTP-like numeric code for reference.
    pub fn as_http_code(&self) -> u16 {
        match self {
            Self::Ok => 200,
            Self::NoChange => 204,
            Self::Resolved => 206,
            Self::Invalid => 400,
            Self::NotFound => 404,
            Self::Conflict => 409,
            Self::SyntaxError => 422,
        }
    }

    /// Returns the standard label for this status code.
    pub fn label(&self) -> &'static str {
        match self {
            Self::Ok => "OK",
            Self::NoChange => "NO_CHANGE",
            Self::Resolved => "RESOLVED",
            Self::Invalid => "INVALID",
            Self::NotFound => "NOT_FOUND",
            Self::Conflict => "CONFLICT",
            Self::SyntaxError => "SYNTAX_ERROR",
        }
    }
}

impl std::fmt::Display for StatusCode {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.label())
    }
}

/// Detailed information about the execution status.
///
/// Provides rich context for both success and error cases,
/// enabling informative CLI output and debugging.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct StatusDetail {
    /// Short reason (one line, suitable for status line).
    /// Example: "3 changes in 2 files"
    /// Example: "Symbol 'foo' not found in registry"
    pub reason: String,

    /// Detailed explanation (can be multi-line).
    /// Example: "The rename operation completed successfully.\nAll references were updated."
    /// Example: "The pattern 'foo*' matched 0 symbols.\nTry 'ryo discover foo*' to see available symbols."
    pub explanation: Option<String>,

    /// Actionable suggestions for the user.
    /// Example: ["Try 'ryo discover <pattern>' to find symbols", "Check spelling of symbol name"]
    pub suggestions: Vec<String>,

    /// Related context (e.g., conflicting symbols, matched patterns).
    pub context: Vec<String>,
}

impl StatusDetail {
    /// Create a new StatusDetail with just a reason.
    pub fn new(reason: impl Into<String>) -> Self {
        Self {
            reason: reason.into(),
            ..Default::default()
        }
    }

    /// Add an explanation.
    pub fn with_explanation(mut self, explanation: impl Into<String>) -> Self {
        self.explanation = Some(explanation.into());
        self
    }

    /// Add a suggestion.
    pub fn with_suggestion(mut self, suggestion: impl Into<String>) -> Self {
        self.suggestions.push(suggestion.into());
        self
    }

    /// Add multiple suggestions.
    pub fn with_suggestions(
        mut self,
        suggestions: impl IntoIterator<Item = impl Into<String>>,
    ) -> Self {
        self.suggestions
            .extend(suggestions.into_iter().map(Into::into));
        self
    }

    /// Add context information.
    pub fn with_context(mut self, context: impl Into<String>) -> Self {
        self.context.push(context.into());
        self
    }
}

/// Complete execution status combining code and detail.
///
/// This is the primary type for representing execution outcomes.
/// It provides both machine-readable status codes and human-readable details.
///
/// # Example
///
/// ```ignore
/// let status = ExecutionStatus::ok("3 changes in 2 files")
///     .with_explanation("Renamed 'foo' to 'bar' across the codebase.");
///
/// if status.is_success() {
///     println!("{}: {}", status.code, status.detail.reason);
/// }
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExecutionStatus {
    /// The status code.
    pub code: StatusCode,
    /// Detailed information.
    pub detail: StatusDetail,
}

impl ExecutionStatus {
    /// Create a new ExecutionStatus.
    pub fn new(code: StatusCode, detail: StatusDetail) -> Self {
        Self { code, detail }
    }

    // ---- Success constructors ----

    /// Create an OK status (200).
    pub fn ok(reason: impl Into<String>) -> Self {
        Self::new(StatusCode::Ok, StatusDetail::new(reason))
    }

    /// Create a NO_CHANGE status (204).
    pub fn no_change(reason: impl Into<String>) -> Self {
        Self::new(StatusCode::NoChange, StatusDetail::new(reason))
    }

    /// Create a RESOLVED status (206).
    pub fn resolved(reason: impl Into<String>) -> Self {
        Self::new(StatusCode::Resolved, StatusDetail::new(reason))
    }

    // ---- Error constructors ----

    /// Create an INVALID status (400).
    pub fn invalid(reason: impl Into<String>) -> Self {
        Self::new(StatusCode::Invalid, StatusDetail::new(reason))
    }

    /// Create a NOT_FOUND status (404).
    pub fn not_found(reason: impl Into<String>) -> Self {
        Self::new(StatusCode::NotFound, StatusDetail::new(reason))
    }

    /// Create a CONFLICT status (409).
    pub fn conflict(reason: impl Into<String>) -> Self {
        Self::new(StatusCode::Conflict, StatusDetail::new(reason))
    }

    /// Create a SYNTAX_ERROR status (422).
    pub fn syntax_error(reason: impl Into<String>) -> Self {
        Self::new(StatusCode::SyntaxError, StatusDetail::new(reason))
    }

    // ---- Builder methods ----

    /// Add an explanation.
    pub fn with_explanation(mut self, explanation: impl Into<String>) -> Self {
        self.detail.explanation = Some(explanation.into());
        self
    }

    /// Add a suggestion.
    pub fn with_suggestion(mut self, suggestion: impl Into<String>) -> Self {
        self.detail.suggestions.push(suggestion.into());
        self
    }

    /// Add multiple suggestions.
    pub fn with_suggestions(
        mut self,
        suggestions: impl IntoIterator<Item = impl Into<String>>,
    ) -> Self {
        self.detail
            .suggestions
            .extend(suggestions.into_iter().map(Into::into));
        self
    }

    /// Add context.
    pub fn with_context(mut self, context: impl Into<String>) -> Self {
        self.detail.context.push(context.into());
        self
    }

    // ---- Query methods ----

    /// Returns true if this is a success status.
    pub fn is_success(&self) -> bool {
        self.code.is_success()
    }

    /// Returns true if this is an error status.
    pub fn is_error(&self) -> bool {
        self.code.is_error()
    }
}

impl std::fmt::Display for ExecutionStatus {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}: {}", self.code, self.detail.reason)
    }
}

// ============================================================================
// Discover
// ============================================================================

/// Sort order for discovery results.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
pub enum SortOrder {
    /// Sort by name alphabetically.
    Alpha,
    /// Sort by reference count (most referenced first).
    #[default]
    Refs,
    /// Sort by impl count.
    Impls,
}

/// Request for symbol discovery.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DiscoverRequest {
    /// Pattern to search for (glob-like: `*`, `?`, `[a-z]`).
    pub pattern: String,
    /// Filter by item kind (function, struct, enum, etc.).
    pub kind: Option<SymbolKind>,
    /// Sort order for results.
    pub sort: Option<SortOrder>,
    /// Maximum number of results to return.
    pub limit: Option<usize>,
    /// Output detail level (snippet, precise, count, def, full).
    #[serde(default)]
    pub view: Option<ViewMode>,
    /// Filter for async functions only (true = async only, false = non-async only).
    #[serde(default)]
    pub is_async: Option<bool>,
    /// Filter for unsafe functions/traits (true = unsafe only, false = safe only).
    #[serde(default)]
    pub is_unsafe: Option<bool>,
    /// Filter by file path pattern (glob, e.g. "src/handlers/**").
    #[serde(default)]
    pub scope_path: Option<String>,
    /// Case-insensitive pattern matching (A-Z == a-z).
    #[serde(default)]
    pub ignore_case: bool,
    /// Ignore word separators and casing style (snake_case == camelCase == PascalCase).
    #[serde(default)]
    pub ignore_word_separate: bool,
    /// Filter by attribute pattern (e.g., "deprecated", "allow(dead_code)").
    #[serde(default)]
    pub attr: Option<String>,
    /// Interpret pattern as SymbolId instead of name pattern.
    ///
    /// When true, the `pattern` field is parsed as a SymbolId (e.g., "165v1")
    /// and a direct registry lookup is performed instead of pattern matching.
    #[serde(default)]
    pub is_id: bool,
}

impl Default for DiscoverRequest {
    fn default() -> Self {
        Self {
            pattern: "*".to_string(),
            kind: None,
            sort: None,
            limit: None,
            view: None,
            is_async: None,
            is_unsafe: None,
            scope_path: None,
            ignore_case: false,
            ignore_word_separate: false,
            attr: None,
            is_id: false,
        }
    }
}

/// A discovered symbol (tarpc-compatible, Bincode-safe).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DiscoveredSymbol {
    /// SymbolId as string (e.g., "165v1")
    ///
    /// **Warning**: This ID is session-volatile. Use `uuid` for persistent references.
    pub id: String,
    /// Persistent UUID for cross-session symbol tracking.
    ///
    /// This UUID survives server restarts and symbol renames.
    /// Returns `None` if the symbol hasn't been assigned a persistent ID.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uuid: Option<String>,
    /// Full symbol path (e.g., "ryo_analysis::registry::DetectRegistry")
    pub path: String,
    /// Symbol name
    pub name: String,
    /// Item kind (e.g., "Function", "Struct")
    pub kind: String,
    /// View mode used
    pub view_mode: String,
    /// Definition (for Def/Full modes)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub definition: Option<String>,
    /// Documentation (for Def/Full modes)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub doc: Option<String>,
    /// Function body (for Full mode)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub body: Option<String>,
    /// Code snippet (for Snippet mode)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub snippet: Option<String>,
}

/// Response from symbol discovery (tarpc-compatible, Bincode-safe).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DiscoverResponse {
    /// Query status
    pub status: String,
    /// Discovered symbols
    pub symbols: Vec<DiscoveredSymbol>,
    /// Total matches
    pub total: usize,
    /// Elapsed time in ms
    pub elapsed_ms: u32,
    /// Alternative search hint when 0 results with kind filter
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
}

// ============================================================================
// Overview
// ============================================================================

/// Request for codebase overview.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OverviewRequest {}

/// A crate with its module tree.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CrateOverview {
    /// Crate name.
    pub name: String,
    /// Module paths within this crate.
    pub modules: Vec<String>,
}

/// A symbol with a count metric (ref_count or impl_count).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OverviewSymbol {
    /// Full symbol path.
    pub path: String,
    /// Metric count (references or implementations).
    pub count: usize,
}

/// Symbol kind statistics.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OverviewStats {
    /// Number of crates.
    pub crate_count: usize,
    /// Counts by symbol kind (e.g., [("Functions", 120), ("Structs", 45)]).
    pub by_kind: Vec<(String, usize)>,
}

/// Response from codebase overview.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OverviewResponse {
    /// Crate/module structure.
    pub crates: Vec<CrateOverview>,
    /// Top structs by reference count.
    pub top_structs: Vec<OverviewSymbol>,
    /// Top traits by implementation count.
    pub top_traits: Vec<OverviewSymbol>,
    /// Statistics.
    pub stats: OverviewStats,
    /// Elapsed time in ms.
    pub elapsed_ms: u32,
}

// ============================================================================
// Literal Search
// ============================================================================

/// Request for literal search.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LiteralSearchRequest {
    /// Pattern to search for (glob-style: `*error*`, `"hello"`, etc.).
    pub pattern: String,
    /// Filter by literal kind (e.g., "string", "int", "bool").
    #[serde(default)]
    pub kind: Option<String>,
    /// Maximum number of results.
    #[serde(default = "default_literal_limit")]
    pub limit: usize,
}

fn default_literal_limit() -> usize {
    100
}

/// A single literal match result.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LiteralMatchResult {
    /// The literal value as it appears in source.
    pub value: String,
    /// The literal kind (e.g., "String", "Int", "Bool").
    pub kind: String,
    /// SymbolId of the containing symbol.
    pub symbol_id: String,
    /// File path containing this literal.
    pub file_path: String,
    /// Search relevance score.
    pub score: f32,
}

/// Response from literal search.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LiteralSearchResponse {
    /// Matched literals.
    pub matches: Vec<LiteralMatchResult>,
    /// Total matches found.
    pub total: usize,
    /// Elapsed time in ms.
    pub elapsed_ms: u32,
}

// ============================================================================
// RyoQL Query
// ============================================================================

/// Request for RyoQL query execution.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RyoqlRequest {
    /// The RyoQL query content (YAML or JSON string).
    pub query: String,
    /// Default view mode when the query itself does not specify one.
    #[serde(default)]
    pub default_view: Option<ViewMode>,
}

// Note: Response type is `QueryResponse` re-exported from ryo-query-language (line 12).

// ============================================================================
// Suggest
// ============================================================================

/// Request for code improvement suggestions.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct SuggestRequest {
    /// Optional pattern to filter suggestions.
    pub pattern_filter: Option<String>,
    /// Only show high-impact suggestions.
    pub high_impact: bool,
    /// Quick mode (fewer but faster suggestions).
    pub quick: bool,
    /// Run scan before returning suggestions.
    /// When true, executes suggest_scan() to detect new suggestions.
    pub scan: bool,
    /// Run pre-check on each suggestion during scan.
    /// When true, uses suggest_scan_with_precheck() which validates
    /// each suggestion before storing, ensuring Apply will succeed.
    #[serde(default)]
    pub precheck: bool,
    /// Rule IDs to exclude (e.g., ["RL021", "RL020"]).
    #[serde(default)]
    pub exclude_rules: Vec<String>,
    /// Return enhanced suggestions with design choices and verification status.
    #[serde(default)]
    pub enhanced: bool,
    /// Scope filter: only include suggestions from these scopes (lib, bin, test).
    /// Empty means include all scopes.
    #[serde(default)]
    pub scope_filter: Vec<String>,
}

/// A code improvement suggestion.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Suggestion {
    /// Unique identifier for the suggestion.
    pub id: String,
    /// Rule ID for @spec:allow directive (e.g., "RL001").
    pub rule_id: Option<String>,
    /// Human-readable title.
    pub title: String,
    /// Detailed description.
    pub description: String,
    /// Category (refactoring, performance, readability, etc.).
    pub category: String,
    /// Impact level (high, medium, low).
    pub impact: String,
    /// File where the suggestion applies.
    pub file: PathBuf,
    /// Symbol path for precise location (e.g., "crate::module::MyStruct").
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub symbol_path: Option<String>,
    /// The Intent that would fix this issue.
    pub fix_intent: Option<String>,
}

/// Summary of suggestions.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct SuggestionSummary {
    /// Total number of suggestions.
    pub total: usize,
    /// Number of high-impact suggestions.
    pub high_impact: usize,
    /// Categories with counts.
    pub by_category: Vec<(String, usize)>,
}

/// Response from suggestion engine.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct SuggestResponse {
    /// List of suggestions.
    pub suggestions: Vec<Suggestion>,
    /// Summary statistics.
    pub summary: SuggestionSummary,
    /// Enhanced suggestions (when request.enhanced = true).
    /// Contains design choices, verification status, and apply commands.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub enhanced: Vec<EnhancedSuggestion>,
}

// ============================================================================
// Suggest Apply
// ============================================================================

/// Request to apply suggestions by ID.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SuggestApplyRequest {
    /// Suggestion IDs to apply (e.g., ["S001g0", "S002g0"]).
    pub ids: Vec<String>,
    /// Skip actual execution (preview only).
    pub dry_run: bool,
    /// Verify syntax after mutations.
    pub check_syntax: bool,
    /// Specific design choice to apply (e.g., "A", "B").
    /// If None, uses the recommended choice.
    #[serde(default)]
    pub choice_id: Option<String>,
    /// Run full verification (cargo check) before applying.
    #[serde(default)]
    pub verify: bool,
}

impl SuggestApplyRequest {
    /// Create a new apply request with suggestion IDs.
    pub fn new(ids: Vec<String>) -> Self {
        Self {
            ids,
            dry_run: false,
            check_syntax: false,
            choice_id: None,
            verify: false,
        }
    }

    /// Enable dry-run mode.
    pub fn dry_run(mut self) -> Self {
        self.dry_run = true;
        self
    }

    /// Enable syntax checking.
    pub fn check_syntax(mut self) -> Self {
        self.check_syntax = true;
        self
    }

    /// Set a specific design choice to apply.
    pub fn choice(mut self, choice_id: impl Into<String>) -> Self {
        self.choice_id = Some(choice_id.into());
        self
    }

    /// Enable verification before applying.
    pub fn verify(mut self) -> Self {
        self.verify = true;
        self
    }
}

/// Response from applying suggestions.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct SuggestApplyResponse {
    /// Whether execution completed successfully.
    pub success: bool,
    /// Number of files modified.
    pub files_modified: usize,
    /// Total number of changes made.
    pub total_changes: usize,
    /// Paths of modified files.
    pub modified_files: Vec<PathBuf>,
    /// Suggestions that were successfully applied.
    pub applied_ids: Vec<String>,
    /// Suggestions that failed to apply (with error messages).
    pub failed: Vec<(String, String)>,
    /// Syntax errors found (if check_syntax enabled).
    pub syntax_errors: Vec<String>,
    /// Error message (if completely failed).
    pub error: Option<String>,
}

// ============================================================================
// Suggest Choices
// ============================================================================

/// Request to get design choices for a suggestion.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SuggestChoicesRequest {
    /// Suggestion ID (e.g., "S001g0").
    pub id: String,
}

impl SuggestChoicesRequest {
    /// Create a new choices request.
    pub fn new(id: impl Into<String>) -> Self {
        Self { id: id.into() }
    }
}

/// A design choice option.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DesignChoiceInfo {
    /// Choice ID (e.g., "A", "B").
    pub id: String,
    /// Short label for display.
    pub label: String,
    /// Human-readable title.
    pub title: String,
    /// Detailed description.
    pub description: String,
    /// Extensibility rating (1-3 stars).
    pub extensibility: u8,
    /// Performance rating (1-3 stars).
    pub performance: u8,
    /// Complexity rating (1-3 stars).
    pub complexity: u8,
    /// Whether this is a breaking change.
    pub breaking_change: bool,
    /// Number of files affected.
    pub affected_files: usize,
    /// Whether this is the recommended choice.
    pub recommended: bool,
}

/// Response with design choices for a suggestion.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct SuggestChoicesResponse {
    /// Suggestion ID.
    pub suggestion_id: String,
    /// Pattern name that generated these choices.
    pub pattern_name: String,
    /// Available choices.
    pub choices: Vec<DesignChoiceInfo>,
    /// Whether choices are available.
    pub has_choices: bool,
    /// Error message if failed.
    pub error: Option<String>,
}

// ============================================================================
// Suggest Verify
// ============================================================================

/// Verification level.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
pub enum VerifyLevel {
    /// Fast in-memory check (GraphChecker, ~100ms).
    #[default]
    Light,
    /// Full cargo check in temp workspace.
    Full,
}

/// Request to verify a suggestion before applying.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SuggestVerifyRequest {
    /// Suggestion ID (e.g., "S001g0").
    pub id: String,
    /// Specific choice to verify (if multiple choices exist).
    #[serde(default)]
    pub choice_id: Option<String>,
    /// Verification level.
    #[serde(default)]
    pub level: VerifyLevel,
}

impl SuggestVerifyRequest {
    /// Create a new verify request.
    pub fn new(id: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            choice_id: None,
            level: VerifyLevel::default(),
        }
    }

    /// Set a specific choice to verify.
    pub fn choice(mut self, choice_id: impl Into<String>) -> Self {
        self.choice_id = Some(choice_id.into());
        self
    }

    /// Set verification level.
    pub fn level(mut self, level: VerifyLevel) -> Self {
        self.level = level;
        self
    }
}

/// Response from verification.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct SuggestVerifyResponse {
    /// Suggestion ID.
    pub suggestion_id: String,
    /// Choice ID (if specified).
    pub choice_id: Option<String>,
    /// Whether verification passed.
    pub passed: bool,
    /// Verification level used.
    pub level: String,
    /// Duration in milliseconds.
    pub duration_ms: u64,
    /// Diagnostics (errors/warnings).
    pub diagnostics: Vec<String>,
    /// Error message if failed.
    pub error: Option<String>,
}

// ============================================================================
// Suggest Compare
// ============================================================================

/// Request to compare design choices.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SuggestCompareRequest {
    /// Suggestion ID (e.g., "S001g0").
    pub id: String,
}

impl SuggestCompareRequest {
    /// Create a new compare request.
    pub fn new(id: impl Into<String>) -> Self {
        Self { id: id.into() }
    }
}

/// Comparison result for choices.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct SuggestCompareResponse {
    /// Suggestion ID.
    pub suggestion_id: String,
    /// Formatted comparison table.
    pub comparison_table: String,
    /// Choices sorted by score (best first).
    pub ranked_choices: Vec<DesignChoiceInfo>,
    /// Recommendation reason.
    pub recommendation_reason: Option<String>,
    /// Error message if failed.
    pub error: Option<String>,
}

// ============================================================================
// Suggest Generate
// ============================================================================

/// Request to generate code from parameterized patterns.
///
/// Use `list: true` to discover available patterns.
/// Use `pattern` + `params` to generate code.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct SuggestGenerateRequest {
    /// Pattern name to use (e.g., "api-pattern", "domain-struct").
    pub pattern: Option<String>,
    /// Parameters for the pattern as key-value pairs.
    /// E.g., `{"name": "Order", "fields": "id:u64,status:String"}`.
    #[serde(default)]
    pub params: std::collections::HashMap<String, String>,
    /// List available parameterized patterns instead of generating.
    #[serde(default)]
    pub list: bool,
    /// Apply generated changes immediately (skip preview).
    #[serde(default)]
    pub apply: bool,
    /// Skip actual execution (preview only).
    #[serde(default)]
    pub dry_run: bool,
}

impl SuggestGenerateRequest {
    /// Create a request to list available patterns.
    pub fn list_patterns() -> Self {
        Self {
            list: true,
            ..Default::default()
        }
    }

    /// Create a request to generate from a pattern.
    pub fn generate(pattern: impl Into<String>) -> Self {
        Self {
            pattern: Some(pattern.into()),
            ..Default::default()
        }
    }

    /// Add a parameter.
    pub fn with_param(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.params.insert(key.into(), value.into());
        self
    }

    /// Set apply mode.
    pub fn apply(mut self) -> Self {
        self.apply = true;
        self
    }

    /// Set dry-run mode.
    pub fn dry_run(mut self) -> Self {
        self.dry_run = true;
        self
    }
}

/// Information about a parameterized pattern.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PatternInfo {
    /// Pattern name (e.g., "api-pattern").
    pub name: String,
    /// Human-readable description.
    pub description: String,
    /// Category (e.g., "Pattern").
    pub category: String,
    /// Parameters this pattern accepts.
    pub params: Vec<ParamInfo>,
}

/// Information about a pattern parameter.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ParamInfo {
    /// Parameter name (e.g., "name").
    pub name: String,
    /// Human-readable description.
    pub description: String,
    /// Whether this parameter is required.
    pub required: bool,
}

/// Response from code generation.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct SuggestGenerateResponse {
    /// Available patterns (when request.list = true).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub patterns: Vec<PatternInfo>,
    /// Generated suggestions (when pattern specified).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub suggestions: Vec<Suggestion>,
    /// Preview of changes (code diff).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub preview: Option<String>,
    /// Applied changes (when apply = true).
    #[serde(default)]
    pub applied: bool,
    /// Number of files modified (when apply = true).
    #[serde(default)]
    pub files_modified: usize,
    /// Error message if failed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
}

// ============================================================================
// Run (Execute)
// ============================================================================

/// Request for code transformation execution.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RunRequest {
    /// The goal to execute.
    pub goal: Goal,
    /// Skip actual execution (plan and validate only).
    pub dry_run: bool,
    /// Verify syntax after mutations.
    pub check_syntax: bool,
}

impl RunRequest {
    /// Create a new run request with a goal.
    pub fn new(goal: Goal) -> Self {
        Self {
            goal,
            dry_run: false,
            check_syntax: false,
        }
    }

    /// Enable dry-run mode.
    pub fn dry_run(mut self) -> Self {
        self.dry_run = true;
        self
    }

    /// Enable syntax checking.
    pub fn check_syntax(mut self) -> Self {
        self.check_syntax = true;
        self
    }
}

/// Response from code transformation execution.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct RunResponse {
    /// Whether execution completed successfully.
    pub success: bool,
    /// Number of files modified.
    pub files_modified: usize,
    /// Total number of changes made.
    pub total_changes: usize,
    /// Paths of modified files.
    pub modified_files: Vec<PathBuf>,
    /// Conflict descriptions (if any).
    pub conflicts: Vec<String>,
    /// Syntax errors found (if check_syntax enabled).
    pub syntax_errors: Vec<String>,
    /// Error message (if failed).
    pub error: Option<String>,
}

// ============================================================================
// Graph Cascade
// ============================================================================

/// Request for cascade analysis.
///
/// Use `ryo discover` to find the SymbolId or UUID.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CascadeRequest {
    /// SymbolId to analyze (e.g., "741v1").
    /// Get this from `ryo discover` output.
    /// **Warning**: Session-volatile. Prefer `uuid` for persistent references.
    pub id: String,
    /// Persistent UUID for cross-session symbol tracking.
    /// Takes precedence over `id` if provided.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uuid: Option<String>,
    /// Maximum depth to traverse (default: 3).
    pub depth: Option<usize>,
}

impl CascadeRequest {
    /// Create a new cascade request with SymbolId.
    pub fn new(id: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            uuid: None,
            depth: None,
        }
    }

    /// Create a new cascade request with UUID.
    pub fn with_uuid(uuid: impl Into<String>) -> Self {
        Self {
            id: String::new(),
            uuid: Some(uuid.into()),
            depth: None,
        }
    }

    /// Set the traversal depth.
    pub fn depth(mut self, depth: usize) -> Self {
        self.depth = Some(depth);
        self
    }
}

/// Response from cascade analysis.
///
/// For detailed type impact analysis, use `graph type` instead.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CascadeResponse {
    /// Display name of the target symbol.
    pub display_name: String,
    /// Functions/methods that call the target.
    pub callers: Vec<String>,
    /// Types/functions that use the target as a type reference.
    pub users: Vec<String>,
    /// Functions containing match expressions on this enum.
    /// Only populated when the target is an Enum.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub match_functions: Vec<String>,
    /// Types that contain this type as a field.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub containing_types: Vec<String>,
}

// ============================================================================
// Graph Summary
// ============================================================================

/// Request for code graph summary.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct GraphSummaryRequest {
    /// Detailed output with file paths and type breakdown.
    #[serde(default)]
    pub detailed: bool,
    /// Compact output for minimal display.
    #[serde(default)]
    pub compact: bool,
    /// Maximum items per section.
    #[serde(default)]
    pub max_items: Option<usize>,
}

impl GraphSummaryRequest {
    /// Create a new default request.
    pub fn new() -> Self {
        Self::default()
    }

    /// Enable detailed output.
    pub fn detailed(mut self) -> Self {
        self.detailed = true;
        self
    }

    /// Enable compact output.
    pub fn compact(mut self) -> Self {
        self.compact = true;
        self
    }

    /// Set max items per section.
    pub fn max_items(mut self, n: usize) -> Self {
        self.max_items = Some(n);
        self
    }
}

/// Response from code graph summary.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GraphSummaryResponse {
    /// Formatted summary content (ready to print).
    pub content: String,
    /// Build time in milliseconds.
    pub build_time_ms: u64,
    /// Number of nodes in the graph.
    pub node_count: usize,
    /// Number of edges in the graph.
    pub edge_count: usize,
    /// Number of files analyzed.
    pub file_count: usize,
}

// ============================================================================
// Ping
// ============================================================================

/// Response from ping (health check with version).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PingResponse {
    /// Server version (from Cargo.toml).
    pub version: String,
}

// ============================================================================
// Status
// ============================================================================

/// Response from status query.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StatusResponse {
    /// Project root path.
    pub project: PathBuf,
    /// Number of symbols in registry.
    pub symbols: usize,
    /// Number of files loaded.
    pub files: usize,
}

// ============================================================================
// Error Types (for RPC transport)
// ============================================================================

/// Structured error type for API responses.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ApiErrorKind {
    /// Symbol or resource not found.
    NotFound { name: String },
    /// Parse or syntax error.
    ParseError { message: String },
    /// Invalid request parameters.
    InvalidRequest { message: String },
    /// Internal server error.
    Internal { message: String },
}

impl std::fmt::Display for ApiErrorKind {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::NotFound { name } => write!(f, "not found: {}", name),
            Self::ParseError { message } => write!(f, "parse error: {}", message),
            Self::InvalidRequest { message } => write!(f, "invalid request: {}", message),
            Self::Internal { message } => write!(f, "internal error: {}", message),
        }
    }
}

impl std::error::Error for ApiErrorKind {}

// ============================================================================
// Spec
// ============================================================================

/// Request for spec hierarchy query.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpecRequest {
    /// Query kind.
    pub query: SpecQueryKind,
}

/// Spec query kinds.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum SpecQueryKind {
    /// Show full hierarchy (groups, relations, stats).
    Show,
    /// List all group names.
    Groups,
    /// List specs in a specific group.
    TypesInGroup { group: String },
    /// Get dependencies of a spec.
    Dependencies { type_name: String },
    /// Get dependents (reverse dependencies) of a spec.
    Dependents { type_name: String },
    /// Get statistics.
    Stats,
    /// Lint specs for consistency.
    Lint,
    /// Generate Mermaid diagram.
    Mermaid,
}

impl SpecRequest {
    /// Create a show request.
    pub fn show() -> Self {
        Self {
            query: SpecQueryKind::Show,
        }
    }

    /// Create a groups request.
    pub fn groups() -> Self {
        Self {
            query: SpecQueryKind::Groups,
        }
    }

    /// Create a types-in-group request.
    pub fn types_in_group(group: impl Into<String>) -> Self {
        Self {
            query: SpecQueryKind::TypesInGroup {
                group: group.into(),
            },
        }
    }

    /// Create a stats request.
    pub fn stats() -> Self {
        Self {
            query: SpecQueryKind::Stats,
        }
    }

    /// Create a lint request.
    pub fn lint() -> Self {
        Self {
            query: SpecQueryKind::Lint,
        }
    }

    /// Create a mermaid request.
    pub fn mermaid() -> Self {
        Self {
            query: SpecQueryKind::Mermaid,
        }
    }
}

/// Response from spec query.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum SpecResponse {
    /// Full hierarchy response.
    Show(SpecShowData),
    /// List of group names.
    Groups(Vec<String>),
    /// List of specs in a group.
    TypesInGroup(Vec<SpecInfoData>),
    /// Dependency list.
    Dependencies(Vec<String>),
    /// Dependent list.
    Dependents(Vec<String>),
    /// Statistics.
    Stats(SpecStatsData),
    /// Lint result.
    Lint(SpecLintData),
    /// Mermaid diagram.
    Mermaid(String),
}

/// Full spec hierarchy data.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpecShowData {
    /// All groups with their specs.
    pub groups: Vec<SpecGroupData>,
    /// All dependency relations.
    pub relations: Vec<SpecRelationData>,
    /// Statistics.
    pub stats: SpecStatsData,
}

/// Group information.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpecGroupData {
    /// Group name.
    pub name: String,
    /// Specs in this group.
    pub specs: Vec<SpecInfoData>,
}

/// Spec information.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpecInfoData {
    /// Alias name (e.g., "DbConfig").
    pub alias_name: String,
    /// Wrapped type name (e.g., "DatabaseConfig").
    pub wrapped_type_name: String,
    /// Source kind.
    pub source: String,
}

/// Spec relation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpecRelationData {
    /// Source spec name.
    pub from: String,
    /// Target spec name.
    pub to: String,
    /// Relation kind.
    pub kind: String,
}

/// Statistics.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpecStatsData {
    /// Number of groups.
    pub groups: usize,
    /// Number of specs.
    pub specs: usize,
    /// Total node count.
    pub nodes: usize,
    /// Total edge count.
    pub edges: usize,
}

/// Lint result data.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpecLintData {
    /// All issues found.
    pub issues: Vec<SpecLintIssueData>,
    /// Number of warnings.
    pub warnings: usize,
    /// Number of errors.
    pub errors: usize,
}

/// Lint issue data.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpecLintIssueData {
    /// Severity ("warning" or "error").
    pub severity: String,
    /// Issue message.
    pub message: String,
    /// Optional location.
    pub location: Option<String>,
}

// ============================================================================
// Graph Type Analysis
// ============================================================================

/// Analysis mode for type relationships.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
pub enum TypeAnalysisMode {
    /// Show type definition details.
    Definition,
    /// Show all usages of this type.
    Usage,
    /// Show impact of changing this type.
    #[default]
    Impact,
}

/// Request for type analysis.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypeAnalysisRequest {
    /// Type name to analyze (used if id/uuid not provided).
    #[serde(default)]
    pub name: Option<String>,
    /// SymbolId to analyze directly (e.g., "165v1").
    /// **Warning**: Session-volatile. Prefer `uuid` for persistent references.
    #[serde(default)]
    pub id: Option<String>,
    /// Persistent UUID for cross-session symbol tracking.
    /// Takes precedence over `id` and `name` if provided.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uuid: Option<String>,
    /// Analysis mode.
    #[serde(default)]
    pub mode: TypeAnalysisMode,
    /// Maximum depth for traversal.
    #[serde(default)]
    pub depth: Option<usize>,
}

impl TypeAnalysisRequest {
    /// Create a new type analysis request by name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: Some(name.into()),
            id: None,
            uuid: None,
            mode: TypeAnalysisMode::default(),
            depth: None,
        }
    }

    /// Create a new type analysis request by SymbolId.
    pub fn with_id(id: impl Into<String>) -> Self {
        Self {
            name: None,
            id: Some(id.into()),
            uuid: None,
            mode: TypeAnalysisMode::default(),
            depth: None,
        }
    }

    /// Create a new type analysis request by UUID.
    pub fn with_uuid(uuid: impl Into<String>) -> Self {
        Self {
            name: None,
            id: None,
            uuid: Some(uuid.into()),
            mode: TypeAnalysisMode::default(),
            depth: None,
        }
    }

    /// Set the analysis mode.
    pub fn mode(mut self, mode: TypeAnalysisMode) -> Self {
        self.mode = mode;
        self
    }
}

/// Response from type analysis.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypeAnalysisResponse {
    /// Symbol ID string.
    pub symbol_id: String,
    /// Display name.
    pub display_name: String,
    /// Module path.
    pub mod_path: Option<String>,
    /// Kind (Struct, Enum, etc.).
    pub kind: Option<String>,
    /// Usage count.
    pub usage_count: usize,
    /// Usages (context, ref_kind). Populated for Usage/Impact modes.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub usages: Vec<TypeUsageInfo>,
    /// Impact info (direct usages, bound usages, containing types). Populated for Impact mode.
    pub impact: Option<TypeImpactInfo>,
    /// Supertraits (for traits only): parent traits from `trait Foo: Bar + Baz`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub supertraits: Vec<String>,
    /// Implementors (for traits only): types that implement this trait.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub implementors: Vec<String>,
    /// Struct/enum fields. Populated for Definition mode.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub fields: Vec<TypeFieldInfo>,
    /// Enum variants. Populated for Definition mode.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub variants: Vec<TypeVariantInfo>,
    /// Function parameters. Populated for Definition mode.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub params: Vec<TypeParamInfo>,
    /// Function return type. Populated for Definition mode.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub return_type: Option<String>,
    /// Trait method names. Populated for Definition mode.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub methods: Vec<String>,
    /// Generic parameters string (e.g. "<T, U: Clone>"). Populated for Definition mode.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub generics: Option<String>,
    /// Attributes (e.g. ["derive", "serde"]). Populated for Definition mode.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub attrs: Vec<String>,
}

/// Field information for definition mode.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypeFieldInfo {
    /// Field name.
    pub name: String,
    /// Type as string.
    pub ty: String,
    /// Is publicly visible.
    pub is_public: bool,
}

/// Enum variant information for definition mode.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypeVariantInfo {
    /// Variant name.
    pub name: String,
    /// Fields of this variant.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub fields: Vec<TypeFieldInfo>,
}

/// Parameter information for definition mode.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypeParamInfo {
    /// Parameter name.
    pub name: String,
    /// Type as string.
    pub ty: String,
}

/// Type usage information.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypeUsageInfo {
    /// Usage context.
    pub context: String,
    /// Reference kind.
    pub ref_kind: String,
    /// Container symbol path (the function/struct that uses this type).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub container: Option<String>,
}

/// Type impact information.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypeImpactInfo {
    /// Direct usage count.
    pub direct_usages: usize,
    /// Bound usage count.
    pub bound_usages: usize,
    /// Containing types.
    pub containing_types: Vec<String>,
}

// ============================================================================
// Graph Flow Analysis
// ============================================================================

/// Analysis mode for data flow.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
pub enum FlowAnalysisMode {
    /// Track where values come from.
    Provenance,
    /// Track where values flow to.
    Impact,
    /// Full chain analysis (provenance + impact).
    #[default]
    Chain,
    /// Find data sources.
    Sources,
    /// Find data sinks.
    Sinks,
}

/// Request for flow analysis.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlowAnalysisRequest {
    /// Variable name to analyze (used if id/uuid not provided).
    #[serde(default)]
    pub name: Option<String>,
    /// SymbolId to analyze directly (e.g., "165v1").
    /// **Warning**: Session-volatile. Prefer `uuid` for persistent references.
    #[serde(default)]
    pub id: Option<String>,
    /// Persistent UUID for cross-session symbol tracking.
    /// Takes precedence over `id` and `name` if provided.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uuid: Option<String>,
    /// Analysis mode.
    #[serde(default)]
    pub mode: FlowAnalysisMode,
    /// Maximum depth for traversal.
    #[serde(default)]
    pub depth: Option<usize>,
}

impl FlowAnalysisRequest {
    /// Create a new flow analysis request by name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: Some(name.into()),
            id: None,
            uuid: None,
            mode: FlowAnalysisMode::default(),
            depth: None,
        }
    }

    /// Create a new flow analysis request by SymbolId.
    pub fn with_id(id: impl Into<String>) -> Self {
        Self {
            name: None,
            id: Some(id.into()),
            uuid: None,
            mode: FlowAnalysisMode::default(),
            depth: None,
        }
    }

    /// Create a new flow analysis request by UUID.
    pub fn with_uuid(uuid: impl Into<String>) -> Self {
        Self {
            name: None,
            id: None,
            uuid: Some(uuid.into()),
            mode: FlowAnalysisMode::default(),
            depth: None,
        }
    }
}

/// Variable information.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VarInfo {
    /// Variable name.
    pub name: String,
    /// Variable kind.
    pub kind: String,
    /// Parent function.
    pub parent: String,
    /// Symbol path.
    pub symbol_path: Option<String>,
}

/// Response from flow analysis.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlowAnalysisResponse {
    /// Display name.
    pub display_name: String,
    /// Found variables.
    pub found_vars: Vec<VarInfo>,
    /// Provenance (sources).
    pub provenance: Vec<VarInfo>,
    /// Impact (targets).
    pub impact: Vec<VarInfo>,
    /// Sources (data origins).
    pub sources: Vec<VarInfo>,
    /// Sinks (data destinations).
    pub sinks: Vec<VarInfo>,
}

// ============================================================================
// Graph Borrow Analysis
// ============================================================================

/// Request for borrow analysis.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BorrowAnalysisRequest {
    /// Variable name to analyze (used if id/uuid not provided).
    #[serde(default)]
    pub name: Option<String>,
    /// SymbolId to analyze directly (e.g., "165v1").
    /// **Warning**: Session-volatile. Prefer `uuid` for persistent references.
    #[serde(default)]
    pub id: Option<String>,
    /// Persistent UUID for cross-session symbol tracking.
    /// Takes precedence over `id` and `name` if provided.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uuid: Option<String>,
    /// Show only conflicts.
    #[serde(default)]
    pub conflicts_only: bool,
}

impl BorrowAnalysisRequest {
    /// Create a new borrow analysis request by name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: Some(name.into()),
            id: None,
            uuid: None,
            conflicts_only: false,
        }
    }

    /// Create a new borrow analysis request by SymbolId.
    pub fn with_id(id: impl Into<String>) -> Self {
        Self {
            name: None,
            id: Some(id.into()),
            uuid: None,
            conflicts_only: false,
        }
    }

    /// Create a new borrow analysis request by UUID.
    pub fn with_uuid(uuid: impl Into<String>) -> Self {
        Self {
            name: None,
            id: None,
            uuid: Some(uuid.into()),
            conflicts_only: false,
        }
    }
}

/// Borrow status for a variable.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BorrowStatus {
    /// Variable name.
    pub var_name: String,
    /// Line number.
    pub line: u32,
    /// Parent function.
    pub parent_info: String,
    /// Has conflict.
    pub has_conflict: bool,
    /// Conflict errors.
    pub errors: Vec<String>,
}

/// Response from borrow analysis.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BorrowAnalysisResponse {
    /// Display name.
    pub display_name: String,
    /// Found variables count.
    pub found_count: usize,
    /// Borrow statuses.
    pub statuses: Vec<BorrowStatus>,
}

// ============================================================================
// Graph Lock Analysis
// ============================================================================

/// Request for lock analysis.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LockAnalysisRequest {
    /// Lock name pattern (used if id/uuid not provided).
    #[serde(default)]
    pub name: Option<String>,
    /// SymbolId to analyze directly (e.g., "165v1").
    /// **Warning**: Session-volatile. Prefer `uuid` for persistent references.
    #[serde(default)]
    pub id: Option<String>,
    /// Persistent UUID for cross-session symbol tracking.
    /// Takes precedence over `id` and `name` if provided.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uuid: Option<String>,
    /// Show optimization suggestions.
    #[serde(default)]
    pub suggest: bool,
}

impl LockAnalysisRequest {
    /// Create a new lock analysis request by name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: Some(name.into()),
            id: None,
            uuid: None,
            suggest: false,
        }
    }

    /// Create a new lock analysis request by SymbolId.
    pub fn with_id(id: impl Into<String>) -> Self {
        Self {
            name: None,
            id: Some(id.into()),
            uuid: None,
            suggest: false,
        }
    }

    /// Create a new lock analysis request by UUID.
    pub fn with_uuid(uuid: impl Into<String>) -> Self {
        Self {
            name: None,
            id: None,
            uuid: Some(uuid.into()),
            suggest: false,
        }
    }
}

/// Lock statistics.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LockStats {
    /// Total locks.
    pub total_locks: u32,
    /// Mutex count.
    pub mutex_count: u32,
    /// RwLock count.
    pub rwlock_count: u32,
    /// RefCell count.
    pub refcell_count: u32,
    /// Total field accesses.
    pub total_field_accesses: u32,
    /// Max critical section span.
    pub max_cs_span: u32,
}

/// Lock acquisition info.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LockAcquisition {
    /// Lock name.
    pub lock_name: String,
    /// Lock type.
    pub lock_type: String,
    /// Line number.
    pub line: u32,
}

/// Lock suggestion.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LockSuggestionInfo {
    /// Suggestion kind.
    pub kind: String,
    /// Target name.
    pub target: String,
    /// Description.
    pub description: String,
    /// Line number.
    pub line: u32,
}

/// Response from lock analysis.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LockAnalysisResponse {
    /// Display name.
    pub display_name: String,
    /// Lock statistics.
    pub stats: LockStats,
    /// Matching acquisitions.
    pub acquisitions: Vec<LockAcquisition>,
    /// Suggestions (if requested).
    pub suggestions: Vec<LockSuggestionInfo>,
}

// ============================================================================
// Graph Chain Analysis (Transitive Call Chain)
// ============================================================================

/// Traversal mode for chain analysis.
///
/// - `Callers`/`Callees`: Call chain traversal (CodeGraphV2)
/// - `TypeUsers`/`TypeDeps`: Type reference chain traversal (TypeFlowGraphV2)
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
pub enum ChainMode {
    /// Follow incoming call edges (who calls this function?)
    #[default]
    Callers,
    /// Follow outgoing call edges (what does this function call?)
    Callees,
    /// Follow type reference edges: who uses this type? (type → containers)
    TypeUsers,
    /// Follow type reference edges: what types does this use? (container → types)
    TypeDeps,
}

impl std::fmt::Display for ChainMode {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ChainMode::Callers => write!(f, "callers"),
            ChainMode::Callees => write!(f, "callees"),
            ChainMode::TypeUsers => write!(f, "type_users"),
            ChainMode::TypeDeps => write!(f, "type_deps"),
        }
    }
}

/// Request for chain analysis.
///
/// Traverses call relationships transitively to find all callers or callees
/// up to a specified depth.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChainAnalysisRequest {
    /// SymbolId to analyze (e.g., "165v1").
    /// Get this from `ryo discover` output.
    /// **Warning**: Session-volatile. Prefer `uuid` for persistent references.
    pub id: String,
    /// Persistent UUID for cross-session symbol tracking.
    /// Takes precedence over `id` if provided.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uuid: Option<String>,
    /// Traversal mode.
    #[serde(default)]
    pub mode: ChainMode,
    /// Maximum traversal depth (default: 5).
    #[serde(default)]
    pub depth: Option<usize>,
}

impl ChainAnalysisRequest {
    /// Create a new chain analysis request with SymbolId.
    pub fn new(id: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            uuid: None,
            mode: ChainMode::default(),
            depth: None,
        }
    }

    /// Create a new chain analysis request with UUID.
    pub fn with_uuid(uuid: impl Into<String>) -> Self {
        Self {
            id: String::new(),
            uuid: Some(uuid.into()),
            mode: ChainMode::default(),
            depth: None,
        }
    }

    /// Set the traversal mode.
    pub fn mode(mut self, mode: ChainMode) -> Self {
        self.mode = mode;
        self
    }

    /// Set the traversal depth.
    pub fn depth(mut self, depth: usize) -> Self {
        self.depth = Some(depth);
        self
    }
}

/// A node in the chain with depth information.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChainNodeInfo {
    /// SymbolId as string.
    pub id: String,
    /// Full symbol path.
    pub path: String,
    /// Symbol kind (Function, Struct, etc.).
    pub kind: Option<String>,
    /// Depth from starting symbol.
    pub depth: usize,
}

/// Response from chain analysis.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ChainAnalysisResponse {
    /// Display name of the starting symbol.
    pub display_name: String,
    /// Traversal direction used.
    pub direction: String,
    /// Total count of nodes in the chain.
    pub total_count: usize,
    /// Maximum depth actually reached.
    pub max_actual_depth: usize,
    /// Nodes grouped by depth level.
    pub by_depth: std::collections::BTreeMap<usize, Vec<ChainNodeInfo>>,
}