# 機能設計書 12-Grep ツール

## 概要

本ドキュメントは、OpenCodeのGrep ツール機能の設計仕様を定義する。Grep ツールは、ripgrepを使用してファイル内容の正規表現検索を行い、マッチした結果をエージェントに提供する機能を担う。

### 本機能の処理概要

Grep ツールは、指定されたパターン（正規表現）でファイル内容を検索し、マッチしたファイルパスと行番号、マッチ内容を返却する機能である。大規模なコードベースでも高速に検索でき、ファイルパターンによるフィルタリングも可能。

**業務上の目的・背景**：AIエージェントがコードベース内の特定のパターンや実装を迅速に見つけ出すために、高速で信頼性の高い検索機能が必要である。本ツールにより、エージェントは関数定義、クラス宣言、特定の文字列パターンなどを効率的に検索し、コンテキストを把握できる。

**機能の利用シーン**：
- 関数やクラスの定義箇所の検索
- 特定の文字列パターンの使用箇所の調査
- エラーメッセージの発生源の特定
- 設定値やハードコードされた値の検索
- コード内のTODOやFIXMEコメントの検索

**主要な処理内容**：
1. パターンパラメータの検証
2. 検索権限の確認
3. 検索パスの正規化
4. ripgrepコマンドの実行
5. 検索結果の解析とソート
6. 結果のフォーマットと返却

**関連システム・外部連携**：
- ripgrep（rg）：高速な正規表現検索エンジン
- Filesystem：ファイル統計情報の取得

**権限による制御**：
- `grep`権限が必要
- 外部ディレクトリ（プロジェクト外）へのアクセスは`external_directory`権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | セッション | 補助機能 | Grepコンポーネントによる検索結果表示 |

## 機能種別

検索 / データ読み取り

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pattern | string | Yes | 検索する正規表現パターン | 空文字列不可 |
| path | string | No | 検索対象のディレクトリ（デフォルト: カレントディレクトリ） | 有効なディレクトリパス |
| include | string | No | 検索対象ファイルのグロブパターン（例: "*.js", "*.{ts,tsx}"） | 有効なグロブパターン |

### 入力データソース

- ローカルファイルシステム
- 実行コンテキスト（セッションID、メッセージID等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| title | string | 検索パターン |
| output | string | 検索結果（ファイルパス、行番号、マッチ内容） |
| metadata.matches | number | マッチ総数 |
| metadata.truncated | boolean | 結果が切り詰められたかどうか |

### 出力先

- エージェントへのレスポンス（ツール実行結果）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ patternが空の場合はエラー

2. 検索権限確認
   └─ ctx.askでgrep権限を要求

3. 検索パス正規化
   └─ 相対パスの場合、Instance.directoryを基準に絶対パスに変換

4. 外部ディレクトリチェック
   └─ プロジェクト外へのアクセス時は権限確認

5. ripgrepコマンド構築
   └─ -nH, --hidden, --no-messages等のオプション設定

6. ripgrep実行
   └─ Bun.spawnでプロセス起動

7. 出力解析
   └─ 結果をパース、ファイル更新時刻でソート

8. 結果フォーマット
   └─ 100件を超える場合は切り詰め
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{patternパラメータ検証}
    B -->|空| ERROR1[エラー: pattern is required]
    B -->|有効| C[検索権限確認]
    C --> D[検索パス正規化]
    D --> E{外部ディレクトリ?}
    E -->|Yes| F[外部ディレクトリ権限確認]
    E -->|No| G[ripgrepパス取得]
    F --> G
    G --> H[ripgrepコマンド構築]
    H --> I[ripgrep実行]
    I --> J{終了コード確認}
    J -->|1| K[No files found返却]
    J -->|2 & 出力なし| K
    J -->|0 or 2 & 出力あり| L[結果解析]
    J -->|その他| ERROR2[エラー: ripgrep failed]
    L --> M[ファイル更新時刻でソート]
    M --> N{100件超過?}
    N -->|Yes| O[100件に切り詰め]
    N -->|No| P[結果フォーマット]
    O --> P
    P --> OUTPUT[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 結果件数制限 | 検索結果は最大100件まで | 常時 |
| BR-02 | 行長制限 | マッチ行は最大2000文字で切り詰め | 全マッチ |
| BR-03 | 隠しファイル検索 | --hiddenオプションで隠しファイルも検索対象 | 常時 |
| BR-04 | 結果ソート | 結果はファイルの更新時刻降順でソート | 常時 |
| BR-05 | エラー抑制 | --no-messagesでエラーメッセージを抑制 | 常時 |

### 計算ロジック

**ripgrepコマンド引数構築**：
```
rg -nH --hidden --no-messages --field-match-separator=| --regexp <pattern> [--glob <include>] <searchPath>
```

## データベース操作仕様

### 操作別データベース影響一覧

本機能はファイルシステムのみを操作し、データベースへの直接的な操作は行わない。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ValidationError | patternが空 | 有効なパターンを指定 |
| - | RipgrepError | ripgrepの実行失敗 | パターンの正規表現構文を確認 |
| - | PermissionError | 権限不足 | 適切な権限を付与 |

### リトライ仕様

本機能はリトライ処理を行わない。エラー発生時は即座にエラーを返却する。

## トランザクション仕様

ファイルシステム操作のため、トランザクション管理は行わない。

## パフォーマンス要件

- 検索結果制限: 100件/回
- ripgrepによる高速検索（並列処理対応）
- AbortSignalによるキャンセル対応

## セキュリティ考慮事項

- 外部ディレクトリへのアクセスは明示的な権限確認が必要
- --no-messagesオプションでエラーメッセージを抑制し、情報漏洩を防止

## 備考

- ripgrepが存在しない場合、自動でダウンロード・インストールされる
- 壊れたシンボリックリンクなどでエラーが発生しても、検索結果があれば返却する
- Windows/Unix両方の改行コードに対応

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

ツールの入出力パラメータを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | grep.ts | `packages/opencode/src/tool/grep.ts` | パラメータスキーマ（13-19行目）を確認 |

**読解のコツ**: Zodスキーマでpattern, path, includeの3パラメータが定義されている。

#### Step 2: エントリーポイントを理解する

Grep ツールの本体実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | grep.ts | `packages/opencode/src/tool/grep.ts` | execute関数の全体フロー（20-150行目） |

**主要処理フロー**:
1. **20-23行目**: パターン検証
2. **25-34行目**: 権限確認
3. **36-38行目**: 検索パス正規化と外部ディレクトリチェック
4. **40-51行目**: ripgrepコマンド構築と実行
5. **53-70行目**: 出力と終了コード処理
6. **75-96行目**: 結果解析
7. **98-148行目**: 結果フォーマットと返却

#### Step 3: ripgrepユーティリティを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ripgrep.ts | `packages/opencode/src/file/ripgrep.ts` | ripgrepのダウンロード・パス取得ロジック |

**主要処理フロー**:
- **126-203行目**: ripgrepバイナリの取得（システムまたはダウンロード）
- **205-208行目**: filepath関数でバイナリパスを返却

### プログラム呼び出し階層図

```
GrepTool.execute
    │
    ├─ ctx.ask (grep権限要求)
    │
    ├─ assertExternalDirectory (外部ディレクトリチェック)
    │      └─ ctx.ask (external_directory権限要求)
    │
    ├─ Ripgrep.filepath (ripgrepバイナリパス取得)
    │      └─ ダウンロード処理（必要な場合）
    │
    ├─ Bun.spawn (ripgrep実行)
    │
    └─ Filesystem.stat (ファイル更新時刻取得)
```

### データフロー図

```
[入力]                        [処理]                              [出力]

pattern ──────────────────▶ パターン検証
                                │
path (optional) ──────────────▶ パス正規化
                                │
include (optional) ────────────▶ コマンド構築
                                │
                                ▼
                           ripgrep実行
                                │
                                ▼
                           結果パース
                                │
                                ▼
                           更新時刻ソート
                                │
                                ▼
                           100件制限
                                │
                                ▼
                           結果返却 ─────────▶ title
                                              output
                                              metadata.matches
                                              metadata.truncated
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| grep.ts | `packages/opencode/src/tool/grep.ts` | ソース | Grep ツール本体 |
| grep.txt | `packages/opencode/src/tool/grep.txt` | テンプレート | ツール説明文 |
| tool.ts | `packages/opencode/src/tool/tool.ts` | ソース | ツール基盤定義 |
| ripgrep.ts | `packages/opencode/src/file/ripgrep.ts` | ソース | ripgrepユーティリティ |
| external-directory.ts | `packages/opencode/src/tool/external-directory.ts` | ソース | 外部ディレクトリアクセス制御 |
| filesystem.ts | `packages/opencode/src/util/filesystem.ts` | ソース | ファイルシステムユーティリティ |
