Add an overload of CSharpSyntaxTree.Create that allows to specify checksum algorithm

[tmat]

Background and Motivation

The existing API always used SourceHashAlgorithm.Sha1 but the IDE needs to be able to create parsed syntax trees backed by text with specific checksum algorithm.

See #62840 for the change, including usage in the IDE.

Proposed API

class CSharpSyntaxTree
{
  public SyntaxTree Create(
   CSharpSyntaxNode root,
   CSharpParseOptions? options = null,
   string? path = "",
   Encoding? encoding = null);

+ public SyntaxTree Create(
+   CSharpSyntaxNode root,
+   CSharpParseOptions? options = null,
+   string? path = "",
+   Encoding? encoding = null, 
+   SourceHashAlgorithm checksumAlgorithm = SourceHashAlgorithm.Sha1);
)

In addition, similarly to SyntaxTree.Encoding make checksum algorithm available from SyntaxTree instance:

class SyntaxTree
{
+ public abstract SourceHashAlgorithm ChecksumAlgorithm { get; }
}

and add a factory method to SyntaxFactory:

class SyntaxFactory
{
- public static SyntaxTree SyntaxTree(
-    SyntaxNode root, ParseOptions? options = null, string path = "", Encoding? encoding = null)

+ public static SyntaxTree SyntaxTree(
+   SyntaxNode root, ParseOptions? options, string path, Encoding? encoding)

+ public static SyntaxTree SyntaxTree(
+   SyntaxNode root,
+   ParseOptions? options = null,
+   string path = "",
+   Encoding? encoding = null,
+   SourceHashAlgorithm checksumAlgorithm = SourceHashAlgorithm.Sha1)
}


Similarly for VB.

[jcouv]

Assigned to @333fred and @CyrusNajmabadi to triage/drive as needed, as area owners for api-syntax.

[333fred]

@tmat what's the motivation for using a different hashing algorithm? Not criticizing, just curious.

[tmat]

Need to use the same hash algorithm as specified in the project settings. As explained in #62840, Hot Reload needs to check for a given Document whether or not it matches the compiled code. It does so by comparing the checksum stored in the PDB with the checksum of the Document. The checksum algorithm thus needs to flow through the system.

[tmat]

Another reason is that it should be possible for users of our API to avoid using SHA1 entirely. Having SHA1 as a default parameter of an API that can't be changed makes that impossible.

[333fred]

API Review

• This seems like it would be a constant value of the input text, rather than needing to be recalculated by the tree.
• We need more background info on where the checksum is needed and when it needs to be calculated.

[tmat]

This seems like it would be a constant value of the input text, rather than needing to be recalculated by the tree.

The tree either holds on a SourceText, if it's created directly from SourceText or it creates SourceText lazily if it's created from a syntax node:
https://sourceroslyn.io/#Microsoft.CodeAnalysis.CSharp/Syntax/CSharpSyntaxTree.ParsedSyntaxTree.cs,63.

In the latter case the checksum algorithm is passed from the SyntaxTree to the SourceText being created. Currently ParsedSyntaxTree is only created with hardcoded checksum algorithm.

The property is added to SyntaxTree in order to avoid creating the underlying SourceText unnecessarily, only when the checksum algorithm is needed.

[333fred]

API Review

• Common case is the SourceText is what is calculating the checksum
• Default implementation forwards to SourceText's property
• However, IDE creates trees without the SourceText in some occasions
  • Don't want to rehydrate the SourceText for this scenario
• We'll make sure doc comments on the property explain the usage
• Can't calculate from the nodes: BOM can't be round-tripped, for example, as it's not represented in in-memory string
• Might consider changing the return of Encoding to be none for trees from binary data or other non-file sources, but that would be a breaking change.
• Do we regret having Encoding on the tree as well?
  • Neither Encoding or Checksum are really components of the tree itself. The tree isn't influenced by them, and just turns the tree into a property bag
  • Could the implementation PR keep this info in a different location?
• Maybe we could create SourceTextProvider component that gets a callback when we need to make a tree?
  • But GetText is already virtual, derived types can override as appropriate
• Next steps will be attempting to make Encoding obsolete in the IDE and see what progress we can make with plumbing extra info in that way.

[tmat]

Changes merged in #63832 enabled defining a subclass of CSharpSyntaxTree/VisualBasicSyntaxTree that customizes creation of SourceText. This approach can be used instead of passing checksum algorithm to SyntaxFactory.CreateTree.