# 帳票設計書 10-crash-report

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの `crash-report` コマンドが出力するクラッシュレポート一覧の設計書です。

### 本帳票の処理概要

`crash-report` コマンドは、既存のクラッシュレポートファイルを一覧表示するCLIレポートです。将来的にはクラッシュレポートの閲覧・送信機能も追加予定です。

**業務上の目的・背景**：ユーザーがGhosttyのクラッシュ履歴を確認し、問題の発生状況を把握できるようにします。サポートチームへの問題報告時に、クラッシュの有無や頻度を確認する際に役立ちます。

**帳票の利用シーン**：
- クラッシュ履歴の確認
- 最近のクラッシュ発生状況の把握
- サポートへの問題報告準備
- アプリケーション安定性の確認

**主要な出力内容**：
1. クラッシュレポートファイル名
2. クラッシュ発生からの経過時間

**帳票の出力タイミング**：`ghostty +crash-report` コマンド実行時

**帳票の利用者**：エンドユーザー、サポートチーム、開発者

## 帳票種別

CLIレポート（テキスト形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | `ghostty +crash-report` | コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（stdout） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（標準出力） |
| 出力方法 | 標準出力への表示 |
| 文字コード | UTF-8 |

### 端末出力固有設定

| 項目 | 内容 |
|-----|------|
| ハイパーリンク | 無 |
| カラー出力 | 無 |
| インタラクティブ | 無 |

## 帳票レイアウト

### レイアウト概要

クラッシュレポートがある場合とない場合で出力が異なります。

#### レポートがある場合
```
┌─────────────────────────────────────┐
│  report_name_1 (X hours ago)        │
│  report_name_2 (Y days ago)         │
│  ...                                │
└─────────────────────────────────────┘
```

#### レポートがない場合（TTY時）
```
┌─────────────────────────────────────┐
│  No crash reports! [ghost emoji]    │
└─────────────────────────────────────┘
```

### ヘッダー部

ヘッダーはありません。

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | レポート名 | クラッシュレポートファイル名 | report.name | "{s}" |
| 2 | 経過時間 | クラッシュからの経過時間 | report.mtime | "({s} ago)" または "(now)" |

### フッター部

フッターはありません。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| なし | 全クラッシュレポートを出力 | - |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | 変更日時（mtime） | 降順（新しい順） |

### 改ページ条件

改ページなし（連続出力）

## データベース参照仕様

### 参照テーブル一覧

データベース参照はありません。

### データ取得元詳細

| 取得元 | 用途 | 取得方法 |
|-------|------|---------|
| crash.defaultDir | クラッシュレポートディレクトリ | プラットフォーム固有パス |
| crash_dir.iterator | レポートファイル一覧 | ディレクトリ走査 |
| report.mtime | 変更日時 | ファイルメタデータ |

### クラッシュレポートディレクトリ

プラットフォームによって異なります（crash/main.zigで定義）。

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| diff | now - report.mtime | - | ナノ秒単位 |
| since | Duration.round(ns_per_s) | 秒単位に丸め | 経過時間表示用 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[オプション解析]
    B --> C[crash.defaultDir取得]
    C --> D[クラッシュディレクトリ走査]
    D --> E{レポートあり?}
    E -->|No| F{TTY?}
    F -->|Yes| G["No crash reports! 出力"]
    F -->|No| H[何も出力しない]
    E -->|Yes| I[mtimeでソート（新しい順）]
    I --> J[各レポートを出力]
    J --> K[経過時間計算]
    K --> L[レポート名と経過時間出力]
    L --> M{次のレポート?}
    M -->|Yes| J
    M -->|No| N[バッファフラッシュ]
    G --> N
    H --> N
    N --> O[終了コード0を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| ディレクトリ取得失敗 | クラッシュディレクトリが存在しない | エラー返却 | プロセス終了 |
| 出力失敗 | stdoutへの書き込みエラー | なし（エラー返却） | プロセス終了 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 0〜数十件 |
| 目標出力時間 | 即時（1秒未満） |
| 同時出力数上限 | N/A |

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

- クラッシュレポートディレクトリへの読み取り権限が必要
- クラッシュレポートの内容は表示しない（ファイル名のみ）
- 将来のレポート閲覧・送信機能では追加のセキュリティ考慮が必要

## 備考

- クラッシュレポートの閲覧・送信機能は未実装（将来追加予定）
- レポートがない場合、非TTY出力時は何も出力しない
- Config.Durationを使用して経過時間をフォーマット

---

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

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

### 推奨読解順序

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

クラッシュレポートの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | crash_report.zig | `src/cli/crash_report.zig` | Options構造体（8-18行目） |
| 1-2 | main.zig | `src/crash/main.zig` | crash.Report構造体、defaultDir |

**読解のコツ**: Options構造体は現在空ですが、将来の拡張（レポート閲覧・送信）のために用意されています。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | crash_report.zig | `src/cli/crash_report.zig` | run関数（26-49行目）がエントリーポイント |
| 2-2 | crash_report.zig | `src/cli/crash_report.zig` | runInner関数（51-89行目）がメイン処理 |

**主要処理フロー**:
1. **27-30行目**: Arena Allocator初期化
2. **32-39行目**: オプション解析
3. **46-48行目**: runInner呼び出し
4. **56-64行目**: クラッシュディレクトリ走査
5. **66-73行目**: レポートなし時の処理
6. **75行目**: ソート処理
7. **77-86行目**: レポート出力ループ

#### Step 3: クラッシュモジュールを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | main.zig | `src/crash/main.zig` | crash.Report構造体の定義 |
| 3-2 | main.zig | `src/crash/main.zig` | defaultDir関数の実装 |

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

```
ghostty (main)
    │
    └─ Action.run (ghostty.zig:99)
           │
           └─ crash_report.run (crash_report.zig:26)
                  │
                  ├─ args.parse (オプション解析)
                  │
                  └─ runInner (crash_report.zig:51)
                         │
                         ├─ crash.defaultDir (ディレクトリ取得)
                         │
                         ├─ crash_dir.iterator (ファイル走査)
                         │
                         ├─ std.mem.sort (ソート)
                         │
                         └─ stdout.print (出力)
```

### データフロー図

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

なし ───▶ crash_report.run()
                      │
                      ▼
              crash.defaultDir()
                      │
                      ▼
              ディレクトリ走査
                      │
    ┌─────────────────┼─────────────────┐
    ▼                 ▼                 ▼
report.name      report.mtime      現在時刻
(ファイル名)      (変更日時)        (now)
    │                 │                 │
    └──────────▶ Report構築 ◀───────────┘
                      │
                      ▼
                   ソート
                      │
                      ▼
              経過時間計算
                      │
                      ▼
                  stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| crash_report.zig | `src/cli/crash_report.zig` | ソース | メイン処理 |
| ghostty.zig | `src/cli/ghostty.zig` | ソース | Actionディスパッチャー |
| args.zig | `src/cli/args.zig` | ソース | 引数解析ユーティリティ |
| main.zig | `src/crash/main.zig` | ソース | クラッシュモジュール |
| Config.zig | `src/config/Config.zig` | ソース | Duration型定義 |
