Skip to main content

code_system_graph_core/
repository_symbols.rs

1//! Per-repository resolution of source-level symbol references across files.
2//!
3//! References are resolved through file-local names, relative script imports, Python package
4//! imports, and module-qualified function paths. A reference that does not resolve to exactly one
5//! declaration stays unresolved.
6
7use std::collections::{BTreeMap, BTreeSet};
8use std::path::Path;
9
10use code_system_graph_model::RepoId;
11
12use crate::{SourceLanguage, SourceObservation, SymbolRef};
13
14const SCRIPT_EXTENSIONS: [&str; 8] = ["ts", "tsx", "js", "jsx", "mjs", "cjs", "mts", "cts"];
15
16/// Source observations of one repository-relative file, as input to repository-level
17/// composition.
18#[derive(Debug, Clone, Copy)]
19pub struct RepositorySourceFile<'a> {
20    /// Repository owning the file.
21    pub repo_id: &'a RepoId,
22    /// Portable repository-relative path.
23    pub path: &'a str,
24    /// Extracted observations of the file.
25    pub observations: &'a [SourceObservation],
26}
27
28/// Indices of `files` grouped by repository, in input order within each repository.
29pub(crate) fn files_by_repository<'a>(
30    files: &[RepositorySourceFile<'a>],
31) -> BTreeMap<&'a RepoId, Vec<usize>> {
32    let mut by_repository = BTreeMap::<&RepoId, Vec<usize>>::new();
33    for (index, file) in files.iter().enumerate() {
34        by_repository.entry(file.repo_id).or_default().push(index);
35    }
36    by_repository
37}
38
39/// Repository-relative source file with its extracted observations.
40#[derive(Debug, Clone, Copy)]
41pub(crate) struct SymbolFile<'a> {
42    pub(crate) path: &'a str,
43    pub(crate) observations: &'a [SourceObservation],
44}
45
46/// Resolved identity of a referenced symbol.
47#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
48pub(crate) enum SymbolKey {
49    /// A name bound in one file, identified by its index.
50    Local { file: usize, name: String },
51    /// A function qualified by its module path.
52    Function(Vec<String>),
53}
54
55/// Files of one repository and the module-qualified functions declared in them.
56pub(crate) struct RepositorySymbols<'a> {
57    files: Vec<SymbolFile<'a>>,
58    paths: BTreeMap<&'a str, usize>,
59    functions: BTreeSet<Vec<String>>,
60}
61
62impl<'a> RepositorySymbols<'a> {
63    pub(crate) fn new(files: Vec<SymbolFile<'a>>) -> Self {
64        let paths = files
65            .iter()
66            .enumerate()
67            .map(|(index, file)| (file.path, index))
68            .collect();
69        Self {
70            files,
71            paths,
72            functions: BTreeSet::new(),
73        }
74    }
75
76    pub(crate) fn files(&self) -> &[SymbolFile<'a>] {
77        &self.files
78    }
79
80    /// Declares a function of file `index`, returning its module-qualified key.
81    pub(crate) fn declare_function(&mut self, index: usize, name: &str) -> Vec<String> {
82        let key = self.function_key(index, name);
83        self.functions.insert(key.clone());
84        key
85    }
86
87    pub(crate) fn resolve(&self, index: usize, reference: &SymbolRef) -> Option<SymbolKey> {
88        match reference {
89            SymbolRef::Local(name) => Some(SymbolKey::Local {
90                file: index,
91                name: name.clone(),
92            }),
93            SymbolRef::Function(name) => Some(SymbolKey::Function(self.function_key(index, name))),
94            SymbolRef::Call(path) => self.resolve_call(index, path).map(SymbolKey::Function),
95            SymbolRef::Import { module, name } => self.resolve_import(index, module, name),
96            SymbolRef::Fixture(name) => self.resolve_fixture(index, name),
97            SymbolRef::Parameter { .. } => None,
98        }
99    }
100
101    pub(crate) fn language(&self, index: usize) -> Option<SourceLanguage> {
102        self.files[index]
103            .observations
104            .first()
105            .map(|observation| observation.language)
106    }
107
108    /// Qualifies a function defined in file `index` with its module path.
109    ///
110    /// Names starting with `@` identify repository-wide functions.
111    pub(crate) fn function_key(&self, index: usize, name: &str) -> Vec<String> {
112        if name.starts_with('@') {
113            return vec![name.to_owned()];
114        }
115        let mut segments = path_segments(self.files[index].path);
116        match self.language(index) {
117            Some(SourceLanguage::Go) => {
118                segments.pop();
119            }
120            Some(SourceLanguage::Rust) => {
121                if let Some(source_root) = segments.iter().rposition(|segment| segment == "src") {
122                    segments.drain(..=source_root);
123                }
124                if segments
125                    .last()
126                    .is_some_and(|stem| matches!(stem.as_str(), "main" | "lib" | "mod"))
127                {
128                    segments.pop();
129                }
130            }
131            _ => {
132                if segments
133                    .last()
134                    .is_some_and(|stem| matches!(stem.as_str(), "index" | "__init__"))
135                {
136                    segments.pop();
137                }
138            }
139        }
140        segments.push(name.to_owned());
141        segments
142    }
143
144    fn resolve_call(&self, index: usize, path: &str) -> Option<Vec<String>> {
145        let segments = path
146            .split("::")
147            .flat_map(|segment| segment.split('.'))
148            .filter(|segment| {
149                !segment.is_empty() && !matches!(*segment, "crate" | "self" | "super" | "this")
150            })
151            .map(str::to_owned)
152            .collect::<Vec<_>>();
153        if segments.len() == 1 {
154            let local = self.function_key(index, &segments[0]);
155            if self.functions.contains(&local) {
156                return Some(local);
157            }
158        }
159        let last = segments.last()?;
160        let suffix_matches = self
161            .functions
162            .iter()
163            .filter(|candidate| candidate.ends_with(&segments))
164            .collect::<Vec<_>>();
165        if !suffix_matches.is_empty() {
166            return unique(suffix_matches.into_iter()).cloned();
167        }
168        // Import aliases, such as Go `orders "example.com/internal/http"`, rename the qualifier.
169        unique(
170            self.functions
171                .iter()
172                .filter(|candidate| candidate.last() == Some(last)),
173        )
174        .cloned()
175    }
176
177    fn resolve_import(&self, index: usize, module: &str, name: &str) -> Option<SymbolKey> {
178        let file = |target: usize, name: &str| SymbolKey::Local {
179            file: target,
180            name: name.to_owned(),
181        };
182        if self.language(index) == Some(SourceLanguage::Python) {
183            let separator = if module.ends_with('.') { "" } else { "." };
184            if let Some((head, tail)) = name.split_once('.')
185                && let Some(target) =
186                    self.python_module(index, &format!("{module}{separator}{head}"))
187            {
188                return Some(file(target, tail));
189            }
190            return self
191                .python_module(index, module)
192                .map(|target| file(target, name));
193        }
194        self.script_module(index, module)
195            .map(|target| file(target, name))
196    }
197
198    /// A fixture declared in the same file, or else in the nearest enclosing `conftest.py`.
199    fn resolve_fixture(&self, index: usize, name: &str) -> Option<SymbolKey> {
200        let declares = |file: usize| {
201            self.files[file].observations.iter().any(|observation| {
202                observation.symbol_name.as_deref() == Some(name)
203                    && observation.role != crate::SourceRole::Test
204            })
205        };
206        if declares(index) {
207            return Some(SymbolKey::Local {
208                file: index,
209                name: name.to_owned(),
210            });
211        }
212        let mut directory = path_components(self.files[index].path);
213        while directory.pop().is_some() {
214            let candidate = directory
215                .iter()
216                .copied()
217                .chain(["conftest.py"])
218                .collect::<Vec<_>>()
219                .join("/");
220            if let Some(&file) = self.paths.get(candidate.as_str())
221                && declares(file)
222            {
223                return Some(SymbolKey::Local {
224                    file,
225                    name: name.to_owned(),
226                });
227            }
228        }
229        None
230    }
231
232    fn script_module(&self, index: usize, module: &str) -> Option<usize> {
233        if !module.starts_with('.') {
234            return None;
235        }
236        let mut base = path_components(self.files[index].path);
237        base.pop();
238        let joined = join_components(base, module.split('/'))?.join("/");
239        let stem = SCRIPT_EXTENSIONS
240            .iter()
241            .find_map(|extension| joined.strip_suffix(&format!(".{extension}")))
242            .unwrap_or(&joined);
243        std::iter::once(joined.clone())
244            .chain(
245                SCRIPT_EXTENSIONS
246                    .iter()
247                    .map(|extension| format!("{stem}.{extension}")),
248            )
249            .chain(
250                SCRIPT_EXTENSIONS
251                    .iter()
252                    .map(|extension| format!("{joined}/index.{extension}")),
253            )
254            .find_map(|candidate| self.paths.get(candidate.as_str()).copied())
255    }
256
257    fn python_module(&self, index: usize, module: &str) -> Option<usize> {
258        let dots = module
259            .chars()
260            .take_while(|character| *character == '.')
261            .count();
262        let rest = module[dots..]
263            .split('.')
264            .filter(|segment| !segment.is_empty());
265        let target = if dots == 0 {
266            rest.map(str::to_owned).collect::<Vec<_>>()
267        } else {
268            let mut base = path_components(self.files[index].path);
269            base.pop();
270            for _ in 1..dots {
271                base.pop()?;
272            }
273            base.into_iter()
274                .chain(rest)
275                .map(str::to_owned)
276                .collect::<Vec<_>>()
277        };
278        if target.is_empty() {
279            return None;
280        }
281        unique(self.paths.iter().filter_map(|(path, candidate)| {
282            let mut segments = path_segments(path);
283            if segments.last().is_some_and(|stem| stem == "__init__") {
284                segments.pop();
285            }
286            let is_python = Path::new(path)
287                .extension()
288                .is_some_and(|extension| extension.eq_ignore_ascii_case("py"));
289            (is_python && segments.ends_with(&target)).then_some(*candidate)
290        }))
291    }
292}
293
294pub(crate) fn unique<T: Clone>(mut candidates: impl Iterator<Item = T>) -> Option<T> {
295    let first = candidates.next()?;
296    candidates.next().is_none().then_some(first)
297}
298
299/// Path components with the file extension removed from the last one.
300fn path_segments(path: &str) -> Vec<String> {
301    let mut segments = path_components(path)
302        .into_iter()
303        .map(str::to_owned)
304        .collect::<Vec<_>>();
305    if let Some(last) = segments.last_mut()
306        && let Some((stem, _)) = last.rsplit_once('.')
307    {
308        *last = stem.to_owned();
309    }
310    segments
311}
312
313fn path_components(path: &str) -> Vec<&str> {
314    path.split('/')
315        .filter(|component| !component.is_empty() && *component != ".")
316        .collect()
317}
318
319fn join_components<'p>(
320    mut base: Vec<&'p str>,
321    relative: impl Iterator<Item = &'p str>,
322) -> Option<Vec<&'p str>> {
323    for component in relative {
324        match component {
325            "" | "." => {}
326            ".." => {
327                base.pop()?;
328            }
329            component => base.push(component),
330        }
331    }
332    Some(base)
333}