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
409
410
411
412
413
414
//! Kotlin'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::getter::node_text;
use crate::lang_helpers::case_arms::kotlin_when_entry_is_else;
use crate::lang_helpers::doc_comment::kotlin_doc;
use crate::role_table;
use crate::roles::control_flow::else_if_prev_sibling_gate;
use crate::{Ancestors, Kotlin, Node, Search};

/// Whether `node`, a modifier keyword leaf, sits in a modifier list the
/// grammar built (#1558), rather than in the recovery of a soft-keyword
/// *name* it failed to parse. Each modifier is a soft keyword that
/// valid Kotlin may use as a name, and where kotlin-ng fails to parse
/// that name the leaf survives in its recovery; such a leaf is no
/// modifier and bills nothing (`kotlin_modifiers_are_operators_1558`
/// in `metrics/halstead.rs` pins both). Two recoveries strand the leaf:
///
/// - an `ERROR` holds it, usually still wrapped in its `*_modifier`
///   node (`open = !open` at statement start, `val suspend = 1`), so the
///   first ancestor above the wrappers is the `ERROR`;
/// - a modifier list is followed by an inserted, zero-width name
///   (`fun f(vararg: Int)`, `class C(open: Int)`).
///
/// Kinds are compared by name: `*_modifier` covers every wrapper, and
/// `user_type` is where recovery can hang `type_modifiers`. The inserted
/// name is found by width, not `is_missing()` (grammar-dispatch).
///
/// The search for the host reads three ancestors at most (#1868). The
/// grammar puts none of the skipped kinds under a `*_modifier` wrapper
/// or under `type_modifiers`, and only `type_modifiers` under a
/// `user_type`, so the longest run of them is those two;
/// `the_kinds_between_a_modifier_and_its_host_nest_two_deep_at_most`
/// reads that off the pinned grammar.
fn modifier_was_written_as_one<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> bool {
    let host = ancestors
        .iter(node)
        .map(|(ancestor, _)| ancestor)
        .find(|ancestor| !wraps_a_modifier(ancestor.kind()));
    host.is_some_and(|host| !host.is_error()) && !next_token_is_inserted(node, ancestors)
}

/// Whether `kind` can sit between a modifier keyword and its host: a
/// `*_modifier` wrapper, or `type_modifiers` and the `user_type`
/// recovery can hang it on.
fn wraps_a_modifier(kind: &str) -> bool {
    kind.ends_with("_modifier") || kind == "type_modifiers" || kind == "user_type"
}

/// Whether the first token after `node`, comments aside, is zero-width:
/// one error recovery inserted where the source has none. A comment
/// between the two is a sibling extra, so `vararg /*c*/: Int` must step
/// over it to reach the inserted name, as `vararg: Int` does. A node
/// never opens with an extra, which the parser hangs on the level above,
/// so the descent takes each first child as it is.
///
/// Every parameter's modifier asks, and the climb reaches
/// `function_value_parameters`, so the sibling is found without a scan
/// from the list's start: that made a long parameter list quadratic.
///
/// Both loops are linear over a walk (#1868). The climb starts at a
/// modifier keyword, which is a leaf, and passes a level only from its
/// last child, so one modifier climbs through each ancestor. The descent
/// starts at a node that follows another and steps through first
/// children only, so no two descents share a node.
fn next_token_is_inserted<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> bool {
    std::iter::once((*node, ancestors))
        .chain(ancestors.iter(node))
        .find_map(|(level, level_ancestors)| {
            level_ancestors
                .siblings_after(&level)
                .find(|sibling| !sibling.is_extra())
        })
        .is_some_and(|mut next| {
            while let Some(first) = next.child(0) {
                next = first;
            }
            next.start_byte() == next.end_byte()
        })
}

/// Whether an `infix_expression` applies one of the eager boolean
/// functions `and` / `or` / `xor`. tree-sitter-kotlin-ng gives an infix
/// call no field and no operator kind: it is three children — the left
/// operand, which may be any expression, an `identifier` leaf spelling
/// the function's name, and the right operand — so only the bytes tell
/// `a and b` from `a shl b` or `a to b`, and the name is the second
/// child that is not a comment. The name is all that is read: a user
/// `infix fun and` on another type, or `Int.and`, spells the same call,
/// which no syntax can tell from `Boolean.and`.
fn eager_infix(node: &Node<'_>, code: &[u8]) -> bool {
    node.children()
        .filter(|child| !child.is_extra())
        .nth(1)
        .filter(|name| name.kind_id() == Kotlin::Identifier as u16)
        .and_then(|name| node_text(code, &name))
        .is_some_and(|name| matches!(name, "and" | "or" | "xor"))
}

/// Whether a `when_entry` is a case-style arm rather than the `else ->`
/// fallback, which has no `condition` field (lesson 11, #469).
fn is_case_entry(node: &Node<'_>) -> bool {
    !kotlin_when_entry_is_else(node)
}

/// Which space a `class_declaration` opens: the grammar models classes
/// and interfaces under one node with the discriminating keyword as a
/// direct child token, so an `interface` token makes it `Interface`
/// and anything else `Class`.
fn class_or_interface(node: &Node<'_>) -> crate::SpaceKind {
    if node.first_child(|id| id == Kotlin::Interface).is_some() {
        crate::SpaceKind::Interface
    } else {
        crate::SpaceKind::Class
    }
}

// `else if` is an `if_expression` whose previous sibling is the bare `else`
// token — no clause wrapper — so a nested `if` under `else { … }` follows
// `{` instead (#1697).
else_if_prev_sibling_gate!(Kotlin, Else);

// Whether a block comment opens with the KDoc marker — `/**`, any but
// the empty `/**/` — read from the bytes. KDoc has no line form.
crate::roles::byte_gate!(opens_with_kdoc_marker, kotlin_doc);

role_table! {
    lang: Kotlin;
    // A `callable_reference` (`::f`) names a function and calls nothing.
    Call { owns [CallExpression] }
    // Both literal kinds `wraps` the long `${expr}` interpolation; the
    // short `$name` form has no node of its own — it is adjacent `$` and
    // `string_content` tokens the operand arm reads by bytes (#454) —
    // so the row cannot name it and the getter keeps that half.
    StringLit { owns [StringLiteral, MultilineStringLiteral] wraps [Interpolation] }
    // A `binary_expression` owns a comparison through its `operator`
    // field, with `<` / `>` gated to that parent; the type test
    // `is_expression` and the membership test `in_expression` own
    // theirs through their keyword, each a token of its own in both
    // the positive and the negated spelling (`is` / `!is`, `in` /
    // `!in`) and gated to the expression, since the `when` entry forms
    // `is Int ->` / `in xs ->` and the `for` header spell the same
    // keywords. The safe cast `as?` is a decision the ABC consumer
    // counts beside these, but no comparison; it stays its own arm.
    Comparison {
        owns [
            BinaryExpression(holds_payer),
            IsExpression, InExpression,
        ]
        pays [
            EQEQ, EQEQEQ, BANGEQ, BANGEQEQ, LTEQ, GTEQ,
            LT under BinaryExpression, GT under BinaryExpression,
            Is under IsExpression, BANGis under IsExpression,
            In under InExpression, BANGin under InExpression,
        ]
        project "operator"
    }
    // `&&` / `||`, which the grammar emits only under a
    // `binary_expression`. The elvis `?:` is `NullSafe`'s, and the
    // infix `and` / `or` / `xor` are `EagerLogical`'s.
    ShortCircuit {
        owns [BinaryExpression(holds_payer)]
        pays [AMPAMP, PIPEPIPE]
        project "operator"
    }
    // The infix functions `and` / `or` / `xor` evaluate both operands
    // (`Boolean.and` is a function, not the `&&` operator), so the
    // decision-counting consumers add no chain increment for them: a
    // slot holding one pays under the ordinary slot rule, as it would
    // for any call. The grammar spells the name as a plain `identifier`
    // inside the `infix_expression`, which Halstead bills as an operand
    // and keeps billing — the row records the construct and nothing
    // reads it to count (#1695). Owner-only and text-gated, since
    // claiming `Identifier` as a payer would claim every name.
    EagerLogical { owns [InfixExpression(text_gated_by eager_infix no_chain)] }
    Ternary { absent "Kotlin has no ternary operator; `if` is an expression" }
    // Two structural forms (#436): the elvis `a ?: b`, a
    // `binary_expression` owned through its `operator` field, and the
    // safe navigation `a?.b`, whose `?.` sits in a
    // `navigation_expression` beside the plain `.`, so the owner is
    // gated on holding one. Which of the two each consumer scores is
    // the consumer's to say (`src/metrics/{abc,cyclomatic}/kotlin.rs`).
    // The not-null assertion `!!` is a postfix on its operand, not a
    // navigation, and is on no row.
    NullSafe {
        owns [
            BinaryExpression(holds_payer),
            NavigationExpression(holds_payer),
        ]
        pays [QMARKCOLON, QMARKDOT]
        project "operator"
        excludes [BANGBANG "`a!!` throws on null rather than branching; an operator, no decision"]
    }
    // A `when_entry` owns a decision and pays at the node — the grammar
    // gives the arm no keyword of its own; its `->` is punctuation —
    // unless it is the `else ->` fallback, told by the absence of a
    // `condition` field (lesson 11, #469). A subject-ful entry's `is` /
    // `in` tests are the entry's, not the `Comparison` row's.
    CaseArm { owns [WhenEntry(gated_by is_case_entry no_chain)] }
    Guard { absent "Kotlin 2.x's `when` guards are not in the pinned grammar; `if` is an expression" }
    // Kotlin counts expression / statement nodes, so every row here is
    // plain (#1697).
    Branch { owns [IfExpression] }
    Switch { owns [WhenExpression] }
    Loop { owns [ForStatement, WhileStatement, DoWhileStatement] }
    Catch { owns [CatchBlock] }
    // Kotlin spells `else if` as Java does: an `if_expression` whose
    // previous sibling is the bare `else` token. Recognition only; the
    // `Else` token pays cognitive's +1 and the expression `Branch`'s.
    ElseIf { owns [IfExpression(gated_by follows_else_keyword)] pays [] }
    Exit { owns [ReturnExpression, ThrowExpression] }
    // Every modifier keyword, billed as C# bills all of its own (#1558;
    // Java and Groovy bill only some, #1565). Each is the keyword leaf;
    // its `*_modifier` / `modifiers` wrappers stay unlisted, so one
    // modifier bills once (grammar-dispatch section 5). Every keyword
    // has exactly one kind, so `kind_id` keys it without splitting it
    // across the two `n1` maps. `Annotation2` is the `annotation` of
    // `annotation class`; `Annotation` is an `@N` use, which is no
    // keyword. `in` is the variance modifier and the `for` / `x in y`
    // operator in one kind and bills with the operators, so `out` alone
    // is here. `reified` has only the `ReificationModifier` kind, which
    // `KotlinCode::is_primitive` keys by its text. Each word but
    // `companion` is a soft keyword gated on having been written as a
    // modifier: `companion` never parses as a name, and gating it would
    // only drop a real `companion object` from a class body that failed
    // to parse.
    Modifier {
        owns [
            Enum(gated_by modifier_was_written_as_one),
            Sealed(gated_by modifier_was_written_as_one),
            Annotation2(gated_by modifier_was_written_as_one),
            Data(gated_by modifier_was_written_as_one),
            Inner(gated_by modifier_was_written_as_one),
            Value(gated_by modifier_was_written_as_one),
            Public(gated_by modifier_was_written_as_one),
            Private(gated_by modifier_was_written_as_one),
            Protected(gated_by modifier_was_written_as_one),
            Internal(gated_by modifier_was_written_as_one),
            Abstract(gated_by modifier_was_written_as_one),
            Final(gated_by modifier_was_written_as_one),
            Open(gated_by modifier_was_written_as_one),
            Override(gated_by modifier_was_written_as_one),
            Lateinit(gated_by modifier_was_written_as_one),
            Const(gated_by modifier_was_written_as_one),
            Tailrec(gated_by modifier_was_written_as_one),
            Operator(gated_by modifier_was_written_as_one),
            Infix(gated_by modifier_was_written_as_one),
            Inline(gated_by modifier_was_written_as_one),
            External(gated_by modifier_was_written_as_one),
            Suspend(gated_by modifier_was_written_as_one),
            Vararg(gated_by modifier_was_written_as_one),
            Noinline(gated_by modifier_was_written_as_one),
            Crossinline(gated_by modifier_was_written_as_one),
            ReificationModifier(gated_by modifier_was_written_as_one),
            Out(gated_by modifier_was_written_as_one),
            Expect(gated_by modifier_was_written_as_one),
            Actual(gated_by modifier_was_written_as_one),
            Companion,
        ]
    }
    // `class`, `interface` (#1556), `fun`, `object`, `val`, `var` and
    // `typealias` (#1564), each the leaf of an unlisted
    // `class_declaration` / `function_declaration` / `object_declaration`
    // / `property_declaration` / `type_alias` wrapper. `typealias` is a
    // hard keyword.
    DeclKeyword { owns [Class, Interface, Fun, Object, Val, Var, Typealias] }
    Primitive { absent "Kotlin's built-in types are ordinary type names (`Int`, `String`)" }
    // A function and either constructor are the callables. The primary
    // constructor is the `primary_constructor` child of the class
    // declaration — the optional `constructor` keyword and its
    // modifiers plus the `class_parameters` list — a sibling of the
    // `class_body` and of the `delegation_specifiers` holding the
    // superclass call, so the call is outside it (#1828). A
    // property accessor (`get()` / `set(v)`) and `init { … }` carry
    // executable code and open a space (#1184) without being callable:
    // in Kotlin one writes `p.foo`, not `p.getFoo()`, and a callable
    // accessor would have the method count score a property twice. A
    // lambda and an anonymous `fun` are closures that open no space —
    // the walk never promoted one (`is_func_space` left both out), even
    // though the byte-less `get_space_kind` labelled them `Function` if
    // asked, the "pair that fails quietly" of grammar-dispatch §7; the
    // row records the walk's answer, as Java's does.
    FuncOpener {
        owns [
            FunctionDeclaration(callable opens Function),
            PrimaryConstructor(callable opens Function),
            SecondaryConstructor(callable opens Function),
            Getter(opens Function),
            Setter(opens Function),
            AnonymousInitializer(opens Function),
        ]
    }
    Closure { owns [LambdaLiteral, AnonymousFunction] }
    // One `class_declaration` kind spells a class and an interface,
    // told apart by the keyword token (`class_or_interface`). A named
    // or companion object and an object literal (`object : T { … }`,
    // #463) are class-like singletons.
    Container {
        owns [
            SourceFile(opens Unit),
            ClassDeclaration(opens_by class_or_interface no_chain),
            ObjectDeclaration(opens Class),
            CompanionObject(opens Class),
            ObjectLiteral(opens Class),
        ]
    }
    // A property declaration in a class body — `val a = 1`, or a
    // destructuring `val (a, b) = …` the consumer counts by variable.
    Member { owns [PropertyDeclaration] }
    // The two comment kinds; KDoc has no line form, so only the block
    // comment is a `DocComment` owner, under the marker gate (#1699).
    Comment { owns [LineComment, BlockComment] }
    DocComment { owns [BlockComment(text_gated_by opens_with_kdoc_marker no_chain)] }
    Docstring { absent "Kotlin documents with KDoc comments, not string literals" }
    // The declarations Dokka documents. The package directive binds no
    // comment (`BindFirstShebangWithWhitespaceOnly`), an import none,
    // and an `init` block has no page to carry one. Outside the
    // space-tree rows: the type alias, the enum entry and the two
    // parameter kinds (a primary constructor's `val` parameter is a
    // property Dokka documents) — the parity exceptions
    // `roles/doc_tests/parity.rs` records.
    DocTarget {
        owns [
            ClassDeclaration,
            ObjectDeclaration,
            CompanionObject,
            FunctionDeclaration,
            PropertyDeclaration,
            TypeAlias,
            SecondaryConstructor,
            EnumEntry,
            Parameter,
            ClassParameter,
        ]
    }
    DocRunOpener { absent "Dokka attaches every KDoc to a declaration; none documents by its own content" }
    DocRunDirective { absent "Dokka reads no directive comment" }
    // Beyond the callables and the closures: an accessor and an `init`
    // block open function spaces without being callees (#1184), and
    // Dokka reads a KDoc in them no more than one in a method. The
    // lambda literal is a `Closure` owner; that it holds a doc comment
    // *without* a body-child test is the Checker's refinement, not a
    // row entry.
    DocBodyResidual { owns [Getter, Setter, AnonymousInitializer] }
}

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

    // The infix eager functions are told from every other infix call by
    // their name alone (#1695): `and` / `or` / `xor` own the construct,
    // `shl` / `to` / a user infix do not. The row lists no payer — the
    // name is an `identifier` that nothing bills as an operator — so
    // the owner is the paying node at both projections, and no token
    // pays.
    #[cfg(feature = "kotlin")]
    #[test]
    fn eager_infix_is_told_by_its_name() {
        let source = b"fun f(a: Boolean, b: Boolean, x: Int) { val c = a and b; val d = a or b; val e = a xor b; val s = x shl 1; val p = 1 to 2; val m = a myInfix b; val n = (a && b) xor a; val o = a and /* c */ b and a; val q = (a) to and }\n";
        let (mut owned, mut paid) = (Vec::new(), Vec::new());
        for_each_node_with_chain::<KotlinCode>(source, |node, chain| {
            let ancestors = Ancestors::known(chain);
            let text = || node.utf8_text(source).expect("fixture is UTF-8").to_owned();
            if eager_logical::owns(node, source, ancestors) {
                owned.push(text());
            }
            if eager_logical::pays_at_leaf(node, source, ancestors) {
                paid.push(text());
            }
        });
        // A compound left operand, a comment before the name, a nested
        // chain (each `and` owns its own node) and a right operand
        // *named* `and`, which is no function.
        assert_eq!(
            owned,
            [
                "a and b",
                "a or b",
                "a xor b",
                "(a && b) xor a",
                "a and /* c */ b and a",
                "a and /* c */ b",
            ]
        );
        assert_eq!(paid, owned);
        assert_eq!(eager_logical::PAYERS, &[] as &[u16]);
    }

    /// `modifier_was_written_as_one` finds a modifier's host within
    /// three ancestors because the kinds it skips do not nest: the one
    /// pair the grammar allows is `type_modifiers` under `user_type`
    /// (#1868). A grammar bump that lets a wrapper hold a wrapper, or a
    /// `user_type` a `user_type`, makes that climb as long as the nest
    /// and must change this with it.
    // test-lang-gates: hand-written(kotlin) — reads the grammar crate's
    //     `NODE_TYPES`, which exists only under the `kotlin` feature
    #[cfg(feature = "kotlin")]
    #[test]
    fn the_kinds_between_a_modifier_and_its_host_nest_two_deep_at_most() {
        let nesting =
            crate::test_support::nesting_among(tree_sitter_kotlin_ng::NODE_TYPES, wraps_a_modifier);
        assert_eq!(
            nesting,
            [("user_type".to_owned(), ["type_modifiers".to_owned()].into())].into()
        );
    }
}