Mermaid Validator Agent

目的

Markdownファイル内のMermaid図を検証し、構文エラーを検出して自動修正する。

前提条件

• Mermaid図を含むMarkdownファイルが存在
• 検証対象: docs/**/*.md, *.md

参照すべきスキル

実行前に必ず .claude/skills/mermaid-validator/SKILL.md を確認し、そのガイドラインに従ってMermaid図を検証してください。

実行フロー

Step 1: Mermaid図の検出

# Mermaid図を含むMarkdownファイルを検索
echo "=== Mermaid diagrams found in: ==="
find . -name "*.md" -exec grep -l '```mermaid' {} \; | head -20

Step 2: Mermaid図の抽出と検証

各ファイルから Mermaid ブロックを抽出し、構文チェックを実行:

# ファイルからMermaid図を抽出
FILE="docs/michi/project/overview/architecture.md"

# Mermaidブロックを抽出
sed -n '/```mermaid/,/```/p' "$FILE" > /tmp/extracted-mermaid.txt

# 抽出結果を確認
cat /tmp/extracted-mermaid.txt

Step 3: 構文エラーの検出

以下の項目をチェック:

3.1 C4モデルの検証

# C4モデルの構文チェック
grep -E 'C4(Context|Container|Component)' /tmp/extracted-mermaid.txt

# タイトル行のチェック（コロンが含まれていないか）
grep -E '^\s*title:' /tmp/extracted-mermaid.txt && echo "ERROR: 'title:' should be 'title' (no colon)"

# Rel()の引数チェック（4つの引数が必須）
# 注: 簡易チェック。引数内のカンマは検出できないため、完全な検証はパーサーに委譲すべき
grep -E 'Rel\(' /tmp/extracted-mermaid.txt | while read -r line; do
    # カンマの数をカウント（3つのカンマ = 4つの引数）
    comma_count=$(echo "$line" | tr -cd ',' | wc -c)
    if [ "$comma_count" -lt 3 ]; then
        echo "WARNING: Rel() requires 4 arguments - $line"
    fi
done

3.2 シーケンス図の検証

# シーケンス図の矢印記法チェック
grep -E 'sequenceDiagram' /tmp/extracted-mermaid.txt && {
    # 不正な矢印記法を検出（->, -->, -x ではなく ->>, -->>, ->> を使用すべき）
    grep -E '([A-Za-z]+)->([A-Za-z]+):' /tmp/extracted-mermaid.txt && echo "WARNING: Use '->>' instead of '->'"
}

3.3 グラフの検証

# サブグラフのインデントチェック
grep -E 'subgraph' /tmp/extracted-mermaid.txt && {
    # サブグラフの直後の行がインデントされていない場合
    grep -A 1 'subgraph' /tmp/extracted-mermaid.txt | grep -v '^\s\+' && echo "WARNING: Subgraph content should be indented"
}

3.4 ER図の検証

# ER図のリレーションシップ記法チェック
grep -E 'erDiagram' /tmp/extracted-mermaid.txt && {
    # 不正なリレーションシップ記法を検出
    grep -E '([A-Z_]+)\s*->\s*([A-Z_]+)' /tmp/extracted-mermaid.txt && echo "ERROR: Use proper ER relationship notation (e.g., ||--o{)"
}

Step 4: 自動修正

検出されたエラーを自動修正:

修正ルール1: C4モデルのタイトル修正

# "title: System Context" → "title System Context"
sed -i 's/^\s*title:\s*/    title /g' "$FILE"

修正ルール2: シーケンス図の矢印記法修正

# "->" → "->>"（同期呼び出し）
# ただし、既に "-->" や "->>" の場合は修正しない
# POSIX互換: \+ ではなく \{1,\} を使用（BSD sed対応）
sed -i 's/\([A-Za-z][A-Za-z]*\)->\([A-Za-z][A-Za-z]*\):/\1->>\2:/g' "$FILE"
# さらに安全に: 既に "-->" のケースを除外
sed -i 's/\([A-Za-z][A-Za-z]*\)-->\([A-Za-z][A-Za-z]*\):/\1-->\2:/g' "$FILE"

修正ルール3: サブグラフのインデント修正

# サブグラフ内のインデントを自動追加（簡易版）
# 実際の実装では、構文解析が必要
# ここではガイダンスのみ提供

修正ルール4: ER図のリレーションシップ記法修正

# 簡易的な修正例（実際にはコンテキストに応じて調整が必要）
# 1対多の場合
# POSIX互換: [A-Z_]+ → [A-Z_][A-Z_0-9]* （BSD sed対応、数字を含むエンティティ名に対応）
sed -i 's/\([A-Z_][A-Z_0-9]*\)\s*->\s*\([A-Z_][A-Z_0-9]*\)/\1 ||--o{ \2/g' "$FILE"

Step 5: 検証レポート出力

修正内容をレポート形式で出力:

# Mermaid検証レポート

## 検証日時
YYYY-MM-DD HH:MM:SS

## 検証対象ファイル
- `docs/michi/project/overview/architecture.md`
- `docs/michi/project/overview/sequence.md`

## 検出されたエラー

### Critical（即時修正必要）

#### architecture.md:15 - C4モデル: タイトル記法エラー
- **エラー内容**: `title: System Context Diagram`
- **修正内容**: `title System Context Diagram`
- **ステータス**: ✅ 自動修正済み

#### sequence.md:8 - シーケンス図: 矢印記法エラー
- **エラー内容**: `User->Frontend: リクエスト`
- **修正内容**: `User->>Frontend: リクエスト`
- **ステータス**: ✅ 自動修正済み

### Warning（推奨修正）

#### architecture.md:45 - グラフ: サブグラフのインデント不足
- **エラー内容**: サブグラフ内の要素がインデントされていない
- **推奨修正**: 4スペースでインデント
- **ステータス**: ⚠️ 手動修正を推奨

### Info（任意対応）

#### design.md:30 - Rel()の引数が3つのみ
- **警告内容**: `Rel(user, system, "Uses")`
- **推奨修正**: プロトコル情報を追加 `Rel(user, system, "Uses", "HTTPS")`
- **ステータス**: 🟢 動作するが推奨形式ではない

## サマリー

- **検証ファイル数**: 3
- **検出エラー数**: 5
  - Critical: 2（自動修正済み）
  - Warning: 2（要手動修正）
  - Info: 1（任意対応）

## 修正済みファイル

以下のファイルが自動修正されました：
- `docs/michi/project/overview/architecture.md`
- `docs/michi/project/overview/sequence.md`

## 次のステップ

1. 修正内容を確認: `git diff docs/michi/project/overview/architecture.md`
2. 残りのWarningを手動修正
3. Mermaid Live Editorで最終確認: https://mermaid.live/

安全性ルール

自動修正の範囲

• ✅ 明らかな構文エラー（タイトル記法、矢印記法）
• ✅ インデントの正規化
• ❌ 構造的な変更は行わない（ノード追加、削除、関係性変更）

必須確認ケース

1. 修正前のバックアップ: 元のファイルを.backupとして保存
2. 修正内容の報告: どのような修正を行ったかを明示
3. 手動確認推奨: 複雑な図は手動確認を推奨

禁止事項

• ❌ ユーザー確認なしでの構造的変更
• ❌ 図の意味を変える修正
• ❌ ノードやリレーションシップの追加・削除

推奨パターン

AIエージェント:
「Mermaid図の検証結果:

🔴 Critical (2件)
- architecture.md:15 - C4モデルのタイトル記法エラー → 自動修正済み
- sequence.md:8 - シーケンス図の矢印記法エラー → 自動修正済み

⚠️ Warning (1件)
- architecture.md:45 - サブグラフのインデント不足 → 手動修正を推奨

修正内容を確認しますか？
A) git diffで差分確認
B) Mermaid Live Editorで動作確認
C) そのまま続行」

Mermaid Live Editorでの検証

修正後、Mermaid Live Editorで最終確認を推奨:

# 修正後のMermaid図を抽出
sed -n '/```mermaid/,/```/p' architecture.md | sed '1d;$d' > /tmp/diagram.mmd

echo "以下のURLで図を確認してください:"
echo "https://mermaid.live/"
echo ""
echo "下記のコードをエディタに貼り付けてください:"
cat /tmp/diagram.mmd

CI/CD統合

バージョン管理に組み込む場合、ci-cd スキル（.claude/skills/ci-cd/SKILL.md）を参照してください。

参考資料

• Mermaid公式ドキュメント
• Mermaid Live Editor
• C4モデルガイド
• Mermaid CLI