//! 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, /// 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, } 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 { 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) { if depth > MAX_DEPTH { return; } let mut cursor = node.walk(); let children: Vec> = 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) { 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) { 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, ) { 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) { 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) { 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) { let detail = self.field_text(node, "type"); let mut cursor = node.walk(); let elements: Vec> = 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) { let detail = self.field_text(node, "type"); let mut cursor = node.walk(); let elements: Vec> = 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, ) -> Option { 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, start: usize, end: usize, ) -> Option { 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, start: usize, end: usize, ) -> Option { 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 { let mut signature = String::from("("); if let Some(parameters) = node.child_by_field_name("parameters") { let mut cursor = parameters.walk(); let rendered: Vec = 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 { 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 { 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 { 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::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::>().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 }