bonsai-ninja

Project maturity: bonsai-ninja is an ambitious early-stage project. Compiler-backed analysis and security modeling across 20 languages leave a lot of room for parser gaps, unresolved dynamic behavior, incorrect findings, performance problems, and ordinary bugs. The current local release gates pass and the tool is ready for people to use, but it is not perfect and should not be the sole basis for a security decision. We are publishing it now to gather real-world feedback, failing examples, rule contributions, and engineering help from the community.

bonsai-ninja is a local code-intelligence and static-analysis engine. It maps repositories, resolves symbols and calls, traces behavior across files, inspects dataflow, exports graph facts, and reports source-to-sink security findings from one compiler-style pipeline.

The project is MIT licensed. It does not require a hosted service, upload source code, or reserve analysis features for a paid tier.

Use cases

Code intelligence for agents and developers

Give agents facts, not file dumps. With tight symbol, file, and kind selectors, bonsai-ninja lets an agent ask for the smallest useful slice of a repository: the definition, callers, references, arguments, path, backward slice, raw dataflow, or source file around one symbol. That means less prompt waste, less repeated reading, and answers tied to compiler evidence.

Use it to map an unfamiliar repository, find the code behind a symptom, follow behavior across files, review change impact, or debug the analyzer itself with AST, HIR, CFG, resolver, call-edge, and taint diagnostics.

Security review

Use the same compiler facts to inventory sources, sinks, sanitizers, and dependencies, then prove modeled source-to-sink paths with the sparse IDG fixed point. Findings can be reviewed in the terminal, emitted as JSON or SARIF for automation, or shared as a standalone HTML report. The analysis is evidence for human review—not a guarantee that code is safe—and completion metadata makes unresolved static behavior visible.

Structured export for model and agent research

Native export exposes compiler, symbol, callgraph, control-flow, dataflow, and compiled-IDG facts in a machine-readable form. GraphML, Cypher, and NetworkX views support graph tooling. These artifacts can be inputs to retrieval, training-data construction, evaluations, code-reasoning experiments, or tool-using agents; bonsai-ninja produces the evidence and does not train or validate a model by itself. The versioned native contract is published as JSON Schema v7.

Our small exploratory tests produced encouraging results, but they are not a general model-quality claim. We would love to see independent teams take the idea further, publish reproducible evaluations, and tell us where it fails— whether that is OpenAI, Anthropic, Google, Poolside/Laguna, Qwen, DeepSeek, academic and independent labs, or local-model hobbyists.

What the pipeline provides

Scale, measured

30,055 source files. Completed modeled analysis. Warm navigation in seconds. The current Elasticsearch measurements use a 3 GiB semantic-worker scheduling budget and separate the first explicit semantic index from commands run after it exists:

The measured cold operation is specifically index --semantic, which users request when they want every reusable semantic sidecar prepared up front. Ordinary index is the lighter syntax/declaration warm-up and does not force a whole-workspace callgraph or IDG build; ordinary commands can also compute their requested facts on demand.

The cold row is an intentional one-time whole-workspace prewarm, not normal command startup. The 3 GiB setting schedules semantic workers rather than limiting operating-system RSS, and compressed export changes representation, not graph meaning. Full methodology, component sizes, memory measurements, and the optimization history live in Release Readiness.

Supported languages

The release includes 20 Tree-sitter frontends:

C, C++, C#, Dart, Elixir, Erlang, Go, Java, JavaScript, Kotlin, Lua, Objective-C, Perl, PHP, Python, Ruby, Rust, Scala, Swift, and TypeScript.

Each adapter owns its grammar and language syntax; shared analysis consumes typed compiler facts, while framework and security meaning stays in security-patterns/. See Language Support for the frontend contract and known dynamic limits.

The release binary embeds that YAML rulepack and uses the same loader and validator after materializing a content-addressed OS-cache generation. Security commands therefore work outside the source checkout; --rules-dir remains the deterministic custom/editable-pack override.

Accuracy contract

bonsai-ninja treats analysis as a compiler pipeline:

source -> Tree-sitter adapter -> typed compiler IR -> resolver/callgraph
       -> IDG fixed point -> query, security, SDK, and export views

Production taint reachability is a sparse monotone IDG fixed point. It has no BFS name search, call-depth ceiling, iteration limit, file limit, or result cap. Memory budgets can change worker concurrency, cache retention, and spill behavior; they do not change semantic scope.

Throughout this documentation, exact or exhaustive describes completion over the static facts admitted by the frontends and resolver: the engine does not silently stop that modeled work at a product-imposed cap. It does not mean that the static model recovers every possible runtime behavior, that every adapter or rule is bug-free, or that an empty result proves a program safe.

Static analysis cannot resolve every runtime-generated call. Reflection, unexpanded macros, computed imports, dynamic dispatch, and metaprogramming can lack enough source evidence. In those cases the tool reports diagnostics or analysis_incomplete_reasons; it does not invent a resolved edge. Always check completion metadata before treating an empty result as proof that no path exists.

Pagination is presentation only. If output reports another page, follow the printed page or cursor before claiming complete coverage. --all removes paging for an intentional exhaustive artifact; it does not enable a different analysis mode.

Install

Install the published Rust package from crates.io:

# Requires Rust 1.88 or newer.
cargo install bonsai-ninja --locked
bonsai-ninja --version

To replace an older Cargo-installed release with the current one:

cargo install bonsai-ninja --locked --force

Or build the release binary from a checkout:

git clone https://github.com/gromhacks/bonsai-ninja.git
cd bonsai-ninja
bash scripts/build-release.sh
./target/release/bonsai-ninja --version

The tag workflow publishes the same version to crates.io and builds release archives for Linux, macOS, and Windows on x64 and arm64. See Platform And Architecture Support for source-build requirements and parser delivery constraints on other targets. When a tagged archive is published, verify its SHA-256 checksum and GitHub/Sigstore provenance before installing:

shasum -a 256 -c bonsai-ninja-<target>.tar.gz.sha256
gh attestation verify bonsai-ninja-<target>.tar.gz \
  --repo gromhacks/bonsai-ninja

Quickstart

Use the release binary. Add --no-color --no-progress for scripts and agent workflows.

# Explain workspace roots and language coverage.
./target/release/bonsai-ninja context ./my-app --no-color --no-progress

# Find an anchor before requesting heavier semantic work.
./target/release/bonsai-ninja search ./my-app --query verify_token \
  --context 8k --no-color --no-progress

# Inspect the target and request raw dataflow only when needed.
./target/release/bonsai-ninja inspect ./my-app --query verify_token \
  --taint-flow --context 16k --no-color --no-progress

# Get one bounded compiler packet without expanding transitive paths.
./target/release/bonsai-ninja symbol-summary ./my-app --symbol verify_token \
  --context 16k --no-color --no-progress

# Run production-oriented security analysis.
./target/release/bonsai-ninja security ./my-app taint-analysis \
  --profile production --context 16k --no-color --no-progress

# Or write an exhaustive SARIF artifact for CI.
./target/release/bonsai-ninja security ./my-app taint-analysis \
  --profile production --format sarif --all \
  --output-path findings.sarif.json --no-color --no-progress

The complete walkthrough is in Getting Started. For any unfamiliar option, use the binary's --help and the CLI Reference.

Choose the smallest command

tree is a direct filesystem walk. It does not initialize the compiler, rulepack, callgraph, IDG, or security engine. Syntax inventory commands also avoid whole-workspace semantic work unless their requested result requires it.

Go deeper

• Documentation home
• Getting Started
• Concepts
• CLI Reference
• Language Support
• Output Formats
• Configuration
• CI Integration
• Rule Authoring Tutorial
• Rust SDK
• Contributing
• Release Readiness

Generated and executable coverage evidence lives in Taint Coverage Matrix, Coverage Baseline, and mega_flow Coverage. Current validation evidence and release commands live only in Release Readiness.

Contributing and license

Contributions should preserve the compiler/rule boundary and include the smallest positive and negative tests that prove the behavior. Start with Contributing and the PR Review Checklist. Participation is governed by the Code of Conduct.

Use the guided GitHub issue forms for reproducible product defects, analysis quality reports, and feature proposals. Do not attach private source code, credentials, generated analysis caches, or proprietary findings to a public issue.

Report exploitable vulnerabilities through the private process in Security Policy, not through a public issue.

bonsai-ninja is licensed under the MIT License. Dependency license policy is documented in Third-Party Licenses.