Reference Compiler CliCAUTION

Deliver web apps with confidence 🚀

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: reference-compiler-cli
description: 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`
---

# Angular Compiler CLI (`ngtsc`) Architecture

## Overview

The `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.

## Mental Model

The compiler is designed as a **lazy, incremental, and partial** compilation pipeline.

1.  **Wrapper Pattern**: `NgtscProgram` wraps the standard `ts.Program`. It intercepts calls to act as a drop-in replacement for standard tooling.
2.  **Traits System**: Every class with an Angular decorator is considered a "Trait". The compiler manages the state of these traits through a state machine:
    - **Pending**: Detected but not processed.
    - **Analyzed**: Metadata extracted, template parsed (but dependencies not yet linked).
    - **Resolved**: Dependencies (directives/pipes in template) resolved, import cycles handled.
    - **Skipped**: Not an Angular class.
3.  **Lazy Analysis**: Analysis only happens when necessary (e.g., when diagnostics are requested or emit is prepared).
4.  **Output AST**: The compiler generates an intermediate "Output AST" (`o.Expression`) for the generated code, which is then translated into TypeScript AST nodes during the emit phase.

## Key Subsystems

### 1. Core Orchestration (`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`.

### 2. Trait Compilation (`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.

### 3. Decorator Handlers (`ngtsc/annotations`)

- **`DecoratorHandler`**: An interface for handling specific decorators.
- **`ComponentDecoratorHandler`**: The most complex handler. It:
  - Extracts metadata (selector, inputs, outputs).
  - Parses the template.
  - Resolves used directives and pipes (`R3TargetBinder`).
  - Generates the `ɵcmp` instruction.
- **`DirectiveDecoratorHandler`**, **`PipeDecoratorHandler`**, **`NgModuleDecoratorHandler`**: Handle their respective decorators.

### 4. Template Type Checking (`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.
- **`generateTypeCheckBlock`** (from `@angular/compiler`, called by `TypeCheckFile` and `InlineTcbOp`): Generates TypeScript source for checking template bindings, events, directive usage, and host bindings.

### 5. Metadata & Scope (`ngtsc/metadata`, `ngtsc/scope`)

- **`MetadataReader`**: Reads Angular metadata from source files (using `LocalMetadataRegistry`) and `.d.ts` files (using `DtsMetadataReader`).
- **`ComponentScopeReader`**: Determines the "compilation scope" of a component (which directives/pipes are available to it), handling `NgModule` transitive exports and Standalone Component imports.

### 6. Emit & Transformation (`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.

## Compilation Phases

1.  **Construction**: `NgtscProgram` creates `NgCompiler`, which sets up all registries and the `TraitCompiler`.
2.  **Analysis** (`analyzeSync`):
    - The `TraitCompiler` scans files.
    - `DecoratorHandler`s extract metadata and parse templates.
    - No cross-file resolution happens here (allowing for parallelism and caching).
3.  **Resolution** (`resolve`):
    - `TraitCompiler` resolves traits.
    - Components link their templates to specific Directives and Pipes (found via `ComponentScopeReader`).
    - Import cycles are detected and handled (e.g., via "remote scoping").
4.  **Type Checking**:
    - `TemplateTypeChecker` creates TCBs for all components.
    - TypeScript diagnostics are retrieved for these TCBs.
5.  **Emit** (`prepareEmit`):
    - `ivyTransformFactory` is created.
    - TS `emit` is called.
    - The transformers run, injecting the compiled Ivy instructions into the JS/DTS output.

## Important File Locations

- `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/checker.ts`: Type checking logic (`TemplateTypeCheckerImpl`).
- `packages/compiler-cli/src/ngtsc/transform/src/transform.ts`: AST transformation logic.

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

You MUST use this skill any time you plan to work with code in `packages/compiler-cli`

.agent/rules/agents.md

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Reference Compiler Cli](https://modelsatlas.com/skills/angular/reference-compiler-cli/badge.svg)](https://modelsatlas.com/skills/angular/reference-compiler-cli/)

Not your listing, or something out of date? Claim or update your listing.