Add RegionDocumentSymbolProvider.cs

Co-authored-by: Andy Jordan <[email protected]>

Author: fflaten

src/PowerShellEditorServices/Services/Symbols/RegionDocumentSymbolProvider.cs

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Collections.Generic;
+using System.Management.Automation.Language;
+using Microsoft.PowerShell.EditorServices.Services.TextDocument;
+
+namespace Microsoft.PowerShell.EditorServices.Services.Symbols
+{
+    /// <summary>
+    /// Provides an IDocumentSymbolProvider implementation for
+    /// enumerating regions as symbols in script (.psd1, .psm1) files.
+    /// </summary>
+    internal class RegionDocumentSymbolProvider : IDocumentSymbolProvider
+    {
+        string IDocumentSymbolProvider.ProviderId => nameof(RegionDocumentSymbolProvider);
+
+        IEnumerable<SymbolReference> IDocumentSymbolProvider.ProvideDocumentSymbols(ScriptFile scriptFile)
+        {
+            Stack<Token> tokenCommentRegionStack = new();
+            Token[] tokens = scriptFile.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);
+
+                        yield return new SymbolReference(
+                            SymbolType.Region,
+                            regionStart.Extent.Text.Trim().TrimStart('#'),
+                            regionStart.Extent.Text.Trim(),
+                            regionStart.Extent,
+                            new ScriptExtent()
+                            {
+                                Text = string.Join(System.Environment.NewLine, scriptFile.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
+                            },
+                            scriptFile,
+                            isDeclaration: true);
+                    }
+                }
+            }
+        }
+    }
+}

src/PowerShellEditorServices/Services/Symbols/SymbolsService.cs

@@ -77,13 +77,13 @@ public SymbolsService(
             PesterCodeLensProvider pesterProvider = new(configurationService);
             _ = _codeLensProviders.TryAdd(pesterProvider.ProviderId, pesterProvider);
 
-            // TODO: Is this complication so necessary?
             _documentSymbolProviders = new ConcurrentDictionary<string, IDocumentSymbolProvider>();
             IDocumentSymbolProvider[] documentSymbolProviders = new IDocumentSymbolProvider[]
             {
                 new ScriptDocumentSymbolProvider(),
                 new PsdDocumentSymbolProvider(),
-                new PesterDocumentSymbolProvider(),
+                new PesterDocumentSymbolProvider()
+                // NOTE: This specifically does not include RegionDocumentSymbolProvider.
             };
 
             foreach (IDocumentSymbolProvider documentSymbolProvider in documentSymbolProviders)

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

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation.
+// Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
 using System;
@@ -35,7 +35,8 @@ public PsesDocumentSymbolHandler(ILoggerFactory factory, WorkspaceService worksp
             {
                 new ScriptDocumentSymbolProvider(),
                 new PsdDocumentSymbolProvider(),
-                new PesterDocumentSymbolProvider()
+                new PesterDocumentSymbolProvider(),
+                new RegionDocumentSymbolProvider()
             };
         }
 

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,16 @@ enum AEnum {
 AFunction
 1..3 | AFilter
 AnAdvancedFunction
+
+<#
+#region don't find me inside comment block
+abc
+#endregion
+#>
+
+#region find me outer
+#region find me inner
+
+#endregion
+#endregion
+#region ignore this unclosed region

test/PowerShellEditorServices.Test/Language/SymbolsServiceTests.cs

@@ -821,6 +821,35 @@ public void FindsSymbolsInFile()
             Assert.Equal("prop AValue", symbol.Id);
             Assert.Equal("AValue", symbol.Name);
             Assert.True(symbol.IsDeclaration);
+
+            // There should be no region symbols unless the provider has been registered.
+            Assert.Empty(symbols.Where(i => i.Type == SymbolType.Region));
+        }
+
+        [Fact]
+        public void FindsRegionsInFile()
+        {
+            symbolsService.TryRegisterDocumentSymbolProvider(new RegionDocumentSymbolProvider());
+            IEnumerable<SymbolReference> symbols = FindSymbolsInFile(FindSymbolsInMultiSymbolFile.SourceDetails);
+            Assert.Collection(symbols.Where(i => i.Type == SymbolType.Region),
+                 (i) =>
+                 {
+                     Assert.Equal("region find me outer", i.Id);
+                     Assert.Equal("#region find me outer", i.Name);
+                     Assert.Equal(SymbolType.Region, i.Type);
+                     Assert.True(i.IsDeclaration);
+                     AssertIsRegion(i.NameRegion, 51, 1, 51, 22);
+                     AssertIsRegion(i.ScriptRegion, 51, 1, 55, 11);
+                 },
+                 (i) =>
+                 {
+                     Assert.Equal("region find me inner", i.Id);
+                     Assert.Equal("#region find me inner", i.Name);
+                     Assert.Equal(SymbolType.Region, i.Type);
+                     Assert.True(i.IsDeclaration);
+                     AssertIsRegion(i.NameRegion, 52, 1, 52, 22);
+                     AssertIsRegion(i.ScriptRegion, 52, 1, 54, 11);
+                 });
         }
 
         [Fact]