M3.3: engine wiring for Phpactor and diagnostics

- One Phpactor per open project on its own session thread, started when
  the toolchain is ready; ordered document sync from buffer.edit and the
  pump; lspStatus, diagnosticsChanged, diagnostics.list, lsp.status,
  lsp.restart; app.quit stops the server synchronously.
- Phpactor 2026.06.25.0 on Windows: keep-alive $/lutra/tick (its event
  loop only runs on stdin input), in-process diagnostics and a polling
  watcher through initializationOptions (amphp subprocesses fail), 500 ms
  shutdown timeout.
- Editor lint extension (underlines, gutter dots, hover; tokens only) and
  a Problems tab in the bottom panel; problems.open Mod+Alt+P.
- Tests: engine tests against the fake server (incl. sync proptest), an
  ignored real-Phpactor test, a TCP test, Vitest for lint and Problems.
- Docs: architecture, gaps G6, parity (Inspections 4% est.), ui-parity,
  roadmap, ROADMAP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-21 18:58:32 +02:00
parent 65c6966588
commit 13c76d3046
34 changed files with 3562 additions and 37 deletions

529
crates/engine/tests/lsp.rs Normal file
View file

@ -0,0 +1,529 @@
//! The engine ↔ language server wiring (M3.3) against `lutra-lsp-fake`,
//! M3.2's scripted server, which publishes every document's whole text as
//! its one diagnostic. That makes the document sync visible: after any
//! sequence of `buffer.edit`s the diagnostic must equal the buffer's text.
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::panic,
clippy::indexing_slicing,
clippy::string_slice
)]
use std::ffi::OsString;
use std::fs;
use std::path::PathBuf;
use std::sync::{Mutex, mpsc};
use std::time::{Duration, Instant};
use lutra_engine::lsp::Launch;
use lutra_engine::{Command, CommandSpec, Engine, EngineError, Event, Outcome, State};
use lutra_lsp::{RestartPolicy, ServerOptions};
use proptest::prelude::*;
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
}
/// Starting the fake server with `args`.
fn launch(args: &[&str], options: ServerOptions) -> Launch {
Launch {
command: fake_server().into(),
args: args.iter().map(OsString::from).collect(),
options,
tick: None,
}
}
/// A temp project with `files`, opened in an engine that runs the fake
/// server.
fn project(files: &[(&str, &str)], launch: Launch) -> (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();
engine.set_language_server(Some(launch));
engine
.execute("project.open", json!({"path": dir.path()}))
.unwrap();
(dir, engine)
}
/// Pumps until `done` holds for an event; returns every event seen, up to
/// the end of that pump's batch.
fn pump_until(engine: &mut Engine, done: impl Fn(&Value) -> bool) -> Vec<Value> {
let deadline = Instant::now() + Duration::from_secs(20);
let mut seen = Vec::new();
while Instant::now() < deadline {
let mut hit = false;
for event in engine.pump_vfs().unwrap() {
let value = serde_json::to_value(&event).unwrap();
hit |= done(&value);
seen.push(value);
}
if hit {
return seen;
}
std::thread::sleep(Duration::from_millis(5));
}
panic!("condition not met within 20 s; events: {seen:#?}");
}
/// Whether `e` is `lspStatus` with `state`.
fn status_is(e: &Value, state: &str) -> bool {
e["kind"] == "lspStatus" && e["state"] == state
}
/// Pumps until the diagnostic of `path` says `text`.
fn wait_for_text(engine: &mut Engine, path: &str, text: &str) {
pump_until(engine, |e| {
e["kind"] == "diagnosticsChanged" && e["path"] == path && e["items"][0]["message"] == text
});
}
/// Applies one UTF-16 edit to buffer `id`; returns the new version.
fn edit(engine: &mut Engine, id: u64, base: u64, from: usize, to: usize, insert: &str) -> u64 {
let out = engine
.execute(
"buffer.edit",
json!({"id": id, "baseVersion": base, "edits": [{"from": from, "to": to, "insert": insert}]}),
)
.unwrap();
out.value["version"].as_u64().unwrap()
}
/// The text of buffer `id`.
fn text(engine: &mut Engine, id: u64) -> String {
let out = engine.execute("buffer.get", json!({"id": id})).unwrap();
out.value["text"].as_str().unwrap().to_string()
}
#[test]
fn syncs_buffers_and_reports_diagnostics() {
let (_dir, mut engine) = project(
&[("a.php", "<?php\necho 1;\n"), ("notes.txt", "plain")],
launch(&[], ServerOptions::default()),
);
let seen = pump_until(&mut engine, |e| status_is(e, "ready"));
assert!(seen.iter().any(|e| status_is(e, "starting")), "{seen:?}");
let status = engine.execute("lsp.status", Value::Null).unwrap().value;
assert_eq!(status["state"], "ready");
assert!(status["startupMs"].as_u64().is_some(), "{status}");
let id = engine
.execute("file.open", json!({"path": "a.php"}))
.unwrap()
.value["id"]
.as_u64()
.unwrap();
wait_for_text(&mut engine, "a.php", "<?php\necho 1;\n");
let v = edit(&mut engine, id, 1, 11, 12, "\u{1F9A6} 2");
let v = edit(&mut engine, id, v, 0, 0, "\r\n");
let _ = edit(&mut engine, id, v, 2, 2, "// é\n");
let expected = text(&mut engine, id);
assert_eq!(expected, "\r\n// é\n<?php\necho \u{1F9A6} 2;\n");
wait_for_text(&mut engine, "a.php", &expected);
let list = engine
.execute("diagnostics.list", json!({"path": "a.php"}))
.unwrap()
.value;
let item = &list["files"][0]["items"][0];
assert_eq!(list["files"][0]["path"], "a.php");
assert_eq!(item["severity"], "error");
assert_eq!(item["source"], "fake");
assert_eq!(item["message"], expected.as_str());
assert_eq!(
item["range"],
json!({"start": {"line": 0, "column": 0}, "end": {"line": 0, "column": 0}})
);
let txt = engine
.execute("file.open", json!({"path": "notes.txt"}))
.unwrap()
.value["id"]
.as_u64()
.unwrap();
edit(&mut engine, txt, 1, 0, 0, "x");
let all = engine
.execute("diagnostics.list", Value::Null)
.unwrap()
.value;
assert_eq!(all["files"].as_array().unwrap().len(), 1, "{all}");
engine
.execute("buffer.close", json!({"id": id, "force": true}))
.unwrap();
pump_until(&mut engine, |e| {
e["kind"] == "diagnosticsChanged" && e["path"] == "a.php" && e["items"] == json!([])
});
let all = engine
.execute("diagnostics.list", Value::Null)
.unwrap()
.value;
assert_eq!(all, json!({"files": []}));
}
#[test]
fn reload_from_disk_resends_the_whole_text() {
let (dir, mut engine) = project(
&[("a.php", "<?php\n")],
launch(&["--sync-full"], ServerOptions::default()),
);
engine
.execute("file.open", json!({"path": "a.php"}))
.unwrap();
wait_for_text(&mut engine, "a.php", "<?php\n");
fs::write(dir.path().join("a.php"), "<?php\n// changed on disk\n").unwrap();
wait_for_text(&mut engine, "a.php", "<?php\n// changed on disk\n");
}
/// `test.probe {path}`: submits a closure that reports the server's copy
/// of `path`, the way M3.4/M3.5 commands send requests.
struct Probe(Mutex<Option<mpsc::Sender<Option<String>>>>);
impl Command for Probe {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "test.probe",
label: "Probe",
menu_path: None,
default_shortcut: None,
params: "path",
}
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let root = state.project.as_ref().unwrap().project.root().to_path_buf();
let path = root.join(params.as_str().unwrap());
let tx = self.0.lock().unwrap().take().unwrap();
let queued = lutra_engine::lsp::submit(state, move |server| {
let _ = tx.send(server.document_text(&path));
});
assert!(queued);
Ok(Outcome::default())
}
}
#[test]
fn requests_never_overtake_edits() {
let (_dir, mut engine) = project(
&[("a.php", "<?php\n")],
launch(&[], ServerOptions::default()),
);
let id = engine
.execute("file.open", json!({"path": "a.php"}))
.unwrap()
.value["id"]
.as_u64()
.unwrap();
engine.pump_vfs().unwrap();
let mut version = 1;
for i in 0..50 {
version = edit(&mut engine, id, version, 0, 0, &format!("{i},"));
}
let expected = text(&mut engine, id);
let (tx, rx) = mpsc::channel();
engine
.register(Box::new(Probe(Mutex::new(Some(tx)))))
.unwrap();
engine.execute("test.probe", json!("a.php")).unwrap();
let seen = rx.recv_timeout(Duration::from_secs(20)).unwrap();
assert_eq!(seen.as_deref(), Some(expected.as_str()));
}
#[test]
fn project_close_stops_the_server_and_clears_diagnostics() {
let (_dir, mut engine) = project(
&[("a.php", "<?php\n")],
launch(&[], ServerOptions::default()),
);
engine
.execute("file.open", json!({"path": "a.php"}))
.unwrap();
wait_for_text(&mut engine, "a.php", "<?php\n");
let out = engine
.execute("project.close", json!({"force": true}))
.unwrap();
let mut seen: Vec<Value> = out
.events
.iter()
.map(|e| serde_json::to_value(e).unwrap())
.collect();
seen.extend(pump_until(&mut engine, |e| status_is(e, "stopped")));
assert!(
seen.iter()
.any(|e| e["kind"] == "diagnosticsChanged" && e["items"] == json!([])),
"{seen:#?}"
);
let all = engine
.execute("diagnostics.list", Value::Null)
.unwrap()
.value;
assert_eq!(all, json!({"files": []}));
assert_eq!(
engine.execute("lsp.status", Value::Null).unwrap().value["state"],
"stopped"
);
}
#[test]
fn quit_stops_the_server_and_keeps_it_stopped() {
let (_dir, mut engine) = project(
&[(
"a.php", "<?php
",
)],
launch(&[], ServerOptions::default()),
);
engine
.execute("file.open", json!({"path": "a.php"}))
.unwrap();
wait_for_text(
&mut engine,
"a.php",
"<?php
",
);
let started = Instant::now();
let out = engine.execute("app.quit", json!({})).unwrap();
assert!(started.elapsed() < Duration::from_secs(5));
let events: Vec<Value> = out
.events
.iter()
.map(|e| serde_json::to_value(e).unwrap())
.collect();
assert!(
events.iter().any(|e| status_is(e, "stopped")),
"{events:#?}"
);
for _ in 0..10 {
let events = engine.pump_vfs().unwrap();
assert!(
!events.iter().any(|e| matches!(e, Event::LspStatus(_))),
"{events:?}"
);
}
assert!(engine.state().lsp.server().is_none());
}
#[test]
fn restart_starts_a_fresh_server() {
let (_dir, mut engine) = project(
&[("a.php", "<?php\n")],
launch(&[], ServerOptions::default()),
);
pump_until(&mut engine, |e| status_is(e, "ready"));
let out = engine.execute("lsp.restart", Value::Null).unwrap();
let mut seen: Vec<Value> = out
.events
.iter()
.map(|e| serde_json::to_value(e).unwrap())
.collect();
seen.extend(pump_until(&mut engine, |e| status_is(e, "ready")));
let states: Vec<&str> = seen
.iter()
.filter(|e| e["kind"] == "lspStatus")
.map(|e| e["state"].as_str().unwrap())
.collect();
assert_eq!(states, ["stopped", "starting", "ready"], "{seen:#?}");
}
#[test]
fn a_missing_server_fails_with_a_notification() {
let dir = tempfile::tempdir().unwrap();
let mut engine = Engine::new().unwrap();
engine.set_language_server(Some(Launch {
command: dir.path().join("no-such-server").into(),
args: Vec::new(),
options: ServerOptions::default(),
tick: None,
}));
engine
.execute("project.open", json!({"path": dir.path()}))
.unwrap();
let seen = pump_until(&mut engine, |e| status_is(e, "failed"));
let failed = seen.iter().find(|e| status_is(e, "failed")).unwrap();
assert!(
failed["message"]
.as_str()
.unwrap()
.contains("no-such-server"),
"{failed}"
);
let note = seen.iter().find(|e| e["kind"] == "notification").unwrap();
assert_eq!(note["messageKey"], "notification.lsp.failed");
assert_eq!(note["level"], "error");
}
#[test]
fn a_crashing_server_restarts_then_gives_up() {
let options = ServerOptions {
restart: RestartPolicy {
first_delay: Duration::from_millis(10),
max_delay: Duration::from_millis(20),
max_crashes: 2,
window: Duration::from_secs(60),
},
..ServerOptions::default()
};
let (_dir, mut engine) = project(
&[("a.php", "<?php\n")],
launch(&["--exit-immediately"], options),
);
let seen = pump_until(&mut engine, |e| status_is(e, "failed"));
assert!(seen.iter().any(|e| status_is(e, "restarting")), "{seen:#?}");
assert_eq!(
engine.execute("lsp.status", Value::Null).unwrap().value["state"],
"failed"
);
}
#[test]
fn no_server_without_a_project_or_toolchain() {
let mut engine = Engine::new().unwrap();
engine.set_language_server(Some(launch(&[], ServerOptions::default())));
assert!(engine.pump_vfs().unwrap().is_empty());
let dir = tempfile::tempdir().unwrap();
let mut engine = Engine::new().unwrap();
engine
.execute("project.open", json!({"path": dir.path()}))
.unwrap();
for _ in 0..5 {
let events = engine.pump_vfs().unwrap();
assert!(
!events.iter().any(|e| matches!(e, Event::LspStatus(_))),
"{events:?}"
);
}
assert_eq!(
engine.execute("lsp.status", Value::Null).unwrap().value,
json!({"state": "stopped"})
);
let err = engine
.execute("diagnostics.list", json!({"bogus": 1}))
.unwrap_err();
assert_eq!(err.code(), "invalid_params");
}
proptest! {
#![proptest_config(ProptestConfig { cases: 12, ..ProptestConfig::default() })]
/// Any sequence of edits, incremental or full sync, ends with the
/// server's copy equal to the buffer.
#[test]
fn random_edits_stay_in_sync(
full in any::<bool>(),
edits in prop::collection::vec((0usize..64, 0usize..8, "[a-zé\u{1F9A6}\n\r ]{0,6}"), 1..25),
) {
let args: &[&str] = if full { &["--sync-full"] } else { &[] };
let (_dir, mut engine) = project(&[("a.php", "<?php\n$x = 'ä';\n")], launch(args, ServerOptions::default()));
let id = engine
.execute("file.open", json!({"path": "a.php"}))
.unwrap()
.value["id"]
.as_u64()
.unwrap();
let mut version = 1;
for (at, len, insert) in edits {
let current = text(&mut engine, id);
let units: Vec<usize> = std::iter::once(0)
.chain(current.char_indices().map(|(i, c)| current[..i].encode_utf16().count() + c.len_utf16()))
.collect();
let from = units[at % units.len()];
let to = units[(at + len).min(units.len() - 1)].max(from);
let result = engine.execute(
"buffer.edit",
json!({"id": id, "baseVersion": version, "edits": [{"from": from, "to": to, "insert": insert}]}),
);
if let Ok(out) = result {
version = out.value["version"].as_u64().unwrap();
}
if at % 5 == 0 {
engine.pump_vfs().unwrap();
}
}
let expected = text(&mut engine, id);
wait_for_text(&mut engine, "a.php", &expected);
}
}
/// The real Phpactor (ignored; needs PHP and a PHAR): a file with two
/// errors gets its diagnostics after `file.open`, and an edit that adds a
/// third gets them again. Prints the startup and diagnostics latencies.
///
/// `LUTRA_PHPACTOR=<phar> [LUTRA_PHP=php] cargo test -p lutra-engine --test lsp real_phpactor -- --ignored --nocapture`
#[test]
#[ignore = "needs PHP and Phpactor (LUTRA_PHPACTOR)"]
fn real_phpactor_reports_diagnostics() {
let phar = std::env::var("LUTRA_PHPACTOR").expect("LUTRA_PHPACTOR");
let php = std::env::var("LUTRA_PHP").unwrap_or_else(|_| "php".into());
let text = "<?php\n\nnamespace App;\n\nfinal class Greeter\n{\n public function greet(): string\n {\n return 'hi';\n }\n}\n\n$g = new Greeter();\n$g->wave();\n";
let launch = lutra_engine::lsp::phpactor_launch(&php, &phar, cfg!(windows));
let (_dir, mut engine) = project(&[("Broken.php", text)], launch);
let started = Instant::now();
let seen = pump_until(&mut engine, |e| {
status_is(e, "ready") || status_is(e, "failed")
});
println!("ready after {:?}: {:?}", started.elapsed(), seen.last());
let id = engine
.execute("file.open", json!({"path": "Broken.php"}))
.unwrap()
.value["id"]
.as_u64()
.unwrap();
let opened = Instant::now();
let has = |e: &Value, word: &str| {
e["kind"] == "diagnosticsChanged"
&& e["items"].as_array().is_some_and(|items| {
items
.iter()
.any(|i| i["message"].as_str().unwrap_or("").contains(word))
})
};
let deadline = Instant::now() + Duration::from_secs(120);
let mut found = false;
while Instant::now() < deadline && !found {
for event in engine.pump_vfs().unwrap() {
let value = serde_json::to_value(&event).unwrap();
if value["kind"] != "notification" {
println!("{:?} {value}", opened.elapsed());
}
found |= has(&value, "wave");
}
std::thread::sleep(Duration::from_millis(20));
}
assert!(found, "no diagnostics for wave() within 120 s");
println!("first diagnostics after {:?}", opened.elapsed());
let end = text.encode_utf16().count();
edit(&mut engine, id, 1, end, end, "$g->dance();\n");
let edited = Instant::now();
let deadline = Instant::now() + Duration::from_secs(60);
let mut found = false;
while Instant::now() < deadline && !found {
for event in engine.pump_vfs().unwrap() {
found |= has(&serde_json::to_value(&event).unwrap(), "dance");
}
std::thread::sleep(Duration::from_millis(20));
}
assert!(found, "no diagnostics for dance() within 60 s");
println!("diagnostics after edit {:?}", edited.elapsed());
}