# rg互換性

`vendor/bin/rg`はripgrep形式の互換ラッパーです。よく使われるripgrepフラグの大半を受け付け、ripgrepと同じようにファイルツリーをたどり、一致した内容を出力します。検証済みの機能範囲は、上流の`rg`バイナリに対するプローブ実行結果をもとに再現しており、[詳細 / 機能マトリクス](https://greph.inline0.dev/ja/docs/advanced/feature-matrix)に掲載しています。

このラッパーは薄いCLIトランスレーターです。実際の検索処理は、`vendor/bin/greph`が使うものと同じ`Greph\Text\TextSearcher`エンジンが行います。

## 使用する場面

次のような場合にラッパーを使ってください。

- すでに`rg`を呼び出しているツール、エージェント、スクリプトがある。
- ripgrep自体をインストールできない環境（共有ホスティング、セキュリティ強化済みコンテナ、制限付きPaaS）で使える、差し替え可能なツールが必要である。
- PHPのみのインフラでripgrepの使い勝手を得たい。

次の場合はネイティブの`vendor/bin/greph`を使ってください。

- 新しいコードを書く際に、ripgrepのCLI形式に合わせる必要がない。
- ラッパーでは公開されていないネイティブフラグ（たとえばASTモード）を使いたい。

## 使い方

```bash
rg [options] pattern [path...]
rg --files [options] [path...]
```

引数なしで呼び出すと、`.`を再帰的に検索します。

```bash
./vendor/bin/rg -F "function"
```

`--files`を指定すると、検索せずに候補ファイルを一覧表示します。

```bash
./vendor/bin/rg --files
./vendor/bin/rg --files --type php
./vendor/bin/rg --files --hidden
```

## JSON出力

`--json`は、ripgrepが生成するものと同じイベント形式のデータを出力します。

```bash
./vendor/bin/rg --json -F "function walk" src/Greph.php
```

```json
{"type":"begin","data":{"path":{"text":"src/Greph.php"}}}
{"type":"match","data":{"path":{"text":"src/Greph.php"},"lines":{"text":"    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList\n"},"line_number":41,"absolute_offset":1034,"submatches":[{"match":{"text":"function walk"},"start":18,"end":31}]}}
{"type":"end","data":{"path":{"text":"src/Greph.php"},"binary_offset":null,"stats":{"elapsed":{"secs":0,"nanos":0,"human":"0.000000s"},"searches":1,"searches_with_match":1,"bytes_searched":13383,"bytes_printed":282,"matched_lines":1,"matches":1}}}
{"type":"summary","data":{"elapsed_total":{"human":"0.000000s","nanos":0,"secs":0},"stats":{"bytes_printed":282,"bytes_searched":13383,"matched_lines":1,"matches":1,"searches":1,"searches_with_match":1,"elapsed":{"human":"0.000000s","nanos":0,"secs":0}}}}
```

`stats`オブジェクト内の処理時間は常にゼロとして報告されます。

これは、ripgrepの構造化出力を有効にしたときに後続ツールが期待するスキーマです。よりシンプルな形式にするには、代わりに`vendor/bin/greph --json`を使ってください。

## 検証済みの機能範囲

以下のフラグは、[機能マトリクス](https://greph.inline0.dev/ja/docs/advanced/feature-matrix)で`rg`自体を使って検証済みです。各プローブで、上流のバイナリとラッパーは同等の出力を生成します。フラグに短縮形と長形式がある場合、プローブでは一方を使い、ラッパーは両方を同じオプションとして解析します。

### 検索フラグ

- `-F`, `--fixed-strings`
- `-i`, `--ignore-case`
- `-w`, `--word-regexp`
- `-v`, `--invert-match`
- `-c`, `--count`
- `-l`, `--files-with-matches`
- `--files-without-match`
- `-I`, `--no-filename`
- `-H`, `--with-filename`
- `-n`, `--line-number`
- `-A N`, `--after-context N`
- `-B N`, `--before-context N`
- `-C N`, `--context N`
- `-m N`, `--max-count N`
- `-e P`, `--regexp P`

### ウォーカーフラグ

- `-L`, `--follow`
- `--glob GLOB`
- `--type NAME`
- `--type-not NAME`
- `--no-ignore`
- `--hidden`
- `--files`
- `--files --hidden`
- `--files --type NAME`

### 出力フラグ

- `--json`

### プローブ未実施の対応フラグ

ラッパーは次のフラグも受け付けますが、機能マトリクスではまだプローブされていません。

- `-j N`、`--threads N`（ワーカー数。[並列ワーカー](https://greph.inline0.dev/ja/docs/advanced/parallel)を参照）
- `-q`、`--quiet`
- `--no-follow`

## 制限事項

Grephの`rg`ラッパーは、ほとんどのツールやエージェントが使う検索機能とウォーカー機能をカバーします。現在、次のripgrep機能は公開されていません。

- 複数行正規表現（`-U`、`--multiline`）
- テキストモードでの置換（`-r`、`--replace`。代わりに`vendor/bin/greph`のAST書き換えを使ってください）
- カスタムタイプ定義（`--type-add`、`--type-clear`）
- エンコーディングフラグ（`-E`、`--encoding`）
- `--pre`フィルタースクリプト
- `--sort`、`--sortr`

未対応のフラグが見つかった場合は、上流の`rg`に対して実行したプローブと期待される出力を添えて課題を報告してください。新機能は対応するオラクルプローブとともに追加され、検証済みの機能範囲が広がっていきます。

## 動作の互換性

このラッパーが目指すのは動作の互換性であり、バイト単位の一致ではありません。出力は行単位で同等ですが、色コードや端末幅による切り詰めなど、見た目の細部は異なる場合があります。[機能マトリクス](https://greph.inline0.dev/ja/docs/advanced/feature-matrix)のプローブでは、バイト単位の差分ではなく意味的な同等性を確認します。

出力を解析するエージェントやツール向けに、検証済みのすべてのプローブで、パーサーが参照するフィールド（ファイルパス、行番号、内容、一致位置）は上流の`rg`とバイト単位で一致します。