# 機能設計書 12-LocalLeaderキーマッピング

## 概要

本ドキュメントは、space-vimにおけるLocalLeaderキーマッピング機能の設計仕様を記述する。カンマキー（,）をローカルリーダーとして使用し、言語固有・バッファローカルなキーバインディング体系を提供する機能である。

### 本機能の処理概要

LocalLeaderキーマッピング機能は、ファイルタイプや言語固有のコマンドを統一的なキー体系で提供する。グローバルなLeaderキー（SPC）とは異なり、特定のファイルタイプでのみ有効なキーバインディングを定義できる。

**業務上の目的・背景**：プログラミング言語ごとに必要な操作は異なる（例：Pythonではインタプリタ実行、Rustではコンパイル、JavaScriptではリンター実行）。LocalLeaderは、これらの言語固有操作を統一的なキープレフィックスで提供することで、複数言語を扱う開発者の作業効率を向上させる。

**機能の利用シーン**：
- 特定のプログラミング言語でのみ使用するコマンドを実行する場合
- ファイルタイプに応じた設定ファイルを素早く開きたい場合
- LSP連携機能を言語固有のコンテキストで操作したい場合
- fzf関連の開発者向けユーティリティ機能を使用する場合

**主要な処理内容**：
1. カンマキー（,）をローカルリーダーキーとして設定
2. `g:spacevim#map#localleader#desc`辞書でキーマッピング定義を管理
3. vim-which-keyにローカルリーダー用辞書を登録してポップアップ表示を実現
4. ftpluginを通じて言語固有のキーバインディングを追加可能
5. ノーマルモードおよびビジュアルモード用の別々のマッピングを提供

**関連システム・外部連携**：
- vim-which-key：キーバインディングのポップアップ表示
- fzf：ファジーファインダー連携（コマンド検索、関数検索）
- ftplugin：ファイルタイプ別設定
- LSP（coc.nvim/vim-lsp）：言語固有のフォーマット操作

**権限による制御**：本機能に権限制御は存在しない。すべてのユーザーが同一のキーバインディングを使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Which-Key（キーバインド表示画面） | 補助機能 | カンマキーをローカルリーダーとした言語固有キーバインディング |

## 機能種別

キーバインディング管理 / ファイルタイプ固有操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:spacevim_localleader | String | No | ローカルリーダーキーのカスタマイズ | デフォルト: `,` |
| g:spacevim#map#localleader#desc | Dictionary | Yes | キーマッピング定義辞書 | - |

### 入力データソース

- `~/.spacevim`ファイル：ユーザーカスタマイズ設定
- `core/autoload/spacevim/map/localleader.vim`：デフォルトマッピング定義
- `core/ftplugin/*.vim`：ファイルタイプ別追加設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| キーバインディング | Vim mapping | カンマキーを起点とした各種コマンドマッピング |
| which-key辞書 | Dictionary | ポップアップ表示用のキー説明辞書 |

### 出力先

- Vimのキーマッピング空間（ノーマルモード、ビジュアルモード）
- vim-which-keyプラグインのレジストリ

## 処理フロー

### 処理シーケンス

```
1. space-vim初期化（spacevim#begin()）
   └─ ~/.spacevimファイルを読み込み、g:spacevim_localleaderを取得
2. ローカルリーダーキー設定
   └─ g:maplocalleader = g:spacevim_localleader（デフォルト: ","）
3. キーマッピング辞書初期化
   └─ core/autoload/spacevim/map/localleader.vimで s:localleader_map を定義
4. 基本コマンド定義
   └─ v:ファイル開く, p:runtimepath, f:fzfサブメニュー
5. vim-which-key連携
   └─ spacevim#autocmd#which_key#Init()でwhich_key#register(',', ...)を呼び出し
6. keybindings.vimでの実キーマッピング設定
   └─ nnoremap <silent> <localleader> :<c-u>WhichKey ','<CR>
7. ファイルタイプ検出時
   └─ ftpluginで言語固有のキーバインディングを追加
```

### フローチャート

```mermaid
flowchart TD
    A[space-vim起動] --> B[spacevim#begin]
    B --> C{~/.spacevim存在?}
    C -->|Yes| D[g:spacevim_localleader読み込み]
    C -->|No| E[デフォルト設定 , 使用]
    D --> F[g:maplocalleader設定]
    E --> F
    F --> G[localleader.vim読み込み]
    G --> H[s:localleader_map辞書定義]
    H --> I[which-keyレイヤー読み込み]
    I --> J[which_key#register , 呼び出し]
    J --> K[keybindings.vim読み込み]
    K --> L[カンマキーマッピング完了]
    L --> M{ファイル開く}
    M -->|ft検出| N[ftplugin読み込み]
    N --> O[言語固有マッピング追加]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトローカルリーダー | カンマキー（,）をローカルリーダーとする | g:spacevim_localleaderが未定義の場合 |
| BR-002 | 言語固有拡張 | ftpluginで言語固有のキーバインディングを追加可能 | 対応言語のファイルを開いた場合 |
| BR-003 | which-key連携 | which-keyレイヤー有効時、ポップアップ表示を行う | which-keyレイヤーが読み込まれている場合 |
| BR-004 | Leaderとの分離 | LocalLeaderはLeader（SPC）とは独立したキー体系 | 常時 |

### 計算ロジック

該当なし（キーマッピングは静的定義）

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 警告 | ~/.spacevimファイルが存在しない | デフォルト値（,）を使用 |
| - | 警告 | which-keyレイヤーが未読込 | ポップアップなしでキーマッピングのみ動作 |

### リトライ仕様

該当なし

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

該当なし（データベース操作なし）

## パフォーマンス要件

- キーマッピング定義の読み込みは起動時に1回のみ実行
- ftpluginはファイルタイプ検出時に読み込み（遅延読み込み）

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

該当なし（ローカルVim操作のみ）

## 備考

- LocalLeaderは言語固有の操作に使用することを想定
- グローバルなLeader（SPC）と併用することで、効率的なキー配置を実現
- LSP連携時、LocalLeaderからフォーマット操作等が可能

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

LocalLeaderのキーマッピング定義構造を理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | localleader.vim | `core/autoload/spacevim/map/localleader.vim` | s:localleader_map辞書の構造を理解 |

**読解のコツ**: Leaderマッピングと比較して、LocalLeaderのマッピングは限定的であることに注目。

**主要データ構造**:
- **1行目**: `let s:localleader_map = {}` - ルート辞書の初期化
- **3行目**: `let s:localleader_map['v'] = ['spacevim#plug#fzf#Open()', 'open-files']` - ファイル開く
- **4行目**: `let s:localleader_map['p'] = ['spacevim#plug#fzf#Rtp()', 'runtimepath']` - ランタイムパス表示
- **5-9行目**: fzfサブメニューの定義

#### Step 2: エントリーポイントを理解する

LocalLeader設定の起点を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | spacevim.vim | `core/autoload/spacevim.vim` | g:maplocalleader設定箇所 |
| 2-2 | config.vim | `layers/+vim/which-key/config.vim` | LocalLeader用which-key設定 |

**主要処理フロー**:
- **61行目（spacevim.vim）**: `let g:maplocalleader = get(g:, 'spacevim_localleader', ',')` - LocalLeader設定
- **4行目（config.vim）**: `nnoremap <silent> <localleader> :<c-u>WhichKey ','<CR>` - which-key起動

#### Step 3: which-key連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | which_key.vim | `core/autoload/spacevim/autocmd/which_key.vim` | LocalLeader辞書登録 |

**主要処理フロー**:
- **3行目**: `call which_key#register(',', 'g:spacevim#map#localleader#desc', 'n')` - ノーマルモード登録
- **5行目**: `call which_key#register(',', 'g:spacevim#map#localleader#desc_visual', 'v')` - ビジュアルモード登録

#### Step 4: ファイルタイプ固有設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | python.vim | `core/ftplugin/python.vim` | Python固有のLocalLeaderマッピング例 |
| 4-2 | go.vim | `core/ftplugin/go.vim` | Go固有のLocalLeaderマッピング例 |
| 4-3 | rust.vim | `core/ftplugin/rust.vim` | Rust固有のLocalLeaderマッピング例 |

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

```
spacevim#bootstrap()
    │
    ├─ spacevim#begin()
    │      └─ s:check_dot_spacevim()
    │             └─ g:maplocalleader 設定（61行目）
    │
    └─ spacevim#end()
           ├─ s:config()
           │      └─ layers/+vim/which-key/config.vim
           │             └─ nnoremap <localleader> WhichKey
           └─ spacevim#autocmd#which_key#Init()
                  └─ which_key#register(',', ...)
                         │
                         └─ FileType autocmd
                                └─ ftplugin/*.vim
                                       └─ 言語固有マッピング追加
```

### データフロー図

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

~/.spacevim ─────────────────▶ spacevim#begin() ─────────────────▶ g:maplocalleader設定
(g:spacevim_localleader)               │
                                       ▼
localleader.vim ─────────────▶ s:localleader_map定義 ────────────▶ g:spacevim#map#localleader#desc
(基本マッピング定義)                   │
                                       ▼
which_key.vim ───────────────▶ which_key#register() ─────────────▶ Which-Keyポップアップ
(辞書登録)                             │
                                       ▼
ftplugin/*.vim ──────────────▶ 言語固有マッピング追加 ───────────▶ 拡張LocalLeader機能
(ファイルタイプ検出時)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| localleader.vim | `core/autoload/spacevim/map/localleader.vim` | ソース | LocalLeader基本マッピング定義 |
| spacevim.vim | `core/autoload/spacevim.vim` | ソース | g:maplocalleader設定 |
| which_key.vim | `core/autoload/spacevim/autocmd/which_key.vim` | ソース | which-key辞書登録 |
| config.vim | `layers/+vim/which-key/config.vim` | 設定 | which-keyキーマッピング |
| python.vim | `core/ftplugin/python.vim` | 設定 | Python固有設定 |
| go.vim | `core/ftplugin/go.vim` | 設定 | Go固有設定 |
| rust.vim | `core/ftplugin/rust.vim` | 設定 | Rust固有設定 |
| lsp/config.vim | `layers/+tools/lsp/config.vim` | 設定 | LSP連携時のLocalLeader設定 |
