Lutra/crates/engine/tests/syntax.rs
danny c68932c39c 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>
2026-10-17 17:04:12 +02:00

239 lines
8.8 KiB
Rust

//! `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<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
}
/// Names of a fresh parse's outline, depth first.
fn fresh_names(text: &str) -> Vec<String> {
fn walk(items: &[lutra_syntax::OutlineItem], out: &mut Vec<String>) {
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 = "<?php\nfunction a() {}\n";
let (_dir, mut engine, id) = open_file("a.php", text);
let first = engine.execute("syntax.outline", json!({"id": id})).unwrap();
assert_eq!(
first.value,
json!({"items": [], "truncated": false, "version": null})
);
let (outline, changed) = outline_at(&mut engine, id, 1);
assert_eq!(names(&outline["items"]), ["a"]);
assert_eq!(changed, 1);
let edit = engine
.execute(
"buffer.edit",
json!({"id": id, "baseVersion": 1, "edits": [{"from": 6, "to": 6, "insert": "function b() {}\n"}]}),
)
.unwrap();
assert!(
!edit
.events
.iter()
.any(|e| matches!(e, Event::OutlineChanged { .. })),
"outlines only come from the pump"
);
let (outline, _) = outline_at(&mut engine, id, 2);
assert_eq!(names(&outline["items"]), ["b", "a"]);
engine
.execute("buffer.close", json!({"id": id, "force": true}))
.unwrap();
assert!(engine.pump_vfs().unwrap().is_empty());
assert_eq!(
engine
.execute("syntax.outline", json!({"id": id}))
.unwrap_err()
.code(),
"failed"
);
}
/// One random edit: a position and a length as fractions of the text, and
/// what to insert.
fn edit_strategy() -> impl Strategy<Value = (f64, f64, String)> {
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 = "<?php\nnamespace N;\nclass A {\n function m() {}\n}\n";
let (_dir, mut engine, id) = open_file("a.php", start);
outline_at(&mut engine, id, 1);
let mut text: Vec<u16> = 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("<?php\nnamespace App\\Big;\n\n");
let mut n = 0;
while text.len() < bytes {
text.push_str(&format!(
"class C{n} extends Base implements I\n{{\n private ?string $name = null;\n public const LIMIT = {n};\n\n public function find(int $id, string ...$tags): ?Product\n {{\n return $this->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:?}");
}