From c68932c39c447019644cc3334ec0d970ea14182b Mon Sep 17 00:00:00 2001 From: danny Date: Sat, 17 Oct 2026 13:31:37 +0200 Subject: [PATCH] M2.7: Structure tool window and syntax.outline Engine: every open PHP buffer keeps a tree-sitter tree, reparsed incrementally on a worker thread off the engine lock (200 ms debounce, edit batches recorded by buffer.edit, full parse when the chain breaks). syntax.outline {id} returns {items, truncated, version}; outlineChanged {id} at most every 200 ms per buffer. Replaced trees and outlines are freed on the worker. UI: left stripe with Project | Structure in MainLayout, the Structure tool window (WAI-ARIA tree, Lucide kind icons, signatures, jumps via editor.reveal), view.toggleStructure on Mod+2. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 1 + ROADMAP.md | 10 +- crates/control/tests/syntax.rs | 170 ++++ crates/engine/Cargo.toml | 1 + crates/engine/src/cmd/buffer.rs | 4 +- crates/engine/src/cmd/mod.rs | 2 + crates/engine/src/cmd/syntax.rs | 796 ++++++++++++++++++ crates/engine/src/engine.rs | 5 +- crates/engine/src/event.rs | 15 + crates/engine/src/state.rs | 2 + .../engine/tests/syntax.proptest-regressions | 7 + crates/engine/tests/syntax.rs | 239 ++++++ docs/architecture.md | 10 +- docs/gaps.md | 9 +- docs/roadmap.md | 3 +- docs/target-app-parity.md | 5 +- docs/ui-parity.md | 5 +- ui/src/commands/uiCommands.ts | 1 + ui/src/components/layout/MainLayout.vue | 125 ++- .../structure/StructureToolWindow.vue | 434 ++++++++++ ui/src/components/structure/structure.ts | 314 +++++++ ui/src/i18n/en.json | 18 + ui/src/ipc.ts | 5 + ui/tests/App.test.ts | 2 +- ui/tests/i18n/catalog.test.ts | 2 +- ui/tests/palette/CommandPalette.test.ts | 3 +- .../structure/StructureToolWindow.test.ts | 436 ++++++++++ 27 files changed, 2596 insertions(+), 28 deletions(-) create mode 100644 crates/control/tests/syntax.rs create mode 100644 crates/engine/src/cmd/syntax.rs create mode 100644 crates/engine/tests/syntax.proptest-regressions create mode 100644 crates/engine/tests/syntax.rs create mode 100644 ui/src/components/structure/StructureToolWindow.vue create mode 100644 ui/src/components/structure/structure.ts create mode 100644 ui/tests/structure/StructureToolWindow.test.ts diff --git a/Cargo.lock b/Cargo.lock index efb22cb..fda53f2 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2584,6 +2584,7 @@ version = "0.0.0" dependencies = [ "lutra-index", "lutra-search", + "lutra-syntax", "lutra-testkit", "lutra-text", "lutra-vfs", diff --git a/ROADMAP.md b/ROADMAP.md index a22ef6f..2eebce5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,7 +2,7 @@ **Stage: pre-alpha (M1 done)** · next: M2 syntax and search; 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-17 · **Change:** minor (M2.4: Find tool window) · **Target:** JetBrains PhpStorm 2026.x, described from public documentation only +> **Last reviewed:** 2026-10-15 · **Last updated:** 2026-10-17 · **Change:** minor (M2.7: Structure tool window) · **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). @@ -13,7 +13,7 @@ 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) | **<1%** (project tool window, editor tabs; no inventory to count against yet) | estimated | -| **Feature depth** (weighted by use, scored by behaviour) | **~2.2%** (Editor core 10% × weight 12, Project view 8% × weight 6, Search and replace 8% × weight 6, Settings 7% × weight 1, of 101) | estimated | +| **Feature depth** (weighted by use, scored by behaviour) | **~2.6%** (Editor core 10% × weight 12, Navigation 4% × weight 10, Project view 8% × weight 6, Search and replace 8% × weight 6, Settings 7% × weight 1, of 101) | estimated | | **To MVP (M3)** | **~13 h left** (M1 done in ~5.6 h measured: C1 2.5 h, C2 3.1 h; M2 ~5 h, M3 ~8 h); was ~190 h before calibration | estimated (×0.1; C1 factor 0.07, C2 factor 0.10) | | **To full parity** | **~330 h** if the speed of cycles C1 and C2 holds (range 300–3,300 h; 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) | ~2.2% | ~2,914 | [target-app-parity.md](docs/target-app-parity.md) | +| Features (depth) | ~2.6% | ~2,902 | [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) | @@ -43,7 +43,7 @@ Stability 8%: no-panic lints, the engine guard, a fuzzed control protocol and a |---|---:|---:| | Editor core (buffers, undo, multi-caret, folding, soft wrap) | 10% (est.) | ~104 | | Project view, VFS, file watching | 8% (est.) | ~40 | -| Navigation (go to class/file/symbol, recent files, structure) | 0% | ~120 | +| Navigation (go to class/file/symbol, recent files, structure) | 4% | ~108 | | Search and replace (in file, in project, structural) | 8% (est.) | ~70 | | Code completion | 0% | ~250 | | Inspections and quick-fixes | 0% | ~300 | @@ -76,6 +76,7 @@ All hours estimated. Weights, evidence and the missing items per area: [target-a | Date | What landed | |---|---| +| 2026-10-17 | M2.7: a Structure tool window next to Project (new left stripe, `Mod+2`) shows the classes, functions, methods, properties and constants of the active PHP file as a tree that follows tabs and edits; click or Enter jumps to the declaration. The file is reparsed in the background, so big files never stall typing. | | 2026-10-17 | M2.4: Find in files has a window: `Mod+Alt+F` opens a bottom panel with the selection or the word at the cursor as the query; results stream in grouped by file with the hit highlighted, with match case, whole words, regex and file globs; Enter or a click jumps to the match; a new search cancels the old one. | | 2026-10-16 | M2.2: PHP files are highlighted (with the HTML around `, + writer: TcpStream, + events: Vec, +} + +impl Client { + fn connect(addr: std::net::SocketAddr) -> Self { + let stream = TcpStream::connect(addr).unwrap(); + stream + .set_read_timeout(Some(Duration::from_secs(10))) + .unwrap(); + Self { + writer: stream.try_clone().unwrap(), + reader: BufReader::new(stream), + events: Vec::new(), + } + } + + fn line(&mut self) -> Value { + let mut line = String::new(); + self.reader.read_line(&mut line).expect("line within 10 s"); + serde_json::from_str(&line).unwrap() + } + + fn call(&mut self, request: Value) -> Value { + self.writer + .write_all(format!("{request}\n").as_bytes()) + .unwrap(); + loop { + let line = self.line(); + if line.get("event").is_some() { + self.events.push(line["event"].clone()); + } else { + return line; + } + } + } + + /// Waits for `outlineChanged` of buffer `id`. + fn outline_changed(&mut self, id: u64) { + let pending = std::mem::take(&mut self.events); + if pending + .iter() + .any(|e| e["kind"] == "outlineChanged" && e["id"] == id) + { + return; + } + loop { + let line = self.line(); + if line["event"]["kind"] == "outlineChanged" && line["event"]["id"] == id { + return; + } + } + } +} + +fn execute(command: &str, params: Value) -> Value { + json!({"id": command, "method": "engine.execute", "params": {"command": command, "params": params}}) +} + +/// Pumps the backend every 20 ms, like the desktop's pump thread, until +/// dropped. +struct Pump(Arc); + +impl Pump { + fn start(backend: Arc) -> Self { + let stop = Arc::new(AtomicBool::new(false)); + let flag = stop.clone(); + std::thread::spawn(move || { + while !flag.load(Ordering::Relaxed) { + backend.pump(); + std::thread::sleep(Duration::from_millis(20)); + } + }); + Self(stop) + } +} + +impl Drop for Pump { + fn drop(&mut self) { + self.0.store(true, Ordering::Relaxed); + } +} + +/// Names of the items, depth first. +fn names(items: &Value) -> Vec { + let mut out = Vec::new(); + for item in items.as_array().unwrap() { + out.push(item["name"].as_str().unwrap().to_string()); + out.extend(names(&item["children"])); + } + out +} + +#[test] +fn outline_follows_the_buffer() { + let dir = tempfile::tempdir().unwrap(); + let source = " Result<(), EngineError> { registry.register(Box::new(goto::File))?; registry.register(Box::new(goto::Class))?; registry.register(Box::new(goto::Symbol))?; + registry.register(Box::new(syntax::OutlineCommand))?; Ok(()) } diff --git a/crates/engine/src/cmd/syntax.rs b/crates/engine/src/cmd/syntax.rs new file mode 100644 index 0000000..38d3cf6 --- /dev/null +++ b/crates/engine/src/cmd/syntax.rs @@ -0,0 +1,796 @@ +//! Syntax of open buffers: the per-buffer tree-sitter parse and +//! `syntax.outline`. +//! +//! Every open PHP buffer (`.php`, `.phtml`, `.inc`) has a syntax tree that +//! follows its text. Parsing never runs under the engine lock: a 1 MB file +//! takes about half a second to parse from scratch and 70–130 ms for its +//! outline (M2.1). Instead: +//! - `buffer.edit` records each edit batch ([`record_edits`]), a cheap copy +//! of the byte-offset edits it applied. +//! - [`pump`] (called by [`crate::Engine::pump_vfs`]) notices buffers whose +//! version moved past their tree and, once a buffer has been quiet for +//! [`DEBOUNCE`] (a new buffer at once), hands a snapshot of its text, the +//! last tree and the recorded batches to one worker thread. At most one +//! job per buffer is in flight. +//! - The worker reparses the old tree batch by batch +//! ([`lutra_syntax::Parser::reparse`]) and checks the result against the +//! snapshot; when no tree, no unbroken chain of batches (a reload from +//! disk or a restore changed the text without `buffer.edit`, or more than +//! [`MAX_PENDING_BATCHES`] batches piled up) or a mismatch remains, it +//! parses the snapshot from scratch. It then builds the outline as JSON. +//! - The worker also compares the new outline with the previous one, so +//! the engine never walks a large outline under its lock. +//! - The next pump stores the tree and outline and, if the outline changed, +//! queues [`Event::OutlineChanged`], at most once per +//! [`MIN_EVENT_INTERVAL`] per buffer. The first outline of a buffer is +//! always announced. Replaced trees and outlines (and those of closed +//! buffers) go back to the worker to be freed there: dropping the outline +//! of a 1 MB file takes tens of milliseconds. +//! +//! `syntax.outline {id}` answers from the stored outline, so it never waits +//! for a parse; its `version` says which buffer version the items describe +//! (`null` before the first parse finished). + +use std::collections::BTreeMap; +use std::path::Path; +use std::sync::Arc; +use std::sync::mpsc::{self, Receiver, Sender, TryRecvError}; +use std::time::{Duration, Instant}; + +use lutra_syntax::{MAX_PARSE_BYTES, OutlineItem, Parser, Range, Tree}; +use lutra_text::{Buffer, Edit}; +use serde::Deserialize; +use serde_json::{Map, Value, json}; + +use super::params::parse; +use crate::buffers::BufferId; +use crate::{Command, CommandSpec, EngineError, Event, Outcome, State}; + +/// How long a buffer must be unchanged before it is reparsed. +pub const DEBOUNCE: Duration = Duration::from_millis(200); + +/// Shortest time between two `outlineChanged` events of one buffer. +pub const MIN_EVENT_INTERVAL: Duration = Duration::from_millis(200); + +/// Most recorded edit batches per buffer; beyond it the next parse starts +/// from scratch. +pub const MAX_PENDING_BATCHES: usize = 64; + +/// Most inserted bytes recorded per buffer; beyond it the next parse starts +/// from scratch. +pub const MAX_PENDING_BYTES: usize = 8 * 1024 * 1024; + +/// The syntax state of the open buffers. +#[derive(Debug, Default)] +pub struct Syntax { + /// Per PHP buffer, by id. + docs: BTreeMap, + /// The parse thread, started by the first pump that needs it. + worker: Option, + /// The grammar could not be loaded; nothing is ever parsed. + unavailable: bool, +} + +impl Syntax { + /// Number of buffers whose parse is running. + pub fn in_flight(&self) -> usize { + self.docs.values().filter(|d| d.in_flight.is_some()).count() + } +} + +/// Channels to the parse thread. +#[derive(Debug)] +struct Worker { + /// Jobs for the thread; dropping it ends the thread. + jobs: Sender, + /// Finished parses. + done: Receiver, +} + +/// The outline of one buffer version, as `syntax.outline` returns it. +#[derive(Debug, Clone)] +struct Outline { + /// Buffer version the items describe. + version: u64, + /// The items as JSON, shared with the worker for its comparison. + items: Arc, + /// The text was too large to parse. + truncated: bool, +} + +/// One edit batch as `buffer.edit` applied it. +#[derive(Debug, Clone)] +struct Batch { + /// Version of the text the batch applies to. + base: u64, + /// Byte-offset edits with [`Buffer::apply`] semantics. + edits: Vec, +} + +/// Syntax state of one buffer. +#[derive(Debug, Default)] +struct Doc { + /// The newest tree and the version it describes. + tree: Option<(u64, Tree)>, + /// The newest outline. + outline: Option, + /// Batches recorded after the tree's version, oldest first. + batches: Vec, + /// Inserted bytes in [`Doc::batches`]. + batch_bytes: usize, + /// The buffer version the engine last saw. + seen_version: u64, + /// When the text last changed; `None` for a new buffer (parse at once). + changed_at: Option, + /// Version of the parse running on the worker. + in_flight: Option, + /// Version of the last parse that failed, so it is not retried. + failed: Option, + /// The outline changed and `outlineChanged` is still to be sent. + announce: bool, + /// When `outlineChanged` was last sent. + last_event: Option, +} + +/// What the engine sends the worker. +enum Message { + /// Parse a buffer. + Parse(Job), + /// Free trees and outlines the engine no longer needs. + Retire(Vec), +} + +/// A replaced tree or outline, freed on the worker. +type Retired = Box; + +/// A parse for the worker. +struct Job { + /// The buffer. + id: BufferId, + /// The buffer version of `text`. + version: u64, + /// The text to parse (a rope snapshot). + text: Buffer, + /// The previous tree to reparse from, if any. + base: Option, + /// The batches leading from `base` to `text`. + batches: Vec>, + /// The outline shown now, to tell whether the new one differs. + previous: Option, +} + +/// A finished parse. +struct Done { + /// The buffer. + id: BufferId, + /// The buffer version parsed. + version: u64, + /// The tree, its outline and whether the outline differs from the + /// job's previous one; `None` if the parse panicked. + result: Option<(Tree, Outline, bool)>, +} + +/// Whether a project-relative path is parsed as PHP. +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)) + }) +} + +/// Records an edit batch that `buffer.edit` applied to buffer `id`, moving +/// it from version `base` to `base + 1`. Buffers that are not PHP or have no +/// parse yet need no record. A batch over the caps clears the record, so +/// the next parse starts from scratch. +pub fn record_edits(state: &mut State, id: BufferId, base: u64, edits: Vec, now: Instant) { + let Some(doc) = state.syntax.docs.get_mut(&id) else { + return; + }; + doc.changed_at = Some(now); + doc.seen_version = base.saturating_add(1); + if doc.tree.is_none() && doc.in_flight.is_none() { + return; + } + let bytes: usize = edits.iter().map(|e| e.text.len()).sum(); + doc.batch_bytes = doc.batch_bytes.saturating_add(bytes); + doc.batches.push(Batch { base, edits }); + if doc.batches.len() > MAX_PENDING_BATCHES || doc.batch_bytes > MAX_PENDING_BYTES { + doc.batches.clear(); + doc.batch_bytes = 0; + } +} + +/// Moves finished parses into the state, starts due parses on the worker +/// and queues `outlineChanged` events. See the module docs. +pub fn pump(state: &mut State, now: Instant) { + let mut retired = Vec::new(); + drain(state, &mut retired); + sync_docs(state, now, &mut retired); + schedule(state, now); + announce(state, now); + retire(state, retired); +} + +/// Hands trees and outlines to the worker to free. Without a worker, or +/// when the send fails because the worker vanished (the failed send hands +/// the items back, so ignoring it frees them here), they are freed on the +/// caller's thread. +fn retire(state: &mut State, retired: Vec) { + if retired.is_empty() { + return; + } + if let Some(worker) = state.syntax.worker.as_ref() { + let _ = worker.jobs.send(Message::Retire(retired)); + } +} + +/// Takes finished parses from the worker. A vanished worker is forgotten, +/// so the next schedule starts a new one; parses it held are started again. +/// Replaced trees and outlines are queued in `retired`. +fn drain(state: &mut State, retired: &mut Vec) { + let syntax = &mut state.syntax; + let Some(worker) = syntax.worker.as_ref() else { + return; + }; + loop { + match worker.done.try_recv() { + Ok(done) => { + let Some(doc) = syntax.docs.get_mut(&done.id) else { + if let Some((tree, outline, _)) = done.result { + retired.push(Box::new(tree) as Retired); + retired.push(Box::new(outline) as Retired); + } + continue; + }; + if doc.in_flight == Some(done.version) { + doc.in_flight = None; + } + let Some((tree, outline, changed)) = done.result else { + doc.failed = Some(done.version); + continue; + }; + if doc.tree.as_ref().is_some_and(|(v, _)| *v > done.version) { + retired.push(Box::new(tree) as Retired); + retired.push(Box::new(outline) as Retired); + continue; + } + if let Some((_, old)) = doc.tree.replace((done.version, tree)) { + retired.push(Box::new(old) as Retired); + } + let mut kept = 0; + doc.batches.retain(|b| { + let keep = b.base >= done.version; + if keep { + kept += b.edits.iter().map(|e| e.text.len()).sum::(); + } + keep + }); + doc.batch_bytes = kept; + doc.announce |= changed; + if let Some(old) = doc.outline.replace(outline) { + retired.push(Box::new(old) as Retired); + } + } + Err(TryRecvError::Empty) => break, + Err(TryRecvError::Disconnected) => { + syntax.worker = None; + for doc in syntax.docs.values_mut() { + doc.in_flight = None; + } + break; + } + } + } +} + +/// Adds a doc for every open PHP buffer, drops docs of closed buffers +/// (their tree and outline go to `retired`) and notes version changes that +/// `buffer.edit` did not record. +fn sync_docs(state: &mut State, now: Instant, retired: &mut Vec) { + let buffers = &state.buffers; + let docs = &mut state.syntax.docs; + let gone: Vec = docs + .keys() + .copied() + .filter(|id| !buffers.get(*id).is_some_and(|b| is_php(&b.path))) + .collect(); + for id in gone { + if let Some(doc) = docs.remove(&id) { + retired.extend(doc.tree.map(|(_, tree)| Box::new(tree) as Retired)); + retired.extend(doc.outline.map(|o| Box::new(o) as Retired)); + } + } + for id in buffers.ids() { + let Some(open) = buffers.get(id) else { + continue; + }; + if !is_php(&open.path) { + continue; + } + let doc = docs.entry(id).or_insert_with(|| Doc { + seen_version: open.version, + ..Doc::default() + }); + if doc.seen_version != open.version { + doc.seen_version = open.version; + doc.changed_at = Some(now); + } + } +} + +/// Starts a parse for every buffer whose tree is behind its text and that +/// has been quiet for [`DEBOUNCE`]. +fn schedule(state: &mut State, now: Instant) { + let State { + buffers, syntax, .. + } = state; + if syntax.unavailable { + return; + } + let mut jobs = Vec::new(); + for (&id, doc) in syntax.docs.iter_mut() { + let Some(open) = buffers.get(id) else { + continue; + }; + let version = open.version; + let current = doc.tree.as_ref().map(|(v, _)| *v) == Some(version); + if current || doc.in_flight.is_some() || doc.failed == Some(version) { + continue; + } + if doc + .changed_at + .is_some_and(|at| now.saturating_duration_since(at) < DEBOUNCE) + { + continue; + } + let (base, batches) = match doc.tree.as_ref() { + Some((tree_version, tree)) => match chain(&doc.batches, *tree_version, version) { + Some(batches) => (Some(tree.clone()), batches), + None => (None, Vec::new()), + }, + None => (None, Vec::new()), + }; + doc.in_flight = Some(version); + jobs.push(Job { + id, + version, + text: open.buffer.clone(), + base, + batches, + previous: doc.outline.clone(), + }); + } + if jobs.is_empty() { + return; + } + if syntax.worker.is_none() { + match spawn() { + Ok(worker) => syntax.worker = Some(worker), + Err(Unavailable::Grammar) => { + syntax.unavailable = true; + for doc in syntax.docs.values_mut() { + doc.in_flight = None; + } + return; + } + Err(Unavailable::Thread) => { + for doc in syntax.docs.values_mut() { + doc.in_flight = None; + } + return; + } + } + } + let Some(worker) = syntax.worker.as_ref() else { + return; + }; + for job in jobs { + let id = job.id; + if worker.jobs.send(Message::Parse(job)).is_err() + && let Some(doc) = syntax.docs.get_mut(&id) + { + doc.in_flight = None; + } + } +} + +/// The batches leading from version `from` to version `to`, if the record +/// holds an unbroken chain. +fn chain(batches: &[Batch], from: u64, to: u64) -> Option>> { + let mut version = from; + let mut out = Vec::new(); + for batch in batches.iter().filter(|b| b.base >= from) { + if batch.base != version { + return None; + } + out.push(batch.edits.clone()); + version = version.saturating_add(1); + } + (version == to).then_some(out) +} + +/// Queues `outlineChanged` for buffers with a new outline whose last event +/// is at least [`MIN_EVENT_INTERVAL`] old. +fn announce(state: &mut State, now: Instant) { + let mut ids = Vec::new(); + for (&id, doc) in state.syntax.docs.iter_mut() { + let due = doc + .last_event + .is_none_or(|at| now.saturating_duration_since(at) >= MIN_EVENT_INTERVAL); + if doc.announce && due { + doc.announce = false; + doc.last_event = Some(now); + ids.push(id); + } + } + for id in ids { + state.emit(Event::OutlineChanged { id }); + } +} + +/// Why no worker could be started. +enum Unavailable { + /// The PHP grammar does not load; retrying cannot help. + Grammar, + /// The OS refused a thread; the next pump tries again. + Thread, +} + +/// Starts the parse thread with its own parser. The thread ends when the +/// job sender is dropped, i.e. with the engine. +fn spawn() -> Result { + let mut parser = Parser::new().map_err(|_| Unavailable::Grammar)?; + let (jobs, job_rx) = mpsc::channel::(); + let (done_tx, done) = mpsc::channel::(); + std::thread::Builder::new() + .name("lutra-syntax".into()) + .spawn(move || { + for message in job_rx { + match message { + Message::Parse(job) => { + if done_tx.send(work(&mut parser, job)).is_err() { + break; + } + } + Message::Retire(retired) => drop(retired), + } + } + }) + .map_err(|_| Unavailable::Thread)?; + Ok(Worker { jobs, done }) +} + +/// Runs one job on the worker, inside a panic boundary: a panic yields a +/// [`Done`] without a result instead of ending the thread. The parser is +/// replaced after a panic, since its state is unknown; if that fails the +/// old one is kept. +fn work(parser: &mut Parser, job: Job) -> Done { + let (id, version) = (job.id, job.version); + let result = + std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| parse_job(parser, job))).ok(); + if result.is_none() + && let Ok(fresh) = Parser::new() + { + *parser = fresh; + } + Done { + id, + version, + result, + } +} + +/// Parses a job's text, incrementally when its batches lead from its base +/// tree to exactly that text, builds the outline and tells whether it +/// differs from the job's previous outline. +fn parse_job(parser: &mut Parser, job: Job) -> (Tree, Outline, bool) { + let snapshot = job.text.text(); + let incremental = job.base.and_then(|mut tree| { + for batch in &job.batches { + tree = parser.reparse(&tree, batch).ok()?; + } + (tree.text().text() == snapshot).then_some(tree) + }); + let tree = incremental.unwrap_or_else(|| parser.parse(&snapshot)); + let items = lutra_syntax::outline(&tree); + let outline = Outline { + version: job.version, + items: Arc::new(Value::Array(items.iter().map(item_json).collect())), + truncated: tree.truncated(), + }; + let changed = job + .previous + .is_none_or(|p| p.truncated != outline.truncated || p.items != outline.items); + (tree, outline, changed) +} + +/// An outline item as JSON: `{kind, name, detail?, range, selectionRange, +/// children}`. +fn item_json(item: &OutlineItem) -> Value { + let mut map = Map::new(); + map.insert("kind".into(), json!(item.kind.as_str())); + map.insert("name".into(), json!(item.name)); + if let Some(detail) = &item.detail { + map.insert("detail".into(), json!(detail)); + } + map.insert("range".into(), range_json(item.range)); + map.insert("selectionRange".into(), range_json(item.selection_range)); + map.insert( + "children".into(), + Value::Array(item.children.iter().map(item_json).collect()), + ); + Value::Object(map) +} + +/// A range as `{start: {line, column}, end: {line, column}}`. +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 }, + }) +} + +/// Params of `syntax.outline`. +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct OutlineParams { + /// Buffer id. + id: BufferId, +} + +/// `syntax.outline`: the declarations of an open buffer. +pub struct OutlineCommand; + +impl Command for OutlineCommand { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "syntax.outline", + label: "File Outline", + menu_path: None, + default_shortcut: None, + params: "{ id: number }; returns { items: [{ kind, name, detail?, range, selectionRange, children }], truncated, version } from the last finished parse (version null before the first; empty for non-PHP files); kind is namespace|class|interface|trait|enum|function|method|property|constant|enumCase; ranges are { start, end } of { line, column } (0-based, UTF-16 columns); event outlineChanged { id } when it changes (at most every 200 ms per buffer)", + } + } + + 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: OutlineParams = parse(command, params)?; + let open = state + .buffers + .get(p.id) + .ok_or_else(|| EngineError::Failed(format!("{command}: no buffer {}", p.id)))?; + let outline = state + .syntax + .docs + .get(&p.id) + .and_then(|d| d.outline.as_ref()); + let value = match outline { + Some(o) => json!({ "items": *o.items, "truncated": o.truncated, "version": o.version }), + None => json!({ + "items": [], + "truncated": is_php(&open.path) && open.buffer.len_bytes() > MAX_PARSE_BYTES, + "version": Value::Null, + }), + }; + Ok(Outcome::value(value)) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use std::path::PathBuf; + + use crate::OpenBuffer; + + fn open(state: &mut State, path: &str, text: &str) -> BufferId { + state.buffers.insert(OpenBuffer { + buffer: Buffer::new(text), + path: PathBuf::from(path), + version: 0, + saved_version: 0, + bom: false, + }) + } + + fn edit(state: &mut State, id: BufferId, edits: Vec, now: Instant) { + let open = state.buffers.get_mut(id).unwrap(); + let base = open.version; + open.buffer.apply(&edits).unwrap(); + open.version += 1; + record_edits(state, id, base, edits, now); + } + + /// Pumps with a clock 50 ms apart per round until every doc's tree is + /// current and nothing waits to be announced. + fn settle(state: &mut State, mut now: Instant) -> (Vec, Instant) { + let mut events = Vec::new(); + for _ in 0..500 { + pump(state, now); + events.extend(state.take_events()); + let current = state.syntax.docs.iter().all(|(id, d)| { + let version = state.buffers.get(*id).unwrap().version; + d.tree.as_ref().map(|(v, _)| *v) == Some(version) && !d.announce + }); + if current && state.syntax.in_flight() == 0 { + return (events, now); + } + std::thread::sleep(Duration::from_millis(5)); + now += Duration::from_millis(50); + } + panic!("parse did not finish"); + } + + fn names(state: &State, id: BufferId) -> Vec { + fn walk(items: &Value, out: &mut Vec) { + for item in items.as_array().unwrap() { + out.push(item["name"].as_str().unwrap().to_string()); + walk(&item["children"], out); + } + } + let mut out = Vec::new(); + let outline = state.syntax.docs[&id].outline.as_ref().unwrap(); + walk(&outline.items, &mut out); + out + } + + #[test] + fn new_buffers_parse_at_once_and_announce() { + let mut state = State::default(); + let id = open(&mut state, "a.php", " 0 { + std::thread::sleep(Duration::from_millis(2)); + drain(&mut state, &mut Vec::new()); + } + announce(&mut state, start); + assert_eq!(state.take_events(), vec![Event::OutlineChanged { id }]); + let doc = state.syntax.docs.get_mut(&id).unwrap(); + doc.announce = true; + announce(&mut state, start + Duration::from_millis(100)); + assert!(state.take_events().is_empty()); + announce(&mut state, start + MIN_EVENT_INTERVAL); + assert_eq!(state.take_events(), vec![Event::OutlineChanged { id }]); + } + + #[test] + fn too_many_batches_fall_back_to_a_full_parse() { + let mut state = State::default(); + let id = open(&mut state, "a.php", " = lutra_syntax::outline(&tree).iter().map(item_json).collect(); + let class = &items[0]; + assert_eq!(class["kind"], "class"); + assert!(class.get("detail").is_none()); + assert_eq!(class["range"]["start"], json!({"line": 1, "column": 0})); + let method = &class["children"][0]; + assert_eq!(method["kind"], "method"); + assert_eq!(method["detail"], "(int $x): int"); + assert_eq!( + method["selectionRange"]["start"], + json!({"line": 2, "column": 18}) + ); + } + + #[test] + fn php_extensions() { + for (path, php) in [ + ("a.php", true), + ("B.PHP", true), + ("v.phtml", true), + ("c.inc", true), + ("d.js", false), + ("php", false), + ] { + assert_eq!(is_php(Path::new(path)), php, "{path}"); + } + } +} diff --git a/crates/engine/src/engine.rs b/crates/engine/src/engine.rs index 10f77bd..0cfadb3 100644 --- a/crates/engine/src/engine.rs +++ b/crates/engine/src/engine.rs @@ -132,7 +132,8 @@ impl Engine { /// changed directories and conflicts), writes due recovery-journal /// entries (see [`crate::journal`]), moves finished search results into /// events (see [`cmd::search`]), merges index updates (see - /// [`cmd::goto`]) and returns every queued event. + /// [`cmd::goto`]), stores finished parses and starts due ones (see + /// [`cmd::syntax`]) and returns every queued event. /// Hosts call it regularly, e.g. every 100 ms from a background thread. /// /// # Errors @@ -145,6 +146,7 @@ impl Engine { crate::journal::tick(state, std::time::Instant::now()); cmd::search::pump(state); cmd::goto::sync(state); + cmd::syntax::pump(state, std::time::Instant::now()); Ok(()) })?; Ok(state.take_events()) @@ -387,6 +389,7 @@ mod tests { "settings.list", "settings.reset", "settings.set", + "syntax.outline", "test.disabled", "theme.list", "theme.systemPreference", diff --git a/crates/engine/src/event.rs b/crates/engine/src/event.rs index ab41522..75ff520 100644 --- a/crates/engine/src/event.rs +++ b/crates/engine/src/event.rs @@ -187,6 +187,13 @@ pub enum Event { /// Wall time of the build in milliseconds. elapsed_ms: u64, }, + /// The outline of a buffer changed; refetch it with `syntax.outline`. + /// Sent at most every 200 ms per buffer, and once after a buffer's + /// first parse. + OutlineChanged { + /// Buffer id. + id: u64, + }, } /// One match of [`Event::SearchResults`]. Positions are 0-based; columns @@ -361,4 +368,12 @@ mod tests { json!({"kind": "recoveryResolved", "paths": ["src/a.php"]}) ); } + + #[test] + fn outline_changed_shape() { + assert_eq!( + serde_json::to_value(Event::OutlineChanged { id: 4 }).unwrap(), + json!({"kind": "outlineChanged", "id": 4}) + ); + } } diff --git a/crates/engine/src/state.rs b/crates/engine/src/state.rs index 626f5d0..503c327 100644 --- a/crates/engine/src/state.rs +++ b/crates/engine/src/state.rs @@ -39,6 +39,8 @@ pub struct State { pub searches: crate::cmd::search::Searches, /// The symbol index of the open project (`index.status`, `goto.*`). pub index: crate::cmd::goto::IndexState, + /// Syntax trees and outlines of open PHP buffers (`syntax.outline`). + pub syntax: crate::cmd::syntax::Syntax, /// Number of notifications emitted, for their ids. notifications: u64, /// Events queued for the host, oldest first. diff --git a/crates/engine/tests/syntax.proptest-regressions b/crates/engine/tests/syntax.proptest-regressions new file mode 100644 index 0000000..3a776b4 --- /dev/null +++ b/crates/engine/tests/syntax.proptest-regressions @@ -0,0 +1,7 @@ +# Seeds for failure cases proptest has generated in the past. It is +# automatically read and these particular cases re-run before any +# novel cases are generated. +# +# It is recommended to check this file in to source control so that +# everyone who runs the test benefits from these saved cases. +cc 487913cee37be422b8983c4418730212af1faa10456b87b98572ae2b7de4a9b3 # shrinks to edits = [(0.0, 0.0, "")] diff --git a/crates/engine/tests/syntax.rs b/crates/engine/tests/syntax.rs new file mode 100644 index 0000000..b522fe6 --- /dev/null +++ b/crates/engine/tests/syntax.rs @@ -0,0 +1,239 @@ +//! `syntax.outline` and `outlineChanged` through the engine: the outline +//! follows `file.open` and `buffer.edit` via the pump, random edit sequences +//! end at the outline of a fresh parse, and (ignored) timings on a 1 MB file. + +#![allow( + clippy::unwrap_used, + clippy::expect_used, + clippy::panic, + clippy::indexing_slicing +)] + +use std::fs; +use std::time::{Duration, Instant}; + +use lutra_engine::{Engine, Event}; +use proptest::prelude::*; +use serde_json::{Value, json}; +use tempfile::TempDir; + +/// A temp folder with one file, opened in a fresh engine with the file in a +/// buffer; returns the buffer id. +fn open_file(name: &str, text: &str) -> (TempDir, Engine, u64) { + let dir = tempfile::tempdir().unwrap(); + fs::write(dir.path().join(name), text).unwrap(); + let mut engine = Engine::new().unwrap(); + engine + .execute("project.open", json!({"path": dir.path()})) + .unwrap(); + let out = engine.execute("file.open", json!({"path": name})).unwrap(); + let id = out.value["id"].as_u64().unwrap(); + (dir, engine, id) +} + +/// Pumps until the outline describes `version`; returns the outline and +/// the number of `outlineChanged` events seen. +fn outline_at(engine: &mut Engine, id: u64, version: u64) -> (Value, usize) { + let deadline = Instant::now() + Duration::from_secs(20); + let mut changed = 0; + while Instant::now() < deadline { + changed += engine + .pump_vfs() + .unwrap() + .iter() + .filter(|e| **e == Event::OutlineChanged { id }) + .count(); + let out = engine.execute("syntax.outline", json!({"id": id})).unwrap(); + if out.value["version"] == version { + return (out.value, changed); + } + std::thread::sleep(Duration::from_millis(10)); + } + panic!("no outline for version {version} within 20 s"); +} + +/// Names of the items, depth first. +fn names(items: &Value) -> Vec { + let mut out = Vec::new(); + for item in items.as_array().unwrap() { + out.push(item["name"].as_str().unwrap().to_string()); + out.extend(names(&item["children"])); + } + out +} + +/// Names of a fresh parse's outline, depth first. +fn fresh_names(text: &str) -> Vec { + fn walk(items: &[lutra_syntax::OutlineItem], out: &mut Vec) { + for item in items { + out.push(item.name.clone()); + walk(&item.children, out); + } + } + let tree = lutra_syntax::Parser::new().unwrap().parse(text); + let mut out = Vec::new(); + walk(&lutra_syntax::outline(&tree), &mut out); + out +} + +#[test] +fn outline_follows_open_and_edit() { + let text = " impl Strategy { + let insert = prop_oneof![ + Just(String::new()), + Just("function f() {}\n".to_string()), + Just("class C { const X = 1; }\n".to_string()), + Just("{".to_string()), + Just("}".to_string()), + Just("\u{e4}\u{20ac}\u{1f600}".to_string()), + "[a-z$(){};\\n ]{0,12}", + ]; + (0.0..1.0f64, 0.0..0.2f64, insert) +} + +/// Whether a UTF-16 unit is a low surrogate (second half of a pair). +fn low_surrogate(unit: u16) -> bool { + (0xDC00..0xE000).contains(&unit) +} + +proptest! { + #![proptest_config(ProptestConfig::with_cases(24))] + + /// Random edits through `buffer.edit` never fail the pump and end at the + /// outline of a fresh parse of the final text whenever that text is free + /// of syntax errors (tree-sitter's recovery may differ on broken code). + #[test] + fn random_edits_end_at_a_fresh_outline(edits in proptest::collection::vec(edit_strategy(), 1..12)) { + let start = " = start.encode_utf16().collect(); + let mut version = 1u64; + for (at, len, insert) in edits { + let mut from = (at * text.len() as f64) as usize; + while from > 0 && from < text.len() && low_surrogate(text[from]) { + from -= 1; + } + let mut to = (from + (len * text.len() as f64) as usize).min(text.len()); + while to < text.len() && low_surrogate(text[to]) { + to += 1; + } + engine.execute( + "buffer.edit", + json!({"id": id, "baseVersion": version, "edits": [{"from": from, "to": to, "insert": insert}]}), + ).unwrap(); + text.splice(from..to, insert.encode_utf16()); + version += 1; + if version.is_multiple_of(3) { + engine.pump_vfs().unwrap(); + } + } + let final_text = String::from_utf16(&text).unwrap(); + let (outline, _) = outline_at(&mut engine, id, version); + let tree = lutra_syntax::Parser::new().unwrap().parse(&final_text); + if !tree.has_errors() { + prop_assert_eq!(names(&outline["items"]), fresh_names(&final_text)); + } + } +} + +/// Generated PHP of about `bytes` bytes: classes with methods and +/// properties. +fn big_php(bytes: usize) -> String { + let mut text = String::from("repo->find($id, $tags) ?? null;\n }}\n\n public function save(Product $p): void\n {{\n $this->repo->save($p);\n }}\n}}\n\n" + )); + n += 1; + } + text +} + +/// Timings on a 1 MB file: `buffer.edit` and `pump_vfs` under the engine +/// lock, and the time from an edit to its `outlineChanged` (the debounce, +/// the worker's reparse and outline, and the pump interval). Run with +/// `cargo test --release -p lutra-engine --test syntax -- --ignored --nocapture`. +#[test] +#[ignore = "timing; run in release on an idle machine"] +fn perf_one_megabyte() { + let text = big_php(1024 * 1024); + let (_dir, mut engine, id) = open_file("big.php", &text); + let started = Instant::now(); + outline_at(&mut engine, id, 1); + println!("first outline after {:?}", started.elapsed()); + let mut edit_max = Duration::ZERO; + let mut pump_max = Duration::ZERO; + let mut to_event = Vec::new(); + let at = text.len() - 2; + for version in 1..=10u64 { + let t = Instant::now(); + engine + .execute( + "buffer.edit", + json!({"id": id, "baseVersion": version, "edits": [{"from": at, "to": at, "insert": format!("function f{version}() {{}}\n")}]}), + ) + .unwrap(); + edit_max = edit_max.max(t.elapsed()); + let edited = Instant::now(); + loop { + let t = Instant::now(); + let events = engine.pump_vfs().unwrap(); + pump_max = pump_max.max(t.elapsed()); + if events.contains(&Event::OutlineChanged { id }) { + to_event.push(edited.elapsed()); + break; + } + std::thread::sleep(Duration::from_millis(5)); + } + std::thread::sleep(Duration::from_millis(200)); + } + let t = Instant::now(); + let out = engine.execute("syntax.outline", json!({"id": id})).unwrap(); + let outline_time = t.elapsed(); + let count = names(&out.value["items"]).len(); + println!("buffer.edit max {edit_max:?}, pump_vfs max {pump_max:?}"); + println!("syntax.outline {outline_time:?} for {count} items"); + println!("edit to outlineChanged: {to_event:?}"); +} diff --git a/docs/architecture.md b/docs/architecture.md index 491d238..12f99c6 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 and the symbol index · **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 and the Structure tool window · **Last updated:** 2026-10-17 ## Overview @@ -256,6 +256,13 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat - 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. +### Structure (M2.7) + +- **Engine:** `crates/engine/src/cmd/syntax.rs` keeps a syntax tree per open PHP buffer (`.php`, `.phtml`, `.inc`) in `State::syntax`. Nothing is parsed under the engine lock. `buffer.edit` records each applied batch (byte-offset `lutra_text` edits, at most 64 batches or 8 MiB of inserted text per buffer, beyond that the record is dropped). `Engine::pump_vfs` (`cmd::syntax::pump`) adds new buffers, drops closed ones, notices version changes that did not come through `buffer.edit` (reload from disk, restore), and once a buffer has been quiet for 200 ms (a new buffer at once) hands its text snapshot (a rope clone), the last tree and the recorded batches to one worker thread (`lutra-syntax`, its own `Parser`, created lazily). At most one parse per buffer is in flight. The worker reparses batch by batch, checks that the result's text equals the snapshot, otherwise parses from scratch, builds the outline as JSON and compares it with the previous one. The next pump stores tree and outline and queues `outlineChanged {id}` if the outline changed, at most once per 200 ms per buffer; the first outline is always announced. Replaced trees and outlines go back to the worker to be freed (dropping a 1 MB file's outline took 60–80 ms on the lock before). A panic in a parse is caught on the worker (the parser is recreated, that version is not retried); a vanished worker is restarted by the next pump. +- **`syntax.outline {id}`** answers from the stored outline: `{items, truncated, version}`, items `{kind, name, detail?, range, selectionRange, children}` with `{start, end}` of `{line, column}` (0-based, UTF-16). `version` is the buffer version the items describe, `null` before the first parse finished. `version` is part of the C3 contract (added by M2.7, accepted by the PM on 2026-10-17): it lets an agent or the UI tell "not parsed yet" from "no declarations"; non-PHP buffers have no items. +- **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. + ## Decisions (M0) | Question | Decision | Why | @@ -273,6 +280,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat | Date | Change | Summary | |---|---|---| +| 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` | | 2026-10-16 | minor | M2.2: highlighting by file extension (Lezer), `--lt-syntax-*` tokens and classes, `editor.reveal`, keystroke-to-highlight measurement | diff --git a/docs/gaps.md b/docs/gaps.md index d7b9858..b379a16 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); G3 M1 part done (project tree, palette, settings dialog, themes); G4 under way (tree-sitter outline and folding library, Lezer highlighting); G5 under way (search backend, Find tool window, symbol index and go-to commands); G14 English UI catalog in place · **Last updated:** 2026-10-17 +> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal); G3 M1 part done (project tree, palette, settings dialog, themes); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index and go-to commands); G14 English UI catalog in place · **Last updated:** 2026-10-17 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. @@ -9,7 +9,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t | G1 | ~~Foundation: workspace, quality gate, command registry, guard, control channel~~ closed 2026-10-14 | M0 | done (~2 h measured) | | G2 | Editor core: ~~engine buffers, save~~ (M1.3), ~~editor UI with tabs, undo, multi-caret~~ (M1.6, CodeMirror basics), ~~recovery journal~~ (M1.7), tab management (preview, pin, split, close others, reopen), conflict UI for files changed on disk, autosave option | M1 | ~16 h | | 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) | 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, semantic highlighting | M2 | ~12 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, diagnostics, definition, hover, rename via Phpactor | M3 | ~45 h | | G7 | Terminal, `lutra` CLI and MCP server | M3 | ~35 h | @@ -17,7 +17,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t | G9 | Debugger, test runner, Composer, run configurations | M5 | ~300 h | | G10 | Own indexer, type inference, inspections, refactorings | M6 | ~800 h | | G11 | Stability: crash-free operation on real projects and machines (~~recovery journal~~, M1.7) | ongoing | ~95 h | -| G12 | Performance budgets: start, open, type, search, index | ongoing | ~100 h | +| G12 | Performance budgets: start, open, type, search, index; command results without a deep copy (M2.7: `syntax.outline` holds the engine lock 82 ms on a 1 MB file because the stored JSON is copied into the result; a raw-JSON `Outcome` would avoid it) | ongoing | ~101 h | | G13 | Frameworks: Symfony, Laravel, Shopware, WordPress | M6 | ~300 h | | G14 | Localization: English and German interface: ~~English message catalog for UI strings~~ (M1.11), engine messages (`EngineError.message`) as message keys, language switch, plurals, German catalog | later | ~38 h | | G15 | Database tools, HTTP client, Docker and remote | later | ~430 h | @@ -25,7 +25,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t G2 progress: the engine text buffer landed (M1.1, `crates/text`: rope, UTF-16 and char positions, atomic edit batches, line ending policy). M1.3 added engine buffers with versions, the edit protocol, save and save all, and reloading on external changes. M1.6 added tabs and a CodeMirror 6 editor synced to engine buffers (version-based edits with resync, CRLF-aware offsets), save and save all by engine shortcuts, the Save / Don't Save / Cancel question and a notice for files changed on disk. M1.7 added the crash-recovery journal (debounced atomic entries per dirty buffer, `recovery.*` commands, restore dialog; not yet checked in the running app). M1.13 made re-opening an open file switch to its tab and keeps the folders of open files watched. Still open: tab management beyond open/close, a conflict UI (compare and merge with the disk version), autosave, editor settings (font size, soft wrap); estimate lowered to ~16 h. -G4 progress: M2.1 added the structural half in `crates/syntax`: tree-sitter PHP parse and incremental reparse, outline (namespaces, class-likes, functions, members, promoted properties, enum cases; anonymous classes marked) and folding ranges, an 8 MiB parse cap, proptests and snapshots. Not visible yet: highlighting (M2.2) and the Structure window (M2.7) are open. Finding: a full parse of 1 MB takes 364–553 ms on the dev machine (target 50 ms; reparse 7–11 ms), so parsing must stay off the engine lock and the index must parse in parallel. +G4 progress: M2.1 added the structural half in `crates/syntax`: tree-sitter PHP parse and incremental reparse, outline (namespaces, class-likes, functions, members, promoted properties, enum cases; anonymous classes marked) and folding ranges, an 8 MiB parse cap, proptests and snapshots. M2.2 made highlighting visible. M2.7 added the Structure tool window: each open PHP buffer keeps a tree-sitter tree, reparsed incrementally on a worker thread off the engine lock (200 ms debounce), `syntax.outline` and `outlineChanged`, and the outline as a tree in the left tool window with jumps through `editor.reveal`. Open in G4: semantic highlighting, folding in the editor, Structure speed search, sorting and filters. Finding: a full parse of 1 MB takes 364–553 ms on the dev machine (target 50 ms; reparse 7–11 ms), so parsing must stay off the engine lock and the index must parse in parallel. G11 progress: M1.7 added the crash-recovery journal: unsaved buffers are written atomically about 1 s after the last edit and offered back after a crash; corrupt entries are skipped with a warning. Covered by a property test (random edits, crash, restore equals the buffer) and a headless control-channel test; not yet checked by killing the running app (gaming mode). Open: journal writes run under the engine lock (8.5 ms for 1 MiB, release), two instances on one project share a journal, local history. @@ -43,6 +43,7 @@ Known smaller items from M0: | Date | Change | Summary | |---|---|---| +| 2026-10-17 | minor | G4: Structure tool window (M2.7); G12: raw-JSON command results | | 2026-10-17 | minor | G5: symbol index and go-to commands (M2.5) | | 2026-10-17 | minor | G5: Find tool window (M2.4) | | 2026-10-16 | minor | G4: Lezer highlighting and `editor.reveal` (M2.2) | diff --git a/docs/roadmap.md b/docs/roadmap.md index 6f3a63b..6cf86a4 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -8,7 +8,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 | in progress (C3: M2.2 highlighting and `editor.reveal`, M2.3 search backend, M2.4 Find tool window) | ~5 | +| M2 | Syntax and search: highlighting, structure, find in files, go to file/class/symbol | in progress (C3: M2.2 highlighting and `editor.reveal`, M2.3 search backend, M2.4 Find tool window, M2.7 Structure tool window) | ~5 | | M3 | LSP, terminal, CLI: completion, diagnostics, go to definition, hover, rename; terminal; `lutra` CLI and MCP — **MVP** | not started | ~8 | | 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 | @@ -31,6 +31,7 @@ By the raw estimates the alpha gate needs M1–M4 plus cross-platform verificati | Date | Change | Summary | |---|---|---| +| 2026-10-17 | minor | M2.7 Structure tool window | | 2026-10-17 | minor | M2.4 Find tool window | | 2026-10-16 | minor | M2 in progress: M2.2 highlighting and `editor.reveal` | | 2026-10-16 | minor | Cycle C2 review: M1 hours measured | diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md index 2d454da..a87ad69 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 go-to commands · **Last updated:** 2026-10-17 · **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 go-to commands, the Structure tool window · **Last updated:** 2026-10-17 · **Target:** PhpStorm 2026.x ## How this is measured @@ -14,7 +14,7 @@ Hours are the estimated agent wall-clock hours for one agent to reach behaviour |---|---:|---:|---|---:|---| | Editor core | 12 | 10% (est.) | semantic highlighting and a colour scheme editor, code folding, soft wrap and other editor settings, preview tab, pinned/split/reordered tabs, close others/all, reopen closed tab, tab limit, conflict UI for files changed on disk, autosave, local history, encodings other than UTF-8, large-file mode, column selection and multi-caret checked against the docs; recovery journal not yet checked in the running app (gaming mode) | ~104 (est.) | M2.2: syntax highlighting by file extension (`ui/src/components/editor/language.ts`): PHP with embedded HTML/CSS/JS through `@codemirror/lang-php` (Lezer), plus HTML, CSS, JS/TS, JSON, YAML, Markdown; spans carry `lt-syntax-*` classes coloured only by the eleven `--lt-syntax-*` tokens of both themes (Lutra's own palette, ≥ 4.5:1 on the editor background and active line, contrast test). `editor.reveal {path, line, column}` opens, activates, places the cursor (UTF-16 column, CRLF-safe) and centres it; agents reach it as a UI command. Checked in the app on Windows 11 (bundled UI, control channel): PHP with embedded HTML in dark and light, `editor.reveal` into a closed CRLF file (last line, then line 302 centred). Vitest: language per extension, classes on spans for PHP/HTML and the other languages, reveal on open and closed files, CRLF mapping, clamping, bad params. keystroke to highlight on a 1 MB PHP file 3.0–11.4 ms median (jsdom, JavaScript work only, measured, not yet in the WebView). M2.1: `crates/syntax` parses PHP with tree-sitter (incremental reparse from `lutra_text` edits) and computes folding ranges (brace blocks, arrays, comments, heredocs, `use` runs); library only, nothing visible in the editor yet, so the score is unchanged. Tests: outline/folding snapshots for five PHP 8.3 fixtures, proptests (random bytes and token soups never panic, reparse equals a fresh parse, undo round trip). 1 MB parse 364–553 ms, reparse after one keystroke 7–11 ms (release, measured, machine busy). M1.13: opening a file that is already open switches to its tab (`bufferFocused`; engine test, Vitest, control-channel test; live check pending (gaming mode)); files in folders the tree never expanded still reload or report changes on disk, because the parent directory of every open buffer stays watched (engine tests). M1.7: crash-recovery journal (`crates/engine/src/journal.rs`, `cmd/recovery.rs`): dirty buffers are written atomically to `/recovery//` about 1 s after the last edit (at least every 2 s while typing), never per keystroke; removed on save, close and discard; `recoveryAvailable` after `project.open`, `recovery.list/restore/discard`; restored buffers are dirty and keep line ending and BOM; corrupt entries are moved aside with a warning. Restore dialog (`ui/src/components/recovery/`: Restore all / selected / Discard, time, changed-on-disk hint). Tests: engine dropped mid-edit and a new engine restores the exact CRLF + BOM text, corrupt entries, removal paths, a property test of random edit sequences → crash → restore equals the buffer (`crates/engine/tests/recovery.rs`, 10 tests), the same flow headless over the control channel (`crates/control/tests/recovery.rs`), 10 Vitest tests for the dialog. 1 MiB entry write: 8.5 ms median (release, measured). Graded against `plan/phpstorm/04-recovery.md`. M1.6: tabs and a CodeMirror 6 editor in the app (`ui/src/components/editor/`, `ui/src/stores/editor.ts`): open from the project tree or engine events, activate, close by button, middle click or `Mod+W`, dirty dot, Save / Don't Save / Cancel on closing a dirty tab, `Mod+S` / `Mod+Alt+S` from engine command specs, non-blocking notice for a dirty file changed or deleted on disk; local edits go to `buffer.edit` with version-based resync, CRLF files keep `\r\n`; undo/redo, multiple selections, search and bracket matching from CodeMirror's basic setup. Vitest: a burst of 400 keystrokes with stale versions and remote edits loses none, a CRLF burst with deletions converges, store and component tests against a fake engine (`ui/tests/editor/`, 22 tests). Checked in the app on Windows 11 with `--control` and `ui.screenshot`: typing via the UI and via `buffer.edit`, save to disk, close question, middle click, disk-change notice. 1 MB file (16,385 lines): engine `file.open` 80 ms over the control channel (debug build, measured), editor state 1–6 ms and first rendered view 4–11 ms in Chromium (measured), ≈ 90 ms in total (estimated, budget 150 ms). Graded against `plan/phpstorm/03-editor-tabs.md`. `crates/text`: rope buffer, positions, edits (M1.1, unit tests + proptests). M1.3: engine buffers with versions and dirty state, `file.open`, `buffer.get`, `buffer.edit` (UTF-16 change sets, `stale_version`), `file.save`, `file.saveAll`, `buffer.close` with unsaved-changes guard, line ending and BOM kept on save, clean buffers reload on external change; 14 integration tests on temp dirs (`crates/engine/tests/workspace.rs`) | | 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 | 0% | everything a user can reach: the go-to popup (M2.6), Structure (M2.7), find usages, go to declaration, recent files, navigation history (M1.8: a command palette over commands only; M2.5: go-to backend without UI; score unchanged) | ~112 (est.) | 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`; not reachable from the UI yet (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/` | +| Navigation | 10 | 4% (est.) | the go-to popup (M2.6), 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; M2.5: go-to backend without UI) | ~108 (est.) | 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`; not reachable from the UI yet (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.) | — | | Inspections and quick-fixes | 8 | 0% | everything | ~300 (est.) | — | @@ -63,6 +63,7 @@ The project tree is the first user-visible feature (Project view 8%, estimated); | Date | Change | Summary | |---|---|---| +| 2026-10-17 | minor | M2.7: Navigation 0% → 4% (est.), Structure tool window; hours 112 → 108 | | 2026-10-17 | minor | M2.5: Navigation evidence (symbol index and go-to commands, no UI), score unchanged at 0%, hours 120 → 112 | | 2026-10-17 | minor | M2.4: Search and replace 0% → 8% (est.), Find tool window; hours 76 → 70 | | 2026-10-16 | minor | M2.2: Editor core 9% → 10% (est.), syntax highlighting and `editor.reveal` | diff --git a/docs/ui-parity.md b/docs/ui-parity.md index 58d02e1..d3c881b 100644 --- a/docs/ui-parity.md +++ b/docs/ui-parity.md @@ -1,8 +1,9 @@ # 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) · **Last updated:** 2026-10-17 +> **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), left stripe and Structure tool window (M2.7) · **Last updated:** 2026-10-17 - [ ] 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. - M1.5 (2026-10-14): left tool window with header, hide button, collapsed stripe with a show button, resizable by pointer and keyboard; editor area placeholder; status bar. Missing: stripes with several tool windows, bottom/right docking, navigation bar, layout persistence. Not checked in the running app yet (needs M1.4). - [ ] Project tool window (tree, scroll from source, file operations) - M1.5 (2026-10-14): tree of the open folder with lazy `project.children` listings, folders and PHP files with Lucide icons, ignored/excluded entries dimmed, keyboard navigation (WAI-ARIA tree: arrows, Home/End, Enter), double-click opens, refresh on `TreeChanged`, listing errors shown in the tree, empty state with Open Folder…. Vitest only, against a mocked engine. @@ -24,6 +25,7 @@ - [ ] Notifications and background task indicator - M1.12 (2026-10-16): toasts at the bottom right for engine and host notifications (corrupt settings and journal entries at startup, folder that cannot be opened, `unsaved_changes` when switching projects, file watching stopped, failed commands without their own UI): info dismissed after 5 s, warnings and errors stay until closed, close button and Escape, at most 5 visible with "+n more", `role="status"`/`role="alert"`; startup notifications are replayed when the page starts listening. Vitest (19 store and component tests); live check pending (gaming mode). Missing: a notification log / Notifications tool window, actions inside a toast, balloon grouping, "don't show again", background task indicator with progress. - [ ] Structure tool window + - 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 - [ ] Find tool window - M2.4 (2026-10-17): docked in the new bottom panel (resizable by pointer and keyboard, collapses to its header, closes; results kept while closed). Query field with case / whole word / regex toggles (`aria-pressed`), include and exclude globs, status line with counts and time, cancel, truncated hint, refused query as an alert; results grouped by file with the match highlighted, a listbox with keyboard navigation; Enter or click reveals the match. `find.open` `Mod+Alt+F`. Missing: tabs per search, grouping options, a preview pane, expand/collapse per file, rerun and next/previous occurrence buttons, context menu, export, history. @@ -34,6 +36,7 @@ | Date | Change | Summary | |---|---|---| +| 2026-10-17 | minor | Structure tool window partial, left stripe (M2.7) | | 2026-10-17 | minor | Find tool window partial, bottom panel (M2.4) | | 2026-10-16 | minor | Editor syntax highlighting partial; `editor.reveal` (M2.2) | | 2026-10-16 | patch | Palette and restore dialog: modal rule, restore dialog follows outside restores (M1.15) | diff --git a/ui/src/commands/uiCommands.ts b/ui/src/commands/uiCommands.ts index c8e3e83..2c4c88e 100644 --- a/ui/src/commands/uiCommands.ts +++ b/ui/src/commands/uiCommands.ts @@ -26,4 +26,5 @@ export const UI_COMMANDS: readonly UiCommandSpec[] = [ { id: "palette.open", labelKey: "command.palette.open", defaultShortcut: "Mod+Shift+P" }, { id: "settings.open", labelKey: "command.settings.open", defaultShortcut: "Mod+," }, { id: "view.toggleProjectTree", labelKey: "command.view.toggleProjectTree", defaultShortcut: "Mod+1" }, + { id: "view.toggleStructure", labelKey: "command.view.toggleStructure", defaultShortcut: "Mod+2" }, ]; diff --git a/ui/src/components/layout/MainLayout.vue b/ui/src/components/layout/MainLayout.vue index 7b8c503..595c04d 100644 --- a/ui/src/components/layout/MainLayout.vue +++ b/ui/src/components/layout/MainLayout.vue @@ -1,26 +1,34 @@ + + + + diff --git a/ui/src/components/structure/structure.ts b/ui/src/components/structure/structure.ts new file mode 100644 index 0000000..3081e16 --- /dev/null +++ b/ui/src/components/structure/structure.ts @@ -0,0 +1,314 @@ +/** + * The Structure tool window's state (M2.7): the outline of the active + * editor tab as a tree, which nodes are collapsed and which row is + * selected. + * + * - **Source:** `syntax.outline {id}` for the active tab's buffer. It is + * fetched again when the active tab changes and on `outlineChanged {id}` + * for that buffer (the engine sends it after the first parse and after + * edits, debounced). An answer that arrives after a newer request is + * dropped. + * - **Tree:** every node starts expanded; collapsed nodes are remembered + * per buffer by their path of names, so they stay collapsed across + * refreshes and tab switches. + * - **Untrusted input:** the outline comes from the engine; malformed items + * are dropped, nesting is capped at {@link MAX_DEPTH} and the item count + * at {@link MAX_ITEMS}. + */ +import { defineStore } from "pinia"; +import { computed, ref, shallowRef, watch, type WatchStopHandle } from "vue"; +import { onEngineEvent, run, type EngineError, type EngineEventPayload } from "../../ipc"; +import { useEditorStore } from "../../stores/editor"; + +/** Engine command that returns the outline. */ +export const OUTLINE_COMMAND = "syntax.outline"; + +/** Deepest nesting kept from the engine's outline. */ +export const MAX_DEPTH = 64; + +/** Most items kept from one outline. */ +export const MAX_ITEMS = 50_000; + +/** The kinds of outline items, as the engine names them. */ +export const OUTLINE_KINDS = [ + "namespace", + "class", + "interface", + "trait", + "enum", + "function", + "method", + "property", + "constant", + "enumCase", +] as const; + +/** Kind of an outline item. */ +export type OutlineKind = (typeof OUTLINE_KINDS)[number]; + +/** A 0-based position; the column counts UTF-16 code units. */ +export interface OutlinePosition { + /** Line. */ + line: number; + /** Column. */ + column: number; +} + +/** One declaration of the outline. */ +export interface OutlineNode { + /** What it declares. */ + kind: OutlineKind; + /** Name as written (`$id` for a property). */ + name: string; + /** Short signature, e.g. `(int $id): ?Product`; null if none. */ + detail: string | null; + /** Start of the name, where a jump lands. */ + start: OutlinePosition; + /** Nested declarations in source order. */ + children: OutlineNode[]; +} + +/** A visible row of the tree. */ +export interface StructureRow { + /** Stable key: the path of kinds and names from the root. */ + key: string; + /** Nesting depth, 0 at the top. */ + depth: number; + /** The item. */ + node: OutlineNode; + /** Whether the item has children. */ + parent: boolean; + /** Whether its children are shown. */ + expanded: boolean; +} + +/** + * Reads a position, or null if malformed. + * + * @param raw - an untrusted `{line, column}`. + */ +function toPosition(raw: unknown): OutlinePosition | null { + if (typeof raw !== "object" || raw === null) { + return null; + } + const p = raw as Record; + const ok = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v >= 0; + return ok(p.line) && ok(p.column) ? { line: p.line, column: p.column } : null; +} + +/** + * Reads the outline items of a `syntax.outline` result. + * + * @param raw - the untrusted `items` field. + * @returns the well-formed items; malformed ones are dropped with their + * children. + */ +export function toOutline(raw: unknown): OutlineNode[] { + let budget = MAX_ITEMS; + const read = (items: unknown, depth: number): OutlineNode[] => { + if (!Array.isArray(items) || depth >= MAX_DEPTH) { + return []; + } + const out: OutlineNode[] = []; + for (const item of items as unknown[]) { + if (budget <= 0) { + break; + } + if (typeof item !== "object" || item === null) { + continue; + } + const i = item as Record; + const kind = OUTLINE_KINDS.find((k) => k === i.kind); + const selection = typeof i.selectionRange === "object" && i.selectionRange !== null + ? toPosition((i.selectionRange as Record).start) + : null; + if (kind === undefined || typeof i.name !== "string" || selection === null) { + continue; + } + budget -= 1; + out.push({ + kind, + name: i.name, + detail: typeof i.detail === "string" && i.detail !== "" ? i.detail : null, + start: selection, + children: read(i.children, depth + 1), + }); + } + return out; + }; + return read(raw, 0); +} + +/** + * The visible rows of an outline. + * + * @param nodes - the outline. + * @param collapsed - keys of collapsed nodes. + */ +export function flatten(nodes: OutlineNode[], collapsed: ReadonlySet): StructureRow[] { + const rows: StructureRow[] = []; + const walk = (list: OutlineNode[], depth: number, prefix: string): void => { + const seen = new Map(); + for (const node of list) { + const base = `${prefix}/${node.kind}:${node.name}`; + const n = seen.get(base) ?? 0; + seen.set(base, n + 1); + const key = n === 0 ? base : `${base}#${String(n)}`; + const parent = node.children.length > 0; + const expanded = parent && !collapsed.has(key); + rows.push({ key, depth, node, parent, expanded }); + if (expanded) { + walk(node.children, depth + 1, key); + } + } + }; + walk(nodes, 0, ""); + return rows; +} + +/** The key of a row's parent, or null at the top. */ +export function parentKey(key: string): string | null { + const slash = key.lastIndexOf("/"); + return slash > 0 ? key.slice(0, slash) : null; +} + +/** Store of the Structure tool window. */ +export const useStructureStore = defineStore("structure", () => { + const editor = useEditorStore(); + /** Buffer whose outline is shown, null without an active tab. */ + const bufferId = ref(null); + /** The outline. */ + const items = shallowRef([]); + /** The file was too large to parse. */ + const truncated = ref(false); + /** No parse of the buffer has finished yet. */ + const pending = ref(false); + /** The last failed `syntax.outline`, null if none. */ + const error = ref(null); + /** Collapsed node keys per buffer. */ + const collapsedBy = ref(new Map>()); + /** Key of the selected row, null if none. */ + const selected = ref(null); + /** Number of the newest request; older answers are dropped. */ + let sequence = 0; + /** How many components started the store. */ + let users = 0; + /** Ends the event subscription and the tab watch. */ + let stops: (() => void)[] = []; + + /** Collapsed keys of the shown buffer. */ + const collapsed = computed>(() => + bufferId.value === null ? new Set() : (collapsedBy.value.get(bufferId.value) ?? new Set()), + ); + + /** The visible rows. */ + const rows = computed(() => flatten(items.value, collapsed.value)); + + /** Path of the shown buffer, for `editor.reveal`. */ + const path = computed(() => editor.tabs.find((tab) => tab.id === bufferId.value)?.path ?? null); + + /** + * Fetches the outline of a buffer. + * + * @param id - buffer id, or null to clear the window. + */ + async function load(id: number | null): Promise { + sequence += 1; + const mine = sequence; + if (id !== bufferId.value) { + selected.value = null; + } + bufferId.value = id; + if (id === null) { + items.value = []; + truncated.value = false; + pending.value = false; + error.value = null; + return; + } + const result = await run<{ items?: unknown; truncated?: unknown; version?: unknown }>(OUTLINE_COMMAND, { id }); + if (mine !== sequence) { + return; + } + if (!result.ok) { + error.value = result.error; + items.value = []; + return; + } + error.value = null; + items.value = toOutline(result.value.items); + truncated.value = result.value.truncated === true; + pending.value = result.value.version === null; + } + + /** + * Handles an engine event. + * + * @param event - the event. + */ + function onEvent(event: EngineEventPayload): void { + if (event.kind === "outlineChanged" && event.id === bufferId.value) { + void load(bufferId.value); + } + } + + /** Starts following the active tab and engine events; counted per user. */ + function start(): void { + users += 1; + if (users > 1) { + return; + } + const unwatch: WatchStopHandle = watch( + () => editor.activeId, + (id) => void load(id), + { immediate: true }, + ); + stops = [onEngineEvent(onEvent), unwatch]; + } + + /** Stops following once the last user stopped. */ + function stop(): void { + users = Math.max(0, users - 1); + if (users > 0) { + return; + } + for (const fn of stops) { + fn(); + } + stops = []; + } + + /** + * Expands or collapses a node. + * + * @param key - the row key. + * @param expand - true to expand, false to collapse. + */ + function setExpanded(key: string, expand: boolean): void { + const id = bufferId.value; + if (id === null) { + return; + } + const open = new Set(editor.tabs.map((tab) => tab.id)); + const next = new Map([...collapsedBy.value].filter(([buffer]) => open.has(buffer))); + const keys = new Set(next.get(id) ?? []); + if (expand) { + keys.delete(key); + } else { + keys.add(key); + } + next.set(id, keys); + collapsedBy.value = next; + } + + /** + * Selects a row. + * + * @param key - the row key, or null. + */ + function select(key: string | null): void { + selected.value = key; + } + + return { bufferId, items, truncated, pending, error, selected, rows, path, collapsed, load, start, stop, setExpanded, select }; +}); diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json index 4291517..fba0390 100644 --- a/ui/src/i18n/en.json +++ b/ui/src/i18n/en.json @@ -11,6 +11,7 @@ "command.settings.open": "Settings…", "command.unavailable": "{command} cannot run right now", "command.view.toggleProjectTree": "Show or Hide Project", + "command.view.toggleStructure": "Show or Hide Structure", "common.cancel": "Cancel", "common.close": "Close", "common.dismiss": "Dismiss", @@ -22,6 +23,7 @@ "common.toolWindow.hide": "Hide {title}", "common.toolWindow.resize": "Resize {title}", "common.toolWindow.show": "Show {title}", + "common.toolWindow.stripe": "Tool windows", "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.", @@ -101,6 +103,22 @@ "settings.ui.language.description": "Language of the interface. More languages follow.", "settings.ui.language.label": "Language", "settings.ui.language.value.en": "English", + "structure.empty.noFile": "Open a file to see its structure", + "structure.empty.none": "No declarations in this file", + "structure.empty.parsing": "Reading the file…", + "structure.empty.tooLarge": "This file is too large to show its structure", + "structure.kind.class": "Class", + "structure.kind.constant": "Constant", + "structure.kind.enum": "Enum", + "structure.kind.enumCase": "Enum case", + "structure.kind.function": "Function", + "structure.kind.interface": "Interface", + "structure.kind.method": "Method", + "structure.kind.namespace": "Namespace", + "structure.kind.property": "Property", + "structure.kind.trait": "Trait", + "structure.toolWindow.title": "Structure", + "structure.tree.label": "Declarations of the file", "theme.lutraDark": "Lutra Dark", "theme.lutraLight": "Lutra Light" } diff --git a/ui/src/ipc.ts b/ui/src/ipc.ts index 8e28289..f60542d 100644 --- a/ui/src/ipc.ts +++ b/ui/src/ipc.ts @@ -85,6 +85,11 @@ export type EngineEventPayload = cancelled: unknown; /** Wall time in milliseconds; unchecked. */ elapsedMs: unknown; + } + | { + kind: "outlineChanged"; + /** Buffer whose outline changed; unchecked, it comes from the engine. */ + id: unknown; }; /** Callback receiving engine events. */ diff --git a/ui/tests/App.test.ts b/ui/tests/App.test.ts index 0f409bc..2afff85 100644 --- a/ui/tests/App.test.ts +++ b/ui/tests/App.test.ts @@ -55,7 +55,7 @@ describe("App", () => { expect(wrapper.find("[data-test=tool-window]").exists()).toBe(true); await press({ key: "1", code: "Digit1", ctrlKey: true }); expect(wrapper.find("[data-test=tool-window]").exists()).toBe(false); - expect(wrapper.find("[data-test=tool-window-stripe]").exists()).toBe(true); + expect(wrapper.find("[data-test=left-stripe]").exists()).toBe(true); await press({ key: "1", code: "Digit1", ctrlKey: true }); expect(wrapper.find("[data-test=tool-window]").exists()).toBe(true); await press({ key: "P", code: "KeyP", ctrlKey: true, shiftKey: true }); diff --git a/ui/tests/i18n/catalog.test.ts b/ui/tests/i18n/catalog.test.ts index 06348a9..60f76c4 100644 --- a/ui/tests/i18n/catalog.test.ts +++ b/ui/tests/i18n/catalog.test.ts @@ -122,7 +122,7 @@ describe("en.json", () => { it("uses flat dotted keys of known areas with string values", () => { for (const [key, value] of Object.entries(en)) { expect(key).toMatch( - /^(app|command|project|editor|common|palette|theme|recovery|notification|settings|find)\.[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$/, + /^(app|command|project|editor|common|palette|theme|recovery|notification|settings|find|structure)\.[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$/, ); expect(typeof value).toBe("string"); expect(value.trim()).not.toBe(""); diff --git a/ui/tests/palette/CommandPalette.test.ts b/ui/tests/palette/CommandPalette.test.ts index a9c6fc9..0e43efb 100644 --- a/ui/tests/palette/CommandPalette.test.ts +++ b/ui/tests/palette/CommandPalette.test.ts @@ -266,6 +266,7 @@ describe("CommandPalette", () => { "editor.reveal", "settings.open", "view.toggleProjectTree", + "view.toggleStructure", ]); const quit = wrapper.find("[data-command='app.quit']"); expect(quit.find("[data-test=palette-shortcut]").text()).toBe("Ctrl+Q"); @@ -297,7 +298,7 @@ describe("CommandPalette", () => { const wrapper = await mountPalette(); await press(PALETTE_KEY); await press({ key: "ArrowUp" }); - expect(wrapper.find("[aria-selected=true]").attributes("data-command")).toBe("view.toggleProjectTree"); + expect(wrapper.find("[aria-selected=true]").attributes("data-command")).toBe("view.toggleStructure"); await press({ key: "ArrowDown" }); expect(wrapper.find("[aria-selected=true]").attributes("data-command")).toBe("project.close"); }); diff --git a/ui/tests/structure/StructureToolWindow.test.ts b/ui/tests/structure/StructureToolWindow.test.ts new file mode 100644 index 0000000..cfc8601 --- /dev/null +++ b/ui/tests/structure/StructureToolWindow.test.ts @@ -0,0 +1,436 @@ +/** + * Tests of the Structure tool window (M2.7): reading the engine's outline + * (malformed items dropped, depth cap), the visible rows and collapsed + * nodes, the store following the active tab and `outlineChanged` (and + * dropping stale answers), the window (empty states, icons and signatures, + * keyboard navigation, jumps through `editor.reveal`), and the left stripe + * with `view.toggleStructure` in the main layout. The engine is a fake + * behind the mocked Tauri `invoke` and `listen`. + */ +import { flushPromises, mount, type VueWrapper } from "@vue/test-utils"; +import { createPinia, setActivePinia, type Pinia } from "pinia"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const invoke = vi.hoisted(() => vi.fn()); +const listen = vi.hoisted(() => vi.fn()); +vi.mock("@tauri-apps/api/core", () => ({ invoke })); +vi.mock("@tauri-apps/api/event", () => ({ listen })); + +import { useCommandsStore } from "../../src/commands/store"; +import MainLayout from "../../src/components/layout/MainLayout.vue"; +import StructureToolWindow from "../../src/components/structure/StructureToolWindow.vue"; +import { MAX_DEPTH, flatten, parentKey, toOutline, useStructureStore } from "../../src/components/structure/structure"; +import { useEditorStore } from "../../src/stores/editor"; + +/** Every `engine_execute` call, in order. */ +let calls: { command: string; params: Record }[]; +/** Engine event callbacks of every subscription. */ +let listeners: ((event: { payload: unknown }) => void)[]; +/** The outline the fake returns per buffer id. */ +let outlines: Map; +/** Answers of `syntax.outline` held back until released, if set. */ +let held: (() => void)[] | null; +/** Pinia of the current test. */ +let pinia: Pinia; +/** Mounted components, unmounted after each test. */ +let mounted: VueWrapper[]; + +/** + * Sends an engine event to every subscription. + * + * @param payload - the event. + */ +async function emit(payload: unknown): Promise { + for (const listener of [...listeners]) { + listener({ payload }); + } + await flushPromises(); +} + +/** + * An outline item as the engine sends it. + * + * @param kind - the kind. + * @param name - the name. + * @param line - line of the name. + * @param children - nested items. + * @param detail - signature, if any. + */ +function item(kind: string, name: string, line: number, children: unknown[] = [], detail?: string): unknown { + const at = { line, column: 4 }; + return { + kind, + name, + ...(detail === undefined ? {} : { detail }), + range: { start: at, end: at }, + selectionRange: { start: at, end: { line, column: 4 + name.length } }, + children, + }; +} + +/** The outline of a small class file. */ +const SHOP = [ + item("namespace", "App", 1, [ + item("class", "Shop", 3, [ + item("property", "$items", 5, [], "array"), + item("method", "find", 7, [], "(int $id): ?Product"), + item("method", "save", 9), + ], "extends Base"), + ]), +]; + +/** + * Opens a fake tab in the editor store. + * + * @param id - buffer id. + * @param path - file path. + */ +function openTab(id: number, path: string): void { + const editor = useEditorStore(pinia); + editor.tabs.push({ id, path, name: path, dirty: false, notice: null }); + editor.activeId = id; +} + +/** The `syntax.outline` ids requested, in order. */ +function outlineRequests(): unknown[] { + return calls.filter((c) => c.command === "syntax.outline").map((c) => c.params.id); +} + +/** Names of the visible rows. */ +function rowNames(wrapper: VueWrapper): string[] { + return wrapper.findAll("[data-test=structure-row]").map((r) => r.get(".structure-tree__name").text()); +} + +/** Mounts the window with an `editor.reveal` spy. */ +async function mountStructure(): Promise<{ wrapper: VueWrapper; reveals: unknown[] }> { + const reveals: unknown[] = []; + useCommandsStore(pinia).provide("editor.reveal", { run: (params) => void reveals.push(params) }); + const wrapper = mount(StructureToolWindow, { attachTo: document.body, global: { plugins: [pinia] } }); + mounted.push(wrapper); + await flushPromises(); + return { wrapper, reveals }; +} + +/** + * Presses a key on the tree. + * + * @param wrapper - the window. + * @param key - the key. + */ +async function key(wrapper: VueWrapper, key: string): Promise { + await wrapper.get("[data-test=structure-tree]").trigger("keydown", { key }); +} + +beforeEach(() => { + pinia = createPinia(); + setActivePinia(pinia); + calls = []; + listeners = []; + outlines = new Map(); + held = null; + mounted = []; + Element.prototype.scrollIntoView = () => undefined; + invoke.mockReset(); + listen.mockReset(); + listen.mockImplementation((_name: string, callback: (event: { payload: unknown }) => void) => { + listeners.push(callback); + return Promise.resolve(() => { + listeners = listeners.filter((l) => l !== callback); + }); + }); + invoke.mockImplementation((cmd: string, args?: { command: string; params: Record }) => { + if (cmd === "engine_list_commands") { + return Promise.resolve([]); + } + if (cmd !== "engine_execute" || !args) { + return Promise.resolve(null); + } + calls.push({ command: args.command, params: args.params }); + if (args.command === "syntax.outline") { + const id = args.params.id as number; + const answer = (): unknown => { + const items = outlines.get(id); + if (items === "fail") { + return Promise.reject(Object.assign(new Error("failed"), { code: "failed", message: "no buffer" })); + } + return { items: items ?? [], truncated: id === 99, version: items === undefined ? null : 1 }; + }; + if (held) { + const queue = held; + return new Promise((resolve) => { + queue.push(() => { + resolve(answer()); + }); + }); + } + return Promise.resolve(answer()); + } + return Promise.resolve(null); + }); +}); + +afterEach(() => { + for (const wrapper of mounted) { + wrapper.unmount(); + } +}); + +describe("outline parsing", () => { + it("keeps well-formed items and drops malformed ones", () => { + const nodes = toOutline([ + item("class", "A", 0, [item("method", "m", 1, [], "(): void"), { kind: "method", name: 3 }]), + item("lambda", "x", 2), + { kind: "function", name: "f", selectionRange: { start: { line: -1, column: 0 } } }, + null, + "class", + ]); + expect(nodes).toEqual([ + { + kind: "class", + name: "A", + detail: null, + start: { line: 0, column: 4 }, + children: [{ kind: "method", name: "m", detail: "(): void", start: { line: 1, column: 4 }, children: [] }], + }, + ]); + expect(toOutline({ items: [] })).toEqual([]); + }); + + it("caps the nesting depth", () => { + let deep: unknown = item("function", "leaf", 0); + for (let i = 0; i < MAX_DEPTH + 10; i += 1) { + deep = item("class", `C${String(i)}`, 0, [deep]); + } + let depth = 0; + let nodes = toOutline([deep]); + while (nodes[0]) { + depth += 1; + nodes = nodes[0].children; + } + expect(depth).toBe(MAX_DEPTH); + }); + + it("flattens with collapsed nodes and unique keys", () => { + const nodes = toOutline([item("class", "A", 0, [item("method", "m", 1), item("method", "m", 2)]), item("class", "B", 3)]); + const rows = flatten(nodes, new Set()); + expect(rows.map((r) => [r.key, r.depth, r.parent, r.expanded])).toEqual([ + ["/class:A", 0, true, true], + ["/class:A/method:m", 1, false, false], + ["/class:A/method:m#1", 1, false, false], + ["/class:B", 0, false, false], + ]); + expect(flatten(nodes, new Set(["/class:A"])).map((r) => r.key)).toEqual(["/class:A", "/class:B"]); + expect(parentKey("/class:A/method:m")).toBe("/class:A"); + expect(parentKey("/class:A")).toBeNull(); + }); +}); + +describe("structure store", () => { + it("follows the active tab and outlineChanged of that buffer only", async () => { + outlines.set(3, SHOP); + outlines.set(4, [item("function", "helper", 0)]); + const store = useStructureStore(pinia); + store.start(); + await flushPromises(); + expect(outlineRequests()).toEqual([]); + openTab(3, "src/Shop.php"); + await flushPromises(); + expect(store.items.map((n) => n.name)).toEqual(["App"]); + openTab(4, "src/helpers.php"); + await flushPromises(); + expect(store.items.map((n) => n.name)).toEqual(["helper"]); + await emit({ kind: "outlineChanged", id: 3 }); + expect(outlineRequests()).toEqual([3, 4]); + outlines.set(4, [item("function", "helper2", 0)]); + await emit({ kind: "outlineChanged", id: 4 }); + expect(outlineRequests()).toEqual([3, 4, 4]); + expect(store.items.map((n) => n.name)).toEqual(["helper2"]); + store.stop(); + await emit({ kind: "outlineChanged", id: 4 }); + expect(outlineRequests()).toEqual([3, 4, 4]); + }); + + it("drops an answer overtaken by a newer request", async () => { + outlines.set(3, SHOP); + outlines.set(4, [item("function", "helper", 0)]); + const store = useStructureStore(pinia); + store.start(); + held = []; + const queue = held; + openTab(3, "a.php"); + await flushPromises(); + openTab(4, "b.php"); + await flushPromises(); + const [first, second] = queue; + second?.(); + await flushPromises(); + first?.(); + await flushPromises(); + expect(store.items.map((n) => n.name)).toEqual(["helper"]); + store.stop(); + }); + + it("keeps collapsed nodes per buffer across refreshes", async () => { + outlines.set(3, SHOP); + outlines.set(4, SHOP); + const store = useStructureStore(pinia); + store.start(); + openTab(3, "a.php"); + await flushPromises(); + store.setExpanded("/namespace:App/class:Shop", false); + expect(store.rows.map((r) => r.node.name)).toEqual(["App", "Shop"]); + await emit({ kind: "outlineChanged", id: 3 }); + expect(store.rows.map((r) => r.node.name)).toEqual(["App", "Shop"]); + openTab(4, "b.php"); + await flushPromises(); + expect(store.rows).toHaveLength(5); + useEditorStore(pinia).activeId = 3; + await flushPromises(); + expect(store.rows).toHaveLength(2); + store.stop(); + }); +}); + +describe("Structure tool window", () => { + it("says when no file is open, a file has no declarations, is being read or is too large", async () => { + const { wrapper } = await mountStructure(); + expect(wrapper.get("[data-test=structure-empty]").text()).toBe("Open a file to see its structure"); + openTab(5, "pending.php"); + await flushPromises(); + expect(wrapper.get("[data-test=structure-empty]").text()).toBe("Reading the file…"); + outlines.set(6, []); + openTab(6, "empty.php"); + await flushPromises(); + expect(wrapper.get("[data-test=structure-empty]").text()).toBe("No declarations in this file"); + openTab(99, "huge.php"); + await flushPromises(); + expect(wrapper.get("[data-test=structure-empty]").text()).toBe("This file is too large to show its structure"); + outlines.set(7, "fail"); + openTab(7, "gone.php"); + await flushPromises(); + expect(wrapper.get("[data-test=structure-error]").text()).toBe("no buffer"); + }); + + it("shows the tree with kind icons and signatures, and updates on outlineChanged", async () => { + outlines.set(3, SHOP); + openTab(3, "src/Shop.php"); + const { wrapper } = await mountStructure(); + expect(rowNames(wrapper)).toEqual(["App", "Shop", "$items", "find", "save"]); + const rows = wrapper.findAll("[data-test=structure-row]"); + expect(rows.map((r) => r.attributes("data-kind"))).toEqual(["namespace", "class", "property", "method", "method"]); + expect(rows.map((r) => r.attributes("aria-level"))).toEqual(["1", "2", "3", "3", "3"]); + expect(rows[3]?.get(".structure-tree__detail").text()).toBe("(int $id): ?Product"); + expect(rows[3]?.get(".structure-tree__icon").attributes("title")).toBe("Method"); + expect(rows[3]?.find("svg").exists()).toBe(true); + expect(rows[1]?.attributes("aria-expanded")).toBe("true"); + expect(rows[2]?.attributes("aria-expanded")).toBeUndefined(); + outlines.set(3, [item("class", "Shop", 3, [item("method", "find", 7)])]); + await emit({ kind: "outlineChanged", id: 3 }); + expect(rowNames(wrapper)).toEqual(["Shop", "find"]); + }); + + it("jumps to a declaration on click, the chevron only folds", async () => { + outlines.set(3, SHOP); + openTab(3, "src/Shop.php"); + const { wrapper, reveals } = await mountStructure(); + await wrapper.findAll("[data-test=structure-row]")[3]?.trigger("click"); + await flushPromises(); + expect(reveals).toEqual([{ path: "src/Shop.php", line: 7, column: 4 }]); + expect(wrapper.findAll("[data-test=structure-row]")[3]?.attributes("aria-selected")).toBe("true"); + await wrapper.findAll("[data-test=structure-chevron]")[1]?.trigger("click"); + await flushPromises(); + expect(rowNames(wrapper)).toEqual(["App", "Shop"]); + expect(reveals).toHaveLength(1); + }); + + it("walks, folds and jumps with the keyboard", async () => { + outlines.set(3, SHOP); + openTab(3, "src/Shop.php"); + const { wrapper, reveals } = await mountStructure(); + const tree = wrapper.get("[data-test=structure-tree]"); + await tree.trigger("focus"); + const selected = (): string | undefined => + wrapper.find("[data-test=structure-row][aria-selected=true] .structure-tree__name").text(); + expect(selected()).toBe("App"); + expect(tree.attributes("aria-activedescendant")).toBe(wrapper.findAll("[data-test=structure-row]")[0]?.attributes("id")); + await key(wrapper, "ArrowRight"); + expect(selected()).toBe("Shop"); + await key(wrapper, "ArrowLeft"); + expect(rowNames(wrapper)).toEqual(["App", "Shop"]); + await key(wrapper, "ArrowRight"); + expect(rowNames(wrapper)).toHaveLength(5); + await key(wrapper, "End"); + expect(selected()).toBe("save"); + await key(wrapper, "ArrowUp"); + await key(wrapper, "Enter"); + await flushPromises(); + expect(reveals).toEqual([{ path: "src/Shop.php", line: 7, column: 4 }]); + await key(wrapper, "ArrowLeft"); + expect(selected()).toBe("Shop"); + await key(wrapper, "Home"); + expect(selected()).toBe("App"); + await key(wrapper, "ArrowDown"); + expect(selected()).toBe("Shop"); + }); +}); + +describe("left stripe and view.toggleStructure", () => { + /** Mounts the main layout with the commands store started. */ + async function mountLayout(): Promise { + const wrapper = mount(MainLayout, { + attachTo: document.body, + global: { plugins: [pinia], stubs: { ProjectToolWindow: true, StatusBar: true } }, + }); + mounted.push(wrapper); + await useCommandsStore(pinia).start(); + await flushPromises(); + return wrapper; + } + + /** The title of the left tool window, or null when it is hidden. */ + function leftTitle(wrapper: VueWrapper): string | null { + const window = wrapper.find("[data-test=tool-window]"); + return window.exists() ? window.get(".tool-window__title").text() : null; + } + + it("is registered with its own shortcut", async () => { + await mountLayout(); + const registered = calls.find((c) => c.command === "ui.registerCommands")?.params.commands as { + id: string; + defaultShortcut?: string; + }[]; + expect(registered.find((c) => c.id === "view.toggleStructure")?.defaultShortcut).toBe("Mod+2"); + }); + + it("switches between Project and Structure from the stripe and hides the shown one", async () => { + const wrapper = await mountLayout(); + const tabs = wrapper.findAll("[role=tab]"); + expect(tabs.map((tab) => tab.attributes("aria-label"))).toEqual(["Project", "Structure"]); + expect(tabs.map((tab) => tab.attributes("aria-selected"))).toEqual(["true", "false"]); + expect(leftTitle(wrapper)).toBe("Project"); + await wrapper.get("[data-test=stripe-structure]").trigger("click"); + expect(leftTitle(wrapper)).toBe("Structure"); + expect(wrapper.get("[data-test=structure-empty]").isVisible()).toBe(true); + await wrapper.get("[data-test=stripe-structure]").trigger("click"); + expect(leftTitle(wrapper)).toBeNull(); + expect(wrapper.findAll("[role=tab]").map((tab) => tab.attributes("aria-selected"))).toEqual(["false", "false"]); + await wrapper.get("[data-test=stripe-project]").trigger("click"); + expect(leftTitle(wrapper)).toBe("Project"); + }); + + it("toggles Structure from the shortcut and from an agent's uiCommand", async () => { + outlines.set(3, SHOP); + openTab(3, "src/Shop.php"); + const wrapper = await mountLayout(); + window.dispatchEvent(new KeyboardEvent("keydown", { key: "2", code: "Digit2", ctrlKey: true, bubbles: true })); + await flushPromises(); + expect(leftTitle(wrapper)).toBe("Structure"); + expect(rowNames(wrapper)).toEqual(["App", "Shop", "$items", "find", "save"]); + await emit({ kind: "uiCommand", id: "view.toggleStructure", params: {} }); + expect(leftTitle(wrapper)).toBeNull(); + await emit({ kind: "uiCommand", id: "view.toggleStructure", params: {} }); + expect(leftTitle(wrapper)).toBe("Structure"); + await emit({ kind: "uiCommand", id: "view.toggleProjectTree", params: {} }); + expect(leftTitle(wrapper)).toBe("Project"); + }); +});