1use std::collections::{BTreeMap, BTreeSet};
2
3use code_system_graph_model::{
4 Edge, EdgeId, EdgeKind, EpistemicStatus, Evidence, EvidenceId, Node, NodeId, NodeKind, Provenance, RepoId, stable_id
5};
6
7use crate::{
8 BoundaryRole, CallScope, DeclaredImplementation, DeclaredTestCase, HttpBoundary, SourceFramework, SourceLanguage, SourceObservation, SourceRole, SourceSymbolIdentity
9};
10
11#[derive(Debug, Clone, Default)]
13pub struct SourceGraphFacts {
14 pub boundaries: Vec<HttpBoundary>,
16 pub tests: Vec<DeclaredTestCase>,
18 pub implementations: Vec<DeclaredImplementation>,
20 pub standalone_test_nodes: Vec<Node>,
22 pub standalone_test_evidence: Vec<Evidence>,
24 pub relation_nodes: Vec<Node>,
26 pub relation_edges: Vec<Edge>,
28 pub relation_evidence: Vec<Evidence>,
30}
31
32#[must_use]
37#[expect(
38 clippy::too_many_lines,
39 reason = "One deterministic conversion pass keeps HTTP, test, and source relations aligned"
40)]
41pub fn source_observations_to_graph(
42 repo_id: &RepoId,
43 source_path: &str,
44 content_hash: &str,
45 observations: &[SourceObservation],
46) -> SourceGraphFacts {
47 let mut result = SourceGraphFacts::default();
48 let confirmed = observations
49 .iter()
50 .filter(|observation| observation.status == crate::SourceEpistemicStatus::Confirmed)
51 .collect::<Vec<_>>();
52 for observation in &confirmed {
53 match observation.role {
54 SourceRole::Provider | SourceRole::Consumer => {
55 let (Some(method), Some(path)) =
56 (observation.method.as_deref(), observation.path.as_deref())
57 else {
58 continue;
59 };
60 let boundary = source_boundary(
61 repo_id,
62 source_path,
63 content_hash,
64 observation,
65 method,
66 path,
67 );
68 if observation.role == SourceRole::Provider
69 && let Some(symbol) = observation.symbol_name.as_deref()
70 {
71 result.implementations.push(source_implementation(
72 repo_id,
73 source_path,
74 content_hash,
75 observation,
76 symbol,
77 method,
78 path,
79 ));
80 }
81 if observation.role == SourceRole::Consumer
82 && let (Some(symbol), Some(line)) = (
83 observation.symbol_name.as_deref(),
84 observation.symbol_start_line,
85 )
86 {
87 let identity = SourceSymbolIdentity::new(
88 repo_id.clone(),
89 language_name(observation.language),
90 source_path,
91 symbol,
92 );
93 let caller = identity.at_declaration(line).node(symbol);
94 let edge_key = format!(
95 "{}:consumes:{}:{}",
96 caller.id.as_str(),
97 boundary.node.id.as_str(),
98 observation.lines.start
99 );
100 result.relation_edges.push(Edge {
101 id: EdgeId::new(stable_id("edge", &edge_key)),
102 source: caller.id.clone(),
103 target: boundary.node.id.clone(),
104 kind: EdgeKind::Consumes,
105 confidence: observation.confidence,
106 status: EpistemicStatus::Confirmed,
107 evidence: vec![boundary.evidence.id.clone()],
108 });
109 result.relation_nodes.push(caller);
110 result.relation_evidence.push(boundary.evidence.clone());
111 }
112 result.boundaries.push(boundary);
113 }
114 SourceRole::Factory => {
115 let (Some(symbol), Some(related_symbol)) = (
116 observation.symbol_name.as_deref(),
117 observation.related_symbol.as_deref(),
118 ) else {
119 continue;
120 };
121 let (nodes, edge, evidence) = source_factory_relation(
122 repo_id,
123 source_path,
124 content_hash,
125 observation,
126 symbol,
127 related_symbol,
128 );
129 result.relation_nodes.extend(nodes);
130 result.relation_edges.push(edge);
131 result.relation_evidence.push(evidence);
132 }
133 SourceRole::Test | SourceRole::Mount | SourceRole::Call | SourceRole::Client => {}
134 }
135 }
136
137 let consumers_by_symbol = confirmed
138 .iter()
139 .filter(|observation| observation.role == SourceRole::Consumer)
140 .filter_map(|observation| {
141 Some((
142 observation.symbol_name.as_deref()?,
143 observation.method.as_deref()?,
144 observation.path.as_deref()?,
145 observation.authority.as_deref(),
146 observation.framework.is_in_process_client(),
147 ))
148 })
149 .fold(
150 BTreeMap::<&str, BTreeSet<(&str, &str, Option<&str>, bool)>>::new(),
151 |mut grouped, (symbol, method, path, authority, in_process)| {
152 grouped
153 .entry(symbol)
154 .or_default()
155 .insert((method, path, authority, in_process));
156 grouped
157 },
158 );
159 for observation in confirmed
160 .iter()
161 .filter(|observation| observation.role == SourceRole::Test)
162 {
163 let Some(symbol) = observation.symbol_name.as_deref() else {
164 continue;
165 };
166 if let Some(targets) = consumers_by_symbol.get(symbol) {
167 result
168 .tests
169 .extend(targets.iter().map(|(method, path, authority, in_process)| {
170 source_test_case(
171 repo_id,
172 source_path,
173 content_hash,
174 observation,
175 symbol,
176 (method, path),
177 call_scope(*authority, *in_process),
178 )
179 }));
180 } else {
181 let (node, evidence) =
182 standalone_test(repo_id, source_path, content_hash, observation, symbol);
183 result.standalone_test_nodes.push(node);
184 result.standalone_test_evidence.push(evidence);
185 }
186 }
187 finish_source_graph(&mut result);
188 result
189}
190
191fn finish_source_graph(result: &mut SourceGraphFacts) {
192 result.boundaries.sort_by(|left, right| {
193 (&left.path, &left.method, left.role as u8, &left.node.id).cmp(&(
194 &right.path,
195 &right.method,
196 right.role as u8,
197 &right.node.id,
198 ))
199 });
200 result
201 .implementations
202 .sort_by(|left, right| left.node.id.cmp(&right.node.id));
203 result.tests.sort_by(|left, right| {
204 (&left.node.id, &left.method, &left.path).cmp(&(&right.node.id, &right.method, &right.path))
205 });
206 result
207 .standalone_test_nodes
208 .sort_by(|left, right| left.id.cmp(&right.id));
209 result
210 .standalone_test_evidence
211 .sort_by(|left, right| left.id.cmp(&right.id));
212 result
213 .relation_nodes
214 .sort_by(|left, right| left.id.cmp(&right.id));
215 result
216 .relation_nodes
217 .dedup_by(|left, right| left.id == right.id);
218 result
219 .relation_edges
220 .sort_by(|left, right| left.id.cmp(&right.id));
221 result
222 .relation_edges
223 .dedup_by(|left, right| left.id == right.id);
224 result
225 .relation_evidence
226 .sort_by(|left, right| left.id.cmp(&right.id));
227 result
228 .relation_evidence
229 .dedup_by(|left, right| left.id == right.id);
230}
231
232fn source_boundary(
233 repo_id: &RepoId,
234 source_path: &str,
235 content_hash: &str,
236 observation: &SourceObservation,
237 method: &str,
238 path: &str,
239) -> HttpBoundary {
240 let role = match observation.role {
241 SourceRole::Provider => BoundaryRole::Provider,
242 SourceRole::Consumer => BoundaryRole::Consumer,
243 SourceRole::Test
244 | SourceRole::Factory
245 | SourceRole::Mount
246 | SourceRole::Call
247 | SourceRole::Client => {
248 unreachable!("test and factory observations are not HTTP boundaries")
249 }
250 };
251 let role_key = match role {
252 BoundaryRole::Provider => "provider",
253 BoundaryRole::Consumer => "consumer",
254 };
255 let stable_key = format!(
256 "http:{}:{role_key}:{method}:{}",
257 repo_id.as_str(),
258 crate::canonical_route(path)
259 );
260 let evidence = source_evidence(
261 repo_id,
262 source_path,
263 content_hash,
264 observation,
265 &format!("{stable_key}:{}", observation.lines.start),
266 );
267 HttpBoundary {
268 node: Node {
269 id: NodeId::new(stable_id("node", &stable_key)),
270 kind: NodeKind::HttpOperation,
271 repo_id: Some(repo_id.clone()),
272 stable_key,
273 label: format!("{method} {path}"),
274 },
275 method: method.to_owned(),
276 path: path.to_owned(),
277 role,
278 scope: call_scope(
279 observation.authority.as_deref(),
280 observation.framework.is_in_process_client(),
281 ),
282 evidence,
283 }
284}
285
286fn call_scope(authority: Option<&str>, in_process: bool) -> CallScope {
287 if in_process {
288 return CallScope::InProcess;
289 }
290 match authority {
291 Some(authority) => CallScope::Authority(authority.to_owned()),
292 None => CallScope::Workspace,
293 }
294}
295
296fn source_implementation(
297 repo_id: &RepoId,
298 source_path: &str,
299 content_hash: &str,
300 observation: &SourceObservation,
301 symbol: &str,
302 method: &str,
303 path: &str,
304) -> DeclaredImplementation {
305 let identity = crate::SourceSymbolIdentity::new(
306 repo_id.clone(),
307 language_name(observation.language),
308 source_path,
309 symbol,
310 );
311 let stable_key = identity.stable_key();
312 DeclaredImplementation {
313 node: identity.node(format!("{}::{symbol}", language_name(observation.language))),
314 method: method.to_owned(),
315 path: path.to_owned(),
316 evidence: source_evidence(
317 repo_id,
318 source_path,
319 content_hash,
320 observation,
321 &format!(
322 "{stable_key}:{}:{}:{}",
323 framework_name(observation.framework),
324 observation.lines.start,
325 observation.lines.end
326 ),
327 ),
328 }
329}
330
331fn source_test_case(
332 repo_id: &RepoId,
333 source_path: &str,
334 content_hash: &str,
335 observation: &SourceObservation,
336 symbol: &str,
337 (method, path): (&str, &str),
338 scope: CallScope,
339) -> DeclaredTestCase {
340 let stable_key = test_stable_key(repo_id, source_path, observation, symbol);
341 DeclaredTestCase {
342 node: Node {
343 id: NodeId::new(stable_id("node", &stable_key)),
344 kind: NodeKind::TestCase,
345 repo_id: Some(repo_id.clone()),
346 stable_key: stable_key.clone(),
347 label: format!(
348 "{}/{}::{symbol}",
349 language_name(observation.language),
350 framework_name(observation.framework)
351 ),
352 },
353 method: method.to_owned(),
354 path: path.to_owned(),
355 scope,
356 evidence: source_evidence(
357 repo_id,
358 source_path,
359 content_hash,
360 observation,
361 &format!("{stable_key}:{method}:{path}"),
362 ),
363 }
364}
365
366fn standalone_test(
367 repo_id: &RepoId,
368 source_path: &str,
369 content_hash: &str,
370 observation: &SourceObservation,
371 symbol: &str,
372) -> (Node, Evidence) {
373 let stable_key = test_stable_key(repo_id, source_path, observation, symbol);
374 (
375 Node {
376 id: NodeId::new(stable_id("node", &stable_key)),
377 kind: NodeKind::TestCase,
378 repo_id: Some(repo_id.clone()),
379 stable_key: stable_key.clone(),
380 label: format!(
381 "{}/{}::{symbol}",
382 language_name(observation.language),
383 framework_name(observation.framework)
384 ),
385 },
386 source_evidence(repo_id, source_path, content_hash, observation, &stable_key),
387 )
388}
389
390fn source_factory_relation(
391 repo_id: &RepoId,
392 source_path: &str,
393 content_hash: &str,
394 observation: &SourceObservation,
395 factory_symbol: &str,
396 model_symbol: &str,
397) -> ([Node; 2], Edge, Evidence) {
398 let factory_identity =
399 SourceSymbolIdentity::new(repo_id.clone(), "python", source_path, factory_symbol);
400 let model_path = observation.related_path.as_deref().unwrap_or(source_path);
401 let model_identity =
402 SourceSymbolIdentity::new(repo_id.clone(), "python", model_path, model_symbol);
403 let factory_node = factory_identity.node(format!("python/factory-boy::{factory_symbol}"));
404 let model_node = model_identity.node(format!("python::{model_symbol}"));
405 let relation_key = format!(
406 "factory-model:{}:{}",
407 factory_node.id.as_str(),
408 model_node.id.as_str()
409 );
410 let evidence = source_evidence(
411 repo_id,
412 source_path,
413 content_hash,
414 observation,
415 &relation_key,
416 );
417 let edge = Edge {
418 id: EdgeId::new(stable_id("edge", &relation_key)),
419 source: factory_node.id.clone(),
420 target: model_node.id.clone(),
421 kind: EdgeKind::Consumes,
422 confidence: observation.confidence,
423 status: EpistemicStatus::Confirmed,
424 evidence: vec![evidence.id.clone()],
425 };
426 ([factory_node, model_node], edge, evidence)
427}
428
429fn test_stable_key(
430 repo_id: &RepoId,
431 source_path: &str,
432 observation: &SourceObservation,
433 symbol: &str,
434) -> String {
435 format!(
436 "test:{}:{}:{}:{source_path}:{symbol}",
437 repo_id.as_str(),
438 language_name(observation.language),
439 framework_name(observation.framework)
440 )
441}
442
443fn source_evidence(
444 repo_id: &RepoId,
445 source_path: &str,
446 content_hash: &str,
447 observation: &SourceObservation,
448 evidence_key: &str,
449) -> Evidence {
450 Evidence {
451 id: EvidenceId::new(stable_id("evidence", evidence_key)),
452 repo_id: Some(repo_id.clone()),
453 file_path: Some(source_path.to_owned()),
454 start_line: Some(observation.lines.start),
455 end_line: Some(observation.lines.end),
456 extractor: format!(
457 "code-system-graph.source.{}",
458 language_name(observation.language)
459 ),
460 extractor_version: "1.0.0".to_owned(),
461 provenance: Provenance::Extracted,
462 confidence: observation.confidence,
463 observed_at_commit: None,
464 content_hash: Some(content_hash.to_owned()),
465 note: Some(format!(
466 "{} {} syntax",
467 framework_name(observation.framework),
468 role_name(observation.role)
469 )),
470 }
471}
472
473fn language_name(language: SourceLanguage) -> &'static str {
474 match language {
475 SourceLanguage::JavaScript => "javascript",
476 SourceLanguage::TypeScript => "typescript",
477 SourceLanguage::Rust => "rust",
478 SourceLanguage::Python => "python",
479 SourceLanguage::Go => "go",
480 SourceLanguage::Java => "java",
481 }
482}
483
484fn framework_name(framework: SourceFramework) -> &'static str {
485 match framework {
486 SourceFramework::Fetch => "fetch",
487 SourceFramework::Axios => "axios",
488 SourceFramework::Express => "express",
489 SourceFramework::Fastify => "fastify",
490 SourceFramework::NestJs => "nestjs",
491 SourceFramework::NextJs => "nextjs",
492 SourceFramework::Axum => "axum",
493 SourceFramework::ActixWeb => "actix-web",
494 SourceFramework::Utoipa => "utoipa",
495 SourceFramework::Reqwest => "reqwest",
496 SourceFramework::RustTest => "rust-test",
497 SourceFramework::TokioTest => "tokio-test",
498 SourceFramework::Rstest => "rstest",
499 SourceFramework::FastApi => "fastapi",
500 SourceFramework::Flask => "flask",
501 SourceFramework::Requests => "requests",
502 SourceFramework::Httpx => "httpx",
503 SourceFramework::AioHttp => "aiohttp",
504 SourceFramework::PythonHttpRegistry => "python-http-registry",
505 SourceFramework::FactoryBoy => "factory-boy",
506 SourceFramework::Pytest => "pytest",
507 SourceFramework::Unittest => "unittest",
508 SourceFramework::PythonTest => "python-test",
509 SourceFramework::GoNetHttp => "net-http",
510 SourceFramework::Gin => "gin",
511 SourceFramework::Chi => "chi",
512 SourceFramework::SpringMvc => "spring-mvc",
513 SourceFramework::WebClient => "webclient",
514 SourceFramework::Feign => "feign",
515 SourceFramework::RestTemplate => "rest-template",
516 SourceFramework::TestClient => "test-client",
517 SourceFramework::FlaskTestClient => "flask-test-client",
518 SourceFramework::Jest => "jest",
519 SourceFramework::Vitest => "vitest",
520 SourceFramework::Mocha => "mocha",
521 SourceFramework::Playwright => "playwright",
522 SourceFramework::Supertest => "supertest",
523 SourceFramework::GoTest => "go-test",
524 SourceFramework::Httptest => "httptest",
525 SourceFramework::JUnit => "junit",
526 SourceFramework::MockMvc => "mockmvc",
527 SourceFramework::RestAssured => "rest-assured",
528 SourceFramework::WebTestClient => "webtestclient",
529 SourceFramework::TestRestTemplate => "test-rest-template",
530 SourceFramework::AxumOneshot => "axum-oneshot",
531 SourceFramework::ActixTest => "actix-test",
532 }
533}
534
535fn role_name(role: SourceRole) -> &'static str {
536 match role {
537 SourceRole::Provider => "provider",
538 SourceRole::Consumer => "consumer",
539 SourceRole::Test => "test",
540 SourceRole::Factory => "factory",
541 SourceRole::Mount => "mount",
542 SourceRole::Call => "call",
543 SourceRole::Client => "client",
544 }
545}
546
547#[cfg(test)]
548mod tests {
549
550 use code_system_graph_model::{EdgeKind, RepoId};
551
552 use super::source_observations_to_graph;
553 use crate::{AuthorityMap, link_http_routes, parse_python_source, parse_rust_source};
554
555 #[test]
556 fn same_named_consumers_keep_distinct_declaration_identities() {
557 let repo = RepoId::new("repo:client");
558 let examples = [
559 crate::parse_python_source(
560 "import requests\nclass A:\n def get(self):\n return requests.get('https://api/a')\nclass B:\n def get(self):\n return requests.get('https://api/b')\n",
561 ),
562 crate::parse_rust_source(
563 "impl A {\n fn get() { reqwest::get(\"https://api/a\"); }\n}\nimpl B {\n fn get() { reqwest::get(\"https://api/b\"); }\n}\n",
564 ),
565 crate::parse_typescript_source(
566 "class A {\n get() { return fetch('https://api/a'); }\n}\nclass B {\n get() { return fetch('https://api/b'); }\n}\n",
567 ),
568 crate::parse_python_source(
569 "import requests\ndef get():\n requests.get('https://api/a')\n def get():\n requests.get('https://api/b')\n",
570 ),
571 ];
572 for observations in examples {
573 let facts = source_observations_to_graph(&repo, "client", "hash", &observations);
574 let consumers = facts
575 .relation_edges
576 .iter()
577 .filter(|edge| edge.kind == EdgeKind::Consumes)
578 .collect::<Vec<_>>();
579 assert_eq!(consumers.len(), 2, "{observations:?}");
580 assert_ne!(consumers[0].source, consumers[1].source);
581 for node in &facts.relation_nodes {
582 let identity =
583 crate::SourceSymbolIdentity::from_node(node).expect("source identity");
584 assert_eq!(identity.symbol(), "get");
585 assert!(identity.declaration_line().is_some());
586 }
587 }
588 }
589
590 #[test]
591 fn source_graph_should_link_python_test_to_rust_handler() {
592 let rust = source_observations_to_graph(
593 &RepoId::new("repo:api"),
594 "src/routes.rs",
595 "rust-hash",
596 &parse_rust_source(
597 r#"use axum::{Router, routing::post}; Router::new().route("/orders", post(create_order));"#,
598 ),
599 );
600 let python = source_observations_to_graph(
601 &RepoId::new("repo:tests"),
602 "tests/test_orders.py",
603 "python-hash",
604 &parse_python_source(
605 r#"import requests
606def test_create_order():
607 requests.post("/orders")
608"#,
609 ),
610 );
611
612 let edges = link_http_routes(
613 &rust.boundaries,
614 &python.tests,
615 &rust.implementations,
616 &AuthorityMap::new(),
617 )
618 .edges;
619 let kinds = edges.iter().map(|edge| edge.kind).collect::<Vec<_>>();
620
621 assert_eq!(
622 (
623 kinds
624 .iter()
625 .filter(|kind| **kind == EdgeKind::Validates)
626 .count(),
627 kinds
628 .iter()
629 .filter(|kind| **kind == EdgeKind::ImplementedBy)
630 .count(),
631 ),
632 (1, 1)
633 );
634 }
635
636 #[test]
637 fn source_graph_should_link_factory_boy_factory_to_model() {
638 let facts = source_observations_to_graph(
639 &RepoId::new("repo:tests"),
640 "src/factories/AccountFactory.py",
641 "python-hash",
642 &parse_python_source(
643 r"import factory
644from src.clases.Account import Account
645
646class AccountFactory(factory.Factory):
647 class Meta:
648 model = Account
649",
650 ),
651 );
652
653 assert!(
654 facts.relation_nodes.len() == 2
655 && facts.relation_edges.len() == 1
656 && facts.relation_edges[0].kind == EdgeKind::Consumes
657 && facts
658 .relation_nodes
659 .iter()
660 .any(|node| node.label == "python/factory-boy::AccountFactory")
661 && facts
662 .relation_nodes
663 .iter()
664 .any(|node| node.stable_key.ends_with("src/clases/Account.py:Account"))
665 );
666 }
667}