(PowerShellGH-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,55 @@
+//
+// 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
+    {
+        public static readonly
+            RequestType<FoldingRangeParams, FoldingRange[], object, object> Type =
+            RequestType<FoldingRangeParams, FoldingRange[], object, object>.Create("textDocument/foldingRange");
+    }
+
+    public class FoldingRangeParams
+    {
+        /// <summary>
+        /// The document to request folding ranges for.
+        /// </summary>
+        public TextDocumentIdentifier TextDocument { get; set; }
+    }
+
+    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,31 @@ protected Task HandleEvaluateRequest(
 
         #region Event Handlers
 
+        /// <summary>
+        /// Converts a FoldingReference object into the LSP FoldingRange object
+        /// </summary>
+        private FoldingRange FoldingReferenceToFoldingRange(FoldingReference value) {
+            FoldingRange item = new FoldingRange();
+            item.EndCharacter = value.EndCharacter;
+            item.EndLine = value.EndLine;
+            item.Kind = value.Kind;
+            item.StartCharacter = value.StartCharacter;
+            item.StartLine = value.StartLine;
+            return item;
+        }
+
+        private FoldingRange[] Fold(
+            string documentUri)
+        {
+            var result = new List<FoldingRange>();
+            foreach (FoldingReference fold in TokenOperations.FoldableRegions(
+                editorSession.Workspace.GetFile(documentUri).ScriptTokens))
+            {
+                result.Add(FoldingReferenceToFoldingRange(item));
+            }
+            return result.ToArray();
+        }
+
         private async Task<Tuple<string, Range>> Format(
             string documentUri,
             FormattingOptions options,

src/PowerShellEditorServices/Language/FoldingReference.cs

@@ -0,0 +1,94 @@
+//
+// 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; }
+
+        /// <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'.
+        /// </summary>
+        public string Kind { get; set; }
+
+        /// <summary>
+        /// Builds a folding reference for start and end line and character position
+        /// </summary>
+        public FoldingReference(
+            int startLine,
+            int startCharacter,
+            int endLine,
+            int endCharacter,
+            string kind)
+        {
+            this.EndCharacter = endCharacter;
+            this.EndLine = endLine;
+            this.Kind = kind;
+            this.StartCharacter = startCharacter;
+            this.StartLine = startLine;
+        }
+
+        /// <summary>
+        /// Builds a folding reference for start and end line
+        /// </summary>
+        public FoldingReference(
+            int startLine,
+            int endLine,
+            string kind)
+        {
+            this.EndCharacter = 0;
+            this.EndLine = endLine;
+            this.Kind = kind;
+            this.StartCharacter = 0;
+            this.StartLine = startLine;
+        }
+
+        /// <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
+            // Check for nulls
+            if ((this.Kind == null) && (that.Kind == null)) { return 0; }
+            return this.Kind.CompareTo(that.Kind);
+        }
+    }
+}