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 — 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}