# 機能設計書 176-Invoke-DbatoolsFormatter

## 概要

本ドキュメントは、dbatools PowerShellモジュールのInvoke-DbatoolsFormatter関数の機能設計を定義する。PowerShell関数ファイルをdbatoolsコーディング標準にフォーマットする機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：PSScriptAnalyzerのInvoke-FormatterをOTBS（One True Brace Style）設定で使用して、PowerShellファイルに一貫したコードフォーマットを適用する。dbatoolsモジュール全体でインデント、ブレース配置、空白処理を標準化し、コントリビューターとメンテナーのコード一貫性を確保する。クロスプラットフォーム互換性のためにBOMなしエンコーディングと適切な改行処理でファイルを保存する。

**機能の利用シーン**：
- dbatoolsへの新規コントリビューション時のコードフォーマット
- 既存ファイルの一括フォーマット
- プルリクエスト前のコードスタイル準拠確認
- モジュール開発時の標準化作業

**主要な処理内容**：
1. PSScriptAnalyzerのバージョン確認（1.18.2必須）
2. ファイル読み込みと末尾空行の除去
3. Invoke-FormatterでOTBSスタイルフォーマット適用
4. コメントブロックヘルプ（CBH）のインデント修正
5. タブをスペースに変換し、行末空白を除去
6. BOMなしUTF-8でファイル保存

**関連システム・外部連携**：PSScriptAnalyzerモジュール（バージョン1.18.2必須）のInvoke-Formatterを使用。

**権限による制御**：ファイルへの読み書き権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングに登録なし |

## 機能種別

コードフォーマット / 開発支援

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | object[] | Yes | フォーマット対象のPowerShellファイルパス | Mandatory, ValueFromPipeline |
| EnableException | switch | No | 例外をスローするか | - |

### 入力データソース

- Pathパラメータで指定されたPowerShell（.ps1）ファイル
- Get-ChildItemからのパイプライン入力

## 出力仕様

### 出力データ

なし（ファイルを直接更新）

### 出力先

- 入力ファイルを直接上書き保存

## 処理フロー

### 処理シーケンス

```
1. beginブロック: PSScriptAnalyzer検証
   ├─ Invoke-Formatterの存在確認
   ├─ バージョン1.18.2の確認
   └─ 必要に応じてモジュール再インポート

2. 正規表現パターン準備
   ├─ CBH全体マッチパターン
   ├─ CBH開始インデントパターン
   └─ CBH終了インデントパターン

3. processブロック: 各ファイル処理
   ├─ パス解決
   ├─ ファイル読み込み（UTF-8）
   ├─ 末尾空行除去
   ├─ Invoke-Formatter実行（CodeFormattingOTBS）
   ├─ CBHインデント修正
   ├─ タブ→スペース変換
   ├─ 行末空白除去
   └─ BOMなしUTF-8で保存
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{PSScriptAnalyzer<br/>インストール済み?}
    B -->|No| C[エラー: インストール案内]
    B -->|Yes| D{バージョン1.18.2?}
    D -->|No| E[モジュール再インポート]
    E --> F{インポート成功?}
    F -->|No| C
    F -->|Yes| G[ファイルループ開始]
    D -->|Yes| G
    G -->|次のFile| H[パス解決]
    H --> I[ファイル読み込み]
    I --> J[末尾空行除去]
    J --> K[Invoke-Formatter<br/>CodeFormattingOTBS]
    K --> L{成功?}
    L -->|No| M[Warning出力]
    L -->|Yes| N[CBHインデント修正]
    M --> G
    N --> O[タブ→スペース変換]
    O --> P[行末空白除去]
    P --> Q[BOMなしUTF-8保存]
    Q --> G
    G -->|完了| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-176-01 | PSScriptAnalyzerバージョン | バージョン1.18.2が必須 | 常時 |
| BR-176-02 | OTBSスタイル | One True Brace Styleでフォーマット | 常時 |
| BR-176-03 | CBHインデント | コメントブロックヘルプの終了行インデントを開始行に合わせる | CBH存在時 |
| BR-176-04 | タブ変換 | タブを4スペースに変換 | 常時 |
| BR-176-05 | BOMなしUTF-8 | ファイルはBOMなしUTF-8で保存 | 常時 |
| BR-176-06 | 改行コード | Windows/Unix環境に応じた改行コードを維持 | 常時 |

### 計算ロジック

CBHインデント修正:
```powershell
$CBHRex = [regex]'(?smi)\s+\<\#[^#]*\#\>'       # CBH全体マッチ
$CBHStartRex = [regex]'(?<spaces>[ ]+)\<\#'      # 開始インデント取得
$CBHEndRex = [regex]'(?<spaces>[ ]*)\#\>'        # 終了インデント置換
```

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

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ModuleNotFound | PSScriptAnalyzer未インストール | Install-Moduleを案内 |
| - | VersionMismatch | PSScriptAnalyzer 1.18.2でない | 正しいバージョンのインストールを案内 |
| - | FileNotFound | 指定ファイルが存在しない | パスを確認 |
| - | FormatError | Invoke-Formatterが失敗 | Warning出力して継続 |

### リトライ仕様

リトライ機能なし。Invoke-Formatter失敗時はWarning出力して次のファイルへ。

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

ファイル単位での処理。途中失敗時に部分的に更新されたファイルが残る可能性あり。

## パフォーマンス要件

- 大規模ファイルの処理には時間がかかる可能性
- パイプラインで複数ファイルを順次処理

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

- ファイルへの書き込み権限が必要
- 入力ファイルの内容を検証しない（信頼できるソースからのみ使用すること）

## 備考

- PSScriptAnalyzerの特定バージョン依存
- #4373問題に対応したCBHインデント修正
- #5830問題に対応したWindows/Unix改行コード処理

---

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

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

### 推奨読解順序

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

正規表現パターンとファイル処理の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbatoolsFormatter.ps1 | `public/Invoke-DbatoolsFormatter.ps1` | 65-71行目: 正規表現パターン定義 |

**読解のコツ**: CBH（Comment-Based Help）の構造とインデント修正の目的を理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbatoolsFormatter.ps1 | `public/Invoke-DbatoolsFormatter.ps1` | 関数全体の流れを把握 |

**主要処理フロー**:
1. **48-64行目**: PSScriptAnalyzerバージョン確認
2. **65-71行目**: 正規表現パターン準備
3. **82-91行目**: ファイル読み込みと改行コード検出
4. **94-99行目**: Invoke-Formatter実行
5. **100-113行目**: CBHインデント修正
6. **114-120行目**: タブ変換と保存

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbatoolsFormatter.ps1 | `public/Invoke-DbatoolsFormatter.ps1` | 100-113行目: CBHインデント修正ロジック |

**主要処理フロー**:
- **101-102行目**: CBH抽出
- **104-105行目**: 開始スペース取得
- **107-110行目**: 終了インデント置換

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

```
Invoke-DbatoolsFormatter
    │
    ├─ beginブロック
    │      ├─ Get-Command Invoke-Formatter
    │      ├─ Remove-Module PSScriptAnalyzer
    │      └─ Import-Module PSScriptAnalyzer -RequiredVersion
    │
    └─ processブロック
           ├─ Resolve-Path
           ├─ Get-Content -Raw -Encoding UTF8
           ├─ Invoke-Formatter -Settings CodeFormattingOTBS
           ├─ 正規表現によるCBH修正
           └─ [System.IO.File]::WriteAllText (BOMなしUTF8)
```

### データフロー図

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

Path (file.ps1) ──▶ Resolve-Path ──▶ Get-Content
                                         │
                                         ▼
                              末尾空行除去
                                         │
                                         ▼
                              Invoke-Formatter
                              (CodeFormattingOTBS)
                                         │
                                         ▼
                              CBHインデント修正
                                         │
                                         ▼
                              タブ→スペース変換
                              行末空白除去
                                         │
                                         ▼
                              WriteAllText
                              (BOMなしUTF-8)
                                         │
                                         ▼
                              file.ps1 (上書き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbatoolsFormatter.ps1 | `public/Invoke-DbatoolsFormatter.ps1` | ソース | メイン関数 |
| PSScriptAnalyzer (外部) | - | 外部モジュール | Invoke-Formatter提供 |
