1#![allow(clippy::all, clippy::pedantic, clippy::restriction, dead_code)]
13
14use std::collections::{BTreeMap, BTreeSet};
15use std::fs;
16use std::path::{Path, PathBuf};
17
18fn 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
76fn 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"), "RepositoryClient" => Some("registry"), "CtlClient" => Some("registry"), "DiscoveryClient" => Some("discovery"),
89 "WorkerClient" => Some("worker"),
90 "StreamChannel" => Some("streams"),
93 "StreamInfo" => Some("streams"),
94 _ => None,
95 }
96}
97
98const CLIENT_TYPES: &[&str] = &[
100 "PolicyClient",
101 "RegistryClient",
102 "ModelClient",
103 "InferenceClient",
104 "WorktreeClient",
105 "RepositoryClient",
106 "CtlClient",
107 "DiscoveryClient",
108 "WorkerClient",
109 "StreamChannel",
111 "StreamInfo",
112];
113
114fn filename_to_service(filename: &str) -> Option<&'static str> {
118 match filename {
119 "factories.rs" => None, "mod.rs" | "core.rs" | "generated.rs" => None, "worktree_helpers.rs" => None, "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 if filename.starts_with("oauth") {
137 Some("oauth")
138 } else {
139 None
140 }
141 }
142 }
143}
144
145#[derive(Debug, Clone)]
149struct MethodDef {
150 schema_name: String,
152 rust_name: String,
154 scope: String,
156 description: String,
158 service: String,
160 parent: String,
162}
163
164#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd)]
166struct MethodCall {
167 caller: String,
169 target_service: String,
171 target_method: String,
173 source_file: String,
175 line: usize,
177}
178
179fn 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
195fn 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; }
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
301fn scan_method_calls(src_root: &Path, method_registry: &[MethodDef]) -> Vec<MethodCall> {
303 let mut calls = Vec::new();
304
305 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 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_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 let caller = path_to_caller(&relative);
354 if caller.is_empty() {
355 return;
356 }
357
358 for (line_num, line) in content.lines().enumerate() {
363 let trimmed = line.trim();
364 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 let pattern = format!(".{}(", method_name);
374 if !trimmed.contains(&pattern) {
375 continue;
376 }
377
378 if is_generic && !has_client_prefix(trimmed, method_name) {
381 continue;
382 }
383
384 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 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
411fn 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 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 "policy",
435 "registry",
436 "model",
437 "worker",
438 "inference",
439 "discovery",
440 "worktree",
442 "repo",
443 ];
444
445 for prefix in CLIENT_PREFIXES {
446 if before_trimmed.ends_with(prefix) {
447 return true;
448 }
449 }
450 if before_trimmed.ends_with(')') {
453 return true;
455 }
456 false
457}
458
459fn resolve_call_target(
461 line: &str,
462 method_name: &str,
463 defs: &[&MethodDef],
464 caller: &str,
465) -> Option<String> {
466 if defs.len() == 1 {
468 let target = &defs[0].service;
469 if target == caller {
471 return None;
472 }
473 return Some(target.clone());
474 }
475
476 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 let var = before_trimmed
495 .rsplit(|c: char| !c.is_alphanumeric() && c != '_' && c != '.')
496 .next()
497 .unwrap_or("");
498
499 if var.contains("self.gen") || var.ends_with(".gen") {
501 return None;
502 }
503
504 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 None
532}
533
534fn path_to_caller(relative: &str) -> String {
536 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
579fn 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
596fn generate_call_graph(calls: &[MethodCall], method_registry: &[MethodDef]) -> String {
598 let mut out = String::new();
599
600 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 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 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 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 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 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 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
710fn caller_id(caller: &str) -> String {
712 caller.replace(':', "_").replace('.', "_")
713}
714
715fn 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
762fn 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 if line.starts_with("#[service_factory(") {
783 if let Some(name) = extract_quoted(line) {
784 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 scan_factory_dependencies(&content, &mut services);
802
803 services
804}
805
806fn 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
813fn 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
863fn scan_factory_dependencies(content: &str, services: &mut [ServiceMeta]) {
865 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 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 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
905fn 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 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 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 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 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
998fn 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
1014fn 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 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 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 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 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 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 out.push_str(" %% Auto-detected service dependencies\n");
1075 for svc in services {
1076 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 if is_policy {
1096 out.push_str(&format!(
1097 " {} -.->|\"authorize\"| {}\n",
1098 svc.name, target
1099 ));
1100 }
1101
1102 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 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
1234fn 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 let factories_path = services_dir.join("factories.rs");
1271 let mut services = scan_factories(&factories_path);
1272
1273 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 scan_service_sources(&services_dir, &mut services);
1303
1304 services.sort_by(|a, b| a.name.cmp(&b.name));
1306
1307 let method_registry = build_method_registry(&metadata_dir);
1309 let method_calls = scan_method_calls(&src_root, &method_registry);
1310
1311 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 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 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}