# バッチ設計書 63-OpenConsole.psm1

## 概要

本ドキュメントは、OpenConsoleプロジェクト用のPowerShellモジュール `OpenConsole.psm1` のバッチ設計書である。プロジェクトのルートディレクトリ検索、ビルド環境設定、テスト実行、コードフォーマット、ローカルモジュール管理等の共通関数を一括して提供するモジュールである。

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

本モジュールは、OpenConsole（Windows Terminal）プロジェクトの開発・ビルド・テスト作業で使用される共通関数群をPowerShellモジュールとして提供する。モジュールをインポートすることで、開発者やCI/CDパイプラインから一貫した方法でプロジェクト操作を行うことができる。

**業務上の目的・背景**：OpenConsoleプロジェクトはビルド、テスト、コードフォーマット等の開発ワークフローが複雑であり、各操作を個別のスクリプトで実行するとパス解決やツールバージョン管理が煩雑になる。本モジュールは、プロジェクトルートの自動検出、Visual Studio開発環境の変数設定、テスト実行（TAEF/WinAppDriver対応）、C++/XAMLコードフォーマットなど、開発に必要な操作を統一的なインターフェースで提供する。これにより、開発者の作業効率向上とCI/CDパイプラインの安定稼働を実現する。

**バッチの実行タイミング**：開発者がPowerShellセッションで `Import-Module` コマンドにより随時インポートする。また、他のスクリプト（runformat.cmd、runxamlformat.cmd等）から間接的に呼び出される。

**主要な処理内容**：
1. `Find-OpenConsoleRoot` - gitリポジトリのルートディレクトリを検出する（フォールバックパスあり）
2. `Import-LocalModule` - PSGalleryからモジュールをダウンロードしローカルにインポートする
3. `Set-MsbuildDevEnvironment` - Visual StudioのVC++開発環境変数を設定する（VSSetupモジュール使用）
4. `Invoke-OpenConsoleTests` - TAEFを使用してユニットテスト/フィーチャーテスト/UIAテストを実行する
5. `Invoke-OpenConsoleBuild` - NuGetリストア後にMSBuildでソリューションをビルドする
6. `Start-OpenConsole` / `Debug-OpenConsole` - ビルド成果物のOpenConsole.exeを起動/デバッグ起動する
7. `Invoke-ClangFormat` - C++ソースファイルにclang-formatを適用する（バッチ処理対応）
8. `Invoke-CodeFormat` - C++とXAMLファイルの一括フォーマットを実行する
9. `Invoke-XamlFormat` / `Test-XamlFormat` - XAMLファイルのフォーマット適用/チェックを行う

**前後の処理との関連**：runformat.cmd（No.30）はInvoke-CodeFormatを呼び出す。runxamlformat.cmd（No.31）はInvoke-XamlFormatを呼び出す。runut.cmd（No.8）等のテストスクリプトとも連携する。Invoke-FormattingCheck.ps1（No.32）でもフォーマットチェック機能が使用される。

**影響範囲**：開発環境のPowerShellセッションの環境変数（Set-MsbuildDevEnvironmentによるVC++環境変数設定）、ファイルシステム（コードフォーマット時のソースファイル書き換え）、プロセス管理（テスト実行時のWinAppDriver起動/停止）に影響する。

## バッチ種別

ユーティリティモジュール / 開発支援

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（Import-Module時） |
| 実行時刻 | 開発者またはCI/CDパイプラインの操作に依存 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | Import-Moduleコマンドまたは他スクリプトからの呼び出し |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| PowerShell 7以上 | `#Requires -Version 7` によりPowerShell 7.0以上が必須 |
| gitインストール | Find-OpenConsoleRootがgitコマンドを使用する |
| Visual Studioインストール | Set-MsbuildDevEnvironmentがVS環境を必要とする |
| NuGetパッケージ | テスト実行時にTAEFパッケージが必要 |

### 実行可否判定

PowerShell 7以上のランタイムで実行されていること。各関数の前提条件は関数ごとに異なる。

## 入力仕様

### 入力パラメータ

モジュール全体としてのパラメータはなし。各エクスポート関数のパラメータは以下の通り。

| パラメータ名 | 対象関数 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---------|-----|-----|-------------|------|
| Name | Import-LocalModule | string | Yes | なし | インポートするモジュール名 |
| Prerelease | Set-MsbuildDevEnvironment | switch | No | $false | プレリリース版VSを含めるか |
| AllTests | Invoke-OpenConsoleTests | switch | No | $false | 全テスト実行 |
| FTOnly | Invoke-OpenConsoleTests | switch | No | $false | FTテストのみ実行 |
| Test | Invoke-OpenConsoleTests | string | No | なし | 個別テスト指定 |
| TaefArgs | Invoke-OpenConsoleTests | string[] | No | なし | TAEF追加引数 |
| Platform | Invoke-OpenConsoleTests / Start-OpenConsole / Debug-OpenConsole | string | No | "x64" | プラットフォーム（x64/x86） |
| Configuration | Invoke-OpenConsoleTests / Start-OpenConsole / Debug-OpenConsole | string | No | "Debug" | ビルド構成（Debug/Release） |
| Path | Invoke-ClangFormat | string[] | Yes | なし | フォーマット対象ファイルパス |
| ClangFormatPath | Invoke-ClangFormat | string | No | "clang-format" | clang-formatのパス |
| IgnoreXaml | Invoke-CodeFormat | switch | No | $false | XAMLフォーマットをスキップ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| tests.xml | XML | テスト構成定義ファイル |
| packages.config | XML | NuGetパッケージ構成（clang-formatパッケージ参照） |
| XamlStyler.json | JSON | XAMLフォーマット設定 |
| ソースファイル | C++/XAML | フォーマット対象のソースコード |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| PowerShellセッション | 環境変数 | Set-MsbuildDevEnvironmentによるVC++環境変数 |
| ファイルシステム | C++/XAMLファイル | コードフォーマット適用後のソースファイル |
| 標準出力 | テキスト | テスト結果やビルド結果 |
| プロセス | 実行プロセス | Start-OpenConsole/Debug-OpenConsoleによるプロセス起動 |

### 出力ファイル仕様

コードフォーマット関数実行時、対象ソースファイルが直接上書きされる。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 既存のC++/XAMLソースファイル |
| 出力先 | src/配下の各ソースファイル |
| 文字コード | UTF-8（XAMLはBOM除去処理あり） |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
モジュールインポート時:
1. $script:OpenConsoleFallbackRoot をPSScriptRoot基準で設定
2. 各関数定義をロード
3. Export-ModuleMemberでエクスポート対象関数を公開

Find-OpenConsoleRoot:
1. git rev-parse --show-toplevel でリポジトリルートを取得
2. 失敗時はフォールバックパス($PSScriptRoot\..)を返す

Set-MsbuildDevEnvironment:
1. VSSetupモジュールをImport-LocalModuleでインポート
2. Get-VSSetupInstanceで最新VS情報取得
3. PROCESSOR_ARCHITECTUREからアーキテクチャ判定
4. Microsoft.VisualStudio.DevShell.dllをインポート
5. Enter-VsDevShellで開発環境変数を設定

Invoke-OpenConsoleTests:
1. フラグの排他チェック（AllTests/FTOnly/Test）
2. OpenConsole.exeとTAEFパスを構築
3. tests.xmlからテスト構成を読み込み
4. UIAテスト時はWinAppDriverを起動
5. テスト種別に応じてTAEF実行
6. WinAppDriver停止

Invoke-CodeFormat:
1. NuGetリストアでclang-formatパッケージ取得
2. packages.configからclang-formatパス特定
3. src/配下のC++ファイルにclang-format適用
4. IgnoreXamlでなければInvoke-XamlFormatも実行
```

### フローチャート

```mermaid
flowchart TD
    A[モジュールインポート] --> B[関数定義ロード]
    B --> C[Export-ModuleMember]
    C --> D{呼び出し関数}
    D -->|Find-OpenConsoleRoot| E[gitでルート検出]
    D -->|Set-MsbuildDevEnvironment| F[VS環境変数設定]
    D -->|Invoke-OpenConsoleTests| G[テスト実行]
    D -->|Invoke-CodeFormat| H[コードフォーマット]
    D -->|Start-OpenConsole| I[OpenConsole起動]
    E --> E1{git成功?}
    E1 -->|Yes| E2[ルートパス返却]
    E1 -->|No| E3[フォールバックパス返却]
    F --> F1[VSSetupモジュールインポート]
    F1 --> F2[VSインスタンス検出]
    F2 --> F3[DevShellモジュールインポート]
    F3 --> F4[Enter-VsDevShell実行]
    G --> G1[テスト構成読み込み]
    G1 --> G2{UIAテスト?}
    G2 -->|Yes| G3[WinAppDriver起動]
    G2 -->|No| G4[TAEF実行]
    G3 --> G4
    G4 --> G5[テスト結果出力]
    H --> H1[clang-format取得]
    H1 --> H2[C++ファイルフォーマット]
    H2 --> H3{XAML含む?}
    H3 -->|Yes| H4[XAMLフォーマット]
    H3 -->|No| H5[完了]
    H4 --> H5
```

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

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

データベース操作は行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | - |

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidCombinationOfFlags | AllTests/FTOnly/Testの複数指定 | パラメータを1つだけ指定する |
| - | UnknownArchitecture | PROCESSOR_ARCHITECTUREが未知の値 | throwで処理中断 |
| - | XamlFormatError | XAMLフォーマットチェックで差分検出 | Invoke-XamlFormatを実行する |
| - | ModuleNotFound | ローカルモジュールが見つからない場合 | PSGalleryからダウンロードを試行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

各関数はErrorActionPreference = 'Stop'を設定しており、エラー発生時は即座に処理を中断する。テスト実行時にWinAppDriverを起動した場合、エラー時にもStop-Processで確実に終了させる。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 関数ごとに異なる（フォーマットは数百ファイル） |
| 目標処理時間 | フォーマット: 数分、ビルド: 数十分、テスト: 数分〜数十分 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

コードフォーマット関数はファイルを直接上書きするため、同一ファイルに対する並行実行は避けるべきである。テスト実行時のWinAppDriverは単一インスタンスで動作する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| Verbose | モジュール検索時 | VSSetupモジュールのダウンロード・インポート状況 |
| Host出力 | 環境設定完了時 | `Dev environment variables set`（緑色） |
| Host出力 | テストエラー時 | `Invalid combination of flags` / `Invalid test type`（赤色） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| テスト失敗 | テスト結果による | 開発者 / CI/CDパイプライン |
| フォーマットチェック失敗 | 差分検出時 | CI/CDパイプライン |

## 備考

- PowerShell 7以上が必須（`#Requires -Version 7`）
- エクスポートされる関数: Set-MsbuildDevEnvironment, Invoke-OpenConsoleTests, Invoke-OpenConsoleBuild, Start-OpenConsole, Debug-OpenConsole, Invoke-CodeFormat, Invoke-XamlFormat, Test-XamlFormat, Get-Format
- Invoke-ClangFormatはバッチサイズ64ファイルずつ処理するパフォーマンス最適化が実装されている
- XAMLフォーマット時にBOM除去処理（[IO.File]::WriteAllLines）が含まれている
- テスト対象はtests.xmlで構成管理されており、unit/ft/uiaの3種別がある
- TAEFのisolatedTaefフラグにより、テストDLLと同じディレクトリのte.exeを使用するケースがある
- ソースファイル: `tools/OpenConsole.psm1`
