Add document symbols for #region

src/PowerShellEditorServices/Services/Symbols/ReferenceTable.cs

@@ -79,6 +79,7 @@ internal void EnsureInitialized()
         }
 
         _parent.ScriptAst.Visit(new SymbolVisitor(_parent, AddReference));
+        RegionVisitor.GetRegionsInDocument(_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. Only used for navigation-features.
+        /// </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/SymbolsService.cs

@@ -160,7 +160,8 @@ public async Task<IEnumerable<SymbolReference>> ScanForReferencesOfSymbolAsync(
             SymbolReference symbol,
             CancellationToken cancellationToken = default)
         {
-            if (symbol is null)
+            // Never scan for regions as they're only useful in current document
+            if (symbol is null || symbol.Type is SymbolType.Region)
             {
                 return Enumerable.Empty<SymbolReference>();
             }

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

@@ -0,0 +1,74 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections.Generic;
+using System.Management.Automation.Language;
+using Microsoft.PowerShell.EditorServices.Services.TextDocument;
+
+namespace Microsoft.PowerShell.EditorServices.Services.Symbols
+{
+    internal static class RegionVisitor
+    {
+        internal static void GetRegionsInDocument(ScriptFile file, Func<SymbolReference, AstVisitAction> action)
+        {
+            Stack<Token> tokenCommentRegionStack = new();
+            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 ||
+                    !TokenOperations.IsBlockComment(i, tokens))
+                {
+                    continue;
+                }
+
+                // Processing for #region -> #endregion
+                if (TokenOperations.s_startRegionTextRegex.IsMatch(token.Text))
+                {
+                    tokenCommentRegionStack.Push(token);
+                    continue;
+                }
+
+                if (TokenOperations.s_endRegionTextRegex.IsMatch(token.Text))
+                {
+                    // Mismatched regions in the script can cause bad stacks.
+                    if (tokenCommentRegionStack.Count > 0)
+                    {
+                        Token regionStart = tokenCommentRegionStack.Pop();
+                        Token regionEnd = token;
+
+                        BufferRange regionRange = new(
+                            regionStart.Extent.StartLineNumber,
+                            regionStart.Extent.StartColumnNumber,
+                            regionEnd.Extent.EndLineNumber,
+                            regionEnd.Extent.EndColumnNumber);
+
+                        action(new SymbolReference(
+                            SymbolType.Region,
+                            regionStart.Extent.Text.Trim().TrimStart('#'),
+                            regionStart.Extent.Text.Trim(),
+                            regionStart.Extent,
+                            new ScriptExtent()
+                            {
+                                Text = string.Join(Environment.NewLine, file.GetLinesInRange(regionRange)),
+                                StartLineNumber = regionStart.Extent.StartLineNumber,
+                                StartColumnNumber = regionStart.Extent.StartColumnNumber,
+                                StartOffset = regionStart.Extent.StartOffset,
+                                EndLineNumber = regionEnd.Extent.EndLineNumber,
+                                EndColumnNumber = regionEnd.Extent.EndColumnNumber,
+                                EndOffset = regionEnd.Extent.EndOffset,
+                                File = regionStart.Extent.File
+                            },
+                            file,
+                            isDeclaration: true));
+                    }
+                }
+            }
+        }
+    }
+}

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

@@ -53,6 +53,11 @@ public override Task<DocumentHighlightContainer> Handle(
             List<DocumentHighlight> highlights = new();
             foreach (SymbolReference occurrence in occurrences)
             {
+                if (occurrence.Type is SymbolType.Region)
+                {
+                    continue;
+                }
+
                 highlights.Add(new DocumentHighlight
                 {
                     Kind = DocumentHighlightKind.Write, // TODO: Which symbol types are writable?

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

@@ -52,7 +52,7 @@ await _symbolsService.FindSymbolDetailsAtLocationAsync(
                         request.Position.Line + 1,
                         request.Position.Character + 1).ConfigureAwait(false);
 
-            if (symbolDetails is null)
+            if (symbolDetails is null || symbolDetails.SymbolReference.Type is SymbolType.Region)
             {
                 return null;
             }

src/PowerShellEditorServices/Services/TextDocument/TokenOperations.cs

@@ -17,9 +17,9 @@ internal static class TokenOperations
         // script. They are 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(
+        internal static readonly Regex s_startRegionTextRegex = new(
            @"^\s*#[rR]egion\b", RegexOptions.Compiled);
-        private static readonly Regex s_endRegionTextRegex = new(
+        internal static readonly Regex s_endRegionTextRegex = new(
            @"^\s*#[eE]nd[rR]egion\b", RegexOptions.Compiled);
 
         /// <summary>
@@ -199,7 +199,7 @@ private static FoldingReference CreateFoldingReference(
         /// - Token text must start with a '#'.false  This is because comment regions
         ///   start with '&lt;#' 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,13 @@ enum AEnum {
 AFunction
 1..3 | AFilter
 AnAdvancedFunction
+
+<#
+#region don't find me
+abc
+#endregion
+#>
+#region my region 123
+
+#endregion
+#region unclosed region

test/PowerShellEditorServices.Test/Language/SymbolsServiceTests.cs

@@ -821,6 +821,13 @@ 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);
+            AssertIsRegion(symbol.ScriptRegion, 50, 1, 52, 11);
+            Assert.True(symbol.IsDeclaration);
         }
 
         [Fact]