M2.5: symbol index and go-to commands

crates/index: walks the project with the search/VFS rules (vendor as
library), parses .php files from tree-sitter outlines on a worker pool
off the engine lock, updates incrementally from disk and buffers through
an updater thread, caps at 200,000 files, and answers fuzzy file, class
and symbol queries (nucleo-matcher, MPL-2.0 as a separate crate).

Engine: index.status, goto.file, goto.class, goto.symbol; events
indexProgress and indexReady drained by the pump; the index starts on
project.open and is cancelled on close. Tests: unit, incremental,
property (random queries and sources), engine and TCP control tests,
release timing on a generated 20k-file project (3.9-4.2 s).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-17 12:53:33 +02:00
parent f13a49064d
commit 053441d066
26 changed files with 3455 additions and 9 deletions

336
crates/engine/tests/goto.rs Normal file
View file

@ -0,0 +1,336 @@
//! The symbol index in the engine: `index.status`, the go-to commands,
//! progress and readiness events, and incremental updates from disk and
//! buffers.
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::panic,
clippy::indexing_slicing
)]
use std::fs;
use std::path::Path;
use std::time::{Duration, Instant};
use lutra_engine::{Engine, Event};
use proptest::prelude::*;
use serde_json::{Value, json};
use tempfile::TempDir;
fn write(root: &Path, rel: &str, text: &str) {
let abs = root.join(rel);
fs::create_dir_all(abs.parent().unwrap()).unwrap();
fs::write(abs, text).unwrap();
}
/// A temp folder with `files`, opened in a fresh engine.
fn open_project(files: &[(&str, &str)]) -> (TempDir, Engine) {
let dir = tempfile::tempdir().unwrap();
for (path, text) in files {
write(dir.path(), path, text);
}
let mut engine = Engine::new().unwrap();
engine
.execute("project.open", json!({"path": dir.path()}))
.unwrap();
(dir, engine)
}
fn run(engine: &mut Engine, command: &str, params: Value) -> Value {
engine.execute(command, params).unwrap().value
}
/// Pumps until `indexReady`; returns every event seen.
fn until_ready(engine: &mut Engine) -> Vec<Event> {
let deadline = Instant::now() + Duration::from_secs(30);
let mut seen = Vec::new();
while Instant::now() < deadline {
let events = engine.pump_vfs().unwrap();
let ready = events.iter().any(|e| matches!(e, Event::IndexReady { .. }));
seen.extend(events);
if ready {
return seen;
}
std::thread::sleep(Duration::from_millis(10));
}
panic!("no indexReady within 30 s");
}
/// Pumps until `query` with `command` gives `count` items.
fn until_count(engine: &mut Engine, command: &str, query: &str, count: usize) -> Value {
let deadline = Instant::now() + Duration::from_secs(10);
loop {
engine.pump_vfs().unwrap();
let out = run(engine, command, json!({"query": query}));
if out["items"].as_array().unwrap().len() == count {
return out;
}
assert!(
Instant::now() < deadline,
"{command} {query}: wanted {count} items, got {out}"
);
std::thread::sleep(Duration::from_millis(20));
}
}
fn names(out: &Value, field: &str) -> Vec<String> {
out["items"]
.as_array()
.unwrap()
.iter()
.map(|i| i[field].as_str().unwrap().to_string())
.collect()
}
#[test]
fn commands_need_a_project_and_status_is_idle_without_one() {
let mut engine = Engine::new().unwrap();
assert_eq!(
run(&mut engine, "index.status", Value::Null),
json!({"state": "idle", "files": 0, "symbols": 0})
);
for command in ["goto.file", "goto.class", "goto.symbol"] {
let err = engine.execute(command, json!({"query": "a"})).unwrap_err();
assert_eq!(err.code(), "disabled");
}
}
#[test]
fn builds_in_the_background_and_answers_go_to_queries() {
let (_dir, mut engine) = open_project(&[
(".gitignore", "/var/\n/vendor/\n"),
(
"src/Models/User.php",
"<?php\nnamespace App\\Models;\n\nfinal class User\n{\n public const ROLE = 'user';\n private ?string $email = null;\n public function find(int $id): ?self { return null; }\n}\n",
),
(
"src/helpers.php",
"<?php\nfunction format_user(): string { return ''; }\n",
),
("templates/user.html.twig", "{{ user }}"),
("var/cache/UserCache.php", "<?php class UserCache {}"),
(
"vendor/acme/lib/User.php",
"<?php\nnamespace Acme;\n\ninterface User { public function find(); }\n",
),
]);
let events = until_ready(&mut engine);
let ready = events
.iter()
.find_map(|e| match e {
Event::IndexReady { files, symbols, .. } => Some((*files, *symbols)),
_ => None,
})
.unwrap();
assert_eq!(ready, (5, 7));
assert_eq!(
run(&mut engine, "index.status", Value::Null),
json!({"state": "idle", "files": 5, "symbols": 7})
);
let files = run(&mut engine, "goto.file", json!({"query": "user"}));
assert_eq!(files["indexing"], false);
assert_eq!(
names(&files, "path"),
vec![
"src/Models/User.php",
"templates/user.html.twig",
"vendor/acme/lib/User.php",
]
);
assert_eq!(files["items"][0]["matches"], json!([[11, 15]]));
assert!(files["items"][0]["score"].as_u64().unwrap() > 0);
let classes = run(&mut engine, "goto.class", json!({"query": "user"}));
assert_eq!(
classes["items"],
json!([
{"name": "User", "fqn": "App\\Models\\User", "kind": "class", "path": "src/Models/User.php", "line": 3, "column": 12, "library": false},
{"name": "User", "fqn": "Acme\\User", "kind": "interface", "path": "vendor/acme/lib/User.php", "line": 3, "column": 10, "library": true},
])
);
let symbols = run(
&mut engine,
"goto.symbol",
json!({"query": "find", "limit": 1}),
);
assert_eq!(
symbols["items"],
json!([{"name": "find", "fqn": "App\\Models\\User::find", "kind": "method", "container": "App\\Models\\User", "path": "src/Models/User.php", "line": 7, "column": 20, "library": false}])
);
let function = run(&mut engine, "goto.symbol", json!({"query": "format_user"}));
assert_eq!(function["items"][0]["container"], Value::Null);
let members = run(&mut engine, "goto.symbol", json!({"query": "User::"}));
assert_eq!(
names(&members, "name"),
vec!["ROLE", "find", "$email", "find"]
);
let empty = run(&mut engine, "goto.class", json!({"query": ""}));
assert_eq!(empty["items"], json!([]));
for bad in [
json!({}),
json!({"query": 3}),
json!({"query": "a", "limit": -1}),
json!({"query": "a", "extra": true}),
] {
let err = engine.execute("goto.file", bad).unwrap_err();
assert_eq!(err.code(), "invalid_params");
}
}
#[test]
fn reports_progress_and_partial_results_while_indexing() {
let dir = tempfile::tempdir().unwrap();
let project = lutra_testkit::generate_php_project(dir.path(), 3_000);
let mut engine = Engine::new().unwrap();
engine
.execute("project.open", json!({"path": dir.path()}))
.unwrap();
let status = run(&mut engine, "index.status", Value::Null);
assert_eq!(status["state"], "indexing");
let early = run(&mut engine, "goto.class", json!({"query": "Service"}));
assert_eq!(early["indexing"], true);
let events = until_ready(&mut engine);
let progress: Vec<(usize, usize)> = events
.iter()
.filter_map(|e| match e {
Event::IndexProgress { done, total } => Some((*done, *total)),
_ => None,
})
.collect();
assert!(
progress
.iter()
.all(|(_, total)| *total == project.indexed_files)
);
assert!(progress.windows(2).all(|w| w[0].0 <= w[1].0));
let status = run(&mut engine, "index.status", Value::Null);
assert_eq!(status["state"], "idle");
assert_eq!(status["files"], project.indexed_files);
let classes = run(
&mut engine,
"goto.class",
json!({"query": "Service1", "limit": 1000}),
);
assert_eq!(classes["indexing"], false);
assert!(!classes["items"].as_array().unwrap().is_empty());
}
#[test]
fn follows_buffers_and_disk_changes() {
let (dir, mut engine) = open_project(&[("src/A.php", "<?php class Alpha {}")]);
until_ready(&mut engine);
run(&mut engine, "project.children", json!({"dir": "src"}));
let opened = run(&mut engine, "file.open", json!({"path": "src/A.php"}));
let id = opened["id"].as_u64().unwrap();
let version = opened["version"].as_u64().unwrap();
run(
&mut engine,
"buffer.edit",
json!({"id": id, "baseVersion": version, "edits": [{"from": 12, "to": 17, "insert": "Omega"}]}),
);
until_count(&mut engine, "goto.class", "Omega", 1);
until_count(&mut engine, "goto.class", "Alpha", 0);
write(dir.path(), "src/A.php", "<?php class Disk {}");
std::thread::sleep(Duration::from_millis(300));
for _ in 0..10 {
engine.pump_vfs().unwrap();
}
assert_eq!(
names(
&run(&mut engine, "goto.class", json!({"query": "Omega"})),
"name"
),
vec!["Omega"],
"the unsaved buffer wins over the disk"
);
run(
&mut engine,
"buffer.close",
json!({"id": id, "force": true}),
);
until_count(&mut engine, "goto.class", "Disk", 1);
until_count(&mut engine, "goto.class", "Omega", 0);
write(dir.path(), "src/B.php", "<?php class Beta {}");
until_count(&mut engine, "goto.class", "Beta", 1);
fs::remove_file(dir.path().join("src/B.php")).unwrap();
until_count(&mut engine, "goto.class", "Beta", 0);
until_count(&mut engine, "goto.file", "B.php", 0);
}
#[test]
fn closing_the_project_drops_the_index() {
let dir = tempfile::tempdir().unwrap();
lutra_testkit::generate_php_project(dir.path(), 2_000);
let mut engine = Engine::new().unwrap();
engine
.execute("project.open", json!({"path": dir.path()}))
.unwrap();
assert_eq!(
run(&mut engine, "index.status", Value::Null)["state"],
"indexing"
);
run(&mut engine, "project.close", json!({}));
assert_eq!(
run(&mut engine, "index.status", Value::Null),
json!({"state": "idle", "files": 0, "symbols": 0})
);
for _ in 0..5 {
let events = engine.pump_vfs().unwrap();
assert!(
!events
.iter()
.any(|e| matches!(e, Event::IndexProgress { .. } | Event::IndexReady { .. }))
);
}
let (other, mut engine2) = open_project(&[("a.php", "<?php class First {}")]);
until_ready(&mut engine2);
let second = tempfile::tempdir().unwrap();
write(second.path(), "b.php", "<?php class Second {}");
engine2
.execute(
"project.open",
json!({"path": second.path(), "force": true}),
)
.unwrap();
until_ready(&mut engine2);
assert!(
run(&mut engine2, "goto.class", json!({"query": "First"}))["items"]
.as_array()
.unwrap()
.is_empty()
);
assert_eq!(
run(&mut engine2, "goto.class", json!({"query": "Second"}))["items"]
.as_array()
.unwrap()
.len(),
1
);
drop(other);
}
proptest! {
#![proptest_config(ProptestConfig::with_cases(64))]
#[test]
fn random_go_to_params_never_panic(query in "\\PC{0,64}", limit in proptest::option::of(0usize..5_000)) {
let (_dir, mut engine) = open_project(&[("src/A.php", "<?php namespace N; class Alpha { function go() {} }")]);
for command in ["goto.file", "goto.class", "goto.symbol"] {
let mut params = json!({"query": query});
if let Some(limit) = limit {
params["limit"] = json!(limit);
}
let out = engine.execute(command, params).unwrap().value;
let items = out["items"].as_array().unwrap();
prop_assert!(items.len() <= limit.unwrap_or(50).min(1_000));
}
}
}