Skip to main content

vvv_engine/
answers.rs

1//! The read-only questions: `outline`, `where`, `deps`, `explain`, and a
2//! file with its highlights. Each reads the graph and answers with plain
3//! data; nothing is planned.
4
5use vvv_core::{Address, Query};
6
7use crate::command::{Command, Context};
8use crate::{
9    Deps, DepsQuery, EngineError, ExplainQuery, Explanation, File, FileQuery, Locations, Outline,
10    OutlineItem, OutlineQuery, ReferencesQuery, Search, Site, WhereQuery,
11};
12
13/// What a file declares, in order, with where a path reaches each item and
14/// who may name it.
15impl Command for OutlineQuery {
16    type Output = Outline;
17
18    fn run(self, cx: &mut Context<'_>) -> Result<Self::Output, EngineError> {
19        let path = cx.workspace.normalize(&self.path);
20        let graph = &mut *cx.graph;
21        let candidate = graph.file(&path)?;
22        let ns = graph.namespace(&candidate.language());
23        let module = ns.as_ref().and_then(|ns| ns.address(&path).ok());
24        let placed = ns.as_ref().zip(module.as_ref());
25        let source = candidate.file().source();
26        let items = candidate
27            .facts()?
28            .symbols
29            .iter()
30            .map(|symbol| OutlineItem {
31                symbol: symbol.clone(),
32                start: source.position(symbol.extent.start),
33                end: source.position(symbol.extent.end),
34                address: placed.and_then(|(ns, m)| ns.address_of(m, symbol)),
35                reach: placed.map(|(ns, m)| ns.reach(m, symbol)),
36            })
37            .collect();
38        Ok(Outline {
39            path: path.into(),
40            module,
41            items,
42        })
43    }
44}
45
46/// Where `name` is declared, and the import that reaches each site from
47/// `from`, spelled as that language writes it.
48impl Command for WhereQuery {
49    type Output = Locations;
50
51    fn run(self, cx: &mut Context<'_>) -> Result<Self::Output, EngineError> {
52        let name = self.name.as_str();
53        let graph = &mut *cx.graph;
54        let declarations = graph.declarations(&ReferencesQuery::new(name))?;
55        let from = self.from.as_deref().map(|f| cx.workspace.normalize(f));
56        let mut sites = Vec::new();
57        for declaration in declarations {
58            let placed = graph.namespace(&declaration.language).and_then(|ns| {
59                let module = ns.address(&declaration.path).ok()?;
60                let address = declaration
61                    .symbol
62                    .as_ref()
63                    .and_then(|s| ns.address_of(&module, s));
64                let import = address.as_ref().and_then(|address| {
65                    ns.surgery().ok()?.import_statement(
66                        ns.project(),
67                        from.as_deref()?,
68                        address,
69                        name,
70                    )
71                });
72                Some((address, import))
73            });
74            let (address, import) = placed.unwrap_or((None, None));
75            sites.push(Site {
76                declaration,
77                address,
78                import,
79            });
80        }
81        Ok(Locations {
82            name: name.to_owned(),
83            sites,
84        })
85    }
86}
87
88/// What a file imports and, across its language, who imports it — through
89/// re-exports both ways: an import is followed to the declaration it
90/// reaches, and a file importing one of this file's declarations under an
91/// address a `pub use` offers it at is an importer.
92impl Command for DepsQuery {
93    type Output = Deps;
94
95    fn run(self, cx: &mut Context<'_>) -> Result<Self::Output, EngineError> {
96        let path = cx.workspace.normalize(&self.path);
97        let graph = &mut *cx.graph;
98        let ns = graph.namespace_of(&path)?;
99        let imports = graph.imports_of(&path)?;
100        let own = ns.address(&path).ok();
101        let importers = match &own {
102            Some(own) => {
103                let mut offered: Vec<Address> = Vec::new();
104                for declared in &graph.file(&path)?.fragment(&ns)?.declarations {
105                    offered.extend(graph.aliases_of(
106                        &ns,
107                        &declared.address,
108                        &declared.symbol.name,
109                    )?);
110                }
111                graph.importers(&ns, &path, |a| a.starts_with(own) || offered.contains(a))?
112            }
113            None => Vec::new(),
114        };
115        Ok(Deps {
116            module: own,
117            path: path.into(),
118            imports,
119            importers,
120            skipped: Vec::new(),
121        })
122    }
123}
124
125/// What is at a position: the enclosing declaration, its address and reach,
126/// and the files whose imports lead to it.
127impl Command for ExplainQuery {
128    type Output = Explanation;
129
130    fn run(self, cx: &mut Context<'_>) -> Result<Self::Output, EngineError> {
131        let position = self.position;
132        let path = cx.workspace.normalize(&self.path);
133        let graph = &mut *cx.graph;
134        let candidate = graph.file(&path)?;
135        let source = candidate.file().source();
136        let offset = source
137            .offset(position)
138            .ok_or_else(|| EngineError::NoSuchPosition {
139                path: path.clone().into(),
140                position,
141            })?;
142        let symbol = candidate.facts()?.enclosing(offset).cloned();
143        let declared = symbol.as_ref().map(|s| source.position(s.name_span.start));
144        let line = declared.and_then(|d| source.line(d.line as usize).map(str::to_owned));
145        let mut explanation = Explanation {
146            path: path.clone().into(),
147            position,
148            symbol,
149            declared,
150            line,
151            module: None,
152            address: None,
153            reach: None,
154            via: Vec::new(),
155            import: None,
156            importers: Vec::new(),
157        };
158        let Some(ns) = graph.namespace(&candidate.language()) else {
159            return Ok(explanation);
160        };
161        let fragment = candidate.fragment(&ns)?;
162        // Inside an import statement: the entry under the position, or the
163        // statement's own path when the position is on none of its entries.
164        let statement = fragment.imports().find(|e| {
165            e.import.span.contains_offset(offset)
166                || e.import
167                    .group
168                    .as_ref()
169                    .is_some_and(|g| g.statement.contains_offset(offset))
170        });
171        if let Some(edge) = statement {
172            explanation.import = Some(graph.dep(&ns, source, edge)?);
173        }
174        let Ok(module) = ns.address(&path) else {
175            return Ok(explanation);
176        };
177        if let Some(symbol) = &explanation.symbol {
178            explanation.address = ns.address_of(&module, symbol);
179            explanation.reach = Some(ns.reach(&module, symbol));
180        }
181        // An import of the item (at any address a re-export offers it), of
182        // something under it, or of an enclosing module leads to it; a bare
183        // package root (`use vvv_core::{…}`'s prefix) leads everywhere and
184        // counts for nothing.
185        let target = explanation
186            .address
187            .clone()
188            .unwrap_or_else(|| module.clone());
189        let aliases = match (&explanation.address, &explanation.symbol) {
190            (Some(address), Some(symbol)) => graph.aliases_of(&ns, address, &symbol.name)?,
191            _ => vec![target.clone()],
192        };
193        explanation.importers = graph
194            .importers(&ns, &path, |a| {
195                aliases.contains(a)
196                    || a.starts_with(&target)
197                    || (!a.is_root() && target.starts_with(a))
198            })?
199            .into_iter()
200            .map(|importer| importer.path)
201            .collect();
202        explanation.via = aliases[1..].to_vec();
203        explanation.module = Some(module);
204        Ok(explanation)
205    }
206}
207
208/// One file as it is now, coloured by its language when one claims it.
209impl Command for FileQuery {
210    type Output = File;
211
212    fn run(self, cx: &mut Context<'_>) -> Result<Self::Output, EngineError> {
213        let path = self.path.as_path();
214        let file = cx.workspace.load(path)?;
215        let highlights = match cx.graph.language_of(path) {
216            Some(language) => {
217                language
218                    .highlights(file.text())
219                    .map_err(|source| EngineError::Search {
220                        path: path.into(),
221                        source,
222                    })?
223            }
224            None => Vec::new(),
225        };
226        Ok(File {
227            path: file.path().into(),
228            text: file.text().to_owned(),
229            highlights,
230        })
231    }
232}
233
234/// Structural or symbolic search across the workspace: only files spelling
235/// the query's literal words are parsed.
236impl Command for Query {
237    type Output = Search;
238
239    fn run(self, cx: &mut Context<'_>) -> Result<Self::Output, EngineError> {
240        self.check()?;
241        cx.graph.search(&self)
242    }
243}