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. `=` compares inside a test and assigns inside
97 // `(( … ))`, which only the test's descent can tell (#1536); the
98 // ABC consumer counts it from the test, as its own extra.
99 Comparison {
100 owns [
101 BinaryExpression(gated_by comparison_operator no_chain),
102 BinaryExpression2(gated_by comparison_operator no_chain),
103 BinaryExpression3(gated_by comparison_operator no_chain),
104 BinaryExpression4(gated_by comparison_operator no_chain),
105 BinaryExpression5(gated_by comparison_operator no_chain),
106 ]
107 pays [
108 EQEQ, BANGEQ, LTEQ, GTEQ, EQTILDE,
109 LT under [
110 BinaryExpression, BinaryExpression2, BinaryExpression3, BinaryExpression4,
111 BinaryExpression5,
112 ],
113 GT under [
114 BinaryExpression, BinaryExpression2, BinaryExpression3, BinaryExpression4,
115 BinaryExpression5,
116 ],
117 TestOperator text_gated_by is_test_comparison,
118 ]
119 project "operator"
120 }
121 // `&&` / `||` join two commands in a `list` and two tests inside
122 // `[[ … ]]` / `(( … ))` in a `binary_expression`; inside `[ … ]` the
123 // same join is the `-a` / `-o` spelling of `test_operator`, read by
124 // text. Bash's `&&` / `||` are command-list separators, so the ABC
125 // consumer reads this row for nothing (#1536 — Fitzpatrick Rule 9
126 // does not map onto its grammar) where cyclomatic and cognitive
127 // read it.
128 ShortCircuit {
129 owns [
130 List,
131 BinaryExpression(gated_by short_circuit_operator no_chain),
132 BinaryExpression2(gated_by short_circuit_operator no_chain),
133 BinaryExpression3(gated_by short_circuit_operator no_chain),
134 BinaryExpression4(gated_by short_circuit_operator no_chain),
135 BinaryExpression5(gated_by short_circuit_operator no_chain),
136 ]
137 pays [AMPAMP, PIPEPIPE, TestOperator text_gated_by is_test_connective]
138 project "operator"
139 }
140 // `-a` / `-o` inside `[ ]` are arguments to the `test` builtin,
141 // which evaluates both sides (`[ 1 -eq 2 -a nope -eq 1 ]` still
142 // complains about `nope`), so by the language they are eager. Every
143 // consumer scores them as the `[[ … && … ]]` twin they spell
144 // (#1536), so they are the `ShortCircuit` row's text-gated payer
145 // above: a policy this package records and does not move. The
146 // bitwise `&` / `|` / `^` inside `(( … ))` are the only other
147 // candidates, and are integral.
148 EagerLogical {
149 owns []
150 excludes [
151 TestOperator "`-a` / `-o` are scored as the `&&` / `||` they spell (#1536), so the \
152 `ShortCircuit` row claims them; the builtin's eager evaluation is recorded here",
153 ]
154 }
155 // The arithmetic `(( a ? b : c ))` is Bash's only ternary: the
156 // `ternary_expression` owns it (`TernaryExpression2` is the second
157 // id carrying the kind, listed per grammar-dispatch §1 and
158 // unreachable at the pinned grammar) and its `?` pays, gated to that
159 // owner since `${y?msg}` spells the same token. `QMARK2` is the
160 // grammar's second `?` id, which no spelling at the pinned grammar
161 // emits — `bash_ternary_expression_alias_is_unreachable` in the
162 // cyclomatic tests pins that beside the owner alias — so it is
163 // recorded as considered rather than paid; the getter still bills
164 // it as the operator it names, should a bump start emitting it.
165 Ternary {
166 owns [TernaryExpression, TernaryExpression2]
167 pays [QMARK under [TernaryExpression, TernaryExpression2]]
168 project "operator"
169 excludes [QMARK2 "the second `?` id, which no spelling at the pinned grammar emits"]
170 }
171 NullSafe { absent "Bash has no optional navigation or null coalescing" }
172 // A `case_item` (`CaseItem2` the second id carrying the kind, per
173 // grammar-dispatch §1) owns a decision and pays at the node — the
174 // arm has no keyword; `case` and `esac` are the statement's and bill
175 // as the keywords they are — unless its sole pattern is `*`, the
176 // catch-all (lesson 11, #469), which only the bytes tell.
177 CaseArm {
178 owns [CaseItem(text_gated_by is_decision_item no_chain), CaseItem2(text_gated_by is_decision_item no_chain)]
179 }
180 Guard { absent "Bash has no guard clause; a `case` pattern is a glob, not a condition" }
181 // Bash counts statement nodes, so every row here is plain (#1697).
182 Branch { owns [IfStatement] }
183 Switch { owns [CaseStatement] }
184 // `for x in …`, the C-style `for ((…))`, `while` and `until` (one
185 // `while_statement` kind for both).
186 Loop { owns [ForStatement, CStyleForStatement, WhileStatement] }
187 Catch { absent "Bash has no exception handling; `trap` is a command" }
188 // The grammar gives `elif` a clause node of its own, a direct child of
189 // the `if_statement`, so the clause *is* the else-if and pays for
190 // itself; no nested `if` is ever an else-if here.
191 ElseIf { owns [ElifClause(pays_itself)] pays [] }
192 // Bash has no `return_statement` node: `return` and `exit` are
193 // ordinary builtins parsed as a `command` whose `name` field is a
194 // `command_name`, told by text.
195 Exit { owns [Command(text_gated_by return_or_exit no_chain)] }
196 Modifier { absent "Bash declares with builtins (`local`, `readonly`), which are commands, not \
197 modifier keywords" }
198 // The declaration builtins the grammar gives a kind of their own:
199 // `function`, and `local` / `declare` / `typeset` / `export` /
200 // `readonly`, each the leaf of a `declaration_command` or a
201 // `function_definition`, neither listed. `unset` / `unsetenv` are
202 // the inverse and bill with the commands.
203 DeclKeyword { owns [Function, Local, Declare, Typeset, Export, Readonly] }
204 Primitive { absent "Bash has no type names" }
205 FuncOpener { owns [FunctionDefinition(callable opens Function)] }
206 Container { owns [Program(opens Unit)] }
207 Closure { absent "Bash has no anonymous function" }
208 Member { absent "Bash has no container to hold a member" }
209 // The one comment kind. The grammar marks no comment as
210 // documentation, and no convention a tool reads over a comment run
211 // (shdoc's `# @description` blocks) is recognised here, so the six
212 // documentation rows are absent — unsupported, not nonexistent —
213 // and `is_comment` is this row's kind table alone (#1699).
214 Comment { owns [Comment] }
215 DocComment { absent "the grammar marks no comment as documentation; no tool's convention is read" }
216 Docstring { absent "Bash documents with comments, not string literals" }
217 DocTarget { absent "no comment is recognised as documentation, so nothing is its target" }
218 DocRunOpener { absent "no comment-run convention (shdoc) is recognised" }
219 DocRunDirective { absent "no comment-run convention (shdoc) is recognised" }
220 DocBodyResidual { absent "no kind holds documentation in a body beyond the function" }
221}
222
223#[cfg(test)]
224mod tests {
225 use super::*;
226 use crate::BashCode;
227 use crate::test_support::for_each_node_with_chain;
228
229 // The `Ternary` row's `?` is the arithmetic ternary's alone: an
230 // expansion's `${y?msg}` spells the same bare token and pays
231 // nothing, and `$?` is a token of its own (#1695). ABC reads the
232 // row at its wrapper and Halstead's byte-less arm keeps billing the
233 // expansion's `?`, so this is the one place the payer gate is
234 // observed.
235 #[cfg(feature = "bash")]
236 #[test]
237 fn ternary_pays_at_the_arithmetic_question_mark_only() {
238 let source = b"c=$(( a ? b : x ))\necho ${y?msg} $?\n";
239 let (mut owned, mut paid) = (Vec::new(), Vec::new());
240 for_each_node_with_chain::<BashCode>(source, |node, chain| {
241 let ancestors = Ancestors::known(chain);
242 let text = || node.utf8_text(source).expect("fixture is UTF-8").to_owned();
243 if ternary::owns(node, source, ancestors) {
244 owned.push(text());
245 }
246 if ternary::pays_at_leaf(node, source, ancestors) {
247 paid.push((node.start_byte(), text()));
248 }
249 });
250 assert_eq!(owned, ["a ? b : x"]);
251 assert_eq!(paid, [(8, "?".to_owned())]);
252 }
253
254 // The `Comparison` and `ShortCircuit` owner gates read the one
255 // `test_operator` kind for its bytes, as the payer gates do: a
256 // `binary_expression` holding `-lt` / `-gt` owns a comparison and
257 // one holding `-a` / `-o` owns a chain, never both. The consumers
258 // read these rows at the token, so only this pins the owner side,
259 // and each payer's parent is held to its own row. The first test's
260 // operators nest left — `(($a -lt $b) -a $c) -gt 1` — so its
261 // outermost node holds `-gt` and the chain is its left operand; the
262 // `=` of the second is the `EQ` kind, which the row leaves to the
263 // consumer (#1536), so that node owns nothing. (`-a` / `-o` are
264 // `[ ]`'s; inside `[[ ]]` they are a syntax error.)
265 #[cfg(feature = "bash")]
266 #[test]
267 fn test_operators_sort_their_owners_by_their_bytes() {
268 let source = b"if [ $a -lt $b -a $c -gt 1 ]; then :; fi\n\
269if [ \"$s\" = x -o \"$t\" != y ]; then :; fi\n";
270 let mut owned: [Vec<String>; 2] = Default::default();
271 let mut paid: [Vec<String>; 2] = Default::default();
272 for_each_node_with_chain::<BashCode>(source, |node, chain| {
273 let ancestors = Ancestors::known(chain);
274 let text = || node.utf8_text(source).expect("fixture is UTF-8").to_owned();
275 let rows = [
276 (
277 comparison::owns(node, source, ancestors),
278 comparison::pays_at_leaf(node, source, ancestors),
279 ),
280 (
281 short_circuit::owns(node, source, ancestors),
282 short_circuit::pays_at_leaf(node, source, ancestors),
283 ),
284 ];
285 assert!(!(rows[0].0 && rows[1].0), "{}", text());
286 assert!(!(rows[0].1 && rows[1].1), "{}", text());
287 for (row, (owns, pays)) in rows.into_iter().enumerate() {
288 if owns {
289 owned[row].push(text());
290 }
291 if pays {
292 paid[row].push(text());
293 // The payer's parent is the owner, asked with the
294 // chain above it.
295 let (parent, above) = chain.split_last().expect("a payer has a parent");
296 let row_owns = [comparison::owns, short_circuit::owns][row];
297 assert!(
298 row_owns(parent, source, Ancestors::known(above)),
299 "{}",
300 text()
301 );
302 }
303 }
304 });
305 assert_eq!(
306 owned[0],
307 ["$a -lt $b -a $c -gt 1", "$a -lt $b", "x -o \"$t\" != y"]
308 );
309 assert_eq!(owned[1], ["$a -lt $b -a $c", "x -o \"$t\""]);
310 assert_eq!(paid[0], ["-lt", "-gt", "!="]);
311 assert_eq!(paid[1], ["-a", "-o"]);
312 }
313}