Explains the mental model and architecture of the code under `packages/compiler-cli`. You MUST use this skill any time you plan to work with code in `packages/compiler-cli`
ngtsc) ArchitectureThe packages/compiler-cli package contains the Angular Compiler (Ivy), often referred to as ngtsc. It is a wrapper around the TypeScript compiler (tsc) that extends it with Angular-specific capabilities.
The core goal of ngtsc is to compile Angular decorators (like @Component, @Directive, @Pipe) into static properties on the class (Ivy instructions, e.g., static ɵcmp = ...). It also performs template type checking and ahead-of-time (AOT) compilation.
The compiler is designed as a lazy, incremental, and partial compilation pipeline.
NgtscProgram wraps the standard ts.Program. It intercepts calls to act as a drop-in replacement for standard tooling.o.Expression) for the generated code, which is then translated into TypeScript AST nodes during the emit phase.ngtsc/core)NgtscProgram: The public API implementing api.Program. It manages the ts.Program and the NgCompiler.NgCompiler: The brain of the compiler. It orchestrates the compilation phases (Analysis, Resolution, Type Checking, Emit). It holds the TraitCompiler.ngtsc/transform)TraitCompiler: Manages the lifecycle of "Traits". It iterates over source files, identifies decorated classes, and delegates to the appropriate DecoratorHandler.Trait: A state container for a class, holding its handler, analysis results, and resolution results.ngtsc/annotations)DecoratorHandler: An interface for handling specific decorators.ComponentDecoratorHandler: The most complex handler. It:
R3TargetBinder).ɵcmp instruction.DirectiveDecoratorHandler, PipeDecoratorHandler, NgModuleDecoratorHandler: Handle their respective decorators.ngtsc/typecheck)TemplateTypeChecker: Generates "Type Check Blocks" (TCBs). A TCB is a block of TypeScript code that represents the template's logic in a way tsc can understand and check for errors.TypeCheckBlock: The actual generated code that validates bindings, events, and structural directives.ngtsc/metadata, ngtsc/scope)MetadataReader: Reads Angular metadata from source files (using LocalMetadataRegistry) and .d.ts files (using DtsMetadataReader).ScopeRegistry: Determines the "compilation scope" of a component (which directives/pipes are available to it), handling NgModule transitive exports and Standalone Component imports.ngtsc/transform)ivyTransformFactory: A TypeScript transformer factory.IvyCompilationVisitor: Visits classes, triggers compilation via TraitCompiler, and collects the Output AST.IvyTransformationVisitor: Translates the Output AST into TypeScript AST, injects the static ɵ... fields, and removes the original decorators.NgtscProgram creates NgCompiler, which sets up all registries and the TraitCompiler.analyzeSync):
TraitCompiler scans files.DecoratorHandlers extract metadata and parse templates.resolve):
TraitCompiler resolves traits.ScopeRegistry).TemplateTypeChecker creates TCBs for all components.prepareEmit):
ivyTransformFactory is created.emit is called.packages/compiler-cli/src/ngtsc/program.ts: Entry point (NgtscProgram).packages/compiler-cli/src/ngtsc/core/src/compiler.ts: Core logic (NgCompiler).packages/compiler-cli/src/ngtsc/transform/src/trait.ts: Trait state machine.packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts: Component compilation logic.packages/compiler-cli/src/ngtsc/typecheck/src/template_type_checker.ts: Type checking logic.packages/compiler-cli/src/ngtsc/transform/src/transform.ts: AST transformation logic.