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
use ;
use crate::;
use CppGreenNodeBuilder;
/// Turns the parser's flat event stream into a rowan green tree.
///
/// Two jobs beyond the mechanical translation:
///
/// 1. **Balancing.** The event stream is not guaranteed to be balanced, for a mundane reason:
/// `Marker::complete` drops empty nodes and therefore emits no `NodeEnd` for them. The parser's
/// own node stack stays consistent (see `CppParser::audit_events`), but the flat list can carry
/// a `NodeStart` that nothing closes. See [`balance_events`].
/// 2. **Re-nesting forward references.** `CompleteMarker::precede` opens a wrapper node *after* its
/// first child has already been parsed (`a + b` is parsed as `a`, then wrapped in `BinaryExpr`).
/// The wrapper's position is recorded in the child's `parent` field, and this builder opens the
/// wrapper before the child when it reaches it.
/// Make `events` balanced so the builder can translate it one-to-one.
///
/// The event **indices are preserved wherever a `parent` forward reference could point at them**,
/// because those references are absolute positions in this list. Events that are removed are
/// replaced by [`MarkEvent::Trivia`], which the builder already ignores, so nothing shifts.
///
/// Three rules:
///
/// * A matched `NodeStart`/`NodeEnd` pair with nothing in between is a zero-width node —
/// `Marker::complete` drops those, so they are removed here too.
/// * Anything still open at the end of the stream gets a synthesized `NodeEnd` **inserted where
/// that node actually ends**, not appended to the end. See below.
/// * A `NodeStart` that a forward reference was dropped for is left alone; empty nodes are never
/// the target of a forward reference.
///
/// # Why a leaked node must be closed eagerly, at its true end
///
/// The naive fix — appending `NodeEnd`s at the end of the stream, innermost first — does not
/// restore the tree's shape, it inverts it. A node opened but never closed *swallows every
/// following sibling*: the next declaration becomes a child of the previous one, and the leak is
/// invisible in the tree, which stays well-formed and lossless throughout. That is the exact
/// failure the parser's marker stack and event-stream audit exist to prevent, so the repair here
/// must not reintroduce it.
///
/// Instead the end of every unclosed node is *derived from the stream*: a node ends where the
/// deepest thing that occurred while it was open ends. Closing at that point bounds the damage to
/// the leaked node itself, and the tokens after it land as siblings, where they belong. A leak
/// still means an inner rule unwound without closing its marker, and the audit in
/// `CppParser::audit_events` still reports it — this only stops a shape bug from silently
/// re-parenting the rest of the file.
/// Make `events` balanced so the builder can translate it one-to-one.
///
/// The event **indices are preserved wherever a forward reference could point at them**, because
/// those references are absolute positions in this list. Events that are removed are replaced by
/// [`MarkEvent::Trivia`], which the builder already ignores, so nothing shifts.
///
/// # Why the raw stream is not balanced
///
/// `Marker::complete` drops a node that produced no content and emits no `NodeEnd` for it, so the
/// stream can carry both defects at once, and they are independent:
///
/// * a `NodeStart` with no `NodeEnd` — a marker that was dropped as empty while its *parent* still
/// owed an event; the parent's `complete` later emits that event, which has nothing left to pair
/// with. Leaving it in makes the builder pop a node it never pushed, so an enclosing node is
/// closed early and every following sibling lands outside its real parent.
/// * a `NodeEnd` with no `NodeStart` — a rule that unwound without closing its marker.
///
/// Repairing only one of the two is not enough, and appending the missing `NodeEnd`s at the end of
/// the stream is worse than doing nothing: a leaked node then *swallows every following sibling*,
/// leaving a tree that is still well formed and lossless while its shape is silently wrong. So the
/// stream is normalized by replaying it against a stack, which resolves both defects at the point
/// where they actually occur.
///
/// This is a repair, not a licence to leak: [`crate::parser::EventStreamAudit`] still reports every
/// node the grammar failed to close, and the tests assert it stays empty.