プロジェクト名: JSVisualizer
バージョン: 0.1 (ドラフト)
作成日: 2026-05-25
作成者: Tetsuo Tanaka
- インクリメンタル開発: 各フェーズで動作するものを完成させてから次に進む
- コアファースト: 可視化の多様性より先に、コア基盤（アダプター・ステップ制御）の安定性を確保する
- 教育効果優先: 実装コストではなく学習者への効果を優先して可視化ビューの順番を決める
- テストドリブン: コア層（
core/以下）はユニットテストを書きながら開発する
| 項目 | 選択 | 理由 |
|---|---|---|
| 言語 | Vanilla JS (ES2022+) | 依存ゼロ、JSInterpreter と一貫性 |
| ビルド | esbuild | JSInterpreter と同方式、高速 |
| テスト | Jest | JSInterpreter と同方式 |
| 可視化 | DOM + CSS + SVG | 外部ライブラリ不要、軽量 |
| スタイル | CSS カスタムプロパティ | テーマ管理が容易 |
| フェーズ | 名称 | 期間目安 | 主な成果物 |
|---|---|---|---|
| Phase 1 | 基盤構築 | 2 週間 | ビルド環境・コアモジュール・骨格 UI |
| Phase 2 | テキスト系可視化 | 3 週間 | V-01〜V-04（トレース表・スコープ・スタック） |
| Phase 3 | データ可視化 | 3 週間 | V-05〜V-08（棒グラフ・色付き箱・時系列・ヒートマップ） |
| Phase 4 | 構造系可視化 | 4 週間 | V-09〜V-11（再帰ツリー・ライフタイム・制御フロー） |
| Phase 5 | 高度な可視化 | 4 週間 | V-12〜V-13（メモリモデル・オブジェクトグラフ） |
| Phase 6 | 仕上げ | 2 週間 | E2E テスト・ドキュメント整備・デプロイ |
目標: ステップ実行して現在イベントを表示できる最小動作版を完成させる
| # | タスク | 担当ファイル | 完了条件 |
|---|---|---|---|
| 1.1 | package.json 作成・JSInterpreter 参照 | package.json |
npm install が成功する |
| 1.2 | esbuild ビルド設定 | package.json scripts |
npm run build で web/app.bundle.js が生成される |
| 1.3 | DebuggerAdapter 実装 |
src/core/debugger-adapter.js |
load(source) → getState() が正しく動作するユニットテストが通る |
| 1.4 | StepController 実装 |
src/core/step-controller.js |
4 粒度のステップ前後でcursor が正しく移動するユニットテストが通る |
| 1.5 | TraceBuilder 骨格実装 |
src/core/trace-builder.js |
buildHumanIndices() が正しく動作するユニットテストが通る |
| 1.6 | コードエディタ実装 | src/components/code-editor.js |
コードを入力して Run ボタンで実行できる |
| 1.7 | ステップコントロールバー実装 | src/components/step-controls.js |
⏮◀▶⏭ボタンとキーボードショートカットが機能する |
| 1.8 | CodeView 実装 |
src/views/code-view/index.js |
現在実行中の行がハイライトされてスクロール追従する |
| 1.9 | 骨格 HTML/CSS 実装 | web/index.html, web/style.css |
ページが開いてエディタとコントロールが表示される |
| 1.10 | app.js 全体協調実装 |
src/app.js |
コードを実行してステップ操作ができる最小動作版が完成する |
フィボナッチのコードを貼り付けて Run → ステップ操作 → コードハイライトが動作する
目標: トレース表・スコープビュー・コールスタックビューを完成させる
| # | タスク | 担当ファイル | 完了条件 |
|---|---|---|---|
| 2.1 | ViewSwitcher 実装 |
src/components/view-switcher.js |
タブでビューが切り替わる |
| 2.2 | BaseView 抽象クラス定義 |
src/views/base-view.js |
init/update/reset/destroy の I/F が定義される |
| 2.3 | AnimatedTrace 実装 |
src/views/animated-trace/ |
ステップごとに行が追記・セルがフラッシュする |
| 2.4 | TraceTable 実装 |
src/views/trace-table/ |
全 humanStep の静的テーブルが生成・ハイライト追従する |
| 2.5 | ScopeView 実装 |
src/views/scope-view/ |
スコープチェーンのネスト枠が正しく更新される |
| 2.6 | CallStackView 実装 |
src/views/callstack-view/ |
push/pop アニメーション付きでスタックが更新される |
| 2.7 | サンプルコード追加 | src/app.js |
バブルソート・フィボナッチ・二分木が選択できる |
バブルソートのコードで、4 つのビューを切り替えながら動作を確認できる
目標: 数値・配列の変化をグラフで視覚化する 4 ビューを完成させる
| # | タスク | 担当ファイル | 完了条件 |
|---|---|---|---|
| 3.1 | TraceBuilder.buildHeatmap() 実装 |
src/core/trace-builder.js |
行ごとの実行回数が正しく集計されるユニットテストが通る |
| 3.2 | BarChart 実装 |
src/views/bar-chart/ |
変数選択 UI + 棒グラフアニメーションが動作する |
| 3.3 | ColorBox 実装 |
src/views/color-box/ |
配列アクセスのインデックスハイライトが正しく動作する |
| 3.4 | Timeline 実装（時系列グラフ） |
src/views/timeline/ |
SVG 折れ線グラフに現在ステップ縦線が表示される |
| 3.5 | Heatmap 実装 |
src/views/heatmap/ |
コードビューに実行頻度の背景色オーバーレイが表示される |
バブルソートで棒グラフ・色付き箱が同期してアニメーションする
目標: 再帰・スコープ寿命・制御フローの構造を可視化する 3 ビューを完成させる
| # | タスク | 担当ファイル | 完了条件 |
|---|---|---|---|
| 4.1 | TraceBuilder.buildRecursionTree() 実装 |
src/core/trace-builder.js |
フィボナッチの再帰ツリーが正しく構築されるユニットテストが通る |
| 4.2 | TraceBuilder.buildLifetime() 実装 |
src/core/trace-builder.js |
変数のライフタイム情報が正しく集計されるユニットテストが通る |
| 4.3 | RecursionTree レイアウトアルゴリズム実装 |
src/views/recursion-tree/layout.js |
ノードが重ならずにレイアウトされる |
| 4.4 | RecursionTree ビュー実装 |
src/views/recursion-tree/index.js |
SVG ツリーが正しくハイライトされる |
| 4.5 | Lifetime ビュー実装 |
src/views/lifetime/ |
ガントチャートが正しく描画・ハイライトされる |
| 4.6 | cfg-builder.js 実装 |
src/views/control-flow/cfg-builder.js |
if/for/while が CFGNode に変換されるユニットテストが通る |
| 4.7 | ControlFlow ビュー実装 |
src/views/control-flow/index.js |
フローチャートで通過済みの辺が青色になる |
再帰的なフィボナッチで再帰ツリーが展開し、制御フロービューで分岐が追跡できる
目標: メモリモデルとオブジェクトグラフを完成させる
| # | タスク | 担当ファイル | 完了条件 |
|---|---|---|---|
| 5.1 | MemoryView 実装 |
src/views/memory-view/ |
スタック/ヒープ分離表示とセル生成・消滅アニメーションが動作する |
| 5.2 | SVG 参照矢印の描画 | src/views/memory-view/index.js |
スタックセル → ヒープオブジェクトへの矢印が正しく描画される |
| 5.3 | ObjectGraph レイアウト実装 |
src/views/object-graph/layout.js |
ノードが重ならない簡易 Force-directed レイアウト |
| 5.4 | ObjectGraph ビュー実装 |
src/views/object-graph/index.js |
オブジェクト・配列の参照関係グラフが更新される |
| 5.5 | 循環参照の検出と表示 | src/views/object-graph/index.js |
循環参照が矢印で表現され無限ループしない |
二分木のコードでメモリモデルとオブジェクトグラフが正しく表示される
目標: プロダクション品質に引き上げてデプロイする
| # | タスク | 完了条件 |
|---|---|---|
| 6.1 | キーボードショートカット完全対応 | ステップ操作・ビュー切り替えがキーのみで可能 |
| 6.2 | エラーハンドリング改善 | パース・実行エラーが分かりやすく表示される |
| 6.3 | localStorage による設定永続化 | 粒度・ビュー選択・変数選択が再訪時に復元される |
| 6.4 | サンプルコードの充実 | 10 種類以上のサンプルが選択できる |
| 6.5 | 色覚多様性対応 | 色以外の手がかり（形・テキスト）が全ビューに追加される |
| 6.6 | 単体テスト整備 | コア層のカバレッジ 80% 以上 |
| 6.7 | GitHub Pages デプロイ設定 | main ブランチへの push で自動デプロイ |
| 6.8 | README 更新・スクリーンショット追加 | ドキュメントが完成する |
GitHub Pages でアクセス可能な状態で全 13 ビューが動作する
| リスク | 影響度 | 発生確率 | 対策 |
|---|---|---|---|
| 再帰ツリーのレイアウトアルゴリズムが難航する | 高 | 中 | まず単純な縦方向展開から実装し、後でアルゴリズムを改善 |
| オブジェクトグラフの Force-directed レイアウトが不安定 | 中 | 高 | 固定レイアウト（左-右 BFS）にフォールバックするオプションを用意 |
| JSInterpreter の API 変更で adapter が壊れる | 高 | 低 | debugger-adapter.js に JSInterpreter との契約を集約し、変更を 1 ファイルで吸収 |
| 大規模コード（500 行超）で trace が巨大になりパフォーマンス低下 | 中 | 中 | maxSteps をデフォルト 100,000 に制限し、超過時に警告表示 |
| 制御フロービューで AST の全パターンを網羅できない | 低 | 高 | try/catch・generator・class メソッドなど非対応構文を明示し、対応可能な構文のみ表示 |
Phase 2 以降でサポートするサンプルコード:
| サンプル名 | 主な学習テーマ | 主な対象ビュー |
|---|---|---|
| 探索 | ||
| 線形探索 | ループ・逐次比較・番兵 | 色付き箱・制御フロー・トレース表 |
| 二分探索 | ループ・条件分岐・探索範囲の縮小 | 制御フロー・色付き箱・時系列グラフ |
| ソート（基本） | ||
| バブルソート | 隣接要素の比較交換・二重ループ | 色付き箱・棒グラフ・ヒートマップ |
| 選択ソート | ループ・最小値探索・交換 | 色付き箱・棒グラフ |
| ソート（高度） | ||
| クイックソート | 再帰・分割・ピボット | 色付き箱・再帰ツリー・コールスタック |
| マージソート | 再帰・分割統治・マージ | 色付き箱・再帰ツリー・コールスタック |
| ソート（オブジェクト） | ||
| オブジェクトのソート（数値キー） | 高階関数・比較関数・Array.sort |
アニメーション付きトレース表・スコープビュー |
| オブジェクトのソート（文字列キー） | 文字列比較・localeCompare・高階関数 |
アニメーション付きトレース表・オブジェクトグラフ |
| 数学・アルゴリズム | ||
| ユークリッド互除法（ループ版） | ループ・条件・余り演算 | トレース表・時系列グラフ |
| ユークリッド互除法（再帰版） | 再帰の末尾呼び出し・基底ケース | 再帰ツリー・コールスタック・トレース表 |
| 階乗（再帰） | 再帰入門・基底ケース | 再帰ツリー・コールスタック |
| フィボナッチ（再帰） | 再帰・重複呼び出し | 再帰ツリー・コールスタック |
| フィボナッチ（DP） | メモ化・配列・計算量改善 | 色付き箱・時系列グラフ |
| データ構造 | ||
| 二分木構築・探索 | 木構造・再帰・オブジェクト参照 | オブジェクトグラフ・再帰ツリー |
| スコープ・オブジェクト | ||
| クロージャ | スコープ・変数寿命・関数オブジェクト | スコープビュー・ライフタイムタイムライン |
| クラスと継承 | オブジェクト・プロトタイプ・参照 | メモリモデル・オブジェクトグラフ |