1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
/// Core AST infrastructure: arena-backed `ParsedDoc`, span utilities, and TypeHint formatting.
use php_ast::{Program, Span, TypeHint, TypeHintKind};
use tower_lsp::lsp_types::{Position, Range};
// ── ParsedDoc ─────────────────────────────────────────────────────────────────
/// Owns a parsed PHP document: the bumpalo arena, source snapshot, and Program.
///
/// SAFETY invariants:
/// - `program` is dropped before `_arena` and `_source` (field declaration order).
/// - Both `_arena` and `_source` are `Box`-allocated; their heap addresses are
/// stable and never move.
/// - The `'static` lifetimes in `Box<Program<'static, 'static>>` are erased
/// versions of the true lifetimes `'_arena` and `'_source`. The public
/// `program()` accessor re-attaches them to `&self`, preventing any reference
/// from escaping beyond the lifetime of the `ParsedDoc`.
pub struct ParsedDoc {
// Drop order is declaration order in Rust — program drops first.
program: Box<Program<'static, 'static>>,
pub errors: Vec<php_rs_parser::diagnostics::ParseError>,
_arena: Box<bumpalo::Bump>,
#[allow(clippy::box_collection)]
_source: Box<String>,
}
// SAFETY: Program nodes contain only data; no thread-local state.
unsafe impl Send for ParsedDoc {}
unsafe impl Sync for ParsedDoc {}
impl ParsedDoc {
pub fn parse(source: String) -> Self {
let source_box = Box::new(source);
let arena_box = Box::new(bumpalo::Bump::new());
// SAFETY: Both boxes are on the heap; moving a Box<T> moves the pointer,
// not the heap data. These references therefore remain valid for as long
// as the boxes (and hence `self`) are alive.
let src_ref: &'static str =
unsafe { std::mem::transmute::<&str, &'static str>(source_box.as_str()) };
let arena_ref: &'static bumpalo::Bump = unsafe {
std::mem::transmute::<&bumpalo::Bump, &'static bumpalo::Bump>(arena_box.as_ref())
};
let result = php_rs_parser::parse(arena_ref, src_ref);
ParsedDoc {
program: Box::new(result.program),
errors: result.errors,
_arena: arena_box,
_source: source_box,
}
}
/// Borrow the program with lifetimes bounded by `&self`.
///
/// SAFETY: covariance of `Program<'arena, 'src>` in both parameters lets
/// `&Program<'static, 'static>` shorten to `&Program<'_, '_>`.
#[inline]
pub fn program(&self) -> &Program<'_, '_> {
&self.program
}
/// Borrow the source text used when parsing.
#[inline]
pub fn source(&self) -> &str {
&self._source
}
}
impl Default for ParsedDoc {
fn default() -> Self {
ParsedDoc::parse(String::new())
}
}
// ── Span / position utilities ─────────────────────────────────────────────────
/// Convert a byte offset into `source` to an LSP `Position` (0-based line/char).
pub fn offset_to_position(source: &str, offset: u32) -> Position {
let offset = (offset as usize).min(source.len());
let prefix = &source[..offset];
let line = prefix.bytes().filter(|&b| b == b'\n').count() as u32;
let last_nl = prefix.rfind('\n').map(|i| i + 1).unwrap_or(0);
let character = prefix[last_nl..]
.chars()
.map(|c| c.len_utf16() as u32)
.sum::<u32>();
Position { line, character }
}
/// Convert a `Span` (byte-offset pair) to an LSP `Range`.
pub fn span_to_range(source: &str, span: Span) -> Range {
Range {
start: offset_to_position(source, span.start),
end: offset_to_position(source, span.end),
}
}
/// Return the byte offset of `substr` within `source`.
///
/// Uses pointer arithmetic when `substr` is a true sub-slice of `source`
/// (i.e. arena-allocated names pointing into the same backing string).
/// Falls back to a content search when the pointers differ — this handles
/// tests and callers that pass a differently-allocated copy of the source.
pub fn str_offset(source: &str, substr: &str) -> u32 {
let src_ptr = source.as_ptr() as usize;
let sub_ptr = substr.as_ptr() as usize;
if sub_ptr >= src_ptr && sub_ptr + substr.len() <= src_ptr + source.len() {
return (sub_ptr - src_ptr) as u32;
}
// Fallback: locate by content (same text, different allocation).
source.find(substr).unwrap_or(0) as u32
}
/// Build an LSP `Range` for a name that is a sub-slice of `source`.
pub fn name_range(source: &str, name: &str) -> Range {
let start = str_offset(source, name);
Range {
start: offset_to_position(source, start),
end: offset_to_position(source, start + name.len() as u32),
}
}
// ── TypeHint formatting ────────────────────────────────────────────────────────
/// Format a `TypeHint` as a PHP type string, e.g. `?int`, `string|null`.
pub fn format_type_hint(hint: &TypeHint<'_, '_>) -> String {
fmt_kind(&hint.kind)
}
fn fmt_kind(kind: &TypeHintKind<'_, '_>) -> String {
match kind {
TypeHintKind::Named(name) => name.to_string_repr().to_string(),
TypeHintKind::Keyword(builtin, _) => builtin.as_str().to_string(),
TypeHintKind::Nullable(inner) => format!("?{}", format_type_hint(inner)),
TypeHintKind::Union(types) => types
.iter()
.map(format_type_hint)
.collect::<Vec<_>>()
.join("|"),
TypeHintKind::Intersection(types) => types
.iter()
.map(format_type_hint)
.collect::<Vec<_>>()
.join("&"),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_empty_source() {
let doc = ParsedDoc::parse("<?php".to_string());
assert!(doc.errors.is_empty());
assert!(doc.program().stmts.is_empty());
}
#[test]
fn parses_function() {
let doc = ParsedDoc::parse("<?php\nfunction foo() {}".to_string());
assert_eq!(doc.program().stmts.len(), 1);
}
#[test]
fn offset_to_position_first_line() {
assert_eq!(
offset_to_position("<?php\nfoo", 0),
Position {
line: 0,
character: 0
}
);
}
#[test]
fn offset_to_position_second_line() {
// "<?php\n" — offset 6 is start of line 1
assert_eq!(
offset_to_position("<?php\nfoo", 6),
Position {
line: 1,
character: 0
}
);
}
#[test]
fn offset_to_position_multibyte_utf16() {
// "é" is U+00E9: 2 UTF-8 bytes, 1 UTF-16 code unit.
// "😀" is U+1F600: 4 UTF-8 bytes, 2 UTF-16 code units.
// source: "a😀b" — byte offsets: a=0, 😀=1..5, b=5
// UTF-16: a=col 0, 😀=col 1..3, b=col 3
let src = "a\u{1F600}b";
assert_eq!(
offset_to_position(src, 5), // byte offset of 'b'
Position {
line: 0,
character: 3
} // UTF-16 col 3
);
}
#[test]
fn str_offset_finds_substr() {
let src = "<?php\nfunction foo() {}";
let name = &src[15..18]; // "foo"
assert_eq!(str_offset(src, name), 15);
}
#[test]
fn str_offset_content_fallback_for_different_allocation() {
// "foo" is a separately owned String (not a sub-slice of the source),
// so pointer arithmetic fails. The fallback finds it by content.
let owned = "foo".to_string();
assert_eq!(str_offset("<?php foo", &owned), 6);
}
#[test]
fn str_offset_unrelated_content_returns_zero() {
let owned = "bar".to_string();
assert_eq!(str_offset("<?php foo", &owned), 0);
}
}