移行: フラグ CLI からサブコマンド CLI へ

CLI は、フラットなフラグスタイルのインターフェイス（1 つのプロセスに相互排他的な多数の --action フラグ）からサブコマンドスタイルのインターフェイス（bca <verb>）へ再構成されました。このページは、旧来のあらゆる呼び出しをその置き換え先に対応付けます。

変更の理由

フラグ CLI は --output-format に 2 つの無関係な意味を重ねていました。ファイルごとのシリアライズ（-O json/yaml/toml/cbor）と、ウォーク後の集約レポート（-O markdown）です。不正な組み合わせを取り締まるために 2 つの clap ArgGroup に加えてランタイムチェックが必要で、--top / --strip-prefix は 1 つの形式にしか適用されないのにグローバルフラグとして存在していました。将来の集約形式（たとえば HTML）はこの脆さをさらに悪化させたでしょう。

サブコマンド CLI はこの構造を修正します。bca metrics と bca ops はファイルごとの出力を、bca report <FORMAT> は集約レポートを出力し、各動詞は自分専用にスコープされたフラグ集合を持ちます。

移行対応表

旧	新
`--metrics -O markdown` (+ `--top`, `--strip-prefix`)	`report markdown`
`--metrics -O json/yaml/toml/cbor`	`metrics -O json/yaml/toml/cbor`
`--metrics -O checkstyle/sarif/code-climate/clang-warning/msvc-warning`	`check --threshold ... --report-format <fmt> [--output FILE]`
`--ops -O ...`	`ops -O ...`
`--dump`	`dump`
`--find <NODE>`	`find -t <NODE> [-t <NODE>...]`
`--count <LIST>`	`count -t <NODE> [-t <NODE>...]`
`--function`	`functions`
`--comments [--in-place]`	`strip-comments [--in-place]`
`--preproc <FILE> <FILE>...`（生成側）	`preproc -o <OUT>`
`--preproc <FILE>`（消費側）	`--preproc-data <FILE>`（サブコマンドごと、動詞の後に指定）
`--list-metrics [MODE]`	`list-metrics [MODE]`
`--pr`（pretty 表示）	`--pretty`（`metrics` と `ops` で使用）
`--ls`, `--le`（グローバル）	`dump`/`find` の `--line-start`、`--line-end`（`--ls`/`--le` は非推奨のエイリアスとして残存）
`-p`, `-I`, `-X`, `-j`, `-l`	サブコマンドにスコープされます。動詞の後に渡してください（`-w` は引き続き全体共通）

新旧対照の例

集約 Markdown レポート

# 旧
big-code-analysis-cli \
    --metrics \
    --paths "$PWD" \
    --output-format markdown \
    --jobs $(nproc) \
    --top 20 \
    --strip-prefix "$PWD/"

# 新
bca \
    report \
    --paths "$PWD" \
    --format markdown \
    --top 20 \
    --strip-prefix "$PWD/"

ファイル単位のメトリクス抽出

# 旧
big-code-analysis-cli --metrics --paths ./src --output-format json --output ./out/

# 新（ファイル単位ツリー: --output は 2.0 で --output-dir になりました）
bca metrics --paths ./src -O json --output-dir ./out/

ファイル単位の ops 抽出

# 旧: big-code-analysis-cli --ops --paths ./src -O json -o ./out/
# 新: bca ops --paths ./src -O json --output-dir ./out/

AST ダンプ

# 旧: big-code-analysis-cli --dump --paths ./file.rs
# 新: bca dump --paths ./file.rs

ノードの検索 / カウント

# 旧: big-code-analysis-cli --find call_expression --paths ./src
# 新: bca find --paths ./src -t call_expression

# 旧: big-code-analysis-cli --count if_statement,for_statement --paths ./src
# 新: bca count --paths ./src -t if_statement -t for_statement

注意: count は、カンマ区切りの 1 つの文字列ではなく、引数 1 つにつき 1 つのノード型（スペース区切り）を受け取るようになりました。

関数のスパン

# 旧: big-code-analysis-cli --function --paths ./src
# 新: bca functions --paths ./src

コメントの除去

# 旧: big-code-analysis-cli --comments --in-place --paths ./src
# 新: bca strip-comments --paths ./src --in-place

プリプロセッサデータ — 生成側

# 旧
big-code-analysis-cli --metrics --preproc a.h --preproc b.h \
    --paths ./src -o /tmp/p.json

# 新
bca preproc --paths ./src -o /tmp/p.json

プリプロセッサデータ — 消費側

# 旧
big-code-analysis-cli --metrics --preproc /tmp/p.json \
    --paths ./src -O json -o ./out/

# 新
bca metrics --paths ./src --preproc-data /tmp/p.json \
    -O json --output-dir ./out/

メトリクス一覧

# 旧: big-code-analysis-cli --list-metrics descriptions
# 新: bca list-metrics descriptions

実行時の移行ヒント

旧形式の呼び出しを実行すると、CLI は clap 自身のエラーの前に、認識した旧フラグとその新しい対応フラグを示すヒントを表示します。例:

$ bca --metrics -O markdown
note: the CLI was restructured into subcommands. See migration.md for the full mapping.
  --metrics  ->  bca metrics
  -O markdown  ->  bca report markdown|html [--top N] [--strip-prefix P]
  Run `bca --help` for the new command list.

error: unexpected argument '--metrics' found

big-code-analysis Documentation