H3: Phpactor UX: fast tick while indexing, progress, messages, php -l
- Session tick: 1 ms while Phpactor reports work-done progress and in a
session's first 120 s, otherwise 25 ms as before. Fast intervals use
thread::sleep, because recv_timeout wakes at most ~64/s on Windows.
First useful completion on 2,000 classes: 71.6 s -> 20.7-26.9 s.
- $/progress -> lspProgress {active, title?, message?, percentage?},
progress in lsp.status, a status-bar item (LspProgressItem).
- window/showMessage -> notification.lsp.message (repeats within 30 s and
the known Windows lint-provider complaint only logged); showMessage,
logMessage and stderr in a 1,000-line log, new command lsp.log.
- Lutra's own php -l on Windows (lsp/php_lint.rs): on open and save, one
worker thread, lutra_proc::spawn, stdin, 10 s timeout, output caps;
merged into diagnosticsChanged with source "php -l".
- editor.completion.delayMs stays 0 (measured: 100 ms only delays the
list; Phpactor marks every list incomplete).
- Fake server: scripted notifications after initialized.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
8701f50d37
commit
e128400246
21 changed files with 1752 additions and 48 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), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4), the banner-aligned themes and diagnostic/VCS tokens (H5); Git backend (M4.1) · **Last updated:** 2026-10-25
|
||||
> **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); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4), the banner-aligned themes and diagnostic/VCS tokens (H5), Phpactor UX: fast tick, messages, progress, `php -l` (H3); Git backend (M4.1) · **Last updated:** 2026-10-25
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -384,7 +384,8 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- Columns are UTF-16, and files outside the project are ignored.
|
||||
- A missing severity counts as error.
|
||||
- Caps: at most 10,000 files, and 10,000 items each from the client.
|
||||
- `diagnostics.list {path?}` returns `{files: [{path, items}]}` sorted by path. `lsp.status` returns `{state, message?, startupMs?}`. `lsp.restart` is in the Tools menu.
|
||||
- `diagnostics.list {path?}` returns `{files: [{path, items}]}` sorted by path. `lsp.status` returns `{state, message?, startupMs?, progress}`. `lsp.restart` is in the Tools menu.
|
||||
- `lspProgress {active, title?, message?, percentage?}` and `lsp.log` (H3), see Phpactor UX below.
|
||||
- Diagnostics are cleared (an empty `diagnosticsChanged` per file) when the session ends or the server fails, so stale ones never stay. The pump handles at most 2,000 server events per call.
|
||||
- **UI:**
|
||||
- **Editor:** `ui/src/components/editor/lint.ts` feeds CodeMirror's lint extension (`@codemirror/lint`, MIT) with wavy underlines, a gutter dot, and the message with source and code on hover.
|
||||
|
|
@ -397,14 +398,24 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- **Phpactor 2026.06.25.0 on Windows:** the live check found two problems, worked around without touching the user's project.
|
||||
- **The event loop stalls.** Its amphp event loop only runs when a message arrives on stdin, so timers stall while the client is quiet: the diagnostics debounce (`language_server.diagnostic_sleep_time`) and the file watcher.
|
||||
- Seen: the server answered `initialize` in 0.8 s, but published nothing after `didOpen` and only a clearing empty list after `didChange`.
|
||||
- Fix: while busy (a job in the last 60 s and the server ready), the session thread sends the no-op notification `$/lutra/tick`. It comes from the thread's own `recv_timeout` loop, so it does not depend on the host's pump.
|
||||
- Fix: while busy (a job in the last 60 s and the server ready), the session thread sends the no-op notification `$/lutra/tick`. It comes from the thread's own loop, so it does not depend on the host's pump. H3 adds a fast tick while Phpactor indexes (see Phpactor UX).
|
||||
- The interval sets the latency, because Phpactor's analysis advances one step per message. Edit to diagnostics (engine test with the real PHAR, measured): 5.9 s at 200 ms, 2.5 s at 50 ms, 1.5 s at 20 ms. Lutra uses 25 ms.
|
||||
- The same stall means Phpactor rarely answers `shutdown` in time, so the shutdown timeout is 500 ms before the kill.
|
||||
- **Subprocesses fail.** Every subprocess it starts through amphp fails with `CreateProcess failed`: outsourced diagnostics, the PHP lint provider, the indexer's `find` watcher.
|
||||
- Fix: `initializationOptions` set `language_server.diagnostic_outsource: false` (diagnostics run in the server process) and `indexer.enabled_watchers: ["php"]` (a polling watcher).
|
||||
- The PHP lint provider still fails once and removes itself; its `window/showMessage` warning is not shown.
|
||||
- So Lutra has no `php -l` syntax errors on Windows yet. The worse-reflection diagnostics (missing members, unknown classes, …) work.
|
||||
- The PHP lint provider still fails once and removes itself; its `window/showMessage` warning is only logged (`lsp::is_hidden_message`).
|
||||
- Lutra runs `php -l` itself instead (H3, see Phpactor UX). The worse-reflection diagnostics (missing members, unknown classes, …) work.
|
||||
- These adjustments (tick, initialization options, short shutdown timeout) apply on Windows only (`lsp::phpactor_launch`). macOS and Linux are untested.
|
||||
- **Phpactor UX (H3):** `crates/engine/src/lsp/` (`mod.rs`: progress, messages, log, merge; `session.rs`: fast tick; `php_lint.rs`), `lsp.log` in `cmd/lsp_diagnostics.rs`, the status-bar item `ui/src/components/problems/LspProgressItem.vue`.
|
||||
- **Fast tick.** Phpactor's indexer waits for a 1 ms timer after every file, and on Windows that timer only fires when a message arrives, so it indexes one file per tick. While Phpactor reports work-done progress, and during the first 120 s of a session, the tick is 1 ms (`FAST_TICK_INTERVAL`, `tick_interval`); otherwise 25 ms and the 60 s window as before. The pump sets a flag the session thread reads.
|
||||
- A channel `recv_timeout` wakes at most ~64 times a second on Windows (15.6 ms timer resolution; measured 63–67 wakes/s for 1, 2 and 5 ms timeouts), so intervals below 16 ms poll the queue and `thread::sleep` (high resolution; 697 wakes/s at 1 ms). A job waits at most one interval.
|
||||
- Measured on a generated 2,000-class project (`real_phpactor_first_completion`, Windows 11, PHP 8.4, debug build), project open to the first completion list with a method of the last class: 71.6 s with the 25 ms tick (before), 47.8 s with a 2 ms `recv_timeout` (really ~16 ms), 29.9 s at 5 ms, 23.8–26.9 s at 2 ms, 20.7–22.6 s at 1 ms with sleep. Phpactor then indexes ~110–190 files/s.
|
||||
- Cost while the window runs and Phpactor is idle: about 10% of one core for Phpactor and 4.5% for the session thread at 1 ms (9% and 3% at 2 ms). After the window it is the old 25 ms tick.
|
||||
- **Progress.** `$/progress` begin/report/end (at most 32 tasks) become `lspProgress {active, title?, message?, percentage?}` with the newest running task; `lsp.status` has it as `progress`. It clears when the session stops, restarts or fails. The status bar shows title and percentage with the message as tooltip (Phpactor: `Indexing workspace 25%`, `500/2001 (24.99%, …)`).
|
||||
- **Messages.** `window/showMessage` becomes a notification of the same level, `notification.lsp.message {message}`; the same text again within 30 s is not shown. Phpactor's known lint-provider complaint on Windows is only logged. `window/showMessage`, `window/logMessage` and stderr lines go to a log of the last 1,000 lines, `lsp.log` → `{lines}` (`[level] …`, `[show level] …`, `[stderr] …`).
|
||||
- **`php -l`.** On Windows Lutra runs the toolchain's `php -n -l -d display_errors=1 -d log_errors=0` itself for each open PHP buffer when first seen and after each save (a clean buffer whose saved version moved), on one worker thread through `lutra_proc::spawn`, with the saved text on stdin. Queued runs of one file collapse to the newest; files over 8 MiB are skipped; a run is killed after 10 s; output is capped at 64 KiB. `Parse error` / `Fatal error` lines become error diagnostics on the whole line with `source: "php -l"` (at most 100 per file). They merge after the server's into `diagnosticsChanged` and `diagnostics.list`, stay until the file's next run, survive a server restart and clear on project close. Elsewhere it is off (Phpactor lints itself); `Engine::set_php_lint` overrides it.
|
||||
- **Completion delay (H4's `editor.completion.delayMs`).** Phpactor answers every completion with `isIncomplete: true`, so CodeMirror asks again on every keystroke. Measured on 2,000 classes: a member completion costs ~6 ms of Phpactor CPU (median 21 ms), a class-name completion ~180 ms CPU (median 270 ms, 100 items). A Vitest model of CodeMirror's behaviour (server latency 40 or 150 ms, 80/150/250 ms per key) gave the same number of requests at 0 and 100 ms for 150 ms per key and slower (`->price`: 6, `ProductRepository`: 17); only typing faster than the delay (80 ms per key) cut them (6 → 1, 17 → 1), and then no list showed until the typing paused. The default stays 0: 100 ms only delays the list. The real lever is cancelling superseded requests (a follow-up).
|
||||
- Tests: `crates/engine/tests/lsp_ux.rs` (scripted fake-server messages and progress, `php -l` on open and save, merge with the server and a restart, off without PHP; the ignored real-Phpactor measurement), unit tests (tick rule, hidden message, `php -l` output parsing with a proptest), Vitest `ui/tests/problems/LspProgressItem.test.ts`.
|
||||
- **Measured** (Windows 11, PHP 8.4.24, debug build, 16-line file):
|
||||
- Phpactor is ready 0.8–0.9 s after the session starts (`startupMs`).
|
||||
- First diagnostics after `file.open`: 1.7 s in the engine test, 2.7 s in the app over the control channel.
|
||||
|
|
@ -412,7 +423,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- Without the adjustments: no diagnostics within 180 s.
|
||||
- **Known gaps:**
|
||||
- ~~A Phpactor process outlives Lutra when Lutra is killed.~~ Fixed by H1: Phpactor starts through `lutra_proc::spawn` (see Child processes).
|
||||
- `window/showMessage` and `logMessage` are dropped, and server-initiated progress is not shown.
|
||||
- ~~`window/showMessage` and `logMessage` are dropped, and server-initiated progress is not shown.~~ Fixed by H3.
|
||||
- **Tests:**
|
||||
- `crates/engine/tests/lsp.rs` has 10 tests against `lutra-lsp-fake`: sync incl. UTF-16 and CRLF edits, diagnostics list/clear, reload resync, requests after edits, project close, restart, quit, missing server, crash and give-up, no server without a project, and a proptest of random edits. The ignored `real_phpactor_reports_diagnostics` runs with `LUTRA_PHPACTOR=<phar>`.
|
||||
- Unit tests cover severity, paths, the Phpactor launch and the tick rule.
|
||||
|
|
@ -593,6 +604,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
| 2026-10-25 | minor | M4.1: Git backend (`lutra-vcs`, `git.*` commands, `gitChanged`, `git.executable`) |
|
||||
| 2026-10-24 | minor | H4: string and path controls in the settings dialog (`pick_file` IPC), assist settings (auto popup, completion delay, hover delay) read live |
|
||||
| 2026-10-25 | minor | H5: banner-aligned light and dark palettes, `DIAGNOSTIC_TOKENS` and `VCS_TOKENS`, completion icon colours by kind, contrast test extended |
|
||||
| 2026-10-25 | minor | H3: Phpactor UX: fast tick while indexing (1 ms, sleep-based), `lspProgress` and the status-bar item, `window/showMessage` as notifications, `lsp.log`, Lutra's own `php -l` on Windows |
|
||||
| 2026-10-25 | minor | H6: isolated data directory (`--data-dir`, `LUTRA_DATA_DIR`, `--control` temp dir), shared tools dir, rendezvous order |
|
||||
| 2026-10-24 | minor | H1: `crates/proc` (L0), child processes in kill-on-close groups (Windows job objects, Unix process groups with a watchdog); Phpactor and the PHP probe use it |
|
||||
| 2026-10-22 | minor | M3.5: definition, references, rename (`lsp_nav`, workspace edits, undoable remote edits, nav UI) |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue