M3.5: go to definition, find references and rename through Phpactor

Engine (`cmd/lsp_nav.rs`, on the pending outcomes of 20d1d28):
- `lsp.definition` (F12) and `lsp.references` (Shift+F12, sorted, with
  line previews) return project-relative locations; locations outside
  the project, such as PHAR stubs and symlink escapes, are dropped.
- `lsp.prepareRename` uses the word at the cursor when the server has
  no prepareProvider.
- `lsp.rename` (F2) applies the workspace edit (`lsp_nav/edit.rs`):
  1. Check everything first: inside the project, ranges fit (UTF-16,
     CRLF), open buffers unchanged since the request, no file
     operations, no incomplete edit.
  2. Write closed files atomically through the VFS, restoring earlier
     writes when a later one fails.
  3. Change open buffers through `buffer.edit` (dirty, undoable).
  4. Send each written file to Phpactor as didOpen/didSave/didClose
     plus didChangeWatchedFiles; without this its index kept the old
     names. Then the summary notification `notification.lsp.renamed`.

UI (`components/editor/nav/`):
- Mod+click goes to the definition, with a pointer cursor while Mod is
  held.
- A location picker for several definitions (exclusive modal).
- A References tab in the bottom panel, grouped by file.
- An inline rename field with a use/file count (exclusive modal).
- `BufferSync.beginUndoableRemote` puts the engine's rename edit into
  the editor history as one undo step per buffer.
- Catalog strings and tokens only.

Fake LSP server: `--script FILE` with scripted capabilities and
answers (additive next to M3.4's arms).

Tests:
- `crates/engine/tests/lsp_nav.rs` (fake): definition; bad positions;
  references; prepareRename; a multi-file rename incl. a closed CRLF
  file; refusals for outside the project, a bad range, a stale buffer,
  bad names and no server.
- The ignored real-Phpactor test covers definition, references and a
  rename and back across 3 files.
- Vitest `ui/tests/nav/`.

Live (Phpactor 2026.06.25.0, Windows, port 7935, tick on):
- definition 93 ms cold / 7-18 ms warm
- references ~140 ms
- prepareRename ~11 ms
- rename 28-59 ms
- index follows written files in 140 ms
- Phpactor 57 MB working set, ~1.6% of a core while ticking idle

Gate: 13 steps, 197 s, Vitest 484 + 1 skipped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-22 18:50:15 +02:00
parent b3fd7c6478
commit 578160a2ba
28 changed files with 3730 additions and 34 deletions

View file

@ -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,

View file

@ -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% |

View file

@ -221,6 +221,7 @@ fn engine_execute_waiting(
) -> Result<Value, ErrorPayload> {
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<Host>>) -> Vec<CommandInfo> {

View file

@ -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<Target, EngineError> {
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<mpsc::Receiver<Result<Value, LspError>>, 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<Map<String, Value>, 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<Value, LspError>>) -> Result<Value, EngineError> {
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<NavLocation> {
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<PathBuf> {
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<PathBuf> {
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<Outcome, EngineError> {
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<Outcome, EngineError> {
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<NavLocation>) -> Vec<Value> {
let mut texts: BTreeMap<String, Option<Buffer>> = 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<String> {
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<Renameable> {
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<Renameable> {
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<Outcome, EngineError> {
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<Outcome, EngineError> {
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<BufferId, u64> = 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<Value> = 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("<?php\n$foo = bar_baz(1);\n");
let w = word_at(&buffer, at(1, 2)).unwrap();
assert_eq!(w.placeholder, "$foo");
assert_eq!((w.range.start.column, w.range.end.column), (0, 4));
let w = word_at(&buffer, at(1, 7)).unwrap();
assert_eq!(w.placeholder, "bar_baz");
let w = word_at(&buffer, at(1, 14)).unwrap();
assert_eq!(w.placeholder, "bar_baz", "cursor right after the name");
assert!(word_at(&buffer, at(1, 16)).is_none(), "a number");
assert!(word_at(&buffer, at(1, 5)).is_none(), "a space");
}
#[test]
fn reads_prepare_rename_answers() {
let buffer = Buffer::new("<?php\nfunction hello() {}\n");
let range =
json!({"start": {"line": 1, "character": 9}, "end": {"line": 1, "character": 14}});
let r = renameable(Some(&buffer), at(1, 10), &range).unwrap();
assert_eq!(r.placeholder, "hello");
let r = renameable(
Some(&buffer),
at(1, 10),
&json!({"range": range, "placeholder": "x"}),
)
.unwrap();
assert_eq!(r.placeholder, "x");
let r = renameable(Some(&buffer), at(1, 10), &json!({"defaultBehavior": true})).unwrap();
assert_eq!(r.placeholder, "hello");
assert!(renameable(Some(&buffer), at(1, 10), &Value::Null).is_none());
}
#[test]
fn previews_trim_the_line() {
let buffer = Buffer::new("<?php\n $a->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());
}
}

View file

@ -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<BufferId>,
/// The buffer's version after the edit.
#[serde(skip_serializing_if = "Option::is_none")]
pub version: Option<u64>,
}
/// 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<FileChange>,
/// 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<BufferId, u64>,
) -> Result<Applied, EngineError> {
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<String> {
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<BufferId, u64>,
) -> Result<Vec<(PathBuf, Planned, usize)>, 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<PathBuf, Vec<&lutra_lsp::TextEdit>> = 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<Vec<Edit>, 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"
))
}

View file

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

View file

@ -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",

View file

@ -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<Value> {
let deadline = Instant::now() + Duration::from_secs(20);
let mut seen = Vec::new();
while Instant::now() < deadline {
let mut hit = false;
for event in 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<Value>), EngineError> {
let mut out: Outcome = self.engine.execute(command, params)?;
let mut events: Vec<Value> = 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 = "<?php\nclass Greeter {\n public function hello() {}\n}\n";
const B: &str = "<?php\n$g = new Greeter();\n$g->hello();\n";
const C: &str = "<?php\r\n// call\r\n$x->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>) -> 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"],
"<?php\nclass Greeter {\n public function greet() {}\n}\n"
);
assert_eq!(
buffer["dirty"], true,
"the open buffer is changed, not saved"
);
assert_eq!(fs::read_to_string(f.path("a.php")).unwrap(), A);
assert_eq!(
fs::read_to_string(f.path("sub/b.php")).unwrap(),
"<?php\n$g = new Greeter();\n$g->greet();\n"
);
assert_eq!(
fs::read_to_string(f.path("c.php")).unwrap(),
"<?php\r\n// call\r\n$x->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=<phar> [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"),
"<?php\n\nnamespace App;\n\nclass Greeter\n{\n public function hello(string $name): string\n {\n return \"Hello {$name}\";\n }\n}\n",
)
.unwrap();
fs::write(
src.join("App.php"),
"<?php\n\nnamespace App;\n\nclass App\n{\n public function run(): string\n {\n $greeter = new Greeter();\n return $greeter->hello('Lutra');\n }\n}\n",
)
.unwrap();
fs::write(
src.join("Other.php"),
"<?php\r\n\r\nnamespace App;\r\n\r\nfunction welcome(Greeter $g): string\r\n{\r\n return $g->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(),
"<?php\r\n\r\nnamespace App;\r\n\r\nfunction welcome(Greeter $g): string\r\n{\r\n return $g->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}");
}

View file

@ -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)),

View file

@ -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=<phar>`.
- 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` |

View file

@ -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) |

View file

@ -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

View file

@ -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 |

File diff suppressed because one or more lines are too long

View file

@ -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(() => {
<CommandPalette />
<GotoPopup />
<SettingsDialog />
<NavLayer />
<NotificationStack />
</template>

View file

@ -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", () => {

View file

@ -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<void> {
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)],
}),
]);
}

View file

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

View file

@ -0,0 +1,29 @@
<script setup lang="ts">
/**
* Mounts the navigation overlays (M3.5), the location picker and the
* inline rename field, and starts the nav store, which supplies the
* context of `lsp.definition`, `lsp.references` and `lsp.rename` and the
* Mod+click handler. The References tab lives in the bottom panel
* (`MainLayout.vue`).
*/
import { onBeforeUnmount, onMounted } from "vue";
import { activeView } from "./navExtension";
import { useNavStore } from "./nav";
import NavPicker from "./NavPicker.vue";
import RenameInput from "./RenameInput.vue";
const nav = useNavStore();
onMounted(() => {
nav.start(activeView);
});
onBeforeUnmount(() => {
nav.stop();
});
</script>
<template>
<NavPicker />
<RenameInput />
</template>

View file

@ -0,0 +1,219 @@
<script setup lang="ts">
/**
* The location picker of Go to Definition (M3.5): shown when the language
* server reports several declarations. Each row has the file name, its
* directory and the 1-based line. Up/Down, Page Up/Down, Home and End move
* the selection; Enter or a click reveals it; Escape or a click outside
* closes the picker. An exclusive modal (the one-modal rule, `modals.ts`).
*/
import { FileCode } from "@lucide/vue";
import { nextTick, ref, watch } from "vue";
import { t } from "../../../i18n";
import { baseName } from "../../../stores/editor";
import { useNavStore, type NavLocation } from "./nav";
const nav = useNavStore();
/** The list element, which holds the focus. */
const list = ref<HTMLElement | null>(null);
/** Rows moved by Page Up and Page Down. */
const PAGE = 10;
/**
* The directory part of a path, empty at the root.
*
* @param path - project-relative path.
*/
function dirName(path: string): string {
const slash = path.lastIndexOf("/");
return slash < 0 ? "" : path.slice(0, slash);
}
/**
* The 1-based line of a location, for people.
*
* @param item - the location.
*/
function lineOf(item: NavLocation): string {
return t("nav.picker.line", { line: String(item.range.start.line + 1) });
}
/**
* Keyboard handling of the list.
*
* @param event - the key press.
*/
function onKeydown(event: KeyboardEvent): void {
const count = nav.picker?.items.length ?? 0;
const moves: Record<string, number> = {
ArrowDown: 1,
ArrowUp: -1,
PageDown: PAGE,
PageUp: -PAGE,
Home: -count,
End: count,
};
const delta = moves[event.key];
if (delta !== undefined) {
nav.movePicker(delta);
scrollSelected();
} else if (event.key === "Enter") {
void nav.choosePicked();
} else if (event.key === "Escape") {
nav.closePicker();
} else {
return;
}
event.preventDefault();
event.stopPropagation();
}
/** Keeps the selected row in view. */
function scrollSelected(): void {
void nextTick(() => {
const row = list.value?.querySelector<HTMLElement>(`#lt-nav-pick-${String(nav.picker?.selected ?? 0)}`);
if (row && typeof row.scrollIntoView === "function") {
row.scrollIntoView({ block: "nearest" });
}
});
}
watch(
() => nav.picker !== null,
(open) => {
if (open) {
void nextTick(() => list.value?.focus());
}
},
);
</script>
<template>
<div
v-if="nav.picker"
class="nav-picker"
data-test="nav-picker"
@mousedown.self.prevent="nav.closePicker()"
>
<div
class="nav-picker__dialog"
role="dialog"
aria-modal="true"
:aria-label="t('nav.picker.title', { name: nav.picker.symbol })"
>
<p class="nav-picker__title">
{{ t("nav.picker.title", { name: nav.picker.symbol }) }}
</p>
<ul
ref="list"
class="nav-picker__list"
role="listbox"
tabindex="0"
:aria-label="t('nav.picker.title', { name: nav.picker.symbol })"
:aria-activedescendant="`lt-nav-pick-${String(nav.picker.selected)}`"
data-test="nav-picker-list"
@keydown="onKeydown"
>
<li
v-for="(item, index) in nav.picker.items"
:id="`lt-nav-pick-${String(index)}`"
:key="`${item.path}:${String(item.range.start.line)}:${String(item.range.start.column)}`"
class="nav-picker__row"
:class="{ 'nav-picker__row--selected': index === nav.picker.selected }"
role="option"
:aria-selected="index === nav.picker.selected"
data-test="nav-picker-row"
@mousemove="nav.picker.selected = index"
@mousedown.prevent
@click="nav.choosePicked(index)"
>
<FileCode
class="nav-picker__icon"
:size="14"
aria-hidden="true"
/>
<span class="nav-picker__name">{{ baseName(item.path) }}</span>
<span class="nav-picker__dir">{{ dirName(item.path) }}</span>
<span class="nav-picker__line">{{ lineOf(item) }}</span>
</li>
</ul>
</div>
</div>
</template>
<style scoped>
.nav-picker {
position: fixed;
inset: 0;
display: flex;
align-items: flex-start;
justify-content: center;
padding-top: 12vh;
background: color-mix(in srgb, var(--lt-bg) 40%, transparent);
z-index: 30;
}
.nav-picker__dialog {
width: min(560px, 90vw);
max-height: 60vh;
display: flex;
flex-direction: column;
background: var(--lt-bg);
color: var(--lt-fg);
border: 1px solid var(--lt-border);
border-radius: var(--lt-radius, 4px);
overflow: hidden;
}
.nav-picker__title {
margin: 0;
padding: var(--lt-space-s, 4px) var(--lt-space-m, 8px);
font-weight: 600;
border-bottom: 1px solid var(--lt-border);
}
.nav-picker__list {
margin: 0;
padding: var(--lt-space-s, 4px) 0;
list-style: none;
overflow-y: auto;
outline: none;
}
.nav-picker__row {
display: flex;
align-items: center;
gap: var(--lt-space-m, 8px);
padding: 3px var(--lt-space-m, 8px);
white-space: nowrap;
cursor: default;
}
.nav-picker__row--selected {
background: var(--lt-editor-selection-bg);
}
.nav-picker__icon {
flex-shrink: 0;
color: var(--lt-fg-muted);
}
.nav-picker__dir {
flex: 1;
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
color: var(--lt-fg-muted);
}
.nav-picker__line {
flex-shrink: 0;
color: var(--lt-fg-muted);
}
.nav-picker__row--selected .nav-picker__dir,
.nav-picker__row--selected .nav-picker__line {
color: var(--lt-fg);
}
</style>

View file

@ -0,0 +1,312 @@
<script setup lang="ts">
/**
* The References tool window (M3.5), a tab of the bottom panel: the uses
* Find References found, grouped by file.
*
* - **Header line:** the symbol and the count, "Searching…" while the
* request runs, or the failure.
* - **List:** one group per file (name, directory, count), then its uses
* with the 1-based line and the line text, the name highlighted.
* Up/Down, Page Up/Down, Home and End move the selection; Enter or a
* click reveals the use through `editor.reveal`.
* - State lives in the nav store, so it is kept while the tab is hidden.
*/
import { computed, nextTick, onMounted, ref, watch } from "vue";
import { t } from "../../../i18n";
import { baseName } from "../../../stores/editor";
import { useNavStore, type ReferenceItem } from "./nav";
const nav = useNavStore();
/** The list element. */
const list = ref<HTMLElement | null>(null);
/** Rows moved by Page Up and Page Down. */
const PAGE = 10;
/** The line above the list. */
const status = computed(() => {
if (nav.searching) {
return t("nav.references.searching", { name: nav.symbol });
}
if (nav.referencesError !== null) {
return t("nav.references.failed", { message: nav.referencesError });
}
if (nav.references.length === 0) {
return t("nav.references.none", { name: nav.symbol });
}
const files = new Set(nav.references.map((item) => item.path)).size;
return t("nav.references.summary", {
name: nav.symbol,
uses: String(nav.references.length),
files: String(files),
});
});
/** A file with its references and their indexes in the flat list. */
interface ReferenceGroup {
/** Project-relative path. */
path: string;
/** The references with their flat index. */
rows: { item: ReferenceItem; index: number }[];
}
/** The references grouped by file. */
const groups = computed<ReferenceGroup[]>(() => {
const out: ReferenceGroup[] = [];
nav.references.forEach((item, index) => {
const last = out[out.length - 1];
if (last?.path === item.path) {
last.rows.push({ item, index });
} else {
out.push({ path: item.path, rows: [{ item, index }] });
}
});
return out;
});
/**
* The DOM id of a row.
*
* @param index - the row's index in the flat list.
*/
function optionId(index: number): string {
return `reference-row-${String(index)}`;
}
/**
* The directory part of a path, empty at the root.
*
* @param path - project-relative path.
*/
function dirName(path: string): string {
const slash = path.lastIndexOf("/");
return slash < 0 ? "" : path.slice(0, slash);
}
/**
* The preview split around the name: before, the name, after. A preview
* whose column does not fit shows unsplit.
*
* @param item - the reference.
*/
function parts(item: ReferenceItem): { before: string; name: string; after: string } {
const { start, end } = item.range;
const length = start.line === end.line ? end.column - start.column : 0;
const from = item.previewColumn;
if (from > item.preview.length || length <= 0) {
return { before: item.preview, name: "", after: "" };
}
return {
before: item.preview.slice(0, from),
name: item.preview.slice(from, from + length),
after: item.preview.slice(from + length),
};
}
/**
* Reveals a reference.
*
* @param item - the reference.
*/
function openRow(item: ReferenceItem): void {
nav.select(item.key);
void nav.reveal(item);
}
/**
* Keyboard navigation in the list.
*
* @param event - the key event.
*/
function onListKey(event: KeyboardEvent): void {
const count = nav.references.length;
const moves: Record<string, number> = {
ArrowDown: 1,
ArrowUp: -1,
PageDown: PAGE,
PageUp: -PAGE,
Home: -count,
End: count,
};
const delta = moves[event.key];
if (delta !== undefined) {
event.preventDefault();
nav.move(delta);
} else if (event.key === "Enter") {
const item = nav.references[nav.selectedIndex];
if (item) {
event.preventDefault();
openRow(item);
}
}
}
/** Takes the focus Find References asked for, once. */
async function takeFocus(): Promise<void> {
if (!nav.focusPending) {
return;
}
nav.focusPending = false;
await nextTick();
list.value?.focus();
}
watch(() => nav.focusRequest, takeFocus);
onMounted(() => {
void takeFocus();
});
watch(
() => nav.selectedIndex,
async (index) => {
await nextTick();
const element = index < 0 ? null : document.getElementById(optionId(index));
if (element && typeof element.scrollIntoView === "function") {
element.scrollIntoView({ block: "nearest" });
}
},
);
</script>
<template>
<div
class="references"
data-test="references"
>
<div
class="references__status"
role="status"
data-test="references-status"
>
{{ status }}
</div>
<div
ref="list"
class="references__list"
role="listbox"
tabindex="0"
:aria-label="t('nav.references.label')"
:aria-activedescendant="nav.selectedIndex >= 0 ? optionId(nav.selectedIndex) : undefined"
data-test="references-list"
@keydown="onListKey"
>
<div
v-for="group in groups"
:key="group.path"
role="group"
:aria-label="group.path"
>
<div
class="references__file"
data-test="references-file"
>
<span class="references__file-name">{{ baseName(group.path) }}</span>
<span class="references__file-dir">{{ dirName(group.path) }}</span>
<span class="references__file-count">{{ group.rows.length }}</span>
</div>
<div
v-for="{ item, index } in group.rows"
:id="optionId(index)"
:key="item.key"
role="option"
class="references__row"
:class="{ 'references__row--selected': nav.selectedKey === item.key }"
:aria-selected="nav.selectedKey === item.key"
data-test="references-row"
@click="openRow(item)"
>
<span class="references__line">{{ item.range.start.line + 1 }}</span>
<span class="references__preview">{{ parts(item).before }}<mark class="references__name">{{ parts(item).name }}</mark>{{ parts(item).after }}</span>
</div>
</div>
</div>
</div>
</template>
<style scoped>
.references {
display: flex;
flex-direction: column;
flex: 1;
min-height: 0;
}
.references__status {
padding: var(--lt-space-xs, 2px) var(--lt-space-m, 8px);
color: var(--lt-fg-muted);
}
.references__list {
flex: 1;
min-height: 0;
overflow: auto;
border-top: 1px solid var(--lt-border);
outline: none;
}
.references__list:focus-visible {
box-shadow: inset 0 0 0 1px var(--lt-accent);
}
.references__file {
display: flex;
align-items: baseline;
gap: var(--lt-space-m, 8px);
padding: var(--lt-space-xs, 2px) var(--lt-space-m, 8px);
white-space: nowrap;
}
.references__file-name {
font-weight: 600;
}
.references__file-dir {
overflow: hidden;
text-overflow: ellipsis;
color: var(--lt-fg-muted);
}
.references__file-count {
margin-left: auto;
color: var(--lt-fg-muted);
}
.references__row {
display: flex;
align-items: baseline;
gap: var(--lt-space-m, 8px);
padding: 0 var(--lt-space-m, 8px) 0 var(--lt-space-l, 24px);
white-space: nowrap;
cursor: pointer;
}
.references__row:hover {
background: color-mix(in srgb, var(--lt-fg) 6%, transparent);
}
.references__row--selected,
.references__row--selected:hover {
background: var(--lt-editor-selection-bg);
}
.references__line {
flex: none;
min-width: 3ch;
text-align: right;
color: var(--lt-fg-muted);
}
.references__preview {
overflow: hidden;
text-overflow: ellipsis;
font-family: var(--lt-font-mono);
}
.references__name {
color: inherit;
background: var(--lt-editor-match-bg);
border-radius: 2px;
}
</style>

View file

@ -0,0 +1,168 @@
<script setup lang="ts">
/**
* The inline rename field (M3.5): placed over the symbol in the editor,
* prefilled with the current name (selected). Below it a line tells how
* many uses in how many files will change (counted with Find References)
* or why the rename failed. Enter applies the new name, Escape or leaving
* the field cancels. An exclusive modal (the one-modal rule, `modals.ts`).
*/
import { computed, nextTick, ref, watch } from "vue";
import { t } from "../../../i18n";
import { useNavStore } from "./nav";
const nav = useNavStore();
/** The input element. */
const input = ref<HTMLInputElement | null>(null);
/** Where the field goes: over the symbol, or near the top without a view. */
const style = computed(() => {
const anchor = nav.rename?.anchor;
return anchor
? { left: `${String(Math.max(0, anchor.left - 4))}px`, top: `${String(Math.max(0, anchor.top - 4))}px` }
: { left: "50%", top: "12vh", transform: "translateX(-50%)" };
});
/** The line under the field. */
const hint = computed(() => {
const r = nav.rename;
if (!r) {
return "";
}
if (r.error !== null) {
return r.error;
}
if (r.busy) {
return t("nav.rename.busy");
}
if (r.preview === null) {
return t("nav.rename.counting");
}
return t("nav.rename.preview", { uses: String(r.preview.uses), files: String(r.preview.files) });
});
/**
* Keyboard handling of the field.
*
* @param event - the key press.
*/
function onKeydown(event: KeyboardEvent): void {
if (event.key === "Enter") {
void nav.commitRename();
} else if (event.key === "Escape") {
nav.cancelRename();
} else {
return;
}
event.preventDefault();
event.stopPropagation();
}
/** Cancels when the focus leaves the field, unless the rename runs. */
function onBlur(): void {
if (nav.rename && !nav.rename.busy) {
nav.cancelRename();
}
}
/**
* Takes the typed text.
*
* @param event - the input event.
*/
function onInput(event: Event): void {
if (nav.rename && event.target instanceof HTMLInputElement) {
nav.rename.value = event.target.value;
nav.rename.error = null;
}
}
watch(
() => nav.rename !== null,
(open) => {
if (open) {
void nextTick(() => {
input.value?.focus();
input.value?.select();
});
}
},
);
</script>
<template>
<div
v-if="nav.rename"
class="rename"
:style="style"
role="dialog"
:aria-label="t('nav.rename.label', { name: nav.rename.placeholder })"
data-test="rename"
>
<input
ref="input"
class="rename__input"
:class="{ 'rename__input--error': nav.rename.error !== null }"
type="text"
:value="nav.rename.value"
:readonly="nav.rename.busy"
:aria-label="t('nav.rename.label', { name: nav.rename.placeholder })"
:aria-describedby="'lt-rename-hint'"
spellcheck="false"
autocomplete="off"
data-test="rename-input"
@input="onInput"
@keydown="onKeydown"
@blur="onBlur"
>
<p
id="lt-rename-hint"
class="rename__hint"
:class="{ 'rename__hint--error': nav.rename.error !== null }"
role="status"
data-test="rename-hint"
>
{{ hint }}
</p>
</div>
</template>
<style scoped>
.rename {
position: fixed;
z-index: 30;
display: flex;
flex-direction: column;
min-width: 220px;
background: var(--lt-bg);
border: 1px solid var(--lt-accent);
border-radius: var(--lt-radius, 4px);
overflow: hidden;
}
.rename__input {
padding: var(--lt-space-xs, 2px) var(--lt-space-s, 4px);
font-family: var(--lt-font-mono);
font-size: var(--lt-font-size-editor);
color: var(--lt-fg);
background: var(--lt-editor-bg);
border: none;
outline: none;
}
.rename__input--error {
box-shadow: inset 0 -2px 0 var(--lt-error);
}
.rename__hint {
margin: 0;
padding: var(--lt-space-xs, 2px) var(--lt-space-s, 4px);
font-size: 0.85em;
color: var(--lt-fg-muted);
border-top: 1px solid var(--lt-border);
}
.rename__hint--error {
color: var(--lt-error);
}
</style>

View file

@ -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<string, unknown>;
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<string, unknown>;
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<string, unknown>).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<string, unknown>;
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<string, unknown>).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<string, unknown>;
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<string, unknown>;
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<EditorView, "state">, 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<PickerState | null>(null);
/** The inline rename field, open while set. */
const rename = ref<RenameState | null>(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<ReferenceItem[]>([]);
/** Whether a Find References request runs. */
const searching = ref(false);
/** Why the last Find References failed. */
const referencesError = ref<string | null>(null);
/** Key of the selected reference. */
const selectedKey = ref<string | null>(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<void> {
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<void> {
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<void> {
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<void> {
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<void> {
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<void> {
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<void> {
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<number, number>();
if (result.ok && Array.isArray(result.value.files)) {
for (const file of result.value.files as unknown[]) {
const f = file as Record<string, unknown> | 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,
};
});

View file

@ -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];
}

View file

@ -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<BottomTool>("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<BottomTool | null>(() => {
});
/** 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'"
/>
<ProblemsToolWindow v-show="bottomActive === 'problems'" />
<ReferencesToolWindow v-show="bottomActive === 'references'" />
</BottomPanel>
<StatusBar />
</div>

View file

@ -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.",

View file

@ -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("");

354
ui/tests/nav/nav.test.ts Normal file
View file

@ -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<string, unknown> }[];
/** Answers by command id; a function gets the params. */
let answers: Record<string, unknown>;
/** Pinia of the current test. */
let pinia: Pinia;
/** Mounted components. */
let mounted: VueWrapper[];
/** Params of every `editor.reveal`. */
let reveals: unknown[];
const TEXT = "<?php\nclass Greeter {\n public function hello() {}\n}\n";
/**
* A range on one line.
*
* @param line - 0-based line.
* @param from - start column.
* @param to - end column.
*/
function range(line: number, from: number, to: number): Record<string, unknown> {
return { start: { line, column: from }, end: { line, column: to } };
}
/** The params of every call of a command. */
function paramsOf(command: string): Record<string, unknown>[] {
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<void> {
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<typeof mount>[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<string, unknown> }) => {
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<HTMLInputElement>("[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<HTMLInputElement>("[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 = "<?php\nhello();\n";
let version = 1;
const sent: unknown[] = [];
const transport: SyncTransport = {
edit: (params) => {
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 = "<?php\ngreet();\n";
version = 2;
sync.notifyVersion(2);
await flushPromises();
sync.endUndoableRemote(2);
expect(sync.state.doc.toString()).toBe("<?php\ngreet();\n");
expect(sent).toEqual([]);
expect(history).toEqual([true]);
engineText = "<?php\nhello2();\n";
version = 3;
sync.notifyVersion(3);
await flushPromises();
expect(sync.state.doc.toString()).toBe("<?php\nhello2();\n");
expect(history).toEqual([true, false]);
});
});