Skip to main content

docattest_rust/protocol/
types.rs

1//! The protocol's data types. Optional fields are left out, never null.
2
3use serde::{Deserialize, Serialize};
4use std::collections::BTreeMap;
5
6/// The greeting: what is fixed for an adapter, whatever the project.
7#[derive(Clone, Debug, Serialize)]
8#[serde(rename_all = "camelCase")]
9pub struct Hello {
10    pub protocol: u64,
11    pub adapter: AdapterName,
12    pub block_languages: Vec<String>,
13    pub source_files: SourceFiles,
14    pub ignored_names: Vec<String>,
15    pub capabilities: Vec<Capability>,
16    pub info_words: Vec<String>,
17    pub vocabulary: Vocabulary,
18}
19
20/// An adapter's name and version.
21#[derive(Clone, Debug, Serialize)]
22pub struct AdapterName {
23    pub name: String,
24    pub version: String,
25}
26
27/// Globs for the project paths that are source files of the language.
28#[derive(Clone, Debug, Serialize)]
29pub struct SourceFiles {
30    pub include: Vec<String>,
31    pub exclude: Vec<String>,
32}
33
34/// A method beyond the required ones that an adapter answers.
35#[derive(Clone, Copy, Debug, Serialize)]
36#[serde(rename_all = "lowercase")]
37pub enum Capability {
38    Tests,
39    Observables,
40    Affected,
41}
42
43/// The language's words for what the core's sentences name.
44#[derive(Clone, Debug, Serialize)]
45#[serde(rename_all = "camelCase")]
46pub struct Vocabulary {
47    pub no_tests: String,
48}
49
50/// An ExampleAttestation: a fenced block, or an example in a doc comment.
51#[derive(Clone, Debug, Default, Serialize, Deserialize)]
52#[serde(default)]
53pub struct Example {
54    pub id: String,
55    pub page: String,
56    pub line: usize,
57    pub claim: String,
58    pub kind: String,
59    pub lang: String,
60    pub mode: String,
61    pub network: bool,
62    pub code: String,
63    pub weak: bool,
64    #[serde(skip_serializing_if = "Option::is_none")]
65    pub owner: Option<String>,
66    #[serde(skip_serializing_if = "Vec::is_empty")]
67    pub tags: Vec<String>,
68    #[serde(skip_serializing_if = "Option::is_none")]
69    pub error: Option<String>,
70}
71
72/// A FactAttestation, as far as the adapter reads it: an expression over a surface.
73#[derive(Clone, Debug, Default, Deserialize)]
74#[serde(default)]
75pub struct Fact {
76    pub id: String,
77    pub expression: String,
78    pub surface: String,
79}
80
81/// One row of a cases table.
82#[derive(Clone, Debug, Default, Deserialize)]
83#[serde(default)]
84pub struct CasesRow {
85    pub line: usize,
86    pub name: String,
87    pub values: BTreeMap<String, String>,
88}
89
90/// A CasesAttestation: a table run row by row by a runner of the setup module.
91#[derive(Clone, Debug, Default, Deserialize)]
92#[serde(default)]
93pub struct Cases {
94    pub page: String,
95    pub line: usize,
96    pub runner: String,
97    pub header: Vec<String>,
98    pub rows: Vec<CasesRow>,
99}
100
101/// Any of the four kinds of attestation, with the fields `symbols` reads of each.
102#[derive(Clone, Debug, Default, Deserialize)]
103#[serde(default)]
104pub struct Attestation {
105    pub id: String,
106    pub page: String,
107    pub line: usize,
108    pub kind: String,
109    pub code: String,
110    pub owner: Option<String>,
111    pub expression: String,
112    pub surface: String,
113    pub runner: String,
114    pub file: String,
115    pub title: String,
116    pub describes: Vec<String>,
117}
118
119/// A reason an example does not compile.
120#[derive(Clone, Debug, Serialize)]
121pub struct Diagnostic {
122    pub id: String,
123    pub message: String,
124    pub line: usize,
125}
126
127/// A value as the runtime observed it.
128#[derive(Clone, Debug, Default, Serialize, Deserialize)]
129pub struct Observation {
130    pub text: String,
131    #[serde(default, skip_serializing_if = "Option::is_none")]
132    pub items: Option<Vec<String>>,
133    pub description: String,
134    #[serde(default, skip_serializing_if = "Option::is_none")]
135    pub kind: Option<String>,
136}
137
138/// The outcome of evaluating one fact expression.
139#[derive(Clone, Debug, Serialize)]
140pub struct Evaluation {
141    pub ok: bool,
142    #[serde(skip_serializing_if = "Option::is_none")]
143    pub value: Option<Observation>,
144    #[serde(skip_serializing_if = "Option::is_none")]
145    pub message: Option<String>,
146}
147
148impl Evaluation {
149    /// The evaluation of a fact that has no value.
150    pub fn failed(message: impl Into<String>) -> Self {
151        Evaluation { ok: false, value: None, message: Some(message.into()) }
152    }
153
154    /// The evaluation of a fact that has a value.
155    pub fn of(value: Observation) -> Self {
156        Evaluation { ok: true, value: Some(value), message: None }
157    }
158}
159
160/// A surface symbol an attestation exercises.
161#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize)]
162pub struct SymbolRef {
163    pub name: String,
164    pub surface: String,
165}
166
167/// What kind of attestation a verdict is on.
168#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
169#[serde(rename_all = "lowercase")]
170pub enum Kind {
171    Example,
172    Fact,
173    Cases,
174    Snapshot,
175    Test,
176}
177
178/// How an attestation fared.
179#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
180#[serde(rename_all = "lowercase")]
181pub enum Status {
182    Pass,
183    Fail,
184    Error,
185    Skipped,
186}
187
188/// The verdict on one example, or on one row of a cases table.
189#[derive(Clone, Debug, Serialize)]
190pub struct Verdict {
191    pub page: String,
192    pub line: usize,
193    pub kind: Kind,
194    pub status: Status,
195    pub symbols: Vec<String>,
196    #[serde(skip_serializing_if = "Option::is_none")]
197    pub expected: Option<String>,
198    #[serde(skip_serializing_if = "Option::is_none")]
199    pub actual: Option<String>,
200    pub message: String,
201}
202
203/// A test, or something that may be cited by mistake for one, that a test file declares.
204#[derive(Clone, Debug, Serialize)]
205pub struct Declared {
206    pub title: String,
207    pub describes: Vec<String>,
208    pub line: usize,
209    /// What it is when it is not a test, with its article.
210    #[serde(skip_serializing_if = "Option::is_none")]
211    pub kind: Option<String>,
212}
213
214/// A value a surface offers, with the fact expression that reads it.
215#[derive(Clone, Debug, Serialize)]
216pub struct Observable {
217    pub surface: String,
218    pub expression: String,
219    pub path: Vec<String>,
220    pub value: Observation,
221}
222
223/// A file by path and text, as the questions about text receive it.
224#[derive(Clone, Debug, Default, Deserialize)]
225#[serde(default)]
226pub struct SourceText {
227    pub page: String,
228    pub text: String,
229}
230
231/// One doc comment as prose, with its first and last line.
232#[derive(Clone, Debug, PartialEq, Serialize)]
233pub struct DocProse {
234    pub text: String,
235    pub start: usize,
236    pub end: usize,
237}
238
239/// A fact expression with its names taken out.
240#[derive(Clone, Debug, Serialize)]
241pub struct ExpressionShape {
242    pub shape: String,
243    pub names: Vec<String>,
244}