M2.1: tree-sitter PHP in crates/syntax

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>
This commit is contained in:
danny 2026-10-16 22:06:21 +02:00
parent d12a517009
commit a5236acd7e
25 changed files with 1768 additions and 6 deletions

View file

@ -0,0 +1,112 @@
//! Folding ranges of a PHP file.
//!
//! A region folds when it spans at least two lines. Foldable regions are
//! blocks in braces (class, interface, trait and enum bodies, function and
//! method bodies, control-flow blocks, `switch` and `match` bodies), array
//! literals, comments, heredoc and nowdoc strings, grouped `use` imports
//! (`use A\{B, C}`) and runs of two or more consecutive `use` statements.
//!
//! Ranges cover the whole region, delimiters included (`{` to `}`, `/*` to
//! `*/`); the editor decides which part stays visible when folded.
use tree_sitter::{Language, Node};
use crate::{Range, Tree};
/// Node kinds that fold as a whole.
const FOLDABLE: &[&str] = &[
"compound_statement",
"declaration_list",
"enum_declaration_list",
"switch_block",
"match_block",
"array_creation_expression",
"comment",
"heredoc",
"nowdoc",
"namespace_use_group",
];
/// The folding ranges of `tree`, sorted by start, without duplicates.
///
/// Empty for a [`Tree::truncated`] tree. Error nodes never fold, but
/// regions inside them do. The walk is iterative, so deeply nested input
/// cannot exhaust the stack, and it skips the inside of single-line nodes,
/// which cannot contain a multi-line region.
pub fn folding(tree: &Tree) -> Vec<Range> {
let Some(root) = tree.root() else {
return Vec::new();
};
let language: Language = tree_sitter_php::LANGUAGE_PHP.into();
let foldable: Vec<u16> = FOLDABLE
.iter()
.map(|kind| language.id_for_node_kind(kind, true))
.collect();
let use_parents = [
language.id_for_node_kind("program", true),
language.id_for_node_kind("compound_statement", true),
];
let mut bytes = Vec::new();
let mut cursor = root.walk();
'walk: loop {
let node = cursor.node();
if node.end_position().row > node.start_position().row {
let kind = node.kind_id();
if foldable.contains(&kind) && !node.is_error() {
bytes.push((node.start_byte(), node.end_byte()));
}
if use_parents.contains(&kind) {
use_runs(&mut bytes, node);
}
if cursor.goto_first_child() {
continue;
}
}
while !cursor.goto_next_sibling() {
if !cursor.goto_parent() {
break 'walk;
}
}
}
let mut ranges: Vec<Range> = bytes
.into_iter()
.filter_map(|(start, end)| Range::from_bytes(tree.text(), start, end))
.collect();
ranges.sort();
ranges.dedup();
ranges
}
/// Adds the runs of two or more consecutive `use` statements among the
/// children of `node`.
fn use_runs(bytes: &mut Vec<(usize, usize)>, node: Node<'_>) {
let mut cursor = node.walk();
let mut run: Option<(Node<'_>, Node<'_>)> = None;
for child in node.named_children(&mut cursor) {
if child.kind() == "namespace_use_declaration" {
run = Some(match run {
Some((first, _)) => (first, child),
None => (child, child),
});
continue;
}
if let Some((first, last)) = run.take()
&& first.id() != last.id()
{
push_multiline(bytes, first, last);
}
}
if let Some((first, last)) = run
&& first.id() != last.id()
{
push_multiline(bytes, first, last);
}
}
/// Adds the byte range from the start of `first` to the end of `last` when
/// it spans more than one line.
fn push_multiline(bytes: &mut Vec<(usize, usize)>, first: Node<'_>, last: Node<'_>) {
if last.end_position().row > first.start_position().row {
bytes.push((first.start_byte(), last.end_byte()));
}
}

View file

@ -1,4 +1,24 @@
//! Syntax layer for Lutra (layer L1).
//!
//! Parses source files with tree-sitter (PHP first) and derives outlines,
//! folding ranges and highlight tokens from the syntax tree.
//! Parses PHP source with tree-sitter and derives the structure the rest of
//! the IDE builds on: the outline (namespaces, classes, functions, members)
//! and folding ranges. Highlighting in the editor is done by CodeMirror's
//! Lezer grammar in the UI; this crate is the structural source for the
//! outline, folding and the symbol index (see `docs/architecture.md`).
//!
//! Source text is untrusted: nothing here panics on broken PHP or random
//! bytes. Files over [`MAX_PARSE_BYTES`] are not parsed; their [`Tree`]
//! reports [`Tree::truncated`] and yields an empty outline.
//!
//! Positions are zero-based lines and columns counted in UTF-16 code units,
//! converted through `lutra_text`.
mod folding;
mod outline;
mod parser;
mod range;
pub use folding::folding;
pub use outline::{ANONYMOUS_CLASS_NAME, OutlineItem, OutlineKind, outline};
pub use parser::{MAX_PARSE_BYTES, Parser, SyntaxError, Tree};
pub use range::Range;

View file

@ -0,0 +1,531 @@
//! 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
}

273
crates/syntax/src/parser.rs Normal file
View file

@ -0,0 +1,273 @@
//! The PHP parser and its syntax tree.
//!
//! [`Parser`] wraps a tree-sitter parser loaded with the PHP grammar
//! (`tree-sitter-php`, the variant that accepts inline HTML around
//! `<?php` tags, as `.php` files do). [`Tree`] keeps the text it was parsed
//! from, so an incremental [`Parser::reparse`] needs only the edits.
use std::fmt;
use lutra_text::{Buffer, Edit, TextError};
use tree_sitter::{InputEdit, Node, Point};
/// Files larger than this many bytes (8 MiB) are not parsed.
///
/// A [`Tree`] for such a text reports [`Tree::truncated`], has no syntax
/// nodes and yields an empty outline and no folding ranges.
pub const MAX_PARSE_BYTES: usize = 8 * 1024 * 1024;
/// Errors of the syntax layer.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SyntaxError {
/// The PHP grammar could not be loaded into tree-sitter, for example
/// because its ABI version is not supported by the linked library.
Language(String),
/// An edit passed to [`Parser::reparse`] was rejected by `lutra_text`
/// (reversed, out of range, not on a character boundary, overlapping).
Edit(TextError),
}
impl fmt::Display for SyntaxError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Language(reason) => write!(f, "cannot load the PHP grammar: {reason}"),
Self::Edit(error) => write!(f, "invalid edit: {error}"),
}
}
}
impl std::error::Error for SyntaxError {}
impl From<TextError> for SyntaxError {
fn from(error: TextError) -> Self {
Self::Edit(error)
}
}
/// A parsed PHP text.
///
/// Holds the tree-sitter tree together with the text it was parsed from.
/// Cloning is cheap: the text is a rope and tree-sitter trees are
/// reference counted. Broken PHP still produces a tree; tree-sitter marks
/// the broken parts as error nodes, which the outline and folding skip.
#[derive(Debug, Clone)]
pub struct Tree {
/// The syntax tree; `None` when the text was too large to parse or
/// tree-sitter gave up.
inner: Option<tree_sitter::Tree>,
/// The text the tree describes.
text: Buffer,
/// Whether parsing was skipped because the text exceeds
/// [`MAX_PARSE_BYTES`].
truncated: bool,
}
impl Tree {
/// The text this tree was parsed from.
pub fn text(&self) -> &Buffer {
&self.text
}
/// Whether the text was too large to parse (over [`MAX_PARSE_BYTES`]).
///
/// The engine reports this as `truncated` next to the outline.
pub fn truncated(&self) -> bool {
self.truncated
}
/// Whether the tree contains syntax errors or missing tokens.
pub fn has_errors(&self) -> bool {
self.root().is_some_and(|root| root.has_error())
}
/// The tree in tree-sitter's S-expression notation, without positions.
///
/// Meant for tests and diagnostics; empty when nothing was parsed.
pub fn to_sexp(&self) -> String {
self.root().map(|root| root.to_sexp()).unwrap_or_default()
}
/// The root node, if the text was parsed.
pub(crate) fn root(&self) -> Option<Node<'_>> {
self.inner.as_ref().map(tree_sitter::Tree::root_node)
}
}
/// A PHP parser.
///
/// Reuse one parser for many parses; it is cheap to keep but not to
/// create. A parser is `Send` but parses one text at a time (`&mut self`).
pub struct Parser {
/// The tree-sitter parser with the PHP grammar loaded.
inner: tree_sitter::Parser,
}
impl fmt::Debug for Parser {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Parser").finish_non_exhaustive()
}
}
impl Parser {
/// Creates a parser for PHP files (inline HTML allowed around
/// `<?php … ?>`).
///
/// # Errors
/// Fails with [`SyntaxError::Language`] when the bundled grammar cannot
/// be loaded, which only happens with a mismatched tree-sitter build.
pub fn new() -> Result<Self, SyntaxError> {
let mut inner = tree_sitter::Parser::new();
inner
.set_language(&tree_sitter_php::LANGUAGE_PHP.into())
.map_err(|error| SyntaxError::Language(error.to_string()))?;
Ok(Self { inner })
}
/// Parses `text` from scratch.
///
/// Never fails: broken PHP yields a tree with error nodes, and a text
/// over [`MAX_PARSE_BYTES`] yields an empty, [`Tree::truncated`] tree.
pub fn parse(&mut self, text: &str) -> Tree {
self.parse_buffer(Buffer::new(text), text, None)
}
/// Applies `edits` to the text of `tree` and parses the result
/// incrementally, reusing the unchanged parts of `tree`.
///
/// `edits` follow [`Buffer::apply`]: every range refers to the text of
/// `tree` (before any of the edits), in any order. The batch is mapped
/// to one tree-sitter edit that covers all changed bytes, with
/// positions computed from the old and new text. The result equals a
/// fresh [`Parser::parse`] of the edited text.
///
/// # Errors
/// Fails with [`SyntaxError::Edit`] when `lutra_text` rejects the
/// batch; `tree` is unaffected.
pub fn reparse(&mut self, tree: &Tree, edits: &[Edit]) -> Result<Tree, SyntaxError> {
let mut buffer = tree.text.clone();
buffer.apply(edits)?;
let new_text = buffer.text();
let (Some(old_tree), Some(input_edit)) = (
tree.inner.as_ref(),
covering_edit(&tree.text.text(), &new_text, edits),
) else {
return Ok(self.parse_buffer(buffer, &new_text, None));
};
let mut edited = old_tree.clone();
edited.edit(&input_edit);
Ok(self.parse_buffer(buffer, &new_text, Some(&edited)))
}
/// Parses `text` (the contents of `buffer`), reusing `old` when given.
fn parse_buffer(
&mut self,
buffer: Buffer,
text: &str,
old: Option<&tree_sitter::Tree>,
) -> Tree {
if text.len() > MAX_PARSE_BYTES {
return Tree {
inner: None,
text: buffer,
truncated: true,
};
}
Tree {
inner: self.inner.parse(text, old),
text: buffer,
truncated: false,
}
}
}
/// Builds the single tree-sitter edit that turns `old` into `new` for a
/// batch of `edits` that `lutra_text` already accepted against `old`.
///
/// The edit spans from the smallest start to the largest end of the batch,
/// which keeps it correct however the batch orders insertions that share
/// an offset. Returns `None` for an empty batch or inconsistent lengths, in
/// which case the caller parses from scratch.
fn covering_edit(old: &str, new: &str, edits: &[Edit]) -> Option<InputEdit> {
let start_byte = edits.iter().map(|edit| edit.range.start).min()?;
let old_end_byte = edits.iter().map(|edit| edit.range.end).max()?;
let new_end_byte = old_end_byte
.checked_add(new.len())?
.checked_sub(old.len())?;
if new_end_byte < start_byte {
return None;
}
Some(InputEdit {
start_byte,
old_end_byte,
new_end_byte,
start_position: point_at(old, start_byte),
old_end_position: point_at(old, old_end_byte),
new_end_position: point_at(new, new_end_byte),
})
}
/// The tree-sitter point (row, byte column) of byte `offset` in `text`.
///
/// tree-sitter counts rows by `\n` only. An offset past the end is clamped
/// to the end of the text.
fn point_at(text: &str, offset: usize) -> Point {
let bytes = text.as_bytes();
let prefix = bytes.get(..offset).unwrap_or(bytes);
let row = prefix.iter().filter(|byte| **byte == b'\n').count();
let line_start = prefix
.iter()
.rposition(|byte| *byte == b'\n')
.map_or(0, |newline| newline.saturating_add(1));
Point {
row,
column: prefix.len().saturating_sub(line_start),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn point_counts_rows_and_byte_columns() {
let text = "ab\ncä\n";
assert_eq!(point_at(text, 0), Point { row: 0, column: 0 });
assert_eq!(point_at(text, 3), Point { row: 1, column: 0 });
assert_eq!(point_at(text, 6), Point { row: 1, column: 3 });
assert_eq!(point_at(text, 7), Point { row: 2, column: 0 });
assert_eq!(point_at(text, 99), Point { row: 2, column: 0 });
}
#[test]
fn oversized_text_is_not_parsed() {
let mut parser = Parser::new().unwrap();
let text = format!("<?php\n/*{}*/", "x".repeat(MAX_PARSE_BYTES));
let tree = parser.parse(&text);
assert!(tree.truncated());
assert!(tree.to_sexp().is_empty());
let shrunk = parser
.reparse(&tree, &[Edit::delete(8..MAX_PARSE_BYTES)])
.unwrap();
assert!(!shrunk.truncated());
assert_eq!(
shrunk.to_sexp(),
parser.parse("<?php\n/*xxxxxxxx*/").to_sexp()
);
}
#[test]
fn rejected_edit_is_an_error() {
let mut parser = Parser::new().unwrap();
let tree = parser.parse("<?php echo 1;");
let error = parser.reparse(&tree, &[Edit::delete(5..99)]).unwrap_err();
assert!(matches!(error, SyntaxError::Edit(_)));
}
#[test]
fn empty_batch_reparses_to_the_same_tree() {
let mut parser = Parser::new().unwrap();
let tree = parser.parse("<?php function f() {}");
let again = parser.reparse(&tree, &[]).unwrap();
assert_eq!(again.to_sexp(), tree.to_sexp());
}
}

View file

@ -0,0 +1,28 @@
//! Ranges in line and UTF-16 column coordinates.
use lutra_text::{Buffer, ColumnUnit, Position};
/// A range between two positions, end exclusive.
///
/// Lines and columns are zero-based; columns count UTF-16 code units, as
/// CodeMirror and LSP do.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct Range {
/// First position inside the range.
pub start: Position,
/// Position just after the range.
pub end: Position,
}
impl Range {
/// Converts the byte range `start..end` of `text` into a [`Range`].
///
/// Returns `None` when either offset is past the end of the text, inside
/// a character or inside a CRLF line break.
pub(crate) fn from_bytes(text: &Buffer, start: usize, end: usize) -> Option<Self> {
Some(Self {
start: text.offset_to_position(start, ColumnUnit::Utf16).ok()?,
end: text.offset_to_position(end, ColumnUnit::Utf16).ok()?,
})
}
}