# TODO: replace_in_file 性能改善候補

## 低リスク・優先度高

### 1. literal 置換時の occurrence 指定を最適化（対応済み）

`occurrence > 0` の場合は、指定位置の一致だけを使うように対応済み。

対応内容:

- `occurrence > 0` の場合は、対象 1 件だけを `hits` に入れる。
- regex 側と同様に、単発置換では全 hit list を作らない。
- `match_count` は従来どおり維持する。

備考:

- `tests/test_replace_in_file_strict.py` の occurrence 系テストで確認済み。
- 実装対象: `src/uagent/tools/replace_in_file_tool.py`

______________________________________________________________________

### 2. `match_hits` 診断生成の上限設定

現状は一致が大量にある場合、行番号・列番号・前後情報の生成が重くなる可能性がある。

改善案:

- 詳細な `match_hits` は先頭 N 件までに制限する。
- 総一致数は維持し、詳細省略件数を `diagnostics` または戻り値に含める。
- 例: `match_hits_truncated: true`, `match_hits_limit: 100`, `match_hits_omitted: 12345`

期待効果:

- preview や replace 結果生成の高速化。
- 大量一致時の JSON 出力サイズ削減。

注意点:

- 既存テストが全件 `match_hits` を前提にしていないか確認する。
- ユーザーが必要に応じて上限を指定できる引数を追加するか、固定上限にするか決める。

______________________________________________________________________

### 3. diff 生成の行数・出力量上限を追加

現在は入力サイズが大きい場合に diff を省略する `MAX_DIFF_INPUT_CHARS` を追加済み。
ただし、小さめの入力でも差分が複雑・大量の場合、`difflib.unified_diff` の生成や出力が重くなる可能性がある。

改善案:

- diff の最大出力文字数または最大行数を追加する。
- 上限超過時は途中で打ち切り、メッセージを付与する。
- 例: `[diff truncated: output too large]`

期待効果:

- 大量差分時のレスポンス肥大化を防止。
- ツール実行結果の扱いやすさ向上。

注意点:

- `difflib.unified_diff` 自体の生成コストは残るため、完全な対策ではない。
- 必要なら diff 生成前の変更規模推定も検討する。

______________________________________________________________________

## 中リスク・中優先度

### 4. newline 変換のさらなるスキップ

今回、`\r` がない場合の不要な CRLF/CR 正規化は削減済み。

追加改善案:

- ファイルの newline profile が LF で、replacement も LF の場合は、置換後の `_apply_newline_style()` をさらに短絡できる箇所がないか確認する。
- replacement 文字列が改行を含まない場合、replacement newline 正規化を省略する。

期待効果:

- 小〜中規模ファイルでの細かな CPU 削減。

注意点:

- CRLF ファイルの保持仕様を壊さないこと。
- `expand_newline_tokens` との組み合わせをテストすること。

______________________________________________________________________

### 5. `replace_all_in_files` の走査・読み取り最適化

多数ファイルを対象にする場合、逐次処理がボトルネックになり得る。

改善案:

- まず読み取り・マッチ判定だけ並列化する。
- 書き込みは安全性のため逐次、またはファイル単位で衝突しないことを確認して並列化する。
- 大きすぎるファイルや除外パターンを早期判定する。

期待効果:

- 多数の小ファイルに対する一括置換を高速化。

注意点:

- バックアップ作成、エラー時の部分成功、ログ順序の扱いを明確にする。
- Windows でのファイルロックに注意する。

______________________________________________________________________

### 6. バックアップ作成コストの見直し

大きなファイルでは、変更前バックアップのコピーが重い。

改善案:

- バックアップが必要な場合だけ作成されているか再確認する。
- オプションでバックアップ無効化を許可するか検討する。
- 可能な環境ではハードリンク等の利用を検討する。

期待効果:

- 大ファイル編集時の I/O 削減。

注意点:

- 安全性低下につながるため、既定ではバックアップ維持が望ましい。

______________________________________________________________________

## 高リスク・低優先度

### 7. 巨大ファイルのストリーミング処理

現状は基本的にファイル全体を読み込んで処理する。

改善案:

- literal replace の単純ケースのみ、チャンク単位のストリーミング置換を導入する。
- regex、replace_between、newline保持、diff、diagnostics が必要な場合は従来処理にフォールバックする。

期待効果:

- 数十MB〜数百MBのファイルでメモリ使用量を削減。

注意点:

- チャンク境界をまたぐ pattern の扱いが難しい。
- 既存仕様との差異が出やすい。
- 実装・テストコストが高い。

______________________________________________________________________

### 8. regex の pathological pattern 対策

ユーザー指定 regex によっては catastrophic backtracking で極端に遅くなる可能性がある。

改善案:

- 巨大ファイルに対する regex 実行時に警告または制限を追加する。
- タイムアウト付きの別プロセス実行を検討する。
- 可能なら標準 `re` 以外の regex エンジンも調査する。

期待効果:

- ハングに近い長時間実行の回避。

注意点:

- 標準 `re` には安全なタイムアウト機構がない。
- 別プロセス化は実装が重い。

______________________________________________________________________

### 9. hash 計算のサイズ上限・警告

`return_hashes=true` の場合、大ファイルでは sha256 計算もコストになる。

改善案:

- 一定サイズ以上では警告を出す。
- 必要なら hash 計算を省略できるオプションを追加する。

期待効果:

- 大ファイル編集時の追加 I/O を抑制。

注意点:

- `return_hashes=true` は明示指定のため、既定では影響が小さい。

______________________________________________________________________

## ベンチマーク追加案

性能改善を継続する場合、先に簡易ベンチマークを追加すると効果確認がしやすい。

候補:

- 10MB literal replace
- 10MB regex replace
- 10万一致の preview
- `occurrence=1` の単発置換
- diff 省略条件
- diff 大量出力の打ち切り条件
- `replace_all_in_files` で 1000 ファイル処理

測定項目:

- 実行時間
- 最大メモリ使用量
- 出力 JSON サイズ
- 変更前後の動作互換性

______________________________________________________________________

## 次に着手するなら

優先候補:

1. literal の occurrence 指定時に全 hit list を作らない
1. `match_hits` 詳細生成を上限付きにする
1. diff の出力量上限を追加する

理由:

- 既存仕様を壊しにくい。
- 実装量が比較的小さい。
- 大量一致・巨大ファイルで効果が出やすい。
