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, 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                result.boundaries.push(boundary);
82            }
83            SourceRole::Factory => {
84                let (Some(symbol), Some(related_symbol)) = (
85                    observation.symbol_name.as_deref(),
86                    observation.related_symbol.as_deref(),
87                ) else {
88                    continue;
89                };
90                let (nodes, edge, evidence) = source_factory_relation(
91                    repo_id,
92                    source_path,
93                    content_hash,
94                    observation,
95                    symbol,
96                    related_symbol,
97                );
98                result.relation_nodes.extend(nodes);
99                result.relation_edges.push(edge);
100                result.relation_evidence.push(evidence);
101            }
102            SourceRole::Test => {}
103        }
104    }
105
106    let consumers_by_symbol = confirmed
107        .iter()
108        .filter(|observation| observation.role == SourceRole::Consumer)
109        .filter_map(|observation| {
110            Some((
111                observation.symbol_name.as_deref()?,
112                observation.method.as_deref()?,
113                observation.path.as_deref()?,
114            ))
115        })
116        .fold(
117            BTreeMap::<&str, BTreeSet<(&str, &str)>>::new(),
118            |mut grouped, (symbol, method, path)| {
119                grouped.entry(symbol).or_default().insert((method, path));
120                grouped
121            },
122        );
123    for observation in confirmed
124        .iter()
125        .filter(|observation| observation.role == SourceRole::Test)
126    {
127        let Some(symbol) = observation.symbol_name.as_deref() else {
128            continue;
129        };
130        if let Some(targets) = consumers_by_symbol.get(symbol) {
131            result.tests.extend(targets.iter().map(|(method, path)| {
132                source_test_case(
133                    repo_id,
134                    source_path,
135                    content_hash,
136                    observation,
137                    symbol,
138                    method,
139                    path,
140                )
141            }));
142        } else {
143            let (node, evidence) =
144                standalone_test(repo_id, source_path, content_hash, observation, symbol);
145            result.standalone_test_nodes.push(node);
146            result.standalone_test_evidence.push(evidence);
147        }
148    }
149    finish_source_graph(&mut result);
150    result
151}
152
153fn finish_source_graph(result: &mut SourceGraphFacts) {
154    result.boundaries.sort_by(|left, right| {
155        (&left.path, &left.method, left.role as u8, &left.node.id).cmp(&(
156            &right.path,
157            &right.method,
158            right.role as u8,
159            &right.node.id,
160        ))
161    });
162    result
163        .implementations
164        .sort_by(|left, right| left.node.id.cmp(&right.node.id));
165    result.tests.sort_by(|left, right| {
166        (&left.node.id, &left.method, &left.path).cmp(&(&right.node.id, &right.method, &right.path))
167    });
168    result
169        .standalone_test_nodes
170        .sort_by(|left, right| left.id.cmp(&right.id));
171    result
172        .standalone_test_evidence
173        .sort_by(|left, right| left.id.cmp(&right.id));
174    result
175        .relation_nodes
176        .sort_by(|left, right| left.id.cmp(&right.id));
177    result
178        .relation_nodes
179        .dedup_by(|left, right| left.id == right.id);
180    result
181        .relation_edges
182        .sort_by(|left, right| left.id.cmp(&right.id));
183    result
184        .relation_edges
185        .dedup_by(|left, right| left.id == right.id);
186    result
187        .relation_evidence
188        .sort_by(|left, right| left.id.cmp(&right.id));
189    result
190        .relation_evidence
191        .dedup_by(|left, right| left.id == right.id);
192}
193
194fn source_boundary(
195    repo_id: &RepoId,
196    source_path: &str,
197    content_hash: &str,
198    observation: &SourceObservation,
199    method: &str,
200    path: &str,
201) -> HttpBoundary {
202    let role = match observation.role {
203        SourceRole::Provider => BoundaryRole::Provider,
204        SourceRole::Consumer => BoundaryRole::Consumer,
205        SourceRole::Test | SourceRole::Factory => {
206            unreachable!("test and factory observations are not HTTP boundaries")
207        }
208    };
209    let role_key = match role {
210        BoundaryRole::Provider => "provider",
211        BoundaryRole::Consumer => "consumer",
212    };
213    let stable_key = format!("http:{}:{role_key}:{method}:{path}", repo_id.as_str());
214    let evidence = source_evidence(
215        repo_id,
216        source_path,
217        content_hash,
218        observation,
219        &format!("{stable_key}:{}", observation.lines.start),
220    );
221    HttpBoundary {
222        node: Node {
223            id: NodeId::new(stable_id("node", &stable_key)),
224            kind: NodeKind::HttpOperation,
225            repo_id: Some(repo_id.clone()),
226            stable_key,
227            label: format!("{method} {path}"),
228        },
229        method: method.to_owned(),
230        path: path.to_owned(),
231        role,
232        evidence,
233    }
234}
235
236fn source_implementation(
237    repo_id: &RepoId,
238    source_path: &str,
239    content_hash: &str,
240    observation: &SourceObservation,
241    symbol: &str,
242    method: &str,
243    path: &str,
244) -> DeclaredImplementation {
245    let identity = crate::SourceSymbolIdentity::new(
246        repo_id.clone(),
247        language_name(observation.language),
248        source_path,
249        symbol,
250    );
251    let stable_key = identity.stable_key();
252    DeclaredImplementation {
253        node: identity.node(format!("{}::{symbol}", language_name(observation.language))),
254        method: method.to_owned(),
255        path: path.to_owned(),
256        evidence: source_evidence(
257            repo_id,
258            source_path,
259            content_hash,
260            observation,
261            &format!(
262                "{stable_key}:{}:{}:{}",
263                framework_name(observation.framework),
264                observation.lines.start,
265                observation.lines.end
266            ),
267        ),
268    }
269}
270
271fn source_test_case(
272    repo_id: &RepoId,
273    source_path: &str,
274    content_hash: &str,
275    observation: &SourceObservation,
276    symbol: &str,
277    method: &str,
278    path: &str,
279) -> DeclaredTestCase {
280    let stable_key = test_stable_key(repo_id, source_path, observation, symbol);
281    DeclaredTestCase {
282        node: Node {
283            id: NodeId::new(stable_id("node", &stable_key)),
284            kind: NodeKind::TestCase,
285            repo_id: Some(repo_id.clone()),
286            stable_key: stable_key.clone(),
287            label: format!(
288                "{}/{}::{symbol}",
289                language_name(observation.language),
290                framework_name(observation.framework)
291            ),
292        },
293        method: method.to_owned(),
294        path: path.to_owned(),
295        evidence: source_evidence(
296            repo_id,
297            source_path,
298            content_hash,
299            observation,
300            &format!("{stable_key}:{method}:{path}"),
301        ),
302    }
303}
304
305fn standalone_test(
306    repo_id: &RepoId,
307    source_path: &str,
308    content_hash: &str,
309    observation: &SourceObservation,
310    symbol: &str,
311) -> (Node, Evidence) {
312    let stable_key = test_stable_key(repo_id, source_path, observation, symbol);
313    (
314        Node {
315            id: NodeId::new(stable_id("node", &stable_key)),
316            kind: NodeKind::TestCase,
317            repo_id: Some(repo_id.clone()),
318            stable_key: stable_key.clone(),
319            label: format!(
320                "{}/{}::{symbol}",
321                language_name(observation.language),
322                framework_name(observation.framework)
323            ),
324        },
325        source_evidence(repo_id, source_path, content_hash, observation, &stable_key),
326    )
327}
328
329fn source_factory_relation(
330    repo_id: &RepoId,
331    source_path: &str,
332    content_hash: &str,
333    observation: &SourceObservation,
334    factory_symbol: &str,
335    model_symbol: &str,
336) -> ([Node; 2], Edge, Evidence) {
337    let factory_identity =
338        SourceSymbolIdentity::new(repo_id.clone(), "python", source_path, factory_symbol);
339    let model_path = observation.related_path.as_deref().unwrap_or(source_path);
340    let model_identity =
341        SourceSymbolIdentity::new(repo_id.clone(), "python", model_path, model_symbol);
342    let factory_node = factory_identity.node(format!("python/factory-boy::{factory_symbol}"));
343    let model_node = model_identity.node(format!("python::{model_symbol}"));
344    let relation_key = format!(
345        "factory-model:{}:{}",
346        factory_node.id.as_str(),
347        model_node.id.as_str()
348    );
349    let evidence = source_evidence(
350        repo_id,
351        source_path,
352        content_hash,
353        observation,
354        &relation_key,
355    );
356    let edge = Edge {
357        id: EdgeId::new(stable_id("edge", &relation_key)),
358        source: factory_node.id.clone(),
359        target: model_node.id.clone(),
360        kind: EdgeKind::Consumes,
361        confidence: observation.confidence,
362        status: EpistemicStatus::Confirmed,
363        evidence: vec![evidence.id.clone()],
364    };
365    ([factory_node, model_node], edge, evidence)
366}
367
368fn test_stable_key(
369    repo_id: &RepoId,
370    source_path: &str,
371    observation: &SourceObservation,
372    symbol: &str,
373) -> String {
374    format!(
375        "test:{}:{}:{}:{source_path}:{symbol}",
376        repo_id.as_str(),
377        language_name(observation.language),
378        framework_name(observation.framework)
379    )
380}
381
382fn source_evidence(
383    repo_id: &RepoId,
384    source_path: &str,
385    content_hash: &str,
386    observation: &SourceObservation,
387    evidence_key: &str,
388) -> Evidence {
389    Evidence {
390        id: EvidenceId::new(stable_id("evidence", evidence_key)),
391        repo_id: Some(repo_id.clone()),
392        file_path: Some(source_path.to_owned()),
393        start_line: Some(observation.lines.start),
394        end_line: Some(observation.lines.end),
395        extractor: format!(
396            "code-system-graph.source.{}",
397            language_name(observation.language)
398        ),
399        extractor_version: "1.0.0".to_owned(),
400        provenance: Provenance::Extracted,
401        confidence: observation.confidence,
402        observed_at_commit: None,
403        content_hash: Some(content_hash.to_owned()),
404        note: Some(format!(
405            "{} {} syntax",
406            framework_name(observation.framework),
407            role_name(observation.role)
408        )),
409    }
410}
411
412fn language_name(language: SourceLanguage) -> &'static str {
413    match language {
414        SourceLanguage::JavaScript => "javascript",
415        SourceLanguage::TypeScript => "typescript",
416        SourceLanguage::Rust => "rust",
417        SourceLanguage::Python => "python",
418        SourceLanguage::Go => "go",
419        SourceLanguage::Java => "java",
420    }
421}
422
423fn framework_name(framework: SourceFramework) -> &'static str {
424    match framework {
425        SourceFramework::Fetch => "fetch",
426        SourceFramework::Axios => "axios",
427        SourceFramework::Express => "express",
428        SourceFramework::Fastify => "fastify",
429        SourceFramework::NestJs => "nestjs",
430        SourceFramework::NextJs => "nextjs",
431        SourceFramework::Axum => "axum",
432        SourceFramework::ActixWeb => "actix-web",
433        SourceFramework::Utoipa => "utoipa",
434        SourceFramework::Reqwest => "reqwest",
435        SourceFramework::RustTest => "rust-test",
436        SourceFramework::TokioTest => "tokio-test",
437        SourceFramework::Rstest => "rstest",
438        SourceFramework::FastApi => "fastapi",
439        SourceFramework::Flask => "flask",
440        SourceFramework::Requests => "requests",
441        SourceFramework::Httpx => "httpx",
442        SourceFramework::AioHttp => "aiohttp",
443        SourceFramework::PythonHttpRegistry => "python-http-registry",
444        SourceFramework::FactoryBoy => "factory-boy",
445        SourceFramework::Pytest => "pytest",
446        SourceFramework::Unittest => "unittest",
447        SourceFramework::PythonTest => "python-test",
448        SourceFramework::GoNetHttp => "net-http",
449        SourceFramework::Gin => "gin",
450        SourceFramework::Chi => "chi",
451        SourceFramework::SpringMvc => "spring-mvc",
452        SourceFramework::WebClient => "webclient",
453        SourceFramework::Feign => "feign",
454    }
455}
456
457fn role_name(role: SourceRole) -> &'static str {
458    match role {
459        SourceRole::Provider => "provider",
460        SourceRole::Consumer => "consumer",
461        SourceRole::Test => "test",
462        SourceRole::Factory => "factory",
463    }
464}
465
466#[cfg(test)]
467mod tests {
468    use code_system_graph_model::{EdgeKind, RepoId};
469
470    use super::source_observations_to_graph;
471    use crate::{
472        link_declared_implementations, link_declared_tests, parse_python_source, parse_rust_source
473    };
474
475    #[test]
476    fn source_graph_should_link_python_test_to_rust_handler() {
477        let rust = source_observations_to_graph(
478            &RepoId::new("repo:api"),
479            "src/routes.rs",
480            "rust-hash",
481            &parse_rust_source(
482                r#"use axum::{Router, routing::post}; Router::new().route("/orders", post(create_order));"#,
483            ),
484        );
485        let python = source_observations_to_graph(
486            &RepoId::new("repo:tests"),
487            "tests/test_orders.py",
488            "python-hash",
489            &parse_python_source(
490                r#"import requests
491def test_create_order():
492    requests.post("https://api.test/orders")
493"#,
494            ),
495        );
496
497        let test_edges = link_declared_tests(&python.tests, &rust.boundaries)
498            .unwrap_or_else(|error| panic!("fixtures must link: {error}"));
499        let implementation_edges =
500            link_declared_implementations(&rust.implementations, &rust.boundaries)
501                .unwrap_or_else(|error| panic!("fixtures must link: {error}"));
502
503        assert!(
504            test_edges
505                .iter()
506                .all(|edge| edge.kind == EdgeKind::Validates)
507        );
508        assert!(
509            implementation_edges
510                .iter()
511                .all(|edge| edge.kind == EdgeKind::ImplementedBy)
512        );
513    }
514
515    #[test]
516    fn source_graph_should_link_factory_boy_factory_to_model() {
517        let facts = source_observations_to_graph(
518            &RepoId::new("repo:tests"),
519            "src/factories/AccountFactory.py",
520            "python-hash",
521            &parse_python_source(
522                r"import factory
523from src.clases.Account import Account
524
525class AccountFactory(factory.Factory):
526    class Meta:
527        model = Account
528",
529            ),
530        );
531
532        assert!(
533            facts.relation_nodes.len() == 2
534                && facts.relation_edges.len() == 1
535                && facts.relation_edges[0].kind == EdgeKind::Consumes
536                && facts
537                    .relation_nodes
538                    .iter()
539                    .any(|node| node.label == "python/factory-boy::AccountFactory")
540                && facts
541                    .relation_nodes
542                    .iter()
543                    .any(|node| node.stable_key.ends_with("src/clases/Account.py:Account"))
544        );
545    }
546}