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 是一段 TypeScript 代码，用于以 tsc 能够理解并检查错误的方式表示模板逻辑。
• 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 解析各个 trait。
   • 组件会将模板关联到特定的指令和管道（通过 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：Trait 状态机。
• 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 转换逻辑。