Skip to main content

vvv_engine/capabilities/
imports.rs

1//! Resolved imports, dependency origins, and import diagnostics.
2use crate::graph::{Node, Structure};
3use crate::protocol::display::{Line, Role};
4use crate::protocol::vocabulary::{Files, Mark};
5use crate::report::lines as l;
6use crate::report::{Block, Document};
7use crate::{Dep, EngineError, Importer, Reach, Skipped};
8use serde::{Deserialize, Serialize};
9use std::collections::BTreeMap;
10use vvv_core::{Address, ImportRef, Parsed, Position, RelPath, Symbol};
11
12/// `vvv deps <path>`: what a file imports and who imports it.
13#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
14#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
15pub struct DepsQuery {
16    pub path: RelPath,
17}
18
19/// `vvv explain <path>:<line>:<col>`: what is at a position.
20#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
21#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
22pub struct ExplainQuery {
23    pub path: RelPath,
24    pub position: Position,
25}
26
27/// `vvv imports [path]`: import statements worth a look.
28#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
29#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
30pub struct ImportsQuery {
31    #[serde(default, skip_serializing_if = "Option::is_none")]
32    pub path: Option<RelPath>,
33}
34
35/// `deps <path>`: what a file imports and who imports it.
36#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
37#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
38pub struct Deps {
39    pub path: RelPath,
40    /// The file's own module address, when the language has one.
41    #[serde(default, skip_serializing_if = "Option::is_none")]
42    pub module: Option<Address>,
43    pub imports: Vec<Dep>,
44    pub importers: Vec<Importer>,
45    #[serde(default, skip_serializing_if = "Vec::is_empty")]
46    pub skipped: Vec<Skipped>,
47}
48
49/// `explain <path>:<line>:<column>`: what is at a position.
50#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
51#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
52pub struct Explanation {
53    pub path: RelPath,
54    pub position: Position,
55    /// The innermost declaration whose extent contains the position.
56    #[serde(default, skip_serializing_if = "Option::is_none")]
57    pub symbol: Option<Symbol>,
58    /// Where that declaration's name starts, and the source line holding it.
59    #[serde(default, skip_serializing_if = "Option::is_none")]
60    pub declared: Option<Position>,
61    #[serde(default, skip_serializing_if = "Option::is_none")]
62    pub line: Option<String>,
63    /// The file's module address, and the declaration's when a path reaches it.
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub module: Option<Address>,
66    #[serde(default, skip_serializing_if = "Option::is_none")]
67    pub address: Option<Address>,
68    #[serde(default, skip_serializing_if = "Option::is_none")]
69    pub reach: Option<Reach>,
70    /// Every other address a re-export chain offers the declaration at.
71    #[serde(default, skip_serializing_if = "Vec::is_empty")]
72    pub via: Vec<Address>,
73    /// The import statement at the position, when it is inside one: what
74    /// it spells and where that really comes from.
75    #[serde(default, skip_serializing_if = "Option::is_none")]
76    pub import: Option<Dep>,
77    /// Files whose imports resolve to the declaration, to any address a
78    /// re-export offers it at, or to its module when the declaration itself
79    /// is not addressable.
80    pub importers: Vec<RelPath>,
81}
82
83/// `imports [path]`: import statements worth a look — unused, unresolved,
84/// or the same target twice.
85#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
86#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
87pub struct ImportsReport {
88    /// The file asked about; every file when absent.
89    #[serde(default, skip_serializing_if = "Option::is_none")]
90    pub path: Option<RelPath>,
91    /// Declared imports whose bound name the file never spells again.
92    pub unused: Vec<ImportSite>,
93    /// Declared imports the layout could not place.
94    pub unresolved: Vec<ImportSite>,
95    /// Declared imports naming an address another statement in the file
96    /// already brings in.
97    pub redundant: Vec<ImportSite>,
98    /// Files whose language has a layout but which it cannot place — a
99    /// crate's integration tests, say — so their imports were not judged.
100    pub unplaced: Vec<RelPath>,
101}
102
103#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
104#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
105pub struct ImportSite {
106    pub path: RelPath,
107    #[serde(flatten)]
108    pub import: ImportRef,
109    pub start: Position,
110    #[serde(default, skip_serializing_if = "Option::is_none")]
111    pub address: Option<Address>,
112}
113
114/// What a file imports and, across its language, who imports it — through
115/// re-exports both ways: an import is followed to the declaration it
116/// reaches, and a file importing one of this file's declarations under an
117/// address a `pub use` offers it at is an importer.
118impl DepsQuery {
119    /// Answer with the concrete result of this query.
120    pub fn execute(self, engine: &crate::Engine) -> Result<Deps, EngineError> {
121        let _operation = engine.operation();
122        let mut graph = engine.graph()?;
123        self.execute_in(&mut graph, engine.workspace())
124    }
125
126    pub(crate) fn execute_in(
127        self,
128        graph: &mut crate::graph::Graph,
129        workspace: &crate::Workspace,
130    ) -> Result<Deps, EngineError> {
131        let path = workspace.normalize(&self.path);
132        let ns = graph.namespace_of(&path)?;
133        let imports = graph.imports_of(&path)?;
134        let own = ns.address(&path).ok();
135        let importers = match &own {
136            Some(own) => {
137                let mut offered: Vec<Address> = Vec::new();
138                for declared in &graph.file(&path)?.fragment(&ns)?.declarations {
139                    offered.extend(graph.aliases_of(
140                        &ns,
141                        &declared.address,
142                        &declared.symbol.name,
143                    )?);
144                }
145                graph.importers(&ns, &path, |a| a.starts_with(own) || offered.contains(a))?
146            }
147            None => Vec::new(),
148        };
149        Ok(Deps {
150            module: own,
151            path: path.into(),
152            imports,
153            importers,
154            skipped: Vec::new(),
155        })
156    }
157}
158
159/// What is at a position: the enclosing declaration, its address and reach,
160/// and the files whose imports lead to it.
161impl ExplainQuery {
162    /// Answer with the concrete result of this query.
163    pub fn execute(self, engine: &crate::Engine) -> Result<Explanation, EngineError> {
164        let _operation = engine.operation();
165        let mut graph = engine.graph()?;
166        self.execute_in(&mut graph, engine.workspace())
167    }
168
169    pub(crate) fn execute_in(
170        self,
171        graph: &mut crate::graph::Graph,
172        workspace: &crate::Workspace,
173    ) -> Result<Explanation, EngineError> {
174        let position = self.position;
175        let path = workspace.normalize(&self.path);
176        let candidate = graph.file(&path)?;
177        let source = candidate.file().source();
178        let offset = source
179            .offset(position)
180            .ok_or_else(|| EngineError::NoSuchPosition {
181                path: path.clone().into(),
182                position,
183            })?;
184        let symbol = candidate.facts()?.enclosing(offset).cloned();
185        let declared = symbol.as_ref().map(|s| source.position(s.name_span.start));
186        let line = declared.and_then(|d| source.line(d.line as usize).map(str::to_owned));
187        let mut explanation = Explanation {
188            path: path.clone().into(),
189            position,
190            symbol,
191            declared,
192            line,
193            module: None,
194            address: None,
195            reach: None,
196            via: Vec::new(),
197            import: None,
198            importers: Vec::new(),
199        };
200        let Some(ns) = graph.namespace(&candidate.language()) else {
201            return Ok(explanation);
202        };
203        let fragment = candidate.fragment(&ns)?;
204        if let Some(edge) = fragment.import_at(offset) {
205            explanation.import = Some(graph.dep(&ns, &path, source, edge)?);
206        }
207        let Ok(module) = ns.address(&path) else {
208            return Ok(explanation);
209        };
210        if let Some(symbol) = &explanation.symbol {
211            explanation.address = ns.address_of(&module, symbol);
212            explanation.reach = Some(ns.reach(&module, symbol));
213        }
214        // An import of the item (at any address a re-export offers it), of
215        // something under it, or of an enclosing module leads to it; a bare
216        // package root (`use vvv_core::{…}`'s prefix) leads everywhere and
217        // counts for nothing.
218        let target = explanation
219            .address
220            .clone()
221            .unwrap_or_else(|| module.clone());
222        let aliases = match (&explanation.address, &explanation.symbol) {
223            (Some(address), Some(symbol)) => graph.aliases_of(&ns, address, &symbol.name)?,
224            _ => vec![target.clone()],
225        };
226        explanation.importers = graph
227            .importers(&ns, &path, |a| {
228                aliases.contains(a)
229                    || a.starts_with(&target)
230                    || (!a.is_root() && target.starts_with(a))
231            })?
232            .into_iter()
233            .map(|importer| importer.path)
234            .collect();
235        explanation.via = aliases[1..].to_vec();
236        explanation.module = Some(module);
237        Ok(explanation)
238    }
239}
240
241/// Import statements worth a look, per file or across the tree.
242impl ImportsQuery {
243    /// Answer with the concrete result of this query.
244    pub fn execute(self, engine: &crate::Engine) -> Result<ImportsReport, EngineError> {
245        let _operation = engine.operation();
246        let mut graph = engine.graph()?;
247        self.execute_in(&mut graph, engine.workspace())
248    }
249
250    pub(crate) fn execute_in(
251        self,
252        graph: &mut crate::graph::Graph,
253        workspace: &crate::Workspace,
254    ) -> Result<ImportsReport, EngineError> {
255        let path = self.path.as_deref().map(|p| workspace.normalize(p));
256        let mut report = ImportsReport {
257            path: path.clone().map(Into::into),
258            unused: Vec::new(),
259            unresolved: Vec::new(),
260            redundant: Vec::new(),
261            unplaced: Vec::new(),
262        };
263        let structure = Structure::of(graph)?;
264        for (ns, fragments) in structure.iter() {
265            for Node {
266                candidate,
267                fragment,
268            } in fragments
269            {
270                if path.as_deref().is_some_and(|p| p != candidate.path()) {
271                    continue;
272                }
273                if fragment.module.is_none() {
274                    report.unplaced.push(candidate.path().into());
275                    continue;
276                }
277                let facts = candidate.facts()?;
278                let source = candidate.file().source();
279                let parsed = Parsed {
280                    path: candidate.path(),
281                    source,
282                    facts,
283                };
284                let site = |edge: &crate::graph::Edge| ImportSite {
285                    path: candidate.path().into(),
286                    import: edge.import.clone(),
287                    start: source.position(edge.import.span.start),
288                    address: edge.address().cloned(),
289                };
290                // What each statement brings in: a glob of `X` and `X`
291                // itself are different things.
292                let mut brought: BTreeMap<(Address, bool), usize> = BTreeMap::new();
293                for edge in fragment.imports() {
294                    if parsed.is_group_prefix(&edge.import) {
295                        continue;
296                    }
297                    if edge.address().is_none() {
298                        report.unresolved.push(site(edge));
299                        continue;
300                    }
301                    if let Some(address) = edge.address() {
302                        let seen = brought
303                            .entry((address.clone(), edge.import.glob))
304                            .or_default();
305                        *seen += 1;
306                        if *seen > 1 {
307                            report.redundant.push(site(edge));
308                            continue;
309                        }
310                    }
311                    // A re-export is used by its takers; a language that hides
312                    // which names an import takes cannot be judged by tokens.
313                    if edge.import.reexport || ns.semantics().import_scopes_names {
314                        continue;
315                    }
316                    let Some(bound) = edge.import.binding() else {
317                        continue;
318                    };
319                    let statement = edge
320                        .import
321                        .group
322                        .as_ref()
323                        .map_or(edge.import.span, |g| g.statement);
324                    let used = facts
325                        .tokens_named(bound.as_str())
326                        .any(|(span, _)| !statement.contains(&span));
327                    if !used {
328                        report.unused.push(site(edge));
329                    }
330                }
331            }
332        }
333        Ok(report)
334    }
335}
336
337impl Document {
338    pub(crate) fn deps(result: &Deps) -> Self {
339        let mut report = Self::new();
340        report.file_header(&result.path);
341        report.block_body(Block::Blank);
342        let outgoing = l::DepGroups::statements(&result.imports);
343        report.body([Line::mark(Mark::Import)
344            .and(Role::Plain, " ")
345            .and(Role::Strong, outgoing.to_string())]);
346        if result.imports.is_empty() {
347            report.body([Line::single(Role::Plain, "  ").and_line(Line::mark(Mark::Nothing))]);
348        }
349        let own = result
350            .module
351            .as_ref()
352            .map(|m| m.package().as_str().to_owned());
353        report.block_body(Block::DepGroups {
354            path: result.path.clone(),
355            imports: result.imports.clone(),
356            own,
357        });
358        report.block_body(Block::Blank);
359        let incoming = l::ImporterRows::sites(&result.importers).len();
360        report.body([Line::mark(Mark::ImportedBy)
361            .and(Role::Plain, " ")
362            .and(Role::Strong, incoming.to_string())
363            .and(Role::Plain, "   ")
364            .and(
365                Role::Dim,
366                Files::among(result.importers.iter().map(|i| i.path.as_path())).to_string(),
367            )]);
368        if result.importers.is_empty() {
369            report.body([Line::single(Role::Plain, "  ").and_line(Line::mark(Mark::Nothing))]);
370        }
371        report.block_body(Block::Importers(result.importers.clone()));
372        report.block_note(Block::Summary(Self::deps_summary(outgoing, incoming)));
373        for skipped in &result.skipped {
374            report.warning(l::SkippedLine::new(skipped).line());
375        }
376        report
377    }
378
379    fn deps_summary(outgoing: usize, incoming: usize) -> Line {
380        Line::mark(Mark::Import)
381            .and(Role::Plain, format!(" {outgoing}  "))
382            .and_line(Line::mark(Mark::ImportedBy))
383            .and(Role::Plain, format!(" {incoming}"))
384    }
385
386    pub(crate) fn explain(result: &Explanation) -> Self {
387        let mut report = Self::new();
388        report.block_body(Block::Explanation(Box::new(result.clone())));
389        report
390    }
391
392    pub(crate) fn imports(result: &ImportsReport) -> Self {
393        let mut report = Self::new();
394        let scope = result.path.as_ref().map_or_else(
395            || "every file".to_owned(),
396            |path| path.display().to_string(),
397        );
398        report.title(format!("imports {scope}"));
399        let sections: [(Mark, &str, &[ImportSite]); 3] = [
400            (Mark::Nothing, "unresolved", &result.unresolved),
401            (Mark::ByHand, "unused", &result.unused),
402            (Mark::ByHand, "redundant", &result.redundant),
403        ];
404        let total: usize = sections.iter().map(|(_, _, s)| s.len()).sum();
405        if total == 0 {
406            report.block_note(Block::Summary(
407                Line::mark(Mark::Nothing).and(Role::Plain, " nothing to look at"),
408            ));
409            return report;
410        }
411        report.block_body(Block::Imports {
412            unresolved: result.unresolved.clone(),
413            unused: result.unused.clone(),
414            redundant: result.redundant.clone(),
415        });
416        report.block_note(Block::Summary(Self::imports_summary(
417            &sections,
418            result.unplaced.len(),
419        )));
420        report
421    }
422
423    fn imports_summary(sections: &[(Mark, &str, &[ImportSite])], unplaced: usize) -> Line {
424        let mut counts: Vec<Line> = sections
425            .iter()
426            .filter(|(_, _, s)| !s.is_empty())
427            .map(|(mark, word, s)| {
428                Line::mark(*mark)
429                    .and(Role::Plain, format!(" {word} "))
430                    .and(Role::Plain, s.len().to_string())
431            })
432            .collect();
433        if unplaced > 0 {
434            counts.push(
435                Line::mark(Mark::Nothing)
436                    .and(Role::Plain, " ")
437                    .and(Role::Dim, "not placed")
438                    .and(Role::Plain, " ")
439                    .and(Role::Dim, unplaced.to_string()),
440            );
441        }
442        Self::join(counts, "   ")
443    }
444}