A more flexible parse endpoint in the TransparentCompiler

[nojaf]

Is your feature request related to a problem? Please describe.

Currently, the new transparent compiler endpoint for parsing a file does not accommodate all the scenarios we're interested in.

At present, we have:

    /// <summary>
    /// Parses the source code of a file and caches the results. Returns an AST that can be traversed for various features.
    /// </summary>
    ///
    /// <param name="fileName">The file path. The file name serves as a module name for implicit top-level modules (e.g., in scripts).</param>
    /// <param name="sourceText">The source code to be parsed.</param>
    /// <param name="options">Parsing options for the project or script.</param>
    /// <param name="cache">Stores the parse in a size-limited cache associated with the FSharpChecker. Default: true.</param>
    /// <param name="userOpName">An optional string for tracing compiler operations related to this request.</param>
    member ParseFile:
        fileName: string * sourceText: ISourceText * options: FSharpParsingOptions * ?cache: bool * ?userOpName: string ->
            Async<FSharpParseFileResults>

    [<Experimental("This FCS API is experimental and subject to change.")>]
    member ParseFile:
        fileName: string * projectSnapshot: FSharpProjectSnapshot * ?userOpName: string -> Async<FSharpParseFileResults>

    /// <summary>
    /// Parses the source code of a file. Returns an AST for feature traversal.
    /// </summary>
    ///
    /// <param name="fileName">The file path. The file name is also used as a module name for implicit top-level modules (e.g., in scripts).</param>
    /// <param name="source">The source code to be parsed.</param>
    /// <param name="options">Parsing options for the project or script.</param>
    /// <param name="cache">Stores the parse in a size-limited cache associated with the FSharpChecker. Default: true.</param>
    /// <param name="userOpName">An optional string for tracing compiler operations related to this request.</param>
    [<Obsolete("Please use checker.ParseFile instead. This requires passing FSharpParsingOptions instead of FSharpProjectOptions. If needed, generate FSharpParsingOptions from FSharpProjectOptions by calling checker.GetParsingOptionsFromProjectOptions(options).")>]
    member ParseFileInProject:
        fileName: string * source: string * options: FSharpProjectOptions * ?cache: bool * ?userOpName: string ->
            Async<FSharpParseFileResults>

The ParseFile endpoint accepting fileName and ISourceText is only available in the old BackgroundCompiler. To phase out the BackgroundCompiler, this functionality needs to be implemented in the new TransparentCompiler.

Describe the solution you'd like

From Rider's perspective, parsing typically occurs in three scenarios:

• Parsing the current file in a project when opening a file.
• Parsing sample source code in a sandbox for code actions/quick fixes before inserting code.
• Parsing the current file and inserting an additional identifier at the cursor position to predict potential syntax tree changes and user input. It's crucial that this parsing is cached separately from the file/project cache to ensure the results are not mistakenly reused for ParseAndCheckResults, as they would not be accurate.

Given FileA.fs in ProjectB.fsproj, the following calls should be feasible:

• ParseFileInProject(FileA.fs, snapshotB) (cache result reusable for ParseAndCheck)
• ParseFile(FileA-bis.fs, ISourceTextNew, ParsingOptions) (cache result for FileA with an extra identifier)
• ParseSourceText(ISourceTextNew, isSignature, ParsingOptions) (do not cache)

ParseFile and ParseSourceText could potentially merge into a single API, with a boolean parameter to indicate caching preference.

//cc @auduchinok (Please correct me if I misunderstood anything).
//cc @0101

Describe alternatives you've considered

I don't think we can do all of this purely with the TransparentCompiler. Or at the very least, it would today invoke the background compiler.