feat(reference): Phase 3 - reference diff と resolve-symbol-at

[akiojin]

Summary

• Phase 3 として unity-cli reference diff (バージョン差分) と unity-cli reference resolve-symbol-at (project cursor → reference cache wrapper) を land し、UnityCsReference 参照キャッシュの活用範囲を広げる。
• gwt-discussion で確定したスコープ:
  • 差分粒度 C = symbol-only がデフォルト + --path で opt-in 全体走査
  • LSP 連携 C2 = unity-cli 独立 RPC（csharp-lsp の workspaceFolders に reference cache を混入させない）

Changes

• src/reference/diff.rs (新規): Hunk / SymbolDiff / PathDiff 型、compute_line_diff（MVP: all-or-nothing 単一 hunk）、compute_symbol_diff (Phase 2 find_symbol + run_view の組み合わせ)、compute_path_diff (added / removed / changed リスト + truncated フラグ)、ensure_cache_dir、split_fqn。
• src/reference/mod.rs: maybe_execute_reference_tool に reference_diff / reference_resolve_symbol_at 分岐、execute_diff / execute_resolve_symbol_at / extract_token_at_cursor (project file の cursor 位置から identifier を抽出) / collect_resolve_candidates (cached versions に対する find-symbol + view)。dispatcher 経由テスト 9 件追加。
• src/cli.rs: ReferenceCommand::Diff { from, to, symbol, path, max_symbols } と ReferenceCommand::ResolveSymbolAt { path, line, column, version }。
• src/app/runner.rs::build_reference_call: 2 分岐追加 + 4 件のテスト。
• src/tooling/tool_catalog.rs: reference_diff / reference_resolve_symbol_at を TOOL_NAMES / tool_executor::Local / is_read_only_tool / tool_params_schema (required: from/to、path/line/column) / parity count (125→127) に登録。
• .claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/SKILL.md: ## Preferred Flow に diff / resolve-symbol-at の使い分けを追記。
• .claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/references/version-diff-playbook.md (新規): Phase 3 の典型ユースケースと anti-patterns。
• docs/tools.md: Reference Cache (7 → 9 tools) と新 tool の行を追加。
• tests/fixtures/reference-cache-v2/{v1,v2}/: 差分テスト用 fixture (Animator changed / LegacyAnimator removed / Awaitable added)。

Testing

• cargo fmt -- --check — clean
• cargo clippy --all-targets -- -D warnings — clean
• cargo test --bin unity-cli — 379 passed / 0 failed
• cargo llvm-cov --all-targets --summary-only -- --test-threads=1 — TOTAL line coverage 90.97%
• unity-cli skills lint --severity error — 15 skills / 0 violations

Closing Issues

• Closes feat(reference): unity-csharp-reference Phase 3 - バージョン差分と LSP 連携実験 #188

Related Issues / Links

• Phase 1 (feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185): MERGED in PR feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #186
• Phase 2 (feat(reference): unity-csharp-reference Phase 2 - シンボル lookup インデックス #187): MERGED in PR feat(reference): Phase 2 - シンボル lookup インデックス（reference find-symbol） #189

Checklist

• Tests added/updated (diff: 9 件、dispatcher: 9 件、build_reference_call: 4 件、token extractor: 1 件)
• Lint/format passed (cargo clippy, cargo fmt, unity-cli skills lint)
• Documentation updated (docs/tools.md、skill SKILL.md、references/version-diff-playbook.md)
• Migration/backfill plan included — Not applicable: 既存の Phase 1/2 cache 構造には触らず、純粋に新コマンドの追加のみ。
• CHANGELOG impact considered — minor bump per Conventional Commits (feat)

Context

Phase 2 で find-symbol がインデックスベース lookup を提供したので、Phase 3 はその上に「2 バージョン比較」と「project cursor → reference cache」の薄い橋を載せる。symbol-only diff は find-symbol を 2 回呼んで run_view で抜粋する設計、resolve-symbol-at はカーソル位置の identifier を抽出して同じ find-symbol + run_view を流用する。compute_line_diff は MVP 用に全行 before/after を 1 hunk に詰めるだけで、unified diff 風の細粒度ハンク化は Phase 4 以降の余地として残す。

Risk / Impact

• Affected areas: src/reference/diff.rs 新規 + 既存 wiring。LSP の workspaceFolders には引き続き reference cache を混入させない（SPEC feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 の原則維持）。
• Disk footprint: compute_path_diff は両 cache のシンボルインデックスを走査するだけで、新規 fixture 以外のディスク追加はない。
• Performance: 既定 --max-symbols 50、run_view の window は 30 行 / symbol。1000 symbol を超える --path 走査は truncated: true で抑制される。
• Rollback plan: 本 commit を revert すれば Phase 2 の動作に戻る。reference cache 自体には影響しない。

Notes

• compute_line_diff は現状 all-or-nothing。LCS ベースの unified hunk への置換は別 Issue として後追い可能。
• resolve-symbol-at の token extractor は regex ベースで C# lexing を理解しない（コメント / 文字列内のカーソルでも identifier を拾う場合がある）。Phase 2.5 以降で改善余地あり。
• Phase 2 と同じく validate_kind の受理リストには method / property / field も含まれているが、現状の find_symbol は型のみを返す。member-level は Phase 2.5 で対応予定。

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: a9da7c9f-8a7b-4d10-9d1f-1fdfd2d7c1c0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch work/20260511-0223

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}