# Vue.js Core (vuejs/core) コードリーディングガイドライン

## はじめに

このガイドラインは、Vue.js 3 のコアリポジトリ（`vuejs/core`）のコードベースを効率的に理解するための手引きです。
TypeScript に精通していないエンジニアでも、段階的に学習できるよう構成されています。

**対象読者:**
- プロジェクトに新規参画するエンジニア
- 他言語からの経験者
- コードレビューを行う担当者

---

## 1. 言語基礎

> このセクションでは、TypeScript の基本構文と概念を解説します。

### 1.1 プログラム構造

Vue.js Core は **TypeScript** で記述されており、ESModules（`import`/`export`）を標準的なモジュールシステムとして使用しています。各ファイルは単一の責務を持つモジュールとして構成され、`export` によって公開APIを定義します。

```typescript
// ファイル: packages/vue/src/index.ts:1-8
import { initDev } from './dev'
import {
  type CompilerError,
  type CompilerOptions,
  compile,
} from '@vue/compiler-dom'
```

- `import` 文でモジュールを読み込む
- `type` キーワード付きインポートは型情報のみ（実行時には消える）
- `export * from '...'` で再エクスポートし、パッケージの公開APIを構成する

### 1.2 データ型と変数

TypeScript では型注釈と型推論の両方を使えます。このプロジェクトでは以下のパターンが頻出します。

**インターフェース（interface）:**
```typescript
// ファイル: packages/reactivity/src/ref.ts:28-37
export interface Ref<T = any, S = T> {
  get value(): T
  set value(_: S)
  [RefSymbol]: true   // ユニークシンボルによる型識別
}
```

**列挙型（enum）:**
```typescript
// ファイル: packages/compiler-core/src/ast.ts:29-61
export enum NodeTypes {
  ROOT,
  ELEMENT,
  TEXT,
  COMMENT,
  SIMPLE_EXPRESSION,
  INTERPOLATION,
  // ...
}
```

**型エイリアス（type）:**
```typescript
// ファイル: packages/reactivity/src/effect.ts:8
export type EffectScheduler = (...args: any[]) => any
```

**ジェネリクス（Generics）:**
```typescript
// ファイル: packages/reactivity/src/ref.ts:58-60
export function ref<T>(
  value: T,
): [T] extends [Ref] ? IfAny<T, Ref<T>, T> : Ref<UnwrapRef<T>, UnwrapRef<T> | T>
```

`<T>` は型パラメータで、関数やクラスを任意の型で汎用的に使えるようにする仕組みです。

### 1.3 制御構造

TypeScript/JavaScript の標準的な制御構造（`if`/`else`, `for`, `switch`, `while`）に加え、本プロジェクトでは以下のパターンが多用されます。

**コンパイル時フラグによる条件分岐:**
```typescript
// ファイル: packages/vue/src/index.ts:24-26
if (__DEV__) {
  initDev()
}
```

`__DEV__`, `__BROWSER__`, `__SSR__` 等のグローバルフラグはビルド時に `true`/`false` に置換され、プロダクションビルドではデッドコードとして削除されます。

**ビットフラグ操作:**
```typescript
// ファイル: packages/reactivity/src/effect.ts:41-53
export enum EffectFlags {
  ACTIVE = 1 << 0,       // 0b00000001
  RUNNING = 1 << 1,      // 0b00000010
  TRACKING = 1 << 2,     // 0b00000100
  NOTIFIED = 1 << 3,     // 0b00001000
  DIRTY = 1 << 4,        // 0b00010000
  ALLOW_RECURSE = 1 << 5,// 0b00100000
  PAUSED = 1 << 6,       // 0b01000000
}
```

ビットフラグは `|` で合成、`&` でチェックします。複数の状態を1つの数値で効率的に管理できます。

### 1.4 関数/メソッド定義

**関数オーバーロード:**
```typescript
// ファイル: packages/reactivity/src/ref.ts:45-48
export function isRef<T>(r: Ref<T> | unknown): r is Ref<T>
export function isRef(r: any): r is Ref {
  return r ? r[ReactiveFlags.IS_REF] === true : false
}
```

最初の行はシグネチャ（型定義のみ）、最後の行が実装です。`r is Ref` は**型ガード**で、`true` を返すと `r` が `Ref` 型として推論されます。

**クラス定義:**
```typescript
// ファイル: packages/reactivity/src/ref.ts:113-164
class RefImpl<T = any> {
  _value: T
  private _rawValue: T
  dep: Dep = new Dep()

  public readonly [ReactiveFlags.IS_REF] = true

  constructor(value: T, isShallow: boolean) {
    this._rawValue = isShallow ? value : toRaw(value)
    this._value = isShallow ? value : toReactive(value)
  }

  get value() {    // getter
    this.dep.track()
    return this._value
  }

  set value(newValue) {  // setter
    if (hasChanged(newValue, this._rawValue)) {
      this._rawValue = newValue
      this._value = toReactive(newValue)
      this.dep.trigger()
    }
  }
}
```

`get`/`set` はプロパティアクセサで、`obj.value` の読み書きをインターセプトします。

### 1.5 モジュール/インポート

```typescript
// 名前付きインポート
import { ref, reactive } from '@vue/reactivity'

// ワイルドカードインポート
import * as runtimeDom from '@vue/runtime-dom'

// 型のみインポート（ビルド時に消える）
import type { CompilerOptions } from './options'

// 再エクスポート
export * from '@vue/runtime-dom'
export { compileToFunction as compile }
```

パッケージ間の参照は `@vue/パッケージ名` というスコープ付きパッケージ名で行います。これは `tsconfig.json` の `paths` 設定で `packages/*/src` にマッピングされています（`tsconfig.json:16-19`）。

---

## 2. プロジェクト固有の概念

> このセクションでは、当プロジェクト特有の概念を解説します。

### 2.1 フレームワーク固有の概念

Vue.js Core は **UIフレームワーク自体のソースコード** であるため、以下の固有概念を理解する必要があります。

**リアクティビティシステム:**
- `ref()` / `reactive()` でリアクティブなデータを生成
- `Dep`（依存）と `Subscriber`（購読者）の双方向連結リストで依存関係を追跡
- `Proxy` オブジェクトでプロパティアクセスをインターセプト

```typescript
// ファイル: packages/reactivity/src/reactive.ts:26-35
export const reactiveMap: WeakMap<Target, any> = new WeakMap<Target, any>()
export const shallowReactiveMap: WeakMap<Target, any> = new WeakMap<Target, any>()
export const readonlyMap: WeakMap<Target, any> = new WeakMap<Target, any>()
```

WeakMap で元オブジェクト → Proxy のマッピングを管理し、同じオブジェクトに対して常に同一のProxyを返します。

**仮想DOM（VNode）:**
- テンプレートまたはrender関数から VNode ツリーを生成
- 差分検出（diff）で効率的にDOMを更新
- `PatchFlags` による最適化ヒントでdiff対象を限定

```typescript
// ファイル: packages/shared/src/patchFlags.ts:19-24
export enum PatchFlags {
  TEXT = 1,          // 動的テキスト
  CLASS = 1 << 1,   // 動的クラス
  STYLE = 1 << 2,   // 動的スタイル
  PROPS = 1 << 3,   // 動的プロパティ
}
```

**テンプレートコンパイラ:**
- `.vue` ファイルや `template` 文字列をパース → AST → 変換 → コード生成
- コンパイル時に最適化情報（PatchFlags, hoisting）を付加

### 2.2 プロジェクト独自のパターン

**コンパイル時フラグ（Feature Flags）:**

本プロジェクト最大の特徴は、グローバル定数フラグによるコンパイル時分岐です。

| フラグ | 意味 | 用途 |
|--------|------|------|
| `__DEV__` | 開発モード | 警告メッセージ、デバッグ情報 |
| `__TEST__` | テスト環境 | テスト専用のコードパス |
| `__BROWSER__` | ブラウザ環境 | ブラウザ固有の処理 |
| `__GLOBAL__` | グローバルビルド | `<script>` タグ直接読み込み用 |
| `__ESM_BUNDLER__` | ESMバンドラービルド | Webpack/Vite用 |
| `__SSR__` | SSRビルド | サーバーサイドレンダリング |
| `__COMPAT__` | Vue 2互換 | マイグレーション支援 |
| `__VERSION__` | バージョン文字列 | ランタイムバージョン情報 |

これらはRollupビルド時に実際の値に置換され、`__DEV__` のコードブロックはプロダクションビルドで完全に除去（tree-shaking）されます。

**プラットフォーム抽象化パターン:**

`runtime-core` はDOMに依存せず、`RendererOptions` インターフェースでDOM操作を抽象化しています。

```typescript
// ファイル: packages/runtime-core/src/renderer.ts（概念図）
// createRenderer() に RendererOptions を渡すことで、
// 任意のプラットフォーム（DOM, Canvas, Native等）に対応可能
```

`runtime-dom` が実際のDOM操作を提供し、`runtime-test` がテスト用の仮想DOMを提供します。

---

## 3. 命名規則

> このセクションでは、プロジェクト全体で使用される命名規則を解説します。

### 3.1 ファイル・ディレクトリ命名

| パターン | 意味 | 例 |
|---------|------|-----|
| `api*.ts` | Vue公開API | `apiCreateApp.ts`, `apiWatch.ts`, `apiLifecycle.ts` |
| `component*.ts` | コンポーネント関連の内部実装 | `component.ts`, `componentProps.ts`, `componentEmits.ts` |
| `v*.ts`（transforms配下） | ディレクティブ変換プラグイン | `vIf.ts`, `vFor.ts`, `vModel.ts`, `vOn.ts` |
| `transform*.ts` | 汎用AST変換プラグイン | `transformElement.ts`, `transformText.ts` |
| `*.spec.ts` | ユニットテスト | `ref.spec.ts`, `effect.spec.ts` |
| `*.bench.ts` | ベンチマーク | `apiWatch.bench.ts` |
| `__tests__/` | テストディレクトリ | 各パッケージ内の `__tests__/` |
| `src/` | ソースコードディレクトリ | 各パッケージ内の `src/` |
| パッケージ名 | `kebab-case` | `compiler-core`, `runtime-dom`, `server-renderer` |

### 3.2 クラス・関数・変数命名

| プレフィックス/サフィックス | 意味 | 例 |
|---------------------------|------|-----|
| `create*` | ファクトリ関数 | `createApp()`, `createVNode()`, `createRenderer()` |
| `is*` | 型ガード/判定関数 | `isRef()`, `isReactive()`, `isReadonly()` |
| `to*` | 変換関数 | `toRef()`, `toRaw()`, `toReactive()` |
| `on*` | イベントハンドラ/ライフサイクル | `onMounted()`, `onUpdated()` |
| `*Impl` | 内部実装クラス | `RefImpl`, `CustomRefImpl`, `ObjectRefImpl` |
| `*Options` | オプション型 | `CompilerOptions`, `ReactiveEffectOptions` |
| `_*` | 内部専用（非公開） | `_value`, `_rawValue`, `_rc` |
| `__*__` | コンパイル時フラグ | `__DEV__`, `__BROWSER__`, `__SSR__` |
| `UPPER_SNAKE_CASE` | 定数 | `EMPTY_OBJ`, `EMPTY_ARR`, `NOOP` |
| `PascalCase` | 型/インターフェース/enum | `NodeTypes`, `PatchFlags`, `EffectFlags` |
| `camelCase` | 関数/変数 | `compileToFunction`, `reactiveMap` |

### 3.3 プログラム分類一覧

| 分類 | 接頭辞/場所 | 説明 |
|------|-------------|------|
| コンパイラパッケージ | `compiler-*` | テンプレートをJavaScriptコードに変換 |
| ランタイムパッケージ | `runtime-*` | アプリケーション実行時の処理 |
| 共有ユーティリティ | `shared` | 全パッケージ共通のヘルパー |
| 統合エントリー | `vue` | npm配布用のまとめパッケージ |
| 互換レイヤー | `vue-compat` | Vue 2からの移行支援 |

---

## 4. ディレクトリ構造

> このセクションでは、プロジェクトのディレクトリ構造を解説します。

```
core-main/
├── .github/                    # CI/CDワークフロー、Issue テンプレート
├── changelogs/                 # バージョン別変更履歴
├── docs/                       # ドキュメント
├── packages/                   # 公開パッケージ群（本体）
│   ├── compiler-core/          # プラットフォーム非依存のコンパイラコア
│   │   ├── src/
│   │   │   ├── ast.ts          # ASTノード型定義
│   │   │   ├── parser.ts       # テンプレートパーサー
│   │   │   ├── tokenizer.ts    # トークナイザー
│   │   │   ├── transform.ts    # AST変換エンジン
│   │   │   ├── codegen.ts      # コード生成
│   │   │   ├── compile.ts      # コンパイルパイプライン統合
│   │   │   └── transforms/     # 個別の変換プラグイン
│   │   └── __tests__/
│   ├── compiler-dom/           # DOM用コンパイラ（compiler-coreの拡張）
│   ├── compiler-sfc/           # SFC (.vue) コンパイラ
│   ├── compiler-ssr/           # SSR用コンパイラ
│   ├── reactivity/             # リアクティビティシステム
│   │   ├── src/
│   │   │   ├── ref.ts          # ref() の実装
│   │   │   ├── reactive.ts     # reactive() の実装
│   │   │   ├── effect.ts       # エフェクト（副作用）管理
│   │   │   ├── computed.ts     # computed() の実装
│   │   │   ├── dep.ts          # 依存追跡（Dep/Link）
│   │   │   ├── watch.ts        # watch() の実装
│   │   │   └── effectScope.ts  # エフェクトスコープ
│   │   └── __tests__/
│   ├── runtime-core/           # プラットフォーム非依存のランタイムコア
│   │   ├── src/
│   │   │   ├── renderer.ts     # レンダラー（diff/patch）
│   │   │   ├── vnode.ts        # VNode定義・生成
│   │   │   ├── component.ts    # コンポーネントインスタンス管理
│   │   │   ├── scheduler.ts    # 非同期バッチスケジューラ
│   │   │   ├── apiCreateApp.ts # createApp() API
│   │   │   ├── apiWatch.ts     # watch/watchEffect API
│   │   │   └── helpers/        # ランタイムヘルパー
│   │   └── __tests__/
│   ├── runtime-dom/            # DOM用ランタイム
│   ├── runtime-test/           # テスト用ランタイム（仮想DOM）
│   ├── server-renderer/        # SSRレンダラー
│   ├── shared/                 # 全パッケージ共通ユーティリティ
│   ├── vue/                    # npm "vue" パッケージ（エントリーポイント）
│   └── vue-compat/             # Vue 2互換レイヤー
├── packages-private/           # 非公開パッケージ
│   ├── sfc-playground/         # ブラウザ上のSFC動作確認環境
│   ├── template-explorer/      # テンプレートコンパイル結果の可視化ツール
│   ├── dts-test/               # 型定義のテスト
│   └── vite-debug/             # Viteデバッグ環境
├── scripts/                    # ビルド・リリース用スクリプト
│   ├── build.js                # ビルドスクリプト
│   ├── dev.js                  # 開発用ウォッチ
│   ├── release.js              # リリーススクリプト
│   └── aliases.js              # パスエイリアス定義
├── package.json                # ルートpackage.json
├── pnpm-workspace.yaml         # pnpmワークスペース定義
├── rollup.config.js            # Rollupビルド設定
├── tsconfig.json               # TypeScript設定（開発用）
├── tsconfig.build.json         # TypeScript設定（ビルド用）
├── vitest.config.ts            # Vitest設定
└── eslint.config.js            # ESLint設定
```

### 各ディレクトリの役割

| ディレクトリ | 役割 | 主要ファイル |
|-------------|------|-------------|
| `packages/compiler-core/` | テンプレート → AST → JavaScript のコンパイルコア | `parser.ts`, `transform.ts`, `codegen.ts` |
| `packages/compiler-dom/` | DOM固有のコンパイル（イベント修飾子等） | `transforms/`, `parserOptions.ts` |
| `packages/compiler-sfc/` | `.vue` ファイルのパース・コンパイル | `parse.ts`, `compileScript.ts`, `compileTemplate.ts` |
| `packages/compiler-ssr/` | SSR向けコード生成 | `ssrCodegenTransform.ts` |
| `packages/reactivity/` | リアクティビティシステムの実装 | `ref.ts`, `reactive.ts`, `effect.ts` |
| `packages/runtime-core/` | プラットフォーム非依存のランタイム | `renderer.ts`, `vnode.ts`, `component.ts` |
| `packages/runtime-dom/` | DOM用のレンダラーオプション実装 | `nodeOps.ts`, `patchProp.ts`, `modules/` |
| `packages/shared/` | 共通ユーティリティ・定数 | `patchFlags.ts`, `shapeFlags.ts`, `general.ts` |
| `packages/vue/` | エントリーポイント（コンパイラ＋ランタイム統合） | `src/index.ts`, `src/runtime.ts` |
| `scripts/` | ビルド・開発・リリース用スクリプト | `build.js`, `dev.js`, `release.js` |

---

## 5. アーキテクチャ

> このセクションでは、プロジェクトのアーキテクチャパターンを解説します。

### 5.1 全体アーキテクチャ

Vue.js Core は**モノレポ構成のモジュラーアーキテクチャ**を採用しています。11個の公開パッケージが明確な依存階層を持ち、各パッケージは単一の責務を担います。

```mermaid
graph TD
    vue["vue<br/>(エントリーポイント)"]

    vue --> runtime-dom["@vue/runtime-dom<br/>(DOM用ランタイム)"]
    vue --> compiler-dom["@vue/compiler-dom<br/>(DOM用コンパイラ)"]
    vue --> compiler-sfc["@vue/compiler-sfc<br/>(SFCコンパイラ)"]
    vue --> server-renderer["@vue/server-renderer<br/>(SSRレンダラー)"]

    runtime-dom --> runtime-core["@vue/runtime-core<br/>(ランタイムコア)"]
    compiler-dom --> compiler-core["@vue/compiler-core<br/>(コンパイラコア)"]
    compiler-sfc --> compiler-core
    compiler-sfc --> compiler-dom

    runtime-core --> reactivity["@vue/reactivity<br/>(リアクティビティ)"]
    runtime-core --> shared["@vue/shared<br/>(共通ユーティリティ)"]
    reactivity --> shared
    compiler-core --> shared
```

設計の原則:
- **コア（`*-core`）** はプラットフォーム非依存
- **DOM固有（`*-dom`）** はブラウザ環境に特化
- **依存は常に上→下**（循環依存なし）
- `shared` が最下層で全パッケージから参照可能

### 5.2 レイヤー構成

| レイヤー | 責務 | 代表的なファイル |
|---------|------|-----------------|
| エントリー | パッケージ統合、公開API | `packages/vue/src/index.ts` |
| コンパイラ | テンプレート → JavaScript変換 | `packages/compiler-core/src/compile.ts` |
| ランタイム | VNode diff/patch、コンポーネント管理 | `packages/runtime-core/src/renderer.ts` |
| リアクティビティ | データの変更追跡・通知 | `packages/reactivity/src/effect.ts` |
| プラットフォーム | DOM操作の具体的実装 | `packages/runtime-dom/src/nodeOps.ts` |
| 共通 | ユーティリティ関数・定数 | `packages/shared/src/general.ts` |

### 5.3 データフロー

**テンプレートからDOMへの流れ:**

```
1. テンプレート文字列
   ↓ baseParse() [compiler-core/src/parser.ts]
2. AST (Abstract Syntax Tree)
   ↓ transform() [compiler-core/src/transform.ts]
3. 最適化済みAST（PatchFlags付き）
   ↓ generate() [compiler-core/src/codegen.ts]
4. JavaScript コード（render関数）
   ↓ new Function(code) [vue/src/index.ts:94-96]
5. RenderFunction
   ↓ renderer.render() [runtime-core/src/renderer.ts]
6. VNode ツリー
   ↓ patch() [runtime-core/src/renderer.ts]
7. 実DOMの作成・更新
```

**リアクティブデータの変更通知フロー:**

```
1. ref.value = newValue (setter呼び出し)
   ↓ [reactivity/src/ref.ts:141-163]
2. dep.trigger() (依存通知)
   ↓ [reactivity/src/dep.ts]
3. subscriber.notify() (エフェクト通知)
   ↓ [reactivity/src/effect.ts]
4. queueJob() (ジョブキューに追加)
   ↓ [runtime-core/src/scheduler.ts:43-44]
5. nextTick で非同期フラッシュ
   ↓ [runtime-core/src/scheduler.ts:50-51]
6. コンポーネント再レンダリング → patch()
```

---

## 6. 主要コンポーネント

> このセクションでは、主要なコンポーネントとその連携を解説します。

### 6.1 エントリーポイント

アプリケーションのエントリーポイントは `packages/vue/src/index.ts` です。このファイルはコンパイラとランタイムを統合し、`compileToFunction` を登録します。

```typescript
// ファイル: packages/vue/src/index.ts:30-46
function compileToFunction(
  template: string | HTMLElement,
  options?: CompilerOptions,
): RenderFunction {
  if (!isString(template)) {
    if (template.nodeType) {
      template = template.innerHTML
    } else {
      __DEV__ && warn(`invalid template option: `, template)
      return NOOP
    }
  }

  const key = genCacheKey(template, options)
  const cached = compileCache[key]
  if (cached) {
    return cached
  }
  // ...
}
```

ランタイム専用ビルドは `packages/vue/src/runtime.ts` が使われ、コンパイラを含みません（ビルドツールが事前にコンパイルする前提）。

### 6.2 ビジネスロジック

Vue.js Core の中核的ビジネスロジックは**リアクティビティシステム**と**レンダラー**です。

**リアクティビティ - ref の実装:**
```typescript
// ファイル: packages/reactivity/src/ref.ts:103-107
function createRef(rawValue: unknown, shallow: boolean) {
  if (isRef(rawValue)) {
    return rawValue
  }
  return new RefImpl(rawValue, shallow)
}
```

`ref()` は `createRef()` に委譲し、`RefImpl` クラスのインスタンスを生成します。`RefImpl` の `get value()` / `set value()` アクセサが依存追跡と変更通知を行います。

**コンパイルパイプライン:**
```typescript
// ファイル: packages/compiler-core/src/compile.ts:67-122
export function baseCompile(
  source: string | RootNode,
  options: CompilerOptions = {},
): CodegenResult {
  // 1. パース
  const ast = isString(source) ? baseParse(source, resolvedOptions) : source
  // 2. 変換プラグインの取得
  const [nodeTransforms, directiveTransforms] =
    getBaseTransformPreset(prefixIdentifiers)
  // 3. AST変換
  transform(ast, { nodeTransforms, directiveTransforms })
  // 4. コード生成
  return generate(ast, resolvedOptions)
}
```

### 6.3 データアクセス

Vue.js Core はデータベースを持たないUIフレームワークですが、**リアクティブデータの管理**がデータアクセス層に相当します。

```typescript
// ファイル: packages/reactivity/src/reactive.ts:26-35
export const reactiveMap: WeakMap<Target, any> = new WeakMap<Target, any>()
export const shallowReactiveMap: WeakMap<Target, any> = new WeakMap<Target, any>()
export const readonlyMap: WeakMap<Target, any> = new WeakMap<Target, any>()
export const shallowReadonlyMap: WeakMap<Target, any> = new WeakMap<Target, any>()
```

4つの `WeakMap` で元オブジェクトとProxy のマッピングを管理し、各リアクティビティモード（deep/shallow × mutable/readonly）をサポートします。`WeakMap` を使うことで、元オブジェクトがガベージコレクションされるとProxyも自動的に回収されます。

### 6.4 ユーティリティ/共通機能

`packages/shared/` パッケージが全パッケージ共通のユーティリティを提供します。

```typescript
// ファイル: packages/shared/src/patchFlags.ts:19-24（一部）
export enum PatchFlags {
  TEXT = 1,              // 動的テキストコンテンツ
  CLASS = 1 << 1,        // 動的クラスバインディング
  STYLE = 1 << 2,        // 動的スタイル
  PROPS = 1 << 3,        // 動的プロパティ
  FULL_PROPS = 1 << 4,   // 動的キーのプロパティ
  CACHED = -1,           // 静的キャッシュVNode
  BAIL = -2,             // 最適化モードから脱出
}
```

`PatchFlags` はコンパイラが生成するVNodeに付与する最適化ヒントで、ランタイムのdiffアルゴリズムが高速パスを選択する際に使用されます。

**スケジューラ:**
```typescript
// ファイル: packages/runtime-core/src/scheduler.ts:43-53
const queue: SchedulerJob[] = []
let flushIndex = -1

const pendingPostFlushCbs: SchedulerJob[] = []
let activePostFlushCbs: SchedulerJob[] | null = null

const resolvedPromise = /*@__PURE__*/ Promise.resolve() as Promise<any>
let currentFlushPromise: Promise<void> | null = null

const RECURSION_LIMIT = 100
```

スケジューラは `Promise.resolve()` を使ったマイクロタスクベースの非同期バッチ処理で、同一Tickの複数の状態変更を1回のDOM更新にまとめます。

---

## 7. よく使われるパターン

> このセクションでは、コード内で頻出するパターンを解説します。

### パターン一覧

| パターン | 説明 | 出現頻度 | 代表的なファイル |
|---------|------|---------|-----------------|
| コンパイル時フラグ分岐 | `__DEV__` 等によるビルド時条件分岐 | 高 | 全パッケージ |
| ビットフラグ | ビット演算による複数状態の効率的管理 | 高 | `patchFlags.ts`, `effect.ts`, `scheduler.ts` |
| Proxy + WeakMap | オブジェクトのインターセプトと管理 | 高 | `reactive.ts`, `baseHandlers.ts` |
| 関数オーバーロード | TypeScriptの型安全なAPI設計 | 中 | `ref.ts`, `apiWatch.ts` |
| ファクトリパターン | `create*` 関数によるオブジェクト生成 | 中 | `apiCreateApp.ts`, `renderer.ts`, `vnode.ts` |
| Tree-shaking注釈 | `/*@__PURE__*/`, `/*@__NO_SIDE_EFFECTS__*/` | 中 | 全パッケージ |

### 各パターンの詳細

#### パターン1: コンパイル時フラグ分岐

**目的:** プロダクションビルドからデバッグコードを完全に除去し、バンドルサイズを最小化する

**実装例:**
```typescript
// ファイル: packages/vue/src/index.ts:24-26
if (__DEV__) {
  initDev()
}
```

```typescript
// ファイル: packages/reactivity/src/ref.ts:129-137
get value() {
  if (__DEV__) {
    this.dep.track({
      target: this,
      type: TrackOpTypes.GET,
      key: 'value',
    })
  } else {
    this.dep.track()
  }
  return this._value
}
```

**解説:** `__DEV__` ブロック内のコードはプロダクションビルドで `if (false) { ... }` に置換され、ミニファイア（terser/SWC）がデッドコードとして削除します。開発モードではデバッグ用の詳細情報（追跡対象やオペレーション種類）を付加します。

#### パターン2: ビットフラグパターン

**目的:** 複数の真偽値状態を1つの整数で効率的に管理し、メモリとCPUを節約する

**実装例:**
```typescript
// ファイル: packages/reactivity/src/effect.ts:41-53
export enum EffectFlags {
  ACTIVE = 1 << 0,       // 1
  RUNNING = 1 << 1,      // 2
  TRACKING = 1 << 2,     // 4
  NOTIFIED = 1 << 3,     // 8
  DIRTY = 1 << 4,        // 16
  ALLOW_RECURSE = 1 << 5,// 32
  PAUSED = 1 << 6,       // 64
  EVALUATED = 1 << 7,    // 128
}
```

**解説:** 各フラグは2のべき乗で定義されるため、ビット演算で複数の状態を同時に管理できます。`flags |= ACTIVE` でフラグをセット、`flags & DIRTY` でチェック、`flags &= ~PAUSED` でクリアします。

#### パターン3: Tree-shaking 注釈

**目的:** バンドラーに副作用がないことを伝え、未使用コードの除去を促進する

**実装例:**
```typescript
// ファイル: packages/reactivity/src/ref.ts:46-47
/*@__NO_SIDE_EFFECTS__*/
export function isRef(r: any): r is Ref {
  return r ? r[ReactiveFlags.IS_REF] === true : false
}
```

```typescript
// ファイル: packages/runtime-core/src/scheduler.ts:50
const resolvedPromise = /*@__PURE__*/ Promise.resolve() as Promise<any>
```

**解説:** `/*@__PURE__*/` は「この式に副作用がない」、`/*@__NO_SIDE_EFFECTS__*/` は「この関数の呼び出しは副作用がない」ことをバンドラーに伝えます。使用されていない場合、バンドラーが安全にコードを除去できます。

---

## 8. 業務フロー追跡の実践例

> このセクションでは、実際の業務フローをコードで追跡する方法を解説します。

### 8.1 フロー追跡の基本手順

1. エントリーポイントを特定
2. 処理の流れを追跡（呼び出し関係を追う）
3. データの変換を確認
4. 最終的な出力を確認

### 8.2 フロー追跡の実例

#### 例1: テンプレートコンパイルフロー

**概要:** テンプレート文字列が render関数に変換されるまでの流れ

**処理フロー:**
```
compileToFunction() → compile() → baseCompile() → baseParse() → transform() → generate() → new Function()
```

**詳細な追跡:**

1. **エントリー: compileToFunction** (`packages/vue/src/index.ts:30-101`)
   ```typescript
   function compileToFunction(
     template: string | HTMLElement,
     options?: CompilerOptions,
   ): RenderFunction {
     // HTMLElementならinnerHTMLを取得
     if (!isString(template)) {
       if (template.nodeType) {
         template = template.innerHTML
       }
     }
     // キャッシュヒットチェック
     const key = genCacheKey(template, options)
     const cached = compileCache[key]
     if (cached) return cached
   ```

2. **コンパイル実行: baseCompile** (`packages/compiler-core/src/compile.ts:67-122`)
   ```typescript
   export function baseCompile(source: string | RootNode, options = {}): CodegenResult {
     // パース: テンプレート文字列 → AST
     const ast = isString(source) ? baseParse(source, resolvedOptions) : source
     // 変換プリセットの取得
     const [nodeTransforms, directiveTransforms] = getBaseTransformPreset(prefixIdentifiers)
     // AST変換: 最適化情報の付加
     transform(ast, { nodeTransforms, directiveTransforms })
     // コード生成: AST → JavaScript文字列
     return generate(ast, resolvedOptions)
   }
   ```

3. **変換プリセット: getBaseTransformPreset** (`packages/compiler-core/src/compile.ts:32-63`)
   ```typescript
   export function getBaseTransformPreset(prefixIdentifiers?: boolean): TransformPreset {
     return [
       [
         transformVBindShorthand, transformOnce, transformIf,
         transformMemo, transformFor,
         transformSlotOutlet, transformElement,
         trackSlotScopes, transformText,
       ],
       { on: transformOn, bind: transformBind, model: transformModel },
     ]
   }
   ```

4. **render関数の生成** (`packages/vue/src/index.ts:94-96`)
   ```typescript
   const render = (
     __GLOBAL__ ? new Function(code)() : new Function('Vue', code)(runtimeDom)
   ) as RenderFunction
   ```

#### 例2: ref の値変更 → DOM更新フロー

**概要:** `ref.value` を更新した際にDOMが更新されるまでの流れ

**処理フロー:**
```
ref.value = x → RefImpl.set → dep.trigger() → subscriber.notify() → queueJob() → nextTick → patch()
```

**詳細な追跡:**

1. **値のセット** (`packages/reactivity/src/ref.ts:141-163`)
   ```typescript
   set value(newValue) {
     const oldValue = this._rawValue
     newValue = useDirectValue ? newValue : toRaw(newValue)
     if (hasChanged(newValue, oldValue)) {
       this._rawValue = newValue
       this._value = useDirectValue ? newValue : toReactive(newValue)
       this.dep.trigger()  // 依存通知
     }
   }
   ```

2. **スケジューラへのジョブ追加** (`packages/runtime-core/src/scheduler.ts:43-44`)
   ```typescript
   const queue: SchedulerJob[] = []
   // queueJob() でコンポーネント更新ジョブをキューに追加
   ```

3. **非同期バッチフラッシュ** (`packages/runtime-core/src/scheduler.ts:50-51`)
   ```typescript
   const resolvedPromise = /*@__PURE__*/ Promise.resolve() as Promise<any>
   // Promise.resolve().then() でマイクロタスクとしてフラッシュ
   ```

### 8.3 フロー追跡チェックリスト

- [ ] エントリーポイント (`packages/vue/src/index.ts`) を特定したか
- [ ] パッケージ間の呼び出し関係を把握したか（`vue` → `runtime-dom` → `runtime-core` → `reactivity`）
- [ ] データの変換ポイントを確認したか（テンプレート → AST → JavaScript → VNode → DOM）
- [ ] `__DEV__` ブロック内のデバッグ専用コードを識別したか
- [ ] エラーハンドリング（`warn()`, `onError`）のパスを確認したか
- [ ] 最終的な出力（DOM更新 or エラーメッセージ）を確認したか

---

## 9. 設計書の参照順序

> このセクションでは、プロジェクト理解のための設計書参照順序を案内します。

### 9.1 目的別ロードマップ

#### 全体像を把握したい場合
1. `docs/code-to-docs/README.md` - プロジェクト概要
2. `docs/code-to-docs/アーキテクチャ設計書/` - 全体アーキテクチャ
3. `docs/code-to-docs/機能一覧/` - 機能の全容

#### 特定機能を理解したい場合
1. `docs/code-to-docs/機能一覧/` - 対象機能の特定
2. `docs/code-to-docs/機能設計書/` - 機能の詳細設計
3. 対象パッケージのソースコード（`packages/*/src/`）

#### リアクティビティシステムを理解したい場合
1. `packages/reactivity/src/ref.ts` - Ref の実装
2. `packages/reactivity/src/reactive.ts` - Reactive の実装
3. `packages/reactivity/src/effect.ts` - エフェクトシステム
4. `packages/reactivity/src/dep.ts` - 依存追跡

#### コンパイラを理解したい場合
1. `packages/compiler-core/src/compile.ts` - パイプライン全体
2. `packages/compiler-core/src/parser.ts` - テンプレートパーサー
3. `packages/compiler-core/src/ast.ts` - AST定義
4. `packages/compiler-core/src/transform.ts` - 変換エンジン
5. `packages/compiler-core/src/codegen.ts` - コード生成

#### 改修作業を行う場合
1. 対象機能の設計書（`docs/code-to-docs/機能設計書/`）
2. 対象パッケージの `__tests__/` でテストケースを確認
3. `docs/code-to-docs/単体テストケース一覧/` で影響範囲を確認

### 9.2 ドキュメント一覧

| ドキュメント | 概要 | 参照タイミング |
|-------------|------|---------------|
| `README.md` | プロジェクト概要・セットアップ | 最初に参照 |
| `アーキテクチャ設計書/` | 全体アーキテクチャ・パッケージ構成 | 全体理解時 |
| `機能一覧/` | 全機能の概要 | 機能探索時 |
| `機能設計書/` | 各機能の詳細設計 | 特定機能の理解時 |
| `API設計書/` | 公開API仕様 | API利用・改修時 |
| `データベース設計書/` | データ構造（リアクティブデータ管理） | データ層の理解時 |
| `セキュリティ設計書/` | セキュリティ考慮事項 | セキュリティレビュー時 |
| `テスト方針書/` | テスト戦略・方針 | テスト作成時 |
| `単体テストケース一覧/` | 各モジュールのテストケース | テスト確認・改修時 |
| `画面設計書/` | UI関連の設計 | フロントエンド改修時 |

---

## 10. トラブルシューティング

> このセクションでは、コードリーディング時によくある問題と解決法を解説します。

### よくある疑問と回答

#### Q: `__DEV__` が未定義としてエラーになる
A: `__DEV__` はコンパイル時に置換されるグローバル定数です。IDE上では `vitest.config.ts` の `define` 設定で値が提供されます。直接実行する場合は `vitest` 経由でテストを実行してください。

#### Q: `@vue/reactivity` のインポートパスが解決できない
A: `tsconfig.json:16-19` の `paths` 設定で `@vue/*` が `packages/*/src` にマッピングされています。IDE のTypeScript言語サーバーがこの設定を認識していることを確認してください。

#### Q: `/*@__PURE__*/` や `/*@__NO_SIDE_EFFECTS__*/` コメントの意味がわからない
A: バンドラー（Rollup/webpack）に対する tree-shaking ヒントです。副作用がないことを示し、未使用の場合にコードを安全に除去できます。実行時の動作には影響しません。

#### Q: テストの実行方法がわからない
A: `vitest.config.ts` で3つのプロジェクト（`unit`, `unit-jsdom`, `e2e`）に分割されています。`pnpm test` でユニットテスト、`pnpm test-e2e` でE2Eテストが実行されます。特定ファイルのテストは `pnpm vitest packages/reactivity/__tests__/ref.spec.ts` のように指定します。

#### Q: enum の数値が `1 << N` で定義されている理由は？
A: ビットフラグパターンです。各値がビット位置で一意になるため、ビット演算（`|` で合成、`&` で判定）で複数フラグを効率的に管理できます。例: `flags = ACTIVE | DIRTY` で2つの状態を同時にセットします。

### デバッグのヒント

- **`packages-private/template-explorer/`** を使うと、テンプレートがどのようなJavaScriptコードにコンパイルされるかをブラウザ上で確認できます
- **テストから理解する:** 各パッケージの `__tests__/` ディレクトリにあるテストは、そのモジュールの動作仕様を示す最良のドキュメントです
- **`__DEV__` ブロック内の `warn()` メッセージ** は、エラー状態の理解に非常に有用です
- **`pnpm-workspace.yaml` の `catalog`** で全パッケージの依存バージョンが一元管理されています

---

## 付録

### A. 用語集

| 用語 | 説明 |
|-----|------|
| VNode | Virtual Node（仮想DOMノード）。実DOMの軽量な表現 |
| AST | Abstract Syntax Tree。テンプレートをパースした構文木 |
| SFC | Single File Component。`.vue` ファイル形式 |
| SSR | Server-Side Rendering。サーバーサイドレンダリング |
| Reactivity | データの変更を自動的に検出・伝播する仕組み |
| Ref | `ref()` で生成されるリアクティブな値のラッパー |
| Reactive | `reactive()` で生成されるリアクティブなProxy |
| Effect | リアクティブデータに依存する副作用（再レンダリングやwatch等） |
| Dep | Dependency。リアクティブデータに紐づく依存関係の追跡単位 |
| PatchFlags | VNodeに付与されるdiff最適化ヒント |
| ShapeFlags | VNodeの種類を示すビットフラグ |
| Tree-shaking | 未使用コードをバンドルから除去する最適化 |
| Hoisting | 静的コンテンツをrender関数外に巻き上げる最適化 |
| Hydration | SSRで生成したHTMLにクライアントサイドのリアクティビティを付与する処理 |
| Scheduler | コンポーネント更新を非同期バッチ処理するスケジューラ |
| nextTick | 現在の更新バッチが完了した後に実行されるコールバック |

### B. ファイル一覧

| ファイル/ディレクトリ | 説明 | 主な内容 |
|---------------------|------|---------|
| `packages/vue/src/index.ts` | フルビルドエントリーポイント | コンパイラ+ランタイム統合 |
| `packages/vue/src/runtime.ts` | ランタイム専用エントリーポイント | コンパイラなし |
| `packages/reactivity/src/ref.ts` | ref() の実装 | RefImpl, isRef, toRef, unref |
| `packages/reactivity/src/reactive.ts` | reactive() の実装 | Proxy生成, WeakMapキャッシュ |
| `packages/reactivity/src/effect.ts` | エフェクトシステム | ReactiveEffect, EffectFlags |
| `packages/reactivity/src/dep.ts` | 依存追跡 | Dep, Link（双方向連結リスト） |
| `packages/reactivity/src/computed.ts` | computed() の実装 | 遅延評価, キャッシュ |
| `packages/compiler-core/src/compile.ts` | コンパイルパイプライン | baseCompile, getBaseTransformPreset |
| `packages/compiler-core/src/parser.ts` | テンプレートパーサー | baseParse |
| `packages/compiler-core/src/ast.ts` | AST型定義 | NodeTypes, ElementTypes |
| `packages/compiler-core/src/transform.ts` | AST変換エンジン | transform, TransformContext |
| `packages/compiler-core/src/codegen.ts` | コード生成 | generate, CodegenResult |
| `packages/runtime-core/src/renderer.ts` | レンダラー | createRenderer, patch |
| `packages/runtime-core/src/vnode.ts` | VNode定義 | createVNode, VNodeTypes |
| `packages/runtime-core/src/component.ts` | コンポーネント管理 | ComponentInternalInstance |
| `packages/runtime-core/src/scheduler.ts` | スケジューラ | queueJob, nextTick |
| `packages/runtime-core/src/apiCreateApp.ts` | createApp API | App interface |
| `packages/shared/src/patchFlags.ts` | PatchFlags定数 | diff最適化ヒント |
| `packages/shared/src/shapeFlags.ts` | ShapeFlags定数 | VNode種類フラグ |
| `rollup.config.js` | Rollupビルド設定 | 7種類の出力フォーマット |
| `vitest.config.ts` | Vitest設定 | unit/unit-jsdom/e2eプロジェクト |
| `tsconfig.json` | TypeScript設定 | パスエイリアス, strict mode |

### C. 参考資料

- [Vue.js 公式ドキュメント](https://vuejs.org/)
- [TypeScript ハンドブック](https://www.typescriptlang.org/docs/handbook/)
- [Rollup 公式ドキュメント](https://rollupjs.org/)
- [Vitest 公式ドキュメント](https://vitest.dev/)
- [pnpm ワークスペース](https://pnpm.io/workspaces)
- [Vue.js Core Contributing Guide](https://github.com/vuejs/core/blob/main/.github/contributing.md)
