Add syntax folding (#777)

* Add simple folding range provider capability
* Uses a similar method to that implemented in the VS Code extension
* 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
* uses the the client configuration settings to modify the behaviour
of the server. In particular the Enable and ShowLastLine setting.
* The enable setting will change the provider to return null when disabled
* The ShowLastLine setting emulates the behaviour in PowerShell/vscode-powershell#1557

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/LanguageServer/ServerCapabilities.cs

@@ -42,6 +42,8 @@ public class ServerCapabilities
         public ExecuteCommandOptions ExecuteCommandProvider { get; set; }
 
         public object Experimental { get; set; }
+
+        public bool FoldingRangeProvider { get; set; } = false;
     }
 
     /// <summary>

src/PowerShellEditorServices.Protocol/Server/LanguageServer.cs

@@ -134,6 +134,7 @@ public void Start()
             this.messageHandlers.SetRequestHandler(
                 DocumentRangeFormattingRequest.Type,
                 this.HandleDocumentRangeFormattingRequest);
+            this.messageHandlers.SetRequestHandler(FoldingRangeRequest.Type, this.HandleFoldingRangeRequestAsync);
 
             this.messageHandlers.SetRequestHandler(ShowOnlineHelpRequest.Type, this.HandleShowOnlineHelpRequest);
             this.messageHandlers.SetRequestHandler(ShowHelpRequest.Type, this.HandleShowHelpRequest);
@@ -243,7 +244,8 @@ await requestContext.SendResult(
                         },
                         DocumentFormattingProvider = false,
                         DocumentRangeFormattingProvider = false,
-                        RenameProvider = false
+                        RenameProvider = false,
+                        FoldingRangeProvider = true
                     }
                 });
         }
@@ -1329,6 +1331,13 @@ await requestContext.SendResult(new TextEdit[1]
             });
         }
 
+        protected async Task HandleFoldingRangeRequestAsync(
+            FoldingRangeParams foldingParams,
+            RequestContext<FoldingRange[]> requestContext)
+        {
+            await requestContext.SendResult(Fold(foldingParams.TextDocument.Uri));
+        }
+
         protected Task HandleEvaluateRequest(
             DebugAdapterMessages.EvaluateRequestArguments evaluateParams,
             RequestContext<DebugAdapterMessages.EvaluateResponseBody> requestContext)
@@ -1367,6 +1376,27 @@ protected Task HandleEvaluateRequest(
 
         #region Event Handlers
 
+        private FoldingRange[] Fold(
+            string documentUri)
+        {
+            // TODO Should be using dynamic registrations
+            if (!this.currentSettings.CodeFolding.Enable) { return null; }
+            var result = new List<FoldingRange>();
+            foreach (FoldingReference fold in TokenOperations.FoldableRegions(
+                editorSession.Workspace.GetFile(documentUri).ScriptTokens,
+                this.currentSettings.CodeFolding.ShowLastLine))
+            {
+                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.Protocol/Server/LanguageServerSettings.cs

@@ -20,10 +20,13 @@ public class LanguageServerSettings
 
         public CodeFormattingSettings CodeFormatting { get; set; }
 
+        public CodeFoldingSettings CodeFolding { get; set; }
+
         public LanguageServerSettings()
         {
             this.ScriptAnalysis = new ScriptAnalysisSettings();
             this.CodeFormatting = new CodeFormattingSettings();
+            this.CodeFolding = new CodeFoldingSettings();
         }
 
         public void Update(
@@ -39,6 +42,7 @@ public void Update(
                     workspaceRootPath,
                     logger);
                 this.CodeFormatting = new CodeFormattingSettings(settings.CodeFormatting);
+                this.CodeFolding.Update(settings.CodeFolding, logger);
             }
         }
     }
@@ -261,6 +265,41 @@ private Hashtable GetCustomPSSASettingsHashtable(int tabSize, bool insertSpaces)
         }
     }
 
+    /// <summary>
+    /// Code folding settings
+    /// </summary>
+    public class CodeFoldingSettings
+    {
+        /// <summary>
+        /// Whether the folding is enabled. Default is true as per VSCode
+        /// </summary>
+        public bool Enable { get; set; } = true;
+
+        /// <summary>
+        /// Whether to show or hide the last line of a folding region. Default is true as per VSCode
+        /// </summary>
+        public bool ShowLastLine { get; set; } = true;
+
+        /// <summary>
+        /// Update these settings from another settings object
+        /// </summary>
+        public void Update(
+            CodeFoldingSettings settings,
+            ILogger logger)
+        {
+            if (settings != null) {
+                if (this.Enable != settings.Enable) {
+                    this.Enable = settings.Enable;
+                    logger.Write(LogLevel.Verbose, string.Format("Using Code Folding Enabled - {0}", this.Enable));
+                }
+                if (this.ShowLastLine != settings.ShowLastLine) {
+                    this.ShowLastLine = settings.ShowLastLine;
+                    logger.Write(LogLevel.Verbose, string.Format("Using Code Folding ShowLastLine - {0}", this.ShowLastLine));
+                }
+            }
+        }
+    }
+
     public class LanguageServerSettingsWrapper
         {
             // NOTE: This property is capitalized as 'Powershell' because the

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);
+        }
+    }
+}