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