Lutra/ui/src/components/editor/assist/commands.ts
danny a212a44490 M3.4: completion, hover and signature help from Phpactor
Engine (crates/engine/src/cmd/lsp_assist.rs), on M3.5's pending outcomes:
- lsp.completion {id, position, triggerCharacter?}: items with label,
  kind, detail, Markdown documentation, insertText, textEdit,
  additionalTextEdits, sortText; sorted, capped at 500 (cut lists are
  incomplete), snippets turned into plain text.
- lsp.hover {id, position}: Markdown contents and range.
- lsp.signatureHelp {id, position}: signatures with UTF-16 parameter spans.
- The request is queued after every didChange; the answer is converted
  in the reply callback, off the engine lock. Positions are checked
  against the buffer. Server strings and lists are capped.
- lutra-lsp-fake answers completion and signature help.

Editor (ui/src/components/editor/assist/):
- Completion source with Lutra's triggers (identifiers, $, ->, ?->, ::,
  namespace \; not in strings or comments unless asked), the server's
  ranking as boost, text edits and imports applied in UTF-16 (CRLF too),
  Lucide kind icons.
- Hover documentation (350 ms) and editor.quickDocumentation (Mod+I).
- Signature help on ( and , following the cursor; editor.parameterInfo.
- editor.complete.
- Lutra's own Markdown renderer without HTML (XSS-tested), tokens only.
- Requests wait for the buffer sync to be idle and use runWaiting.
- New dependency @codemirror/autocomplete (MIT, already transitive).

Tests: 6 engine tests against the fake server, 9 unit tests, an ignored
real-Phpactor latency test, 29 Vitest tests; palette and menu tests list
the new UI commands.

Measured with the real Phpactor (Windows 11, debug build, 25 ms tick):
- Completion 61-109 ms while typing (median 76 ms; ~107 ms in the app).
- Hover and signature help ~16 ms median.
- A useful list 2.3 s after opening a file in a 20-class project, ~65 s
  for 2,000 classes (indexing).
- Phpactor 56-71 MB working set, ~6% of one core while typing.

Live-checked in the app on port 7934. Docs: Code completion 0% -> 5%
(est.), feature depth ~4.1% -> ~4.6%, breadth 26/155, architecture, G6,
ui-parity, language-parity, roadmap, README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 18:38:07 +02:00

127 lines
3.9 KiB
TypeScript

/**
* 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<Tooltip | null>();
/** The quick documentation tooltip; closed by any edit or cursor move. */
const quickDocField = StateField.define<Tooltip | null>({
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<void> {
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);
}
}