Parser (parse, incremental reparse from lutra_text edits), outline with UTF-16 ranges and short signatures, folding ranges, 8 MiB parse cap. Snapshot tests for five PHP 8.3 fixtures, proptests (random bytes, reparse equals fresh parse, undo round trip), ignored release timing test. Docs: architecture Syntax section, parity evidence, G4 note. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
531 lines
18 KiB
Rust
531 lines
18 KiB
Rust
//! The structural outline of a PHP file.
|
|
//!
|
|
//! The outline lists namespaces, classes, interfaces, traits, enums,
|
|
//! functions and their members (methods, properties, constants, enum
|
|
//! cases) as a tree in source order. It feeds the Structure tool window
|
|
//! and the symbol index.
|
|
//!
|
|
//! - Braced namespaces (`namespace A { … }`) contain their declarations;
|
|
//! an unbraced `namespace A;` contains every declaration up to the next
|
|
//! namespace statement. The global `namespace { … }` adds no item.
|
|
//! - Constructor-promoted parameters become properties of their class,
|
|
//! listed right after the constructor.
|
|
//! - Anonymous classes appear as classes named [`ANONYMOUS_CLASS_NAME`]
|
|
//! (PHP's own name for them); indexers skip them with
|
|
//! [`OutlineItem::is_anonymous`].
|
|
//! - Function, method and closure bodies are not searched, so local
|
|
//! closures and classes inside them are not listed. Declarations nested
|
|
//! in top-level statements (`if (!function_exists(…)) { function … }`)
|
|
//! are.
|
|
//! - Error nodes are transparent: their content is searched, but they never
|
|
//! become items, and declarations without a name are skipped.
|
|
|
|
use lutra_text::Buffer;
|
|
use tree_sitter::Node;
|
|
|
|
use crate::{Range, Tree};
|
|
|
|
/// The name given to anonymous classes (`new class { … }`), as PHP itself
|
|
/// reports them.
|
|
pub const ANONYMOUS_CLASS_NAME: &str = "class@anonymous";
|
|
|
|
/// How deep the outline search descends through statements and
|
|
/// expressions. Deeper nesting is not searched, which bounds recursion on
|
|
/// adversarial input.
|
|
const MAX_DEPTH: usize = 96;
|
|
|
|
/// Longest `detail` string, in chars; longer signatures end in `…`.
|
|
const MAX_DETAIL_CHARS: usize = 160;
|
|
|
|
/// What an outline item declares.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
|
|
pub enum OutlineKind {
|
|
/// `namespace A\B;` or `namespace A\B { … }`.
|
|
Namespace,
|
|
/// A class, named or anonymous.
|
|
Class,
|
|
/// An interface.
|
|
Interface,
|
|
/// A trait.
|
|
Trait,
|
|
/// An enum.
|
|
Enum,
|
|
/// A function declared outside a class.
|
|
Function,
|
|
/// A method of a class, interface, trait or enum.
|
|
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 OutlineKind {
|
|
/// The kind's name as the engine and the UI use it: `namespace`,
|
|
/// `class`, `interface`, `trait`, `enum`, `function`, `method`,
|
|
/// `property`, `constant` or `enumCase`.
|
|
pub fn as_str(self) -> &'static str {
|
|
match self {
|
|
Self::Namespace => "namespace",
|
|
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",
|
|
}
|
|
}
|
|
}
|
|
|
|
/// One declaration in the outline.
|
|
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
|
|
pub struct OutlineItem {
|
|
/// What the item declares.
|
|
pub kind: OutlineKind,
|
|
/// The declared name as written: `App\Models` for a namespace, `$id`
|
|
/// for a property (with the `$`), [`ANONYMOUS_CLASS_NAME`] for an
|
|
/// anonymous class.
|
|
pub name: String,
|
|
/// A short signature with whitespace collapsed, capped at 160 chars:
|
|
/// - functions and methods: `(int $id, string ...$tags): ?Product`
|
|
/// (types, `&`, `...` and names; no defaults or attributes);
|
|
/// - classes: `extends Base implements A, B`; interfaces: `extends A`;
|
|
/// enums: `: string implements HasLabel`;
|
|
/// - properties and typed constants: the type, e.g. `?string`;
|
|
/// - enum cases: the backing value, e.g. `'draft'`.
|
|
///
|
|
/// `None` when there is nothing to show.
|
|
pub detail: Option<String>,
|
|
/// The whole declaration, attributes and modifiers included.
|
|
pub range: Range,
|
|
/// The name inside the declaration, to select or reveal.
|
|
pub selection_range: Range,
|
|
/// Nested declarations in source order.
|
|
pub children: Vec<OutlineItem>,
|
|
}
|
|
|
|
impl OutlineItem {
|
|
/// Whether the item is an anonymous class.
|
|
pub fn is_anonymous(&self) -> bool {
|
|
self.kind == OutlineKind::Class && self.name == ANONYMOUS_CLASS_NAME
|
|
}
|
|
}
|
|
|
|
/// The outline of `tree`, top-level items in source order.
|
|
///
|
|
/// Empty for a [`Tree::truncated`] tree. Never fails: broken code yields
|
|
/// the items that could still be recognised.
|
|
pub fn outline(tree: &Tree) -> Vec<OutlineItem> {
|
|
let Some(root) = tree.root() else {
|
|
return Vec::new();
|
|
};
|
|
let source = tree.text().text();
|
|
let builder = Builder {
|
|
source: &source,
|
|
text: tree.text(),
|
|
};
|
|
let mut items = Vec::new();
|
|
builder.collect(root, 0, &mut items);
|
|
items
|
|
}
|
|
|
|
/// Walks the syntax tree and builds outline items.
|
|
struct Builder<'a> {
|
|
/// The parsed text, for names and signatures.
|
|
source: &'a str,
|
|
/// The same text as a buffer, for UTF-16 positions.
|
|
text: &'a Buffer,
|
|
}
|
|
|
|
impl Builder<'_> {
|
|
/// Adds the items found among the named children of `node` to `out`,
|
|
/// grouping declarations after an unbraced namespace into it.
|
|
fn collect(&self, node: Node<'_>, depth: usize, out: &mut Vec<OutlineItem>) {
|
|
if depth > MAX_DEPTH {
|
|
return;
|
|
}
|
|
let mut cursor = node.walk();
|
|
let children: Vec<Node<'_>> = node.named_children(&mut cursor).collect();
|
|
let mut children = children.into_iter().peekable();
|
|
while let Some(child) = children.next() {
|
|
if child.kind() != "namespace_definition" || child.child_by_field_name("body").is_some()
|
|
{
|
|
self.item(child, depth, out);
|
|
continue;
|
|
}
|
|
let mut members = Vec::new();
|
|
let mut end = child.end_byte();
|
|
while let Some(next) = children.next_if(|next| next.kind() != "namespace_definition") {
|
|
end = next.end_byte();
|
|
self.item(next, depth.saturating_add(1), &mut members);
|
|
}
|
|
match self.named(
|
|
child,
|
|
"name",
|
|
OutlineKind::Namespace,
|
|
None,
|
|
child.start_byte(),
|
|
end,
|
|
) {
|
|
Some(mut namespace) => {
|
|
namespace.children = members;
|
|
out.push(namespace);
|
|
}
|
|
None => out.append(&mut members),
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Adds the item(s) declared by `node` to `out`, or searches inside it
|
|
/// when it declares nothing itself.
|
|
fn item(&self, node: Node<'_>, depth: usize, out: &mut Vec<OutlineItem>) {
|
|
let next = depth.saturating_add(1);
|
|
match node.kind() {
|
|
"namespace_definition" => self.braced_namespace(node, next, out),
|
|
"class_declaration" => self.class_like(node, OutlineKind::Class, next, out),
|
|
"interface_declaration" => self.class_like(node, OutlineKind::Interface, next, out),
|
|
"trait_declaration" => self.class_like(node, OutlineKind::Trait, next, out),
|
|
"enum_declaration" => self.class_like(node, OutlineKind::Enum, next, out),
|
|
"anonymous_class" => self.anonymous_class(node, next, out),
|
|
"function_definition" => {
|
|
let detail = self.signature(node);
|
|
out.extend(self.whole(node, OutlineKind::Function, detail));
|
|
}
|
|
"method_declaration" => self.method(node, out),
|
|
"property_declaration" => self.properties(node, out),
|
|
"const_declaration" => self.constants(node, out),
|
|
"enum_case" => {
|
|
let detail = self.field_text(node, "value");
|
|
out.extend(self.whole(node, OutlineKind::EnumCase, detail));
|
|
}
|
|
"anonymous_function" | "arrow_function" | "comment" | "text" | "php_tag" => {}
|
|
_ => self.collect(node, next, out),
|
|
}
|
|
}
|
|
|
|
/// A braced namespace with its declarations; the global `namespace {}`
|
|
/// adds its declarations directly.
|
|
fn braced_namespace(&self, node: Node<'_>, depth: usize, out: &mut Vec<OutlineItem>) {
|
|
let mut members = Vec::new();
|
|
if let Some(body) = node.child_by_field_name("body") {
|
|
self.collect(body, depth, &mut members);
|
|
}
|
|
let item = self.named(
|
|
node,
|
|
"name",
|
|
OutlineKind::Namespace,
|
|
None,
|
|
node.start_byte(),
|
|
node.end_byte(),
|
|
);
|
|
match item {
|
|
Some(mut namespace) => {
|
|
namespace.children = members;
|
|
out.push(namespace);
|
|
}
|
|
None => out.append(&mut members),
|
|
}
|
|
}
|
|
|
|
/// A class, interface, trait or enum with its members.
|
|
fn class_like(
|
|
&self,
|
|
node: Node<'_>,
|
|
kind: OutlineKind,
|
|
depth: usize,
|
|
out: &mut Vec<OutlineItem>,
|
|
) {
|
|
let Some(mut item) = self.whole(node, kind, self.heritage(node)) else {
|
|
return;
|
|
};
|
|
if let Some(body) = node.child_by_field_name("body") {
|
|
self.collect(body, depth, &mut item.children);
|
|
}
|
|
out.push(item);
|
|
}
|
|
|
|
/// An anonymous class, selected at its `class` keyword.
|
|
fn anonymous_class(&self, node: Node<'_>, depth: usize, out: &mut Vec<OutlineItem>) {
|
|
let mut cursor = node.walk();
|
|
let keyword = node
|
|
.children(&mut cursor)
|
|
.find(|child| child.kind() == "class");
|
|
let (Some(range), Some(selection_range)) = (
|
|
self.range(node.start_byte(), node.end_byte()),
|
|
keyword.and_then(|keyword| self.range(keyword.start_byte(), keyword.end_byte())),
|
|
) else {
|
|
return;
|
|
};
|
|
let mut item = OutlineItem {
|
|
kind: OutlineKind::Class,
|
|
name: ANONYMOUS_CLASS_NAME.to_owned(),
|
|
detail: self.heritage(node),
|
|
range,
|
|
selection_range,
|
|
children: Vec::new(),
|
|
};
|
|
if let Some(body) = node.child_by_field_name("body") {
|
|
self.collect(body, depth, &mut item.children);
|
|
}
|
|
out.push(item);
|
|
}
|
|
|
|
/// A method, followed by the properties its parameters promote when it
|
|
/// is the constructor.
|
|
fn method(&self, node: Node<'_>, out: &mut Vec<OutlineItem>) {
|
|
let Some(method) = self.whole(node, OutlineKind::Method, self.signature(node)) else {
|
|
return;
|
|
};
|
|
let is_constructor = method.name.eq_ignore_ascii_case("__construct");
|
|
out.push(method);
|
|
if !is_constructor {
|
|
return;
|
|
}
|
|
let Some(parameters) = node.child_by_field_name("parameters") else {
|
|
return;
|
|
};
|
|
let mut cursor = parameters.walk();
|
|
for parameter in parameters.named_children(&mut cursor) {
|
|
if parameter.kind() != "property_promotion_parameter" {
|
|
continue;
|
|
}
|
|
let Some(mut name) = parameter.child_by_field_name("name") else {
|
|
continue;
|
|
};
|
|
if name.kind() == "by_ref" {
|
|
let mut inner = name.walk();
|
|
let Some(variable) = name
|
|
.named_children(&mut inner)
|
|
.find(|child| child.kind() == "variable_name")
|
|
else {
|
|
continue;
|
|
};
|
|
name = variable;
|
|
}
|
|
let detail = self.field_text(parameter, "type");
|
|
out.extend(self.item_at(
|
|
OutlineKind::Property,
|
|
name,
|
|
detail,
|
|
parameter.start_byte(),
|
|
parameter.end_byte(),
|
|
));
|
|
}
|
|
}
|
|
|
|
/// One property item per element of a property declaration
|
|
/// (`public int $a, $b;` gives two).
|
|
fn properties(&self, node: Node<'_>, out: &mut Vec<OutlineItem>) {
|
|
let detail = self.field_text(node, "type");
|
|
let mut cursor = node.walk();
|
|
let elements: Vec<Node<'_>> = node
|
|
.named_children(&mut cursor)
|
|
.filter(|child| child.kind() == "property_element")
|
|
.collect();
|
|
let single = elements.len() == 1;
|
|
for element in elements {
|
|
let outer = if single { node } else { element };
|
|
out.extend(self.named(
|
|
element,
|
|
"name",
|
|
OutlineKind::Property,
|
|
detail.clone(),
|
|
outer.start_byte(),
|
|
outer.end_byte(),
|
|
));
|
|
}
|
|
}
|
|
|
|
/// One constant item per element of a `const` declaration.
|
|
fn constants(&self, node: Node<'_>, out: &mut Vec<OutlineItem>) {
|
|
let detail = self.field_text(node, "type");
|
|
let mut cursor = node.walk();
|
|
let elements: Vec<Node<'_>> = node
|
|
.named_children(&mut cursor)
|
|
.filter(|child| child.kind() == "const_element")
|
|
.collect();
|
|
let single = elements.len() == 1;
|
|
for element in elements {
|
|
let mut inner = element.walk();
|
|
let Some(name) = element
|
|
.named_children(&mut inner)
|
|
.find(|child| child.kind() == "name")
|
|
else {
|
|
continue;
|
|
};
|
|
let outer = if single { node } else { element };
|
|
out.extend(self.item_at(
|
|
OutlineKind::Constant,
|
|
name,
|
|
detail.clone(),
|
|
outer.start_byte(),
|
|
outer.end_byte(),
|
|
));
|
|
}
|
|
}
|
|
|
|
/// An item spanning `node`, named by its `name` field.
|
|
fn whole(
|
|
&self,
|
|
node: Node<'_>,
|
|
kind: OutlineKind,
|
|
detail: Option<String>,
|
|
) -> Option<OutlineItem> {
|
|
self.named(
|
|
node,
|
|
"name",
|
|
kind,
|
|
detail,
|
|
node.start_byte(),
|
|
node.end_byte(),
|
|
)
|
|
}
|
|
|
|
/// An item spanning bytes `start..end`, named by the `field` child of
|
|
/// `node`.
|
|
fn named(
|
|
&self,
|
|
node: Node<'_>,
|
|
field: &str,
|
|
kind: OutlineKind,
|
|
detail: Option<String>,
|
|
start: usize,
|
|
end: usize,
|
|
) -> Option<OutlineItem> {
|
|
let name = node.child_by_field_name(field)?;
|
|
self.item_at(kind, name, detail, start, end)
|
|
}
|
|
|
|
/// An item spanning bytes `start..end` whose name is the text of
|
|
/// `name`. `None` when the name is missing, empty or an error node.
|
|
fn item_at(
|
|
&self,
|
|
kind: OutlineKind,
|
|
name: Node<'_>,
|
|
detail: Option<String>,
|
|
start: usize,
|
|
end: usize,
|
|
) -> Option<OutlineItem> {
|
|
if name.is_missing() || name.is_error() {
|
|
return None;
|
|
}
|
|
let text: String = self.text_of(name)?.split_whitespace().collect();
|
|
if text.is_empty() {
|
|
return None;
|
|
}
|
|
Some(OutlineItem {
|
|
kind,
|
|
name: text,
|
|
detail,
|
|
range: self.range(start, end)?,
|
|
selection_range: self.range(name.start_byte(), name.end_byte())?,
|
|
children: Vec::new(),
|
|
})
|
|
}
|
|
|
|
/// The parameter list and return type of a function or method, e.g.
|
|
/// `(int $id, string &...$tags): ?Product`.
|
|
fn signature(&self, node: Node<'_>) -> Option<String> {
|
|
let mut signature = String::from("(");
|
|
if let Some(parameters) = node.child_by_field_name("parameters") {
|
|
let mut cursor = parameters.walk();
|
|
let rendered: Vec<String> = parameters
|
|
.named_children(&mut cursor)
|
|
.filter_map(|parameter| self.parameter(parameter))
|
|
.collect();
|
|
signature.push_str(&rendered.join(", "));
|
|
}
|
|
signature.push(')');
|
|
if let Some(returns) = self.field_text(node, "return_type") {
|
|
signature.push_str(": ");
|
|
signature.push_str(&returns);
|
|
}
|
|
Some(cap(signature))
|
|
}
|
|
|
|
/// One parameter as `type &...$name`; `None` for anything that is not
|
|
/// a parameter (comments, error nodes).
|
|
fn parameter(&self, node: Node<'_>) -> Option<String> {
|
|
let variadic = match node.kind() {
|
|
"simple_parameter" | "property_promotion_parameter" => false,
|
|
"variadic_parameter" => true,
|
|
_ => return None,
|
|
};
|
|
let mut rendered = String::new();
|
|
if let Some(kind) = self.field_text(node, "type") {
|
|
rendered.push_str(&kind);
|
|
rendered.push(' ');
|
|
}
|
|
if node.child_by_field_name("reference_modifier").is_some() {
|
|
rendered.push('&');
|
|
}
|
|
if variadic {
|
|
rendered.push_str("...");
|
|
}
|
|
let name: String = self
|
|
.text_of(node.child_by_field_name("name")?)?
|
|
.split_whitespace()
|
|
.collect();
|
|
rendered.push_str(&name);
|
|
Some(rendered)
|
|
}
|
|
|
|
/// `extends …` / `implements …` of a class-like declaration, and the
|
|
/// backing type of an enum.
|
|
fn heritage(&self, node: Node<'_>) -> Option<String> {
|
|
let mut cursor = node.walk();
|
|
let mut parts = Vec::new();
|
|
for child in node.named_children(&mut cursor) {
|
|
match child.kind() {
|
|
"primitive_type" => parts.push(format!(": {}", collapse(self.text_of(child)?))),
|
|
"base_clause" | "class_interface_clause" => {
|
|
parts.push(collapse(self.text_of(child)?))
|
|
}
|
|
_ => {}
|
|
}
|
|
}
|
|
(!parts.is_empty()).then(|| cap(parts.join(" ")))
|
|
}
|
|
|
|
/// The whitespace-collapsed, capped text of the `field` child of
|
|
/// `node`.
|
|
fn field_text(&self, node: Node<'_>, field: &str) -> Option<String> {
|
|
let child = node.child_by_field_name(field)?;
|
|
let text = collapse(self.text_of(child)?);
|
|
(!text.is_empty()).then(|| cap(text))
|
|
}
|
|
|
|
/// The source text of `node`.
|
|
fn text_of(&self, node: Node<'_>) -> Option<&str> {
|
|
self.source.get(node.byte_range())
|
|
}
|
|
|
|
/// The UTF-16 range of bytes `start..end`.
|
|
fn range(&self, start: usize, end: usize) -> Option<Range> {
|
|
Range::from_bytes(self.text, start, end)
|
|
}
|
|
}
|
|
|
|
/// `text` with every run of whitespace replaced by one space and the ends
|
|
/// trimmed.
|
|
fn collapse(text: &str) -> String {
|
|
text.split_whitespace().collect::<Vec<_>>().join(" ")
|
|
}
|
|
|
|
/// `text` cut to [`MAX_DETAIL_CHARS`] chars, ending in `…` when cut.
|
|
fn cap(text: String) -> String {
|
|
if text.chars().count() <= MAX_DETAIL_CHARS {
|
|
return text;
|
|
}
|
|
let mut capped: String = text
|
|
.chars()
|
|
.take(MAX_DETAIL_CHARS.saturating_sub(1))
|
|
.collect();
|
|
capped.push('…');
|
|
capped
|
|
}
|