[api] Add createIncrementalProgram

[Andrew Branch (andrewbranch)]

Part of #63875

This is kind of an interesting one. In an incremental program, emitting is a state-changing operation, so this is modeled as a snapshot change:

using program = api.createIncrementalProgram(rootFiles, options);
const { snapshot, program, ...emitResult } = program.emit();
// returns new snapshot and incremental program along with the emit result
snapshot.dispose();

This was mostly Copilot with a few high-level conceptual corrections from me; implementation still needs a closer review from me.

[Titian Cernicova-Dragomir (dragomirtitian)]

Trying to integrate this in our build tool. One small issue, createIncrementalProgram does not take a VFS. I worked around this by using createSnapshot directly, but createIncrementalProgram call setOwnedSnapshot on the program, which is internal, so probably this isn't a good way to o it long term.

[Andrew Branch (andrewbranch)]

Can you elaborate on the issue? That sounds right to me. A VFS isn't a property of a program, it's something you can apply to a snapshot, and then any programs of any kind you add to that snapshot will use the VFS. api.createIncrementalProgram is just a convenience method to be used when you don't need to interact with the snapshot directly. The setOwnedProgram path makes it so you can dispose the snapshot by disposing the program, since we know from api.createIncrementalProgram or api.createProgram that there's exactly one Program in the Snapshot and we never gave you a direct handle to the Snapshot itself, so you need a way to dispose it. If you use createSnapshot or snapshot.update, you should dispose the Snapshot directly.

[Andrew Branch (andrewbranch)]

I guess you could argue that since using an incremental program usually involves changing its state by emitting, the convenience method that gives you the program directly without the snapshot makes it kind of confusing... you really need to know how to manage a snapshot if you're going to use an incremental program.

[Titian Cernicova-Dragomir (dragomirtitian)]

I guess you could argue that since using an incremental program usually involves changing its state by emitting, the convenience method that gives you the program directly without the snapshot makes it kind of confusing... you really need to know how to manage a snapshot if you're going to use an incremental program.

If we can manage the snapshot ourselves then that is fine I guess. It's juts that the convenience method is of no use to us, but it might be of use to others who don't need to apply a VFS on the snapshot.

[Titian Cernicova-Dragomir (dragomirtitian)]

I tested our build tool with the changes in this PR. Shape of the API works for us. Everything seems to work.

[Andrew Branch (andrewbranch)]

Great! Do you see performance improvements over using non-incremental programs?