rust-meth-lib 0.4.0

Core library for rust-meth: discover methods on Rust types via rust-analyzer.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
//! Orchestrates `rust-analyzer` LSP sessions.
//!
//! Each public function here spins up an ephemeral `rust-analyzer` subprocess,
//! drives it through the handshake, asks one question (completion or
//! definition), and tears it back down. The two query functions are
//! intentionally similar in shape, see the module-level note below.

use std::collections::BTreeSet;
use std::process::{Command, Stdio};
use std::time;

use serde_json::Value;

use crate::error::Result;
use crate::probe::Probe;
use crate::{LspTransport, error};

use super::parse::{self, Definition, Method};

/// Queries `rust-analyzer` for all available methods on a given type type expression.
///
/// This spins up an ephemeral LSP session, generates a mock workspace via a [`Probe`],
/// triggers a completion request at the appropriate line/column location, and parses the results.
///
/// # Environment Variables
///
/// * `RUST_METH_DEBUG` - If set, logs raw LSP method lifecycle events to standard error.
///
/// # Errors
///
/// Returns an error if:
/// * Spawning the `rust-analyzer` subprocess fails.
/// * The LSP server communication channels break.
/// * The server returns an unexpectedly structured or malformed JSON payload.
pub fn query_methods(
    type_name: &str,
    ra_path: &std::path::Path,
    deps: Option<&str>,
) -> Result<Vec<Method>> {
    query_methods_inner(type_name, ra_path, deps)
}

/// Queries `rust-analyzer` for methods on multiple types in parallel.
///
/// Spawns one thread per query using [`std::thread::scope`]. Each query runs
/// an independent `rust-analyzer` subprocess, so failures are per-type and do
/// not abort the batch. Results are returned in the same order as `queries`.
///
/// # Example
///
/// ```no_run
/// use rust_meth_lib::analyzer::{find_rust_analyzer, query_methods_batch};
///
/// let ra_path = find_rust_analyzer().unwrap();
/// let queries = &[
///     ("Vec<u8>", None),
///     ("String", None),
///     ("HashMap<String, u32>", None),
/// ];
/// for (type_name, result) in query_methods_batch(queries, &ra_path) {
///     match result {
///         Ok(methods) => println!("{type_name}: {} methods", methods.len()),
///         Err(e) => eprintln!("{type_name}: {e}"),
///     }
/// }
/// ```
/// # Environment Variables
///
/// * `RUST_METH_DEBUG` - If set, logs raw LSP method lifecycle events to standard error.
///
/// ## Panics
///
/// Panics if any of the spawned background threads for processing queries panics
/// or fails to join (e.g., due to an unhandled thread fault during the LSP session).
#[allow(clippy::needless_collect)]
#[must_use]
pub fn query_methods_batch<'a>(
    queries: &[(&'a str, Option<&'a str>)],
    ra_path: &std::path::Path,
) -> Vec<(&'a str, Result<Vec<Method>>)> {
    std::thread::scope(|s| {
        let handles: Vec<_> = queries
            .iter()
            .map(|&(type_name, deps)| {
                s.spawn(move || (type_name, query_methods_inner(type_name, ra_path, deps)))
            })
            .collect(); // <-- all threads spawned before any are joined

        handles
            .into_iter()
            .map(|h| h.join().expect("query thread should not panic"))
            .collect()
    })
}

/// Inner implementation shared by [`query_methods`] and [`query_methods_batch`].
fn query_methods_inner(
    type_name: &str,
    ra_path: &std::path::Path,
    deps: Option<&str>,
) -> Result<Vec<Method>> {
    use crate::probe::cache::ra_version;
    use crate::results_cache::{load_results, save_results};

    // Infer effective deps the same way Probe does, so the cache key matches.
    let effective_deps = deps.map(str::to_owned).or_else(|| {
        if type_name.contains("::")
            && type_name
                .split("::")
                .next()
                .and_then(|s| s.chars().next())
                .is_some_and(|c| c.is_ascii_lowercase())
        {
            let crate_name = type_name.split("::").next().unwrap_or("");
            Some(format!(r#"{crate_name} = "*""#))
        } else {
            None
        }
    });

    let ra_version = ra_version(ra_path);
    if let Some(methods) = load_results(type_name, effective_deps.as_deref(), &ra_version) {
        return Ok(methods);
    }

    let probe = Probe::new_with_deps_cached(type_name, deps, ra_path)?;
    let mut child = Command::new(ra_path)
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::null())
        .spawn()?;
    let mut lsp = LspTransport::new(&mut child)?;
    let pid = std::process::id();

    lsp.send(&LspTransport::initialize(pid, &probe.root_uri()))?;
    lsp.recv_until(20, |msg| {
        (msg["id"] == 1 && msg["result"].is_object()).then_some(())
    })?;

    lsp.send(&LspTransport::initialized())?;

    lsp.send(&LspTransport::did_open(&probe.src_uri(), &probe.source()?))?;

    let diag_msg = wait_for_indexing(&mut lsp, &probe.src_uri());
    check_diagnostics_for_type_error(type_name, diag_msg.as_ref())?;

    // RA may return isIncomplete+empty if it isn't fully ready yet.
    let completion_response = retry_lsp_request(
        &mut lsp,
        20,
        type_name,
        |req_id| LspTransport::completion(req_id, &probe.src_uri(), probe.dot_line, probe.dot_col),
        |msg| {
            let items = msg["result"]["items"]
                .as_array()
                .cloned()
                .unwrap_or_default();
            if std::env::var("RUST_METH_DEBUG").is_ok() {
                for item in &items {
                    eprintln!(
                        "[debug] completion label={:?} kind={:?}",
                        item["label"], item["kind"]
                    );
                }
            }
            !items.is_empty() && !is_blanket_fallback(&items)
        },
    )?;

    lsp.send(&LspTransport::shutdown(13))?;
    let _ = lsp.recv_until(10, |msg| (msg["id"] == 13).then_some(()));
    lsp.send(&LspTransport::exit())?;
    let _ = child.wait();

    let methods = parse::parse_methods(&completion_response)?;
    save_results(type_name, effective_deps.as_deref(), &ra_version, &methods);
    Ok(methods)
}

/// Use diagnostics to find the error type
fn check_diagnostics_for_type_error(type_name: &str, diag_msg: Option<&Value>) -> Result<()> {
    let Some(msg) = diag_msg else { return Ok(()) };

    let diagnostics = msg["params"]["diagnostics"]
        .as_array()
        .map_or(&[][..], Vec::as_slice);

    for diag in diagnostics {
        // severity 1 = Error in LSP
        if diag["severity"].as_u64() != Some(1) {
            continue;
        }

        // Feature-gated items resolve structurally but were compiled out,
        // check this before the generic "not found" check, since the two
        // are easy to conflate (both stem from E04xx "cannot find" codes).
        if let Some(rendered) = diag["data"]["rendered"].as_str()
            && (rendered.contains("configured out") || rendered.contains("gated behind"))
        {
            return Err(crate::error::RustMethError::FeatureGated {
                type_name: type_name.to_string(),
                message: rendered.to_string(),
            });
        }

        let message = diag["message"].as_str().unwrap_or("");
        // RA reports unknown types as "cannot find type `X` in this scope"
        if message.contains("cannot find type") || message.contains("not found in") {
            return Err(crate::error::RustMethError::TypeNotFound {
                type_name: type_name.to_string(),
                message: message.to_string(),
            });
        }
    }
    Ok(())
}

/// Queries `rust-analyzer` for the precise upstream source file declaration layout of a specific method.
///
/// Under the hood, this sets up a mock environment containing an isolated invocation of your method,
/// queries `textDocument/definition`, and intercepts the target file location coordinates.
///
/// # Errors
///
/// Returns an error if the underlying LSP runtime breaks, or if `rust-analyzer` encounters structural errors.
/// If a method exists but has no discoverable source code location definitions, it evaluates cleanly into `Ok(None)`.
pub fn query_definition(
    type_name: &str,
    method_name: &str,
    ra_path: &std::path::Path,
    deps: Option<&str>,
) -> Result<Option<Definition>> {
    let probe = Probe::for_definition_with_deps_cached(type_name, method_name, deps, ra_path)?;
    let mut child = Command::new(ra_path)
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::null())
        .spawn()?;
    let mut lsp = LspTransport::new(&mut child)?;
    let pid = std::process::id();

    // Send didOpen immediately after initialized, don't wait
    lsp.send(&LspTransport::initialize(pid, &probe.root_uri()))?;
    lsp.recv_until(5000, |msg| {
        (msg["id"] == 1 && msg["result"].is_object()).then_some(())
    })?;

    // Send both notifications back-to-back (no wait needed)
    lsp.send(&LspTransport::initialized())?;
    lsp.send(&LspTransport::did_open(&probe.src_uri(), &probe.source()?))?;

    // Now wait for indexing
    wait_for_indexing(&mut lsp, &probe.src_uri());

    // Retry on "content modified" - RA rejects requests while it's still
    // processing the file. Same pattern as the completion retry loop.
    let response = retry_lsp_request(
        &mut lsp,
        60,
        type_name,
        |req_id| LspTransport::definition(req_id, &probe.src_uri(), probe.dot_line, probe.dot_col),
        |msg| {
            let is_error = msg["error"]["code"].as_i64().is_some();
            let is_null = msg["result"].is_null();
            !is_error && !is_null
        },
    )?;

    lsp.send(&LspTransport::shutdown(13))?;
    let _ = lsp.recv_until(10, |msg| (msg["id"] == 13).then_some(()));
    lsp.send(&LspTransport::exit())?;
    let _ = child.wait();

    Ok(parse::parse_definition(&response))
}

/// Wait until rust-analyzer is ready to serve completions.
///
/// RA doesn't always send $/progress. On fast/warm projects it skips straight
/// to publishing diagnostics. We treat any of these as "ready":
///   - $/progress with value.kind == "end"
///   - experimental/serverStatus with quiescent == true
///   - workspace/diagnostic/refresh
///   - textDocument/publishDiagnostics
fn wait_for_indexing(lsp: &mut LspTransport, probe_uri: &str) -> Option<Value> {
    let debug = std::env::var("RUST_METH_DEBUG").is_ok();
    // Accumulate the last publishDiagnostics message seen.
    // Wait untill RA signals it's truly done.
    let mut last_diag: Option<Value> = None;
    let mut done = false;

    let drain_start = time::Instant::now();
    let _ = lsp.recv_until(20, |msg| {
        // Timeout escape hatch
        if drain_start.elapsed() > time::Duration::from_mins(2) {
            return Some(());
        }
        let method = msg["method"].as_str().unwrap_or("");
        if debug {
            eprintln!("[debug] {method}");
        }
        match method {
            "$/progress" => {
                if msg["params"]["value"]["kind"] == "end" {
                    done = true;
                    Some(())
                } else {
                    None
                }
            }
            "experimental/serverStatus" => {
                if msg["params"]["quiescent"] == true {
                    done = true;
                    Some(())
                } else {
                    None
                }
            }

            "workspace/diagnostic/refresh" => {
                done = true;
                Some(())
            }
            "textDocument/publishDiagnostics" => {
                if debug {
                    eprintln!(
                        "[debug] diagnostics: {}",
                        serde_json::to_string_pretty(&msg["params"]).unwrap_or_default()
                    );
                }

                let is_probe_file = msg["params"]["uri"].as_str() == Some(probe_uri);
                let has_type_error = is_probe_file
                    && msg["params"]["diagnostics"]
                        .as_array()
                        .is_some_and(|diags| {
                            diags.iter().any(|d| {
                                d["severity"].as_u64() == Some(1)
                                    && d["message"].as_str().is_some_and(|m| {
                                        m.contains("cannot find type") || m.contains("not found in")
                                    })
                            })
                        });
                if has_type_error || (is_probe_file && last_diag.is_none()) {
                    last_diag = Some(msg.clone());
                }
                None
            }
            _ => None,
        }
    });
    let _ = done;

    last_diag
}

fn retry_lsp_request<F, G>(
    lsp: &mut LspTransport,
    max_attempts: u64,
    type_name: &str,
    mut make_request: F,
    mut is_success: G,
) -> Result<Value>
where
    F: FnMut(u64) -> Value,   // takes req_id, returns the request to send
    G: FnMut(&Value) -> bool, // returns true when response is good
{
    let start = time::Instant::now();
    for attempt in 1..=max_attempts {
        let req_id = attempt + 2;
        lsp.send(&make_request(req_id))?;
        let msg = lsp.recv_until(50, |msg| (msg["id"] == req_id).then(|| msg.clone()))?;
        if is_success(&msg) {
            return Ok(msg);
        }
        if attempt < max_attempts {
            std::thread::sleep(time::Duration::from_millis(500));
        }
    }
    Err(error::RustMethError::Timeout {
        type_name: type_name.to_string(),
        waited_secs: start.elapsed().as_secs(),
    })
}

/// The generic blanket-impl completions RA returns for any type it can't
/// fully resolve yet (still indexing) or can't resolve at all (unknown type).
/// If completion results are *exactly* this set, treat it as "not ready":
/// never treat it as a legitimate answer.
const BLANKET_FALLBACK_METHODS: &[&str] = &[
    "clamp",
    "clone",
    "clone_from",
    "clone_into",
    "cmp",
    "eq",
    "ge",
    "gt",
    "into",
    "le",
    "lt",
    "max",
    "min",
    "ne",
    "not",
    "partial_cmp",
    "to_owned",
    "to_string",
    "try_into",
];

fn is_blanket_fallback(items: &[Value]) -> bool {
    let names: BTreeSet<&str> = items
        .iter()
        .filter_map(|i| i["label"].as_str())
        .map(|label| label.split('(').next().unwrap_or(label).trim())
        .collect();
    let fallback: BTreeSet<&str> = BLANKET_FALLBACK_METHODS.iter().copied().collect();
    !names.is_empty() && names == fallback
}