wave-agent-sdk 1.1.5 → 1.2.0

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

@@ -0,0 +1,96 @@
+/**
+ * Tokenizer for the structure-aware bash parser.
+ *
+ * Unlike `bashParser.ts`'s text-based heuristics, this tokenizer understands
+ * bash quoting so that structural tokens (;, &&, ||, |, &, ( ), do/done/fi…)
+ * are only recognized OUTSIDE quotes/substitutions, and words keep enough
+ * internal structure for the semantic layer to tell quoted `"$f"` from bare
+ * `$f`.
+ *
+ * Words are tokenized into parts:
+ *   - lit        literal text (single-quoted or plain)
+ *   - var        `$name` / `${name}` expansion (name kept raw, unexpanded)
+ *   - special    `$@` `$*` `$?` `$$` `$!` `$#` `$-` `$0`..`$9`
+ *   - cmdsub     `$(...)` or backtick command substitution (text = inner)
+ *   - arith      `$((...))` — unsupported (dynamic), fail closed
+ *   - brace      `{a,b}` brace expansion — unsupported (dynamic)
+ *   - process    `<(cmd)` / `>(cmd)` process substitution — unsupported
+ * Each part records whether it appeared inside double quotes (`q: 'double'`)
+ * or bare (`q: 'none'`); single-quoted text is fully literal.
+ *
+ * The tokenizer FAILS (returns null) on any construct it cannot safely delimit
+ * (unterminated quotes / $( / backticks / heredocs). Failures are surfaced by
+ * the caller as a fail-closed `unsupported` parse result.
+ */
+export type QuoteCtx = "none" | "single" | "double";
+export type WordPart = {
+    t: "lit";
+    v: string;
+    q: QuoteCtx;
+} | {
+    t: "var";
+    name: string;
+    q: "none" | "double";
+} | {
+    t: "special";
+    name: string;
+    q: "none" | "double";
+} | {
+    t: "cmdsub";
+    text: string;
+    q: "none" | "double";
+} | {
+    t: "arith";
+    q: "none" | "double";
+} | {
+    t: "brace";
+    v: string;
+    q: "none" | "double";
+} | {
+    t: "process";
+    text: string;
+    q: "none" | "double";
+};
+export interface WordToken {
+    t: "word";
+    /** Raw word text as written (quotes and $ references preserved). */
+    raw: string;
+    /** Inner structure for the semantic layer. */
+    parts: WordPart[];
+}
+export type OpToken = "&&" | "||" | "|" | "|&" | ";" | ";;" | ";&" | ";;&" | "&" | "(" | ")" | "newline" | "{" | "}";
+export interface OpTok {
+    t: "op";
+    op: OpToken;
+}
+export interface NlTok {
+    t: "nl";
+}
+export type Token = WordToken | OpTok | NlTok | {
+    t: "eof";
+};
+/** Raw tokenizer failure: a construct we cannot model → ask (fail closed). */
+export type LexFailureReason = "heredoc" | "unterminated" | "unexpected-char" | "length-limit";
+export declare function isVariableNameStart(ch: string): boolean;
+/**
+ * Classify a redirection operator word emitted by the tokenizer.
+ * Returns "plain" when the operator still needs a separate following target
+ * word (`>`, `2>`, `>>`, `&>`, `>&` …), "folded" when the target is already
+ * part of the operator token (`2>&1`, `>&-`), or null when the word is not a
+ * redirection operator.
+ *
+ * The raw word may carry an optional file-descriptor digit prefix (`2>`) and
+ * the dup operators `<&`/`>&` may fold their fd/- target when it directly
+ * touches the operator (`2>&1` must stay one token so the reconstructed text
+ * remains faithful — legacy `2>& 1` text checks would mis-read the target).
+ */
+export declare function redirectOpKind(raw: string): "plain" | "folded" | null;
+/** True when the raw text is a redirection operator (fd prefix allowed). */
+export declare function isRedirectRaw(raw: string): boolean;
+/** Whether a word token is a redirection operator (raw literal, no quoting). */
+export declare function isRedirectWord(w: WordToken): boolean;
+/**
+ * Tokenize a bash command string. Returns tokens or null on a lexical
+ * construct we deliberately do not support (fail closed).
+ */
+export declare function tokenize(input: string): Token[] | null;