big-code-analysis-ast 2.6.0

Parse and classification layer behind big-code-analysis (internal, version-locked)
Documentation
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
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
//! Rust's role rows. The Halstead keyword roles (#1693), the
//! paying-construct roles — `Comparison`, `ShortCircuit`, `EagerLogical`,
//! `Ternary`, `CaseArm`, `Guard`, `NullSafe` (#1694, #1695) — the space
//! tree (#1696) and the control flow — `Branch`, `Switch`, `Loop`,
//! `Catch`, `ElseIf`, `Exit` (#1697) — and
//! the documentation rows (#1699) are declared.

use crate::lang_helpers::case_arms::pattern_is_bare_underscore;
use crate::role_table;
use crate::roles::control_flow::else_if_parent_clause_gate;
use crate::{Ancestors, Node, Rust};

// The chained `if` sits directly inside an `else_clause`; a nested one
// under `else { … }` sits inside the block (#1697).
else_if_parent_clause_gate!(Rust, ElseClause);

/// Whether a `match_arm` is a decision: its `pattern` is not a bare `_`
/// (lesson 11, #469). `Some(_)`, `(_, x)` and `_ if g` are not bare and
/// still count; a leading `|` of an or-pattern is skipped. The field is
/// required at the pinned grammar, so an arm without one — error
/// recovery only — counts, the polarity both consumers had (#1454).
fn is_decision_arm<'a>(node: &Node<'a>, _ancestors: Ancestors<'a, '_>) -> bool {
    !node
        .child_by_field_name("pattern")
        .is_some_and(|pat| pattern_is_bare_underscore(&pat, Rust::UNDERSCORE as u16))
}

/// Whether a `let_declaration` is `let PAT = e else { … }`: it carries
/// the `alternative` field. Read by field, not by the `else` token the
/// `if` expression also emits.
fn has_alternative(node: &Node<'_>) -> bool {
    node.child_by_field_name("alternative").is_some()
}

/// Whether a `for` keyword is a loop's and not type syntax (#1720): the
/// token's parent is not an `impl_item` (`impl T for S`), a
/// `higher_ranked_trait_bound` (`F: for<'a> Fn(&'a u8)`, in a generic
/// list or a `where` clause), a `for_lifetimes` (`for<'a> fn(&'a u8)`)
/// or an `abstract_type` (`impl for<'a> Fn(&'a u8)` in argument or
/// return position, where the grammar puts the token directly under the
/// `impl` type rather than under a bound). Read off the chain, so
/// `O(1)`. A `for` inside a macro's `token_tree` / `token_repetition`
/// has the tree as its parent and stays paid — a policy about opaque
/// macro bodies that applies to `if` / `while` / `loop` there too and
/// is pinned separately (`rust_macro_token_tree_keywords_score`).
fn not_in_type_syntax<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> bool {
    !ancestors.parent(node).is_some_and(|parent| {
        matches!(
            parent.kind_id().into(),
            Rust::ImplItem | Rust::HigherRankedTraitBound | Rust::ForLifetimes | Rust::AbstractType
        )
    })
}

/// Whether a `match_pattern` carries a guard: its `condition` field.
fn has_guard(node: &Node<'_>) -> bool {
    node.child_by_field_name("condition").is_some()
}

/// The marker tree-sitter-rust puts after the opening delimiter of
/// every doc form: the outer one for `///` and `/** */`, the inner one
/// for `//!` and `/*! */`. Each name has two ids, the block form's
/// token and the line form's non-terminal; the parser canonicalises
/// them, so written source reaches `kind_id()` as the base id and the
/// `2` aliases are defensive (grammar-dispatch section 1;
/// `doc_markers_reach_the_gate_as_the_base_ids` records which is
/// observed).
const DOC_MARKERS: [u16; 4] = [
    Rust::OuterDocCommentMarker as u16,
    Rust::OuterDocCommentMarker2 as u16,
    Rust::InnerDocCommentMarker as u16,
    Rust::InnerDocCommentMarker2 as u16,
];

/// Whether a comment carries the doc marker child tree-sitter-rust
/// opens every doc form with — `///`, `//!`, `/** */`, `/*! */` — and
/// leaves `////`, `/**/` and `/***/` without, so the bytes are never
/// consulted. The marker decides, not the `doc_comment` text node after
/// it: the empty `/*!*/` is an inner doc comment to rustc, and the
/// grammar gives it a marker and no text (#1890). A plain comment has
/// at most its two delimiters as children, so the count spares every
/// one of them the cursor the child scan allocates.
fn has_doc_marker_child(node: &Node<'_>) -> bool {
    node.child_count() > 2 && node.wraps_any(&DOC_MARKERS)
}

role_table! {
    lang: Rust;
    // A `macro_invocation` is not a call to this row, as before it.
    Call { owns [CallExpression] }
    // A `char_literal` is not a string, though the dump flattens it
    // beside the two (#391).
    StringLit { owns [StringLiteral, RawStringLiteral] }
    // The one `binary_expression` kind carries every binary operator;
    // its `operator` field says which, so the owner is gated on the
    // field and `<` / `>` on the parent: a generic list and a turbofish
    // spell the same tokens. The four other tokens occur nowhere else.
    Comparison {
        owns [BinaryExpression(holds_payer)]
        pays [
            EQEQ, BANGEQ, LTEQ, GTEQ,
            LT under BinaryExpression, GT under BinaryExpression,
        ]
        project "operator"
    }
    // A `binary_expression` whose operator is `&&` / `||`, and a Rust
    // 2024 let-chain (`if let Some(x) = a && b`) — `LetChain` the
    // visible alias, `LetChain2` the hidden `_let_chain` supertype —
    // whose `&&` tokens are its direct children, so the chain owns them
    // with no field to project through and the row's payer fallback
    // finds the first. The tokens pay ungated: the grammar spells them
    // bare only inside a macro's `token_tree` (`m!(a || b)`), where the
    // parser sees no expression and the counting consumers have always
    // paid them (an empty closure's `||` is two `|` tokens under
    // `closure_parameters`, not this kind).
    ShortCircuit {
        owns [
            BinaryExpression(holds_payer),
            LetChain, LetChain2,
        ]
        pays [AMPAMP, PIPEPIPE]
        project "operator"
    }
    // `&` / `|` / `^` on boolean operands evaluate both sides, but the
    // grammar emits them as the same `binary_expression` as the integral
    // forms, so the syntax alone cannot tell them apart; no consumer
    // treats them as a decision, and the three tokens bill as the
    // operators they are. A recognition boundary, recorded as the
    // kinds considered rather than as an absence.
    EagerLogical {
        owns []
        excludes [
            AMP "a boolean `&` is the integral `&`'s kind, which the grammar does not tell apart",
            PIPE "a boolean `|` is the integral `|`'s kind, which the grammar does not tell apart",
            CARET "a boolean `^` is the integral `^`'s kind, which the grammar does not tell apart",
        ]
    }
    Ternary { absent "Rust has no ternary operator; `if` is an expression" }
    NullSafe { absent "Rust has no optional navigation or null coalescing; `?` is an exit" }
    // A `match_arm` (`MatchArm2` the second id carrying the kind, per
    // grammar-dispatch §1) owns a decision and pays at the node — its
    // `=>` is punctuation — unless its pattern is a bare `_`, the
    // C-family `default:` (lesson 11, #469).
    CaseArm { owns [MatchArm(gated_by is_decision_arm), MatchArm2(gated_by is_decision_arm)] }
    // A match guard is the `match_pattern`'s `condition` field, opened
    // by an `if` keyword the grammar shares with the `if` expression;
    // the pattern owns it where the field is present and the keyword
    // pays, gated to the pattern. Cyclomatic counts that keyword
    // wherever it is written, so the guard pays as an `if` does; ABC
    // walks the field as a boolean slot.
    Guard {
        owns [MatchPattern(gated_by has_guard no_chain)]
        pays [If under MatchPattern]
    }
    // Rust counts keyword tokens (#284), so each row below pays at its
    // keyword. The `if` keyword is one kind for the `if` expression,
    // `if let`, and a match guard (the `Guard` row's payer, gated to the
    // pattern); cyclomatic counts it once wherever it is written, so the
    // two rows share the token and a consumer reads them as one. A
    // `let … else` either binds or diverges: one decision, as its `if
    // let` twin pays, told by the `alternative` field rather than the
    // `else` token the `if` expression also emits; it has no keyword of
    // its own to pay at, so the node pays (`pays_itself`).
    Branch {
        owns [IfExpression, LetDeclaration(pays_itself gated_by has_alternative no_chain)]
        pays [If]
    }
    // The `match` expression, the modified tier's container; its arms
    // are the `CaseArm` row's.
    Switch { owns [MatchExpression] }
    // `for`, `while` (and `while let`, the same kind) and `loop`, each
    // paid at its keyword. The `for` keyword is also type syntax —
    // `impl T for S`, `for<'a> Fn(…)`, `for<'a> fn(…)`, `impl for<'a>
    // Fn(…)` — which decides nothing and is declined by the payer's gate
    // (#1720); a `for` inside a macro's `token_tree` pays and stays paid.
    Loop {
        owns [ForExpression, WhileExpression, LoopExpression]
        pays [For gated_by not_in_type_syntax, While, Loop]
    }
    Catch { absent "Rust has no exception handling; `?` is an exit and `match` on a `Result` a switch" }
    // `else if` is an `if_expression` directly inside an `else_clause`,
    // as the C family spells it; a nested `if` under `else { … }` sits
    // inside the block. Recognition only: the chained `if`'s keyword is
    // `Branch`'s and the `else` token pays cognitive's +1.
    ElseIf { owns [IfExpression(gated_by continues_else_clause)] pays [] }
    // Explicit `return`, and `?`, which returns the error early (#243:
    // the implicit final expression is not an exit). `?` is also what
    // cyclomatic's `count_try` toggles; the row says it is an exit,
    // the option says whether it is a decision.
    Exit { owns [ReturnExpression, TryExpression] }
    // `pub` is the leaf of an unlisted `visibility_modifier`, so it
    // bills once whatever the `(crate)` / `(super)` qualifier; `mut` is
    // the grammar's `mutable_specifier` node, one kind for a binding,
    // a reference and a `self` receiver. `const` and `static` are each
    // one kind for the item and the qualifier (`const fn`, `static
    // ref`), as `unsafe`, `async`, `extern` and `move` are for theirs;
    // all bill once per spelling.
    Modifier {
        owns [Pub, MutableSpecifier, Const, Static, Unsafe, Async, Extern, Move, Dyn]
    }
    // The item keywords (#394): each the leaf of an unlisted `*_item`
    // / `let_declaration` / `where_clause` wrapper.
    DeclKeyword { owns [Fn, Let, Enum, Struct, Union, Trait, Impl, Use, Mod, Type, Where] }
    // tree-sitter-rust spells `primitive_type` as
    // `alias(choice(u8, i8, …, char), $.primitive_type)`: one generated
    // id per spelling, seventeen in all, every one named
    // `primitive_type`. The parser canonicalises them, so written source
    // reaches `kind_id()` as the base `PrimitiveType` and the sixteen
    // suffixed ids are defensive (grammar-dispatch section 1;
    // `rust_aliased_primitive_type_classification` records which is
    // observed). `Checker::is_primitive` keys each by text.
    Primitive {
        owns [
            PrimitiveType, PrimitiveType2, PrimitiveType3, PrimitiveType4, PrimitiveType5,
            PrimitiveType6, PrimitiveType7, PrimitiveType8, PrimitiveType9, PrimitiveType10,
            PrimitiveType11, PrimitiveType12, PrimitiveType13, PrimitiveType14, PrimitiveType15,
            PrimitiveType16, PrimitiveType17,
        ]
    }
    // A `fn` item opens a `Function` space and is the one callable; a
    // closure opens one too and is the `Closure` (Rust's closures open
    // spaces where Java's and Python's do not — the book's "which
    // lambdas open a space" paragraph is this row). `impl` and `trait`
    // blocks are the class-like containers; a `struct_item` is not a
    // space, so its fields land on the enclosing one (`npa/rust.rs`).
    FuncOpener { owns [FunctionItem(callable opens Function), ClosureExpression(opens Function)] }
    Closure { owns [ClosureExpression] }
    Container { owns [SourceFile(opens Unit), ImplItem(opens Impl), TraitItem(opens Trait)] }
    // A struct's named field, an `impl` or `trait` body's associated
    // `const` / `static`, and a trait's associated `type`. Which body a
    // member sits in, its visibility, and a tuple struct's positional
    // fields — which are type nodes, not declarations — stay with the
    // attribute consumer.
    Member { owns [FieldDeclaration, ConstItem, StaticItem, AssociatedType] }
    // The two comment kinds; either carries the grammar's doc marker
    // child in a doc form, so both are `DocComment` owners under a
    // *child* gate — the one `DocComment` row that reads structure
    // rather than bytes (#1699).
    Comment { owns [LineComment, BlockComment] }
    DocComment {
        owns [
            LineComment(gated_by has_doc_marker_child no_chain),
            BlockComment(gated_by has_doc_marker_child no_chain),
        ]
    }
    Docstring { absent "Rust documents with `///` comments, not string literals" }
    // What rustc's `unused_doc_comments` lint leaves alone: an item, an
    // associated or foreign item, a field or a variant. It lints a doc
    // comment on an extern block, a macro invocation, a statement, an
    // expression and a generic parameter, none of which is listed. A
    // tuple struct's field has no node of its own, so its first token
    // stands in — a clause over *any* named kind under
    // `ordered_field_declaration_list`, which no kind list spells and
    // which stays in `checker/rust.rs`. Outside the space-tree rows:
    // the module, enum, variant, type, `use`, `extern crate`, macro
    // definition and function signature — the parity exceptions
    // `roles/doc_tests/parity.rs` records.
    DocTarget {
        owns [
            ModItem,
            StructItem,
            UnionItem,
            EnumItem,
            EnumVariant,
            FieldDeclaration,
            ConstItem,
            StaticItem,
            TypeItem,
            FunctionItem,
            FunctionSignatureItem,
            ImplItem,
            TraitItem,
            AssociatedType,
            UseDeclaration,
            ExternCrateDeclaration,
            MacroDefinition,
        ]
    }
    DocRunOpener { absent "rustdoc attaches every doc comment to an item; none documents by its own content" }
    DocRunDirective { absent "rustdoc reads no directive comment" }
    // Nothing beyond the callables and the closure: rustc lints a doc
    // comment on a statement as unused and rustdoc renders no item
    // nested in a body, so the trait default holds, and the one
    // exception — an inner `//!` opening a function's body is that
    // function's own doc — is `Checker::doc_comment_opens_body`.
    DocBodyResidual { absent "only the callables and closures hold a doc comment in a body; the trait default" }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::RustCode;
    use crate::test_support::for_each_node_with_chain;

    // The `Guard` row owns a `match_pattern` exactly where it carries
    // a `condition`, and the guard's `if` pays under it. The one
    // consumer that reads the owner, ABC's arm walk, reads the
    // `condition` field again beside it, so an owner that admitted
    // every pattern scores the same there; the row is asked here.
    #[cfg(feature = "rust")]
    #[test]
    fn guard_owns_a_pattern_only_where_it_carries_a_condition() {
        let source = b"fn f(x: i32) -> i32 { match x { a if a > 0 => 1, b => b, _ => 0 } }\n";
        let (mut patterns, mut owned, mut paid) = (0, Vec::new(), Vec::new());
        for_each_node_with_chain::<RustCode>(source, |node, chain| {
            let ancestors = Ancestors::known(chain);
            let text = || node.utf8_text(source).expect("fixture is UTF-8").to_owned();
            if node.kind_id() == Rust::MatchPattern as u16 {
                patterns += 1;
            }
            if guard::owns(node, source, ancestors) {
                owned.push(text());
            }
            if guard::pays_at_leaf(node, source, ancestors) {
                paid.push(text());
            }
        });
        // Three arms, three patterns; only the first is guarded.
        assert_eq!(patterns, 3);
        assert_eq!(owned, ["a if a > 0"]);
        assert_eq!(paid, ["if"]);
    }

    // The marker of a line form and of a block form reach `kind_id()` as
    // the same base id, so the two `2` aliases in `DOC_MARKERS` are
    // defensive. The markers are selected by name, not through the
    // list, so a grammar that starts emitting an alias fails here.
    #[cfg(feature = "rust")]
    #[test]
    fn doc_markers_reach_the_gate_as_the_base_ids() {
        let source = b"/// a\n//! b\n/** c */\n/*! d */\n/*!*/\nfn f() {}\n";
        let mut markers = Vec::new();
        for_each_node_with_chain::<RustCode>(source, |node, chain| {
            if matches!(
                node.kind(),
                "outer_doc_comment_marker" | "inner_doc_comment_marker"
            ) {
                let comment = Ancestors::known(chain)
                    .parent(node)
                    .map(|parent| parent.kind());
                markers.push((comment, node.kind_id()));
            }
        });
        // expected: one marker per doc comment, in source order: outer
        // for `///` and `/** */`, inner for `//!`, `/*! */` and `/*!*/`.
        let (outer, inner) = (
            Rust::OuterDocCommentMarker as u16,
            Rust::InnerDocCommentMarker as u16,
        );
        assert_eq!(
            markers,
            [
                (Some("line_comment"), outer),
                (Some("line_comment"), inner),
                (Some("block_comment"), outer),
                (Some("block_comment"), inner),
                (Some("block_comment"), inner),
            ]
        );
    }

    // The `DocComment` gate reads a comment's child count before it
    // scans for the marker, so a plain comment builds no cursor
    // (`Node::children` records each one in `child_scan_cursors`). No
    // answer shows that: a scan finds no marker in a plain comment
    // either, so a gate that scanned every comment would own the same
    // nodes. The doc comments are scanned once each, which also shows
    // the counter counts.
    #[cfg(feature = "rust")]
    #[test]
    fn doc_comment_gate_scans_a_doc_comment_and_no_plain_one() {
        use crate::node::child_scan_cursors;

        let source = b"// a\n//// b\n/* c */\n/**/\n/***/\n/// d\n//! e\n/** f */\n/*! g */\n/*!*/\nfn f() {}\n";
        let mut asked = Vec::new();
        for_each_node_with_chain::<RustCode>(source, |node, chain| {
            let ancestors = Ancestors::known(chain);
            if !comment::owns(node, source, ancestors) {
                return;
            }
            let before = child_scan_cursors::observed();
            let doc = doc_comment::owns(node, source, ancestors);
            let scans = child_scan_cursors::observed() - before;
            let text = node.utf8_text(source).expect("fixture is UTF-8");
            asked.push((text.trim_end().to_owned(), doc, scans));
        });
        // expected: (comment, documentation, child scans). A plain
        // comment has one child (`//`) or two (`/*`, `*/`) and is
        // answered by the count. A doc comment has three (`//`, marker,
        // text; `/*`, marker, `*/`) or four and is scanned once.
        let expected = [
            ("// a", false, 0),
            ("//// b", false, 0),
            ("/* c */", false, 0),
            ("/**/", false, 0),
            ("/***/", false, 0),
            ("/// d", true, 1),
            ("//! e", true, 1),
            ("/** f */", true, 1),
            ("/*! g */", true, 1),
            ("/*!*/", true, 1),
        ];
        assert_eq!(
            asked,
            expected.map(|(text, doc, scans)| (text.to_owned(), doc, scans))
        );
    }
}