reference-compiler-cli

Angular Compiler CLI（ngtsc）のアーキテクチャ

概要

packages/compiler-cli パッケージには、Angular Compiler（Ivy）が含まれており、一般に ngtsc と呼ばれています。これは TypeScript コンパイラー（tsc）をラップし、Angular 固有の機能を拡張するものです。

ngtsc の主な目的は、Angular デコレーター（@Component、@Directive、@Pipe など）を、クラス上の静的プロパティ（Ivy 命令、例：static ɵcmp = ...）にコンパイルすることです。また、テンプレートの型チェックと事前（AOT）コンパイルも行います。

メンタルモデル

このコンパイラーは、遅延型、インクリメンタル、部分的なコンパイルパイプラインとして設計されています。

1. ラッパーパターン：NgtscProgram は標準の ts.Program をラップします。標準のツールをそのまま置き換えられるよう、呼び出しをインターセプトします。
2. Trait システム：Angular デコレーターを持つすべてのクラスは「Trait」として扱われます。コンパイラーは、次の状態を持つステートマシンでこれらの Trait を管理します。
   • Pending：検出済みですが、未処理です。
   • Analyzed：メタデータが抽出され、テンプレートが解析されています（ただし、依存関係はまだリンクされていません）。
   • Resolved：依存関係（テンプレート内のディレクティブ／パイプ）が解決され、インポートの循環が処理されています。
   • Skipped：Angular クラスではありません。
3. 遅延分析：分析は必要な場合にのみ行われます（診断が要求されたときや、出力の準備が行われるときなど）。
4. 出力 AST：コンパイラーは、生成コード用の中間的な「出力 AST」（o.Expression）を生成します。出力フェーズでは、これが TypeScript AST ノードに変換されます。

主なサブシステム

1. コアのオーケストレーション（ngtsc/core）

• NgtscProgram：api.Program を実装する公開 API です。ts.Program と NgCompiler を管理します。
• NgCompiler：コンパイラーの中核です。コンパイルフェーズ（分析、解決、型チェック、出力）を統括します。TraitCompiler を保持します。

2. Trait のコンパイル（ngtsc/transform）

• TraitCompiler：「Trait」のライフサイクルを管理します。ソースファイルを反復処理し、デコレーター付きクラスを識別して、適切な DecoratorHandler に処理を委譲します。
• Trait：クラスの状態を保持するコンテナーで、ハンドラー、分析結果、解決結果を格納します。

3. デコレーターのハンドラー（ngtsc/annotations）

• DecoratorHandler：特定のデコレーターを処理するためのインターフェースです。
• ComponentDecoratorHandler：最も複雑なハンドラーです。次の処理を行います。
  • メタデータ（セレクター、入力、出力）を抽出します。
  • テンプレートを解析します。
  • 使用されているディレクティブとパイプを解決します（R3TargetBinder）。
  • ɵcmp 命令を生成します。
• DirectiveDecoratorHandler、PipeDecoratorHandler、NgModuleDecoratorHandler：それぞれ対応するデコレーターを処理します。

4. テンプレートの型チェック（ngtsc/typecheck）

• TemplateTypeChecker：「型チェックブロック」（TCB）を生成します。TCB は、tsc が理解してエラーをチェックできる形式でテンプレートのロジックを表す TypeScript コードのブロックです。
• generateTypeCheckBlock（@angular/compiler から提供され、TypeCheckFile と InlineTcbOp から呼び出されます）：テンプレートのバインディング、イベント、ディレクティブの使用、ホストバインディングをチェックするための TypeScript ソースを生成します。

5. メタデータとスコープ（ngtsc/metadata、ngtsc/scope）

• MetadataReader：ソースファイル（LocalMetadataRegistry を使用）および .d.ts ファイル（DtsMetadataReader を使用）から Angular メタデータを読み取ります。
• ComponentScopeReader：NgModule の推移的なエクスポートとスタンドアロンコンポーネントのインポートを処理し、コンポーネントの「コンパイルスコープ」（そのコンポーネントで使用できるディレクティブ／パイプ）を特定します。

6. 出力と変換（ngtsc/transform）

• ivyTransformFactory：TypeScript トランスフォーマーファクトリーです。
• IvyCompilationVisitor：クラスを訪問し、TraitCompiler を介してコンパイルを実行し、出力 AST を収集します。
• IvyTransformationVisitor：出力 AST を TypeScript AST に変換し、static ɵ... フィールドを挿入して、元のデコレーターを削除します。

コンパイルのフェーズ

1. 構築：NgtscProgram が NgCompiler を作成し、すべてのレジストリと TraitCompiler を初期化します。
2. 解析（analyzeSync）：
   • TraitCompiler がファイルをスキャンします。
   • DecoratorHandler がメタデータを抽出し、テンプレートを解析します。
   • ここではファイル間の解決は行われません（並列処理とキャッシュを可能にするためです）。
3. 解決（resolve）：
   • TraitCompiler がトレイトを解決します。
   • コンポーネントはテンプレートを特定のディレクティブとパイプにリンクします（ComponentScopeReader を通じて検出します）。
   • インポートの循環依存を検出して処理します（「リモートスコーピング」など）。
4. 型チェック：
   • TemplateTypeChecker がすべてのコンポーネントの TCB を作成します。
   • これらの TCB に関する TypeScript の診断情報を取得します。
5. 出力（prepareEmit）：
   • ivyTransformFactory を作成します。
   • TS の emit を呼び出します。
   • トランスフォーマーが実行され、コンパイルされた Ivy 命令を JS／DTS 出力に挿入します。

重要なファイルの場所

• packages/compiler-cli/src/ngtsc/program.ts：エントリーポイント（NgtscProgram）。
• packages/compiler-cli/src/ngtsc/core/src/compiler.ts：コアロジック（NgCompiler）。
• packages/compiler-cli/src/ngtsc/transform/src/trait.ts：トレイトの状態機械。
• packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts：コンポーネントのコンパイルロジック。
• packages/compiler-cli/src/ngtsc/typecheck/src/checker.ts：型チェックのロジック（TemplateTypeCheckerImpl）。
• packages/compiler-cli/src/ngtsc/transform/src/transform.ts：AST 変換ロジック。