# 機能設計書 69-cscope

## 概要

本ドキュメントは、space-vimにおけるcscope機能の設計について記載する。Vim内蔵のcscope連携機能とvim-qfプラグインによるコード検索機能を提供する。

### 本機能の処理概要

cscope機能は、C/C++コードベースに対してシンボル検索、関数呼び出し検索、定義検索などの高度なコード検索機能を提供する。ctagsよりも詳細な検索が可能であり、特に大規模なC/C++プロジェクトで効果を発揮する。

**業務上の目的・背景**：大規模なC/C++プロジェクトでは、関数の定義位置だけでなく、その関数がどこから呼び出されているか、どの関数を呼び出しているかなどの情報が重要である。cscopeはこれらの情報をデータベース化し、高速に検索できるようにする。これにより、コードの依存関係の把握やリファクタリング時の影響範囲調査が容易になる。

**機能の利用シーン**：
- 関数がどこから呼び出されているかを調べる場合
- 特定のシンボルを参照している箇所をすべて見つける場合
- 関数が呼び出している他の関数を調べる場合
- 特定のテキストパターンをコード全体から検索する場合

**主要な処理内容**：
1. cscopeデータベースの自動生成・更新
2. `<Leader>c*` キーマッピングによる各種検索
3. 検索結果のQuickfixウィンドウ表示
4. 非同期でのデータベース構築

**関連システム・外部連携**：
- Vimのcscope連携機能（`:h cscope`）
- romainl/vim-qf プラグイン（Quickfix拡張）
- cscope（外部ツール）
- space-vimの+tools/cscopeレイヤーとして提供

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | Quickfix/Location List | 遷移先機能 | cscope検索結果の表示 |

## 機能種別

コード検索 / シンボル解析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 検索タイプ | String | Yes | symbol, global, calls, text, egrep, file, includes, called | 有効な検索タイプ |
| 検索対象 | String | Yes | カーソル下の単語またはファイル名 | なし |

### 入力データソース

- カーソル下の単語（`<cword>`）
- カーソル下のファイル名（`<cfile>`）
- cscopeデータベース（cscope.out）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 検索結果 | List | マッチしたファイル名、行番号、コンテキスト |

### 出力先

- Quickfixウィンドウ
- エコーエリア（エラーメッセージ）

## 処理フロー

### 処理シーケンス

```
1. 検索コマンド実行
   └─ <Leader>cs, <Leader>cg, <Leader>cc 等

2. cscope接続確認
   └─ データベースが接続されているか確認

3. データベース未接続時
   └─ 自動的にcscopeデータベースを構築

4. cscope検索実行
   └─ :cs find {type} {pattern}

5. 結果をQuickfixに表示
   └─ cscopequickfix設定により自動表示
```

### フローチャート

```mermaid
flowchart TD
    A[検索コマンド実行] --> B{cscope接続あり?}
    B -->|Yes| C[cscope検索実行]
    B -->|No| D[データベース構築開始]
    D --> E{非同期構築?}
    E -->|Yes| F[バックグラウンド構築]
    E -->|No| G[同期構築]
    F --> H[構築完了待ち]
    G --> I[データベース追加]
    H --> I
    I --> C
    C --> J{結果あり?}
    J -->|Yes| K[Quickfixに表示]
    J -->|No| L[エラーメッセージ表示]
    K --> M[完了]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 検索優先順位 | cscopeデータベースをタグファイルより優先（csto=0） | 常時 |
| BR-02 | 自動検索 | ctagsとcscopeの両方を検索（cscopetag設定） | 常時 |
| BR-03 | Quickfix連携 | 検索結果をQuickfixに自動表示 | cscopequickfix設定 |
| BR-04 | テスト除外 | データベース構築時に/test/ディレクトリを除外 | データベース構築時 |

### 計算ロジック

特になし（cscope検索による処理）

## データベース操作仕様

該当なし（ファイルベースのデータベース）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E567 | cscope接続なし | cscopeデータベースが存在しない | 自動的にデータベースを構築 |
| E259 | マッチなし | 検索対象が見つからない | エラーメッセージを表示 |

### リトライ仕様

データベース構築後に自動リトライ

## トランザクション仕様

該当なし

## パフォーマンス要件

- データベース構築は非同期で実行可能
- 構築中はVim操作を継続可能

## セキュリティ考慮事項

特になし

## 備考

- cscopeはC/C++、Java等のファイルに対応
- vim-qfプラグインによりQuickfixの操作性が向上
- gtagsとの併用も可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: プラグイン登録を理解する

cscopeレイヤーのプラグイン登録を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+tools/cscope/packages.vim` | vim-qfプラグインの登録を確認 |

**読解のコツ**: cscopeレイヤーではvim-qfプラグインを使用し、Quickfixウィンドウの機能を拡張している。

**主要処理フロー**:
1. **1行目**: `MP 'romainl/vim-qf'` - Quickfix拡張プラグイン登録

#### Step 2: 設定とキーマッピングを理解する

cscope設定とキーマッピングを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.vim | `layers/+tools/cscope/config.vim` | cscope設定とキーマッピングを確認 |

**主要処理フロー**:
- **1-22行目**: cscopeのUSAGE説明コメント
- **25行目**: `set csto=0` - cscopeデータベースを優先検索
- **27行目**: `set cscopetag` - ctagsとcscopeの両方を検索
- **28行目**: `set cscopequickfix=s-,c-,d-,i-,t-,e-,a-` - 結果をQuickfixに表示
- **30-37行目**: キーマッピング
  - **30行目**: `<leader>cs` - symbol（シンボル参照検索）
  - **31行目**: `<leader>cg` - global（定義検索）
  - **32行目**: `<leader>cc` - calls（呼び出し元検索）
  - **33行目**: `<leader>ct` - text（テキスト検索）
  - **34行目**: `<leader>ce` - egrep（正規表現検索）
  - **35行目**: `<leader>cf` - file（ファイル検索）
  - **36行目**: `<leader>ci` - includes（インクルード検索）
  - **37行目**: `<leader>cd` - called（呼び出し先検索）

#### Step 3: cscope操作関数を理解する

cscope操作の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cscope.vim | `core/autoload/spacevim/vim/cscope.vim` | cscopeの検索・構築関数を確認 |

**主要処理フロー**:
- **1行目**: `let s:is_building = 0` - 構築中フラグ
- **4-29行目**: `s:add_db()` - データベース追加関数
  - **6行目**: `findfile('cscope.out', '.;')` - データベースファイル検索
  - **8行目**: `set nocsverb` - 詳細メッセージ抑制
  - **14行目**: `cs add` - データベース追加
- **31-36行目**: `s:build_sync()` - 同期構築
- **49-56行目**: `s:build_async()` - 非同期構築
  - **52行目**: `jobstart()` - NeoVimジョブAPI
  - **54行目**: `job_start()` - Vimジョブ API
- **58-77行目**: `s:build()` - 構築メイン処理
  - **61-62行目**: 対象拡張子設定
  - **65-67行目**: findコマンドでファイル一覧生成
- **79-81行目**: `spacevim#vim#cscope#Build()` - 公開関数
- **89-109行目**: `s:find()` - 検索実行
  - **90-92行目**: 検索タイプと:cs findオプションのマッピング
  - **97行目**: `:cs find` コマンド実行
- **111-123行目**: `spacevim#vim#cscope#Find()` - 公開検索関数
  - **112-114行目**: 構築中チェック
  - **118-121行目**: データベースなし時の自動構築

### プログラム呼び出し階層図

```
<Leader>cs 等のキーマッピング
    │
    └─ spacevim#vim#cscope#Find(type)
           │
           ├─ 構築中チェック
           │      └─ s:is_building フラグ確認
           │
           └─ s:find(type) 実行
                  │
                  ├─ :cs find {opt} {cword}
                  │
                  └─ エラー時: E567 (no cscope connections)
                         │
                         └─ s:build() 呼び出し
                                │
                                ├─ find コマンドでファイル一覧生成
                                │
                                ├─ cscope -b -q -i{tmp}
                                │
                                └─ s:add_db() でデータベース追加
```

### データフロー図

```
[入力]                    [処理]                         [出力]

<Leader>cs               spacevim#vim#cscope#Find        Quickfix
    +            ───▶    ('symbol')            ───▶      検索結果表示
カーソル下の単語               │
                              ▼
                         :cs find s {cword}
                              │
                              ▼
                         cscope.out
                         データベース検索

ソースファイル群          s:build()                      cscope.out
(*.c, *.cpp, *.h)  ───▶  cscope -b -q -i      ───▶      データベース
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+tools/cscope/packages.vim` | 設定 | プラグイン登録 |
| config.vim | `layers/+tools/cscope/config.vim` | 設定 | cscope設定とキーマッピング |
| cscope.vim | `core/autoload/spacevim/vim/cscope.vim` | ソース | cscope操作関数 |
| LAYERS.md | `layers/LAYERS.md` | ドキュメント | レイヤー一覧 |
| vim-qf | 外部プラグイン（romainl/vim-qf） | プラグイン | Quickfix拡張 |
