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 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-17 13:31:37 +02:00
parent 73819df926
commit c68932c39c
27 changed files with 2596 additions and 28 deletions

View file

@ -0,0 +1,170 @@
//! The outline over a real TCP control connection: `syntax.outline` after
//! `file.open`, `outlineChanged` from the pump after the first parse and
//! after a `buffer.edit` that changes the declarations.
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::indexing_slicing,
clippy::panic
)]
use std::io::{BufRead, BufReader, Write};
use std::net::TcpStream;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::time::Duration;
use lutra_testkit::EngineBackend;
use serde_json::{Value, json};
/// A client that keeps responses and event lines apart.
struct Client {
reader: BufReader<TcpStream>,
writer: TcpStream,
events: Vec<Value>,
}
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<AtomicBool>);
impl Pump {
fn start(backend: Arc<EngineBackend>) -> 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<String> {
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 = "<?php\nnamespace App;\n\nclass Shop\n{\n public function find(int $id): ?Product {}\n}\n";
std::fs::write(dir.path().join("Shop.php"), source).unwrap();
std::fs::write(dir.path().join("notes.txt"), "class Nope {}").unwrap();
let backend = Arc::new(EngineBackend::new());
let server = lutra_control::start(0, backend.clone()).unwrap();
let mut client = Client::connect(server.local_addr());
client.call(json!({"id": 1, "method": "events.subscribe"}));
client.call(execute("project.open", json!({"path": dir.path()})));
let r = client.call(execute("file.open", json!({"path": "Shop.php"})));
let id = r["result"]["id"].as_u64().unwrap();
let r = client.call(execute("syntax.outline", json!({"id": id})));
assert_eq!(r["result"]["version"], Value::Null, "{r}");
let _pump = Pump::start(backend.clone());
client.outline_changed(id);
let r = client.call(execute("syntax.outline", json!({"id": id})));
let outline = &r["result"];
assert_eq!(outline["truncated"], false);
assert_eq!(outline["version"], 1);
assert_eq!(names(&outline["items"]), ["App", "Shop", "find"]);
let method = &outline["items"][0]["children"][0]["children"][0];
assert_eq!(method["kind"], "method");
assert_eq!(method["detail"], "(int $id): ?Product");
assert_eq!(
method["selectionRange"]["start"],
json!({"line": 5, "column": 20})
);
let at = source.find("\n}").unwrap() + 1;
let r = client.call(execute(
"buffer.edit",
json!({"id": id, "baseVersion": 1, "edits": [{"from": at, "to": at, "insert": " const LIMIT = 10;\n"}]}),
));
assert_eq!(r["result"]["version"], 2, "{r}");
client.outline_changed(id);
let r = client.call(execute("syntax.outline", json!({"id": id})));
assert_eq!(r["result"]["version"], 2);
assert_eq!(
names(&r["result"]["items"]),
["App", "Shop", "find", "LIMIT"]
);
let r = client.call(execute("file.open", json!({"path": "notes.txt"})));
let txt = r["result"]["id"].as_u64().unwrap();
let r = client.call(execute("syntax.outline", json!({"id": txt})));
assert_eq!(r["result"]["items"], json!([]));
let r = client.call(execute("syntax.outline", json!({"id": 999})));
assert_eq!(r["error"]["code"], "failed", "{r}");
let r = client.call(execute("syntax.outline", json!({"id": id, "x": 1})));
assert_eq!(r["error"]["code"], "invalid_params", "{r}");
}