big-code-analysis-ast 2.5.1

Parse and classification layer behind big-code-analysis (internal, version-locked)
Documentation
//! `Getter` implementation for Bash.
#![allow(clippy::wildcard_imports, clippy::enum_glob_use)]

use super::*;

impl Getter for BashCode {
    // The mapping is the `opens` annotations of `roles/bash.rs`
    // (#1696). The rows read no bytes and no chain, so the byte-less
    // spelling forwards with none.
    impl_byte_less_space_kind!(bash);

    fn get_space_kind_with_code<'a>(
        node: &Node<'a>,
        code: &[u8],
        ancestors: Ancestors<'a, '_>,
    ) -> SpaceKind {
        crate::roles::bash::opens_space(node, code, ancestors)
    }

    keyword_roles!(bash);

    /// The `Comparison` and `ShortCircuit` rows' payers bill as
    /// operators (#1695), except a `test_operator`: the grammar gives
    /// `-z`, `-eq`, `-lt`, `-a`, `-o`, … one kind that this getter has
    /// never billed — a test operator names a predicate as a `test`
    /// builtin's flag does — and the rows' text gates split it for the
    /// counting consumers only. That reading stays here, where the
    /// macro cannot express it.
    // role-bypass: allow(Comparison, ShortCircuit) — the Halstead reading of a payer the rows
    // text-gate: a test operator bills nothing, as before the rows
    fn get_paying_role<'a>(
        node: &Node<'a>,
        code: &[u8],
        ancestors: Ancestors<'a, '_>,
    ) -> TokenRole {
        use crate::roles::bash::{comparison, short_circuit, ternary};
        let kind = node.kind_id();
        if kind == Bash::TestOperator as u16 {
            return TokenRole::Unknown;
        }
        if comparison::pays_at_token_kind(kind, node, code, ancestors)
            || short_circuit::pays_at_token_kind(kind, node, code, ancestors)
            || ternary::pays_at_token_kind(kind, node, code, ancestors)
        {
            TokenRole::Operator
        } else {
            TokenRole::Unknown
        }
    }

    fn get_op_type<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> TokenRole {
        match node.kind_id().into() {
            // Control flow keywords and the undeclaring builtins. The
            // declaration keywords are not here: `roles/bash.rs`
            // declares them and `get_keyword_role` bills them (#1693).
            Bash::If | Bash::Then | Bash::Fi | Bash::Elif | Bash::Else
            | Bash::For | Bash::In | Bash::While | Bash::Until | Bash::Do | Bash::Done
            | Bash::Case | Bash::Esac
            | Bash::Unset | Bash::Unsetenv
            // Punctuation acting as operators. Only the *opening*
            // delimiter counts — `get_operator_id_as_str` folds
            // `LPAREN`/`LBRACK`/`LBRACE` to the pair glyph, so a balanced
            // pair is one operator. Counting the matching closer too
            // (former `RPAREN`/`RBRACE`/`RBRACK`/`RBRACKRBRACK` arms)
            // double-counted every pair, inflating n1/N1 (#695). `[[`
            // (`LBRACKLBRACK`) is the test-command opener; its `]]` closer
            // is dropped for the same reason.
            | Bash::LPAREN | Bash::LBRACE
            | Bash::LBRACK | Bash::LBRACKLBRACK
            | Bash::SEMI | Bash::SEMISEMI | Bash::SEMIAMP | Bash::SEMISEMIAMP
            | Bash::COMMA | Bash::COLON
            // Assignment, arithmetic, and comparison operators
            | Bash::EQ | Bash::PLUSEQ | Bash::DASHEQ | Bash::STAREQ | Bash::SLASHEQ
            | Bash::PERCENTEQ | Bash::STARSTAREQ | Bash::LTLTEQ | Bash::GTGTEQ
            | Bash::AMPEQ | Bash::CARETEQ | Bash::PIPEEQ
            | Bash::PLUS | Bash::DASH | Bash::STAR | Bash::SLASH | Bash::PERCENT | Bash::STARSTAR
            | Bash::PLUSPLUS | Bash::DASHDASH
            // `<` / `>` for the spelling the `Comparison` row's parent
            // gate leaves out — a redirection (`cmd > out`) — which billed
            // before the row existed; the other comparison tokens and
            // `&&` / `||` are the rows' and `get_paying_role` bills them
            // (#1695). `?` likewise stays, below, for the `Ternary` row's
            // gated-out expansion spelling.
            // role-bypass: allow(Comparison, Ternary) — the operator classification of the
            // spellings the rows' `under BinaryExpression` / `under TernaryExpression` gates
            // leave out
            | Bash::LT | Bash::GT
            // Bitwise operators
            | Bash::PIPE | Bash::PIPEAMP
            | Bash::AMP | Bash::CARET | Bash::TILDE | Bash::BANG
            | Bash::LTLT | Bash::GTGT
            // Test operators (prefix)
            | Bash::DASHa | Bash::DASHo
            // Redirection operators
            | Bash::AMPGT | Bash::GTAMP | Bash::LTAMP | Bash::GTPIPE
            | Bash::LTAMPDASH | Bash::GTAMPDASH | Bash::LTLTDASH | Bash::AMPGTGT
            | Bash::LTLTLT
            // `?` for the spelling the `Ternary` row's `under TernaryExpression` gate
            // leaves out — an expansion's `${y?msg}` — which billed before
            // the row existed; `QMARK2` is the second `?` id, which no
            // spelling at the pinned grammar emits.
            | Bash::QMARK | Bash::QMARK2
                => TokenRole::Operator,

            // Quoted strings count as one operand when they are inert.
            // When they contain any `$var`/`${...}`/`$(...)`/`$((...))`
            // expansion child — the `StringLit` row's `wraps` list — those
            // expansions are already walked through; only `simple_expansion`
            // is itself an operand, for the other three it is the leaves
            // beneath them (`ls` in `$(ls)`, `1` in `$((1))`) that carry
            // the count, and `${#}` carries none at all. Either way the
            // wrapping literal must not be counted on top (issue #180).
            // `RawString` is single-quoted and `AnsiCString` is a leaf
            // token, so neither can interpolate, but the check is uniform
            // across the three string kinds for clarity.
            //
            // `translated_string` is deliberately absent (#1358) — see the
            // note on `command_name` below, which it shares a shape with.
            // role-bypass: allow(StringLit) — the operand classification of the literals
            // under the row's `wraps` list, a projection the row does not answer
            Bash::String | Bash::RawString | Bash::AnsiCString => {
                Self::string_operand_type(node, crate::roles::bash::string_lit::WRAPS)
            }

            // Operands: identifiers, literals, variables. `variable_name`
            // and `special_variable_name` each surface under multiple
            // aliased kind_ids (tree-sitter generates one per parse-table
            // context); every alias must be matched or assignment LHS
            // identifiers like `name` in `name=value` are silently
            // unclassified — see lesson 2.
            //
            // `command_name` is deliberately absent (#1351). The grammar
            // gives it exactly one required child — a `_primary_expression`
            // or a `concatenation` — and it contributes no text of its own,
            // so classifying the wrapper *and* letting the walk reach the
            // child counted every command name twice in N2 (`ls bar` scored
            // N2 3 for two operands). For a `"$cmd"` command name it also
            // planted a second vocabulary entry alongside the inner `$cmd`.
            // Deleting rather than gating is safe here because the wrapper
            // is never childless and the child kinds are the ordinary
            // operand kinds; the one residue — a brace `expansion` with no
            // `variable_name` leaf, `${#}` — scores zero in argument
            // position too, so the wrapper was masking that gap for command
            // names alone.
            //
            // `translated_string` is absent for the same reason (#1358).
            // `translated_string: $ => seq('$', $.string)` gives it one
            // required `string` child and no text of its own beyond the
            // `$`, so `a=$"x"` scored N2 3 for two operands. It also
            // defeated the #180 expansion guard: the wrapper's own children
            // are `$` and `string`, so the `wraps` check never saw the
            // `simple_expansion` one level down and `b=$"$y"` counted
            // both `$"$y"` and `$y`.
            //
            // The `string` is the keeper because it is the node present for
            // *every* spelling. Wherever the grammar omits the wrapper — in
            // ordinary argument position, `echo $"hi"`, which emits a bare
            // `$` token and a `string` — the child is still there, so
            // dropping the wrapper makes each position that *does* carry one
            // (assignment RHS, `case` subject, command name, `for` list,
            // array element, redirection target, `[[ ]]` operand, and any
            // other the grammar admits) agree with argument position rather
            // than newly disagree (grammar-dispatch §6).
            //
            // The residue is `command_name`'s, one level down: `$"${#}"`
            // scores zero, because its inner `string` wraps an operandless
            // `expansion`. A plain `"${#}"` already scored zero, so that is
            // the parity rather than a new gap, and
            // `bash_translated_string_scores_alike_in_both_positions` pins
            // both halves of it.
            //
            // `Checker::is_string` still matches the wrapper, and that is
            // not drift: `bca find string` reports nodes, and an
            // interpolating `"$y"` is likewise a string the operand walk
            // skips.
            //
            // `_concat` (`Bash::Concat`) is absent for a different reason:
            // it is a hidden zero-width external token the scanner emits
            // between `concatenation` parts, never a named node, and it
            // spells no operand even if a future grammar promoted it.
            // Lesson 34 prefers keeping a hidden-rule arm and pinning it,
            // but keeping this one would preserve a classification that is
            // wrong the moment it becomes reachable, so the arm goes and
            // only the marker stays:
            // `bash_hidden_concat_token_is_unreachable`.
            Bash::Word | Bash::Word2 | Bash::Word3 | Bash::Word4
            | Bash::Number | Bash::Number2 | Bash::NumberToken1 | Bash::NumberToken2
            // role-bypass: allow(StringLit) — the operand classification of an expansion
            // the `StringLit` row `wraps`, a projection the row does not answer
            | Bash::SimpleExpansion
                => TokenRole::Operand,

            // `variable_name` / `special_variable_name` are operands when
            // they stand alone — the `name` in `name=value`, or the inner
            // leaf of a brace `${name}` `expansion` whose wrapper is *not*
            // itself an operand. But `$name` (and `$?`, `$1`, …) parses as a
            // `simple_expansion` wrapping the same leaf, and `SimpleExpansion`
            // is already an operand above; counting the inner leaf too would
            // double-count every bare `$var` reference (inflating n2/N2 and
            // every derived Halstead value). Exclude the leaf exactly in
            // that position — the same guard Tcl applies via its anonymous
            // `Id2` exclusion and iRules applies via a parent check on
            // `variable_substitution`.
            Bash::VariableName | Bash::VariableName2 | Bash::VariableName3
            | Bash::SpecialVariableName | Bash::SpecialVariableName2 => {
                if ancestors.parent_has_kind(node, Bash::SimpleExpansion as u16) {
                    TokenRole::Unknown
                } else {
                    TokenRole::Operand
                }
            }
            _ => TokenRole::Unknown,
        }
    }

    get_operator!(Bash);
}