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

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)

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)

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.

Budget System (budget.ts)

The budget module defines three critical parameters in 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)

The grammar contains hand-written rules that map token streams to AST nodes. The node types are taken directly from upstream node-types.json, guaranteeing one-to-one correspondence with the reference C implementation in packages/tree-sitter-bash/src/grammar.ts.

Public API (index.ts)

The entry point in packages/tree-sitter-bash/src/index.ts exports:

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 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

# 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:

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

Step 5: Create a Changeset

If your change alters released artifacts, run:

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:

// 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:

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 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:

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	Public API exports
packages/tree-sitter-bash/src/lexer.ts	UTF-16 tokenization
packages/tree-sitter-bash/src/parser.ts	Budget-aware recursive descent
packages/tree-sitter-bash/src/budget.ts	Limit constants and checks
packages/tree-sitter-bash/src/grammar.ts	Hand-written grammar rules
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. 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 documents all public types and usage patterns.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}