M2.6: go-to popup for files, classes and symbols

One popup with Files / Classes / Symbols tabs (Tab switches), opened by
goto.fileOpen (Mod+P), goto.classOpen (Mod+Alt+C) and goto.symbolOpen
(Mod+T), each with an optional {query} for agents. Live debounced query
against goto.* with stale answers dropped, matched characters marked,
directory / namespace / container column, library rows labelled, an
indexing hint with progress and a re-query on indexReady. Enter or a
click opens through editor.reveal; Escape closes. An exclusive modal and
a launcher: any other command closes it.

goto.file items now carry `library` (PM decision). indexProgress and
indexReady join the ipc event union. Notes in plan/phpstorm/08-goto.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-17 17:03:06 +02:00
parent ef198f5f8f
commit 943ff889df
21 changed files with 1650 additions and 23 deletions

View file

@ -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 and the Structure tool window · **Last updated:** 2026-10-17
> **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 · **Last updated:** 2026-10-17
## Overview
@ -252,7 +252,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- Queries: `Index` (a `BTreeMap` by path, so a directory's files drop with one range) answers `find_files`, `find_classes` and `find_symbols`. Every whitespace-separated query word must match fuzzily (fzf-style scoring, smart case, no other special syntax); queries are capped at 256 characters and 1,000 results. Files: a query without `/` (a `\` counts as `/`) is matched against the file name first with double weight, else the path; match ranges are merged UTF-16 ranges in the path. Classes: by name, by FQN when the query has a `\`. Symbols: by name; `Class::member` matches the container's short name (FQN with a `\`) and the member separately, `Class::` lists members. Order: project before library, higher score, shorter name, byte order. Indexes over 20,000 files plus symbols are scanned on `default_threads()` threads, each keeping its own best hits.
- Engine (`cmd/goto.rs`): `State::index` holds the index of the open project. `goto::sync` runs on every `Engine::pump_vfs` and before every index command: it starts the build and the updater when a project is open and the index belongs to another root (or none), drops them without a project (dropping cancels the threads; `project.close` also drops it at once), merges up to 4,096 updates, emits `indexProgress {done, total}` at most every 250 ms while building and `indexReady {files, symbols, elapsedMs}` at the end, and re-indexes buffers. The engine lock is held only for inserts and queries; walking and parsing never run under it. Updater results that arrive while the build runs mark their paths, and later build results for those paths are ignored, so a buffer edit or a disk change is never overwritten by the stale build.
- Incremental sources: `workspace::pump` hands the VFS events to `goto::note_disk_changes` (removed paths dropped at once, created or modified files re-read, created directories and rename targets rescanned); the watcher is not recursive, so only watched directories (root, listed, pinned) report changes. A buffer whose version changed is re-indexed from its text when its path is in the index (or the build still runs); while it is dirty, disk changes for it are ignored; closing it dirty re-reads the file.
- Commands: `index.status` → `{state: "idle"|"indexing", files, symbols}` (idle and zero without a project). `goto.file {query, limit?}` → `{items: [{path, score, matches: [[start, end]]}], indexing}`; `goto.class` → `{items: [{name, fqn, kind, path, line, column, library}], indexing}`; `goto.symbol` → the same plus `container` (FQN or `null`), for functions, methods, properties, constants and enum cases. `limit` defaults to 50 (at most 1,000); an empty query returns no items. The go-to commands are disabled without a project; none has a menu path or shortcut yet (M2.6 adds the popup).
- Commands: `index.status` → `{state: "idle"|"indexing", files, symbols}` (idle and zero without a project). `goto.file {query, limit?}` → `{items: [{path, score, matches: [[start, end]], library}], indexing}` (`library` added by M2.6, PM decision: vendor files, as in class and symbol items); `goto.class` → `{items: [{name, fqn, kind, path, line, column, library}], indexing}`; `goto.symbol` → the same plus `container` (FQN or `null`), for functions, methods, properties, constants and enum cases. `limit` defaults to 50 (at most 1,000); an empty query returns no items. The go-to commands are disabled without a project; none has a menu path or shortcut; the popup's UI commands do (below).
- Measured (release, Windows 11, 8 cores / 16 threads, 15 workers, generated `lutra_testkit::generate_php_project(20_000)`: 20,001 files, 19,000 PHP of ~5 KB, 87.7 MB, 324,080 symbols): build 3.9–4.2 s on an idle machine (target < 5 s met), 4.6–5.7 s while other agents' builds ran; the walk takes 25–35 ms and the first batch arrives after ~30 ms, so the parse dominates (~21 MB/s over 15 workers, ~1.4 MB/s per worker). Queries on the full index, median of 7: `goto.class` 2–4 ms, `goto.symbol` 7–11 ms, `Class::member` 11–12 ms, `goto.file` 2 ms (single-threaded before the parallel scan: `goto.symbol` 72–100 ms). `cargo test --release -p lutra-index --test perf -- --ignored --nocapture` repeats it.
- Live check over the control channel against the running app (debug build, port 7825, generated 6,002-file project with gitignored `vendor/` and `var/`): `index.status` answered `indexing` right after `project.open`, a go-to query during the build returned `indexing: true`, 25 `indexProgress` events at least 251 ms apart, `indexReady` after 8.2 s (debug build: the tree-sitter C code and the workers are unoptimised) with 6,002 files and 62,000 symbols; `goto.file`, `goto.class` (vendor marked `library`), `goto.symbol` with `Class::member` answered in 5–25 ms; the gitignored `var/` class was absent; a `buffer.edit` renaming a class and a file created on disk were found within a second; `project.close` reset the status to idle.
@ -263,6 +263,16 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- **UI:** `MainLayout.vue` has a left stripe (a vertical tab list, Lucide `FolderTree` and `ListTree`) with Project and Structure; the left tool window shows one of them, both stay mounted while it is open (`v-show`). Clicking the shown one's tab or running its command again hides the window. UI commands `view.toggleProjectTree` (`Mod+1`) and `view.toggleStructure` (`Mod+2`, Lutra's own). `ui/src/components/structure/structure.ts` (Pinia `structure`, started by the window) follows the editor's active tab and `outlineChanged` for that buffer, drops answers overtaken by a newer request, validates the untrusted outline (depth cap 64, at most 50,000 items) and remembers collapsed nodes per buffer by the path of kinds and names. `StructureToolWindow.vue` is a WAI-ARIA tree: kind icons from Lucide coloured with `--lt-syntax-*` tokens, the name and the signature; arrows, Home/End, Left/Right fold, Enter or a click jumps through `editor.reveal` to the start of the name; empty states for no file, no declarations, still parsing and too large.
- **Measured** (release, Windows 11, generated 1 MB PHP file with 16,281 outline items, other builds running): `buffer.edit` under the lock at most 0.07–0.25 ms, `pump_vfs` at most 3.8 ms; first outline 0.9–1.3 s after `file.open` (full parse ~0.75 s plus outline); edit to `outlineChanged` 0.43–0.76 s (200 ms debounce, incremental reparse 9–14 ms, outline with JSON 0.2–0.3 s, pump interval). `syntax.outline` itself takes 82 ms on that file, because the engine deep-copies the stored JSON into the command result; typing is not blocked by it (the editor syncs asynchronously), but the engine lock is. Typical files (10–50 KB) are a few milliseconds end to end. `cargo test --release -p lutra-engine --test syntax -- --ignored --nocapture` repeats it.
### Go-to popup (M2.6)
- `ui/src/components/goto/GotoPopup.vue` (mounted in `App.vue`) with the state in `ui/src/stores/goto.ts`. One popup, three modes (`file`, `class`, `symbol`) as tabs; Tab / Shift+Tab or a click switches the mode and re-runs the same text in it.
- UI commands `goto.fileOpen` (`Mod+P`), `goto.classOpen` (`Mod+Alt+C`), `goto.symbolOpen` (`Mod+T`), each with an optional `{query}` so an agent can open the popup on a query over `uiCommand`; enabled only while a project is open. The shortcuts are Lutra's own.
- Live query: typing waits 60 ms after the last keystroke, then runs the mode's `goto.*` with `limit: 100`; every query takes a sequence number, and an answer that is not the newest is dropped (also after the popup closed). Mode switches and a `{query}` from the params query at once.
- Rows: file items split `matches` at the file name (name marked in the label, directory in the second column); class and symbol answers carry no ranges, so the popup marks the query's characters in order in the name (after `::` for `Class::member`). The second column is the namespace, or the container for members. `library: true` rows are dimmed and labelled. Untrusted fields are checked; malformed items and ranges are dropped or clamped.
- Indexing: `indexing: true` shows a hint with the latest `indexProgress {done, total}`; `indexReady` re-runs the open query.
- Opening: Enter or a click closes the popup (focus goes back) and runs `editor.reveal` with `{path}` for files (the file's cursor stays) or `{path, line, column}` for symbols. The popup is an exclusive modal (`ModalId` `goto` in `commands/modals.ts`). Like the palette it is a launcher: running any command other than the three open commands closes it (`commands/store.ts` › `execute`), so an agent's `editor.reveal` never leaves it open.
- Live check (debug build, bundled UI, port 7826, temp project with 34 files and a `vendor/` folder): `goto.fileOpen {query: "user"}` listed the two project files before the vendor one with its `library` label; `goto.classOpen {query: "usr"}` and `goto.symbolOpen {query: "User::find"}` switched the tab with marks shown; `palette.open` then `goto.fileOpen` left only the popup; an `editor.reveal` of the symbol item closed the popup and put the cursor on `find`. `goto.file` answered in < 1 ms over the control channel. Enter and clicks cannot be sent over the control channel; Vitest covers them.
## Decisions (M0)
| Question | Decision | Why |
@ -280,6 +290,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 2026-10-17 | minor | M2.6: go-to popup (store, debounce and stale drop, modes, `editor.reveal`), `library` on `goto.file` items |
| 2026-10-17 | minor | M2.7: per-buffer syntax tree off the engine lock, `syntax.outline`, `outlineChanged`, left stripe, Structure tool window |
| 2026-10-17 | minor | M2.5: symbol index (`crates/index`: parallel build, updater, fuzzy queries), `index.status`, `goto.file`/`goto.class`/`goto.symbol`, `indexProgress`/`indexReady` via the pump, timing |
| 2026-10-17 | minor | M2.4: bottom panel, Find tool window (store, event race, one search at a time), `find.open` |