# バッチ設計書 40-GenerateHeaderForJson.ps1

## 概要

本ドキュメントは、OpenConsoleプロジェクトにおいてJSONファイルの内容を `constexpr std::string_view` としてC++ヘッダーファイルに埋め込むスクリプト `GenerateHeaderForJson.ps1` の設計仕様を記載する。

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

本スクリプトは、指定されたJSONファイルを読み込み、内容を圧縮（ホワイトスペース除去）した上で、C++の `constexpr std::string_view` としてヘッダーファイルに書き出す。これにより、JSONデータをコンパイル時にC++バイナリに埋め込むことが可能になる。

**業務上の目的・背景**：Windows TerminalおよびOpenConsoleプロジェクトでは、設定ファイルのスキーマ定義やデフォルト設定などのJSONデータをC++バイナリに埋め込む必要がある。ランタイムにファイルから読み込む方式ではファイル配置の依存性やI/Oのオーバーヘッドが生じるため、ビルド時にJSONをヘッダーファイルに変換してコンパイル時に組み込む方式を採用している。本スクリプトはこの変換処理を自動化する。

**バッチの実行タイミング**：ビルドプロセスの一部として自動実行される。JSONファイルの変更時に再生成が必要。

**主要な処理内容**：
1. 指定されたJSONファイルを読み込む
2. JSONをパース後、圧縮（ホワイトスペース除去）して再シリアライズする
3. C++ヘッダーファイルのテンプレートに埋め込む
4. 指定された出力パスにUTF-8で書き出す

**前後の処理との関連**：ビルドシステム（MSBuild）から呼び出される。生成されたヘッダーファイルはC++コンパイルに使用される。`CompressJson.ps1`（No.42）は類似の圧縮機能を提供するが、本スクリプトはヘッダーファイル生成まで行う点が異なる。

**影響範囲**：生成されたC++ヘッダーファイルはコンパイル時にバイナリに組み込まれ、ランタイムのJSON処理に使用される。

## バッチ種別

コード生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | ビルド時（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | ビルドプロセス / 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| PowerShellが利用可能 | スクリプト実行環境としてPowerShellが必要 |
| 入力JSONファイルが存在 | -JsonFileパラメータで指定されたファイルが存在すること |
| 出力先ディレクトリが存在 | -OutPathパラメータで指定されたパスの親ディレクトリが存在すること |

### 実行可否判定

`Resolve-Path` による入力ファイルの存在確認が暗黙的に行われる。ファイルが存在しない場合はエラーとなる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| JsonFile | string | Yes | なし | 入力JSONファイルのパス |
| OutPath | string | Yes | なし | 出力先C++ヘッダーファイルのパス |
| VariableName | string | Yes | なし | C++ヘッダーで使用するconstexpr変数名 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| -JsonFileで指定されたファイル | JSON | 埋め込み対象のJSONファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| -OutPathで指定されたファイル | C++ヘッダー（テキスト） | JSONを埋め込んだconstexpr string_viewの定義 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | -OutPathパラメータで指定 |
| 出力先 | -OutPathパラメータで指定 |
| 文字コード | UTF-8 |
| 区切り文字 | - |

出力内容の構造:
```cpp
// Copyright (c) Microsoft Corporation
// Licensed under the MIT license.

// THIS IS AN AUTO-GENERATED FILE
// Generated from {fullPath}
constexpr std::string_view {VariableName}{ R"#({compressedJson})#" };
```

## 処理フロー

### 処理シーケンス

```
1. パラメータバインディング
   └─ JsonFile, OutPath, VariableNameの3つの必須パラメータを受け取る
2. JSONファイルの完全パス解決
   └─ Resolve-Pathで絶対パスに変換
3. JSONファイルの読み込み・圧縮
   ├─ Get-Content -Rawで全文読み込み
   ├─ ConvertFrom-JsonでPSObjectにパース
   └─ ConvertTo-Json -Compress -Depth 100で圧縮再シリアライズ
4. C++ヘッダーコード生成
   ├─ Copyrightコメント
   ├─ ライセンスコメント
   ├─ 自動生成警告コメント
   ├─ 元ファイルパスコメント
   └─ constexpr std::string_view定義（Raw文字列リテラル使用）
5. ファイル出力
   └─ Out-File -Encoding utf8でOutPathに書き出し
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B[パラメータ受取]
    B --> C[Resolve-Pathで絶対パス取得]
    C --> D[JSONファイル読み込み]
    D --> E[ConvertFrom-JsonでParse]
    E --> F[ConvertTo-Json -Compressで圧縮]
    F --> G[C++ヘッダーコード生成]
    G --> H[Out-FileでUTF-8出力]
    H --> I[スクリプト終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル不在エラー | -JsonFileで指定されたファイルが存在しない | 正しいパスを指定する |
| - | JSONパースエラー | 入力ファイルが不正なJSON形式 | JSONファイルの内容を修正する |
| - | 出力先エラー | -OutPathの親ディレクトリが存在しない | 出力先ディレクトリを作成する |

### リトライ仕様

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

### 障害時対応

入力JSONファイルの内容を確認し、再実行する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ファイル |
| 目標処理時間 | 1秒以内 |
| メモリ使用量上限 | 特に定義なし |

## 排他制御

同一出力先ファイルへの同時書き込みは想定されていない。ビルドシステムが排他制御を行う前提。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| - | - | ログ出力なし（エラー時のみPowerShellエラーストリームに出力） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルドエラー | ヘッダー生成失敗時 | ビルドログ |

## 備考

- JSONの圧縮は `ConvertTo-Json -Compress -Depth 100` で行われる。Depth 100は深くネストされたJSONにも対応するため。
- C++のRaw文字列リテラル `R"#(...)#"` を使用してJSONデータを埋め込む。これによりJSON内の特殊文字（クォート等）のエスケープが不要になる。
- 出力ファイルにはMicrosoft Copyrightヘッダーが自動付与される。
- 生成されたヘッダーファイルには元のJSONファイルの完全パスがコメントとして含まれる。
- 本スクリプトは非常にシンプル（26行）であり、単一のJSONファイルの変換に特化している。
- ソースファイル: `tools/GenerateHeaderForJson.ps1`
