# How to Contribute to the @moonshot-ai/tree-sitter-bash Package

> Contribute to the @moonshot-ai/tree-sitter-bash package by opening issues running tests and submitting pull requests. Learn the Moonshot AI contribution workflow for the bash parser.

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

---

**Yes, you can contribute to the @moonshot-ai/tree-sitter-bash package** by following the standard Moonshot AI contribution workflow, which includes opening issues for substantial changes, running the comprehensive test suite, and submitting focused pull requests through the monorepo.

The **@moonshot-ai/tree-sitter-bash** package is a pure-TypeScript Bash parser maintained in the MoonshotAI/kimi-code repository. It reproduces the node types of the official tree-sitter-bash 0.25.0 grammar without native dependencies, making it an attractive target for contributors interested in parsing technology, performance optimization, or shell scripting tools.

## Understanding the Package Architecture

Before contributing, you need to understand how the parser is structured. The architecture splits responsibility across five core modules in `packages/tree-sitter-bash/src/`.

### Lexer ([`lexer.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/lexer.ts))

The **lexer** tokenizes Bash source into a stream of simple tokens. It operates on UTF-16 code units, enabling direct `source.slice(startIndex, endIndex)` operations to obtain `node.text` without complex conversions.

### Parser ([`parser.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/parser.ts))

The **parser** implements a recursive-descent algorithm with **hard budget limits** for time-outs and node-count caps. It never throws exceptions; instead, it returns `{ ok: false, reason: 'aborted' }` when limits are exceeded in [`packages/tree-sitter-bash/src/parser.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/parser.ts).

### Budget System ([`budget.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/budget.ts))

The **budget module** defines three critical parameters in [`packages/tree-sitter-bash/src/budget.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/budget.ts):

- `MAX_SUBSTITUTION_DEPTH`
- `MAX_PARSE_DEPTH`
- `MAX_SCAN_DEPTH`

These limits protect against pathological inputs and ensure predictable performance.

### Grammar ([`grammar.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/grammar.ts))

The **grammar** contains hand-written rules that map token streams to AST nodes. The node types are taken directly from upstream [`node-types.json`](https://github.com/MoonshotAI/kimi-code/blob/main/node-types.json), guaranteeing one-to-one correspondence with the reference C implementation in [`packages/tree-sitter-bash/src/grammar.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/grammar.ts).

### Public API ([`index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/index.ts))

The entry point in [`packages/tree-sitter-bash/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/index.ts) exports:

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

const result = parse('git status && rm -rf /');
if (result.ok) {
  // result.rootNode is a SyntaxNode representing the program
}

```

The `parse` function accepts optional `ParseOptions` with `timeoutMs` and `maxNodes` to tune parsing behavior for large scripts.

## Contribution Workflow for tree-sitter-bash

MoonshotAI/kimi-code follows a structured contribution process. Here's how to contribute specifically to the tree-sitter-bash package.

### Step 1: Review Contribution Guidelines

Read [`CONTRIBUTING.md`](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md) in the repository root. This document covers the full process, including the requirement to discuss substantial changes via an issue first.

### Step 2: Set Up the Development Environment

```bash

# Clone the monorepo

git clone https://github.com/MoonshotAI/kimi-code.git
cd kimi-code

# Install dependencies

pnpm install

# Verify the test suite passes

pnpm test

```

### Step 3: Make Focused Changes

Small, well-scoped pull requests have the highest acceptance rate. Typical contributions include:

- Adding test cases for uncovered edge-cases
- Improving budget handling or diagnostic information
- Updating documentation for known differences
- Refactoring internal utilities without changing public behavior

### Step 4: Run the Full Test Suite

Package-specific tests live in `packages/tree-sitter-bash/test/`. The suite includes:

1. **Differential tests** against the official tree-sitter-bash corpus
2. **Performance tests** verifying budget abort paths
3. **Edge-case tests** for handcrafted inputs

Execute all tests before opening a PR:

```bash
pnpm test --filter=@moonshot-ai/tree-sitter-bash

```

### Step 5: Create a Changeset

If your change alters released artifacts, run:

```bash
pnpm changeset

```

Follow the repository's changeset policy for versioning and changelog entries.

### Step 6: Submit Your Pull Request

Use the PR template, link related issues, and format your title with **Conventional Commits**:

```

fix(tree-sitter-bash): handle stray '&' after heredoc
feat(tree-sitter-bash): add configurable memory limits
docs(tree-sitter-bash): clarify known differences section

```

## Code Examples for Common Contributions

### Adding a New Test Case

Create a fixture in `packages/tree-sitter-bash/test/fixtures/` and reference it:

```typescript
// packages/tree-sitter-bash/test/new-edgecase.test.ts
import { parse } from '#/parse';
import { readFileSync } from 'fs';
import { join } from 'path';

const src = readFileSync(join(__dirname, '../fixtures/corpus/edgecase.txt'), 'utf8');

test('edgecase parsing', () => {
  const res = parse(src);
  expect(res.ok).toBe(true);
  // Additional assertions on AST shape...
});

```

### Customizing Parse Budgets

When testing large scripts or profiling performance:

```typescript
const hugeScript = /* very long Bash script */;

const result = parse(hugeScript, {
  timeoutMs: 200,
  maxNodes: 200_000
});

if (!result.ok) {
  console.warn('Parsing aborted due to budget limits:', result.reason);
}

```

## Testing and Correctness Standards

The @moonshot-ai/tree-sitter-bash package maintains strict correctness guarantees through its **differential test suite**. The test infrastructure parses the official corpus plus hundreds of handcrafted edge-cases, then compares generated trees byte-for-byte against the reference implementation.

Documented "Known differences" in [`packages/tree-sitter-bash/README.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/README.md) represent intentional deviations—these should not be "fixed" without discussion.

### Performance Benchmarks

The package guarantees specific performance characteristics verified by [`packages/tree-sitter-bash/test/performance.test.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/test/performance.test.ts):

| Scenario | Target |
|----------|--------|
| Typical one-line command | ~4 µs |
| 100 KB scripts | < 50 ms (default budget) |
| Budget abort for 400 KB bomb | ~20 ms |

Contributions affecting parsing speed must maintain these thresholds.

## Key Files Reference

| File | Purpose |
|------|---------|
| [`packages/tree-sitter-bash/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/index.ts) | Public API exports |
| [`packages/tree-sitter-bash/src/lexer.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/lexer.ts) | UTF-16 tokenization |
| [`packages/tree-sitter-bash/src/parser.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/parser.ts) | Budget-aware recursive descent |
| [`packages/tree-sitter-bash/src/budget.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/budget.ts) | Limit constants and checks |
| [`packages/tree-sitter-bash/src/grammar.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/grammar.ts) | Hand-written grammar rules |
| [`packages/tree-sitter-bash/README.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/README.md) | API documentation and known differences |
| `packages/tree-sitter-bash/test/` | Differential and performance tests |

## Summary

- **You can contribute** to @moonshot-ai/tree-sitter-bash through the standard MoonshotAI/kimi-code workflow
- The **pure-TypeScript architecture** splits work across lexer, parser, budget, grammar, and API modules
- **Budget-aware design** with hard limits protects against abuse and ensures predictable performance
- **Differential testing** against upstream tree-sitter-bash guarantees correctness
- **Focused PRs** with test coverage and proper changesets have the highest merge probability

## Frequently Asked Questions

### Do I need to know C or Rust to contribute?

No. Unlike the upstream tree-sitter-bash implementation, the @moonshot-ai/tree-sitter-bash package is **pure TypeScript** with no native addons. You only need familiarity with TypeScript, parsing concepts, and Bash syntax.

### What types of contributions are most needed?

The maintainers prioritize **test coverage for edge-cases**, **performance improvements** that maintain existing guarantees, and **documentation clarifications** for known differences. New grammar features require discussion via issue first.

### How does the budget system protect against attacks?

The parser enforces three depth limits (`MAX_SUBSTITUTION_DEPTH`, `MAX_PARSE_DEPTH`, `MAX_SCAN_DEPTH`) with runtime checks in [`packages/tree-sitter-bash/src/budget.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/budget.ts). When exceeded, parsing returns `{ ok: false, reason: 'aborted' }` rather than throwing, enabling graceful degradation in production systems.

### Can I use this parser for my own Bash tooling?

Yes. The package is published as `@moonshot-ai/tree-sitter-bash` and exposes a stable API through `parse()` with configurable options. The README in [`packages/tree-sitter-bash/README.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/README.md) documents all public types and usage patterns.