# バッチ設計書 20-rake doc:update-index

## 概要

本ドキュメントは、mrubyプロジェクトにおけるREADME.mdのドキュメントインデックスを自動更新する`rake doc:update-index`タスクのバッチ設計書である。

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

`rake doc:update-index`は、doc/ディレクトリ配下のMarkdownファイル一覧からドキュメントインデックスを生成し、README.mdの所定のマーカー位置にインデックスを自動挿入・更新するRakeタスクである。各Markdownファイルの先頭行にあるHTMLコメント形式のsummaryタグからドキュメントの概要を抽出し、リンク付きのリスト形式で出力する。

**業務上の目的・背景**：mrubyプロジェクトのREADME.mdに含まれるドキュメントインデックスを、doc/配下のMarkdownファイルの追加・削除・変更に応じて自動的に最新の状態に維持するために必要なタスクである。手動でのインデックス管理の手間を省き、ドキュメント構成の変更がREADMEに自動的に反映される。

**バッチの実行タイミング**：開発者による手動実行。doc/配下にMarkdownファイルが追加・削除された後に実行される。

**主要な処理内容**：
1. gitのls-filesコマンドでdoc/*.mdファイル一覧を取得
2. ディレクトリの優先順序（doc/internal/、doc/guides/、doc/）でソート
3. 各ファイルの先頭行からsummaryコメント（`<!-- summary: ... -->`）を抽出
4. doc/internal/配下のファイルには「Internal Implementation / 」プレフィックスを付加
5. README.md内のマーカー（`<!-- BEGIN OF MRUBY DOCUMENT INDEX -->`〜`<!-- END OF MRUBY DOCUMENT INDEX -->`）間を更新
6. 変更がある場合のみファイルを書き込み

**前後の処理との関連**：前提として、doc/*.mdファイルがgit管理下にあること。後続処理として、更新されたREADME.mdのgitコミットが想定される。

**影響範囲**：README.mdファイルのみが更新される（マーカー間のインデックスセクションのみ）。doc/配下のファイルは読み取りのみで変更されない。

## バッチ種別

ドキュメント自動更新

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行（doc/*.mdの追加・削除後） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Ruby実行環境 | Rubyインタプリタがインストールされていること |
| Gitリポジトリ | Gitリポジトリ内で実行されること |
| README.md存在 | プロジェクトルートにREADME.mdが存在すること |
| マーカー存在 | README.md内にBEGIN/ENDマーカーが存在すること |

### 実行可否判定

README.md内にドキュメントインデックスのマーカー（`<!-- BEGIN OF MRUBY DOCUMENT INDEX -->`および`<!-- END OF MRUBY DOCUMENT INDEX -->`）が存在しない場合、「missing marker for document index in README.md」エラーが発生する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本タスクにパラメータはない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| doc/*.md | Markdown | git管理下のドキュメントファイル一覧 |
| doc/guides/*.md | Markdown | ガイドドキュメント |
| doc/internal/*.md | Markdown | 内部実装ドキュメント |
| README.md | Markdown | 更新対象のREADMEファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| README.md | Markdown | 更新されたドキュメントインデックスを含むREADME |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | README.md |
| 出力先 | プロジェクトルート |
| 文字コード | バイナリモード書き込み（mode: "wb"） |
| インデックス形式 | `- [summary](ファイルパス)` のリスト形式 |

## 処理フロー

### 処理シーケンス

```
1. ソートの優先順序を定義
   └─ rev_order = %w(doc/internal/ doc/guides/ doc/)
2. git ls-filesでdoc/*.mdファイル一覧を取得
   └─ IO.popenでgitコマンドを実行
3. ファイル一覧のソート
   └─ rev_orderに基づく逆順ソートとファイル名ソート
4. README.mdの読み込み
   └─ File.readでREADME.md全体を読み込み
5. 各ファイルからsummaryを抽出
   └─ 先頭行の<!-- summary: ... -->コメントを正規表現で抽出
   └─ doc/internal/配下は「Internal Implementation / 」を付加
6. マーカー間のインデックスを更新
   └─ BEGIN/ENDマーカー間を新しいインデックスで置換
7. 変更がある場合のみファイル書き込み
   └─ readme == readme1 でない場合のみFile.write実行
```

### フローチャート

```mermaid
flowchart TD
    A[rake doc:update-index 開始] --> B[ソート優先順序の定義]
    B --> C[git ls-files で doc/*.md 一覧取得]
    C --> D[ファイル一覧のソート]
    D --> E[README.md 読み込み]
    E --> F[各ファイルから summary 抽出]
    F --> G{summary コメントあり?}
    G -->|Yes| H[インデックス行を生成]
    G -->|No| I[スキップ]
    H --> J{doc/internal/ 配下?}
    J -->|Yes| K[Internal Implementation プレフィックス付加]
    J -->|No| L[そのまま]
    K --> M[次のファイルへ]
    L --> M
    I --> M
    M --> N{全ファイル処理完了?}
    N -->|No| F
    N -->|Yes| O{README.md マーカー存在?}
    O -->|No| P[raise エラー]
    O -->|Yes| Q[マーカー間をインデックスで置換]
    Q --> R{変更あり?}
    R -->|Yes| S[File.write で書き込み]
    R -->|No| T[書き込みスキップ]
    S --> U[完了]
    T --> U
```

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

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

本バッチはデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | マーカー不在 | README.md内にBEGIN/ENDマーカーが存在しない | README.mdにマーカーコメントを追加する |

### リトライ仕様

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

### 障害時対応

マーカー不在エラーの場合は、README.mdに以下のマーカーを追加する：
```
<!-- BEGIN OF MRUBY DOCUMENT INDEX -->

<!-- END OF MRUBY DOCUMENT INDEX -->
```

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | ファイル単位（README.md全体を一括書き換え） |
| コミットタイミング | 変更がある場合のみファイル書き込み |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | doc/配下のmdファイル数（数十件程度） |
| 目標処理時間 | 1秒以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

同時実行に対する制限は特にないが、README.mdへの同時書き込みは避けるべきである。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| なし | - | 特にログ出力は行われない |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理完了 | N/A | 手動確認 |

## 備考

- summaryコメントの形式は `<!-- summary: {概要テキスト} -->` で、ファイルの先頭行に記述する
- summaryコメントがないファイルはインデックスに含まれない
- ファイルのソート順序はdoc/internal/ > doc/guides/ > doc/ の逆順、同ディレクトリ内ではファイル名順
- doc/internal/配下のドキュメントには自動的に「Internal Implementation / 」がプレフィックスとして付加される
- README.mdの変更がない場合（インデックスが既に最新の場合）はファイル書き込みをスキップする
- ファイル書き込みはmode: "wb"（バイナリ書き込みモード）で行われる
