# 機能設計書 74-vim-sneak

## 概要

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

### 本機能の処理概要

**業務上の目的・背景**：
Vimの標準的なf/t/F/Tコマンドは単一文字を対象とするため、一般的な文字（e、a、s等）では同じ行に多数のマッチが存在し、;キーを繰り返し押す必要がある。vim-sneakは2文字の組み合わせを検索対象とすることで、一意性を高め、より少ないキーストロークで目的位置に到達できるようにする。これにより、EasyMotionよりも軽量でありながら、標準のf/tコマンドよりも効率的なカーソル移動が実現される。

**機能の利用シーン**：
- 行内または複数行にわたって特定の2文字の組み合わせにジャンプしたい場合
- f/tコマンドの延長として、より精度の高い文字検索を行いたい場合
- EasyMotionほどの視覚的なオーバーレイなしに、素早く移動したい場合

**主要な処理内容**：
1. vim-sneakプラグインの遅延読み込み（タイマーによる600ms後のロード）
2. s/Sキーによる2文字検索のトリガー
3. マッチ位置への即座のジャンプ
4. ;/,キーによる次/前のマッチへの移動

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

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Vimエディタ画面 | 主画面 | s/Sキーによる2文字検索とジャンプ |

## 機能種別

エディタ補助機能 / カーソル移動

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 検索方向 | String | Yes | s（前方）またはS（後方） | s/Sキーのみ |
| 検索文字 | Char[2] | Yes | 検索対象の2文字 | 任意の2文字 |

### 入力データソース

- ユーザーのキーボード入力（s/S + 2文字）
- 現在のバッファ内容（検索対象）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| カーソル位置 | Number | ジャンプ後のカーソル行・列 |
| ハイライト | Visual | マッチ位置のハイライト表示（オプション） |

### 出力先

- カーソル位置（ジャンプ実行後）
- バッファ画面（マッチのハイライト）

## 処理フロー

### 処理シーケンス

```
1. ユーザーがs（またはS）を押下
   └─ 2文字入力モードに入る
2. 2文字を入力
   └─ 前方（または後方）検索を実行
3. 最初のマッチ位置にジャンプ
   └─ カーソルが移動
4. ;で次のマッチ、,で前のマッチに移動（オプション）
   └─ 検索を継続
```

### フローチャート

```mermaid
flowchart TD
    A[s/S 押下] --> B[2文字入力待ち]
    B --> C[2文字入力]
    C --> D{マッチあり?}
    D -->|Yes| E[最初のマッチにジャンプ]
    D -->|No| F[ビープ/警告]
    E --> G{継続操作?}
    G -->|;| H[次のマッチにジャンプ]
    G -->|,| I[前のマッチにジャンプ]
    G -->|その他| J[検索終了]
    H --> G
    I --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-74-1 | 遅延読み込み | 起動時間短縮のため600ms後にロード | speed_up_via_timer有効時 |
| BR-74-2 | 2文字検索 | 常に2文字の組み合わせで検索 | s/Sコマンド実行時 |
| BR-74-3 | 大文字小文字 | デフォルトでは大文字小文字を区別 | 設定による |

### 計算ロジック

本機能に独自の計算ロジックは存在しない（vim-sneakプラグインに委譲）。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | マッチなし | 指定2文字がバッファ内に存在しない | 別の文字を指定 |
| - | Escキャンセル | ユーザーがEscでsneakをキャンセル | 正常終了として扱う |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 遅延読み込みにより起動時間への影響を最小化（600ms後にバックグラウンドロード）
- 検索は即座に実行される（EasyMotionよりも軽量）

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

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

## 備考

- vim-sneakはjustinmk氏が開発・メンテナンスしている外部プラグイン
- 標準のf/t/F/Tコマンドの強化版として位置づけられる
- EasyMotionと比較して、視覚的なオーバーレイが少なく軽量

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: vim-sneakはEasyMotionと同じ遅延読み込みグループに含まれており、600msのタイマーで`spacevim#defer#motion`関数によりロードされる。

**主要処理フロー**:
- **4行目**: `MP 'justinmk/vim-sneak', { 'on': [] }` - 遅延読み込み設定
- **9行目**: `MP 'justinmk/vim-sneak'` - 通常ロード設定

#### Step 2: 遅延読み込み関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | defer.vim | `core/autoload/spacevim/defer.vim` | 遅延読み込みの実装 |

**読解のコツ**: `spacevim#defer#motion`関数でvim-sneak、vim-easymotion、incsearch-easymotion.vimが一括でロードされる。

**主要処理フロー**:
- **41-43行目**: `spacevim#defer#motion`関数 - vim-sneakを含む複数プラグインをロード

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

```
~/.spacevim（ユーザー設定）
    │
    └─ Layer('+vim/better-motion')
           │
           └─ packages.vim
                  ├─ MP 'justinmk/vim-sneak'（遅延/通常）
                  └─ timer_start(600, 'spacevim#defer#motion')

core/autoload/spacevim/defer.vim
    │
    └─ spacevim#defer#motion()
           └─ s:lod('vim-sneak', 'vim-easymotion', ...)
```

### データフロー図

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

s + {2文字}        ───▶  前方検索              ───▶  カーソルジャンプ
S + {2文字}        ───▶  後方検索              ───▶  カーソルジャンプ
;                  ───▶  次のマッチ            ───▶  カーソルジャンプ
,                  ───▶  前のマッチ            ───▶  カーソルジャンプ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+vim/better-motion/packages.vim` | ソース | プラグイン登録と遅延読み込み設定 |
| defer.vim | `core/autoload/spacevim/defer.vim` | ソース | 遅延読み込み実装 |
