feat(reference): unity-csharp-reference Phase 4 - 内部実装の改善 (umbrella)

[akiojin]

目的

SPEC #185 (Phase 1) / #187 (Phase 2) / #188 (Phase 3) で構築した UnityCsReference 参照キャッシュの内部実装を底上げするための umbrella SPEC。Phase 1-3 で "Out of Scope" として明示した 5 件の改善 (Phase 4-A / B / C / D / E) を 1 つの SPEC で集約し、サブタスク単位で commit / PR を進める。子 SPEC は新設せず、本 SPEC を Refs する commit / PR で改善を land させる方針を採る。

スコープ

Phase 4 として扱う 5 サブタスク:

• A: Member-level シンボル抽出 (method / property / field を find-symbol の対象に追加)
• B: compute_line_diff の LCS / Myers 化 (Phase 3 の all-or-nothing MVP を細粒度 hunk に置換)
• C: extract_token_at_cursor の C# lexer 化 (line comment / string literal 内の cursor を正しく除外)
• D: reference fetch の zip fallback (git バイナリ不在環境向け、Phase 1.5 保留分)
• E: Vector embedding 検索 (semantic / natural-language なシンボル検索)

各サブタスクは autonomous で 1 PR ずつ land し、umbrella の Tasks セクションでチェックボックス進捗を管理する。

Out of Scope（umbrella でも扱わない）

• csharp-lsp の workspaceFolders に reference cache を混入させる方向 (SPEC feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 で却下済みの原則を維持)
• AST レベルの semantic diff (Roslyn を本格的にホストする方向)
• Phase 4 内の各 MVP に対する精度の本格 polish (regex で取り切れない多行シグネチャ / block comment / interpolated string 等は umbrella の継続改善余地として残置)

採用方針（gwt-discussion で確定）

• 子 SPEC は新設しない (2026-05-12 ルール、tasks/lessons.md)
• 各サブタスクの commit / PR は Refs #191 で umbrella に紐付ける
• サブタスク完了時に本 SPEC の Tasks をチェックボックス更新する
• サブタスクごとに gwt-discussion を別途行う場合は本 SPEC 本文を起点に進める
• 正式な gwt-spec は close せず OPEN 維持 (living documentation 運用、2026-05-12 ルール、tasks/lessons.md)

Related

• Phase 1: SPEC feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 (実装 MERGED, PR feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #186, SPEC 自体は OPEN 維持)
• Phase 2: SPEC feat(reference): unity-csharp-reference Phase 2 - シンボル lookup インデックス #187 (実装 MERGED, PR feat(reference): Phase 2 - シンボル lookup インデックス（reference find-symbol） #189, SPEC 自体は OPEN 維持)
• Phase 3: SPEC feat(reference): unity-csharp-reference Phase 3 - バージョン差分と LSP 連携実験 #188 (実装 MERGED, PR feat(reference): Phase 3 - reference diff と resolve-symbol-at #190, SPEC 自体は OPEN 維持)
• 重複 SPEC: feat(reference): Phase 4-B - compute_line_diff の LCS / Myers 化 #192 (Phase 4-B 用の子 SPEC として誤起票、umbrella ルール訂正により OPEN 維持)

Phase 4 サブタスク進捗

• T-A: Member-level シンボル抽出 MVP (method / property) — PR feat(reference): member-level シンボル抽出 MVP（Phase 4-A / Refs #191） #197 MERGED
• T-B: compute_line_diff の LCS / Myers 化 (similar クレート採用) — PR feat(reference): compute_line_diff を LCS / Myers 化（Phase 4-B / Refs #191） #193 MERGED
• T-C: extract_token_at_cursor の C# lexer 化 (line comment / string literal) — PR feat(reference): extract_token_at_cursor を C# lexer 化（Phase 4-C / Refs #191） #194 MERGED
• T-D: reference fetch の zip fallback (zip クレート + ureq) — PR feat(reference): reference fetch に zip fallback を追加（Phase 4-D / Refs #191） #196 MERGED
• T-E: Vector embedding 検索 MVP (fastembed-rs + 線形 scan) — PR feat(reference): Vector embedding 検索 MVP（Phase 4-E / Refs #191） #198 MERGED

受け入れ基準の充足状況

• 各サブタスク PR が cargo fmt --check / cargo clippy --all-targets -- -D warnings / cargo test --bin unity-cli を Pass
• 各サブタスク PR が cargo llvm-cov --all-targets >= 90% を Pass
• 各サブタスク PR が unity-cli skills lint --severity error を 0 violations で Pass
• docs/tools.md の Reference Cache tools 数を Phase 4-E 完了時点で 11 tools に更新
• unity-csharp-reference/SKILL.md の Preferred Flow が新 CLI を反映
• Phase 4-E 用 references/embed-search-playbook.md を追加

運用方針

• 本 umbrella SPEC は正式な gwt-spec として OPEN 維持 (living documentation 運用、close しない)
• Out of Scope に挙げた継続改善 (多言語 model / HNSW / block comment / interpolated string / 多行シグネチャ等) は、必要に応じて本 SPEC を Refs する PR で land する
• 重複起票として残る SPEC feat(reference): Phase 4-B - compute_line_diff の LCS / Myers 化 #192 も同様に OPEN のまま運用 (gwt-spec 一律 OPEN ルール)

[akiojin]

Phase 4 進捗報告

Phase 4 umbrella の 5 サブタスクのうち、これまでに以下を land しました。

Sub-task	Title	PR	状態
B	compute_line_diff の LCS / Myers 化	#193	MERGED
C	extract_token_at_cursor の C# lexer 化	#194	OPEN, CI 確認中

PR #194 では line comment と string literal (\" エスケープ込み) の判定を入れて resolve-symbol-at の偽陽性候補を抑制しました。block comment / char literal / interpolated string / preprocessor directive は意図的にスコープアウトし、本 umbrella の継続課題として残置します。

残タスク:

• A: Member-level シンボル抽出 (method / property / field)
• D: reference fetch の zip fallback
• E: Vector embedding 検索

これらは引き続き umbrella SPEC #191 の Tasks として進めます。新たな子 SPEC は作りません。

[akiojin]

Phase 4 進捗報告（B / C / D 完了）

Phase 4 umbrella の 5 サブタスクのうち、B / C / D を develop に統合しました。

Sub-task	Title	PR	状態
B	compute_line_diff の LCS / Myers 化	#193	MERGED
C	extract_token_at_cursor の C# lexer 化 (line comment / string literal)	#194	MERGED
D	reference fetch の zip fallback	#196	MERGED

残タスクと scope の評価

残り 2 つは autonomous で 1 PR に収めるには scope が大きいため、いったん handoff します。

• A: Member-level シンボル抽出 (method / property / field) — 必要作業
  • extract_symbols_from_text の regex 拡張（戻り値型 + 多行シグネチャ + ジェネリック型パラメータ）
  • .unity-cli-index/symbols.json の version を 1→2 に bump し、cache 互換性のリビルド戦略
  • regex MVP は偽陽性が出やすいので fixture 追加と精度評価が必要
  • PR scope の見込み: 中〜大規模
• E: Vector embedding 検索 — 必要作業
  • 依存追加 (ChromaDB / Qdrant / 純 Rust embedding lib のいずれか)
  • シンボル / view の embedding を per-Unity-version 索引化
  • 検索インターフェース reference embed-search --query "Animator related"
  • PR scope の見込み: 大規模、別 SPEC として切り出す価値あり

提案

• A: 次回 gwt-discussion で精度方針 (regex MVP / Roslyn 経由) を user と確定してから着手
• E: 別 SPEC として切り出すか、umbrella 内で詳細議論してから着手
• どちらも user の在席タイミングで議論したい

[akiojin]

Phase 4 進捗報告 (A / B / C / D 完了)

Phase 4 umbrella の 5 サブタスクのうち、A / B / C / D を develop に統合しました。

Sub-task	Title	PR	状態
A	Member-level シンボル抽出 MVP (method / property)	#197	MERGED
B	compute_line_diff の LCS / Myers 化	#193	MERGED
C	extract_token_at_cursor の C# lexer 化	#194	MERGED
D	reference fetch の zip fallback	#196	MERGED

残タスク (umbrella 内で継続管理)

• E: Vector embedding 検索 — 大規模。外部 dependency (ChromaDB / Qdrant / fastembed-rs 等) の選定、per-Unity-version の embedding index 構築、reference embed-search --query "..." の API 設計が必要。

Phase 4-A の既知の制限 (継続改善余地)

• 多行シグネチャ (戻り値型と method 名が改行で分かれるケース)
• constructor / destructor (戻り値型を持たないため現 regex を通らない)
• field / event 抽出
• ジェネリック制約句 where T : ... の取り扱い
• record / record struct のような新しい型構文

これらは MVP で意図的にスコープアウト。--kind method / --kind property フィルタで noise を抑える運用で当面しのげる。本格的な精度向上は Roslyn 経由解析を別 SPEC として検討する余地あり。

Next

E の着手は外部 dependency 選定が議論ポイントになるので、/gwt-discussion で SPEC #191 を起点に方針を user と確定してから build を開始するのが安全です。