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}