# 機能設計書 52-設定検証

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの設定検証機能(`+validate-config`コマンド)の設計仕様を記載する。

### 本機能の処理概要

設定検証機能は、Ghostty設定ファイルの構文を検証するCLIコマンドである。設定ファイルの誤りを事前に検出し、アプリケーション起動時のエラーを防止する。

**業務上の目的・背景**：設定ファイルの誤りはアプリケーションの起動失敗や予期しない動作を引き起こす可能性がある。本機能により、ユーザーは設定変更後にアプリケーションを再起動する前に設定の妥当性を確認でき、トラブルシューティングの効率が向上する。CIパイプラインでの設定検証にも活用できる。

**機能の利用シーン**：
- 設定ファイル編集後の構文チェック
- CI/CDパイプラインでの設定ファイル検証
- 複数環境での設定ファイルの事前検証
- 設定エラーのデバッグ

**主要な処理内容**：
1. コマンドライン引数の解析（`--config-file`オプションの処理）
2. 設定ファイルのロード（指定ファイルまたはデフォルト設定ファイル）
3. 設定のファイナライズ（finalize）による検証
4. 診断メッセージの出力（エラーがある場合）

**関連システム・外部連携**：設定ファイルシステム(`~/.config/ghostty/config`等)との連携

**権限による制御**：特になし。全ユーザーが実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI | 主機能 | コマンドライン実行による設定検証 |

## 機能種別

CLI操作 / バリデーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --config-file | 文字列 | No | 検証対象の設定ファイルパス。未指定の場合はデフォルトパスを使用 | ファイルが存在すること |

### 入力データソース

- コマンドライン引数
- 設定ファイル（指定パスまたはデフォルトパス）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 診断メッセージ | テキスト | 設定エラーの詳細情報（エラーがある場合のみ） |

### 出力先

- 標準出力（stdout）: 診断メッセージ
- 終了コード: 0（成功）または1（エラーあり）

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ Options構造体に--config-fileの値を設定
2. デフォルト設定のロード
   └─ Config.default()で初期化
3. 設定ファイルのロード
   └─ --config-fileが指定された場合: loadFile()で指定ファイルをロード
   └─ 未指定の場合: Config.load()でデフォルト設定ファイルをロード
4. 設定のファイナライズ
   └─ cfg.finalize()で設定を確定し検証
5. 診断結果の出力
   └─ _diagnostics.items()をイテレートして各診断メッセージを出力
6. 終了コードの決定
   └─ 診断メッセージがある場合: 1、ない場合: 0
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[引数解析]
    B --> C[Config.default]
    C --> D{--config-file指定?}
    D -->|Yes| E[loadFile で指定ファイルをロード]
    D -->|No| F[Config.load でデフォルトファイルをロード]
    E --> G[loadRecursiveFiles]
    G --> H[finalize]
    F --> H
    H --> I{診断メッセージあり?}
    I -->|Yes| J[診断メッセージ出力]
    J --> K[終了コード1で終了]
    I -->|No| L[終了コード0で終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-52-1 | デフォルトファイル検証 | --config-file未指定時はデフォルト設定ファイルを検証 | 常時 |
| BR-52-2 | 絶対パス変換 | 指定されたファイルパスを絶対パスに変換して処理 | --config-file指定時 |
| BR-52-3 | 再帰的ファイルロード | config-file設定で追加ファイルが参照される場合、それらも検証対象 | --config-file指定時 |

### 計算ロジック

特になし

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

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

データベース操作なし（読み取り専用のCLIコマンド）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 検証エラー | 設定ファイルに構文エラーまたは無効な値がある | 診断メッセージに従って設定を修正 |
| - | ファイル不存在 | 指定されたファイルが存在しない | ファイルパスを確認 |

### リトライ仕様

リトライなし

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

該当なし

## パフォーマンス要件

即座にレスポンスが返ること（通常1秒未満）

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

設定ファイルのパスが外部から指定されるため、パストラバーサル攻撃に注意（ただし、現実的なリスクは低い）

## 備考

- 検証成功時は何も出力せず終了コード0で終了する
- CI/CDでの使用例: `ghostty +validate-config --config-file=./config && echo "Valid"`

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | validate_config.zig | `src/cli/validate_config.zig` | Options構造体（7-21行目）でCLIオプションを定義 |

**読解のコツ**: `@"config-file"`はZigの文字列リテラルで、ハイフンを含むフィールド名を定義している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | validate_config.zig | `src/cli/validate_config.zig` | run関数（32-48行目）がエントリーポイント |

**主要処理フロー**:
1. **33-40行目**: コマンドライン引数の解析
2. **42-44行目**: 標準出力writerの準備
3. **45行目**: runInner関数の呼び出し

#### Step 3: 検証ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | validate_config.zig | `src/cli/validate_config.zig` | runInner関数（50-78行目）で検証ロジックを実装 |

**主要処理フロー**:
- **55-56行目**: デフォルト設定の初期化
- **59-66行目**: 設定ファイルのロード（パス指定有無で分岐）
- **68行目**: finalize()で設定を確定・検証
- **70-75行目**: 診断メッセージの出力と終了コード決定

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

```
ghostty +validate-config
    │
    └─ validate_config.run()
           │
           ├─ args.parse() ─ オプション解析
           │
           └─ runInner()
                  │
                  ├─ Config.default() ─ デフォルト設定初期化
                  │
                  ├─ cfg.loadFile() または Config.load()
                  │      └─ 設定ファイル読み込み
                  │
                  ├─ cfg.loadRecursiveFiles() ─ 追加ファイル読み込み
                  │
                  ├─ cfg.finalize() ─ 設定検証
                  │
                  └─ 診断メッセージ出力
```

### データフロー図

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

コマンドライン ───▶ args.parse() ───────▶ Options
引数

設定ファイル ───▶ Config.loadFile() ──▶ Config
                         │
                         ▼
                  Config.finalize()
                         │
                         ▼
                  _diagnostics ─────────▶ 診断メッセージ
                                          （stdout）
                         │
                         ▼
                  終了コード ───────────▶ 0 or 1
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| validate_config.zig | `src/cli/validate_config.zig` | ソース | メインエントリーポイント |
| Config.zig | `src/config/Config.zig` | ソース | 設定データ構造と検証ロジック |
| args.zig | `src/cli/args.zig` | ソース | コマンドライン引数解析 |
