M3.3: engine wiring for Phpactor and diagnostics
- One Phpactor per open project on its own session thread, started when the toolchain is ready; ordered document sync from buffer.edit and the pump; lspStatus, diagnosticsChanged, diagnostics.list, lsp.status, lsp.restart; app.quit stops the server synchronously. - Phpactor 2026.06.25.0 on Windows: keep-alive $/lutra/tick (its event loop only runs on stdin input), in-process diagnostics and a polling watcher through initializationOptions (amphp subprocesses fail), 500 ms shutdown timeout. - Editor lint extension (underlines, gutter dots, hover; tokens only) and a Problems tab in the bottom panel; problems.open Mod+Alt+P. - Tests: engine tests against the fake server (incl. sync proptest), an ignored real-Phpactor test, a TCP test, Vitest for lint and Problems. - Docs: architecture, gaps G6, parity (Inspections 4% est.), ui-parity, roadmap, ROADMAP. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
65c6966588
commit
13c76d3046
34 changed files with 3562 additions and 37 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 · **Last updated:** 2026-10-20
|
||||
> **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
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -343,6 +343,65 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- **Bottom panel tabs:** `BottomPanel.vue` takes `tabs` and `v-model:active`; with tabs the header shows a tab list instead of the title. `MainLayout.vue` shows Find and Terminal as tabs while both are visible; `find.open` and `terminal.open` make their tool window the active tab, the close button hides the active one, and expansion is kept per tool window.
|
||||
- **`terminal.open`** (UI command, `Mod+Shift+T`, Lutra's own; enabled with a project): shows the Terminal tab, creates a terminal if none is running (always with `{new: true}`) and focuses it.
|
||||
|
||||
### Engine wiring and diagnostics (M3.3)
|
||||
|
||||
- **Where:** `crates/engine/src/lsp/` (`mod.rs`: state, pump, sync, diagnostics; `session.rs`: the session thread), commands in `crates/engine/src/cmd/lsp_diagnostics.rs`. One-line hooks in `buffer.edit` (`lsp::record_edits`), the pump (`lsp::pump`), `app.quit` (`lsp::shutdown_now`), `State`, `Event` and the registry.
|
||||
- **Lifecycle:** one session per open project.
|
||||
- It starts at the first pump where a project is open and `toolchain.status` reports a usable PHP and a ready Phpactor (`php <phar> language-server` in the project root). With a host-set server (`Engine::set_language_server`, the fake server in tests) it starts at once.
|
||||
- A change of root, PHP or PHAR replaces the session. Closing the project, `lsp.restart` and dropping the engine stop it.
|
||||
- `app.quit` stops it synchronously (`shutdown`, `exit`, kill; quit measured at 1.55 s on Windows). The host exits right after, which would cut a background shutdown short and leave `php.exe` running.
|
||||
- **Nothing heavy under the lock:** each session has one thread (`lsp-session`) that owns the `lutra_lsp::Server`, and it also spawns the process. The engine lock only enqueues jobs on the thread's FIFO:
|
||||
- `Open`/`Full` carry an O(1) rope clone of the buffer; the text is built on the thread.
|
||||
- `Change` carries the edit batch that `buffer.edit` applied.
|
||||
- `Save`, `Close`, and `Run(closure)` for requests.
|
||||
|
||||
Requests from M3.4/M3.5 go through `lsp::submit` on the same queue, so a request never overtakes an edit's `didChange` (tested).
|
||||
- **Document sync:** PHP buffers (`.php`, `.phtml`, `.inc`) are opened when the pump first sees them and closed when they close.
|
||||
- `buffer.edit` queues its batch as `didChange` when the server's copy is at the edit's base version.
|
||||
- Otherwise the next pump resends the whole text: after a reload from disk, a restore, or a `didChange` the client copy rejected.
|
||||
- When the saved version of a clean buffer moves, the pump sends `didSave`.
|
||||
- Property-tested with random edits (incremental and full sync): the fake server's copy always ends equal to the buffer.
|
||||
- **Events and commands:**
|
||||
- `lspStatus {state: starting|ready|restarting|failed|stopped, message?}` follows the client's status. `failed` (spawn error, too many crashes) also raises `notification.lsp.failed`.
|
||||
- `diagnosticsChanged {path, items: [{range: {start: {line, column}, end}, severity: error|warning|info|hint, message, source?, code?}]}` per project file.
|
||||
- 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 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.
|
||||
- Colours come only from tokens: error `--lt-error`, warning `--lt-accent`, info/hint `--lt-fg-muted`. Dedicated diagnostic tokens are a design follow-up.
|
||||
- A view plugin per editor state applies its path's list when the view shows the state and on every change. CodeMirror maps ranges through edits until the next publication.
|
||||
- **Problems:** `ui/src/components/problems/` holds the store and the tab.
|
||||
- The store loads `diagnostics.list` and `lsp.status` on start and on project open, follows the events, and hands each file to `lint.ts`.
|
||||
- The Problems tab in the bottom panel groups by file, errors first; click or Enter runs `editor.reveal`.
|
||||
- `problems.open` is `Mod+Alt+P`, menu View/Problems.
|
||||
- **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.
|
||||
- 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.
|
||||
- These adjustments (tick, initialization options, short shutdown timeout) apply on Windows only (`lsp::phpactor_launch`). macOS and Linux are untested.
|
||||
- **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.
|
||||
- After an edit: 1.8 s and 2.7–2.9 s, including Phpactor's 1 s debounce.
|
||||
- Without the adjustments: no diagnostics within 180 s.
|
||||
- **Known gaps:**
|
||||
- A Phpactor process outlives Lutra when Lutra is killed, or when a test process exits right after dropping the engine. There is no job object or kill-on-close yet; that is a `lutra-lsp` follow-up.
|
||||
- `window/showMessage` and `logMessage` are dropped, and server-initiated progress is not shown.
|
||||
- **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.
|
||||
- `crates/control/tests/lsp.rs` runs over TCP with ticks on.
|
||||
- Vitest: `ui/tests/editor/lint.test.ts` and `ui/tests/problems/ProblemsToolWindow.test.ts`.
|
||||
|
||||
### 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`.
|
||||
|
|
@ -386,6 +445,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 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 |
|
||||
| 2026-10-19 | minor | M3.8: MCP server (`lutra mcp`, dual era 2026-07-28 + legacy `initialize`), tools, resources, event buffer; `buffer.list` |
|
||||
| 2026-10-19 | minor | M3.9: app menu (header bar, `menu.open`, grouping by `menuPath`, launcher under the modal rule); menu paths for user commands |
|
||||
| 2026-10-18 | minor | M3.6: integrated terminal (`crates/terminal` sessions, backpressure, `terminal.*`, `terminalOutput`/`terminalExited` via the pump, lifecycle, xterm.js views, terminal tokens, focus rule, bottom panel tabs) |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue