(GH-793) Add a folding provider and tests

This commit adds the the code to return folding ranges when the server receives
a FoldingRangeRequest.  This commit;

* Uses a similar method to that implemented in the VS Code extension [1]
* Uses the PowerShell tokeniser instead of the AST.  This is due to the AST
  ignoring comment sections.  Without the comment parsing folding for #region
  etc. will not work
* Translates the tests in VS Code [1] into equivalent C# tests

[1] PowerShell/vscode-powershell#1355

Author: glennsarti

src/PowerShellEditorServices.Protocol/LanguageServer/Folding.cs

@@ -0,0 +1,69 @@
+//
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+//
+
+using Microsoft.PowerShell.EditorServices.Protocol.MessageProtocol;
+
+namespace Microsoft.PowerShell.EditorServices.Protocol.LanguageServer
+{
+    public class FoldingRangeRequest
+    {
+        /// <summary>
+        /// A request to provide folding ranges in a document. The request's
+        /// parameter is of type [FoldingRangeParams](#FoldingRangeParams), the
+        /// response is of type [FoldingRangeList](#FoldingRangeList) or a Thenable
+        /// that resolves to such.
+        /// Ref: https://github.com/Microsoft/vscode-languageserver-node/blob/5350bc2ffe8afb17357c1a66fbdd3845fa05adfd/protocol/src/protocol.foldingRange.ts#L112-L120
+        /// </summary>
+        public static readonly
+            RequestType<FoldingRangeParams, FoldingRange[], object, object> Type =
+            RequestType<FoldingRangeParams, FoldingRange[], object, object>.Create("textDocument/foldingRange");
+    }
+
+    /// <summary>
+    /// Parameters for a [FoldingRangeRequest](#FoldingRangeRequest).
+    /// Ref: https://github.com/Microsoft/vscode-languageserver-node/blob/5350bc2ffe8afb17357c1a66fbdd3845fa05adfd/protocol/src/protocol.foldingRange.ts#L102-L110
+    /// </summary>
+    public class FoldingRangeParams
+    {
+        /// <summary>
+        /// The text document
+        /// </summary>
+        public TextDocumentIdentifier TextDocument { get; set; }
+    }
+
+    /// <summary>
+    /// Represents a folding range.
+    /// Ref: https://github.com/Microsoft/vscode-languageserver-node/blob/5350bc2ffe8afb17357c1a66fbdd3845fa05adfd/protocol/src/protocol.foldingRange.ts#L69-L100
+    /// </summary>
+    public class FoldingRange
+    {
+        /// <summary>
+        /// The zero-based line number from where the folded range starts.
+        /// </summary>
+        public int StartLine { get; set; }
+
+        /// <summary>
+        /// The zero-based character offset from where the folded range starts. If not defined, defaults to the length of the start line.
+        /// </summary>
+        public int StartCharacter { get; set; }
+
+        /// <summary>
+        /// The zero-based line number where the folded range ends.
+        /// </summary>
+        public int EndLine { get; set; }
+
+        /// <summary>
+        /// The zero-based character offset before the folded range ends. If not defined, defaults to the length of the end line.
+        /// </summary>
+        public int EndCharacter { get; set; }
+
+        /// <summary>
+        /// Describes the kind of the folding range such as `comment' or 'region'. The kind
+        /// is used to categorize folding ranges and used by commands like 'Fold all comments'. See
+        /// [FoldingRangeKind](#FoldingRangeKind) for an enumeration of standardized kinds.
+        /// </summary>
+        public string Kind { get; set; }
+    }
+}

src/PowerShellEditorServices.Protocol/Server/LanguageServer.cs

@@ -131,6 +131,7 @@ public void Start()
             this.messageHandlers.SetRequestHandler(
                 DocumentRangeFormattingRequest.Type,
                 this.HandleDocumentRangeFormattingRequest);
+            this.messageHandlers.SetRequestHandler(FoldingRangeRequest.Type, this.HandleFoldingRangeRequest);
 
             this.messageHandlers.SetRequestHandler(ShowOnlineHelpRequest.Type, this.HandleShowOnlineHelpRequest);
             this.messageHandlers.SetRequestHandler(ShowHelpRequest.Type, this.HandleShowHelpRequest);
@@ -1251,6 +1252,13 @@ await requestContext.SendResult(new TextEdit[1]
             });
         }
 
+        protected async Task HandleFoldingRangeRequest(
+            FoldingRangeParams foldingParams,
+            RequestContext<FoldingRange[]> requestContext)
+        {
+            await requestContext.SendResult(Fold(foldingParams.TextDocument.Uri));
+        }
+
         protected Task HandleEvaluateRequest(
             DebugAdapterMessages.EvaluateRequestArguments evaluateParams,
             RequestContext<DebugAdapterMessages.EvaluateResponseBody> requestContext)
@@ -1289,6 +1297,24 @@ protected Task HandleEvaluateRequest(
 
         #region Event Handlers
 
+        private FoldingRange[] Fold(
+            string documentUri)
+        {
+            var result = new List<FoldingRange>();
+            foreach (FoldingReference fold in TokenOperations.FoldableRegions(
+                editorSession.Workspace.GetFile(documentUri).ScriptTokens))
+            {
+                result.Add(new FoldingRange {
+                    EndCharacter   = fold.EndCharacter,
+                    EndLine        = fold.EndLine,
+                    Kind           = fold.Kind,
+                    StartCharacter = fold.StartCharacter,
+                    StartLine      = fold.StartLine
+                });
+            }
+            return result.ToArray();
+        }
+
         private async Task<Tuple<string, Range>> Format(
             string documentUri,
             FormattingOptions options,

src/PowerShellEditorServices/Language/FoldingReference.cs

@@ -0,0 +1,63 @@
+//
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+//
+
+using System;
+
+namespace Microsoft.PowerShell.EditorServices
+{
+    /// <summary>
+    /// A class that holds the information for a foldable region of text in a document
+    /// </summary>
+    public class FoldingReference: IComparable<FoldingReference>
+    {
+        /// <summary>
+        /// The zero-based line number from where the folded range starts.
+        /// </summary>
+        public int StartLine { get; set; }
+
+        /// <summary>
+        /// The zero-based character offset from where the folded range starts. If not defined, defaults to the length of the start line.
+        /// </summary>
+        public int StartCharacter { get; set; } = 0;
+
+        /// <summary>
+        /// The zero-based line number where the folded range ends.
+        /// </summary>
+        public int EndLine { get; set; }
+
+        /// <summary>
+        /// The zero-based character offset before the folded range ends. If not defined, defaults to the length of the end line.
+        /// </summary>
+        public int EndCharacter { get; set; } = 0;
+
+        /// <summary>
+        /// Describes the kind of the folding range such as `comment' or 'region'.
+        /// </summary>
+        public string Kind { get; set; }
+
+        /// <summary>
+        /// A custom comparable method which can properly sort FoldingReference objects
+        /// </summary>
+        public int CompareTo(FoldingReference that) {
+            // Initially look at the start line
+            if (this.StartLine < that.StartLine) { return -1; }
+            if (this.StartLine > that.StartLine) { return 1; }
+
+            // They have the same start line so now consider the end line.
+            // The biggest line range is sorted first
+            if (this.EndLine > that.EndLine) { return -1; }
+            if (this.EndLine < that.EndLine) { return 1; }
+
+            // They have the same lines, but what about character offsets
+            if (this.StartCharacter < that.StartCharacter) { return -1; }
+            if (this.StartCharacter > that.StartCharacter) { return 1; }
+            if (this.EndCharacter < that.EndCharacter) { return -1; }
+            if (this.EndCharacter > that.EndCharacter) { return 1; }
+
+            // They're the same range, but what about kind
+            return string.Compare(this.Kind, that.Kind);
+        }
+    }
+}