# バッチ設計書 9-pr-commands（style）

## 概要

本ドキュメントは、GitHub ActionsでPRコメント「/style」をトリガーとしてstylerパッケージによるコード自動整形を実行するワークフローの設計書である。

### 本バッチの処理概要

このバッチは、Pull RequestにMEMBERまたはOWNERが「/style」というコメントを投稿した際にトリガーされ、stylerパッケージを使用してRコードのスタイルを自動整形し、PRブランチにコミットする処理を行う。

**業務上の目的・背景**：Rコードのスタイルを一貫させることは、コードの可読性向上やチーム開発の効率化に重要である。stylerは、tidyverseスタイルガイドに基づいてRコードを自動整形するパッケージであり、インデント、スペース、改行などを統一する。このワークフローにより、メンテナがPRコメントでコード整形を指示でき、コントリビューターの環境に依存せずにコードスタイルを統一できる。

**バッチの実行タイミング**：PRコメントに「/style」が含まれ、コメント投稿者がMEMBERまたはOWNERである場合に実行される。

**主要な処理内容**：
1. リポジトリのチェックアウト
2. PRブランチのフェッチ
3. Rのセットアップ
4. stylerパッケージのインストール
5. styler::style_pkg()の実行
6. *.Rファイルの変更をコミット
7. PRブランチへのプッシュ

**前後の処理との関連**：format-suggestワークフロー（airフォーマッター）とは異なるスタイルガイドを使用する可能性がある。R-CMD-checkワークフローでの構文チェックには影響しない（スタイル変更のみ）。

**影響範囲**：PRブランチの*.Rファイルが整形される。

## バッチ種別

CI/CD（PRコマンド）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動 |
| 実行時刻 | N/A（イベント発生時） |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | issue_comment（created）+ /style コマンド |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actionsの有効化 | リポジトリでGitHub Actionsが有効であること |
| GITHUB_TOKEN | シークレットとしてGITHUB_TOKENが利用可能であること |
| contents: write権限 | PRブランチへの書き込み権限 |

### 実行可否判定

以下の全条件を満たす場合に実行される：
- コメントがPRに対するものである（github.event.issue.pull_request）
- コメント投稿者がMEMBERまたはOWNERである
- コメント本文が「/style」で始まる

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本バッチはPRコメントによりトリガー |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| PRブランチコード | Git | フェッチされたPRブランチのソースコード |
| *.R | Rソース | 整形対象のソースファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| *.R | Rソース | 整形されたソースファイル |
| PRブランチ | Git | コミットされた変更 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | *.R（パッケージ内全Rファイル） |
| 出力先 | PRブランチ |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. ワークフロートリガー
   └─ /styleコメントでissue_commentイベントが発火
2. 条件判定
   └─ PRコメントかつMEMBER/OWNERかつ/styleで始まるかチェック
3. リポジトリチェックアウト
   └─ actions/checkout@v4でリポジトリを取得
4. PRブランチフェッチ
   └─ r-lib/actions/pr-fetch@v2でPRブランチをチェックアウト
5. Rセットアップ
   └─ r-lib/actions/setup-r@v2でRをインストール
6. stylerインストール
   └─ install.packages("styler")でstylerをインストール
7. コード整形
   └─ styler::style_pkg()を実行
8. 変更をコミット
   └─ git add *.R && git commit -m 'Style'
9. PRブランチにプッシュ
   └─ r-lib/actions/pr-push@v2でPRブランチを更新
```

### フローチャート

```mermaid
flowchart TD
    A[/style コメント] --> B{条件判定}
    B -->|PR + MEMBER/OWNER| C[チェックアウト]
    B -->|条件不一致| Z[スキップ]
    C --> D[PRブランチフェッチ]
    D --> E[Rセットアップ]
    E --> F[stylerインストール]
    F --> G[styler::style_pkg実行]
    G --> H[*.R をコミット]
    H --> I[PRブランチにプッシュ]
    I --> J[ジョブ完了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | 本バッチはデータベースを使用しない |

### テーブル別操作詳細

本バッチはデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | stylerエラー | Rコードの構文エラー | Rファイルの構文エラーを修正 |
| - | コミットエラー | 変更がない場合 | 正常終了（変更なし） |
| - | プッシュエラー | PRブランチへの書き込み失敗 | 権限設定を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 再度/styleコメントで実行可能 |
| リトライ間隔 | N/A |
| リトライ対象エラー | 一時的なエラー |

### 障害時対応

エラー発生時は、GitHub Actions UIでログを確認し、エラー原因を特定して修正。Rコードの構文エラーの場合は、PRのソースコードを修正後に再度/styleコメントを投稿。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A |
| コミットタイミング | styler実行後 |
| ロールバック条件 | git revertで手動対応 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | パッケージ内全Rファイル |
| 目標処理時間 | 2-5分 |
| メモリ使用量上限 | GitHub Actions標準 |

## 排他制御

同一PRに対して同時に複数の/styleコマンドが実行された場合、後のプッシュが競合する可能性がある。実行中は再度コマンドを投稿しないことを推奨。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| stylerログ | コード整形時 | 整形されたファイル一覧 |
| gitログ | コミット/プッシュ時 | コミットハッシュ、変更ファイル |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1件以上 | GitHub通知 |

## 備考

- permissions: read-allがデフォルトで設定され、styleジョブでcontents: writeを個別に設定
- MEMBER/OWNER以外のユーザーが/styleコメントしても無視される（セキュリティ対策）
- pr-fetch@v2とpr-push@v2により、PRブランチの操作を安全に行う
- コミットメッセージは「Style」固定
- git configでGITHUB_ACTORを使用してコミット者情報を設定
- install.packages("styler")で直接インストール（setup-r-dependenciesを使用しない簡易版）
- styler::style_pkg()はパッケージ全体のRファイルを整形する
- git add \*.Rにより、全Rファイルの変更をステージング
