# 機能設計書 13-Glob ツール

## 概要

本ドキュメントは、OpenCodeのGlob ツール機能の設計仕様を定義する。Glob ツールは、ripgrepを使用してファイルパターンマッチング検索を行い、マッチしたファイルパスをエージェントに提供する機能を担う。

### 本機能の処理概要

Glob ツールは、指定されたグロブパターンにマッチするファイルを検索し、そのファイルパス一覧を返却する機能である。大規模なコードベースでも高速に検索でき、ファイルの更新日時順にソートされた結果を提供する。

**業務上の目的・背景**：AIエージェントがプロジェクト内の特定の種類のファイル（特定の拡張子、命名規則など）を迅速に見つけ出すために、ファイルパターンマッチング機能が必要である。本ツールにより、エージェントは設定ファイル、テストファイル、特定の言語のソースファイルなどを効率的に検索できる。

**機能の利用シーン**：
- 特定の拡張子を持つファイルの検索（例: "**/*.ts"）
- 特定のディレクトリ配下のファイル検索（例: "src/**/*.tsx"）
- 設定ファイルの検索（例: "**/*.config.js"）
- テストファイルの検索（例: "**/*.test.ts"）
- 特定の命名パターンを持つファイルの検索

**主要な処理内容**：
1. グロブ権限の確認
2. 検索パスの正規化
3. 外部ディレクトリチェック
4. ripgrepによるファイル検索
5. ファイル更新日時の取得
6. 結果のソートとフォーマット

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

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

## 関連画面

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

## 機能種別

検索 / ファイル一覧

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pattern | string | Yes | ファイル名のグロブパターン（例: "**/*.ts"） | 有効なグロブパターン |
| path | string | No | 検索対象のディレクトリ（デフォルト: カレントディレクトリ） | 有効なディレクトリパス、"undefined"や"null"は不可 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| title | string | ワークツリーからの相対パス |
| output | string | マッチしたファイルパス一覧（絶対パス、改行区切り） |
| metadata.count | number | マッチしたファイル数 |
| metadata.truncated | boolean | 結果が切り詰められたかどうか |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. グロブ権限確認
   └─ ctx.askでglob権限を要求

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

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

4. ripgrepファイル検索
   └─ Ripgrep.files()でファイル列挙

5. ファイル情報収集
   └─ 各ファイルの更新日時を取得

6. 結果ソート
   └─ 更新日時降順でソート

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

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[グロブ権限確認]
    B --> C[検索パス正規化]
    C --> D{外部ディレクトリ?}
    D -->|Yes| E[外部ディレクトリ権限確認]
    D -->|No| F[ripgrepファイル検索開始]
    E --> F
    F --> G{ファイルあり?}
    G -->|No| H[No files found返却]
    G -->|Yes| I[ファイル更新日時取得]
    I --> J{100件超過?}
    J -->|Yes| K[検索打ち切り]
    J -->|No| L{検索完了?}
    L -->|No| I
    L -->|Yes| M[更新日時降順ソート]
    K --> M
    M --> N[結果フォーマット]
    N --> OUTPUT[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 結果件数制限 | 検索結果は最大100件まで | 常時 |
| BR-02 | 結果ソート | 結果はファイルの更新時刻降順でソート | 常時 |
| BR-03 | 絶対パス出力 | 結果は絶対パスで出力 | 常時 |
| BR-04 | .gitディレクトリ除外 | .gitディレクトリ配下は検索対象外 | 常時 |

### 計算ロジック

**ripgrepファイル検索引数**：
- `--files`：ファイル一覧モード
- `--glob=!.git/*`：.gitディレクトリを除外
- `--hidden`：隠しファイルも検索対象
- `--glob=<pattern>`：指定されたグロブパターン

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | PermissionError | 権限不足 | 適切な権限を付与 |
| - | DirectoryNotFoundError | 指定ディレクトリが存在しない | 有効なパスを指定 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 検索結果制限: 100件/回
- ripgrepによる高速検索
- AbortSignalによるキャンセル対応
- ストリーミング処理による効率的なメモリ使用

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

- 外部ディレクトリへのアクセスは明示的な権限確認が必要
- pathパラメータに"undefined"や"null"を指定しないよう注意喚起

## 備考

- Grep ツールとは異なり、ファイル内容ではなくファイル名・パスを検索する
- 検索結果は更新日時が新しいファイルから順に表示される
- 並列で複数の検索を実行することが推奨される

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: Zodスキーマでpatternとpathの2パラメータが定義されている。pathの説明に"undefined"や"null"を使用しないよう注意書きがある。

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

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

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

**主要処理フロー**:
1. **22-30行目**: 権限確認
2. **32-34行目**: 検索パス正規化と外部ディレクトリチェック
3. **36-54行目**: ripgrepファイル検索とファイル情報収集
4. **55行目**: 更新日時降順ソート
5. **57-76行目**: 結果フォーマットと返却

#### Step 3: ripgrepファイル検索を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ripgrep.ts | `packages/opencode/src/file/ripgrep.ts` | files関数（210-276行目） |

**主要処理フロー**:
- **220行目**: --files, --glob=!.git/*オプションの設定
- **221-228行目**: オプション引数の構築
- **240-273行目**: ストリーミング読み取りとyield

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

```
GlobTool.execute
    │
    ├─ ctx.ask (glob権限要求)
    │
    ├─ assertExternalDirectory (外部ディレクトリチェック)
    │      └─ ctx.ask (external_directory権限要求)
    │
    ├─ Ripgrep.files (ファイル検索ジェネレーター)
    │      └─ Bun.spawn (ripgrep実行)
    │
    └─ Filesystem.stat (ファイル更新時刻取得)
```

### データフロー図

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

pattern ──────────────────▶ パターン検証
                                │
path (optional) ──────────────▶ パス正規化
                                │
                                ▼
                           ripgrepファイル検索
                                │
                                ▼
                           ファイル情報収集
                           (mtime取得)
                                │
                                ▼
                           100件制限チェック
                                │
                                ▼
                           更新日時降順ソート
                                │
                                ▼
                           結果返却 ─────────▶ title
                                              output
                                              metadata.count
                                              metadata.truncated
```

### 関連ファイル一覧

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