はじめに：なぜ「目視」のWebpack解析は破綻するのか
フロントエンドの大規模化に伴い、私たちが日常的に向き合うWebpackのDependency Graph（依存関係グラフ）は、もはや人間の脳内やフラットなファイルツリーで把握できる限界を遥かに超越しています。
「なぜこのユーティリティを変更しただけで、全く関係なさそうなレガシー画面が壊れるのか？」
「誰がこの循環参照（Circular Dependency）を生み出したのか？」
「どのサードパーティライブラリがバンドルサイズを肥大化させているのか？」
チャットツールで誰かに尋ねても、「とりあえずCircular Dependency Pluginを入れてエラーが出たら直してる」といった場当たり的な答えしか返ってこない。そんなスパゲッティコード化したリポジトリで疲弊していませんか？
Webpackが内部で構築しているDependency Graphは、本質的に「ノード（モジュール）」と「エッジ（インポート）」の集合体、すなわち純粋なグラフ構造です。であるならば、このデータをテキストのログや静的なHTMLビジュアライザー（`webpack-bundle-analyzer`など）で眺めるだけなのは、宝の持ち腐れと言わざるを得ません。
本記事では、Webpackの心臓部から出力した`stats.json`をグラフデータベース（Neo4j）にインポートし、クエリ言語（Cypher）によって複雑怪奇な依存関係を完全解剖・可視化するデータ駆動型リファクタリング術を伝授します。感覚的な「リファクタリング」に終止符を打ち、数理的なアプローチでチームの生産性を限界突破させましょう。
—
1. Webpackの心臓部を暴く：`stats.json`の限界値引き出し設定
まず、Webpackの内部グラフをデータベースにインポートするための「高解像度な生データ」を出力させます。デフォルトの`stats`出力では、モジュール間の厳密な親子関係や非同期チャンクの繋がりが欠落します。
以下の設定を`webpack.config.js`に施し、すべてのモジュールID、被依存回数、そして正確なパス情報を含んだ完全なJSONを生成します。
`webpack.config.js` のベストプラクティス構成例
const path = require(‘path’);
module.exports = {
mode: ‘production’,
entry: ‘./src/index.js’,
output: {
path: path.resolve(__dirname, ‘dist’),
filename: ‘[name].[contenthash].js’,
},
stats: {
// グラフ解析の精度を上げるため、可能な限りすべてのメタデータをJSONに吐き出させる
all: false, // デフォルトの冗長な出力を一旦すべて抑制
modules: true, // モジュール（各ソースファイル）のリストを出力に含める
maxModules: Infinity, // 大規模プロジェクトでモジュールが切り捨てられないよう無限に設定
reasons: true, // 「なぜそのモジュールがバンドルに含まれたのか（誰からインポートされたか）」の理由を出力
usedExports: true, // Tree Shakingの解析用：どのエクスポートが実際に使われているか
providedExports: true, // モジュールが提供しているエクスポートのリスト
dependentModules: true, // 依存しているモジュールの詳細
chunkModules: true, // チャンクに含まれるモジュールの詳細
},
// 以下、通常の設定が続く…
};
ビルドコマンドの最適化（CLIからの吐き出し）
大規模なプロジェクトでは、メモリ不足（`JavaScript heap out of memory`）を防ぎつつ、高速にデータをダンプするためにNode.jsのメモリ上限を引き上げて実行します。
Node.jsに4GBのヒープを割り当て、標準出力を汚さずに stats.json のみファイル出力する
NODE_OPTIONS=”–max-old-space-size=4096″ npx webpack –profile –json=stats.json
このコマンドにより生成された数MB〜数十MBの`stats.json`こそが、あなたのアプリの「神経回路図」そのものです。
—
2. グラフデータベース（Neo4j）へのインポートパイプライン
出力されたJSONは階層構造を持っているため、そのままではグラフデータベースで扱いにくい。ここでは、Pythonスクリプトを用いて`stats.json`をパースし、Neo4jへ一気にグラフ構造（Nodes & Edges）として流し込むパイプラインを構築します。
事前準備：Pythonによるインポートスクリプト (`import_to_neo4j.py`)
以下のスクリプトをプロジェクトルートに配置し実行します。Neo4jの公式ドライバを使用します。
import json
from neo4j import GraphDatabase
Neo4jへの接続情報（環境変数やローカルコンテナの設定に合わせて変更）
URI = “bolt://localhost:7687”
AUTH = (“neo4j”, “password”)
def parse_and_load_stats(file_path):
print(f”[] Loading {file_path}…”)
with open(file_path, ‘r’, encoding=’utf-8′) as f:
data = json.load(f)
driver = GraphDatabase.driver(URI, auth=AUTH)
with driver.session() as session:
# 1. 既存のグラフデータを全クリア（クリーンな状態から構築）
session.run(“MATCH (n) DETACH DELETE n”)
print(“[] Cleared existing graph.”)
# 2. インデックスの作成（パフォーマンス向上）
session.run(“CREATE CONSTRAINT module_identifier IF NOT EXISTS FOR (m:Module) REQUIRE m.id IS UNIQUE”)
modules = data.get(“modules”, [])
print(f”[] Processing {len(modules)} modules…”)
# 3. モジュールノードの作成
for mod in modules:
mod_id = mod.get(“identifier”) or mod.get(“name”)
mod_name = mod.get(“name”, “”)
mod_size = mod.get(“size”, 0)
# 外部ライブラリ（node_modules）か、自社コード（src）かを判定するフラグ
is_vendor = “node_modules” in mod_name
session.run(
“””
CREATE (m:Module {
id: $id,
name: $name,
size: $size,
isVendor: $is_vendor
})
“””,
id=mod_id, name=mod_name, size=mod_size, is_vendor=is_vendor
)
# 4. 依存関係（エッジ: DEPENDS_ON）の構築
print(“[] Building dependency edges…”)
for mod in modules:
source_id = mod.get(“identifier”) or mod.get(“name”)
reasons = mod.get(“reasons”, [])
for reason in reasons:
target_id = reason.get(“moduleIdentifier”) or reason.get(“moduleName”)
if target_id and source_id:
# target_id が依存先、source_id が依存元（※Webpackのreasonsの向きに注意）
session.run(
“””
MATCH (source:Module {id: $source_id})
MATCH (target:Module {id: $target_id})
MERGE (source)-[r:DEPENDS_ON]->(target)
“””,
source_id=source_id, target_id=target_id
)
driver.close()
print(“[+] Successfully imported Webpack Dependency Graph into Neo4j!”)
if __name__ == “__main__”:
parse_and_load_stats(“stats.json”)
このスクリプトを実行することで、Neo4j内部に `(:Module)-[:DEPENDS_ON]->(:Module)` という完璧なWebアプリケーションの神経網が構築されます。
—
3. Cypherクエリによる「スパゲッティコード」の解明と実戦的解析
ここからが本領発揮です。Neo4jのブラウザやクライアントからCypher（サイファー）クエリを投げ、目視では絶対に発見できないコードの悪意や設計の歪みを暴き出します。
パターンA：循環参照（Circular Dependency）の完全自動検知
「AがBを呼び、BがCを呼び、Cが再びAを呼んでいる」ような循環参照は、Webpackのビルド順序を狂わせ、実行時エラー（`Cannot access ‘X’ before initialization`）の原因になります。プラグインによるその場しのぎではなく、グラフの閉路（Cycle）を数学的に検出します。
// 長さ2から6までの循環参照をすべて炙り出すCypherクエリ
MATCH path = (m:Module)-[:DEPENDS_ON2..6]->(m)
WHERE NOT m.isVendor // サードモジュールは除外して自社コードの循環のみに絞る
RETURN
[node in nodes(path) | node.name] AS CircularPath,
length(path) AS Depth
ORDER BY Depth DESC
実務でのメリット：
このクエリを実行すると、どのファイルとどのファイルが互いに依存し合っているかがパスの配列として一目瞭然になります。CI/CDパイプラインに組み込み、このクエリの結果が0件以外であればビルドを落とす、という厳格なガバナンスルールを敷くことが可能です。
パターンB：レガシー肥大化モジュールの特定（媒介中心性 / Betweenness Centrality）
「どのファイルを消したら、あるいはリファクタリングしたら最も影響範囲が大きいか」を、グラフ理論の「媒介中心性（Betweenness Centrality）」を使って算出します。これは、他のモジュール同士を結ぶ最短経路上にどれだけ頻繁に現れるかを示す指標です。
// GDS（Graph Data Science）ライブラリを使用した中心性の高い「ボトルネック・モジュール」の特定
CALL gds.betweenness.stream({
nodeProjection: ‘Module’,
relationshipProjection: {
DEPENDS_ON: {
type: ‘DEPENDS_ON’,
orientation: ‘NATURAL’
}
}
})
YIELD nodeId, score
MATCH (m:Module) WHERE id(m) = nodeId
RETURN m.name AS ModuleName, m.size AS SizeBytes, score AS CentralityScore
ORDER BY CentralityScore DESC
LIMIT 10
実務でのメリット：
ここにヒットするファイルは、アプリケーション全体の「ハブ（要）」となっています。もしこのファイルがスパゲッティ化している場合、全チームの生産性がここに足を引っ張られていることになります。リファクタリングの優先順位をつける際の絶対的なエビデンスとなります。
—
4. チーム開発・CI/CDへの組み込みと継続的ガバナンス
この高度な解析手法を、一過性のイベントで終わらせず、チームの日常的な開発フローに定着させるための実践ルールを策定します。
1. チーム共有の VS Code 拡張機能 & キーボードショートカット
開発者が日々のコーディング中に依存関係の異常に気づけるよう、チーム全員に以下のVS Code拡張機能を強制します。
- Graphviz Preview または Neo4j Cypher Runner
- Circular Dependency Check
現場で差が出る時短ショートカット（macOS / Windows）：
- `Cmd + Shift + P` （`Ctrl + Shift + P`）から `Neo4j: Run Cypher Query` を即座に呼び出せるよう、カスタムキーボードショートカットに `Cmd + Option + N` を割り当てておく。これにより、コードを書きながら瞬時に自分の変更がグラフに与える影響を想定できます。
2. CI/CD（GitHub Actions）での自動静的解析パイプライン
プルリクエストが作成されるたびに、マスターブランチとの依存関係の「劣化（循環参照の増加やバンドルサイズの急増）」を検知するワークフローを定義します。
`.github/workflows/dependency_audit.yml`
name: Dependency Graph Audit
on:
pull_request:
branches: [ main ]
jobs:
analyze-graph:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v3
- name: Set up Node.js
uses: actions/setup-node@v3
with:
node-version: ’18’
cache: ‘npm’
- name: Install Dependencies
run: npm ci
- name: Generate Webpack Stats
run: |
npx webpack –profile –json=stats.json
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: ‘3.10’
- name: Install Python Neo4j Driver
run: pip install neo4j
# ※実際にはCI環境用にNeo4jのコンテナをサービスとして立ち上げるか、
# Pythonスクリプト側でNetworkxなどのインメモリグラフライブラリに置き換えてCIを軽量化する手法も有効です。
- name: Run Dependency Health Check
run: |
python scripts/audit_dependency.py
env:
NEO4J_URI: ${{ secrets.NEO4J_URI }}
NEO4J_USER: ${{ secrets.NEO4J_USER }}
NEO4J_PASSWORD: ${{ secrets.NEO4J_PASSWORD }}
—
おわりに：直感と感情のマネジメントから、データ駆動のアーキテクチャへ
「このコード、なんだかスパゲッティ化していて怖いよね」
「誰かあの循環参照直してよ」
現場でこんな会話が飛び交っているうちは、そのプロジェクトのスケールには必ず限界が訪れます。コードの複雑性は、人間の感情や記憶力でコントロールできるものではありません。だからこそ、Webpackというビルドツールの生み出す生データをグラフデータベースに流し込み、数学的なアプローチで構造を「観測」するのです。
この手法を導入したチームは、もはや「勘」でコードを触る必要がなくなります。リファクタリングの効果は数値化され、技術負債は可視化され、レビューの質は劇的に跳ね上がります。
さあ、今すぐあなたのプロジェクトの`stats.json`を吐き出し、コードの真の姿をグラフの海で捉えてみてください。そこには、これまで見えなかった新しいアーキテクチャの地平が広がっているはずです。