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

man/bca-exemptions.1

@@ -0,0 +1,109 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-EXEMPTIONS 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-exemptions \- 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
+.SH SYNOPSIS
+\fBbca\-exemptions\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\-O\fR|\fB\-\-format\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-\-strip\-prefix\fR] [\fB\-\-markers\-only\fR] [\fB\-\-excludes\-only\fR] [\fB\-\-baseline\-only\fR] [\fB\-\-baseline\fR] [\fB\-\-check\-exclude\fR] [\fB\-\-check\-exclude\-from\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIPATHS\fR] 
+.SH DESCRIPTION
+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
+.SH OPTIONS
+.TP
+\fB\-O\fR, \fB\-\-format\fR \fI<FORMAT>\fR [default: text]
+Output style: `text` (default), `markdown`, or `json`. JSON nests all three sections under a single `suppressions` envelope
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+text
+.IP \(bu 2
+markdown
+.IP \(bu 2
+json
+.RE
+.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
+.TP
+\fB\-\-markers\-only\fR
+Report only the in\-source markers section. The old `\-\-only\-markers` spelling stays a hidden alias for one cycle
+.TP
+\fB\-\-excludes\-only\fR
+Report only the `[check.exclude]` globs section. The old `\-\-only\-excludes` spelling stays a hidden alias for one cycle
+.TP
+\fB\-\-baseline\-only\fR
+Report only the `.bca\-baseline.toml` entries section. The old `\-\-only\-baseline` spelling stays a hidden alias for one cycle
+.TP
+\fB\-\-baseline\fR \fI<BASELINE>\fR
+Baseline file to audit. Defaults to `bca.toml`\*(Aqs `[check] baseline` key, then `.bca\-baseline.toml` in the working directory when present. A path given here must exist
+.TP
+\fB\-\-check\-exclude\fR \fI<GLOB>\fR
+Glob exempting files from the check gate, mirroring `bca check \-\-check\-exclude`. Repeatable. CLI values are *added to* (merged with), not a replacement for, the `bca.toml` `[check] exclude` list, so a CLI `\-\-check\-exclude` never silently re\-gates a path the project config deliberately exempted
+.TP
+\fB\-\-check\-exclude\-from\fR \fI<CHECK_EXCLUDE_FROM>\fR
+Read newline\-separated `\-\-check\-exclude` globs from a file (`.gitignore`\-style), mirroring `bca check \-\-check\-exclude\-from`. Use `\-` for stdin. Unioned with any `\-\-check\-exclude` values
+.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-find.1

@@ -0,0 +1,95 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-FIND 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-find \- Find nodes of one or more types
+.SH SYNOPSIS
+\fBbca\-find\fR <\fB\-t\fR|\fB\-\-type\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
+Find 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\-\-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

man/bca-functions.1

@@ -0,0 +1,86 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-FUNCTIONS 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-functions \- List functions/methods and their spans
+.SH SYNOPSIS
+\fBbca\-functions\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
+List functions/methods and their spans
+.SH OPTIONS
+.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

man/bca-init.1

@@ -0,0 +1,76 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-INIT 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-init \- 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`
+.SH SYNOPSIS
+\fBbca\-init\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\-\-dir\fR] [\fB\-\-force\fR] [\fB\-\-no\-baseline\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+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`
+.SH OPTIONS
+.TP
+\fB\-\-dir\fR \fI<DIR>\fR
+Directory to scaffold into. Defaults to the current working directory. The directory must already exist; `init` will not create the project root itself
+.TP
+\fB\-\-force\fR
+Overwrite any of the canonical files that already exist. Default: refuse to clobber, listing which files block
+.TP
+\fB\-\-no\-baseline\fR
+Skip the baseline\-generation pass. The written `.bca\-baseline.toml` is then an empty placeholder; the user can populate it later with `bca check \-\-write\-baseline .bca\-baseline.toml`. Default: walk the target directory and pin today\*(Aqs offenders
+.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
+.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-list-metrics.1

@@ -0,0 +1,26 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-LIST-METRICS 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-list\-metrics \- List the metrics this tool can compute and exit
+.SH SYNOPSIS
+\fBbca\-list\-metrics\fR [\fB\-h\fR|\fB\-\-help\fR] [\fIMODE\fR] 
+.SH DESCRIPTION
+List the metrics this tool can compute and exit
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help (see a summary with \*(Aq\-h\*(Aq)
+.TP
+[\fIMODE\fR] [default: names]
+What to print: `names` (one per line) or `descriptions` (name + one\-line summary)
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+names: Print metric names, one per line
+.IP \(bu 2
+descriptions: Print metric names alongside short descriptions
+.RE

man/bca-metrics.1

@@ -0,0 +1,125 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH BCA-METRICS 1  "big-code-analysis 2.0.0" "big-code-analysis Manual"
+.SH NAME
+bca\-metrics \- Compute per\-file metrics and emit them in a structured format
+.SH SYNOPSIS
+\fBbca\-metrics\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\-O\fR|\fB\-\-format\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-\-output\-dir\fR] [\fB\-\-pretty\fR] [\fB\-\-metrics\fR] [\fB\-\-vcs\fR] [\fB\-\-vcs\-per\-function\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIPATHS\fR] 
+.SH DESCRIPTION
+Compute per\-file metrics and emit them in a structured format
+.SH OPTIONS
+.TP
+\fB\-O\fR, \fB\-\-format\fR \fI<FORMAT>\fR
+Output format. When omitted, the default `text` format prints a human\-readable colored tree to stdout (`metrics` shows the metric tree, `ops` the operator/operand tree); pass `\-\-format text` to request that default explicitly (e.g. to override a `bca.toml` that set a structured format). `json` / `yaml` / `toml` / `cbor` / `csv` emit structured per\-file data. `\-\-output\-format` is accepted as a deprecated alias; it is hidden from help and slated for removal in 2.0
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+text: Human\-readable colored tree printed to stdout (`metrics` shows the metric tree, `ops` the operator/operand tree) — the default when `\-\-format` is omitted. Selecting it explicitly produces byte\-identical output to omitting the flag, so it is the way to request the default in a script or to override a `bca.toml` that set a structured format. It only ever streams to stdout, so unlike the structured serializers it has no file destination: pairing it with `\-\-output`/`\-\-output\-dir` is a hard error, not a silent no\-op — pass a structured `\-\-format` to write files
+.IP \(bu 2
+cbor
+.IP \(bu 2
+csv
+.IP \(bu 2
+json
+.IP \(bu 2
+toml
+.IP \(bu 2
+yaml
+.RE
+.TP
+\fB\-o\fR, \fB\-\-output\fR \fI<OUTPUT>\fR
+Output file. Writes one aggregate document (a top\-level array of the per\-file results; TOML wraps it under a `files` key) for the whole run. Stdout if omitted (CBOR requires this flag). Use `\-\-output\-dir` for the per\-file directory tree; passing both is an error
+.TP
+\fB\-\-output\-dir\fR \fI<OUTPUT_DIR>\fR
+Output directory. Writes one document per input file, named by the input path plus the format extension. Mutually exclusive with `\-\-output` (which writes a single aggregate file)
+.TP
+\fB\-\-pretty\fR
+Pretty\-print JSON / TOML output
+.TP
+\fB\-\-metrics\fR \fI<NAME>\fR
+Restrict computation to this comma\-separated and/or repeated set of metrics (`\-\-metrics cyclomatic,cognitive \-\-metrics loc`). Names are the canonical ids `bca list\-metrics` prints — the same vocabulary `bca check \-\-threshold` and `bca diff \-\-metric` use; dotted (`cyclomatic.modified`) and bare `loc` sub\-metric (`sloc`) spellings are accepted too. An unknown name errors (exit 1) with a "did you mean" hint. Derived metrics auto\-pull their dependencies (selecting `mi` also computes `loc` / `cyclomatic` / `halstead`). When omitted, every metric is computed
+.TP
+\fB\-\-vcs\fR
+Also compute change\-history (VCS) metrics and attach a `vcs` block — plus a `hotspot_score` (cyclomatic × recent churn) — to each file\*(Aqs metrics. Uses default windows (12mo / 90d, weighted formula); for window / formula tuning use `bca vcs`. Outside a git working tree this opt\-in is skipped with a warning (the AST metrics still emit, without the `vcs` block)
+.TP
+\fB\-\-vcs\-per\-function\fR
+Additionally attach a `vcs` block to every nested function / method / class space, via `git blame` of each file\*(Aqs surviving lines. Implies `\-\-vcs`. The per\-function numbers are a current\-blame snapshot — `churn` is surviving\-line count, not the file\-level added+deleted churn — so they rank functions within a file but are not directly comparable to the file block. Costs one blame per file; skipped (with a warning) outside a git working tree
+.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