(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,73 @@
+//
+// 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; }
+    }
+
+    public sealed class FoldingRangeKind
+    {
+        private FoldingRangeKind() {}
+
+        /// <summary>
+        /// Folding range for a comment
+        /// <summary>
+        public static readonly string Comment = "comment";
+        /// <summary>
+        /// Folding range for a imports or includes
+        /// <summary>
+        public static readonly string Imports = "imports";
+        /// <summary>
+        /// Folding range for a region (e.g. `#region`)
+        /// <summary>
+        public static readonly string Region = "region";
+    }
+}

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,14 @@ await requestContext.SendResult(new TextEdit[1]
             });
         }
 
+        protected async Task HandleFoldingRangeRequest(
+            FoldingRangeParams foldingParams,
+            RequestContext<FoldingRange[]> requestContext)
+        {
+            var result = Fold(foldingParams.TextDocument.Uri);
+            await requestContext.SendResult(result);
+        }
+
         protected Task HandleEvaluateRequest(
             DebugAdapterMessages.EvaluateRequestArguments evaluateParams,
             RequestContext<DebugAdapterMessages.EvaluateResponseBody> requestContext)
@@ -1289,6 +1298,25 @@ protected Task HandleEvaluateRequest(
 
         #region Event Handlers
 
+        private FoldingRange[] Fold(
+            string documentUri)
+        {
+            // TODO Surely there's a better way to do type adapters?
+            List<FoldingRange> result = new List<FoldingRange>();
+            foreach (FoldingReference fold in TokenOperations.FoldableRegions(
+                editorSession.Workspace.GetFile(documentUri).ScriptTokens))
+            {
+                FoldingRange item = new FoldingRange();
+                item.EndCharacter = fold.EndCharacter;
+                item.EndLine = fold.EndLine;
+                item.Kind = fold.Kind; // TODO: Need to make sure the string is expected
+                item.StartCharacter = fold.StartCharacter;
+                item.StartLine = fold.StartLine;
+                result.Add(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);
+        }
+    }
+}