# 機能設計書 88-GitHub連携

## 概要

本ドキュメントは、space-vimのGitHub連携機能の設計について記述する。この機能は、GitHubダッシュボード表示、Gist連携、およびコミットURL生成機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：現代のソフトウェア開発において、GitHubは中心的なコラボレーションプラットフォームとなっている。開発者は頻繁にGitHubのダッシュボードを確認し、Gistでコードスニペットを共有し、コードレビュー時にコミットリンクを共有する必要がある。本機能は、Vimから離れることなくこれらのGitHub関連操作を実行できるようにし、開発ワークフローの効率化を実現する。

**機能の利用シーン**：GitHubのアクティビティ確認時、コードスニペットをGistとして共有したい時、コードレビューでソースコードの特定行へのリンクをクリップボードにコピーしたい時など、GitHub関連の操作が必要な場面で利用される。

**主要な処理内容**：
1. `+version-control/github`レイヤーの有効化によりGitHub関連プラグインをロード
2. `:GHDashboard`コマンドでGitHubダッシュボードを表示
3. `:GHActivity`コマンドでGitHubアクティビティを表示
4. `:Gist`コマンドでGist作成・閲覧
5. `spacevim#github#CommitRef()`でコミットURLを生成・クリップボードにコピー

**関連システム・外部連携**：GitHub API、vim-clap（プロジェクトルート検出）、gitコマンド（リモートURL・リビジョン取得）。

**権限による制御**：GitHubトークンの設定が必要な場合あり（ダッシュボード、Gist機能）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | GitHubダッシュボード | 主画面 | GitHubアクティビティの表示 |
| - | Gist | 主画面 | Gistの作成・閲覧 |

## 機能種別

外部サービス連携 / API呼び出し

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| bufnr | Number | Yes | 対象バッファ番号（CommitRef用） | 有効なバッファ番号 |

### 入力データソース

- 現在のバッファ情報（expand('%:p')）
- Gitリポジトリ情報（git remote -v、git rev-parse HEAD）
- プロジェクトルート（vim-clapのclap#path#find_project_root()）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| commit_url | String | GitHubコミットへの直接リンク |
| ダッシュボード表示 | Buffer | GitHubダッシュボード内容 |
| Gist操作結果 | String | Gist URLまたはエラーメッセージ |

### 出力先

- システムクリップボード（@+レジスタ）
- Vimのバッファ（ダッシュボード表示）
- コマンドライン（echo/echoerr）

## 処理フロー

### 処理シーケンス（CommitRef）

```
1. プロジェクトルート取得
   └─ clap#path#find_project_root()を呼び出し
2. Gitリポジトリ確認
   └─ ルートが空なら処理終了
3. 相対パス計算
   └─ expand('%:p')からroot_dirを引いた相対パス
4. リモートURL取得
   └─ git remote -vを実行してorigin URLを取得
5. URL正規化
   └─ .git接尾辞の除去
   └─ 認証トークンの除去（セキュリティ対策）
6. リビジョン取得
   └─ git rev-parse HEADで現在のコミットハッシュ取得
7. URL生成
   └─ {remote_url}/blob/{rev}{relative_path}#L{line}形式
8. クリップボードコピー
   └─ @+レジスタに格納し、メッセージ表示
```

### フローチャート

```mermaid
flowchart TD
    A[CommitRef呼び出し] --> B[プロジェクトルート検出]
    B --> C{Gitリポジトリ?}
    C -->|No| Z[処理終了]
    C -->|Yes| D[相対パス計算]
    D --> E[git remote -v実行]
    E --> F{originあり?}
    F -->|No| G[エラー表示]
    F -->|Yes| H[リモートURL取得]
    H --> I[URL正規化]
    I --> J[git rev-parse HEAD]
    J --> K[コミットURL生成]
    K --> L[クリップボードにコピー]
    L --> M[成功メッセージ表示]
    G --> Z
    M --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-88-1 | オンデマンドロード | プラグインはコマンド実行時のみロード | GHDashboard/GHActivity/Gist実行時 |
| BR-88-2 | .git除去 | リモートURLの.git接尾辞を自動除去 | URL正規化時 |
| BR-88-3 | トークン除去 | ghp_TOKEN形式の認証情報を除去 | セキュリティ対策 |
| BR-88-4 | 行番号付加 | コミットURLに現在行番号を付加 | #L{line}形式 |

### 計算ロジック

**コミットURL生成**:
```vim
let commit_url = printf('%s/blob/%s%s#L%d', remote_url, rev, relative_path, line('.'))
```

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

本機能はデータベース操作を行わない。

### 操作別データベース影響一覧

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Gitリポジトリ外 | root_dirが空 | Gitリポジトリ内でコマンド実行 |
| - | originなし | git remote -vにoriginがない | git remote add originでリモート設定 |
| - | パス不一致 | abs_pathがroot_dir配下にない | 正しいリポジトリ内でファイルを開く |
| - | プラグイン未インストール | vim-github-dashboard等がない | :PlugInstallを実行 |

### リトライ仕様

リトライは不要。エラー発生時はユーザーが環境を修正して再度コマンド実行。

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

該当なし（ファイルシステムやDBへの永続化を伴わない）

## パフォーマンス要件

- コミットURL生成は即座（500ms以内）に完了すること
- Git操作はsystemlist()で実行、ブロッキングを最小化

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

- 認証トークン（ghp_TOKEN形式）をURLから自動除去
- クリップボードへのコピーはローカル操作のみ
- GitHub APIへのアクセスはプラグイン（webapi-vim等）経由

## 備考

- vim-github-dashboardはjunegunn氏作成（fzf、goyoと同じ作者）
- gist-vimはmattn氏作成（webapi-vimと同じ作者）
- CommitRef機能はvim-clapのプロジェクト検出機能に依存

---

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

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

### 推奨読解順序

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

本機能は複数のプラグインとGit操作を組み合わせて動作する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+version-control/github/packages.vim` | ロードされるプラグインの確認 |

**読解のコツ**: `{ 'on': ['GHDashboard', 'GHActivity'] }`は複数コマンドでの遅延ロードを指定。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | packages.vim | `layers/+version-control/github/packages.vim` | プラグイン登録 |
| 2-2 | github.vim | `core/autoload/spacevim/github.vim` | CommitRef関数 |

**主要処理フロー（packages.vim）**:
1. **1行目**: vim-github-dashboard登録（GHDashboard/GHActivityで遅延ロード）
2. **2行目**: webapi-vim登録（Gistで遅延ロード）
3. **3行目**: gist-vim登録（Gistで遅延ロード）

#### Step 3: CommitRef関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | github.vim | `core/autoload/spacevim/github.vim` | URL生成ロジック |

**主要処理フロー**:
- **2行目**: `clap#path#find_project_root(bufnr(''))` - プロジェクトルート取得
- **4-7行目**: Gitリポジトリ確認
- **9-17行目**: 相対パス計算
- **20-25行目**: git remote -vでorigin URL取得
- **28-37行目**: URL正規化（.git除去、トークン除去）
- **39行目**: git rev-parse HEADでコミットハッシュ取得
- **41行目**: commit_url生成
- **43行目**: クリップボード（@+）へコピー
- **45-51行目**: 成功メッセージ表示

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

```
ユーザー操作
    │
    ├─ :GHDashboard / :GHActivity
    │      └─ vim-plugが遅延ロード
    │             └─ vim-github-dashboard実行
    │                    └─ GitHub API呼び出し
    │
    ├─ :Gist
    │      └─ vim-plugが遅延ロード
    │             └─ webapi-vim + gist-vim実行
    │                    └─ GitHub Gist API呼び出し
    │
    └─ spacevim#github#CommitRef()
           ├─ clap#path#find_project_root()
           │      └─ プロジェクトルート検出
           ├─ systemlist('git remote -v')
           │      └─ リモートURL取得
           ├─ systemlist('git rev-parse HEAD')
           │      └─ コミットハッシュ取得
           └─ @+ = commit_url
                  └─ クリップボードにコピー
```

### データフロー図

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

expand('%:p')       spacevim#github#CommitRef()      commit_url
line('.')     ──▶  URL生成・正規化              ──▶  @+レジスタ
git remote                                            エコー表示
git rev-parse
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+version-control/github/packages.vim` | ソース | プラグイン登録 |
| config.vim | `layers/+version-control/github/config.vim` | ソース | 設定（現在空） |
| README.md | `layers/+version-control/github/README.md` | ドキュメント | レイヤー説明 |
| github.vim | `core/autoload/spacevim/github.vim` | ソース | CommitRef関数 |
