Skip to main content

vvv_engine/protocol/
answer.rs

1//! What a question about the tree comes back as: plain data over the facts
2//! the model holds, for the CLI to print, the JSON to carry, an agent to read.
3
4use vvv_core::RelPath;
5
6use serde::{Deserialize, Serialize};
7
8use crate::{Match, Occurrence, Reach, Skipped};
9use vvv_core::{Address, Highlight, ImportRef, Position, Symbol};
10
11/// `outline <path>`: what a file declares, in order.
12#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
13pub struct Outline {
14    pub path: RelPath,
15    /// The file's own module address, when the language has one.
16    #[serde(default, skip_serializing_if = "Option::is_none")]
17    pub module: Option<Address>,
18    pub items: Vec<OutlineItem>,
19}
20
21#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
22pub struct OutlineItem {
23    #[serde(flatten)]
24    pub symbol: Symbol,
25    /// Where the extent starts and ends, as lines and columns.
26    pub start: Position,
27    pub end: Position,
28    /// The module address the declaration is reached by, when a path can
29    /// reach it in this language.
30    #[serde(default, skip_serializing_if = "Option::is_none")]
31    pub address: Option<Address>,
32    /// Who may name it, from its modifier and its module.
33    #[serde(default, skip_serializing_if = "Option::is_none")]
34    pub reach: Option<Reach>,
35}
36
37/// `references <name>`: the declarations called `name` and every token that
38/// spells it, each judged against the declaration meant.
39#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
40pub struct References {
41    pub name: String,
42    pub declarations: Vec<Match>,
43    pub occurrences: Vec<Occurrence>,
44}
45
46/// `where <name>`: where `name` is declared and how to reach each site.
47#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
48pub struct Locations {
49    pub name: String,
50    pub sites: Vec<Site>,
51}
52
53#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
54pub struct Site {
55    pub declaration: Match,
56    #[serde(default, skip_serializing_if = "Option::is_none")]
57    pub address: Option<Address>,
58    /// The import statement that brings it into the file asked from, spelled
59    /// as that language writes it.
60    #[serde(default, skip_serializing_if = "Option::is_none")]
61    pub import: Option<String>,
62}
63
64/// `deps <path>`: what a file imports and who imports it.
65#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
66pub struct Deps {
67    pub path: RelPath,
68    /// The file's own module address, when the language has one.
69    #[serde(default, skip_serializing_if = "Option::is_none")]
70    pub module: Option<Address>,
71    pub imports: Vec<Dep>,
72    pub importers: Vec<Importer>,
73    #[serde(default, skip_serializing_if = "Vec::is_empty")]
74    pub skipped: Vec<Skipped>,
75}
76
77/// One import statement in the file and, when the layout can follow it,
78/// where it leads.
79#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
80pub struct Dep {
81    #[serde(flatten)]
82    pub import: ImportRef,
83    /// Where the import starts, as a line and column.
84    pub start: Position,
85    /// What the path spells, as the layout places it.
86    #[serde(default, skip_serializing_if = "Option::is_none")]
87    pub address: Option<Address>,
88    /// The declaration the address reaches through re-exports, when that is
89    /// somewhere else: `vvv_core::text::span::Span` for `use vvv_core::Span`.
90    #[serde(default, skip_serializing_if = "Option::is_none")]
91    pub origin: Option<Address>,
92    /// The file declaring what the import reaches — the origin's when known.
93    #[serde(default, skip_serializing_if = "Option::is_none")]
94    pub file: Option<RelPath>,
95}
96
97/// A file that imports from the one asked about.
98#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
99pub struct Importer {
100    pub path: RelPath,
101    #[serde(flatten)]
102    pub import: ImportRef,
103    pub start: Position,
104}
105
106/// `explain <path>:<line>:<column>`: what is at a position.
107#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
108pub struct Explanation {
109    pub path: RelPath,
110    pub position: Position,
111    /// The innermost declaration whose extent contains the position.
112    #[serde(default, skip_serializing_if = "Option::is_none")]
113    pub symbol: Option<Symbol>,
114    /// Where that declaration's name starts, and the source line holding it.
115    #[serde(default, skip_serializing_if = "Option::is_none")]
116    pub declared: Option<Position>,
117    #[serde(default, skip_serializing_if = "Option::is_none")]
118    pub line: Option<String>,
119    /// The file's module address, and the declaration's when a path reaches it.
120    #[serde(default, skip_serializing_if = "Option::is_none")]
121    pub module: Option<Address>,
122    #[serde(default, skip_serializing_if = "Option::is_none")]
123    pub address: Option<Address>,
124    #[serde(default, skip_serializing_if = "Option::is_none")]
125    pub reach: Option<Reach>,
126    /// Every other address a re-export chain offers the declaration at.
127    #[serde(default, skip_serializing_if = "Vec::is_empty")]
128    pub via: Vec<Address>,
129    /// The import statement at the position, when it is inside one: what
130    /// it spells and where that really comes from.
131    #[serde(default, skip_serializing_if = "Option::is_none")]
132    pub import: Option<Dep>,
133    /// Files whose imports resolve to the declaration, to any address a
134    /// re-export offers it at, or to its module when the declaration itself
135    /// is not addressable.
136    pub importers: Vec<RelPath>,
137}
138
139/// `Engine::file`: one file as it is, with its syntax colouring.
140#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
141pub struct File {
142    pub path: RelPath,
143    pub text: String,
144    #[serde(default, skip_serializing_if = "Vec::is_empty")]
145    pub highlights: Vec<Highlight>,
146}
147
148/// A declaration as the graph holds it: placed, with its reach.
149#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
150pub struct Placed {
151    pub path: RelPath,
152    #[serde(flatten)]
153    pub symbol: Symbol,
154    /// Where the declaration's name starts, as a line and column.
155    pub start: Position,
156    pub address: Address,
157    pub reach: Reach,
158}
159
160/// `surface [package]`: what a package offers to everyone, and who takes it.
161#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
162pub struct Surface {
163    /// The package asked about; every package when absent.
164    #[serde(default, skip_serializing_if = "Option::is_none")]
165    pub package: Option<vvv_core::PackageId>,
166    pub items: Vec<Exposed>,
167}
168
169#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
170pub struct Exposed {
171    #[serde(flatten)]
172    pub declaration: Placed,
173    /// The other addresses it is offered at, through re-exports.
174    #[serde(default, skip_serializing_if = "Vec::is_empty")]
175    pub via: Vec<Address>,
176    /// Files in the workspace importing it, at any of its addresses.
177    pub importers: usize,
178}
179
180/// `impact <name>`: every module that would feel a change to a declaration —
181/// those importing it, then those importing them, outward.
182#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
183pub struct Impact {
184    pub name: String,
185    pub address: Address,
186    /// Nearest first: depth 1 imports the declaration itself.
187    pub consumers: Vec<Consumer>,
188}
189
190#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
191pub struct Consumer {
192    pub module: Address,
193    pub path: RelPath,
194    pub depth: u32,
195    /// The module it reaches the declaration through; the declaration's
196    /// own module at depth 1.
197    pub through: Address,
198}
199
200/// `dead [--lang]`: declarations nothing in the workspace refers to, with
201/// how many tokens might.
202#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
203pub struct Dead {
204    pub items: Vec<Unreferenced>,
205}
206
207#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
208pub struct Unreferenced {
209    #[serde(flatten)]
210    pub declaration: Placed,
211    /// Tokens spelling the name that vvv could not judge: any of them might
212    /// be a use.
213    pub unsure: usize,
214}
215
216/// `imports [path]`: import statements worth a look — unused, unresolved,
217/// or the same target twice.
218#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
219pub struct ImportsReport {
220    /// The file asked about; every file when absent.
221    #[serde(default, skip_serializing_if = "Option::is_none")]
222    pub path: Option<RelPath>,
223    /// Declared imports whose bound name the file never spells again.
224    pub unused: Vec<ImportSite>,
225    /// Declared imports the layout could not place.
226    pub unresolved: Vec<ImportSite>,
227    /// Declared imports naming an address another statement in the file
228    /// already brings in.
229    pub redundant: Vec<ImportSite>,
230    /// Files whose language has a layout but which it cannot place — a
231    /// crate's integration tests, say — so their imports were not judged.
232    pub unplaced: Vec<RelPath>,
233}
234
235#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
236pub struct ImportSite {
237    pub path: RelPath,
238    #[serde(flatten)]
239    pub import: ImportRef,
240    pub start: Position,
241    #[serde(default, skip_serializing_if = "Option::is_none")]
242    pub address: Option<Address>,
243}