big-code-analysis-cli 2.0.0__py3-none-manylinux_2_28_aarch64.whl

man/bca.1

@@ -0,0 +1,93 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca \- Analyze source code.
+.SH SYNOPSIS
+\fBbca\fR [\fB\-w\fR|\fB\-\-warnings\fR] [\fB\-\-report\-skipped\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Analyze source code.
+.SH OPTIONS
+.TP
+\fB\-w\fR, \fB\-\-warnings\fR
+Print warnings (skipped files, unrecognized languages). `\-\-warning` (singular) is kept as a hidden alias for one release cycle and is slated for removal in the next major
+.TP
+\fB\-\-report\-skipped\fR
+Log a "skipped (generated): <path>" line to stderr for each file auto\-skipped by the generated\-code detector. Useful for auditing which files were excluded
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH SUBCOMMANDS
+.TP
+bca\-metrics(1)
+Compute per\-file metrics and emit them in a structured format
+.TP
+bca\-ops(1)
+Extract per\-file operands and operators
+.TP
+bca\-vcs(1)
+Rank files by change\-history (VCS) risk: churn, commit and author counts, ownership dilution, and bug\- / security\-fix history over a git working tree. Errors clearly outside a repo
+.TP
+bca\-report(1)
+Generate an aggregated report across the analyzed source
+.TP
+bca\-dump(1)
+Dump the AST to stdout. Each file\*(Aqs tree is prefixed with a `== <path> ==` banner so a multi\-file dump is attributable. Requires an explicit path — unlike the other walking subcommands, bare `bca dump` errors instead of dumping the whole current directory (a whole\-tree AST dump has no plausible use)
+.TP
+bca\-find(1)
+Find nodes of one or more types
+.TP
+bca\-count(1)
+Count nodes of one or more types
+.TP
+bca\-functions(1)
+List functions/methods and their spans
+.TP
+bca\-strip\-comments(1)
+Remove comments from source files
+.TP
+bca\-preproc(1)
+Generate preprocessor\-data JSON for C/C++ analysis
+.TP
+bca\-list\-metrics(1)
+List the metrics this tool can compute and exit
+.TP
+bca\-check(1)
+Check per\-function metrics against thresholds. Exits 2 when any threshold is exceeded; reserve exit 1 for tool errors so CI can distinguish "metric regression" from "tool crashed". `\-\-strict\-exit\-codes` opts into tiered codes (2\-5) that split the violation case by severity
+.TP
+bca\-init(1)
+Scaffold the canonical adoption files (`bca.toml` manifest, `.bcaignore`, `.bca\-baseline.toml`) in the current directory. Replaces the six\-step copy\-paste flow from the book\*(Aqs adoption recipe. Refuses to overwrite existing files without `\-\-force`
+.TP
+bca\-diff\-baseline(1)
+Diff two `.bca\-baseline.toml` files and report what was added, removed, worsened, or improved. Replaces the in\-the\-head TOML diff parsing the book\*(Aqs PR\-review recipe used to walk through. Exits 0 on success by default — the diff is informational, not a gate. With `\-\-exit\-code`, exits 2 when the filtered diff is non\-empty
+.TP
+bca\-diff(1)
+Compare two metric\-output runs and report, per metric, which files changed (old to new), plus files added/removed between the two sets. Each side is a per\-file JSON file or a directory tree of them (the form `bca metrics \-O json \-\-output\-dir DIR` writes). Replaces the grammar\-bump glue chain — the external `json\-minimal\-tests` binary plus `split\-minimal\-tests.py` — with one native command. Exits 0 on success by default; the diff is informational, not a gate. With `\-\-exit\-code`, exits 2 when the filtered diff is non\-empty
+.TP
+bca\-exemptions(1)
+Audit everything the `bca check` gate skips in one view: in\-source suppression markers (`bca: suppress`, `#lizard forgives`, …), `[check.exclude]` globs, and `.bca\-baseline.toml` entries. Read\-only; always exits 0 on success
+.TP
+bca\-help(1)
+Print this message or the help of the given subcommand(s)
+.SH EXTRA
+Exit codes:
+  0  success
+  1  tool error (bad flag/threshold/glob spec, unreadable input, parse failure)
+  2  metric gate: `check` thresholds exceeded / `vcs commit \-\-fail\-above` breached / `diff \-\-exit\-code` non\-empty (default contract)
+  3\-5  `check \-\-strict\-exit\-codes` only: tiered violation severity
+
+Exit code 1 is always a tool error, never a metric signal — usage errors
+(unknown flag, bad subcommand, malformed `\-\-threshold` value) exit 1, not 2.
+Codes 2\-5 are gate signals emitted only by `check`, `vcs commit \-\-fail\-above`,
+and `diff` / `diff\-baseline` when run with the opt\-in `\-\-exit\-code` flag.
+Every other subcommand exits 0 on success and 1 on error.
+
+Migrating from the flag\-style CLI? See the migration guide:
+  https://dekobon.github.io/big\-code\-analysis/migration.html
+.SH VERSION
+v2.0.0
+.SH AUTHORS
+Calixte Denizet <cdenizet@mozilla.com>, Elijah Zupancic <elijah@zupancic.name>