Skip to main content

docattest_rust/session/
mod.rs

1//! The one project `open` creates, as the protocol sees it: what `open` says, and which
2//! of the session's methods is answered from syntax (`analysis`) and which by
3//! building and running programs (`running`).
4
5use crate::analysis::Analysis;
6use crate::analysis::surfaces::{Configured, workspace_start};
7use crate::project::{self, Project};
8use crate::protocol::{Answer, Attestation, Cases, Error, Example, Fact, decode};
9use crate::running::{Limits, Runner, Snapshots};
10use serde::Deserialize;
11use serde_json::{Value, json};
12use std::collections::HashMap;
13use std::path::{Path, PathBuf};
14use std::sync::Arc;
15
16/// The time limit of a program when `open` gives none.
17const DEFAULT_TIMEOUT_MS: f64 = 10_000.0;
18
19/// What `open` says.
20#[derive(Deserialize)]
21#[serde(rename_all = "camelCase")]
22struct Params {
23    root: String,
24    #[serde(default)]
25    files: Option<HashMap<String, String>>,
26    surfaces: Vec<Configured>,
27    #[serde(default)]
28    setup: Option<String>,
29    timeout_ms: f64,
30    workers: f64,
31    network: bool,
32    snapshots: Snapshots,
33    manifests: Value,
34    examples: Vec<Example>,
35}
36
37/// A project, for one docattest invocation.
38struct Session {
39    analysis: Arc<Analysis>,
40    runner: Arc<Runner>,
41    /// The directory a project in memory was written to, removed when the session closes.
42    written: Option<PathBuf>,
43}
44
45/// Creates the session of a process.
46pub fn open(params: Value) -> Result<Arc<dyn crate::protocol::Session>, Error> {
47    let told: Params = decode(params)?;
48    let (root, written) = match &told.files {
49        Some(files) => {
50            let dir = project::materialise(&told.root, files).map_err(|err| {
51                Error::Internal(format!("cannot write the project in memory to a directory: {err}"))
52            })?;
53            (dir.clone(), Some(dir))
54        }
55        None => (canonical(&told.root)?, None),
56    };
57    let in_memory = told.files.as_ref().map(|_| told.root.as_str());
58    let project = Project::read(&workspace_start(&root, &told.surfaces), in_memory);
59    let analysis = Arc::new(Analysis::new(root, project, told.setup, &told.surfaces));
60    let timeout_ms = if told.timeout_ms > 0.0 { told.timeout_ms } else { DEFAULT_TIMEOUT_MS };
61    let limits = Limits { timeout_ms, workers: told.workers as usize, network: told.network };
62    let runner = Arc::new(Runner::new(Arc::clone(&analysis), limits, told.snapshots, told.manifests));
63    // Building is most of the time a check takes, so it starts now: `compile` and `run`
64    // find the examples `open` named already built, or wait for them.
65    let early = Arc::clone(&runner);
66    std::thread::spawn(move || early.build_ahead(&told.examples));
67    Ok(Arc::new(Session { analysis, runner, written }))
68}
69
70/// The project's directory as the file system names it.
71fn canonical(root: &str) -> Result<PathBuf, Error> {
72    Path::new(root)
73        .canonicalize()
74        .map_err(|err| Error::Internal(format!("the project root {root} cannot be read: {err}")))
75}
76
77#[derive(Deserialize)]
78struct ExamplesParams {
79    examples: Vec<Example>,
80}
81
82#[derive(Deserialize)]
83struct RunParams {
84    examples: Vec<Example>,
85    cases: Vec<Cases>,
86}
87
88#[derive(Deserialize)]
89struct FactsParams {
90    facts: Vec<Fact>,
91}
92
93#[derive(Deserialize)]
94struct SymbolsParams {
95    attestations: Vec<Attestation>,
96}
97
98#[derive(Deserialize)]
99struct SurfaceParams {
100    surface: String,
101}
102
103#[derive(Deserialize)]
104struct FileParams {
105    file: String,
106}
107
108#[derive(Deserialize)]
109struct AffectedParams {
110    base: HashMap<String, Option<String>>,
111}
112
113#[derive(Deserialize)]
114struct InCodeParams {
115    names: Vec<String>,
116    files: Vec<String>,
117}
118
119impl crate::protocol::Session for Session {
120    fn call(&self, method: &str, params: Value) -> Option<Answer> {
121        let runner = &self.runner;
122        Some(match method {
123            "compile" => decode::<ExamplesParams>(params).map(|p| json!(runner.compile(&p.examples))),
124            "run" => decode::<RunParams>(params).map(|p| json!(runner.run(&p.examples, &p.cases))),
125            "evaluate" => decode::<FactsParams>(params).map(|p| json!(runner.evaluate(&p.facts))),
126            "observables" => decode::<SurfaceParams>(params).and_then(|p| runner.observables(&p.surface)),
127            _ => return self.read(method, params),
128        })
129    }
130
131    fn close(&self) {
132        // The examples `open` began building are let finish: cargo holds the files.
133        self.runner.wait_for_build();
134        if let Some(dir) = &self.written {
135            // What is left of a project in memory is in the system's temporary
136            // directory, and nothing reads it again.
137            let _ = std::fs::remove_dir_all(dir);
138        }
139    }
140}
141
142impl Session {
143    /// Answers a method that only reads the project's syntax; `None` for any other.
144    fn read(&self, method: &str, params: Value) -> Option<Answer> {
145        let analysis = &self.analysis;
146        Some(match method {
147            "symbols" => decode::<SymbolsParams>(params).map(|p| {
148                let by_id = p.attestations.iter().map(|a| (a.id.clone(), json!(analysis.symbols(a))));
149                Value::Object(by_id.collect())
150            }),
151            "exports" => decode::<SurfaceParams>(params).map(|p| json!(analysis.exports_of(&p.surface))),
152            "describeSurfaces" => Ok(analysis.describe_surfaces()),
153            "tests" => decode::<FileParams>(params).map(|p| analysis.list_tests(&p.file)),
154            "affected" => decode::<AffectedParams>(params).map(|p| json!(analysis.affected(&p.base))),
155            "inCode" => decode::<InCodeParams>(params).map(|p| json!(analysis.in_code(&p.names, &p.files))),
156            _ => return None,
157        })
158    }
159}