Skip to main content

generate_rpc_diagrams/
generate_rpc_diagrams.rs

1//! Generate Mermaid architecture diagrams from Cap'n Proto schema metadata
2//! and auto-detected service dependencies.
3//!
4//! Usage:
5//!   cargo run --bin generate-rpc-diagrams -- [--metadata-dir PATH] [--services-dir PATH] [-o PATH]
6//!
7//! Reads:
8//!   - *_metadata.json files (from capnp build output) for method counts + scopes
9//!   - services/factories.rs for service registrations, transport types, QUIC support
10//!   - services/*.rs for client imports (auto-detected call graph)
11// CLI binary — relaxed lints for a dev tool (not library code)
12#![allow(clippy::all, clippy::pedantic, clippy::restriction, dead_code)]
13
14use std::collections::{BTreeMap, BTreeSet};
15use std::fs;
16use std::path::{Path, PathBuf};
17
18// ── Types ───────────────────────────────────────────────────────────────────
19
20fn scope_name(ordinal: u64) -> &'static str {
21    match ordinal {
22        0 => "query",
23        1 => "write",
24        2 => "manage",
25        3 => "infer",
26        4 => "train",
27        5 => "serve",
28        6 => "context",
29        7 => "subscribe",
30        8 => "publish",
31        _ => "unknown",
32    }
33}
34
35fn title_case(s: &str) -> String {
36    let mut c = s.chars();
37    match c.next() {
38        None => String::new(),
39        Some(f) => f.to_uppercase().to_string() + c.as_str(),
40    }
41}
42
43#[derive(Debug)]
44struct ServiceMeta {
45    name: String,
46    transport: Transport,
47    methods: usize,
48    scopes: BTreeMap<String, usize>,
49    dependencies: BTreeSet<DepEdge>,
50    has_quic: bool,
51}
52
53#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd)]
54struct DepEdge {
55    target: String,
56    client_type: String,
57}
58
59#[derive(Debug, Clone, Copy, PartialEq)]
60enum Transport {
61    RpcReqRep,
62    Http,
63    Proxy,
64}
65
66impl Transport {
67    fn label(&self) -> &'static str {
68        match self {
69            Transport::RpcReqRep => "RPC REQ/REP",
70            Transport::Http => "HTTP",
71            Transport::Proxy => "Event Proxy",
72        }
73    }
74}
75
76// ── Client type → target service mapping ────────────────────────────────────
77
78/// Maps a client/type name found in source to the service it connects to.
79fn client_to_service(client_type: &str) -> Option<&'static str> {
80    match client_type {
81        "PolicyClient" => Some("policy"),
82        "RegistryClient" => Some("registry"),
83        "ModelClient" => Some("model"),
84        "InferenceClient" => Some("inference"),
85        "WorktreeClient" => Some("registry"), // scoped sub-client of registry
86        "RepositoryClient" => Some("registry"), // scoped sub-client of registry
87        "CtlClient" => Some("registry"),      // scoped sub-client of registry
88        "DiscoveryClient" => Some("discovery"),
89        "WorkerClient" => Some("worker"),
90        // Streaming: StreamChannel/StreamInfo indicate the service publishes
91        // through StreamService (PUSH → XPUB relay)
92        "StreamChannel" => Some("streams"),
93        "StreamInfo" => Some("streams"),
94        _ => None,
95    }
96}
97
98/// All known client/type names to scan for.
99const CLIENT_TYPES: &[&str] = &[
100    "PolicyClient",
101    "RegistryClient",
102    "ModelClient",
103    "InferenceClient",
104    "WorktreeClient",
105    "RepositoryClient",
106    "CtlClient",
107    "DiscoveryClient",
108    "WorkerClient",
109    // Streaming types — presence means service publishes via StreamService
110    "StreamChannel",
111    "StreamInfo",
112];
113
114// ── Source file → service name mapping ──────────────────────────────────────
115
116/// Maps a source filename to the service it implements.
117fn filename_to_service(filename: &str) -> Option<&'static str> {
118    match filename {
119        "factories.rs" => None,                        // handled separately
120        "mod.rs" | "core.rs" | "generated.rs" => None, // infrastructure, not a service
121        "worktree_helpers.rs" => None,                 // helper, not a service
122        "registry.rs" => Some("registry"),
123        "model.rs" => Some("model"),
124        "inference.rs" => Some("inference"),
125        "discovery.rs" => Some("discovery"),
126        "worker.rs" => Some("worker"),
127        "mcp_service.rs" => Some("mcp"),
128        "oai.rs" => Some("oai"),
129        "flight.rs" => Some("flight"),
130        "tui.rs" | "tui_service.rs" => Some("tui"),
131        "stream.rs" => Some("streams"),
132        "policy.rs" => Some("policy"),
133        "editing.rs" => Some("editing"),
134        _ => {
135            // oauth/mod.rs, oauth/state.rs etc
136            if filename.starts_with("oauth") {
137                Some("oauth")
138            } else {
139                None
140            }
141        }
142    }
143}
144
145// ── Method-level call graph types ────────────────────────────────────────────
146
147/// A method defined in a service's schema.
148#[derive(Debug, Clone)]
149struct MethodDef {
150    /// camelCase name from schema (e.g., "generateStream")
151    schema_name: String,
152    /// snake_case name as it appears in Rust code (e.g., "generate_stream")
153    rust_name: String,
154    /// Scope action (query, write, manage, infer, train, etc.)
155    scope: String,
156    /// Human description from $mcpDescription
157    description: String,
158    /// Which service this method belongs to
159    service: String,
160    /// Parent struct name (e.g., "ModelRequest", "RepositoryRequest")
161    parent: String,
162}
163
164/// A detected method-level call from one caller to a target service method.
165#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd)]
166struct MethodCall {
167    /// Caller module (service name or "cli:handlers", "server:routes", etc.)
168    caller: String,
169    /// Target service
170    target_service: String,
171    /// Target method (snake_case)
172    target_method: String,
173    /// Source file path (relative)
174    source_file: String,
175    /// Line number
176    line: usize,
177}
178
179/// camelCase → snake_case conversion (e.g., "generateStream" → "generate_stream")
180fn to_snake_case(s: &str) -> String {
181    let mut result = String::with_capacity(s.len() + 4);
182    for (i, c) in s.chars().enumerate() {
183        if c.is_uppercase() {
184            if i > 0 {
185                result.push('_');
186            }
187            result.push(c.to_lowercase().next().unwrap());
188        } else {
189            result.push(c);
190        }
191    }
192    result
193}
194
195/// Parse all metadata files to build a method registry.
196fn build_method_registry(metadata_dir: &Path) -> Vec<MethodDef> {
197    let mut methods = Vec::new();
198
199    let entries = match fs::read_dir(metadata_dir) {
200        Ok(e) => e,
201        Err(_) => return methods,
202    };
203
204    for entry in entries.flatten() {
205        let path = entry.path();
206        let is_metadata = path
207            .file_name()
208            .map(|n| n.to_string_lossy().ends_with("_metadata.json"))
209            .unwrap_or(false);
210        if !is_metadata {
211            continue;
212        }
213
214        let content = match fs::read_to_string(&path) {
215            Ok(c) => c,
216            Err(_) => continue,
217        };
218        let json: serde_json::Value = match serde_json::from_str(&content) {
219            Ok(j) => j,
220            Err(_) => continue,
221        };
222
223        let service = match json.get("service").and_then(|s| s.as_str()) {
224            Some(s) => s.to_string(),
225            None => continue,
226        };
227
228        let structs = match json.get("structs").and_then(|s| s.as_array()) {
229            Some(s) => s,
230            None => continue,
231        };
232
233        for s in structs {
234            let struct_name = s.get("name").and_then(|n| n.as_str()).unwrap_or("");
235
236            for field in s
237                .get("fields")
238                .and_then(|f| f.as_array())
239                .into_iter()
240                .flatten()
241            {
242                let disc = field
243                    .get("discriminant")
244                    .and_then(|d| d.as_u64())
245                    .unwrap_or(65535);
246                if disc == 65535 {
247                    continue; // not a union variant
248                }
249
250                let name = match field.get("name").and_then(|n| n.as_str()) {
251                    Some(n) => n.to_string(),
252                    None => continue,
253                };
254
255                let mut scope = String::new();
256                let mut description = String::new();
257
258                for ann in field
259                    .get("annotations")
260                    .and_then(|a| a.as_array())
261                    .into_iter()
262                    .flatten()
263                {
264                    let ann_name = ann.get("name").and_then(|n| n.as_str()).unwrap_or("");
265                    if ann_name == "scope" || ann_name == "capability" {
266                        scope = ann
267                            .get("value")
268                            .and_then(|v| {
269                                v.as_object()
270                                    .and_then(|o| o.get("enum_ordinal"))
271                                    .and_then(|o| o.as_u64())
272                                    .map(|ord| scope_name(ord).to_string())
273                                    .or_else(|| v.as_str().map(String::from))
274                            })
275                            .unwrap_or_default();
276                    }
277                    if ann_name == "mcpDescription" {
278                        description = ann
279                            .get("value")
280                            .and_then(|v| v.as_str())
281                            .unwrap_or("")
282                            .to_string();
283                    }
284                }
285
286                methods.push(MethodDef {
287                    rust_name: to_snake_case(&name),
288                    schema_name: name,
289                    scope,
290                    description,
291                    service: service.clone(),
292                    parent: struct_name.to_string(),
293                });
294            }
295        }
296    }
297
298    methods
299}
300
301/// Scan all Rust source files for method-level calls to known service methods.
302fn scan_method_calls(src_root: &Path, method_registry: &[MethodDef]) -> Vec<MethodCall> {
303    let mut calls = Vec::new();
304
305    // Generic Rust method names that produce too many false positives.
306    // These are only matched when preceded by a known client variable pattern.
307    const GENERIC_METHODS: &[&str] = &[
308        "clone",
309        "get",
310        "list",
311        "remove",
312        "status",
313        "check",
314        "register",
315        "load",
316        "unload",
317        "connect",
318        "attach",
319        "subscribe",
320        "unsubscribe",
321        "success",
322        "repo",
323        "worktree",
324        "get_by_name",
325    ];
326
327    // Build a lookup: snake_case method name → Vec<MethodDef>
328    // (multiple services might have same method name like "status", "list")
329    let mut method_lookup: BTreeMap<String, Vec<&MethodDef>> = BTreeMap::new();
330    for m in method_registry {
331        method_lookup
332            .entry(m.rust_name.clone())
333            .or_default()
334            .push(m);
335    }
336
337    let generic_set: std::collections::HashSet<&str> = GENERIC_METHODS.iter().copied().collect();
338
339    // Walk all .rs files under src_root
340    walk_rs_files(src_root, &mut |path| {
341        let content = match fs::read_to_string(path) {
342            Ok(c) => c,
343            Err(_) => return,
344        };
345
346        let relative = path
347            .strip_prefix(src_root)
348            .unwrap_or(path)
349            .to_string_lossy()
350            .to_string();
351
352        // Determine caller identity from file path
353        let caller = path_to_caller(&relative);
354        if caller.is_empty() {
355            return;
356        }
357
358        // Scan for patterns like:
359        //   <ident>_client.<method>(    — cross-service call via named client
360        //   <ident>.<method>(           — via client variable
361        // We look for known method names preceded by a dot.
362        for (line_num, line) in content.lines().enumerate() {
363            let trimmed = line.trim();
364            // Skip comments
365            if trimmed.starts_with("//") || trimmed.starts_with("///") || trimmed.starts_with("*") {
366                continue;
367            }
368
369            for (method_name, defs) in &method_lookup {
370                let is_generic = generic_set.contains(method_name.as_str());
371
372                // Look for .<method_name>( pattern
373                let pattern = format!(".{}(", method_name);
374                if !trimmed.contains(&pattern) {
375                    continue;
376                }
377
378                // For generic method names, require a client variable prefix
379                // (e.g., "policy_client.check(" or "model_client.load(")
380                if is_generic && !has_client_prefix(trimmed, method_name) {
381                    continue;
382                }
383
384                // Disambiguate: figure out which client type is being called.
385                if let Some(target_service) =
386                    resolve_call_target(trimmed, method_name, defs, &caller)
387                {
388                    calls.push(MethodCall {
389                        caller: caller.clone(),
390                        target_service,
391                        target_method: method_name.clone(),
392                        source_file: relative.clone(),
393                        line: line_num + 1,
394                    });
395                }
396            }
397        }
398    });
399
400    // Deduplicate (same caller → same target method, keep first occurrence)
401    calls.sort();
402    calls.dedup_by(|a, b| {
403        a.caller == b.caller
404            && a.target_service == b.target_service
405            && a.target_method == b.target_method
406    });
407
408    calls
409}
410
411/// Check if a line has a known client variable prefix before the method call.
412/// Matches patterns like: policy_client.check(, model_client.load(, registry.list(
413fn has_client_prefix(line: &str, method_name: &str) -> bool {
414    let pattern = format!(".{}(", method_name);
415    let pos = match line.find(&pattern) {
416        Some(p) => p,
417        None => return false,
418    };
419
420    let before = &line[..pos];
421    let before_trimmed = before.trim_end();
422
423    // Known client variable patterns
424    const CLIENT_PREFIXES: &[&str] = &[
425        "policy_client",
426        "registry_client",
427        "model_client",
428        "worker_client",
429        "inference_client",
430        "discovery_client",
431        "tui_client",
432        "mcp_client",
433        // Short forms used in some code
434        "policy",
435        "registry",
436        "model",
437        "worker",
438        "inference",
439        "discovery",
440        // Scoped sub-clients
441        "worktree",
442        "repo",
443    ];
444
445    for prefix in CLIENT_PREFIXES {
446        if before_trimmed.ends_with(prefix) {
447            return true;
448        }
449    }
450    // Also match `.gen.infer(...).method(` and `.gen.ttt(...).method(`
451    // (these are internal dispatch, but we'll let resolve_call_target filter them)
452    if before_trimmed.ends_with(')') {
453        // Chained call like `.generate_stream(` after `.infer(model_ref)`
454        return true;
455    }
456    false
457}
458
459/// Resolve which service a method call targets based on context.
460fn resolve_call_target(
461    line: &str,
462    method_name: &str,
463    defs: &[&MethodDef],
464    caller: &str,
465) -> Option<String> {
466    // If only one service defines this method, it's unambiguous
467    if defs.len() == 1 {
468        let target = &defs[0].service;
469        // Don't report self-calls
470        if target == caller {
471            return None;
472        }
473        return Some(target.clone());
474    }
475
476    // Disambiguate by looking at what precedes .<method>(
477    // Common patterns:
478    //   policy_client.check(     → policy
479    //   registry_client.list(    → registry
480    //   model_client.load(       → model
481    //   self.gen.load(           → self (skip)
482    //   worker_client.stop(      → worker
483
484    let pattern = format!(".{}(", method_name);
485    let pos = match line.find(&pattern) {
486        Some(p) => p,
487        None => return None,
488    };
489
490    let before = &line[..pos];
491    let before_trimmed = before.trim_end();
492
493    // Extract the variable/expression before the dot
494    let var = before_trimmed
495        .rsplit(|c: char| !c.is_alphanumeric() && c != '_' && c != '.')
496        .next()
497        .unwrap_or("");
498
499    // self.gen calls are internal dispatch (not cross-service)
500    if var.contains("self.gen") || var.ends_with(".gen") {
501        return None;
502    }
503
504    // Match variable name to client type
505    for def in defs {
506        let target = &def.service;
507        if target == caller {
508            continue;
509        }
510        if var.contains("policy") && target == "policy" {
511            return Some(target.clone());
512        }
513        if var.contains("registry") && target == "registry" {
514            return Some(target.clone());
515        }
516        if var.contains("model") && target == "model" {
517            return Some(target.clone());
518        }
519        if var.contains("worker") && target == "worker" {
520            return Some(target.clone());
521        }
522        if var.contains("inference") && target == "inference" {
523            return Some(target.clone());
524        }
525        if var.contains("discovery") && target == "discovery" {
526            return Some(target.clone());
527        }
528    }
529
530    // Fallback: if caller is known to depend on a specific service, prefer that
531    None
532}
533
534/// Map a relative source path to a caller identity.
535fn path_to_caller(relative: &str) -> String {
536    // services/model.rs → model
537    // services/mcp_service.rs → mcp
538    // services/oauth/mod.rs → oauth
539    // cli/handlers.rs → cli:handlers
540    // cli/shell_handlers.rs → cli:shell
541    // server/routes/openai.rs → server:openai
542    // tui/service.rs → tui
543
544    if relative.starts_with("services/") {
545        let file = relative.trim_start_matches("services/");
546        if file.starts_with("oauth") {
547            return "oauth".to_string();
548        }
549        let stem = file.trim_end_matches(".rs").trim_end_matches("/mod");
550        return match stem {
551            "factories" | "mod" | "core" | "generated" | "worktree_helpers" | "rpc_types"
552            | "callback" => String::new(),
553            "mcp_service" => "mcp".to_string(),
554            "oai" => "oai".to_string(),
555            other => other.to_string(),
556        };
557    }
558
559    if relative.starts_with("cli/") {
560        let stem = relative.trim_start_matches("cli/").trim_end_matches(".rs");
561        return format!("cli:{}", stem.replace("_handlers", ""));
562    }
563
564    if relative.starts_with("server/") {
565        let stem = relative
566            .trim_start_matches("server/")
567            .trim_start_matches("routes/")
568            .trim_end_matches(".rs");
569        return format!("server:{stem}");
570    }
571
572    if relative.starts_with("tui/") {
573        return "tui".to_string();
574    }
575
576    String::new()
577}
578
579/// Recursively walk .rs files.
580fn walk_rs_files(dir: &Path, callback: &mut dyn FnMut(&Path)) {
581    let entries = match fs::read_dir(dir) {
582        Ok(e) => e,
583        Err(_) => return,
584    };
585
586    for entry in entries.flatten() {
587        let path = entry.path();
588        if path.is_dir() {
589            walk_rs_files(&path, callback);
590        } else if path.extension().map(|e| e == "rs").unwrap_or(false) {
591            callback(&path);
592        }
593    }
594}
595
596/// Generate the method-level call graph diagram.
597fn generate_call_graph(calls: &[MethodCall], method_registry: &[MethodDef]) -> String {
598    let mut out = String::new();
599
600    // Build a method scope lookup for coloring
601    let method_scope: BTreeMap<(&str, &str), &str> = method_registry
602        .iter()
603        .map(|m| ((m.service.as_str(), m.rust_name.as_str()), m.scope.as_str()))
604        .collect();
605
606    out.push_str("```mermaid\ngraph LR\n");
607
608    // Group calls by caller → target_service
609    let mut grouped: BTreeMap<(&str, &str), Vec<&str>> = BTreeMap::new();
610    for call in calls {
611        grouped
612            .entry((call.caller.as_str(), call.target_service.as_str()))
613            .or_default()
614            .push(call.target_method.as_str());
615    }
616
617    // Collect unique callers and target services as nodes
618    let mut callers: BTreeSet<&str> = BTreeSet::new();
619    let mut targets: BTreeSet<&str> = BTreeSet::new();
620    for ((caller, target), _) in &grouped {
621        callers.insert(caller);
622        targets.insert(target);
623    }
624
625    // Caller subgraphs (group by category)
626    let svc_callers: Vec<&&str> = callers.iter().filter(|c| !c.contains(':')).collect();
627    let cli_callers: Vec<&&str> = callers.iter().filter(|c| c.starts_with("cli:")).collect();
628    let server_callers: Vec<&&str> = callers
629        .iter()
630        .filter(|c| c.starts_with("server:"))
631        .collect();
632
633    if !svc_callers.is_empty() {
634        out.push_str("\n    subgraph svc_callers [\"Services\"]\n");
635        out.push_str("        direction TB\n");
636        for c in &svc_callers {
637            let id = caller_id(c);
638            out.push_str(&format!("        {id}[\"{}\"]\n", title_case(c)));
639        }
640        out.push_str("    end\n");
641    }
642
643    if !cli_callers.is_empty() {
644        out.push_str("\n    subgraph cli_callers [\"CLI\"]\n");
645        out.push_str("        direction TB\n");
646        for c in &cli_callers {
647            let id = caller_id(c);
648            let label = c.trim_start_matches("cli:");
649            out.push_str(&format!("        {id}[\"cli:{label}\"]\n"));
650        }
651        out.push_str("    end\n");
652    }
653
654    if !server_callers.is_empty() {
655        out.push_str("\n    subgraph server_callers [\"HTTP Routes\"]\n");
656        out.push_str("        direction TB\n");
657        for c in &server_callers {
658            let id = caller_id(c);
659            let label = c.trim_start_matches("server:");
660            out.push_str(&format!("        {id}[\"server:{label}\"]\n"));
661        }
662        out.push_str("    end\n");
663    }
664
665    // Target service + method nodes
666    for target in &targets {
667        out.push_str(&format!(
668            "\n    subgraph {target}_methods [\"{} Methods\"]\n",
669            title_case(target)
670        ));
671        out.push_str("        direction TB\n");
672
673        // Collect all methods called on this target
674        let mut called_methods: BTreeSet<&str> = BTreeSet::new();
675        for ((_, t), methods) in &grouped {
676            if t == target {
677                for m in methods {
678                    called_methods.insert(m);
679                }
680            }
681        }
682
683        for method in &called_methods {
684            let node_id = format!("{target}_{method}");
685            let scope = method_scope.get(&(target, method)).copied().unwrap_or("");
686            let scope_suffix = if scope.is_empty() {
687                String::new()
688            } else {
689                format!(" [{scope}]")
690            };
691            out.push_str(&format!("        {node_id}[\"{method}{scope_suffix}\"]\n"));
692        }
693        out.push_str("    end\n");
694    }
695
696    // Edges
697    out.push_str("\n    %% Method-level calls\n");
698    for ((caller, target), methods) in &grouped {
699        let caller_node = caller_id(caller);
700        for method in methods {
701            let target_node = format!("{target}_{method}");
702            out.push_str(&format!("    {caller_node} --> {target_node}\n"));
703        }
704    }
705
706    out.push_str("```\n");
707    out
708}
709
710/// Generate a stable node ID from a caller string.
711fn caller_id(caller: &str) -> String {
712    caller.replace(':', "_").replace('.', "_")
713}
714
715// ── Schema metadata parsing ─────────────────────────────────────────────────
716
717fn parse_metadata(path: &Path) -> Option<(String, usize, BTreeMap<String, usize>)> {
718    let content = fs::read_to_string(path).ok()?;
719    let json: serde_json::Value = serde_json::from_str(&content).ok()?;
720
721    let service = json.get("service")?.as_str()?.to_string();
722    let mut methods = 0usize;
723    let mut scopes = BTreeMap::new();
724
725    for s in json.get("structs")?.as_array()? {
726        for field in s
727            .get("fields")
728            .and_then(|f| f.as_array())
729            .into_iter()
730            .flatten()
731        {
732            for ann in field
733                .get("annotations")
734                .and_then(|a| a.as_array())
735                .into_iter()
736                .flatten()
737            {
738                if matches!(
739                    ann.get("name").and_then(|n| n.as_str()),
740                    Some("scope") | Some("capability")
741                ) {
742                    methods += 1;
743                    let scope = ann
744                        .get("value")
745                        .and_then(|v| {
746                            v.as_object()
747                                .and_then(|o| o.get("enum_ordinal"))
748                                .and_then(|o| o.as_u64())
749                                .map(|ord| scope_name(ord).to_string())
750                                .or_else(|| v.as_str().map(String::from))
751                        })
752                        .unwrap_or_else(|| "unknown".into());
753                    *scopes.entry(scope).or_insert(0) += 1;
754                }
755            }
756        }
757    }
758
759    Some((service, methods, scopes))
760}
761
762// ── Factory scanning ────────────────────────────────────────────────────────
763
764/// Parse factories.rs to extract service registrations with transport + QUIC.
765fn scan_factories(factories_path: &Path) -> Vec<ServiceMeta> {
766    let content = match fs::read_to_string(factories_path) {
767        Ok(c) => c,
768        Err(e) => {
769            eprintln!("Warning: cannot read {}: {e}", factories_path.display());
770            return Vec::new();
771        }
772    };
773
774    let mut services = Vec::new();
775    let lines: Vec<&str> = content.lines().collect();
776
777    let mut i = 0;
778    while i < lines.len() {
779        let line = lines[i].trim();
780
781        // Detect #[service_factory("name"...)]
782        if line.starts_with("#[service_factory(") {
783            if let Some(name) = extract_quoted(line) {
784                // Scan the function body to determine transport + QUIC
785                let (transport, has_quic) = scan_factory_body(&lines, i + 1);
786                services.push(ServiceMeta {
787                    name,
788                    transport,
789                    methods: 0,
790                    scopes: BTreeMap::new(),
791                    dependencies: BTreeSet::new(),
792                    has_quic,
793                });
794            }
795        }
796        i += 1;
797    }
798
799    // Also scan factories.rs itself for client usage per factory function.
800    // We split by factory boundaries and detect clients within each.
801    scan_factory_dependencies(&content, &mut services);
802
803    services
804}
805
806/// Extract the first quoted string from a line.
807fn extract_quoted(line: &str) -> Option<String> {
808    let start = line.find('"')? + 1;
809    let end = line[start..].find('"')? + start;
810    Some(line[start..end].to_string())
811}
812
813/// Scan a factory function body to detect transport type and QUIC support.
814fn scan_factory_body(lines: &[&str], start: usize) -> (Transport, bool) {
815    let mut transport = Transport::RpcReqRep;
816    let mut has_quic = false;
817    let mut brace_depth = 0;
818    let mut in_body = false;
819
820    for line in &lines[start..] {
821        let trimmed = line.trim();
822
823        for ch in trimmed.chars() {
824            if ch == '{' {
825                brace_depth += 1;
826                in_body = true;
827            }
828            if ch == '}' {
829                brace_depth -= 1;
830            }
831        }
832
833        if in_body {
834            if trimmed.contains("into_spawnable_quic") {
835                has_quic = true;
836            }
837            if trimmed.contains("ProxyService")
838                || trimmed.contains("XPubProxy")
839                || trimmed.contains("PullToXPub")
840            {
841                transport = Transport::Proxy;
842            }
843            if trimmed.contains("OAIService")
844                || trimmed.contains("ServerState")
845                || trimmed.contains("FlightService")
846                || trimmed.contains("OAuthService")
847                || trimmed.contains("axum")
848                || trimmed.contains("Axum")
849                || trimmed.contains("FlightSqlService")
850            {
851                transport = Transport::Http;
852            }
853
854            if brace_depth == 0 {
855                break;
856            }
857        }
858    }
859
860    (transport, has_quic)
861}
862
863/// Scan factories.rs to detect which clients each factory function creates.
864fn scan_factory_dependencies(content: &str, services: &mut [ServiceMeta]) {
865    // Split content into factory function blocks.
866    // Each block starts at #[service_factory and ends at the next one (or EOF).
867    let lines: Vec<&str> = content.lines().collect();
868    let mut factory_ranges: Vec<(String, usize, usize)> = Vec::new();
869
870    for (i, line) in lines.iter().enumerate() {
871        if line.trim().starts_with("#[service_factory(") {
872            if let Some(name) = extract_quoted(line.trim()) {
873                // Close previous range
874                if let Some(last) = factory_ranges.last_mut() {
875                    last.2 = i;
876                }
877                factory_ranges.push((name, i, lines.len()));
878            }
879        }
880    }
881
882    for (name, start, end) in &factory_ranges {
883        let block: String = lines[*start..*end].join("\n");
884        let svc = match services.iter_mut().find(|s| &s.name == name) {
885            Some(s) => s,
886            None => continue,
887        };
888
889        for client_type in CLIENT_TYPES {
890            if block.contains(client_type) {
891                if let Some(target) = client_to_service(client_type) {
892                    // Don't add self-dependency
893                    if target != svc.name {
894                        svc.dependencies.insert(DepEdge {
895                            target: target.to_string(),
896                            client_type: client_type.to_string(),
897                        });
898                    }
899                }
900            }
901        }
902    }
903}
904
905// ── Service source scanning ─────────────────────────────────────────────────
906
907/// Scan services/*.rs files for client type usage to build call graph.
908fn scan_service_sources(services_dir: &Path, services: &mut [ServiceMeta]) {
909    let scan_dir = |dir: &Path| {
910        let entries = match fs::read_dir(dir) {
911            Ok(e) => e,
912            Err(_) => return Vec::new(),
913        };
914
915        let mut results: Vec<(String, BTreeSet<DepEdge>)> = Vec::new();
916
917        for entry in entries.flatten() {
918            let path = entry.path();
919
920            if path.is_dir() {
921                // Handle subdirectories like oauth/
922                let dirname = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
923                let service_name = match dirname {
924                    "oauth" => "oauth",
925                    _ => continue,
926                };
927
928                // Scan all .rs files in the subdirectory
929                let mut deps = BTreeSet::new();
930                if let Ok(sub_entries) = fs::read_dir(&path) {
931                    for sub_entry in sub_entries.flatten() {
932                        let sub_path = sub_entry.path();
933                        if sub_path.extension().map(|e| e == "rs").unwrap_or(false) {
934                            if let Ok(content) = fs::read_to_string(&sub_path) {
935                                find_client_deps(&content, service_name, &mut deps);
936                            }
937                        }
938                    }
939                }
940                if !deps.is_empty() {
941                    results.push((service_name.to_string(), deps));
942                }
943                continue;
944            }
945
946            if path.extension().map(|e| e == "rs").unwrap_or(false) {
947                let filename = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
948
949                let service_name = match filename_to_service(filename) {
950                    Some(name) => name,
951                    None => continue,
952                };
953
954                let content = match fs::read_to_string(&path) {
955                    Ok(c) => c,
956                    Err(_) => continue,
957                };
958
959                let mut deps = BTreeSet::new();
960                find_client_deps(&content, service_name, &mut deps);
961
962                if !deps.is_empty() {
963                    results.push((service_name.to_string(), deps));
964                }
965            }
966        }
967        results
968    };
969
970    let mut all_deps = scan_dir(services_dir);
971
972    // Also scan tui/ directory for TUI service dependencies
973    let tui_dir = services_dir.parent().map(|p| p.join("tui"));
974    if let Some(ref td) = tui_dir {
975        if td.is_dir() {
976            let mut tui_deps = BTreeSet::new();
977            walk_rs_files(td, &mut |path| {
978                if let Ok(content) = fs::read_to_string(path) {
979                    find_client_deps(&content, "tui", &mut tui_deps);
980                }
981            });
982            if !tui_deps.is_empty() {
983                all_deps.push(("tui".to_string(), tui_deps));
984            }
985        }
986    }
987
988    // Merge discovered deps into service metadata
989    for (svc_name, deps) in all_deps {
990        if let Some(svc) = services.iter_mut().find(|s| s.name == svc_name) {
991            for dep in deps {
992                svc.dependencies.insert(dep);
993            }
994        }
995    }
996}
997
998/// Find client type references in a source file.
999fn find_client_deps(content: &str, service_name: &str, deps: &mut BTreeSet<DepEdge>) {
1000    for client_type in CLIENT_TYPES {
1001        if content.contains(client_type) {
1002            if let Some(target) = client_to_service(client_type) {
1003                if target != service_name {
1004                    deps.insert(DepEdge {
1005                        target: target.to_string(),
1006                        client_type: client_type.to_string(),
1007                    });
1008                }
1009            }
1010        }
1011    }
1012}
1013
1014// ── Diagram generation ──────────────────────────────────────────────────────
1015
1016fn generate_topology(services: &[ServiceMeta]) -> String {
1017    let mut out = String::new();
1018
1019    out.push_str("```mermaid\n");
1020    out.push_str("---\nconfig:\n  layout: elk\n  elk:\n    mergeEdges: true\n    nodePlacementStrategy: NETWORK_SIMPLEX\n---\n");
1021    out.push_str("graph TD\n\n");
1022
1023    // Group by transport
1024    let http: Vec<&ServiceMeta> = services
1025        .iter()
1026        .filter(|s| s.transport == Transport::Http)
1027        .collect();
1028    let rpc_services: Vec<&ServiceMeta> = services
1029        .iter()
1030        .filter(|s| s.transport == Transport::RpcReqRep)
1031        .collect();
1032    let proxies: Vec<&ServiceMeta> = services
1033        .iter()
1034        .filter(|s| s.transport == Transport::Proxy)
1035        .collect();
1036
1037    // HTTP subgraph
1038    if !http.is_empty() {
1039        out.push_str("    subgraph http [\"HTTP Services\"]\n");
1040        out.push_str("        direction LR\n");
1041        for s in &http {
1042            out.push_str(&format!("        {}[\"{}\"]\n", s.name, service_label(s)));
1043        }
1044        out.push_str("    end\n\n");
1045    }
1046
1047    // RPC subgraph
1048    if !rpc_services.is_empty() {
1049        out.push_str("    subgraph rpc_services [\"RPC Services\"]\n");
1050        out.push_str("        direction LR\n");
1051        for s in &rpc_services {
1052            out.push_str(&format!("        {}[\"{}\"]\n", s.name, service_label(s)));
1053        }
1054        out.push_str("    end\n\n");
1055    }
1056
1057    // Proxy subgraph
1058    if !proxies.is_empty() {
1059        out.push_str("    subgraph proxies [\"Proxy Services\"]\n");
1060        out.push_str("        direction LR\n");
1061        for s in &proxies {
1062            out.push_str(&format!("        {}[\"{}\"]\n", s.name, service_label(s)));
1063        }
1064        out.push_str("    end\n\n");
1065    }
1066
1067    // Special: ModelService spawns InferenceService
1068    if services.iter().any(|s| s.name == "model") {
1069        out.push_str("    %% ModelService spawns InferenceService per loaded model\n");
1070        out.push_str("    model -->|\"spawns per model\"| inference\n\n");
1071    }
1072
1073    // Dependency edges
1074    out.push_str("    %% Auto-detected service dependencies\n");
1075    for svc in services {
1076        // Group deps by target, collect client types
1077        let mut target_clients: BTreeMap<&str, Vec<&str>> = BTreeMap::new();
1078        for dep in &svc.dependencies {
1079            target_clients
1080                .entry(dep.target.as_str())
1081                .or_default()
1082                .push(dep.client_type.as_str());
1083        }
1084
1085        for (target, clients) in &target_clients {
1086            let is_stream = clients
1087                .iter()
1088                .any(|c| *c == "StreamChannel" || *c == "StreamInfo");
1089            let is_policy = *target == "policy" && clients.iter().any(|c| *c == "PolicyClient");
1090            let has_other = clients
1091                .iter()
1092                .any(|c| *c != "StreamChannel" && *c != "StreamInfo" && *c != "PolicyClient");
1093
1094            // Policy: dashed line with "authorize" label
1095            if is_policy {
1096                out.push_str(&format!(
1097                    "    {} -.->|\"authorize\"| {}\n",
1098                    svc.name, target
1099                ));
1100            }
1101
1102            // Streaming: thick arrow
1103            if is_stream {
1104                let stream_types: Vec<&str> = clients
1105                    .iter()
1106                    .filter(|c| **c == "StreamChannel" || **c == "StreamInfo")
1107                    .copied()
1108                    .collect();
1109                let label = stream_types.join(", ");
1110                out.push_str(&format!("    {} ==>|\"{}\"| {}\n", svc.name, label, target));
1111            }
1112
1113            // Other deps: normal arrow with client type labels
1114            if has_other {
1115                let other_clients: Vec<&str> = clients
1116                    .iter()
1117                    .filter(|c| {
1118                        **c != "StreamChannel" && **c != "StreamInfo" && **c != "PolicyClient"
1119                    })
1120                    .copied()
1121                    .collect();
1122                if !other_clients.is_empty() {
1123                    let label = other_clients.join(", ");
1124                    out.push_str(&format!("    {} -->|\"{}\"| {}\n", svc.name, label, target));
1125                }
1126            }
1127        }
1128    }
1129
1130    out.push_str("```\n");
1131    out
1132}
1133
1134fn service_label(s: &ServiceMeta) -> String {
1135    let mut label = title_case(&s.name);
1136    if s.methods > 0 || s.has_quic {
1137        let mut parts = Vec::new();
1138        if s.methods > 0 {
1139            parts.push(format!("{} methods", s.methods));
1140        }
1141        if s.has_quic {
1142            parts.push("QUIC".to_string());
1143        }
1144        label.push_str(&format!("<br/>{}", parts.join(" · ")));
1145    }
1146    if !s.scopes.is_empty() {
1147        let scope_str: Vec<String> = s.scopes.iter().map(|(k, v)| format!("{k}:{v}")).collect();
1148        label.push_str(&format!("<br/>{}", scope_str.join(" · ")));
1149    }
1150    label
1151}
1152
1153fn generate_method_breakdown(services: &[ServiceMeta]) -> String {
1154    let mut out = String::new();
1155    out.push_str("```mermaid\ngraph LR\n\n");
1156
1157    for s in services {
1158        if s.methods == 0 {
1159            continue;
1160        }
1161
1162        let id = &s.name;
1163        out.push_str(&format!(
1164            "    subgraph {id}_svc [\"{} · {} · {} methods\"]\n",
1165            title_case(&s.name),
1166            s.transport.label(),
1167            s.methods
1168        ));
1169        out.push_str("        direction TB\n");
1170
1171        for (scope, count) in &s.scopes {
1172            out.push_str(&format!("        {id}_{scope}[\"{scope}: {count}\"]\n"));
1173        }
1174
1175        if s.has_quic {
1176            out.push_str(&format!("        {id}_quic[\"QUIC\"]\n"));
1177            out.push_str(&format!(
1178                "        style {id}_quic fill:#2d8a4e,stroke:#333,color:#fff\n"
1179            ));
1180        }
1181
1182        out.push_str("    end\n\n");
1183    }
1184
1185    out.push_str("```\n");
1186    out
1187}
1188
1189fn generate_summary_table(services: &[ServiceMeta]) -> String {
1190    let mut out = String::new();
1191    out.push_str("| Service | Transport | QUIC | Methods | Scopes | Dependencies |\n");
1192    out.push_str("|---------|-----------|------|---------|--------|--------------|\n");
1193
1194    for s in services {
1195        let quic = if s.has_quic { "yes" } else { "-" };
1196        let methods = if s.methods > 0 {
1197            s.methods.to_string()
1198        } else {
1199            "0".to_string()
1200        };
1201        let scopes = if s.scopes.is_empty() {
1202            "-".to_string()
1203        } else {
1204            s.scopes
1205                .iter()
1206                .map(|(k, v)| format!("{k}:{v}"))
1207                .collect::<Vec<_>>()
1208                .join(" · ")
1209        };
1210        let deps = if s.dependencies.is_empty() {
1211            "-".to_string()
1212        } else {
1213            let mut targets: BTreeSet<&str> = BTreeSet::new();
1214            for dep in &s.dependencies {
1215                targets.insert(&dep.target);
1216            }
1217            targets.into_iter().collect::<Vec<_>>().join(", ")
1218        };
1219
1220        out.push_str(&format!(
1221            "| **{}** | {} | {} | {} | {} | {} |\n",
1222            title_case(&s.name),
1223            s.transport.label(),
1224            quic,
1225            methods,
1226            scopes,
1227            deps
1228        ));
1229    }
1230
1231    out
1232}
1233
1234// ── Main ─────────────────────────────────────────────────────────────────────
1235
1236fn main() {
1237    let matches = clap::Command::new("generate-rpc-diagrams")
1238        .about("Generate Mermaid architecture diagrams from Cap'n Proto metadata")
1239        .arg(
1240            clap::Arg::new("metadata-dir")
1241                .long("metadata-dir")
1242                .help("Directory containing *_metadata.json files")
1243                .default_value("target/rpc-metadata"),
1244        )
1245        .arg(
1246            clap::Arg::new("services-dir")
1247                .long("services-dir")
1248                .help("Path to services/ source directory")
1249                .default_value("crates/hyprstream/src/services"),
1250        )
1251        .arg(
1252            clap::Arg::new("src-root")
1253                .long("src-root")
1254                .help("Root source directory for method-level call scanning")
1255                .default_value("crates/hyprstream/src"),
1256        )
1257        .arg(
1258            clap::Arg::new("output")
1259                .short('o')
1260                .long("output")
1261                .help("Output file path (default: stdout)"),
1262        )
1263        .get_matches();
1264
1265    let metadata_dir = PathBuf::from(matches.get_one::<String>("metadata-dir").unwrap());
1266    let services_dir = PathBuf::from(matches.get_one::<String>("services-dir").unwrap());
1267    let src_root = PathBuf::from(matches.get_one::<String>("src-root").unwrap());
1268
1269    // 1. Scan factories for service registrations
1270    let factories_path = services_dir.join("factories.rs");
1271    let mut services = scan_factories(&factories_path);
1272
1273    // 2. Merge schema metadata (method counts + scopes)
1274    if metadata_dir.is_dir() {
1275        if let Ok(entries) = fs::read_dir(&metadata_dir) {
1276            for entry in entries.flatten() {
1277                let path = entry.path();
1278                let is_metadata = path
1279                    .file_name()
1280                    .map(|n| n.to_string_lossy().ends_with("_metadata.json"))
1281                    .unwrap_or(false);
1282                if !is_metadata {
1283                    continue;
1284                }
1285
1286                if let Some((name, methods, scopes)) = parse_metadata(&path) {
1287                    if let Some(svc) = services.iter_mut().find(|s| s.name == name) {
1288                        svc.methods = methods;
1289                        svc.scopes = scopes;
1290                    }
1291                }
1292            }
1293        }
1294    } else {
1295        eprintln!(
1296            "Warning: metadata dir {} not found, method counts will be zero",
1297            metadata_dir.display()
1298        );
1299    }
1300
1301    // 3. Scan service sources for client dependencies
1302    scan_service_sources(&services_dir, &mut services);
1303
1304    // Sort services by name
1305    services.sort_by(|a, b| a.name.cmp(&b.name));
1306
1307    // 4. Build method registry and scan for method-level calls
1308    let method_registry = build_method_registry(&metadata_dir);
1309    let method_calls = scan_method_calls(&src_root, &method_registry);
1310
1311    // 5. Generate output
1312    let mut output = String::new();
1313    output.push_str("# HyprStream RPC Service Architecture\n\n");
1314    output.push_str("<!-- Auto-generated by `cargo run --bin generate-rpc-diagrams` -->\n");
1315    output.push_str("<!-- Do not edit manually. Regenerate after schema changes. -->\n\n");
1316
1317    output.push_str("## Service Topology\n\n");
1318    output.push_str(&generate_topology(&services));
1319
1320    output.push_str("\n## Service Method Breakdown\n\n");
1321    output.push_str(&generate_method_breakdown(&services));
1322
1323    if !method_calls.is_empty() {
1324        output.push_str("\n## Method-Level Call Graph\n\n");
1325        output.push_str(&generate_call_graph(&method_calls, &method_registry));
1326    }
1327
1328    output.push_str("\n## Service Summary\n\n");
1329    output.push_str(&generate_summary_table(&services));
1330
1331    // Write output
1332    if let Some(out_path) = matches.get_one::<String>("output") {
1333        match fs::write(out_path, &output) {
1334            Ok(_) => eprintln!("Written to {out_path}"),
1335            Err(e) => eprintln!("Error writing {out_path}: {e}"),
1336        }
1337    } else {
1338        print!("{output}");
1339    }
1340
1341    // Print stats
1342    eprintln!("\n--- Stats ---");
1343    eprintln!("Services: {}", services.len());
1344    eprintln!(
1345        "Dependency edges: {}",
1346        services.iter().map(|s| s.dependencies.len()).sum::<usize>()
1347    );
1348    eprintln!("Schema methods: {}", method_registry.len());
1349    eprintln!("Method-level calls: {}", method_calls.len());
1350}