feat(reference): Phase 2 - シンボル lookup インデックス（reference find-symbol）

[akiojin]

Summary

• Phase 1 (feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 / PR feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #186) の延長として、unity-cli reference find-symbol で UnityCsReference キャッシュ内の型定義（class / interface / struct / enum）を per-version index で定数時間 lookup できるようにする。
• gwt-discussion で採用方針 B（独自 ReferenceSymbolEntry） と symbol scope 型のみ が確定。member-level lookup は Phase 2.5 以降の拡張余地として残す。
• 同時に Phase 1 で得た振り返り (clippy バージョン差 / coverage gate / SPEC section markers) を tasks/lessons.md に追記して再発防止する。

Changes

• src/reference/index.rs (新規): ReferenceSymbolEntry / ReferenceSymbolIndex / extract_symbols_from_text（軽量 regex で型定義抽出）/ build_or_update_index（size + mtime ベース incremental）/ find_symbol / validate_kind / file_signature。LSP workspace には混入させない独立空間。
• src/reference/mod.rs: maybe_execute_reference_tool に "reference_find_symbol" 分岐と execute_find_symbol を追加。required name パラメータ、optional kind / namespace / version / projectRoot。dispatcher 経由 test を 6 件追加。
• src/cli.rs: ReferenceCommand::FindSymbol { name, kind, namespace, version } variant を追加。
• src/app/runner.rs::build_reference_call: FindSymbol 分岐と 2 件の test。
• src/tooling/tool_catalog.rs: reference_find_symbol を TOOL_NAMES / tool_executor::Local / is_read_only_tool / tool_params_schema (required: name) / parity count (124→125) に登録。
• .claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/SKILL.md: ## Preferred Flow に reference find-symbol 例 + 使い分けガイド (find-symbol → grep への fallback)。
• .claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/references/symbol-lookup-playbook.md: workflow step 1 に find-symbol 例とインクリメンタル index の説明。
• docs/tools.md: 「Reference Cache (6 → 7 tools)」に行追加。
• tasks/lessons.md: SPEC feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 振り返り 3 件 (clippy 1.95 のローカル差、coverage 90% を新 module 追加時に確保する手順、gwtd issue spec create の section markers 運用)。

Testing

• cargo fmt -- --check — clean
• cargo clippy --all-targets -- -D warnings — clean (clippy 1.95 想定の unnecessary-map-iter 修正含む)
• cargo test --bin unity-cli — 356 passed / 0 failed (Phase 2 で 9 + 6 + 2 + schema test を追加)
• cargo llvm-cov --all-targets --summary-only -- --test-threads=1 — TOTAL line coverage 90.69% (≥ 90% gate を満たす)
• unity-cli skills lint --severity error — 15 skills / 0 violations

Closing Issues

• Closes feat(reference): unity-csharp-reference Phase 2 - シンボル lookup インデックス #187

Related Issues / Links

• Phase 1 (feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185): MERGED in PR feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #186
• Phase 3 (feat(reference): unity-csharp-reference Phase 3 - バージョン差分と LSP 連携実験 #188): 後続別 SPEC

Checklist

• Tests added/updated (src/reference/index.rs 9 件、dispatcher 6 件、build_reference_call 2 件)
• Lint/format passed (cargo clippy, cargo fmt, unity-cli skills lint)
• Documentation updated (docs/tools.md、skill SKILL.md、references/symbol-lookup-playbook.md、tasks/lessons.md)
• Migration/backfill plan included — Not applicable: no schema or data change. reference find-symbol の初回実行で ~/.unity/cache/UnityCsReference/<version>/.unity-cli-index/symbols.json を新規生成するだけで、既存 Phase 1 cache (.unity-cli-meta.json 等) には触らない。
• CHANGELOG impact considered — minor bump per Conventional Commits (feat)

Context

• Phase 1 で land した reference grep / view / search は walkdir + regex の線形検索のため、UnityEngine.Animator のような頻出シンボルを LLM が連続して引くと毎回フルスキャンが走り高コスト。
• Phase 2 で per-version の .unity-cli-index/symbols.json を持ち、初回 lookup 時に build、以降は size + mtime ベースで incremental 更新する。

Risk / Impact

• Affected areas: 新規 src/reference/index.rs + CLI / catalog / local dispatcher への配線。新 skill / docs は既存 Phase 1 用のものに追記のみ。LSP の workspaceFolders には reference cache を引き続き混入させない（Phase 1 と同じ方針）。
• Disk footprint: 1 バージョンあたりの index は数 MB 程度の JSON。Phase 1 の shallow clone (400-600 MB / 版) に対する追加は小さい。
• Rollback plan: この commit を revert すれば Phase 1 の動作に戻る。.unity-cli-index/ ディレクトリを手動で削除しても良い (reference clean も次回以降のみ）。

Notes

• Phase 3 (バージョン差分 + LSP 連携) は別 SPEC feat(reference): unity-csharp-reference Phase 3 - バージョン差分と LSP 連携実験 #188 で後続。Phase 2 の find-symbol を前提とした symbol-level diff を予定。
• WIP commit f813632 は本 PR の中に含まれており、その上に dispatcher テスト / skill / docs / clippy fix が 6c8311f として重ねられている。

[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: 9c2df440-f28c-4766-8d69-f9debd7d08c7

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.}

[akiojin]

CI gate clear: merge_state CLEAN

gwt-discussion で確定した方針（採用方針 B + 型のみ scope）に基づく Phase 2 (#187) 実装を完成させ、CI を緑にしました。

修正サマリ

• Markdown & Commitlint (commitlint failure): 旧 WIP commit (f813632) が wip(reference): という type-enum 違反、加えて footer の長行が 100 char overflow していた。3 commits を 1 commit feat(reference): Phase 2 - reference find-symbol と Phase 1 振り返り に squash し、--force-with-lease で push し直して履歴を整理。

現在の CI 状態（全 SUCCESS）

• Rust Format & Lint
• Rust Tests / LSP Tests / LSP Performance
• Rust Coverage / LSP Coverage (>= 90%)
• Skill Contract Lint / Markdown & Commitlint / CodeRabbit
• mergeable: MERGEABLE, merge_state: CLEAN

Phase 2 で land する内容

• unity-cli reference find-symbol --name <name> [--kind ...] [--namespace ...] [--version ...] — per-version on-disk index (~/.unity/cache/UnityCsReference/<version>/.unity-cli-index/symbols.json) で型定義を定数時間 lookup
• 初回 lookup で full scan、以降は size + mtime で incremental 更新
• skill SKILL.md / docs/tools.md / symbol-lookup-playbook.md に find-symbol の使い分けを反映
• tasks/lessons.md に SPEC feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 振り返り 3 件 (clippy 1.95 のローカル差、coverage 90% 維持、SPEC section markers)

Out of Scope（Phase 3 #188 へ）

• バージョン差分表示 (reference diff <v1> <v2> --symbol <fqn>)
• LSP go-to-definition 連携実験
• member-level lookup (method / property / field)

レビューと merge をお願いします。Phase 3 は別 SPEC #188 で後続。