1use 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#[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#[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#[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#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
37#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
38pub struct Deps {
39 pub path: RelPath,
40 #[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#[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 #[serde(default, skip_serializing_if = "Option::is_none")]
57 pub symbol: Option<Symbol>,
58 #[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 #[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 #[serde(default, skip_serializing_if = "Vec::is_empty")]
72 pub via: Vec<Address>,
73 #[serde(default, skip_serializing_if = "Option::is_none")]
76 pub import: Option<Dep>,
77 pub importers: Vec<RelPath>,
81}
82
83#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
86#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
87pub struct ImportsReport {
88 #[serde(default, skip_serializing_if = "Option::is_none")]
90 pub path: Option<RelPath>,
91 pub unused: Vec<ImportSite>,
93 pub unresolved: Vec<ImportSite>,
95 pub redundant: Vec<ImportSite>,
98 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
114impl DepsQuery {
119 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
159impl ExplainQuery {
162 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 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
241impl ImportsQuery {
243 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 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 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 §ions,
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}