Skip to main content

code_system_graph_core/
source_graph.rs

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/// Graph-ready facts derived from one focused Rust or Python source file.
12#[derive(Debug, Clone, Default)]
13pub struct SourceGraphFacts {
14    /// Exact HTTP provider and consumer boundaries.
15    pub boundaries: Vec<HttpBoundary>,
16    /// Tests paired with exact HTTP calls in the same test symbol.
17    pub tests: Vec<DeclaredTestCase>,
18    /// Exact provider implementation symbols.
19    pub implementations: Vec<DeclaredImplementation>,
20    /// Test nodes that have no exact HTTP target in the same symbol.
21    pub standalone_test_nodes: Vec<Node>,
22    /// Evidence for standalone test nodes.
23    pub standalone_test_evidence: Vec<Evidence>,
24    /// Factory and statically imported model symbols.
25    pub relation_nodes: Vec<Node>,
26    /// Direct source-level relationships such as Factory Boy `Meta.model`.
27    pub relation_edges: Vec<Edge>,
28    /// Evidence for direct source-level relationships.
29    pub relation_evidence: Vec<Evidence>,
30}
31
32/// Converts exact focused source observations into graph-ready facts.
33///
34/// Ambiguous and incomplete observations remain in the persisted extractor payload but are not
35/// promoted to factual graph nodes or links.
36#[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}