Lutra/crates/index/src/symbol.rs
danny 053441d066 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>
2026-10-17 12:53:33 +02:00

313 lines
11 KiB
Rust

//! Symbols and indexed files, extracted from tree-sitter outlines.
use lutra_syntax::{OutlineItem, OutlineKind, Parser};
use crate::{MAX_PARSE_BYTES, MAX_SYMBOLS_PER_FILE};
/// What a symbol declares.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SymbolKind {
/// A class.
Class,
/// An interface.
Interface,
/// A trait.
Trait,
/// An enum.
Enum,
/// A function outside a class.
Function,
/// A method.
Method,
/// A property, declared or constructor-promoted.
Property,
/// A class constant or a `const` outside a class.
Constant,
/// A `case` of an enum.
EnumCase,
}
impl SymbolKind {
/// The kind's name as the engine and the UI use it, the same as the
/// outline's: `class`, `interface`, `trait`, `enum`, `function`,
/// `method`, `property`, `constant` or `enumCase`.
pub fn as_str(self) -> &'static str {
match self {
Self::Class => "class",
Self::Interface => "interface",
Self::Trait => "trait",
Self::Enum => "enum",
Self::Function => "function",
Self::Method => "method",
Self::Property => "property",
Self::Constant => "constant",
Self::EnumCase => "enumCase",
}
}
/// Whether the kind is a class, interface, trait or enum (Go to Class);
/// the others are found by Go to Symbol.
pub fn is_class_like(self) -> bool {
matches!(
self,
Self::Class | Self::Interface | Self::Trait | Self::Enum
)
}
/// The symbol kind of an outline kind; `None` for a namespace.
fn from_outline(kind: OutlineKind) -> Option<Self> {
Some(match kind {
OutlineKind::Namespace => return None,
OutlineKind::Class => Self::Class,
OutlineKind::Interface => Self::Interface,
OutlineKind::Trait => Self::Trait,
OutlineKind::Enum => Self::Enum,
OutlineKind::Function => Self::Function,
OutlineKind::Method => Self::Method,
OutlineKind::Property => Self::Property,
OutlineKind::Constant => Self::Constant,
OutlineKind::EnumCase => Self::EnumCase,
})
}
}
/// One declaration.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Symbol {
/// The name as written: `Product`, `find`, `$id` (properties keep the
/// `$`), `MAX`.
pub name: String,
/// The fully qualified name without a leading `\`: `App\Models\Product`
/// for a class or function, `App\Models\Product::find` for a member.
pub fqn: String,
/// What it declares.
pub kind: SymbolKind,
/// The FQN of the class, interface, trait or enum that declares a
/// member; `None` for classes, functions and constants outside a class.
pub container: Option<String>,
/// 0-based line of the name.
pub line: usize,
/// Column of the name in UTF-16 code units.
pub column: usize,
}
/// A file in the index.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct IndexedFile {
/// Project-relative path with `/` separators.
pub path: String,
/// Library code: the file is below the root's `vendor/`.
pub library: bool,
/// Declarations in source order; empty for files that are not parsed.
pub symbols: Vec<Symbol>,
}
/// Whether the project-relative `path` is library code (the root's
/// `vendor/` or anything below it).
pub fn is_library(path: &str) -> bool {
path == "vendor" || path.starts_with("vendor/")
}
/// Whether the project-relative `path` is a PHP file to parse.
pub(crate) fn is_php(path: &str) -> bool {
path.rsplit('/')
.next()
.and_then(|name| name.rsplit_once('.'))
.is_some_and(|(stem, ext)| !stem.is_empty() && ext.eq_ignore_ascii_case("php"))
}
/// Indexes `text` as the file at `path`: parses it when it is a PHP file
/// of at most [`MAX_PARSE_BYTES`] and extracts its symbols; other files get
/// no symbols.
///
/// # Parameters
/// - `parser`: reused between files.
/// - `path`: project-relative path with `/` separators.
/// - `text`: the file's text.
pub fn index_text(parser: &mut Parser, path: String, text: &str) -> IndexedFile {
let library = is_library(&path);
let parse = is_php(&path) && text.len() as u64 <= MAX_PARSE_BYTES;
let symbols = if parse {
let tree = parser.parse(text);
symbols_from_outline(&lutra_syntax::outline(&tree))
} else {
Vec::new()
};
IndexedFile {
path,
library,
symbols,
}
}
/// The symbols declared in an outline, in source order, at most
/// [`MAX_SYMBOLS_PER_FILE`].
///
/// Namespaces give the FQN prefix of what they contain; classes,
/// interfaces, traits and enums are the container of their members.
/// Anonymous classes and their members are skipped: nothing can navigate to
/// them by name.
pub fn symbols_from_outline(items: &[OutlineItem]) -> Vec<Symbol> {
let mut out = Vec::new();
collect(items, "", None, &mut out);
out
}
/// Adds the symbols of `items` to `out`.
///
/// # Parameters
/// - `namespace`: the enclosing namespace without leading or trailing `\`;
/// empty for the global namespace.
/// - `container`: the FQN of the enclosing class-like declaration.
fn collect(items: &[OutlineItem], namespace: &str, container: Option<&str>, out: &mut Vec<Symbol>) {
for item in items {
if out.len() >= MAX_SYMBOLS_PER_FILE {
return;
}
let Some(kind) = SymbolKind::from_outline(item.kind) else {
let name = item.name.trim_matches('\\');
collect(&item.children, name, None, out);
continue;
};
if item.is_anonymous() || item.name.is_empty() {
continue;
}
let (fqn, owner) = match container {
Some(owner) if !kind.is_class_like() && kind != SymbolKind::Function => {
(format!("{owner}::{}", item.name), Some(owner.to_string()))
}
_ => (qualify(namespace, &item.name), None),
};
let start = item.selection_range.start;
out.push(Symbol {
name: item.name.clone(),
fqn: fqn.clone(),
kind,
container: owner,
line: start.line,
column: start.column,
});
if kind.is_class_like() {
collect(&item.children, namespace, Some(&fqn), out);
}
}
}
/// `name` qualified with `namespace`: `App\Product`, or `Product` in the
/// global namespace.
fn qualify(namespace: &str, name: &str) -> String {
let name = name.trim_start_matches('\\');
if namespace.is_empty() {
name.to_string()
} else {
format!("{namespace}\\{name}")
}
}
#[cfg(test)]
mod tests {
use super::*;
fn symbols(source: &str) -> Vec<Symbol> {
let mut parser = Parser::new().unwrap();
index_text(&mut parser, "src/a.php".into(), source).symbols
}
#[test]
fn qualifies_classes_members_and_functions() {
let found = symbols(
"<?php\nnamespace App\\Models;\n\ninterface HasId {}\nfinal class Product implements HasId\n{\n public const MAX = 3;\n private ?string $name = null;\n public function __construct(private int $id) {}\n public function find(int $id): ?self { return null; }\n}\nenum Status: string { case Draft = 'draft'; }\nfunction helper(): void {}\nconst VERSION = 1;\n$x = new class { public function hidden() {} };\n",
);
let summary: Vec<(String, &str, Option<String>)> = found
.iter()
.map(|s| (s.fqn.clone(), s.kind.as_str(), s.container.clone()))
.collect();
let product = Some("App\\Models\\Product".to_string());
assert_eq!(
summary,
vec![
("App\\Models\\HasId".into(), "interface", None),
("App\\Models\\Product".into(), "class", None),
(
"App\\Models\\Product::MAX".into(),
"constant",
product.clone()
),
(
"App\\Models\\Product::$name".into(),
"property",
product.clone()
),
(
"App\\Models\\Product::__construct".into(),
"method",
product.clone()
),
(
"App\\Models\\Product::$id".into(),
"property",
product.clone()
),
("App\\Models\\Product::find".into(), "method", product),
("App\\Models\\Status".into(), "enum", None),
(
"App\\Models\\Status::Draft".into(),
"enumCase",
Some("App\\Models\\Status".into())
),
("App\\Models\\helper".into(), "function", None),
("App\\Models\\VERSION".into(), "constant", None),
]
);
let product = found.iter().find(|s| s.name == "Product").unwrap();
assert_eq!((product.line, product.column), (4, 12));
}
#[test]
fn braced_and_global_namespaces() {
let found = symbols(
"<?php\nnamespace A { class One {} }\nnamespace { class Two {} function three() {} }\n",
);
let fqns: Vec<&str> = found.iter().map(|s| s.fqn.as_str()).collect();
assert_eq!(fqns, vec!["A\\One", "Two", "three"]);
}
#[test]
fn only_php_files_are_parsed() {
let mut parser = Parser::new().unwrap();
let text = "<?php class A {}";
assert_eq!(
index_text(&mut parser, "a.php".into(), text).symbols.len(),
1
);
assert_eq!(
index_text(&mut parser, "A.PHP".into(), text).symbols.len(),
1
);
assert!(
index_text(&mut parser, "a.twig".into(), text)
.symbols
.is_empty()
);
assert!(
index_text(&mut parser, ".php".into(), text)
.symbols
.is_empty()
);
let file = index_text(&mut parser, "vendor/x/a.php".into(), text);
assert!(file.library);
assert!(!is_library("vendors/a.php"));
}
#[test]
fn oversized_files_have_no_symbols() {
let mut parser = Parser::new().unwrap();
let mut text = String::from("<?php class A {}\n");
text.push_str(&"// filler\n".repeat((MAX_PARSE_BYTES as usize) / 10 + 1));
assert!(
index_text(&mut parser, "a.php".into(), &text)
.symbols
.is_empty()
);
}
}