diff --git a/README.md b/README.md index ff2964f..985be7c 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ claude mcp add lutra -- lutra mcp ## Status -**Pre-alpha (2026-10-17): M2 done.** You can open a folder, browse it in the project tree with live updates from disk, and edit and save files in tabs with syntax highlighting for PHP (and HTML, CSS, JS/TS, JSON, YAML, Markdown), with every command in a palette (`Mod+Shift+P`) and settings and the light or dark theme in a settings dialog (`Mod+,`); unsaved text survives a crash and is offered back on the next open; M2 added find in files (`Mod+Alt+F`) and go to file, class or symbol (`Mod+P`, `Mod+Alt+C`, `Mod+T`); M3 has begun with an integrated terminal (`Mod+Shift+T`) and PHP language features from Phpactor: errors underlined as you type (Problems tab `Mod+Alt+P`), code completion, documentation on hover and parameter info; go to definition and rename come next. About 12 agent hours remain to the MVP (M3: language server, terminal, CLI and MCP). [**ROADMAP.md**](ROADMAP.md) has the stage and what's next, +**Pre-alpha (2026-10-17): M2 done.** You can open a folder, browse it in the project tree with live updates from disk, and edit and save files in tabs with syntax highlighting for PHP (and HTML, CSS, JS/TS, JSON, YAML, Markdown), with every command in a palette (`Mod+Shift+P`) and settings and the light or dark theme in a settings dialog (`Mod+,`); unsaved text survives a crash and is offered back on the next open; M2 added find in files (`Mod+Alt+F`) and go to file, class or symbol (`Mod+P`, `Mod+Alt+C`, `Mod+T`); M3 has begun with an integrated terminal (`Mod+Shift+T`) and PHP language features from Phpactor: errors underlined as you type (Problems tab `Mod+Alt+P`), code completion, documentation on hover and parameter info, go to definition (`F12` or Ctrl+click), find references (`Shift+F12`) and rename (`F2`). About 12 agent hours remain to the MVP (M3: language server, terminal, CLI and MCP). [**ROADMAP.md**](ROADMAP.md) has the stage and what's next, [`docs/target-app-parity.md`](docs/target-app-parity.md) the parity assessment and [`docs/gaps.md`](docs/gaps.md) the ranked work list. **First target (MVP, M1–M3):** open a project, project tree, tabs, editor with highlighting, find in files, diff --git a/ROADMAP.md b/ROADMAP.md index 36c5dc6..b3adbb5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,7 +2,7 @@ **Stage: pre-alpha (M2 done)** · next: M3 language server, terminal, CLI and MCP (the MVP); alpha when the six core workflows work end to end (see [docs/roadmap.md › Alpha gate](docs/roadmap.md#alpha-gate)) -> **Last reviewed:** 2026-10-15 · **Last updated:** 2026-10-22 · **Change:** minor (M3.4: completion, hover and signature help) · **Target:** JetBrains PhpStorm 2026.x, described from public documentation only +> **Last reviewed:** 2026-10-15 · **Last updated:** 2026-10-22 · **Change:** minor (M3.5: go to definition, find references, rename; after M3.4 completion) · **Target:** JetBrains PhpStorm 2026.x, described from public documentation only Lutra is a clean-room, open-source PHP IDE with a Rust core and a Tauri + Vue interface, targeting the PhpStorm workflow. Agents can drive all of it over MCP, the `lutra` CLI and a JSON control channel. This page is the summary; the evidence is in [`docs/target-app-parity.md`](docs/target-app-parity.md) and the work list in [`docs/gaps.md`](docs/gaps.md). @@ -12,8 +12,8 @@ Lutra is a clean-room, open-source PHP IDE with a Rust core and a Tauri + Vue in | | Value | Kind | |---|---|---| -| **Feature breadth** (PhpStorm's actions, tool windows, languages, integrations exist) | **~17%** (26 of 155 feature units of the public PhpStorm help have at least partial support; ~21% after the running cycle C4) | estimated | -| **Feature depth** (weighted by use, scored by behaviour) | **~4.6%** (Editor core 11% × weight 12, Navigation 10% × weight 10, Code completion 5% × weight 10, Inspections 4% × weight 8, Project view 8% × weight 6, Search and replace 8% × weight 6, Terminal 15% × weight 3, Settings 7% × weight 1, of 101) | estimated | +| **Feature breadth** (PhpStorm's actions, tool windows, languages, integrations exist) | **~18%** (28 of 155 feature units of the public PhpStorm help have at least partial support; ~21% after the running cycle C4) | estimated | +| **Feature depth** (weighted by use, scored by behaviour) | **~5.1%** (Editor core 11% × weight 12, Navigation 13% × weight 10, Code completion 5% × weight 10, Inspections 4% × weight 8, Refactoring 3% × weight 7, Project view 8% × weight 6, Search and replace 8% × weight 6, Terminal 15% × weight 3, Settings 7% × weight 1, of 101) | estimated | | **To MVP (M3)** | **~12 h left** (M3 = 80 h raw × 0.15; done so far: M1 ~5.6 h, M2 ~6.1 h, measured); was ~190 h before calibration | estimated (factor per cycle: C1 0.07, C2 0.10, C3 0.14) | | **To full parity** | **~450 h** at the current factor of ~0.15 (range 300–3,300 h; the factor has risen each cycle, and deep areas such as type inference and inspections have no data yet) | estimated | @@ -25,7 +25,7 @@ Dimension hours overlap: language, framework and tooling hours are part of the f | Dimension | % | One agent (h) | Doc | |---|---:|---:|---| -| Features (depth) | ~4.6% | ~2,872 | [target-app-parity.md](docs/target-app-parity.md) | +| Features (depth) | ~5.1% | ~2,860 | [target-app-parity.md](docs/target-app-parity.md) | | UI/UX fidelity | 1% (est.) | ~150 on top of features | [ui-parity.md](docs/ui-parity.md) | | PHP language support | 0% | ~920 (in features) | [language-parity.md](docs/language-parity.md) | | Frameworks (Symfony, Laravel, Shopware, WordPress) | 0% | ~300 (in features) | [framework-parity.md](docs/framework-parity.md) | @@ -43,11 +43,11 @@ Stability 8%: no-panic lints, the engine guard, a fuzzed control protocol and a |---|---:|---:| | Editor core (buffers, undo, multi-caret, folding, soft wrap) | 11% (est.) | ~100 | | Project view, VFS, file watching | 8% (est.) | ~40 | -| Navigation (go to class/file/symbol, recent files, structure) | 10% (est.) | ~102 | +| Navigation (go to class/file/symbol, recent files, structure) | 13% (est.) | ~96 | | Search and replace (in file, in project, structural) | 8% (est.) | ~70 | | Code completion | 5% (est.) | ~240 | | Inspections and quick-fixes | 4% (est.) | ~290 | -| Refactoring | 0% | ~250 | +| Refactoring | 3% (est.) | ~244 | | Code style and formatting | 0% | ~120 | | Version control (Git) | 0% | ~150 | | Terminal | 15% (est.) | ~26 | @@ -76,6 +76,7 @@ All hours estimated. Weights, evidence and the missing items per area: [target-a | Date | What landed | |---|---| | 2026-10-22 | M3.4: PHP code completes as you type. After `->`, `::`, `$` or a few letters Lutra shows Phpactor's suggestions with an icon per kind, and accepting one also adds its import. Resting the mouse on a class or method shows its documentation (`Mod+I` at the cursor), and typing `(` or `,` shows the parameters with the current one highlighted. A suggestion takes about 60–110 ms on Windows. | +| 2026-10-22 | M3.5: Jump to where a class or method is defined with F12 or Ctrl+click (a list when there are several), list every use of it with Shift+F12 in a References tab grouped by file, and rename it everywhere with F2: type the new name in a small field over the old one, which shows how many uses in how many files will change. Open files are changed but not saved, so Ctrl+Z takes it back; files that are not open are saved directly. | | 2026-10-21 | M3.3: PHP errors show up while you type. Lutra starts Phpactor for the open project. Problems such as calling a method that does not exist or using an unknown class get a wavy underline, a dot in the gutter and their message on hover, and `Mod+Alt+P` opens a Problems tab that lists them by file; click one to jump there. | | 2026-10-20 | M3.10: autosave. Changed files are saved when you leave the Lutra window, when you switch tabs and after 15 seconds without typing; each can be turned off in Settings › Editor. Files that were changed outside Lutra are left for you to decide. Later features such as deployment save everything first through the same step. | | 2026-10-19 | M3.8: agents can drive Lutra over MCP: `claude mcp add lutra -- lutra mcp`, then Claude can list and run every command, look at the window, read open files including unsaved changes and follow what happens. Closing Lutra needs an explicit confirmation. | @@ -101,6 +102,7 @@ All hours estimated. Weights, evidence and the missing items per area: [target-a | Date | Change | Summary | |---|---|---| | 2026-10-22 | minor | M3.4: Code completion 0% → 5% (est.), feature depth ~4.1% → ~4.6%, breadth 24 → 26 units | +| 2026-10-22 | minor | M3.5: Navigation 10% → 13% (est.), Refactoring 0% → 3% (est.), feature depth ~4.6% → ~5.1%, breadth 26 → 28 units | | 2026-10-21 | minor | M3.3: Inspections 0% → 4% (est.), feature depth ~3.8% → ~4.1%, breadth 23 → 24 units | | 2026-10-20 | minor | M3.6: Terminal 0% → 15%, feature depth ~3.3% → ~3.8% | | 2026-10-20 | minor | M3.10: autosave; Editor core 10% → 11% (est.), feature depth ~3.2% → ~3.3% | diff --git a/apps/lutra-desktop/src/main.rs b/apps/lutra-desktop/src/main.rs index 4b767a6..316b462 100644 --- a/apps/lutra-desktop/src/main.rs +++ b/apps/lutra-desktop/src/main.rs @@ -221,6 +221,7 @@ fn engine_execute_waiting( ) -> Result { host.run(&command, params).map_err(|e| e.payload()) } + /// IPC: lists the engine's commands for the frontend. #[tauri::command] fn engine_list_commands(host: tauri::State<'_, Arc>) -> Vec { diff --git a/crates/engine/src/cmd/lsp_nav.rs b/crates/engine/src/cmd/lsp_nav.rs new file mode 100644 index 0000000..36fe76e --- /dev/null +++ b/crates/engine/src/cmd/lsp_nav.rs @@ -0,0 +1,839 @@ +//! Navigation and refactoring through the language server (M3.5): +//! `lsp.definition`, `lsp.references`, `lsp.prepareRename` and +//! `lsp.rename`. +//! +//! Every command names an open buffer and a position in it (0-based line, +//! UTF-16 column). The request goes to the server through +//! [`crate::lsp::submit`], after every document change queued so far, so the +//! server answers for the text the user sees. The engine lock is never held +//! while the server works: the command returns a [`crate::Pending`] that the +//! host waits for without the lock, and the answer is turned into the result +//! under the lock again ([`crate::Engine::resolve`]). +//! +//! Results: +//! - Locations are project-relative; locations outside the project (PHP +//! stubs inside the Phpactor PHAR, files elsewhere on disk) are left out, +//! because Lutra only opens project files. +//! - `lsp.rename` applies the workspace edit as [`edit`] describes and +//! reports it with one summary notification. + +pub mod edit; + +use std::collections::BTreeMap; +use std::path::{Component, Path, PathBuf}; +use std::sync::mpsc; +use std::time::Duration; + +use lutra_lsp::{Location, LspError, Server, WorkspaceEdit}; +use lutra_text::{Buffer, Position}; +use serde::{Deserialize, Serialize}; +use serde_json::{Map, Value, json}; + +use super::params::parse; +use crate::buffers::BufferId; +use crate::lsp::{LinePosition, LineRange}; +use crate::workspace::path_string; +use crate::{ + Command, CommandSpec, EngineError, NotificationLevel, Outcome, Pending, Registry, State, +}; + +/// How long a navigation request may take before it fails with a timeout. +pub const REQUEST_TIMEOUT: Duration = Duration::from_secs(10); + +/// How long a rename may take: Phpactor searches the whole project. +pub const RENAME_TIMEOUT: Duration = Duration::from_secs(30); + +/// Most locations returned by `lsp.definition` and `lsp.references`. +pub const MAX_LOCATIONS: usize = 10_000; + +/// Longest new name `lsp.rename` accepts, in bytes. +pub const MAX_NAME_BYTES: usize = 1_024; + +/// 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(Definition))?; + registry.register(Box::new(References))?; + registry.register(Box::new(PrepareRename))?; + registry.register(Box::new(Rename))?; + Ok(()) +} + +/// A position in a buffer, as clients send it. +#[derive(Debug, Clone, Copy, Deserialize)] +#[serde(deny_unknown_fields)] +struct PositionParam { + /// 0-based line. + line: usize, + /// 0-based column in UTF-16 code units. + column: usize, +} + +/// Params of `lsp.definition` and `lsp.prepareRename`. +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct AtParams { + /// Buffer id. + id: BufferId, + /// Where the cursor is. + position: PositionParam, +} + +/// Params of `lsp.references`. +#[derive(Deserialize)] +#[serde(deny_unknown_fields, rename_all = "camelCase")] +struct ReferencesParams { + /// Buffer id. + id: BufferId, + /// Where the cursor is. + position: PositionParam, + /// Include the declaration itself (default true). + #[serde(default = "yes")] + include_declaration: bool, +} + +/// `true`, for serde defaults. +fn yes() -> bool { + true +} + +/// Params of `lsp.rename`. +#[derive(Deserialize)] +#[serde(deny_unknown_fields, rename_all = "camelCase")] +struct RenameParams { + /// Buffer id. + id: BufferId, + /// Where the symbol is. + position: PositionParam, + /// The new name. + new_name: String, +} + +/// A location in a project file. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct NavLocation { + /// Project-relative path with `/`. + pub path: String, + /// The range. + pub range: LineRange, +} + +/// What a request needs from the state: the server-side path of the buffer, +/// the checked position and the project root. +struct Target { + /// Absolute path of the buffer's file. + abs: PathBuf, + /// The position. + position: Position, + /// The project root. + root: PathBuf, +} + +/// Resolves buffer `id` and checks `position` against its text. +/// +/// # Errors +/// [`EngineError::Failed`] for an unknown buffer, a position outside the +/// text, or no running language server; [`EngineError::InvalidParams`] +/// never (the shape was parsed already). +fn target( + state: &State, + command: &str, + id: BufferId, + position: PositionParam, +) -> Result { + let open = state + .buffers + .get(id) + .ok_or_else(|| EngineError::Failed(format!("{command}: no buffer {id}")))?; + let position = Position { + line: position.line, + column: position.column, + }; + open.buffer + .position_to_offset(position, lutra_text::ColumnUnit::Utf16) + .map_err(|e| EngineError::invalid_params(command, e.to_string()))?; + let root = state + .project + .as_ref() + .ok_or_else(|| EngineError::Disabled(command.to_string()))? + .project + .root() + .to_path_buf(); + if state.lsp.server().is_none() { + return Err(EngineError::Failed( + "the PHP language server is not running".into(), + )); + } + Ok(Target { + abs: root.join(&open.path), + position, + root, + }) +} + +/// Sends a request built by `send` on the session thread, after every +/// queued document change, and returns a receiver for the answer. The +/// session's document sync runs first, so a buffer opened a moment ago is +/// known to the server. +/// +/// # Errors +/// [`EngineError::Failed`] when no session runs. +fn request( + state: &mut State, + method: &'static str, + params: Value, + timeout: Duration, +) -> Result>, EngineError> { + crate::lsp::pump(state); + let (tx, rx) = mpsc::channel(); + let queued = crate::lsp::submit(state, move |server: &Server| { + let reply = tx.clone(); + let sent = server.request_with( + method, + params, + timeout, + Box::new(move |result| { + let _ = reply.send(result); + }), + ); + if let Err(e) = sent { + let _ = tx.send(Err(e)); + } + }); + if !queued { + return Err(EngineError::Failed( + "the PHP language server is not running".into(), + )); + } + Ok(rx) +} + +/// `{textDocument: {uri}, position: {line, character}}` for `target`. +/// +/// # Errors +/// [`EngineError::Failed`] if the path has no `file:` URI. +fn document_position(target: &Target) -> Result, EngineError> { + let uri = lutra_lsp::uri::path_to_uri(&target.abs).map_err(|e| { + EngineError::Failed(format!("cannot address {}: {e}", target.abs.display())) + })?; + let mut params = Map::new(); + params.insert("textDocument".into(), json!({ "uri": uri })); + params.insert( + "position".into(), + json!({ "line": target.position.line, "character": target.position.column }), + ); + Ok(params) +} + +/// Turns a server failure into the command's error. +fn server_error(method: &str, error: LspError) -> EngineError { + match error { + LspError::Timeout { .. } => EngineError::Failed(format!( + "the PHP language server did not answer {method} in time" + )), + other => EngineError::Failed(format!("{method} failed: {other}")), + } +} + +/// The answer of a pending request, or the error it ended with. +/// +/// # Errors +/// [`EngineError::Failed`] for a server error, a timeout, or a session that +/// ended before answering. +fn answer(method: &str, answer: Option>) -> Result { + match answer { + Some(Ok(value)) => Ok(value), + Some(Err(e)) => Err(server_error(method, e)), + None => Err(EngineError::Failed(format!( + "the PHP language server stopped before answering {method}" + ))), + } +} + +/// Project-relative locations from a definition or references result, +/// without duplicates and capped at [`MAX_LOCATIONS`], in the server's +/// order. +pub fn locations(state: &State, root: &Path, value: &Value) -> Vec { + let mut seen = std::collections::BTreeSet::new(); + let mut out = Vec::new(); + for location in Location::list_from_json(value) { + let Some(rel) = location + .path + .as_deref() + .and_then(|p| project_relative(state, root, p)) + else { + continue; + }; + let item = NavLocation { + path: path_string(&rel), + range: LineRange { + start: LinePosition::from(location.range.start), + end: LinePosition::from(location.range.end), + }, + }; + let key = ( + item.path.clone(), + item.range.start.line, + item.range.start.column, + item.range.end.line, + item.range.end.column, + ); + if seen.insert(key) { + out.push(item); + } + if out.len() >= MAX_LOCATIONS { + break; + } + } + out +} + +/// `path` (absolute, from the server) relative to the project, or `None` +/// outside it. Windows paths compare without regard to case, as the file +/// system does, and `..` never escapes. A path that resolves through a +/// symbolic link to a place outside the project counts as outside. +pub fn project_relative(state: &State, root: &Path, path: &Path) -> Option { + let rel = match state + .project + .as_ref() + .and_then(|w| w.project.relative(path)) + { + Some(rel) => rel, + None => windows_relative(root, path)?, + }; + if rel.components().any(|c| !matches!(c, Component::Normal(_))) { + return None; + } + if let (Ok(real_root), Ok(real)) = ( + std::fs::canonicalize(root), + std::fs::canonicalize(root.join(&rel)), + ) && !real.starts_with(&real_root) + { + return None; + } + Some(rel) +} + +/// The case-insensitive fallback of [`project_relative`] on Windows. +fn windows_relative(root: &Path, path: &Path) -> Option { + 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(['\\', '/']))) +} + +/// `lsp.definition`: where the symbol at a position is declared. +pub struct Definition; + +impl Command for Definition { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "lsp.definition", + label: "Go to Definition", + menu_path: Some("Navigate/Go to Definition"), + default_shortcut: Some("F12"), + params: "{ id: buffer id, position: { line, column } (0-based, UTF-16 column) }; returns { locations: [{ path, range: { start: { line, column }, end } }] } (project files only; empty when the server knows no definition); fails when no language server runs", + } + } + + fn enabled(&self, state: &State) -> bool { + state.has_project() + } + + fn run(&self, state: &mut State, params: Value) -> Result { + let command = self.spec().id; + let p: AtParams = parse(command, params)?; + let target = target(state, command, p.id, p.position)?; + let params = Value::Object(document_position(&target)?); + let rx = request(state, "textDocument/definition", params, REQUEST_TIMEOUT)?; + let root = target.root; + Ok(Outcome::pending(Pending::new( + rx, + REQUEST_TIMEOUT, + move |state, reply| { + let value = answer("definition", reply)?; + let locations = locations(state, &root, &value); + Ok(json!({ "locations": locations })) + }, + ))) + } +} + +/// `lsp.references`: every use of the symbol at a position. +pub struct References; + +impl Command for References { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "lsp.references", + label: "Find References", + menu_path: Some("Navigate/Find References"), + default_shortcut: Some("Shift+F12"), + params: "{ id: buffer id, position: { line, column }, includeDeclaration?: bool (default true) }; returns { locations: [{ path, range, preview, previewColumn }] } sorted by path and position (project files only); preview is the trimmed line text, previewColumn the UTF-16 column of the range start in it", + } + } + + fn enabled(&self, state: &State) -> bool { + state.has_project() + } + + fn run(&self, state: &mut State, params: Value) -> Result { + let command = self.spec().id; + let p: ReferencesParams = parse(command, params)?; + let target = target(state, command, p.id, p.position)?; + let mut params = document_position(&target)?; + params.insert( + "context".into(), + json!({ "includeDeclaration": p.include_declaration }), + ); + let rx = request( + state, + "textDocument/references", + Value::Object(params), + REQUEST_TIMEOUT, + )?; + let root = target.root; + Ok(Outcome::pending(Pending::new( + rx, + REQUEST_TIMEOUT, + move |state, reply| { + let value = answer("references", reply)?; + let mut found = locations(state, &root, &value); + found.sort_by(|a, b| { + (&a.path, a.range.start.line, a.range.start.column).cmp(&( + &b.path, + b.range.start.line, + b.range.start.column, + )) + }); + let items = with_previews(state, &root, found); + Ok(json!({ "locations": items })) + }, + ))) + } +} + +/// Most characters of a line kept in a reference preview. +const PREVIEW_CHARS: usize = 200; + +/// Adds the line text to each location: from the open buffer if the file is +/// open, otherwise from disk (each file read once). A file that cannot be +/// read gets an empty preview. +fn with_previews(state: &State, root: &Path, found: Vec) -> Vec { + let mut texts: BTreeMap> = BTreeMap::new(); + found + .into_iter() + .map(|location| { + let buffer = texts.entry(location.path.clone()).or_insert_with(|| { + let rel = PathBuf::from(&location.path); + match state + .buffers + .find(&rel) + .and_then(|id| state.buffers.get(id)) + { + Some(open) => Some(open.buffer.clone()), + None => lutra_vfs::read_text(&root.join(&rel)) + .ok() + .map(|f| Buffer::new(&f.text)), + } + }); + let (preview, column) = buffer + .as_ref() + .map(|b| preview(b, location.range.start)) + .unwrap_or_default(); + json!({ + "path": location.path, + "range": location.range, + "preview": preview, + "previewColumn": column, + }) + }) + .collect() +} + +/// The text of `at`'s line without leading whitespace, cut to +/// [`PREVIEW_CHARS`], and `at`'s UTF-16 column in it. +fn preview(buffer: &Buffer, at: LinePosition) -> (String, usize) { + let Ok(line) = buffer.line_text(at.line) else { + return (String::new(), 0); + }; + let trimmed = line.trim_start(); + let cut = line.len().saturating_sub(trimmed.len()); + let removed: usize = line + .get(..cut) + .map(|s| s.encode_utf16().count()) + .unwrap_or(0); + let text: String = trimmed.trim_end().chars().take(PREVIEW_CHARS).collect(); + (text, at.column.saturating_sub(removed)) +} + +/// The answer of `lsp.prepareRename`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Renameable { + /// The range of the name that is renamed. + pub range: LineRange, + /// The current name, the suggested start of the new one. + pub placeholder: String, +} + +/// The name at `range` in `buffer`, for a server that answered with a +/// range only. +fn name_at(buffer: &Buffer, range: &lutra_lsp::Range) -> Option { + let (start, end) = edit::byte_range(buffer, range).ok()?; + buffer.slice(start..end).ok() +} + +/// The identifier around `at` in `buffer` (letters, digits, `_`, a leading +/// `$`, and non-ASCII characters as PHP allows), for servers without +/// `prepareRename`. `None` when the cursor is not on a name. +fn word_at(buffer: &Buffer, at: Position) -> Option { + let line = buffer.line_text(at.line).ok()?; + let units: Vec<(usize, char)> = line + .chars() + .scan(0usize, |cu, c| { + let start = *cu; + *cu += c.len_utf16(); + Some((start, c)) + }) + .collect(); + let is_name = |c: char| c.is_alphanumeric() || c == '_' || !c.is_ascii(); + let index = units + .iter() + .position(|(cu, c)| *cu + c.len_utf16() > at.column && is_name(*c)) + .filter(|&i| units.get(i).is_some_and(|(cu, _)| *cu <= at.column)) + .or_else(|| { + units + .iter() + .rposition(|(cu, c)| *cu + c.len_utf16() == at.column && is_name(*c)) + })?; + let mut first = index; + while first > 0 && units.get(first - 1).is_some_and(|(_, c)| is_name(*c)) { + first -= 1; + } + if first > 0 && units.get(first - 1).is_some_and(|(_, c)| *c == '$') { + first -= 1; + } + let mut last = index; + while units.get(last + 1).is_some_and(|(_, c)| is_name(*c)) { + last += 1; + } + let (start, _) = *units.get(first)?; + let (end_start, end_char) = *units.get(last)?; + let end = end_start + end_char.len_utf16(); + let placeholder: String = units.get(first..=last)?.iter().map(|(_, c)| *c).collect(); + if placeholder + .chars() + .next() + .is_some_and(|c| c.is_ascii_digit()) + { + return None; + } + Some(Renameable { + range: LineRange { + start: LinePosition { + line: at.line, + column: start, + }, + end: LinePosition { + line: at.line, + column: end, + }, + }, + placeholder, + }) +} + +/// Reads a `prepareRename` answer: a range, `{range, placeholder}`, or +/// `{defaultBehavior: true}` (then the word at the cursor); `null` means +/// the position cannot be renamed. +fn renameable(buffer: Option<&Buffer>, at: Position, value: &Value) -> Option { + if value.is_null() { + return None; + } + if value.get("defaultBehavior").and_then(Value::as_bool) == Some(true) { + return word_at(buffer?, at); + } + let range_value = value.get("range").unwrap_or(value); + let range = lutra_lsp::Range::from_json(range_value)?; + let placeholder = match value.get("placeholder").and_then(Value::as_str) { + Some(text) => text.to_string(), + None => name_at(buffer?, &range)?, + }; + Some(Renameable { + range: LineRange { + start: range.start.into(), + end: range.end.into(), + }, + placeholder, + }) +} + +/// `lsp.prepareRename`: whether the symbol at a position can be renamed, +/// and its current name. +pub struct PrepareRename; + +impl Command for PrepareRename { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "lsp.prepareRename", + label: "Prepare Rename", + menu_path: None, + default_shortcut: None, + params: "{ id: buffer id, position: { line, column } }; returns { range, placeholder } for a renameable symbol, or null when the position cannot be renamed; uses the word at the cursor when the server has no prepareRename", + } + } + + fn enabled(&self, state: &State) -> bool { + state.has_project() + } + + fn run(&self, state: &mut State, params: Value) -> Result { + let command = self.spec().id; + let p: AtParams = parse(command, params)?; + let target = target(state, command, p.id, p.position)?; + let supports_prepare = state + .lsp + .server() + .and_then(|s| s.capabilities()) + .is_some_and(|c| { + c.raw + .get("renameProvider") + .and_then(|r| r.get("prepareProvider")) + .and_then(Value::as_bool) + == Some(true) + }); + let id = p.id; + let at = target.position; + if !supports_prepare { + let found = state + .buffers + .get(id) + .and_then(|open| word_at(&open.buffer, at)); + return Ok(Outcome::value( + serde_json::to_value(found).map_err(|e| EngineError::Internal(e.to_string()))?, + )); + } + let params = Value::Object(document_position(&target)?); + let rx = request(state, "textDocument/prepareRename", params, REQUEST_TIMEOUT)?; + Ok(Outcome::pending(Pending::new( + rx, + REQUEST_TIMEOUT, + move |state, reply| { + let value = match reply { + Some(Err(LspError::Response { .. })) => Value::Null, + other => answer("prepareRename", other)?, + }; + let buffer = state.buffers.get(id).map(|o| &o.buffer); + let found = renameable(buffer, at, &value); + serde_json::to_value(found).map_err(|e| EngineError::Internal(e.to_string())) + }, + ))) + } +} + +/// Checks a new name: not empty, one line, at most [`MAX_NAME_BYTES`]. +/// +/// # Errors +/// [`EngineError::InvalidParams`] naming `command`. +fn check_name(command: &str, name: &str) -> Result<(), EngineError> { + if name.trim().is_empty() { + return Err(EngineError::invalid_params(command, "newName is empty")); + } + if name.contains(['\n', '\r']) { + return Err(EngineError::invalid_params( + command, + "newName must be one line", + )); + } + if name.len() > MAX_NAME_BYTES { + return Err(EngineError::invalid_params( + command, + format!("newName is longer than {MAX_NAME_BYTES} bytes"), + )); + } + Ok(()) +} + +/// `lsp.rename`: renames the symbol at a position everywhere in the +/// project. +pub struct Rename; + +impl Command for Rename { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "lsp.rename", + label: "Rename Symbol", + menu_path: Some("Refactor/Rename…"), + default_shortcut: Some("F2"), + params: "{ id: buffer id, position: { line, column }, newName }; applies the server's workspace edit: open buffers through buffer.edit (dirty, undoable in the editor), closed files written atomically; refused as a whole when a file is outside the project, an edit does not fit, a buffer changed meanwhile, or the server wants to create/rename/delete files; returns { files: [{ path, edits, bufferId?, version? }], edits, written } and notifies a summary", + } + } + + fn enabled(&self, state: &State) -> bool { + state.has_project() + } + + fn run(&self, state: &mut State, params: Value) -> Result { + let command = self.spec().id; + let p: RenameParams = parse(command, params)?; + check_name(command, &p.new_name)?; + let target = target(state, command, p.id, p.position)?; + let mut params = document_position(&target)?; + params.insert("newName".into(), Value::from(p.new_name.clone())); + let versions: BTreeMap = state + .buffers + .ids() + .into_iter() + .filter_map(|id| Some((id, state.buffers.get(id)?.version))) + .collect(); + let rx = request( + state, + "textDocument/rename", + Value::Object(params), + RENAME_TIMEOUT, + )?; + let root = target.root; + let new_name = p.new_name; + Ok(Outcome::pending(Pending::new( + rx, + RENAME_TIMEOUT, + move |state, reply| { + let value = answer("rename", reply)?; + if value.is_null() { + return Err(EngineError::Failed( + "the language server found nothing to rename here".into(), + )); + } + let edit = WorkspaceEdit::from_json(&value).ok_or_else(|| { + EngineError::Failed("the language server sent no valid edit".into()) + })?; + let mut applied = edit::apply(state, &root, &edit, &versions)?; + announce_written(state, std::mem::take(&mut applied.written_files)); + notify_summary(state, &new_name, &applied); + serde_json::to_value(&applied).map_err(|e| EngineError::Internal(e.to_string())) + }, + ))) + } +} + +/// Tells the language server that a rename wrote `files` on disk, so its +/// index follows at once: each file is opened with its new text and closed +/// again (`didOpen`, `didSave`, `didClose`), which makes Phpactor reindex it, and +/// `workspace/didChangeWatchedFiles` reports the change for servers that +/// watch through the client. Phpactor ignored the notification alone and +/// kept the old names until its own polling watcher noticed (live check: +/// a "method does not exist" error stayed on the renamed call, and renaming +/// back found one use instead of four). A file the user opened meanwhile is +/// skipped, because its buffer is synced already (`did_open` refuses it). +/// Without a ready session nothing is sent, so the results of `submit`, +/// `did_open`, `did_save`, `did_close` and `notify` are ignored: a session that starts +/// later indexes the files fresh. +fn announce_written(state: &mut State, files: Vec<(PathBuf, String)>) { + if files.is_empty() { + return; + } + let _ = crate::lsp::submit(state, move |server| { + let changes: Vec = files + .iter() + .filter_map(|(path, _)| lutra_lsp::uri::path_to_uri(path).ok()) + .map(|uri| json!({ "uri": uri, "type": 2 })) + .collect(); + for (path, text) in &files { + if server.did_open(path, "php", text).is_ok() { + let _ = server.did_save(path); + let _ = server.did_close(path); + } + } + let _ = server.notify( + "workspace/didChangeWatchedFiles", + json!({ "changes": changes }), + ); + }); +} + +/// Tells the user what a rename changed, in one notification. +fn notify_summary(state: &mut State, new_name: &str, applied: &edit::Applied) { + let mut params = Map::new(); + params.insert("name".into(), Value::from(new_name)); + params.insert("edits".into(), Value::from(applied.edits)); + params.insert("files".into(), Value::from(applied.files.len())); + params.insert("written".into(), Value::from(applied.written)); + state.notify( + NotificationLevel::Info, + Some("notification.lsp.renamed"), + Some(format!( + "Renamed to {new_name}: {} occurrences in {} files ({} closed files saved).", + applied.edits, + applied.files.len(), + applied.written + )), + Some(params), + ); +} + +#[cfg(test)] +mod tests { + use super::*; + + fn at(line: usize, column: usize) -> Position { + Position { line, column } + } + + #[test] + fn finds_the_word_at_the_cursor() { + let buffer = Buffer::new("run();\r\n"); + let (text, column) = preview(&buffer, LinePosition { line: 1, column: 8 }); + assert_eq!(text, "$a->run();"); + assert_eq!(column, 4); + } + + #[test] + fn names_are_checked() { + assert!(check_name("x", "ok").is_ok()); + assert!(check_name("x", " ").is_err()); + assert!(check_name("x", "a\nb").is_err()); + assert!(check_name("x", &"a".repeat(MAX_NAME_BYTES + 1)).is_err()); + } +} diff --git a/crates/engine/src/cmd/lsp_nav/edit.rs b/crates/engine/src/cmd/lsp_nav/edit.rs new file mode 100644 index 0000000..ef0e882 --- /dev/null +++ b/crates/engine/src/cmd/lsp_nav/edit.rs @@ -0,0 +1,322 @@ +//! Applying a language server's workspace edit (`lsp.rename`). +//! +//! The edit is checked completely before anything changes: +//! - It must be complete (no skipped edits) and contain text edits only (no +//! file creation, renaming or deletion). +//! - Every document must lie inside the project; one outside refuses the +//! whole edit. +//! - Every edit must apply: ranges are converted with the text crate +//! (UTF-16 columns, CRLF counted as one line break) and tried on a copy. +//! - Open buffers must still be at the version they had when the request was +//! sent; a buffer the user changed meanwhile refuses the edit (the ranges +//! would be stale). +//! +//! Then closed files are written, each atomically through the VFS. If a +//! write fails, the files written so far are restored to their old content +//! (best effort; a failed restore is reported in the error) and no buffer +//! is touched. Only after every file is written are the open buffers changed, +//! through `buffer.edit` (one batch per buffer, so they become dirty and the +//! editor can undo it), which cannot fail any more after the checks. +//! "All or nothing" therefore holds except for a crash or a failed restore +//! between two file writes. + +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; + +use lutra_lsp::{Range, WorkspaceEdit}; +use lutra_text::{Buffer, ColumnUnit, Edit}; +use serde::Serialize; +use serde_json::json; + +use crate::buffers::BufferId; +use crate::workspace::{path_string, vfs_error}; +use crate::{Command, EngineError, State}; + +/// Most documents one workspace edit may change. +pub const MAX_FILES: usize = 5_000; + +/// What happened to one file of an applied edit. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct FileChange { + /// Project-relative path with `/`. + pub path: String, + /// Number of text edits applied. + pub edits: usize, + /// The open buffer that was changed; `None` for a file written on disk. + #[serde(skip_serializing_if = "Option::is_none")] + pub buffer_id: Option, + /// The buffer's version after the edit. + #[serde(skip_serializing_if = "Option::is_none")] + pub version: Option, +} + +/// The summary of an applied workspace edit. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct Applied { + /// Changed files, sorted by path. + pub files: Vec, + /// Text edits over all files. + pub edits: usize, + /// Files written on disk (not open). + pub written: usize, + /// The files written on disk, absolute path and new text, for telling + /// the language server. + #[serde(skip)] + pub written_files: Vec<(PathBuf, String)>, +} + +/// One document of the edit, checked and ready to apply. +enum Planned { + /// An open buffer: `buffer.edit` with UTF-16 offsets at `base`. + Buffer { + /// The buffer. + id: BufferId, + /// Its current version. + base: u64, + /// `(from, to, insert)` in UTF-16 code units of the current text. + edits: Vec<(usize, usize, String)>, + }, + /// A closed file: its old and new contents. + Disk { + /// Absolute path. + abs: PathBuf, + /// The text before the edit, for a restore. + old: String, + /// The text after the edit. + new: String, + /// Whether the file has a byte order mark. + bom: bool, + }, +} + +/// Applies `edit` to the project. See the module docs. +/// +/// # Parameters +/// - `root`: the project root the server was started in (absolute). +/// - `versions`: the versions of the open buffers when the request was +/// sent, by id. +/// +/// # Errors +/// [`EngineError::Failed`] with the reason when the edit is refused or a +/// file cannot be written; nothing (or, after a failed restore, only what +/// the message lists) has changed then. +pub fn apply( + state: &mut State, + root: &Path, + edit: &WorkspaceEdit, + versions: &BTreeMap, +) -> Result { + let plan = plan(state, root, edit, versions)?; + let mut applied = Applied::default(); + let mut written: Vec<(PathBuf, &str, bool)> = Vec::new(); + for (rel, planned, count) in &plan { + if let Planned::Disk { abs, old, new, bom } = planned { + if let Err(e) = lutra_vfs::write_text(abs, new, *bom) { + let failed = restore(&written); + let mut message = format!("cannot write {}: {}", path_string(rel), vfs_error(e)); + if !failed.is_empty() { + message.push_str(&format!( + "; these files keep the new text because restoring them failed too: {}", + failed.join(", ") + )); + } + return Err(EngineError::Failed(message)); + } + written.push((abs.clone(), old.as_str(), *bom)); + applied.written_files.push((abs.clone(), new.clone())); + applied.written = applied.written.saturating_add(1); + applied.files.push(FileChange { + path: path_string(rel), + edits: *count, + buffer_id: None, + version: None, + }); + applied.edits = applied.edits.saturating_add(*count); + } + } + for (rel, planned, count) in plan { + if let Planned::Buffer { id, base, edits } = planned { + let changes: Vec<_> = edits + .into_iter() + .map(|(from, to, insert)| json!({"from": from, "to": to, "insert": insert})) + .collect(); + let out = super::super::buffer::Edit.run( + state, + json!({"id": id, "baseVersion": base, "edits": changes}), + )?; + applied.files.push(FileChange { + path: path_string(&rel), + edits: count, + buffer_id: Some(id), + version: out.value.get("version").and_then(|v| v.as_u64()), + }); + applied.edits = applied.edits.saturating_add(count); + } + } + applied.files.sort_by(|a, b| a.path.cmp(&b.path)); + Ok(applied) +} + +/// Writes the old contents back into files written by a failed edit. +/// +/// # Returns +/// The paths whose restore failed too. +fn restore(written: &[(PathBuf, &str, bool)]) -> Vec { + written + .iter() + .filter(|(abs, old, bom)| lutra_vfs::write_text(abs, old, *bom).is_err()) + .map(|(abs, _, _)| abs.display().to_string()) + .collect() +} + +/// Checks the whole edit and computes every change without applying any. +/// +/// # Returns +/// The documents with their project-relative path, change and edit count. +/// +/// # Errors +/// [`EngineError::Failed`] naming the first problem. +fn plan( + state: &State, + root: &Path, + edit: &WorkspaceEdit, + versions: &BTreeMap, +) -> Result, EngineError> { + if edit.incomplete { + return Err(EngineError::Failed( + "the language server sent an incomplete or malformed edit; nothing was changed".into(), + )); + } + if edit.has_resource_operations { + return Err(EngineError::Failed( + "the edit creates, renames or deletes files, which Lutra does not support yet; nothing was changed".into(), + )); + } + let mut documents: BTreeMap> = BTreeMap::new(); + for document in &edit.documents { + let rel = document + .path + .as_deref() + .and_then(|p| super::project_relative(state, root, p)) + .ok_or_else(|| { + EngineError::Failed(format!( + "the edit changes {}, which is outside the project; nothing was changed", + document.uri + )) + })?; + documents + .entry(rel) + .or_default() + .extend(document.edits.iter()); + } + if documents.len() > MAX_FILES { + return Err(EngineError::Failed(format!( + "the edit changes {} files, more than the {MAX_FILES} Lutra applies at once; nothing was changed", + documents.len() + ))); + } + let mut plan = Vec::with_capacity(documents.len()); + for (rel, edits) in documents { + if edits.is_empty() { + continue; + } + let shown = path_string(&rel); + let count = edits.len(); + let planned = match state.buffers.find(&rel) { + Some(id) => { + let open = state + .buffers + .get(id) + .ok_or_else(|| EngineError::Internal(format!("buffer {id} vanished")))?; + let expected = versions.get(&id).copied(); + if expected.is_some_and(|v| v != open.version) + || (expected.is_none() && open.dirty()) + { + return Err(EngineError::Failed(format!( + "{shown} changed while the language server computed the edit; nothing was changed, try again" + ))); + } + let byte_edits = byte_edits(&open.buffer, &edits, &shown)?; + let mut probe = open.buffer.clone(); + probe.apply(&byte_edits).map_err(|e| bad_edit(&shown, &e))?; + let mut utf16 = Vec::with_capacity(byte_edits.len()); + for e in byte_edits { + let from = open + .buffer + .offset_to_utf16(e.range.start) + .map_err(|err| bad_edit(&shown, &err))?; + let to = open + .buffer + .offset_to_utf16(e.range.end) + .map_err(|err| bad_edit(&shown, &err))?; + utf16.push((from, to, e.text)); + } + Planned::Buffer { + id, + base: open.version, + edits: utf16, + } + } + None => { + let abs = super::super::params::absolute(state, "lsp.rename", &rel)?; + let file = lutra_vfs::read_text(&abs).map_err(|e| { + EngineError::Failed(format!( + "cannot read {shown}: {}; nothing was changed", + vfs_error(e) + )) + })?; + let mut buffer = Buffer::new(&file.text); + let byte_edits = byte_edits(&buffer, &edits, &shown)?; + buffer + .apply(&byte_edits) + .map_err(|e| bad_edit(&shown, &e))?; + Planned::Disk { + abs, + new: buffer.text(), + old: file.text, + bom: file.bom, + } + } + }; + plan.push((rel, planned, count)); + } + Ok(plan) +} + +/// Converts LSP text edits (line, UTF-16 column) into byte edits of +/// `buffer`. +/// +/// # Errors +/// [`EngineError::Failed`] for a range that does not fit the text. +fn byte_edits( + buffer: &Buffer, + edits: &[&lutra_lsp::TextEdit], + shown: &str, +) -> Result, EngineError> { + edits + .iter() + .map(|e| { + let (start, end) = byte_range(buffer, &e.range).map_err(|err| bad_edit(shown, &err))?; + Ok(Edit::replace(start..end, e.new_text.clone())) + }) + .collect() +} + +/// The byte range of an LSP range in `buffer`. +/// +/// # Errors +/// The text crate's error for a position that does not exist. +pub fn byte_range(buffer: &Buffer, range: &Range) -> Result<(usize, usize), lutra_text::TextError> { + let start = buffer.position_to_offset(range.start, ColumnUnit::Utf16)?; + let end = buffer.position_to_offset(range.end, ColumnUnit::Utf16)?; + Ok((start, end)) +} + +/// The error for an edit that does not fit `shown`'s text. +fn bad_edit(shown: &str, error: &lutra_text::TextError) -> EngineError { + EngineError::Failed(format!( + "the edit does not fit {shown} ({error}); nothing was changed" + )) +} diff --git a/crates/engine/src/cmd/mod.rs b/crates/engine/src/cmd/mod.rs index 59bd663..0e987f7 100644 --- a/crates/engine/src/cmd/mod.rs +++ b/crates/engine/src/cmd/mod.rs @@ -6,6 +6,7 @@ mod file; pub mod goto; mod lsp_assist; mod lsp_diagnostics; +mod lsp_nav; mod params; mod project; mod recovery; @@ -62,5 +63,6 @@ pub fn register_builtins(registry: &mut Registry) -> Result<(), EngineError> { registry.register(Box::new(terminal::Close))?; lsp_diagnostics::register(registry)?; lsp_assist::register(registry)?; + lsp_nav::register(registry)?; Ok(()) } diff --git a/crates/engine/src/engine.rs b/crates/engine/src/engine.rs index 68e8f87..2ce330a 100644 --- a/crates/engine/src/engine.rs +++ b/crates/engine/src/engine.rs @@ -468,7 +468,11 @@ mod tests { "goto.symbol", "index.status", "lsp.completion", + "lsp.definition", "lsp.hover", + "lsp.prepareRename", + "lsp.references", + "lsp.rename", "lsp.restart", "lsp.signatureHelp", "lsp.status", diff --git a/crates/engine/tests/lsp_nav.rs b/crates/engine/tests/lsp_nav.rs new file mode 100644 index 0000000..5a498a5 --- /dev/null +++ b/crates/engine/tests/lsp_nav.rs @@ -0,0 +1,575 @@ +//! Navigation and rename (M3.5) against `lutra-lsp-fake` with scripted +//! answers (`--script`): definition, references, prepareRename and the +//! workspace edit of a rename (open buffers, closed files, CRLF ranges, +//! edits outside the project, stale buffers). + +#![allow( + clippy::unwrap_used, + clippy::expect_used, + clippy::panic, + clippy::indexing_slicing +)] + +use std::ffi::OsString; +use std::fs; +use std::path::{Path, PathBuf}; +use std::time::{Duration, Instant}; + +use lutra_engine::lsp::Launch; +use lutra_engine::{Engine, EngineError, Outcome}; +use lutra_lsp::ServerOptions; +use lutra_lsp::uri::path_to_uri; +use serde_json::{Value, json}; +use tempfile::TempDir; + +/// The fake server binary, built on demand (see `tests/lsp.rs`). +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 project with `files` and an engine running the fake server with the +/// script `script(root)` (a JSON object, see the fake server's docs). +struct Fixture { + /// The project. + dir: TempDir, + /// Holds the script file. + _scripts: TempDir, + /// The engine, with the server ready. + engine: Engine, +} + +impl Fixture { + fn new(files: &[(&str, &str)], script: impl Fn(&Path) -> Value) -> Self { + let dir = tempfile::tempdir().unwrap(); + for (name, text) in files { + let path = dir.path().join(name); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(path, text).unwrap(); + } + let scripts = tempfile::tempdir().unwrap(); + let script_path = scripts.path().join("script.json"); + fs::write(&script_path, script(dir.path()).to_string()).unwrap(); + let mut engine = Engine::new().unwrap(); + engine.set_language_server(Some(Launch { + command: fake_server().into(), + args: vec![OsString::from("--script"), script_path.into_os_string()], + options: ServerOptions::default(), + tick: None, + })); + engine + .execute("project.open", json!({"path": dir.path()})) + .unwrap(); + let mut fixture = Self { + dir, + _scripts: scripts, + engine, + }; + fixture.pump_until(|e| e["kind"] == "lspStatus" && e["state"] == "ready"); + fixture + } + + /// Pumps until `done` holds for an event. + fn pump_until(&mut self, done: impl Fn(&Value) -> bool) -> Vec { + let deadline = Instant::now() + Duration::from_secs(20); + let mut seen = Vec::new(); + while Instant::now() < deadline { + let mut hit = false; + for event in self.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:#?}"); + } + + /// Opens a file; returns its buffer id. + fn open(&mut self, path: &str) -> u64 { + self.engine + .execute("file.open", json!({"path": path})) + .unwrap() + .value["id"] + .as_u64() + .unwrap() + } + + /// Runs a command and waits for its pending answer, like a host. + fn run(&mut self, command: &str, params: Value) -> Result<(Value, Vec), EngineError> { + let mut out: Outcome = self.engine.execute(command, params)?; + let mut events: Vec = out + .events + .iter() + .map(|e| serde_json::to_value(e).unwrap()) + .collect(); + let Some(pending) = out.pending.take() else { + return Ok((out.value, events)); + }; + let resolved = self.engine.resolve(pending.wait())?; + events.extend( + resolved + .events + .iter() + .map(|e| serde_json::to_value(e).unwrap()), + ); + Ok((resolved.value, events)) + } + + /// The text of buffer `id`. + fn text(&mut self, id: u64) -> Value { + self.engine + .execute("buffer.get", json!({"id": id})) + .unwrap() + .value + } + + /// The absolute path of a project file. + fn path(&self, name: &str) -> PathBuf { + self.dir.path().join(name) + } +} + +/// The `file:` URI of `name` under `root`. +fn uri(root: &Path, name: &str) -> String { + path_to_uri(&root.join(name)).unwrap() +} + +/// An LSP range on one line. +fn range(line: u32, from: u32, to: u32) -> Value { + json!({"start": {"line": line, "character": from}, "end": {"line": line, "character": to}}) +} + +/// An LSP text edit on one line. +fn text_edit(line: u32, from: u32, to: u32, text: &str) -> Value { + json!({"range": range(line, from, to), "newText": text}) +} + +const A: &str = "hello();\n"; +const C: &str = "hello(); $y->hello();\r\n"; + +#[test] +fn definition_returns_project_locations() { + let mut f = Fixture::new(&[("a.php", A)], |_| json!({})); + let id = f.open("a.php"); + let (value, _) = f + .run( + "lsp.definition", + json!({"id": id, "position": {"line": 2, "column": 21}}), + ) + .unwrap(); + assert_eq!( + value, + json!({"locations": [{"path": "a.php", "range": {"start": {"line": 2, "column": 21}, "end": {"line": 2, "column": 21}}}]}) + ); +} + +#[test] +fn bad_positions_and_buffers_fail_fast() { + let mut f = Fixture::new(&[("a.php", A)], |_| json!({})); + let id = f.open("a.php"); + let err = f + .run( + "lsp.definition", + json!({"id": id, "position": {"line": 99, "column": 0}}), + ) + .unwrap_err(); + assert_eq!(err.code(), "invalid_params"); + let err = f + .run( + "lsp.definition", + json!({"id": 999, "position": {"line": 0, "column": 0}}), + ) + .unwrap_err(); + assert_eq!(err.code(), "failed"); +} + +#[test] +fn references_are_sorted_deduplicated_and_inside_the_project() { + let outside = tempfile::tempdir().unwrap(); + let outside_uri = path_to_uri(&outside.path().join("x.php")).unwrap(); + let mut f = Fixture::new(&[("a.php", A), ("sub/b.php", B)], |root| { + json!({"capabilities": {"referencesProvider": true}, "responses": { + "textDocument/references": [ + {"uri": uri(root, "sub/b.php"), "range": range(2, 4, 9)}, + {"uri": uri(root, "a.php"), "range": range(2, 20, 25)}, + {"uri": outside_uri, "range": range(0, 0, 1)}, + {"uri": uri(root, "a.php"), "range": range(2, 20, 25)}, + {"uri": "phar://stubs/Core.php", "range": range(0, 0, 1)} + ] + }}) + }); + let id = f.open("a.php"); + let (value, _) = f + .run( + "lsp.references", + json!({"id": id, "position": {"line": 2, "column": 22}}), + ) + .unwrap(); + let locations = value["locations"].as_array().unwrap(); + assert_eq!(locations.len(), 2, "{value}"); + assert_eq!(locations[0]["path"], "a.php"); + assert_eq!(locations[0]["preview"], "public function hello() {}"); + assert_eq!(locations[0]["previewColumn"], 16); + assert_eq!(locations[1]["path"], "sub/b.php"); + assert_eq!(locations[1]["preview"], "$g->hello();"); +} + +#[test] +fn prepare_rename_uses_the_server_or_the_word() { + let mut f = Fixture::new(&[("a.php", A)], |_| { + json!({"capabilities": {"renameProvider": {"prepareProvider": true}}, "responses": { + "textDocument/prepareRename": {"range": range(2, 20, 25), "placeholder": "hello"} + }}) + }); + let id = f.open("a.php"); + let (value, _) = f + .run( + "lsp.prepareRename", + json!({"id": id, "position": {"line": 2, "column": 22}}), + ) + .unwrap(); + assert_eq!(value["placeholder"], "hello"); + assert_eq!(value["range"]["start"]["column"], 20); + + let mut plain = Fixture::new(&[("a.php", A)], |_| json!({})); + let id = plain.open("a.php"); + let (value, _) = plain + .run( + "lsp.prepareRename", + json!({"id": id, "position": {"line": 1, "column": 8}}), + ) + .unwrap(); + assert_eq!(value["placeholder"], "Greeter"); + let (value, _) = plain + .run( + "lsp.prepareRename", + json!({"id": id, "position": {"line": 2, "column": 2}}), + ) + .unwrap(); + assert_eq!(value, Value::Null, "whitespace cannot be renamed"); +} + +/// The rename answer for `hello` → `greet` over a.php (open), sub/b.php and +/// c.php (closed, CRLF). +fn rename_script(root: &Path, extra: Option) -> Value { + let mut changes = json!({ + uri(root, "a.php"): [text_edit(2, 20, 25, "greet")], + uri(root, "sub/b.php"): [text_edit(2, 4, 9, "greet")], + uri(root, "c.php"): [text_edit(2, 4, 9, "greet"), text_edit(2, 17, 22, "greet")] + }); + if let Some(Value::Object(more)) = extra { + changes.as_object_mut().unwrap().extend(more); + } + json!({"capabilities": {"renameProvider": true}, "responses": { + "textDocument/rename": {"changes": changes} + }}) +} + +#[test] +fn rename_changes_open_buffers_and_closed_files() { + let mut f = Fixture::new(&[("a.php", A), ("sub/b.php", B), ("c.php", C)], |root| { + rename_script(root, None) + }); + let id = f.open("a.php"); + let (value, events) = f + .run( + "lsp.rename", + json!({"id": id, "position": {"line": 2, "column": 22}, "newName": "greet"}), + ) + .unwrap(); + assert_eq!(value["edits"], 4); + assert_eq!(value["written"], 2); + let files = value["files"].as_array().unwrap(); + let paths: Vec<_> = files.iter().map(|f| f["path"].as_str().unwrap()).collect(); + assert_eq!(paths, ["a.php", "c.php", "sub/b.php"]); + assert_eq!(files[0]["bufferId"], id); + assert_eq!(files[0]["version"], 2); + + let buffer = f.text(id); + assert_eq!( + buffer["text"], + "greet();\n" + ); + assert_eq!( + fs::read_to_string(f.path("c.php")).unwrap(), + "greet(); $y->greet();\r\n", + "CRLF line breaks are kept and the ranges counted per line" + ); + assert!( + events + .iter() + .any(|e| e["kind"] == "bufferChanged" && e["id"] == id), + "{events:?}" + ); + let note = events + .iter() + .find(|e| e["kind"] == "notification") + .expect("a summary notification"); + assert_eq!(note["messageKey"], "notification.lsp.renamed"); + assert_eq!(note["params"]["files"], 3); + assert_eq!(note["params"]["written"], 2); +} + +#[test] +fn rename_outside_the_project_changes_nothing() { + let outside = tempfile::tempdir().unwrap(); + fs::write(outside.path().join("lib.php"), B).unwrap(); + let lib = path_to_uri(&outside.path().join("lib.php")).unwrap(); + let mut f = Fixture::new(&[("a.php", A), ("sub/b.php", B), ("c.php", C)], |root| { + rename_script( + root, + Some(json!({ lib.clone(): [text_edit(2, 4, 9, "greet")] })), + ) + }); + let id = f.open("a.php"); + let err = f + .run( + "lsp.rename", + json!({"id": id, "position": {"line": 2, "column": 22}, "newName": "greet"}), + ) + .unwrap_err(); + assert!(err.to_string().contains("outside the project"), "{err}"); + assert_eq!(f.text(id)["text"], A); + assert_eq!(f.text(id)["dirty"], false); + assert_eq!(fs::read_to_string(f.path("sub/b.php")).unwrap(), B); + assert_eq!(fs::read_to_string(f.path("c.php")).unwrap(), C); + assert_eq!( + fs::read_to_string(outside.path().join("lib.php")).unwrap(), + B + ); +} + +#[test] +fn rename_with_a_bad_range_changes_nothing() { + let mut f = Fixture::new(&[("a.php", A), ("sub/b.php", B), ("c.php", C)], |root| { + rename_script( + root, + Some(json!({ uri(root, "c.php"): [text_edit(2, 4, 99, "greet")] })), + ) + }); + let id = f.open("a.php"); + let err = f + .run( + "lsp.rename", + json!({"id": id, "position": {"line": 2, "column": 22}, "newName": "greet"}), + ) + .unwrap_err(); + assert!(err.to_string().contains("c.php"), "{err}"); + assert_eq!(f.text(id)["text"], A); + assert_eq!(fs::read_to_string(f.path("sub/b.php")).unwrap(), B); +} + +#[test] +fn rename_refuses_a_buffer_edited_meanwhile() { + let mut f = Fixture::new(&[("a.php", A), ("sub/b.php", B), ("c.php", C)], |root| { + rename_script(root, None) + }); + let id = f.open("a.php"); + let mut out = f + .engine + .execute( + "lsp.rename", + json!({"id": id, "position": {"line": 2, "column": 22}, "newName": "greet"}), + ) + .unwrap(); + f.engine + .execute( + "buffer.edit", + json!({"id": id, "baseVersion": 1, "edits": [{"from": 0, "to": 0, "insert": "\n"}]}), + ) + .unwrap(); + let err = f + .engine + .resolve(out.pending.take().unwrap().wait()) + .unwrap_err(); + assert!(err.to_string().contains("changed while"), "{err}"); + assert_eq!(fs::read_to_string(f.path("sub/b.php")).unwrap(), B); +} + +#[test] +fn rename_rejects_bad_names() { + let mut f = Fixture::new(&[("a.php", A)], |root| rename_script(root, None)); + let id = f.open("a.php"); + for name in ["", "a\nb"] { + let err = f + .run( + "lsp.rename", + json!({"id": id, "position": {"line": 2, "column": 22}, "newName": name}), + ) + .unwrap_err(); + assert_eq!(err.code(), "invalid_params"); + } +} + +/// Against the real Phpactor (`LUTRA_PHPACTOR= [LUTRA_PHP=php] cargo +/// test -p lutra-engine --test lsp_nav real_phpactor -- --ignored +/// --nocapture`): definition across files, references, a method rename over +/// an open buffer and two closed files (one CRLF), and the rename back, +/// which finds every use only if Phpactor learned about the written files. +/// Prints the latencies. +#[test] +#[ignore = "needs a Phpactor PHAR in LUTRA_PHPACTOR"] +fn real_phpactor_navigates_and_renames_across_files() { + let phar = std::env::var("LUTRA_PHPACTOR").expect("LUTRA_PHPACTOR"); + let php = std::env::var("LUTRA_PHP").unwrap_or_else(|_| "php".into()); + let dir = tempfile::tempdir().unwrap(); + let src = dir.path().join("src"); + fs::create_dir_all(&src).unwrap(); + fs::write( + dir.path().join("composer.json"), + r#"{"autoload": {"psr-4": {"App\\": "src/"}}}"#, + ) + .unwrap(); + fs::write( + src.join("Greeter.php"), + "hello('Lutra');\n }\n}\n", + ) + .unwrap(); + fs::write( + src.join("Other.php"), + "hello(\"otter\") . $g->hello(\"sea otter\");\r\n}\r\n", + ) + .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 deadline = Instant::now() + Duration::from_secs(60); + while engine.state().lsp.status().state != lutra_engine::lsp::LspState::Ready { + assert!(Instant::now() < deadline, "Phpactor never got ready"); + engine.pump_vfs().unwrap(); + std::thread::sleep(Duration::from_millis(10)); + } + let id = engine + .execute("file.open", json!({"path": "src/App.php"})) + .unwrap() + .value["id"] + .as_u64() + .unwrap(); + let mut run = |command: &str, params: Value| { + let started = Instant::now(); + let mut out = engine.execute(command, params).unwrap(); + let value = match out.pending.take() { + Some(pending) => engine.resolve(pending.wait()).unwrap().value, + None => out.value, + }; + engine.pump_vfs().unwrap(); + println!("{command}: {:?}", started.elapsed()); + value + }; + let at_hello = json!({"line": 9, "column": 27}); + let indexing = Instant::now(); + loop { + let found = run( + "lsp.definition", + json!({"id": id, "position": {"line": 8, "column": 24}}), + ); + if found["locations"][0]["path"] == "src/Greeter.php" { + break; + } + assert!( + indexing.elapsed() < Duration::from_secs(60), + "no definition after 60 s: {found}" + ); + std::thread::sleep(Duration::from_millis(250)); + } + println!("first definition after {:?}", indexing.elapsed()); + let definition = run( + "lsp.definition", + json!({"id": id, "position": {"line": 8, "column": 24}}), + ); + assert_eq!(definition["locations"][0]["path"], "src/Greeter.php"); + let references = run("lsp.references", json!({"id": id, "position": at_hello})); + assert_eq!( + references["locations"].as_array().unwrap().len(), + 4, + "{references}" + ); + let prepared = run("lsp.prepareRename", json!({"id": id, "position": at_hello})); + assert_eq!(prepared["placeholder"], "hello"); + let renamed = run( + "lsp.rename", + json!({"id": id, "position": at_hello, "newName": "greet"}), + ); + assert_eq!(renamed["edits"], 4, "{renamed}"); + assert_eq!(renamed["written"], 2); + assert_eq!( + fs::read_to_string(src.join("Other.php")).unwrap(), + "greet(\"otter\") . $g->greet(\"sea otter\");\r\n}\r\n" + ); + let reindex = Instant::now(); + loop { + let found = run("lsp.references", json!({"id": id, "position": at_hello})); + if found["locations"].as_array().map_or(0, Vec::len) == 4 { + break; + } + assert!( + reindex.elapsed() < Duration::from_secs(30), + "Phpactor never saw the written files: {found}" + ); + std::thread::sleep(Duration::from_millis(100)); + } + println!("index followed the rename after {:?}", reindex.elapsed()); + let back = run( + "lsp.rename", + json!({"id": id, "position": at_hello, "newName": "hello"}), + ); + assert_eq!(back["edits"], 4, "Phpactor saw the written files: {back}"); +} + +#[test] +fn without_a_server_the_commands_fail() { + let dir = tempfile::tempdir().unwrap(); + fs::write(dir.path().join("a.php"), A).unwrap(); + let mut engine = Engine::new().unwrap(); + engine + .execute("project.open", json!({"path": dir.path()})) + .unwrap(); + let id = engine + .execute("file.open", json!({"path": "a.php"})) + .unwrap() + .value["id"] + .as_u64() + .unwrap(); + let err = engine + .execute( + "lsp.definition", + json!({"id": id, "position": {"line": 0, "column": 0}}), + ) + .unwrap_err(); + assert!(err.to_string().contains("not running"), "{err}"); +} diff --git a/crates/lsp/src/bin/lutra-lsp-fake.rs b/crates/lsp/src/bin/lutra-lsp-fake.rs index 641752a..ba5dd13 100644 --- a/crates/lsp/src/bin/lutra-lsp-fake.rs +++ b/crates/lsp/src/bin/lutra-lsp-fake.rs @@ -24,6 +24,10 @@ //! (then `RequestCancelled` and the notification `fake/cancelled`), //! `fake/crash` exits with code 7, `fake/garbage` writes malformed frames //! before answering. `shutdown` answers `null`; `exit` exits with 0. +//! - `--script FILE` reads a JSON object `{capabilities?, responses?}`: +//! `capabilities` are merged into the `initialize` answer, and +//! `responses` maps a request method to the result it gets, before the +//! built-in answers (M3.5: references, prepareRename, rename). use std::collections::HashMap; use std::io::{self, BufReader, Write}; @@ -48,6 +52,8 @@ struct Fake { full_sync: bool, /// Whether `initialize` fails. init_error: bool, + /// The `--script` file's content, `null` without one. + script: Value, } /// The fake answer to `textDocument/completion`: a `CompletionList` whose @@ -103,6 +109,7 @@ fn main() { responses: Vec::new(), full_sync: args.iter().any(|a| a == "--sync-full"), init_error: args.iter().any(|a| a == "--init-error"), + script: script(&args), }; let mut reader = BufReader::new(io::stdin().lock()); while let Ok(Some(frame)) = jsonrpc::read_frame(&mut reader, MAX_MESSAGE_BYTES) { @@ -115,6 +122,21 @@ fn main() { } } +/// The JSON in the file after `--script`, `null` without one; exits with 4 +/// when it cannot be read. +fn script(args: &[String]) -> Value { + let Some(at) = args.iter().position(|a| a == "--script") else { + return Value::Null; + }; + let Some(path) = args.get(at + 1) else { + exit(4); + }; + match std::fs::read_to_string(path).map(|text| serde_json::from_str(&text)) { + Ok(Ok(value)) => value, + _ => exit(4), + } +} + /// Writes one message to stdout; exits if stdout is gone. fn send(value: &Value) { let mut stdout = io::stdout().lock(); @@ -180,23 +202,34 @@ impl Fake { /// Answers a request. fn request(&mut self, id: Value, method: &str, params: &Value) { + if let Some(result) = self + .script + .pointer(&format!("/responses/{}", method.replace('/', "~1"))) + { + respond(id, Ok(result.clone())); + return; + } match method { "initialize" if self.init_error => respond(id, Err(error(-32002, "no init"))), "initialize" => { let change = if self.full_sync { 1 } else { 2 }; + let mut capabilities = json!({ + "positionEncoding": "utf-16", + "textDocumentSync": {"openClose": true, "change": change, "save": {"includeText": true}}, + "hoverProvider": true, + "definitionProvider": true, + "completionProvider": {"triggerCharacters": [">", ":", "$", "\\"]}, + "signatureHelpProvider": {"triggerCharacters": ["(", ","]} + }); + if let (Some(all), Some(extra)) = ( + capabilities.as_object_mut(), + self.script.get("capabilities").and_then(Value::as_object), + ) { + all.extend(extra.clone()); + } respond( id, - Ok(json!({ - "capabilities": { - "positionEncoding": "utf-16", - "textDocumentSync": {"openClose": true, "change": change, "save": {"includeText": true}}, - "hoverProvider": true, - "definitionProvider": true, - "completionProvider": {"triggerCharacters": [">", ":", "$", "\\"]}, - "signatureHelpProvider": {"triggerCharacters": ["(", ","]} - }, - "serverInfo": {"name": "fake"} - })), + Ok(json!({"capabilities": capabilities, "serverInfo": {"name": "fake"}})), ); } "shutdown" => respond(id, Ok(Value::Null)), diff --git a/docs/architecture.md b/docs/architecture.md index 8083e2c..adde674 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -462,6 +462,46 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat - Unit tests: kinds, lists, snippets, hover parts, signature spans, caps. - Vitest `ui/tests/editor/assist/`: triggers, the query, applying (text edits, typing since the request, imports, CRLF), the Markdown renderer (incl. an XSS set), hover, signature help and the UI commands. +### Definition, references, rename (M3.5) + +- **Commands** (`crates/engine/src/cmd/lsp_nav.rs`). All take `{id, position: {line, column}}` (buffer id, 0-based, UTF-16 column) and return a pending outcome (see above): + - `lsp.definition` (F12) returns `{locations: [{path, range}]}`. + - `lsp.references` (Shift+F12, `includeDeclaration?` default true) returns `{locations: [{path, range, preview, previewColumn}]}`, sorted. + - `lsp.prepareRename` returns `{range, placeholder}` or null. It uses the word at the cursor when the server has no `prepareProvider`. + - `lsp.rename {…, newName}` (F2) returns `{files: [{path, edits, bufferId?, version?}], edits, written}`. + - Locations are project-relative, deduplicated and capped at 10,000. Locations outside the project are dropped: Phpactor stubs inside the PHAR, other folders, symlinks that resolve outside. + - A position outside the buffer is `invalid_params`; no running server is `failed`. +- **Workspace edits** (`cmd/lsp_nav/edit.rs`), all or nothing as far as a file system allows: + 1. **Check everything first:** + - The edit is complete and has no file operations. + - Every document is inside the project. + - Every range converts (UTF-16 columns, CRLF as one break) and applies to a copy. + - Every open buffer is still at the version it had when the request was sent. + 2. **Write closed files**, each atomically through the VFS, keeping the BOM and line endings. If a write fails, the files written so far get their old text back; a failed restore is named in the error. No buffer is touched then. + 3. **Change open buffers** through `buffer.edit`, one batch per buffer. They become dirty and get journal, LSP and syntax updates like typing. + 4. **Follow-up:** each written file is sent to Phpactor as `didOpen` → `didSave` → `didClose` with its new text (files the user opened meanwhile are skipped), plus `workspace/didChangeWatchedFiles` for servers that watch through the client. Phpactor ignored the notification alone and kept the old names until its polling watcher noticed: in the live check a "method does not exist" error stayed, and renaming back found one use instead of four. `didOpen` alone reindexed only class files, not the member references of a function file. With all three, its index followed in 140 ms (`real_phpactor_navigates_and_renames_across_files`). Then the notification `notification.lsp.renamed {name, edits, files, written}`. +- **Undo:** the frontend calls `BufferSync.beginUndoableRemote()` on every tab before `lsp.rename` and `endUndoableRemote(version)` after it. The engine's change to an open buffer then enters the CodeMirror history as one step, and Mod+Z reverts it through `buffer.edit`. Files written on disk are not part of any editor history. Without the UI (control channel, MCP) the change is applied the same way but is not undoable in an editor. +- **UI** (`ui/src/components/editor/nav/`): + - `nav.ts` (store) supplies the context of the three engine commands with `commands.provide` and calls them with `runWaiting` after the sync is idle. + - `navExtension.ts`: Mod+click goes to the definition; the cursor becomes a pointer while Mod is held; the extension remembers the view for placing the rename field. + - `NavPicker.vue` (exclusive modal `navPicker`), `RenameInput.vue` (exclusive modal `rename`, the preview count from `lsp.references`), `ReferencesToolWindow.vue` (bottom panel tab `references`), all mounted by `NavLayer.vue`. +- **Tests:** + - `crates/engine/tests/lsp_nav.rs` runs against the fake server's `--script` answers. It covers definition, bad positions, references (sorted, deduplicated, outside dropped), prepareRename with and without the server, a multi-file rename over an open buffer and two closed files (one CRLF), refusals (outside the project, a bad range, a buffer edited meanwhile, bad names) and no server. + - The ignored `real_phpactor_navigates_and_renames_across_files` runs with `LUTRA_PHPACTOR=`. + - Vitest: `ui/tests/nav/nav.test.ts`. +- **Live** (Phpactor 2026.06.25.0, Windows 11, debug build, tick on, a 3-file temp project), measured: + + | Request | Latency | + |---|---| + | definition across files | 93 ms cold, 7–18 ms warm | + | references (4 uses in 3 files) | 137–150 ms | + | prepareRename | 10–11 ms | + | rename (4 edits, 2 files written) | 28 ms in the app, 44–59 ms in the real test | + | index follows the written files | 140 ms | + + - Phpactor took 57 MB working set (45 MB private) and 4 s of CPU over the session, about 1.6% of one core while ticking idle. + - The keys and Mod+click were not pressed in the live app: sending keys would need the window focused, and the owner was using another app. Vitest covers them. + ### Toolchain (M3.1) - **Owner decision D15:** Lutra downloads the Phpactor PHAR itself; PHP is the user's (found through `php.executable` or `PATH`). Library code lives in `crates/lsp/src/toolchain/` (L3), the engine side in `crates/engine/src/cmd/toolchain.rs`. @@ -504,6 +544,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat | Date | Change | Summary | |---|---|---| +| 2026-10-22 | minor | M3.5: definition, references, rename (`lsp_nav`, workspace edits, undoable remote edits, nav UI) | | 2026-10-22 | minor | M3.4: code assistance (`lsp.completion`, `lsp.hover`, `lsp.signatureHelp` on pending outcomes; editor completion source, hover, signature help, safe Markdown, assist UI commands), Phpactor latency and resources | | 2026-10-22 | minor | M3.5 step 1: pending outcomes (`Pending`, `Engine::resolve`, `run_waiting`), `engine_execute_waiting` / `runWaiting` | | 2026-10-20 | minor | M3.10: autosave (blur, tab switch, idle), `flushDirty`, `file.saveAll {skipConflicts}`, disk conflicts and own-write hashes in `Buffers` | diff --git a/docs/gaps.md b/docs/gaps.md index 31523ce..1bfa34f 100644 --- a/docs/gaps.md +++ b/docs/gaps.md @@ -1,6 +1,6 @@ # Gaps -> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal, autosave); G3 M1 part done (project tree, palette, settings dialog, themes) plus the app menu (M3.9); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G6 under way (LSP client library, PHP detection, Phpactor download, engine wiring and diagnostics, completion and hover); G7 under way (`lutra` CLI and single instance, MCP server, integrated terminal); G14 English UI catalog in place · **Last updated:** 2026-10-22 +> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal, autosave); G3 M1 part done (project tree, palette, settings dialog, themes) plus the app menu (M3.9); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G6 under way (LSP client library, PHP detection, Phpactor download, engine wiring and diagnostics, completion and hover, definition, references and rename); G7 under way (`lutra` CLI and single instance, MCP server, integrated terminal); G14 English UI catalog in place · **Last updated:** 2026-10-22 Every known shortfall, ranked. This is the work list: unless the owner gives a task, take the highest open gap. Hours are agent wall-clock hours for one agent, all estimated. @@ -11,7 +11,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t | G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), ~~project tree wiring~~ (M1.5 UI, M1.3 engine, M1.4 bridge: folder picker, live tree), tree toolbar and options, ~~showing truncated listings~~ (M1.13), ~~error notifications for the folder picker~~ (M1.12), ~~tabs~~ (M1.6), ~~command palette~~ (M1.8: commands only, global keymap, UI commands over the control channel); ~~settings~~ (backend: M1.9a; dialog with search: M1.9b), ~~theme switching~~ (M1.10: light/dark, live, system mode; picker in the dialog, M1.9b), ~~main menu~~ (M3.9: hamburger dropdown from `menuPath`s; native macOS menu bar and display modes open) | M1 | ~24 h | | G4 | Syntax and structure: tree-sitter PHP, ~~Lezer highlighting~~ (M2.2: PHP with embedded HTML plus HTML, CSS, JS/TS, JSON, YAML, Markdown; `--lt-syntax-*` tokens; `editor.reveal`), ~~file structure~~ (M2.7: Structure tool window, `syntax.outline`), semantic highlighting, folding in the editor | M2 | ~8 h | | G5 | Search and navigation: find in files, go to file/class/symbol, first index | M2 | ~35 h | -| G6 | Language server: completion, definition, hover, rename via Phpactor (~~PHP detection and Phpactor download~~, M3.1; ~~engine wiring and diagnostics~~, M3.3; ~~completion, hover, signature help~~, M3.4) | M3 | ~23 h | +| G6 | Language server: completion, definition, hover, rename via Phpactor (~~PHP detection and Phpactor download~~, M3.1; ~~engine wiring and diagnostics~~, M3.3; ~~completion, hover, signature help~~, M3.4; ~~definition, references, rename~~, M3.5) | M3 | ~15 h | | G7 | ~~Terminal~~ (M3.6: PTY sessions, xterm.js sub-tabs in the bottom panel; settings, persistence, links and search still open), ~~`lutra` CLI and single instance~~ (M3.7: open folders and files at a line, `--wait`, forwarding a second start, token-protected rendezvous), ~~MCP server~~ (M3.8: `lutra mcp` with list/execute every command, screenshot, read buffer, recent events, open buffers as resources; still missing: resource and tool change notifications, progress for long commands), files outside the open project (the CLI refuses them; needs out-of-project buffers or a second window), `lutra diff` | M3 | ~16 h | | G8 | Git integration | M4 | ~150 h | | G9 | Debugger, test runner, Composer, run configurations | M5 | ~300 h | @@ -44,12 +44,13 @@ Known smaller items from M0: - `ui.screenshot` captures the screen region of the window, so covering windows appear in the image; a webview-native capture would avoid that. - `cargo xtask fixtures` needs Composer, which the M0 machine does not have. -G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framing over stdio (32 MiB cap, malformed messages dropped and logged, fuzzed), `initialize` with UTF-16 positions, typed requests with timeouts and `$/cancelRequest`, answers to server requests, supervision with backoff restarts (give up after 5 crashes in 2 min) and reopening of documents, incremental document sync from `lutra_text` edits, all tested against a fake server. M3.3 wired it into the engine (one Phpactor per project on its own thread, ordered document sync, `lspStatus`) and shows Phpactor's diagnostics as editor underlines and in a Problems tab. It was checked against the real Phpactor on Windows, which needed three workarounds: a keep-alive tick, in-process diagnostics and a polling watcher (see `docs/architecture.md`). M3.4 added completion, hover and signature help in the editor (Phpactor's answers, Lutra's triggers, safe Markdown, measured 61–109 ms per completion while typing on Windows). Still open: navigation and rename (M3.5), slow first indexing on Windows (Phpactor advances one step per stdin message, so a 2,000-class project takes ~65 s before completion is useful), PHP lint syntax errors on Windows, quick-fixes, and killing a Phpactor process left behind when Lutra itself is killed. +G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framing over stdio (32 MiB cap, malformed messages dropped and logged, fuzzed), `initialize` with UTF-16 positions, typed requests with timeouts and `$/cancelRequest`, answers to server requests, supervision with backoff restarts (give up after 5 crashes in 2 min) and reopening of documents, incremental document sync from `lutra_text` edits, all tested against a fake server. M3.3 wired it into the engine (one Phpactor per project on its own thread, ordered document sync, `lspStatus`) and shows Phpactor's diagnostics as editor underlines and in a Problems tab. It was checked against the real Phpactor on Windows, which needed three workarounds: a keep-alive tick, in-process diagnostics and a polling watcher (see `docs/architecture.md`). M3.4 added completion, hover and signature help in the editor (Phpactor's answers, Lutra's triggers, safe Markdown, measured 61–109 ms per completion while typing on Windows). M3.5 added go to definition (F12, Mod+click, a picker for several), find references (a References tab) and rename (F2, an inline field; open buffers dirty and undoable, closed files written atomically, edits outside the project refused), all through Phpactor without blocking the engine; rename has no preview list yet, and the editor's undo does not revert closed files it wrote. Still open: slow first indexing on Windows (Phpactor advances one step per stdin message, so a 2,000-class project takes ~65 s before completion is useful), PHP lint syntax errors on Windows, quick-fixes, and killing a Phpactor process left behind when Lutra itself is killed. ## Revision history | Date | Change | Summary | |---|---|---| +| 2026-10-22 | minor | G6 shrunk: definition, references, rename (M3.5) | | 2026-10-22 | minor | G6 shrunk: completion, hover and signature help (M3.4) | | 2026-10-21 | minor | G6 shrunk: engine wiring and diagnostics (M3.3) | | 2026-10-20 | minor | G2 shrunk: autosave and `flushDirty` (M3.10) | diff --git a/docs/language-parity.md b/docs/language-parity.md index ada8ea1..176ae8f 100644 --- a/docs/language-parity.md +++ b/docs/language-parity.md @@ -6,12 +6,12 @@ - [ ] Highlighting, including heredoc/nowdoc and embedded HTML - [ ] File structure: namespaces, classes, interfaces, traits, enums, functions, constants - [ ] Go to declaration and implementation -- [ ] Find usages +- [ ] Find usages (partial, M3.5: find references and go to definition through Phpactor; no scopes, no usage kinds) - [ ] Completion: members, functions, classes with auto-import, keywords - M3.4 (2026-10-22): partial, from Phpactor: members after `->`/`::`, variables, classes and keywords with hover documentation and signature help; imports applied when Phpactor sends them. No type inference of Lutra's own. - [ ] Type inference from declarations, PHPDoc, generics in PHPDoc - [ ] Diagnostics: syntax errors, undefined symbols, type mismatches -- [ ] Refactorings: rename, extract variable/method, move class, change signature +- [ ] Refactorings: rename (partial, M3.5: through Phpactor with an inline field; no preview list), extract variable/method, move class, change signature - [ ] Formatting to PSR-12 / PER coding style - [ ] PHPDoc generation and completion diff --git a/docs/roadmap.md b/docs/roadmap.md index b46106d..11350da 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -9,7 +9,7 @@ Hours are agent wall-clock hours for one agent; M0 and M1 so far are measured, t | M0 | Foundation: workspace, lints, quality gate, command registry, control channel, empty window | done 2026-10-14 (CI workflow written, not yet run: hosted on Forgejo, runners unknown) | ~2 (measured) | | M1 | Editor and project: open folder, tree, tabs, editor, save, recovery, palette, settings, themes | done 2026-10-16 (M1.1 text, M1.2 VFS, M1.5 tree UI, M1.3 engine workspace, M1.4 desktop bridge, M1.6 tabs and editor, M1.11 message catalog, M1.9a settings backend, M1.10 themes, M1.7 recovery journal, M1.12 notifications, M1.13 C1 follow-ups, M1.8 command palette and keymap, M1.14 app icon, M1.9b settings dialog; C2 live checks pending, gaming mode) | ~5.6 (measured: C1 2.5, C2 3.1) | | M2 | Syntax and search: highlighting, structure, find in files, go to file/class/symbol | done 2026-10-17 (C3: M2.1 tree-sitter syntax, M2.2 highlighting + `editor.reveal`, M2.3 search backend, M2.4 Find tool window, M2.5 symbol index + go-to commands, M2.6 go-to popup, M2.7 Structure tool window) | ~6.1 (measured) | -| M3 | LSP, terminal, CLI: completion, diagnostics, go to definition, hover, rename; terminal; `lutra` CLI and MCP — **MVP** | in progress (M3.7 CLI and single instance, M3.8 MCP server, M3.10 autosave, M3.6 integrated terminal, M3.3 engine wiring and diagnostics, M3.4 completion, hover and signature help done) | ~12 | +| M3 | LSP, terminal, CLI: completion, diagnostics, go to definition, hover, rename; terminal; `lutra` CLI and MCP — **MVP** | in progress (M3.7 CLI and single instance, M3.8 MCP server, M3.10 autosave, M3.6 integrated terminal, M3.3 engine wiring and diagnostics, M3.4 completion, hover and signature help, M3.5 definition, references and rename done) | ~12 | | M4 | Git: status, diff, commit, branches, log, blame, conflicts | not started | ~150 | | M5 | Debugger (Xdebug via DAP), PHPUnit/Pest runner, Composer, run configurations | not started | ~300 | | M6 | Own indexer and inspections; Symfony, Laravel, Shopware, WordPress support | not started | ~1,100 | @@ -34,6 +34,7 @@ By the raw estimates the alpha gate needs M1–M4 plus cross-platform verificati | Date | Change | Summary | |---|---|---| +| 2026-10-22 | minor | M3.5 definition, references, rename | | 2026-10-22 | minor | M3.4 completion, hover and signature help | | 2026-10-21 | minor | M3.3 engine wiring and diagnostics | | 2026-10-20 | minor | M3.10 autosave | diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md index 72c5fd2..ff29c9c 100644 --- a/docs/target-app-parity.md +++ b/docs/target-app-parity.md @@ -1,6 +1,6 @@ # Target-app parity -> **Status:** M1 done (text buffer, VFS, engine workspace, project tree, tabs and a plain-text editor, recovery, palette, settings and themes in the app); M2 started: PHP syntax highlighting, find in files with its tool window, the symbol index and the go-to popup, the Structure tool window; M3 started: the integrated terminal · **Last updated:** 2026-10-22 · **Target:** PhpStorm 2026.x +> **Status:** M1 done (text buffer, VFS, engine workspace, project tree, tabs and a plain-text editor, recovery, palette, settings and themes in the app); M2 started: PHP syntax highlighting, find in files with its tool window, the symbol index and the go-to popup, the Structure tool window; M3 started: the integrated terminal, go to definition, find references and rename through Phpactor · **Last updated:** 2026-10-22 · **Target:** PhpStorm 2026.x ## How this is measured @@ -16,11 +16,11 @@ Hours are the estimated agent wall-clock hours for one agent to reach behaviour |---|---:|---:|---|---:|---| | Editor core | 12 | 11% (est.) | semantic highlighting and a colour scheme editor, code folding, soft wrap and other editor settings, preview tab, pinned/split/reordered tabs, close others/all, reopen closed tab, tab limit, conflict UI for files changed on disk, save before run/commit (no such features yet; they will call `flushDirty`), local history, encodings other than UTF-8, large-file mode, column selection and multi-caret checked against the docs; recovery journal not yet checked in the running app (gaming mode) | ~100 (est.) | M3.10: autosave (`ui/src/stores/autosave.ts`): changed files are saved on window blur / hidden page, on a tab switch and after `editor.autosave.idleSeconds` (default 15) without an edit; three settings in Settings › Editor, all on by default. `flushDirty()` is the one "save all dirty and wait" entry point (waits for pending buffer sync, then `file.saveAll {skipConflicts: true}`), for deployment, run configurations and terminal commands later. Files changed or deleted on disk while dirty are skipped, our own save reported late is not a conflict (hash of the last read/written content); one toast per failed file, not repeated by autosave. Tests: engine (`crates/engine/tests/workspace.rs`: skip conflict, removed file not recreated, typing right after a save; settings validation), Vitest with fake timers (`ui/tests/editor/autosave.test.ts`, 11 tests: idle, idle setting/0, blur, hidden page, tab switch, settings off, pending-sync wait, skipped conflicts, toasts, command failure, serialised flushes). Checked in the app on Windows 11 (bundled UI, `--control 7940`, edits via `buffer.edit`, measured): not saved 10 s after an edit, saved at 15.0 s; edit then switching tabs a→b and b→a saved in ≤ 0.1 s; edit, then another app took focus: saved in 0.75 s; no buffer dirty afterwards. Graded against `plan/phpstorm/15-autosave.md`. M2.2: syntax highlighting by file extension (`ui/src/components/editor/language.ts`): PHP with embedded HTML/CSS/JS through `@codemirror/lang-php` (Lezer), plus HTML, CSS, JS/TS, JSON, YAML, Markdown; spans carry `lt-syntax-*` classes coloured only by the eleven `--lt-syntax-*` tokens of both themes (Lutra's own palette, ≥ 4.5:1 on the editor background and active line, contrast test). `editor.reveal {path, line, column}` opens, activates, places the cursor (UTF-16 column, CRLF-safe) and centres it; agents reach it as a UI command. Checked in the app on Windows 11 (bundled UI, control channel): PHP with embedded HTML in dark and light, `editor.reveal` into a closed CRLF file (last line, then line 302 centred). Vitest: language per extension, classes on spans for PHP/HTML and the other languages, reveal on open and closed files, CRLF mapping, clamping, bad params. keystroke to highlight on a 1 MB PHP file 3.0–11.4 ms median (jsdom, JavaScript work only, measured, not yet in the WebView). M2.1: `crates/syntax` parses PHP with tree-sitter (incremental reparse from `lutra_text` edits) and computes folding ranges (brace blocks, arrays, comments, heredocs, `use` runs); library only, nothing visible in the editor yet, so the score is unchanged. Tests: outline/folding snapshots for five PHP 8.3 fixtures, proptests (random bytes and token soups never panic, reparse equals a fresh parse, undo round trip). 1 MB parse 364–553 ms, reparse after one keystroke 7–11 ms (release, measured, machine busy). M1.13: opening a file that is already open switches to its tab (`bufferFocused`; engine test, Vitest, control-channel test; live check pending (gaming mode)); files in folders the tree never expanded still reload or report changes on disk, because the parent directory of every open buffer stays watched (engine tests). M1.7: crash-recovery journal (`crates/engine/src/journal.rs`, `cmd/recovery.rs`): dirty buffers are written atomically to `/recovery//` about 1 s after the last edit (at least every 2 s while typing), never per keystroke; removed on save, close and discard; `recoveryAvailable` after `project.open`, `recovery.list/restore/discard`; restored buffers are dirty and keep line ending and BOM; corrupt entries are moved aside with a warning. Restore dialog (`ui/src/components/recovery/`: Restore all / selected / Discard, time, changed-on-disk hint). Tests: engine dropped mid-edit and a new engine restores the exact CRLF + BOM text, corrupt entries, removal paths, a property test of random edit sequences → crash → restore equals the buffer (`crates/engine/tests/recovery.rs`, 10 tests), the same flow headless over the control channel (`crates/control/tests/recovery.rs`), 10 Vitest tests for the dialog. 1 MiB entry write: 8.5 ms median (release, measured). Graded against `plan/phpstorm/04-recovery.md`. M1.6: tabs and a CodeMirror 6 editor in the app (`ui/src/components/editor/`, `ui/src/stores/editor.ts`): open from the project tree or engine events, activate, close by button, middle click or `Mod+W`, dirty dot, Save / Don't Save / Cancel on closing a dirty tab, `Mod+S` / `Mod+Alt+S` from engine command specs, non-blocking notice for a dirty file changed or deleted on disk; local edits go to `buffer.edit` with version-based resync, CRLF files keep `\r\n`; undo/redo, multiple selections, search and bracket matching from CodeMirror's basic setup. Vitest: a burst of 400 keystrokes with stale versions and remote edits loses none, a CRLF burst with deletions converges, store and component tests against a fake engine (`ui/tests/editor/`, 22 tests). Checked in the app on Windows 11 with `--control` and `ui.screenshot`: typing via the UI and via `buffer.edit`, save to disk, close question, middle click, disk-change notice. 1 MB file (16,385 lines): engine `file.open` 80 ms over the control channel (debug build, measured), editor state 1–6 ms and first rendered view 4–11 ms in Chromium (measured), ≈ 90 ms in total (estimated, budget 150 ms). Graded against `plan/phpstorm/03-editor-tabs.md`. `crates/text`: rope buffer, positions, edits (M1.1, unit tests + proptests). M1.3: engine buffers with versions and dirty state, `file.open`, `buffer.get`, `buffer.edit` (UTF-16 change sets, `stale_version`), `file.save`, `file.saveAll`, `buffer.close` with unsaved-changes guard, line ending and BOM kept on save, clean buffers reload on external change; 14 integration tests on temp dirs (`crates/engine/tests/workspace.rs`) | | Project view, VFS | 6 | 8% (est.) | views list (project / scopes), toolbar (Select Opened File, Expand/Collapse All), sort and display options, show/hide excluded, distinct icons for library and excluded folders, file colours, speed search, preview, file operations | ~37 (est.) | `lutra-vfs` (M1.2): lazy sorted listing, ignore rules (.gitignore, .ignore, info/exclude, global excludes, Lutra defaults), native file watching via `notify` with a polling fallback, capped UTF-8 reads, atomic writes; 34 tests on temp dirs, watcher tests run on both backends (`crates/vfs/tests`). M1.5: project tree UI (lazy listing, keyboard navigation, dimmed ignored entries, event refresh) in `ui/src/components/project/`, Vitest against a mocked engine. M1.3: `project.open`, `project.close`, `project.children` (watches listed directories, capped at 256 native / 32 polling, least recently listed dropped), `treeChanged` events from disk, `events.subscribe` on the control channel with a TCP test (`crates/control/tests/events.rs`). M1.4: the tree runs against the engine in the app: folder picker (`project.openDialog`) and `lutra-desktop --control PORT PATH` open a project, the tree lists it lazily with ignored (`var/` from `.gitignore`) and excluded (`node_modules`) entries dimmed, a file created on disk appears in an expanded folder within ~100 ms; verified with `ui.screenshot` on Windows 11 and Vitest (`ui/tests/project/`, `ui/tests/ipcEvents.test.ts`). M1.13: a directory listed only partly (more than 100,000 entries) ends with a "Listing truncated" note row (Vitest). M1.12: a folder that cannot be opened from the picker or the command line (including `unsaved_changes` when switching projects) and stopped file watching show as toasts instead of stderr (`apps/lutra-desktop/src/host.rs`, `ui/src/stores/notifications.ts`, `ui/tests/notifications/`, 19 Vitest tests; live check pending, gaming mode); score unchanged. Graded against `plan/phpstorm/02-project-view.md`: tool window, folder-first tree, dimmed ignored/excluded, keyboard navigation and live refresh exist; most toolbar, view and display options do not | -| Navigation | 10 | 10% (est.) | go-to: recent files on an empty query, a non-project toggle (library items always show), file-type filter, `:line` suffixes, actions and text tabs, sending the list to Find; find usages, go to declaration, recent files and locations, navigation history, File Structure popup, Structure speed search, sorting and filters (visibility, inherited members), autoscroll from the caret, navigation bar, bookmarks (M1.8: a command palette over commands only) | ~102 (est.) | M2.6: go-to popup `ui/src/components/goto/` with Files / Classes / Symbols tabs (Tab and Shift+Tab or a click switch, the text stays), UI commands `goto.fileOpen` `Mod+P`, `goto.classOpen` `Mod+Alt+C`, `goto.symbolOpen` `Mod+T` (optional `{query}` for agents), live query against `goto.*` (60 ms debounce, stale answers dropped), matched characters marked, directory / namespace / container column, library rows dimmed and labelled (`goto.file` items now carry `library`), an indexing hint with progress and a re-query on `indexReady`, Enter or a click opens through `editor.reveal`, Escape closes, one modal at a time; Vitest `ui/tests/goto/`, live-checked in the app (port 7826). M2.7: Structure tool window (`ui/src/components/structure/`) in a new left stripe with Project | Structure: the active tab's outline as a tree with Lucide kind icons and signatures, follows the active tab and edits (`outlineChanged`), click or Enter jumps through `editor.reveal`, arrows fold, `view.toggleStructure` `Mod+2`; engine `syntax.outline {id}` from a per-buffer tree-sitter tree reparsed off the engine lock on a worker thread (200 ms debounce). Tests: 11 engine unit tests, engine integration tests with a proptest of random edit sequences (end at a fresh parse's outline), a control-channel test (`crates/control/tests/syntax.rs`), 13 Vitest tests (`ui/tests/structure/`). Checked in the app on Windows 11 (bundled UI, control port 7827): a class file with namespace, interface, enum, trait, class with promoted property and a function; `outlineChanged` 149 ms after `file.open`, `view.toggleStructure` shows the tree, a jump to `find` centres line 62, an added method appears about 0.3 s after `buffer.edit` (debug build). Rows were not clicked in the app (the control channel has no input method); click and Enter are covered by Vitest. 1 MB file: `buffer.edit` ≤ 0.25 ms and `pump_vfs` ≤ 3.8 ms under the lock, edit to `outlineChanged` 0.43–0.76 s, `syntax.outline` 82 ms (release, measured). Graded against `plan/phpstorm/09-structure.md`. M2.5: symbol index in `crates/index` (every project file listed, `.php` parsed in parallel from tree-sitter outlines, vendor marked library, incremental on disk and buffer changes, capped at 200,000 files) and the engine commands `index.status`, `goto.file`, `goto.class`, `goto.symbol` (fuzzy, file names weighted, `Class::member`, project before library, partial results with `indexing: true`), events `indexProgress`/`indexReady`; 20k-file / 88 MB generated project indexed in 3.9–4.2 s (release, measured), queries 2–12 ms; tests `crates/index/tests/`, `crates/engine/tests/goto.rs`, `crates/control/tests/goto.rs`; reached from the UI by M2.6. M2.1: file outline in `crates/syntax` (namespaces braced and unbraced, classes, interfaces, traits, enums with cases, functions, methods, properties incl. promoted ones, constants; UTF-16 ranges and short signatures), the base for the Structure window (M2.7) and the symbol index (M2.5); not reachable from the UI yet, score unchanged. M1.8: `ui/src/components/palette/`, `ui/src/commands/` (fuzzy ranking, recent commands, global keymap), Vitest `ui/tests/palette/`, `ui/tests/commands/` | +| Navigation | 10 | 13% (est.) | go to declaration: type declaration, implementations, the hover link underline; find usages: popup variant, usages highlighted in the file, scopes, grouping options, read/write access; go-to: recent files on an empty query, a non-project toggle (library items always show), file-type filter, `:line` suffixes, actions and text tabs, sending the list to Find; recent files and locations, navigation history, File Structure popup, Structure speed search, sorting and filters (visibility, inherited members), autoscroll from the caret, navigation bar, bookmarks (M1.8: a command palette over commands only) | ~96 (est.) | M3.5: Go to Definition (`lsp.definition`, F12 or Mod+click with a pointer cursor while Mod is held) through Phpactor: one location revealed, several in a picker (one modal at a time), none as a toast; Find References (`lsp.references`, Shift+F12) in a References tab of the bottom panel, grouped by file with the line preview and the name marked, click or Enter reveals. Requests wait off the engine lock (pending outcomes) and see every edit sent before them. Live against Phpactor 2026.06.25.0 on Windows (port 7935, three-file temp project, debug build, tick on): class definition across files 93 ms cold, 7–18 ms warm; references (4 uses in 3 files, incl. a CRLF file) ~140 ms (measured). Tests: `crates/engine/tests/lsp_nav.rs` (fake server with scripted answers; an ignored real-Phpactor test), Vitest `ui/tests/nav/`. The F12 and F2 keys were not pressed in the live app (no key input without stealing the owner's focus); the key and click paths are covered by Vitest. M2.6: go-to popup `ui/src/components/goto/` with Files / Classes / Symbols tabs (Tab and Shift+Tab or a click switch, the text stays), UI commands `goto.fileOpen` `Mod+P`, `goto.classOpen` `Mod+Alt+C`, `goto.symbolOpen` `Mod+T` (optional `{query}` for agents), live query against `goto.*` (60 ms debounce, stale answers dropped), matched characters marked, directory / namespace / container column, library rows dimmed and labelled (`goto.file` items now carry `library`), an indexing hint with progress and a re-query on `indexReady`, Enter or a click opens through `editor.reveal`, Escape closes, one modal at a time; Vitest `ui/tests/goto/`, live-checked in the app (port 7826). M2.7: Structure tool window (`ui/src/components/structure/`) in a new left stripe with Project | Structure: the active tab's outline as a tree with Lucide kind icons and signatures, follows the active tab and edits (`outlineChanged`), click or Enter jumps through `editor.reveal`, arrows fold, `view.toggleStructure` `Mod+2`; engine `syntax.outline {id}` from a per-buffer tree-sitter tree reparsed off the engine lock on a worker thread (200 ms debounce). Tests: 11 engine unit tests, engine integration tests with a proptest of random edit sequences (end at a fresh parse's outline), a control-channel test (`crates/control/tests/syntax.rs`), 13 Vitest tests (`ui/tests/structure/`). Checked in the app on Windows 11 (bundled UI, control port 7827): a class file with namespace, interface, enum, trait, class with promoted property and a function; `outlineChanged` 149 ms after `file.open`, `view.toggleStructure` shows the tree, a jump to `find` centres line 62, an added method appears about 0.3 s after `buffer.edit` (debug build). Rows were not clicked in the app (the control channel has no input method); click and Enter are covered by Vitest. 1 MB file: `buffer.edit` ≤ 0.25 ms and `pump_vfs` ≤ 3.8 ms under the lock, edit to `outlineChanged` 0.43–0.76 s, `syntax.outline` 82 ms (release, measured). Graded against `plan/phpstorm/09-structure.md`. M2.5: symbol index in `crates/index` (every project file listed, `.php` parsed in parallel from tree-sitter outlines, vendor marked library, incremental on disk and buffer changes, capped at 200,000 files) and the engine commands `index.status`, `goto.file`, `goto.class`, `goto.symbol` (fuzzy, file names weighted, `Class::member`, project before library, partial results with `indexing: true`), events `indexProgress`/`indexReady`; 20k-file / 88 MB generated project indexed in 3.9–4.2 s (release, measured), queries 2–12 ms; tests `crates/index/tests/`, `crates/engine/tests/goto.rs`, `crates/control/tests/goto.rs`; reached from the UI by M2.6. M2.1: file outline in `crates/syntax` (namespaces braced and unbraced, classes, interfaces, traits, enums with cases, functions, methods, properties incl. promoted ones, constants; UTF-16 ranges and short signatures), the base for the Structure window (M2.7) and the symbol index (M2.5); not reachable from the UI yet, score unchanged. M1.8: `ui/src/components/palette/`, `ui/src/commands/` (fuzzy ranking, recent commands, global keymap), Vitest `ui/tests/palette/`, `ui/tests/commands/` | | Search and replace | 6 | 8% (est.) | find in the current file, replace in files and in a file, scopes (module, directory, open files, custom), comment/string filters, search history, a tab per search, grouping options, merging matches on one line, find in path from the tree, structural search | ~70 (est.) | M2.4 Find tool window in a new resizable, collapsible bottom panel: query with case / whole word / regex toggles, include and exclude globs, streamed results grouped by file (sorted) with the match highlighted in the line preview, counts and elapsed time, cancel, a truncated hint, a refused regex or glob shown in place; Enter or click opens the match through `editor.reveal`, arrow keys / Page / Home / End walk the results; `find.open` (`Mod+Alt+F`, Lutra's own) prefills the selection or the word at the cursor, `find.open {query}` from an agent searches at once; a new search cancels the running one. Tests: 26 Vitest store and component tests (`ui/tests/find/FindToolWindow.test.ts`). Live check (bundled-ui debug build, control port 7824, 3-file temp project): `find.open {query}` over `uiCommand` showed 14 matches in 3 files (vendor included) grouped and highlighted in 17 ms; with `*.php` include 2 matches; revealing a result's position opened the file at the match; `find.open` without params prefilled the word at the cursor; a bad regex showed the engine's message in place (screenshots read, measured). Opening a result by mouse or Enter is covered by Vitest only (the control channel cannot click). M2.3 backend: `crates/search` (parallel `ignore` walk + `grep-searcher`: literal/regex, case, whole word, include/exclude globs, project ignore rules with `vendor/` searched and `node_modules` skipped, binary and > 8 MiB files skipped, match cap, cancel) and engine `search.find` / `search.cancel` with `searchResults` / `searchDone` events through the pump; dirty buffers are searched in their buffer text. Tests: 9 library tests incl. a property test of random queries and file bytes (`crates/search/tests/search.rs`), 3 preview/column unit tests, 4 engine tests (`crates/engine/tests/search.rs`), a TCP control-channel test (find → results → done, invalid regex, cancel; `crates/control/tests/search.rs`). 20k-file generated tree, release: first result 10–43 ms, full walk 0.66–1.43 s (measured); live over the control channel against the running app: first result 55 ms, done 386 ms on a 5,900-file project (debug build, measured) | | Code completion | 10 | 5% (est.) | type-matching and second-invocation completion, postfix completion, live templates, path completion, ranking options and the replace-on-accept variant, accept characters, auto-insert of a single suggestion, auto-import checked against the real Phpactor (applied when the server sends it; tested with the fake server only), completion settings (auto popup, delay, case), parameter info settings, a documentation tool window, type info, faster indexing on Windows (Phpactor's tick-driven loop takes ~65 s for 2,000 classes) | ~240 (est.) | M3.4: completion, hover and signature help from Phpactor. Engine `lsp.completion {id, position, triggerCharacter?}` (items with label, kind, detail, Markdown documentation, insertText, textEdit, additionalTextEdits, sortText; at most 500, sorted by sortText, `incomplete` when cut or when the server says so; snippets turned into plain text), `lsp.hover` (Markdown, range) and `lsp.signatureHelp` (UTF-16 parameter spans), sent off the engine lock through M3.5's pending outcomes (`crates/engine/src/cmd/lsp_assist.rs`). Editor (`ui/src/components/editor/assist/`): a CodeMirror completion source with Lutra's own triggers (identifiers, `$`, `->`, `?->`, `::`, namespace `\`; not in strings or comments unless asked), the server's ranking as boost, local filtering for complete lists, text edits and imports applied in UTF-16 (CRLF files too), Lucide kind icons; hover documentation after 350 ms and on demand (`editor.quickDocumentation` `Mod+I`); signature help on `(` and `,` that follows the cursor (`editor.parameterInfo`); `editor.complete`; Markdown rendered by Lutra's own renderer without any HTML (XSS-tested). Tests: 6 engine tests against the fake server, 9 unit tests, 29 Vitest tests, an ignored test against the real PHAR. Measured with the real Phpactor on Windows 11 (debug build, 25 ms tick): completion while typing 61–109 ms (median 76 ms; ~107 ms through the control channel in the app), hover 4–91 ms (median 15–16 ms), signature help 4–28 ms (median 16 ms); a useful list 2.3 s after opening a file of a 20-class project and 65 s for 2,000 classes (Phpactor indexes first and answers with an empty incomplete list until then). Checked in the app (port 7934): completion after `->`, quick documentation of a class, parameter info with the active parameter, screenshots read. Graded against `plan/phpstorm/12-completion.md`: the depth comes from Phpactor (members, classes, variables, keywords; detail and documentation often missing), Lutra has no type inference of its own | | Inspections and quick-fixes | 8 | 4% (est.) | Lutra's own inspections and their settings, severities per inspection, quick-fixes (LSP code actions), suppression, inspection profiles, running inspections on a scope, PHP lint syntax errors on Windows, the editor's problem counter and scrollbar marks, next/previous problem, a current-file Problems view and severity filters, external tools (PHPStan, Psalm, PHP_CodeSniffer) | ~290 (est.) | M3.3: diagnostics from Phpactor (worse reflection: missing members, unknown classes, …) as wavy underlines, gutter markers and hover messages in the editor (`ui/src/components/editor/lint.ts`, tokens only), and a Problems tab in the bottom panel grouped by file with click to reveal (`ui/src/components/problems/`, `problems.open` `Mod+Alt+P`); engine `diagnosticsChanged`, `diagnostics.list`, `lspStatus` (`crates/engine/src/lsp/`). Tests: 10 engine tests against a fake server incl. a sync proptest, a TCP test, 16 Vitest tests, an ignored test against the real PHAR. Checked in the app on Windows 11 with the real Phpactor (port 7933): five errors underlined and listed; first diagnostics 2.7 s after `file.open`, 2.7–2.9 s after an edit (debug build, measured, incl. Phpactor's 1 s debounce). Graded against `plan/phpstorm/11-problems.md`: the depth comes from Phpactor, Lutra has no inspections of its own | -| Refactoring | 7 | 0% | everything | ~250 (est.) | — | +| Refactoring | 7 | 3% (est.) | rename: preview of all changes, comments/strings and text occurrences, scope, renaming files with classes, one undo across files (closed files written on disk are not undone by the editor); extract variable/method/constant, inline, move, change signature, safe delete, pull up/push down, introduce parameter | ~244 (est.) | M3.5: Rename (`lsp.prepareRename` then `lsp.rename`, F2) through Phpactor with an inline field over the symbol that shows how many uses in how many files change. The workspace edit is checked completely first (inside the project, ranges fit, open buffers unchanged since the request, no file operations); then closed files are written atomically through the VFS (written ones restored if a later write fails), open buffers change through `buffer.edit` (dirty, one undo step each in the editor), Phpactor reindexes the written files (sent as `didOpen`/`didSave`/`didClose`; its index followed in 140 ms, measured) and a summary notification follows. Live: renaming a method used in 3 files took 28 ms (open buffer + 2 closed files, CRLF kept). Tests: `crates/engine/tests/lsp_nav.rs` (multi-file rename incl. a closed CRLF file, an edit outside the project refused, a bad range refused, a buffer edited meanwhile refused; ignored real-Phpactor rename and rename back), Vitest `ui/tests/nav/`. | | Code style and formatting | 4 | 0% | everything | ~120 (est.) | — | | Git | 8 | 0% | everything | ~150 (est.) | — | | Terminal | 3 | 15% (est.) | renaming and splitting tabs, sessions kept across restarts, search in the output, clickable paths and links, drag and drop, command completion, terminal settings (shell path, start directory, environment, font, cursor shape, bell, copy on selection, middle-click paste), a key back to the editor, the PHP interpreter in `PATH`, a terminal in a file's directory, confirmation before killing a running process, moving a terminal into the editor | ~26 (est.) | M3.6: `crates/terminal` runs the shell in a pseudo terminal (`portable-pty`: ConPTY on Windows, Unix pty elsewhere) on its own reader, writer and waiter threads: UTF-8 split across reads joined, invalid bytes U+FFFD, a 1 MiB output buffer per session with backpressure (the shell waits, nothing is dropped while it runs), a non-blocking input queue, resize, kill, exit codes. Engine `terminal.create {cwd?, shell?, cols, rows}` / `terminal.input` / `terminal.resize` / `terminal.close`, events `terminalOutput` (≤ 64 KiB per terminal and 256 KiB per pump, round-robin) and `terminalExited {code}`; terminals close with the project and on `app.quit`. UI: a Terminal tab in the bottom panel (tabs next to Find), xterm.js with the fit addon, several terminals as sub-tabs (Local, Local (2)…) with close and new buttons, output replayed after collapsing the panel, copy (`Mod+Shift+C`, `Ctrl+C` with a selection) and paste (`Mod+Shift+V`, `Ctrl+V`), a focus rule that leaves plain Ctrl keys to the shell, Lutra's own ANSI colours (`--lt-terminal-*`, all text colours ≥ 4.5:1), `terminal.open` `Mod+Shift+T`. Tests: 8 session tests with real `cmd.exe` (echo, exit code, input, 6,000 multibyte characters without U+FFFD, 30,000 lines through a full buffer without losing a line, resize, kill, spawn errors) and UTF-8 proptests (`crates/terminal`), 3 engine tests (`crates/engine/tests/terminal.rs`), a TCP control test create → output → input → exit (`crates/control/tests/terminal.rs`), 20 Vitest tests with a mocked xterm (`ui/tests/terminal/`). Live check (Windows 11, debug build with bundled UI, control port 7936, temp project): `terminal.open` showed a pwsh prompt in the project root, first `terminalOutput` 0.2–0.5 s after the command; `php -v` printed PHP 8.4.24 within 0.5–1.5 s; `dir` listed the project; resizing the window changed the shell's width 144 → 190 → 105 → 142 columns (pwsh `WindowSize`); a second terminal as sub-tab "Local (2)"; Find and Terminal as bottom tabs; dark and light screenshots read; `exit 3` gave `terminalExited {code: 3}`; `app.quit` ended the app and its shells (measured). The live check found two bugs, fixed before the commit: xterm's own black viewport background showed as a bar under the last row, and programs printing ANSI white (PSReadLine) were unreadable on the light theme, so xterm now enforces a 4.5:1 minimum contrast. Typing, clicking and copy/paste were not driven in the app (the control channel has no input method); Vitest covers them. Graded against `plan/phpstorm/10-terminal.md` | @@ -65,6 +65,7 @@ The project tree is the first user-visible feature (Project view 8%, estimated); | Date | Change | Summary | |---|---|---| +| 2026-10-22 | minor | M3.5: Navigation 10% → 13% (est.), go to definition and find references; Refactoring 0% → 3% (est.), rename; hours 102 → 96 and 250 → 244 | | 2026-10-22 | minor | M3.4: Code completion 0% → 5% (est.), completion, hover and signature help from Phpactor; hours 250 → 240; breadth 26/155 | | 2026-10-21 | minor | M3.3: Inspections and quick-fixes 0% → 4% (est.), diagnostics from Phpactor and the Problems tab; hours 300 → 290 | | 2026-10-20 | minor | M3.10: Editor core 10% → 11% (est.), autosave and `flushDirty`; hours 104 → 100 | diff --git a/ui/src/App.vue b/ui/src/App.vue index 52a5b0b..c7fa45c 100644 --- a/ui/src/App.vue +++ b/ui/src/App.vue @@ -16,6 +16,7 @@ import CommandPalette from "./components/palette/CommandPalette.vue"; import EditorArea from "./components/editor/EditorArea.vue"; import GotoPopup from "./components/goto/GotoPopup.vue"; import MainLayout from "./components/layout/MainLayout.vue"; +import NavLayer from "./components/editor/nav/NavLayer.vue"; import NotificationStack from "./components/notifications/NotificationStack.vue"; import RecoveryDialog from "./components/recovery/RecoveryDialog.vue"; import SettingsDialog from "./components/settings/SettingsDialog.vue"; @@ -65,6 +66,7 @@ onUnmounted(() => { + diff --git a/ui/src/commands/modals.ts b/ui/src/commands/modals.ts index 94cedbf..8ab9a36 100644 --- a/ui/src/commands/modals.ts +++ b/ui/src/commands/modals.ts @@ -17,13 +17,15 @@ * what the command shows. The go-to popup is a launcher too: any command * but the go-to open commands closes it. So is the app menu (M3.9): any * command but `menu.open` closes it. + * - **Navigation (M3.5):** the definition picker and the inline rename field + * are exclusive modals too. */ import { defineStore } from "pinia"; import { ref, watch } from "vue"; import { useEditorStore } from "../stores/editor"; /** The exclusive modals. */ -export type ModalId = "palette" | "goto" | "menu" | "settings" | "closePrompt"; +export type ModalId = "palette" | "goto" | "menu" | "settings" | "closePrompt" | "navPicker" | "rename"; /** Store of the open exclusive modal. */ export const useModalsStore = defineStore("modals", () => { diff --git a/ui/src/components/editor/bufferSync.ts b/ui/src/components/editor/bufferSync.ts index 42b14b0..e594a77 100644 --- a/ui/src/components/editor/bufferSync.ts +++ b/ui/src/components/editor/bufferSync.ts @@ -131,6 +131,12 @@ export class BufferSync { private disposed = false; /** Callbacks waiting for {@link idle}. */ private waiters: (() => void)[] = []; + /** + * Remote changes up to this engine version enter the undo history + * (a rename, M3.5); `Infinity` while the version is not known yet, null + * when off. + */ + private undoableUntil: number | null = null; /** Engine transport. */ private readonly transport: SyncTransport; /** Receives errors that are not handled by a resync. */ @@ -241,6 +247,27 @@ export class BufferSync { } } + /** + * Makes the engine's next changes to this buffer undoable in the editor + * (they enter the history instead of bypassing it), until + * {@link endUndoableRemote}. Called before a command that edits open + * buffers on the user's behalf, such as `lsp.rename`. + */ + beginUndoableRemote(): void { + this.undoableUntil = Number.POSITIVE_INFINITY; + } + + /** + * Ends {@link beginUndoableRemote} once the engine version `version` has + * been taken over; null ends it now (the command did not touch this + * buffer or failed). + * + * @param version - the buffer's version after the command, or null. + */ + endUndoableRemote(version: number | null): void { + this.undoableUntil = version === null || this.version >= version ? null : version; + } + /** Resolves once every local change has reached the engine. */ idle(): Promise { if (!this.pending || this.disposed) { @@ -370,11 +397,15 @@ export class BufferSync { this.version = info.version; this.latestKnown = Math.max(this.latestKnown, info.version); this.separator = separatorOf(info.lineEnding); + const undoable = this.undoableUntil !== null && info.version <= this.undoableUntil && !dropLocal; + if (this.undoableUntil !== null && Number.isFinite(this.undoableUntil) && this.version >= this.undoableUntil) { + this.undoableUntil = null; + } if (!toLocal.empty) { this.applyTransactions([ this.current.update({ changes: toLocal, - annotations: [remoteChange.of(true), Transaction.addToHistory.of(false)], + annotations: [remoteChange.of(true), Transaction.addToHistory.of(undoable)], }), ]); } diff --git a/ui/src/components/editor/extensions.ts b/ui/src/components/editor/extensions.ts index 8093e4c..8ac2a98 100644 --- a/ui/src/components/editor/extensions.ts +++ b/ui/src/components/editor/extensions.ts @@ -13,6 +13,7 @@ import { basicSetup } from "codemirror"; import { languageExtensions, type SYNTAX_CLASS, type SyntaxToken } from "./language"; import { lintExtensions } from "./lint"; import { assistExtensions, type AssistBuffer } from "./assist"; +import { navExtensions } from "./nav/navExtension"; /** * Colours of the highlight classes (`language.ts`), one `--lt-syntax-*` @@ -120,5 +121,6 @@ export function editorExtensions(path = "", buffer?: AssistBuffer): Extension { languageExtensions(path), lintExtensions(path), assistExtensions(path, buffer), + navExtensions(), ]; } diff --git a/ui/src/components/editor/nav/NavLayer.vue b/ui/src/components/editor/nav/NavLayer.vue new file mode 100644 index 0000000..f85ec0b --- /dev/null +++ b/ui/src/components/editor/nav/NavLayer.vue @@ -0,0 +1,29 @@ + + + diff --git a/ui/src/components/editor/nav/NavPicker.vue b/ui/src/components/editor/nav/NavPicker.vue new file mode 100644 index 0000000..5d51f58 --- /dev/null +++ b/ui/src/components/editor/nav/NavPicker.vue @@ -0,0 +1,219 @@ + + + + + diff --git a/ui/src/components/editor/nav/ReferencesToolWindow.vue b/ui/src/components/editor/nav/ReferencesToolWindow.vue new file mode 100644 index 0000000..0d9cdfe --- /dev/null +++ b/ui/src/components/editor/nav/ReferencesToolWindow.vue @@ -0,0 +1,312 @@ + + + + + diff --git a/ui/src/components/editor/nav/RenameInput.vue b/ui/src/components/editor/nav/RenameInput.vue new file mode 100644 index 0000000..a7eabe4 --- /dev/null +++ b/ui/src/components/editor/nav/RenameInput.vue @@ -0,0 +1,168 @@ + + + + + diff --git a/ui/src/components/editor/nav/nav.ts b/ui/src/components/editor/nav/nav.ts new file mode 100644 index 0000000..d8bef49 --- /dev/null +++ b/ui/src/components/editor/nav/nav.ts @@ -0,0 +1,621 @@ +/** + * Navigation and rename through the language server (M3.5). + * + * - **Go to Definition** (`lsp.definition`, F12 or Mod+click): one location + * is revealed at once (`editor.reveal`); several open the location picker + * ({@link NavPicker}, an exclusive modal under the one-modal rule); none + * raises an info toast. + * - **Find References** (`lsp.references`, Shift+F12): the result fills the + * References tab of the bottom panel, grouped by file; a click or Enter + * reveals the use. + * - **Rename** (`lsp.rename`, F2): `lsp.prepareRename` first; a position + * that cannot be renamed raises an info toast. Otherwise an inline field + * over the symbol ({@link RenameInput}) takes the new name and shows how + * many uses will change (from `lsp.references`). Enter applies it, Escape + * cancels. Open buffers become dirty and one undo in each reverts it + * ({@link BufferSync.beginUndoableRemote}); closed files are written by + * the engine, which reports a summary notification. + * + * The engine commands are the ones the keymap and palette list; this store + * supplies their context (buffer id and cursor position) with + * `commands.provide`. Requests go through `runWaiting`, after the active + * buffer's edits reached the engine. Results come from the engine and, + * through it, from Phpactor: they are read defensively. + */ +import type { EditorView } from "@codemirror/view"; +import { defineStore } from "pinia"; +import { computed, ref, shallowRef } from "vue"; +import { useCommandsStore } from "../../../commands/store"; +import { useModalsStore } from "../../../commands/modals"; +import { t } from "../../../i18n"; +import { runWaiting, type EngineError, type JsonValue } from "../../../ipc"; +import { useEditorStore } from "../../../stores/editor"; +import { useNotificationsStore } from "../../../stores/notifications"; +import { positionOf } from "../engineText"; +import { setDefinitionHandler } from "./navExtension"; + +/** The engine commands this store supplies context for. */ +export const NAV_COMMANDS = { + definition: "lsp.definition", + references: "lsp.references", + prepareRename: "lsp.prepareRename", + rename: "lsp.rename", +} as const; + +/** Most locations kept from one answer. */ +export const MAX_LOCATIONS = 10_000; + +/** A 0-based line and UTF-16 column. */ +export interface NavPosition { + /** Line. */ + line: number; + /** Column in UTF-16 code units. */ + column: number; +} + +/** A range in a file. */ +export interface NavRange { + /** Start. */ + start: NavPosition; + /** End (exclusive). */ + end: NavPosition; +} + +/** A location in a project file. */ +export interface NavLocation { + /** Project-relative path with `/`. */ + path: string; + /** The range. */ + range: NavRange; +} + +/** A use found by Find References. */ +export interface ReferenceItem extends NavLocation { + /** Stable key: path and position. */ + key: string; + /** The trimmed line text. */ + preview: string; + /** Column of the range start inside {@link preview}. */ + previewColumn: number; +} + +/** The location picker's state. */ +export interface PickerState { + /** The name the locations belong to, for the title. */ + symbol: string; + /** The locations. */ + items: NavLocation[]; + /** Index of the selected one. */ + selected: number; +} + +/** The inline rename field's state. */ +export interface RenameState { + /** The buffer. */ + id: number; + /** Where the request was made. */ + position: NavPosition; + /** The range of the current name. */ + range: NavRange; + /** The current name. */ + placeholder: string; + /** The typed name. */ + value: string; + /** Uses that change and their files; null while counting or unknown. */ + preview: { uses: number; files: number } | null; + /** Whether the rename runs. */ + busy: boolean; + /** Why the last attempt failed. */ + error: string | null; + /** Where the field goes, in viewport pixels; null without a view. */ + anchor: { left: number; top: number } | null; +} + +/** + * Reads a position; null if malformed. + * + * @param raw - untrusted `{line, column}`. + */ +function toPosition(raw: unknown): NavPosition | null { + if (typeof raw !== "object" || raw === null) { + return null; + } + const { line, column } = raw as Record; + const ok = (n: unknown): n is number => typeof n === "number" && Number.isInteger(n) && n >= 0; + return ok(line) && ok(column) ? { line, column } : null; +} + +/** + * Reads a range; null if malformed. + * + * @param raw - untrusted `{start, end}`. + */ +export function toRange(raw: unknown): NavRange | null { + if (typeof raw !== "object" || raw === null) { + return null; + } + const r = raw as Record; + const start = toPosition(r.start); + const end = toPosition(r.end); + return start && end ? { start, end } : null; +} + +/** + * Reads the `locations` of a definition or references answer. + * + * @param raw - the untrusted command result. + * @returns the well-formed locations, at most {@link MAX_LOCATIONS}. + */ +export function toLocations(raw: unknown): NavLocation[] { + const list = typeof raw === "object" && raw !== null ? (raw as Record).locations : null; + if (!Array.isArray(list)) { + return []; + } + const out: NavLocation[] = []; + for (const entry of list as unknown[]) { + if (out.length >= MAX_LOCATIONS || typeof entry !== "object" || entry === null) { + continue; + } + const e = entry as Record; + const range = toRange(e.range); + if (typeof e.path === "string" && e.path !== "" && range) { + out.push({ path: e.path, range }); + } + } + return out; +} + +/** + * Reads the answer of `lsp.references`. + * + * @param raw - the untrusted command result. + */ +export function toReferences(raw: unknown): ReferenceItem[] { + const list = typeof raw === "object" && raw !== null ? (raw as Record).locations : null; + if (!Array.isArray(list)) { + return []; + } + const out: ReferenceItem[] = []; + for (const entry of list as unknown[]) { + if (out.length >= MAX_LOCATIONS || typeof entry !== "object" || entry === null) { + continue; + } + const e = entry as Record; + const range = toRange(e.range); + if (typeof e.path !== "string" || e.path === "" || !range) { + continue; + } + const preview = typeof e.preview === "string" ? e.preview : ""; + const column = typeof e.previewColumn === "number" && e.previewColumn >= 0 ? e.previewColumn : 0; + const { line, column: start } = range.start; + const key = `${e.path}:${String(line)}:${String(start)}#${String(out.length)}`; + out.push({ path: e.path, range, key, preview, previewColumn: column }); + } + return out; +} + +/** + * Reads the answer of `lsp.prepareRename`. + * + * @param raw - the untrusted command result. + * @returns the range and current name, or null when the position cannot + * be renamed. + */ +export function toRenameable(raw: unknown): { range: NavRange; placeholder: string } | null { + if (typeof raw !== "object" || raw === null) { + return null; + } + const r = raw as Record; + const range = toRange(r.range); + return range && typeof r.placeholder === "string" && r.placeholder !== "" ? { range, placeholder: r.placeholder } : null; +} + +/** + * Number of distinct files among locations. + * + * @param items - the locations. + */ +export function fileCount(items: readonly NavLocation[]): number { + return new Set(items.map((item) => item.path)).size; +} + +/** + * The line and UTF-16 column of a document position. + * + * @param view - the editor view (or anything with its `state.doc`). + * @param pos - the position. + */ +function lineColumn(view: Pick, pos: number): NavPosition { + const line = view.state.doc.lineAt(pos); + return { line: line.number - 1, column: pos - line.from }; +} + +/** The nav store. */ +export const useNavStore = defineStore("nav", () => { + const editor = useEditorStore(); + const commands = useCommandsStore(); + const modals = useModalsStore(); + const notifications = useNotificationsStore(); + + /** The location picker, open while set. */ + const picker = ref(null); + /** The inline rename field, open while set. */ + const rename = ref(null); + + /** Whether the References tab is shown in the bottom panel. */ + const visible = ref(false); + /** Whether the panel is expanded while References is shown. */ + const expanded = ref(true); + /** The name the shown references belong to. */ + const symbol = ref(""); + /** The shown references, sorted by path and position. */ + const references = shallowRef([]); + /** Whether a Find References request runs. */ + const searching = ref(false); + /** Why the last Find References failed. */ + const referencesError = ref(null); + /** Key of the selected reference. */ + const selectedKey = ref(null); + /** Bumped when the References window should take the focus. */ + const focusRequest = ref(0); + /** Whether a focus request waits for the window. */ + const focusPending = ref(false); + + /** Index of the selected reference, -1 if none. */ + const selectedIndex = computed(() => references.value.findIndex((item) => item.key === selectedKey.value)); + + /** + * The active buffer and its cursor, after its edits reached the engine. + * + * @returns the buffer id, the cursor and the name under it, or null + * without an active tab. + */ + async function cursor(): Promise<{ id: number; position: NavPosition; word: string } | null> { + const id = editor.activeId; + const sync = id === null ? undefined : editor.syncOf(id); + if (id === null || !sync) { + return null; + } + await sync.idle(); + const state = sync.state; + const head = state.selection.main.head; + const word = state.wordAt(head); + return { + id, + position: lineColumn({ state }, head), + word: word ? state.sliceDoc(word.from, word.to) : "", + }; + } + + /** + * Shows an engine failure as an error toast. + * + * @param command - the command id. + * @param error - the error. + */ + function fail(command: string, error: EngineError): void { + notifications.notifyError(command, error); + } + + /** + * Reveals a location in the editor. + * + * @param location - the location. + */ + async function reveal(location: NavLocation): Promise { + const { line, column } = location.range.start; + await commands.execute("editor.reveal", { path: location.path, line, column }); + } + + /** Go to Definition at the cursor. */ + async function definition(): Promise { + const at = await cursor(); + if (!at) { + return; + } + const result = await runWaiting(NAV_COMMANDS.definition, { id: at.id, position: { ...at.position } }); + if (!result.ok) { + fail(NAV_COMMANDS.definition, result.error); + return; + } + const items = toLocations(result.value); + const first = items[0]; + if (!first) { + notifications.notify({ level: "info", message: t("nav.definition.none", { name: at.word || "?" }) }); + return; + } + if (items.length === 1) { + await reveal(first); + return; + } + openPicker(at.word, items); + } + + /** + * Opens the location picker. + * + * @param name - the symbol's name, for the title. + * @param items - the locations. + */ + function openPicker(name: string, items: NavLocation[]): void { + modals.opened("navPicker", closePicker); + picker.value = { symbol: name, items, selected: 0 }; + } + + /** Closes the location picker. */ + function closePicker(): void { + picker.value = null; + modals.closed("navPicker"); + } + + /** + * Moves the picker's selection, clamped. + * + * @param delta - rows to move; positive is down. + */ + function movePicker(delta: number): void { + const p = picker.value; + if (!p || p.items.length === 0) { + return; + } + p.selected = Math.min(p.items.length - 1, Math.max(0, p.selected + delta)); + } + + /** + * Reveals a picker entry and closes the picker. + * + * @param index - the entry; the selected one when omitted. + */ + async function choosePicked(index?: number): Promise { + const p = picker.value; + const item = p ? p.items[index ?? p.selected] : undefined; + closePicker(); + if (item) { + await reveal(item); + } + } + + /** Find References at the cursor. */ + async function findReferences(): Promise { + const at = await cursor(); + if (!at) { + return; + } + symbol.value = at.word; + searching.value = true; + referencesError.value = null; + showReferences(); + const result = await runWaiting(NAV_COMMANDS.references, { id: at.id, position: { ...at.position } }); + searching.value = false; + if (!result.ok) { + references.value = []; + referencesError.value = result.error.message; + fail(NAV_COMMANDS.references, result.error); + return; + } + references.value = toReferences(result.value); + selectedKey.value = references.value[0]?.key ?? null; + } + + /** Shows the References tab and asks it to take the focus. */ + function showReferences(): void { + visible.value = true; + expanded.value = true; + focusPending.value = true; + focusRequest.value += 1; + } + + /** Hides the References tab; the results stay. */ + function hide(): void { + visible.value = false; + } + + /** + * Selects a reference. + * + * @param key - its key, or null. + */ + function select(key: string | null): void { + selectedKey.value = key; + } + + /** + * Moves the reference selection, clamped. + * + * @param delta - rows to move; positive is down. + */ + function move(delta: number): void { + const list = references.value; + if (list.length === 0) { + return; + } + const from = selectedIndex.value < 0 ? (delta > 0 ? -1 : list.length) : selectedIndex.value; + selectedKey.value = list[Math.min(list.length - 1, Math.max(0, from + delta))]?.key ?? null; + } + + /** + * Where the rename field goes: over the start of `range` in the active + * view. + * + * @param view - the editor view, if any. + * @param range - the name's range. + */ + function anchorOf(view: EditorView | null, range: NavRange): { left: number; top: number } | null { + if (!view) { + return null; + } + const pos = positionOf(view.state.doc, range.start.line, range.start.column); + const coords = view.coordsAtPos(pos); + return coords ? { left: coords.left, top: coords.top } : null; + } + + /** + * Starts a rename at the cursor: asks the server whether the name can be + * renamed and opens the inline field. + * + * @param view - the editor view to place the field in. + */ + async function startRename(view: EditorView | null): Promise { + const at = await cursor(); + if (!at) { + return; + } + const prepared = await runWaiting(NAV_COMMANDS.prepareRename, { id: at.id, position: { ...at.position } }); + if (!prepared.ok) { + fail(NAV_COMMANDS.prepareRename, prepared.error); + return; + } + const target = toRenameable(prepared.value); + if (!target) { + notifications.notify({ level: "info", message: t("nav.rename.notHere") }); + return; + } + modals.opened("rename", cancelRename); + rename.value = { + id: at.id, + position: at.position, + range: target.range, + placeholder: target.placeholder, + value: target.placeholder, + preview: null, + busy: false, + error: null, + anchor: anchorOf(view, target.range), + }; + void countUses(at.id, at.position); + } + + /** + * Fills the rename field's preview with the number of uses and files. + * + * @param id - the buffer. + * @param position - the symbol's position. + */ + async function countUses(id: number, position: NavPosition): Promise { + const result = await runWaiting(NAV_COMMANDS.references, { id, position: { ...position } }); + const current = rename.value; + if (!result.ok || !current || current.id !== id) { + return; + } + const items = toLocations(result.value); + current.preview = { uses: items.length, files: fileCount(items) }; + } + + /** Closes the rename field without renaming. */ + function cancelRename(): void { + rename.value = null; + modals.closed("rename"); + } + + /** + * Applies the typed name. An unchanged or empty name just closes the + * field. Open buffers take the edit as one undoable step each. + */ + async function commitRename(): Promise { + const current = rename.value; + if (!current || current.busy) { + return; + } + const name = current.value.trim(); + if (name === "" || name === current.placeholder) { + cancelRename(); + return; + } + current.busy = true; + current.error = null; + const syncs = editor.tabs.map((tab) => editor.syncOf(tab.id)).filter((s) => s !== undefined); + for (const sync of syncs) { + sync.beginUndoableRemote(); + } + const params: JsonValue = { id: current.id, position: { ...current.position }, newName: name }; + const result = await runWaiting<{ files?: unknown }>(NAV_COMMANDS.rename, params); + const versions = new Map(); + if (result.ok && Array.isArray(result.value.files)) { + for (const file of result.value.files as unknown[]) { + const f = file as Record | null; + if (typeof f?.bufferId === "number" && typeof f.version === "number") { + versions.set(f.bufferId, f.version); + } + } + } + for (const sync of syncs) { + sync.endUndoableRemote(versions.get(sync.id) ?? null); + } + if (rename.value !== current) { + return; + } + if (!result.ok) { + current.busy = false; + current.error = result.error.message; + return; + } + cancelRename(); + } + + /** Runs Go to Definition at a Mod+click; the cursor is at the click already. */ + function onModClick(): void { + void commands.execute(NAV_COMMANDS.definition); + } + + /** Withdraws the command handlers; filled while started. */ + let withdraw: (() => void)[] = []; + + /** + * Supplies the commands' context and the Mod+click handler. + * + * @param view - returns the active editor view, for placing the rename + * field. + */ + function start(view: () => EditorView | null): void { + if (withdraw.length > 0) { + return; + } + const hasTab = (): boolean => editor.activeId !== null; + withdraw = [ + commands.provide(NAV_COMMANDS.definition, { run: definition, enabled: hasTab }), + commands.provide(NAV_COMMANDS.references, { run: findReferences, enabled: hasTab }), + commands.provide(NAV_COMMANDS.rename, { run: () => startRename(view()), enabled: hasTab }), + ]; + setDefinitionHandler(onModClick); + } + + /** Withdraws everything {@link start} supplied. */ + function stop(): void { + for (const fn of withdraw) { + fn(); + } + withdraw = []; + setDefinitionHandler(null); + } + + return { + picker, + rename, + visible, + expanded, + symbol, + references, + searching, + referencesError, + selectedKey, + selectedIndex, + focusRequest, + focusPending, + definition, + openPicker, + closePicker, + movePicker, + choosePicked, + findReferences, + showReferences, + hide, + select, + move, + reveal, + startRename, + cancelRename, + commitRename, + start, + stop, + }; +}); diff --git a/ui/src/components/editor/nav/navExtension.ts b/ui/src/components/editor/nav/navExtension.ts new file mode 100644 index 0000000..208ff61 --- /dev/null +++ b/ui/src/components/editor/nav/navExtension.ts @@ -0,0 +1,105 @@ +/** + * The editor side of navigation (M3.5): Mod+click on a name runs Go to + * Definition there, and the view showing the active tab is remembered so + * the inline rename field can be placed over the symbol. + * + * The extension knows nothing about the engine: the nav store registers a + * handler with {@link setDefinitionHandler}. `Mod` is Cmd on macOS and + * Ctrl elsewhere, as in the keymap. + */ +import { EditorView, ViewPlugin } from "@codemirror/view"; +import type { Extension } from "@codemirror/state"; +import { isMac } from "../../../commands/keymap"; + +/** Receives the document position of a Mod+click. */ +export type DefinitionHandler = (view: EditorView, pos: number) => void; + +/** The registered handler, or null. */ +let handler: DefinitionHandler | null = null; + +/** The view that showed a buffer last; one view serves every tab. */ +let currentView: EditorView | null = null; + +/** + * Registers what a Mod+click does. + * + * @param next - the handler, or null to remove it. + */ +export function setDefinitionHandler(next: DefinitionHandler | null): void { + handler = next; +} + +/** The editor view showing the active tab, if one is mounted. */ +export function activeView(): EditorView | null { + return currentView; +} + +/** + * Whether a mouse event holds `Mod` and nothing else that changes a click. + * + * @param event - the mouse event. + * @param mac - whether `Mod` means Cmd. + */ +export function isModClick(event: MouseEvent, mac: boolean): boolean { + const mod = mac ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey; + return event.button === 0 && mod && !event.altKey && !event.shiftKey; +} + +/** Remembers the view while it exists. */ +const trackView = ViewPlugin.define((view) => { + currentView = view; + return { + destroy(): void { + if (currentView === view) { + currentView = null; + } + }, + }; +}); + +/** Mod+click: moves the cursor to the click and asks for the definition. */ +const modClick = EditorView.domEventHandlers({ + mousedown(event, view) { + if (!handler || !isModClick(event, isMac())) { + return false; + } + const pos = view.posAtCoords({ x: event.clientX, y: event.clientY }); + if (pos === null) { + return false; + } + event.preventDefault(); + view.dispatch({ selection: { anchor: pos }, userEvent: "select.pointer" }); + handler(view, pos); + return true; + }, +}); + +/** A pointer cursor over the text while `Mod` is held, hinting at Mod+click. */ +const modCursor = EditorView.theme({ + "&.lt-nav-mod .cm-content": { cursor: "pointer" }, +}); + +/** Toggles {@link modCursor}'s class with the modifier key. */ +const modTracker = EditorView.domEventHandlers({ + keydown(event, view) { + if (event.key === (isMac() ? "Meta" : "Control")) { + view.dom.classList.add("lt-nav-mod"); + } + return false; + }, + keyup(event, view) { + if (event.key === (isMac() ? "Meta" : "Control")) { + view.dom.classList.remove("lt-nav-mod"); + } + return false; + }, + blur(_event, view) { + view.dom.classList.remove("lt-nav-mod"); + return false; + }, +}); + +/** The navigation extensions of an editor state. */ +export function navExtensions(): Extension { + return [trackView, modClick, modCursor, modTracker]; +} diff --git a/ui/src/components/layout/MainLayout.vue b/ui/src/components/layout/MainLayout.vue index 8a60f50..44a6d83 100644 --- a/ui/src/components/layout/MainLayout.vue +++ b/ui/src/components/layout/MainLayout.vue @@ -24,7 +24,9 @@ * The panel collapses to its header; closing it hides the active tool * window (another shown one becomes active). The Find store keeps the * results, the Terminal store the running terminals and the Problems store - * the diagnostics while they are hidden. + * the diagnostics while they are hidden. The References tab (M3.5) shows + * when Find References runs (`lsp.references`); the nav store keeps its + * results. * * A slim header bar along the top (M3.9) holds the app menu * ({@link AppMenu}); its `header` slot can replace it. @@ -39,6 +41,8 @@ import FindToolWindow from "../find/FindToolWindow.vue"; import TerminalToolWindow from "../terminal/TerminalToolWindow.vue"; import ProblemsToolWindow from "../problems/ProblemsToolWindow.vue"; import { useProblemsStore } from "../problems/problems"; +import ReferencesToolWindow from "../editor/nav/ReferencesToolWindow.vue"; +import { useNavStore } from "../editor/nav/nav"; import ProjectToolWindow from "../project/ProjectToolWindow.vue"; import StatusBar from "../StatusBar.vue"; import StructureToolWindow from "../structure/StructureToolWindow.vue"; @@ -84,9 +88,10 @@ const commands = useCommandsStore(); const find = useFindStore(); const terminal = useTerminalStore(); const problems = useProblemsStore(); +const nav = useNavStore(); /** Tool windows of the bottom panel. */ -type BottomTool = "find" | "terminal" | "problems"; +type BottomTool = "find" | "terminal" | "problems" | "references"; /** The bottom tool window last chosen. */ const bottomTool = ref("find"); /** Bottom tool windows that are shown, in tab order. */ @@ -95,6 +100,7 @@ const bottomTools = computed(() => { if (find.visible) tools.push({ id: "find", title: t("find.toolWindow.title") }); if (terminal.visible) tools.push({ id: "terminal", title: t("terminal.toolWindow.title") }); if (problems.visible) tools.push({ id: "problems", title: t("problems.toolWindow.title") }); + if (nav.visible) tools.push({ id: "references", title: t("nav.references.title") }); return tools; }); /** The active bottom tool window: the chosen one if shown, else the first. */ @@ -104,7 +110,13 @@ const bottomActive = computed(() => { }); /** The store of the active bottom tool window. */ const bottomStore = computed(() => - bottomActive.value === "terminal" ? terminal : bottomActive.value === "problems" ? problems : find, + bottomActive.value === "terminal" + ? terminal + : bottomActive.value === "problems" + ? problems + : bottomActive.value === "references" + ? nav + : find, ); /** Expansion of the panel, kept per tool window by its store. */ const bottomOpen = computed({ @@ -120,7 +132,7 @@ const bottomOpen = computed({ * @param id - the tool window id from the panel. */ function chooseBottom(id: string): void { - if (id === "find" || id === "terminal" || id === "problems") { + if (id === "find" || id === "terminal" || id === "problems" || id === "references") { bottomTool.value = id; } } @@ -250,6 +262,7 @@ onBeforeUnmount(() => { v-show="bottomActive === 'terminal'" /> + diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json index 17b8728..c7d682c 100644 --- a/ui/src/i18n/en.json +++ b/ui/src/i18n/en.json @@ -108,9 +108,24 @@ "menu.group.help": "Help", "menu.group.view": "View", "menu.label": "Main menu", + "nav.definition.none": "No definition found for {name}", + "nav.picker.line": "line {line}", + "nav.picker.title": "Definitions of {name}", + "nav.references.failed": "Find References failed: {message}", + "nav.references.label": "References", + "nav.references.none": "No references to {name} found", + "nav.references.searching": "Searching references to {name}…", + "nav.references.summary": "{uses} references to {name} in {files} files", + "nav.references.title": "References", + "nav.rename.busy": "Renaming…", + "nav.rename.counting": "Counting uses…", + "nav.rename.label": "New name for {name}", + "nav.rename.notHere": "There is nothing to rename at the cursor", + "nav.rename.preview": "Changes {uses} uses in {files} files. Enter to rename, Escape to cancel", "notification.close": "Close notification", "notification.command.failed": "{command} failed: {message}", "notification.lsp.failed": "The PHP language server stopped: {reason}. Run Restart PHP Language Server to try again.", + "notification.lsp.renamed": "Renamed to {name}: {edits} changes in {files} files ({written} closed files saved)", "notification.project.notLocal": "The chosen folder is not on this computer: {reason}", "notification.project.openFailed": "Cannot open {path}: {reason}", "notification.project.unsavedChanges": "Cannot open {path} while {what} has unsaved changes. Save or close it first.", diff --git a/ui/tests/i18n/catalog.test.ts b/ui/tests/i18n/catalog.test.ts index 27a3743..0e5c59f 100644 --- a/ui/tests/i18n/catalog.test.ts +++ b/ui/tests/i18n/catalog.test.ts @@ -49,6 +49,7 @@ const usedKeys = sourceFiles(SRC).flatMap((file) => const RUNTIME_KEYS = new Set([ "notification.command.failed", "notification.lsp.failed", + "notification.lsp.renamed", "notification.project.notLocal", "notification.project.openFailed", "notification.project.unsavedChanges", @@ -141,7 +142,7 @@ describe("en.json", () => { it("uses flat dotted keys of known areas with string values", () => { for (const [key, value] of Object.entries(en)) { expect(key).toMatch( - /^(app|command|project|editor|common|palette|theme|recovery|notification|settings|find|goto|structure|menu|terminal|problems)\.[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$/, + /^(app|command|project|editor|common|palette|theme|recovery|notification|settings|find|goto|structure|menu|terminal|problems|nav)\.[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$/, ); expect(typeof value).toBe("string"); expect(value.trim()).not.toBe(""); diff --git a/ui/tests/nav/nav.test.ts b/ui/tests/nav/nav.test.ts new file mode 100644 index 0000000..3134282 --- /dev/null +++ b/ui/tests/nav/nav.test.ts @@ -0,0 +1,354 @@ +/** + * Tests of navigation (M3.5): reading untrusted answers, Go to Definition + * (one location reveals, several open the picker, none raises a toast), + * the picker (keyboard, click, Escape, modal rule), the References tab + * (status, grouping, click and Enter reveal), the inline rename (prepare, + * preview count, Enter applies, errors stay in the field, Escape cancels) + * and the undoable remote edit of the buffer sync. The engine is a fake + * behind the mocked Tauri `invoke` and `listen`. + */ +import { Transaction } from "@codemirror/state"; +import { flushPromises, mount, type VueWrapper } from "@vue/test-utils"; +import { createPinia, setActivePinia, type Pinia } from "pinia"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const invoke = vi.hoisted(() => vi.fn()); +const listen = vi.hoisted(() => vi.fn()); +vi.mock("@tauri-apps/api/core", () => ({ invoke })); +vi.mock("@tauri-apps/api/event", () => ({ listen })); + +import { useCommandsStore } from "../../src/commands/store"; +import { useModalsStore } from "../../src/commands/modals"; +import { BufferSync, type BufferInfo, type SyncTransport } from "../../src/components/editor/bufferSync"; +import NavPicker from "../../src/components/editor/nav/NavPicker.vue"; +import ReferencesToolWindow from "../../src/components/editor/nav/ReferencesToolWindow.vue"; +import RenameInput from "../../src/components/editor/nav/RenameInput.vue"; +import { + fileCount, + toLocations, + toReferences, + toRenameable, + useNavStore, +} from "../../src/components/editor/nav/nav"; +import { useEditorStore } from "../../src/stores/editor"; +import { useNotificationsStore } from "../../src/stores/notifications"; + +/** Every engine call, in order. */ +let calls: { command: string; params: Record }[]; +/** Answers by command id; a function gets the params. */ +let answers: Record; +/** Pinia of the current test. */ +let pinia: Pinia; +/** Mounted components. */ +let mounted: VueWrapper[]; +/** Params of every `editor.reveal`. */ +let reveals: unknown[]; + +const TEXT = " { + return { start: { line, column: from }, end: { line, column: to } }; +} + +/** The params of every call of a command. */ +function paramsOf(command: string): Record[] { + return calls.filter((c) => c.command === command).map((c) => c.params); +} + +/** Opens `a.php` as the active tab with the cursor on `hello`. */ +async function openTab(): Promise { + const editor = useEditorStore(); + answers["file.open"] = { id: 7, path: "a.php", text: TEXT, version: 1, dirty: false, lineEnding: "lf" }; + await editor.openFile("a.php"); + editor.syncOf(7)?.dispatch({ selection: { anchor: TEXT.indexOf("hello") + 2 } }); +} + +/** + * Mounts a component with the test's pinia. + * + * @param component - the component. + */ +function mountIt(component: Parameters[0]): VueWrapper { + const wrapper = mount(component, { attachTo: document.body, global: { plugins: [pinia] } }); + mounted.push(wrapper); + return wrapper; +} + +beforeEach(() => { + pinia = createPinia(); + setActivePinia(pinia); + calls = []; + answers = {}; + mounted = []; + reveals = []; + Element.prototype.scrollIntoView = () => undefined; + invoke.mockReset(); + listen.mockReset(); + listen.mockResolvedValue(() => undefined); + invoke.mockImplementation((cmd: string, args?: { command: string; params: Record }) => { + if (cmd === "engine_list_commands") { + return Promise.resolve([]); + } + if ((cmd !== "engine_execute" && cmd !== "engine_execute_waiting") || !args) { + return Promise.resolve(null); + } + calls.push({ command: args.command, params: args.params }); + const answer = answers[args.command]; + if (answer instanceof Error) { + return Promise.reject(Object.assign(new Error(answer.message), { code: "failed" })); + } + return Promise.resolve(typeof answer === "function" ? (answer as (p: unknown) => unknown)(args.params) : (answer ?? null)); + }); + useCommandsStore().provide("editor.reveal", { run: (params) => void reveals.push(params) }); + useNavStore().start(() => null); +}); + +afterEach(() => { + for (const wrapper of mounted) { + wrapper.unmount(); + } + useNavStore().stop(); +}); + +describe("reading answers", () => { + it("drops malformed locations and counts files", () => { + const items = toLocations({ + locations: [ + { path: "a.php", range: range(1, 2, 3) }, + { path: "", range: range(0, 0, 1) }, + { path: "b.php", range: { start: { line: -1, column: 0 }, end: { line: 0, column: 0 } } }, + { path: "b.php", range: range(4, 0, 2) }, + "junk", + ], + }); + expect(items.map((i) => i.path)).toEqual(["a.php", "b.php"]); + expect(fileCount(items)).toBe(2); + expect(toLocations(null)).toEqual([]); + const refs = toReferences({ locations: [{ path: "a.php", range: range(2, 4, 9), preview: "$g->hello();", previewColumn: 4 }] }); + expect(refs[0]?.preview).toBe("$g->hello();"); + expect(toRenameable(null)).toBeNull(); + expect(toRenameable({ range: range(2, 20, 25), placeholder: "hello" })?.placeholder).toBe("hello"); + expect(toRenameable({ range: range(2, 20, 25), placeholder: "" })).toBeNull(); + }); +}); + +describe("go to definition", () => { + it("reveals a single location at once, with the cursor position", async () => { + await openTab(); + answers["lsp.definition"] = { locations: [{ path: "src/G.php", range: range(3, 6, 11) }] }; + await useCommandsStore().execute("lsp.definition"); + await flushPromises(); + expect(paramsOf("lsp.definition")).toEqual([{ id: 7, position: { line: 2, column: 22 } }]); + expect(reveals).toEqual([{ path: "src/G.php", line: 3, column: 6 }]); + expect(useNavStore().picker).toBeNull(); + }); + + it("opens the picker for several locations; Enter reveals the selected one", async () => { + await openTab(); + answers["lsp.definition"] = { + locations: [ + { path: "a.php", range: range(2, 20, 25) }, + { path: "lib/b.php", range: range(9, 4, 9) }, + ], + }; + const wrapper = mountIt(NavPicker); + await useNavStore().definition(); + await flushPromises(); + expect(useModalsStore().current).toBe("navPicker"); + const rows = wrapper.findAll("[data-test=nav-picker-row]"); + expect(rows.map((r) => r.text())).toEqual(["a.phpline 3", "b.phplibline 10"]); + const list = wrapper.find("[data-test=nav-picker-list]"); + await list.trigger("keydown", { key: "ArrowDown" }); + await list.trigger("keydown", { key: "Enter" }); + await flushPromises(); + expect(reveals).toEqual([{ path: "lib/b.php", line: 9, column: 4 }]); + expect(wrapper.find("[data-test=nav-picker]").exists()).toBe(false); + expect(useModalsStore().current).toBeNull(); + }); + + it("closes the picker with Escape and when another modal opens", async () => { + const nav = useNavStore(); + const wrapper = mountIt(NavPicker); + nav.openPicker("x", [ + { path: "a.php", range: { start: { line: 0, column: 0 }, end: { line: 0, column: 1 } } }, + { path: "b.php", range: { start: { line: 0, column: 0 }, end: { line: 0, column: 1 } } }, + ]); + await flushPromises(); + await wrapper.find("[data-test=nav-picker-list]").trigger("keydown", { key: "Escape" }); + expect(nav.picker).toBeNull(); + nav.openPicker("x", []); + useModalsStore().opened("palette", () => undefined); + expect(nav.picker).toBeNull(); + expect(reveals).toEqual([]); + }); + + it("tells the user when there is no definition", async () => { + await openTab(); + answers["lsp.definition"] = { locations: [] }; + await useNavStore().definition(); + await flushPromises(); + const toasts = useNotificationsStore().toasts; + expect(toasts.map((t) => t.text)).toEqual(["No definition found for hello"]); + }); + + it("raises an error toast when the server fails", async () => { + await openTab(); + answers["lsp.definition"] = new Error("the PHP language server is not running"); + await useNavStore().definition(); + await flushPromises(); + expect(useNotificationsStore().toasts[0]?.level).toBe("error"); + }); +}); + +describe("references", () => { + it("fills the References tab grouped by file; click and Enter reveal", async () => { + await openTab(); + answers["lsp.references"] = { + locations: [ + { path: "a.php", range: range(2, 20, 25), preview: "public function hello() {}", previewColumn: 16 }, + { path: "src/b.php", range: range(2, 4, 9), preview: "$g->hello();", previewColumn: 4 }, + { path: "src/b.php", range: range(5, 4, 9), preview: "$h->hello();", previewColumn: 4 }, + ], + }; + const nav = useNavStore(); + const wrapper = mountIt(ReferencesToolWindow); + await useCommandsStore().execute("lsp.references"); + await flushPromises(); + expect(nav.visible).toBe(true); + expect(wrapper.find("[data-test=references-status]").text()).toBe("3 references to hello in 2 files"); + expect(wrapper.findAll("[data-test=references-file]").map((f) => f.text())).toEqual(["a.php1", "b.phpsrc2"]); + const rows = wrapper.findAll("[data-test=references-row]"); + expect(rows[1]?.find("mark").text()).toBe("hello"); + await rows[2]?.trigger("click"); + expect(reveals).toEqual([{ path: "src/b.php", line: 5, column: 4 }]); + const list = wrapper.find("[data-test=references-list]"); + await list.trigger("keydown", { key: "Home" }); + await list.trigger("keydown", { key: "Enter" }); + expect(reveals[1]).toEqual({ path: "a.php", line: 2, column: 20 }); + }); + + it("shows a failure in the status line", async () => { + await openTab(); + answers["lsp.references"] = new Error("timed out"); + const wrapper = mountIt(ReferencesToolWindow); + await useNavStore().findReferences(); + await flushPromises(); + expect(wrapper.find("[data-test=references-status]").text()).toBe("Find References failed: timed out"); + }); +}); + +describe("rename", () => { + it("prepares, previews the uses and applies the new name", async () => { + await openTab(); + answers["lsp.prepareRename"] = { range: range(2, 20, 25), placeholder: "hello" }; + answers["lsp.references"] = { + locations: [ + { path: "a.php", range: range(2, 20, 25) }, + { path: "b.php", range: range(2, 4, 9) }, + { path: "c.php", range: range(2, 4, 9) }, + ], + }; + answers["lsp.rename"] = { files: [{ path: "a.php", edits: 1, bufferId: 7, version: 2 }], edits: 3, written: 2 }; + const wrapper = mountIt(RenameInput); + await useCommandsStore().execute("lsp.rename"); + await flushPromises(); + expect(useModalsStore().current).toBe("rename"); + const input = wrapper.find("[data-test=rename-input]"); + expect(input.element.value).toBe("hello"); + expect(wrapper.find("[data-test=rename-hint]").text()).toBe( + "Changes 3 uses in 3 files. Enter to rename, Escape to cancel", + ); + await input.setValue("greet"); + await input.trigger("keydown", { key: "Enter" }); + await flushPromises(); + expect(paramsOf("lsp.rename")).toEqual([{ id: 7, position: { line: 2, column: 22 }, newName: "greet" }]); + expect(wrapper.find("[data-test=rename]").exists()).toBe(false); + expect(useModalsStore().current).toBeNull(); + }); + + it("keeps the field open with the error when the rename fails", async () => { + await openTab(); + answers["lsp.prepareRename"] = { range: range(2, 20, 25), placeholder: "hello" }; + answers["lsp.references"] = { locations: [] }; + answers["lsp.rename"] = new Error("the edit changes /x.php, which is outside the project"); + const wrapper = mountIt(RenameInput); + await useNavStore().startRename(null); + await flushPromises(); + const input = wrapper.find("[data-test=rename-input]"); + await input.setValue("greet"); + await input.trigger("keydown", { key: "Enter" }); + await flushPromises(); + expect(wrapper.find("[data-test=rename-hint]").text()).toContain("outside the project"); + await input.trigger("keydown", { key: "Escape" }); + expect(useNavStore().rename).toBeNull(); + }); + + it("tells the user when nothing can be renamed, and skips an unchanged name", async () => { + await openTab(); + answers["lsp.prepareRename"] = null; + await useNavStore().startRename(null); + await flushPromises(); + expect(useNavStore().rename).toBeNull(); + expect(useNotificationsStore().toasts.map((t) => t.text)).toEqual(["There is nothing to rename at the cursor"]); + answers["lsp.prepareRename"] = { range: range(2, 20, 25), placeholder: "hello" }; + await useNavStore().startRename(null); + await flushPromises(); + await useNavStore().commitRename(); + expect(paramsOf("lsp.rename")).toEqual([]); + expect(useNavStore().rename).toBeNull(); + }); +}); + +describe("undoable remote edits", () => { + it("puts an engine edit made during a rename into the undo history", async () => { + let engineText = " { + sent.push(params); + version += 1; + return Promise.resolve({ ok: true, value: { id: 1, version, dirty: true } }); + }, + get: () => + Promise.resolve({ + ok: true, + value: { id: 1, path: "a.php", text: engineText, version, dirty: true, lineEnding: "lf" } satisfies BufferInfo, + }), + }; + const sync = new BufferSync( + { id: 1, path: "a.php", text: engineText, version: 1, dirty: false, lineEnding: "lf" }, + [], + transport, + ); + const history: (boolean | undefined)[] = []; + const apply = sync.applyTransactions.bind(sync); + sync.applyTransactions = (transactions) => { + history.push(...transactions.map((tr) => tr.annotation(Transaction.addToHistory))); + apply(transactions); + }; + sync.beginUndoableRemote(); + engineText = "