Index of every page on this site: llms.txt
All skills
angular avatar

/reference-compiler-cli

@ee18d57
by angularangular/angular101k stars
28,193
Run it yourself

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`

Use this Skill: https://skilld.dev/gh/angular/angular/reference-compiler-cli

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈49 tokens for metadata: the name and description. ≈1.4k when used: this file.

Description uses 2.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈197 characters, or 2.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.
    • DecoratorHandlers 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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill is a documentation-only resource providing an architectural overview of the Angular Compiler CLI (ngtsc). It contains no executable code, network operations, or sensitive data access.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer9mo

    1 file scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at ee18d57. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago

README badge

README badge for angular/angular/reference-compiler-cli