yoi/docs/report/test-validity-20260612/tools.md

# テスト妥当性レビュー: tools

- 評価: 混在

## 確認範囲

- Workspace: `/home/hare/Projects/yoi`
- Crate: `tools`
- 確認対象:
  - `crates/tools/Cargo.toml`
  - `crates/tools/src/{lib,scoped_fs,tracker,read,write,edit,glob,grep,bash,web,error}.rs`
  - `crates/tools/tests/{integration,edge_cases}.rs`
- この crate は以下の built-in tool の挙動を担っている:
  - filesystem tools: `Read`, `Write`, `Edit`, `Glob`, `Grep`
  - process tool: `Bash`
  - network tools: `WebSearch`, `WebFetch`
  - 共有 safety primitives: `ScopedFs`, `Tracker`, `ToolsError`

## 現在のテストがよくカバーしていること

主要な機能テストのカバレッジは広く、概ね適切な対象に向いている。

- `ScopedFs` tests は中核的な read/write scope enforcement をカバーしている:
  - absolute-path requirement
  - missing files と directory targets
  - out-of-scope と read-only paths
  - write 時の parent creation
  - symlink-to-file behavior
  - symlink escape diagnostics
  - clone 間での動的な `SharedScope` updates
- `Tracker` tests は重要な read-before-edit invariant をカバーしている:
  - record 後の clean verify
  - `NotRead`
  - externally modified hash mismatch
  - clone-shared state
  - symlink variants の canonical key collapse
  - recent-file LRU behavior
  - per-file mutation guard serialization と different-file parallelism
- `Read` / `Write` / `Edit` tests は期待される user-facing contract をカバーしている:
  - Read が history を記録する
  - Write は read なしで new files を作成できる
  - 既存ファイルへの Write/Edit は prior Read を要求する
  - external modification が検出される
  - unique replacement、`replace_all`、missing string、non-unique string
- `Glob` と `Grep` は user-visible options を多くカバーしている:
  - glob matching、hidden files、mtime ordering、invalid pattern
  - grep output modes、line numbers、context、multiline、glob/type filters、pagination、binary skip、invalid regex/type
  - scope-denied results が filter される
- `Bash` tests は重要な runtime behavior をカバーしている:
  - stdout/stderr merge
  - nonzero exit summary
  - stateless cwd
  - timeout
  - long output spill と tail rendering
  - drop 時の spill cleanup
  - background job non-hang regression
- `WebFetch` / `WebSearch` には有用な local-server tests がある:
  - disabled tools が network requests を行わない
  - private address blocking
  - redirect handling
  - Brave request shaping と secret ref use
  - oversized Brave response rejection
  - HTML fallback、local reader extraction、navigation inclusion/omission、output truncation

2つの integration test files は価値がある。`core_builtin_tools()` factory wiring と、cross-tool sharing of `ScopedFs` / `Tracker` を exercise しており、これはこの crate の中心的 invariant の1つである。

## 不足 / 疑問のあるテスト

default の crate test command は現在 green ではない。`cargo test -p tools` は doctests のみで失敗する。理由は、`tracker.rs` の documentation example がまだ `core_builtin_tools(fs, tracker, bash_outputs, None)` を呼んでいる一方で、実際の関数は現在3引数を取るためである。これは test-suite validity issue である。機能テストは通っているが、開発者が実行する default command は failure を報告する。

実質的に最も大きな gap は `web_builtin_tools()` 周辺である。core tool factory は integration-tested だが、web factory については registration names、metadata/schema presence、実際の `Tool` trait object 経由の disabled behavior、public tool surface との parity が確認されていない。

いくつかの領域は happy-path や string-fragment checks でテストされているが、boundary behavior はテストされていない:

- `Read`
  - invalid UTF-8 / binary-ish content rendering behavior の直接的な coverage がない
  - offset-beyond-EOF や `limit = 0` behavior test がない
  - trailing newline / CRLF line-count semantics が固定されていない
- `Write` / `Edit`
  - mutation serialization はテストされているが、`write_then_edit_same_file_same_batch_uses_call_order` は脆く見える。coordinator は path ごとに serialize するが、test name は call-index ordering を示唆している。この test は ordering invariant を証明するというより、polling order によって通っている可能性が高い。
  - `old_string == new_string`、empty `old_string`、non-UTF-8 edit target の明示的な test がない
  - write/edit の broken symlink handling は read/symlink escape より直接的な coverage が少ない
- `Glob`
  - result cap at 1000 がテストされていない
  - relative explicit `path`、non-directory `path`、out-of-scope explicit `path` が直接カバーされていない
  - symlink directory behavior は `Glob` でカバーされているが、direct path としてのみである
- `Grep`
  - description では `.gitignore` を honor するとされているが、直接的な `.gitignore` regression test は見当たらなかった
  - `-n: false`、個別の `-A` / `-B`、zero `head_limit`、context lines 付き content-mode pagination がカバーされていない
  - `Glob` test と同様の symlink-directory rejection がカバーされていない
- `Bash`
  - timeout behavior は確認されているが、process-tree cleanup や partial output を伴う timed-out command は確認されていない
  - tail read budget を超える very large output と partial UTF-8 tail boundaries がカバーされていない
  - unusual shell syntax を含む multiline commands などの command wrapping edge cases は、間接的にしか軽くカバーされていない
- `WebFetch`
  - URL parser constraints の coverage が不足している: non-http schemes、embedded credentials、missing host
  - content-type rejection、binary body rejection、invalid UTF-8、JSON/XML/text rendering、`Content-Length` なしの response-size truncation、redirect limit exceeded、redirect-to-private blocking が直接カバーされていない
  - private-address tests は有用だが必然的に local であり、DNS/rebinding-style behavior はここでは深くテストできない

一部の tests は exact または near-exact な diagnostic strings を assert している。remediation-focused user diagnostics に対しては正当化できるが、invariant-focused checks よりもいくつかの tests を脆くしてもいる。

## 追加提案

1. `tracker.rs` の stale doctest を修正するか、意図的に mark する。`cargo test -p tools` が今日失敗するため、これは最初の test-suite maintenance item として扱うべきである。

2. 小さな `web_builtin_tools_registers_full_set` integration test を追加する:
   - `WebSearch` と `WebFetch` を期待する
   - non-empty descriptions と object schemas を verify する
   - trait object 経由で disabled tools を execute し、no-network disabled error を assert する

3. focused boundary tests を追加する:
   - `Read` offset beyond EOF、`limit = 0`、CRLF/trailing newline behavior
   - `Edit` empty `old_string`、identical strings、non-UTF-8 target
   - `Glob` explicit relative/out-of-scope/non-directory path と 1000-result cap
   - `Grep` `.gitignore`、`-n: false`、個別の `-A`/`-B`、symlink directory rejection、zero/low `head_limit`
   - `Bash` partial output 付き timeout と `TAIL_READ_BUDGET` を超える huge output
   - `WebFetch` unsupported scheme、credentials in URL、unsupported content-type、binary body、invalid UTF-8、redirect limit、redirect-to-private

4. `write_then_edit_same_file_same_batch_uses_call_order` を作り直すか rename する。call-index ordering が intended invariant なら、implementation と test がそれを deterministic にすべきである。same-file serialization のみが intended なら、test name と assertion は ordering guarantees を示唆しないようにすべきである。

## 実行したコマンド

- `cargo test -p tools`
  - Result: failed.
  - Unit/integration portions passed:
    - lib tests: `99 passed`
    - `tests/edge_cases.rs`: `10 passed`
    - `tests/integration.rs`: `14 passed`
  - Doctest failed:
    - `crates/tools/src/tracker.rs - tracker (line 29)`
    - error `E0061`: `core_builtin_tools` は現在3引数を取るが、doctest は4引数を渡している。

- `cargo test -p tools --lib --tests`
  - Result: passed.
  - `99` lib tests、`10` edge-case tests、`14` integration tests が passed。

- `cargo test -p tools --doc`
  - Result: 同じ stale `tracker.rs` doctest error で failed。