reflex/pulse/
onboard.rs

1//! Onboard Guide: "Getting Started" page for developer onboarding
2//!
3//! Identifies entry points (main files, CLI handlers, API routes),
4//! suggests a reading order via dependency topology, and provides
5//! structural context for LLM narration.
6
7use anyhow::{Context, Result};
8use rusqlite::Connection;
9use rusqlite::OptionalExtension;
10use std::collections::{HashMap, HashSet, VecDeque};
11use std::path::Path;
12
13use crate::cache::CacheManager;
14use crate::models::{SearchResult, SymbolKind};
15
16/// Kind of entry point detected
17#[derive(Debug, Clone, PartialEq, Eq, Hash)]
18pub enum EntryPointKind {
19    CliBinary,
20    HttpServer,
21    Library,
22    Script,
23    TestRunner,
24}
25
26impl std::fmt::Display for EntryPointKind {
27    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
28        match self {
29            EntryPointKind::CliBinary => write!(f, "CLI Binary"),
30            EntryPointKind::HttpServer => write!(f, "HTTP Server"),
31            EntryPointKind::Library => write!(f, "Library"),
32            EntryPointKind::Script => write!(f, "Script"),
33            EntryPointKind::TestRunner => write!(f, "Test Runner"),
34        }
35    }
36}
37
38/// A detected entry point in the codebase
39#[derive(Debug, Clone)]
40pub struct EntryPoint {
41    pub path: String,
42    pub kind: EntryPointKind,
43    pub key_symbols: Vec<String>,
44}
45
46/// A layer in the reading order (BFS from entry points)
47#[derive(Debug, Clone)]
48pub struct ReadingLayer {
49    pub depth: usize,
50    pub label: String,
51    pub files: Vec<String>,
52}
53
54/// Complete reading order computed via BFS from entry points
55#[derive(Debug, Clone)]
56pub struct ReadingOrder {
57    pub layers: Vec<ReadingLayer>,
58}
59
60/// Full onboard data
61#[derive(Debug, Clone)]
62pub struct OnboardData {
63    pub entry_points: Vec<EntryPoint>,
64    pub reading_order: ReadingOrder,
65    pub project_stats: ProjectStats,
66    pub narration: Option<String>,
67}
68
69/// Quick stats for the onboard page
70#[derive(Debug, Clone)]
71pub struct ProjectStats {
72    pub total_files: usize,
73    pub total_lines: usize,
74    pub languages: Vec<(String, usize)>,
75    pub module_count: usize,
76}
77
78/// Detect entry points by matching well-known file patterns and names
79pub fn detect_entry_points(cache: &CacheManager) -> Result<Vec<EntryPoint>> {
80    let db_path = cache.path().join("meta.db");
81    let conn = Connection::open(&db_path).context("Failed to open meta.db")?;
82
83    // Get all file paths
84    let mut stmt = conn.prepare("SELECT path FROM files ORDER BY path")?;
85    let paths: Vec<String> = stmt
86        .query_map([], |row| row.get(0))?
87        .filter_map(|r| r.ok())
88        .collect();
89
90    let mut entry_points = Vec::new();
91    let mut seen_paths = HashSet::new();
92
93    for path in &paths {
94        let filename = Path::new(path)
95            .file_name()
96            .and_then(|f| f.to_str())
97            .unwrap_or("");
98        let lower = filename.to_lowercase();
99
100        // CLI binary entry points
101        if matches!(
102            filename,
103            "main.rs" | "main.go" | "main.py" | "main.c" | "main.cpp" | "main.zig"
104        ) || (filename == "cli.rs"
105            || filename == "cli.ts"
106            || filename == "cli.py"
107            || filename == "cli.js")
108        {
109            if seen_paths.insert(path.clone()) {
110                let kind = EntryPointKind::CliBinary;
111                let symbols = extract_key_symbols_for_entry(&conn, path);
112                entry_points.push(EntryPoint {
113                    path: path.clone(),
114                    kind,
115                    key_symbols: symbols,
116                });
117            }
118            continue;
119        }
120
121        // HTTP server entry points
122        if matches!(
123            filename,
124            "server.rs"
125                | "server.ts"
126                | "server.js"
127                | "server.py"
128                | "server.go"
129                | "app.rs"
130                | "app.ts"
131                | "app.js"
132                | "app.py"
133                | "app.go"
134                | "routes.rs"
135                | "routes.ts"
136                | "routes.js"
137                | "routes.py"
138        ) {
139            if seen_paths.insert(path.clone()) {
140                let symbols = extract_key_symbols_for_entry(&conn, path);
141                entry_points.push(EntryPoint {
142                    path: path.clone(),
143                    kind: EntryPointKind::HttpServer,
144                    key_symbols: symbols,
145                });
146            }
147            continue;
148        }
149
150        // Library entry points
151        if matches!(
152            filename,
153            "lib.rs" | "mod.rs" | "index.ts" | "index.js" | "__init__.py" | "mod.go"
154        ) {
155            // Only include top-level or shallow lib/index files, not deeply nested ones
156            let depth = path.matches('/').count();
157            if depth <= 2 && seen_paths.insert(path.clone()) {
158                let symbols = extract_key_symbols_for_entry(&conn, path);
159                entry_points.push(EntryPoint {
160                    path: path.clone(),
161                    kind: EntryPointKind::Library,
162                    key_symbols: symbols,
163                });
164            }
165            continue;
166        }
167
168        // Script entry points (package.json scripts, Makefile, etc.)
169        if matches!(
170            filename,
171            "Makefile" | "Rakefile" | "Taskfile.yml" | "justfile"
172        ) {
173            if seen_paths.insert(path.clone()) {
174                entry_points.push(EntryPoint {
175                    path: path.clone(),
176                    kind: EntryPointKind::Script,
177                    key_symbols: vec![],
178                });
179            }
180            continue;
181        }
182
183        // Test runners
184        if matches!(
185            lower.as_str(),
186            "conftest.py"
187                | "jest.config.js"
188                | "jest.config.ts"
189                | "vitest.config.ts"
190                | "vitest.config.js"
191                | "pytest.ini"
192                | "setup.cfg"
193        ) && path.matches('/').count() <= 1
194            && seen_paths.insert(path.clone())
195        {
196            entry_points.push(EntryPoint {
197                path: path.clone(),
198                kind: EntryPointKind::TestRunner,
199                key_symbols: vec![],
200            });
201        }
202    }
203
204    // Sort: CLI first, then HTTP, then Library, then others
205    entry_points.sort_by_key(|ep| match ep.kind {
206        EntryPointKind::CliBinary => 0,
207        EntryPointKind::HttpServer => 1,
208        EntryPointKind::Library => 2,
209        EntryPointKind::Script => 3,
210        EntryPointKind::TestRunner => 4,
211    });
212
213    Ok(entry_points)
214}
215
216/// Extract key symbol names for an entry point file from the symbol cache.
217///
218/// Queries the `symbols` table which stores all symbols for a file as a
219/// serialized JSON blob (`symbols_json` column containing `Vec<SearchResult>`).
220fn extract_key_symbols_for_entry(conn: &Connection, path: &str) -> Vec<String> {
221    // Get file_id
222    let file_id: Option<i64> = conn
223        .query_row("SELECT id FROM files WHERE path = ?1", [path], |row| {
224            row.get(0)
225        })
226        .ok();
227
228    let Some(file_id) = file_id else {
229        return vec![];
230    };
231
232    // Query the symbols table for this file's serialized symbols
233    let symbols_json: Option<String> = conn
234        .query_row(
235            "SELECT symbols_json FROM symbols WHERE file_id = ?1",
236            [file_id],
237            |row| row.get(0),
238        )
239        .optional()
240        .ok()
241        .flatten();
242
243    let Some(json) = symbols_json else {
244        return vec![];
245    };
246
247    // Deserialize and filter to key symbol kinds
248    let symbols: Vec<SearchResult> = match serde_json::from_str(&json) {
249        Ok(s) => s,
250        Err(_) => return vec![],
251    };
252
253    symbols
254        .iter()
255        .filter(|sr| {
256            matches!(
257                sr.kind,
258                SymbolKind::Function
259                    | SymbolKind::Struct
260                    | SymbolKind::Class
261                    | SymbolKind::Trait
262                    | SymbolKind::Interface
263            )
264        })
265        .filter_map(|sr| sr.symbol.clone())
266        .take(8)
267        .collect()
268}
269
270/// Compute reading order via BFS from entry points through the dependency graph
271pub fn compute_reading_order(
272    cache: &CacheManager,
273    entry_points: &[EntryPoint],
274) -> Result<ReadingOrder> {
275    let db_path = cache.path().join("meta.db");
276    let conn = Connection::open(&db_path)?;
277
278    // Build adjacency list: file_id -> [dependent file_ids]
279    // We traverse in the direction entry_point -> its dependencies
280    let mut deps: HashMap<i64, Vec<i64>> = HashMap::new();
281    let mut path_to_id: HashMap<String, i64> = HashMap::new();
282    let mut id_to_path: HashMap<i64, String> = HashMap::new();
283
284    // Load file id mappings
285    let mut stmt = conn.prepare("SELECT id, path FROM files")?;
286    let rows = stmt.query_map([], |row| {
287        Ok((row.get::<_, i64>(0)?, row.get::<_, String>(1)?))
288    })?;
289    for row in rows.flatten() {
290        path_to_id.insert(row.1.clone(), row.0);
291        id_to_path.insert(row.0, row.1);
292    }
293
294    // Load dependency edges (file -> its dependency)
295    let mut stmt = conn.prepare(
296        "SELECT file_id, resolved_file_id FROM file_dependencies WHERE resolved_file_id IS NOT NULL"
297    )?;
298    let edges = stmt.query_map([], |row| Ok((row.get::<_, i64>(0)?, row.get::<_, i64>(1)?)))?;
299    for edge in edges.flatten() {
300        deps.entry(edge.0).or_default().push(edge.1);
301    }
302
303    // BFS from entry points
304    let mut visited: HashSet<i64> = HashSet::new();
305    let mut queue: VecDeque<(i64, usize)> = VecDeque::new();
306    let mut layers_map: HashMap<usize, Vec<String>> = HashMap::new();
307
308    for ep in entry_points {
309        if let Some(&file_id) = path_to_id.get(&ep.path)
310            && visited.insert(file_id)
311        {
312            queue.push_back((file_id, 0));
313        }
314    }
315
316    while let Some((file_id, depth)) = queue.pop_front() {
317        if depth > 5 {
318            continue;
319        } // Cap depth to keep reading order manageable
320
321        if let Some(path) = id_to_path.get(&file_id) {
322            layers_map.entry(depth).or_default().push(path.clone());
323        }
324
325        if let Some(dep_ids) = deps.get(&file_id) {
326            for &dep_id in dep_ids {
327                if visited.insert(dep_id) {
328                    queue.push_back((dep_id, depth + 1));
329                }
330            }
331        }
332    }
333
334    let layer_labels = [
335        "Entry Points",
336        "Direct Dependencies",
337        "Core Infrastructure",
338        "Supporting Modules",
339        "Deep Dependencies",
340        "Periphery",
341    ];
342
343    let mut layers: Vec<ReadingLayer> = Vec::new();
344    for depth in 0..=5 {
345        if let Some(files) = layers_map.get(&depth)
346            && !files.is_empty()
347        {
348            layers.push(ReadingLayer {
349                depth,
350                label: layer_labels.get(depth).unwrap_or(&"Other").to_string(),
351                files: files.clone(),
352            });
353        }
354    }
355
356    Ok(ReadingOrder { layers })
357}
358
359/// Gather project stats for the onboard page
360pub fn gather_project_stats(cache: &CacheManager, module_count: usize) -> Result<ProjectStats> {
361    let db_path = cache.path().join("meta.db");
362    let conn = Connection::open(&db_path)?;
363
364    let total_files: usize = conn.query_row("SELECT COUNT(*) FROM files", [], |r| r.get(0))?;
365    let total_lines: usize =
366        conn.query_row("SELECT COALESCE(SUM(line_count), 0) FROM files", [], |r| {
367            r.get(0)
368        })?;
369
370    let mut stmt = conn.prepare(
371        "SELECT COALESCE(language, 'other'), COUNT(*) FROM files GROUP BY language ORDER BY COUNT(*) DESC LIMIT 10"
372    )?;
373    let languages: Vec<(String, usize)> = stmt
374        .query_map([], |row| {
375            Ok((row.get::<_, String>(0)?, row.get::<_, usize>(1)?))
376        })?
377        .filter_map(|r| r.ok())
378        .collect();
379
380    Ok(ProjectStats {
381        total_files,
382        total_lines,
383        languages,
384        module_count,
385    })
386}
387
388/// Generate the full onboard data (structural phase)
389pub fn generate_onboard_structural(
390    cache: &CacheManager,
391    module_count: usize,
392) -> Result<OnboardData> {
393    let entry_points = detect_entry_points(cache)?;
394    let reading_order = compute_reading_order(cache, &entry_points)?;
395    let project_stats = gather_project_stats(cache, module_count)?;
396
397    Ok(OnboardData {
398        entry_points,
399        reading_order,
400        project_stats,
401        narration: None,
402    })
403}
404
405/// Build structural context string for LLM narration
406pub fn build_onboard_context(data: &OnboardData) -> String {
407    let mut ctx = String::new();
408
409    ctx.push_str(&format!(
410        "Project size: {} files, {} lines across {} modules\n\n",
411        data.project_stats.total_files,
412        data.project_stats.total_lines,
413        data.project_stats.module_count,
414    ));
415
416    // Languages
417    ctx.push_str("Languages:\n");
418    for (lang, count) in &data.project_stats.languages {
419        ctx.push_str(&format!("- {}: {} files\n", lang, count));
420    }
421    ctx.push('\n');
422
423    // Entry points
424    ctx.push_str("Entry points:\n");
425    for ep in &data.entry_points {
426        ctx.push_str(&format!("- {} ({})", ep.path, ep.kind));
427        if !ep.key_symbols.is_empty() {
428            ctx.push_str(&format!(" — key symbols: {}", ep.key_symbols.join(", ")));
429        }
430        ctx.push('\n');
431    }
432    ctx.push('\n');
433
434    // Reading order
435    ctx.push_str("Suggested reading order (BFS from entry points through dependencies):\n");
436    for layer in &data.reading_order.layers {
437        ctx.push_str(&format!(
438            "Layer {} — {} ({} files):\n",
439            layer.depth,
440            layer.label,
441            layer.files.len()
442        ));
443        for file in layer.files.iter().take(15) {
444            ctx.push_str(&format!("  - {}\n", file));
445        }
446        if layer.files.len() > 15 {
447            ctx.push_str(&format!("  ... and {} more\n", layer.files.len() - 15));
448        }
449    }
450
451    ctx
452}
453
454/// Render onboard data as markdown (structural content)
455pub fn render_onboard_markdown(data: &OnboardData) -> String {
456    let mut md = String::new();
457
458    // Narration (if available)
459    if let Some(ref narration) = data.narration {
460        md.push_str(narration);
461        md.push_str("\n\n");
462    }
463
464    // Quick stats
465    md.push_str("## At a Glance\n\n");
466    md.push_str(&format!(
467        "| Metric | Value |\n|---|---|\n| Files | {} |\n| Lines | {} |\n| Modules | {} |\n| Languages | {} |\n\n",
468        data.project_stats.total_files,
469        data.project_stats.total_lines,
470        data.project_stats.module_count,
471        data.project_stats.languages.len(),
472    ));
473
474    // Entry points table
475    md.push_str("## Entry Points\n\n");
476    md.push_str("These are the starting files — where execution begins or where the public API is exposed.\n\n");
477    md.push_str("| File | Kind | Key Symbols |\n|---|---|---|\n");
478    for ep in &data.entry_points {
479        let symbols = if ep.key_symbols.is_empty() {
480            "—".to_string()
481        } else {
482            ep.key_symbols
483                .iter()
484                .map(|s| format!("`{}`", s))
485                .collect::<Vec<_>>()
486                .join(", ")
487        };
488        md.push_str(&format!("| `{}` | {} | {} |\n", ep.path, ep.kind, symbols));
489    }
490    md.push('\n');
491
492    // Reading order as Mermaid flowchart
493    if !data.reading_order.layers.is_empty() {
494        md.push_str("## Reading Order\n\n");
495        md.push_str(
496            "Start at the top and work your way down. Each layer depends on the one below it.\n\n",
497        );
498
499        md.push_str("{% mermaid() %}\nflowchart TD\n");
500        for layer in &data.reading_order.layers {
501            let node_id = format!("L{}", layer.depth);
502            let file_list: String = layer
503                .files
504                .iter()
505                .take(6)
506                .map(|f| {
507                    // Extract just the filename for readability
508                    Path::new(f)
509                        .file_name()
510                        .and_then(|n| n.to_str())
511                        .unwrap_or(f)
512                })
513                .collect::<Vec<_>>()
514                .join(", ");
515            let suffix = if layer.files.len() > 6 {
516                format!(" +{} more", layer.files.len() - 6)
517            } else {
518                String::new()
519            };
520            md.push_str(&format!(
521                "    {}[\"{}: {}{}\"]\n",
522                node_id, layer.label, file_list, suffix
523            ));
524        }
525
526        // Connect layers top-to-bottom
527        for i in 0..data.reading_order.layers.len().saturating_sub(1) {
528            md.push_str(&format!("    L{} --> L{}\n", i, i + 1));
529        }
530
531        // Styling
532        md.push_str("    style L0 fill:#a78bfa,color:#0d0d0d,stroke:#a78bfa\n");
533        md.push_str("{% end %}\n\n");
534
535        // Detailed file lists per layer
536        for layer in &data.reading_order.layers {
537            md.push_str(&format!("### Layer {}: {}\n\n", layer.depth, layer.label));
538            for file in &layer.files {
539                md.push_str(&format!("- `{}`\n", file));
540            }
541            md.push('\n');
542        }
543    }
544
545    md
546}
547
548#[cfg(test)]
549mod tests {
550    use super::*;
551
552    #[test]
553    fn test_entry_point_kind_display() {
554        assert_eq!(format!("{}", EntryPointKind::CliBinary), "CLI Binary");
555        assert_eq!(format!("{}", EntryPointKind::HttpServer), "HTTP Server");
556        assert_eq!(format!("{}", EntryPointKind::Library), "Library");
557    }
558
559    #[test]
560    fn test_render_onboard_markdown_empty() {
561        let data = OnboardData {
562            entry_points: vec![],
563            reading_order: ReadingOrder { layers: vec![] },
564            project_stats: ProjectStats {
565                total_files: 100,
566                total_lines: 5000,
567                languages: vec![("Rust".to_string(), 80), ("Python".to_string(), 20)],
568                module_count: 5,
569            },
570            narration: None,
571        };
572        let md = render_onboard_markdown(&data);
573        assert!(md.contains("## At a Glance"));
574        assert!(md.contains("100"));
575        assert!(md.contains("5000"));
576    }
577
578    #[test]
579    fn test_build_onboard_context() {
580        let data = OnboardData {
581            entry_points: vec![EntryPoint {
582                path: "src/main.rs".to_string(),
583                kind: EntryPointKind::CliBinary,
584                key_symbols: vec!["main".to_string()],
585            }],
586            reading_order: ReadingOrder {
587                layers: vec![ReadingLayer {
588                    depth: 0,
589                    label: "Entry Points".to_string(),
590                    files: vec!["src/main.rs".to_string()],
591                }],
592            },
593            project_stats: ProjectStats {
594                total_files: 50,
595                total_lines: 3000,
596                languages: vec![("Rust".to_string(), 50)],
597                module_count: 3,
598            },
599            narration: None,
600        };
601        let ctx = build_onboard_context(&data);
602        assert!(ctx.contains("src/main.rs"));
603        assert!(ctx.contains("CLI Binary"));
604        assert!(ctx.contains("Entry Points"));
605    }
606}
reflex/pulse/onboard.rs

reflex/pulse/
onboard.rs
