M3.4: completion, hover and signature help from Phpactor
Engine (crates/engine/src/cmd/lsp_assist.rs), on M3.5's pending outcomes:
- lsp.completion {id, position, triggerCharacter?}: items with label,
kind, detail, Markdown documentation, insertText, textEdit,
additionalTextEdits, sortText; sorted, capped at 500 (cut lists are
incomplete), snippets turned into plain text.
- lsp.hover {id, position}: Markdown contents and range.
- lsp.signatureHelp {id, position}: signatures with UTF-16 parameter spans.
- The request is queued after every didChange; the answer is converted
in the reply callback, off the engine lock. Positions are checked
against the buffer. Server strings and lists are capped.
- lutra-lsp-fake answers completion and signature help.
Editor (ui/src/components/editor/assist/):
- Completion source with Lutra's triggers (identifiers, $, ->, ?->, ::,
namespace \; not in strings or comments unless asked), the server's
ranking as boost, text edits and imports applied in UTF-16 (CRLF too),
Lucide kind icons.
- Hover documentation (350 ms) and editor.quickDocumentation (Mod+I).
- Signature help on ( and , following the cursor; editor.parameterInfo.
- editor.complete.
- Lutra's own Markdown renderer without HTML (XSS-tested), tokens only.
- Requests wait for the buffer sync to be idle and use runWaiting.
- New dependency @codemirror/autocomplete (MIT, already transitive).
Tests: 6 engine tests against the fake server, 9 unit tests, an ignored
real-Phpactor latency test, 29 Vitest tests; palette and menu tests list
the new UI commands.
Measured with the real Phpactor (Windows 11, debug build, 25 ms tick):
- Completion 61-109 ms while typing (median 76 ms; ~107 ms in the app).
- Hover and signature help ~16 ms median.
- A useful list 2.3 s after opening a file in a 20-class project, ~65 s
for 2,000 classes (indexing).
- Phpactor 56-71 MB working set, ~6% of one core while typing.
Live-checked in the app on port 7934. Docs: Code completion 0% -> 5%
(est.), feature depth ~4.1% -> ~4.6%, breadth 26/155, architecture, G6,
ui-parity, language-parity, roadmap, README.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
12d21d96f4
commit
a212a44490
35 changed files with 3916 additions and 25 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Architecture
|
||||
|
||||
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3) · **Last updated:** 2026-10-21
|
||||
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4) · **Last updated:** 2026-10-22
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -422,6 +422,46 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- `lsp.restart`, project close, `app.quit` (`shutdown_now`) or a crash: queued jobs are dropped and in-flight requests resolve with `Stopped`/`ServerCrashed`, so the waiter gets an error at once instead of hanging (test: `crates/engine/tests/pending.rs`).
|
||||
- A finish must check that its answer still applies to the state; `lsp.rename` refuses when a buffer's version changed since the request.
|
||||
|
||||
### Code assistance: completion, hover, signature help (M3.4)
|
||||
|
||||
- **Where:** `crates/engine/src/cmd/lsp_assist.rs` (commands and conversion), `ui/src/components/editor/assist/` (CodeMirror extensions, Markdown renderer, UI commands). One-line hooks: `editorExtensions(path, buffer)` in `extensions.ts`, the buffer handle in the editor store's `adopt`, three `provide` calls in `EditorArea.vue`.
|
||||
- **Commands:**
|
||||
- `lsp.completion {id, position, triggerCharacter?}` returns `{items: [{label, kind, detail?, documentation?, insertText, textEdit?, additionalTextEdits?, sortText?, filterText?, deprecated?}], incomplete}`.
|
||||
- Items are sorted by `sortText`, then label, and cut at 500; a cut list is `incomplete`.
|
||||
- Snippet texts become plain text (tab stops dropped, placeholders kept), because Lutra announces no snippet support.
|
||||
- Plain-text documentation is escaped into Markdown.
|
||||
- `lsp.hover {id, position}` returns `{contents (markdown, empty for nothing), range?}`.
|
||||
- `lsp.signatureHelp {id, position}` returns `{signatures: [{label, documentation?, parameters: [{label: [start, end] | null, documentation?}], activeParameter?}], activeSignature, activeParameter}`. Parameter labels become UTF-16 offsets into the signature label.
|
||||
- The position is checked against the buffer (UTF-16 column, not past the line end, not inside a surrogate pair). A non-PHP buffer, or a server without the provider, gives the empty result. Without a session the command fails with `failed`.
|
||||
- Every string and list from the server is capped (labels 1 KiB, documentation 64 KiB, 32 imports per item, 32 signatures).
|
||||
- **Off the lock** (on M3.5's pending outcomes):
|
||||
- Under the lock the command validates, runs the LSP pump once (so a buffer opened a moment ago is opened on the server first) and queues a closure with `lsp::submit`. That runs after every queued `didChange`.
|
||||
- The closure sends the request with `request_with` (timeout 10 s). The reply callback converts the answer on the client thread, so a big list is never converted under the lock.
|
||||
- It sends the result into the `Pending`'s channel. The host waits without the lock (wait 11 s + 1 s grace) and resolves.
|
||||
- The UI calls these commands with `runWaiting` (`engine_execute_waiting`, off the main thread).
|
||||
- **Editor:**
|
||||
- **Before a request,** the UI awaits the buffer sync's `idle()` and drops the request if the document changed meanwhile. Positions are lines and UTF-16 columns, which CodeMirror counts the same way within a line, so CRLF files need no conversion.
|
||||
- **Completion source** (overrides CodeMirror's word completion in PHP files).
|
||||
- Lutra's triggers: identifiers (not after a digit), `$`, `->`, `?->`, `::` and namespace `\`, sent as `triggerCharacter`. Nothing inside strings or comments unless asked (`Ctrl-Space`, `editor.complete`).
|
||||
- The server's order becomes the boost. A complete list is filtered locally while typing; an incomplete one is asked again on each keystroke.
|
||||
- Applying an item uses its `textEdit` (else replaces the typed word with `insertText`) and its `additionalTextEdits` in one transaction. Text typed after the request is accounted for, and overlapping imports are skipped.
|
||||
- The kind icon is a Lucide component rendered into the list row.
|
||||
- **Hover:** `hoverTooltip` after 350 ms; `editor.quickDocumentation` (`Mod+I`) shows the same tooltip at the cursor.
|
||||
- **Signature help:**
|
||||
- A state field holds the tooltip; a view plugin asks on `(` and `,`, and while open on every edit or cursor move (120 ms debounce), dropping stale answers.
|
||||
- `Escape` closes it, `Mod-Shift-Space` and `editor.parameterInfo` open it.
|
||||
- **Markdown:** Lutra's own renderer builds DOM nodes with `createElement`/`textContent` from a fixed element set (paragraphs, code blocks, emphasis, lists, quotes, rules). HTML in the source stays text; links and images show their text only (no `href`, no `src`). No Markdown or sanitizer dependency.
|
||||
- Colours come only from tokens. New dependency: `@codemirror/autocomplete` (MIT, already transitive).
|
||||
- **Measured** with the real Phpactor (Windows 11, PHP 8.4, debug build, 25 ms tick, `real_phpactor_assist_latency`):
|
||||
- **Latency:** completion while typing 61–109 ms (median 76 ms), ~107 ms through the control channel in the app; hover median 15–16 ms; signature help median 16 ms.
|
||||
- **After 70 s idle** (ticks stopped): the first completion takes 92–262 ms.
|
||||
- **Indexing first:** Phpactor answers an empty `incomplete` list until it has indexed the project, which takes 2.3 s for 20 classes and ~65 s for 2,000. Its loop advances one step per stdin message, so indexing uses only ~15% of one core.
|
||||
- **Phpactor process:** 56–59 MB working set for 20 classes and 70–71 MB for 2,000. CPU while typing ~6% of one core; idle 1.5–4% while the tick window runs, ~0.1% after it.
|
||||
- **Tests:**
|
||||
- `crates/engine/tests/lsp_assist.rs`: 6 tests against `lutra-lsp-fake`, which now answers completion and signature help. They cover conversion, the trigger character, an edit seen before the request, the 500 cap, positions on CRLF and emoji lines, non-PHP buffers and no server. There is also the ignored real-PHAR test above.
|
||||
- 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.
|
||||
|
||||
### 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`.
|
||||
|
|
@ -464,6 +504,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
|
||||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 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` |
|
||||
| 2026-10-21 | minor | M3.3: engine ↔ Phpactor wiring (session thread, ordered sync, `lspStatus`, `diagnosticsChanged`, `diagnostics.list`, `lsp.status`, `lsp.restart`), Phpactor-on-Windows workarounds, lint extension, Problems tab |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue