big-code-analysis

big-code-analysis measures how maintainable your code is. The bca command line tool computes per-function metrics for more than twenty programming languages: cyclomatic and cognitive complexity, Halstead, maintainability index, ABC, lines-of-code variants, and the rest of the metric suite. It parses with tree-sitter, so it needs no compiler, build step, or language runtime: point it at a directory and it prints numbers.

The project is a hard fork of Mozilla's rust-code-analysis that grows the metric engine into a code-quality toolchain:

• bca check: a threshold gate with baselines, in-source suppression markers, and CI-friendly exit codes.
• Agent feedback: violations piped back into Claude Code or opencode after every edit (below).
• bca report: Markdown and HTML hotspot reports.
• bca vcs: change-history metrics over a git tree (churn, ownership dilution, bug-fix history).
• Library bindings: the same engine as a Rust crate, a Python package, and a REST server (bca-web).

The full documentation lives in the book: metrics definitions, command reference, CI recipes, and library guides.

Feed metrics to your coding agent

Coding agents write a lot of code, and nothing in their loop tells them a function has become too complex to maintain. bca check closes that loop: it checks each file the agent edits and reports the offending functions back into the model's context the moment the edit lands. All it needs is bca on PATH (see Quick start) plus a few lines of config.

• Claude Code: a PostToolUse hook runs bca check on the edited file and feeds violations back through stderr. This repository dogfoods a reference hook at .claude/hooks/bca-check.sh.
• opencode: a tool.execute.after plugin does the same; the reference copy is at .opencode/plugins/bca-check.js.

The agent feedback recipe has copy-pasteable wiring for both tools, plus the guidance block that keeps an agent from gaming the metric instead of simplifying the code.

Quick start

Install a prebuilt bca from the releases page (signed tarballs for Linux, macOS, and Windows, plus .deb, .rpm, and .apk packages), or install it from a package registry:

cargo install big-code-analysis-cli    # or: pip install big-code-analysis-cli

Then, from a project root:

bca metrics src/main.rs      # per-function metric tree for one file
bca init                     # scaffold bca.toml, .bcaignore, .bca-baseline.toml
bca check                    # exit 2 when a function crosses a threshold
bca report -O html -o report.html

The Commands chapter of the book documents every subcommand, flag, and output format.

Quality gates and reports in CI

bca check reads thresholds, baselines, and excludes from a committed bca.toml, so CI, local runs, and agent hooks all gate on the same signal. bca report turns the same run into a Markdown comment for a pull request or an HTML hotspot page. This repository gates itself on every push and publishes the result:

• HTML hotspot report: https://dekobon.github.io/big-code-analysis/reports/index.html
• Markdown PR/MR comment: https://dekobon.github.io/big-code-analysis/reports/report.md

The CI integration recipe is the adoption guide: a pinned-release install with checksum verification, ready-made GitHub Actions and GitLab CI jobs, and the baselines and local threshold gates recipes for ratcheting an existing codebase.

Use it as a library

The big-code-analysis crate is published on crates.io under a written stability contract (STABILITY.md): the public API holds stable across patch and minor bumps within 2.x, and breaking changes wait for the next major. Metric values may still drift across minor bumps when a grammar pin moves or a metric definition is fixed; the contract spells out exactly what is and is not promised.

[dependencies]
big-code-analysis = "2"

Every grammar sits behind a per-language Cargo feature; the default is all of them, and consumers who need a subset can disable default features and re-enable individual languages. See Per-language Cargo features in the book, and the Using as a Library chapter for task-oriented walkthroughs (quick start, in-memory analysis, walking FuncSpace results, error handling). The API reference is on docs.rs.

Python bindings (PyO3) live in big-code-analysis-py/ and ship the same metric pipeline as the big-code-analysis package on PyPI. The book's Python Bindings chapter covers installation, batch and async processing, and SARIF output.

For a service, bca-web wraps the library in a REST API; see Operating bca-web.

Building and contributing

The repository is a Cargo workspace with a Makefile wrapper for common tasks. Run make help for the full list.

make build        # debug build of the entire workspace
make test         # full test suite (workspace, all features)
make pre-commit   # full local gate, mirrors CI

CONTRIBUTING.md covers the contribution workflow, and the Developers Guide in the book covers internals: adding a language, implementing a metric, and updating grammars.

Licenses

• The vendored grammar crates (tree-sitter-ccomment, tree-sitter-mozcpp, tree-sitter-mozjs, tree-sitter-preproc, tree-sitter-tcl) are released under the MIT license.

• big-code-analysis, big-code-analysis-cli, big-code-analysis-web, and big-code-analysis-py are released under the Mozilla Public License v2.0.