add document symbols for #region start

Author: fflaten

src/PowerShellEditorServices/Services/Symbols/ReferenceTable.cs

@@ -79,6 +79,7 @@ internal void EnsureInitialized()
         }
 
         _parent.ScriptAst.Visit(new SymbolVisitor(_parent, AddReference));
+        RegionVisitor.FindRegionsInDocument(_parent, AddReference);
     }
 
     private AstVisitAction AddReference(SymbolReference symbol)

src/PowerShellEditorServices/Services/Symbols/SymbolType.cs

@@ -79,6 +79,11 @@ internal enum SymbolType
         /// The symbol is a type reference
         /// </summary>
         Type,
+
+        /// <summary>
+        /// The symbol is a region
+        /// </summary>
+        Region
     }
 
     internal static class SymbolTypeUtils
@@ -97,6 +102,7 @@ internal static SymbolKind GetSymbolKind(SymbolType symbolType)
                 SymbolType.Variable or SymbolType.Parameter => SymbolKind.Variable,
                 SymbolType.HashtableKey => SymbolKind.Key,
                 SymbolType.Type => SymbolKind.TypeParameter,
+                SymbolType.Region => SymbolKind.String,
                 SymbolType.Unknown or _ => SymbolKind.Object,
             };
         }

src/PowerShellEditorServices/Services/Symbols/Visitors/RegionVisitor.cs

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using System.Management.Automation.Language;
+using System.Text.RegularExpressions;
+using Microsoft.PowerShell.EditorServices.Services.TextDocument;
+
+namespace Microsoft.PowerShell.EditorServices.Services.Symbols
+{
+    internal static class RegionVisitor
+    {
+        // 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);
+
+        internal static void FindRegionsInDocument(ScriptFile file, Func<SymbolReference, AstVisitAction> action)
+        {
+            Token[] tokens = file.ScriptTokens;
+            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))
+                {
+                    action(new SymbolReference(
+                            SymbolType.Region,
+                            token.Extent.Text.TrimStart().TrimStart('#'),
+                            token.Extent.Text,
+                            token.Extent,
+                            token.Extent,
+                            file,
+                            isDeclaration: true));
+                }
+            }
+        }
+    }
+}

src/PowerShellEditorServices/Services/TextDocument/TokenOperations.cs

@@ -199,7 +199,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

@@ -41,3 +41,11 @@ enum AEnum {
 AFunction
 1..3 | AFilter
 AnAdvancedFunction
+
+<#
+#region don't find me
+abc
+#endregion
+#>
+#region my region 123
+#endregion

test/PowerShellEditorServices.Test/Language/SymbolsServiceTests.cs

@@ -821,6 +821,12 @@ public void FindsSymbolsInFile()
             Assert.Equal("prop AValue", symbol.Id);
             Assert.Equal("AValue", symbol.Name);
             Assert.True(symbol.IsDeclaration);
+
+            symbol = Assert.Single(symbols.Where(i => i.Type == SymbolType.Region));
+            Assert.Equal("region my region 123", symbol.Id);
+            Assert.Equal("#region my region 123", symbol.Name);
+            AssertIsRegion(symbol.NameRegion, 50, 1, 50, 22);
+            Assert.True(symbol.IsDeclaration);
         }
 
         [Fact]