Report Compiler Agent

分析結果のMarkdownファイルを統合HTMLレポートに変換するエージェントです。

概要

このエージェントは以下の機能を提供します：

Markdownの自動検出・統合 - 各ディレクトリ内のすべてのMarkdownファイルを動的に検出し統合
設定ファイルの表示 - YAML/JSON/Properties/TOML等の設定ファイルをシンタックスハイライト付きで表示
Mermaid図のレンダリング - Mermaid図をインライン埋め込み
GraphDB可視化 - D3.jsインタラクティブグラフを埋め込み（事前に/visualize-graphで生成）
目次生成 - 自動的にサイドバー目次を生成
スタイリング - プロフェッショナルなスタイルを適用（ライト/ダークテーマ）
レスポンシブ - モバイル/印刷対応
重複除去 - ファイル名の命名規則が異なる重複ファイルを自動的に除去
HTML検証・自動修正 - 生成されたHTMLの各セクションが正しく表示されるか検証し、問題があれば修正
XSSサニタイゼーション - 危険なHTMLタグ（<script>, <img onerror>等）を自動的にエスケープしてXSS攻撃を防止

出力形式の選択

レポートは2つの形式で生成できます：

| 形式 | 推奨用途 | 利点 | 欠点 | |------|---------|------|------| | HTML | 単一ファイル配布、ローカル閲覧 | 単一ファイル、依存関係なし、検索機能あり | ページ分割なし、大きいファイル | | Nextra | Webホスティング、大規模レポート | ページ分割、高速ナビゲーション、モダンUI | Node.js必要、ビルド時間長い |

選択ガイド:

メール添付や単一ファイル配布 → HTML
Webサイトとして公開 → Nextra
100ページ以下のレポート → HTML
100ページ以上のレポート → Nextra

前提条件

HTML形式

Python 3.9+
markdown パッケージ
pymdown-extensions パッケージ
（オプション）mermaid-cli（Mermaid図の検証用）

Nextra形式

Node.js 16.x以上
npm 8.x以上
Python 3.9+（変換スクリプト用）

実行プロンプト

あなたはレポートをコンパイルする専門家エージェントです。以下の手順でレポートを生成してください。

方式A: HTML形式（単一ファイル）

Step 1: 環境確認

# 必要なパッケージの確認
source .venv/bin/activate
pip install markdown pymdown-extensions

Step 2: Mermaid図の検証（推奨）

レポート生成前にMermaid図の構文エラーをチェックします。

# mmdc がインストールされている場合
/fix-mermaid ./reports

注意: Mermaidの予約語問題

以下の単語はMermaidのsequenceDiagramで予約語として解釈されるため、participant名として使用しないでください：

| 予約語 | 代替案 | |-------|-------| | BOX | BoxAPI, BoxPlatform, BoxWebhook | | box | 同上 |

例:

# NG
participant BOX as BOX Platform

# OK
participant BoxPlatform as BOX Platform

Step 3: GraphDB可視化の準備

ナレッジグラフのインタラクティブビューアを含める場合、事前に可視化ファイルを生成します。

# GraphDBが構築済みの場合
/visualize-graph ./reports/graph

# GraphDBが未構築の場合は先に構築
/build-graph ./path/to/source
/visualize-graph ./reports/graph

生成されるファイル:

reports/graph/
├── visualizations/
│   ├── graph.html          # D3.jsインタラクティブグラフ（これが必要）
│   ├── graph-mermaid.md    # Mermaid形式
│   └── graph-dot.dot       # DOT形式
└── data/
    ├── nodes.csv
    └── edges.csv

重要: reports/graph/visualizations/graph.htmlが存在する場合、自動的にインタラクティブグラフがレポートに埋め込まれます。

Step 4: レポートコンパイルスクリプトの実行

source .venv/bin/activate && python scripts/compile_report.py \
  --input-dir ./reports \
  --output ./reports/00_summary/full-report.html \
  --title "リファクタリング分析レポート"

自動的に実行される処理:

Markdownファイルの検出・統合
Mermaid図のレンダリング
設定ファイルのシンタックスハイライト
GraphDB可視化の埋め込み
XSSサニタイゼーション - 危険なHTMLタグを自動エスケープ
HTML検証

Step 5: 出力形式

統合HTMLレポート

<!DOCTYPE html>
<html>
<head>
    <title>リファクタリング分析レポート</title>
    <script src="mermaid.min.js"></script>
    <script src="d3.v7.min.js"></script>
    <style>/* プロフェッショナルスタイル */</style>
</head>
<body>
    <nav class="sidebar"><!-- サイドバー目次 --></nav>
    <main class="main-content">
        <section id="summary"><!-- エグゼクティブサマリー --></section>
        <section id="analysis"><!-- 分析結果 --></section>
        <section id="evaluation"><!-- MMI評価 --></section>
        <section id="design"><!-- 設計書 --></section>
        <section id="stories"><!-- ドメインストーリー --></section>
        <section id="graph">
            <!-- ナレッジグラフ -->
            <!-- D3.jsインタラクティブビューア -->
        </section>
    </main>
</body>
</html>

Step 6: コマンドオプション

| オプション | 説明 | デフォルト | |-----------|------|----------| | --input-dir | 入力ディレクトリ | ./reports | | --output | 出力HTMLファイル（--format html時） | ./reports/00_summary/full-report.html | | --title | レポートタイトル | リファクタリング分析レポート | | --theme | テーマ (light/dark)（--format html時） | light | | --format | 出力形式 (html/nextra) | html | | --nextra-output | Nextraサイト出力先（--format nextra時） | ./reports/nextra-site | | --no-verify | HTML検証をスキップ（--format html時） | false（検証はデフォルト有効） |

Step 7: HTML検証と修正

レポート生成後、各セクションが正しく表示されるかを検証します。

検証項目:

セクションの存在確認 - 各セクションIDが存在するか
コンテンツの存在確認 - 各セクションに内容が含まれているか
Mermaid図のレンダリング - Mermaid図が正しく埋め込まれているか
GraphDBビューアの動作確認 - graph.htmlからデータが正しく抽出されているか
設定ファイルの表示 - YAML/JSON等がシンタックスハイライト付きで表示されるか
リンクの整合性 - 目次のリンクが正しいセクションを指しているか
XSSサニタイゼーション - 危険なHTMLタグが適切にエスケープされているか

自動修正される問題:

空のセクション → スキップまたは「コンテンツなし」表示
破損したMermaidブロック → エラーメッセージを表示
不正なJSON → パース失敗時はそのまま表示

検証の実行:

# スクリプト実行時に自動で検証（デフォルト）
python scripts/compile_report.py --input-dir ./reports --output ./reports/00_summary/full-report.html

# 検証をスキップ
python scripts/compile_report.py --input-dir ./reports --output ./reports/00_summary/full-report.html --no-verify

検証結果の出力例:

=== HTML Verification ===
✓ Section 'summary' - 2 articles
✓ Section 'analysis' - 5 articles
✓ Section 'evaluation' - 9 articles
✓ Section 'design' - 12 articles (3 config files)
✓ Section 'graph' - 2 articles + interactive viewer
⚠ Section 'stories' - Empty (no content found)
✓ Mermaid diagrams: 15 found
✓ Navigation links: 31 valid

=== Verification Complete ===
Warnings: 1
Errors: 0

方式B: Nextra形式（静的サイト）

Nextra形式は、Next.js + Nextra 2.xを使用した静的サイト生成です。

概要

出力: 44ページの静的サイト（23MB、out/ディレクトリ）
ビルド時間: 約30-40秒
特徴: ページ分割、高速ナビゲーション、検索機能、レスポンシブUI

Step 1: 環境確認

# Node.jsバージョン確認
node --version  # 16.x以上

# Python環境
source .venv/bin/activate

Step 2: Markdownから.mdxへの変換

python scripts/convert_to_nextra.py \
  --input ./reports \
  --output ./reports/nextra-site

自動実行される処理:

Markdownファイルの検出
MDXエスケープ処理 - JSX構文と衝突するパターンを自動エスケープ
_meta.jsonの生成（ナビゲーション構造）
.mdxファイルの出力

MDXエスケープルール（自動適用）:

| パターン | 変換 | 理由 | |---------|------|------| | Array<String> | Array<String> | JSX汎用型syntax | | <500ms | <500ms | JSX開始タグとして解釈される | | {id}, {token} | \{id\}, \{token\} | JSX式として解釈される | | test<>.txt | test<>.txt | 空フラグメント | | <img src=x> | <img src=x> | XSSテスト用HTMLタグ |

注意: コードブロック内（...）はエスケープされません。

Step 3: npm依存関係のインストール

cd reports/nextra-site
npm install

初回のみ実行。依存関係:

next ^13.5.0
nextra ^2.13.4
nextra-theme-docs ^2.13.4
react, react-dom

Step 4: ビルド実行

cd reports/nextra-site
npx next build

出力: out/ ディレクトリに静的サイトが生成されます。

Step 5: プレビュー

# ローカルサーバーで確認（開発モード）
cd reports/nextra-site
npx next dev

# ブラウザで開く
open http://localhost:3000

# 本番ビルド後のプレビュー
npx serve out/

Step 6: 出力構造

reports/nextra-site/
├── pages/                  # MDXソースファイル
│   ├── index.mdx          # トップページ
│   ├── _meta.json         # ナビゲーション定義
│   ├── 00_summary/        # エグゼクティブサマリー（3ページ）
│   ├── 01_analysis/       # システム分析（4ページ）
│   ├── 02_evaluation/     # 品質評価（8ページ）
│   ├── 03_design/         # アーキテクチャ設計（9ページ）
│   ├── 04_stories/        # ドメインストーリー（1ページ）
│   ├── 06_implementation/ # 実装仕様（2ページ）
│   ├── 07_test-specs/     # テスト仕様（11ページ）
│   └── graph/             # ナレッジグラフ（3ページ）
├── out/                   # 静的サイト（next build後）
│   ├── index.html
│   ├── _next/            # JSバンドル
│   ├── 00_summary/
│   ├── 01_analysis/
│   └── ...
├── package.json
├── next.config.js
└── theme.config.tsx

Nextra提供機能

ビルトイン機能

検索機能: サイドバー検索（全ページ対象）
ナビゲーション: サイドバー + パンくず + 前/次ページ移動
テーマ切り替え: ライト/ダークモード
レスポンシブ: モバイル対応（ハンバーガーメニュー）
シンタックスハイライト: コードブロック
コピーボタン: コードブロックに自動追加

Mermaid図の表示

Nextra 2.xはMermaidをネイティブサポートしていないため、カスタムコンポーネントが必要です：

import Mermaid from '@/components/Mermaid'

<Mermaid chart={`
graph TD
  A[Start] --> B[End]
`} />

TODO: Mermaidコンポーネントの実装（次のステップ）

GraphDB可視化の表示

同様にカスタムコンポーネントが必要です：

import GraphViewer from '@/components/GraphViewer'

<GraphViewer dataPath="/data/graph.json" />

TODO: GraphViewerコンポーネントの実装（次のステップ）

トラブルシューティング

MDXパースエラー

エラー例:

Expected a closing tag for `<String>`

原因: MDXは<>や{}をJSX構文として解釈します。

対応: convert_to_nextra.pyが自動エスケープします。エラーが出る場合:

最新の変換スクリプトを使用しているか確認

手動でエスケープ:

# 問題箇所を特定
npx next build  # エラーメッセージでファイル名と行番号を確認

# 該当MDXファイルを編集
# Array<String> → Array&lt;String&gt;
# {id} → \{id\}

ビルド時間が長い

対応:

キャッシュ削除: rm -rf .next/
増分ビルド: npx next build は変更ファイルのみ再ビルド

npm installエラー

エラー: ERESOLVE unable to resolve dependency tree

対応:

# 強制インストール
npm install --legacy-peer-deps

# またはpackage-lock.jsonを削除
rm package-lock.json
npm install

HTML vs Nextra 比較表

| 観点 | HTML | Nextra | |------|------|--------| | ファイルサイズ | 1.3MB（単一） | 23MB（ディレクトリ） | | ビルド時間 | ~10秒 | ~35秒 | | ページ分割 | ❌ 単一ファイル | ✅ 44ページ | | 検索機能 | ✅ Lunr.js | ✅ ビルトイン | | ナビゲーション | サイドバーのみ | パンくず + 前/次移動 | | モバイル対応 | ⚠️ 重い | ✅ 最適化済み | | 配布方法 | 単一ファイル添付 | ディレクトリまたはホスティング | | 依存関係 | Python | Node.js + npm | | カスタマイズ | CSSのみ | Reactコンポーネント |

詳細調査レポート

Nextra移行の技術詳細、MDXパターン問題の完全な分析、既知の制限については以下を参照:

📖 docs/nextra-investigation.md - Nextra移行調査レポート

機能詳細

Markdownファイルの自動検出

スクリプトは各レポートディレクトリ（00_summary, 01_analysis, 02_evaluation, など）から自動的にすべてのMarkdownファイルを検出します。

動作:

優先ファイルリストに従って順序を決定
ディレクトリ内の他のMarkdownファイルを自動検出
重複ファイルを自動除去
サブディレクトリ（visualizations/など）も検索対象

対応するファイル構造:

reports/
├── 00_summary/          # エグゼクティブサマリー
├── 01_analysis/         # システム分析（全ファイル自動検出）
├── 02_evaluation/       # MMI評価
├── 03_design/           # 設計（API、ScalarDB含む全ファイル）
│   └── api-specifications/  # OpenAPI/AsyncAPI仕様（YAML/JSON）
├── 04_stories/          # ドメインストーリー（個別ストーリー含む）
├── 05_estimate/         # コスト試算
└── graph/               # ナレッジグラフ（サブディレクトリ含む）

設定ファイルの表示

Markdown以外の設定ファイルも自動的に検出し、シンタックスハイライト付きで表示します。

対応するファイル形式:

| 拡張子 | 形式 | 表示方法 | |-------|------|---------| | .yaml, .yml | YAML | コードブロック（yaml） | | .json | JSON | フォーマット済みコードブロック（json） | | .properties | Properties | コードブロック（properties） | | .toml | TOML | コードブロック（toml） | | .xml | XML | コードブロック（xml） | | .env, .env.example | 環境変数 | コードブロック（bash） | | .feature | Gherkin | コードブロック（gherkin） | | .graphql, .gql | GraphQL | コードブロック（graphql） | | .proto | Protocol Buffers | コードブロック（protobuf） | | .tf, .hcl | Terraform/HCL | コードブロック（hcl） |

例: OpenAPI仕様の表示

reports/03_design/api-specifications/openapi.yamlが存在する場合：

<h2>Openapi</h2>
<pre><code class="language-yaml">
openapi: 3.0.0
info:
  title: Order Service API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders
      ...
</code></pre>

自動検出されるディレクトリ:

api-specifications/ - API仕様書（OpenAPI, AsyncAPI, GraphQL, gRPC）
config/ - 設定ファイル
k8s/ - Kubernetesマニフェスト
schemas/ - スキーマ定義（JSON Schema, Protocol Buffers等）
bdd-scenarios/ - BDDシナリオ（Gherkin .featureファイル）
visualizations/ - 可視化ファイル

GraphDB可視化の統合

reports/graph/visualizations/graph.htmlが存在する場合、自動的にインタラクティブグラフをレポートに埋め込みます。

機能:

ノードのドラッグ移動
マウスホイールでズーム
ノードホバーで詳細表示（名前、タイプ、グループ）
ノード検索
凡例表示（Domain/Entity/Term）

前提:

/build-graph でGraphDBが構築済み
/visualize-graph で可視化ファイルが生成済み

Mermaid図のレンダリング

Markdownファイル内のmermaidブロックを自動的に<div class="mermaid">に変換し、Mermaid.jsでレンダリングします。

対応図:

flowchart / graph
sequenceDiagram
classDiagram
stateDiagram
erDiagram
gantt
xychart-beta

非対応:

radarChart（xychart-betaで代替）

XSSサニタイゼーション

セキュリティテストケース等で危険なHTMLタグが含まれるMarkdownファイルを処理する際、自動的にXSS対策を行います。

エスケープ対象のタグ:

<script>...</script> - JavaScriptコード実行
<img onerror="..."> - エラーハンドラによるコード実行
<iframe>...</iframe> - 外部コンテンツ埋め込み
<embed> - 外部リソース埋め込み
<object>...</object> - 外部オブジェクト埋め込み

処理例:

入力（Markdownテーブル内）:

| File name with script | "<script>alert('XSS')</script>.pdf" | Rejected by validation |

出力（HTMLテーブル内）:

<td>"&lt;script&gt;alert('XSS')&lt;/script&gt;.pdf"</td>

動作:

MarkdownをHTMLに変換
危険なHTMLタグを検出（正規表現）
html.escape()でHTMLエンティティに変換
安全なHTMLとして出力

注意事項:

Mermaid図内の<div class="mermaid">、コードブロック内の<code>等、正当なHTMLタグはエスケープされません
セキュリティテストケースの内容が安全にテキストとして表示されます
ブラウザでXSSエラーが発生することなくHTMLを開けます

出力ファイル

reports/
└── 00_summary/
    └── full-report.html   # 統合HTMLレポート (約450KB)

使用例

例1: HTML形式で基本コンパイル

# コマンド形式
/compile-report

# または直接実行
source .venv/bin/activate && python scripts/compile_report.py \
  --input-dir ./reports \
  --output ./reports/00_summary/full-report.html

例2: Nextra形式で静的サイト生成

# Step 1: 変換
python scripts/convert_to_nextra.py --input ./reports --output ./reports/nextra-site

# Step 2: ビルド
cd reports/nextra-site
npm install  # 初回のみ
npx next build

# Step 3: 確認
npx serve out/

例3: HTMLをカスタムタイトルとダークテーマで生成

source .venv/bin/activate && python scripts/compile_report.py \
  --input-dir ./reports \
  --output ./reports/00_summary/full-report.html \
  --title "My Project Report" \
  --theme dark

例4: ブラウザで開く

# HTML
open reports/00_summary/full-report.html

# Nextra（ローカル開発サーバー）
cd reports/nextra-site && npx next dev
# → http://localhost:3000 を開く

# Nextra（ビルド済みサイト）
cd reports/nextra-site && npx serve out/
# → http://localhost:3000 を開く

トラブルシューティング

Mermaid図が表示されない

ブラウザのコンソールでエラーを確認
/fix-mermaidで構文エラーをチェック
予約語（BOX等）を使用していないか確認

GraphDBビューアが表示されない

reports/graph/visualizations/graph.htmlの存在を確認
/visualize-graphを実行してファイルを生成

日本語が文字化けする

HTMLファイルがUTF-8で保存されているか確認
ブラウザのエンコーディング設定を確認

XSSエラーが表示される

HTMLを開いた際にXSSエラーが表示される場合：

原因: セキュリティテストケース等に含まれる<script>タグがエスケープされていない
対応: スクリプトが最新版（XSSサニタイゼーション対応）であることを確認

確認方法:

# sanitize_html_content関数が存在するか確認
grep -n "def sanitize_html_content" scripts/compile_report.py

修正後: レポートを再コンパイル

source .venv/bin/activate && python scripts/compile_report.py \
  --input-dir ./reports \
  --output ./reports/00_summary/full-report.html

Report Compiler Agent

分析結果のMarkdownファイルを統合HTMLレポートに変換するエージェントです。

概要

このエージェントは以下の機能を提供します：

Markdownの自動検出・統合 - 各ディレクトリ内のすべてのMarkdownファイルを動的に検出し統合
設定ファイルの表示 - YAML/JSON/Properties/TOML等の設定ファイルをシンタックスハイライト付きで表示
Mermaid図のレンダリング - Mermaid図をインライン埋め込み
GraphDB可視化 - D3.jsインタラクティブグラフを埋め込み（事前に/visualize-graphで生成）
目次生成 - 自動的にサイドバー目次を生成
スタイリング - プロフェッショナルなスタイルを適用（ライト/ダークテーマ）
レスポンシブ - モバイル/印刷対応
重複除去 - ファイル名の命名規則が異なる重複ファイルを自動的に除去
HTML検証・自動修正 - 生成されたHTMLの各セクションが正しく表示されるか検証し、問題があれば修正
XSSサニタイゼーション - 危険なHTMLタグ（<script>, <img onerror>等）を自動的にエスケープしてXSS攻撃を防止

出力形式の選択

レポートは2つの形式で生成できます：

選択ガイド:

メール添付や単一ファイル配布 → HTML
Webサイトとして公開 → Nextra
100ページ以下のレポート → HTML
100ページ以上のレポート → Nextra

前提条件

HTML形式

Python 3.9+
markdown パッケージ
pymdown-extensions パッケージ
（オプション）mermaid-cli（Mermaid図の検証用）

Nextra形式

Node.js 16.x以上
npm 8.x以上
Python 3.9+（変換スクリプト用）

実行プロンプト

あなたはレポートをコンパイルする専門家エージェントです。以下の手順でレポートを生成してください。

方式A: HTML形式（単一ファイル）

Step 1: 環境確認

# 必要なパッケージの確認
source .venv/bin/activate
pip install markdown pymdown-extensions

Step 2: Mermaid図の検証（推奨）

レポート生成前にMermaid図の構文エラーをチェックします。

# mmdc がインストールされている場合
/fix-mermaid ./reports

注意: Mermaidの予約語問題

以下の単語はMermaidのsequenceDiagramで予約語として解釈されるため、participant名として使用しないでください：

| 予約語 | 代替案 | |-------|-------| | BOX | BoxAPI, BoxPlatform, BoxWebhook | | box | 同上 |

例:

# NG
participant BOX as BOX Platform

# OK
participant BoxPlatform as BOX Platform

Step 3: GraphDB可視化の準備

ナレッジグラフのインタラクティブビューアを含める場合、事前に可視化ファイルを生成します。

# GraphDBが構築済みの場合
/visualize-graph ./reports/graph

# GraphDBが未構築の場合は先に構築
/build-graph ./path/to/source
/visualize-graph ./reports/graph

生成されるファイル:

reports/graph/
├── visualizations/
│   ├── graph.html          # D3.jsインタラクティブグラフ（これが必要）
│   ├── graph-mermaid.md    # Mermaid形式
│   └── graph-dot.dot       # DOT形式
└── data/
    ├── nodes.csv
    └── edges.csv

重要: reports/graph/visualizations/graph.htmlが存在する場合、自動的にインタラクティブグラフがレポートに埋め込まれます。

Step 4: レポートコンパイルスクリプトの実行

source .venv/bin/activate && python scripts/compile_report.py \
  --input-dir ./reports \
  --output ./reports/00_summary/full-report.html \
  --title "リファクタリング分析レポート"

自動的に実行される処理:

Markdownファイルの検出・統合
Mermaid図のレンダリング
設定ファイルのシンタックスハイライト
GraphDB可視化の埋め込み
XSSサニタイゼーション - 危険なHTMLタグを自動エスケープ
HTML検証

Step 5: 出力形式

統合HTMLレポート

<!DOCTYPE html>
<html>
<head>
    <title>リファクタリング分析レポート</title>
    <script src="mermaid.min.js"></script>
    <script src="d3.v7.min.js"></script>
    <style>/* プロフェッショナルスタイル */</style>
</head>
<body>
    <nav class="sidebar"><!-- サイドバー目次 --></nav>
    <main class="main-content">
        <section id="summary"><!-- エグゼクティブサマリー --></section>
        <section id="analysis"><!-- 分析結果 --></section>
        <section id="evaluation"><!-- MMI評価 --></section>
        <section id="design"><!-- 設計書 --></section>
        <section id="stories"><!-- ドメインストーリー --></section>
        <section id="graph">
            <!-- ナレッジグラフ -->
            <!-- D3.jsインタラクティブビューア -->
        </section>
    </main>
</body>
</html>

Step 6: コマンドオプション

Step 7: HTML検証と修正

レポート生成後、各セクションが正しく表示されるかを検証します。

検証項目:

セクションの存在確認 - 各セクションIDが存在するか
コンテンツの存在確認 - 各セクションに内容が含まれているか
Mermaid図のレンダリング - Mermaid図が正しく埋め込まれているか
GraphDBビューアの動作確認 - graph.htmlからデータが正しく抽出されているか
設定ファイルの表示 - YAML/JSON等がシンタックスハイライト付きで表示されるか
リンクの整合性 - 目次のリンクが正しいセクションを指しているか
XSSサニタイゼーション - 危険なHTMLタグが適切にエスケープされているか

自動修正される問題:

空のセクション → スキップまたは「コンテンツなし」表示
破損したMermaidブロック → エラーメッセージを表示
不正なJSON → パース失敗時はそのまま表示

検証の実行:

# スクリプト実行時に自動で検証（デフォルト）
python scripts/compile_report.py --input-dir ./reports --output ./reports/00_summary/full-report.html

# 検証をスキップ
python scripts/compile_report.py --input-dir ./reports --output ./reports/00_summary/full-report.html --no-verify

検証結果の出力例:

=== HTML Verification ===
✓ Section 'summary' - 2 articles
✓ Section 'analysis' - 5 articles
✓ Section 'evaluation' - 9 articles
✓ Section 'design' - 12 articles (3 config files)
✓ Section 'graph' - 2 articles + interactive viewer
⚠ Section 'stories' - Empty (no content found)
✓ Mermaid diagrams: 15 found
✓ Navigation links: 31 valid

=== Verification Complete ===
Warnings: 1
Errors: 0

方式B: Nextra形式（静的サイト）

Nextra形式は、Next.js + Nextra 2.xを使用した静的サイト生成です。

概要

出力: 44ページの静的サイト（23MB、out/ディレクトリ）
ビルド時間: 約30-40秒
特徴: ページ分割、高速ナビゲーション、検索機能、レスポンシブUI

Step 1: 環境確認

# Node.jsバージョン確認
node --version  # 16.x以上

# Python環境
source .venv/bin/activate

Step 2: Markdownから.mdxへの変換

python scripts/convert_to_nextra.py \
  --input ./reports \
  --output ./reports/nextra-site

自動実行される処理:

Markdownファイルの検出
MDXエスケープ処理 - JSX構文と衝突するパターンを自動エスケープ
_meta.jsonの生成（ナビゲーション構造）
.mdxファイルの出力

MDXエスケープルール（自動適用）:

注意: コードブロック内（...）はエスケープされません。

Step 3: npm依存関係のインストール

cd reports/nextra-site
npm install

初回のみ実行。依存関係:

next ^13.5.0
nextra ^2.13.4
nextra-theme-docs ^2.13.4
react, react-dom

Step 4: ビルド実行

cd reports/nextra-site
npx next build

出力: out/ ディレクトリに静的サイトが生成されます。

Step 5: プレビュー

# ローカルサーバーで確認（開発モード）
cd reports/nextra-site
npx next dev

# ブラウザで開く
open http://localhost:3000

# 本番ビルド後のプレビュー
npx serve out/

Step 6: 出力構造

reports/nextra-site/
├── pages/                  # MDXソースファイル
│   ├── index.mdx          # トップページ
│   ├── _meta.json         # ナビゲーション定義
│   ├── 00_summary/        # エグゼクティブサマリー（3ページ）
│   ├── 01_analysis/       # システム分析（4ページ）
│   ├── 02_evaluation/     # 品質評価（8ページ）
│   ├── 03_design/         # アーキテクチャ設計（9ページ）
│   ├── 04_stories/        # ドメインストーリー（1ページ）
│   ├── 06_implementation/ # 実装仕様（2ページ）
│   ├── 07_test-specs/     # テスト仕様（11ページ）
│   └── graph/             # ナレッジグラフ（3ページ）
├── out/                   # 静的サイト（next build後）
│   ├── index.html
│   ├── _next/            # JSバンドル
│   ├── 00_summary/
│   ├── 01_analysis/
│   └── ...
├── package.json
├── next.config.js
└── theme.config.tsx

Nextra提供機能

ビルトイン機能

検索機能: サイドバー検索（全ページ対象）
ナビゲーション: サイドバー + パンくず + 前/次ページ移動
テーマ切り替え: ライト/ダークモード
レスポンシブ: モバイル対応（ハンバーガーメニュー）
シンタックスハイライト: コードブロック
コピーボタン: コードブロックに自動追加

Mermaid図の表示

Nextra 2.xはMermaidをネイティブサポートしていないため、カスタムコンポーネントが必要です：

import Mermaid from '@/components/Mermaid'

<Mermaid chart={`
graph TD
  A[Start] --> B[End]
`} />

TODO: Mermaidコンポーネントの実装（次のステップ）

GraphDB可視化の表示

同様にカスタムコンポーネントが必要です：

import GraphViewer from '@/components/GraphViewer'

<GraphViewer dataPath="/data/graph.json" />

TODO: GraphViewerコンポーネントの実装（次のステップ）

トラブルシューティング

MDXパースエラー

エラー例:

Expected a closing tag for `<String>`

原因: MDXは<>や{}をJSX構文として解釈します。

対応: convert_to_nextra.pyが自動エスケープします。エラーが出る場合:

最新の変換スクリプトを使用しているか確認

手動でエスケープ:

# 問題箇所を特定
npx next build  # エラーメッセージでファイル名と行番号を確認

# 該当MDXファイルを編集
# Array<String> → Array&lt;String&gt;
# {id} → \{id\}

ビルド時間が長い

対応:

キャッシュ削除: rm -rf .next/
増分ビルド: npx next build は変更ファイルのみ再ビルド

npm installエラー

エラー: ERESOLVE unable to resolve dependency tree

対応:

# 強制インストール
npm install --legacy-peer-deps

# またはpackage-lock.jsonを削除
rm package-lock.json
npm install

HTML vs Nextra 比較表

詳細調査レポート

Nextra移行の技術詳細、MDXパターン問題の完全な分析、既知の制限については以下を参照:

📖 docs/nextra-investigation.md - Nextra移行調査レポート

機能詳細

Markdownファイルの自動検出

スクリプトは各レポートディレクトリ（00_summary, 01_analysis, 02_evaluation, など）から自動的にすべてのMarkdownファイルを検出します。

動作:

優先ファイルリストに従って順序を決定
ディレクトリ内の他のMarkdownファイルを自動検出
重複ファイルを自動除去
サブディレクトリ（visualizations/など）も検索対象

対応するファイル構造:

reports/
├── 00_summary/          # エグゼクティブサマリー
├── 01_analysis/         # システム分析（全ファイル自動検出）
├── 02_evaluation/       # MMI評価
├── 03_design/           # 設計（API、ScalarDB含む全ファイル）
│   └── api-specifications/  # OpenAPI/AsyncAPI仕様（YAML/JSON）
├── 04_stories/          # ドメインストーリー（個別ストーリー含む）
├── 05_estimate/         # コスト試算
└── graph/               # ナレッジグラフ（サブディレクトリ含む）

設定ファイルの表示

Markdown以外の設定ファイルも自動的に検出し、シンタックスハイライト付きで表示します。

対応するファイル形式:

例: OpenAPI仕様の表示

reports/03_design/api-specifications/openapi.yamlが存在する場合：

<h2>Openapi</h2>
<pre><code class="language-yaml">
openapi: 3.0.0
info:
  title: Order Service API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders
      ...
</code></pre>

自動検出されるディレクトリ:

api-specifications/ - API仕様書（OpenAPI, AsyncAPI, GraphQL, gRPC）
config/ - 設定ファイル
k8s/ - Kubernetesマニフェスト
schemas/ - スキーマ定義（JSON Schema, Protocol Buffers等）
bdd-scenarios/ - BDDシナリオ（Gherkin .featureファイル）
visualizations/ - 可視化ファイル

GraphDB可視化の統合

reports/graph/visualizations/graph.htmlが存在する場合、自動的にインタラクティブグラフをレポートに埋め込みます。

機能:

ノードのドラッグ移動
マウスホイールでズーム
ノードホバーで詳細表示（名前、タイプ、グループ）
ノード検索
凡例表示（Domain/Entity/Term）

前提:

/build-graph でGraphDBが構築済み
/visualize-graph で可視化ファイルが生成済み

Mermaid図のレンダリング

Markdownファイル内のmermaidブロックを自動的に<div class="mermaid">に変換し、Mermaid.jsでレンダリングします。

対応図:

flowchart / graph
sequenceDiagram
classDiagram
stateDiagram
erDiagram
gantt
xychart-beta

非対応:

radarChart（xychart-betaで代替）

XSSサニタイゼーション

セキュリティテストケース等で危険なHTMLタグが含まれるMarkdownファイルを処理する際、自動的にXSS対策を行います。

エスケープ対象のタグ:

<script>...</script> - JavaScriptコード実行
<img onerror="..."> - エラーハンドラによるコード実行
<iframe>...</iframe> - 外部コンテンツ埋め込み
<embed> - 外部リソース埋め込み
<object>...</object> - 外部オブジェクト埋め込み

処理例:

入力（Markdownテーブル内）:

| File name with script | "<script>alert('XSS')</script>.pdf" | Rejected by validation |

出力（HTMLテーブル内）:

<td>"&lt;script&gt;alert('XSS')&lt;/script&gt;.pdf"</td>

動作:

MarkdownをHTMLに変換
危険なHTMLタグを検出（正規表現）
html.escape()でHTMLエンティティに変換
安全なHTMLとして出力

注意事項:

Mermaid図内の<div class="mermaid">、コードブロック内の<code>等、正当なHTMLタグはエスケープされません
セキュリティテストケースの内容が安全にテキストとして表示されます
ブラウザでXSSエラーが発生することなくHTMLを開けます

出力ファイル

reports/
└── 00_summary/
    └── full-report.html   # 統合HTMLレポート (約450KB)

使用例

例1: HTML形式で基本コンパイル

# コマンド形式
/compile-report

# または直接実行
source .venv/bin/activate && python scripts/compile_report.py \
  --input-dir ./reports \
  --output ./reports/00_summary/full-report.html

例2: Nextra形式で静的サイト生成

# Step 1: 変換
python scripts/convert_to_nextra.py --input ./reports --output ./reports/nextra-site

# Step 2: ビルド
cd reports/nextra-site
npm install  # 初回のみ
npx next build

# Step 3: 確認
npx serve out/

例3: HTMLをカスタムタイトルとダークテーマで生成

source .venv/bin/activate && python scripts/compile_report.py \
  --input-dir ./reports \
  --output ./reports/00_summary/full-report.html \
  --title "My Project Report" \
  --theme dark

例4: ブラウザで開く

# HTML
open reports/00_summary/full-report.html

# Nextra（ローカル開発サーバー）
cd reports/nextra-site && npx next dev
# → http://localhost:3000 を開く

# Nextra（ビルド済みサイト）
cd reports/nextra-site && npx serve out/
# → http://localhost:3000 を開く

トラブルシューティング

Mermaid図が表示されない

ブラウザのコンソールでエラーを確認
/fix-mermaidで構文エラーをチェック
予約語（BOX等）を使用していないか確認

GraphDBビューアが表示されない

reports/graph/visualizations/graph.htmlの存在を確認
/visualize-graphを実行してファイルを生成

日本語が文字化けする

HTMLファイルがUTF-8で保存されているか確認
ブラウザのエンコーディング設定を確認

XSSエラーが表示される

HTMLを開いた際にXSSエラーが表示される場合：

原因: セキュリティテストケース等に含まれる<script>タグがエスケープされていない
対応: スクリプトが最新版（XSSサニタイゼーション対応）であることを確認

確認方法:

# sanitize_html_content関数が存在するか確認
grep -n "def sanitize_html_content" scripts/compile_report.py

修正後: レポートを再コンパイル

source .venv/bin/activate && python scripts/compile_report.py \
  --input-dir ./reports \
  --output ./reports/00_summary/full-report.html

Adoption

wfukatsu/compile-report

$ install --global

Security Scan Results

SKILL.md

Report Compiler Agent

概要

出力形式の選択

前提条件

HTML形式

Nextra形式

実行プロンプト

方式A: HTML形式（単一ファイル）

Step 1: 環境確認

Step 2: Mermaid図の検証（推奨）

Step 3: GraphDB可視化の準備

Step 4: レポートコンパイルスクリプトの実行

Step 5: 出力形式

統合HTMLレポート

Step 6: コマンドオプション

Step 7: HTML検証と修正

方式B: Nextra形式（静的サイト）

概要

Step 1: 環境確認

Step 2: Markdownから.mdxへの変換

Step 3: npm依存関係のインストール

Step 4: ビルド実行

Step 5: プレビュー

Step 6: 出力構造

Nextra提供機能

ビルトイン機能

Mermaid図の表示

GraphDB可視化の表示

トラブルシューティング

MDXパースエラー

ビルド時間が長い

npm installエラー

HTML vs Nextra 比較表

詳細調査レポート

機能詳細

Markdownファイルの自動検出

設定ファイルの表示

GraphDB可視化の統合

Mermaid図のレンダリング

XSSサニタイゼーション

出力ファイル

使用例

例1: HTML形式で基本コンパイル

例2: Nextra形式で静的サイト生成

例3: HTMLをカスタムタイトルとダークテーマで生成

例4: ブラウザで開く

トラブルシューティング

Mermaid図が表示されない

GraphDBビューアが表示されない

日本語が文字化けする

XSSエラーが表示される

関連スキル

Related Skills

wfukatsu/workflow

wfukatsu/visualize-graph

wfukatsu/system-investigation

wfukatsu/select-scalardb-edition

wfukatsu/compile-report

$ install --global

Security Scan Results

SKILL.md

Report Compiler Agent

概要

出力形式の選択

前提条件

HTML形式

Nextra形式

実行プロンプト

方式A: HTML形式（単一ファイル）

Step 1: 環境確認

Step 2: Mermaid図の検証（推奨）

Step 3: GraphDB可視化の準備

Step 4: レポートコンパイルスクリプトの実行

Step 5: 出力形式

統合HTMLレポート