# 機能設計書 66-タグ管理

## 概要

本ドキュメントは、space-vimにおけるタグ管理機能の設計について記載する。tagbarおよびvista.vimプラグインによるコードのアウトライン表示機能を提供する。

### 本機能の処理概要

タグ管理機能は、現在編集中のファイルのシンボル（関数、クラス、変数、メソッド等）を抽出し、サイドバーに階層的に表示する機能を提供する。コードの全体構造を把握しながら効率的にナビゲーションを行える。

**業務上の目的・背景**：大規模なソースコードを編集する際、ファイル内の関数やクラスの位置を把握することは重要である。スクロールして探すのは非効率であり、全体構造の把握も困難である。タグ管理機能により、ファイル内のすべてのシンボルが一覧表示され、クリックまたはEnterで即座にジャンプできるため、コードナビゲーションが大幅に効率化される。

**機能の利用シーン**：
- 大きなソースファイルで特定の関数に素早くジャンプしたい場合
- ファイル内のクラスやメソッドの構造を確認したい場合
- コードレビュー時にファイルの概要を把握したい場合
- リファクタリング対象のシンボルを探す場合

**主要な処理内容**：
1. `:TagbarToggle` コマンドでTagbarサイドバーをトグル
2. `<F6>` または `<Leader>tt` キーマッピングでトグル
3. ctagsベースでシンボルを抽出・表示
4. vista.vimはLSPベースでより正確なシンボル解析を提供

**関連システム・外部連携**：
- majutsushi/tagbar プラグイン（ctagsベース）
- liuchengxu/vista.vim プラグイン（LSPベース）
- ctagsまたはuniversal-ctags（外部ツール）
- LSPサーバー（coc.nvim等経由）
- space-vimの+programming/programmingレイヤーの一部として提供

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Tagbar（タグバー） | 主画面 | 現在のファイルのシンボルをサイドバー表示 |
| 7 | Vista（シンボルアウトライン） | 主画面 | LSPベースのシンボルビューア表示 |

## 機能種別

コードナビゲーション / 表示制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:tagbar_sort | Number | No | 0でソートなし、1でアルファベット順 | 0または1 |
| g:tagbar_autofocus | Number | No | 1でTagbar表示時に自動フォーカス | 0または1 |

### 入力データソース

- 編集中のバッファ（ソースコード）
- ctagsによるタグ情報
- LSPサーバーからのシンボル情報（vista.vim使用時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| シンボルリスト | 視覚表示 | 関数、クラス、変数等のリスト |
| シンボル階層 | 視覚表示 | ネストされたシンボルの階層構造 |

### 出力先

サイドバーウィンドウ（Tagbar/Vista）

## 処理フロー

### 処理シーケンス

```
1. TagbarToggleコマンド実行
   └─ :TagbarToggle または <F6> または <Leader>tt

2. ファイル解析
   └─ ctagsでファイルを解析しタグ情報を取得

3. シンボル抽出
   └─ 関数、クラス、変数等のシンボルを抽出

4. サイドバー表示
   └─ 階層構造でシンボルを表示

5. ナビゲーション
   └─ シンボル選択でカーソルジャンプ
```

### フローチャート

```mermaid
flowchart TD
    A[TagbarToggleコマンド] --> B{Tagbar表示中?}
    B -->|Yes| C[Tagbar閉じる]
    B -->|No| D[ファイル解析開始]
    D --> E[ctagsでタグ生成]
    E --> F[シンボル抽出]
    F --> G[階層構造構築]
    G --> H[サイドバー表示]
    H --> I{シンボル選択?}
    I -->|Yes| J[定義位置にジャンプ]
    I -->|No| K[待機]
    J --> K
    C --> L[終了]
    K --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 自動フォーカス | Tagbar表示時に自動的にフォーカスが移動 | g:tagbar_autofocus = 1 |
| BR-02 | ソート順 | 定義順（ソートなし）で表示 | g:tagbar_sort = 0 |
| BR-03 | Vista優先 | LSP環境ではvista.vimがより正確な解析を提供 | LSPサーバー利用時 |

### 計算ロジック

特になし（ctagsまたはLSPによる解析）

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

該当なし（表示機能のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ctags未インストール | ctagsがシステムにインストールされていない | エラーメッセージを表示 |
| - | 未対応ファイルタイプ | ctagsが対応していないファイルタイプ | シンボルが表示されない |

### リトライ仕様

該当なし

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

該当なし（表示機能のみ、ファイルへの変更なし）

## パフォーマンス要件

- 通常のソースファイルでは1秒以内に表示
- 大規模ファイルではctags解析に時間がかかる可能性あり

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

特になし

## 備考

- Tagbarは遅延ロードで設定されている（`:TagbarToggle`コマンド実行時にロード）
- vista.vimはTagbarの代替として、より現代的なアプローチを提供
- airline拡張のtagbar連携を無効化している（vim-airline issue 1313対応）

---

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

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

### 推奨読解順序

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

タグ管理関連プラグインの登録を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+programming/programming/packages.vim` | tagbarとvista.vimの登録を確認 |

**読解のコツ**: tagbarは遅延ロード、vista.vimは即時ロードで設定されている。

**主要処理フロー**:
1. **23-25行目**: airlineとtagbarの連携に関するコメント
2. **25行目**: `MP 'majutsushi/tagbar', { 'on': 'TagbarToggle' }` - tagbarの遅延ロード登録
3. **27行目**: `MP 'liuchengxu/vista.vim'` - vista.vimの即時ロード登録

#### Step 2: 設定内容を理解する

tagbarの詳細設定を確認する。

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

**主要処理フロー**:
- **67-73行目**: tagbar設定セクション
- **68行目**: `let g:tagbar_sort = 0` - 定義順で表示（ソートなし）
- **69行目**: `let g:tagbar_autofocus = 1` - Tagbar表示時に自動フォーカス
- **70行目**: `nnoremap <F6> :TagbarToggle<CR>` - F6キーでトグル
- **71行目**: `inoremap <F6> <ESC>:TagbarToggle<CR>` - 挿入モードからもF6でトグル
- **72行目**: `nnoremap <Leader>tt :TagbarToggle<CR>` - Leader+ttでトグル

#### Step 3: vista.vimの利用を確認する

vista.vimの設定を確認する（存在する場合）。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | lsp/config.vim | `layers/+tools/lsp/config.vim` | vista無視リストを確認 |

**主要処理フロー**:
- **9行目**: `let ignore_list = ['vista', ...]` - vistaをLSP無視リストに含む

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

```
space-vim起動
    │
    └─ spacevim#bootstrap()
           │
           └─ +programming/programming レイヤー読み込み
                  │
                  ├─ packages.vim
                  │      ├─ MP 'majutsushi/tagbar' (遅延ロード)
                  │      └─ MP 'liuchengxu/vista.vim' (即時ロード)
                  │
                  └─ config.vim
                         │
                         ├─ g:tagbar_sort = 0
                         ├─ g:tagbar_autofocus = 1
                         │
                         └─ キーマッピング
                                ├─ <F6> → :TagbarToggle
                                ├─ <F6> (挿入モード) → :TagbarToggle
                                └─ <Leader>tt → :TagbarToggle

:TagbarToggle 実行時
    │
    └─ vim-plug による遅延ロード
           │
           └─ tagbar プラグイン初期化
                  │
                  ├─ ctags 実行
                  │      └─ タグ情報取得
                  │
                  └─ サイドバー表示
                         └─ シンボル一覧

:Vista 実行時
    │
    └─ vista.vim プラグイン
           │
           ├─ LSP 経由でシンボル取得
           │      └─ coc.nvim / vim-lsp
           │
           └─ サイドバー表示
                  └─ シンボル一覧
```

### データフロー図

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

:TagbarToggle            tagbar                         サイドバー
     +            ───▶   プラグイン処理    ───▶         シンボル一覧
バッファ内容                   │
                              ▼
                         ctags 実行
                         タグ情報取得

:Vista                   vista.vim                      サイドバー
     +            ───▶   プラグイン処理    ───▶         シンボル一覧
バッファ内容                   │
                              ▼
                         LSPサーバー
                         シンボル情報取得
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+programming/programming/packages.vim` | 設定 | プラグイン登録 |
| config.vim | `layers/+programming/programming/config.vim` | 設定 | 設定とキーマッピング |
| LAYERS.md | `layers/LAYERS.md` | ドキュメント | レイヤー一覧 |
| tagbar | 外部プラグイン（majutsushi/tagbar） | プラグイン | ctagsベースタグバー |
| vista.vim | 外部プラグイン（liuchengxu/vista.vim） | プラグイン | LSPベースシンボルビューア |
