Using as a Library

big-code-analysis is published on crates.io as a Rust library. The CLI (bca) and REST server (bca-web) are both thin wrappers around the same public API, so anything they can do you can do directly from your own crate.

This section is task-oriented. For full type signatures and field docs, follow the rustdoc on docs.rs.

When to embed the library

Reach for the library (instead of shelling out to bca) when you want one or more of the following:

• In-process analysis. Avoid the cost of spawning a subprocess per file when scoring thousands of files in a custom tool, IDE plugin, or static-analysis pipeline.
• In-memory source. Score generated, pre-processed, or streamed source without writing it to disk first. See Analyzing in-memory source.
• Selective walking. Drive a custom traversal over the FuncSpace tree to extract per-function metrics on your own schedule. See Walking FuncSpace results.
• Custom output. Skip the JSON / YAML / TOML / CBOR serializers shipped under src/output/ and emit your own report format (CSV, SARIF, a database row, whatever).

If you just want a Markdown quality report or a CI threshold gate, the bca CLI is faster to wire up.

What is on offer today

• Quick start — parse a string, get a FuncSpace, print the cognitive complexity.
• Analyzing in-memory source — feed source from a buffer rather than a file.
• Reusing an existing tree-sitter Tree — feed a caller-built tree_sitter::Tree into the metric walker.
• Parse once, run metrics many times — hold a parsed Ast and run multiple metric subsets / custom walks against the same tree.
• Walking the AST directly — count syntactic constructs, find nodes by kind, detect parse errors, or build a symbol table alongside the metrics walk.
• Selecting metrics — (stub — planned).
• Walking FuncSpace results — recurse into nested function / class / impl spaces.
• Error handling — what Result<FuncSpace, MetricsError> means today and how to turn it into a useful diagnostic.
• Stability and versioning — what you can and cannot rely on across the 1.x line.

A note on API stability

The library is on the 1.x line and ships under a written stability contract: the shape of the public API is held stable across patch and minor bumps, and breaking changes are reserved for the next major bump. Every example in this section compiles against the current published crate and is expected to keep compiling across 1.x without edits.

Metric values may still drift across minor bumps when a grammar pin moves or a metric definition is fixed — see STABILITY.md § What is stable in value for the carve-out. Each drift is called out in the changelog entry that introduces it.