Module shell 

tree-sitter-bash AST walker for compound command splitting. Shell command parsing backed by tree-sitter-bash.

This module provides two public functions:

• parse_with_substitutions — decomposes a shell command string into a ParsedPipeline of segments joined by operators, plus a list of extracted command/process substitution contents.

• has_output_redirection — checks whether a command string contains output redirection that could mutate filesystem state.

Both functions parse their input with tree-sitter-bash, which provides a full AST from a formal grammar. This means quoting, heredocs, control flow keywords, and nested substitutions are handled by the grammar itself — the code here walks the resulting AST rather than scanning characters.

Control flow handling

Shell keywords (for, if, while, case) are grammar structure, not commands. The AST walker recurses into control flow bodies and extracts the actual commands inside them as pipeline segments. For example, for i in *; do rm "$i"; done produces a segment for rm "$i", not for for or done.

Redirection propagation

When a control flow construct is wrapped in a redirected_statement (e.g. for ... done > file), the output redirection is propagated to the inner segments via ShellSegment::redirection. The eval layer uses this field to escalate decisions for commands that are contextually mutating even though their own text contains no redirect.

Substitution extraction

Outermost $(), backtick, <(), and >() nodes are collected and their spans replaced with __SUBST__ placeholders in the segment text. The eval layer recursively evaluates each substitution’s inner command independently.

Functions

dump_ast

Dump the tree-sitter AST and parsed pipeline for a command string.

has_output_redirection

Check whether command contains output redirection that could mutate filesystem state.

parse_with_substitutions

Parse a shell command string into a pipeline of segments and a list of extracted substitution contents.