bonsai-ninja: Instructions file for Codex

bonsai-ninja

Use bonsai-ninja when you need structural code intelligence: map a repo, find symbols, trace behavior, debug dataflow, or run SAST.

Command truth comes from the binary:

./target/release/bonsai-ninja --help
./target/release/bonsai-ninja <command> --help
./target/release/bonsai-ninja security --help

Prefer ./target/release/bonsai-ninja; use debug only if release is missing. For scripts use --format json --no-color --no-progress; add --all or --context uncapped only for intentional exhaustive artifacts. For LLM-readable text use --no-color --no-progress --context 16k. Keep the workspace positional and prefer explicit selector flags (--query, --symbol, --file, --from, --to, --id) in scripts and agent calls. Positional selectors remain supported for interactive use, but the CLI rejects supplying both forms. Output files accept -o, --output, and --output-path. Use --html-output <file> for a standalone themed human report rendered from the command's canonical JSON result (the same document --format json prints); it must never enable additional analysis and is mutually exclusive with --output-path. For save-time workflows, keep index <workspace> --watch --no-progress running; command and SDK facades refresh saved file changes before they render. index <workspace> is the syntax/construct warm-up path: it parses source and builds declaration/import indexes without forcing a whole-workspace semantic prewarm. Use index <workspace> --semantic only when you intentionally want structural semantic sidecars and the external workspace-cache manifest.json built up front; commands still validate sidecar headers/payloads before reuse and compute requested exact facts on demand. Retrieval is candidate lookup only: search and literal-filtered browse can reuse a fresh sidecar before candidate lookup, and large-workspace inspect-graph can use a warmed sidecar only before opening a scoped workspace. Rendered facts still hydrate through canonical APIs, and scoped query workspaces do not publish partial retrieval sidecars under the full workspace cache.

Analysis sidecars live in a canonical-path-keyed OS cache directory, not in the inspected repository; cache stats <workspace> reports it and BONSAI_WORKSPACE_DIR overrides it. The cache root carries a locked canonical workspace binding so dependency-manifest freshness cannot be lost when a sidecar path is outside the source tree. Workspace-local rule overlays remain under <workspace>/.bonsai/rules/ and are not analysis caches.

A workspace ignored by an enclosing Git repository cannot use an empty Git status as freshness proof. Manifest validation and live refresh must fall back to filesystem reconciliation, including file additions, edits, renames, and deletions, without changing the selected analysis scope.

Treat the analyzer as a compiler pipeline. Each language adapter owns its Tree-sitter grammar, source-syntax recognition, declaration/import lowering, literal/value node inventories, and FlowEvent/capability facts. String and comment length filters consume adapter-proven lexical body lengths; shared browse code must not guess those boundaries by stripping source delimiters. Shared analysis consumes that typed IR; do not add language-id branches, cross-language token inventories, or API-name guesses to shared crates. Library/package/framework identities and every security-sensitive value belong in security-patterns/langs/<lang>, not in shared analysis or an adapter; adapters emit generic syntax/capability facts and rule data assigns their security meaning. Pack-wide package spelling, review profiles, test-path policy, dependency metadata, and taxonomy live in security-patterns/metadata.yml. The production taint engine is the sparse IDG fixed-point closure. It has no BFS name search, call-depth ceiling, iteration limit, or result cap. Paging and diagnostic path limits affect rendering only and must report truncation explicitly.