CodeGarden

📚 CodeGardenって何？

CodeGardenは、JavaScriptやTypeScriptのコードを「星空のように美しく」視覚化するツールです。 複雑なコードの構造を、星（ノード）と線（関係性）で表現し、一目で全体像を把握できるようにします。

🚀 はじめての使い方（3ステップ）

🌟 表示されるものの意味

💡 初心者のためのコツ

❓ よくある質問（初心者向け）

🖥️ 実際のアプリ画面

CodeGardenのメイン画面では、左側のサイドバーでコントロールし、右側のキャンバスでコードを視覚化します。

CodeGardenメイン画面 - 左側で設定、右側で視覚化

📊 品質評価システムの見方

CodeGardenは、コードの品質を複数の指標で評価し、分かりやすいスコアで表示します。

実際のメイン画面

CodeGardenメイン画面 - 左側サイドバーと右側コード視覚化

CodeGardenメイン画面 - サイドバーの詳細情報とExtended metrics

品質レポートの実際の画面

品質レポート - コード品質分析レポートのメイン画面（総合スコア68% C+評価）

📊 総合評価

• 総合スコア: 68% - 平均的なコード品質
• 評価: C+ - 平均以下
• 保守性: 100% - 優れた保守性
• 業界標準: SonarQube C+、CodeClimate GPA 2.7

⚠️ 主要な課題

• 技術的負債: 非常に高い（57.8pt）
• コードスメル: 非常に多い（33個）
• コード構造: 26% - 改善が必要
• 複雑度: 89% - 理解が困難

品質レポート - 詳細指標と技術的負債の詳細分析

📄 HTMLレポート出力機能

品質レポートは、HTML形式でエクスポートして保存・共有することができます

HTMLレポート出力 - コード品質分析レポートのエクスポート機能

📊 レポートの内容

• 総合品質スコア: コード全体の品質評価
• 詳細指標: 複雑度、保守性、セキュリティなど
• 技術的負債: 修正が必要な問題の一覧
• コードスメル: 改善すべきコードの問題点
• 改善提案: 具体的なアクションプラン

💡 活用方法

• チーム共有: 開発チームでの品質議論
• 進捗管理: 改善作業の進捗追跡
• ドキュメント化: プロジェクトの品質記録
• レビュー資料: コードレビューの参考資料

🔍 解析パターン（アナライザー）の違い

CodeGardenには5つの解析パターンがあり、それぞれ異なる角度からコードを分析します。

解析パターンの実際の違い

CodeGardenメイン画面 - 異なる解析パターンの表示例

📈 Extended metrics（拡張メトリクス）とは

MetricsExt解析を使用すると、より詳細な品質指標が表示されます。

Extended metricsの実際の表示

Extended metrics - サイドバーでの技術的負債とコードスメル表示

💡 改善提案の見方

品質レポートでは、具体的な改善提案も表示されます。

改善提案 - HIGH/MEDIUM優先度の具体的な実施ステップ

📱 アプリケーションの実際の画面

メイン画面

左側のコントロールパネルと右側のコード視覚化エリア

Star Density機能

Star Densityスライダーでノードの密集具合を調整

以下は要点の抜粋です。詳細はアプリ内の「Render Pattern Spec」を参照してください。

概要パネル

• File: 解析ファイルのパス
• Lines: 総行数
• Functions: 関数数
• Max depth: ツリーの最大深さ
• Language: 検出されたプログラミング言語（JavaScript, TypeScript, Java, C++, Go, Rust, Python等）
• Categories: 主要カテゴリの統計情報（上位3カテゴリを表示）

選択サマリ

• Nodes / Blocks / Functions / Classes / Interfaces
• Total lines と 重複を除いたユニーク行数
• Avg cc（サイクロマティック複雑度の平均）, Avg nest（ネスティング深さの平均）
• Score sum（視認性のための合成指標）, Max depth（最大深さ）
• Category breakdown（カテゴリ別の詳細統計）
• 重複除去アルゴリズム: 連続する行範囲を統合して正確なユニーク行数を計算

アプリ内部では、解析結果を統一フォーマット（XML v2）へ変換し、描画時に再構築しています。

summary

• totalLines, filePath, functionCount, maxDepth, deadCodeCount
• language, categoryCount, totalComplexity, averageNesting

node

• 属性: id, kind, category, name
• loc: start, end, lines
• complexity: cyclomatic, nestingDepth
• layout: depth, angle, radius
• metrics（拡張）: 文数、分岐数、ループ数、呼び出し数、return文数、例外処理数、switch文数など
• language: 検出されたプログラミング言語
• category: 関数、クラス、インターフェース、トレイト、構造体、列挙型、ブロック、制御フロー、データ構造、マクロ、テンプレート、デコレータ、ラムダ、コルーチン、テストなど

edge

• 属性: id, kind（hierarchy / call）, from, to
• 関係性: 継承、実装、依存、呼び出し、包含、参照など

詳細はアプリ内の「XML Spec (XML_FORMAT.md)」で確認できます。

内部データ形式

• XML フォーマット: アプリ内部で解析結果を統一フォーマット（XML v2）として管理しています。
• 解析結果の保存: 現在のアプリでは、解析結果はセッション中のみ保持されます。
• 外部エクスポート: 将来的な機能拡張として、解析結果の外部保存が検討されています。

技術仕様

• AST解析: 各言語の構文解析木を基にした構造化データ
• メトリクス計算: 複雑度、ネスティング深さ、行数などの統計情報
• レイアウト情報: 表示パターンに応じた座標・角度・半径データ

• ノード数が非常に多い場合は、v6（グリッド）やv9（カテゴリ帯）で俯瞰→気になる領域を拡大。
• スタイル v2〜v4 は装飾を含みます。ズームやノード数に応じて自動的に軽量化されます（視認性は維持）。
• 呼び出し線が多い場合は、v10以外に切り替えると見やすくなります。
• TypeScriptファイルの場合は、v11（TypeScript対応）やv13（拡張黄金角）が最適です。TypeScript固有の最適化が適用されます。
• Star Densityを活用して、ノード数や画面サイズに応じて最適な表示密度を設定してください。密集させると全体像を把握しやすく、分散させると個別ノードの詳細が確認しやすくなります。

• 何も表示されない: ソースに構造が少ない／パースに失敗。別ファイルで確認してください。
• 重い: 全体表示時は装飾が軽量化されます。v6やv9に切り替え、拡大して詳細を確認してください。
• 中心がズレる（v6）: 最新版ではグリッド全体を原点中心に配置するよう修正済みです。
• TypeScriptファイルで解析が不完全: MultiLangやCategory-Awareアナライザーを試してください。TypeScript固有の構文要素が適切に認識されます。
• レンダリングが遅い: v1やv6などの軽量パターンに切り替えてください。v11-v13はTypeScript対応のため若干重くなる場合があります。

Q. スコア（score）とは？

行数・複雑度などを統合した視認性指標です。大きいほど目立つノードとして描かれ、着目候補になります。

Q. 品質レポートのスコアはどう計算される？

総合スコアは、コード複雑度、構造、保守性、技術的負債、コードスメルなどを総合的に評価して0-100%で算出されます。業界標準（SonarQube、CodeClimate、ISO 25010）との比較も提供されます。

Q. ネスト構造の深さはどう確認できる？

Basic アナライザーを使用すると、コードの階層構造が視覚的に表示されます。ノードの色分けやグリッド配置で深さを確認でき、メトリクス表示（nest値）で具体的なネスト深度を数値で確認できます。特にRenderer v6（グリッド/深度）パターンが階層構造の確認に適しています。

Q. 推奨レイアウトの使い分けは？

3つのプリセットは用途に応じて使い分けます。Overviewは複雑度と拡張メトリクスを強調するサンバースト配置で、プロジェクト全体の概要把握に適しています。CallGraphは呼び出し関係を力学レイアウトで強調し、関数間の依存関係分析に最適です。Categoryはカテゴリ帯とグルーピングを強調し、コードの分類と構造理解に役立ちます。

Q. 拡張メトリクスで何が分かる？

MetricsExtアナライザーを選択すると、技術的負債とコードスメルの詳細な分析が表示されます。技術的負債は数値化されたスコアで表示され、コードスメルは具体的な問題項目（長すぎる関数、戻り値が多すぎる等）としてリストアップされます。各問題には深刻度（MAJOR/MINOR）が表示され、優先順位をつけて改善に取り組めます。

Q. Documents機能は何に使える？

サイドバーのDocumentsセクションから、ユーザーマニュアル、XML仕様書、レンダーパターン仕様書にアクセスできます。特にユーザーマニュアルは6言語（英語、日本語、ドイツ語、中国語、韓国語、ヒンディー語）で提供されており、グローバルなユーザーサポートを実現しています。各ドキュメントはクリック一つで開くことができ、詳細な機能説明や仕様確認に便利です。

Q. Selection Summaryで何が分かる？

星々（ノード）を選択すると、サイドバーのSelection Summaryセクションに選択範囲の詳細情報が表示されます。選択されたノード数、関数・ブロック数、総行数、平均循環複雑度、平均ネスト深度、スコア合計、最大深度などのメトリクスがリアルタイムで更新され、選択範囲のコード品質を定量的に把握できます。ドラッグ選択やCtrl+クリックで複数ノードを選択し、特定のコード領域の分析に活用できます。

Q. XML/JSON のどちらを使うべき？

アプリ外で解析を再利用する場合は JSON が簡便です。XML は内部の標準形式で、仕様の確認に向きます。

Q. どのパターンを選べばよい？

最初は v1/v9 で俯瞰 → 密度や関係が気になれば v10 → 詳細比較は v2/v6 → TypeScript対応は v11/v13、の流れがスムーズです。TypeScript固有の最適化が必要な場合は v11/v13 を優先してください。

📋 Basic アナライザー（Grundlegend (Struktur)）

基本的なAST解析を行い、関数、クラス、ブロックの階層構造と複雑度（サイクロマティック複雑度、ネスティング深さ）を計算します。最も軽量で高速な解析が可能です。言語検出とカテゴリ決定も含みます。

階層構造の視覚化

階層構造表示 - Basic アナライザーによるネスト構造の可視化（Renderer v6 グリッド/深度パターン）

🏗️ 階層構造の特徴

• ネスト深度の可視化: コードの階層構造が明確に表示
• ブロック構造: 関数内のブロック（if文、for文など）を識別
• 関数階層: 関数の包含関係とネスト構造を表示
• 変数スコープ: 変数の有効範囲を視覚的に理解

🔍 ネスト構造の確認方法

• 深さの色分け: ノードの色で階層の深さを表現
• グリッド配置: 深さごとに整列して表示
• メトリクス表示: cc/nest/lines/scoreで詳細情報
• 選択サマリー: 選択したノード群の統計情報

CallGraph アナライザー

関数間の呼び出し関係を解析し、依存性グラフを構築します。関数の入次数・出次数、ファンイン・ファンアウトなどの指標を提供します。階層エッジとコールエッジの両方を生成します。

MetricsExt アナライザー

詳細なメトリクスを計算します。文数、分岐数、ループ数、return文数、例外処理数、switch文数など、コードの品質指標を数値化します。言語固有の構文要素も検出します。また、技術的負債、コードスメル、保守性指標などの高度な品質分析も含みます。

MultiLang アナライザー

TypeScript対応の解析を行い、TypeScript固有の構文要素（インターフェース、ジェネリクス、デコレータ、列挙型、型エイリアスなど）を適切に認識します。JavaScriptとTypeScriptの言語特性に対応します。

Category-Aware アナライザー

カテゴリを意識したスマート解析を行い、ノードの重要度や関連性を考慮した分析結果を提供します。カテゴリ統計の自動計算と、JavaScript/TypeScript固有のカテゴリマッピングを含みます。

📊 総合品質評価

CodeGardenは、コードの品質を多角的に評価し、分かりやすいスコアで表示します。総合スコアは0-100%で表され、業界標準との比較も提供されます。

技術的負債（Technical Debt）

複雑性、ネスト深度、関数長、パラメータ数に基づいて技術的負債を積み上げ評価します。合計値はソースの状態に応じて増減し、深刻度（info / minor / major / critical）で自動分類されます。

• info: 0.00〜1.99 — 改善候補の把握段階
• minor: 2.00〜4.99 — 優先度中程度の改善タスク
• major: 5.00〜9.99 — 優先して対処すべき負債
• critical: 10.00以上 — 早急な是正が必要な状態

コードスメル（Code Smells）

以下のコードスメルを自動検出します：

• 長い関数: 50行以上（S138）
• 複雑な関数: サイクロマティック複雑度10以上（S1541）
• 深いネスト: ネスト深度5以上（S134）
• パラメータ過多: 5個以上（S107）
• マジックナンバー: ハードコードされた数値（S109）
• 未使用変数: 定義されているが使用されていない変数（S1481）

保守性指標（Maintainability Index）

Halstead Volume、複雑性、関数長、関数数、カテゴリ多様性を考慮した保守性指標を0-100の範囲で計算します。高いほど保守性が良いことを示します。

📈 詳細品質指標

レポートでは、以下の詳細な品質指標が表示されます：

その他の指標

• コード重複率: 関数名と行数ベースの重複検出
• 結合度: モジュール間の依存関係の強さ
• 凝集度: モジュール内の関連性の強さ
• セキュリティスコア: 危険な関数名やパターンの検出

完全サポート言語

現在サポートされている言語固有の特徴

• JavaScript: ES6+機能、動的型付け、プロトタイプベース継承、非同期処理、アロー関数、スプレッド/レスト演算子、分割代入
• TypeScript: 静的型付け、高度な型システム、インターフェース、ジェネリクス、デコレータ、非同期処理、TS固有構文、型注釈

📊 テスト結果の概要

🔧 テスト環境

🔍 テストの種類

📋 テスト結果の詳細

💡 品質の考え方

⚠️ 品質の限界について

本アプリケーションは、以下のオープンソースソフトウェアに支えられています。提供元コミュニティと貢献者の皆様に深く感謝いたします。

            MIT License
            
            Permission is hereby granted, free of charge, to any person obtaining a copy
            of this software and associated documentation files (the "Software"), to deal
            in the Software without restriction, including without limitation the rights
            to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
            copies of the Software, and to permit persons to whom the Software is
            furnished to do so, subject to the following conditions:
            
            The above copyright notice and this permission notice shall be included in all
            copies or substantial portions of the Software.
            
            THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
            IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
            FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
            AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
            LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
            OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
            SOFTWARE.
                            

                GNU LESSER GENERAL PUBLIC LICENSE
                Version 2.1, February 1999
                
                Copyright (C) 1991, 1999 Free Software Foundation, Inc.
                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
                Everyone is permitted to copy and distribute verbatim copies
                of this license document, but changing it is not allowed.
                
                [... 省略せず全文を参照する場合は上記GNUサイトの原文をご確認ください ...]