# 画面設計書 279-フォーマッター

## 概要

本ドキュメントは、dbatoolsモジュールのコードフォーマッター機能（Invoke-DbatoolsFormatter）に関する画面設計書です。

### 本画面の処理概要

PowerShellスクリプトファイルをdbatoolsのコーディング標準に従ってフォーマットするPowerShellコマンドを提供します。PSScriptAnalyzerのInvoke-Formatterを使用してOTBS（One True Brace Style）スタイルでコードを整形します。

**業務上の目的・背景**：dbatoolsプロジェクトへの貢献者やメンテナーは、一貫したコードスタイルを維持する必要があります。本機能により、インデント、ブレース配置、空白処理を自動的に標準化し、コードレビューの効率化とコードベース全体の一貫性を確保します。クロスプラットフォーム互換性のため、BOMなしのUTF-8エンコーディングと適切な改行処理も行います。

**画面へのアクセス方法**：PowerShellコンソールから`Invoke-DbatoolsFormatter`コマンドを実行します。

**主要な操作・処理内容**：
1. PowerShellファイル（.ps1）の読み込み
2. PSScriptAnalyzerのInvoke-FormatterによるOTBS整形
3. コメントブロックヘルプ（CBH）のインデント調整
4. 末尾空白の削除とタブのスペース変換
5. BOMなしUTF-8でのファイル書き込み

**画面遷移**：CLIベースのため画面遷移は存在しません。

**権限による表示制御**：対象ファイルへの書き込み権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 176 | Invoke-DbatoolsFormatter | 主機能 | dbatoolsコードフォーマッター |

## 画面種別

コマンドラインインターフェース（CLI）

## URL/ルーティング

PowerShellコマンドレット
- `Invoke-DbatoolsFormatter`

## 入出力項目

### Invoke-DbatoolsFormatter

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Path | object[] | Yes | フォーマット対象のファイルパス（パイプライン入力対応、エイリアス: FullName） |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Invoke-DbatoolsFormatter出力

本コマンドはパイプラインに何も出力しません。ファイルを直接更新します。

## イベント仕様

### 1-ファイルフォーマット

Invoke-DbatoolsFormatterコマンド実行時、指定されたファイルを読み込み、フォーマット処理を行い、元のファイルに上書き保存します。

**処理詳細**：
1. PSScriptAnalyzerのバージョン確認（1.18.2が必要）
2. ファイルパスの解決
3. UTF-8でファイル内容を読み込み
4. 改行コードの検出と適切な処理
5. 末尾の空行を削除
6. Invoke-Formatter -Settings CodeFormattingOTBS でフォーマット
7. コメントブロックヘルプ（CBH）のインデント調整
8. タブをスペースに変換し、末尾空白を削除
9. BOMなしUTF-8でファイルに書き込み

## データベース更新仕様

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

本機能はSQL Serverデータベースに対する直接的な操作は行いません。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| Error | You need PSScriptAnalyzer version 1.18.2 installed | PSScriptAnalyzerが未インストールまたはバージョン不一致 |
| Warning | Install-Module -Name PSScriptAnalyzer -RequiredVersion '1.18.2' | PSScriptAnalyzer要件未満時 |
| Error | Cannot find or resolve {path} | パスが解決できない |
| Warning | Unable to format {path} | フォーマット処理に失敗 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| PSScriptAnalyzer未インストール | Stop-Functionでエラー、インストールコマンドを案内 |
| PSScriptAnalyzerバージョン不一致 | 正しいバージョンのインポートを試行、失敗時はエラー |
| パス解決失敗 | Stop-Functionで続行（-Continue） |
| フォーマット失敗 | 警告メッセージを出力して続行 |

## 備考

- PSScriptAnalyzer 1.18.2が必須
- OTBSスタイル（One True Brace Style）を適用
- タブは4スペースに変換
- BOMなしUTF-8エンコーディング
- 改行コードはプラットフォームに応じて自動判定（CRLF/LF）
- コメントブロックヘルプの終了インデントを開始インデントに合わせる
- Get-ChildItemからのパイプライン入力に対応

---

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

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

### 推奨読解順序

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

本コマンドはファイルを直接操作するため、特定のデータ構造は存在しません。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbatoolsFormatter.ps1 | `public/Invoke-DbatoolsFormatter.ps1` | 必要なPSScriptAnalyzerバージョンと設定を理解 |

**読解のコツ**: PSScriptAnalyzerのInvoke-Formatterコマンドとその設定を把握することが重要です。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbatoolsFormatter.ps1 | `public/Invoke-DbatoolsFormatter.ps1` | コマンド実行時の動作 |

**主要処理フロー**:
1. **48-64行目（begin）**: PSScriptAnalyzerバージョン確認と正規表現定義
2. **65-71行目**: 改行コード設定
3. **76-80行目**: パス解決
4. **82-91行目**: ファイル読み込みと改行コード判定
5. **94-99行目**: 末尾空行削除とInvoke-Formatter実行
6. **100-113行目**: CBHインデント調整
7. **114-120行目**: ファイル書き込み

#### Step 3: フォーマット処理の詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbatoolsFormatter.ps1 | `public/Invoke-DbatoolsFormatter.ps1` | 正規表現によるCBH処理（65-67行目、101-113行目） |

**主要処理フロー**:
- **65行目**: CBHブロック全体にマッチする正規表現
- **66-67行目**: CBH開始/終了インデント取得用正規表現
- **101-113行目**: CBH終了インデントを開始インデントに合わせる

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

```
Invoke-DbatoolsFormatter
    │
    ├─ Begin Block
    │      ├─ Get-Command Invoke-Formatter
    │      └─ Import-Module PSScriptAnalyzer -RequiredVersion 1.18.2
    │
    └─ Process Block
           ├─ Resolve-Path
           ├─ Get-Content -Raw -Encoding UTF8
           ├─ Invoke-Formatter -Settings CodeFormattingOTBS
           ├─ $CBHRex.Match / $CBHEndRex.Replace
           └─ [System.IO.File]::WriteAllText (UTF8NoBom)
```

### データフロー図

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

ファイルパス ──────────▶ Get-Content ────────────────────▶ 文字列
                              │
                              ├─ Invoke-Formatter (OTBS)
                              │
                              ├─ CBHインデント調整
                              │
                              ├─ タブ→スペース変換
                              │
                              └─ 末尾空白削除
                                     │
                                     └─ WriteAllText ────▶ ファイル更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbatoolsFormatter.ps1 | `public/Invoke-DbatoolsFormatter.ps1` | ソース | コードフォーマッターコマンド |
| PSScriptAnalyzer（外部モジュール） | - | 依存 | Invoke-Formatterを提供 |
