Skip to main content

reflex/pulse/
map.rs

1//! Architecture map generation
2//!
3//! Produces dependency diagrams in mermaid or d2 format.
4//! Modules come from [`ModuleGraph`], the same source modules the site's Internals tab shows.
5
6use anyhow::Result;
7use serde::{Deserialize, Serialize};
8use std::collections::{HashMap, HashSet};
9
10use crate::cache::CacheManager;
11use crate::dependency::DependencyIndex;
12
13use super::build::modules::ModuleGraph;
14use super::extract::Corpus;
15
16/// One map node: a module of [`ModuleGraph`].
17#[derive(Debug, Clone)]
18pub struct ModuleDefinition {
19    /// Module path (e.g. "src", "src/parsers").
20    pub path: String,
21    /// 1 = top-level, 2 = a submodule.
22    pub tier: u8,
23    pub file_count: usize,
24}
25
26/// The source modules of the index (depth 2), without the root pseudo-module.
27fn detect_modules(cache: &CacheManager) -> Result<Vec<ModuleDefinition>> {
28    let corpus = Corpus::load(cache)?;
29    let graph = ModuleGraph::build(&corpus, 2, 1);
30    Ok(graph
31        .modules
32        .iter()
33        .filter(|m| !m.is_root())
34        .map(|m| ModuleDefinition {
35            path: m.id.as_str().to_string(),
36            tier: m.tier,
37            file_count: m.files.len(),
38        })
39        .collect())
40}
41
42/// Zoom level for the architecture map
43#[derive(Debug, Clone, Serialize, Deserialize)]
44pub enum MapZoom {
45    /// Whole-repo view: modules as nodes
46    Repo,
47    /// Single module view: files within module as nodes
48    Module(String),
49}
50
51/// Output format for the map
52#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
53pub enum MapFormat {
54    Mermaid,
55    D2,
56}
57
58impl std::str::FromStr for MapFormat {
59    type Err = anyhow::Error;
60    fn from_str(s: &str) -> Result<Self> {
61        match s.to_lowercase().as_str() {
62            "mermaid" => Ok(MapFormat::Mermaid),
63            "d2" => Ok(MapFormat::D2),
64            _ => anyhow::bail!("Unknown map format: {}. Supported: mermaid, d2", s),
65        }
66    }
67}
68
69/// Generate an architecture map
70pub fn generate_map(cache: &CacheManager, zoom: &MapZoom, format: MapFormat) -> Result<String> {
71    match zoom {
72        MapZoom::Repo => generate_repo_map(cache, format),
73        MapZoom::Module(module) => generate_module_map(cache, module, format),
74    }
75}
76
77fn generate_repo_map(cache: &CacheManager, format: MapFormat) -> Result<String> {
78    let db_path = cache.path().join("meta.db");
79    let conn = crate::cache::open_meta_db(&db_path)?;
80
81    let modules = detect_modules(cache)?;
82
83    // Build module info for node labels
84    let module_info: Vec<(String, usize)> = modules
85        .iter()
86        .map(|m| (m.path.clone(), m.file_count))
87        .collect();
88
89    // Get all file-level dependency edges
90    let mut stmt = conn.prepare(
91        "SELECT f1.path, f2.path
92         FROM import_edges e
93         JOIN files f1 ON e.src = f1.id
94         JOIN files f2 ON e.dst = f2.id",
95    )?;
96
97    let file_edges: Vec<(String, String)> = stmt
98        .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))?
99        .collect::<Result<Vec<_>, _>>()?;
100
101    // Aggregate file-level edges to module-level edges
102    let mut module_edges: HashMap<(String, String), usize> = HashMap::new();
103    for (src_file, tgt_file) in &file_edges {
104        let src_module = find_owning_module(src_file, &modules);
105        let tgt_module = find_owning_module(tgt_file, &modules);
106
107        if src_module != tgt_module {
108            *module_edges.entry((src_module, tgt_module)).or_insert(0) += 1;
109        }
110    }
111
112    let mut edges: Vec<(String, String, usize)> = module_edges
113        .into_iter()
114        .map(|((s, t), c)| (s, t, c))
115        .collect();
116    // Heaviest first; equal weights by module name (`module_edges` is a HashMap)
117    edges.sort_by(|a, b| b.2.cmp(&a.2).then_with(|| (&a.0, &a.1).cmp(&(&b.0, &b.1))));
118
119    // Get hotspots for highlighting
120    let deps_index = DependencyIndex::new(cache.clone());
121    let hotspots = deps_index.find_hotspots(Some(10), 5).unwrap_or_default();
122    let hotspot_modules: HashSet<String> = hotspots
123        .iter()
124        .filter_map(|(id, _)| {
125            deps_index
126                .get_file_paths(&[*id])
127                .ok()
128                .and_then(|paths| paths.get(id).cloned())
129                .map(|p| find_owning_module(&p, &modules))
130        })
131        .collect();
132
133    match format {
134        MapFormat::Mermaid => render_mermaid_repo(&module_info, &edges, &hotspot_modules),
135        MapFormat::D2 => render_d2_repo(&module_info, &edges, &hotspot_modules),
136    }
137}
138
139/// Find the most-specific module that owns a given file path
140fn find_owning_module(file_path: &str, modules: &[ModuleDefinition]) -> String {
141    let mut best_match = String::new();
142    let mut best_len = 0;
143
144    for module in modules {
145        let prefix = format!("{}/", module.path);
146        if file_path.starts_with(&prefix) && module.path.len() > best_len {
147            best_match = module.path.clone();
148            best_len = module.path.len();
149        }
150    }
151
152    if best_match.is_empty() {
153        file_path.split('/').next().unwrap_or("root").to_string()
154    } else {
155        best_match
156    }
157}
158
159fn generate_module_map(
160    cache: &CacheManager,
161    module_path: &str,
162    format: MapFormat,
163) -> Result<String> {
164    let db_path = cache.path().join("meta.db");
165    let conn = crate::cache::open_meta_db(&db_path)?;
166    let pattern = format!("{}/%", module_path);
167
168    // Get files in this module
169    let mut stmt = conn.prepare("SELECT id, path FROM files WHERE path LIKE ?1 ORDER BY path")?;
170    let files: Vec<(i64, String)> = stmt
171        .query_map([&pattern], |row| Ok((row.get(0)?, row.get(1)?)))?
172        .collect::<Result<Vec<_>, _>>()?;
173
174    // Get intra-module edges
175    let mut stmt = conn.prepare(
176        "SELECT f1.path, f2.path
177         FROM import_edges e
178         JOIN files f1 ON e.src = f1.id
179         JOIN files f2 ON e.dst = f2.id
180         WHERE f1.path LIKE ?1 AND f2.path LIKE ?1",
181    )?;
182    let edges: Vec<(String, String)> = stmt
183        .query_map([&pattern], |row| Ok((row.get(0)?, row.get(1)?)))?
184        .collect::<Result<Vec<_>, _>>()?;
185
186    match format {
187        MapFormat::Mermaid => render_mermaid_module(module_path, &files, &edges),
188        MapFormat::D2 => render_d2_module(module_path, &files, &edges),
189    }
190}
191
192/// Create a Mermaid-safe node ID with a prefix to avoid reserved word collisions.
193/// Mermaid v11 can choke on IDs that match internal keywords or contain certain patterns.
194fn sanitize_id(s: &str) -> String {
195    format!("m_{}", s.replace(['/', '.', '-', ' '], "_"))
196}
197
198fn render_mermaid_repo(
199    modules: &[(String, usize)],
200    edges: &[(String, String, usize)],
201    hotspot_modules: &HashSet<String>,
202) -> Result<String> {
203    let mut out = String::from("graph LR\n");
204
205    // Only emit modules that participate in at least one edge
206    let connected: HashSet<&str> = edges
207        .iter()
208        .flat_map(|(s, t, _)| [s.as_str(), t.as_str()])
209        .collect();
210
211    for (module, count) in modules {
212        if !connected.contains(module.as_str()) {
213            continue;
214        }
215        let id = sanitize_id(module);
216        out.push_str(&format!("  {}[\"{}/ ({} files)\"]\n", id, module, count));
217    }
218
219    out.push('\n');
220
221    // Track thick edges for linkStyle directives
222    let mut thick_edge_indices: Vec<usize> = Vec::new();
223    for (i, (src, tgt, count)) in edges.iter().enumerate() {
224        let src_id = sanitize_id(src);
225        let tgt_id = sanitize_id(tgt);
226        out.push_str(&format!("  {} -->|{}| {}\n", src_id, count, tgt_id));
227        if *count > 5 {
228            thick_edge_indices.push(i);
229        }
230    }
231
232    // Apply thick stroke to high-count edges via linkStyle
233    for idx in &thick_edge_indices {
234        out.push_str(&format!(
235            "  linkStyle {} stroke-width:3px,stroke:#a78bfa\n",
236            idx
237        ));
238    }
239
240    // High-contrast styling for dark theme
241    out.push_str("\n  classDef default fill:#1a1a2e,stroke:#a78bfa,color:#e0e0e0\n");
242    out.push_str("  classDef hotspot fill:#2a1030,stroke:#f472b6,color:#f472b6\n");
243    if !hotspot_modules.is_empty() {
244        for module in hotspot_modules {
245            if !connected.contains(module.as_str()) {
246                continue;
247            }
248            let id = sanitize_id(module);
249            out.push_str(&format!("  class {} hotspot\n", id));
250        }
251    }
252
253    Ok(out)
254}
255
256/// Generate a layered (top-to-bottom) architecture diagram with Tier 1 subgraphs containing Tier 2 children
257pub fn generate_layered_map(cache: &CacheManager, format: MapFormat) -> Result<String> {
258    let db_path = cache.path().join("meta.db");
259    let conn = crate::cache::open_meta_db(&db_path)?;
260    let modules = detect_modules(cache)?;
261
262    let module_info: Vec<(String, usize, u8)> = modules
263        .iter()
264        .map(|m| (m.path.clone(), m.file_count, m.tier))
265        .collect();
266
267    // Get module-level edges
268    let mut stmt = conn.prepare(
269        "SELECT f1.path, f2.path
270         FROM import_edges e
271         JOIN files f1 ON e.src = f1.id
272         JOIN files f2 ON e.dst = f2.id",
273    )?;
274    let file_edges: Vec<(String, String)> = stmt
275        .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))?
276        .collect::<Result<Vec<_>, _>>()?;
277
278    let mut module_edges: HashMap<(String, String), usize> = HashMap::new();
279    for (src_file, tgt_file) in &file_edges {
280        let src_module = find_owning_module(src_file, &modules);
281        let tgt_module = find_owning_module(tgt_file, &modules);
282        if src_module != tgt_module {
283            *module_edges.entry((src_module, tgt_module)).or_insert(0) += 1;
284        }
285    }
286
287    let mut edges: Vec<(String, String, usize)> = module_edges
288        .into_iter()
289        .map(|((s, t), c)| (s, t, c))
290        .collect();
291    // Heaviest first; equal weights by module name (`module_edges` is a HashMap)
292    edges.sort_by(|a, b| b.2.cmp(&a.2).then_with(|| (&a.0, &a.1).cmp(&(&b.0, &b.1))));
293
294    let deps_index = DependencyIndex::new(cache.clone());
295    let hotspots = deps_index.find_hotspots(Some(10), 5).unwrap_or_default();
296    let hotspot_modules: HashSet<String> = hotspots
297        .iter()
298        .filter_map(|(id, _)| {
299            deps_index
300                .get_file_paths(&[*id])
301                .ok()
302                .and_then(|paths| paths.get(id).cloned())
303                .map(|p| find_owning_module(&p, &modules))
304        })
305        .collect();
306
307    match format {
308        MapFormat::Mermaid => render_mermaid_layered(&module_info, &edges, &hotspot_modules),
309        MapFormat::D2 => render_d2_repo(
310            &module_info
311                .iter()
312                .map(|(p, c, _)| (p.clone(), *c))
313                .collect::<Vec<_>>(),
314            &edges,
315            &hotspot_modules,
316        ),
317    }
318}
319
320fn render_mermaid_layered(
321    modules: &[(String, usize, u8)],
322    edges: &[(String, String, usize)],
323    hotspot_modules: &HashSet<String>,
324) -> Result<String> {
325    let mut out = String::from("flowchart TB\n");
326
327    // Only emit modules that participate in at least one edge
328    let connected: HashSet<&str> = edges
329        .iter()
330        .flat_map(|(s, t, _)| [s.as_str(), t.as_str()])
331        .collect();
332
333    // Group Tier 2 modules under their Tier 1 parent
334    let tier1: Vec<&(String, usize, u8)> = modules.iter().filter(|m| m.2 == 1).collect();
335    let tier2: Vec<&(String, usize, u8)> = modules.iter().filter(|m| m.2 == 2).collect();
336
337    // Build proxy map: Tier 1 modules that become subgraphs get an inner proxy node.
338    // Mermaid v11 cannot target subgraph IDs with edges or classDef,
339    // so we create a real node inside the subgraph to receive those interactions.
340    let mut proxy_map: HashMap<String, String> = HashMap::new();
341
342    for t1 in &tier1 {
343        if !connected.contains(t1.0.as_str()) {
344            continue;
345        }
346        let t1_id = sanitize_id(&t1.0);
347        let children: Vec<&&(String, usize, u8)> = tier2
348            .iter()
349            .filter(|t2| {
350                t2.0.starts_with(&format!("{}/", t1.0)) && connected.contains(t2.0.as_str())
351            })
352            .collect();
353
354        if children.is_empty() {
355            // Standalone Tier 1 node (no subgraph needed)
356            out.push_str(&format!("  {}[\"{}/ ({} files)\"]\n", t1_id, t1.0, t1.1));
357        } else {
358            // Subgraph with proxy node for edges and styling
359            let proxy_id = format!("{}_self", t1_id);
360            proxy_map.insert(t1.0.clone(), proxy_id.clone());
361
362            out.push_str(&format!("  subgraph {} [\"{}/ \"]\n", t1_id, t1.0));
363            out.push_str(&format!(
364                "    {}[\"{}/ ({} files)\"]\n",
365                proxy_id, t1.0, t1.1
366            ));
367            for child in &children {
368                let child_id = sanitize_id(&child.0);
369                let short = child
370                    .0
371                    .strip_prefix(&format!("{}/", t1.0))
372                    .unwrap_or(&child.0);
373                out.push_str(&format!(
374                    "    {}[\"{}/ ({} files)\"]\n",
375                    child_id, short, child.1
376                ));
377            }
378            out.push_str("  end\n");
379        }
380    }
381
382    // Orphan Tier 2 modules (no matching Tier 1 parent)
383    for t2 in &tier2 {
384        if !connected.contains(t2.0.as_str()) {
385            continue;
386        }
387        let has_parent = tier1
388            .iter()
389            .any(|t1| t2.0.starts_with(&format!("{}/", t1.0)));
390        if !has_parent {
391            let id = sanitize_id(&t2.0);
392            out.push_str(&format!("  {}[\"{}/ ({} files)\"]\n", id, t2.0, t2.1));
393        }
394    }
395
396    out.push('\n');
397
398    // Track thick edges for linkStyle directives
399    // Resolve edge endpoints through proxy_map so edges target proxy nodes, not subgraphs
400    let mut thick_edge_indices: Vec<usize> = Vec::new();
401    for (i, (src, tgt, count)) in edges.iter().enumerate() {
402        let src_id = proxy_map
403            .get(src)
404            .cloned()
405            .unwrap_or_else(|| sanitize_id(src));
406        let tgt_id = proxy_map
407            .get(tgt)
408            .cloned()
409            .unwrap_or_else(|| sanitize_id(tgt));
410        out.push_str(&format!("  {} -->|{}| {}\n", src_id, count, tgt_id));
411        if *count > 5 {
412            thick_edge_indices.push(i);
413        }
414    }
415
416    // Apply thick stroke to high-count edges via linkStyle
417    for idx in &thick_edge_indices {
418        out.push_str(&format!(
419            "  linkStyle {} stroke-width:3px,stroke:#a78bfa\n",
420            idx
421        ));
422    }
423
424    // Styling — apply classDef to proxy nodes, not subgraph containers
425    out.push_str("\n  classDef default fill:#1a1a2e,stroke:#a78bfa,color:#e0e0e0\n");
426    out.push_str("  classDef hotspot fill:#2a1030,stroke:#f472b6,color:#f472b6\n");
427    for module in hotspot_modules {
428        if !connected.contains(module.as_str()) {
429            continue;
430        }
431        let id = proxy_map
432            .get(module)
433            .cloned()
434            .unwrap_or_else(|| sanitize_id(module));
435        out.push_str(&format!("  class {} hotspot\n", id));
436    }
437
438    Ok(out)
439}
440
441fn render_d2_repo(
442    modules: &[(String, usize)],
443    edges: &[(String, String, usize)],
444    hotspot_modules: &HashSet<String>,
445) -> Result<String> {
446    let mut out = String::new();
447
448    for (module, count) in modules {
449        let id = sanitize_id(module);
450        out.push_str(&format!("{}: \"{}/ ({} files)\"\n", id, module, count));
451        if hotspot_modules.contains(module) {
452            out.push_str(&format!("{}.style.fill: \"#ff6b6b\"\n", id));
453        }
454    }
455
456    out.push('\n');
457
458    for (src, tgt, count) in edges {
459        let src_id = sanitize_id(src);
460        let tgt_id = sanitize_id(tgt);
461        out.push_str(&format!("{} -> {}: {}\n", src_id, tgt_id, count));
462    }
463
464    Ok(out)
465}
466
467fn render_mermaid_module(
468    module_path: &str,
469    files: &[(i64, String)],
470    edges: &[(String, String)],
471) -> Result<String> {
472    let mut out = format!("graph LR\n  subgraph {}\n", module_path);
473
474    for (_, path) in files {
475        let id = sanitize_id(path);
476        let short_name = path.rsplit('/').next().unwrap_or(path);
477        out.push_str(&format!("    {}[\"{}\"]\n", id, short_name));
478    }
479
480    for (src, tgt) in edges {
481        let src_id = sanitize_id(src);
482        let tgt_id = sanitize_id(tgt);
483        out.push_str(&format!("    {} --> {}\n", src_id, tgt_id));
484    }
485
486    out.push_str("  end\n");
487
488    Ok(out)
489}
490
491fn render_d2_module(
492    module_path: &str,
493    files: &[(i64, String)],
494    edges: &[(String, String)],
495) -> Result<String> {
496    let mut out = format!("{}: {{\n", sanitize_id(module_path));
497
498    for (_, path) in files {
499        let id = sanitize_id(path);
500        let short_name = path.rsplit('/').next().unwrap_or(path);
501        out.push_str(&format!("  {}: \"{}\"\n", id, short_name));
502    }
503
504    for (src, tgt) in edges {
505        let src_id = sanitize_id(src);
506        let tgt_id = sanitize_id(tgt);
507        out.push_str(&format!("  {} -> {}\n", src_id, tgt_id));
508    }
509
510    out.push_str("}\n");
511
512    Ok(out)
513}
514
515#[cfg(test)]
516mod tests {
517    use super::*;
518
519    #[test]
520    fn test_sanitize_id() {
521        assert_eq!(sanitize_id("src/parsers"), "m_src_parsers");
522        assert_eq!(sanitize_id("my-module.rs"), "m_my_module_rs");
523    }
524
525    #[test]
526    fn test_mermaid_repo_output() {
527        let modules = vec![("src".to_string(), 50), ("tests".to_string(), 10)];
528        let edges = vec![("src".to_string(), "tests".to_string(), 3)];
529        let hotspots = HashSet::new();
530
531        let result = render_mermaid_repo(&modules, &edges, &hotspots).unwrap();
532        assert!(result.contains("graph LR"));
533        assert!(result.contains("src"));
534        assert!(result.contains("tests"));
535        assert!(result.contains("-->"));
536    }
537
538    #[test]
539    fn test_d2_repo_output() {
540        let modules = vec![("src".to_string(), 50)];
541        let edges = vec![];
542        let hotspots = HashSet::from(["src".to_string()]);
543
544        let result = render_d2_repo(&modules, &edges, &hotspots).unwrap();
545        assert!(result.contains("src:"));
546        assert!(result.contains("#ff6b6b"));
547    }
548
549    #[test]
550    fn test_mermaid_repo_filters_orphans() {
551        let modules = vec![
552            ("src".to_string(), 50),
553            ("tests".to_string(), 10),
554            ("docs".to_string(), 5),    // orphan — no edges
555            ("scripts".to_string(), 2), // orphan — no edges
556        ];
557        let edges = vec![("src".to_string(), "tests".to_string(), 3)];
558        let hotspots = HashSet::from(["docs".to_string()]);
559
560        let result = render_mermaid_repo(&modules, &edges, &hotspots).unwrap();
561
562        // Connected modules are present
563        assert!(
564            result.contains("m_src["),
565            "connected module 'src' should be in output"
566        );
567        assert!(
568            result.contains("m_tests["),
569            "connected module 'tests' should be in output"
570        );
571
572        // Orphan modules are excluded
573        assert!(
574            !result.contains("m_docs"),
575            "orphan 'docs' should not be in output"
576        );
577        assert!(
578            !result.contains("m_scripts"),
579            "orphan 'scripts' should not be in output"
580        );
581
582        // Hotspot styling for orphan should not appear
583        assert!(
584            !result.contains("class m_docs hotspot"),
585            "orphan hotspot should not be styled"
586        );
587    }
588
589    #[test]
590    fn test_mermaid_layered_proxy_nodes() {
591        let modules = vec![
592            ("src".to_string(), 80, 1u8),
593            ("src/parsers".to_string(), 15, 2u8),
594            ("tests".to_string(), 10, 1u8),
595        ];
596        let edges = vec![
597            ("src/parsers".to_string(), "src".to_string(), 16),
598            ("src".to_string(), "tests".to_string(), 3),
599        ];
600        let hotspots = HashSet::from(["src".to_string()]);
601
602        let result = render_mermaid_layered(&modules, &edges, &hotspots).unwrap();
603
604        // Subgraph for src should exist (it has children)
605        assert!(
606            result.contains("subgraph m_src ["),
607            "Tier 1 with children should be a subgraph"
608        );
609
610        // Proxy node inside the subgraph
611        assert!(
612            result.contains("m_src_self["),
613            "subgraph should contain proxy node"
614        );
615
616        // Edges should target proxy node, not subgraph ID
617        assert!(
618            result.contains("m_src_self"),
619            "edges should reference proxy node"
620        );
621        assert!(
622            !result.contains(" -->|16| m_src\n"),
623            "edges should NOT target bare subgraph ID"
624        );
625
626        // classDef should target proxy node
627        assert!(
628            result.contains("class m_src_self hotspot"),
629            "hotspot class should target proxy node"
630        );
631
632        // tests is standalone Tier 1 (no children), should be a regular node
633        assert!(
634            result.contains("m_tests["),
635            "standalone Tier 1 should be a regular node"
636        );
637        assert!(
638            !result.contains("subgraph m_tests"),
639            "standalone Tier 1 should not be a subgraph"
640        );
641    }
642
643    #[test]
644    fn test_find_owning_module() {
645        let modules = vec![
646            ModuleDefinition {
647                path: "src".to_string(),
648                tier: 1,
649                file_count: 80,
650            },
651            ModuleDefinition {
652                path: "src/parsers".to_string(),
653                tier: 2,
654                file_count: 15,
655            },
656        ];
657
658        assert_eq!(
659            find_owning_module("src/parsers/rust.rs", &modules),
660            "src/parsers"
661        );
662        assert_eq!(find_owning_module("src/main.rs", &modules), "src");
663        assert_eq!(
664            find_owning_module("tests/integration.rs", &modules),
665            "tests"
666        );
667    }
668}