# 機能設計書 39-設定ファイル

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける設定ファイル読み込み・管理機能の設計を定義する。

### 本機能の処理概要

設定ファイル機能は、Ghosttyの動作を制御する設定値をファイルから読み込み、解析し、アプリケーションに適用する。XDGベースディレクトリ規格に準拠し、複数の設定ファイルの階層的読み込み、ランタイム再読み込み、入れ子設定ファイルをサポートする。

**業務上の目的・背景**：ユーザーがターミナルの外観や動作を永続的にカスタマイズできるようにする。テキストベースの設定ファイルにより、バージョン管理やマシン間での共有が容易になる。

**機能の利用シーン**：
- 初回起動時のデフォルト設定ファイル読み込み
- 設定ファイルの手動編集後の再読み込み
- 複数の設定ファイルを組み合わせた構成管理
- CLIオプションによる設定上書き

**主要な処理内容**：
1. デフォルト設定ファイルパスの決定
2. 設定ファイルの読み込みと解析
3. 入れ子設定ファイル（config-file）の処理
4. CLIオプションとの統合
5. 設定変更のランタイム適用

**関連システム・外部連携**：
- ファイルシステム（XDG/Application Support）
- CLIオプション
- 各種サブシステム（フォント、レンダリング、入力等）

**権限による制御**：ファイルシステムの読み取り権限に依存。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 設定はすべての画面に影響 |

## 機能種別

設定管理 / 構成管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| config-file | RepeatablePath | No | 追加設定ファイルパス | パス存在確認 |
| config-default-files | bool | No | デフォルトファイル読み込み | - |

### 設定ファイルパス（デフォルト）

**XDG（Linux/Unix）**:
- 新形式: `$XDG_CONFIG_HOME/ghostty/config.ghostty`
- レガシー: `$XDG_CONFIG_HOME/ghostty/config`
- デフォルト: `~/.config/ghostty/config.ghostty`

**macOS Application Support**:
- 新形式: `~/Library/Application Support/com.mitchellh.ghostty/config.ghostty`
- レガシー: `~/Library/Application Support/com.mitchellh.ghostty/config`

### 設定ファイル形式

```
# コメント行
key = value
key=value

# 複数行設定
font-family = "Monaco"
font-family = "Fira Code"  # フォールバック

# 入れ子設定ファイル
config-file = ?themes/dark.ghostty  # ?はオプショナル
```

### 入力データソース

- 設定ファイル（テキストファイル）
- CLIオプション
- 環境変数（一部）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Config | struct | 解析済み設定構造体 |
| DiagnosticList | struct | 警告・エラー一覧 |

### 出力先

- メモリ内Config構造体

## 処理フロー

### 処理シーケンス

```
1. デフォルトファイル読み込み（loadDefaultFiles）
   ├─ XDGパス決定
   │      ├─ legacyDefaultXdgPath（config）
   │      └─ defaultXdgPath（config.ghostty）
   ├─ ファイル存在確認（open）
   ├─ 両方存在時は警告＋両方読み込み
   └─ macOS: Application Supportも読み込み
2. 設定ファイル解析
   └─ loadOptionalFile
       ├─ ファイルオープン
       ├─ 行単位解析
       └─ Config構造体更新
3. 入れ子設定ファイル処理（loadConfigFiles）
   └─ config-file項目を順次処理
       ├─ サイクル検出
       ├─ 相対パス展開
       └─ 再帰読み込み
4. CLIオプション読み込み（loadCliArgs）
   └─ コマンドライン引数解析
       └─ Config構造体更新（優先）
5. パス展開（expandPaths）
   └─ 相対パスを絶対パスに変換
6. 設定適用
   └─ 各サブシステムに通知
```

### フローチャート

```mermaid
flowchart TD
    A[起動] --> B{config-default-files?}
    B -->|true| C[loadDefaultFiles]
    B -->|false| D[スキップ]
    C --> E[XDGパス決定]
    E --> F{レガシーファイル存在?}
    F -->|Yes| G[legacyファイル読み込み]
    F -->|No| H{新形式ファイル存在?}
    G --> H
    H -->|Yes| I[新形式ファイル読み込み]
    H -->|No| J[テンプレート作成]
    I --> K{macOS?}
    J --> K
    K -->|Yes| L[Application Support読み込み]
    K -->|No| M[loadConfigFiles]
    L --> M
    D --> M
    M --> N[config-file処理]
    N --> O{サイクル検出?}
    O -->|Yes| P[エラーログ＋スキップ]
    O -->|No| Q[再帰読み込み]
    P --> R[loadCliArgs]
    Q --> R
    R --> S[expandPaths]
    S --> T[設定適用完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-39-01 | ファイル優先順位 | レガシー → 新形式 → config-file → CLI の順で上書き | 常時 |
| BR-39-02 | サイクル検出 | config-fileの循環参照を検出・禁止 | config-file処理時 |
| BR-39-03 | オプショナルパス | ?プレフィックスでファイル不在エラー抑制 | config-file指定時 |
| BR-39-04 | テンプレート作成 | 設定ファイルが存在しない場合、テンプレートを自動作成 | 初回起動時 |
| BR-39-05 | 相対パス展開 | config-file内の相対パスは定義元ファイルからの相対 | 常時 |
| BR-39-06 | ホーム展開 | `~/`プレフィックスをホームディレクトリに展開 | パス処理時 |
| BR-39-07 | 両ファイル読み込み | レガシーと新形式が両方存在する場合、警告して両方読み込み | ファイル読み込み時 |

### 計算ロジック

特になし。

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | FileNotFound | 必須ファイルが存在しない | エラーログ出力 |
| - | FileIsEmpty | ファイルが空 | スキップ |
| - | NotAFile | パスがファイルでない | 警告ログ＋スキップ |
| - | CycleDetected | config-fileの循環参照 | エラーログ＋スキップ |
| - | ParseError | 設定値の解析失敗 | DiagnosticListに追加 |

### リトライ仕様

リトライは行わない。エラーは診断リストに追加し、処理を継続する。

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

トランザクションは使用しない。

## パフォーマンス要件

- 設定ファイル読み込み: 100ms以内
- ランタイム再読み込み: 即時反映

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

- ファイルパスはサニタイズされる
- シンボリックリンクの追跡制限なし（ユーザー責任）

## 備考

- Ghostty 1.3.0以降は`.ghostty`拡張子を推奨
- 設定変更のホットリロードをサポート
- 設定エラー時はデフォルト値にフォールバック

---

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

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

### 推奨読解順序

#### Step 1: ファイルパス決定ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | file_load.zig | `src/config/file_load.zig` | ファイルパス決定・読み込み |

**主要処理フロー**:
- **11-16行目**: defaultXdgPath（新形式パス）
- **18-25行目**: legacyDefaultXdgPath（レガシーパス）
- **27-50行目**: preferredXdgPath（優先パス決定）
- **52-87行目**: macOS Application Supportパス
- **96-121行目**: preferredDefaultFilePath（プラットフォーム別）
- **133-166行目**: open関数（ファイルオープン＋検証）

#### Step 2: Config構造体を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Config.zig | `src/config/Config.zig` | メイン設定構造体 |

**主要処理フロー**:
- **1-60行目**: import文と互換性マップ
- **166-265行目**: フォント関連設定フィールド
- **2427-2467行目**: config-file、config-default-files設定

#### Step 3: 設定ファイル読み込みフローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Config.zig | `src/config/Config.zig` | 読み込みメソッド群 |

**主要処理フロー**:
- **3974-4034行目**: loadDefaultFiles関数（デフォルトファイル読み込み）
- **4036-4059行目**: loadCliArgs関数（CLI引数読み込み）
- **4140-4311行目**: loadConfigFiles関数（入れ子設定ファイル処理）

#### Step 4: パス処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | path.zig | `src/config/path.zig` | パス型とパス展開 |

**主要処理フロー**:
- **18-63行目**: Path union型（optional/required）
- **118-220行目**: expand関数（相対パス展開）
- **341-496行目**: RepeatablePath（複数パス管理）

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

```
main
    │
    └─ Config初期化
           │
           ├─ loadDefaultFiles
           │      │
           │      ├─ file_load.legacyDefaultXdgPath
           │      ├─ file_load.defaultXdgPath
           │      ├─ loadOptionalFile
           │      │      ├─ file_load.open
           │      │      └─ パース処理
           │      │
           │      └─ [macOS] file_load.preferredAppSupportPath
           │              └─ loadOptionalFile
           │
           ├─ loadConfigFiles
           │      │
           │      ├─ サイクル検出
           │      ├─ path.expand
           │      └─ loadFile（再帰）
           │
           ├─ loadCliArgs
           │      └─ コマンドライン解析
           │
           └─ expandPaths
                  └─ 全パスを絶対パスに変換
```

### データフロー図

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

XDGパス ─────────────────▶ legacyDefaultXdgPath ─────────▶ パス文字列
                          defaultXdgPath

設定ファイル ────────────▶ loadOptionalFile ─────────────▶ Config更新
(テキスト)                     │
                          行単位解析
                               │
                          フィールド更新

config-file ─────────────▶ loadConfigFiles ─────────────▶ Config更新
                               │
                          サイクル検出
                          相対パス展開
                          再帰読み込み

CLIオプション ───────────▶ loadCliArgs ──────────────────▶ Config更新
                               │
                          引数解析
                          優先適用

相対パス ────────────────▶ expandPaths ──────────────────▶ 絶対パス
                               │
                          ホーム展開
                          ベースパス結合
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Config.zig | `src/config/Config.zig` | ソース | メイン設定構造体・読み込みロジック |
| file_load.zig | `src/config/file_load.zig` | ソース | ファイルパス決定・オープン |
| path.zig | `src/config/path.zig` | ソース | パス型・パス展開 |
| key.zig | `src/config/key.zig` | ソース | 設定キー定義 |
| formatter.zig | `src/config/formatter.zig` | ソース | 設定フォーマッター |
| ErrorList.zig | `src/config/ErrorList.zig` | ソース | エラーリスト |
| theme.zig | `src/config/theme.zig` | ソース | テーマ読み込み |
| config-template | `src/config/config-template` | テンプレート | デフォルト設定テンプレート |
| edit.zig | `src/config/edit.zig` | ソース | 設定編集 |
| CApi.zig | `src/config/CApi.zig` | ソース | C API |
