gwt-spec: unity-csharp-reference (UnityCsReference 参照キャッシュ・シンボル lookup・差分・embedding)

[akiojin]

目的

UnityCsReference (Unity Technologies 公式 C# ソース) をローカルキャッシュし、LLM / Skill から read-only で参照する仕組みのドメイン SPEC。unity-cli reference * サブコマンド群と Skill unity-csharp-reference を 1 つの SPEC で管理する。Phase 単位ではなくドメイン単位で扱い、改善は本 SPEC を Refs する commit / PR で進める。

スコープ

• ローカルキャッシュ (shallow clone + zip fallback): unity-cli reference fetch / reference status / reference clean
• 検索系: reference grep / reference view
• シンボル lookup インデックス (type + member-level method / property): reference find-symbol
• バージョン差分 (symbol-only + path opt-in, LCS / Myers ベース): reference diff
• LSP go-to-definition 連携 (unity-cli 独立 RPC, C# lexer 化済み token extractor): reference resolve-symbol-at
• Vector embedding 検索 (fastembed-rs + 線形 scan MVP): reference embed-build / reference embed-search
• Skill unity-csharp-reference の正本 (.claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/)
• 関連 docs: docs/tools.md の Reference Cache セクション、references/*-playbook.md、ATTRIBUTION.md の Unity Companion License 出典

Out of Scope

• AST レベルの semantic diff (Roslyn をホストする方向)
• csharp-lsp の workspaceFolders に reference cache を混入させる方向 (旧 feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 で却下済みの原則を維持)
• 各 MVP の本格 polish (詳細は Backlog で管理):
  • シンボル抽出: 多行シグネチャ / constructor / destructor / field / event / generic 制約 / record / record struct
  • 差分: character-level diff / unified diff text 形式
  • Token extractor: block comment /* */ / interpolated string / char literal / preprocessor directive
  • Zip fallback: ネットワーク実 download integration test / Unix 権限ビット保持
  • Vector embedding: 多言語 model / HNSW ANN / file-chunk embedding / score 正規化 / incremental rebuild

採用方針

• gwt-spec はドメイン単位 1 件。Phase / umbrella / 子 SPEC は新設しない (tasks/lessons.md 2026-05-12 ルール準拠)
• 改善は本 SPEC を Refs #<本 SPEC 番号> する commit / PR で land する
• 本 SPEC は living documentation として OPEN 維持
• 旧 Phase SPEC (feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 / feat(reference): unity-csharp-reference Phase 2 - シンボル lookup インデックス #187 / feat(reference): unity-csharp-reference Phase 3 - バージョン差分と LSP 連携実験 #188 / feat(reference): unity-csharp-reference Phase 4 - 内部実装の改善 (umbrella) #191 / feat(reference): Phase 4-B - compute_line_diff の LCS / Myers 化 #192) は本 SPEC への統合により close 済み (集約 close の例外条項を tasks/lessons.md に追記)

Related (履歴)

旧 Phase 軸の SPEC は本 SPEC に統合され close。詳細実装と検証エビデンスは各 PR とコメントを参照する。

• 旧 Phase 1 (ローカルキャッシュ): feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 → 本 SPEC、PR feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #186 MERGED
• 旧 Phase 2 (シンボル lookup, type): feat(reference): unity-csharp-reference Phase 2 - シンボル lookup インデックス #187 → 本 SPEC、PR feat(reference): Phase 2 - シンボル lookup インデックス（reference find-symbol） #189 MERGED
• 旧 Phase 3 (バージョン差分 + LSP 連携): feat(reference): unity-csharp-reference Phase 3 - バージョン差分と LSP 連携実験 #188 → 本 SPEC、PR feat(reference): Phase 3 - reference diff と resolve-symbol-at #190 MERGED
• 旧 Phase 4 umbrella (内部実装の改善 A-E): feat(reference): unity-csharp-reference Phase 4 - 内部実装の改善 (umbrella) #191 → 本 SPEC、PR feat(reference): compute_line_diff を LCS / Myers 化（Phase 4-B / Refs #191） #193 / feat(reference): extract_token_at_cursor を C# lexer 化（Phase 4-C / Refs #191） #194 / feat(reference): reference fetch に zip fallback を追加（Phase 4-D / Refs #191） #196 / feat(reference): member-level シンボル抽出 MVP（Phase 4-A / Refs #191） #197 / feat(reference): Vector embedding 検索 MVP（Phase 4-E / Refs #191） #198 MERGED
• 旧 Phase 4-B 誤起票: feat(reference): Phase 4-B - compute_line_diff の LCS / Myers 化 #192 → 本 SPEC (umbrella 集約のための重複)

既存実装 (旧 Phase SPEC からの引き継ぎ、本 SPEC 起票時点で完了済み)

• ローカルキャッシュ (旧 Phase 1 / PR feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #186)
• シンボル lookup インデックス (type, 旧 Phase 2 / PR feat(reference): Phase 2 - シンボル lookup インデックス（reference find-symbol） #189)
• バージョン差分 + LSP 連携 RPC (旧 Phase 3 / PR feat(reference): Phase 3 - reference diff と resolve-symbol-at #190)
• Member-level シンボル抽出 MVP (method / property, 旧 Phase 4-A / PR feat(reference): member-level シンボル抽出 MVP（Phase 4-A / Refs #191） #197)
• compute_line_diff の LCS / Myers 化 (similar クレート, 旧 Phase 4-B / PR feat(reference): compute_line_diff を LCS / Myers 化（Phase 4-B / Refs #191） #193)
• extract_token_at_cursor の C# lexer 化 (line comment / string literal, 旧 Phase 4-C / PR feat(reference): extract_token_at_cursor を C# lexer 化（Phase 4-C / Refs #191） #194)
• reference fetch の zip fallback (旧 Phase 4-D / PR feat(reference): reference fetch に zip fallback を追加（Phase 4-D / Refs #191） #196)
• Vector embedding 検索 MVP (fastembed-rs + 線形 scan, 旧 Phase 4-E / PR feat(reference): Vector embedding 検索 MVP（Phase 4-E / Refs #191） #198)

Backlog (旧 5 SPEC の Out of Scope を集約、優先度未確定)

• シンボル抽出: 多行シグネチャ / constructor / destructor / field / event / generic 制約 / record / record struct
• 差分: character-level diff / unified diff text 形式
• Token extractor: block comment /* */ / interpolated string / char literal / preprocessor directive
• Zip fallback: ネットワーク実 download integration test / Unix 権限ビット保持
• Vector embedding: 多言語 model / HNSW ANN / file-chunk embedding / score 正規化 / incremental rebuild
• AST レベル semantic 解析 (Roslyn ホスティングの是非含めて discussion 起点)

運用方針

• 本 SPEC は OPEN のまま living documentation として維持する (close しない)
• 改善 PR は本 SPEC を Refs #204 する
• Backlog 着手時は SPEC を分割せず、本 SPEC の該当チェックボックスを [x] で確定する
• 重要な設計変更は本 SPEC を起点に gwt-discussion を行い、Spec / Plan / Tasks セクションを更新する
• 旧 Phase SPEC (feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 / feat(reference): unity-csharp-reference Phase 2 - シンボル lookup インデックス #187 / feat(reference): unity-csharp-reference Phase 3 - バージョン差分と LSP 連携実験 #188 / feat(reference): unity-csharp-reference Phase 4 - 内部実装の改善 (umbrella) #191 / feat(reference): Phase 4-B - compute_line_diff の LCS / Myers 化 #192) は本 SPEC への統合に伴い close 済み。再 open しない

[akiojin]

現時点の実装

旧 Phase 1-4 で構築済みの構成を以下のモジュールに保持する。本 SPEC 起票時点ではコード変更は伴わず、SPEC レイヤーの集約のみ。

• src/reference/version.rs — ProjectVersion.txt 検出 + VERSION_BRANCH_MAP
• src/reference/cache.rs — reference_root / version_dir / read_meta / write_meta / list_versions / gc
• src/reference/fetcher.rs — shallow clone + zip fallback (zip クレート)
• src/reference/search.rs — walkdir + regex の grep / view
• src/reference/index.rs — type + member-level シンボル抽出 (ReferenceSymbolEntry, .unity-cli-index/symbols.json)
• src/reference/diff.rs — similar クレートの TextDiff::from_slices ベース LCS / Myers diff
• src/reference/embed.rs — fastembed-rs (BGE-Small-EN ONNX) + 線形 scan、MockEmbedder テスト
• src/reference/mod.rs — maybe_execute_reference_tool dispatcher、C# lexer 化済み extract_token_at_cursor
• src/tooling/tool_catalog.rs — reference_* ツール定義 (現在 11 tools)

Backlog 着手時の方針

Backlog 項目に着手する際は本セクションへサブタスクごとの採用方針を追記し、gwt-discussion で詳細を確定する (旧 SPEC #191 の plan コメントを踏襲)。子 SPEC や umbrella を新設せず、本 SPEC を Refs する commit / PR を直接 land する。

共通の検証ゲート

Backlog 着手で land する PR は以下を全 Pass:

• cargo fmt --all -- --check
• cargo clippy --all-targets -- -D warnings
• cargo test --bin unity-cli
• cargo llvm-cov --all-targets --summary-only -- --test-threads=1 (TOTAL line coverage ≥ 90%)
• unity-cli skills lint --severity error (0 violations)

[akiojin]

既存テストの所在 (旧 Phase で導入済み)

• src/reference/version.rs — detect_from_project / VERSION_BRANCH_MAP の unit tests (旧 Phase 1)
• src/reference/cache.rs — read_meta / write_meta / list_versions / gc の unit tests (旧 Phase 1)
• src/reference/fetcher.rs — build_clone_args / archive_url_uses_unity_cs_reference_org / extract_zip_to_* (旧 Phase 1 + 4-D)
• src/reference/search.rs — walkdir + regex 5 tests (旧 Phase 1)
• src/reference/index.rs — build_or_update_index_skips_already_indexed_files_until_change / extract_symbols_from_text_finds_methods / extract_symbols_from_text_finds_property / extract_symbols_from_text_does_not_double_capture_class_name (旧 Phase 2 + 4-A)
• src/reference/diff.rs — compute_line_diff_replacement_isolates_changed_lines / _for_inserts_only_returns_addition_hunk / _for_deletes_only_returns_removal_hunk / _for_separate_changes_produces_multiple_hunks (旧 Phase 4-B)
• src/reference/mod.rs — extract_token_at_cursor_skips_line_comment / _skips_string_literal / _returns_ident_after_closed_string / _handles_escaped_quote_in_string (旧 Phase 4-C)
• src/reference/embed.rs — symbol_to_text / save_embedding_index + load_embedding_index / search / cosine_similarity + MockEmbedder (旧 Phase 4-E)
• dispatcher tests: execute_embed_search_requires_query / execute_embed_search_errors_when_index_missing / execute_embed_build_errors_when_cache_missing

Backlog 着手時の TDD ガイドライン

Backlog 項目に着手する際は本セクションへサブタスクごとの RED → GREEN → REFACTOR ガイドラインを追記する (旧 SPEC #191 の tdd コメントを踏襲)。

共通方針

• ONNX 実モデル / 実 git clone / 実ネットワーク download に依存する path は test を #[ignore] または mock 経由で隔離し、CI 安定性を保つ
• 各 PR で cargo llvm-cov >= 90% を維持
• 新規 fixture は tests/fixtures/reference-cache*/ 配下にまとめ、.unity-cli-index/ 生成物は .gitignore 対象