Skip to main content

code_system_graph_core/
extraction_graph.rs

1//! Deterministic graph conversion for extraction documents.
2
3use std::collections::{BTreeMap, BTreeSet};
4
5use code_system_graph_model::{
6    Edge, EdgeId, EdgeKind, EpistemicStatus, Evidence, EvidenceId, Node, NodeId, NodeKind, Provenance, RepoId, RepositoryCoverageGap, stable_id
7};
8
9use crate::{
10    DataAccessObservation, DataAccessRole, DataArtifactKind, DataArtifactReference, DataArtifactReferenceKind, DataDocument, DatabaseForeignKey, DatabaseTable, DeploymentKind, DeploymentUnit, DocumentKind, DocumentRecord, DocumentationDocument, ExplicitReference, ExplicitReferenceKind, InfrastructureDocument, InfrastructureEvidence, InfrastructureResource, InfrastructureResourceKind, OwnershipRule, SafeConfigDocument
11};
12
13type RepositoryReference<'a> = (&'a str, &'a RepoId, Option<&'a str>);
14
15/// Graph-ready facts assembled from supported extraction documents.
16#[derive(Debug, Clone, Default)]
17pub struct ExtractionGraphFacts {
18    /// Repository, artifact, data, deployment, configuration, document, and owner nodes.
19    pub nodes: Vec<Node>,
20    /// Directly evidenced extraction relationships.
21    pub edges: Vec<Edge>,
22    /// Value-free evidence supporting the emitted relationships.
23    pub evidence: Vec<Evidence>,
24    /// Explicit repository dependencies that could not be resolved without guessing.
25    pub coverage_gaps: Vec<RepositoryCoverageGap>,
26}
27
28#[derive(Debug, Clone)]
29struct TableInfo {
30    node: Node,
31    database: Option<String>,
32    schema: Option<String>,
33    name: String,
34    columns: BTreeMap<String, Node>,
35}
36
37#[derive(Debug, Clone)]
38struct PendingAccess {
39    repo_id: RepoId,
40    source_path: String,
41    content_hash: String,
42    access: DataAccessObservation,
43}
44
45type KnownSourceSymbols = BTreeMap<(RepoId, String, String), Node>;
46
47#[derive(Debug, Clone)]
48struct PendingForeignKey {
49    repo_id: RepoId,
50    source_path: String,
51    content_hash: String,
52    source_table_key: String,
53    foreign_key: DatabaseForeignKey,
54}
55
56#[derive(Debug, Clone, Copy, PartialEq, Eq)]
57enum MigrationDirection {
58    Forward,
59    Up,
60    Down,
61}
62
63#[derive(Debug, Clone)]
64struct MigrationArtifact {
65    repo_id: RepoId,
66    source_path: String,
67    content_hash: String,
68    artifact: Node,
69    order_hint: Option<u64>,
70    evidence_line: u32,
71    direction: MigrationDirection,
72}
73
74#[derive(Debug, Clone)]
75struct DeploymentInfo {
76    repo_id: RepoId,
77    node: Node,
78    aliases: BTreeSet<String>,
79}
80
81#[derive(Debug, Clone)]
82struct ResourceInfo {
83    node: Node,
84    aliases: BTreeSet<String>,
85}
86
87#[derive(Debug, Clone)]
88struct PendingDependency {
89    source: Node,
90    target: String,
91    repo_id: RepoId,
92    source_path: String,
93    content_hash: String,
94    line: Option<u32>,
95}
96
97#[derive(Debug, Clone)]
98struct PendingReference {
99    document: Node,
100    repo_id: RepoId,
101    source_path: String,
102    content_hash: String,
103    reference: ExplicitReference,
104}
105
106#[derive(Default)]
107struct GraphBuilder {
108    facts: ExtractionGraphFacts,
109}
110
111impl GraphBuilder {
112    fn node(&mut self, node: Node) {
113        self.facts.nodes.push(node);
114    }
115
116    fn evidence(&mut self, evidence: Evidence) {
117        self.facts.evidence.push(evidence);
118    }
119
120    fn edge(&mut self, source: &Node, target: &Node, kind: EdgeKind, evidence: &Evidence) {
121        if source.id == target.id {
122            return;
123        }
124        let key = format!("{}:{kind:?}:{}", source.id.as_str(), target.id.as_str());
125        self.facts.edges.push(Edge {
126            id: EdgeId::new(stable_id("edge", &key)),
127            source: source.id.clone(),
128            target: target.id.clone(),
129            kind,
130            confidence: 1.0,
131            status: EpistemicStatus::Confirmed,
132            evidence: vec![evidence.id.clone()],
133        });
134    }
135
136    fn finish(mut self) -> ExtractionGraphFacts {
137        let mut nodes = BTreeMap::new();
138        for node in self.facts.nodes {
139            nodes.entry(node.id.clone()).or_insert(node);
140        }
141        self.facts.nodes = nodes.into_values().collect();
142
143        let mut edges: BTreeMap<EdgeId, Edge> = BTreeMap::new();
144        for edge in self.facts.edges {
145            if let Some(existing) = edges.get_mut(&edge.id) {
146                existing.evidence.extend(edge.evidence);
147                existing.confidence = existing.confidence.max(edge.confidence);
148            } else {
149                edges.insert(edge.id.clone(), edge);
150            }
151        }
152        self.facts.edges = edges
153            .into_values()
154            .map(|mut edge| {
155                edge.evidence.sort();
156                edge.evidence.dedup();
157                edge
158            })
159            .collect();
160
161        let mut evidence = BTreeMap::new();
162        for item in self.facts.evidence {
163            evidence.entry(item.id.clone()).or_insert(item);
164        }
165        self.facts.evidence = evidence.into_values().collect();
166        self.facts.coverage_gaps.sort_by(|left, right| {
167            (&left.repo_id, &left.reason).cmp(&(&right.repo_id, &right.reason))
168        });
169        self.facts.coverage_gaps.dedup();
170        self.facts
171    }
172}
173
174/// Converts all supported extractor outputs into deterministic, ambiguity-safe graph facts.
175///
176/// Only exact, unique targets are linked. Dynamic or incomplete observations that lack a concrete
177/// target remain unlinked, and retained evidence contains locators and static notes rather than
178/// source or configuration values.
179#[must_use]
180pub fn documents_to_graph(
181    data_inputs: &[(&RepoId, &str, &str, &DataDocument)],
182    infrastructure_inputs: &[(&RepoId, &str, &str, &InfrastructureDocument)],
183    documentation_inputs: &[(&RepoId, &str, &str, &DocumentationDocument)],
184    config_inputs: &[(&RepoId, &str, &str, &SafeConfigDocument)],
185    known_nodes: &[Node],
186    repository_aliases: &[RepositoryReference<'_>],
187) -> ExtractionGraphFacts {
188    let mut builder = GraphBuilder::default();
189    let source_symbols = index_known_source_symbols(known_nodes);
190
191    append_config_documents(&mut builder, config_inputs);
192    let tables = append_data_documents(&mut builder, data_inputs);
193    append_infrastructure_documents(&mut builder, infrastructure_inputs);
194    append_documentation_documents(
195        &mut builder,
196        documentation_inputs,
197        known_nodes,
198        repository_aliases,
199    );
200
201    // Data observations can resolve across documents, so they are linked after every declaration
202    // has entered the exact-match table index.
203    link_data_observations(&mut builder, data_inputs, &tables, &source_symbols);
204    link_data_artifact_references(&mut builder, data_inputs, &tables, &source_symbols);
205    builder.finish()
206}
207
208fn append_config_documents(
209    builder: &mut GraphBuilder,
210    inputs: &[(&RepoId, &str, &str, &SafeConfigDocument)],
211) {
212    for (repo_id, source_path, content_hash, document) in inputs {
213        if document.keys.is_empty() {
214            continue;
215        }
216        let artifact = append_artifact(
217            builder,
218            repo_id,
219            source_path,
220            content_hash,
221            "code-system-graph.extraction.config",
222            "configuration artifact",
223        );
224        for key in &document.keys {
225            let node = config_node(repo_id, &key.scope.join("."), &key.name);
226            let evidence = extraction_evidence(
227                repo_id,
228                source_path,
229                content_hash,
230                line_from_usize(key.line),
231                line_from_usize(key.line),
232                "code-system-graph.extraction.config",
233                "configuration key declaration",
234            );
235            builder.edge(&artifact, &node, EdgeKind::Configures, &evidence);
236            builder.node(node);
237            builder.evidence(evidence);
238        }
239    }
240}
241
242fn append_data_documents(
243    builder: &mut GraphBuilder,
244    inputs: &[(&RepoId, &str, &str, &DataDocument)],
245) -> BTreeMap<String, TableInfo> {
246    let mut tables = BTreeMap::new();
247    let mut migrations = Vec::new();
248    for (repo_id, source_path, content_hash, document) in inputs {
249        if document.tables.is_empty()
250            && document.accesses.is_empty()
251            && document.references.is_empty()
252            && document.artifact_kind != DataArtifactKind::SqlMigration
253        {
254            continue;
255        }
256        let artifact = append_artifact(
257            builder,
258            repo_id,
259            source_path,
260            content_hash,
261            "code-system-graph.extraction.data",
262            "data artifact",
263        );
264        if let Some(migration) = &document.migration {
265            migrations.push(MigrationArtifact {
266                repo_id: (*repo_id).clone(),
267                source_path: (*source_path).to_owned(),
268                content_hash: (*content_hash).to_owned(),
269                artifact: artifact.clone(),
270                order_hint: migration.order_hint,
271                evidence_line: migration.evidence.get(),
272                direction: migration_direction(source_path),
273            });
274        }
275        for table in &document.tables {
276            let info = table_info(document, table);
277            let table_evidence = extraction_evidence(
278                repo_id,
279                source_path,
280                content_hash,
281                Some(table.evidence.get()),
282                Some(table.evidence.get()),
283                "code-system-graph.extraction.data",
284                "database table declaration",
285            );
286            builder.edge(&artifact, &info.node, EdgeKind::Contains, &table_evidence);
287            builder.node(info.node.clone());
288            builder.evidence(table_evidence.clone());
289
290            if let Some(database) = &info.database {
291                let database = database_node(database);
292                builder.edge(&database, &info.node, EdgeKind::Contains, &table_evidence);
293                builder.node(database);
294            }
295            for column in &table.columns {
296                let Some(column_node) = info.columns.get(&column.name) else {
297                    continue;
298                };
299                let evidence = extraction_evidence(
300                    repo_id,
301                    source_path,
302                    content_hash,
303                    Some(column.evidence.get()),
304                    Some(column.evidence.get()),
305                    "code-system-graph.extraction.data",
306                    "database column declaration",
307                );
308                builder.edge(&info.node, column_node, EdgeKind::Contains, &evidence);
309                builder.node(column_node.clone());
310                builder.evidence(evidence);
311            }
312            tables
313                .entry(info.node.stable_key.clone())
314                .and_modify(|existing: &mut TableInfo| {
315                    existing.columns.extend(info.columns.clone());
316                })
317                .or_insert(info);
318        }
319    }
320    link_migration_artifacts(builder, &migrations);
321    tables
322}
323
324fn link_migration_artifacts(builder: &mut GraphBuilder, migrations: &[MigrationArtifact]) {
325    let mut pairs: BTreeMap<(RepoId, String, String), Vec<&MigrationArtifact>> = BTreeMap::new();
326    let mut ordered: BTreeMap<(RepoId, String), BTreeMap<u64, Vec<&MigrationArtifact>>> =
327        BTreeMap::new();
328
329    for migration in migrations {
330        let (directory, family) = migration_family(&migration.source_path);
331        pairs
332            .entry((migration.repo_id.clone(), directory.clone(), family))
333            .or_default()
334            .push(migration);
335        if migration.direction != MigrationDirection::Down
336            && let Some(order_hint) = migration.order_hint
337        {
338            ordered
339                .entry((migration.repo_id.clone(), directory))
340                .or_default()
341                .entry(order_hint)
342                .or_default()
343                .push(migration);
344        }
345    }
346
347    for candidates in pairs.values() {
348        let up = exactly_one_migration(
349            candidates
350                .iter()
351                .filter(|migration| migration.direction == MigrationDirection::Up)
352                .copied(),
353        );
354        let down = exactly_one_migration(
355            candidates
356                .iter()
357                .filter(|migration| migration.direction == MigrationDirection::Down)
358                .copied(),
359        );
360        let (Some(up), Some(down)) = (up, down) else {
361            continue;
362        };
363        let evidence = extraction_evidence(
364            &down.repo_id,
365            &down.source_path,
366            &down.content_hash,
367            Some(down.evidence_line),
368            Some(down.evidence_line),
369            "code-system-graph.extraction.data",
370            "reversible migration pair",
371        );
372        builder.edge(&down.artifact, &up.artifact, EdgeKind::Reverts, &evidence);
373        builder.evidence(evidence);
374    }
375
376    for revisions in ordered.values() {
377        let migrations = revisions
378            .values()
379            .map(|candidates| exactly_one_migration(candidates.iter().copied()))
380            .collect::<Vec<_>>();
381        for pair in migrations.windows(2) {
382            let [Some(previous), Some(next)] = pair else {
383                continue;
384            };
385            let evidence = extraction_evidence(
386                &next.repo_id,
387                &next.source_path,
388                &next.content_hash,
389                Some(next.evidence_line),
390                Some(next.evidence_line),
391                "code-system-graph.extraction.data",
392                "migration order",
393            );
394            builder.edge(
395                &previous.artifact,
396                &next.artifact,
397                EdgeKind::Precedes,
398                &evidence,
399            );
400            builder.evidence(evidence);
401        }
402    }
403}
404
405fn exactly_one_migration<'a>(
406    mut candidates: impl Iterator<Item = &'a MigrationArtifact>,
407) -> Option<&'a MigrationArtifact> {
408    let candidate = candidates.next()?;
409    candidates.next().is_none().then_some(candidate)
410}
411
412fn migration_direction(source_path: &str) -> MigrationDirection {
413    if source_path.ends_with(".up.sql") {
414        MigrationDirection::Up
415    } else if source_path.ends_with(".down.sql") {
416        MigrationDirection::Down
417    } else {
418        MigrationDirection::Forward
419    }
420}
421
422fn migration_family(source_path: &str) -> (String, String) {
423    let (directory, filename) = source_path
424        .rsplit_once('/')
425        .map_or(("", source_path), |(directory, filename)| {
426            (directory, filename)
427        });
428    let family = filename
429        .strip_suffix(".up.sql")
430        .or_else(|| filename.strip_suffix(".down.sql"))
431        .or_else(|| filename.strip_suffix(".sql"))
432        .unwrap_or(filename);
433    (directory.to_owned(), family.to_owned())
434}
435
436fn link_data_observations(
437    builder: &mut GraphBuilder,
438    inputs: &[(&RepoId, &str, &str, &DataDocument)],
439    tables: &BTreeMap<String, TableInfo>,
440    source_symbols: &KnownSourceSymbols,
441) {
442    let mut accesses = Vec::new();
443    let mut foreign_keys = Vec::new();
444    for (repo_id, source_path, content_hash, document) in inputs {
445        accesses.extend(
446            document
447                .accesses
448                .iter()
449                .cloned()
450                .map(|access| PendingAccess {
451                    repo_id: (*repo_id).clone(),
452                    source_path: (*source_path).to_owned(),
453                    content_hash: (*content_hash).to_owned(),
454                    access,
455                }),
456        );
457        for table in &document.tables {
458            let info = table_info(document, table);
459            foreign_keys.extend(table.foreign_keys.iter().cloned().map(|foreign_key| {
460                PendingForeignKey {
461                    repo_id: (*repo_id).clone(),
462                    source_path: (*source_path).to_owned(),
463                    content_hash: (*content_hash).to_owned(),
464                    source_table_key: info.node.stable_key.clone(),
465                    foreign_key,
466                }
467            }));
468        }
469    }
470    link_accesses(builder, accesses, tables, source_symbols);
471    link_foreign_keys(builder, foreign_keys, tables);
472}
473
474fn link_data_artifact_references(
475    builder: &mut GraphBuilder,
476    inputs: &[(&RepoId, &str, &str, &DataDocument)],
477    tables: &BTreeMap<String, TableInfo>,
478    source_symbols: &KnownSourceSymbols,
479) {
480    let mut referenced_accesses = Vec::new();
481    for (repo_id, source_path, content_hash, document) in inputs {
482        for reference in &document.references {
483            let effective_path = effective_data_reference_path(reference, repo_id, inputs);
484            let targets = inputs
485                .iter()
486                .filter(|(candidate_repo, candidate_path, _, candidate)| {
487                    *candidate_repo == *repo_id
488                        && match reference.kind {
489                            DataArtifactReferenceKind::QueryFile => {
490                                *candidate_path == reference.path
491                                    && candidate.artifact_kind == DataArtifactKind::SqlQueryFile
492                            }
493                            DataArtifactReferenceKind::MigrationDirectory
494                            | DataArtifactReferenceKind::SqlxDefaultMigrationDirectory => {
495                                matches!(
496                                    candidate.artifact_kind,
497                                    DataArtifactKind::SqlMigration
498                                        | DataArtifactKind::DeclarativeSqlSchema
499                                        | DataArtifactKind::SqlQueryFile
500                                ) && path_is_within(candidate_path, &effective_path)
501                            }
502                        }
503                })
504                .collect::<Vec<_>>();
505            if reference.kind == DataArtifactReferenceKind::QueryFile && targets.len() != 1 {
506                continue;
507            }
508            let source_artifact = append_artifact(
509                builder,
510                repo_id,
511                source_path,
512                content_hash,
513                "code-system-graph.extraction.data",
514                "data source artifact",
515            );
516            let source = reference.owner.as_deref().map_or_else(
517                || source_artifact.clone(),
518                |owner| data_symbol_node(repo_id, source_path, owner, source_symbols),
519            );
520            for (target_repo, target_path, target_hash, target_document) in targets {
521                let target_artifact = append_artifact(
522                    builder,
523                    target_repo,
524                    target_path,
525                    target_hash,
526                    "code-system-graph.extraction.data",
527                    "referenced data artifact",
528                );
529                let evidence = extraction_evidence(
530                    repo_id,
531                    source_path,
532                    content_hash,
533                    Some(reference.evidence.get()),
534                    Some(reference.evidence.get()),
535                    "code-system-graph.extraction.data",
536                    match reference.kind {
537                        DataArtifactReferenceKind::QueryFile => "SQLx query file reference",
538                        DataArtifactReferenceKind::MigrationDirectory => {
539                            "SQLx migration directory reference"
540                        }
541                        DataArtifactReferenceKind::SqlxDefaultMigrationDirectory => {
542                            "SQLx configured migration directory reference"
543                        }
544                    },
545                );
546                builder.edge(&source, &target_artifact, EdgeKind::Consumes, &evidence);
547                builder.node(source.clone());
548                builder.evidence(evidence);
549
550                if reference.kind == DataArtifactReferenceKind::QueryFile {
551                    referenced_accesses.extend(target_document.accesses.iter().map(|access| {
552                        let mut access = access.clone();
553                        access.owner.clone_from(&reference.owner);
554                        access.evidence = reference.evidence;
555                        PendingAccess {
556                            repo_id: (*repo_id).clone(),
557                            source_path: (*source_path).to_owned(),
558                            content_hash: (*content_hash).to_owned(),
559                            access,
560                        }
561                    }));
562                }
563            }
564        }
565    }
566    link_accesses(builder, referenced_accesses, tables, source_symbols);
567}
568
569fn effective_data_reference_path(
570    reference: &DataArtifactReference,
571    repo_id: &RepoId,
572    inputs: &[(&RepoId, &str, &str, &DataDocument)],
573) -> String {
574    if reference.kind != DataArtifactReferenceKind::SqlxDefaultMigrationDirectory {
575        return reference.path.clone();
576    }
577    inputs
578        .iter()
579        .find(|(candidate_repo, candidate_path, _, candidate)| {
580            *candidate_repo == repo_id
581                && candidate.artifact_kind == DataArtifactKind::SqlxConfiguration
582                && *candidate_path == sqlx_configuration_path(&reference.path)
583        })
584        .and_then(|(_, _, _, configuration)| {
585            configuration
586                .references
587                .iter()
588                .find(|candidate| candidate.kind == DataArtifactReferenceKind::MigrationDirectory)
589                .map(|candidate| candidate.path.clone())
590        })
591        .unwrap_or_else(|| join_portable_path(&reference.path, "migrations"))
592}
593
594fn path_is_within(candidate: &str, directory: &str) -> bool {
595    candidate == directory
596        || candidate
597            .strip_prefix(directory)
598            .is_some_and(|suffix| suffix.starts_with('/'))
599}
600
601fn sqlx_configuration_path(crate_root: &str) -> String {
602    join_portable_path(crate_root, "sqlx.toml")
603}
604
605fn join_portable_path(parent: &str, child: &str) -> String {
606    if parent.is_empty() {
607        child.to_owned()
608    } else {
609        format!("{}/{}", parent.trim_end_matches('/'), child)
610    }
611}
612
613fn link_accesses(
614    builder: &mut GraphBuilder,
615    accesses: Vec<PendingAccess>,
616    tables: &BTreeMap<String, TableInfo>,
617    source_symbols: &KnownSourceSymbols,
618) {
619    let mut model_tables = BTreeMap::<String, BTreeSet<String>>::new();
620    for pending in &accesses {
621        if pending.access.role != DataAccessRole::ModelBinding {
622            continue;
623        }
624        let Some(model) = pending.access.owner.as_ref() else {
625            continue;
626        };
627        model_tables
628            .entry(model.clone())
629            .or_default()
630            .insert(pending.access.table.clone());
631    }
632    for pending in accesses {
633        let Some(owner) = pending.access.owner.as_deref() else {
634            continue;
635        };
636        let resolved_model_table = pending
637            .access
638            .model
639            .as_ref()
640            .and_then(|model| model_tables.get(model).cloned().and_then(exactly_one));
641        let target_name = if pending.access.table.is_empty() {
642            let Some(table) = resolved_model_table.as_deref() else {
643                continue;
644            };
645            table
646        } else {
647            &pending.access.table
648        };
649        let Some(target) = resolve_table(tables, target_name) else {
650            continue;
651        };
652        let symbol = data_symbol_node(
653            &pending.repo_id,
654            &pending.source_path,
655            owner,
656            source_symbols,
657        );
658        let evidence = extraction_evidence(
659            &pending.repo_id,
660            &pending.source_path,
661            &pending.content_hash,
662            Some(pending.access.evidence.get()),
663            Some(pending.access.evidence.get()),
664            "code-system-graph.extraction.data",
665            "database access observation",
666        );
667        match pending.access.role {
668            DataAccessRole::Reader => {
669                builder.edge(&symbol, &target.node, EdgeKind::ReadsTable, &evidence);
670            }
671            DataAccessRole::Writer => {
672                builder.edge(&symbol, &target.node, EdgeKind::WritesTable, &evidence);
673            }
674            DataAccessRole::ModelBinding => {
675                builder.edge(&target.node, &symbol, EdgeKind::ImplementedBy, &evidence);
676            }
677            DataAccessRole::Declaration => continue,
678        }
679        builder.node(symbol);
680        builder.evidence(evidence);
681    }
682}
683
684fn link_foreign_keys(
685    builder: &mut GraphBuilder,
686    foreign_keys: Vec<PendingForeignKey>,
687    tables: &BTreeMap<String, TableInfo>,
688) {
689    for pending in foreign_keys {
690        let Some(source) = tables.get(&pending.source_table_key) else {
691            continue;
692        };
693        let Some(target) = resolve_table(tables, &pending.foreign_key.referenced_table) else {
694            continue;
695        };
696        let evidence = extraction_evidence(
697            &pending.repo_id,
698            &pending.source_path,
699            &pending.content_hash,
700            Some(pending.foreign_key.evidence.get()),
701            Some(pending.foreign_key.evidence.get()),
702            "code-system-graph.extraction.data",
703            "foreign key declaration",
704        );
705        if pending.foreign_key.referenced_columns.is_empty() {
706            builder.edge(&source.node, &target.node, EdgeKind::Consumes, &evidence);
707            builder.evidence(evidence);
708            continue;
709        }
710        if pending.foreign_key.columns.len() != pending.foreign_key.referenced_columns.len() {
711            continue;
712        }
713        let pairs = pending
714            .foreign_key
715            .columns
716            .iter()
717            .zip(&pending.foreign_key.referenced_columns)
718            .filter_map(|(local, referenced)| {
719                Some((source.columns.get(local)?, target.columns.get(referenced)?))
720            })
721            .collect::<Vec<_>>();
722        if pairs.len() != pending.foreign_key.columns.len() {
723            continue;
724        }
725        for (local, referenced) in pairs {
726            builder.edge(local, referenced, EdgeKind::Consumes, &evidence);
727        }
728        builder.evidence(evidence);
729    }
730}
731
732fn append_infrastructure_documents(
733    builder: &mut GraphBuilder,
734    inputs: &[(&RepoId, &str, &str, &InfrastructureDocument)],
735) {
736    let mut deployments = Vec::new();
737    let mut resources = Vec::new();
738    let mut dependencies = Vec::new();
739
740    for (repo_id, source_path, content_hash, document) in inputs {
741        if document.deployment_units.is_empty()
742            && document.resources.is_empty()
743            && document.environment_keys.is_empty()
744        {
745            continue;
746        }
747        let artifact = append_artifact(
748            builder,
749            repo_id,
750            source_path,
751            content_hash,
752            "code-system-graph.extraction.infrastructure",
753            "infrastructure artifact",
754        );
755        append_deployment_units(
756            builder,
757            repo_id,
758            source_path,
759            content_hash,
760            &document.deployment_units,
761            &mut deployments,
762            &mut dependencies,
763        );
764        append_infrastructure_resources(
765            builder,
766            repo_id,
767            source_path,
768            content_hash,
769            &artifact,
770            &document.resources,
771            &mut deployments,
772            &mut resources,
773            &mut dependencies,
774        );
775        append_document_environment_keys(
776            builder,
777            repo_id,
778            source_path,
779            content_hash,
780            &artifact,
781            &document.environment_keys,
782        );
783    }
784    link_infrastructure_dependencies(builder, &deployments, &resources, dependencies);
785}
786
787fn link_infrastructure_dependencies(
788    builder: &mut GraphBuilder,
789    deployments: &[DeploymentInfo],
790    resources: &[ResourceInfo],
791    dependencies: Vec<PendingDependency>,
792) {
793    for dependency in dependencies {
794        let target = resolve_infrastructure_target(deployments, resources, &dependency.target);
795        let Some(target) = target else {
796            continue;
797        };
798        let evidence = extraction_evidence(
799            &dependency.repo_id,
800            &dependency.source_path,
801            &dependency.content_hash,
802            dependency.line,
803            dependency.line,
804            "code-system-graph.extraction.infrastructure",
805            "explicit infrastructure dependency",
806        );
807        builder.edge(
808            &dependency.source,
809            &target,
810            EdgeKind::CallsRemote,
811            &evidence,
812        );
813        builder.node(target);
814        builder.evidence(evidence);
815    }
816}
817
818fn append_deployment_units(
819    builder: &mut GraphBuilder,
820    repo_id: &RepoId,
821    source_path: &str,
822    content_hash: &str,
823    units: &[DeploymentUnit],
824    deployments: &mut Vec<DeploymentInfo>,
825    dependencies: &mut Vec<PendingDependency>,
826) {
827    for unit in units {
828        let technology = deployment_technology(unit.kind);
829        let deployment = deployment_node(technology, unit.namespace.as_deref(), &unit.name);
830        let line = infrastructure_line(&unit.evidence);
831        let evidence = extraction_evidence(
832            repo_id,
833            source_path,
834            content_hash,
835            line,
836            line,
837            "code-system-graph.extraction.infrastructure",
838            "deployment declaration",
839        );
840        let repository = repository_node(repo_id);
841        builder.edge(&repository, &deployment, EdgeKind::Deploys, &evidence);
842        builder.node(repository);
843        builder.node(deployment.clone());
844        builder.evidence(evidence.clone());
845        for service_name in &unit.service_names {
846            let service = service_node(repo_id, service_name);
847            builder.edge(&deployment, &service, EdgeKind::Provides, &evidence);
848            builder.node(service);
849        }
850        append_deployment_environment_keys(
851            builder,
852            repo_id,
853            source_path,
854            content_hash,
855            &deployment,
856            &unit.environment_keys,
857            line,
858        );
859        dependencies.extend(unit.dependencies.iter().map(|target| PendingDependency {
860            source: deployment.clone(),
861            target: target.clone(),
862            repo_id: repo_id.clone(),
863            source_path: source_path.to_owned(),
864            content_hash: content_hash.to_owned(),
865            line,
866        }));
867        let aliases = BTreeSet::from([
868            unit.name.clone(),
869            deployment.stable_key.clone(),
870            deployment
871                .stable_key
872                .strip_prefix("deployment:")
873                .unwrap_or(&deployment.stable_key)
874                .to_owned(),
875        ]);
876        deployments.push(DeploymentInfo {
877            repo_id: repo_id.clone(),
878            node: deployment,
879            aliases,
880        });
881    }
882}
883
884fn append_deployment_environment_keys(
885    builder: &mut GraphBuilder,
886    repo_id: &RepoId,
887    source_path: &str,
888    content_hash: &str,
889    deployment: &Node,
890    key_names: &[String],
891    line: Option<u32>,
892) {
893    for key_name in key_names {
894        let config = resolve_or_create_config(builder, repo_id, &deployment.stable_key, key_name);
895        let evidence = extraction_evidence(
896            repo_id,
897            source_path,
898            content_hash,
899            line,
900            line,
901            "code-system-graph.extraction.infrastructure",
902            "environment key declaration",
903        );
904        builder.edge(deployment, &config, EdgeKind::Configures, &evidence);
905        builder.node(config);
906        builder.evidence(evidence);
907    }
908}
909
910#[expect(
911    clippy::too_many_arguments,
912    reason = "The helper preserves explicit source provenance."
913)]
914fn append_infrastructure_resources(
915    builder: &mut GraphBuilder,
916    repo_id: &RepoId,
917    source_path: &str,
918    content_hash: &str,
919    artifact: &Node,
920    document_resources: &[InfrastructureResource],
921    deployments: &mut [DeploymentInfo],
922    resources: &mut Vec<ResourceInfo>,
923    dependencies: &mut Vec<PendingDependency>,
924) {
925    for resource in document_resources {
926        let line = infrastructure_line(&resource.evidence);
927        let node = infrastructure_resource_node(repo_id, resource);
928        if let Some(node) = node {
929            let evidence = extraction_evidence(
930                repo_id,
931                source_path,
932                content_hash,
933                line,
934                line,
935                "code-system-graph.extraction.infrastructure",
936                "infrastructure resource declaration",
937            );
938            builder.edge(artifact, &node, EdgeKind::Contains, &evidence);
939            builder.node(node.clone());
940            builder.evidence(evidence);
941            let aliases = BTreeSet::from([
942                resource.name.clone(),
943                format!("{}.{}", resource.resource_type, resource.name),
944                format!("{}/{}", resource.resource_type, resource.name),
945                node.stable_key.clone(),
946            ]);
947            resources.push(ResourceInfo {
948                node: node.clone(),
949                aliases: aliases.clone(),
950            });
951            for deployment in &mut *deployments {
952                if deployment.repo_id == *repo_id && deployment.node.label == resource.name {
953                    deployment.aliases.extend(aliases.iter().cloned());
954                }
955            }
956            dependencies.extend(
957                resource
958                    .dependencies
959                    .iter()
960                    .map(|target| PendingDependency {
961                        source: node.clone(),
962                        target: target.clone(),
963                        repo_id: repo_id.clone(),
964                        source_path: source_path.to_owned(),
965                        content_hash: content_hash.to_owned(),
966                        line,
967                    }),
968            );
969        }
970        append_resource_config_keys(
971            builder,
972            repo_id,
973            source_path,
974            content_hash,
975            artifact,
976            resource,
977            line,
978        );
979    }
980}
981
982fn infrastructure_resource_node(
983    repo_id: &RepoId,
984    resource: &InfrastructureResource,
985) -> Option<Node> {
986    match resource.kind {
987        InfrastructureResourceKind::Service => Some(service_node(repo_id, &resource.name)),
988        InfrastructureResourceKind::Database => Some(database_node(&resource.name)),
989        InfrastructureResourceKind::Topic | InfrastructureResourceKind::Queue => Some(
990            event_channel_node(resource.namespace.as_deref(), &resource.name),
991        ),
992        InfrastructureResourceKind::Ingress | InfrastructureResourceKind::Other => None,
993    }
994}
995
996fn append_resource_config_keys(
997    builder: &mut GraphBuilder,
998    repo_id: &RepoId,
999    source_path: &str,
1000    content_hash: &str,
1001    artifact: &Node,
1002    resource: &InfrastructureResource,
1003    line: Option<u32>,
1004) {
1005    for key_name in &resource.key_names {
1006        let scope = format!(
1007            "resource:{}:{}:{}",
1008            resource.resource_type,
1009            resource.namespace.as_deref().unwrap_or(""),
1010            resource.name
1011        );
1012        let config = resolve_or_create_config(builder, repo_id, &scope, key_name);
1013        let evidence = extraction_evidence(
1014            repo_id,
1015            source_path,
1016            content_hash,
1017            line,
1018            line,
1019            "code-system-graph.extraction.infrastructure",
1020            "infrastructure configuration key",
1021        );
1022        builder.edge(artifact, &config, EdgeKind::Configures, &evidence);
1023        builder.node(config);
1024        builder.evidence(evidence);
1025    }
1026}
1027
1028fn append_document_environment_keys(
1029    builder: &mut GraphBuilder,
1030    repo_id: &RepoId,
1031    source_path: &str,
1032    content_hash: &str,
1033    artifact: &Node,
1034    key_names: &[String],
1035) {
1036    for key_name in key_names {
1037        let config = resolve_or_create_config(builder, repo_id, "environment", key_name);
1038        let evidence = extraction_evidence(
1039            repo_id,
1040            source_path,
1041            content_hash,
1042            None,
1043            None,
1044            "code-system-graph.extraction.infrastructure",
1045            "environment key declaration",
1046        );
1047        builder.edge(artifact, &config, EdgeKind::Configures, &evidence);
1048        builder.node(config);
1049        builder.evidence(evidence);
1050    }
1051}
1052
1053fn append_documentation_documents(
1054    builder: &mut GraphBuilder,
1055    inputs: &[(&RepoId, &str, &str, &DocumentationDocument)],
1056    known_nodes: &[Node],
1057    repository_aliases: &[RepositoryReference<'_>],
1058) {
1059    let mut references = Vec::new();
1060    for (repo_id, source_path, content_hash, document) in inputs {
1061        let artifact = append_artifact(
1062            builder,
1063            repo_id,
1064            source_path,
1065            content_hash,
1066            "code-system-graph.extraction.documents",
1067            "documentation artifact",
1068        );
1069        append_document_records(
1070            builder,
1071            repo_id,
1072            source_path,
1073            content_hash,
1074            &artifact,
1075            &document.records,
1076            &mut references,
1077        );
1078        append_ownership_rules(
1079            builder,
1080            repo_id,
1081            source_path,
1082            content_hash,
1083            &document.ownership_rules,
1084        );
1085    }
1086
1087    let mut candidates = builder.facts.nodes.clone();
1088    candidates.extend_from_slice(known_nodes);
1089    for (alias, repo_id, _) in repository_aliases {
1090        if !alias.is_empty() {
1091            candidates.push(repository_node(repo_id));
1092        }
1093    }
1094    link_document_references(builder, &candidates, repository_aliases, references);
1095}
1096
1097fn link_document_references(
1098    builder: &mut GraphBuilder,
1099    candidates: &[Node],
1100    repository_aliases: &[RepositoryReference<'_>],
1101    references: Vec<PendingReference>,
1102) {
1103    for pending in references {
1104        let Some(target) = resolve_reference(
1105            candidates,
1106            repository_aliases,
1107            &pending.repo_id,
1108            &pending.reference,
1109        ) else {
1110            if pending.reference.kind == ExplicitReferenceKind::RepositoryDependency {
1111                builder.facts.coverage_gaps.push(RepositoryCoverageGap {
1112                    repo_id: pending.repo_id.clone(),
1113                    reason: format!(
1114                        "An explicit repository dependency at {}:{} could not be matched to an exact registered remote; no dependency edge was asserted.",
1115                        pending.source_path,
1116                        pending.reference.evidence.start
1117                    ),
1118                });
1119            }
1120            continue;
1121        };
1122        let evidence = extraction_evidence(
1123            &pending.repo_id,
1124            &pending.source_path,
1125            &pending.content_hash,
1126            Some(pending.reference.evidence.start),
1127            Some(pending.reference.evidence.end),
1128            "code-system-graph.extraction.documents",
1129            "explicit document reference",
1130        );
1131        if pending.reference.kind == ExplicitReferenceKind::RepositoryDependency {
1132            let source = repository_node(&pending.repo_id);
1133            builder.edge(&source, &target, EdgeKind::DependsOnRepository, &evidence);
1134            builder.node(source);
1135        } else {
1136            builder.edge(&pending.document, &target, EdgeKind::Documents, &evidence);
1137        }
1138        builder.node(target);
1139        builder.evidence(evidence);
1140    }
1141}
1142
1143fn append_document_records(
1144    builder: &mut GraphBuilder,
1145    repo_id: &RepoId,
1146    source_path: &str,
1147    content_hash: &str,
1148    artifact: &Node,
1149    records: &[DocumentRecord],
1150    references: &mut Vec<PendingReference>,
1151) {
1152    for record in records {
1153        let node = document_node(
1154            repo_id,
1155            &record.source_path,
1156            record.kind,
1157            record.title.as_deref(),
1158        );
1159        let record_evidence = extraction_evidence(
1160            repo_id,
1161            source_path,
1162            content_hash,
1163            None,
1164            None,
1165            "code-system-graph.extraction.documents",
1166            "document record",
1167        );
1168        builder.edge(artifact, &node, EdgeKind::Contains, &record_evidence);
1169        builder.node(node.clone());
1170        builder.evidence(record_evidence);
1171        let catalog_service = (record.kind == DocumentKind::ServiceCatalog)
1172            .then_some(record.title.as_deref())
1173            .flatten()
1174            .map(|name| service_node(repo_id, name));
1175        if let Some(service) = &catalog_service {
1176            builder.node(service.clone());
1177        }
1178        for owner_name in &record.owners {
1179            let owner = owner_node(owner_name);
1180            let owner_range = record
1181                .references
1182                .iter()
1183                .find(|reference| {
1184                    reference.kind == ExplicitReferenceKind::Owner
1185                        && reference.target == *owner_name
1186                })
1187                .map(|reference| reference.evidence);
1188            let evidence = extraction_evidence(
1189                repo_id,
1190                source_path,
1191                content_hash,
1192                owner_range.map(|range| range.start),
1193                owner_range.map(|range| range.end),
1194                "code-system-graph.extraction.documents",
1195                "explicit ownership declaration",
1196            );
1197            let ownership_subject = catalog_service.as_ref().unwrap_or(&node);
1198            builder.edge(ownership_subject, &owner, EdgeKind::OwnedBy, &evidence);
1199            builder.node(owner);
1200            builder.evidence(evidence);
1201        }
1202        references.extend(
1203            record
1204                .references
1205                .iter()
1206                .cloned()
1207                .map(|reference| PendingReference {
1208                    document: node.clone(),
1209                    repo_id: repo_id.clone(),
1210                    source_path: source_path.to_owned(),
1211                    content_hash: content_hash.to_owned(),
1212                    reference,
1213                }),
1214        );
1215    }
1216}
1217
1218fn append_ownership_rules(
1219    builder: &mut GraphBuilder,
1220    repo_id: &RepoId,
1221    source_path: &str,
1222    content_hash: &str,
1223    rules: &[OwnershipRule],
1224) {
1225    let document = document_node(
1226        repo_id,
1227        source_path,
1228        DocumentKind::Codeowners,
1229        Some("CODEOWNERS"),
1230    );
1231    for rule in rules {
1232        for owner_name in &rule.owners {
1233            let owner = owner_node(owner_name);
1234            let evidence = extraction_evidence(
1235                repo_id,
1236                source_path,
1237                content_hash,
1238                Some(rule.line),
1239                Some(rule.line),
1240                "code-system-graph.extraction.documents",
1241                "CODEOWNERS owner declaration",
1242            );
1243            builder.edge(&document, &owner, EdgeKind::OwnedBy, &evidence);
1244            builder.node(document.clone());
1245            builder.node(owner);
1246            builder.evidence(evidence);
1247        }
1248    }
1249}
1250
1251fn append_artifact(
1252    builder: &mut GraphBuilder,
1253    repo_id: &RepoId,
1254    source_path: &str,
1255    content_hash: &str,
1256    extractor: &str,
1257    note: &str,
1258) -> Node {
1259    let repository = repository_node(repo_id);
1260    let artifact = artifact_node(repo_id, source_path);
1261    let evidence = extraction_evidence(
1262        repo_id,
1263        source_path,
1264        content_hash,
1265        Some(1),
1266        Some(1),
1267        extractor,
1268        note,
1269    );
1270    builder.edge(&repository, &artifact, EdgeKind::Contains, &evidence);
1271    builder.node(repository);
1272    builder.node(artifact.clone());
1273    builder.evidence(evidence);
1274    artifact
1275}
1276
1277fn table_info(document: &DataDocument, table: &DatabaseTable) -> TableInfo {
1278    let database = table
1279        .database
1280        .clone()
1281        .or_else(|| document.database_name.clone());
1282    let schema = table
1283        .schema
1284        .clone()
1285        .or_else(|| document.schema_name.clone());
1286    let node = table_node(database.as_deref(), schema.as_deref(), &table.name);
1287    let columns = table
1288        .columns
1289        .iter()
1290        .map(|column| {
1291            (
1292                column.name.clone(),
1293                column_node(&node.stable_key, &column.name),
1294            )
1295        })
1296        .collect();
1297    TableInfo {
1298        node,
1299        database,
1300        schema,
1301        name: table.name.clone(),
1302        columns,
1303    }
1304}
1305
1306fn resolve_table<'a>(
1307    tables: &'a BTreeMap<String, TableInfo>,
1308    target: &str,
1309) -> Option<&'a TableInfo> {
1310    let matches = tables
1311        .values()
1312        .filter(|table| table_aliases(table).contains(target))
1313        .map(|table| table.node.id.clone())
1314        .collect::<BTreeSet<_>>();
1315    let id = exactly_one(matches)?;
1316    tables.values().find(|table| table.node.id == id)
1317}
1318
1319fn table_aliases(table: &TableInfo) -> BTreeSet<String> {
1320    let mut aliases = BTreeSet::from([
1321        table.node.stable_key.clone(),
1322        table
1323            .node
1324            .stable_key
1325            .strip_prefix("table:")
1326            .unwrap_or(&table.node.stable_key)
1327            .to_owned(),
1328        table.name.clone(),
1329    ]);
1330    if let Some(schema) = &table.schema {
1331        aliases.insert(format!("{schema}.{}", table.name));
1332    }
1333    if let Some(database) = &table.database {
1334        aliases.insert(format!("{database}.{}", table.name));
1335        if let Some(schema) = &table.schema {
1336            aliases.insert(format!("{database}.{schema}.{}", table.name));
1337        }
1338    }
1339    aliases
1340}
1341
1342fn resolve_or_create_config(
1343    builder: &GraphBuilder,
1344    repo_id: &RepoId,
1345    fallback_scope: &str,
1346    name: &str,
1347) -> Node {
1348    let matches = builder
1349        .facts
1350        .nodes
1351        .iter()
1352        .filter(|node| {
1353            node.kind == NodeKind::ConfigKey
1354                && node.repo_id.as_ref() == Some(repo_id)
1355                && node.label == name
1356        })
1357        .map(|node| node.id.clone())
1358        .collect::<BTreeSet<_>>();
1359    exactly_one(matches)
1360        .and_then(|id| {
1361            builder
1362                .facts
1363                .nodes
1364                .iter()
1365                .find(|node| node.id == id)
1366                .cloned()
1367        })
1368        .unwrap_or_else(|| config_node(repo_id, fallback_scope, name))
1369}
1370
1371fn resolve_infrastructure_target(
1372    deployments: &[DeploymentInfo],
1373    resources: &[ResourceInfo],
1374    target: &str,
1375) -> Option<Node> {
1376    let deployment_matches = deployments
1377        .iter()
1378        .filter(|deployment| deployment.aliases.contains(target))
1379        .map(|deployment| deployment.node.id.clone())
1380        .collect::<BTreeSet<_>>();
1381    if !deployment_matches.is_empty() {
1382        let id = exactly_one(deployment_matches)?;
1383        return deployments
1384            .iter()
1385            .find(|deployment| deployment.node.id == id)
1386            .map(|deployment| deployment.node.clone());
1387    }
1388    let resource_matches = resources
1389        .iter()
1390        .filter(|resource| resource.aliases.contains(target))
1391        .map(|resource| resource.node.id.clone())
1392        .collect::<BTreeSet<_>>();
1393    let id = exactly_one(resource_matches)?;
1394    resources
1395        .iter()
1396        .find(|resource| resource.node.id == id)
1397        .map(|resource| resource.node.clone())
1398}
1399
1400fn resolve_reference(
1401    candidates: &[Node],
1402    repository_aliases: &[RepositoryReference<'_>],
1403    repo_id: &RepoId,
1404    reference: &ExplicitReference,
1405) -> Option<Node> {
1406    let matches = candidates
1407        .iter()
1408        .filter(|node| {
1409            reference_matches(
1410                node,
1411                repository_aliases,
1412                repo_id,
1413                reference.kind,
1414                &reference.target,
1415            )
1416        })
1417        .map(|node| node.id.clone())
1418        .collect::<BTreeSet<_>>();
1419    let id = exactly_one(matches)?;
1420    candidates.iter().find(|node| node.id == id).cloned()
1421}
1422
1423fn reference_matches(
1424    node: &Node,
1425    repository_aliases: &[RepositoryReference<'_>],
1426    repo_id: &RepoId,
1427    kind: ExplicitReferenceKind,
1428    target: &str,
1429) -> bool {
1430    let expected = match kind {
1431        ExplicitReferenceKind::Repository | ExplicitReferenceKind::RepositoryDependency => {
1432            &[NodeKind::Repository][..]
1433        }
1434        ExplicitReferenceKind::Service => &[NodeKind::Service][..],
1435        ExplicitReferenceKind::HttpContract => &[NodeKind::HttpOperation][..],
1436        ExplicitReferenceKind::EventChannel => &[NodeKind::EventChannel][..],
1437        ExplicitReferenceKind::GraphqlOperation => &[NodeKind::GraphqlOperation][..],
1438        ExplicitReferenceKind::RpcMethod => &[NodeKind::RpcMethod][..],
1439        ExplicitReferenceKind::DatabaseTable => &[NodeKind::DatabaseTable][..],
1440        ExplicitReferenceKind::Deployment => &[NodeKind::Deployment][..],
1441        ExplicitReferenceKind::ConfigKey => &[NodeKind::ConfigKey][..],
1442        ExplicitReferenceKind::Document => &[NodeKind::Document, NodeKind::Adr][..],
1443        ExplicitReferenceKind::Owner => &[NodeKind::Owner][..],
1444    };
1445    if !expected.contains(&node.kind) {
1446        return false;
1447    }
1448    if matches!(
1449        kind,
1450        ExplicitReferenceKind::Repository | ExplicitReferenceKind::RepositoryDependency
1451    ) {
1452        return node.repo_id.as_ref().is_some_and(|candidate| {
1453            candidate.as_str() == target
1454                || repository_aliases.iter().any(|(alias, repo, remote)| {
1455                    (*alias == target || remote.is_some_and(|remote| remote == target))
1456                        && *repo == candidate
1457                })
1458        });
1459    }
1460    if node.stable_key == target || node.label == target {
1461        return true;
1462    }
1463    let prefix = reference_prefix(kind);
1464    if node
1465        .stable_key
1466        .strip_prefix(prefix)
1467        .is_some_and(|suffix| suffix == target)
1468    {
1469        return true;
1470    }
1471    match kind {
1472        ExplicitReferenceKind::Service => {
1473            target
1474                .split_once(':')
1475                .and_then(|(alias, name)| {
1476                    repository_aliases
1477                        .iter()
1478                        .find(|(candidate, _, _)| *candidate == alias)
1479                        .map(|(_, repository, _)| (repository, name))
1480                })
1481                .is_some_and(|(repository, name)| {
1482                    node.stable_key == format!("service:{}:{name}", repository.as_str())
1483                })
1484                || node.stable_key == format!("service:{}:{target}", repo_id.as_str())
1485        }
1486        ExplicitReferenceKind::Document => {
1487            node.stable_key == format!("document:{}:{target}", repo_id.as_str())
1488        }
1489        ExplicitReferenceKind::ConfigKey => {
1490            node.stable_key == format!("config:{}:{target}", repo_id.as_str())
1491        }
1492        ExplicitReferenceKind::Repository
1493        | ExplicitReferenceKind::RepositoryDependency
1494        | ExplicitReferenceKind::HttpContract
1495        | ExplicitReferenceKind::EventChannel
1496        | ExplicitReferenceKind::GraphqlOperation
1497        | ExplicitReferenceKind::RpcMethod
1498        | ExplicitReferenceKind::DatabaseTable
1499        | ExplicitReferenceKind::Deployment
1500        | ExplicitReferenceKind::Owner => false,
1501    }
1502}
1503
1504const fn reference_prefix(kind: ExplicitReferenceKind) -> &'static str {
1505    match kind {
1506        ExplicitReferenceKind::Repository | ExplicitReferenceKind::RepositoryDependency => {
1507            "repository:"
1508        }
1509        ExplicitReferenceKind::Service => "service:",
1510        ExplicitReferenceKind::HttpContract => "http:",
1511        ExplicitReferenceKind::EventChannel => "event:",
1512        ExplicitReferenceKind::GraphqlOperation => "graphql:",
1513        ExplicitReferenceKind::RpcMethod => "rpc:",
1514        ExplicitReferenceKind::DatabaseTable => "table:",
1515        ExplicitReferenceKind::Deployment => "deployment:",
1516        ExplicitReferenceKind::ConfigKey => "config:",
1517        ExplicitReferenceKind::Document => "document:",
1518        ExplicitReferenceKind::Owner => "owner:",
1519    }
1520}
1521
1522fn exactly_one<T: Ord>(mut values: BTreeSet<T>) -> Option<T> {
1523    (values.len() == 1).then(|| values.pop_first()).flatten()
1524}
1525
1526fn repository_node(repo_id: &RepoId) -> Node {
1527    graph_node(
1528        format!("repository:{}", repo_id.as_str()),
1529        NodeKind::Repository,
1530        Some(repo_id.clone()),
1531        repo_id.as_str(),
1532    )
1533}
1534
1535fn artifact_node(repo_id: &RepoId, source_path: &str) -> Node {
1536    graph_node(
1537        format!("artifact:{}:{source_path}", repo_id.as_str()),
1538        NodeKind::Artifact,
1539        Some(repo_id.clone()),
1540        source_path,
1541    )
1542}
1543
1544fn database_node(name: &str) -> Node {
1545    graph_node(format!("database:{name}"), NodeKind::Database, None, name)
1546}
1547
1548fn table_node(database: Option<&str>, schema: Option<&str>, name: &str) -> Node {
1549    graph_node(
1550        format!(
1551            "table:{}:{}:{name}",
1552            database.unwrap_or(""),
1553            schema.unwrap_or("")
1554        ),
1555        NodeKind::DatabaseTable,
1556        None,
1557        name,
1558    )
1559}
1560
1561fn column_node(table_key: &str, name: &str) -> Node {
1562    graph_node(
1563        format!("column:{table_key}:{name}"),
1564        NodeKind::DatabaseColumn,
1565        None,
1566        name,
1567    )
1568}
1569
1570fn index_known_source_symbols(nodes: &[Node]) -> KnownSourceSymbols {
1571    nodes
1572        .iter()
1573        .filter_map(|node| {
1574            let identity = crate::SourceSymbolIdentity::from_node(node)?;
1575            identity.language()?;
1576            // A line-scoped consumer cannot identify an unqualified data owner.
1577            if identity.declaration_line().is_some() {
1578                return None;
1579            }
1580            Some((
1581                (
1582                    identity.repository().clone(),
1583                    identity.source_path().to_owned(),
1584                    identity.symbol().to_owned(),
1585                ),
1586                node.clone(),
1587            ))
1588        })
1589        .collect()
1590}
1591
1592fn data_symbol_node(
1593    repo_id: &RepoId,
1594    source_path: &str,
1595    owner: &str,
1596    source_symbols: &KnownSourceSymbols,
1597) -> Node {
1598    if let Some(node) =
1599        source_symbols.get(&(repo_id.clone(), source_path.to_owned(), owner.to_owned()))
1600    {
1601        return node.clone();
1602    }
1603    crate::SourceSymbolIdentity::data(repo_id.clone(), source_path, owner).node(owner)
1604}
1605
1606fn deployment_node(technology: &str, namespace: Option<&str>, name: &str) -> Node {
1607    graph_node(
1608        format!("deployment:{technology}:{}:{name}", namespace.unwrap_or("")),
1609        NodeKind::Deployment,
1610        None,
1611        name,
1612    )
1613}
1614
1615fn service_node(repo_id: &RepoId, name: &str) -> Node {
1616    graph_node(
1617        format!("service:{}:{name}", repo_id.as_str()),
1618        NodeKind::Service,
1619        Some(repo_id.clone()),
1620        name,
1621    )
1622}
1623
1624fn config_node(repo_id: &RepoId, scope: &str, name: &str) -> Node {
1625    graph_node(
1626        format!("config:{}:{scope}:{name}", repo_id.as_str()),
1627        NodeKind::ConfigKey,
1628        Some(repo_id.clone()),
1629        name,
1630    )
1631}
1632
1633fn event_channel_node(namespace: Option<&str>, name: &str) -> Node {
1634    graph_node(
1635        format!("event:infrastructure:{}:{name}", namespace.unwrap_or("")),
1636        NodeKind::EventChannel,
1637        None,
1638        name,
1639    )
1640}
1641
1642fn document_node(
1643    repo_id: &RepoId,
1644    source_path: &str,
1645    kind: DocumentKind,
1646    _title: Option<&str>,
1647) -> Node {
1648    graph_node(
1649        format!("document:{}:{source_path}", repo_id.as_str()),
1650        if kind == DocumentKind::Adr {
1651            NodeKind::Adr
1652        } else {
1653            NodeKind::Document
1654        },
1655        Some(repo_id.clone()),
1656        source_path,
1657    )
1658}
1659
1660fn owner_node(name: &str) -> Node {
1661    graph_node(format!("owner:{name}"), NodeKind::Owner, None, name)
1662}
1663
1664fn graph_node(stable_key: String, kind: NodeKind, repo_id: Option<RepoId>, label: &str) -> Node {
1665    Node {
1666        id: NodeId::new(stable_id("node", &stable_key)),
1667        kind,
1668        repo_id,
1669        stable_key,
1670        label: label.to_owned(),
1671    }
1672}
1673
1674fn extraction_evidence(
1675    repo_id: &RepoId,
1676    source_path: &str,
1677    content_hash: &str,
1678    start_line: Option<u32>,
1679    end_line: Option<u32>,
1680    extractor: &str,
1681    note: &str,
1682) -> Evidence {
1683    let key = format!(
1684        "{}:{source_path}:{}:{}:{extractor}:{note}:{content_hash}",
1685        repo_id.as_str(),
1686        start_line.map_or_else(String::new, |line| line.to_string()),
1687        end_line.map_or_else(String::new, |line| line.to_string())
1688    );
1689    Evidence {
1690        id: EvidenceId::new(stable_id("evidence", &key)),
1691        repo_id: Some(repo_id.clone()),
1692        file_path: Some(source_path.to_owned()),
1693        start_line,
1694        end_line,
1695        extractor: extractor.to_owned(),
1696        extractor_version: "1.0.0".to_owned(),
1697        provenance: Provenance::Extracted,
1698        confidence: 1.0,
1699        observed_at_commit: None,
1700        content_hash: Some(content_hash.to_owned()),
1701        note: Some(note.to_owned()),
1702    }
1703}
1704
1705const fn deployment_technology(kind: DeploymentKind) -> &'static str {
1706    match kind {
1707        DeploymentKind::DockerComposeService => "docker_compose_service",
1708        DeploymentKind::KubernetesDeployment => "kubernetes_deployment",
1709        DeploymentKind::KubernetesStatefulSet => "kubernetes_stateful_set",
1710        DeploymentKind::KubernetesDaemonSet => "kubernetes_daemon_set",
1711        DeploymentKind::KubernetesJob => "kubernetes_job",
1712        DeploymentKind::KubernetesCronJob => "kubernetes_cron_job",
1713        DeploymentKind::KubernetesPod => "kubernetes_pod",
1714        DeploymentKind::HelmTemplate => "helm_template",
1715        DeploymentKind::TerraformResource => "terraform_resource",
1716    }
1717}
1718
1719fn infrastructure_line(evidence: &[InfrastructureEvidence]) -> Option<u32> {
1720    evidence.iter().filter_map(|item| item.line).min()
1721}
1722
1723fn line_from_usize(line: usize) -> Option<u32> {
1724    u32::try_from(line).ok()
1725}
1726
1727#[cfg(test)]
1728mod tests {
1729    use code_system_graph_model::{EdgeKind, Node, NodeId, NodeKind, RepoId, stable_id};
1730
1731    use super::documents_to_graph;
1732    use crate::{
1733        DataAccessObservation, DataAccessRole, DataArtifactKind, DataDocument, DataEvidenceLine, DataOperation, DatabaseTable, DeploymentKind, DeploymentUnit, InfrastructureArtifactKind, InfrastructureDocument, InfrastructureEvidence, InfrastructureEvidenceKind, SourceLanguage, extract_data_artifact, extract_markdown, extract_safe_config, extract_service_catalog, parse_literal_sql_source_at_root
1734    };
1735
1736    #[test]
1737    fn data_reader_links_source_symbol_to_unique_table() {
1738        let repo = RepoId::new("repo:data");
1739        let line = DataEvidenceLine::new(7).expect("valid evidence line");
1740        let declaration = DataDocument {
1741            source_path: "schema.sql".to_owned(),
1742            artifact_kind: DataArtifactKind::DeclarativeSqlSchema,
1743            database_name: None,
1744            schema_name: None,
1745            tables: vec![DatabaseTable {
1746                database: None,
1747                schema: None,
1748                name: "users".to_owned(),
1749                columns: Vec::new(),
1750                indexes: Vec::new(),
1751                foreign_keys: Vec::new(),
1752                evidence: line,
1753            }],
1754            migration: None,
1755            accesses: Vec::new(),
1756            frameworks: Vec::new(),
1757            references: Vec::new(),
1758            owners: Vec::new(),
1759            warnings: Vec::new(),
1760            incomplete: false,
1761        };
1762        let reader = DataDocument {
1763            source_path: "src/users.rs".to_owned(),
1764            artifact_kind: DataArtifactKind::LiteralQuerySource,
1765            database_name: None,
1766            schema_name: None,
1767            tables: Vec::new(),
1768            migration: None,
1769            accesses: vec![DataAccessObservation {
1770                role: DataAccessRole::Reader,
1771                table: "users".to_owned(),
1772                model: None,
1773                owner: Some("load_users".to_owned()),
1774                operation: Some(DataOperation::Select),
1775                evidence: line,
1776            }],
1777            frameworks: Vec::new(),
1778            references: Vec::new(),
1779            owners: vec!["load_users".to_owned()],
1780            warnings: Vec::new(),
1781            incomplete: false,
1782        };
1783
1784        let facts = documents_to_graph(
1785            &[
1786                (&repo, "schema.sql", "schema-hash", &declaration),
1787                (&repo, "src/users.rs", "source-hash", &reader),
1788            ],
1789            &[],
1790            &[],
1791            &[],
1792            &[],
1793            &[],
1794        );
1795
1796        assert!(facts.edges.iter().any(|edge| {
1797            edge.kind == EdgeKind::ReadsTable
1798                && facts.nodes.iter().any(|node| {
1799                    node.id == edge.source
1800                        && node.kind == NodeKind::SymbolRef
1801                        && node.label == "load_users"
1802                })
1803                && facts.nodes.iter().any(|node| {
1804                    node.id == edge.target
1805                        && node.kind == NodeKind::DatabaseTable
1806                        && node.label == "users"
1807                })
1808        }));
1809    }
1810
1811    #[test]
1812    fn data_reader_reuses_exact_known_source_symbol() {
1813        let repo = RepoId::new("repo:data");
1814        let line = DataEvidenceLine::new(7).expect("valid evidence line");
1815        let declaration = DataDocument {
1816            source_path: "schema.sql".to_owned(),
1817            artifact_kind: DataArtifactKind::DeclarativeSqlSchema,
1818            database_name: None,
1819            schema_name: None,
1820            tables: vec![DatabaseTable {
1821                database: None,
1822                schema: None,
1823                name: "users".to_owned(),
1824                columns: Vec::new(),
1825                indexes: Vec::new(),
1826                foreign_keys: Vec::new(),
1827                evidence: line,
1828            }],
1829            migration: None,
1830            accesses: Vec::new(),
1831            frameworks: Vec::new(),
1832            references: Vec::new(),
1833            owners: Vec::new(),
1834            warnings: Vec::new(),
1835            incomplete: false,
1836        };
1837        let reader = DataDocument {
1838            source_path: "src/users.rs".to_owned(),
1839            artifact_kind: DataArtifactKind::LiteralQuerySource,
1840            database_name: None,
1841            schema_name: None,
1842            tables: Vec::new(),
1843            migration: None,
1844            accesses: vec![DataAccessObservation {
1845                role: DataAccessRole::Reader,
1846                table: "users".to_owned(),
1847                model: None,
1848                owner: Some("load_users".to_owned()),
1849                operation: Some(DataOperation::Select),
1850                evidence: line,
1851            }],
1852            frameworks: Vec::new(),
1853            references: Vec::new(),
1854            owners: vec!["load_users".to_owned()],
1855            warnings: Vec::new(),
1856            incomplete: false,
1857        };
1858        let stable_key = "symbol:repo:data:rust:src/users.rs:load_users".to_owned();
1859        let source_symbol = Node {
1860            id: NodeId::new(stable_id("node", &stable_key)),
1861            kind: NodeKind::SymbolRef,
1862            repo_id: Some(repo.clone()),
1863            stable_key,
1864            label: "rust::load_users".to_owned(),
1865        };
1866
1867        let facts = documents_to_graph(
1868            &[
1869                (&repo, "schema.sql", "schema-hash", &declaration),
1870                (&repo, "src/users.rs", "source-hash", &reader),
1871            ],
1872            &[],
1873            &[],
1874            &[],
1875            std::slice::from_ref(&source_symbol),
1876            &[],
1877        );
1878
1879        assert!(facts.nodes.iter().any(|node| node == &source_symbol));
1880        assert!(
1881            !facts
1882                .nodes
1883                .iter()
1884                .any(|node| node.stable_key.starts_with("data-symbol:"))
1885        );
1886        assert!(
1887            facts.edges.iter().any(|edge| {
1888                edge.source == source_symbol.id && edge.kind == EdgeKind::ReadsTable
1889            })
1890        );
1891    }
1892
1893    #[test]
1894    fn sqlalchemy_access_links_through_explicit_model_binding() {
1895        let repo = RepoId::new("repo:orm");
1896        let models = extract_data_artifact(
1897            "app/models.py",
1898            r#"
1899class Services(Base):
1900    __tablename__ = "services"
1901    id = Column(Integer, primary_key=True)
1902"#,
1903        )
1904        .expect("model should parse");
1905        let controller = parse_literal_sql_source_at_root(
1906            SourceLanguage::Python,
1907            "app/controllers.py",
1908            "",
1909            r"
1910from sqlalchemy.orm import Session
1911from app import models
1912
1913def list_services(db: Session):
1914    return db.query(models.Services).all()
1915
1916def create_service(db: Session):
1917    service = models.Services()
1918    db.add(service)
1919",
1920        );
1921
1922        let facts = documents_to_graph(
1923            &[
1924                (&repo, "app/models.py", "models-hash", &models),
1925                (&repo, "app/controllers.py", "controllers-hash", &controller),
1926            ],
1927            &[],
1928            &[],
1929            &[],
1930            &[],
1931            &[],
1932        );
1933
1934        assert!(facts.edges.iter().any(|edge| {
1935            edge.kind == EdgeKind::ReadsTable
1936                && facts
1937                    .nodes
1938                    .iter()
1939                    .any(|node| node.id == edge.source && node.label == "list_services")
1940                && facts
1941                    .nodes
1942                    .iter()
1943                    .any(|node| node.id == edge.target && node.label == "services")
1944        }));
1945        assert!(facts.edges.iter().any(|edge| {
1946            edge.kind == EdgeKind::WritesTable
1947                && facts
1948                    .nodes
1949                    .iter()
1950                    .any(|node| node.id == edge.source && node.label == "create_service")
1951                && facts
1952                    .nodes
1953                    .iter()
1954                    .any(|node| node.id == edge.target && node.label == "services")
1955        }));
1956    }
1957
1958    #[test]
1959    fn sqlx_query_file_links_calling_symbol_to_file_and_table() {
1960        let repo = RepoId::new("repo:data");
1961        let schema =
1962            extract_data_artifact("crates/api/schema.sql", "CREATE TABLE users (id INTEGER);")
1963                .expect("schema should parse");
1964        let query = extract_data_artifact(
1965            "crates/api/queries/users.sql",
1966            "SELECT id FROM users WHERE id = $1;",
1967        )
1968        .expect("query should parse");
1969        let source = parse_literal_sql_source_at_root(
1970            SourceLanguage::Rust,
1971            "crates/api/src/users.rs",
1972            "crates/api",
1973            r#"
1974async fn load_user(pool: &sqlx::PgPool) {
1975    sqlx::query_file!("queries/users.sql", 7_i64).fetch_one(pool).await;
1976}
1977"#,
1978        );
1979
1980        let facts = documents_to_graph(
1981            &[
1982                (&repo, "crates/api/schema.sql", "schema-hash", &schema),
1983                (&repo, "crates/api/queries/users.sql", "query-hash", &query),
1984                (&repo, "crates/api/src/users.rs", "source-hash", &source),
1985            ],
1986            &[],
1987            &[],
1988            &[],
1989            &[],
1990            &[],
1991        );
1992        let symbol = facts
1993            .nodes
1994            .iter()
1995            .find(|node| node.kind == NodeKind::SymbolRef && node.label == "load_user")
1996            .expect("calling symbol");
1997        let query_artifact = facts
1998            .nodes
1999            .iter()
2000            .find(|node| {
2001                node.kind == NodeKind::Artifact && node.label == "crates/api/queries/users.sql"
2002            })
2003            .expect("query artifact");
2004        let users = facts
2005            .nodes
2006            .iter()
2007            .find(|node| node.kind == NodeKind::DatabaseTable && node.label == "users")
2008            .expect("users table");
2009
2010        assert!(facts.edges.iter().any(|edge| {
2011            edge.source == symbol.id
2012                && edge.target == query_artifact.id
2013                && edge.kind == EdgeKind::Consumes
2014        }));
2015        assert!(facts.edges.iter().any(|edge| {
2016            edge.source == symbol.id && edge.target == users.id && edge.kind == EdgeKind::ReadsTable
2017        }));
2018    }
2019
2020    #[test]
2021    fn sqlx_default_migrate_macro_uses_incremental_configuration_artifact() {
2022        let repo = RepoId::new("repo:data");
2023        let source = parse_literal_sql_source_at_root(
2024            SourceLanguage::Rust,
2025            "crates/api/src/lib.rs",
2026            "crates/api",
2027            "static MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate!();",
2028        );
2029        let configuration = extract_data_artifact(
2030            "crates/api/sqlx.toml",
2031            "[migrate]\nmigrations-dir = \"db/migrations\"\n",
2032        )
2033        .expect("SQLx configuration should parse");
2034        let migration = extract_data_artifact(
2035            "crates/api/db/migrations/0001_users.sql",
2036            "CREATE TABLE users (id INTEGER);",
2037        )
2038        .expect("migration should parse");
2039
2040        let facts = documents_to_graph(
2041            &[
2042                (&repo, "crates/api/src/lib.rs", "source-hash", &source),
2043                (
2044                    &repo,
2045                    "crates/api/sqlx.toml",
2046                    "configuration-hash",
2047                    &configuration,
2048                ),
2049                (
2050                    &repo,
2051                    "crates/api/db/migrations/0001_users.sql",
2052                    "migration-hash",
2053                    &migration,
2054                ),
2055            ],
2056            &[],
2057            &[],
2058            &[],
2059            &[],
2060            &[],
2061        );
2062        let source_artifact = facts
2063            .nodes
2064            .iter()
2065            .find(|node| node.kind == NodeKind::Artifact && node.label == "crates/api/src/lib.rs")
2066            .expect("source artifact");
2067        let migration_artifact = facts
2068            .nodes
2069            .iter()
2070            .find(|node| {
2071                node.kind == NodeKind::Artifact
2072                    && node.label == "crates/api/db/migrations/0001_users.sql"
2073            })
2074            .expect("migration artifact");
2075
2076        assert!(facts.edges.iter().any(|edge| {
2077            edge.source == source_artifact.id
2078                && edge.target == migration_artifact.id
2079                && edge.kind == EdgeKind::Consumes
2080        }));
2081    }
2082
2083    #[test]
2084    fn reversible_migrations_keep_empty_artifacts_and_explicit_lineage() {
2085        let repo = RepoId::new("repo:migrations");
2086        let first_up = extract_data_artifact(
2087            "migrations/0001_users.up.sql",
2088            "CREATE TABLE users (id INTEGER);",
2089        )
2090        .expect("up migration should parse");
2091        let first_down =
2092            extract_data_artifact("migrations/0001_users.down.sql", "DROP TABLE users;")
2093                .expect("down migration should parse");
2094        let second_up = extract_data_artifact(
2095            "migrations/0002_accounts.up.sql",
2096            "CREATE TABLE accounts (id INTEGER);",
2097        )
2098        .expect("second migration should parse");
2099
2100        let facts = documents_to_graph(
2101            &[
2102                (&repo, "migrations/0001_users.up.sql", "first-up", &first_up),
2103                (
2104                    &repo,
2105                    "migrations/0001_users.down.sql",
2106                    "first-down",
2107                    &first_down,
2108                ),
2109                (
2110                    &repo,
2111                    "migrations/0002_accounts.up.sql",
2112                    "second-up",
2113                    &second_up,
2114                ),
2115            ],
2116            &[],
2117            &[],
2118            &[],
2119            &[],
2120            &[],
2121        );
2122        let artifact = |label: &str| {
2123            facts
2124                .nodes
2125                .iter()
2126                .find(|node| node.kind == NodeKind::Artifact && node.label == label)
2127                .unwrap_or_else(|| panic!("missing migration artifact {label}"))
2128        };
2129        let first_up = artifact("migrations/0001_users.up.sql");
2130        let first_down = artifact("migrations/0001_users.down.sql");
2131        let second_up = artifact("migrations/0002_accounts.up.sql");
2132
2133        assert!(facts.edges.iter().any(|edge| {
2134            edge.source == first_down.id
2135                && edge.target == first_up.id
2136                && edge.kind == EdgeKind::Reverts
2137        }));
2138        assert!(facts.edges.iter().any(|edge| {
2139            edge.source == first_up.id
2140                && edge.target == second_up.id
2141                && edge.kind == EdgeKind::Precedes
2142        }));
2143    }
2144
2145    #[test]
2146    fn repository_deploys_unit_that_provides_exact_service() {
2147        let repo = RepoId::new("repo:api");
2148        let document = InfrastructureDocument {
2149            artifact_kind: InfrastructureArtifactKind::DockerCompose,
2150            source_path: "compose.yaml".to_owned(),
2151            deployment_units: vec![DeploymentUnit {
2152                kind: DeploymentKind::DockerComposeService,
2153                name: "api".to_owned(),
2154                namespace: None,
2155                images: Vec::new(),
2156                ports: Vec::new(),
2157                environment_keys: Vec::new(),
2158                dependencies: Vec::new(),
2159                service_names: vec!["api".to_owned()],
2160                host_aliases: Vec::new(),
2161                selectors: Vec::new(),
2162                evidence: vec![InfrastructureEvidence {
2163                    kind: InfrastructureEvidenceKind::Declaration,
2164                    line: Some(2),
2165                }],
2166            }],
2167            resources: Vec::new(),
2168            environment_keys: Vec::new(),
2169            warnings: Vec::new(),
2170            incomplete: false,
2171        };
2172
2173        let facts = documents_to_graph(
2174            &[],
2175            &[(&repo, "compose.yaml", "compose-hash", &document)],
2176            &[],
2177            &[],
2178            &[],
2179            &[],
2180        );
2181
2182        assert!(
2183            [EdgeKind::Deploys, EdgeKind::Provides]
2184                .into_iter()
2185                .all(|kind| facts.edges.iter().any(|edge| edge.kind == kind))
2186        );
2187    }
2188
2189    #[test]
2190    fn explicit_catalog_references_document_service_and_owner() {
2191        let repo = RepoId::new("repo:billing");
2192        let document = extract_service_catalog(
2193            "catalog.yaml",
2194            "services:\n  - name: billing\n    owner: '@payments'\n",
2195        )
2196        .expect("valid service catalog");
2197
2198        let facts = documents_to_graph(
2199            &[],
2200            &[],
2201            &[(&repo, "catalog.yaml", "catalog-hash", &document)],
2202            &[],
2203            &[],
2204            &[],
2205        );
2206
2207        assert!(
2208            facts
2209                .edges
2210                .iter()
2211                .filter(|edge| edge.kind == EdgeKind::Documents)
2212                .any(|edge| {
2213                    facts.nodes.iter().any(|node| {
2214                        node.id == edge.target
2215                            && node.kind == NodeKind::Service
2216                            && node.label == "billing"
2217                    })
2218                })
2219                && facts
2220                    .edges
2221                    .iter()
2222                    .filter(|edge| edge.kind == EdgeKind::Documents)
2223                    .any(|edge| {
2224                        facts.nodes.iter().any(|node| {
2225                            node.id == edge.target
2226                                && node.kind == NodeKind::Owner
2227                                && node.label == "@payments"
2228                        })
2229                    })
2230        );
2231    }
2232
2233    #[test]
2234    fn explicit_generated_by_link_creates_cross_repository_dependency() {
2235        let platform = RepoId::new("repo:platform");
2236        let transpiler = RepoId::new("repo:transpiler");
2237        let document = extract_markdown(
2238            "README.md",
2239            "Generated by [hugint-transpiler](https://github.com/huginthub/hugint-transpiler).\n",
2240        )
2241        .expect("valid Markdown");
2242
2243        let facts = documents_to_graph(
2244            &[],
2245            &[],
2246            &[(&platform, "README.md", "readme-hash", &document)],
2247            &[],
2248            &[],
2249            &[
2250                (
2251                    "hugint-platform",
2252                    &platform,
2253                    Some("github.com/huginthub/hugint-platform"),
2254                ),
2255                (
2256                    "hugint-transpiler",
2257                    &transpiler,
2258                    Some("github.com/huginthub/hugint-transpiler"),
2259                ),
2260            ],
2261        );
2262
2263        let relation = facts
2264            .edges
2265            .iter()
2266            .find(|edge| {
2267                edge.kind == EdgeKind::DependsOnRepository
2268                    && facts.nodes.iter().any(|node| {
2269                        node.id == edge.source
2270                            && node.kind == NodeKind::Repository
2271                            && node.repo_id.as_ref() == Some(&platform)
2272                    })
2273                    && facts.nodes.iter().any(|node| {
2274                        node.id == edge.target
2275                            && node.kind == NodeKind::Repository
2276                            && node.repo_id.as_ref() == Some(&transpiler)
2277                    })
2278            })
2279            .expect("cross-repository dependency");
2280        assert_ne!(relation.source, relation.target);
2281    }
2282
2283    #[test]
2284    fn repository_link_with_wrong_owner_does_not_match_alias_basename() {
2285        let platform = RepoId::new("repo:platform");
2286        let payments = RepoId::new("repo:payments");
2287        let document = extract_markdown(
2288            "README.md",
2289            "Generated by [payments](https://github.com/evil-owner/payments).\n",
2290        )
2291        .expect("valid Markdown");
2292
2293        let facts = documents_to_graph(
2294            &[],
2295            &[],
2296            &[(&platform, "README.md", "readme-hash", &document)],
2297            &[],
2298            &[],
2299            &[("payments", &payments, Some("github.com/acme/payments"))],
2300        );
2301
2302        assert!(
2303            facts
2304                .edges
2305                .iter()
2306                .all(|edge| edge.kind != EdgeKind::DependsOnRepository)
2307        );
2308        assert_eq!(facts.coverage_gaps.len(), 1);
2309        assert_eq!(facts.coverage_gaps[0].repo_id, platform);
2310    }
2311
2312    #[test]
2313    fn repository_link_with_wrong_host_does_not_match_remote_slug() {
2314        let platform = RepoId::new("repo:platform");
2315        let payments = RepoId::new("repo:payments");
2316        let document = extract_markdown(
2317            "README.md",
2318            "Generated by [payments](https://github.com/acme/payments).\n",
2319        )
2320        .expect("valid Markdown");
2321
2322        let facts = documents_to_graph(
2323            &[],
2324            &[],
2325            &[(&platform, "README.md", "readme-hash", &document)],
2326            &[],
2327            &[],
2328            &[("payments", &payments, Some("gitlab.com/acme/payments"))],
2329        );
2330
2331        assert!(
2332            facts
2333                .edges
2334                .iter()
2335                .all(|edge| edge.kind != EdgeKind::DependsOnRepository)
2336        );
2337        assert_eq!(facts.coverage_gaps.len(), 1);
2338        assert_eq!(facts.coverage_gaps[0].repo_id, platform);
2339    }
2340
2341    #[test]
2342    fn serialized_graph_never_contains_fixture_secret() {
2343        const FIXTURE_SECRET: &str = "extraction-fixture-secret-5f16";
2344        let repo = RepoId::new("repo:config");
2345        let source = format!("API_TOKEN={FIXTURE_SECRET}\n");
2346        let document = extract_safe_config(".env", &source).expect("valid dotenv");
2347        let facts = documents_to_graph(
2348            &[],
2349            &[],
2350            &[],
2351            &[(&repo, ".env", "config-hash", &document)],
2352            &[],
2353            &[],
2354        );
2355
2356        let serialized = serde_json::to_string(&(&facts.nodes, &facts.edges, &facts.evidence))
2357            .expect("graph facts should serialize");
2358
2359        assert!(!serialized.contains(FIXTURE_SECRET));
2360    }
2361}