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.
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 --versionNote 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.
cargo install big-code-analysis-clicd big-code-analysis-cli/
cargo build --releasebca [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.
| Command | Purpose |
|---|---|
metrics |
Per-file metric output (-O cbor/csv/json/toml/yaml, --output-dir DIR). |
ops |
Per-file operand/operator output (same formats as metrics). |
report <FORMAT> |
Aggregated report (markdown or html). |
check |
Check per-function metrics against thresholds; exits 2 on threshold violations. |
dump |
AST dump to stdout (--line-start/--line-end to scope a range). |
find <NODE>... |
Find nodes of one or more types (--line-start/--line-end to scope a range). |
count <NODE>... |
Count nodes of one or more types. |
functions |
List functions/methods and their spans. |
strip-comments |
Remove comments from source files (--in-place). |
preproc |
Build preprocessor-data JSON for C/C++ analysis. |
list-metrics [names|descriptions] |
List computable metrics. |
Run bca <COMMAND> --help for command-specific 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-jobsis 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).--warningis a deprecated alias.--no-skip-generated— disable auto-skip of files marked as generated (see Skipping generated code).--report-skipped— log askipped (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 withbca preproc.
-w / --warnings and --report-skipped are the only universal options;
they are accepted in any position, before or after the subcommand.
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.
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.rsList all metrics with one-line descriptions:
bca list-metrics descriptionsGenerated 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.