From a212a44490e48c57c4e9885ae42a344d40575919 Mon Sep 17 00:00:00 2001 From: danny Date: Thu, 22 Oct 2026 18:38:07 +0200 Subject: [PATCH] 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 --- README.md | 2 +- ROADMAP.md | 12 +- crates/engine/src/cmd/lsp_assist.rs | 927 ++++++++++++++++++ crates/engine/src/cmd/mod.rs | 2 + crates/engine/src/engine.rs | 3 + crates/engine/tests/lsp_assist.rs | 477 +++++++++ crates/lsp/src/bin/lutra-lsp-fake.rs | 79 +- docs/architecture.md | 43 +- docs/gaps.md | 7 +- docs/language-parity.md | 4 +- docs/roadmap.md | 5 +- docs/target-app-parity.md | 7 +- docs/ui-parity.md | 5 +- ui/package.json | 1 + ui/pnpm-lock.yaml | 3 + ui/src/commands/uiCommands.ts | 3 + ui/src/components/editor/EditorArea.vue | 7 +- ui/src/components/editor/assist/commands.ts | 127 +++ ui/src/components/editor/assist/completion.ts | 289 ++++++ ui/src/components/editor/assist/hover.ts | 69 ++ ui/src/components/editor/assist/icons.ts | 104 ++ ui/src/components/editor/assist/index.ts | 153 +++ ui/src/components/editor/assist/markdown.ts | 292 ++++++ ui/src/components/editor/assist/request.ts | 73 ++ ui/src/components/editor/assist/signature.ts | 270 +++++ ui/src/components/editor/assist/types.ts | 319 ++++++ ui/src/components/editor/extensions.ts | 13 +- ui/src/i18n/en.json | 29 + ui/src/stores/editor.ts | 7 +- ui/tests/editor/assist/completion.test.ts | 285 ++++++ ui/tests/editor/assist/fakes.ts | 41 + ui/tests/editor/assist/hoverSignature.test.ts | 178 ++++ ui/tests/editor/assist/markdown.test.ts | 97 ++ ui/tests/menu/AppMenu.test.ts | 5 +- ui/tests/palette/CommandPalette.test.ts | 3 + 35 files changed, 3916 insertions(+), 25 deletions(-) create mode 100644 crates/engine/src/cmd/lsp_assist.rs create mode 100644 crates/engine/tests/lsp_assist.rs create mode 100644 ui/src/components/editor/assist/commands.ts create mode 100644 ui/src/components/editor/assist/completion.ts create mode 100644 ui/src/components/editor/assist/hover.ts create mode 100644 ui/src/components/editor/assist/icons.ts create mode 100644 ui/src/components/editor/assist/index.ts create mode 100644 ui/src/components/editor/assist/markdown.ts create mode 100644 ui/src/components/editor/assist/request.ts create mode 100644 ui/src/components/editor/assist/signature.ts create mode 100644 ui/src/components/editor/assist/types.ts create mode 100644 ui/tests/editor/assist/completion.test.ts create mode 100644 ui/tests/editor/assist/fakes.ts create mode 100644 ui/tests/editor/assist/hoverSignature.test.ts create mode 100644 ui/tests/editor/assist/markdown.test.ts diff --git a/README.md b/README.md index 5d38d90..ff2964f 100644 --- a/README.md +++ b/README.md @@ -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`); PHP language features 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 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, [`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, diff --git a/ROADMAP.md b/ROADMAP.md index 91dc5e1..36c5dc6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -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-21 · **Change:** minor (M3.3: diagnostics from Phpactor) · **Target:** JetBrains PhpStorm 2026.x, described from public documentation only +> **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 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) | **~15%** (24 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.1%** (Editor core 11% × weight 12, Navigation 10% × 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) | **~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 | | **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.1% | ~2,882 | [target-app-parity.md](docs/target-app-parity.md) | +| Features (depth) | ~4.6% | ~2,872 | [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) | @@ -45,7 +45,7 @@ Stability 8%: no-panic lints, the engine guard, a fuzzed control protocol and a | Project view, VFS, file watching | 8% (est.) | ~40 | | Navigation (go to class/file/symbol, recent files, structure) | 10% (est.) | ~102 | | Search and replace (in file, in project, structural) | 8% (est.) | ~70 | -| Code completion | 0% | ~250 | +| Code completion | 5% (est.) | ~240 | | Inspections and quick-fixes | 4% (est.) | ~290 | | Refactoring | 0% | ~250 | | Code style and formatting | 0% | ~120 | @@ -75,6 +75,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-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. | @@ -99,6 +100,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-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% | diff --git a/crates/engine/src/cmd/lsp_assist.rs b/crates/engine/src/cmd/lsp_assist.rs new file mode 100644 index 0000000..a4fb69b --- /dev/null +++ b/crates/engine/src/cmd/lsp_assist.rs @@ -0,0 +1,927 @@ +//! Code assistance from the language server (M3.4): `lsp.completion`, +//! `lsp.hover` and `lsp.signatureHelp`. +//! +//! The mechanism, off the engine lock: +//! 1. Under the lock the command checks the buffer and the position, runs +//! the LSP pump once (so a buffer opened a moment ago is opened on the +//! server first) and queues a closure with [`crate::lsp::submit`]. That +//! is all the lock is held for. +//! 2. The closure runs on the session thread after every `didChange` +//! queued so far, so the server answers for the text the caller sees. +//! It sends the request with [`Server::request_with`]; the reply +//! callback (on a client thread, still off the lock) converts the +//! answer into Lutra's shape, so even a 20,000-item list is never +//! converted under the lock, and sends it into the channel of a +//! [`Pending`] (M3.5's mechanism, `crate::command`). +//! 3. The command returns [`Outcome::pending`]. The host releases the +//! engine lock, waits ([`Pending::wait`]) and resolves the answer +//! ([`crate::Engine::resolve`], via [`crate::run_waiting`]); the desktop +//! runs these commands through the `engine_execute_waiting` IPC, on a +//! worker thread, so the window never waits either. +//! +//! Without a session (no project, toolchain not ready, server failed) the +//! commands fail with `failed`; a server that does not offer the feature, +//! and a buffer that is not PHP, give the empty result. Server answers are +//! untrusted: every list and string is capped, unknown shapes become the +//! empty result. + +use std::path::Path; +use std::time::Duration; + +use lutra_lsp::types::position_to_json; +use lutra_lsp::uri::path_to_uri; +use lutra_lsp::{LspError, Range, Server}; +use lutra_text::{ColumnUnit, Position}; +use serde::Deserialize; +use serde_json::{Map, Value, json}; + +use super::params::parse; +use crate::buffers::BufferId; +use crate::{Command, CommandSpec, EngineError, Outcome, Pending, Registry, Reply, State}; + +/// Most completion items returned; a longer list is cut and marked +/// `incomplete`, so the editor asks again as the user types. +pub const MAX_ITEMS: usize = 500; + +/// Most items of a server answer looked at (the rest is dropped unread). +const MAX_SCANNED: usize = 20_000; + +/// Longest label, detail or sort text kept, in bytes. +const MAX_SHORT: usize = 1024; + +/// Longest documentation, insert text or hover kept, in bytes. +const MAX_LONG: usize = 64 * 1024; + +/// Most additional text edits (imports) kept per item. +const MAX_EXTRA_EDITS: usize = 32; + +/// Most signatures, and parameters per signature, kept. +const MAX_SIGNATURES: usize = 32; + +/// How long the server gets to answer. +pub const REQUEST_TIMEOUT: Duration = Duration::from_secs(10); + +/// How long a host waits for the result: the request timeout plus slack +/// for the queue in front of it ([`Pending::wait`] adds one more second). +const WAIT_TIMEOUT: Duration = Duration::from_secs(11); + +/// 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(Completion))?; + registry.register(Box::new(Hover))?; + registry.register(Box::new(SignatureHelp))?; + Ok(()) +} + +/// A position in params: 0-based line, UTF-16 column. +#[derive(Debug, Clone, Copy, Deserialize)] +#[serde(deny_unknown_fields)] +struct PositionParam { + /// Line. + line: usize, + /// Column in UTF-16 code units. + column: usize, +} + +/// Params of `lsp.completion`. +#[derive(Deserialize)] +#[serde(deny_unknown_fields, rename_all = "camelCase")] +struct CompletionParams { + /// Buffer id. + id: BufferId, + /// The cursor. + position: PositionParam, + /// The character that triggered the completion, if typing did. + #[serde(default)] + trigger_character: Option, +} + +/// Params of `lsp.hover` and `lsp.signatureHelp`. +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct AtParams { + /// Buffer id. + id: BufferId, + /// The position. + position: PositionParam, +} + +/// `lsp.completion`: completion items at a position. +pub struct Completion; + +impl Command for Completion { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "lsp.completion", + label: "Complete Code", + menu_path: None, + default_shortcut: None, + params: "{ id: number, position: { line, column }, triggerCharacter?: string }; returns { items: [{ label, kind, detail?, documentation? (markdown), insertText, textEdit?: { range: { start: { line, column }, end }, newText }, additionalTextEdits?: [{ range, newText }], sortText?, filterText?, deprecated? }], incomplete } with at most 500 items sorted by sortText; incomplete: ask again as the user types; columns are UTF-16; kind: text|method|function|constructor|field|variable|class|interface|module|property|unit|value|enum|keyword|snippet|color|file|reference|folder|enumMember|constant|struct|event|operator|typeParameter; fails without a running language server", + } + } + + fn enabled(&self, state: &State) -> bool { + state.has_project() + } + + fn run(&self, state: &mut State, params: Value) -> Result { + let command = self.spec().id; + let p: CompletionParams = parse(command, params)?; + let trigger = p.trigger_character.filter(|c| c.chars().count() == 1); + let empty = json!({ "items": [], "incomplete": false }); + ask( + state, + Ask { + command, + id: p.id, + position: p.position, + method: "textDocument/completion", + provider: "completionProvider", + empty, + context: Some(match trigger { + Some(character) => json!({"triggerKind": 2, "triggerCharacter": character}), + None => json!({"triggerKind": 1}), + }), + convert: completion_result, + }, + ) + } +} + +/// `lsp.hover`: documentation of the symbol at a position. +pub struct Hover; + +impl Command for Hover { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "lsp.hover", + label: "Show Quick Documentation", + menu_path: None, + default_shortcut: None, + params: "{ id: number, position: { line, column } }; returns { contents: string (markdown, empty when there is nothing), range?: { start: { line, column }, end } }; columns are UTF-16; fails without a running language server", + } + } + + fn enabled(&self, state: &State) -> bool { + state.has_project() + } + + fn run(&self, state: &mut State, params: Value) -> Result { + let command = self.spec().id; + let p: AtParams = parse(command, params)?; + ask( + state, + Ask { + command, + id: p.id, + position: p.position, + method: "textDocument/hover", + provider: "hoverProvider", + empty: json!({ "contents": "" }), + context: None, + convert: hover_result, + }, + ) + } +} + +/// `lsp.signatureHelp`: the signatures of the call around a position. +pub struct SignatureHelp; + +impl Command for SignatureHelp { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "lsp.signatureHelp", + label: "Show Parameter Info", + menu_path: None, + default_shortcut: None, + params: "{ id: number, position: { line, column } }; returns { signatures: [{ label, documentation? (markdown), parameters: [{ label: [start, end] (UTF-16 offsets into the signature label) | null, documentation? }], activeParameter? }], activeSignature, activeParameter }, signatures empty outside a call; fails without a running language server", + } + } + + fn enabled(&self, state: &State) -> bool { + state.has_project() + } + + fn run(&self, state: &mut State, params: Value) -> Result { + let command = self.spec().id; + let p: AtParams = parse(command, params)?; + ask( + state, + Ask { + command, + id: p.id, + position: p.position, + method: "textDocument/signatureHelp", + provider: "signatureHelpProvider", + empty: json!({ "signatures": [], "activeSignature": 0, "activeParameter": 0 }), + context: None, + convert: signature_result, + }, + ) + } +} + +/// One request to the language server, as the commands describe it. +struct Ask { + /// The command id, for errors. + command: &'static str, + /// The buffer. + id: BufferId, + /// The position in it. + position: PositionParam, + /// The LSP method. + method: &'static str, + /// The server capability that must be present. + provider: &'static str, + /// The result when there is nothing to ask. + empty: Value, + /// The request's `context` member, if any. + context: Option, + /// Converts the server's answer into the command's result. + convert: fn(&Value) -> Value, +} + +/// Validates the request, queues it on the session (see the module docs) +/// and returns the pending result. +/// +/// # Errors +/// [`EngineError::Failed`] for an unknown buffer or without a language +/// server session; [`EngineError::InvalidParams`] for a position outside +/// the buffer or inside a surrogate pair. +fn ask(state: &mut State, ask: Ask) -> Result { + let Ask { + command, + id, + position, + method, + provider, + empty, + context, + convert, + } = ask; + let open = state + .buffers + .get(id) + .ok_or_else(|| EngineError::Failed(format!("{command}: no buffer {id}")))?; + let at = Position::new(position.line, position.column); + open.buffer + .position_to_offset(at, ColumnUnit::Utf16) + .map_err(|e| EngineError::invalid_params(command, format!("position: {e}")))?; + if !is_php(&open.path) { + return Ok(Outcome::value(empty)); + } + let Some(root) = state + .project + .as_ref() + .map(|w| w.project.root().to_path_buf()) + else { + return Ok(Outcome::value(empty)); + }; + let path = root.join(&open.path); + let uri = path_to_uri(&path).map_err(|e| EngineError::Failed(format!("{command}: {e}")))?; + let mut request = json!({ + "textDocument": { "uri": uri }, + "position": position_to_json(at), + }); + if let (Some(context), Some(object)) = (context, request.as_object_mut()) { + object.insert("context".into(), context); + } + crate::lsp::pump(state); + let (sender, receiver) = std::sync::mpsc::channel::>(); + let queued = crate::lsp::submit(state, move |server: &Server| { + let supported = server + .capabilities() + .is_none_or(|caps| caps.supports(provider)); + if !supported { + let _ = sender.send(Ok(empty)); + return; + } + let reply = sender.clone(); + let sent = server.request_with( + method, + request, + REQUEST_TIMEOUT, + Box::new(move |result: Result| { + let _ = reply.send(result.map(|value| convert(&value))); + }), + ); + if let Err(e) = sent { + let _ = sender.send(Err(e)); + } + }); + if !queued { + return Err(EngineError::Failed(format!( + "{command}: no PHP language server is running" + ))); + } + Ok(Outcome::pending(Pending::new( + receiver, + WAIT_TIMEOUT, + move |_state: &mut State, reply: Reply| finish(command, reply), + ))) +} + +/// The command's value from the converted answer. +/// +/// # Errors +/// [`EngineError::Failed`] for a server error, and when no answer came +/// (the session ended or the wait timed out). +fn finish(command: &str, reply: Reply) -> Result { + match reply { + Some(Ok(value)) => Ok(value), + Some(Err(e)) => Err(EngineError::Failed(format!( + "{command}: language server: {e}" + ))), + None => Err(EngineError::Failed(format!( + "{command}: the PHP language server did not answer" + ))), + } +} + +/// Whether a project-relative path is PHP, as the document sync decides. +fn is_php(path: &Path) -> bool { + path.extension().and_then(|e| e.to_str()).is_some_and(|e| { + ["php", "phtml", "inc"] + .iter() + .any(|x| e.eq_ignore_ascii_case(x)) + }) +} + +/// The LSP `CompletionItemKind` names, from 1. +const KINDS: [&str; 25] = [ + "text", + "method", + "function", + "constructor", + "field", + "variable", + "class", + "interface", + "module", + "property", + "unit", + "value", + "enum", + "keyword", + "snippet", + "color", + "file", + "reference", + "folder", + "enumMember", + "constant", + "struct", + "event", + "operator", + "typeParameter", +]; + +/// The name of a completion item kind; `text` for missing or unknown ones. +fn kind_name(kind: Option<&Value>) -> &'static str { + kind.and_then(Value::as_u64) + .and_then(|k| usize::try_from(k).ok()) + .and_then(|k| k.checked_sub(1)) + .and_then(|k| KINDS.get(k)) + .copied() + .unwrap_or("text") +} + +/// Converts a `textDocument/completion` answer (`CompletionItem[]`, +/// `CompletionList` or `null`). Items are sorted by `sortText`, then +/// label, and cut at [`MAX_ITEMS`]. +pub fn completion_result(value: &Value) -> Value { + let (list, mut incomplete) = match value { + Value::Array(items) => (items.as_slice(), false), + Value::Object(object) => ( + object + .get("items") + .and_then(Value::as_array) + .map_or(&[][..], Vec::as_slice), + object + .get("isIncomplete") + .and_then(Value::as_bool) + .unwrap_or(false), + ), + _ => (&[][..], false), + }; + if list.len() > MAX_SCANNED { + incomplete = true; + } + let mut items: Vec<(String, String, Value)> = list + .iter() + .take(MAX_SCANNED) + .filter_map(completion_item) + .collect(); + items.sort_by(|a, b| a.0.cmp(&b.0).then_with(|| a.1.cmp(&b.1))); + if items.len() > MAX_ITEMS { + items.truncate(MAX_ITEMS); + incomplete = true; + } + let items: Vec = items.into_iter().map(|(_, _, item)| item).collect(); + json!({ "items": items, "incomplete": incomplete }) +} + +/// Converts one `CompletionItem`; `None` without a label. +/// +/// # Returns +/// The sort key, the label and the item. +fn completion_item(item: &Value) -> Option<(String, String, Value)> { + let label = item.get("label").and_then(Value::as_str)?; + if label.is_empty() { + return None; + } + let label = cap(label, MAX_SHORT); + let snippet = item.get("insertTextFormat").and_then(Value::as_u64) == Some(2); + let plain = |text: &str| { + if snippet { + cap(&snippet_to_text(text), MAX_LONG) + } else { + cap(text, MAX_LONG) + } + }; + let mut out = Map::new(); + out.insert("label".into(), Value::from(label.clone())); + out.insert("kind".into(), Value::from(kind_name(item.get("kind")))); + if let Some(detail) = detail_of(item) { + out.insert("detail".into(), Value::from(detail)); + } + if let Some(doc) = item.get("documentation").and_then(markup) { + out.insert("documentation".into(), Value::from(doc)); + } + let text_edit = item.get("textEdit").and_then(|edit| { + let range = edit + .get("range") + .or_else(|| edit.get("insert")) + .and_then(Range::from_json)?; + let new_text = edit.get("newText").and_then(Value::as_str)?; + Some((range, plain(new_text))) + }); + let insert_text = match (&text_edit, item.get("insertText").and_then(Value::as_str)) { + (Some((_, new_text)), _) => new_text.clone(), + (None, Some(text)) => plain(text), + (None, None) => label.clone(), + }; + out.insert("insertText".into(), Value::from(insert_text)); + if let Some((range, new_text)) = text_edit { + out.insert("textEdit".into(), edit_json(range, new_text)); + } + let extra: Vec = item + .get("additionalTextEdits") + .and_then(Value::as_array) + .map(|edits| { + edits + .iter() + .filter_map(|edit| { + let range = edit.get("range").and_then(Range::from_json)?; + let new_text = edit.get("newText").and_then(Value::as_str)?; + Some(edit_json(range, cap(new_text, MAX_LONG))) + }) + .take(MAX_EXTRA_EDITS) + .collect() + }) + .unwrap_or_default(); + if !extra.is_empty() { + out.insert("additionalTextEdits".into(), Value::from(extra)); + } + let sort_text = item + .get("sortText") + .and_then(Value::as_str) + .map(|s| cap(s, MAX_SHORT)); + if let Some(sort) = &sort_text { + out.insert("sortText".into(), Value::from(sort.clone())); + } + if let Some(filter) = item.get("filterText").and_then(Value::as_str) { + out.insert("filterText".into(), Value::from(cap(filter, MAX_SHORT))); + } + let deprecated = item.get("deprecated").and_then(Value::as_bool) == Some(true) + || item + .get("tags") + .and_then(Value::as_array) + .is_some_and(|tags| tags.iter().any(|t| t.as_u64() == Some(1))); + if deprecated { + out.insert("deprecated".into(), Value::Bool(true)); + } + let key = sort_text.unwrap_or_else(|| label.clone()); + Some((key, label, Value::Object(out))) +} + +/// The item's detail; the label details stand in when it has none. +fn detail_of(item: &Value) -> Option { + if let Some(detail) = item.get("detail").and_then(Value::as_str) + && !detail.is_empty() + { + return Some(cap(detail, MAX_SHORT)); + } + let details = item.get("labelDetails")?; + let parts: Vec<&str> = ["detail", "description"] + .iter() + .filter_map(|k| details.get(*k).and_then(Value::as_str)) + .filter(|s| !s.is_empty()) + .collect(); + (!parts.is_empty()).then(|| cap(&parts.join(" "), MAX_SHORT)) +} + +/// A text edit as Lutra's protocol writes it. +fn edit_json(range: Range, new_text: String) -> Value { + json!({ "range": range_json(range), "newText": new_text }) +} + +/// A range with `{line, column}` positions. +fn range_json(range: Range) -> Value { + json!({ + "start": { "line": range.start.line, "column": range.start.column }, + "end": { "line": range.end.line, "column": range.end.column }, + }) +} + +/// Converts a `textDocument/hover` answer into `{contents, range?}`. +pub fn hover_result(value: &Value) -> Value { + let contents = match value.get("contents") { + Some(Value::Array(parts)) => parts + .iter() + .take(MAX_SIGNATURES) + .filter_map(marked) + .filter(|s| !s.trim().is_empty()) + .collect::>() + .join("\n\n"), + Some(part) => marked(part).unwrap_or_default(), + None => String::new(), + }; + let mut out = Map::new(); + out.insert("contents".into(), Value::from(cap(&contents, MAX_LONG))); + if let Some(range) = value.get("range").and_then(Range::from_json) { + out.insert("range".into(), range_json(range)); + } + Value::Object(out) +} + +/// One hover part as markdown: a `MarkupContent`, a markdown string or a +/// `{language, value}` code block. +fn marked(part: &Value) -> Option { + match part { + Value::String(text) => Some(text.clone()), + Value::Object(object) if object.contains_key("language") => { + let language = object.get("language").and_then(Value::as_str)?; + let code = object.get("value").and_then(Value::as_str)?; + let language: String = language + .chars() + .filter(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '+')) + .collect(); + Some(format!( + "```{language}\n{}\n```", + code.replace("```", "`\u{200b}``") + )) + } + Value::Object(_) => markup(part), + _ => None, + } +} + +/// Documentation as markdown: a `MarkupContent` or a plain string, whose +/// markdown characters are escaped. +fn markup(value: &Value) -> Option { + let (kind, text) = match value { + Value::String(text) => ("plaintext", text.as_str()), + Value::Object(object) => ( + object + .get("kind") + .and_then(Value::as_str) + .unwrap_or("plaintext"), + object.get("value").and_then(Value::as_str)?, + ), + _ => return None, + }; + if text.trim().is_empty() { + return None; + } + let text = cap(text, MAX_LONG); + Some(if kind == "markdown" { + text + } else { + escape_markdown(&text) + }) +} + +/// Escapes the characters markdown gives a meaning, so plain text shows +/// as written. +pub fn escape_markdown(text: &str) -> String { + let mut out = String::with_capacity(text.len()); + for c in text.chars() { + if "\\`*_{}[]()<>#+-.!|~".contains(c) { + out.push('\\'); + } + out.push(c); + } + out +} + +/// Converts a `textDocument/signatureHelp` answer. +pub fn signature_result(value: &Value) -> Value { + let signatures: Vec = value + .get("signatures") + .and_then(Value::as_array) + .map(|list| { + list.iter() + .take(MAX_SIGNATURES) + .filter_map(signature) + .collect() + }) + .unwrap_or_default(); + let index = |key: &str| value.get(key).and_then(Value::as_u64).unwrap_or(0); + json!({ + "signatures": signatures, + "activeSignature": index("activeSignature"), + "activeParameter": index("activeParameter"), + }) +} + +/// Converts one `SignatureInformation`; `None` without a label. +fn signature(value: &Value) -> Option { + let label = cap(value.get("label").and_then(Value::as_str)?, MAX_SHORT * 4); + let length = label.encode_utf16().count(); + let parameters: Vec = value + .get("parameters") + .and_then(Value::as_array) + .map(|list| { + list.iter() + .take(MAX_SIGNATURES * 2) + .map(|p| { + let span = match p.get("label") { + Some(Value::String(text)) if !text.is_empty() => { + label.find(text.as_str()).map(|byte| { + let start = label.get(..byte).unwrap_or("").encode_utf16().count(); + (start, start + text.encode_utf16().count()) + }) + } + Some(Value::Array(pair)) => { + let at = |i: usize| { + pair.get(i) + .and_then(Value::as_u64) + .and_then(|n| usize::try_from(n).ok()) + }; + match (at(0), at(1)) { + (Some(a), Some(b)) if a <= b && b <= length => Some((a, b)), + _ => None, + } + } + _ => None, + }; + let mut out = Map::new(); + out.insert( + "label".into(), + span.map_or(Value::Null, |(a, b)| json!([a, b])), + ); + if let Some(doc) = p.get("documentation").and_then(markup) { + out.insert("documentation".into(), Value::from(doc)); + } + Value::Object(out) + }) + .collect() + }) + .unwrap_or_default(); + let mut out = Map::new(); + out.insert("label".into(), Value::from(label)); + if let Some(doc) = value.get("documentation").and_then(markup) { + out.insert("documentation".into(), Value::from(doc)); + } + out.insert("parameters".into(), Value::from(parameters)); + if let Some(active) = value.get("activeParameter").and_then(Value::as_u64) { + out.insert("activeParameter".into(), Value::from(active)); + } + Some(Value::Object(out)) +} + +/// Turns snippet syntax into the text it inserts: tab stops (`$1`, +/// `${2}`) vanish, placeholders (`${1:name}`) keep their text, choices +/// (`${1|a,b|}`) their first option, escapes (`\$`, `\}`, `\\`) their +/// character. `$` before anything else (a PHP variable) stays. +pub fn snippet_to_text(snippet: &str) -> String { + let mut out = String::with_capacity(snippet.len()); + let chars: Vec = snippet.chars().collect(); + let mut i = 0; + let mut depth = 0usize; + while let Some(&c) = chars.get(i) { + let next = chars.get(i + 1).copied(); + match c { + '\\' if matches!(next, Some('$' | '}' | '\\' | ',' | '|')) => { + if let Some(n) = next { + out.push(n); + } + i += 2; + } + '$' if next.is_some_and(|n| n.is_ascii_digit()) => { + i += 1; + while chars.get(i).is_some_and(char::is_ascii_digit) { + i += 1; + } + } + '$' if next == Some('{') => { + let mut j = i + 2; + while chars.get(j).is_some_and(char::is_ascii_digit) { + j += 1; + } + match chars.get(j) { + Some(':') => { + depth += 1; + i = j + 1; + } + Some('|') => { + depth += 1; + i = j + 1; + let mut first = true; + while let Some(&ch) = chars.get(i) { + if ch == '|' && chars.get(i + 1) == Some(&'}') { + i += 1; + break; + } + if ch == ',' { + first = false; + } else if first { + out.push(ch); + } + i += 1; + } + } + Some('}') => i = j + 1, + _ => { + out.push(c); + i += 1; + } + } + } + '}' if depth > 0 => { + depth -= 1; + i += 1; + } + _ => { + out.push(c); + i += 1; + } + } + } + out +} + +/// `text` cut to at most `max` bytes, on a character boundary. +fn cap(text: &str, max: usize) -> String { + if text.len() <= max { + return text.to_string(); + } + let end = text + .char_indices() + .map(|(i, _)| i) + .take_while(|&i| i <= max) + .last() + .unwrap_or(0); + text.get(..end).unwrap_or("").to_string() +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::{ + MAX_ITEMS, cap, completion_result, escape_markdown, hover_result, kind_name, + signature_result, snippet_to_text, + }; + + #[test] + fn kinds_map_to_names() { + assert_eq!(kind_name(Some(&json!(2))), "method"); + assert_eq!(kind_name(Some(&json!(25))), "typeParameter"); + assert_eq!(kind_name(Some(&json!(0))), "text"); + assert_eq!(kind_name(Some(&json!(99))), "text"); + assert_eq!(kind_name(Some(&json!("x"))), "text"); + assert_eq!(kind_name(None), "text"); + } + + #[test] + fn completion_reads_lists_and_arrays() { + let list = completion_result(&json!({ + "isIncomplete": true, + "items": [ + {"label": "b", "sortText": "2"}, + {"label": "a", "sortText": "1", "kind": 7, "detail": "App\\A", + "documentation": {"kind": "markdown", "value": "**A**"}}, + {"label": ""}, + {"nolabel": true} + ] + })); + assert_eq!(list["incomplete"], true); + let items = list["items"].as_array().unwrap(); + assert_eq!(items.len(), 2); + assert_eq!(items[0]["label"], "a"); + assert_eq!(items[0]["kind"], "class"); + assert_eq!(items[0]["documentation"], "**A**"); + assert_eq!(items[0]["insertText"], "a"); + let array = completion_result(&json!([{"label": "x", "insertText": "x()"}])); + assert_eq!(array["incomplete"], false); + assert_eq!(array["items"][0]["insertText"], "x()"); + assert_eq!(completion_result(&json!(null))["items"], json!([])); + assert_eq!(completion_result(&json!("junk"))["items"], json!([])); + } + + #[test] + fn completion_is_capped_and_marked_incomplete() { + let items: Vec<_> = (0..MAX_ITEMS + 50) + .map(|i| json!({"label": format!("item{i:04}")})) + .collect(); + let out = completion_result(&json!({"isIncomplete": false, "items": items})); + assert_eq!(out["items"].as_array().unwrap().len(), MAX_ITEMS); + assert_eq!(out["incomplete"], true); + assert_eq!(out["items"][0]["label"], "item0000"); + } + + #[test] + fn text_edits_and_snippets_become_plain_text() { + let out = completion_result(&json!([{ + "label": "format", + "insertTextFormat": 2, + "textEdit": {"range": {"start": {"line": 1, "character": 6}, "end": {"line": 1, "character": 8}}, + "newText": "format(${1:\\$pattern})$0"}, + "additionalTextEdits": [{"range": {"start": {"line": 0, "character": 5}, "end": {"line": 0, "character": 5}}, + "newText": "\nuse App\\Fmt;"}], + "documentation": "a < b *c*", + "tags": [1] + }])); + let item = &out["items"][0]; + assert_eq!(item["insertText"], "format($pattern)"); + assert_eq!(item["textEdit"]["newText"], "format($pattern)"); + assert_eq!( + item["textEdit"]["range"], + json!({"start": {"line": 1, "column": 6}, "end": {"line": 1, "column": 8}}) + ); + assert_eq!(item["additionalTextEdits"][0]["newText"], "\nuse App\\Fmt;"); + assert_eq!(item["documentation"], "a \\< b \\*c\\*"); + assert_eq!(item["deprecated"], true); + } + + #[test] + fn label_details_stand_in_for_a_missing_detail() { + let out = completion_result(&json!([{ + "label": "f", "labelDetails": {"detail": "(int $a)", "description": "App"} + }])); + assert_eq!(out["items"][0]["detail"], "(int $a) App"); + } + + #[test] + fn snippets() { + assert_eq!(snippet_to_text("foo($1, $2)$0"), "foo(, )"); + assert_eq!(snippet_to_text("${1:a} ${2:${3:b}}"), "a b"); + assert_eq!(snippet_to_text("${1|one,two|}"), "one"); + assert_eq!(snippet_to_text("\\$this->x"), "$this->x"); + assert_eq!(snippet_to_text("$this"), "$this"); + assert_eq!(snippet_to_text("${x"), "${x"); + assert_eq!(snippet_to_text("${12}a"), "a"); + } + + #[test] + fn hover_parts_become_markdown() { + assert_eq!( + hover_result(&json!({"contents": {"kind": "markdown", "value": "# T"}}))["contents"], + "# T" + ); + let out = hover_result(&json!({ + "contents": [{"language": "php", "value": "class A {}"}, "text", ""], + "range": {"start": {"line": 0, "character": 1}, "end": {"line": 0, "character": 2}} + })); + assert_eq!(out["contents"], "```php\nclass A {}\n```\n\ntext"); + assert_eq!(out["range"]["end"]["column"], 2); + assert_eq!(hover_result(&json!(null)), json!({"contents": ""})); + assert_eq!( + hover_result(&json!({"contents": {"kind": "plaintext", "value": ""}}))["contents"], + "\\" + ); + } + + #[test] + fn signatures_get_utf16_parameter_spans() { + let out = signature_result(&json!({ + "signatures": [{ + "label": "f(\u{1f600} $a, int $b)", + "documentation": "doc", + "parameters": [{"label": "\u{1f600} $a"}, {"label": [9, 15]}, {"label": [3, 99]}, {"label": "zz"}] + }], + "activeSignature": 0, + "activeParameter": 1 + })); + let sig = &out["signatures"][0]; + assert_eq!(sig["parameters"][0]["label"], json!([2, 7])); + assert_eq!(sig["parameters"][1]["label"], json!([9, 15])); + assert_eq!(sig["parameters"][2]["label"], json!(null)); + assert_eq!(sig["parameters"][3]["label"], json!(null)); + assert_eq!(out["activeParameter"], 1); + assert_eq!(signature_result(&json!(null))["signatures"], json!([])); + } + + #[test] + fn caps_cut_on_character_boundaries() { + assert_eq!(cap("äöü", 3), "ä"); + assert_eq!(cap("abc", 10), "abc"); + assert_eq!(escape_markdown("a_b"), "a\\_b"); + } +} diff --git a/crates/engine/src/cmd/mod.rs b/crates/engine/src/cmd/mod.rs index 5a14af2..59bd663 100644 --- a/crates/engine/src/cmd/mod.rs +++ b/crates/engine/src/cmd/mod.rs @@ -4,6 +4,7 @@ mod app; mod buffer; mod file; pub mod goto; +mod lsp_assist; mod lsp_diagnostics; mod params; mod project; @@ -60,5 +61,6 @@ pub fn register_builtins(registry: &mut Registry) -> Result<(), EngineError> { registry.register(Box::new(terminal::Resize))?; registry.register(Box::new(terminal::Close))?; lsp_diagnostics::register(registry)?; + lsp_assist::register(registry)?; Ok(()) } diff --git a/crates/engine/src/engine.rs b/crates/engine/src/engine.rs index 58e1307..68e8f87 100644 --- a/crates/engine/src/engine.rs +++ b/crates/engine/src/engine.rs @@ -467,7 +467,10 @@ mod tests { "goto.file", "goto.symbol", "index.status", + "lsp.completion", + "lsp.hover", "lsp.restart", + "lsp.signatureHelp", "lsp.status", "project.children", "project.close", diff --git a/crates/engine/tests/lsp_assist.rs b/crates/engine/tests/lsp_assist.rs new file mode 100644 index 0000000..a057f23 --- /dev/null +++ b/crates/engine/tests/lsp_assist.rs @@ -0,0 +1,477 @@ +//! Completion, hover and signature help (M3.4) against `lutra-lsp-fake`, +//! whose answers are scripted (see its `completion` function). The +//! commands return pending results, which the tests wait for without the +//! engine lock and resolve with it (`run_waiting`), as hosts do. + +#![allow( + clippy::unwrap_used, + clippy::expect_used, + clippy::panic, + clippy::indexing_slicing +)] + +use std::ffi::OsString; +use std::fs; +use std::path::PathBuf; + +use lutra_engine::lsp::Launch; +use lutra_engine::{Engine, EngineError}; +use lutra_lsp::ServerOptions; +use serde_json::{Value, json}; +use tempfile::TempDir; + +/// The fake server binary, built on demand when this test runs without +/// the rest of the workspace (`cargo test -p lutra-engine`). +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 temp project with `files`, opened in an engine that runs the fake +/// server (or none). +fn project(files: &[(&str, &str)], server: bool) -> (TempDir, Engine) { + let dir = tempfile::tempdir().unwrap(); + for (name, text) in files { + fs::write(dir.path().join(name), text).unwrap(); + } + let mut engine = Engine::new().unwrap(); + if server { + engine.set_language_server(Some(Launch { + command: fake_server().into(), + args: Vec::::new(), + options: ServerOptions::default(), + tick: None, + })); + } + engine + .execute("project.open", json!({"path": dir.path()})) + .unwrap(); + (dir, engine) +} + +/// Opens `path`; returns the buffer id. +fn open(engine: &mut Engine, path: &str) -> u64 { + engine + .execute("file.open", json!({"path": path})) + .unwrap() + .value["id"] + .as_u64() + .unwrap() +} + +/// Runs `command` and waits for its pending result, as a host does. +fn ask(engine: &mut Engine, command: &str, params: Value) -> Result { + let mut outcome = engine.execute(command, params)?; + match outcome.pending.take() { + Some(pending) => Ok(engine.resolve(pending.wait())?.value), + None => Ok(outcome.value), + } +} + +#[test] +fn completion_converts_the_servers_list() { + let (_dir, mut engine) = project(&[("a.php", "fo")], true); + let id = open(&mut engine, "a.php"); + let out = ask( + &mut engine, + "lsp.completion", + json!({"id": id, "position": {"line": 1, "column": 6}}), + ) + .unwrap(); + assert_eq!(out["incomplete"], true); + let items = out["items"].as_array().unwrap(); + let labels: Vec<&str> = items.iter().map(|i| i["label"].as_str().unwrap()).collect(); + assert_eq!(labels, ["format", "$value", "pair", "trigger:none"]); + let format = &items[0]; + assert_eq!(format["kind"], "method"); + assert_eq!(format["detail"], "format(string $pattern): string"); + assert_eq!(format["documentation"], "Formats **text**."); + assert_eq!(format["insertText"], "format("); + assert_eq!( + format["textEdit"], + json!({"range": {"start": {"line": 1, "column": 4}, "end": {"line": 1, "column": 6}}, "newText": "format("}) + ); + assert_eq!( + format["additionalTextEdits"][0]["newText"], + "\nuse App\\Fmt;" + ); + assert_eq!(items[1]["kind"], "variable"); + assert_eq!(items[1]["insertText"], "$value"); + assert_eq!(items[2]["insertText"], "pair($a, )"); + + let triggered = ask( + &mut engine, + "lsp.completion", + json!({"id": id, "position": {"line": 1, "column": 4}, "triggerCharacter": ">"}), + ) + .unwrap(); + assert_eq!(triggered["items"][3]["label"], "trigger:>"); +} + +#[test] +fn completion_sees_the_edit_before_it_and_is_capped() { + let (_dir, mut engine) = project(&[("a.php", " u128 { + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_millis() +} + +/// Times `f`. +fn timed(f: impl FnOnce() -> T) -> (T, f64) { + let start = std::time::Instant::now(); + let value = f(); + (value, start.elapsed().as_secs_f64() * 1000.0) +} + +/// Replaces line `line` (0-based) of buffer `id` with `text`. +fn set_line(engine: &mut Engine, id: u64, line: usize, text: &str) { + let current = engine + .execute("buffer.get", json!({"id": id})) + .unwrap() + .value; + let whole = current["text"].as_str().unwrap(); + let from: usize = whole + .split('\n') + .take(line) + .map(|l| l.encode_utf16().count() + 1) + .sum(); + let to = from + whole.split('\n').nth(line).unwrap().encode_utf16().count(); + engine + .execute( + "buffer.edit", + json!({"id": id, "baseVersion": current["version"], "edits": [{"from": from, "to": to, "insert": text}]}), + ) + .unwrap(); +} + +/// Min, median and max of `samples` in ms. +fn summary(samples: &mut [f64]) -> String { + samples.sort_by(f64::total_cmp); + let n = samples.len(); + format!( + "n={n} min={:.0} median={:.0} max={:.0} ms", + samples[0], + samples[n / 2], + samples[n - 1] + ) +} + +/// A shop-like project: `classes` classes in `src/` plus the file the +/// test types in. +fn shop(classes: usize) -> Vec<(String, String)> { + let mut files = Vec::new(); + for i in 0..classes { + files.push(( + format!("src/Product{i}.php"), + format!( + "name;\n }}\n\n /** The price in cents, times `$count`. */\n public function price(int $count = 1, bool $gross = true): int\n {{\n return $this->price * $count;\n }}\n}}\n" + ), + )); + } + files.push(( + "src/Cart.php".into(), + "\n }\n}\n".into(), + )); + files +} + +/// Completion, hover and signature help against the real Phpactor, with +/// latencies and phase timestamps (`PHASE `) +/// for an outside sampler of the Phpactor process: +/// +/// `LUTRA_PHPACTOR= [LUTRA_PHP=php] [LUTRA_SHOP_CLASSES=20] cargo test -p lutra-engine --test lsp_assist real_phpactor -- --ignored --nocapture` +#[test] +#[ignore = "needs PHP and Phpactor (LUTRA_PHPACTOR)"] +fn real_phpactor_assist_latency() { + let phar = std::env::var("LUTRA_PHPACTOR").expect("LUTRA_PHPACTOR"); + let php = std::env::var("LUTRA_PHP").unwrap_or_else(|_| "php".into()); + let classes: usize = std::env::var("LUTRA_SHOP_CLASSES") + .ok() + .and_then(|n| n.parse().ok()) + .unwrap_or(20); + let dir = tempfile::tempdir().unwrap(); + for (name, text) in shop(classes) { + let path = dir.path().join(name); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(path, text).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 started = std::time::Instant::now(); + loop { + let ready = engine + .pump_vfs() + .unwrap() + .iter() + .any(|e| serde_json::to_value(e).unwrap()["state"] == "ready"); + if ready { + break; + } + assert!(started.elapsed().as_secs() < 60, "Phpactor not ready"); + std::thread::sleep(std::time::Duration::from_millis(10)); + } + println!("ready after {:?} ({classes} classes)", started.elapsed()); + let id = open(&mut engine, "src/Cart.php"); + let at_arrow = + json!({"id": id, "position": {"line": 8, "column": 18}, "triggerCharacter": ">"}); + let opened = std::time::Instant::now(); + let mut attempts = 0; + let first = loop { + attempts += 1; + let (out, ms) = timed(|| ask(&mut engine, "lsp.completion", at_arrow.clone()).unwrap()); + let found = out["items"] + .as_array() + .unwrap() + .iter() + .any(|i| i["label"] == "price"); + if attempts == 1 { + println!("first completion after -> {ms:.0} ms: {out}"); + } + if found { + break out; + } + assert!( + opened.elapsed().as_secs() < 90, + "no useful completion within 90 s: {out}" + ); + std::thread::sleep(std::time::Duration::from_millis(250)); + }; + println!( + "useful completion {:?} after file.open ({attempts} attempts)", + opened.elapsed() + ); + let labels: Vec<&str> = first["items"] + .as_array() + .unwrap() + .iter() + .map(|i| i["label"].as_str().unwrap()) + .collect(); + println!("labels: {labels:?}"); + println!("first item: {}", first["items"][0]); + + println!("PHASE idle start {}", epoch_ms()); + std::thread::sleep(std::time::Duration::from_secs(70)); + println!("PHASE idle end {}", epoch_ms()); + + let (_, after_idle) = timed(|| ask(&mut engine, "lsp.completion", at_arrow.clone()).unwrap()); + println!("completion after 70 s idle (ticks stopped) {after_idle:.0} ms"); + + println!("PHASE typing start {}", epoch_ms()); + let mut completion = Vec::new(); + for round in 0..15 { + let typed = ["", "p", "pr"][round % 3]; + let line = format!(" $product->{typed}"); + set_line(&mut engine, id, 8, &line); + let (_, ms) = timed(|| { + ask( + &mut engine, + "lsp.completion", + json!({"id": id, "position": {"line": 8, "column": line.encode_utf16().count()}}), + ) + .unwrap() + }); + completion.push(ms); + std::thread::sleep(std::time::Duration::from_millis(150)); + } + println!("completion while typing: {}", summary(&mut completion)); + let call = " $product->price(1, "; + set_line(&mut engine, id, 8, call); + let mut signature = Vec::new(); + for _ in 0..10 { + let (out, ms) = timed(|| { + ask( + &mut engine, + "lsp.signatureHelp", + json!({"id": id, "position": {"line": 8, "column": call.encode_utf16().count()}}), + ) + .unwrap() + }); + signature.push(ms); + if signature.len() == 1 { + println!("signature help: {out}"); + } + } + println!("signature help: {}", summary(&mut signature)); + let mut hover = Vec::new(); + for _ in 0..10 { + let (out, ms) = timed(|| { + ask( + &mut engine, + "lsp.hover", + json!({"id": id, "position": {"line": 6, "column": 26}}), + ) + .unwrap() + }); + hover.push(ms); + assert!( + out["contents"].as_str().unwrap().contains("Product0"), + "{out}" + ); + } + println!("hover on a class: {}", summary(&mut hover)); + let text = ask( + &mut engine, + "lsp.hover", + json!({"id": id, "position": {"line": 6, "column": 26}}), + ) + .unwrap(); + println!("hover contents: {}", text["contents"]); + println!("PHASE typing end {}", epoch_ms()); +} diff --git a/crates/lsp/src/bin/lutra-lsp-fake.rs b/crates/lsp/src/bin/lutra-lsp-fake.rs index 4c561b5..641752a 100644 --- a/crates/lsp/src/bin/lutra-lsp-fake.rs +++ b/crates/lsp/src/bin/lutra-lsp-fake.rs @@ -16,6 +16,9 @@ //! document version; `didClose` publishes no diagnostics; `didSave` sends //! `fake/saved` with the text it received. //! - Requests: `textDocument/hover` answers `hover L:C`, +//! `textDocument/completion` a scripted list (see [`completion`]), +//! `textDocument/signatureHelp` one signature whose active parameter is +//! the column modulo 2, //! `textDocument/definition` the same position, `fake/echo` its params, //! `fake/error` an error, `fake/sleep` never answers until cancelled //! (then `RequestCancelled` and the notification `fake/cancelled`), @@ -47,6 +50,46 @@ struct Fake { init_error: bool, } +/// The fake answer to `textDocument/completion`: a `CompletionList` whose +/// first item replaces the word before the cursor through a `textEdit` +/// (with an import as `additionalTextEdits`), then a plain variable, a +/// snippet and an item echoing the trigger character. A document +/// containing `MANY` gets 700 numbered items instead. +fn completion(text: &str, position: &Value, context: &Value) -> Value { + if text.contains("MANY") { + let items: Vec = (0..700) + .map(|i| json!({"label": format!("item{i:03}"), "kind": 6})) + .collect(); + return json!({"isIncomplete": false, "items": items}); + } + let line = at(position, "/line").as_u64().unwrap_or(0); + let character = at(position, "/character").as_u64().unwrap_or(0); + let trigger = at(context, "/triggerCharacter").as_str().unwrap_or("none"); + json!({ + "isIncomplete": true, + "items": [ + { + "label": "format", + "kind": 2, + "detail": "format(string $pattern): string", + "documentation": {"kind": "markdown", "value": "Formats **text**."}, + "sortText": "0001", + "textEdit": { + "range": {"start": {"line": line, "character": character.saturating_sub(2)}, "end": {"line": line, "character": character}}, + "newText": "format(" + }, + "additionalTextEdits": [{ + "range": {"start": {"line": 0, "character": 5}, "end": {"line": 0, "character": 5}}, + "newText": "\nuse App\\Fmt;" + }] + }, + {"label": "$value", "kind": 6, "sortText": "0002"}, + {"label": "pair", "kind": 3, "insertTextFormat": 2, "insertText": "pair(${1:\\$a}, $2)$0", "sortText": "0003"}, + {"label": format!("trigger:{trigger}"), "kind": 14, "sortText": "0004"} + ] + }) +} + /// Runs the fake server until `exit` or the end of stdin. fn main() { let args: Vec = std::env::args().skip(1).collect(); @@ -148,7 +191,9 @@ impl Fake { "positionEncoding": "utf-16", "textDocumentSync": {"openClose": true, "change": change, "save": {"includeText": true}}, "hoverProvider": true, - "definitionProvider": true + "definitionProvider": true, + "completionProvider": {"triggerCharacters": [">", ":", "$", "\\"]}, + "signatureHelpProvider": {"triggerCharacters": ["(", ","]} }, "serverInfo": {"name": "fake"} })), @@ -172,6 +217,38 @@ impl Fake { Ok(json!([{"uri": uri, "range": {"start": position, "end": position}}])), ); } + "textDocument/completion" => { + let uri = at(params, "/textDocument/uri").as_str().unwrap_or_default(); + let text = self + .documents + .get(uri) + .map(Buffer::text) + .unwrap_or_default(); + respond( + id, + Ok(completion( + &text, + at(params, "/position"), + at(params, "/context"), + )), + ); + } + "textDocument/signatureHelp" => { + let position = at(params, "/position"); + let active = at(position, "/character").as_u64().unwrap_or(0) % 2; + respond( + id, + Ok(json!({ + "signatures": [{ + "label": "pair(int $a, string $b): void", + "documentation": {"kind": "markdown", "value": "Makes a *pair*."}, + "parameters": [{"label": "int $a"}, {"label": [13, 22]}] + }], + "activeSignature": 0, + "activeParameter": active + })), + ); + } "fake/echo" => respond(id, Ok(params.clone())), "fake/error" => respond(id, Err(error(-32001, "boom"))), "fake/sleep" => self.sleeping.push(id), diff --git a/docs/architecture.md b/docs/architecture.md index c7430a2..8083e2c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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 | diff --git a/docs/gaps.md b/docs/gaps.md index 671108a..31523ce 100644 --- a/docs/gaps.md +++ b/docs/gaps.md @@ -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); G7 under way (`lutra` CLI and single instance, MCP server, integrated terminal); G14 English UI catalog in place · **Last updated:** 2026-10-21 +> **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 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) | M3 | ~33 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 | | 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`). Still open: completion and hover (M3.4), navigation and rename (M3.5), 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). 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. ## Revision history | Date | Change | Summary | |---|---|---| +| 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) | | 2026-10-19 | minor | G7: MCP server (M3.8) | diff --git a/docs/language-parity.md b/docs/language-parity.md index d98f466..ada8ea1 100644 --- a/docs/language-parity.md +++ b/docs/language-parity.md @@ -1,6 +1,6 @@ # PHP language checklist -> **Status:** baseline · **Last updated:** 2026-10-13 · Reference: php.net and the PHP RFCs +> **Status:** baseline; completion and hover partial via Phpactor (M3.4) · **Last updated:** 2026-10-22 · Reference: php.net and the PHP RFCs - [ ] Parsing of PHP 8.0–8.4 syntax (attributes, match, enums, readonly, first-class callables, property hooks, asymmetric visibility) - [ ] Highlighting, including heredoc/nowdoc and embedded HTML @@ -8,6 +8,7 @@ - [ ] Go to declaration and implementation - [ ] Find usages - [ ] 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 @@ -18,4 +19,5 @@ | Date | Change | Summary | |---|---|---| +| 2026-10-22 | minor | Completion partial via Phpactor (M3.4) | | 2026-10-13 | major | Baseline | diff --git a/docs/roadmap.md b/docs/roadmap.md index 83af4c3..b46106d 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,6 +1,6 @@ # Milestones -> **Status:** M0 done, M1 done, M2 in progress · **Last updated:** 2026-10-21 +> **Status:** M0 done, M1 done, M2 in progress · **Last updated:** 2026-10-22 Hours are agent wall-clock hours for one agent; M0 and M1 so far are measured, the rest estimated. Since cycle C1 (factor 0.07) M1–M3 are scaled ×0.1; M4–M6 keep their first raw estimates (multiply by ~0.1 for the calibrated value). @@ -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 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 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.4 completion, hover and signature help | | 2026-10-21 | minor | M3.3 engine wiring and diagnostics | | 2026-10-20 | minor | M3.10 autosave | | 2026-10-18 | minor | M3.6 integrated terminal | diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md index 46a2c37..72c5fd2 100644 --- a/docs/target-app-parity.md +++ b/docs/target-app-parity.md @@ -1,6 +1,6 @@ # Target-app parity -> **Status:** M1 done (text buffer, VFS, engine workspace, project tree, tabs and a plain-text editor, recovery, palette, settings and themes in the app); M2 started: PHP syntax highlighting, find in files with its tool window, the symbol index and the go-to popup, the Structure tool window; M3 started: the integrated terminal · **Last updated:** 2026-10-21 · **Target:** PhpStorm 2026.x +> **Status:** M1 done (text buffer, VFS, engine workspace, project tree, tabs and a plain-text editor, recovery, palette, settings and themes in the app); M2 started: PHP syntax highlighting, find in files with its tool window, the symbol index and the go-to popup, the Structure tool window; M3 started: the integrated terminal · **Last updated:** 2026-10-22 · **Target:** PhpStorm 2026.x ## How this is measured @@ -9,7 +9,7 @@ Each feature area gets a weight (how much a typical PHP developer uses it) and a Hours are the estimated agent wall-clock hours for one agent to reach behaviour parity in the area, from zero. They are first estimates made at the end of M0 and are recalibrated after each milestone from merged-commit timestamps. -**Breadth inventory (2026-10-18).** Breadth is counted against the public PhpStorm help table of contents (https://www.jetbrains.com/help/phpstorm/HelpTOC.json): 155 level-1 feature units across 20 sections, without getting-started, reference, tutorial, troubleshooting and FAQ pages. A unit counts when Lutra has at least partial behaviour for it. Now 23/155 (~15%, estimated); the running cycle C4 adds 9 (completion, diagnostics, rename, hover, PHP interpreter, terminal, CLI, MCP server, main menu). Sections with no support yet: version control, debugging, run configurations, testing and profiling, code quality tools, frameworks (Laravel, Symfony, WordPress, others), deployment, database tools, HTTP client, SSH/Docker/WSL, remote development, Dev Containers, AI. Only titles and URLs are used; behaviour is read from each public page when the feature is planned. +**Breadth inventory (2026-10-18).** Breadth is counted against the public PhpStorm help table of contents (https://www.jetbrains.com/help/phpstorm/HelpTOC.json): 155 level-1 feature units across 20 sections, without getting-started, reference, tutorial, troubleshooting and FAQ pages. A unit counts when Lutra has at least partial behaviour for it. Now 26/155 (~17%, estimated; M3.4 added completion and hover); the running cycle C4 adds 9 (completion, diagnostics, rename, hover, PHP interpreter, terminal, CLI, MCP server, main menu). Sections with no support yet: version control, debugging, run configurations, testing and profiling, code quality tools, frameworks (Laravel, Symfony, WordPress, others), deployment, database tools, HTTP client, SSH/Docker/WSL, remote development, Dev Containers, AI. Only titles and URLs are used; behaviour is read from each public page when the feature is planned. ## Feature areas | Area | Weight | Score | Missing | Hours (one agent) | Evidence | @@ -18,7 +18,7 @@ Hours are the estimated agent wall-clock hours for one agent to reach behaviour | Project view, VFS | 6 | 8% (est.) | views list (project / scopes), toolbar (Select Opened File, Expand/Collapse All), sort and display options, show/hide excluded, distinct icons for library and excluded folders, file colours, speed search, preview, file operations | ~37 (est.) | `lutra-vfs` (M1.2): lazy sorted listing, ignore rules (.gitignore, .ignore, info/exclude, global excludes, Lutra defaults), native file watching via `notify` with a polling fallback, capped UTF-8 reads, atomic writes; 34 tests on temp dirs, watcher tests run on both backends (`crates/vfs/tests`). M1.5: project tree UI (lazy listing, keyboard navigation, dimmed ignored entries, event refresh) in `ui/src/components/project/`, Vitest against a mocked engine. M1.3: `project.open`, `project.close`, `project.children` (watches listed directories, capped at 256 native / 32 polling, least recently listed dropped), `treeChanged` events from disk, `events.subscribe` on the control channel with a TCP test (`crates/control/tests/events.rs`). M1.4: the tree runs against the engine in the app: folder picker (`project.openDialog`) and `lutra-desktop --control PORT PATH` open a project, the tree lists it lazily with ignored (`var/` from `.gitignore`) and excluded (`node_modules`) entries dimmed, a file created on disk appears in an expanded folder within ~100 ms; verified with `ui.screenshot` on Windows 11 and Vitest (`ui/tests/project/`, `ui/tests/ipcEvents.test.ts`). M1.13: a directory listed only partly (more than 100,000 entries) ends with a "Listing truncated" note row (Vitest). M1.12: a folder that cannot be opened from the picker or the command line (including `unsaved_changes` when switching projects) and stopped file watching show as toasts instead of stderr (`apps/lutra-desktop/src/host.rs`, `ui/src/stores/notifications.ts`, `ui/tests/notifications/`, 19 Vitest tests; live check pending, gaming mode); score unchanged. Graded against `plan/phpstorm/02-project-view.md`: tool window, folder-first tree, dimmed ignored/excluded, keyboard navigation and live refresh exist; most toolbar, view and display options do not | | Navigation | 10 | 10% (est.) | go-to: recent files on an empty query, a non-project toggle (library items always show), file-type filter, `:line` suffixes, actions and text tabs, sending the list to Find; find usages, go to declaration, recent files and locations, navigation history, File Structure popup, Structure speed search, sorting and filters (visibility, inherited members), autoscroll from the caret, navigation bar, bookmarks (M1.8: a command palette over commands only) | ~102 (est.) | M2.6: go-to popup `ui/src/components/goto/` with Files / Classes / Symbols tabs (Tab and Shift+Tab or a click switch, the text stays), UI commands `goto.fileOpen` `Mod+P`, `goto.classOpen` `Mod+Alt+C`, `goto.symbolOpen` `Mod+T` (optional `{query}` for agents), live query against `goto.*` (60 ms debounce, stale answers dropped), matched characters marked, directory / namespace / container column, library rows dimmed and labelled (`goto.file` items now carry `library`), an indexing hint with progress and a re-query on `indexReady`, Enter or a click opens through `editor.reveal`, Escape closes, one modal at a time; Vitest `ui/tests/goto/`, live-checked in the app (port 7826). M2.7: Structure tool window (`ui/src/components/structure/`) in a new left stripe with Project | Structure: the active tab's outline as a tree with Lucide kind icons and signatures, follows the active tab and edits (`outlineChanged`), click or Enter jumps through `editor.reveal`, arrows fold, `view.toggleStructure` `Mod+2`; engine `syntax.outline {id}` from a per-buffer tree-sitter tree reparsed off the engine lock on a worker thread (200 ms debounce). Tests: 11 engine unit tests, engine integration tests with a proptest of random edit sequences (end at a fresh parse's outline), a control-channel test (`crates/control/tests/syntax.rs`), 13 Vitest tests (`ui/tests/structure/`). Checked in the app on Windows 11 (bundled UI, control port 7827): a class file with namespace, interface, enum, trait, class with promoted property and a function; `outlineChanged` 149 ms after `file.open`, `view.toggleStructure` shows the tree, a jump to `find` centres line 62, an added method appears about 0.3 s after `buffer.edit` (debug build). Rows were not clicked in the app (the control channel has no input method); click and Enter are covered by Vitest. 1 MB file: `buffer.edit` ≤ 0.25 ms and `pump_vfs` ≤ 3.8 ms under the lock, edit to `outlineChanged` 0.43–0.76 s, `syntax.outline` 82 ms (release, measured). Graded against `plan/phpstorm/09-structure.md`. M2.5: symbol index in `crates/index` (every project file listed, `.php` parsed in parallel from tree-sitter outlines, vendor marked library, incremental on disk and buffer changes, capped at 200,000 files) and the engine commands `index.status`, `goto.file`, `goto.class`, `goto.symbol` (fuzzy, file names weighted, `Class::member`, project before library, partial results with `indexing: true`), events `indexProgress`/`indexReady`; 20k-file / 88 MB generated project indexed in 3.9–4.2 s (release, measured), queries 2–12 ms; tests `crates/index/tests/`, `crates/engine/tests/goto.rs`, `crates/control/tests/goto.rs`; reached from the UI by M2.6. M2.1: file outline in `crates/syntax` (namespaces braced and unbraced, classes, interfaces, traits, enums with cases, functions, methods, properties incl. promoted ones, constants; UTF-16 ranges and short signatures), the base for the Structure window (M2.7) and the symbol index (M2.5); not reachable from the UI yet, score unchanged. M1.8: `ui/src/components/palette/`, `ui/src/commands/` (fuzzy ranking, recent commands, global keymap), Vitest `ui/tests/palette/`, `ui/tests/commands/` | | Search and replace | 6 | 8% (est.) | find in the current file, replace in files and in a file, scopes (module, directory, open files, custom), comment/string filters, search history, a tab per search, grouping options, merging matches on one line, find in path from the tree, structural search | ~70 (est.) | M2.4 Find tool window in a new resizable, collapsible bottom panel: query with case / whole word / regex toggles, include and exclude globs, streamed results grouped by file (sorted) with the match highlighted in the line preview, counts and elapsed time, cancel, a truncated hint, a refused regex or glob shown in place; Enter or click opens the match through `editor.reveal`, arrow keys / Page / Home / End walk the results; `find.open` (`Mod+Alt+F`, Lutra's own) prefills the selection or the word at the cursor, `find.open {query}` from an agent searches at once; a new search cancels the running one. Tests: 26 Vitest store and component tests (`ui/tests/find/FindToolWindow.test.ts`). Live check (bundled-ui debug build, control port 7824, 3-file temp project): `find.open {query}` over `uiCommand` showed 14 matches in 3 files (vendor included) grouped and highlighted in 17 ms; with `*.php` include 2 matches; revealing a result's position opened the file at the match; `find.open` without params prefilled the word at the cursor; a bad regex showed the engine's message in place (screenshots read, measured). Opening a result by mouse or Enter is covered by Vitest only (the control channel cannot click). M2.3 backend: `crates/search` (parallel `ignore` walk + `grep-searcher`: literal/regex, case, whole word, include/exclude globs, project ignore rules with `vendor/` searched and `node_modules` skipped, binary and > 8 MiB files skipped, match cap, cancel) and engine `search.find` / `search.cancel` with `searchResults` / `searchDone` events through the pump; dirty buffers are searched in their buffer text. Tests: 9 library tests incl. a property test of random queries and file bytes (`crates/search/tests/search.rs`), 3 preview/column unit tests, 4 engine tests (`crates/engine/tests/search.rs`), a TCP control-channel test (find → results → done, invalid regex, cancel; `crates/control/tests/search.rs`). 20k-file generated tree, release: first result 10–43 ms, full walk 0.66–1.43 s (measured); live over the control channel against the running app: first result 55 ms, done 386 ms on a 5,900-file project (debug build, measured) | -| Code completion | 10 | 0% | everything | ~250 (est.) | — | +| Code completion | 10 | 5% (est.) | type-matching and second-invocation completion, postfix completion, live templates, path completion, ranking options and the replace-on-accept variant, accept characters, auto-insert of a single suggestion, auto-import checked against the real Phpactor (applied when the server sends it; tested with the fake server only), completion settings (auto popup, delay, case), parameter info settings, a documentation tool window, type info, faster indexing on Windows (Phpactor's tick-driven loop takes ~65 s for 2,000 classes) | ~240 (est.) | M3.4: completion, hover and signature help from Phpactor. Engine `lsp.completion {id, position, triggerCharacter?}` (items with label, kind, detail, Markdown documentation, insertText, textEdit, additionalTextEdits, sortText; at most 500, sorted by sortText, `incomplete` when cut or when the server says so; snippets turned into plain text), `lsp.hover` (Markdown, range) and `lsp.signatureHelp` (UTF-16 parameter spans), sent off the engine lock through M3.5's pending outcomes (`crates/engine/src/cmd/lsp_assist.rs`). Editor (`ui/src/components/editor/assist/`): a CodeMirror completion source with Lutra's own triggers (identifiers, `$`, `->`, `?->`, `::`, namespace `\`; not in strings or comments unless asked), the server's ranking as boost, local filtering for complete lists, text edits and imports applied in UTF-16 (CRLF files too), Lucide kind icons; hover documentation after 350 ms and on demand (`editor.quickDocumentation` `Mod+I`); signature help on `(` and `,` that follows the cursor (`editor.parameterInfo`); `editor.complete`; Markdown rendered by Lutra's own renderer without any HTML (XSS-tested). Tests: 6 engine tests against the fake server, 9 unit tests, 29 Vitest tests, an ignored test against the real PHAR. Measured with the real Phpactor on Windows 11 (debug build, 25 ms tick): completion while typing 61–109 ms (median 76 ms; ~107 ms through the control channel in the app), hover 4–91 ms (median 15–16 ms), signature help 4–28 ms (median 16 ms); a useful list 2.3 s after opening a file of a 20-class project and 65 s for 2,000 classes (Phpactor indexes first and answers with an empty incomplete list until then). Checked in the app (port 7934): completion after `->`, quick documentation of a class, parameter info with the active parameter, screenshots read. Graded against `plan/phpstorm/12-completion.md`: the depth comes from Phpactor (members, classes, variables, keywords; detail and documentation often missing), Lutra has no type inference of its own | | Inspections and quick-fixes | 8 | 4% (est.) | Lutra's own inspections and their settings, severities per inspection, quick-fixes (LSP code actions), suppression, inspection profiles, running inspections on a scope, PHP lint syntax errors on Windows, the editor's problem counter and scrollbar marks, next/previous problem, a current-file Problems view and severity filters, external tools (PHPStan, Psalm, PHP_CodeSniffer) | ~290 (est.) | M3.3: diagnostics from Phpactor (worse reflection: missing members, unknown classes, …) as wavy underlines, gutter markers and hover messages in the editor (`ui/src/components/editor/lint.ts`, tokens only), and a Problems tab in the bottom panel grouped by file with click to reveal (`ui/src/components/problems/`, `problems.open` `Mod+Alt+P`); engine `diagnosticsChanged`, `diagnostics.list`, `lspStatus` (`crates/engine/src/lsp/`). Tests: 10 engine tests against a fake server incl. a sync proptest, a TCP test, 16 Vitest tests, an ignored test against the real PHAR. Checked in the app on Windows 11 with the real Phpactor (port 7933): five errors underlined and listed; first diagnostics 2.7 s after `file.open`, 2.7–2.9 s after an edit (debug build, measured, incl. Phpactor's 1 s debounce). Graded against `plan/phpstorm/11-problems.md`: the depth comes from Phpactor, Lutra has no inspections of its own | | Refactoring | 7 | 0% | everything | ~250 (est.) | — | | Code style and formatting | 4 | 0% | everything | ~120 (est.) | — | @@ -65,6 +65,7 @@ The project tree is the first user-visible feature (Project view 8%, estimated); | Date | Change | Summary | |---|---|---| +| 2026-10-22 | minor | M3.4: Code completion 0% → 5% (est.), completion, hover and signature help from Phpactor; hours 250 → 240; breadth 26/155 | | 2026-10-21 | minor | M3.3: Inspections and quick-fixes 0% → 4% (est.), diagnostics from Phpactor and the Problems tab; hours 300 → 290 | | 2026-10-20 | minor | M3.10: Editor core 10% → 11% (est.), autosave and `flushDirty`; hours 104 → 100 | | 2026-10-18 | minor | M3.6: Terminal 0% → 15% (est.), integrated terminal with xterm.js sub-tabs | diff --git a/docs/ui-parity.md b/docs/ui-parity.md index 79926f8..3d35a8e 100644 --- a/docs/ui-parity.md +++ b/docs/ui-parity.md @@ -1,6 +1,6 @@ # UI parity checklist -> **Status:** main window layout (M1.5), project tree running against the engine (M1.4), editor tabs with a CodeMirror editor (M1.6), light and dark themes (M1.10), restore dialog for unsaved changes (M1.7), notification toasts (M1.12), command palette and global keymap (M1.8), settings dialog with search (M1.9b), syntax highlighting and `editor.reveal` (M2.2), Find tool window in the bottom panel (M2.4), go-to popup (M2.6), left stripe and Structure tool window (M2.7), app menu (M3.9), Terminal tool window and bottom panel tabs (M3.6), Problems tool window and editor diagnostics (M3.3) · **Last updated:** 2026-10-21 +> **Status:** main window layout (M1.5), project tree running against the engine (M1.4), editor tabs with a CodeMirror editor (M1.6), light and dark themes (M1.10), restore dialog for unsaved changes (M1.7), notification toasts (M1.12), command palette and global keymap (M1.8), settings dialog with search (M1.9b), syntax highlighting and `editor.reveal` (M2.2), Find tool window in the bottom panel (M2.4), go-to popup (M2.6), left stripe and Structure tool window (M2.7), app menu (M3.9), Terminal tool window and bottom panel tabs (M3.6), Problems tool window and editor diagnostics (M3.3), completion, quick documentation and parameter info (M3.4) · **Last updated:** 2026-10-22 - [ ] Main window: tool window stripes, editor area, status bar, navigation bar - M2.7 (2026-10-17): a left stripe with one tab per left tool window (Project, Structure); the shown one is marked, clicking it again hides the window. Still missing: right docking, several bottom tool windows, drag to rearrange, navigation bar, layout persistence. @@ -30,6 +30,8 @@ - M2.7 (2026-10-17): in the left tool window, chosen from the new stripe (Project | Structure); the active tab's declarations (namespaces, class-likes, functions, methods, properties, constants, enum cases) as a WAI-ARIA tree with Lucide kind icons in syntax colours and the short signature; follows the active tab and edits; click or Enter jumps to the name (`editor.reveal`), arrows walk and fold, collapsed nodes kept per file; empty states for no file, no declarations, still reading, too large. `view.toggleStructure` `Mod+2`. Checked in the app on Windows 11 over the control channel (tree, jump to a method, tree updated after an edit; no clicks, the control channel cannot send input). Missing: speed search, sorting and filters, visibility markers, inherited members, autoscroll from the caret, the File Structure popup, VCS colours, running tests from an entry. - [ ] Problems tool window - M3.3 (2026-10-21): a Problems tab in the bottom panel (next to Find and Terminal): the language server's diagnostics of every reported file, grouped by file (name, directory, count), errors first, then by position; each row with a Lucide severity icon in a token colour (error `--lt-error`, warning `--lt-accent`, info and hint `--lt-fg-muted`), the message, source and code, and the 1-based position; a status line with totals or the server state (starting, restarting, failed, not running). Click or Enter reveals the position (`editor.reveal`), arrows / Page / Home / End move. `problems.open` `Mod+Alt+P` (Lutra's own), menu View/Problems. In the editor: wavy underlines per severity, a gutter dot and the message with source and code on hover (CodeMirror lint, tokens only), mapped through edits until the next publication. Diagnostics come from Phpactor, not from Lutra's own inspections. Vitest; live check with the real Phpactor on Windows 11. Missing: a current-file tab or filter, severity filters, sort and group options, quick-fixes (code actions), the editor's problem counter, scrollbar marks, next/previous problem. Behaviour notes: `plan/phpstorm/11-problems.md`. +- [ ] Code completion popup, quick documentation, parameter info + - M3.4 (2026-10-22): CodeMirror's completion list with Lutra's triggers, a Lucide icon per kind (with the kind's catalog name as tooltip), the matched characters in `--lt-accent`, detail on the right, documentation beside the list; quick documentation as a tooltip on hover (350 ms) and on `editor.quickDocumentation` `Mod+I`; parameter info above the cursor with the active parameter bold in `--lt-accent`, a counter for overloads and the parameter's documentation; `editor.complete` and `editor.parameterInfo` in the palette and the Edit menu. Markdown rendered without HTML, tokens only. Checked in the app with the real Phpactor (screenshots). Missing: the documentation popup's toolbar and links, a documentation tool window, completion and tooltip settings, type info. Behaviour notes: `plan/phpstorm/12-completion.md`. - [ ] Go to file / class / symbol popup - M2.6 (2026-10-17): one popup with Files / Classes / Symbols tabs (Tab / Shift+Tab or a click; the text stays), opened by `goto.fileOpen` `Mod+P`, `goto.classOpen` `Mod+Alt+C`, `goto.symbolOpen` `Mod+T` (Lutra's own keys) or by an agent with `{query}`; live fuzzy results (60 ms debounce, stale answers dropped) with matched characters marked, a Lucide icon per kind, the directory, namespace or container beside the name, library (vendor) rows dimmed with a label; an indexing hint with progress, re-queried on `indexReady`; arrows / Page keys move, Enter or a click opens through `editor.reveal`, Escape or a click outside closes; an exclusive modal. Checked in the running app. Missing: recent files on an empty query, a non-project toggle, file-type filter, `:line` suffixes, preview, more tabs (actions, text), sending results to Find. - [ ] Find tool window @@ -42,6 +44,7 @@ | Date | Change | Summary | |---|---|---| +| 2026-10-22 | minor | Completion popup, quick documentation and parameter info partial (M3.4) | | 2026-10-21 | minor | Problems tool window partial, editor diagnostics (M3.3) | | 2026-10-19 | minor | Main menu partial (M3.9) | | 2026-10-18 | minor | Terminal tool window partial, bottom panel tabs (M3.6) | diff --git a/ui/package.json b/ui/package.json index 4102f84..d883183 100644 --- a/ui/package.json +++ b/ui/package.json @@ -16,6 +16,7 @@ "test": "vitest run" }, "dependencies": { + "@codemirror/autocomplete": "^6.20.3", "@codemirror/lang-css": "^6.3.1", "@codemirror/lang-html": "^6.4.12", "@codemirror/lang-javascript": "^6.2.5", diff --git a/ui/pnpm-lock.yaml b/ui/pnpm-lock.yaml index e247f07..86b60ca 100644 --- a/ui/pnpm-lock.yaml +++ b/ui/pnpm-lock.yaml @@ -8,6 +8,9 @@ importers: .: dependencies: + '@codemirror/autocomplete': + specifier: ^6.20.3 + version: 6.20.3 '@codemirror/lang-css': specifier: ^6.3.1 version: 6.3.1 diff --git a/ui/src/commands/uiCommands.ts b/ui/src/commands/uiCommands.ts index 32120e9..cde561a 100644 --- a/ui/src/commands/uiCommands.ts +++ b/ui/src/commands/uiCommands.ts @@ -22,6 +22,9 @@ export interface UiCommandSpec { /** The frontend's UI commands. */ export const UI_COMMANDS: readonly UiCommandSpec[] = [ { id: "editor.reveal", labelKey: "command.editor.reveal" }, + { id: "editor.complete", labelKey: "command.editor.complete", menuPath: "Edit/Complete Code" }, + { id: "editor.quickDocumentation", labelKey: "command.editor.quickDocumentation", menuPath: "Edit/Quick Documentation", defaultShortcut: "Mod+I" }, + { id: "editor.parameterInfo", labelKey: "command.editor.parameterInfo", menuPath: "Edit/Parameter Info" }, { id: "find.open", labelKey: "command.find.open", menuPath: "View/Find in Files…", defaultShortcut: "Mod+Alt+F" }, { id: "goto.classOpen", labelKey: "command.goto.classOpen", menuPath: "Go/Class…", defaultShortcut: "Mod+Alt+C" }, { id: "goto.fileOpen", labelKey: "command.goto.fileOpen", menuPath: "Go/File…", defaultShortcut: "Mod+P" }, diff --git a/ui/src/components/editor/EditorArea.vue b/ui/src/components/editor/EditorArea.vue index 078c486..fc0c142 100644 --- a/ui/src/components/editor/EditorArea.vue +++ b/ui/src/components/editor/EditorArea.vue @@ -6,7 +6,8 @@ * Save, save all and close run through the global keymap and the * palette (`commands/store.ts`): the area supplies their behaviour with the * active buffer as context and says when they can run. It also supplies the - * UI command `editor.reveal` (`reveal.ts`). + * UI commands `editor.reveal` (`reveal.ts`) and the assist commands + * (`assist/commands.ts`). */ import { onBeforeUnmount, onMounted } from "vue"; import { useCommandsStore } from "../../commands/store"; @@ -16,6 +17,7 @@ import ClosePrompt from "./ClosePrompt.vue"; import CodeEditor from "./CodeEditor.vue"; import EditorTabs from "./EditorTabs.vue"; import { reveal, REVEAL_COMMAND } from "./reveal"; +import * as assist from "./assist/commands"; const editor = useEditorStore(); const commands = useCommandsStore(); @@ -31,6 +33,9 @@ onMounted(() => { commands.provide("file.saveAll", { run: () => editor.saveAll(), enabled: () => editor.tabs.length > 0 }), commands.provide("buffer.close", { run: () => editor.requestClose(), enabled: hasActive }), commands.provide(REVEAL_COMMAND, { run: (params) => reveal(editor, params) }), + commands.provide(assist.COMPLETE_COMMAND, { run: assist.completeAtCursor, enabled: assist.assistEnabled }), + commands.provide(assist.QUICK_DOC_COMMAND, { run: assist.quickDocumentation, enabled: assist.assistEnabled }), + commands.provide(assist.PARAMETER_INFO_COMMAND, { run: assist.parameterInfo, enabled: assist.assistEnabled }), ]; }); diff --git a/ui/src/components/editor/assist/commands.ts b/ui/src/components/editor/assist/commands.ts new file mode 100644 index 0000000..3561665 --- /dev/null +++ b/ui/src/components/editor/assist/commands.ts @@ -0,0 +1,127 @@ +/** + * The assist UI commands, so the palette, the keymap, agents and the + * control channel reach completion, quick documentation and parameter + * info without typing: + * - `editor.complete` opens the completion list at the cursor (in the + * editor also `Ctrl-Space`, CodeMirror's key). + * - `editor.quickDocumentation` shows the hover documentation of the + * symbol at the cursor (`Mod+I`); `Escape` or moving on closes it. + * - `editor.parameterInfo` shows the signature help (in the editor also + * `Mod-Shift-Space`). + * + * They act on the active PHP editor, which a view plugin of the assist + * extensions records ({@link assistTracker}); without one they are + * disabled. + */ +import { startCompletion } from "@codemirror/autocomplete"; +import { StateEffect, StateField, type Extension } from "@codemirror/state"; +import { EditorView, ViewPlugin, keymap, showTooltip, type Tooltip } from "@codemirror/view"; +import { hoverAt } from "./hover"; +import { requestSignatureHelp } from "./signature"; +import type { AssistBuffer, AssistTransport } from "./types"; + +/** Command ids. */ +export const COMPLETE_COMMAND = "editor.complete"; +/** Command id of quick documentation. */ +export const QUICK_DOC_COMMAND = "editor.quickDocumentation"; +/** Command id of parameter info. */ +export const PARAMETER_INFO_COMMAND = "editor.parameterInfo"; + +/** The active PHP editor and what its assist features use. */ +interface Active { + /** The view. */ + view: EditorView; + /** Its buffer. */ + buffer: AssistBuffer; + /** How it reaches the engine. */ + transport: AssistTransport; +} + +/** The active PHP editor, if any. */ +let active: Active | null = null; + +/** Shows (a tooltip) or clears (null) the quick documentation. */ +const setQuickDoc = StateEffect.define(); + +/** The quick documentation tooltip; closed by any edit or cursor move. */ +const quickDocField = StateField.define({ + create: () => null, + update(value, tr) { + for (const effect of tr.effects) { + if (effect.is(setQuickDoc)) { + return effect.value; + } + } + return tr.docChanged || tr.selection ? null : value; + }, + provide: (field) => showTooltip.from(field), +}); + +/** + * Records the view as the active PHP editor while it shows a state with + * these extensions, and adds the quick documentation tooltip. + * + * @param buffer - the buffer the state shows. + * @param transport - how to reach the engine. + */ +export function assistTracker(buffer: AssistBuffer, transport: AssistTransport): Extension { + return [ + quickDocField, + ViewPlugin.define((view) => { + active = { view, buffer, transport }; + return { + destroy(): void { + if (active?.view === view) { + active = null; + } + }, + }; + }), + keymap.of([ + { + key: "Escape", + run: (view) => { + if (!view.state.field(quickDocField, false)) { + return false; + } + view.dispatch({ effects: setQuickDoc.of(null) }); + return true; + }, + }, + ]), + ]; +} + +/** Whether an assist command can run (a PHP editor is active). */ +export function assistEnabled(): boolean { + return active !== null; +} + +/** Opens the completion list at the cursor. */ +export function completeAtCursor(): void { + if (active) { + active.view.focus(); + startCompletion(active.view); + } +} + +/** Shows the documentation of the symbol at the cursor. */ +export async function quickDocumentation(): Promise { + const current = active; + if (!current) { + return; + } + const { view } = current; + const pos = view.state.selection.main.head; + const tooltip = await hoverAt(view, pos, current.buffer, current.transport); + if (tooltip && view.state.selection.main.head === pos) { + view.dispatch({ effects: setQuickDoc.of({ ...tooltip, pos, end: pos }) }); + } +} + +/** Shows the signature help at the cursor. */ +export function parameterInfo(): void { + if (active) { + requestSignatureHelp(active.view); + } +} diff --git a/ui/src/components/editor/assist/completion.ts b/ui/src/components/editor/assist/completion.ts new file mode 100644 index 0000000..5c8c665 --- /dev/null +++ b/ui/src/components/editor/assist/completion.ts @@ -0,0 +1,289 @@ +/** + * Code completion from the language server (`lsp.completion`) as a + * CodeMirror completion source. + * + * Trigger rules (Lutra's own, see {@link completionTrigger}): typing an + * identifier, `$`, `->`, `?->`, `::` or a namespace `\` asks the server; + * so does the explicit completion shortcut anywhere. Typing inside a + * string or comment does not, unless asked explicitly. Typing on filters + * the list locally while the server says the list is complete; an + * incomplete list is asked for again on every keystroke. + * + * Applying an item ({@link completionChanges}) uses its `textEdit` when it + * has one, else replaces the typed word with `insertText`, and applies the + * `additionalTextEdits` (such as a `use` import) in the same transaction. + * The server's positions refer to the text at the time of the request; + * text typed since then (after the request position) is accounted for. + * Positions are lines and UTF-16 columns, which CodeMirror counts the same + * way within a line, so CRLF files need no conversion here. + */ +import type { + Completion, + CompletionContext, + CompletionResult, + CompletionSource, +} from "@codemirror/autocomplete"; +import { pickedCompletion } from "@codemirror/autocomplete"; +import { syntaxTree } from "@codemirror/language"; +import type { EditorState, Text } from "@codemirror/state"; +import type { EditorView } from "@codemirror/view"; +import { positionOf } from "../engineText"; +import { renderMarkdown } from "./markdown"; +import { engineAssistTransport, queryAt } from "./request"; +import { + toCompletionList, + type AssistBuffer, + type AssistEdit, + type AssistTransport, + type CompletionItem, +} from "./types"; + +/** Where a completion starts and what triggered it. */ +export interface CompletionTrigger { + /** How many characters before the cursor the completed word starts. */ + back: number; + /** The trigger character sent to the server, if typing one triggered. */ + character?: string; +} + +/** An identifier (optionally a `$variable`) right before the cursor. */ +const WORD_BEFORE = /\$?[A-Za-z_\u0080-￿][\w\u0080-￿]*$/; + +/** What may follow while the list is filtered locally. */ +const WORD_CHARS = /^\$?[\w\u0080-￿]*$/; + +/** + * Decides whether the text before the cursor asks for completion. + * + * @param before - the line's text up to the cursor. + * @param explicit - whether the user asked (the completion shortcut). + * @returns the trigger, or null for none. + */ +export function completionTrigger(before: string, explicit: boolean): CompletionTrigger | null { + if (/(?:->|::)$/.test(before)) { + return { back: 0, character: before.slice(-1) }; + } + if (before.endsWith("$")) { + return { back: 1, character: "$" }; + } + if (before.endsWith("\\")) { + return { back: 0, character: "\\" }; + } + const word = WORD_BEFORE.exec(before); + if (word) { + const start = before.length - word[0].length; + if (!/[0-9]/.test(before.charAt(start - 1))) { + return { back: word[0].length }; + } + return explicit ? { back: 0 } : null; + } + return explicit ? { back: 0 } : null; +} + +/** + * Whether `pos` lies in a string or comment of the parsed document. + * + * @param state - the editor state. + * @param pos - the cursor. + */ +export function inStringOrComment(state: EditorState, pos: number): boolean { + for (let node: { name: string; parent: unknown } | null = syntaxTree(state).resolveInner(pos, -1); node; ) { + if (/String|Comment|Heredoc|Nowdoc/.test(node.name)) { + return true; + } + node = node.parent as { name: string; parent: unknown } | null; + } + return false; +} + +/** One change in document offsets. */ +export interface DocChange { + /** Start. */ + from: number; + /** End. */ + to: number; + /** Inserted text. */ + insert: string; +} + +/** The changes that apply an item, and where the cursor goes. */ +export interface CompletionPlan { + /** Non-overlapping changes in offsets of the current document. */ + changes: DocChange[]; + /** The end of the main replacement in the current document, before the changes. */ + mainEnd: number; +} + +/** + * The changes that apply a completion item. + * + * @param requestDoc - the document the completion was asked for. + * @param requestPos - the cursor then. + * @param item - the chosen item. + * @param from - where the completed word starts now. + * @param to - where it ends now (the cursor). + * @param length - the current document's length. + */ +export function completionChanges( + requestDoc: Text, + requestPos: number, + item: CompletionItem, + from: number, + to: number, + length: number, +): CompletionPlan { + const typed = Math.max(0, to - requestPos); + const clamp = (p: number): number => Math.max(0, Math.min(p, length)); + const offset = (edit: AssistEdit): [number, number] => { + const start = positionOf(requestDoc, edit.range.start.line, edit.range.start.column); + const end = Math.max(start, positionOf(requestDoc, edit.range.end.line, edit.range.end.column)); + return [start, end]; + }; + let main: DocChange; + let mainRange: [number, number]; + if (item.textEdit) { + const [start, end] = offset(item.textEdit); + mainRange = [start, end]; + const mainFrom = start <= requestPos ? start : start + typed; + const mainTo = end < requestPos ? end : end + typed; + main = { from: clamp(mainFrom), to: clamp(Math.max(mainFrom, mainTo)), insert: item.textEdit.newText }; + } else { + mainRange = [Math.min(from, requestPos), requestPos]; + main = { from: clamp(from), to: clamp(Math.max(from, to)), insert: item.insertText }; + } + const changes: DocChange[] = [main]; + const taken: [number, number][] = [mainRange]; + for (const edit of item.additionalTextEdits ?? []) { + const [start, end] = offset(edit); + const overlaps = taken.some(([a, b]) => start < b && end > a) || taken.some(([a, b]) => start === end && start > a && start < b); + if (overlaps) { + continue; + } + taken.push([start, end]); + const shift = (p: number): number => (p < requestPos ? p : p + typed); + changes.push({ from: clamp(shift(start)), to: clamp(shift(end)), insert: edit.newText }); + } + return { changes, mainEnd: main.to }; +} + +/** + * Applies a completion item to a view. + * + * @param view - the editor view. + * @param completion - the CodeMirror option (for `pickedCompletion`). + * @param item - the item. + * @param requestDoc - the document the completion was asked for. + * @param requestPos - the cursor then. + * @param from - start of the completed word now. + * @param to - its end now. + */ +export function applyCompletion( + view: EditorView, + completion: Completion, + item: CompletionItem, + requestDoc: Text, + requestPos: number, + from: number, + to: number, +): void { + const plan = completionChanges(requestDoc, requestPos, item, from, to, view.state.doc.length); + const changes = view.state.changes(plan.changes); + view.dispatch({ + changes, + selection: { anchor: changes.mapPos(plan.mainEnd, 1) }, + scrollIntoView: true, + userEvent: "input.complete", + annotations: pickedCompletion.of(completion), + }); +} + +/** The items behind the CodeMirror options, for icons and classes. */ +export const itemOf = new WeakMap(); + +/** + * Builds the documentation panel of an item. + * + * @param item - the item. + * @returns a node, or null without documentation. + */ +export function infoOf(item: CompletionItem): HTMLElement | null { + if (item.documentation === undefined) { + return null; + } + const dom = renderMarkdown(item.documentation); + dom.classList.add("lt-assist-info"); + return dom; +} + +/** + * Converts the server's items into CodeMirror options. The server's order + * becomes the boost, so it decides among equally good matches. + * + * @param items - the items, best first. + * @param requestDoc - the document they were asked for. + * @param requestPos - the cursor then. + */ +export function toOptions(items: readonly CompletionItem[], requestDoc: Text, requestPos: number): Completion[] { + return items.map((item, index) => { + const option: Completion = { + label: item.label, + type: item.kind, + boost: items.length > 1 ? Math.round(99 - (198 * index) / (items.length - 1)) : 0, + apply: (view, completion, from, to) => { + applyCompletion(view, completion, item, requestDoc, requestPos, from, to); + }, + }; + if (item.detail !== undefined) { + option.detail = item.detail; + } + if (item.documentation !== undefined) { + option.info = () => infoOf(item); + } + itemOf.set(option, item); + return option; + }); +} + +/** + * The completion source for one buffer. + * + * @param buffer - the buffer the editor state shows. + * @param transport - how to reach the engine. + */ +export function lspCompletionSource( + buffer: AssistBuffer, + transport: AssistTransport = engineAssistTransport, +): CompletionSource { + return async (context: CompletionContext): Promise => { + const line = context.state.doc.lineAt(context.pos); + const trigger = completionTrigger(line.text.slice(0, context.pos - line.from), context.explicit); + if (!trigger || (!context.explicit && inStringOrComment(context.state, context.pos))) { + return null; + } + const doc = context.state.doc; + const value = await queryAt({ + buffer, + transport, + doc, + current: () => context.view?.state.doc ?? doc, + pos: context.pos, + command: "lsp.completion", + extra: trigger.character === undefined ? {} : { triggerCharacter: trigger.character }, + }); + if (context.aborted || value === null) { + return null; + } + const list = toCompletionList(value); + if (list.items.length === 0) { + return null; + } + const result: CompletionResult = { + from: context.pos - trigger.back, + options: toOptions(list.items, doc, context.pos), + }; + if (!list.incomplete) { + result.validFor = WORD_CHARS; + } + return result; + }; +} diff --git a/ui/src/components/editor/assist/hover.ts b/ui/src/components/editor/assist/hover.ts new file mode 100644 index 0000000..b25f17a --- /dev/null +++ b/ui/src/components/editor/assist/hover.ts @@ -0,0 +1,69 @@ +/** + * Hover documentation from the language server (`lsp.hover`): resting the + * pointer on a symbol shows its Markdown documentation, rendered safely + * ({@link renderMarkdown}), in a tooltip above it. + */ +import type { Extension } from "@codemirror/state"; +import { hoverTooltip, type EditorView, type Tooltip } from "@codemirror/view"; +import { positionOf } from "../engineText"; +import { renderMarkdown } from "./markdown"; +import { engineAssistTransport, queryAt } from "./request"; +import { toHover, type AssistBuffer, type AssistTransport } from "./types"; + +/** Milliseconds the pointer rests before the hover is asked for. */ +export const HOVER_DELAY = 350; + +/** + * Asks for the hover at `pos` and builds its tooltip. + * + * @param view - the editor view. + * @param pos - the hovered offset. + * @param buffer - the buffer the view shows. + * @param transport - how to reach the engine. + * @returns the tooltip, or null when there is nothing to show. + */ +export async function hoverAt( + view: EditorView, + pos: number, + buffer: AssistBuffer, + transport: AssistTransport = engineAssistTransport, +): Promise { + const doc = view.state.doc; + const value = await queryAt({ + buffer, + transport, + doc, + current: () => view.state.doc, + pos, + command: "lsp.hover", + }); + const hover = toHover(value); + if (!hover) { + return null; + } + const start = hover.range ? positionOf(doc, hover.range.start.line, hover.range.start.column) : pos; + const end = hover.range ? positionOf(doc, hover.range.end.line, hover.range.end.column) : pos; + return { + pos: Math.min(start, pos), + end: Math.max(end, pos), + above: true, + create: () => { + const dom = renderMarkdown(hover.contents, view.dom.ownerDocument); + dom.classList.add("lt-assist-hover"); + return { dom }; + }, + }; +} + +/** + * The hover extension for one buffer. + * + * @param buffer - the buffer the editor state shows. + * @param transport - how to reach the engine. + */ +export function lspHover(buffer: AssistBuffer, transport: AssistTransport = engineAssistTransport): Extension { + return hoverTooltip((view, pos) => hoverAt(view, pos, buffer, transport), { + hoverTime: HOVER_DELAY, + hideOnChange: true, + }); +} diff --git a/ui/src/components/editor/assist/icons.ts b/ui/src/components/editor/assist/icons.ts new file mode 100644 index 0000000..a7e1636 --- /dev/null +++ b/ui/src/components/editor/assist/icons.ts @@ -0,0 +1,104 @@ +/** + * Lucide icons (ISC) for completion item kinds, rendered into plain DOM + * nodes for CodeMirror's completion list. The icon has the kind's catalog + * name as its tooltip; its colour is the list's text colour. + */ +import { + Box, + Braces, + Code, + Component, + File, + Folder, + Hash, + KeyRound, + Link, + ListOrdered, + Package, + Palette, + Ruler, + Scissors, + SquareDot, + SquareFunction, + Text, + Type, + Variable, + Zap, +} from "@lucide/vue"; +import { h, render, type Component as VueComponent } from "vue"; +import { t } from "../../../i18n"; +import type { CompletionKind } from "./types"; + +/** The icon of each kind. */ +export const KIND_ICONS: Readonly> = { + text: Text, + method: SquareFunction, + function: SquareFunction, + constructor: SquareFunction, + field: SquareDot, + variable: Variable, + class: Box, + interface: Component, + module: Package, + property: SquareDot, + unit: Ruler, + value: Hash, + enum: ListOrdered, + keyword: KeyRound, + snippet: Scissors, + color: Palette, + file: File, + reference: Link, + folder: Folder, + enumMember: ListOrdered, + constant: Hash, + struct: Braces, + event: Zap, + operator: Code, + typeParameter: Type, +}; + +/** The catalog name of each kind, shown as the icon's tooltip. */ +export const KIND_LABELS: Readonly string>> = { + text: () => t("editor.assist.kind.text"), + method: () => t("editor.assist.kind.method"), + function: () => t("editor.assist.kind.function"), + constructor: () => t("editor.assist.kind.constructor"), + field: () => t("editor.assist.kind.field"), + variable: () => t("editor.assist.kind.variable"), + class: () => t("editor.assist.kind.class"), + interface: () => t("editor.assist.kind.interface"), + module: () => t("editor.assist.kind.module"), + property: () => t("editor.assist.kind.property"), + unit: () => t("editor.assist.kind.unit"), + value: () => t("editor.assist.kind.value"), + enum: () => t("editor.assist.kind.enum"), + keyword: () => t("editor.assist.kind.keyword"), + snippet: () => t("editor.assist.kind.snippet"), + color: () => t("editor.assist.kind.color"), + file: () => t("editor.assist.kind.file"), + reference: () => t("editor.assist.kind.reference"), + folder: () => t("editor.assist.kind.folder"), + enumMember: () => t("editor.assist.kind.enumMember"), + constant: () => t("editor.assist.kind.constant"), + struct: () => t("editor.assist.kind.struct"), + event: () => t("editor.assist.kind.event"), + operator: () => t("editor.assist.kind.operator"), + typeParameter: () => t("editor.assist.kind.typeParameter"), +}; + +/** + * Renders the icon of a kind. + * + * @param kind - the kind; unknown kinds get the `text` icon. + * @param owner - the document that creates the node. + * @returns a `span.lt-assist-kind` with the SVG inside. + */ +export function kindIcon(kind: string, owner: Document = document): HTMLElement { + const known = Object.hasOwn(KIND_ICONS, kind) ? (kind as CompletionKind) : "text"; + const span = owner.createElement("span"); + span.className = `lt-assist-kind lt-assist-kind-${known}`; + span.title = KIND_LABELS[known](); + render(h(KIND_ICONS[known], { size: 14, "aria-hidden": "true" }), span); + return span; +} diff --git a/ui/src/components/editor/assist/index.ts b/ui/src/components/editor/assist/index.ts new file mode 100644 index 0000000..c5984ec --- /dev/null +++ b/ui/src/components/editor/assist/index.ts @@ -0,0 +1,153 @@ +/** + * Code assistance in the editor (M3.4): completion, hover documentation + * and signature help from the PHP language server, through the engine's + * `lsp.completion`, `lsp.hover` and `lsp.signatureHelp` (pending + * queries, see `request.ts`). + * + * {@link assistExtensions} is the hook the editor uses: PHP files of a + * buffer get the extensions, everything else none. Colours come from + * `--lt-*` tokens only; strings from the catalog. + */ +import { autocompletion } from "@codemirror/autocomplete"; +import type { Extension } from "@codemirror/state"; +import { EditorView } from "@codemirror/view"; +import { languageOf } from "../language"; +import { assistTracker } from "./commands"; +import { itemOf, lspCompletionSource } from "./completion"; +import { lspHover } from "./hover"; +import { kindIcon } from "./icons"; +import { engineAssistTransport } from "./request"; +import { lspSignatureHelp } from "./signature"; +import type { AssistBuffer, AssistTransport } from "./types"; + +export type { AssistBuffer } from "./types"; + +/** Markdown and tooltip styles from tokens. */ +const assistTheme: Extension = EditorView.theme({ + ".cm-tooltip.cm-tooltip-autocomplete > ul": { + fontFamily: "var(--lt-font-mono)", + maxHeight: "16em", + }, + ".cm-tooltip.cm-tooltip-autocomplete > ul > li": { + display: "flex", + alignItems: "center", + gap: "6px", + padding: "1px 8px 1px 4px", + }, + ".cm-tooltip-autocomplete ul li[aria-selected]": { + backgroundColor: "var(--lt-editor-selection-bg)", + color: "var(--lt-fg)", + }, + ".cm-completionMatchedText": { + textDecoration: "none", + fontWeight: "600", + color: "var(--lt-accent)", + }, + ".cm-completionDetail": { + marginLeft: "auto", + paddingLeft: "16px", + fontStyle: "normal", + color: "var(--lt-fg-muted)", + }, + ".lt-assist-kind": { + display: "inline-flex", + flex: "none", + color: "var(--lt-fg-muted)", + }, + ".lt-assist-deprecated .cm-completionLabel": { + textDecoration: "line-through", + }, + ".cm-tooltip.cm-completionInfo": { + maxWidth: "480px", + padding: "4px 8px", + }, + ".cm-tooltip-hover": { + maxWidth: "640px", + }, + ".lt-markdown": { + padding: "4px 8px", + maxHeight: "320px", + overflow: "auto", + lineHeight: "1.45", + color: "var(--lt-fg)", + }, + ".lt-markdown p, .lt-markdown ul, .lt-markdown ol, .lt-markdown blockquote": { + margin: "4px 0", + }, + ".lt-markdown ul, .lt-markdown ol": { + paddingLeft: "20px", + }, + ".lt-markdown pre": { + margin: "4px 0", + padding: "4px 6px", + whiteSpace: "pre-wrap", + backgroundColor: "var(--lt-editor-bg)", + border: "1px solid var(--lt-border)", + fontFamily: "var(--lt-font-mono)", + }, + ".lt-markdown code": { + fontFamily: "var(--lt-font-mono)", + }, + ".lt-markdown hr": { + border: "none", + borderTop: "1px solid var(--lt-border)", + margin: "6px 0", + }, + ".lt-markdown blockquote": { + paddingLeft: "8px", + borderLeft: "3px solid var(--lt-border)", + color: "var(--lt-fg-muted)", + }, + ".lt-markdown-link": { + color: "var(--lt-accent)", + }, + ".lt-assist-signature": { + maxWidth: "640px", + padding: "2px 0", + }, + ".lt-assist-signature-label": { + padding: "2px 8px", + fontFamily: "var(--lt-font-mono)", + }, + ".lt-assist-signature-active": { + fontWeight: "700", + color: "var(--lt-accent)", + }, + ".lt-assist-signature-count": { + marginRight: "8px", + color: "var(--lt-fg-muted)", + }, + ".lt-assist-signature-doc": { + borderTop: "1px solid var(--lt-border)", + }, +}); + +/** + * The assist extensions of an editor state. + * + * @param path - project-relative path of the file. + * @param buffer - the buffer it shows; none for states without one. + * @param transport - how to reach the engine. + * @returns the extensions; empty unless a PHP file of a buffer. + */ +export function assistExtensions( + path: string, + buffer: AssistBuffer | undefined, + transport: AssistTransport = engineAssistTransport, +): Extension { + if (!buffer || languageOf(path) !== "php") { + return []; + } + return [ + autocompletion({ + override: [lspCompletionSource(buffer, transport)], + icons: false, + addToOptions: [{ render: (completion) => kindIcon(completion.type ?? "text"), position: 20 }], + optionClass: (completion) => (itemOf.get(completion)?.deprecated === true ? "lt-assist-deprecated" : ""), + }), + lspHover(buffer, transport), + lspSignatureHelp(buffer, transport), + assistTracker(buffer, transport), + assistTheme, + ]; +} diff --git a/ui/src/components/editor/assist/markdown.ts b/ui/src/components/editor/assist/markdown.ts new file mode 100644 index 0000000..701055b --- /dev/null +++ b/ui/src/components/editor/assist/markdown.ts @@ -0,0 +1,292 @@ +/** + * A small, safe Markdown renderer for language server documentation + * (hover, completion details, signature help). + * + * Safety: the renderer never parses HTML. It builds DOM nodes with + * `createElement` and `textContent` only, from a fixed set of elements + * (`p`, `pre`, `code`, `strong`, `em`, `ul`, `ol`, `li`, `hr`, + * `blockquote`, `span`). HTML in the source shows as text; links and + * images show their text only (no `href`, no `src`), so nothing in a + * server answer can run script, load a resource or navigate the window. + * + * Supported: fenced code blocks (``` and ~~~), ATX headings (shown as + * bold paragraphs), thematic breaks, bullet and numbered lists (flat), + * block quotes, paragraphs with hard breaks, and inline code, strong, + * emphasis, links, images and backslash escapes. That covers what + * Phpactor writes. Styling comes from `--lt-*` tokens in the assist theme. + */ + +/** Longest source rendered; the rest is cut. */ +export const MAX_MARKDOWN = 64 * 1024; + +/** Deepest nesting of inline emphasis followed. */ +const MAX_DEPTH = 8; + +/** ASCII punctuation a backslash can escape (CommonMark). */ +const ESCAPABLE = "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"; + +/** A thematic break line. */ +const RULE = /^ {0,3}([-*_])(?: *\1){2,} *$/; + +/** An ATX heading line. */ +const HEADING = /^ {0,3}(#{1,6})(?:\s+(.*?))?\s*#*\s*$/; + +/** The opening line of a fenced code block. */ +const FENCE = /^ {0,3}(`{3,}|~{3,})\s*([^`\s]*)/; + +/** A list item line. */ +const LIST_ITEM = /^\s{0,3}([-*+]|\d{1,9}[.)])\s+(.*)$/; + +/** A block quote line. */ +const QUOTE = /^ {0,3}> ?(.*)$/; + +/** + * Renders Markdown into a detached element. + * + * @param source - the Markdown text (untrusted). + * @param owner - the document that creates the nodes. + * @returns a `div.lt-markdown` with the rendered blocks. + */ +export function renderMarkdown(source: string, owner: Document = document): HTMLElement { + const root = owner.createElement("div"); + root.className = "lt-markdown"; + const lines = source.slice(0, MAX_MARKDOWN).split(/\r\n|\r|\n/); + let paragraph: string[] = []; + let list: HTMLElement | null = null; + const flushParagraph = (): void => { + if (paragraph.length > 0) { + const p = owner.createElement("p"); + appendLines(p, paragraph, owner); + root.append(p); + paragraph = []; + } + }; + const endBlocks = (): void => { + flushParagraph(); + list = null; + }; + for (let i = 0; i < lines.length; i += 1) { + const line = lines[i] ?? ""; + const fence = FENCE.exec(line); + if (fence) { + endBlocks(); + const marker = fence[1] ?? "```"; + const code: string[] = []; + i += 1; + while (i < lines.length && !(lines[i] ?? "").trimStart().startsWith(marker)) { + code.push(lines[i] ?? ""); + i += 1; + } + const pre = owner.createElement("pre"); + const element = owner.createElement("code"); + const language = fence[2] ?? ""; + if (/^[\w+-]{1,32}$/.test(language)) { + element.dataset.language = language; + } + element.textContent = code.join("\n"); + pre.append(element); + root.append(pre); + continue; + } + if (line.trim() === "") { + endBlocks(); + continue; + } + if (RULE.test(line)) { + endBlocks(); + root.append(owner.createElement("hr")); + continue; + } + const heading = HEADING.exec(line); + if (heading) { + endBlocks(); + const p = owner.createElement("p"); + p.className = "lt-markdown-heading"; + const strong = owner.createElement("strong"); + appendInline(strong, heading[2] ?? "", owner, 0); + p.append(strong); + root.append(p); + continue; + } + const item = LIST_ITEM.exec(line); + if (item) { + flushParagraph(); + const ordered = /\d/.test(item[1] ?? ""); + const tag = ordered ? "OL" : "UL"; + if (!list || list.tagName !== tag) { + list = owner.createElement(ordered ? "ol" : "ul"); + root.append(list); + } + const li = owner.createElement("li"); + appendInline(li, item[2] ?? "", owner, 0); + list.append(li); + continue; + } + const quote = QUOTE.exec(line); + if (quote) { + endBlocks(); + const block = owner.createElement("blockquote"); + appendInline(block, quote[1] ?? "", owner, 0); + root.append(block); + continue; + } + if (list && /^\s{2,}\S/.test(line) && list.lastElementChild) { + list.lastElementChild.append(owner.createTextNode(" ")); + appendInline(list.lastElementChild as HTMLElement, line.trim(), owner, 0); + continue; + } + list = null; + paragraph.push(line); + } + flushParagraph(); + return root; +} + +/** + * Appends the lines of one paragraph: joined with spaces, with a line + * break where a line ends in two spaces or a backslash. + */ +function appendLines(parent: HTMLElement, lines: readonly string[], owner: Document): void { + lines.forEach((raw, index) => { + const hard = / {2,}$/.test(raw) || (raw.endsWith("\\") && !raw.endsWith("\\\\")); + const text = hard ? raw.replace(/ +$/, "").replace(/\\$/, "") : raw; + appendInline(parent, index === 0 ? text.trimStart() : text.trim(), owner, 0); + if (index < lines.length - 1) { + parent.append(hard ? owner.createElement("br") : owner.createTextNode(" ")); + } + }); +} + +/** + * Appends inline Markdown as nodes. + * + * @param parent - the element that receives the nodes. + * @param text - one block's inline source. + * @param owner - the document that creates the nodes. + * @param depth - the current emphasis nesting. + */ +function appendInline(parent: HTMLElement, text: string, owner: Document, depth: number): void { + let plain = ""; + const flush = (): void => { + if (plain !== "") { + parent.append(owner.createTextNode(plain)); + plain = ""; + } + }; + let i = 0; + while (i < text.length) { + const c = text.charAt(i); + const next = text.charAt(i + 1); + if (c === "\\" && next !== "" && ESCAPABLE.includes(next)) { + plain += next; + i += 2; + continue; + } + if (c === "`") { + const run = /^`+/.exec(text.slice(i))?.[0] ?? "`"; + const close = text.indexOf(run, i + run.length); + if (close > 0) { + flush(); + const code = owner.createElement("code"); + code.textContent = text.slice(i + run.length, close).replace(/^ (.*) $/, "$1"); + parent.append(code); + i = close + run.length; + continue; + } + plain += run; + i += run.length; + continue; + } + if ((c === "*" || c === "_") && depth < MAX_DEPTH) { + const before = text.charAt(i - 1); + const opens = c === "*" || !/[\p{L}\p{N}]/u.test(before); + const strong = next === c; + const marker = strong ? c + c : c; + const close = opens ? findClose(text, marker, i + marker.length) : -1; + if (close > i + marker.length) { + flush(); + const element = owner.createElement(strong ? "strong" : "em"); + appendInline(element, text.slice(i + marker.length, close), owner, depth + 1); + parent.append(element); + i = close + marker.length; + continue; + } + plain += marker; + i += marker.length; + continue; + } + if (c === "[" || (c === "!" && next === "[")) { + const start = c === "!" ? i + 1 : i; + const link = matchLink(text, start); + if (link && depth < MAX_DEPTH) { + flush(); + const span = owner.createElement("span"); + span.className = "lt-markdown-link"; + appendInline(span, link.label, owner, depth + 1); + parent.append(span); + i = link.end; + continue; + } + } + if (c === "<") { + const auto = /^<((?:https?|mailto):[^\s<>]*)>/i.exec(text.slice(i)); + if (auto) { + plain += auto[1] ?? ""; + i += auto[0].length; + continue; + } + } + plain += c; + i += 1; + } + flush(); +} + +/** + * Finds the closing emphasis marker: the next `marker` after `from` that + * is not escaped and not preceded by whitespace. + * + * @returns its index, or -1. + */ +function findClose(text: string, marker: string, from: number): number { + let at = text.indexOf(marker, from); + while (at >= 0) { + const before = text.charAt(at - 1); + const doubled = marker.length === 1 && text.charAt(at + 1) === marker; + if (before !== "\\" && !/\s/.test(before) && !doubled) { + return at; + } + at = text.indexOf(marker, at + (doubled ? 2 : 1)); + } + return -1; +} + +/** + * Matches `[label](target)` at `start`. + * + * @returns the label and the index after the link, or null. + */ +function matchLink(text: string, start: number): { label: string; end: number } | null { + let depth = 0; + for (let i = start; i < text.length; i += 1) { + const c = text.charAt(i); + if (c === "\\") { + i += 1; + } else if (c === "[") { + depth += 1; + } else if (c === "]") { + depth -= 1; + if (depth === 0) { + if (text.charAt(i + 1) !== "(") { + return null; + } + const close = text.indexOf(")", i + 2); + if (close < 0) { + return null; + } + return { label: text.slice(start + 1, i), end: close + 1 }; + } + } + } + return null; +} diff --git a/ui/src/components/editor/assist/request.ts b/ui/src/components/editor/assist/request.ts new file mode 100644 index 0000000..f244d31 --- /dev/null +++ b/ui/src/components/editor/assist/request.ts @@ -0,0 +1,73 @@ +/** + * Sending an assist query for a position of an editor state. + * + * Positions must refer to the text the engine has. The local document can + * be ahead of it while the buffer sync has edits in flight, so a query + * first waits until the sync is idle and then checks that the document is + * still the one the position belongs to; if the user typed meanwhile, the + * query is dropped (the editor asks again for the new text). + */ +import type { Text } from "@codemirror/state"; +import { runWaiting, type JsonValue } from "../../../ipc"; +import type { AssistBuffer, AssistPosition, AssistTransport } from "./types"; + +/** + * The transport through the engine IPC: `runWaiting` waits for the + * language server on a worker thread of the shell and without the engine + * lock, so a slow server never blocks the window or the engine. + */ +export const engineAssistTransport: AssistTransport = { + query: (command, params) => runWaiting(command, params), +}; + +/** + * The engine position of a document offset: 0-based line and UTF-16 + * column, which is what CodeMirror counts within a line. CRLF files have + * the same lines and columns in the engine. + * + * @param doc - the document. + * @param pos - an offset in it. + */ +export function positionAt(doc: Text, pos: number): AssistPosition { + const line = doc.lineAt(Math.max(0, Math.min(pos, doc.length))); + return { line: line.number - 1, column: Math.max(0, Math.min(pos, doc.length)) - line.from }; +} + +/** What one query needs. */ +export interface QueryRequest { + /** The buffer. */ + buffer: AssistBuffer; + /** How to reach the engine. */ + transport: AssistTransport; + /** The document the position refers to. */ + doc: Text; + /** The current document, read after the sync is idle. */ + current: () => Text; + /** The offset. */ + pos: number; + /** The command id. */ + command: string; + /** More params next to `id` and `position`. */ + extra?: Record; +} + +/** + * Runs an assist query once the engine has the document. + * + * @returns the untrusted result, or null when the document moved on, the + * query failed (no language server, a timeout) or nothing was found. + * Failures are not shown: assistance is best effort while typing. + */ +export async function queryAt(request: QueryRequest): Promise { + await request.buffer.idle(); + if (request.current() !== request.doc) { + return null; + } + const position = positionAt(request.doc, request.pos); + const result = await request.transport.query(request.command, { + id: request.buffer.id, + position: { line: position.line, column: position.column }, + ...request.extra, + }); + return result.ok ? result.value : null; +} diff --git a/ui/src/components/editor/assist/signature.ts b/ui/src/components/editor/assist/signature.ts new file mode 100644 index 0000000..4b7198e --- /dev/null +++ b/ui/src/components/editor/assist/signature.ts @@ -0,0 +1,270 @@ +/** + * Signature help (`lsp.signatureHelp`) while typing call arguments. + * + * Typing `(` or `,` asks the server for the signatures of the call around + * the cursor; while the tooltip is open, every edit and cursor move asks + * again (debounced), so the highlighted parameter follows the cursor and + * the tooltip closes when the cursor leaves the call (the server returns + * no signatures). `Escape` closes it, `Mod-Shift-Space` opens it on + * demand. The tooltip shows the active signature with its active + * parameter highlighted, a counter when there are several, and the + * parameter's and the signature's documentation as safe Markdown. + */ +import { StateEffect, StateField, type Extension } from "@codemirror/state"; +import { + EditorView, + ViewPlugin, + keymap, + showTooltip, + type PluginValue, + type Tooltip, + type ViewUpdate, +} from "@codemirror/view"; +import { t } from "../../../i18n"; +import { renderMarkdown } from "./markdown"; +import { engineAssistTransport, queryAt } from "./request"; +import { toSignatureHelp, type AssistBuffer, type AssistTransport, type SignatureHelpResult } from "./types"; + +/** Milliseconds between a cursor move or edit and the follow-up request. */ +export const SIGNATURE_DEBOUNCE = 120; + +/** What the tooltip shows, anchored at `pos`. */ +export interface SignatureState { + /** Where the tooltip is anchored (the cursor when it was asked for). */ + pos: number; + /** The signatures. */ + help: SignatureHelpResult; +} + +/** Sets or clears (null) the shown signature help. */ +export const setSignature = StateEffect.define(); + +/** The shown signature help, mapped through edits. */ +export const signatureField = StateField.define({ + create: () => null, + update(value, tr) { + for (const effect of tr.effects) { + if (effect.is(setSignature)) { + return effect.value; + } + } + if (value && tr.docChanged) { + return { pos: tr.changes.mapPos(value.pos), help: value.help }; + } + return value; + }, + provide: (field) => + showTooltip.from(field, (value): Tooltip | null => + value + ? { + pos: value.pos, + above: true, + create: (view) => ({ dom: renderSignature(value.help, view.dom.ownerDocument) }), + } + : null, + ), +}); + +/** + * Renders signature help. + * + * @param help - the signatures. + * @param owner - the document that creates the nodes. + * @returns a `div.lt-assist-signature`. + */ +export function renderSignature(help: SignatureHelpResult, owner: Document = document): HTMLElement { + const root = owner.createElement("div"); + root.className = "lt-assist-signature"; + const signature = help.signatures[help.activeSignature] ?? help.signatures[0]; + if (!signature) { + return root; + } + const head = owner.createElement("div"); + head.className = "lt-assist-signature-label"; + const active = signature.activeParameter ?? help.activeParameter; + const span = signature.parameters[active]?.label ?? null; + if (span) { + const [from, to] = span; + const mark = owner.createElement("span"); + mark.className = "lt-assist-signature-active"; + mark.textContent = signature.label.slice(from, to); + head.append(owner.createTextNode(signature.label.slice(0, from)), mark, owner.createTextNode(signature.label.slice(to))); + } else { + head.textContent = signature.label; + } + if (help.signatures.length > 1) { + const counter = owner.createElement("span"); + counter.className = "lt-assist-signature-count"; + counter.textContent = t("editor.assist.signature.count", { + index: help.activeSignature + 1, + count: help.signatures.length, + }); + head.prepend(counter); + } + root.append(head); + const parameterDoc = signature.parameters[active]?.documentation; + for (const doc of [parameterDoc, signature.documentation]) { + if (doc !== undefined) { + const dom = renderMarkdown(doc, owner); + dom.classList.add("lt-assist-signature-doc"); + root.append(dom); + } + } + return root; +} + +/** + * Whether an update typed a character that opens or continues an + * argument list. + * + * @param update - the view update. + */ +export function typedArgumentStart(update: ViewUpdate): boolean { + let typed = false; + for (const tr of update.transactions) { + if (!tr.isUserEvent("input")) { + continue; + } + tr.changes.iterChanges((_fromA, _toA, _fromB, _toB, inserted) => { + if (/[(,]$/.test(inserted.toString())) { + typed = true; + } + }); + } + return typed; +} + +/** The plugin that asks for signature help; see the module docs. */ +class SignaturePlugin implements PluginValue { + /** The pending debounce timer. */ + private timer: ReturnType | null = null; + /** Number of the newest request; older answers are dropped. */ + private sequence = 0; + /** Set once the view is gone. */ + private destroyed = false; + + /** + * @param view - the editor view. + * @param buffer - the buffer it shows. + * @param transport - how to reach the engine. + */ + constructor( + private readonly view: EditorView, + private readonly buffer: AssistBuffer, + private readonly transport: AssistTransport, + ) {} + + /** Asks again after relevant typing or, while open, any edit or move. */ + update(update: ViewUpdate): void { + const open = update.state.field(signatureField, false) ?? null; + if (typedArgumentStart(update)) { + this.schedule(0); + } else if (open && (update.docChanged || update.selectionSet)) { + this.schedule(SIGNATURE_DEBOUNCE); + } + } + + /** + * Asks for signature help after `delay` milliseconds. + * + * @param delay - the debounce. + */ + schedule(delay: number): void { + if (this.timer !== null) { + clearTimeout(this.timer); + } + this.timer = setTimeout(() => { + this.timer = null; + void this.ask(); + }, delay); + } + + /** Sends the request and shows or clears the answer. */ + private async ask(): Promise { + this.sequence += 1; + const sequence = this.sequence; + const view = this.view; + const pos = view.state.selection.main.head; + const value = await queryAt({ + buffer: this.buffer, + transport: this.transport, + doc: view.state.doc, + current: () => view.state.doc, + pos, + command: "lsp.signatureHelp", + }); + if (this.destroyed || sequence !== this.sequence || view.state.selection.main.head !== pos) { + return; + } + const help = toSignatureHelp(value); + const shown = view.state.field(signatureField, false) ?? null; + if (!help && !shown) { + return; + } + view.dispatch({ effects: setSignature.of(help ? { pos, help } : null) }); + } + + /** Stops pending work. */ + destroy(): void { + this.destroyed = true; + this.sequence += 1; + if (this.timer !== null) { + clearTimeout(this.timer); + } + } +} + +/** The plugins of every signature help extension built so far. */ +const plugins = new Set>(); + +/** + * Asks for signature help at the cursor of `view` now. + * + * @param view - an editor view with the signature help extension. + */ +export function requestSignatureHelp(view: EditorView): void { + for (const plugin of plugins) { + const instance = view.plugin(plugin); + if (instance) { + instance.schedule(0); + return; + } + } +} + +/** + * The signature help extension for one buffer. + * + * @param buffer - the buffer the editor state shows. + * @param transport - how to reach the engine. + */ +export function lspSignatureHelp( + buffer: AssistBuffer, + transport: AssistTransport = engineAssistTransport, +): Extension { + const plugin = ViewPlugin.define((view) => new SignaturePlugin(view, buffer, transport)); + plugins.add(plugin); + return [ + signatureField, + plugin, + keymap.of([ + { + key: "Mod-Shift-Space", + run: (view) => { + view.plugin(plugin)?.schedule(0); + return true; + }, + }, + { + key: "Escape", + run: (view) => { + if (!view.state.field(signatureField, false)) { + return false; + } + view.dispatch({ effects: setSignature.of(null) }); + return true; + }, + }, + ]), + ]; +} diff --git a/ui/src/components/editor/assist/types.ts b/ui/src/components/editor/assist/types.ts new file mode 100644 index 0000000..e2ad078 --- /dev/null +++ b/ui/src/components/editor/assist/types.ts @@ -0,0 +1,319 @@ +/** + * Shapes of the engine's assist results (`lsp.completion`, `lsp.hover`, + * `lsp.signatureHelp`) and checks that turn the untrusted command results + * into them. Anything malformed is dropped, never thrown. + */ +import type { JsonValue, RunResult } from "../../../ipc"; + +/** A 0-based position; the column counts UTF-16 code units. */ +export interface AssistPosition { + /** Line. */ + line: number; + /** Column. */ + column: number; +} + +/** A range between two positions, end exclusive. */ +export interface AssistRange { + /** Start. */ + start: AssistPosition; + /** End. */ + end: AssistPosition; +} + +/** A text edit of a completion item. */ +export interface AssistEdit { + /** What it replaces, in the text the completion was asked for. */ + range: AssistRange; + /** The replacement. */ + newText: string; +} + +/** The completion item kinds the engine names. */ +export const COMPLETION_KINDS = [ + "text", + "method", + "function", + "constructor", + "field", + "variable", + "class", + "interface", + "module", + "property", + "unit", + "value", + "enum", + "keyword", + "snippet", + "color", + "file", + "reference", + "folder", + "enumMember", + "constant", + "struct", + "event", + "operator", + "typeParameter", +] as const; + +/** A completion item kind. */ +export type CompletionKind = (typeof COMPLETION_KINDS)[number]; + +/** One completion item, as `lsp.completion` returns it. */ +export interface CompletionItem { + /** Shown and matched against the typed text. */ + label: string; + /** What it is. */ + kind: CompletionKind; + /** A one-line description (signature, type). */ + detail?: string; + /** Markdown documentation. */ + documentation?: string; + /** Inserted text when there is no {@link textEdit}. */ + insertText: string; + /** The edit to apply instead of inserting {@link insertText}. */ + textEdit?: AssistEdit; + /** More edits elsewhere, such as a `use` import. */ + additionalTextEdits?: AssistEdit[]; + /** Whether the symbol is deprecated. */ + deprecated?: boolean; +} + +/** The result of `lsp.completion`. */ +export interface CompletionList { + /** The items, best first. */ + items: CompletionItem[]; + /** Whether typing more should ask the server again. */ + incomplete: boolean; +} + +/** The result of `lsp.hover`. */ +export interface HoverResult { + /** Markdown; empty when there is nothing to show. */ + contents: string; + /** The range the hover applies to. */ + range?: AssistRange; +} + +/** One parameter of a signature. */ +export interface SignatureParameter { + /** UTF-16 offsets of the parameter inside the signature label. */ + label: [number, number] | null; + /** Markdown documentation. */ + documentation?: string; +} + +/** One signature of `lsp.signatureHelp`. */ +export interface Signature { + /** The whole signature. */ + label: string; + /** Markdown documentation. */ + documentation?: string; + /** Its parameters. */ + parameters: SignatureParameter[]; + /** The active parameter, overriding the result's. */ + activeParameter?: number; +} + +/** The result of `lsp.signatureHelp`. */ +export interface SignatureHelpResult { + /** The signatures; empty outside a call. */ + signatures: Signature[]; + /** The signature to show. */ + activeSignature: number; + /** The parameter to highlight. */ + activeParameter: number; +} + +/** How the assist features reach the engine; replaced by a fake in tests. */ +export interface AssistTransport { + /** + * Runs an engine command that waits for the language server + * (`runWaiting` in `ipc.ts`). + * + * @param command - the command id. + * @param params - its params. + */ + query(command: string, params: JsonValue): Promise>; +} + +/** The buffer an editor state shows, as the assist features need it. */ +export interface AssistBuffer { + /** Engine buffer id. */ + id: number; + /** Resolves once every local edit has reached the engine. */ + idle(): Promise; +} + +/** Whether a value is a plain object. */ +function isObject(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +/** A non-negative integer, or null. */ +function count(value: unknown): number | null { + return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null; +} + +/** A string, or undefined. */ +function text(value: unknown): string | undefined { + return typeof value === "string" ? value : undefined; +} + +/** Reads a position. */ +function toPosition(value: unknown): AssistPosition | null { + if (!isObject(value)) { + return null; + } + const line = count(value.line); + const column = count(value.column); + return line === null || column === null ? null : { line, column }; +} + +/** Reads a range. */ +export function toRange(value: unknown): AssistRange | null { + if (!isObject(value)) { + return null; + } + const start = toPosition(value.start); + const end = toPosition(value.end); + return start && end ? { start, end } : null; +} + +/** Reads a text edit. */ +function toEdit(value: unknown): AssistEdit | null { + if (!isObject(value)) { + return null; + } + const range = toRange(value.range); + const newText = text(value.newText); + return range && newText !== undefined ? { range, newText } : null; +} + +/** Reads one completion item. */ +function toItem(value: unknown): CompletionItem | null { + if (!isObject(value)) { + return null; + } + const label = text(value.label); + if (label === undefined || label === "") { + return null; + } + const kind = COMPLETION_KINDS.find((k) => k === value.kind) ?? "text"; + const item: CompletionItem = { label, kind, insertText: text(value.insertText) ?? label }; + const detail = text(value.detail); + if (detail !== undefined && detail !== "") { + item.detail = detail; + } + const documentation = text(value.documentation); + if (documentation !== undefined && documentation !== "") { + item.documentation = documentation; + } + const edit = toEdit(value.textEdit); + if (edit) { + item.textEdit = edit; + } + if (Array.isArray(value.additionalTextEdits)) { + const extra = value.additionalTextEdits.map(toEdit).filter((e): e is AssistEdit => e !== null); + if (extra.length > 0) { + item.additionalTextEdits = extra; + } + } + if (value.deprecated === true) { + item.deprecated = true; + } + return item; +} + +/** + * Reads an `lsp.completion` result. + * + * @param value - the untrusted result. + * @returns the list; empty when malformed. + */ +export function toCompletionList(value: unknown): CompletionList { + if (!isObject(value) || !Array.isArray(value.items)) { + return { items: [], incomplete: false }; + } + return { + items: value.items.map(toItem).filter((i): i is CompletionItem => i !== null), + incomplete: value.incomplete === true, + }; +} + +/** + * Reads an `lsp.hover` result. + * + * @param value - the untrusted result. + * @returns the hover, or null when there is nothing to show. + */ +export function toHover(value: unknown): HoverResult | null { + if (!isObject(value)) { + return null; + } + const contents = text(value.contents); + if (contents === undefined || contents.trim() === "") { + return null; + } + const range = toRange(value.range); + return range ? { contents, range } : { contents }; +} + +/** Reads one signature. */ +function toSignature(value: unknown): Signature | null { + if (!isObject(value)) { + return null; + } + const label = text(value.label); + if (label === undefined) { + return null; + } + const parameters: SignatureParameter[] = Array.isArray(value.parameters) + ? value.parameters.map((p): SignatureParameter => { + const span = isObject(p) && Array.isArray(p.label) ? p.label : null; + const from = span ? count(span[0]) : null; + const to = span ? count(span[1]) : null; + const parameter: SignatureParameter = { + label: from !== null && to !== null && from <= to && to <= label.length ? [from, to] : null, + }; + const documentation = isObject(p) ? text(p.documentation) : undefined; + if (documentation !== undefined && documentation !== "") { + parameter.documentation = documentation; + } + return parameter; + }) + : []; + const signature: Signature = { label, parameters }; + const documentation = text(value.documentation); + if (documentation !== undefined && documentation !== "") { + signature.documentation = documentation; + } + const active = count(value.activeParameter); + if (active !== null) { + signature.activeParameter = active; + } + return signature; +} + +/** + * Reads an `lsp.signatureHelp` result. + * + * @param value - the untrusted result. + * @returns the signatures, or null when there are none. + */ +export function toSignatureHelp(value: unknown): SignatureHelpResult | null { + if (!isObject(value) || !Array.isArray(value.signatures)) { + return null; + } + const signatures = value.signatures.map(toSignature).filter((s): s is Signature => s !== null); + if (signatures.length === 0) { + return null; + } + return { + signatures, + activeSignature: Math.min(count(value.activeSignature) ?? 0, signatures.length - 1), + activeParameter: count(value.activeParameter) ?? 0, + }; +} diff --git a/ui/src/components/editor/extensions.ts b/ui/src/components/editor/extensions.ts index 344ac61..8093e4c 100644 --- a/ui/src/components/editor/extensions.ts +++ b/ui/src/components/editor/extensions.ts @@ -12,6 +12,7 @@ import type { Extension } from "@codemirror/state"; import { basicSetup } from "codemirror"; import { languageExtensions, type SYNTAX_CLASS, type SyntaxToken } from "./language"; import { lintExtensions } from "./lint"; +import { assistExtensions, type AssistBuffer } from "./assist"; /** * Colours of the highlight classes (`language.ts`), one `--lt-syntax-*` @@ -109,7 +110,15 @@ export const lutraEditorTheme: Extension = EditorView.theme({ * * @param path - the file's path, which picks the language; plain text when * omitted or unknown. + * @param buffer - the engine buffer the state shows; PHP files of a buffer + * get completion, hover and signature help (`./assist`). */ -export function editorExtensions(path = ""): Extension { - return [basicSetup, lutraEditorTheme, languageExtensions(path), lintExtensions(path)]; +export function editorExtensions(path = "", buffer?: AssistBuffer): Extension { + return [ + basicSetup, + lutraEditorTheme, + languageExtensions(path), + lintExtensions(path), + assistExtensions(path, buffer), + ]; } diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json index d997ce5..17b8728 100644 --- a/ui/src/i18n/en.json +++ b/ui/src/i18n/en.json @@ -1,5 +1,8 @@ { "app.statusBar.version": "{name} {version}", + "command.editor.complete": "Complete Code", + "command.editor.parameterInfo": "Parameter Info", + "command.editor.quickDocumentation": "Quick Documentation", "command.editor.reveal": "Reveal Cursor in Editor", "command.find.open": "Find in Files…", "command.goto.classOpen": "Go to Class…", @@ -31,6 +34,32 @@ "common.toolWindow.resize": "Resize {title}", "common.toolWindow.show": "Show {title}", "common.toolWindow.stripe": "Tool windows", + "editor.assist.kind.class": "Class", + "editor.assist.kind.color": "Colour", + "editor.assist.kind.constant": "Constant", + "editor.assist.kind.constructor": "Constructor", + "editor.assist.kind.enum": "Enum", + "editor.assist.kind.enumMember": "Enum case", + "editor.assist.kind.event": "Event", + "editor.assist.kind.field": "Field", + "editor.assist.kind.file": "File", + "editor.assist.kind.folder": "Folder", + "editor.assist.kind.function": "Function", + "editor.assist.kind.interface": "Interface", + "editor.assist.kind.keyword": "Keyword", + "editor.assist.kind.method": "Method", + "editor.assist.kind.module": "Namespace", + "editor.assist.kind.operator": "Operator", + "editor.assist.kind.property": "Property", + "editor.assist.kind.reference": "Reference", + "editor.assist.kind.snippet": "Snippet", + "editor.assist.kind.struct": "Structure", + "editor.assist.kind.text": "Text", + "editor.assist.kind.typeParameter": "Type parameter", + "editor.assist.kind.unit": "Unit", + "editor.assist.kind.value": "Value", + "editor.assist.kind.variable": "Variable", + "editor.assist.signature.count": "{index} of {count}", "editor.closePrompt.question": "Save changes to {name} before closing?", "editor.notice.changedOnDisk": "{name} changed on disk. Your unsaved changes are kept; saving overwrites the file.", "editor.notice.removedOnDisk": "{name} was deleted on disk. Your text is kept; saving writes it again.", diff --git a/ui/src/stores/editor.ts b/ui/src/stores/editor.ts index 67b7b6b..a37d3af 100644 --- a/ui/src/stores/editor.ts +++ b/ui/src/stores/editor.ts @@ -16,6 +16,7 @@ import { run, type EngineError, type RunResult } from "../ipc"; import { BufferSync, isBufferInfo, engineTransport, type BufferInfo, type SyncTransport } from "../components/editor/bufferSync"; import { onEditorEvent, type EditorEvent } from "../components/editor/engineEvents"; import { editorExtensions } from "../components/editor/extensions"; +import type { AssistBuffer } from "../components/editor/assist"; import type { Extension } from "@codemirror/state"; /** Engine command ids used by the editor. */ @@ -111,7 +112,7 @@ export const useEditorStore = defineStore("editor", () => { /** Engine transport for syncs, replaceable in tests. */ let transport: SyncTransport = engineTransport; /** Extensions of a new editor state for a file path, replaceable in tests. */ - let extensions: (path: string) => Extension = editorExtensions; + let extensions: (path: string, buffer?: AssistBuffer) => Extension = editorExtensions; /** Counter of tab adoptions, so only the newest open activates its tab. */ let openSequence = 0; /** Unsubscribe function of the event subscription. */ @@ -144,7 +145,7 @@ export const useEditorStore = defineStore("editor", () => { * @param next - transport for new syncs. * @param nextExtensions - extensions for new editor states, by file path. */ - function configure(next: SyncTransport, nextExtensions?: (path: string) => Extension): void { + function configure(next: SyncTransport, nextExtensions?: (path: string, buffer?: AssistBuffer) => Extension): void { transport = next; if (nextExtensions) { extensions = nextExtensions; @@ -163,7 +164,7 @@ export const useEditorStore = defineStore("editor", () => { const started = openStarted.get(info.path); syncs.set( info.id, - new BufferSync(info, extensions(info.path), transport, (error) => { + new BufferSync(info, extensions(info.path, { id: info.id, idle: () => syncs.get(info.id)?.idle() ?? Promise.resolve() }), transport, (error) => { const tab = tabOf(info.id); if (tab) { tab.notice = { kind: "error", message: error.message }; diff --git a/ui/tests/editor/assist/completion.test.ts b/ui/tests/editor/assist/completion.test.ts new file mode 100644 index 0000000..030f22e --- /dev/null +++ b/ui/tests/editor/assist/completion.test.ts @@ -0,0 +1,285 @@ +/** + * Tests of the completion source (M3.4, `assist/completion.ts`): Lutra's + * trigger rules, the query it sends (UTF-16 columns, trigger characters, + * waiting for the buffer sync), local filtering only for complete lists, + * and applying items: text edits, text typed after the request, imports + * as additional edits, CRLF documents and CRLF insert texts. + */ +import { CompletionContext, type Completion, type CompletionResult } from "@codemirror/autocomplete"; +import { php } from "@codemirror/lang-php"; +import { ensureSyntaxTree } from "@codemirror/language"; +import { EditorState, Text } from "@codemirror/state"; +import { EditorView } from "@codemirror/view"; +import { afterEach, describe, expect, it } from "vitest"; +import { + completionChanges, + completionTrigger, + lspCompletionSource, + toOptions, +} from "../../../src/components/editor/assist/completion"; +import { kindIcon } from "../../../src/components/editor/assist/icons"; +import { assistExtensions } from "../../../src/components/editor/assist"; +import { toCompletionList, type CompletionItem } from "../../../src/components/editor/assist/types"; +import { fakeBuffer, fakeTransport } from "./fakes"; + +/** Views created by a test, destroyed after it. */ +let views: EditorView[] = []; + +afterEach(() => { + for (const view of views) { + view.destroy(); + } + views = []; +}); + +/** A PHP editor state with the cursor at `|` in `text`. */ +function stateAt(text: string): { state: EditorState; pos: number } { + const pos = text.indexOf("|"); + const doc = text.slice(0, pos) + text.slice(pos + 1); + const state = EditorState.create({ doc, extensions: [php()], selection: { anchor: pos } }); + ensureSyntaxTree(state, state.doc.length, 5000); + return { state, pos }; +} + +/** A complete item with defaults. */ +function item(over: Partial): CompletionItem { + return { label: "x", kind: "text", insertText: over.label ?? "x", ...over }; +} + +/** Applies a plan to a document and returns the text and cursor. */ +function applyPlan(doc: string, plan: ReturnType): { text: string; cursor: number } { + const state = EditorState.create({ doc }); + const changes = state.changes(plan.changes); + return { text: changes.apply(state.doc).toString(), cursor: changes.mapPos(plan.mainEnd, 1) }; +} + +describe("completionTrigger", () => { + it("triggers after member and static access, variables and namespaces", () => { + expect(completionTrigger("$a->", false)).toEqual({ back: 0, character: ">" }); + expect(completionTrigger("$a?->", false)).toEqual({ back: 0, character: ">" }); + expect(completionTrigger("Foo::", false)).toEqual({ back: 0, character: ":" }); + expect(completionTrigger("echo $", false)).toEqual({ back: 1, character: "$" }); + expect(completionTrigger("new App\\", false)).toEqual({ back: 0, character: "\\" }); + }); + + it("triggers on identifiers and variables being typed", () => { + expect(completionTrigger("$a->fo", false)).toEqual({ back: 2 }); + expect(completionTrigger("echo $na", false)).toEqual({ back: 3 }); + expect(completionTrigger("strl", false)).toEqual({ back: 4 }); + expect(completionTrigger("$ä", false)).toEqual({ back: 2 }); + }); + + it("does not trigger on numbers, operators or spaces unless asked", () => { + expect(completionTrigger("x = 12", false)).toBeNull(); + expect(completionTrigger("x = 1e5", false)).toBeNull(); + expect(completionTrigger("a - ", false)).toBeNull(); + expect(completionTrigger("a -", false)).toBeNull(); + expect(completionTrigger("", false)).toBeNull(); + expect(completionTrigger("a - ", true)).toEqual({ back: 0 }); + expect(completionTrigger("12", true)).toEqual({ back: 0 }); + }); +}); + +describe("toCompletionList", () => { + it("drops malformed items and defaults the rest", () => { + const list = toCompletionList({ + incomplete: true, + items: [ + { label: "a", kind: "nonsense" }, + { label: "" }, + "junk", + { label: "b", kind: "class", insertText: "B", textEdit: { range: { start: {}, end: {} }, newText: "x" } }, + { label: "c", additionalTextEdits: [{ range: { start: { line: 0, column: 0 }, end: { line: 0, column: 0 } }, newText: "u" }, null] }, + ], + }); + expect(list.incomplete).toBe(true); + expect(list.items.map((i) => i.label)).toEqual(["a", "b", "c"]); + expect(list.items[0]).toEqual({ label: "a", kind: "text", insertText: "a" }); + expect(list.items[1]?.textEdit).toBeUndefined(); + expect(list.items[2]?.additionalTextEdits).toHaveLength(1); + expect(toCompletionList(null)).toEqual({ items: [], incomplete: false }); + expect(toCompletionList({ items: "no" })).toEqual({ items: [], incomplete: false }); + }); +}); + +describe("completionChanges", () => { + it("applies a text edit and the typing since the request", () => { + const doc = "fo"; + const requestDoc = Text.of(doc.split("\n")); + const requestPos = doc.length; + const format = item({ + label: "format", + insertText: "format(", + textEdit: { range: { start: { line: 1, column: 4 }, end: { line: 1, column: 6 } }, newText: "format(" }, + }); + expect(applyPlan(doc, completionChanges(requestDoc, requestPos, format, 10, 12, doc.length))).toEqual({ + text: "format(", + cursor: 17, + }); + const typedMore = doc + "rm"; + expect(applyPlan(typedMore, completionChanges(requestDoc, requestPos, format, 10, 14, typedMore.length))).toEqual({ + text: "format(", + cursor: 17, + }); + }); + + it("replaces the typed word with insertText without a text edit", () => { + const doc = " { + const doc = " { + const engineText = "ru\r\n}\r\n"; + const lines = engineText.split("\r\n"); + const requestDoc = Text.of(lines); + const state = EditorState.create({ doc: requestDoc }); + const line = state.doc.line(3); + const requestPos = line.to; + const run = item({ + label: "run", + textEdit: { range: { start: { line: 2, column: 11 }, end: { line: 2, column: 13 } }, newText: "run(\r\n 1\r\n)" }, + }); + const plan = completionChanges(requestDoc, requestPos, run, requestPos - 2, requestPos, state.doc.length); + const changes = state.changes(plan.changes); + const after = changes.apply(state.doc); + expect(after.lines).toBe(7); + expect(after.line(3).text).toBe(" $this->run("); + expect(after.line(4).text).toBe(" 1"); + expect(after.line(5).text).toBe(")"); + expect(after.sliceString(0)).not.toContain("\r"); + }); + + it("clamps edits that point past the document to its last line", () => { + const doc = " { + it("asks with UTF-16 columns after the sync is idle and maps the items", async () => { + const transport = fakeTransport({ + items: [ + { label: "format", kind: "method", detail: "format(): string", documentation: "**doc**", insertText: "format(" }, + { label: "$value", kind: "variable", insertText: "$value" }, + ], + incomplete: false, + }); + const buffer = fakeBuffer(7); + const { state, pos } = stateAt("fo|"); + const source = lspCompletionSource(buffer, transport); + const result = (await source(new CompletionContext(state, pos, false))) as CompletionResult; + expect(buffer.idleCalls).toBe(1); + expect(transport.calls).toEqual([ + { command: "lsp.completion", params: { id: 7, position: { line: 1, column: 7 } } }, + ]); + expect(result.from).toBe(pos - 2); + expect(result.validFor).toBeInstanceOf(RegExp); + expect(result.options.map((o) => o.label)).toEqual(["format", "$value"]); + expect(result.options[0]?.detail).toBe("format(): string"); + expect(result.options[0]?.type).toBe("method"); + expect((result.options[0]?.boost ?? 0) > (result.options[1]?.boost ?? 0)).toBe(true); + const info = result.options[0]?.info; + expect(typeof info).toBe("function"); + }); + + it("sends the trigger character and asks again for incomplete lists", async () => { + const transport = fakeTransport({ items: [{ label: "run", kind: "method", insertText: "run" }], incomplete: true }); + const { state, pos } = stateAt("|"); + const result = (await lspCompletionSource(fakeBuffer(1), transport)(new CompletionContext(state, pos, false))) as CompletionResult; + expect(transport.calls[0]?.params).toMatchObject({ triggerCharacter: ">" }); + expect(result.from).toBe(pos); + expect(result.validFor).toBeUndefined(); + }); + + it("stays quiet in comments and strings unless asked", async () => { + const transport = fakeTransport({ items: [{ label: "x", kind: "text", insertText: "x" }], incomplete: false }); + const source = lspCompletionSource(fakeBuffer(1), transport); + const comment = stateAt(" { + const { state, pos } = stateAt(" { + view.dispatch({ changes: { from: pos, insert: "o" } }); + }); + const transport = fakeTransport({ items: [{ label: "foo", kind: "function", insertText: "foo" }], incomplete: false }); + const context = new CompletionContext(state, pos, false, view); + expect(await lspCompletionSource(buffer, transport)(context)).toBeNull(); + expect(transport.calls).toHaveLength(0); + const failing = fakeTransport(null, { code: "failed", message: "no PHP language server is running" }); + expect(await lspCompletionSource(fakeBuffer(1), failing)(new CompletionContext(state, pos, false))).toBeNull(); + }); + + it("applies an option through the view, with the import", () => { + const doc = " { + it("is only added for PHP files of a buffer", () => { + expect(assistExtensions("a.txt", fakeBuffer(1))).toEqual([]); + expect(assistExtensions("a.php", undefined)).toEqual([]); + expect(assistExtensions("src/A.php", fakeBuffer(1))).not.toEqual([]); + }); + + it("renders a Lucide icon with the kind's catalog name", () => { + const icon = kindIcon("class"); + expect(icon.title).toBe("Class"); + expect(icon.querySelector("svg")).not.toBeNull(); + expect(kindIcon("nonsense").className).toContain("lt-assist-kind-text"); + }); +}); + diff --git a/ui/tests/editor/assist/fakes.ts b/ui/tests/editor/assist/fakes.ts new file mode 100644 index 0000000..08bd0d6 --- /dev/null +++ b/ui/tests/editor/assist/fakes.ts @@ -0,0 +1,41 @@ +/** + * Fakes for the assist tests: a transport that records queries and + * answers with a fixed result, and a buffer whose sync is always idle. + */ +import type { AssistBuffer, AssistTransport } from "../../../src/components/editor/assist/types"; +import type { EngineError, JsonValue } from "../../../src/ipc"; + +/** A recording transport. */ +export interface FakeTransport extends AssistTransport { + /** The queries sent, in order. */ + calls: { command: string; params: JsonValue }[]; +} + +/** + * A transport that answers every query with `value`, or fails with + * `error`. + */ +export function fakeTransport(value: unknown, error?: EngineError): FakeTransport { + const calls: { command: string; params: JsonValue }[] = []; + return { + calls, + query: (command, params) => { + calls.push({ command, params }); + return Promise.resolve(error ? { ok: false, error } : { ok: true, value }); + }, + }; +} + +/** A buffer that counts idle waits; `onIdle` runs inside each one. */ +export function fakeBuffer(id: number, onIdle?: () => void): AssistBuffer & { idleCalls: number } { + const buffer = { + id, + idleCalls: 0, + idle: (): Promise => { + buffer.idleCalls += 1; + onIdle?.(); + return Promise.resolve(); + }, + }; + return buffer; +} diff --git a/ui/tests/editor/assist/hoverSignature.test.ts b/ui/tests/editor/assist/hoverSignature.test.ts new file mode 100644 index 0000000..7788391 --- /dev/null +++ b/ui/tests/editor/assist/hoverSignature.test.ts @@ -0,0 +1,178 @@ +/** + * Tests of hover documentation and signature help (M3.4, + * `assist/hover.ts`, `assist/signature.ts`): the queries they send, the + * tooltip range, safe rendering, the highlighted parameter, the counter, + * typing `(` and `,`, following the cursor and closing with Escape. + */ +import { EditorState, type Extension } from "@codemirror/state"; +import { EditorView } from "@codemirror/view"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { assistExtensions } from "../../../src/components/editor/assist"; +import { assistEnabled, quickDocumentation } from "../../../src/components/editor/assist/commands"; +import { hoverAt } from "../../../src/components/editor/assist/hover"; +import { + lspSignatureHelp, + renderSignature, + setSignature, + signatureField, +} from "../../../src/components/editor/assist/signature"; +import { toHover, toSignatureHelp, type SignatureHelpResult } from "../../../src/components/editor/assist/types"; +import { fakeBuffer, fakeTransport } from "./fakes"; + +/** Views created by a test, destroyed after it. */ +let views: EditorView[] = []; + +afterEach(() => { + for (const view of views) { + view.destroy(); + } + views = []; +}); + +/** A mounted view with `doc` and `extensions`. */ +function mount(doc: string, extensions: Extension = []): EditorView { + const parent = document.createElement("div"); + document.body.append(parent); + const view = new EditorView({ state: EditorState.create({ doc, extensions }), parent }); + views.push(view); + return view; +} + +/** A signature help result for `pair(int $a, string $b)`. */ +const pair: SignatureHelpResult = { + signatures: [ + { + label: "pair(int $a, string $b): void", + documentation: "Makes a *pair*.", + parameters: [{ label: [5, 11], documentation: "the `first`" }, { label: [13, 22] }], + }, + ], + activeSignature: 0, + activeParameter: 1, +}; + +describe("hover", () => { + it("asks for the hovered position and spans the returned range", async () => { + const view = mount("", + range: { start: { line: 1, column: 9 }, end: { line: 1, column: 12 } }, + }); + const tooltip = await hoverAt(view, 16, fakeBuffer(3), transport); + expect(transport.calls).toEqual([{ command: "lsp.hover", params: { id: 3, position: { line: 1, column: 10 } } }]); + expect(tooltip?.pos).toBe(15); + expect(tooltip?.end).toBe(18); + expect(tooltip?.above).toBe(true); + const dom = tooltip?.create(view).dom as HTMLElement; + expect(dom.classList.contains("lt-assist-hover")).toBe(true); + expect(dom.querySelector("pre code")?.textContent).toBe("class Foo"); + expect(dom.querySelector("img")).toBeNull(); + expect(dom.textContent).toContain(""); + }); + + it("shows nothing for empty or failed answers", async () => { + const view = mount(" { + it("highlights the active parameter and shows its and the signature's docs", () => { + const dom = renderSignature(pair); + expect(dom.querySelector(".lt-assist-signature-label")?.textContent).toBe("pair(int $a, string $b): void"); + expect(dom.querySelector(".lt-assist-signature-active")?.textContent).toBe("string $b"); + expect(dom.querySelectorAll(".lt-assist-signature-doc")).toHaveLength(1); + const first = renderSignature({ ...pair, activeParameter: 0 }); + expect(first.querySelector(".lt-assist-signature-active")?.textContent).toBe("int $a"); + expect(first.querySelectorAll(".lt-assist-signature-doc")).toHaveLength(2); + expect(first.querySelector(".lt-assist-signature-doc code")?.textContent).toBe("first"); + }); + + it("counts several signatures and lets a signature override the active parameter", () => { + const two: SignatureHelpResult = { + signatures: [...pair.signatures, { label: "pair(int $a)", parameters: [{ label: [5, 11] }], activeParameter: 0 }], + activeSignature: 1, + activeParameter: 3, + }; + const dom = renderSignature(two); + expect(dom.querySelector(".lt-assist-signature-count")?.textContent).toBe("2 of 2"); + expect(dom.querySelector(".lt-assist-signature-active")?.textContent).toBe("int $a"); + }); + + it("checks the untrusted result", () => { + expect(toSignatureHelp({ signatures: [] })).toBeNull(); + expect(toSignatureHelp(null)).toBeNull(); + const help = toSignatureHelp({ + signatures: [{ label: "f(a)", parameters: [{ label: [2, 3] }, { label: [2, 99] }, { label: "a" }, "junk"] }], + activeSignature: 7, + activeParameter: -1, + }); + expect(help?.activeSignature).toBe(0); + expect(help?.activeParameter).toBe(0); + expect(help?.signatures[0]?.parameters.map((p) => p.label)).toEqual([[2, 3], null, null, null]); + }); +}); + +describe("signature help while typing", () => { + it("opens on (, follows the cursor and closes with Escape", async () => { + const transport = fakeTransport({ + signatures: [{ label: "pair(int $a, string $b): void", parameters: [{ label: [5, 11] }, { label: [13, 22] }] }], + activeSignature: 0, + activeParameter: 0, + }); + const view = mount(" { + expect(view.state.field(signatureField)).not.toBeNull(); + }); + expect(transport.calls[0]).toEqual({ command: "lsp.signatureHelp", params: { id: 5, position: { line: 1, column: 5 } } }); + expect(view.dom.querySelector(".lt-assist-signature-active")?.textContent).toBe("int $a"); + view.dispatch({ changes: { from: 11, insert: "1" }, selection: { anchor: 12 }, userEvent: "input.type" }); + await vi.waitFor(() => { + expect(transport.calls).toHaveLength(2); + }); + const escape = new KeyboardEvent("keydown", { key: "Escape", bubbles: true }); + view.contentDOM.dispatchEvent(escape); + expect(view.state.field(signatureField)).toBeNull(); + }); + + it("closes when the server has no signatures any more", async () => { + const transport = fakeTransport({ signatures: [], activeSignature: 0, activeParameter: 0 }); + const view = mount(" { + expect(view.state.field(signatureField)).toBeNull(); + }); + }); + + it("ignores typing that does not start an argument", async () => { + const transport = fakeTransport(null); + const view = mount(" setTimeout(resolve, 20)); + expect(transport.calls).toHaveLength(0); + }); +}); + +describe("assist commands", () => { + it("are enabled only with a PHP editor and show quick documentation at the cursor", async () => { + expect(assistEnabled()).toBe(false); + const transport = fakeTransport({ contents: "**Foo** docs" }); + const view = mount(" v !== view); + expect(assistEnabled()).toBe(false); + }); +}); diff --git a/ui/tests/editor/assist/markdown.test.ts b/ui/tests/editor/assist/markdown.test.ts new file mode 100644 index 0000000..e1648f7 --- /dev/null +++ b/ui/tests/editor/assist/markdown.test.ts @@ -0,0 +1,97 @@ +/** + * Tests of the safe Markdown renderer (M3.4, `assist/markdown.ts`): the + * supported blocks and inlines, and that nothing in a server answer turns + * into HTML, script, a link target or an image source (XSS). + */ +import { describe, expect, it } from "vitest"; +import { MAX_MARKDOWN, renderMarkdown } from "../../../src/components/editor/assist/markdown"; + +/** Tag names of every element below `root`. */ +function tags(root: Element): string[] { + return [...root.querySelectorAll("*")].map((e) => e.tagName.toLowerCase()); +} + +describe("renderMarkdown", () => { + it("renders code fences, headings, rules, lists and paragraphs", () => { + const root = renderMarkdown( + [ + "```php", + "class A { }", + "```", + "", + "---", + "", + "# Title", + "First line", + "second line ", + "third", + "", + "- one", + "- two", + "1. first", + "> quoted", + ].join("\n"), + ); + expect(root.className).toBe("lt-markdown"); + const code = root.querySelector("pre > code"); + expect(code?.textContent).toBe("class A { }"); + expect((code as HTMLElement | null)?.dataset.language).toBe("php"); + expect(root.querySelector("hr")).not.toBeNull(); + expect(root.querySelector(".lt-markdown-heading strong")?.textContent).toBe("Title"); + const paragraph = [...root.querySelectorAll("p")].find((p) => p.textContent.startsWith("First")); + expect(paragraph?.textContent).toBe("First line second linethird"); + expect(paragraph?.querySelector("br")).not.toBeNull(); + expect([...root.querySelectorAll("ul > li")].map((li) => li.textContent)).toEqual(["one", "two"]); + expect(root.querySelector("ol > li")?.textContent).toBe("first"); + expect(root.querySelector("blockquote")?.textContent).toBe("quoted"); + }); + + it("renders inline code, strong, emphasis, links and escapes", () => { + const root = renderMarkdown("Use `a*b*c` with **bold**, *em*, _em2_, snake_case_name, [docs](https://php.net) and \\*not em\\*."); + const p = root.querySelector("p"); + expect(p?.querySelector("code")?.textContent).toBe("a*b*c"); + expect(p?.querySelector("strong")?.textContent).toBe("bold"); + expect([...(p?.querySelectorAll("em") ?? [])].map((e) => e.textContent)).toEqual(["em", "em2"]); + expect(p?.querySelector(".lt-markdown-link")?.textContent).toBe("docs"); + expect(p?.textContent).toContain("snake_case_name"); + expect(p?.textContent).toContain("*not em*."); + }); + + it("never creates HTML, links, images or script from the source (XSS)", () => { + const attacks = [ + "", + "", + "[click](javascript:alert(1))", + "![x](https://evil.example/x.png)", + "a", + "", + "```\n\n```", + "**"); + expect(img.textContent).toBe(""); + expect(renderMarkdown("<b>").textContent).toBe("<b>"); + const fenced = renderMarkdown("```\"onmouseover=alert(1)\n```"); + expect(fenced.querySelector("code")?.dataset.language).toBeUndefined(); + }); + + it("caps the source and survives deep nesting", () => { + const long = renderMarkdown("a".repeat(MAX_MARKDOWN + 100)); + expect(long.textContent.length).toBe(MAX_MARKDOWN); + const nested = renderMarkdown("*".repeat(200) + "x" + "*".repeat(200)); + expect(nested.textContent).toContain("x"); + const brackets = renderMarkdown("[".repeat(500) + "x"); + expect(brackets.textContent).toContain("x"); + }); +}); diff --git a/ui/tests/menu/AppMenu.test.ts b/ui/tests/menu/AppMenu.test.ts index d285265..387dd94 100644 --- a/ui/tests/menu/AppMenu.test.ts +++ b/ui/tests/menu/AppMenu.test.ts @@ -254,7 +254,7 @@ describe("AppMenu", () => { expect(menuShown()).toBe(true); expect(menu.find("[data-test=menu-button]").attributes("aria-expanded")).toBe("true"); const headings = [...document.querySelectorAll("[data-test=menu-group]")].map((g) => g.querySelector(".app-menu__heading")?.textContent.trim()); - expect(headings).toEqual(["File", "View", "Go", "Help"]); + expect(headings).toEqual(["File", "Edit", "View", "Go", "Help"]); expect(itemIds()).toEqual([ "project.openDialog", "file.save", @@ -262,6 +262,9 @@ describe("AppMenu", () => { "buffer.close", "project.close", "app.quit", + "editor.complete", + "editor.parameterInfo", + "editor.quickDocumentation", "palette.open", "view.toggleProjectTree", "view.toggleStructure", diff --git a/ui/tests/palette/CommandPalette.test.ts b/ui/tests/palette/CommandPalette.test.ts index 4b23369..f9f0993 100644 --- a/ui/tests/palette/CommandPalette.test.ts +++ b/ui/tests/palette/CommandPalette.test.ts @@ -260,13 +260,16 @@ describe("CommandPalette", () => { expect(rows(wrapper)).toEqual([ "project.close", "palette.open", + "editor.complete", "find.open", "goto.classOpen", "goto.fileOpen", "goto.symbolOpen", "project.openDialog", "menu.open", + "editor.parameterInfo", "problems.open", + "editor.quickDocumentation", "app.quit", "editor.reveal", "settings.open",