Skip to main content

big_code_analysis_ast/roles/
javascript.rs

1//! Javascript's role rows. The Halstead keyword roles (#1693), the
2//! paying-construct roles — `Comparison`, `ShortCircuit`, `EagerLogical`,
3//! `Ternary`, `CaseArm`, `Guard`, `NullSafe` (#1694, #1695) — the space
4//! tree (#1696) and the control flow — `Branch`, `Switch`, `Loop`,
5//! `Catch`, `ElseIf`, `Exit` (#1697) — and
6//! the documentation rows (#1699) are declared.
7
8use crate::Javascript;
9use crate::role_table;
10use crate::roles::control_flow::else_if_parent_clause_gate;
11use crate::roles::js_family::{
12    js_doc_gates, js_family_binding_gates, js_family_closures, js_family_comparison_payers,
13    js_family_containers, js_family_decl_keywords, js_family_doc_gates, js_family_doc_targets,
14    js_family_exits, js_family_func_openers, js_family_loops, js_family_modifiers,
15    js_family_short_circuit_payers, js_family_strings,
16};
17
18// The chained `if` sits directly inside an `else_clause`; a nested one
19// under `else { … }` sits inside the statement block (#1697).
20else_if_parent_clause_gate!(Javascript, ElseClause);
21js_family_binding_gates!(Javascript, JavascriptCode, FieldDefinition);
22
23// The documentation gates, per dialect (#1699): JSDoc ignores `/***`; plain JavaScript follows it.
24js_family_doc_gates!(Javascript, javadoc_block);
25js_doc_gates!(Javascript);
26
27role_table! {
28    lang: Javascript;
29    // Two `call_expression` ids at the pin; the second is the alias a
30    // decorator call takes, never emitted (probed with `bca dump` over
31    // `@dec(1)`), and listed defensively (grammar-dispatch §1).
32    Call { owns [CallExpression, CallExpression2] }
33    // `String2` (kind id 221) is JS's anonymous string-*literal* alias
34    // (e.g. the module string in `import "m"`), a string alongside
35    // `String` (#283).
36    StringLit { owns [..js_family_strings!(), String2] wraps [TemplateSubstitution] }
37    // The one `binary_expression` kind carries every binary operator;
38    // its `operator` field says which, so each row's owner holds its
39    // payer (`roles/js_family.rs` has the lists). `??` is `NullSafe`'s
40    // and `&&=` / `||=` are assignments.
41    Comparison {
42        owns [BinaryExpression(holds_payer)]
43        pays [..js_family_comparison_payers!()]
44        project "operator"
45    }
46    ShortCircuit {
47        owns [BinaryExpression(holds_payer)]
48        pays [..js_family_short_circuit_payers!()]
49        project "operator"
50    }
51    EagerLogical { absent "JavaScript's `&` / `|` / `^` are bitwise" }
52    // The `ternary_expression` owns it and its `?` pays, ungated: the
53    // JavaScript grammars spell the bare token nowhere else, and a `?`
54    // error recovery strands under an `ERROR` (`let c = a ?` at end of
55    // input) has always paid (the TypeScript grammars gate theirs, for
56    // the ten type productions `roles/js_family.rs` names).
57    Ternary {
58        owns [TernaryExpression]
59        pays [QMARK]
60        project "operator"
61    }
62    // Two structural forms, each one decision per token (#281, #248):
63    // the null coalescing `a ?? b`, a `binary_expression` owned through
64    // its `operator` field, and the optional chain `a?.b` / `a?.[0]` /
65    // `a?.()`, whose `?.` the JavaScript grammars emit as the bare
66    // `optional_chain` token (no wrapper) — the TypeScript grammars wrap
67    // it, and their rows say so. The compound `??=` is an
68    // `augmented_assignment_expression`, not a `binary_expression`: it
69    // stays the consumers' own, recorded here as considered.
70    NullSafe {
71        owns [BinaryExpression(holds_payer)]
72        pays [QMARKQMARK, OptionalChain]
73        project "operator"
74        excludes [QMARKQMARKEQ "the compound `??=`, an assignment ABC pays as one and a decision cyclomatic pays as its own (#236, #248)"]
75    }
76    // A `switch_case` owns a decision and its `case` keyword pays; the
77    // `switch_default` and its `default` keyword are the fallback and
78    // pay nothing (lesson 11, #469).
79    CaseArm {
80        owns [SwitchCase(holds_payer)]
81        pays [Case]
82        excludes [
83            SwitchDefault "the fallback arm, no decision (lesson 11, #469)",
84            Default "the fallback label's keyword",
85        ]
86    }
87    Guard { absent "JavaScript has no guard clause" }
88    // The JS family's control flow (#1697): the one-kind rows are spelled
89    // inline, the loop and exit lists are fragments of
90    // `roles/js_family.rs`, and no dialect has an extra — the four
91    // grammars share the shape and differ only in kind ids. The `ElseIf`
92    // gate is emitted beside this table.
93    Branch { owns [IfStatement] pays [If] }
94    Switch { owns [SwitchStatement] }
95    Loop { owns [..js_family_loops!()] pays [For, While] }
96    Catch { owns [CatchClause] pays [Catch] }
97    ElseIf { owns [IfStatement(gated_by continues_else_clause)] pays [] }
98    Exit { owns [..js_family_exits!()] }
99    // The shared JS-family `static` (`roles/js_family.rs`) plus
100    // `Staticget`, one token spelling `static get` followed by a
101    // newline — the static getter whose name starts the next line —
102    // which these two grammars alone have. It is billed beside `static`
103    // (#1563) so that form bills a modifier rather than nothing; being
104    // one node it is one operator.
105    Modifier { owns [..js_family_modifiers!(), Staticget] }
106    DeclKeyword { owns [..js_family_decl_keywords!()] }
107    Primitive { absent "JavaScript has no type names" }
108    // The shared JS-family openers, closures and containers
109    // (`roles/js_family.rs`); the binding gates are emitted above, with
110    // this grammar's class-field kind.
111    FuncOpener { owns [..js_family_func_openers!()] }
112    Closure { owns [..js_family_closures!()] }
113    Container { owns [..js_family_containers!()] }
114    // A class field (`x = v;`); one whose initialiser is a function is
115    // a method written as a field, which the consumers tell apart
116    // themselves — the row recognises the declaration, the consumer
117    // reads its value.
118    Member { owns [FieldDefinition] }
119    // The two comment kinds — a `/* */` or `//` `comment` and the Annex-B
120    // `<!-- -->` `html_comment` (#697); only the first can open with the
121    // tool's block marker (#1699).
122    Comment { owns [Comment, HtmlComment] }
123    DocComment { owns [Comment(text_gated_by opens_with_doc_block_marker no_chain)] }
124    Docstring { absent "JavaScript documents with JSDoc comments, not string literals" }
125    // What JSDoc's `astnode.getInfo` names: the family fragment, plus an
126    // export other than a bare `export { … }` list and an expression
127    // statement assigning to a name or a member. Every target but the
128    // class, method and field is outside the space-tree rows — the
129    // parity exceptions `roles/doc_tests/parity.rs` records.
130    DocTarget {
131        owns [
132            ..js_family_doc_targets!(),
133            UsingDeclaration(gated_by first_declarator_binds_a_name no_chain),
134            FieldDefinition,
135            ExportStatement(gated_by export_declares no_chain),
136            ExpressionStatement(gated_by assigns_to_a_name_or_member no_chain),
137        ]
138    }
139    DocRunOpener { absent "JSDoc attaches every doc comment to a declaration or a named symbol; none documents by its own content" }
140    DocRunDirective { absent "JSDoc reads no directive comment" }
141    // Nothing beyond the callables and the closures: JSDoc documents
142    // inner symbols (`outer~inner`), so a doc comment in a body stays
143    // documentation (`DOC_COMMENTS_IN_FUNCTION_BODIES`, #1597), and which
144    // child is the body — a statement block, an arrow's expression — is
145    // the Checker's body-child test, not a kind.
146    DocBodyResidual { absent "only the callables and closures hold a doc comment in a body; the body-child test is the Checker's" }
147}