機能マトリクス
機能マトリクスは生成されたレポートです。サポート対象の各フラグと動作について、ネイティブツールとGrephラッパーが同等の出力をするかを記録します。「Grephはこれをサポートしているか」という疑問に答える基準となります。
決定論的なフィクスチャワークスペースに対して実際のコマンドプローブを実行し、マトリクスを再生成します。生の証拠はFEATURE_MATRIX.jsonに、整形済みの表はFEATURE_MATRIX.mdにあります。
ステータスの凡例
| ステータス | 意味 |
|---|---|
Pass |
プローブが実行され、期待された動作と一致した |
Fail |
プローブは実行されたが、期待された動作を満たさなかった |
Unavailable |
この環境にプロバイダーのコマンドがなかった |
セクション
マトリクスは6つのセクションで構成されています:
- rg互換性の範囲: すべてのプローブを、上流の
rgバイナリとbin/rgの両方に対して実行します。行をサポート済みとするには、両方がPass必要です。 - sg互換性の範囲: すべてのプローブを、上流の
sgバイナリとbin/sgの両方に対して実行します。行をサポート済みとするには、両方がPass必要です。 - sgラッパーのみの範囲:
bin/sgのみを対象とするプローブです（ast-grep自体にはない機能をラッパーが提供します）。 - ネイティブgrephの範囲:
bin/grephを直接実行するプローブです。比較対象となる上流ツールはありません。フィクスチャワークスペースで期待される動作を検証します。 - インデックス付きgrephの範囲:
bin/greph-indexを実行するプローブです（ビルド、更新、ウォーム状態でのテキスト検索）。 - インデックス付きASTライブラリの範囲: PHP API（
Greph::buildAstIndex()、Greph::searchAstIndexed()、Greph::buildAstCache()、Greph::searchAstCached()）を呼び出し、ビルド、検索、更新を確認するプローブです。
マトリクスの再生成
php bin/feature-matrix
rgとsgをPATHに配置したリポジトリのクローンから実行します。bin/feature-matrixはComposerパッケージに含まれません。フィクスチャワークスペースを構築し、上流のバイナリ（インストールされている場合）とGrephラッパーに対して各互換性プローブを実行し、構造化された結果を記録して、FEATURE_MATRIX.jsonとFEATURE_MATRIX.mdの両方を書き込みます。--stdoutを指定すると、どちらのファイルも書き込まずにMarkdownを表示します。
コミット済みのファイルは手作業で再生成され、CIでは再生成されません。CIで実行されるPHPUnitスイートには、上流ツールを利用不可としてマトリクスを生成し、レポートの構造を確認するテストが含まれています。そのため、単一のプローブが失敗してもCIは失敗しません。リリース前にマトリクスを再生成し、差分を確認してください。
マトリクスとドキュメントの役割
CLIリファレンスと互換性 / rgおよび互換性 / sgのページでは、意図する機能範囲を説明しています。機能マトリクスには、各行の正確なプローブ引数とともに、検証済みの機能範囲を記録しています。
ドキュメントに記載されているのにマトリクスにない場合、ドキュメントは古くなっています。マトリクスにあるのにドキュメントにない場合は、ドキュメントへの追記が必要です。両者を一致させてください。
行の例
rgの互換性（一部抜粋）
| 機能 | rg | bin/rg | 備考 |
|---|---|---|---|
| 固定文字列検索 | Pass | Pass | プローブ: -F needle single.txt |
| 大文字小文字を区別しない固定文字列検索 | Pass | Pass | プローブ: -F -i needle single.txt |
| 単語全体の検索 | Pass | Pass | プローブ: -F -w needle words.txt |
| Globフィルター | Pass | Pass | プローブ: --glob *.php function . |
| 隠しファイル | Pass | Pass | プローブ: --hidden -F secret . |
| 構造化JSON出力 | Pass | Pass | ripgrepのJSONイベント方式を使うプローブ: --json -F needle single.txt |
sgの互換性（一部抜粋）
| 機能 | sg | bin/sg | 備考 |
|---|---|---|---|
run --patternを使ったパターン検索 |
Pass | Pass | プローブ: run --pattern array($$$ITEMS) src/App.php |
run --rewriteによる書き換え |
Pass | Pass | プローブ: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php |
| 構造化JSONストリーム出力 | Pass | Pass | プローブ: run --json=stream --pattern dispatch($EVENT) src/App.php |
| 全件更新による書き換え | Pass | Pass | プローブ: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php |
全表はFEATURE_MATRIX.mdを参照してください。
プローブ駆動にする理由
手作業で管理する互換性表は、実装とのずれが生じます。ラッパーの狙いは「以前rgまたはsgを呼び出していた場所に置き換えても、そのまま動作する」ことです。この約束を守るには、上流ツールとラッパーを実際に並べて実行し、結果を比較するしかありません。プローブランナーは、マトリクスを再生成するたびにそれを行います。