ビルド不要のモードが 2 つと、コンパイラ補助のモードが 1 つあります。モードは実行の identity の一部なので、異なるモードで読んだ結果どうしが比較されることはありません。
トークンレベルで Type-1（完全一致）と Type-2（識別子のリネーム、リテラルの変更）を検出します。比較の前にコメントと空白を除くため、コメントだけの編集でひとつの finding が 2 つに割れることはありません。
Fast が既定なのは、実際の問いに答える最も安価な手段だからです。測れないのは、構文構造を必要とするものすべてです。欠落を伴うコピー、識別子の一致度、類似度の内訳、sibling と near miss が該当します。boilerplate・テストコード・整数幅ファミリの抑制ポリシーもこれらの分類を必要とするため、Fast では適用できず、その旨をレポートに明示します。
そのため、ある程度以上の規模のツリーでは Fast のレポートは有用な長さを超えます。「このファイルはあのファイルのコピーか」を問うときは Fast を、「まず何を見るべきか」を問うときは Structural を使ってください。
Structural は Type-3 検出、つまり文の追加・削除・変更を伴うコピーの検出を加え、判定根拠となった次元別の similarity を報告します。構文解析は行いますが、ツリーの中のコードを実行しないことは変わりません。
codehelion scan --mode structuralレポートを並べ替えて読めるようにするのが Structural です。canonical member に対する識別子の一致度を測り、2 つの出現箇所が「どのように」似ているかを述べる類似度の内訳を出し、グループ化で説明する 2 つの sibling channel と near miss の帯を動かします。抑制ポリシーもここで適用され、生成コード・テストのフィクスチャ・整数幅ごとに 1 本ずつ書かれた関数群が、読む価値のある finding を押しのけないようにします。
代償はセットアップではなく時間とメモリです。ビルドもツールチェーンも不要で、バイナリ以外に導入するものはありません。
1.0 前の面です。 文書化もテストもされていますが、約束に値するだけの実利用を経ていないため、リリース間で変わり得ます。
Semantic は、Structural が測るものすべてに加えて、コンパイラが解決した型と名前の情報、および登録済みの semantic ルールを加えます。
codehelion scan --mode semantic解析対象の言語ごとに helper が必要です。Rust なら codehelion-backend-rust、C / C++ なら codehelion-backend-clang を PATH に置くか --helper で指定します。codehelion doctor が、どれが存在するか、各 helper が話す protocol のバージョン、見つけたコンパイラ、供給できると言っている情報を報告します。ツリーにソースがあるのに、そのどの言語も読める helper が 1 つもインストールされていない場合、スキャンは失敗し、helper なしで解析する方法として --mode structural を示します。黙って Structural に切り替えることはありません。複数の言語を含むツリーでは、helper の無い言語は Structural として解析し、他の言語にはコンパイラを使います。
Rust の helper は、展開しなかったマクロ呼び出しを、attribute マクロと derive マクロも含めて理由とともに記録します。procedural macro は、展開するとそのマクロの crate を実行することになるため「実行が必要」（requires execution）として、組み込みの derive や、helper が扱わない形で展開を得られないマクロは「展開不可」（expansion unavailable）として記録されます。この記録によって、薄い答えが完全な答えに見えることを防ぎます。C / C++ では、compile_commands.json が存在するのに読めない場合、スキャンはビルド記述の段階で止まります。推測した条件の下に実行を記録しないためです。コンパイルデータベースが無いツリーはエラーではありません。
helper はバージョン付き protocol で通信する別プロセスなので、compiler API が CLI にリンクされることはありません。コンパイラがクラッシュしても終わるのは helper プロセスで、スキャンは該当ユニットを unavailable として記録し継続します。アーキテクチャを参照してください。
Semantic も、実行分類を明示的に許可しないかぎりプロジェクトのコードを実行しません。
codehelion scan --mode semantic --allow-execution=build-scriptこのフラグが無ければツリーの中のコードは実行されず、--untrusted では実行を一切許可しません。ローカル実行と信頼を参照してください。
Semantic 限定の opt-in な比較が 2 つあります。--compare-build-variants は異なる C/C++ build variant のあいだで完全一致の unit を比較し、--compare-languages は明示的に選んだ compilation partition をまたいで Rust と C++ の登録済みパイプラインを比較します。どちらも独立した comparison を出力し、通常の scan partition を混ぜることはありません。
| 問い | モード |
|---|---|
| このファイルはあのファイルのコピーか | Fast |
| ある程度の規模のツリーで、まず何を見るべきか | Structural |
| 終えたばかりのリファクタで呼び出し元を取り逃していないか | Structural |
| コンパイラが名前を解決したあとで、この 2 つは同じルーチンか | Semantic |
そのモードで測れない次元は推測せず「測定なし」として報告するため、レポートは常に、この問いのどれに答えられたかを示します。