Skip to main content

vvv_engine/capabilities/
declarations.rs

1//! Declaration locations and placement: outline and where.
2use crate::protocol::display::{Line, Role};
3use crate::protocol::vocabulary::Mark;
4use crate::report::{Block, Document};
5use crate::{EngineError, Match, Reach, ReferencesQuery, SymbolKind};
6use serde::{Deserialize, Serialize};
7use vvv_core::{Address, Position, RelPath, Symbol};
8
9/// `vvv outline <path>`: what a file declares.
10#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
11#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
12pub struct OutlineQuery {
13    pub path: RelPath,
14}
15
16/// `vvv where <name> [--from <file>]`: where a name is declared, and the
17/// import that reaches each site from `from`.
18#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
19#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
20pub struct WhereQuery {
21    pub name: String,
22    #[serde(default, skip_serializing_if = "Option::is_none")]
23    pub from: Option<RelPath>,
24}
25
26/// `outline <path>`: what a file declares, in order.
27#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
28#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
29pub struct Outline {
30    pub path: RelPath,
31    /// The file's own module address, when the language has one.
32    #[serde(default, skip_serializing_if = "Option::is_none")]
33    pub module: Option<Address>,
34    pub items: Vec<OutlineItem>,
35}
36
37#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
38#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
39pub struct OutlineItem {
40    #[serde(flatten)]
41    pub symbol: Symbol,
42    /// Where the extent starts and ends, as lines and columns.
43    pub start: Position,
44    pub end: Position,
45    /// The module address the declaration is reached by, when a path can
46    /// reach it in this language.
47    #[serde(default, skip_serializing_if = "Option::is_none")]
48    pub address: Option<Address>,
49    /// Who may name it, from its modifier and its module.
50    #[serde(default, skip_serializing_if = "Option::is_none")]
51    pub reach: Option<Reach>,
52}
53
54/// `where <name>`: where `name` is declared and how to reach each site.
55#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
56#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
57pub struct Locations {
58    pub name: String,
59    pub sites: Vec<Site>,
60}
61
62#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
63#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
64pub struct Site {
65    pub declaration: Match,
66    #[serde(default, skip_serializing_if = "Option::is_none")]
67    pub address: Option<Address>,
68    /// The import statement that brings it into the file asked from, spelled
69    /// as that language writes it.
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub import: Option<String>,
72}
73
74/// What a file declares, in order, with where a path reaches each item and
75/// who may name it.
76impl OutlineQuery {
77    /// Answer with the concrete result of this query.
78    pub fn execute(self, engine: &crate::Engine) -> Result<Outline, EngineError> {
79        let _operation = engine.operation();
80        let mut graph = engine.graph()?;
81        self.execute_in(&mut graph, engine.workspace())
82    }
83
84    pub(crate) fn execute_in(
85        self,
86        graph: &mut crate::graph::Graph,
87        workspace: &crate::Workspace,
88    ) -> Result<Outline, EngineError> {
89        let path = workspace.normalize(&self.path);
90        let candidate = graph.file(&path)?;
91        let ns = graph.namespace(&candidate.language());
92        let module = ns.as_ref().and_then(|ns| ns.address(&path).ok());
93        let placed = ns.as_ref().zip(module.as_ref());
94        let source = candidate.file().source();
95        let items = candidate
96            .facts()?
97            .symbols
98            .iter()
99            .map(|symbol| OutlineItem {
100                symbol: symbol.clone(),
101                start: source.position(symbol.extent.start),
102                end: source.position(symbol.extent.end),
103                address: placed.and_then(|(ns, m)| ns.address_of(m, symbol)),
104                reach: placed.map(|(ns, m)| ns.reach(m, symbol)),
105            })
106            .collect();
107        Ok(Outline {
108            path: path.into(),
109            module,
110            items,
111        })
112    }
113}
114
115/// Where `name` is declared, and the import that reaches each site from
116/// `from`, spelled as that language writes it.
117impl WhereQuery {
118    /// Answer with the concrete result of this query.
119    pub fn execute(self, engine: &crate::Engine) -> Result<Locations, EngineError> {
120        let _operation = engine.operation();
121        let mut graph = engine.graph()?;
122        self.execute_in(&mut graph, engine.workspace())
123    }
124
125    pub(crate) fn execute_in(
126        self,
127        graph: &mut crate::graph::Graph,
128        workspace: &crate::Workspace,
129    ) -> Result<Locations, EngineError> {
130        let name = self.name.as_str();
131        let declarations = graph.declarations(&ReferencesQuery::new(name))?;
132        let from = self.from.as_deref().map(|f| workspace.normalize(f));
133        let mut sites = Vec::new();
134        for declaration in declarations {
135            let placed = graph.namespace(&declaration.language).and_then(|ns| {
136                let module = ns.address(&declaration.path).ok()?;
137                let address = declaration
138                    .symbol
139                    .as_ref()
140                    .and_then(|s| ns.address_of(&module, s));
141                let import = address.as_ref().and_then(|address| {
142                    ns.surgery().ok()?.import_statement(
143                        ns.project(),
144                        from.as_deref()?,
145                        address,
146                        name,
147                    )
148                });
149                Some((address, import))
150            });
151            let (address, import) = placed.unwrap_or((None, None));
152            sites.push(Site {
153                declaration,
154                address,
155                import,
156            });
157        }
158        Ok(Locations {
159            name: name.to_owned(),
160            sites,
161        })
162    }
163}
164
165impl Document {
166    pub(crate) fn outline(result: &Outline) -> Self {
167        let mut report = Self::new();
168        report.file_header(&result.path);
169        if result.items.is_empty() {
170            report.block_note(Block::Summary(
171                Line::mark(Mark::Nothing).and(Role::Plain, " no declarations"),
172            ));
173            return report;
174        }
175        report.block_body(Block::Blank);
176        report.block_body(Block::Outline {
177            path: result.path.clone(),
178            items: result.items.clone(),
179        });
180        report.block_note(Block::Summary(Self::outline_summary(result)));
181        report
182    }
183
184    /// `● 14   pub 9  pub(crate) 1  · 4`: how many of each modifier.
185    fn outline_summary(result: &Outline) -> Line {
186        let mut counts: Vec<(String, usize)> = Vec::new();
187        for item in &result.items {
188            if item.symbol.kind == SymbolKind::Impl {
189                continue;
190            }
191            let key = item.symbol.modifier().unwrap_or("·").to_owned();
192            match counts.iter_mut().find(|(k, _)| *k == key) {
193                Some((_, n)) => *n += 1,
194                None => counts.push((key, 1)),
195            }
196        }
197        counts.sort_by_key(|(k, _)| k == "·");
198        let counts: Vec<Line> = counts
199            .iter()
200            .map(|(k, n)| {
201                Line::single(Role::Dim, k.clone())
202                    .and(Role::Plain, " ")
203                    .and(Role::Plain, n.to_string())
204            })
205            .collect();
206        Line::mark(Mark::Declaration)
207            .and(Role::Plain, " ")
208            .and(Role::Plain, result.items.len().to_string())
209            .and(Role::Plain, "   ")
210            .and_line(Self::join(counts, "  "))
211    }
212
213    pub(crate) fn locations(result: &Locations) -> Self {
214        let mut report = Self::new();
215        report.block_body(Block::Sites(result.sites.clone()));
216        report.block_note(Block::Summary(
217            Line::mark(Mark::Declaration)
218                .and(Role::Plain, " ")
219                .and(Role::Plain, result.sites.len().to_string()),
220        ));
221        report
222    }
223}