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

man/bca-check.1

@@ -0,0 +1,208 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-CHECK 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-check \- 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
+.SH SYNOPSIS
+\fBbca\-check\fR [\fB\-p\fR|\fB\-\-paths\fR] [\fB\-I\fR|\fB\-\-include\fR] [\fB\-X\fR|\fB\-\-exclude\fR] [\fB\-l\fR|\fB\-\-language\fR] [\fB\-\-no\-skip\-generated\fR] [\fB\-\-paths\-from\fR] [\fB\-\-exclude\-from\fR] [\fB\-\-no\-ignore\fR] [\fB\-\-no\-config\fR] [\fB\-j\fR|\fB\-\-jobs\fR] [\fB\-\-exclude\-tests\fR] [\fB\-\-cyclomatic\-count\-try\fR] [\fB\-\-preproc\-data\fR] [\fB\-\-threshold\fR] [\fB\-\-config\fR] [\fB\-\-no\-fail\fR] [\fB\-\-no\-suppress\fR] [\fB\-\-report\-suppressed\fR] [\fB\-\-report\-format\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-\-baseline\fR] [\fB\-\-write\-baseline\fR] [\fB\-\-no\-summary\fR] [\fB\-\-since\fR] [\fB\-\-changed\-only\fR] [\fB\-\-github\-annotations\fR] [\fB\-\-summary\-file\fR] [\fB\-\-no\-remediation\fR] [\fB\-\-print\-effective\-config\fR] [\fB\-\-tier\fR] [\fB\-\-exit\-codes\fR] [\fB\-\-baseline\-line\-tolerance\fR] [\fB\-\-baseline\-fuzzy\-match\fR] [\fB\-\-check\-exclude\fR] [\fB\-\-check\-exclude\-from\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIPATHS\fR] 
+.SH DESCRIPTION
+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
+.SH OPTIONS
+.TP
+\fB\-\-threshold\fR \fI<THRESHOLDS>\fR
+Threshold expressed as `<metric>=<limit>`. Repeatable. Metric names match `bca list\-metrics`; sub\-metrics use a dotted form (e.g. `loc.lloc`, `halstead.volume`). The bare `bca diff \-\-metric` spelling of a `loc` sub\-metric is accepted as an alias (`sloc` == `loc.sloc`); a bare family head with no single scalar (`halstead`, `mi`) is rejected with a "did you mean" hint. CLI flags override values from `\-\-config`. Limits must be finite and non\-negative; `0` is allowed and means "no value permitted"
+.TP
+\fB\-\-config\fR \fI<CONFIG>\fR
+Path to a TOML config with a `[thresholds]` table. Example:
+
+    [thresholds]
+    cyclomatic = 15
+    "loc.lloc" = 200
+
+CLI `\-\-threshold` flags override values read from this file.
+.TP
+\fB\-\-no\-fail\fR
+Print offenders to stderr but exit 0 even when thresholds are exceeded. Useful while adopting baselines without flipping CI red. Default: exit 2 when any threshold is exceeded
+.TP
+\fB\-\-no\-suppress\fR
+Ignore in\-source suppression markers (`bca: suppress`, `#lizard forgives`, etc.). Every threshold violation is reported regardless of comment\-based silencers. CI auditors pass this to see the raw, un\-silenced offender list
+.TP
+\fB\-\-report\-suppressed\fR
+Surface suppressed debt in the offender document instead of dropping it. Offenders silenced by an in\-source `bca: suppress` marker or covered by the baseline are still kept out of the gate (exit code and human stream are unaffected), but are emitted into the `\-\-format sarif` document carrying a SARIF `suppressions` entry — GitHub Code Scanning renders them as suppressed (closed) alerts so the debt stays visible. Only the SARIF format represents suppression; other formats ignore the flag. Mutually exclusive with `\-\-no\-suppress` (which un\-silences markers) and `\-\-write\-baseline`
+.TP
+\fB\-\-report\-format\fR \fI<FORMAT>\fR
+CI/IDE *report dialect* for offender records (Checkstyle 4.3 XML, SARIF 2.1.0 JSON, GitLab Code Climate JSON, clang/GCC warning lines, MSVC warning lines). Named `\-\-report\-format` to separate "which CI report dialect" from the data\-serialization `\-\-format` the structured subcommands use. When omitted *and* `\-\-output` is also omitted, only the human\-readable stderr stream is emitted; the exit\-code contract is unaffected. When omitted but `\-\-output` is given, the dialect is inferred from the output extension (`.sarif` → sarif, `.xml` → checkstyle); an extension with no unique dialect is a usage error. The old `\-\-format` / `\-O` / `\-\-output\-format` spellings stay hidden aliases for one release cycle and are slated for removal in 2.0
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+checkstyle
+.IP \(bu 2
+clang\-warning
+.IP \(bu 2
+code\-climate
+.IP \(bu 2
+msvc\-warning
+.IP \(bu 2
+sarif
+.RE
+.TP
+\fB\-o\fR, \fB\-\-output\fR \fI<OUTPUT>\fR
+File path for the aggregated offender document. Stdout if omitted. When `\-\-report\-format` is also omitted, the dialect is inferred from this path\*(Aqs extension (`.sarif` → sarif, `.xml` → checkstyle); a path with no dialect\-bearing extension is rejected rather than silently ignored. Parent directories are created on demand
+.TP
+\fB\-\-baseline\fR \fI<BASELINE>\fR
+Filter known offenders listed in this TOML baseline. A baselined function whose metric value has not worsened is suppressed; a worsened value (or any new offender) still fails. See the "Baselines" recipe in the book for the full adoption flow
+.TP
+\fB\-\-write\-baseline\fR [\fI<PATH>\fR]
+Walk the tree and write the current offender set to a baseline file instead of failing. The resulting file pins today\*(Aqs metric values as the baseline; subsequent `\-\-baseline <path>` runs ratchet down from there. Takes an optional path: `\-\-write\-baseline <path>` writes there; a bare `\-\-write\-baseline` (no value) writes to the `[check] baseline` key from the auto\-discovered `bca.toml` manifest (errors if no manifest baseline is set). Conflicts with `\-\-baseline`, `\-\-report\-format`, `\-\-output`, `\-\-since`, and `\-\-changed\-only` — diff\-scope filtering would write a *partial* baseline that the next non\-`\-\-changed\-only` run would treat as a complete snapshot, silently masking every offender outside the diff scope
+.TP
+\fB\-\-no\-summary\fR
+Skip the trailing per\-file rollup footer. The footer groups violations by file and cites the single worst\-ratio metric per file. Pass this when downstream tooling grep\-pipes the stderr stream and would be confused by the trailing summary block. Default: footer enabled
+.TP
+\fB\-\-since\fR \fI<SINCE>\fR
+Git ref to diff `HEAD` against. The set of files reported by `git diff \-\-name\-only <ref>...HEAD` is surfaced first in the summary footer under "Files in this range:", so a reader scanning a CI log sees their own contributions before the legacy offender list. Defaults to auto\-detection from `BCA_DIFF_BASE`, `GITHUB_BASE_REF` (PR runs), or `GITHUB_EVENT_BEFORE` (push runs), in that precedence
+.TP
+\fB\-\-changed\-only\fR
+Drop violations from files outside the `\-\-since`/auto\-detected touched set entirely (terser CI output for PR gates). Requires a resolvable diff base, either via `\-\-since` or one of the auto\-detected env vars; failing to resolve is fatal so a misconfigured CI does not silently turn the gate into a no\-op
+.TP
+\fB\-\-github\-annotations\fR[=\fI<auto|always|never>\fR] [default: auto]
+Emit GitHub Actions `::error file=…,line=…,title=…::msg` workflow commands per violation so the GHA UI renders them as inline annotations on the file\-diff view. Additive to the human\-readable stderr stream — annotations ride on top, they don\*(Aqt replace it. Tri\-state `<auto|always|never>` mirroring `\-\-color`: `auto` (default) emits annotations when `$GITHUB_ACTIONS == "true"`; `always` forces them on; `never` suppresses them even inside a GHA step (so a workflow that runs `bca check` twice can annotate from only one run). A bare `\-\-github\-annotations` means `always`. Capped at 10 per metric (GitHub Actions surfaces at most 10 errors per step in the UI); overflow rolls up to one `::error::N more <metric> violations not shown` line per affected metric so the count is still visible
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+auto: Enable when the GitHub Actions env signal is present
+.IP \(bu 2
+always: Always enable, even outside a GHA step
+.IP \(bu 2
+never: Never enable, even inside a GHA step
+.RE
+.TP
+\fB\-\-summary\-file\fR \fI<PATH|auto|never>\fR
+Where to append a markdown digest of the violations — per\-file rollup table, per\-metric breakdown, and top\-N offenders by `value / limit` ratio. Mirrors the format `bca report markdown` produces so a reader skimming the GHA step\-summary panel sees a familiar table layout. Accepts a file path, or the keywords `auto` / `never`: `auto` (the default when the flag is omitted) appends to `$GITHUB_STEP_SUMMARY` when that env var is set; `never` suppresses the digest even inside a GHA step; a path appends there unconditionally. The block is bracketed by HTML\-comment markers so a retried step replaces (not stacks) the previous digest
+.TP
+\fB\-\-no\-remediation\fR
+Suppress the trailing "\-\-\- next steps \-\-\-" remediation block that names the artifact, prints a copy\-paste\-safe `\-\-write\-baseline` refresh invocation, and links to the Baselines recipe. By default the block is emitted on failure (and in `$GITHUB_STEP_SUMMARY` when present) so a first\-time reader of a failing CI log can see what to do next without leaving the page
+.TP
+\fB\-\-print\-effective\-config\fR [\fI<FORMAT>\fR]
+Print the resolved threshold/check configuration (after merging `\-\-config` TOML + `\-\-threshold` CLI overrides) to stdout, then exit 0 without walking the codebase. Default format is TOML; pass `=json` for JSON. Mutually exclusive with `\-\-write\-baseline` — this flag is a read\-only debug aid, not a side\-effecting operation. Output is round\-trippable: piping it back through `\-\-config` produces the same effective view
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+toml
+.IP \(bu 2
+json
+.RE
+.TP
+\fB\-\-tier\fR[=\fI<hard|soft|soft=RATIO>\fR] [default: hard]
+Which threshold tier to gate against. Accepts `hard`, `soft`, or `soft=<RATIO>`:
+
+\- `hard` (default) — flag a function only when a metric is at or over its `[thresholds]` limit. \- `soft` — early\-warning tier: flag a function when a metric reaches `RATIO` (default 0.95) of any limit, i.e. before the hard gate trips. With a `[thresholds.soft]` table present, the per\-metric soft limits take precedence over the blanket ratio (metrics absent from it inherit their hard limit). \- `soft=0.90` — soft tier scaling every limit by 0.90; `soft=1.0` disables the blanket scale (a soft tier driven only by an explicit `[thresholds.soft]` table).
+
+Resolution order: `[thresholds]` (manifest + `\-\-config`) → `[thresholds.soft]` or the soft ratio → absolute `\-\-threshold name=value` overrides (applied last, never scaled). Both tiers ratchet through the same `\-\-baseline`. `RATIO` must lie in `(0, 1]`; an out\-of\-range value is a usage error.
+.TP
+\fB\-\-exit\-codes\fR[=\fI<default|tiered>\fR]
+Exit\-code style: `default` keeps the stable 0/1/2 contract; `tiered` splits exit `2` by severity so CI can branch without parsing the `[new]` / `[regr +N%]` stderr tags:
+
+\- `0` — clean. \- `1` — tool error (bad config, unknown metric, unreadable path). \- `2` — new offenders only (no baseline entry matched). \- `3` — regressions only (a baselined offender worsened). \- `4` — both new offenders and regressions. \- `5` — at least one `\-\-tier=soft` violation also breaches the hard limit (more urgent than soft\-band encroachment). Only emitted at the soft tier; at the hard tier every violation is a hard breach by definition, so the 2/3/4 split is used instead.
+
+Every fail\-state stays non\-zero, so existing `exit != 0 → fail` tooling is unaffected; only consumers that test `$? \-eq 2` explicitly need to widen to 2\-5. `\-\-no\-fail` still forces exit `0`. Mirrors the `[check] exit_codes` key in `bca.toml`; the CLI value overrides the manifest in either direction.
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+default
+.IP \(bu 2
+tiered
+.RE
+.TP
+\fB\-\-baseline\-line\-tolerance\fR \fI<LINES>\fR
+Tolerance, in lines, for matching a `\-\-baseline` entry whose qualified symbol is ambiguous (two methods with the same name on different `impl` blocks, overloads, collided anonymous spaces). Unambiguous symbols match regardless of line drift; this only disambiguates a tie. Defaults to 50. Mirrored by the `baseline_line_tolerance` key in `bca.toml`
+.TP
+\fB\-\-baseline\-fuzzy\-match\fR[=\fI<BOOL>\fR]
+Enable rename\-tolerant baseline matching: when a `\-\-baseline` entry\*(Aqs qualified symbol no longer matches but the function body is unchanged (a rename that kept the shape), match on a normalised body hash instead. Off by default. The hash is also written into the baseline by `\-\-write\-baseline` when this flag is set, so populate it once with a fuzzy write to enable fuzzy reads. Value\-taking: a bare `\-\-baseline\-fuzzy\-match` means `true`; `\-\-baseline\-fuzzy\-match=false` forces it off even when the `baseline_fuzzy_match` key in `bca.toml` set it. The CLI value overrides the manifest in either direction
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+true
+.IP \(bu 2
+false
+.RE
+.TP
+\fB\-\-check\-exclude\fR \fI<GLOB>\fR
+Glob for files to analyse and report but exempt from the threshold gate. Repeatable. Matching files are still walked, parsed, metric\*(Aqd, and shown by `bca report`; `bca check` simply drops their violations before emitting offenders and before `\-\-write\-baseline` records anything — so structural exemptions (test fixtures, generated code, macro\-dispatch modules) stay out of `.bca\-baseline.toml`. Precedence: in\-source `bca: suppress` markers win first, then these globs, then the baseline. Unioned with `\-\-check\-exclude\-from` and with the `bca.toml` `[check] exclude` list: CLI values are *added to* (merged with), not a replacement for, the manifest\*(Aqs exemptions, so a CLI `\-\-check\-exclude` never silently re\-gates a path the project config deliberately exempted. Pass `\-\-no\-config` to ignore the manifest entirely. Globs match the path as walked, exactly like `\-\-exclude`
+.TP
+\fB\-\-check\-exclude\-from\fR \fI<CHECK_EXCLUDE_FROM>\fR
+Read newline\-separated `\-\-check\-exclude` globs from a file (one per line, `.gitignore`\-style: blank lines and `#`\-comments are skipped). Use `\-` for stdin; to pass a file literally named `\-`, use `./\-`. Unioned with any `\-\-check\-exclude` values. Convention is a `.bcacheckignore` at the repo root, mirroring `.bcaignore` for the walker. Mirrored by the `[check] exclude_from` key in `bca.toml`
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help (see a summary with \*(Aq\-h\*(Aq)
+.SH "INPUT SELECTION"
+.TP
+\fB\-p\fR, \fB\-\-paths\fR \fI<PATHS>\fR
+Input files or directories to analyze. Unioned with any positional `[PATHS]`. Defaults to the current directory (`.`) when omitted and no manifest `paths` is set; an explicitly\-given path that does not exist is an error (exit 1)
+.TP
+\fB\-I\fR, \fB\-\-include\fR \fI<INCLUDE>\fR
+Glob to include files. Repeat the flag to add multiple globs (`\-I \*(Aq*.rs\*(Aq \-I \*(Aq*.toml\*(Aq`); each occurrence takes exactly one value, so a positional argument that follows is never swallowed. A leading `./` is optional: `dir/**` and `./dir/**` are equivalent
+.TP
+\fB\-X\fR, \fB\-\-exclude\fR \fI<EXCLUDE>\fR
+Glob to exclude files. Repeat the flag to add multiple globs (`\-X \*(Aq*.tmp\*(Aq \-X \*(Aq*.bak\*(Aq`); each occurrence takes exactly one value, so a positional argument that follows is never swallowed. A leading `./` is optional: `dir/**` and `./dir/**` are equivalent. CLI values are *merged with* (unioned, not a replacement for) any `bca.toml` `exclude` list and any `\-\-exclude\-from` patterns, so a CLI `\-\-exclude` never silently un\-excludes a directory the project config deliberately skipped. Pass `\-\-no\-config` to ignore the manifest entirely
+.TP
+\fB\-l\fR, \fB\-\-language\fR \fI<LANGUAGE>\fR
+Force a language instead of inferring from extension. Accepts a canonical language name (`rust`, `python`, `cpp`, …) or a file extension (`rs`, `py`, …). An unrecognized value is a hard error
+.TP
+\fB\-\-no\-skip\-generated\fR
+Disable auto\-skip of files marked as generated (e.g. `@generated`, `DO NOT EDIT`, `GENERATED CODE` near the top). By default the CLI skips such files so generated bindings do not skew metrics
+.TP
+\fB\-\-paths\-from\fR \fI<PATHS_FROM>\fR
+Read newline\-separated input paths from a file. Use `\-` to read from stdin. Combined as a union with any `\-\-paths` values; globs still apply. Blank lines are skipped; `#` is treated as a path character (not a comment). To pass a file literally named `\-`, use `./\-`
+.TP
+\fB\-\-exclude\-from\fR \fI<EXCLUDE_FROM>\fR
+Read additional `\-\-exclude` glob patterns from a file (one per line, `.gitignore`\-style). Blank lines and lines whose first non\-whitespace character is `#` are skipped. Use `\-` to read from stdin; to pass a file literally named `\-`, use `./\-`. Patterns are unioned with any `\-\-exclude` values into a single deny\-set; order does not matter. Convention is a `.bcaignore` at the repo root, mirroring `.gitignore` / `.dockerignore`
+.TP
+\fB\-\-no\-ignore\fR
+Disable `.gitignore` / `.ignore` / global gitignore awareness when expanding input directories. Explicit file paths are always honored regardless of this flag
+.TP
+\fB\-\-no\-config\fR
+Skip auto\-discovery of a `bca.toml` manifest. By default `bca` climbs from the working directory to the repo root looking for `bca.toml` and merges its keys *under* any explicit CLI flags. Pass this for raw, fully\-explicit invocations that must not pick up repo\-level config (e.g. a reproducible CI one\-liner). When no manifest is discovered this flag is a no\-op
+.TP
+[\fIPATHS\fR]
+Input files or directories to analyze, given positionally (`bca metrics src/ tests/`). Unioned with any `\-\-paths`/`\-p` values
+.SH "WALKER TUNING"
+.TP
+\fB\-j\fR, \fB\-\-jobs\fR \fI<N|auto>\fR [default: auto]
+Number of jobs.
+
+Defaults to the effective CPU count as reported by the OS (cgroup\-quota\- and cpuset\-aware on Linux). Pass an explicit integer or `auto` to override. `\-\-jobs 1` forces serial mode for debugging. `\-\-num\-jobs` is kept as a hidden alias for one release cycle and is slated for removal in the next major.
+.TP
+\fB\-\-exclude\-tests\fR
+Exclude inline test code from metric computation. Currently applies to Rust only (skips `#[test]`, `#[cfg(test)]`, `#[tokio::test]`, `#[rstest]`, `#![cfg(test)]` items and their subtrees). Default is off — every node is counted, so numbers stay byte\-for\-byte stable. Languages without a test\-subtree skip rule ignore this flag
+.TP
+\fB\-\-cyclomatic\-count\-try\fR[=\fI<BOOL>\fR]
+Whether Rust\*(Aqs `?` operator (the `try_expression` node) contributes to cyclomatic complexity (standard and modified). Defaults to `true` — `?` counts +1, matching upstream rust\-code\-analysis and every published metric value. Pass `\-\-cyclomatic\-count\-try=false` to treat `?` as linear error propagation — useful when cyclomatic is used as a maintainability gate that should not penalize fallible\-but\-linear code. Rust\-only: no other language emits the node, so the flag is inert elsewhere. Mirrors the `cyclomatic_count_try` manifest key; the CLI value overrides the manifest in either direction
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+true
+.IP \(bu 2
+false
+.RE
+.SH PREPROCESSOR
+.TP
+\fB\-\-preproc\-data\fR \fI<PREPROC_DATA>\fR
+Existing preprocessor\-data JSON to consume during C/C++ analysis. Use `bca preproc` to produce one

man/bca-count.1

@@ -0,0 +1,73 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-COUNT 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-count \- Count nodes of one or more types
+.SH SYNOPSIS
+\fBbca\-count\fR <\fB\-t\fR|\fB\-\-type\fR> [\fB\-p\fR|\fB\-\-paths\fR] [\fB\-I\fR|\fB\-\-include\fR] [\fB\-X\fR|\fB\-\-exclude\fR] [\fB\-l\fR|\fB\-\-language\fR] [\fB\-\-no\-skip\-generated\fR] [\fB\-\-paths\-from\fR] [\fB\-\-exclude\-from\fR] [\fB\-\-no\-ignore\fR] [\fB\-\-no\-config\fR] [\fB\-j\fR|\fB\-\-jobs\fR] [\fB\-\-exclude\-tests\fR] [\fB\-\-cyclomatic\-count\-try\fR] [\fB\-\-preproc\-data\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIPATHS\fR] 
+.SH DESCRIPTION
+Count nodes of one or more types
+.SH OPTIONS
+.TP
+\fB\-t\fR, \fB\-\-type\fR \fI<NODE_TYPE>\fR
+Node\-type name to match. Repeat the flag to match several (`\-t function_item \-t struct_item`). Required: pass at least one
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help (see a summary with \*(Aq\-h\*(Aq)
+.SH "INPUT SELECTION"
+.TP
+\fB\-p\fR, \fB\-\-paths\fR \fI<PATHS>\fR
+Input files or directories to analyze. Unioned with any positional `[PATHS]`. Defaults to the current directory (`.`) when omitted and no manifest `paths` is set; an explicitly\-given path that does not exist is an error (exit 1)
+.TP
+\fB\-I\fR, \fB\-\-include\fR \fI<INCLUDE>\fR
+Glob to include files. Repeat the flag to add multiple globs (`\-I \*(Aq*.rs\*(Aq \-I \*(Aq*.toml\*(Aq`); each occurrence takes exactly one value, so a positional argument that follows is never swallowed. A leading `./` is optional: `dir/**` and `./dir/**` are equivalent
+.TP
+\fB\-X\fR, \fB\-\-exclude\fR \fI<EXCLUDE>\fR
+Glob to exclude files. Repeat the flag to add multiple globs (`\-X \*(Aq*.tmp\*(Aq \-X \*(Aq*.bak\*(Aq`); each occurrence takes exactly one value, so a positional argument that follows is never swallowed. A leading `./` is optional: `dir/**` and `./dir/**` are equivalent. CLI values are *merged with* (unioned, not a replacement for) any `bca.toml` `exclude` list and any `\-\-exclude\-from` patterns, so a CLI `\-\-exclude` never silently un\-excludes a directory the project config deliberately skipped. Pass `\-\-no\-config` to ignore the manifest entirely
+.TP
+\fB\-l\fR, \fB\-\-language\fR \fI<LANGUAGE>\fR
+Force a language instead of inferring from extension. Accepts a canonical language name (`rust`, `python`, `cpp`, …) or a file extension (`rs`, `py`, …). An unrecognized value is a hard error
+.TP
+\fB\-\-no\-skip\-generated\fR
+Disable auto\-skip of files marked as generated (e.g. `@generated`, `DO NOT EDIT`, `GENERATED CODE` near the top). By default the CLI skips such files so generated bindings do not skew metrics
+.TP
+\fB\-\-paths\-from\fR \fI<PATHS_FROM>\fR
+Read newline\-separated input paths from a file. Use `\-` to read from stdin. Combined as a union with any `\-\-paths` values; globs still apply. Blank lines are skipped; `#` is treated as a path character (not a comment). To pass a file literally named `\-`, use `./\-`
+.TP
+\fB\-\-exclude\-from\fR \fI<EXCLUDE_FROM>\fR
+Read additional `\-\-exclude` glob patterns from a file (one per line, `.gitignore`\-style). Blank lines and lines whose first non\-whitespace character is `#` are skipped. Use `\-` to read from stdin; to pass a file literally named `\-`, use `./\-`. Patterns are unioned with any `\-\-exclude` values into a single deny\-set; order does not matter. Convention is a `.bcaignore` at the repo root, mirroring `.gitignore` / `.dockerignore`
+.TP
+\fB\-\-no\-ignore\fR
+Disable `.gitignore` / `.ignore` / global gitignore awareness when expanding input directories. Explicit file paths are always honored regardless of this flag
+.TP
+\fB\-\-no\-config\fR
+Skip auto\-discovery of a `bca.toml` manifest. By default `bca` climbs from the working directory to the repo root looking for `bca.toml` and merges its keys *under* any explicit CLI flags. Pass this for raw, fully\-explicit invocations that must not pick up repo\-level config (e.g. a reproducible CI one\-liner). When no manifest is discovered this flag is a no\-op
+.TP
+[\fIPATHS\fR]
+Input files or directories to analyze, given positionally (`bca metrics src/ tests/`). Unioned with any `\-\-paths`/`\-p` values
+.SH "WALKER TUNING"
+.TP
+\fB\-j\fR, \fB\-\-jobs\fR \fI<N|auto>\fR [default: auto]
+Number of jobs.
+
+Defaults to the effective CPU count as reported by the OS (cgroup\-quota\- and cpuset\-aware on Linux). Pass an explicit integer or `auto` to override. `\-\-jobs 1` forces serial mode for debugging. `\-\-num\-jobs` is kept as a hidden alias for one release cycle and is slated for removal in the next major.
+.TP
+\fB\-\-exclude\-tests\fR
+Exclude inline test code from metric computation. Currently applies to Rust only (skips `#[test]`, `#[cfg(test)]`, `#[tokio::test]`, `#[rstest]`, `#![cfg(test)]` items and their subtrees). Default is off — every node is counted, so numbers stay byte\-for\-byte stable. Languages without a test\-subtree skip rule ignore this flag
+.TP
+\fB\-\-cyclomatic\-count\-try\fR[=\fI<BOOL>\fR]
+Whether Rust\*(Aqs `?` operator (the `try_expression` node) contributes to cyclomatic complexity (standard and modified). Defaults to `true` — `?` counts +1, matching upstream rust\-code\-analysis and every published metric value. Pass `\-\-cyclomatic\-count\-try=false` to treat `?` as linear error propagation — useful when cyclomatic is used as a maintainability gate that should not penalize fallible\-but\-linear code. Rust\-only: no other language emits the node, so the flag is inert elsewhere. Mirrors the `cyclomatic_count_try` manifest key; the CLI value overrides the manifest in either direction
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+true
+.IP \(bu 2
+false
+.RE
+.SH PREPROCESSOR
+.TP
+\fB\-\-preproc\-data\fR \fI<PREPROC_DATA>\fR
+Existing preprocessor\-data JSON to consume during C/C++ analysis. Use `bca preproc` to produce one

man/bca-diff-baseline.1

@@ -0,0 +1,55 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-DIFF-BASELINE 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-diff\-baseline \- 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
+.SH SYNOPSIS
+\fBbca\-diff\-baseline\fR [\fB\-O\fR|\fB\-\-format\fR] [\fB\-\-added\-only\fR] [\fB\-\-removed\-only\fR] [\fB\-\-worsened\-only\fR] [\fB\-\-improved\-only\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-\-strip\-prefix\fR] [\fB\-\-exit\-code\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIOLD\fR> <\fINEW\fR> 
+.SH DESCRIPTION
+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
+.SH OPTIONS
+.TP
+\fB\-O\fR, \fB\-\-format\fR \fI<FORMAT>\fR [default: text]
+Output style: `text` (default), `markdown`, or `json`
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+text
+.IP \(bu 2
+markdown
+.IP \(bu 2
+json
+.RE
+.TP
+\fB\-\-added\-only\fR
+Render only the "Added" section (combinable with the other `\-\-*\-only` flags). Ignored by `\-\-format json`
+.TP
+\fB\-\-removed\-only\fR
+Render only the "Removed" section. Ignored by `\-\-format json`
+.TP
+\fB\-\-worsened\-only\fR
+Render only the "Worsened" section. Ignored by `\-\-format json`
+.TP
+\fB\-\-improved\-only\fR
+Render only the "Improved" section. Ignored by `\-\-format json`
+.TP
+\fB\-o\fR, \fB\-\-output\fR \fI<OUTPUT>\fR
+Output file. Stdout if omitted
+.TP
+\fB\-\-strip\-prefix\fR \fI<STRIP_PREFIX>\fR [default: ]
+Path prefix to strip from displayed file paths in the TTY and Markdown per\-file tables. No\-op for `\-\-format json`, whose paths are a stable machine identity
+.TP
+\fB\-\-exit\-code\fR
+Exit with the metric\-gate code (`2`) when the diff — after the active `\-\-*\-only` section filtering — is non\-empty; exit `0` when it is empty. Opt\-in (`git diff \-\-exit\-code`\-style) for grammar\-bump CI that wants a boolean "anything changed" without parsing the output. Default (flag absent) always exits `0` on success. A tool error still exits `1` regardless
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fIOLD\fR>
+Old (base) baseline file — the "before" side of the diff
+.TP
+<\fINEW\fR>
+New (updated) baseline file — the "after" side of the diff

man/bca-diff.1

@@ -0,0 +1,104 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-DIFF 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-diff \- 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
+.SH SYNOPSIS
+\fBbca\-diff\fR [\fB\-p\fR|\fB\-\-paths\fR] [\fB\-I\fR|\fB\-\-include\fR] [\fB\-X\fR|\fB\-\-exclude\fR] [\fB\-l\fR|\fB\-\-language\fR] [\fB\-\-no\-skip\-generated\fR] [\fB\-\-paths\-from\fR] [\fB\-\-exclude\-from\fR] [\fB\-\-no\-ignore\fR] [\fB\-\-no\-config\fR] [\fB\-j\fR|\fB\-\-jobs\fR] [\fB\-\-exclude\-tests\fR] [\fB\-\-cyclomatic\-count\-try\fR] [\fB\-\-since\fR] [\fB\-O\fR|\fB\-\-format\fR] [\fB\-\-min\-change\fR] [\fB\-\-metric\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-\-strip\-prefix\fR] [\fB\-\-exit\-code\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIOLD\fR] [\fINEW\fR] 
+.SH DESCRIPTION
+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
+.SH OPTIONS
+.TP
+\fB\-\-since\fR \fI<SINCE>\fR
+Analyze the tree at this git ref for the "before" side instead of reading a captured metric set. Hard\-errors (exit 1) if the process is not in a git checkout, `git` is missing, or the ref does not resolve. Honors the same `\-\-paths` / `\-\-include` / `\-\-exclude` selection as the rest of the CLI so both sides analyze the same file set.
+
+In this mode the before side comes from `<ref>` and the after side is the working tree, so at most one positional is accepted and it is a relative path *scope* (equivalent to `\-\-paths`) applied to both sides; omit it to diff the whole tree. Passing two positionals with `\-\-since` is rejected at runtime.
+.TP
+\fB\-O\fR, \fB\-\-format\fR \fI<FORMAT>\fR [default: text]
+Output style: `text` (default), `markdown`, or `json`
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+text
+.IP \(bu 2
+markdown
+.IP \(bu 2
+json
+.RE
+.TP
+\fB\-\-min\-change\fR \fI<MIN_CHANGE>\fR [default: 0]
+Minimum absolute change for a per\-file metric delta to be reported. `0` (the default) reports any change of any size; raise it to suppress small deltas and surface only the larger metric movements (e.g. on a grammar bump)
+.TP
+\fB\-\-metric\fR \fI<METRIC>\fR
+Restrict the diff to one or more metrics (repeatable). Names are those printed by `bca list\-metrics` (e.g. `cyclomatic`, `sloc`). The dotted `bca check \-\-threshold` spelling is accepted as an alias (`loc.sloc` == `sloc`, `halstead.volume` == `halstead`). When omitted, every metric is reported
+.TP
+\fB\-o\fR, \fB\-\-output\fR \fI<OUTPUT>\fR
+Output file. Stdout if omitted
+.TP
+\fB\-\-strip\-prefix\fR \fI<STRIP_PREFIX>\fR [default: ]
+Path prefix to strip from displayed file paths in the TTY and Markdown per\-file tables. No\-op for `\-\-format json`, whose paths are a stable machine identity
+.TP
+\fB\-\-exit\-code\fR
+Exit with the metric\-gate code (`2`) when the diff is non\-empty in any section the active `\-\-metric` / `\-\-min\-change` filtering keeps; exit `0` when it is empty. Opt\-in (`git diff \-\-exit\-code`\-style) for grammar\-bump CI that wants a boolean "anything changed". Default (flag absent) always exits `0` on success. A tool error still exits `1` regardless
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help (see a summary with \*(Aq\-h\*(Aq)
+.TP
+[\fIOLD\fR]
+In file/dir mode: the old (base) metric output — the "before" side (a per\-file JSON file or a directory of per\-file JSON). In `\-\-since` mode: an optional *relative path scope* (a subdirectory or file), equivalent to `\-\-paths`, applied to both sides — so `bca diff \-\-since HEAD src` diffs only the `src` subtree. It is a scope, never an alternate root: both sides stay rooted at the repo top, so the keys always line up. Must be relative (an absolute path is rejected); omit it to diff the whole tree
+.TP
+[\fINEW\fR]
+In file/dir mode: the new (after) metric output (a per\-file JSON file or a directory of them). Not used in `\-\-since` mode, where the after side is always the working tree and the single positional is a path scope — a second positional with `\-\-since` is rejected at runtime
+.SH "INPUT SELECTION"
+.TP
+\fB\-p\fR, \fB\-\-paths\fR \fI<PATHS>\fR
+Input files or directories to analyze. Unioned with any positional `[PATHS]`. Defaults to the current directory (`.`) when omitted and no manifest `paths` is set; an explicitly\-given path that does not exist is an error (exit 1)
+.TP
+\fB\-I\fR, \fB\-\-include\fR \fI<INCLUDE>\fR
+Glob to include files. Repeat the flag to add multiple globs (`\-I \*(Aq*.rs\*(Aq \-I \*(Aq*.toml\*(Aq`); each occurrence takes exactly one value, so a positional argument that follows is never swallowed. A leading `./` is optional: `dir/**` and `./dir/**` are equivalent
+.TP
+\fB\-X\fR, \fB\-\-exclude\fR \fI<EXCLUDE>\fR
+Glob to exclude files. Repeat the flag to add multiple globs (`\-X \*(Aq*.tmp\*(Aq \-X \*(Aq*.bak\*(Aq`); each occurrence takes exactly one value, so a positional argument that follows is never swallowed. A leading `./` is optional: `dir/**` and `./dir/**` are equivalent. CLI values are *merged with* (unioned, not a replacement for) any `bca.toml` `exclude` list and any `\-\-exclude\-from` patterns, so a CLI `\-\-exclude` never silently un\-excludes a directory the project config deliberately skipped. Pass `\-\-no\-config` to ignore the manifest entirely
+.TP
+\fB\-l\fR, \fB\-\-language\fR \fI<LANGUAGE>\fR
+Force a language instead of inferring from extension. Accepts a canonical language name (`rust`, `python`, `cpp`, …) or a file extension (`rs`, `py`, …). An unrecognized value is a hard error
+.TP
+\fB\-\-no\-skip\-generated\fR
+Disable auto\-skip of files marked as generated (e.g. `@generated`, `DO NOT EDIT`, `GENERATED CODE` near the top). By default the CLI skips such files so generated bindings do not skew metrics
+.TP
+\fB\-\-paths\-from\fR \fI<PATHS_FROM>\fR
+Read newline\-separated input paths from a file. Use `\-` to read from stdin. Combined as a union with any `\-\-paths` values; globs still apply. Blank lines are skipped; `#` is treated as a path character (not a comment). To pass a file literally named `\-`, use `./\-`
+.TP
+\fB\-\-exclude\-from\fR \fI<EXCLUDE_FROM>\fR
+Read additional `\-\-exclude` glob patterns from a file (one per line, `.gitignore`\-style). Blank lines and lines whose first non\-whitespace character is `#` are skipped. Use `\-` to read from stdin; to pass a file literally named `\-`, use `./\-`. Patterns are unioned with any `\-\-exclude` values into a single deny\-set; order does not matter. Convention is a `.bcaignore` at the repo root, mirroring `.gitignore` / `.dockerignore`
+.TP
+\fB\-\-no\-ignore\fR
+Disable `.gitignore` / `.ignore` / global gitignore awareness when expanding input directories. Explicit file paths are always honored regardless of this flag
+.TP
+\fB\-\-no\-config\fR
+Skip auto\-discovery of a `bca.toml` manifest. By default `bca` climbs from the working directory to the repo root looking for `bca.toml` and merges its keys *under* any explicit CLI flags. Pass this for raw, fully\-explicit invocations that must not pick up repo\-level config (e.g. a reproducible CI one\-liner). When no manifest is discovered this flag is a no\-op
+.SH "WALKER TUNING"
+.TP
+\fB\-j\fR, \fB\-\-jobs\fR \fI<N|auto>\fR [default: auto]
+Number of jobs.
+
+Defaults to the effective CPU count as reported by the OS (cgroup\-quota\- and cpuset\-aware on Linux). Pass an explicit integer or `auto` to override. `\-\-jobs 1` forces serial mode for debugging. `\-\-num\-jobs` is kept as a hidden alias for one release cycle and is slated for removal in the next major.
+.TP
+\fB\-\-exclude\-tests\fR
+Exclude inline test code from metric computation. Currently applies to Rust only (skips `#[test]`, `#[cfg(test)]`, `#[tokio::test]`, `#[rstest]`, `#![cfg(test)]` items and their subtrees). Default is off — every node is counted, so numbers stay byte\-for\-byte stable. Languages without a test\-subtree skip rule ignore this flag
+.TP
+\fB\-\-cyclomatic\-count\-try\fR[=\fI<BOOL>\fR]
+Whether Rust\*(Aqs `?` operator (the `try_expression` node) contributes to cyclomatic complexity (standard and modified). Defaults to `true` — `?` counts +1, matching upstream rust\-code\-analysis and every published metric value. Pass `\-\-cyclomatic\-count\-try=false` to treat `?` as linear error propagation — useful when cyclomatic is used as a maintainability gate that should not penalize fallible\-but\-linear code. Rust\-only: no other language emits the node, so the flag is inert elsewhere. Mirrors the `cyclomatic_count_try` manifest key; the CLI value overrides the manifest in either direction
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+true
+.IP \(bu 2
+false
+.RE

man/bca-dump.1

@@ -0,0 +1,92 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-DUMP 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-dump \- 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)
+.SH SYNOPSIS
+\fBbca\-dump\fR [\fB\-\-line\-start\fR] [\fB\-\-line\-end\fR] [\fB\-p\fR|\fB\-\-paths\fR] [\fB\-I\fR|\fB\-\-include\fR] [\fB\-X\fR|\fB\-\-exclude\fR] [\fB\-l\fR|\fB\-\-language\fR] [\fB\-\-no\-skip\-generated\fR] [\fB\-\-paths\-from\fR] [\fB\-\-exclude\-from\fR] [\fB\-\-no\-ignore\fR] [\fB\-\-no\-config\fR] [\fB\-j\fR|\fB\-\-jobs\fR] [\fB\-\-exclude\-tests\fR] [\fB\-\-cyclomatic\-count\-try\fR] [\fB\-\-preproc\-data\fR] [\fB\-\-color\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIPATHS\fR] 
+.SH DESCRIPTION
+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)
+.SH OPTIONS
+.TP
+\fB\-\-line\-start\fR \fI<LINE_START>\fR
+First line of the range to analyze (1\-based, inclusive)
+.TP
+\fB\-\-line\-end\fR \fI<LINE_END>\fR
+Last line of the range to analyze (1\-based, inclusive)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help (see a summary with \*(Aq\-h\*(Aq)
+.SH "INPUT SELECTION"
+.TP
+\fB\-p\fR, \fB\-\-paths\fR \fI<PATHS>\fR
+Input files or directories to analyze. Unioned with any positional `[PATHS]`. Defaults to the current directory (`.`) when omitted and no manifest `paths` is set; an explicitly\-given path that does not exist is an error (exit 1)
+.TP
+\fB\-I\fR, \fB\-\-include\fR \fI<INCLUDE>\fR
+Glob to include files. Repeat the flag to add multiple globs (`\-I \*(Aq*.rs\*(Aq \-I \*(Aq*.toml\*(Aq`); each occurrence takes exactly one value, so a positional argument that follows is never swallowed. A leading `./` is optional: `dir/**` and `./dir/**` are equivalent
+.TP
+\fB\-X\fR, \fB\-\-exclude\fR \fI<EXCLUDE>\fR
+Glob to exclude files. Repeat the flag to add multiple globs (`\-X \*(Aq*.tmp\*(Aq \-X \*(Aq*.bak\*(Aq`); each occurrence takes exactly one value, so a positional argument that follows is never swallowed. A leading `./` is optional: `dir/**` and `./dir/**` are equivalent. CLI values are *merged with* (unioned, not a replacement for) any `bca.toml` `exclude` list and any `\-\-exclude\-from` patterns, so a CLI `\-\-exclude` never silently un\-excludes a directory the project config deliberately skipped. Pass `\-\-no\-config` to ignore the manifest entirely
+.TP
+\fB\-l\fR, \fB\-\-language\fR \fI<LANGUAGE>\fR
+Force a language instead of inferring from extension. Accepts a canonical language name (`rust`, `python`, `cpp`, …) or a file extension (`rs`, `py`, …). An unrecognized value is a hard error
+.TP
+\fB\-\-no\-skip\-generated\fR
+Disable auto\-skip of files marked as generated (e.g. `@generated`, `DO NOT EDIT`, `GENERATED CODE` near the top). By default the CLI skips such files so generated bindings do not skew metrics
+.TP
+\fB\-\-paths\-from\fR \fI<PATHS_FROM>\fR
+Read newline\-separated input paths from a file. Use `\-` to read from stdin. Combined as a union with any `\-\-paths` values; globs still apply. Blank lines are skipped; `#` is treated as a path character (not a comment). To pass a file literally named `\-`, use `./\-`
+.TP
+\fB\-\-exclude\-from\fR \fI<EXCLUDE_FROM>\fR
+Read additional `\-\-exclude` glob patterns from a file (one per line, `.gitignore`\-style). Blank lines and lines whose first non\-whitespace character is `#` are skipped. Use `\-` to read from stdin; to pass a file literally named `\-`, use `./\-`. Patterns are unioned with any `\-\-exclude` values into a single deny\-set; order does not matter. Convention is a `.bcaignore` at the repo root, mirroring `.gitignore` / `.dockerignore`
+.TP
+\fB\-\-no\-ignore\fR
+Disable `.gitignore` / `.ignore` / global gitignore awareness when expanding input directories. Explicit file paths are always honored regardless of this flag
+.TP
+\fB\-\-no\-config\fR
+Skip auto\-discovery of a `bca.toml` manifest. By default `bca` climbs from the working directory to the repo root looking for `bca.toml` and merges its keys *under* any explicit CLI flags. Pass this for raw, fully\-explicit invocations that must not pick up repo\-level config (e.g. a reproducible CI one\-liner). When no manifest is discovered this flag is a no\-op
+.TP
+[\fIPATHS\fR]
+Input files or directories to analyze, given positionally (`bca metrics src/ tests/`). Unioned with any `\-\-paths`/`\-p` values
+.SH "WALKER TUNING"
+.TP
+\fB\-j\fR, \fB\-\-jobs\fR \fI<N|auto>\fR [default: auto]
+Number of jobs.
+
+Defaults to the effective CPU count as reported by the OS (cgroup\-quota\- and cpuset\-aware on Linux). Pass an explicit integer or `auto` to override. `\-\-jobs 1` forces serial mode for debugging. `\-\-num\-jobs` is kept as a hidden alias for one release cycle and is slated for removal in the next major.
+.TP
+\fB\-\-exclude\-tests\fR
+Exclude inline test code from metric computation. Currently applies to Rust only (skips `#[test]`, `#[cfg(test)]`, `#[tokio::test]`, `#[rstest]`, `#![cfg(test)]` items and their subtrees). Default is off — every node is counted, so numbers stay byte\-for\-byte stable. Languages without a test\-subtree skip rule ignore this flag
+.TP
+\fB\-\-cyclomatic\-count\-try\fR[=\fI<BOOL>\fR]
+Whether Rust\*(Aqs `?` operator (the `try_expression` node) contributes to cyclomatic complexity (standard and modified). Defaults to `true` — `?` counts +1, matching upstream rust\-code\-analysis and every published metric value. Pass `\-\-cyclomatic\-count\-try=false` to treat `?` as linear error propagation — useful when cyclomatic is used as a maintainability gate that should not penalize fallible\-but\-linear code. Rust\-only: no other language emits the node, so the flag is inert elsewhere. Mirrors the `cyclomatic_count_try` manifest key; the CLI value overrides the manifest in either direction
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+true
+.IP \(bu 2
+false
+.RE
+.SH PREPROCESSOR
+.TP
+\fB\-\-preproc\-data\fR \fI<PREPROC_DATA>\fR
+Existing preprocessor\-data JSON to consume during C/C++ analysis. Use `bca preproc` to produce one
+.SH OUTPUT
+.TP
+\fB\-\-color\fR \fI<WHEN>\fR [default: auto]
+When to colorize the human\-readable `text` dumps (`metrics` / `ops` default tree, `dump`, `find`, `functions`): `auto` (default — color only when stdout is a terminal and `NO_COLOR` is unset), `always` (force escapes even when piped/redirected), or `never` (plain text). Structured formats (`json` / `yaml` / `toml` / `cbor` / `csv`) and file output are never colorized. Honors the `NO_COLOR` convention (<https://no\-color.org>) unless `\-\-color always` overrides it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+auto: Color when stdout is a terminal and `NO_COLOR` is unset
+.IP \(bu 2
+always: Always emit color, even when piped or redirected
+.IP \(bu 2
+never: Never emit color
+.RE