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

View file

@ -49,6 +49,7 @@ impl Command for Quit {
fn run(&self, state: &mut State, _params: Value) -> Result<Outcome, EngineError> {
crate::cmd::terminal::close_all(state);
crate::lsp::shutdown_now(state);
Ok(Outcome::effect(Effect::Quit))
}
}

View file

@ -167,6 +167,7 @@ impl Command for Edit {
let (version, dirty) = (open.version, open.dirty());
let now = std::time::Instant::now();
journal::mark_edited(state, p.id, now);
crate::lsp::record_edits(state, p.id, p.base_version, &edits);
super::syntax::record_edits(state, p.id, p.base_version, edits, now);
state.emit(Event::BufferChanged { id: p.id, version });
if dirty != was_dirty {

View file

@ -0,0 +1,110 @@
//! Language server commands of M3.3: `diagnostics.list`, `lsp.status` and
//! `lsp.restart`. The wiring itself lives in [`crate::lsp`].
use serde::Deserialize;
use serde_json::{Value, json};
use super::params::{parse, project_path};
use crate::workspace::path_string;
use crate::{Command, CommandSpec, EngineError, Outcome, Registry, State};
/// 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(List))?;
registry.register(Box::new(Status))?;
registry.register(Box::new(Restart))?;
Ok(())
}
/// Params of `diagnostics.list`.
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct ListParams {
/// Only this file (project-relative or absolute inside the project).
#[serde(default)]
path: Option<String>,
}
/// `diagnostics.list`: the language server's current diagnostics.
pub struct List;
impl Command for List {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "diagnostics.list",
label: "List Diagnostics",
menu_path: None,
default_shortcut: None,
params: "{ path?: string }; returns { files: [{ path, items: [{ range: { start: { line, column }, end }, severity: error|warning|info|hint, message, source?, code? }] }] } sorted by path, only files with diagnostics; columns are UTF-16; empty without a project or language server",
}
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: ListParams = parse(command, params)?;
let path = match p.path {
Some(path) if state.has_project() => {
Some(path_string(&project_path(state, command, &path)?))
}
Some(_) => return Ok(Outcome::value(json!({ "files": [] }))),
None => None,
};
let files = state.lsp.diagnostics(path.as_deref());
let files =
serde_json::to_value(files).map_err(|e| EngineError::Internal(e.to_string()))?;
Ok(Outcome::value(json!({ "files": files })))
}
}
/// `lsp.status`: the language server's state, as `lspStatus` last reported
/// it.
pub struct Status;
impl Command for Status {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "lsp.status",
label: "Language Server Status",
menu_path: None,
default_shortcut: None,
params: "none; returns { state: starting|ready|restarting|failed|stopped, message?, startupMs? } (startupMs: from start to the first ready)",
}
}
fn run(&self, state: &mut State, _params: Value) -> Result<Outcome, EngineError> {
let mut value = serde_json::to_value(state.lsp.status())
.map_err(|e| EngineError::Internal(e.to_string()))?;
if let (Some(ms), Some(object)) = (state.lsp.startup_ms(), value.as_object_mut()) {
object.insert("startupMs".into(), Value::from(ms));
}
Ok(Outcome::value(value))
}
}
/// `lsp.restart`: stops the language server; the next pump starts a fresh
/// one when the project and toolchain allow it.
pub struct Restart;
impl Command for Restart {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "lsp.restart",
label: "Restart PHP Language Server",
menu_path: Some("Tools/Restart PHP Language Server"),
default_shortcut: None,
params: "none; returns null; lspStatus reports stopped, then starting and ready",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, _params: Value) -> Result<Outcome, EngineError> {
crate::lsp::restart(state);
Ok(Outcome::value(Value::Null))
}
}

View file

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

View file

@ -151,6 +151,7 @@ impl Engine {
cmd::syntax::pump(state, std::time::Instant::now());
cmd::toolchain::pump(state);
cmd::terminal::pump(state);
crate::lsp::pump(state);
Ok(())
})?;
Ok(state.take_events())
@ -241,6 +242,14 @@ impl Engine {
self.state.toolchain.allow_downloads(source);
}
/// Makes the engine run `launch` as the project's language server
/// instead of Phpactor from the toolchain; `None` goes back to the
/// toolchain. For tests (the fake server) and hosts with their own
/// server. See [`crate::lsp`].
pub fn set_language_server(&mut self, launch: Option<crate::lsp::Launch>) {
self.state.lsp.set_launch(launch);
}
/// Read access to the state.
pub fn state(&self) -> &State {
&self.state
@ -392,6 +401,7 @@ mod tests {
"buffer.edit",
"buffer.get",
"buffer.list",
"diagnostics.list",
"file.open",
"file.save",
"file.saveAll",
@ -399,6 +409,8 @@ mod tests {
"goto.file",
"goto.symbol",
"index.status",
"lsp.restart",
"lsp.status",
"project.children",
"project.close",
"project.open",

View file

@ -197,6 +197,12 @@ pub enum Event {
/// PHP or Phpactor changed: `{php, phpactor}` as `toolchain.status`
/// returns it.
ToolchainChanged(crate::cmd::toolchain::ToolchainStatus),
/// The language server's state changed: `{state, message?}` with state
/// `starting`, `ready`, `restarting`, `failed` or `stopped`.
LspStatus(crate::lsp::LspStatus),
/// The diagnostics of one file changed: `{path, items}`; empty items
/// mean the file has none any more. Fetch all with `diagnostics.list`.
DiagnosticsChanged(crate::lsp::FileDiagnostics),
/// Terminal events (`terminalOutput`, `terminalExited`), see [`crate::cmd::terminal`].
#[serde(untagged)]
Terminal(crate::cmd::terminal::TerminalEvent),
@ -382,4 +388,40 @@ mod tests {
json!({"kind": "outlineChanged", "id": 4})
);
}
#[test]
fn lsp_shapes() {
use crate::lsp::{
DiagnosticItem, DiagnosticSeverity, FileDiagnostics, LineRange, LspState, LspStatus,
};
let e = Event::LspStatus(LspStatus {
state: LspState::Restarting,
message: Some("exit code 7".into()),
});
assert_eq!(
serde_json::to_value(e).unwrap(),
json!({"kind": "lspStatus", "state": "restarting", "message": "exit code 7"})
);
let range = LineRange {
start: lutra_text::Position::new(1, 2).into(),
end: lutra_text::Position::new(1, 5).into(),
};
let e = Event::DiagnosticsChanged(FileDiagnostics {
path: "src/a.php".into(),
items: vec![DiagnosticItem {
range,
severity: DiagnosticSeverity::Info,
message: "unused".into(),
source: None,
code: Some("X1".into()),
}],
});
assert_eq!(
serde_json::to_value(e).unwrap(),
json!({"kind": "diagnosticsChanged", "path": "src/a.php", "items": [{
"range": {"start": {"line": 1, "column": 2}, "end": {"line": 1, "column": 5}},
"severity": "info", "message": "unused", "code": "X1"
}]})
);
}
}

View file

@ -13,6 +13,7 @@ mod error;
mod event;
pub mod guard;
pub mod journal;
pub mod lsp;
mod registry;
pub mod settings;
mod state;

View file

@ -0,0 +1,868 @@
//! Engine ↔ language server wiring (M3.3): one Phpactor per open project,
//! document sync of PHP buffers, `lspStatus` and diagnostics.
//!
//! Lifecycle, all decided in [`pump`] (called by
//! [`crate::Engine::pump_vfs`]):
//! - A session starts when a project is open and the toolchain reports a
//! usable PHP and a ready Phpactor (`toolchain.status`), or at once when
//! the host set its own server ([`Lsp::set_launch`], tests and the fake
//! server). The server runs `php <phar> language-server` in the project
//! root.
//! - It stops when the project closes, when the PHP or Phpactor path
//! changes (a new session starts with the new ones), on `lsp.restart`,
//! and when the engine is dropped. The stop happens on the session thread
//! ([`session`]), never under the engine lock.
//!
//! Document sync: [`record_edits`] (called by `buffer.edit`) queues the
//! edit batch as a `didChange`; the pump opens newly opened PHP buffers,
//! closes closed ones, sends `didSave` when a buffer's saved version moves
//! and resends the whole text when the version moved without a recorded
//! edit (a reload from disk, a restore) or a `didChange` no longer fit.
//! Under the lock that is a cheap rope clone and a channel send; the text
//! is built on the session thread.
//!
//! The pump drains the server's events: status changes become `lspStatus`
//! (`starting`, `ready`, `restarting`, `failed`, `stopped`), published
//! diagnostics of project files become `diagnosticsChanged` and are kept
//! for `diagnostics.list`. Diagnostics are dropped when the session ends or
//! the server gives up, so stale ones never stay on screen.
//!
//! Requests (completion, hover, definition, … in M3.4/M3.5) go through
//! [`submit`], on the same queue as document sync, so they never overtake
//! an edit.
pub mod session;
use std::collections::BTreeMap;
use std::ffi::OsString;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::mpsc::Receiver;
use std::time::{Duration, Instant};
use lutra_lsp::{PublishDiagnostics, Server, ServerEvent, Severity, Status};
use lutra_text::{Edit, Position};
use serde::Serialize;
use serde_json::{Map, Value};
pub use lutra_lsp::{RestartPolicy, ServerOptions};
pub use session::Launch;
use session::{Job, Report, Session};
use crate::buffers::BufferId;
use crate::cmd::toolchain::PhpactorState;
use crate::workspace::path_string;
use crate::{Event, NotificationLevel, State};
/// Most server events handled per pump; the rest wait for the next one,
/// so a chatty server cannot hold the engine lock.
pub const MAX_EVENTS_PER_PUMP: usize = 2_000;
/// Most files with diagnostics kept; publications for further files are
/// ignored until others clear.
pub const MAX_FILES: usize = 10_000;
/// The state of the language server as `lspStatus` and `lsp.status`
/// report it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum LspState {
/// The process runs and `initialize` is in flight.
Starting,
/// Initialized; diagnostics and requests work.
Ready,
/// The server crashed and is restarted after a delay.
Restarting,
/// The server could not be started or crashed too often.
Failed,
/// No server runs (no project, toolchain not ready, or shut down).
Stopped,
}
/// The payload of `lspStatus`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct LspStatus {
/// The state.
pub state: LspState,
/// Why it is restarting or failed.
#[serde(skip_serializing_if = "Option::is_none")]
pub message: Option<String>,
}
impl LspStatus {
/// No server.
fn stopped() -> Self {
Self {
state: LspState::Stopped,
message: None,
}
}
}
/// How severe a diagnostic is, as the UI shows it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum DiagnosticSeverity {
/// An error (also when the server gave no severity).
Error,
/// A warning.
Warning,
/// Information.
Info,
/// A hint.
Hint,
}
impl From<Option<Severity>> for DiagnosticSeverity {
fn from(severity: Option<Severity>) -> Self {
match severity {
Some(Severity::Warning) => Self::Warning,
Some(Severity::Information) => Self::Info,
Some(Severity::Hint) => Self::Hint,
Some(Severity::Error) | None => Self::Error,
}
}
}
/// A position with a UTF-16 column, as everywhere in Lutra's protocol.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct LinePosition {
/// 0-based line.
pub line: usize,
/// 0-based column in UTF-16 code units.
pub column: usize,
}
impl From<Position> for LinePosition {
fn from(p: Position) -> Self {
Self {
line: p.line,
column: p.column,
}
}
}
/// A range between two positions, end exclusive.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct LineRange {
/// Start.
pub start: LinePosition,
/// End.
pub end: LinePosition,
}
/// One diagnostic of a file.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct DiagnosticItem {
/// Where it applies.
pub range: LineRange,
/// How severe it is.
pub severity: DiagnosticSeverity,
/// The message (at most 8 KiB).
pub message: String,
/// Who produced it (`phpactor`, `php-lint`, …).
#[serde(skip_serializing_if = "Option::is_none")]
pub source: Option<String>,
/// The diagnostic code.
#[serde(skip_serializing_if = "Option::is_none")]
pub code: Option<String>,
}
/// The payload of `diagnosticsChanged`, and one file of
/// `diagnostics.list`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct FileDiagnostics {
/// Project-relative path with `/`.
pub path: String,
/// The diagnostics, in the server's order; empty when they cleared.
pub items: Vec<DiagnosticItem>,
}
/// The language server part of the engine state.
#[derive(Default)]
pub struct Lsp {
/// A server the host chose instead of Phpactor from the toolchain.
launch: Option<Launch>,
/// The running session.
active: Option<Active>,
/// Status as last reported.
status: Option<LspStatus>,
/// Diagnostics by project-relative path; files without any are absent.
diagnostics: BTreeMap<String, Vec<DiagnosticItem>>,
/// Set by [`shutdown_now`] (`app.quit`): no session starts any more.
quitting: bool,
}
impl std::fmt::Debug for Lsp {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Lsp")
.field("launch", &self.launch)
.field("running", &self.active.is_some())
.field("status", &self.status)
.field("files_with_diagnostics", &self.diagnostics.len())
.finish()
}
}
impl Lsp {
/// Makes sessions start `launch` instead of Phpactor from the toolchain
/// (`None` goes back to the toolchain). A running session is replaced
/// at the next pump.
pub fn set_launch(&mut self, launch: Option<Launch>) {
self.launch = launch;
}
/// The status as last reported; stopped without a session.
pub fn status(&self) -> LspStatus {
self.status.clone().unwrap_or_else(LspStatus::stopped)
}
/// Milliseconds from the start of the session to the server's first
/// `ready`, once it was reached.
pub fn startup_ms(&self) -> Option<u64> {
self.active.as_ref().and_then(|a| a.ready_ms)
}
/// The diagnostics of one file (project-relative, `/`), or of every
/// file, sorted by path.
pub fn diagnostics(&self, path: Option<&str>) -> Vec<FileDiagnostics> {
self.diagnostics
.iter()
.filter(|(p, _)| path.is_none_or(|want| want == p.as_str()))
.map(|(p, items)| FileDiagnostics {
path: p.clone(),
items: items.clone(),
})
.collect()
}
/// The server of the running session, once its process started. For
/// reading its status and capabilities; send requests with [`submit`].
pub fn server(&self) -> Option<&Arc<Server>> {
self.active.as_ref().and_then(|a| a.server.as_ref())
}
}
/// What a session was started for; a change replaces the session.
#[derive(Debug, Clone, PartialEq)]
struct Key {
/// The project root.
root: PathBuf,
/// The server command line and options.
launch: Launch,
}
/// A PHP buffer as the server knows it.
#[derive(Debug, Clone)]
struct Doc {
/// Absolute path.
path: PathBuf,
/// The buffer version the server has (after the queued jobs).
version: u64,
/// The buffer's saved version last seen.
saved_version: u64,
/// The whole text must be resent.
stale: bool,
}
/// The running session and what the engine knows about it.
struct Active {
/// Why it runs.
key: Key,
/// The session thread.
session: Session,
/// The server, once started.
server: Option<Arc<Server>>,
/// Its events, once started.
events: Option<Receiver<ServerEvent>>,
/// When the session started.
started: Instant,
/// Milliseconds to the first `ready`.
ready_ms: Option<u64>,
/// Synced buffers.
docs: BTreeMap<BufferId, Doc>,
}
/// Queues `f` on the session thread, after every document change queued
/// so far. It runs with the server and must not block (use
/// [`Server::request_with`] or keep the [`lutra_lsp::RequestHandle`] and
/// poll it from the pump); without a running session it is dropped
/// unrun, which a caller notices through a dropped channel sender it
/// captured.
///
/// # Returns
/// Whether it was queued.
pub fn submit(state: &mut State, f: impl FnOnce(&Server) + Send + 'static) -> bool {
state
.lsp
.active
.as_ref()
.is_some_and(|a| a.session.send(Job::Run(Box::new(f))))
}
/// Records an edit batch `buffer.edit` applied to buffer `id` (moving it
/// from version `base` to `base + 1`) and queues it as a `didChange`. A
/// buffer the server does not have yet, or whose synced version is not
/// `base`, is resent whole by the next pump instead.
pub fn record_edits(state: &mut State, id: BufferId, base: u64, edits: &[Edit]) {
let Some(active) = state.lsp.active.as_mut() else {
return;
};
let Some(doc) = active.docs.get_mut(&id) else {
return;
};
if doc.stale || doc.version != base {
doc.stale = true;
return;
}
let job = Job::Change {
path: doc.path.clone(),
edits: edits.to_vec(),
};
if active.session.send(job) {
doc.version = base.saturating_add(1);
} else {
doc.stale = true;
}
}
/// Starts, replaces or stops the session, applies the session thread's
/// reports and the server's events, and syncs open PHP buffers. See the
/// module docs. Never blocks.
pub fn pump(state: &mut State) {
let wanted = wanted(state);
let current = state.lsp.active.as_ref().map(|a| a.key.clone());
if current != wanted {
if current.is_some() {
stop(state);
}
if let Some(key) = wanted {
start(state, key);
}
}
if state.lsp.active.is_none() {
return;
}
drain_reports(state);
drain_events(state);
sync_docs(state);
}
/// Stops the running session at the next pump and lets the pump start a
/// fresh one if the project and toolchain still allow it.
pub fn restart(state: &mut State) {
if state.lsp.active.is_some() {
stop(state);
}
}
/// Stops the language server now and waits for it (at most about 3 s), for
/// `app.quit`: the host exits right after, which would cut a background
/// shutdown short and leave the Phpactor process running. Clears the
/// diagnostics and reports `stopped`.
pub fn shutdown_now(state: &mut State) {
state.lsp.quitting = true;
let Some(active) = state.lsp.active.take() else {
return;
};
let Active {
session,
server,
events,
..
} = active;
drop(server);
drop(events);
session.join();
clear_diagnostics(state);
set_status(state, LspState::Stopped, None);
}
/// The session the state calls for: none without a project; the host's
/// server if it set one; otherwise Phpactor once the toolchain found PHP
/// and has the PHAR ready.
fn wanted(state: &State) -> Option<Key> {
if state.lsp.quitting {
return None;
}
let root = state.project.as_ref()?.project.root().to_path_buf();
if let Some(launch) = &state.lsp.launch {
return Some(Key {
root,
launch: launch.clone(),
});
}
let status = state.toolchain.status();
if !status.php.found || status.phpactor.state != PhpactorState::Ready {
return None;
}
let php = status.php.path.as_ref()?;
let phar = status.phpactor.path.as_ref()?;
Some(Key {
root,
launch: phpactor_launch(php, phar, cfg!(windows)),
})
}
/// How Lutra starts Phpactor: `php <phar> language-server`.
///
/// On Windows, Phpactor 2026.06.25.0 needs two adjustments (found in the
/// M3.3 live check, see `docs/architecture.md` › Engine wiring):
/// - Every subprocess it starts through amphp fails there with
/// `CreateProcess failed` (outsourced diagnostics, the PHP lint provider,
/// the `find` file watcher of the indexer). The `initializationOptions`
/// run diagnostics in the server process
/// (`language_server.diagnostic_outsource: false`) and let the indexer
/// poll in PHP (`indexer.enabled_watchers: ["php"]`). The PHP lint
/// provider still fails once and removes itself; its warning arrives as
/// `window/showMessage`, which Lutra does not show.
/// - Its event loop only runs when a message arrives on stdin, so timers
/// (the diagnostics debounce, the watcher) stall while the client is
/// quiet. The session thread sends [`TICK_METHOD`] every 25 ms while
/// busy; Phpactor's analysis advances one step per message, so the
/// interval sets the latency (edit to diagnostics with its 1 s debounce:
/// 5.9 s at 200 ms, 2.5 s at 50 ms, 1.5 s at 20 ms, measured). For the
/// same reason it rarely answers `shutdown` in time, so the shutdown
/// timeout is 500 ms instead of 2 s before the process is killed (quit
/// took 3 s otherwise).
///
/// Nothing is written into the user's project.
///
/// # Parameters
/// - `php`, `phar`: the executables from `toolchain.status`.
/// - `windows`: whether to apply the Windows adjustments.
pub fn phpactor_launch(php: &str, phar: &str, windows: bool) -> Launch {
let options = ServerOptions {
initialization_options: windows.then(|| {
serde_json::json!({
"language_server.diagnostic_outsource": false,
"indexer.enabled_watchers": ["php"],
})
}),
shutdown_timeout: if windows {
Duration::from_millis(500)
} else {
ServerOptions::default().shutdown_timeout
},
..ServerOptions::default()
};
Launch {
command: OsString::from(php),
args: vec![OsString::from(phar), OsString::from("language-server")],
options,
tick: windows.then_some(TICK_INTERVAL),
}
}
/// The no-op notification that keeps a server's event loop turning
/// ([`Launch::tick`]). Servers ignore `$/` notifications they do not know.
pub const TICK_METHOD: &str = "$/lutra/tick";
/// How often a busy session sends [`TICK_METHOD`] to Phpactor on Windows
/// (from its own thread, independent of the host's pump).
pub const TICK_INTERVAL: Duration = Duration::from_millis(25);
/// How long a session counts as busy after its last document change,
/// open, save or submitted request. Long enough for Phpactor's first
/// analysis of a project on a cold cache (16 s measured in M3.3).
pub const TICK_WINDOW: Duration = Duration::from_secs(60);
/// Whether a session with tick interval `interval` sends a tick at `now`.
///
/// # Parameters
/// - `ready`: whether the server is ready.
/// - `last_activity`: the last change, open, save or request, if any.
/// - `last_tick`: when the last tick was sent, if any.
pub fn tick_due(
interval: Option<Duration>,
ready: bool,
last_activity: Option<Instant>,
last_tick: Option<Instant>,
now: Instant,
) -> bool {
let Some(interval) = interval else {
return false;
};
let busy = last_activity.is_some_and(|t| now.saturating_duration_since(t) <= TICK_WINDOW);
let due = last_tick.is_none_or(|t| now.saturating_duration_since(t) >= interval);
ready && busy && due
}
/// Starts a session for `key` and reports `starting`, or `failed` if the
/// thread cannot be started.
fn start(state: &mut State, key: Key) {
match Session::start(key.launch.clone(), key.root.clone()) {
Ok(session) => {
state.lsp.active = Some(Active {
key,
session,
server: None,
events: None,
started: Instant::now(),
ready_ms: None,
docs: BTreeMap::new(),
});
set_status(state, LspState::Starting, None);
}
Err(message) => fail(state, message),
}
}
/// Drops the session (its thread shuts the server down), clears the
/// diagnostics and reports `stopped`.
fn stop(state: &mut State) {
state.lsp.active = None;
clear_diagnostics(state);
set_status(state, LspState::Stopped, None);
}
/// Reports `failed` with `message`, clears the diagnostics and tells the
/// user once.
fn fail(state: &mut State, message: String) {
clear_diagnostics(state);
let changed = set_status(state, LspState::Failed, Some(message.clone()));
if changed {
let mut params = Map::new();
params.insert("reason".into(), Value::from(message.clone()));
state.notify(
NotificationLevel::Error,
Some("notification.lsp.failed"),
Some(format!(
"The PHP language server stopped: {message}. Run \"Restart Language Server\" to try again."
)),
Some(params),
);
}
}
/// Stores the status and queues `lspStatus` if it changed.
///
/// # Returns
/// Whether it changed.
fn set_status(state: &mut State, lsp_state: LspState, message: Option<String>) -> bool {
let status = LspStatus {
state: lsp_state,
message,
};
if state.lsp.status.as_ref() == Some(&status) {
return false;
}
state.lsp.status = Some(status.clone());
state.emit(Event::LspStatus(status));
true
}
/// Applies the session thread's reports.
fn drain_reports(state: &mut State) {
let mut reports = Vec::new();
if let Some(active) = &state.lsp.active {
while let Ok(report) = active.session.reports.try_recv() {
reports.push(report);
}
}
for report in reports {
match report {
Report::Started { server, events } => {
if let Some(active) = state.lsp.active.as_mut() {
active.server = Some(server);
active.events = Some(events);
}
}
Report::SpawnFailed(message) => fail(state, message),
Report::Desync(path) => {
if let Some(active) = state.lsp.active.as_mut() {
for doc in active.docs.values_mut().filter(|d| d.path == path) {
doc.stale = true;
}
}
}
}
}
}
/// Handles up to [`MAX_EVENTS_PER_PUMP`] server events.
fn drain_events(state: &mut State) {
let mut events = Vec::new();
if let Some(receiver) = state.lsp.active.as_ref().and_then(|a| a.events.as_ref()) {
while events.len() < MAX_EVENTS_PER_PUMP {
let Ok(event) = receiver.try_recv() else {
break;
};
events.push(event);
}
}
for event in events {
match event {
ServerEvent::Status(status) => apply_status(state, status),
ServerEvent::Diagnostics(published) => publish(state, published),
_ => {}
}
}
}
/// Maps a client status onto `lspStatus`.
fn apply_status(state: &mut State, status: Status) {
match status {
Status::Starting => {
set_status(state, LspState::Starting, None);
}
Status::Ready => {
if let Some(active) = state.lsp.active.as_mut()
&& active.ready_ms.is_none()
{
active.ready_ms =
Some(u64::try_from(active.started.elapsed().as_millis()).unwrap_or(u64::MAX));
}
set_status(state, LspState::Ready, None);
}
Status::Restarting { reason, .. } => {
set_status(state, LspState::Restarting, Some(reason));
}
Status::Failed { message } => fail(state, message),
Status::Stopped => {
clear_diagnostics(state);
set_status(state, LspState::Stopped, None);
}
}
}
/// Stores the diagnostics of one file and queues `diagnosticsChanged`.
/// Files outside the project are ignored.
fn publish(state: &mut State, published: PublishDiagnostics) {
let Some(root) = state.lsp.active.as_ref().map(|a| a.key.root.clone()) else {
return;
};
let Some(relative) = published.path.as_deref().and_then(|p| relative(&root, p)) else {
return;
};
let path = path_string(&relative);
let items: Vec<DiagnosticItem> = published
.diagnostics
.into_iter()
.map(|d| DiagnosticItem {
range: LineRange {
start: d.range.start.into(),
end: d.range.end.into(),
},
severity: d.severity.into(),
message: d.message,
source: d.source,
code: d.code,
})
.collect();
let diagnostics = &mut state.lsp.diagnostics;
if items.is_empty() {
if diagnostics.remove(&path).is_none() {
return;
}
} else {
if diagnostics.get(&path) == Some(&items) {
return;
}
if !diagnostics.contains_key(&path) && diagnostics.len() >= MAX_FILES {
return;
}
diagnostics.insert(path.clone(), items.clone());
}
state.emit(Event::DiagnosticsChanged(FileDiagnostics { path, items }));
}
/// Drops every diagnostic, queuing an empty `diagnosticsChanged` per file
/// that had some.
fn clear_diagnostics(state: &mut State) {
let files = std::mem::take(&mut state.lsp.diagnostics);
for path in files.into_keys() {
state.emit(Event::DiagnosticsChanged(FileDiagnostics {
path,
items: Vec::new(),
}));
}
}
/// `path` relative to `root`; `None` outside it. Windows paths compare
/// without regard to case, as the file system does.
fn relative(root: &Path, path: &Path) -> Option<PathBuf> {
if let Ok(rel) = path.strip_prefix(root) {
return Some(rel.to_path_buf());
}
if !cfg!(windows) {
return None;
}
let root_text = root.to_str()?.trim_end_matches(['\\', '/']);
let text = path.to_str()?;
let head = text.get(..root_text.len())?;
let rest = text.get(root_text.len()..)?;
if !head.eq_ignore_ascii_case(root_text) || !rest.starts_with(['\\', '/']) {
return None;
}
Some(PathBuf::from(rest.trim_start_matches(['\\', '/'])))
}
/// Whether a project-relative path is synced as PHP.
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))
})
}
/// Opens new PHP buffers, closes closed ones, resends stale texts and
/// reports saves.
fn sync_docs(state: &mut State) {
let State { buffers, lsp, .. } = state;
let Some(active) = lsp.active.as_mut() else {
return;
};
let gone: Vec<BufferId> = active
.docs
.keys()
.copied()
.filter(|id| !buffers.get(*id).is_some_and(|b| is_php(&b.path)))
.collect();
for id in gone {
if let Some(doc) = active.docs.remove(&id) {
active.session.send(Job::Close { path: doc.path });
}
}
for id in buffers.ids() {
let Some(open) = buffers.get(id) else {
continue;
};
if !is_php(&open.path) {
continue;
}
let path = active.key.root.join(&open.path);
let Some(doc) = active.docs.get_mut(&id) else {
active.session.send(Job::Open {
path: path.clone(),
text: open.buffer.clone(),
});
active.docs.insert(
id,
Doc {
path,
version: open.version,
saved_version: open.saved_version,
stale: false,
},
);
continue;
};
if doc.path != path {
active.session.send(Job::Close {
path: std::mem::replace(&mut doc.path, path.clone()),
});
active.session.send(Job::Open {
path,
text: open.buffer.clone(),
});
doc.version = open.version;
doc.stale = false;
} else if doc.stale || doc.version != open.version {
active.session.send(Job::Full {
path: doc.path.clone(),
text: open.buffer.clone(),
});
doc.version = open.version;
doc.stale = false;
}
if doc.saved_version != open.saved_version {
doc.saved_version = open.saved_version;
if !open.dirty() {
active.session.send(Job::Save {
path: doc.path.clone(),
});
}
}
}
}
#[cfg(test)]
mod tests {
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
use super::{
DiagnosticSeverity, TICK_INTERVAL, TICK_WINDOW, phpactor_launch, relative, tick_due,
};
use lutra_lsp::Severity;
#[test]
fn severity_defaults_to_error() {
assert_eq!(DiagnosticSeverity::from(None), DiagnosticSeverity::Error);
assert_eq!(
DiagnosticSeverity::from(Some(Severity::Information)),
DiagnosticSeverity::Info
);
assert_eq!(
DiagnosticSeverity::from(Some(Severity::Hint)),
DiagnosticSeverity::Hint
);
}
#[test]
fn relative_paths_stay_inside_the_root() {
let root = if cfg!(windows) {
PathBuf::from(r"C:\work\demo")
} else {
PathBuf::from("/work/demo")
};
let inside = root.join("src").join("a.php");
assert_eq!(
relative(&root, &inside),
Some(Path::new("src").join("a.php"))
);
let sibling = if cfg!(windows) {
PathBuf::from(r"C:\work\demo2\a.php")
} else {
PathBuf::from("/work/demo2/a.php")
};
assert_eq!(relative(&root, &sibling), None);
if cfg!(windows) {
assert_eq!(
relative(&root, Path::new(r"c:\WORK\demo\b.php")),
Some(PathBuf::from("b.php"))
);
}
}
#[test]
fn phpactor_gets_the_windows_adjustments_only_there() {
let windows = phpactor_launch("php.exe", r"C: \phpactor.phar", true);
assert_eq!(windows.tick, Some(TICK_INTERVAL));
let options = windows.options.initialization_options.unwrap();
assert_eq!(options["language_server.diagnostic_outsource"], false);
assert_eq!(
options["indexer.enabled_watchers"],
serde_json::json!(["php"])
);
assert_eq!(windows.args.len(), 2);
let unix = phpactor_launch("php", "/t/phpactor.phar", false);
assert_eq!(unix.tick, None);
assert_eq!(unix.options.initialization_options, None);
assert_eq!(windows.options.shutdown_timeout, Duration::from_millis(500));
assert_eq!(unix.options.shutdown_timeout, Duration::from_secs(2));
}
#[test]
fn ticks_only_while_ready_and_busy() {
let now = Instant::now() + Duration::from_secs(3600);
let tick = Some(TICK_INTERVAL);
let recent = Some(now - Duration::from_secs(1));
assert!(tick_due(tick, true, recent, None, now));
assert!(!tick_due(None, true, recent, None, now));
assert!(!tick_due(tick, false, recent, None, now));
let quiet = Some(now - TICK_WINDOW - Duration::from_secs(1));
assert!(!tick_due(tick, true, quiet, None, now));
assert!(!tick_due(
tick,
true,
recent,
Some(now - TICK_INTERVAL / 2),
now
));
assert!(tick_due(tick, true, recent, Some(now - TICK_INTERVAL), now));
}
}

View file

@ -0,0 +1,247 @@
//! One language server session: the thread that owns the
//! [`lutra_lsp::Server`] of the open project.
//!
//! The engine lock only ever enqueues [`Job`]s. The session thread starts
//! the server (spawning a process can take tens of milliseconds on Windows
//! with a virus scanner), turns buffer snapshots into text, sends document
//! sync and runs the closures of [`super::submit`], strictly in the order
//! they were queued. A request queued after an edit therefore reaches the
//! server after that edit's `didChange`. What the thread learns goes back
//! to the next pump as a [`Report`].
use std::ffi::OsString;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::mpsc::{self, Receiver, RecvTimeoutError, Sender};
use std::time::{Duration, Instant};
use lutra_lsp::{LspError, Server, ServerEvent, ServerOptions, Status};
use lutra_text::{Buffer, Edit};
use serde_json::{Map, Value};
/// How a session starts its server.
#[derive(Debug, Clone, PartialEq)]
pub struct Launch {
/// The executable (PHP for Phpactor).
pub command: OsString,
/// Its arguments (the PHAR and `language-server` for Phpactor).
pub args: Vec<OsString>,
/// Client options (timeouts, restart policy, `initializationOptions`).
pub options: ServerOptions,
/// Send the no-op notification [`super::TICK_METHOD`] at this interval
/// while the session is busy (see [`super::TICK_WINDOW`]); `None` for
/// servers that need no nudge. Phpactor on Windows needs it, see
/// [`super::phpactor_launch`].
pub tick: Option<Duration>,
}
/// Work for the session thread, run in queue order.
pub enum Job {
/// Open a document with the text of a buffer snapshot.
Open {
/// Absolute path.
path: PathBuf,
/// The buffer at the version the engine recorded.
text: Buffer,
},
/// Apply the edits `buffer.edit` applied (byte ranges into the previous
/// text).
Change {
/// Absolute path.
path: PathBuf,
/// The edit batch.
edits: Vec<Edit>,
},
/// Replace the whole text (a reload from disk, a restore, a resync).
Full {
/// Absolute path.
path: PathBuf,
/// The buffer snapshot.
text: Buffer,
},
/// The buffer was saved.
Save {
/// Absolute path.
path: PathBuf,
},
/// The buffer was closed.
Close {
/// Absolute path.
path: PathBuf,
},
/// A closure from [`super::submit`]: requests of M3.4/M3.5.
Run(Box<dyn FnOnce(&Server) + Send>),
}
/// What the session thread reports to the pump.
pub enum Report {
/// The server process started; its events arrive on `events`.
Started {
/// The server, shared so the engine can read its status.
server: Arc<Server>,
/// Its event channel.
events: Receiver<ServerEvent>,
},
/// The server could not be started.
SpawnFailed(String),
/// A `didChange` did not fit the client's copy of the document; the
/// pump resends the whole text.
Desync(PathBuf),
}
/// The engine's handle on a running session thread.
pub struct Session {
/// Jobs to the thread. Dropping it ends the thread, which shuts the
/// server down.
jobs: Sender<Job>,
/// Reports from the thread.
pub reports: Receiver<Report>,
/// The thread, joined by [`Session::join`].
thread: Option<std::thread::JoinHandle<()>>,
}
impl Session {
/// Starts the session thread, which starts `launch` in `root`.
///
/// # Errors
/// The thread could not be started.
pub fn start(launch: Launch, root: PathBuf) -> Result<Self, String> {
let (jobs, queue) = mpsc::channel::<Job>();
let (reporter, reports) = mpsc::channel::<Report>();
let thread = std::thread::Builder::new()
.name("lsp-session".into())
.spawn(move || run(launch, &root, &queue, &reporter))
.map_err(|e| format!("cannot start the language server thread: {e}"))?;
Ok(Self {
jobs,
reports,
thread: Some(thread),
})
}
/// Queues a job.
///
/// # Returns
/// `false` when the thread is gone.
pub fn send(&self, job: Job) -> bool {
self.jobs.send(job).is_ok()
}
/// Ends the queue and waits until the thread has shut the server down
/// (`shutdown`, `exit`, kill if needed: at most about 3 s). For a host
/// that is about to exit, where a background shutdown would be cut
/// short and leave the server process running. The caller must have
/// dropped its own handles on the server first, or the thread cannot
/// take sole ownership and the server is only stopped in the
/// background. A thread that panicked is ignored: there is nothing
/// left to stop.
pub fn join(self) {
let Self {
jobs,
reports,
thread,
} = self;
drop(jobs);
drop(reports);
if let Some(thread) = thread {
let _ = thread.join();
}
}
}
/// The session thread: starts the server, works off the queue until the
/// engine drops its sender, then shuts the server down (`shutdown`, `exit`,
/// kill), here and never under the engine lock. Reports that cannot be
/// delivered are dropped because the engine has stopped listening.
fn run(launch: Launch, root: &Path, queue: &Receiver<Job>, reporter: &Sender<Report>) {
let Launch {
command,
args,
options,
tick,
} = launch;
let server = match Server::spawn(&command, &args, root, options) {
Ok((server, events)) => {
let server = Arc::new(server);
let _ = reporter.send(Report::Started {
server: Arc::clone(&server),
events,
});
server
}
Err(error) => {
let _ = reporter.send(Report::SpawnFailed(error.to_string()));
while queue.recv().is_ok() {}
return;
}
};
work(&server, tick, queue, reporter);
match Arc::try_unwrap(server) {
Ok(server) => server.shutdown(),
Err(shared) => drop(shared),
}
}
/// Works off the queue until the engine drops its sender. With a tick
/// interval, also sends [`super::TICK_METHOD`] whenever one is due
/// ([`super::tick_due`]): the thread wakes at least once per interval, so
/// ticks do not depend on how often the host pumps.
fn work(server: &Server, tick: Option<Duration>, queue: &Receiver<Job>, reporter: &Sender<Report>) {
let mut last_job = Instant::now();
let mut last_tick = None;
loop {
let next = match tick {
Some(interval) => queue.recv_timeout(interval),
None => queue.recv().map_err(|_| RecvTimeoutError::Disconnected),
};
match next {
Ok(job) => {
last_job = Instant::now();
handle(server, job, reporter);
}
Err(RecvTimeoutError::Timeout) => {}
Err(RecvTimeoutError::Disconnected) => return,
}
let now = Instant::now();
let ready = server.status() == Status::Ready;
if super::tick_due(tick, ready, Some(last_job), last_tick, now) {
last_tick = Some(now);
server.notify(super::TICK_METHOD, Value::Object(Map::new()));
}
}
}
/// Runs one job against the server. Sync failures are expected races
/// (a buffer closed twice, a document already open after a restart of the
/// session) and change nothing, except a `didChange` that no longer fits,
/// which asks the pump for a full resync.
fn handle(server: &Server, job: Job, reporter: &Sender<Report>) {
match job {
Job::Open { path, text } => {
let text = text.text();
if let Err(LspError::AlreadyOpen { .. }) = server.did_open(&path, "php", &text) {
let _ = server.did_change_full(&path, &text);
}
}
Job::Change { path, edits } => {
if let Err(LspError::Text(_) | LspError::NotOpen { .. }) =
server.did_change(&path, &edits)
{
let _ = reporter.send(Report::Desync(path));
}
}
Job::Full { path, text } => {
let text = text.text();
if let Err(LspError::NotOpen { .. }) = server.did_change_full(&path, &text) {
let _ = server.did_open(&path, "php", &text);
}
}
Job::Save { path } => {
let _ = server.did_save(&path);
}
Job::Close { path } => {
let _ = server.did_close(&path);
}
Job::Run(f) => f(server),
}
}

View file

@ -45,6 +45,8 @@ pub struct State {
pub toolchain: crate::cmd::toolchain::Toolchain,
/// Open integrated terminals (`terminal.*`).
pub terminals: crate::cmd::terminal::Terminals,
/// The language server session and its diagnostics (M3.3).
pub lsp: crate::lsp::Lsp,
/// Number of notifications emitted, for their ids.
notifications: u64,
/// Events queued for the host, oldest first.

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());
}