# ngcc schematics

This document discusses schematic support in ngcc, in the context of the [undecorated classes migration](https://hackmd.io/sfb3Ju2MTmKHSUiX_dLWGg), although it should be applicable to other kinds of migrations as well. The primary goal is to design a mechanism for ngcc to apply these transformations to a library as it processes it.

## Requirements

The two migrations described in the plan give rise to several requirements of ngcc:

1) ngcc must be able to recognize faulty inheritance patterns:
* decorated directives/components which inherit their constructors from undecorated classes
* undecorated classes which inherit from decorated directives/components

2) ngcc must be able to apply the mitigations in the plan. In practice this means:
* for undecorated base classes, ngcc must pretend as if an `@Directive()` annotation was added to the base class.
* for undecorated derived classes, ngcc must pretend as if an `@Directive()` or `@Component()` with associated selector and potentially template/styles was present.

In practice, this means that ngcc needs to be able to "inject" decorators into the program before compilation. This means that certain classes which are not natively decorated will need to be treated as such by the rest of the compiler. Moreover, to know which classes need to be annotated (and the metadata for those annotations), ngcc needs to be able to examine the decorated classes and their metadata. This means they should already be analyzed by the time ngcc is trying to make this decision.

## Background

ngcc uses the same flow as ngtsc for the compilation of a package:

1) Detect phase: each class is examined separately for Angular decorators.

2) Analysis phase: each detected decorator is analyzed on its class, and metadata about that class recorded for later compilation. During this phase, only information from each individual class is available.

3) Resolve phase: the whole program is analyzed together, and metadata about individual classes can be updated with more global information if need be (for example, the directives/pipes used in a component template).

4) Emit/compile: during TypeScript emit, a transformer patches any new Ivy definitions onto classes just before they're emitted.

This flow is managed in ngcc by the `DecorationAnalyzer` class.

## Design

The `DecorationAnalyzer` will execute a "migration" phase between the "analysis" and "resolve" phases which will iterate through each of a set of configured `Migration` instances asking each to attempt to migrate each class in each file in the program.

...
const analysedFiles = this.program.getSourceFiles()
                          .filter(sourceFile => isWithinPackage(this.packagePath, sourceFile))
                          .map(sourceFile => this.analyzeFile(sourceFile))
                          .filter(isDefined);
analysedFiles.forEach(analysedFile => this.migrateFile(analysedFile));
analysedFiles.forEach(analysedFile => this.resolveFile(analysedFile));
...

protected migrateFile(analyzedFile: AnalyzedFile): void {
  analyzedFile.analyzedClasses.forEach(({declaration}) => {
    this.migrations.forEach(migration => {
      const result = migration.apply(declaration, this.migrationHost);
      if (result !== null) {
        this.errorHandler(result);
      }
    });
  });
}

### Migrations

A `Migration` is any class that implements an interface:

interface Migration {
  apply(clazz: ClassDeclaration, host: MigrationHost): ts.Diagnostic[]|null;
}

A new instance of each `Migration` should be created for each entry-point, as migrations may be stateful (e.g. to avoid decorating the same class twice). A `DecorationAnalyzer` is created for each entry-point, so it makes sense for the migrations to have the same life-time, i.e. migrations are owned by the `DecorationAnalyzer`. This is the same as for the `DecorationHandler` instances currently.

The `MigrationHost` provides a limited environment via which migrations can interact with the rest of the compilation. This enforces that migrations don't get too crazy in terms of mutating compilation state, which will allow a broader set of authors to write them without needing to understand compiler internals and code formats.

interface MigrationHost {
  metadata: MetadataReader;
  evaluator: PartialEvaluator;
  host: ReflectionHost;
  injectSyntheticDecorator(clazz: ClassDeclaration, decorator: Decorator);
}

The `metadata` property provides access to the component/directive/pipe metadata of classes in the program, while the `host` and `evaluator` provide abstractions to reflect over and evaluate expressions in the context of the program.

A new instance of the `MigrationHost` will be created for each `DecorationAnalyzer`, similar to the life-time of the `Migration` instances.

### Injecting decorators

The `MigrationHost` also provides a method to associate a synthesized decorator with a class in the program. The implementation will attempt to get each `DecoratorHandler` in the `DecoratorAnalyzer` to handle the given `clazz` + `decorator` combination:

  injectSyntheticDecorator(clazz: ClassDeclaration, decorator: Decorator): void {
    for (const handler of this.handlers) {
      if (handler.detect(clazz, [decorator])) {
        handler.analyze(clazz, decorator);
      }
    }
  }

This requires that the `Migration` can create a synthetic `Decorator`, which means constructing `ts.Node`s for the decorator information. Since these nodes have to survive the `PartialEvaluator`, this forces some restrictions:

* synthetic nodes cannot reference newly declared (or imported) identifiers (since the `ts.TypeChecker` won't know about them).
* synthetic nodes cannot be used in a context where a source mapping to the original TS is required (this will make use of synthetic nodes for `template` challenging).

:::warning
Should we provide a method to create synthesized decorators that removes some of the underlying complexity from the `Migration` author?
:::

The result of calling `injectSyntheticDecorator()` is that the `MetadataReader` (used in the "resolve" and "compile" phases) will show this new decorator associated with the specified class.

### Failure handling

In the event a migration fails, it can return `ts.Diagnostic`s describing the problem. Depending on configuration, ngcc can either ignore these failures or surface them to the user as errors or warnings.

### Overall flow

In between `IvyCompilation.analyzeSync()` and `IvyCompilation.resolve()`, ngcc will iterate over the program and for each compatible class, call each `Migration`'s `apply()`.