Skip to main content

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}