Api for tsc --build and --incremental

[sheetalkamat]

This PR provides api for tooling to use build and incremental options:
TypeStrong/ts-loader#935 shows use of --build api

Solution Builder

Two functions createSolutionBuilder and createSolutionBuilderWithWatch provide a way to create SolutionBuilder for given root projects, and build options. The only difference in later is that it also watches the projects for changes to be able to build.

interface SolutionBuilder<T extends BuilderProgram> {
    build(project?: string, cancellationToken?: CancellationToken): ExitStatus;
    clean(project?: string): ExitStatus;
    buildReferences(project: string, cancellationToken?: CancellationToken): ExitStatus;
    cleanReferences(project?: string): ExitStatus;
    getNextInvalidatedProject(cancellationToken?: CancellationToken): InvalidatedProject<T> | undefined;
}

build and clean provide a compact way of building/cleaning all root projects provided or project mentioned (including their references).
getNextInvalidatedProject is the API for more granular level operations on each project. This function will give you a project that needs to be either built or needs to update output because prepend changed or just needs update timestamps. When done method of the returned project is called, it ensures all actions are taken place and its ready to move to next project so that next call to getNextInvalidatedProject will return you next project that's invalid or undefined if the build is complete.

Incremental Builder Program

createIncrementalProgram and createIncrementalCompilerHost are methods similar to createProgram and createCompilerHost to build the incremental builder program.
This also exposes readBuilderProgram provides a way to be able to create the EmitAndSemanticDiagnosticsBuilder from the .tsbuildinfo for the compiler options. Note that this is special program that is readonly version and it can only be used as oldProgram to create new builder program.

[manucorporat]

@sheetalkamat could this API be used from a Language Service createLanguageService?

[sheetalkamat]

@manucorporat Sorry I missed your question earlier. I am not sure what you mean by createLanguageService. This is the api for compiling the programs like tsc --b or tsc --incremental.

[mihailik]

It looks like these APIs either allow fine-granular acccess with getNextInvalidatedProject, or support watching.

In order to trigger the watching behaviour one needs to call solutionBuilder.build() which does not support custom transformers.

However, not all is lost. It is possible to sneak transformers in by using createProgram callback, inside which you can patch program.emit() method with your own code, calling the original emit(...) with extra transformers added.

Here is a simple example on Stack Overflow:

https://stackoverflow.com/questions/62026189/typescript-custom-transformers-with-ts-createwatchprogram/62027253