big_code_analysis_ast/roles/bash.rs
1//! Bash'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::lang_helpers::bash::bash_test_connective;
9use crate::lang_helpers::case_arms::bash_case_item_is_bare_wildcard;
10use crate::role_table;
11use crate::{Ancestors, Bash, Node};
12
13/// Whether a `case_item` is a decision arm rather than the `*)`
14/// catch-all: exactly one `value` field spelling `*` (lesson 11, #469).
15/// `a|b)` and `*|b)` are not bare and still count.
16fn is_decision_item(node: &Node<'_>, code: &[u8]) -> bool {
17 !bash_case_item_is_bare_wildcard(node, code)
18}
19
20/// Whether a `test_operator` is a comparison rather than one of the
21/// `-a` / `-o` connectives: the grammar gives `-z`, `-n`, `-eq`, `-lt`,
22/// `-a`, `-o`, … one kind, so only the bytes tell them apart (#1536).
23fn is_test_comparison<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool {
24 ancestors
25 .parent(node)
26 .is_none_or(|parent| bash_test_connective(node, &parent, code).is_none())
27}
28
29/// Whether a `test_operator` is an `-a` / `-o` connective.
30fn is_test_connective<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool {
31 ancestors
32 .parent(node)
33 .is_some_and(|parent| bash_test_connective(node, &parent, code).is_some())
34}
35
36/// Whether a `binary_expression`'s `operator` field is one of the
37/// `Comparison` payers, with a `test_operator` read for its bytes.
38fn comparison_operator(node: &Node<'_>, code: &[u8]) -> bool {
39 comparison::project(node).is_some_and(|op| {
40 comparison::PAYERS.contains(&op.kind_id())
41 && (op.kind_id() != Bash::TestOperator as u16
42 || bash_test_connective(&op, node, code).is_none())
43 })
44}
45
46/// Whether a `binary_expression`'s `operator` field is a short-circuit
47/// payer, with a `test_operator` read for its bytes.
48fn short_circuit_operator(node: &Node<'_>, code: &[u8]) -> bool {
49 short_circuit::project(node).is_some_and(|op| {
50 let kind = op.kind_id();
51 if kind == Bash::TestOperator as u16 {
52 bash_test_connective(&op, node, code).is_some()
53 } else {
54 short_circuit::PAYERS.contains(&kind)
55 }
56 })
57}
58
59/// Whether a `command` is the `return` or `exit` builtin, by the text of
60/// its `name` field. Invalid UTF-8 reads as no match.
61fn return_or_exit(node: &Node<'_>, code: &[u8]) -> bool {
62 node.child_by_field_name("name")
63 .is_some_and(|name| matches!(name.utf8_text(code), Some("return" | "exit")))
64}
65
66role_table! {
67 lang: Bash;
68 // Every command is a call: Bash has no other call kind, and the
69 // `command` node covers the builtin, the function and the external
70 // program alike.
71 Call { owns [Command] }
72 // The heredoc body is `HeredocBody2`: tree-sitter-bash 0.25.1 emits
73 // only that `heredoc_body` parser-node symbol in observed trees; the
74 // duplicate `HeredocBody` entry plus the hidden `_heredoc_body`
75 // (`HeredocBody3`) and `_simple_heredoc_body` (`SimpleHeredocBody`)
76 // rules never surface and are left out. An expanding string
77 // `wraps` the four expansion kinds, whose inner names are billed on
78 // their own (#180); `raw_string` and `ansi_c_string` cannot expand,
79 // and the `translated_string` (`$"…"`) is one `$` and a `string`
80 // child that is the keeper in argument position (#1358), so the
81 // operand arm bills the child rather than the wrapper.
82 StringLit {
83 owns [String, RawString, AnsiCString, TranslatedString, HeredocBody2]
84 wraps [SimpleExpansion, Expansion, CommandSubstitution, ArithmeticExpansion]
85 }
86 // A comparison inside `[[ … ]]` / `(( … ))` is a `binary_expression`
87 // (`BinaryExpression3` at the pinned grammar; the four siblings are
88 // listed defensively) owning one of `==` `!=` `<=` `>=` `=~`, or `<`
89 // / `>` under that parent (any alias) since the same two tokens
90 // spell an I/O redirection (`cmd > out`, `read x < in`), which the
91 // grammar parents under `file_redirect` (#1280). Inside `[ … ]` the
92 // comparison is a `test_operator` —
93 // `-eq`, `-lt`, `-z`, `-n`, … — one kind the grammar shares with the
94 // `-a` / `-o` connectives, so that payer is text-gated: a
95 // `test_operator` pays as a comparison exactly when its bytes are
96 // not a connective — and so is the owner, whose gate reads the same
97 // bytes off its `operator` field (#1863). `=` compares inside a test
98 // and assigns inside `(( … ))`, which only the test's descent can
99 // tell (#1536); the ABC consumer counts it from the test, as its own
100 // extra.
101 Comparison {
102 owns [
103 BinaryExpression(text_gated_by comparison_operator no_chain),
104 BinaryExpression2(text_gated_by comparison_operator no_chain),
105 BinaryExpression3(text_gated_by comparison_operator no_chain),
106 BinaryExpression4(text_gated_by comparison_operator no_chain),
107 BinaryExpression5(text_gated_by comparison_operator no_chain),
108 ]
109 pays [
110 EQEQ, BANGEQ, LTEQ, GTEQ, EQTILDE,
111 LT under [
112 BinaryExpression, BinaryExpression2, BinaryExpression3, BinaryExpression4,
113 BinaryExpression5,
114 ],
115 GT under [
116 BinaryExpression, BinaryExpression2, BinaryExpression3, BinaryExpression4,
117 BinaryExpression5,
118 ],
119 TestOperator text_gated_by is_test_comparison,
120 ]
121 project "operator"
122 }
123 // `&&` / `||` join two commands in a `list` and two tests inside
124 // `[[ … ]]` / `(( … ))` in a `binary_expression`; inside `[ … ]` the
125 // same join is the `-a` / `-o` spelling of `test_operator`, read by
126 // text, at the payer and at the owner alike. Bash's `&&` / `||` are
127 // command-list separators, so the ABC consumer reads this row for
128 // nothing (#1536 — Fitzpatrick Rule 9 does not map onto its grammar)
129 // where cyclomatic and cognitive read it.
130 ShortCircuit {
131 owns [
132 List,
133 BinaryExpression(text_gated_by short_circuit_operator no_chain),
134 BinaryExpression2(text_gated_by short_circuit_operator no_chain),
135 BinaryExpression3(text_gated_by short_circuit_operator no_chain),
136 BinaryExpression4(text_gated_by short_circuit_operator no_chain),
137 BinaryExpression5(text_gated_by short_circuit_operator no_chain),
138 ]
139 pays [AMPAMP, PIPEPIPE, TestOperator text_gated_by is_test_connective]
140 project "operator"
141 }
142 // `-a` / `-o` inside `[ ]` are arguments to the `test` builtin,
143 // which evaluates both sides (`[ 1 -eq 2 -a nope -eq 1 ]` still
144 // complains about `nope`), so by the language they are eager. Every
145 // consumer scores them as the `[[ … && … ]]` twin they spell
146 // (#1536), so they are the `ShortCircuit` row's text-gated payer
147 // above: a policy this package records and does not move. The
148 // bitwise `&` / `|` / `^` inside `(( … ))` are the only other
149 // candidates, and are integral.
150 EagerLogical {
151 owns []
152 excludes [
153 TestOperator "`-a` / `-o` are scored as the `&&` / `||` they spell (#1536), so the \
154 `ShortCircuit` row claims them; the builtin's eager evaluation is recorded here",
155 ]
156 }
157 // The arithmetic `(( a ? b : c ))` is Bash's only ternary: the
158 // `ternary_expression` owns it (`TernaryExpression2` is the second
159 // id carrying the kind, listed per grammar-dispatch §1 and
160 // unreachable at the pinned grammar) and its `?` pays, gated to that
161 // owner since `${y?msg}` spells the same token. `QMARK2` is the
162 // grammar's second `?` id, which no spelling at the pinned grammar
163 // emits — `bash_ternary_expression_alias_is_unreachable` in the
164 // cyclomatic tests pins that beside the owner alias — so it is
165 // recorded as considered rather than paid; the getter still bills
166 // it as the operator it names, should a bump start emitting it.
167 Ternary {
168 owns [TernaryExpression, TernaryExpression2]
169 pays [QMARK under [TernaryExpression, TernaryExpression2]]
170 project "operator"
171 excludes [QMARK2 "the second `?` id, which no spelling at the pinned grammar emits"]
172 }
173 NullSafe { absent "Bash has no optional navigation or null coalescing" }
174 // A `case_item` (`CaseItem2` the second id carrying the kind, per
175 // grammar-dispatch §1) owns a decision and pays at the node — the
176 // arm has no keyword; `case` and `esac` are the statement's and bill
177 // as the keywords they are — unless its sole pattern is `*`, the
178 // catch-all (lesson 11, #469), which only the bytes tell.
179 CaseArm {
180 owns [CaseItem(text_gated_by is_decision_item no_chain), CaseItem2(text_gated_by is_decision_item no_chain)]
181 }
182 Guard { absent "Bash has no guard clause; a `case` pattern is a glob, not a condition" }
183 // Bash counts statement nodes, so every row here is plain (#1697).
184 Branch { owns [IfStatement] }
185 Switch { owns [CaseStatement] }
186 // `for x in …`, the C-style `for ((…))`, `while` and `until` (one
187 // `while_statement` kind for both).
188 Loop { owns [ForStatement, CStyleForStatement, WhileStatement] }
189 Catch { absent "Bash has no exception handling; `trap` is a command" }
190 // The grammar gives `elif` a clause node of its own, a direct child of
191 // the `if_statement`, so the clause *is* the else-if and pays for
192 // itself; no nested `if` is ever an else-if here.
193 ElseIf { owns [ElifClause(pays_itself)] pays [] }
194 // Bash has no `return_statement` node: `return` and `exit` are
195 // ordinary builtins parsed as a `command` whose `name` field is a
196 // `command_name`, told by text.
197 Exit { owns [Command(text_gated_by return_or_exit no_chain)] }
198 Modifier { absent "Bash declares with builtins (`local`, `readonly`), which are commands, not \
199 modifier keywords" }
200 // The declaration builtins the grammar gives a kind of their own:
201 // `function`, and `local` / `declare` / `typeset` / `export` /
202 // `readonly`, each the leaf of a `declaration_command` or a
203 // `function_definition`, neither listed. `unset` / `unsetenv` are
204 // the inverse and bill with the commands.
205 DeclKeyword { owns [Function, Local, Declare, Typeset, Export, Readonly] }
206 Primitive { absent "Bash has no type names" }
207 FuncOpener { owns [FunctionDefinition(callable opens Function)] }
208 Container { owns [Program(opens Unit)] }
209 Closure { absent "Bash has no anonymous function" }
210 Member { absent "Bash has no container to hold a member" }
211 // The one comment kind. The grammar marks no comment as
212 // documentation, and no convention a tool reads over a comment run
213 // (shdoc's `# @description` blocks) is recognised here, so the six
214 // documentation rows are absent — unsupported, not nonexistent —
215 // and `is_comment` is this row's kind table alone (#1699).
216 Comment { owns [Comment] }
217 DocComment { absent "the grammar marks no comment as documentation; no tool's convention is read" }
218 Docstring { absent "Bash documents with comments, not string literals" }
219 DocTarget { absent "no comment is recognised as documentation, so nothing is its target" }
220 DocRunOpener { absent "no comment-run convention (shdoc) is recognised" }
221 DocRunDirective { absent "no comment-run convention (shdoc) is recognised" }
222 DocBodyResidual { absent "no kind holds documentation in a body beyond the function" }
223}
224
225#[cfg(test)]
226mod tests {
227 use super::*;
228 use crate::BashCode;
229 use crate::test_support::for_each_node_with_chain;
230
231 // The `Ternary` row's `?` is the arithmetic ternary's alone: an
232 // expansion's `${y?msg}` spells the same bare token and pays
233 // nothing, and `$?` is a token of its own (#1695). ABC reads the
234 // row at its wrapper and Halstead's byte-less arm keeps billing the
235 // expansion's `?`, so this is the one place the payer gate is
236 // observed.
237 #[cfg(feature = "bash")]
238 #[test]
239 fn ternary_pays_at_the_arithmetic_question_mark_only() {
240 let source = b"c=$(( a ? b : x ))\necho ${y?msg} $?\n";
241 let (mut owned, mut paid) = (Vec::new(), Vec::new());
242 for_each_node_with_chain::<BashCode>(source, |node, chain| {
243 let ancestors = Ancestors::known(chain);
244 let text = || node.utf8_text(source).expect("fixture is UTF-8").to_owned();
245 if ternary::owns(node, source, ancestors) {
246 owned.push(text());
247 }
248 if ternary::pays_at_leaf(node, source, ancestors) {
249 paid.push((node.start_byte(), text()));
250 }
251 });
252 assert_eq!(owned, ["a ? b : x"]);
253 assert_eq!(paid, [(8, "?".to_owned())]);
254 }
255
256 // The `Comparison` and `ShortCircuit` owner gates read the one
257 // `test_operator` kind for its bytes, as the payer gates do: a
258 // `binary_expression` holding `-lt` / `-gt` owns a comparison and
259 // one holding `-a` / `-o` owns a chain, never both. The consumers
260 // read these rows at the token, so only this pins the owner side,
261 // and each payer's parent is held to its own row. The first test's
262 // operators nest left — `(($a -lt $b) -a $c) -gt 1` — so its
263 // outermost node holds `-gt` and the chain is its left operand; the
264 // `=` of the second is the `EQ` kind, which the row leaves to the
265 // consumer (#1536), so that node owns nothing. (`-a` / `-o` are
266 // `[ ]`'s; inside `[[ ]]` they are a syntax error.)
267 #[cfg(feature = "bash")]
268 #[test]
269 fn test_operators_sort_their_owners_by_their_bytes() {
270 let source = b"if [ $a -lt $b -a $c -gt 1 ]; then :; fi\n\
271if [ \"$s\" = x -o \"$t\" != y ]; then :; fi\n";
272 let mut owned: [Vec<String>; 2] = Default::default();
273 let mut paid: [Vec<String>; 2] = Default::default();
274 for_each_node_with_chain::<BashCode>(source, |node, chain| {
275 let ancestors = Ancestors::known(chain);
276 let text = || node.utf8_text(source).expect("fixture is UTF-8").to_owned();
277 let rows = [
278 (
279 comparison::owns(node, source, ancestors),
280 comparison::pays_at_leaf(node, source, ancestors),
281 ),
282 (
283 short_circuit::owns(node, source, ancestors),
284 short_circuit::pays_at_leaf(node, source, ancestors),
285 ),
286 ];
287 assert!(!(rows[0].0 && rows[1].0), "{}", text());
288 assert!(!(rows[0].1 && rows[1].1), "{}", text());
289 for (row, (owns, pays)) in rows.into_iter().enumerate() {
290 if owns {
291 owned[row].push(text());
292 }
293 if pays {
294 paid[row].push(text());
295 // The payer's parent is the owner, asked with the
296 // chain above it.
297 let (parent, above) = chain.split_last().expect("a payer has a parent");
298 let row_owns = [comparison::owns, short_circuit::owns][row];
299 assert!(
300 row_owns(parent, source, Ancestors::known(above)),
301 "{}",
302 text()
303 );
304 }
305 }
306 });
307 assert_eq!(
308 owned[0],
309 ["$a -lt $b -a $c -gt 1", "$a -lt $b", "x -o \"$t\" != y"]
310 );
311 assert_eq!(owned[1], ["$a -lt $b -a $c", "x -o \"$t\""]);
312 assert_eq!(paid[0], ["-lt", "-gt", "!="]);
313 assert_eq!(paid[1], ["-a", "-o"]);
314 }
315}