add document symbol for #region

Author: fflaten

src/PowerShellEditorServices/Services/Symbols/ScriptDocumentSymbolProvider.cs

@@ -4,6 +4,7 @@
 using System.Collections.Generic;
 using System.Linq;
 using System.Management.Automation.Language;
+using System.Text.RegularExpressions;
 using Microsoft.PowerShell.EditorServices.Services.TextDocument;
 
 namespace Microsoft.PowerShell.EditorServices.Services.Symbols
@@ -16,14 +17,26 @@ internal class ScriptDocumentSymbolProvider : IDocumentSymbolProvider
     {
         string IDocumentSymbolProvider.ProviderId => nameof(ScriptDocumentSymbolProvider);
 
+        // This regular expression are used to match lines which mark the start of a region comment in a script.
+        // Based on the defaults in the VS Code Language Configuration at;
+        // https://github.com/Microsoft/vscode/blob/64186b0a26/extensions/powershell/language-configuration.json#L26-L31
+        // https://github.com/Microsoft/vscode/issues/49070
+        private static readonly Regex s_startRegionTextRegex = new(
+            @"^\s*#[rR]egion\b", RegexOptions.Compiled);
+
         IEnumerable<ISymbolReference> IDocumentSymbolProvider.ProvideDocumentSymbols(
             ScriptFile scriptFile)
         {
+            if (scriptFile?.ScriptAst is null)
+            {
+                return Enumerable.Empty<SymbolReference>();
+            }
+
             // If we have an AST, then we know it's a PowerShell file
             // so lets try to find symbols in the document.
-            return scriptFile?.ScriptAst != null
-                ? FindSymbolsInDocument(scriptFile.ScriptAst)
-                : Enumerable.Empty<SymbolReference>();
+            IEnumerable<SymbolReference> astSymbols = FindSymbolsInDocument(scriptFile.ScriptAst);
+            IEnumerable<SymbolReference> regions = FindRegionsInDocument(scriptFile.ScriptTokens);
+            return astSymbols.Concat(regions);
         }
 
         /// <summary>
@@ -48,5 +61,31 @@ public static IEnumerable<SymbolReference> FindSymbolsInDocument(Ast scriptAst)
             scriptAst.Visit(findSymbolsVisitor);
             return findSymbolsVisitor.SymbolReferences;
         }
+
+        private static IEnumerable<SymbolReference> FindRegionsInDocument(Token[] tokens)
+        {
+            for (int i = 0; i < tokens.Length; i++)
+            {
+                Token token = tokens[i];
+
+                // Exclude everything but single-line comments
+                if (token.Kind != TokenKind.Comment ||
+                    token.Extent.StartLineNumber != token.Extent.EndLineNumber)
+                {
+                    continue;
+                }
+
+                // Look for <newline> #region <optional name>
+                // Document symbols only care about the symbol start and regex is expensive,
+                // so skip checking if region is actually closed with #endregion.
+                if (TokenOperations.IsBlockComment(i, tokens) &&
+                    s_startRegionTextRegex.IsMatch(token.Text))
+                {
+                    yield return new SymbolReference(
+                                        SymbolType.Region,
+                                        token.Extent);
+                }
+            }
+        }
     }
 }

src/PowerShellEditorServices/Services/Symbols/SymbolType.cs

@@ -41,6 +41,11 @@ internal enum SymbolType
         /// <summary>
         /// The symbol is a hashtable key
         /// </summary>
-        HashtableKey
+        HashtableKey,
+
+        /// <summary>
+        /// The symbol is a region
+        /// </summary>
+        Region
     }
 }

src/PowerShellEditorServices/Services/TextDocument/Handlers/DocumentSymbolHandler.cs

@@ -129,7 +129,8 @@ private static SymbolKind GetSymbolKind(SymbolType symbolType)
             return symbolType switch
             {
                 SymbolType.Configuration or SymbolType.Function or SymbolType.Workflow => SymbolKind.Function,
-                _ => SymbolKind.Variable,
+                SymbolType.Region => SymbolKind.String,
+                _ => SymbolKind.Variable
             };
         }
 

src/PowerShellEditorServices/Services/TextDocument/TokenOperations.cs

@@ -198,7 +198,7 @@ private static FoldingReference CreateFoldingReference(
         /// - Token text must start with a '#'.false  This is because comment regions
         ///   start with '<#' but have the same TokenKind
         /// </summary>
-        private static bool IsBlockComment(int index, Token[] tokens)
+        internal static bool IsBlockComment(int index, Token[] tokens)
         {
             Token thisToken = tokens[index];
             if (thisToken.Kind != TokenKind.Comment) { return false; }

test/PowerShellEditorServices.Test.Shared/Symbols/MultipleSymbols.ps1

@@ -25,7 +25,14 @@ workflow AWorkflow {}
 Configuration AConfiguration {
     Node "TEST-PC" {}
 }
+<#
+#region don't find me
+abc
+#endregion
+#>
+#region my region 123
+#endregion
 
 AFunction
 1..3 | AFilter
-AnAdvancedFunction
+AnAdvancedFunction

test/PowerShellEditorServices.Test/Language/SymbolsServiceTests.cs

@@ -287,6 +287,7 @@ public void FindsSymbolsInFile()
             Assert.Equal(4, symbolsResult.Count(symbolReference => symbolReference.SymbolType == SymbolType.Function));
             Assert.Equal(3, symbolsResult.Count(symbolReference => symbolReference.SymbolType == SymbolType.Variable));
             Assert.Single(symbolsResult.Where(symbolReference => symbolReference.SymbolType == SymbolType.Workflow));
+            Assert.Single(symbolsResult.Where(symbolReference => symbolReference.SymbolType == SymbolType.Region));
 
             SymbolReference firstFunctionSymbol = symbolsResult.First(r => r.SymbolType == SymbolType.Function);
             Assert.Equal("AFunction", firstFunctionSymbol.SymbolName);
@@ -303,6 +304,11 @@ public void FindsSymbolsInFile()
             Assert.Equal(23, firstWorkflowSymbol.ScriptRegion.StartLineNumber);
             Assert.Equal(1, firstWorkflowSymbol.ScriptRegion.StartColumnNumber);
 
+            SymbolReference firstRegionSymbol = symbolsResult.First(r => r.SymbolType == SymbolType.Region);
+            Assert.Equal("#region my region 123", firstRegionSymbol.SymbolName);
+            Assert.Equal(33, firstRegionSymbol.ScriptRegion.StartLineNumber);
+            Assert.Equal(1, firstRegionSymbol.ScriptRegion.StartColumnNumber);
+
             // TODO: Bring this back when we can use AstVisitor2 again (#276)
             //Assert.Equal(1, symbolsResult.FoundOccurrences.Where(r => r.SymbolType == SymbolType.Configuration).Count());
             //SymbolReference firstConfigurationSymbol = symbolsResult.FoundOccurrences.Where(r => r.SymbolType == SymbolType.Configuration).First();