ngcc config file
===

While ngcc attempts to understand a wide variety of compiled Angular packages, there are occasions when it is not possible to infer the format or setup of a package.

This document proposes a method to configure ngcc so that it can process such packages.

## Problem Scenarios

### 1) Missing entry-point markers

See https://angular-team.atlassian.net/browse/FW-1299

* **primeng**: clients use deep imports such as `primeng/breadcrumb` and these do not have entry-point packages.json files; so no `typings` or other "format" properties.

### 2) Unwanted entry-points

See https://angular-team.atlassian.net/browse/FW-1223 and https://github.com/angular/angular/issues/29703

* **ng2-dragula**: has two copies of package.json and ng2-dragular.metadata.json which both point to the same source files. So ngcc tries to compile the source twice.

### 3) Dynamic source files

Some packages compute which source file to use based on compile time options.
For example, NativeScript. We need to e able to provide a custom file resolver to
ngcc that knows where to find such dynamic source file.

## Proposed Design

Customize ngcc processing by values found in one or more configuration files.

The configuration files can be published at the root of the package to be customized or provided by the consumer of a package in an application project.

### Config file Format

The config will be provided by executable JS files, similar to that used in karma and rollupjs.
This allows the developer to generate configuration programmatically or to import configuration or helper functions from other files.

**File name**: ngcc.config.js

**Structure**:
The configuration files will export an object that contains the configuration.

The format leaves room for adding other kinds of configuration, at the top level, the package level and the entry-point level.

### Package Level Config

The configuration file will exist adjacent to the `package.json` of the primary entry-point. It will only configure ngcc for the entry-points of this package.

This level of configuration can be provided by a library author if they know that there are aspects of their entry-points that ngcc will not understand but cannot/will not be fixed in the package itself.

interface NgccPackageConfig {
  entryPoints: {
    [relativeEntryPointPath: string]: NgccEntryPointConfig;
  }
}

interface NgccEntryPointConfig {
  /**
   * If true then ngcc should pretend that this
   * entry-point does not exist and so not attempt
   * to process it or use it in dependency resolution.
   */
  ignore?: boolean = false;

  /**
   * Properties from the package.json file to override.
   * For example, paths to the associated format files for this
   * entry-point.
   */
  override?: PackageJsonFormatProperties;
   [formatProperty: NgccEntryPointFormatProperty]?: string;
   
  /**
   * A function used to resolve an import to a file.
   /*
  resolve?: NgccImportResolverFunction;
}

### Project Level Config

The configuration file will exist adjacent to the `package.json` of the application project. It will configure ngcc for any packages (and their entry-points) that ngcc may attempt to process for this project.

This level of configuration can be provided by an application developer if they know that there are entry-points in imported packages that ngcc will not understand.

Configuration at this project level will override the configuration of a package at the package level.

interface NgccProjectConfig {
  packages: {
    [packagePath: string]: NgccPackageConfig;
  }
}

### Examples

**Project level config file:**

export = {
  packages: {
    "ng2-dragula": {
      entryPoints: {
        "./dist": {
          "ignore": true
        },
        ...
      }
    },
    "other": {
      entry-points: {
        ... 
      }
    },
    ...
  }
}

**Package level config file:**

{
  entryPoints: {
    "./inputtext": {
      "typings": "./inputtext.d.ts",
      "main": "./inputtest.js"
    },
    "./button": {
      "typings": "./button.d.ts",
      "main": "./button.js"
    },
    ...
  }
}

## Implementation

The following tasks will need to be completed:

1) Modify `mainNgcc` to load a project level configuration file.
2) Modify `EntryPointFinder` to load package level configuration files.
3) Modify `EntryPointFinder.findEntryPoints()` to skip entry-points marked with `ignore`.
4) Modify `getEntryPointInfo()`:
a) ignore missing `metadata.json` if configuration is provided.
b) use configured `typings` property if provided.
c) add configured "format" properties to `EntryPoint.packageJson` object
5) Change build-marker implementation to be able to store (and retrieve) build-marker information for entry-points that have no `package.json`.