ryo_analysis/
summary.rs

1//! AI-readable output traits for graph structures
2//!
3//! This module provides traits for generating structured output that is:
4//! - **AI-readable**: Clear, unambiguous format that LLMs can parse reliably
5//! - **Human-readable**: Also useful for developers reviewing analysis results
6
7/// Options for customizing summary output
8#[derive(Debug, Clone, Default)]
9pub struct SummaryOptions {
10    /// Filter to specific scope (function name, module, etc.)
11    pub scope: Option<String>,
12
13    /// Maximum depth for hierarchical structures
14    pub max_depth: Option<usize>,
15
16    /// Include detailed statistics
17    pub include_stats: bool,
18
19    /// Include file paths and line numbers
20    pub include_locations: bool,
21
22    /// Compact mode (less whitespace, shorter labels)
23    pub compact: bool,
24}
25
26impl SummaryOptions {
27    /// Create options with all details included
28    pub fn detailed() -> Self {
29        Self {
30            include_stats: true,
31            include_locations: true,
32            ..Default::default()
33        }
34    }
35
36    /// Create compact options for minimal output
37    pub fn compact() -> Self {
38        Self {
39            compact: true,
40            include_locations: false,
41            include_stats: false,
42            ..Default::default()
43        }
44    }
45
46    /// Filter to a specific scope
47    pub fn with_scope(mut self, scope: impl Into<String>) -> Self {
48        self.scope = Some(scope.into());
49        self
50    }
51
52    /// Set maximum depth
53    pub fn with_max_depth(mut self, depth: usize) -> Self {
54        self.max_depth = Some(depth);
55        self
56    }
57}
58
59/// Generate AI-readable structured text summary
60///
61/// This trait provides a standardized way to convert graph structures into
62/// text format optimized for LLM comprehension.
63///
64/// # Output Format Guidelines
65///
66/// Implementations should follow these conventions:
67///
68/// 1. **Section Headers**: Use `=== Title ===` for main sections
69/// 2. **Subsections**: Use `[Subsection]` with indented content
70/// 3. **Relationships**: Use `--kind-->` arrows (e.g., `a --assign--> b`)
71/// 4. **Node Types**: Use `(type)` suffix (e.g., `var1 (param)`)
72/// 5. **Locations**: Use `@ file:line` suffix when relevant
73/// 6. **Lists**: Use consistent indentation (2 spaces)
74pub trait ToSummary {
75    /// Generate a structured text summary with default options
76    fn to_summary(&self) -> String {
77        self.to_summary_with_options(&SummaryOptions::default())
78    }
79
80    /// Generate a structured text summary with custom options
81    fn to_summary_with_options(&self, opts: &SummaryOptions) -> String;
82}
ryo_analysis/summary.rs

ryo_analysis/
summary.rs
