wave-agent-sdk 1.1.4 → 1.2.0

package/dist/utils/bashStructure/bashParser.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Recursive-descent parser for the structure-aware bash parser.
+ *
+ * Consumes the token stream from `bashLexer.ts` and produces a light AST that
+ * preserves shell structure: command lists/and-or chains, pipelines,
+ * subshells/brace groups, for/while/until/if/case loops and function
+ * definitions. Each structural token (do/done/then/fi/esac…) is consumed by
+ * the parser and never reaches the semantic layer as a "command".
+ *
+ * The grammar handled here is deliberately the subset bash uses in agent
+ * tool commands:
+ *   program   := list (sep list)*            sep ∈ {newline, ';', eof}
+ *   list      := andor (op andor)*           op ∈ {&& || | |& &}
+ *   andor     := command
+ *   command   := simple | subshell | brace-group | for | while | until
+ *              | if | case | function | select
+ *
+ * Anything not modelled (heredocs, arithmetic expansion, brace expansion,
+ * process substitution, `${x:-y}`-style parameter expansion, unterminated
+ * constructs) is a FAILURE: `parseProgram` returns null and the caller treats
+ * it as a fail-closed "unsupported" result (ask instead of auto-allowing).
+ */
+import { type Token, type WordToken } from "./bashLexer.js";
+/** A simple command: a word list (may start with VAR=value assignments). */
+export interface CmdNode {
+    kind: "cmd";
+    words: WordToken[];
+}
+export interface ForNode {
+    kind: "for";
+    /** Select-style loops (select name [in words]) parsed as `for`. */
+    varName: string;
+    /** Iteration words — null when no `in` clause (implicit "$@"). */
+    iter: WordToken[];
+    body: StmtNode[];
+}
+export interface WhileNode {
+    kind: "while";
+    until: boolean;
+    cond: StmtNode[];
+    body: StmtNode[];
+}
+export interface IfClause {
+    cond: StmtNode[];
+    body: StmtNode[];
+}
+export interface IfNode {
+    kind: "if";
+    clauses: IfClause[];
+    elseBody: StmtNode[] | null;
+}
+export interface CaseArm {
+    /** Pattern words (may contain `|` alternatives joined already). */
+    patterns: WordToken[];
+    body: StmtNode[];
+}
+export interface CaseNode {
+    kind: "case";
+    word: WordToken;
+    arms: CaseArm[];
+}
+export interface FuncNode {
+    kind: "function";
+    name: string;
+    body: StmtNode[];
+}
+export interface SubshellNode {
+    kind: "subshell";
+    body: StmtNode[];
+}
+export interface GroupNode {
+    kind: "group";
+    body: StmtNode[];
+}
+/** A chain step: body plus whether varScope should fork after it. */
+export interface ChainStep {
+    nodes: StmtNode[];
+    /** true → following steps run in a forked scope (|| | & |& …). */
+    forkAfter: boolean;
+}
+/** An and-or chain inside a statement position. */
+export interface ListNode {
+    kind: "list";
+    steps: ChainStep[];
+}
+/**
+ * A compound command with trailing redirections (`while …; done < input`).
+ * The redirect words bind to the whole compound, not the last inner command.
+ */
+export interface RedirectsNode {
+    kind: "redirects";
+    target: StmtNode;
+    /** Redirect operator + target word tokens (`<`, `input`, …). */
+    redirects: WordToken[];
+}
+export type StmtNode = CmdNode | ForNode | WhileNode | IfNode | CaseNode | FuncNode | SubshellNode | GroupNode | ListNode | RedirectsNode;
+export type Program = StmtNode[];
+export declare class BashParser {
+    private tokens;
+    private pos;
+    private depth;
+    constructor(tokens: Token[]);
+    /** Parse the full token stream. */
+    parseProgram(): Program | null;
+    private peek;
+    private next;
+    private isOp;
+    /** True when the current word is a bare (unquoted) keyword. */
+    private isBareWord;
+    /** Skip newline tokens. */
+    private skipNl;
+    /**
+     * Parse statements until a terminator in `stop` (as bare keyword) or a
+     * closing op. Used for compound bodies (do…done, then…fi, case arms).
+     */
+    private parseSequence;
+    /** Parse an and-or chain: cmd (&&|… cmd)* */
+    private parseChain;
+    /** Parse a single command (simple or compound). Returns nodes array. */
+    private parseCommand;
+    /**
+     * Absorb redirections that trail a compound command (e.g. the `< input.txt`
+     * in `while read x; do …; done < input.txt`). Shell grammar binds them to
+     * the whole compound; we wrap it in a RedirectsNode so the semantic layer can
+     * attach the redirect text to the compound's last leaf command.
+     */
+    private absorbTrailingRedirects;
+    private parseIf;
+    private parseWhile;
+    private parseFor;
+    private parseCase;
+    private parseFunctionKw;
+    /** Detect `name() { …; }` form. Must be called at a simple-command word. */
+    private tryParseFunctionDecl;
+    /** Parse `{ …; }` compound body for function definitions. */
+    private parseBraceBody;
+    /** Collect words of a simple command until a chain separator. */
+    private parseSimpleCommandWords;
+}
+/**
+ * Parse a token stream into a program. Returns null on any construct that
+ * cannot be statically modelled (fail-closed → caller asks).
+ */
+export declare function parseTokens(tokens: Token[]): Program | null;