ryo-analysis 0.1.0

//! AI-readable output traits for graph structures
//!
//! This module provides traits for generating structured output that is:
//! - **AI-readable**: Clear, unambiguous format that LLMs can parse reliably
//! - **Human-readable**: Also useful for developers reviewing analysis results

/// Options for customizing summary output
#[derive(Debug, Clone, Default)]
pub struct SummaryOptions {
    /// Filter to specific scope (function name, module, etc.)
    pub scope: Option<String>,

    /// Maximum depth for hierarchical structures
    pub max_depth: Option<usize>,

    /// Include detailed statistics
    pub include_stats: bool,

    /// Include file paths and line numbers
    pub include_locations: bool,

    /// Compact mode (less whitespace, shorter labels)
    pub compact: bool,
}

impl SummaryOptions {
    /// Create options with all details included
    pub fn detailed() -> Self {
        Self {
            include_stats: true,
            include_locations: true,
            ..Default::default()
        }
    }

    /// Create compact options for minimal output
    pub fn compact() -> Self {
        Self {
            compact: true,
            include_locations: false,
            include_stats: false,
            ..Default::default()
        }
    }

    /// Filter to a specific scope
    pub fn with_scope(mut self, scope: impl Into<String>) -> Self {
        self.scope = Some(scope.into());
        self
    }

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

/// Generate AI-readable structured text summary
///
/// This trait provides a standardized way to convert graph structures into
/// text format optimized for LLM comprehension.
///
/// # Output Format Guidelines
///
/// Implementations should follow these conventions:
///
/// 1. **Section Headers**: Use `=== Title ===` for main sections
/// 2. **Subsections**: Use `[Subsection]` with indented content
/// 3. **Relationships**: Use `--kind-->` arrows (e.g., `a --assign--> b`)
/// 4. **Node Types**: Use `(type)` suffix (e.g., `var1 (param)`)
/// 5. **Locations**: Use `@ file:line` suffix when relevant
/// 6. **Lists**: Use consistent indentation (2 spaces)
pub trait ToSummary {
    /// Generate a structured text summary with default options
    fn to_summary(&self) -> String {
        self.to_summary_with_options(&SummaryOptions::default())
    }

    /// Generate a structured text summary with custom options
    fn to_summary_with_options(&self, opts: &SummaryOptions) -> String;
}