# 機能設計書 75-quick-scope

## 概要

本ドキュメントは、space-vimの+vim/better-motionレイヤーが提供するquick-scope機能について、その設計と実装を詳細に記述する。

### 本機能の処理概要

**業務上の目的・背景**：
Vimのf/F/t/Tコマンドは行内の特定文字へのジャンプに使用されるが、どの文字を指定すれば最小キーストロークで目的位置に到達できるかを瞬時に判断するのは難しい。quick-scopeは、各単語内でf/tジャンプの「最適なターゲット文字」をハイライト表示することで、この問題を解決する。これにより、ユーザーはハイライトされた文字を見て即座に効率的なジャンプキーを選択できる。

**機能の利用シーン**：
- f/tコマンドでの行内移動時に、最適なターゲット文字を視覚的に確認したい場合
- 長い行で複数の単語をまたいで移動する際の効率化
- ペアプログラミングやコードレビュー時に、移動操作を説明・学習する場面

**主要な処理内容**：
1. quick-scopeプラグインの即時読み込み（遅延読み込みなし）
2. f/F/t/Tキー押下時に、各単語のユニークな文字をハイライト
3. ハイライトは一時的に表示され、移動操作後に消える
4. ハイライト対象キーのカスタマイズ（設定による）

**関連システム・外部連携**：
- 外部プラグイン: unblevable/quick-scope
- +vim/better-motionレイヤー内でEasyMotion、vim-sneakと共存

**権限による制御**：
本機能に権限による制御は存在しない。+vim/better-motionレイヤーを有効化することで全ユーザーが利用可能となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Vimエディタ画面 | 主画面 | f/F/t/Tキー押下時のハイライト表示 |

## 機能種別

エディタ補助機能 / 視覚的ヒント表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| トリガーキー | Char | Yes | f/F/t/Tのいずれか | config.vimで定義 |

### 入力データソース

- ユーザーのキーボード入力（f/F/t/Tキー）
- 現在の行のテキスト内容（ハイライト対象の計算用）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ハイライト表示 | Visual | 各単語内のユニーク文字をハイライト |

### 出力先

- Vimエディタのバッファ画面（ハイライトのオーバーレイ）

## 処理フロー

### 処理シーケンス

```
1. ユーザーがf/F/t/Tキーを押下
   └─ quick-scopeがトリガーされる
2. 現在行のテキストを解析
   └─ 各単語内でユニークな文字を特定
3. ユニーク文字をハイライト表示
   └─ 第1候補と第2候補で異なる色を使用
4. ユーザーが対象文字を入力
   └─ 標準のf/F/t/T動作でジャンプ
5. ハイライトが消える
   └─ 通常のエディタ表示に戻る
```

### フローチャート

```mermaid
flowchart TD
    A[f/F/t/T 押下] --> B[現在行を解析]
    B --> C[各単語のユニーク文字を特定]
    C --> D[ハイライト表示]
    D --> E[対象文字入力待ち]
    E --> F[ジャンプ実行]
    F --> G[ハイライト消去]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-1 | 即時ロード | 遅延読み込みなしで即座にロード | 常時（packages.vimで定義） |
| BR-75-2 | トリガーキー | f/F/t/Tキーでハイライトをトリガー | config.vimで設定 |
| BR-75-3 | ユニーク優先 | 単語内で1回のみ出現する文字を優先ハイライト | ハイライト計算時 |

### 計算ロジック

- 各単語内で出現回数が1回の文字を「第1候補」としてハイライト
- 出現回数が複数でも、行内で最も左にある出現を「第2候補」としてハイライト

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

本機能にデータベース操作は存在しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ハイライト対象なし | 行が空または単語がない | 何も表示せず標準動作 |

### リトライ仕様

本機能にリトライ処理は存在しない。

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

本機能にトランザクション処理は存在しない。

## パフォーマンス要件

- 即時ロード（遅延読み込みなし）だが、軽量プラグインのため起動時間への影響は軽微
- ハイライト計算は即座に完了（現在行のみが対象のため）

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

本機能は表示のみであり、セキュリティ上の考慮事項は特になし。

## 備考

- quick-scopeはunblevable氏が開発・メンテナンスしている外部プラグイン
- f/tコマンドの標準動作を変更せず、視覚的ヒントのみを追加
- EasyMotionやvim-sneakと組み合わせて使用することで、様々な移動スタイルに対応

---

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

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

### 推奨読解順序

#### Step 1: パッケージ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+vim/better-motion/packages.vim` | quick-scopeプラグインの登録 |

**読解のコツ**: quick-scopeは他のモーションプラグインと異なり、遅延読み込みなしで即座にロードされる。これはハイライト機能が常に利用可能である必要があるため。

**主要処理フロー**:
- **1行目**: `MP 'unblevable/quick-scope'` - 即時ロード設定（オプションなし）

#### Step 2: 設定ファイルを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.vim | `layers/+vim/better-motion/config.vim` | トリガーキーの設定 |

**読解のコツ**: `g:qs_highlight_on_keys`変数でハイライトをトリガーするキーを定義している。

**主要処理フロー**:
- **32行目**: `let g:qs_highlight_on_keys = ['f', 'F', 't', 'T']` - トリガーキー設定

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

```
~/.spacevim（ユーザー設定）
    │
    └─ Layer('+vim/better-motion')
           │
           ├─ packages.vim
           │      └─ MP 'unblevable/quick-scope'（即時ロード）
           │
           └─ config.vim
                  └─ g:qs_highlight_on_keys = ['f', 'F', 't', 'T']
```

### データフロー図

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

f/F/t/T 押下       ───▶  行内テキスト解析       ───▶  ユニーク文字ハイライト
                                ↓
対象文字入力        ───▶  標準f/t動作            ───▶  カーソルジャンプ
                                ↓
                          ハイライト消去
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+vim/better-motion/packages.vim` | ソース | プラグイン登録（即時ロード） |
| config.vim | `layers/+vim/better-motion/config.vim` | ソース | トリガーキー設定 |
