M3.4: completion, hover and signature help from Phpactor

Engine (crates/engine/src/cmd/lsp_assist.rs), on M3.5's pending outcomes:
- lsp.completion {id, position, triggerCharacter?}: items with label,
  kind, detail, Markdown documentation, insertText, textEdit,
  additionalTextEdits, sortText; sorted, capped at 500 (cut lists are
  incomplete), snippets turned into plain text.
- lsp.hover {id, position}: Markdown contents and range.
- lsp.signatureHelp {id, position}: signatures with UTF-16 parameter spans.
- The request is queued after every didChange; the answer is converted
  in the reply callback, off the engine lock. Positions are checked
  against the buffer. Server strings and lists are capped.
- lutra-lsp-fake answers completion and signature help.

Editor (ui/src/components/editor/assist/):
- Completion source with Lutra's triggers (identifiers, $, ->, ?->, ::,
  namespace \; not in strings or comments unless asked), the server's
  ranking as boost, text edits and imports applied in UTF-16 (CRLF too),
  Lucide kind icons.
- Hover documentation (350 ms) and editor.quickDocumentation (Mod+I).
- Signature help on ( and , following the cursor; editor.parameterInfo.
- editor.complete.
- Lutra's own Markdown renderer without HTML (XSS-tested), tokens only.
- Requests wait for the buffer sync to be idle and use runWaiting.
- New dependency @codemirror/autocomplete (MIT, already transitive).

Tests: 6 engine tests against the fake server, 9 unit tests, an ignored
real-Phpactor latency test, 29 Vitest tests; palette and menu tests list
the new UI commands.

Measured with the real Phpactor (Windows 11, debug build, 25 ms tick):
- Completion 61-109 ms while typing (median 76 ms; ~107 ms in the app).
- Hover and signature help ~16 ms median.
- A useful list 2.3 s after opening a file in a 20-class project, ~65 s
  for 2,000 classes (indexing).
- Phpactor 56-71 MB working set, ~6% of one core while typing.

Live-checked in the app on port 7934. Docs: Code completion 0% -> 5%
(est.), feature depth ~4.1% -> ~4.6%, breadth 26/155, architecture, G6,
ui-parity, language-parity, roadmap, README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-22 18:38:07 +02:00
parent 12d21d96f4
commit a212a44490
35 changed files with 3916 additions and 25 deletions

View file

@ -0,0 +1,927 @@
//! Code assistance from the language server (M3.4): `lsp.completion`,
//! `lsp.hover` and `lsp.signatureHelp`.
//!
//! The mechanism, off the engine lock:
//! 1. Under the lock the command checks the buffer and the position, runs
//! the LSP pump once (so a buffer opened a moment ago is opened on the
//! server first) and queues a closure with [`crate::lsp::submit`]. That
//! is all the lock is held for.
//! 2. The closure runs on the session thread after every `didChange`
//! queued so far, so the server answers for the text the caller sees.
//! It sends the request with [`Server::request_with`]; the reply
//! callback (on a client thread, still off the lock) converts the
//! answer into Lutra's shape, so even a 20,000-item list is never
//! converted under the lock, and sends it into the channel of a
//! [`Pending`] (M3.5's mechanism, `crate::command`).
//! 3. The command returns [`Outcome::pending`]. The host releases the
//! engine lock, waits ([`Pending::wait`]) and resolves the answer
//! ([`crate::Engine::resolve`], via [`crate::run_waiting`]); the desktop
//! runs these commands through the `engine_execute_waiting` IPC, on a
//! worker thread, so the window never waits either.
//!
//! Without a session (no project, toolchain not ready, server failed) the
//! commands fail with `failed`; a server that does not offer the feature,
//! and a buffer that is not PHP, give the empty result. Server answers are
//! untrusted: every list and string is capped, unknown shapes become the
//! empty result.
use std::path::Path;
use std::time::Duration;
use lutra_lsp::types::position_to_json;
use lutra_lsp::uri::path_to_uri;
use lutra_lsp::{LspError, Range, Server};
use lutra_text::{ColumnUnit, Position};
use serde::Deserialize;
use serde_json::{Map, Value, json};
use super::params::parse;
use crate::buffers::BufferId;
use crate::{Command, CommandSpec, EngineError, Outcome, Pending, Registry, Reply, State};
/// Most completion items returned; a longer list is cut and marked
/// `incomplete`, so the editor asks again as the user types.
pub const MAX_ITEMS: usize = 500;
/// Most items of a server answer looked at (the rest is dropped unread).
const MAX_SCANNED: usize = 20_000;
/// Longest label, detail or sort text kept, in bytes.
const MAX_SHORT: usize = 1024;
/// Longest documentation, insert text or hover kept, in bytes.
const MAX_LONG: usize = 64 * 1024;
/// Most additional text edits (imports) kept per item.
const MAX_EXTRA_EDITS: usize = 32;
/// Most signatures, and parameters per signature, kept.
const MAX_SIGNATURES: usize = 32;
/// How long the server gets to answer.
pub const REQUEST_TIMEOUT: Duration = Duration::from_secs(10);
/// How long a host waits for the result: the request timeout plus slack
/// for the queue in front of it ([`Pending::wait`] adds one more second).
const WAIT_TIMEOUT: Duration = Duration::from_secs(11);
/// Registers the commands of this module.
///
/// # Errors
/// [`EngineError::Internal`] if an id is already taken.
pub fn register(registry: &mut Registry) -> Result<(), EngineError> {
registry.register(Box::new(Completion))?;
registry.register(Box::new(Hover))?;
registry.register(Box::new(SignatureHelp))?;
Ok(())
}
/// A position in params: 0-based line, UTF-16 column.
#[derive(Debug, Clone, Copy, Deserialize)]
#[serde(deny_unknown_fields)]
struct PositionParam {
/// Line.
line: usize,
/// Column in UTF-16 code units.
column: usize,
}
/// Params of `lsp.completion`.
#[derive(Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
struct CompletionParams {
/// Buffer id.
id: BufferId,
/// The cursor.
position: PositionParam,
/// The character that triggered the completion, if typing did.
#[serde(default)]
trigger_character: Option<String>,
}
/// Params of `lsp.hover` and `lsp.signatureHelp`.
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct AtParams {
/// Buffer id.
id: BufferId,
/// The position.
position: PositionParam,
}
/// `lsp.completion`: completion items at a position.
pub struct Completion;
impl Command for Completion {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "lsp.completion",
label: "Complete Code",
menu_path: None,
default_shortcut: None,
params: "{ id: number, position: { line, column }, triggerCharacter?: string }; returns { items: [{ label, kind, detail?, documentation? (markdown), insertText, textEdit?: { range: { start: { line, column }, end }, newText }, additionalTextEdits?: [{ range, newText }], sortText?, filterText?, deprecated? }], incomplete } with at most 500 items sorted by sortText; incomplete: ask again as the user types; columns are UTF-16; kind: text|method|function|constructor|field|variable|class|interface|module|property|unit|value|enum|keyword|snippet|color|file|reference|folder|enumMember|constant|struct|event|operator|typeParameter; fails without a running language server",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: CompletionParams = parse(command, params)?;
let trigger = p.trigger_character.filter(|c| c.chars().count() == 1);
let empty = json!({ "items": [], "incomplete": false });
ask(
state,
Ask {
command,
id: p.id,
position: p.position,
method: "textDocument/completion",
provider: "completionProvider",
empty,
context: Some(match trigger {
Some(character) => json!({"triggerKind": 2, "triggerCharacter": character}),
None => json!({"triggerKind": 1}),
}),
convert: completion_result,
},
)
}
}
/// `lsp.hover`: documentation of the symbol at a position.
pub struct Hover;
impl Command for Hover {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "lsp.hover",
label: "Show Quick Documentation",
menu_path: None,
default_shortcut: None,
params: "{ id: number, position: { line, column } }; returns { contents: string (markdown, empty when there is nothing), range?: { start: { line, column }, end } }; columns are UTF-16; fails without a running language server",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: AtParams = parse(command, params)?;
ask(
state,
Ask {
command,
id: p.id,
position: p.position,
method: "textDocument/hover",
provider: "hoverProvider",
empty: json!({ "contents": "" }),
context: None,
convert: hover_result,
},
)
}
}
/// `lsp.signatureHelp`: the signatures of the call around a position.
pub struct SignatureHelp;
impl Command for SignatureHelp {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "lsp.signatureHelp",
label: "Show Parameter Info",
menu_path: None,
default_shortcut: None,
params: "{ id: number, position: { line, column } }; returns { signatures: [{ label, documentation? (markdown), parameters: [{ label: [start, end] (UTF-16 offsets into the signature label) | null, documentation? }], activeParameter? }], activeSignature, activeParameter }, signatures empty outside a call; fails without a running language server",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: AtParams = parse(command, params)?;
ask(
state,
Ask {
command,
id: p.id,
position: p.position,
method: "textDocument/signatureHelp",
provider: "signatureHelpProvider",
empty: json!({ "signatures": [], "activeSignature": 0, "activeParameter": 0 }),
context: None,
convert: signature_result,
},
)
}
}
/// One request to the language server, as the commands describe it.
struct Ask {
/// The command id, for errors.
command: &'static str,
/// The buffer.
id: BufferId,
/// The position in it.
position: PositionParam,
/// The LSP method.
method: &'static str,
/// The server capability that must be present.
provider: &'static str,
/// The result when there is nothing to ask.
empty: Value,
/// The request's `context` member, if any.
context: Option<Value>,
/// Converts the server's answer into the command's result.
convert: fn(&Value) -> Value,
}
/// Validates the request, queues it on the session (see the module docs)
/// and returns the pending result.
///
/// # Errors
/// [`EngineError::Failed`] for an unknown buffer or without a language
/// server session; [`EngineError::InvalidParams`] for a position outside
/// the buffer or inside a surrogate pair.
fn ask(state: &mut State, ask: Ask) -> Result<Outcome, EngineError> {
let Ask {
command,
id,
position,
method,
provider,
empty,
context,
convert,
} = ask;
let open = state
.buffers
.get(id)
.ok_or_else(|| EngineError::Failed(format!("{command}: no buffer {id}")))?;
let at = Position::new(position.line, position.column);
open.buffer
.position_to_offset(at, ColumnUnit::Utf16)
.map_err(|e| EngineError::invalid_params(command, format!("position: {e}")))?;
if !is_php(&open.path) {
return Ok(Outcome::value(empty));
}
let Some(root) = state
.project
.as_ref()
.map(|w| w.project.root().to_path_buf())
else {
return Ok(Outcome::value(empty));
};
let path = root.join(&open.path);
let uri = path_to_uri(&path).map_err(|e| EngineError::Failed(format!("{command}: {e}")))?;
let mut request = json!({
"textDocument": { "uri": uri },
"position": position_to_json(at),
});
if let (Some(context), Some(object)) = (context, request.as_object_mut()) {
object.insert("context".into(), context);
}
crate::lsp::pump(state);
let (sender, receiver) = std::sync::mpsc::channel::<Result<Value, LspError>>();
let queued = crate::lsp::submit(state, move |server: &Server| {
let supported = server
.capabilities()
.is_none_or(|caps| caps.supports(provider));
if !supported {
let _ = sender.send(Ok(empty));
return;
}
let reply = sender.clone();
let sent = server.request_with(
method,
request,
REQUEST_TIMEOUT,
Box::new(move |result: Result<Value, LspError>| {
let _ = reply.send(result.map(|value| convert(&value)));
}),
);
if let Err(e) = sent {
let _ = sender.send(Err(e));
}
});
if !queued {
return Err(EngineError::Failed(format!(
"{command}: no PHP language server is running"
)));
}
Ok(Outcome::pending(Pending::new(
receiver,
WAIT_TIMEOUT,
move |_state: &mut State, reply: Reply| finish(command, reply),
)))
}
/// The command's value from the converted answer.
///
/// # Errors
/// [`EngineError::Failed`] for a server error, and when no answer came
/// (the session ended or the wait timed out).
fn finish(command: &str, reply: Reply) -> Result<Value, EngineError> {
match reply {
Some(Ok(value)) => Ok(value),
Some(Err(e)) => Err(EngineError::Failed(format!(
"{command}: language server: {e}"
))),
None => Err(EngineError::Failed(format!(
"{command}: the PHP language server did not answer"
))),
}
}
/// Whether a project-relative path is PHP, as the document sync decides.
fn is_php(path: &Path) -> bool {
path.extension().and_then(|e| e.to_str()).is_some_and(|e| {
["php", "phtml", "inc"]
.iter()
.any(|x| e.eq_ignore_ascii_case(x))
})
}
/// The LSP `CompletionItemKind` names, from 1.
const KINDS: [&str; 25] = [
"text",
"method",
"function",
"constructor",
"field",
"variable",
"class",
"interface",
"module",
"property",
"unit",
"value",
"enum",
"keyword",
"snippet",
"color",
"file",
"reference",
"folder",
"enumMember",
"constant",
"struct",
"event",
"operator",
"typeParameter",
];
/// The name of a completion item kind; `text` for missing or unknown ones.
fn kind_name(kind: Option<&Value>) -> &'static str {
kind.and_then(Value::as_u64)
.and_then(|k| usize::try_from(k).ok())
.and_then(|k| k.checked_sub(1))
.and_then(|k| KINDS.get(k))
.copied()
.unwrap_or("text")
}
/// Converts a `textDocument/completion` answer (`CompletionItem[]`,
/// `CompletionList` or `null`). Items are sorted by `sortText`, then
/// label, and cut at [`MAX_ITEMS`].
pub fn completion_result(value: &Value) -> Value {
let (list, mut incomplete) = match value {
Value::Array(items) => (items.as_slice(), false),
Value::Object(object) => (
object
.get("items")
.and_then(Value::as_array)
.map_or(&[][..], Vec::as_slice),
object
.get("isIncomplete")
.and_then(Value::as_bool)
.unwrap_or(false),
),
_ => (&[][..], false),
};
if list.len() > MAX_SCANNED {
incomplete = true;
}
let mut items: Vec<(String, String, Value)> = list
.iter()
.take(MAX_SCANNED)
.filter_map(completion_item)
.collect();
items.sort_by(|a, b| a.0.cmp(&b.0).then_with(|| a.1.cmp(&b.1)));
if items.len() > MAX_ITEMS {
items.truncate(MAX_ITEMS);
incomplete = true;
}
let items: Vec<Value> = items.into_iter().map(|(_, _, item)| item).collect();
json!({ "items": items, "incomplete": incomplete })
}
/// Converts one `CompletionItem`; `None` without a label.
///
/// # Returns
/// The sort key, the label and the item.
fn completion_item(item: &Value) -> Option<(String, String, Value)> {
let label = item.get("label").and_then(Value::as_str)?;
if label.is_empty() {
return None;
}
let label = cap(label, MAX_SHORT);
let snippet = item.get("insertTextFormat").and_then(Value::as_u64) == Some(2);
let plain = |text: &str| {
if snippet {
cap(&snippet_to_text(text), MAX_LONG)
} else {
cap(text, MAX_LONG)
}
};
let mut out = Map::new();
out.insert("label".into(), Value::from(label.clone()));
out.insert("kind".into(), Value::from(kind_name(item.get("kind"))));
if let Some(detail) = detail_of(item) {
out.insert("detail".into(), Value::from(detail));
}
if let Some(doc) = item.get("documentation").and_then(markup) {
out.insert("documentation".into(), Value::from(doc));
}
let text_edit = item.get("textEdit").and_then(|edit| {
let range = edit
.get("range")
.or_else(|| edit.get("insert"))
.and_then(Range::from_json)?;
let new_text = edit.get("newText").and_then(Value::as_str)?;
Some((range, plain(new_text)))
});
let insert_text = match (&text_edit, item.get("insertText").and_then(Value::as_str)) {
(Some((_, new_text)), _) => new_text.clone(),
(None, Some(text)) => plain(text),
(None, None) => label.clone(),
};
out.insert("insertText".into(), Value::from(insert_text));
if let Some((range, new_text)) = text_edit {
out.insert("textEdit".into(), edit_json(range, new_text));
}
let extra: Vec<Value> = item
.get("additionalTextEdits")
.and_then(Value::as_array)
.map(|edits| {
edits
.iter()
.filter_map(|edit| {
let range = edit.get("range").and_then(Range::from_json)?;
let new_text = edit.get("newText").and_then(Value::as_str)?;
Some(edit_json(range, cap(new_text, MAX_LONG)))
})
.take(MAX_EXTRA_EDITS)
.collect()
})
.unwrap_or_default();
if !extra.is_empty() {
out.insert("additionalTextEdits".into(), Value::from(extra));
}
let sort_text = item
.get("sortText")
.and_then(Value::as_str)
.map(|s| cap(s, MAX_SHORT));
if let Some(sort) = &sort_text {
out.insert("sortText".into(), Value::from(sort.clone()));
}
if let Some(filter) = item.get("filterText").and_then(Value::as_str) {
out.insert("filterText".into(), Value::from(cap(filter, MAX_SHORT)));
}
let deprecated = item.get("deprecated").and_then(Value::as_bool) == Some(true)
|| item
.get("tags")
.and_then(Value::as_array)
.is_some_and(|tags| tags.iter().any(|t| t.as_u64() == Some(1)));
if deprecated {
out.insert("deprecated".into(), Value::Bool(true));
}
let key = sort_text.unwrap_or_else(|| label.clone());
Some((key, label, Value::Object(out)))
}
/// The item's detail; the label details stand in when it has none.
fn detail_of(item: &Value) -> Option<String> {
if let Some(detail) = item.get("detail").and_then(Value::as_str)
&& !detail.is_empty()
{
return Some(cap(detail, MAX_SHORT));
}
let details = item.get("labelDetails")?;
let parts: Vec<&str> = ["detail", "description"]
.iter()
.filter_map(|k| details.get(*k).and_then(Value::as_str))
.filter(|s| !s.is_empty())
.collect();
(!parts.is_empty()).then(|| cap(&parts.join(" "), MAX_SHORT))
}
/// A text edit as Lutra's protocol writes it.
fn edit_json(range: Range, new_text: String) -> Value {
json!({ "range": range_json(range), "newText": new_text })
}
/// A range with `{line, column}` positions.
fn range_json(range: Range) -> Value {
json!({
"start": { "line": range.start.line, "column": range.start.column },
"end": { "line": range.end.line, "column": range.end.column },
})
}
/// Converts a `textDocument/hover` answer into `{contents, range?}`.
pub fn hover_result(value: &Value) -> Value {
let contents = match value.get("contents") {
Some(Value::Array(parts)) => parts
.iter()
.take(MAX_SIGNATURES)
.filter_map(marked)
.filter(|s| !s.trim().is_empty())
.collect::<Vec<_>>()
.join("\n\n"),
Some(part) => marked(part).unwrap_or_default(),
None => String::new(),
};
let mut out = Map::new();
out.insert("contents".into(), Value::from(cap(&contents, MAX_LONG)));
if let Some(range) = value.get("range").and_then(Range::from_json) {
out.insert("range".into(), range_json(range));
}
Value::Object(out)
}
/// One hover part as markdown: a `MarkupContent`, a markdown string or a
/// `{language, value}` code block.
fn marked(part: &Value) -> Option<String> {
match part {
Value::String(text) => Some(text.clone()),
Value::Object(object) if object.contains_key("language") => {
let language = object.get("language").and_then(Value::as_str)?;
let code = object.get("value").and_then(Value::as_str)?;
let language: String = language
.chars()
.filter(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '+'))
.collect();
Some(format!(
"```{language}\n{}\n```",
code.replace("```", "`\u{200b}``")
))
}
Value::Object(_) => markup(part),
_ => None,
}
}
/// Documentation as markdown: a `MarkupContent` or a plain string, whose
/// markdown characters are escaped.
fn markup(value: &Value) -> Option<String> {
let (kind, text) = match value {
Value::String(text) => ("plaintext", text.as_str()),
Value::Object(object) => (
object
.get("kind")
.and_then(Value::as_str)
.unwrap_or("plaintext"),
object.get("value").and_then(Value::as_str)?,
),
_ => return None,
};
if text.trim().is_empty() {
return None;
}
let text = cap(text, MAX_LONG);
Some(if kind == "markdown" {
text
} else {
escape_markdown(&text)
})
}
/// Escapes the characters markdown gives a meaning, so plain text shows
/// as written.
pub fn escape_markdown(text: &str) -> String {
let mut out = String::with_capacity(text.len());
for c in text.chars() {
if "\\`*_{}[]()<>#+-.!|~".contains(c) {
out.push('\\');
}
out.push(c);
}
out
}
/// Converts a `textDocument/signatureHelp` answer.
pub fn signature_result(value: &Value) -> Value {
let signatures: Vec<Value> = value
.get("signatures")
.and_then(Value::as_array)
.map(|list| {
list.iter()
.take(MAX_SIGNATURES)
.filter_map(signature)
.collect()
})
.unwrap_or_default();
let index = |key: &str| value.get(key).and_then(Value::as_u64).unwrap_or(0);
json!({
"signatures": signatures,
"activeSignature": index("activeSignature"),
"activeParameter": index("activeParameter"),
})
}
/// Converts one `SignatureInformation`; `None` without a label.
fn signature(value: &Value) -> Option<Value> {
let label = cap(value.get("label").and_then(Value::as_str)?, MAX_SHORT * 4);
let length = label.encode_utf16().count();
let parameters: Vec<Value> = value
.get("parameters")
.and_then(Value::as_array)
.map(|list| {
list.iter()
.take(MAX_SIGNATURES * 2)
.map(|p| {
let span = match p.get("label") {
Some(Value::String(text)) if !text.is_empty() => {
label.find(text.as_str()).map(|byte| {
let start = label.get(..byte).unwrap_or("").encode_utf16().count();
(start, start + text.encode_utf16().count())
})
}
Some(Value::Array(pair)) => {
let at = |i: usize| {
pair.get(i)
.and_then(Value::as_u64)
.and_then(|n| usize::try_from(n).ok())
};
match (at(0), at(1)) {
(Some(a), Some(b)) if a <= b && b <= length => Some((a, b)),
_ => None,
}
}
_ => None,
};
let mut out = Map::new();
out.insert(
"label".into(),
span.map_or(Value::Null, |(a, b)| json!([a, b])),
);
if let Some(doc) = p.get("documentation").and_then(markup) {
out.insert("documentation".into(), Value::from(doc));
}
Value::Object(out)
})
.collect()
})
.unwrap_or_default();
let mut out = Map::new();
out.insert("label".into(), Value::from(label));
if let Some(doc) = value.get("documentation").and_then(markup) {
out.insert("documentation".into(), Value::from(doc));
}
out.insert("parameters".into(), Value::from(parameters));
if let Some(active) = value.get("activeParameter").and_then(Value::as_u64) {
out.insert("activeParameter".into(), Value::from(active));
}
Some(Value::Object(out))
}
/// Turns snippet syntax into the text it inserts: tab stops (`$1`,
/// `${2}`) vanish, placeholders (`${1:name}`) keep their text, choices
/// (`${1|a,b|}`) their first option, escapes (`\$`, `\}`, `\\`) their
/// character. `$` before anything else (a PHP variable) stays.
pub fn snippet_to_text(snippet: &str) -> String {
let mut out = String::with_capacity(snippet.len());
let chars: Vec<char> = snippet.chars().collect();
let mut i = 0;
let mut depth = 0usize;
while let Some(&c) = chars.get(i) {
let next = chars.get(i + 1).copied();
match c {
'\\' if matches!(next, Some('$' | '}' | '\\' | ',' | '|')) => {
if let Some(n) = next {
out.push(n);
}
i += 2;
}
'$' if next.is_some_and(|n| n.is_ascii_digit()) => {
i += 1;
while chars.get(i).is_some_and(char::is_ascii_digit) {
i += 1;
}
}
'$' if next == Some('{') => {
let mut j = i + 2;
while chars.get(j).is_some_and(char::is_ascii_digit) {
j += 1;
}
match chars.get(j) {
Some(':') => {
depth += 1;
i = j + 1;
}
Some('|') => {
depth += 1;
i = j + 1;
let mut first = true;
while let Some(&ch) = chars.get(i) {
if ch == '|' && chars.get(i + 1) == Some(&'}') {
i += 1;
break;
}
if ch == ',' {
first = false;
} else if first {
out.push(ch);
}
i += 1;
}
}
Some('}') => i = j + 1,
_ => {
out.push(c);
i += 1;
}
}
}
'}' if depth > 0 => {
depth -= 1;
i += 1;
}
_ => {
out.push(c);
i += 1;
}
}
}
out
}
/// `text` cut to at most `max` bytes, on a character boundary.
fn cap(text: &str, max: usize) -> String {
if text.len() <= max {
return text.to_string();
}
let end = text
.char_indices()
.map(|(i, _)| i)
.take_while(|&i| i <= max)
.last()
.unwrap_or(0);
text.get(..end).unwrap_or("").to_string()
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::{
MAX_ITEMS, cap, completion_result, escape_markdown, hover_result, kind_name,
signature_result, snippet_to_text,
};
#[test]
fn kinds_map_to_names() {
assert_eq!(kind_name(Some(&json!(2))), "method");
assert_eq!(kind_name(Some(&json!(25))), "typeParameter");
assert_eq!(kind_name(Some(&json!(0))), "text");
assert_eq!(kind_name(Some(&json!(99))), "text");
assert_eq!(kind_name(Some(&json!("x"))), "text");
assert_eq!(kind_name(None), "text");
}
#[test]
fn completion_reads_lists_and_arrays() {
let list = completion_result(&json!({
"isIncomplete": true,
"items": [
{"label": "b", "sortText": "2"},
{"label": "a", "sortText": "1", "kind": 7, "detail": "App\\A",
"documentation": {"kind": "markdown", "value": "**A**"}},
{"label": ""},
{"nolabel": true}
]
}));
assert_eq!(list["incomplete"], true);
let items = list["items"].as_array().unwrap();
assert_eq!(items.len(), 2);
assert_eq!(items[0]["label"], "a");
assert_eq!(items[0]["kind"], "class");
assert_eq!(items[0]["documentation"], "**A**");
assert_eq!(items[0]["insertText"], "a");
let array = completion_result(&json!([{"label": "x", "insertText": "x()"}]));
assert_eq!(array["incomplete"], false);
assert_eq!(array["items"][0]["insertText"], "x()");
assert_eq!(completion_result(&json!(null))["items"], json!([]));
assert_eq!(completion_result(&json!("junk"))["items"], json!([]));
}
#[test]
fn completion_is_capped_and_marked_incomplete() {
let items: Vec<_> = (0..MAX_ITEMS + 50)
.map(|i| json!({"label": format!("item{i:04}")}))
.collect();
let out = completion_result(&json!({"isIncomplete": false, "items": items}));
assert_eq!(out["items"].as_array().unwrap().len(), MAX_ITEMS);
assert_eq!(out["incomplete"], true);
assert_eq!(out["items"][0]["label"], "item0000");
}
#[test]
fn text_edits_and_snippets_become_plain_text() {
let out = completion_result(&json!([{
"label": "format",
"insertTextFormat": 2,
"textEdit": {"range": {"start": {"line": 1, "character": 6}, "end": {"line": 1, "character": 8}},
"newText": "format(${1:\\$pattern})$0"},
"additionalTextEdits": [{"range": {"start": {"line": 0, "character": 5}, "end": {"line": 0, "character": 5}},
"newText": "\nuse App\\Fmt;"}],
"documentation": "a < b *c*",
"tags": [1]
}]));
let item = &out["items"][0];
assert_eq!(item["insertText"], "format($pattern)");
assert_eq!(item["textEdit"]["newText"], "format($pattern)");
assert_eq!(
item["textEdit"]["range"],
json!({"start": {"line": 1, "column": 6}, "end": {"line": 1, "column": 8}})
);
assert_eq!(item["additionalTextEdits"][0]["newText"], "\nuse App\\Fmt;");
assert_eq!(item["documentation"], "a \\< b \\*c\\*");
assert_eq!(item["deprecated"], true);
}
#[test]
fn label_details_stand_in_for_a_missing_detail() {
let out = completion_result(&json!([{
"label": "f", "labelDetails": {"detail": "(int $a)", "description": "App"}
}]));
assert_eq!(out["items"][0]["detail"], "(int $a) App");
}
#[test]
fn snippets() {
assert_eq!(snippet_to_text("foo($1, $2)$0"), "foo(, )");
assert_eq!(snippet_to_text("${1:a} ${2:${3:b}}"), "a b");
assert_eq!(snippet_to_text("${1|one,two|}"), "one");
assert_eq!(snippet_to_text("\\$this->x"), "$this->x");
assert_eq!(snippet_to_text("$this"), "$this");
assert_eq!(snippet_to_text("${x"), "${x");
assert_eq!(snippet_to_text("${12}a"), "a");
}
#[test]
fn hover_parts_become_markdown() {
assert_eq!(
hover_result(&json!({"contents": {"kind": "markdown", "value": "# T"}}))["contents"],
"# T"
);
let out = hover_result(&json!({
"contents": [{"language": "php", "value": "class A {}"}, "text", ""],
"range": {"start": {"line": 0, "character": 1}, "end": {"line": 0, "character": 2}}
}));
assert_eq!(out["contents"], "```php\nclass A {}\n```\n\ntext");
assert_eq!(out["range"]["end"]["column"], 2);
assert_eq!(hover_result(&json!(null)), json!({"contents": ""}));
assert_eq!(
hover_result(&json!({"contents": {"kind": "plaintext", "value": "<b>"}}))["contents"],
"\\<b\\>"
);
}
#[test]
fn signatures_get_utf16_parameter_spans() {
let out = signature_result(&json!({
"signatures": [{
"label": "f(\u{1f600} $a, int $b)",
"documentation": "doc",
"parameters": [{"label": "\u{1f600} $a"}, {"label": [9, 15]}, {"label": [3, 99]}, {"label": "zz"}]
}],
"activeSignature": 0,
"activeParameter": 1
}));
let sig = &out["signatures"][0];
assert_eq!(sig["parameters"][0]["label"], json!([2, 7]));
assert_eq!(sig["parameters"][1]["label"], json!([9, 15]));
assert_eq!(sig["parameters"][2]["label"], json!(null));
assert_eq!(sig["parameters"][3]["label"], json!(null));
assert_eq!(out["activeParameter"], 1);
assert_eq!(signature_result(&json!(null))["signatures"], json!([]));
}
#[test]
fn caps_cut_on_character_boundaries() {
assert_eq!(cap("äöü", 3), "ä");
assert_eq!(cap("abc", 10), "abc");
assert_eq!(escape_markdown("a_b"), "a\\_b");
}
}

View file

@ -4,6 +4,7 @@ mod app;
mod buffer;
mod file;
pub mod goto;
mod lsp_assist;
mod lsp_diagnostics;
mod params;
mod project;
@ -60,5 +61,6 @@ pub fn register_builtins(registry: &mut Registry) -> Result<(), EngineError> {
registry.register(Box::new(terminal::Resize))?;
registry.register(Box::new(terminal::Close))?;
lsp_diagnostics::register(registry)?;
lsp_assist::register(registry)?;
Ok(())
}

View file

@ -467,7 +467,10 @@ mod tests {
"goto.file",
"goto.symbol",
"index.status",
"lsp.completion",
"lsp.hover",
"lsp.restart",
"lsp.signatureHelp",
"lsp.status",
"project.children",
"project.close",

View file

@ -0,0 +1,477 @@
//! Completion, hover and signature help (M3.4) against `lutra-lsp-fake`,
//! whose answers are scripted (see its `completion` function). The
//! commands return pending results, which the tests wait for without the
//! engine lock and resolve with it (`run_waiting`), as hosts do.
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::panic,
clippy::indexing_slicing
)]
use std::ffi::OsString;
use std::fs;
use std::path::PathBuf;
use lutra_engine::lsp::Launch;
use lutra_engine::{Engine, EngineError};
use lutra_lsp::ServerOptions;
use serde_json::{Value, json};
use tempfile::TempDir;
/// The fake server binary, built on demand when this test runs without
/// the rest of the workspace (`cargo test -p lutra-engine`).
fn fake_server() -> PathBuf {
let exe = format!("lutra-lsp-fake{}", std::env::consts::EXE_SUFFIX);
let deps = std::env::current_exe().unwrap();
let path = deps.parent().unwrap().parent().unwrap().join(exe);
if !path.exists() {
let cargo = std::env::var_os("CARGO").unwrap_or_else(|| "cargo".into());
let status = std::process::Command::new(cargo)
.args(["build", "-p", "lutra-lsp", "--bin", "lutra-lsp-fake"])
.status()
.unwrap();
assert!(status.success(), "building lutra-lsp-fake failed");
}
path
}
/// A temp project with `files`, opened in an engine that runs the fake
/// server (or none).
fn project(files: &[(&str, &str)], server: bool) -> (TempDir, Engine) {
let dir = tempfile::tempdir().unwrap();
for (name, text) in files {
fs::write(dir.path().join(name), text).unwrap();
}
let mut engine = Engine::new().unwrap();
if server {
engine.set_language_server(Some(Launch {
command: fake_server().into(),
args: Vec::<OsString>::new(),
options: ServerOptions::default(),
tick: None,
}));
}
engine
.execute("project.open", json!({"path": dir.path()}))
.unwrap();
(dir, engine)
}
/// Opens `path`; returns the buffer id.
fn open(engine: &mut Engine, path: &str) -> u64 {
engine
.execute("file.open", json!({"path": path}))
.unwrap()
.value["id"]
.as_u64()
.unwrap()
}
/// Runs `command` and waits for its pending result, as a host does.
fn ask(engine: &mut Engine, command: &str, params: Value) -> Result<Value, EngineError> {
let mut outcome = engine.execute(command, params)?;
match outcome.pending.take() {
Some(pending) => Ok(engine.resolve(pending.wait())?.value),
None => Ok(outcome.value),
}
}
#[test]
fn completion_converts_the_servers_list() {
let (_dir, mut engine) = project(&[("a.php", "<?php\n$x->fo")], true);
let id = open(&mut engine, "a.php");
let out = ask(
&mut engine,
"lsp.completion",
json!({"id": id, "position": {"line": 1, "column": 6}}),
)
.unwrap();
assert_eq!(out["incomplete"], true);
let items = out["items"].as_array().unwrap();
let labels: Vec<&str> = items.iter().map(|i| i["label"].as_str().unwrap()).collect();
assert_eq!(labels, ["format", "$value", "pair", "trigger:none"]);
let format = &items[0];
assert_eq!(format["kind"], "method");
assert_eq!(format["detail"], "format(string $pattern): string");
assert_eq!(format["documentation"], "Formats **text**.");
assert_eq!(format["insertText"], "format(");
assert_eq!(
format["textEdit"],
json!({"range": {"start": {"line": 1, "column": 4}, "end": {"line": 1, "column": 6}}, "newText": "format("})
);
assert_eq!(
format["additionalTextEdits"][0]["newText"],
"\nuse App\\Fmt;"
);
assert_eq!(items[1]["kind"], "variable");
assert_eq!(items[1]["insertText"], "$value");
assert_eq!(items[2]["insertText"], "pair($a, )");
let triggered = ask(
&mut engine,
"lsp.completion",
json!({"id": id, "position": {"line": 1, "column": 4}, "triggerCharacter": ">"}),
)
.unwrap();
assert_eq!(triggered["items"][3]["label"], "trigger:>");
}
#[test]
fn completion_sees_the_edit_before_it_and_is_capped() {
let (_dir, mut engine) = project(&[("a.php", "<?php\n")], true);
let id = open(&mut engine, "a.php");
let first = ask(
&mut engine,
"lsp.completion",
json!({"id": id, "position": {"line": 1, "column": 0}}),
)
.unwrap();
assert_eq!(first["items"].as_array().unwrap().len(), 4);
engine
.execute(
"buffer.edit",
json!({"id": id, "baseVersion": 1, "edits": [{"from": 6, "to": 6, "insert": "MANY"}]}),
)
.unwrap();
let out = ask(
&mut engine,
"lsp.completion",
json!({"id": id, "position": {"line": 1, "column": 4}}),
)
.unwrap();
let items = out["items"].as_array().unwrap();
assert_eq!(items.len(), 500);
assert_eq!(out["incomplete"], true);
assert_eq!(items[0]["label"], "item000");
}
#[test]
fn hover_and_signature_help() {
let (_dir, mut engine) = project(&[("a.php", "<?php\r\npair(1, 2);\r\n")], true);
let id = open(&mut engine, "a.php");
let hover = ask(
&mut engine,
"lsp.hover",
json!({"id": id, "position": {"line": 1, "column": 11}}),
)
.unwrap();
assert_eq!(hover, json!({"contents": "hover 1:11"}));
let help = ask(
&mut engine,
"lsp.signatureHelp",
json!({"id": id, "position": {"line": 1, "column": 9}}),
)
.unwrap();
assert_eq!(help["activeParameter"], 1);
let signature = &help["signatures"][0];
assert_eq!(signature["label"], "pair(int $a, string $b): void");
assert_eq!(signature["documentation"], "Makes a *pair*.");
assert_eq!(signature["parameters"][0]["label"], json!([5, 11]));
assert_eq!(signature["parameters"][1]["label"], json!([13, 22]));
}
#[test]
fn positions_are_checked_against_the_buffer() {
let (_dir, mut engine) = project(&[("a.php", "<?php\r\n\u{1F9A6}\r\n")], true);
let id = open(&mut engine, "a.php");
let past_line_break = ask(
&mut engine,
"lsp.hover",
json!({"id": id, "position": {"line": 0, "column": 6}}),
);
assert_eq!(past_line_break.unwrap_err().code(), "invalid_params");
let inside_pair = ask(
&mut engine,
"lsp.hover",
json!({"id": id, "position": {"line": 1, "column": 1}}),
);
assert_eq!(inside_pair.unwrap_err().code(), "invalid_params");
let no_line = ask(
&mut engine,
"lsp.completion",
json!({"id": id, "position": {"line": 9, "column": 0}}),
);
assert_eq!(no_line.unwrap_err().code(), "invalid_params");
let after_emoji = ask(
&mut engine,
"lsp.hover",
json!({"id": id, "position": {"line": 1, "column": 2}}),
)
.unwrap();
assert_eq!(after_emoji["contents"], "hover 1:2");
let unknown = ask(
&mut engine,
"lsp.hover",
json!({"id": 999, "position": {"line": 0, "column": 0}}),
);
assert_eq!(unknown.unwrap_err().code(), "failed");
let extra = ask(
&mut engine,
"lsp.hover",
json!({"id": id, "position": {"line": 0, "column": 0}, "nope": 1}),
);
assert_eq!(extra.unwrap_err().code(), "invalid_params");
}
#[test]
fn non_php_buffers_get_empty_results() {
let (_dir, mut engine) = project(&[("notes.txt", "hello")], true);
let id = open(&mut engine, "notes.txt");
let out = ask(
&mut engine,
"lsp.completion",
json!({"id": id, "position": {"line": 0, "column": 2}}),
)
.unwrap();
assert_eq!(out, json!({"items": [], "incomplete": false}));
let help = ask(
&mut engine,
"lsp.signatureHelp",
json!({"id": id, "position": {"line": 0, "column": 2}}),
)
.unwrap();
assert_eq!(help["signatures"], json!([]));
}
#[test]
fn fails_without_a_language_server() {
let (_dir, mut engine) = project(&[("a.php", "<?php\n")], false);
let id = open(&mut engine, "a.php");
let err = ask(
&mut engine,
"lsp.completion",
json!({"id": id, "position": {"line": 0, "column": 0}}),
)
.unwrap_err();
assert_eq!(err.code(), "failed");
assert!(err.to_string().contains("no PHP language server"), "{err}");
let mut bare = Engine::new().unwrap();
let disabled = bare
.execute(
"lsp.hover",
json!({"id": 1, "position": {"line": 0, "column": 0}}),
)
.unwrap_err();
assert_eq!(disabled.code(), "disabled");
}
/// Milliseconds since the Unix epoch, for lining up the phases with an
/// outside RAM/CPU sampler.
fn epoch_ms() -> u128 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_millis()
}
/// Times `f`.
fn timed<T>(f: impl FnOnce() -> T) -> (T, f64) {
let start = std::time::Instant::now();
let value = f();
(value, start.elapsed().as_secs_f64() * 1000.0)
}
/// Replaces line `line` (0-based) of buffer `id` with `text`.
fn set_line(engine: &mut Engine, id: u64, line: usize, text: &str) {
let current = engine
.execute("buffer.get", json!({"id": id}))
.unwrap()
.value;
let whole = current["text"].as_str().unwrap();
let from: usize = whole
.split('\n')
.take(line)
.map(|l| l.encode_utf16().count() + 1)
.sum();
let to = from + whole.split('\n').nth(line).unwrap().encode_utf16().count();
engine
.execute(
"buffer.edit",
json!({"id": id, "baseVersion": current["version"], "edits": [{"from": from, "to": to, "insert": text}]}),
)
.unwrap();
}
/// Min, median and max of `samples` in ms.
fn summary(samples: &mut [f64]) -> String {
samples.sort_by(f64::total_cmp);
let n = samples.len();
format!(
"n={n} min={:.0} median={:.0} max={:.0} ms",
samples[0],
samples[n / 2],
samples[n - 1]
)
}
/// A shop-like project: `classes` classes in `src/` plus the file the
/// test types in.
fn shop(classes: usize) -> Vec<(String, String)> {
let mut files = Vec::new();
for i in 0..classes {
files.push((
format!("src/Product{i}.php"),
format!(
"<?php\n\nnamespace Shop;\n\n/**\n * A product of the shop, number {i}.\n */\nfinal class Product{i}\n{{\n public function __construct(private string $name, private int $price) {{}}\n\n /** The display name. */\n public function name(): string\n {{\n return $this->name;\n }}\n\n /** The price in cents, times `$count`. */\n public function price(int $count = 1, bool $gross = true): int\n {{\n return $this->price * $count;\n }}\n}}\n"
),
));
}
files.push((
"src/Cart.php".into(),
"<?php\n\nnamespace Shop;\n\nfinal class Cart\n{\n public function add(Product0 $product): void\n {\n $product->\n }\n}\n".into(),
));
files
}
/// Completion, hover and signature help against the real Phpactor, with
/// latencies and phase timestamps (`PHASE <name> <start|end> <epoch ms>`)
/// for an outside sampler of the Phpactor process:
///
/// `LUTRA_PHPACTOR=<phar> [LUTRA_PHP=php] [LUTRA_SHOP_CLASSES=20] cargo test -p lutra-engine --test lsp_assist real_phpactor -- --ignored --nocapture`
#[test]
#[ignore = "needs PHP and Phpactor (LUTRA_PHPACTOR)"]
fn real_phpactor_assist_latency() {
let phar = std::env::var("LUTRA_PHPACTOR").expect("LUTRA_PHPACTOR");
let php = std::env::var("LUTRA_PHP").unwrap_or_else(|_| "php".into());
let classes: usize = std::env::var("LUTRA_SHOP_CLASSES")
.ok()
.and_then(|n| n.parse().ok())
.unwrap_or(20);
let dir = tempfile::tempdir().unwrap();
for (name, text) in shop(classes) {
let path = dir.path().join(name);
fs::create_dir_all(path.parent().unwrap()).unwrap();
fs::write(path, text).unwrap();
}
let mut engine = Engine::new().unwrap();
engine.set_language_server(Some(lutra_engine::lsp::phpactor_launch(
&php,
&phar,
cfg!(windows),
)));
engine
.execute("project.open", json!({"path": dir.path()}))
.unwrap();
let started = std::time::Instant::now();
loop {
let ready = engine
.pump_vfs()
.unwrap()
.iter()
.any(|e| serde_json::to_value(e).unwrap()["state"] == "ready");
if ready {
break;
}
assert!(started.elapsed().as_secs() < 60, "Phpactor not ready");
std::thread::sleep(std::time::Duration::from_millis(10));
}
println!("ready after {:?} ({classes} classes)", started.elapsed());
let id = open(&mut engine, "src/Cart.php");
let at_arrow =
json!({"id": id, "position": {"line": 8, "column": 18}, "triggerCharacter": ">"});
let opened = std::time::Instant::now();
let mut attempts = 0;
let first = loop {
attempts += 1;
let (out, ms) = timed(|| ask(&mut engine, "lsp.completion", at_arrow.clone()).unwrap());
let found = out["items"]
.as_array()
.unwrap()
.iter()
.any(|i| i["label"] == "price");
if attempts == 1 {
println!("first completion after -> {ms:.0} ms: {out}");
}
if found {
break out;
}
assert!(
opened.elapsed().as_secs() < 90,
"no useful completion within 90 s: {out}"
);
std::thread::sleep(std::time::Duration::from_millis(250));
};
println!(
"useful completion {:?} after file.open ({attempts} attempts)",
opened.elapsed()
);
let labels: Vec<&str> = first["items"]
.as_array()
.unwrap()
.iter()
.map(|i| i["label"].as_str().unwrap())
.collect();
println!("labels: {labels:?}");
println!("first item: {}", first["items"][0]);
println!("PHASE idle start {}", epoch_ms());
std::thread::sleep(std::time::Duration::from_secs(70));
println!("PHASE idle end {}", epoch_ms());
let (_, after_idle) = timed(|| ask(&mut engine, "lsp.completion", at_arrow.clone()).unwrap());
println!("completion after 70 s idle (ticks stopped) {after_idle:.0} ms");
println!("PHASE typing start {}", epoch_ms());
let mut completion = Vec::new();
for round in 0..15 {
let typed = ["", "p", "pr"][round % 3];
let line = format!(" $product->{typed}");
set_line(&mut engine, id, 8, &line);
let (_, ms) = timed(|| {
ask(
&mut engine,
"lsp.completion",
json!({"id": id, "position": {"line": 8, "column": line.encode_utf16().count()}}),
)
.unwrap()
});
completion.push(ms);
std::thread::sleep(std::time::Duration::from_millis(150));
}
println!("completion while typing: {}", summary(&mut completion));
let call = " $product->price(1, ";
set_line(&mut engine, id, 8, call);
let mut signature = Vec::new();
for _ in 0..10 {
let (out, ms) = timed(|| {
ask(
&mut engine,
"lsp.signatureHelp",
json!({"id": id, "position": {"line": 8, "column": call.encode_utf16().count()}}),
)
.unwrap()
});
signature.push(ms);
if signature.len() == 1 {
println!("signature help: {out}");
}
}
println!("signature help: {}", summary(&mut signature));
let mut hover = Vec::new();
for _ in 0..10 {
let (out, ms) = timed(|| {
ask(
&mut engine,
"lsp.hover",
json!({"id": id, "position": {"line": 6, "column": 26}}),
)
.unwrap()
});
hover.push(ms);
assert!(
out["contents"].as_str().unwrap().contains("Product0"),
"{out}"
);
}
println!("hover on a class: {}", summary(&mut hover));
let text = ask(
&mut engine,
"lsp.hover",
json!({"id": id, "position": {"line": 6, "column": 26}}),
)
.unwrap();
println!("hover contents: {}", text["contents"]);
println!("PHASE typing end {}", epoch_ms());
}