big-code-analysis-cli

bca analyzes source code and emits per-file structured metrics, aggregated reports, AST dumps, node lookups, and more.

Migrating from the flag-style CLI? The CLI is now subcommand-driven. See the migration guide for old-form -> new-form mappings of every flag.

Installation

From PyPI (pip)

The fastest path on Linux, macOS, and Windows — no Rust toolchain required:

pip install big-code-analysis-cli   # installs the `bca` command on PATH
bca --version

Note the deliberate split between the distribution name and the command name: you pip install big-code-analysis-cli, but the installed executable is bca. The bca name on PyPI belongs to an unrelated project, and big-code-analysis is this project's importable library bindings (pip install big-code-analysis — a different deliverable). The wheel ships the full all-languages grammar set; a single py3-none-<platform> wheel covers every CPython 3.x (and PyPy) on that platform. Prebuilt wheels are published for Linux (manylinux_2_28 x86_64 / aarch64), macOS (x86_64 / arm64), and Windows (x86_64); other platforms fall back to a source build.

From crates.io (cargo)

cargo install big-code-analysis-cli

From source

cd big-code-analysis-cli/
cargo build --release

Usage

bca [OPTIONS] <COMMAND> [COMMAND OPTIONS]

The command picks what to do; its options describe both what to walk (paths, includes/excludes, parallelism, language overrides) and how to format the result. Input-selection and walker-tuning flags are scoped to the subcommand that consumes them and must be written after the subcommand token — only -w / --warnings and --report-skipped are universal and accepted in any position.

Commands

Run bca <COMMAND> --help for command-specific options.

Walking options

These input-selection and walker-tuning flags are accepted by the walking subcommands (metrics, ops, report, check, dump, find, count, functions, strip-comments) and must be written after the subcommand. A flag passed to a subcommand that never consumes it is a hard usage error (exit 1), not a silent no-op.

• -p, --paths <FILE>... — input files or directories. The walking subcommands also accept paths positionally (bca metrics src/).
• -I, --include <GLOB> — include files matching pattern (repeatable).
• -X, --exclude <GLOB> — exclude files matching pattern (repeatable).
• -j, --jobs <N> — worker threads (--num-jobs is a deprecated alias).
• -l, --language <LANG> — force a language instead of inferring. Accepts a language name (rust) or extension (rs); unknown values error out.
• -w, --warnings — print warnings (skipped files, unrecognized languages). --warning is a deprecated alias.
• --no-skip-generated — disable auto-skip of files marked as generated (see Skipping generated code).
• --report-skipped — log a skipped (generated): <path> line to stderr for every file the generated-code detector excludes.
• --preproc-data <FILE> — consume an existing preproc JSON during C/C++ analysis. Build one with bca preproc.

-w / --warnings and --report-skipped are the only universal options; they are accepted in any position, before or after the subcommand.

Building with a subset of languages

The shipped bca binary compiles every supported tree-sitter grammar in. The big-code-analysis-cli crate pins the library's all-languages feature set explicitly, so passing --no-default-features or a custom --features list to cargo build -p big-code-analysis-cli does not drop grammars from the resulting binary — feature selection on the CLI crate is not honoured (see #252 for the rationale: dropping a grammar silently from a user-facing binary would surface as "language X stopped working" rather than a build error).

Consumers who need a reduced feature set should embed the big-code-analysis library in their own Rust code and control feature selection in their own Cargo.toml. See the library's per-language Cargo features chapter for the full list of features and a worked example.

Examples

Per-file JSON metrics:

bca metrics --paths ./src -O json --output-dir ./out/

Aggregated markdown quality report:

bca report markdown --paths "$PWD" --jobs $(nproc) \
    --top 20 --strip-prefix "$PWD/"

AST dump for one file:

bca dump ./file.rs

List all metrics with one-line descriptions:

bca list-metrics descriptions

Skipping generated code

Generated bindings (protobuf stubs, OpenAPI clients, lex/yacc output, build-system plumbing) inflate metrics for code no human will refactor. By default, bca scans the first ~50 lines / 5 KiB of each file for a generated-code marker and skips matches before parsing.

Recognized markers (case-insensitive):

• @generated — Facebook / Meta convention; also emitted by buck2, rustfmt, prettier, and many code generators.
• DO NOT EDIT — Go's // Code generated by … DO NOT EDIT. is the canonical form; the bare phrase is also widely copied (Bazel, protoc, OpenAPI clients).
• GENERATED CODE — Lizard's marker, recognized for compatibility.

A marker phrase that appears only deep in the file body (past the scan window) does not trigger the skip.

To restore the previous behavior and analyze everything, pass --no-skip-generated. To audit which files were excluded, pass --report-skipped; the CLI logs skipped (generated): <path> to stderr for each file.