# アーキテクチャ設計書

## 概要

本ドキュメントは、webpack v5.105.3のアプリケーションアーキテクチャを記述する。webpackはECMAScript/CommonJS/AMDモジュールをブラウザ向けにバンドルするモジュールバンドラーであり、プラグインベースのパイプラインアーキテクチャを採用している。tapableライブラリによるフックシステムを中核として、コンパイルパイプラインの各フェーズにプラグインが介入可能な拡張性の高い設計となっている。

## システム全体構成

### アーキテクチャ概要図

[アーキテクチャ構成図](./アーキテクチャ構成図.md) を参照。

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| webpack-cli | CLIバイナリ (`bin/webpack.js`) 経由 | コマンドラインインターフェース。CLIが未インストールの場合は自動インストールを促す |
| enhanced-resolve | Node.js モジュール依存 | モジュールパス解決（ファイルシステム上のモジュール探索） |
| loader-runner | Node.js モジュール依存 | ローダーの実行エンジン（ソースコード変換パイプライン） |
| tapable | Node.js モジュール依存 | プラグインフックシステムの基盤ライブラリ |
| acorn | Node.js モジュール依存 | JavaScriptパーサー（AST生成） |
| webpack-sources | Node.js モジュール依存 | ソースコード・ソースマップの抽象化レイヤー |
| @webassemblyjs | Node.js モジュール依存 | WebAssemblyバイナリの解析・編集 |
| schema-utils | Node.js モジュール依存 | JSONスキーマによるオプションバリデーション |
| watchpack | Node.js モジュール依存 | ファイルシステム監視（watchモード） |
| terser-webpack-plugin | Node.js モジュール依存 | JavaScriptコード圧縮（デフォルトminifier） |
| ファイルシステム | Node.js fs API | 入力ファイルの読み取り、出力バンドルの書き込み |

## レイヤー構成

### アーキテクチャスタイル

**プラグインベースのパイプラインアーキテクチャ**

webpackは伝統的なレイヤードアーキテクチャではなく、パイプライン（コンパイルパイプライン）をプラグインで構成するアーキテクチャを採用している。tapableライブラリが提供するフック（SyncHook, AsyncSeriesHook, AsyncParallelHook等）を通じて、各処理フェーズにプラグインがタップ（登録）し、コンパイル処理の流れを制御する。

核となるのは以下のパイプラインフローである：

1. **構成解決** -- オプションの正規化とデフォルト値適用
2. **コンパイラ初期化** -- プラグインの適用とフック登録
3. **コンパイル実行** -- モジュールのビルド、依存解決、チャンクグラフ構築
4. **最適化** -- Tree Shaking、コード分割、モジュール連結等
5. **コード生成・出力** -- バンドルコードの生成とファイル出力

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| CLI / エントリーポイント | コマンドラインインターフェースとwebpack関数のエクスポート | `bin/webpack.js`, `lib/index.js`, `lib/webpack.js`, `lib/cli.js` |
| 構成・設定 | オプションの正規化、デフォルト値適用、スキーマバリデーション | `lib/config/normalization.js`, `lib/config/defaults.js`, `lib/config/target.js`, `lib/validateSchema.js`, `schemas/` |
| コンパイラコア | コンパイルライフサイクルの管理、プラグイン適用の統括 | `lib/Compiler.js`, `lib/MultiCompiler.js`, `lib/WebpackOptionsApply.js`, `lib/Watching.js` |
| コンパイル | モジュールビルド、依存解決、チャンク・モジュールグラフ管理 | `lib/Compilation.js`, `lib/NormalModuleFactory.js`, `lib/ContextModuleFactory.js`, `lib/buildChunkGraph.js` |
| モジュール | 各種モジュール型の表現とビルド処理 | `lib/Module.js`, `lib/NormalModule.js`, `lib/ExternalModule.js`, `lib/ContextModule.js`, `lib/DllModule.js`, `lib/CssModule.js` |
| 依存関係 | モジュール間の依存関係の表現と解析 | `lib/Dependency.js`, `lib/dependencies/` (CommonJS, Harmony, AMD, Import, URL, Worker等 120+ファイル) |
| パーサー | ソースコード解析とAST処理 | `lib/javascript/JavascriptParser.js`, `lib/css/CssParser.js`, `lib/json/JsonParser.js`, `lib/asset/AssetParser.js` |
| コード生成 | モジュールからのバンドルコード生成 | `lib/javascript/JavascriptGenerator.js`, `lib/css/CssGenerator.js`, `lib/json/JsonGenerator.js`, `lib/Template.js`, `lib/RuntimeTemplate.js` |
| 最適化 | バンドルサイズ削減と効率化 | `lib/optimize/SplitChunksPlugin.js`, `lib/optimize/ModuleConcatenationPlugin.js`, `lib/FlagDependencyExportsPlugin.js`, `lib/FlagDependencyUsagePlugin.js` |
| ランタイム | ブラウザ/Node.jsでのモジュール読み込みランタイムコード | `lib/RuntimeModule.js`, `lib/RuntimePlugin.js`, `lib/RuntimeGlobals.js`, `lib/runtime/` (30+ファイル) |
| キャッシュ | コンパイル結果のキャッシュ管理 | `lib/Cache.js`, `lib/CacheFacade.js`, `lib/cache/MemoryCachePlugin.js`, `lib/cache/IdleFileCachePlugin.js`, `lib/cache/PackFileCacheStrategy.js` |
| シリアライゼーション | キャッシュデータの永続化 | `lib/serialization/Serializer.js`, `lib/serialization/ObjectMiddleware.js`, `lib/serialization/BinaryMiddleware.js`, `lib/serialization/FileMiddleware.js` |
| 統計・レポート | ビルド結果の統計情報とレポート生成 | `lib/Stats.js`, `lib/MultiStats.js`, `lib/stats/StatsFactory.js`, `lib/stats/StatsPrinter.js` |
| ユーティリティ | 共通ヘルパー関数群 | `lib/util/` (ハッシュ生成、比較関数、非同期キュー、ファイルシステム抽象化等 57ファイル) |

### レイヤー間の依存関係ルール

webpackのアーキテクチャでは、レイヤー間の依存関係は以下のルールに従う：

1. **コンパイラコアが統括** -- `Compiler`が`Compilation`を生成し、`NormalModuleFactory`と`ContextModuleFactory`を管理する
2. **プラグインによる疎結合** -- 各レイヤーは直接依存するのではなく、tapableフックを通じて間接的に連携する
3. **モジュール型の多態性** -- `Module`基底クラスを各種モジュール型（`NormalModule`, `ExternalModule`, `ConcatenatedModule`等）が継承する
4. **ファクトリーパターン** -- モジュール生成は`ModuleFactory`経由で行い、直接インスタンス化しない
5. **ユーティリティは全レイヤーから参照可能** -- `lib/util/`配下のユーティリティ関数は全レイヤーから利用される
6. **WebpackOptionsApplyが設定とプラグインを橋渡し** -- 設定レイヤーとプラグインレイヤーの間を`WebpackOptionsApply`が仲介し、設定値に応じたプラグイン適用を行う

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| JavaScript処理 | JS/ESMモジュールの解析・生成・チャンクフォーマット | `lib/javascript/` (JavascriptParser, JavascriptGenerator, JavascriptModulesPlugin, EnableChunkLoadingPlugin等) |
| CSS処理 | CSSモジュールの解析・生成・ランタイムロード | `lib/css/` (CssParser, CssGenerator, CssModulesPlugin, CssLoadingRuntimeModule等) |
| JSON処理 | JSONファイルのモジュール化 | `lib/json/` (JsonParser, JsonGenerator, JsonModulesPlugin) |
| アセット処理 | 画像・フォント等の静的アセットのモジュール化 | `lib/asset/` (AssetParser, AssetGenerator, AssetModulesPlugin, AssetSourceGenerator等) |
| WebAssembly処理 | 同期/非同期Wasmモジュールのサポート | `lib/wasm-sync/`, `lib/wasm-async/` |
| 依存関係解析 | CommonJS/ESM/AMD/動的インポート等の依存関係表現 | `lib/dependencies/` (120+ファイル) |
| 最適化 | Tree Shaking、コード分割、モジュール連結、サイドエフェクト分析 | `lib/optimize/` (SplitChunksPlugin, ModuleConcatenationPlugin, SideEffectsFlagPlugin等) |
| ランタイム | バンドル実行時のモジュールロードランタイム | `lib/runtime/` (30+RuntimeModule) |
| キャッシュ | メモリ/ファイルベースのビルドキャッシュ | `lib/cache/`, `lib/serialization/` |
| Module Federation | マイクロフロントエンド向けモジュール共有 | `lib/container/` (ContainerPlugin, ModuleFederationPlugin, RemoteModule等) |
| 共有モジュール | Module Federationにおけるモジュール共有 | `lib/sharing/` (SharePlugin, ConsumeSharedPlugin, ProvideSharedPlugin等) |
| ID割り当て | モジュール/チャンクIDの決定戦略 | `lib/ids/` (DeterministicModuleIdsPlugin, NamedModuleIdsPlugin等) |
| ライブラリ出力 | 各種ライブラリフォーマット(UMD, AMD, CommonJS, ESM等)での出力 | `lib/library/` (EnableLibraryPlugin, UmdLibraryPlugin, ModuleLibraryPlugin等) |
| Node.js環境 | Node.js固有の環境設定とチャンクロード | `lib/node/` (NodeEnvironmentPlugin, NodeTargetPlugin, NodeTemplatePlugin等) |
| Web環境 | ブラウザ固有のチャンクロード(JSONP)とWasm対応 | `lib/web/` (JsonpTemplatePlugin, FetchCompileWasmPlugin等) |
| ESM出力 | ESMフォーマットでのチャンク出力 | `lib/esm/` (ModuleChunkFormatPlugin, ModuleChunkLoadingPlugin等) |
| WebWorker | WebWorker向けテンプレートとロード | `lib/webworker/` (WebWorkerTemplatePlugin) |
| Electron | Electron環境向け外部モジュール処理 | `lib/electron/` (ElectronTargetPlugin) |
| スキーム処理 | data:, file:, http: URI等のスキーム処理 | `lib/schemes/` (DataUriPlugin, FileUriPlugin, HttpUriPlugin, VirtualUrlPlugin) |
| HMR | Hot Module Replacementの実装 | `lib/hmr/`, `lib/HotModuleReplacementPlugin.js`, `hot/` |
| ロギング | ビルドログの出力制御 | `lib/logging/` (Logger, createConsoleLogger) |
| デバッグ | プロファイリングとデバッグ支援 | `lib/debug/` (ProfilingPlugin) |
| ルール処理 | モジュールルール(loader適用条件)の評価 | `lib/rules/` (RuleSetCompiler, BasicMatcherRulePlugin等) |
| 非同期モジュール | 非同期モジュール(Top-Level Await)の推論と処理 | `lib/async-modules/` (InferAsyncModulesPlugin) |
| プリフェッチ | チャンクのプリフェッチ/プリロード | `lib/prefetch/` (ChunkPrefetchPreloadPlugin) |
| 統計・レポート | ビルド統計のファクトリとプリンター | `lib/stats/` (StatsFactory, StatsPrinter, DefaultStatsFactoryPlugin等) |

### パッケージ構造

```
lib/
├── index.js                    # メインエントリーポイント（遅延ロードによる公開API）
├── webpack.js                  # webpack関数本体（Compiler/MultiCompiler生成）
├── Compiler.js                 # コンパイラコア（ビルドライフサイクル管理）
├── Compilation.js              # コンパイル処理（モジュールビルド・チャンクグラフ構築）
├── Module.js                   # モジュール基底クラス
├── NormalModule.js             # 通常モジュール（ファイルベース）
├── NormalModuleFactory.js      # モジュール生成ファクトリ
├── ContextModuleFactory.js     # コンテキスト(ディレクトリ)モジュール生成
├── Chunk.js                    # チャンク（バンドル出力単位）
├── ChunkGraph.js               # チャンク-モジュール関係グラフ
├── ChunkGroup.js               # チャンクグループ管理
├── ModuleGraph.js              # モジュール依存関係グラフ
├── Dependency.js               # 依存関係基底クラス
├── WebpackOptionsApply.js      # 設定からプラグイン適用への変換
├── buildChunkGraph.js          # チャンクグラフ構築アルゴリズム
├── ExportsInfo.js              # エクスポート情報管理（Tree Shaking用）
├── RuntimeGlobals.js           # ランタイムグローバル変数定義
├── RuntimeModule.js            # ランタイムモジュール基底クラス
├── RuntimeTemplate.js          # ランタイムコードテンプレート
├── Template.js                 # テンプレートヘルパー
├── Cache.js                    # キャッシュインターフェース
├── ResolverFactory.js          # モジュール解決ファクトリ
├── Stats.js                    # ビルド統計
├── MultiCompiler.js            # 複数コンパイラ管理
├── Watching.js                 # ファイル監視モード
├── WebpackError.js             # エラー基底クラス
│
├── config/                     # 設定処理
│   ├── normalization.js        #   オプション正規化
│   ├── defaults.js             #   デフォルト値適用
│   └── target.js               #   ターゲット環境解析
│
├── javascript/                 # JavaScript処理
│   ├── JavascriptParser.js     #   JSパーサー（acornベース）
│   ├── JavascriptGenerator.js  #   JSコード生成
│   └── JavascriptModulesPlugin.js  # JSモジュールプラグイン
│
├── css/                        # CSS処理
│   ├── CssParser.js            #   CSSパーサー
│   ├── CssGenerator.js         #   CSSコード生成
│   └── CssModulesPlugin.js     #   CSSモジュールプラグイン
│
├── json/                       # JSON処理
├── asset/                      # アセット処理
├── wasm-sync/                  # 同期WebAssembly
├── wasm-async/                 # 非同期WebAssembly
│
├── dependencies/               # 依存関係定義（120+ファイル）
│   ├── HarmonyModulesPlugin.js #   ESM依存関係
│   ├── CommonJsPlugin.js       #   CommonJS依存関係
│   ├── AMDPlugin.js            #   AMD依存関係
│   ├── ImportPlugin.js         #   動的import()
│   └── ...
│
├── optimize/                   # 最適化プラグイン群
│   ├── SplitChunksPlugin.js    #   コード分割
│   ├── ModuleConcatenationPlugin.js  # スコープホイスティング
│   ├── SideEffectsFlagPlugin.js      # サイドエフェクト分析
│   └── ...
│
├── runtime/                    # ランタイムモジュール（30+ファイル）
├── ids/                        # ID割り当て戦略
├── cache/                      # キャッシュ実装
├── serialization/              # シリアライゼーション
├── container/                  # Module Federation
├── sharing/                    # 共有モジュール
├── library/                    # ライブラリ出力フォーマット
├── node/                       # Node.js環境サポート
├── web/                        # Web環境サポート
├── esm/                        # ESM出力サポート
├── webworker/                  # WebWorkerサポート
├── electron/                   # Electronサポート
├── schemes/                    # URIスキーム処理
├── hmr/                        # Hot Module Replacement
├── logging/                    # ロギング
├── debug/                      # デバッグ・プロファイリング
├── rules/                      # ルールセットコンパイラ
├── async-modules/              # 非同期モジュール推論
├── prefetch/                   # プリフェッチ/プリロード
├── stats/                      # 統計レポート
├── errors/                     # エラー定義
├── url/                        # URLモジュール
├── wasm/                       # Wasmロード有効化
└── util/                       # ユーティリティ（57ファイル）
    ├── createHash.js           #   ハッシュ生成
    ├── AsyncQueue.js           #   非同期キュー
    ├── comparators.js          #   比較関数
    ├── fs.js                   #   ファイルシステム抽象化
    ├── runtime.js              #   ランタイムユーティリティ
    └── ...
```

### コンポーネント依存関係

webpackの主要コンポーネントの依存関係は以下の通りである。

1. **webpack関数** (`lib/webpack.js`) が `Compiler` / `MultiCompiler` を生成する
2. **Compiler** が `NormalModuleFactory`, `ContextModuleFactory`, `ResolverFactory`, `Compilation` を生成・管理する
3. **Compilation** が `ModuleGraph`, `ChunkGraph` を保持し、モジュールビルドとチャンクグラフ構築を行う
4. **NormalModuleFactory** が `RuleSetCompiler` でローダーを解決し、`NormalModule` インスタンスを生成する
5. **NormalModule** が `JavascriptParser`（または他のParser）でソースを解析し、依存関係（`Dependency`サブクラス群）を抽出する
6. **buildChunkGraph** が `ModuleGraph` の情報を元に `ChunkGraph` を構築する
7. 最適化プラグイン群（`SplitChunksPlugin`, `ModuleConcatenationPlugin`等）が `ChunkGraph` と `ModuleGraph` を操作する
8. **JavascriptGenerator** 等のコード生成器が最終バンドルコードを生成する
9. **RuntimeModule** のサブクラス群がバンドル実行時のランタイムコードを提供する

## ミドルウェア構成

### データベース

本プロジェクトはCLIツール（モジュールバンドラー）であり、データベースは使用しない。

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| メモリキャッシュ（`MemoryCachePlugin`） | 内蔵 | developmentモードでのインメモリビルドキャッシュ | コンパイラインスタンスのライフタイム |
| メモリキャッシュ+GC（`MemoryWithGcCachePlugin`） | 内蔵 | GC対応のメモリキャッシュ（世代管理による自動解放） | 設定可能（世代ベース） |
| ファイルキャッシュ（`IdleFileCachePlugin` + `PackFileCacheStrategy`） | 内蔵 | productionモードでのファイルシステムベースの永続キャッシュ | ビルド間で永続化（バージョンとビルド依存関係による無効化） |
| リゾルバキャッシュ（`ResolverCachePlugin`） | 内蔵 | モジュール解決結果のキャッシュ | コンパイル単位 |

### メッセージキュー

本プロジェクトはメッセージキューを使用しない。内部的には `AsyncQueue`（`lib/util/AsyncQueue.js`）が非同期処理のキューイングを担っている。

### 検索エンジン

該当なし。

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| watchpack | ^2.5.1 | ファイルシステム監視（incremental build / watchモード） |
| enhanced-resolve | ^5.20.0 | モジュールパス解決（Node.js互換のresolveアルゴリズム拡張版） |
| loader-runner | ^4.3.1 | webpackローダーの実行エンジン |

## データフロー

### リクエスト処理の流れ

webpackのコンパイルパイプラインの処理フローを以下に示す。

1. **エントリーポイント**: `webpack(options)` が呼ばれ、`createCompiler` が実行される
2. **オプション正規化**: `getNormalizedWebpackOptions` でユーザ設定を内部形式に正規化する
3. **デフォルト適用**: `applyWebpackOptionsBaseDefaults` と `applyWebpackOptionsDefaults` でデフォルト値を適用する
4. **Compiler生成**: `new Compiler(context, options)` でCompilerインスタンスを生成する
5. **環境プラグイン適用**: `NodeEnvironmentPlugin` でファイルシステム関連の環境を構築する
6. **ユーザプラグイン適用**: `options.plugins` に指定された各プラグインの `apply` メソッドを呼び出す
7. **WebpackOptionsApply**: 設定値に基づいて内部プラグイン群（JavascriptModulesPlugin, HarmonyModulesPlugin, CommonJsPlugin, 最適化プラグイン群等）を適用する
8. **compiler.run()**: コンパイルを開始する
   - `beforeRun` フック -> `run` フック
   - `readRecords` でレコードを読み込む
9. **compile()**: `Compilation` インスタンスを生成する
   - `NormalModuleFactory`, `ContextModuleFactory` を生成する
   - `beforeCompile` -> `compile` -> `make` フックを発火する
10. **モジュールビルド（make）**: エントリーポイントから再帰的にモジュールをビルドする
    - `addEntry` でエントリーモジュールを追加する
    - `NormalModuleFactory.create` でモジュールを生成する
    - ローダーを実行してソースコードを変換する
    - `JavascriptParser` でASTを解析し、依存関係を抽出する
    - 依存モジュールを再帰的に処理する（`AsyncQueue` で並行処理）
11. **チャンクグラフ構築**: `buildChunkGraph` で `ModuleGraph` を元に `ChunkGraph` を構築する
    - エントリーポイントからチャンクグループを形成する
    - 動的importで新たなチャンクを分割する
12. **最適化**: 各種最適化プラグインが実行される
    - Tree Shaking (`FlagDependencyExportsPlugin`, `FlagDependencyUsagePlugin`)
    - コード分割 (`SplitChunksPlugin`)
    - スコープホイスティング (`ModuleConcatenationPlugin`)
    - サイドエフェクト分析 (`SideEffectsFlagPlugin`)
13. **コード生成**: 各モジュールのコードを生成する
    - `JavascriptGenerator` 等がモジュールごとのコードを生成する
    - `RuntimeModule` がランタイムコードを生成する
14. **ハッシュ計算**: コンテンツハッシュを計算し、ファイル名を確定する
15. **アセット出力**: `emitAssets` でバンドルファイルをファイルシステムに書き込む
16. **完了**: `done` フックを発火し、`Stats` オブジェクトを返す

### 非同期処理の流れ

webpackのビルドプロセスにおける非同期処理は以下の仕組みで管理される。

1. **AsyncQueue** (`lib/util/AsyncQueue.js`): モジュールの追加・ビルド・コード生成を並行処理するキューイングシステム。`parallelism` パラメータで同時処理数を制御する
2. **neo-async**: コールバックベースの非同期制御フロー。`parallel`、`forEach`、`each` 等のパターンで並列/逐次処理を実現する
3. **tapableフック**: `AsyncSeriesHook`, `AsyncParallelHook`, `AsyncSeriesBailHook` 等による非同期プラグインフックチェーン
4. **Watchモード** (`lib/Watching.js`): `watchpack`を使用してファイルシステムの変更を監視し、incremental rebuildをトリガーする
5. **Lazy Compilation** (`lib/hmr/LazyCompilationPlugin.js`): 実験的機能として、エントリーやインポートを遅延コンパイルする

### データ永続化の流れ

1. **ファイルキャッシュ**: `PackFileCacheStrategy` がシリアライゼーション層（`ObjectMiddleware` -> `BinaryMiddleware` -> `FileMiddleware`）を経由して、ビルドキャッシュをファイルシステムに永続化する
2. **レコード**: `RecordIdsPlugin` がモジュールID/チャンクIDの割り当て情報をJSON形式で保存し、ビルド間のID安定性を保証する
3. **マニフェスト**: `ManifestPlugin` がビルド成果物のマニフェスト（ファイル名マッピング）をJSON形式で出力する

## 横断的関心事

### 認証・認可

本プロジェクトはCLIツールであり、認証・認可の仕組みは該当しない。

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| ビルドログ | `lib/logging/Logger.js` (`WebpackLogger`クラス) | コンソール出力（`createConsoleLogger`で構成） |
| 進捗ログ | `lib/ProgressPlugin.js` | コンソール出力（パーセンテージ表示、フェーズ情報） |
| プロファイリング | `lib/debug/ProfilingPlugin.js` | chrome-trace-eventフォーマットのJSONファイル |
| 統計レポート | `lib/Stats.js` + `lib/stats/DefaultStatsFactoryPlugin.js` | `Stats` オブジェクトとして返却（JSON/文字列出力可能） |

ロギングレベルは `error`, `warn`, `info`, `log`, `debug`, `trace` の6段階が定義されている（`lib/logging/Logger.js`の`LogType`）。

### エラーハンドリング

webpackのエラーハンドリングは階層的に構成されている。

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| 設定バリデーションエラー | `schema-utils`による`ValidationError` | プロセス終了（エラーメッセージにスキーマ違反の詳細を含む） |
| モジュールビルドエラー | `ModuleBuildError` としてキャプチャ | `Compilation.errors`に蓄積。ビルドは継続し、Stats経由で報告 |
| モジュール未発見エラー | `ModuleNotFoundError` としてキャプチャ | `Compilation.errors`に蓄積。解決候補の提案を含む |
| モジュール依存エラー | `ModuleDependencyError` / `ModuleDependencyWarning` | `Compilation.errors`/`warnings`に蓄積 |
| パースエラー | `ModuleParseError` としてキャプチャ | ソース位置情報付きのエラーメッセージ |
| コード生成エラー | `CodeGenerationError` としてキャプチャ | `Compilation.errors`に蓄積 |
| チャンク描画エラー | `ChunkRenderError` としてキャプチャ | `Compilation.errors`に蓄積 |
| プラグインフックエラー | `HookWebpackError` で`WebpackError`にラップ | フック名とプラグイン情報を付加してエラー伝播 |
| 並行コンパイルエラー | `ConcurrentCompilationError` | 同時コンパイル検出時に即座にエラーを返す |
| 致命的エラー | Node.jsプロセスエラーとして伝播 | コールバック経由でユーザに通知 |

全てのwebpack固有エラーは `WebpackError` (`lib/WebpackError.js`) を基底クラスとして継承しており、`hideStack` プロパティによるスタックトレース表示制御をサポートする。

### トランザクション管理

本プロジェクトはデータベースを使用しないため、伝統的なトランザクション管理は該当しない。ただし、以下のアトミック性を保証する仕組みが存在する。

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| ファイル出力 | `Compiler.emitAssets` でアセット出力をバッチ処理 | 全アセットの出力完了後に`afterEmit`フックを発火 |
| キャッシュ永続化 | `PackFileCacheStrategy` がシリアライズをアイドル時に実行 | `Cache.beginIdle` / `Cache.endIdle` フックで排他制御 |
| Watchモード | `Watching` が無効化タイマーでデバウンスし、rebuild中の変更を次回に持ち越し | `invalid` / `watchRun` フックによる状態管理 |

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| プラグインアーキテクチャ（OCP） | 全体 | tapableフックによる拡張ポイント。`Compiler`, `Compilation`等が多数のフックを公開し、プラグインが処理を追加できる |
| ファクトリーパターン | モジュール生成 | `NormalModuleFactory`, `ContextModuleFactory`, `DllModuleFactory`等がモジュールの生成責務を担う |
| テンプレートメソッドパターン | モジュール型 | `Module`基底クラスが`build`, `codeGeneration`等のインターフェースを定義し、`NormalModule`, `ExternalModule`等が実装する |
| 遅延ロード（Lazy Loading） | エントリーポイント | `lib/index.js`で全ての公開クラスをgetterとして定義し、初回アクセス時にのみrequireする。`memoize`でキャッシュする |
| 依存性逆転（DIP） | ファイルシステム | `InputFileSystem`, `OutputFileSystem`, `IntermediateFileSystem`インターフェースを通じてファイルシステムを抽象化する |
| イベント駆動 | コンパイルパイプライン | tapableの各種フック（Sync/Async, Series/Parallel, Bail/Waterfall）でパイプライン各フェーズの処理を制御する |
| グラフデータ構造 | 依存関係管理 | `ModuleGraph`と`ChunkGraph`による双方向グラフで、モジュール間・チャンク間の関係を管理する |
| Visitorパターン | AST走査 | `JavascriptParser`がacorn ASTを走査し、各ノード型に対応するフック（expression, statement等）を発火する |
| Serializerパターン | キャッシュ永続化 | `Serializer` -> `ObjectMiddleware` -> `BinaryMiddleware` -> `FileMiddleware` のチェーンでオブジェクトをシリアライズする |

### コーディング規約

- **言語**: JavaScript (CommonJS形式)。TypeScriptの型はJSDocアノテーションで記述する
- **型チェック**: `tsconfig.json` で `allowJs: true` / `checkJs: true` を有効化し、JSDocベースの型チェックを行う
- **ターゲット**: ES2017 (Node.js >= 10.13.0)
- **フォーマット**: Prettier (`prettierrc.js`) による自動フォーマット
- **リント**: ESLint (`eslint.config.mjs`) による静的解析。`eslint-config-webpack`を使用
- **スペルチェック**: cspell (`cspell.json`) によるスペルチェック
- **テスト**: Jest (`jest.config.js`) による単体テスト・統合テスト
- **コミットフック**: Husky + lint-stagedによるコミット前チェック
- **ライセンス**: MIT License。各ファイル先頭にライセンスヘッダーを記載する
- **`"use strict"`**: 全ファイルで `"use strict"` を宣言する
- **クラス名定数**: 各プラグインクラスで `CLASS_NAME` 定数を定義し、プラグインの識別に使用する

## 備考

- webpackはバージョン5系であり、内部的にCommonJS (`require`/`module.exports`) を使用しているが、ビルド対象としてはESM (import/export)、CommonJS、AMDの全てをサポートする
- `experiments` オプションにより、CSS対応、WebAssembly対応、Module Federation、Lazy Compilation、HTTP URIインポート等の実験的機能が有効化できる
- `lib/index.js`のエクスポートは全てgetter（遅延ロード）で定義されており、必要なモジュールのみがメモリにロードされる設計となっている
- 依存関係モジュール (`lib/dependencies/`) は120ファイル以上と非常に多く、各モジュールシステム（CommonJS, ESM, AMD）の各種構文に対応したDependencyクラスとParserPluginクラスの組み合わせで構成される
- ランタイムモジュール (`lib/runtime/`) は30ファイル以上あり、バンドル実行時に必要なランタイムコード（モジュールロード、チャンクロード、公開API等）を提供する
