# Tree-Sitter-Bash Parser API: How to Use the MoonshotAI Parser Safely

> Explore the Tree Sitter Bash parser API from MoonshotAI. Learn how to safely parse Bash code in TypeScript with the @moonshot-ai/tree-sitter-bash package. Discover best practices for secure usage.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: how-to-guide
- Published: 2026-08-16

---

**TLDR:** The `@moonshot-ai/tree-sitter-bash` package provides a pure-TypeScript Bash parser with a `parse(source, options?)` function that returns a discriminated `ParseResult`. Use it safely by setting budget limits, checking `result.ok`, and handling error states.

The **tree-sitter-bash parser API** from MoonshotAI offers a deterministic, type-safe way to parse Bash scripts in TypeScript without native dependencies. This complete guide covers the core API, safety guarantees, and best practices for reliable integration.

## Understanding the Parse Function

The `parse()` function in [`src/parse.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/parse.ts) serves as the primary entry point for all tree-sitter-bash parser operations.

```typescript
parse(source: string, options?: ParseOptions): ParseResult

```

The function accepts a Bash source string and optional configuration. It returns a discriminated union: `{ ok: true, root: SyntaxNode }` on success, or `{ ok: false, error: ParseError }` when parsing fails.

**Key parameters to understand:**
- `source` — The complete Bash script to parse
- `ParseOptions` — Extends `ParseBudget` from [`src/budget.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/budget.ts) with `timeoutMs` and `maxNodes`

## ParseBudget: Enforcing Safe Execution

Safety in the tree-sitter-bash parser API centers on the **budget system** defined in [`src/budget.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/budget.ts).

The parser enforces deterministic limits to prevent runaway execution:

| Budget Parameter | Default Value | Purpose |
|-----------------|-------------|---------|
| `timeoutMs` | 50 ms | Maximum parsing duration |
| `maxNodes` | 50,000 | Maximum AST nodes generated |

When limits are exceeded, the parser throws a custom `Aborted` error. This prevents denial-of-service scenarios with malformed or malicious input.

```typescript
import { parse } from '@moonshot-ai/tree-sitter-bash';

// Safe parsing with strict limits for untrusted input
const result = parse(untrustedScript, {
  timeoutMs: 30,
  maxNodes: 5_000
});

if (!result.ok) {
  // Handle budget exhaustion or parse error
  console.error('Parsing failed:', result.error);
}

```

## Working with SyntaxNode Objects

The **SyntaxNode** interface in [`src/node.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/node.ts) represents elements of the parsed Bash AST.

Each node provides:
- `type` — Grammar node type (e.g., `"program"`, `"command"`, `"variable_name"`)
- `text` — Source text span
- `startByte` / `endByte` — Position in source
- `hasError` — Boolean indicating parse errors in this subtree
- `descendants` — Array of child nodes for tree traversal

Helper functions assist common operations:

```typescript
import { parse, descendantsOfType, createNode } from '@moonshot-ai/tree-sitter-bash';

const result = parse('echo $HOME && ls -la');

if (result.ok) {
  // Find all variable references
  const variables = descendantsOfType(result.root, 'variable_name');
  
  // Check for partial parse errors
  const errorNodes = result.root.descendants.filter(n => n.hasError);
}

```

## Safe Usage Patterns for Tree-Sitter-Bash

Follow these four rules to use the tree-sitter-bash parser API safely in production.

### 1. Always Validate Parse Results

Never access `result.root` without confirming success.

```typescript
const result = parse(script);

// Correct: check ok before accessing root
if (result.ok) {
  analyzeTree(result.root);
} else {
  failGracefully(result.error);
}

// Dangerous: throws if parsing failed
doSomething(result.root); // Never do this

```

### 2. Respect Node Error State

A successful parse may still contain **error nodes** indicating incomplete or invalid syntax.

```typescript
if (result.ok) {
  const hasErrors = result.root.descendants.some(n => n.hasError);
  
  if (hasErrors) {
    // Treat as unreliable — partial parse only
    return { confidence: 'low', tree: result.root };
  }
}

```

### 3. Configure Appropriate Budgets

Match limits to your threat model and latency requirements.

```typescript
// Interactive editing: tight limits for responsiveness
const quickParse = parse(script, { timeoutMs: 10, maxNodes: 1_000 });

// Batch analysis of known-good files: relaxed limits
const thoroughParse = parse(script, { timeoutMs: 500, maxNodes: 500_000 });

```

### 4. Maintain Parser Purity

The tree-sitter-bash parser is **pure**: identical inputs produce identical outputs. Avoid mutable state patterns that could introduce non-determinism.

```typescript
// Safe: parser has no side effects
const r1 = parse(source);
const r2 = parse(source);
// r1 and r2 are structurally equal

```

## Complete Integration Example

This production-ready pattern demonstrates safe tree-sitter-bash parser API usage:

```typescript
import { parse, SyntaxNode, ParseError } from '@moonshot-ai/tree-sitter-bash';

interface ParseAttempt {
  success: boolean;
  tree?: SyntaxNode;
  error?: ParseError;
  hasSyntaxErrors: boolean;
  confidence: 'high' | 'medium' | 'low' | 'failed';
}

function safeParseBash(
  source: string,
  budget = { timeoutMs: 50, maxNodes: 50_000 }
): ParseAttempt {
  const result = parse(source, budget);
  
  if (!result.ok) {
    return {
      success: false,
      error: result.error,
      hasSyntaxErrors: true,
      confidence: 'failed'
    };
  }
  
  const errorNodes = result.root.descendants.filter(n => n.hasError);
  const hasSyntaxErrors = errorNodes.length > 0;
  
  return {
    success: true,
    tree: result.root,
    hasSyntaxErrors,
    confidence: hasSyntaxErrors ? 'low' : 'high'
  };
}

// Usage
const analysis = safeParseBash(userInput, { timeoutMs: 30, maxNodes: 10_000 });

if (!analysis.success || analysis.confidence === 'low') {
  // Degrade: skip advanced features, show warning
  return basicFallbackMode(userInput);
}

// Proceed with full AST analysis
performRefactoring(analysis.tree!);

```

## Key Source Files Reference

| File | Location | Responsibility |
|------|----------|--------------|
| [`src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/index.ts) | Package root | Public API exports (`parse`, `SyntaxNode`, `ParseBudget`) |
| [`src/parse.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/parse.ts) | Core implementation | `parse()` function and `ParseResult` types |
| [`src/node.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/node.ts) | AST structures | `SyntaxNode` interface and traversal helpers |
| [`src/budget.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/budget.ts) | Safety enforcement | `ParseBudget`, `Aborted` error class |
| [`src/lexer.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/lexer.ts) | Tokenization | Low-level lexical scanner |
| [`src/grammar.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/grammar.ts) | Language definition | Reserved words, operators, grammar constants |

## Summary

- **Entry point:** `parse()` in [`src/parse.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/parse.ts) returns a discriminated union — always check `result.ok`
- **Safety mechanism:** `ParseBudget` in [`src/budget.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/budget.ts) enforces `timeoutMs` and `maxNodes` limits with `Aborted` errors
- **Error handling:** Treat `!result.ok` and `node.hasError` as unreliable states requiring graceful degradation
- **Pure design:** Parser has no side effects; reuse for deterministic results

## Frequently Asked Questions

### What happens if parsing exceeds the budget limits?

The parser throws an `Aborted` error from [`src/budget.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/budget.ts), and `parse()` returns `{ ok: false, error }`. This prevents resource exhaustion from malicious or pathological input. Set limits appropriate to your workload and always handle the error case.

### Can I parse partial or syntactically invalid Bash scripts?

Yes, but with caution. The parser may return `result.ok: true` with `hasError: true` on specific nodes. These **error nodes** indicate where the grammar failed. Inspect `node.hasError` throughout the tree before trusting any analysis results.

### How do I find specific node types in the AST?

Use `descendantsOfType(root, typeString)` from [`src/node.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/node.ts) or filter `root.descendants` manually. Both approaches traverse the complete tree — consider caching results for large documents to avoid repeated walks.

### Is this parser API compatible with standard tree-sitter tools?

The `@moonshot-ai/tree-sitter-bash` API mirrors the official tree-sitter grammar but implements a pure-TypeScript parser. While node types and tree structure align with tree-sitter conventions, this is a standalone implementation without WebAssembly dependencies.