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

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