Add support for comment syntax to route detector (dotnet#45185)

Co-authored-by: Safia Abdalla <[email protected]>

Author: JamesNK

src/Framework/AspNetCoreAnalyzers/samples/WebAppSample/Pages/Index.cshtml.cs

@@ -1,3 +1,6 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Mvc.RazorPages;
 

src/Framework/AspNetCoreAnalyzers/src/Analyzers/RouteEmbeddedLanguage/Infrastructure/EmbeddedLanguageCommentDetector.cs

@@ -0,0 +1,51 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Text.RegularExpressions;
+
+namespace Microsoft.AspNetCore.Analyzers.RouteEmbeddedLanguage.Infrastructure;
+
+// Copied from https://github.com/dotnet/roslyn/blob/9fee6f5461baae5152c956c3c3024ca15b85feb9/src/Features/Core/Portable/EmbeddedLanguages/EmbeddedLanguageCommentDetector.cs
+
+/// <summary>
+/// Helps match patterns of the form: language=name,option1,option2,option3
+/// <para/>
+/// All matching is case insensitive, with spaces allowed between the punctuation. Option values are
+/// returned as strings.
+/// <para/>
+/// Option names are the values from the TOptions enum.
+/// </summary>
+internal readonly struct EmbeddedLanguageCommentDetector
+{
+    private readonly Regex _regex;
+
+    public EmbeddedLanguageCommentDetector(ImmutableArray<string> identifiers)
+    {
+        var namePortion = string.Join("|", identifiers.Select(n => $"({Regex.Escape(n)})"));
+        _regex = new Regex($@"^((//)|(')|(/\*))\s*lang(uage)?\s*=\s*(?<identifier>{namePortion})\b((\s*,\s*)(?<option>[a-zA-Z]+))*",
+            RegexOptions.ExplicitCapture | RegexOptions.IgnoreCase | RegexOptions.Compiled);
+    }
+
+    public bool TryMatch(
+        string text,
+        [NotNullWhen(true)] out string? identifier,
+        [NotNullWhen(true)] out IEnumerable<string>? options)
+    {
+        var match = _regex.Match(text);
+        identifier = null;
+        options = null;
+        if (!match.Success)
+        {
+            return false;
+        }
+
+        identifier = match.Groups["identifier"].Value;
+        var optionGroup = match.Groups["option"];
+        options = optionGroup.Captures.OfType<Capture>().Select(c => c.Value);
+        return true;
+    }
+}

src/Framework/AspNetCoreAnalyzers/src/Analyzers/RouteEmbeddedLanguage/Infrastructure/EmbeddedLanguageCommentOptions.cs

@@ -0,0 +1,55 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+
+namespace Microsoft.AspNetCore.Analyzers.RouteEmbeddedLanguage.Infrastructure;
+
+// Copied from https://github.com/dotnet/roslyn/blob/9fee6f5461baae5152c956c3c3024ca15b85feb9/src/Features/Core/Portable/EmbeddedLanguages/EmbeddedLanguageCommentOptions.cs
+
+/// <summary>
+/// Helps match patterns of the form: language=name,option1,option2,option3
+/// <para/>
+/// All matching is case insensitive, with spaces allowed between the punctuation. Option values will be or'ed
+/// together to produce final options value.  If an unknown option is encountered, processing will stop with
+/// whatever value has accumulated so far.
+/// <para/>
+/// Option names are the values from the TOptions enum.
+/// </summary>
+internal static class EmbeddedLanguageCommentOptions<TOptions> where TOptions : struct, Enum
+{
+    private static readonly Dictionary<string, TOptions> s_nameToOption =
+        typeof(TOptions).GetTypeInfo().DeclaredFields
+            .Where(f => f.FieldType == typeof(TOptions))
+            .ToDictionary(f => f.Name, f => (TOptions)f.GetValue(null)!, StringComparer.OrdinalIgnoreCase);
+
+    public static bool TryGetOptions(IEnumerable<string> captures, out TOptions options)
+    {
+        options = default;
+
+        foreach (var capture in captures)
+        {
+            if (!s_nameToOption.TryGetValue(capture, out var specificOption))
+            {
+                // hit something we don't understand.  bail out.  that will help ensure
+                // users don't have weird behavior just because they misspelled something.
+                // instead, they will know they need to fix it up.
+                return false;
+            }
+
+            options = CombineOptions(options, specificOption);
+        }
+
+        return true;
+    }
+
+    private static TOptions CombineOptions(TOptions options, TOptions specificOption)
+    {
+        var int1 = (int)(object)options;
+        var int2 = (int)(object)specificOption;
+        return (TOptions)(object)(int1 | int2);
+    }
+}

src/Framework/AspNetCoreAnalyzers/src/Analyzers/RouteEmbeddedLanguage/Infrastructure/RouteStringSyntaxDetector.cs

@@ -1,6 +1,7 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Collections.Generic;
 using System.Collections.Immutable;
 using System.Diagnostics.CodeAnalysis;
 using System.Linq;
@@ -13,14 +14,18 @@ namespace Microsoft.AspNetCore.Analyzers.RouteEmbeddedLanguage.Infrastructure;
 
 internal static class RouteStringSyntaxDetector
 {
-    public static bool IsRouteStringSyntaxToken(SyntaxToken token, SemanticModel semanticModel, CancellationToken cancellationToken)
+    private static readonly EmbeddedLanguageCommentDetector _commentDetector = new(ImmutableArray.Create("Route"));
+    
+    public static bool IsRouteStringSyntaxToken(SyntaxToken token, SemanticModel semanticModel, CancellationToken cancellationToken, out RouteOptions options)
     {
+        options = default;
+        
         if (!IsAnyStringLiteral(token.RawKind))
         {
             return false;
         }
 
-        if (!TryGetStringFormat(token, semanticModel, cancellationToken, out var identifier))
+        if (!TryGetStringFormat(token, semanticModel, cancellationToken, out var identifier, out var stringOptions))
         {
             return false;
         }
@@ -30,6 +35,11 @@ public static bool IsRouteStringSyntaxToken(SyntaxToken token, SemanticModel sem
             return false;
         }
 
+        if (stringOptions != null)
+        {
+            return EmbeddedLanguageCommentOptions<RouteOptions>.TryGetOptions(stringOptions, out options);
+        }
+
         return true;
     }
 
@@ -43,14 +53,26 @@ private static bool IsAnyStringLiteral(int rawKind)
                rawKind == (int)SyntaxKind.Utf8MultiLineRawStringLiteralToken;
     }
 
-    private static bool TryGetStringFormat(SyntaxToken token, SemanticModel semanticModel, CancellationToken cancellationToken, [NotNullWhen(true)] out string identifier)
+    private static bool TryGetStringFormat(
+        SyntaxToken token,
+        SemanticModel semanticModel,
+        CancellationToken cancellationToken,
+        [NotNullWhen(true)] out string identifier,
+        [NotNullWhen(true)] out IEnumerable<string>? options)
     {
+        options = null;
+        
         if (token.Parent is not LiteralExpressionSyntax)
         {
             identifier = null;
             return false;
         }
 
+        if (HasLanguageComment(token, out identifier, out options))
+        {
+            return true;
+        }
+
         var container = token.TryFindContainer();
         if (container is null)
         {
@@ -117,6 +139,84 @@ private static bool TryGetStringFormat(SyntaxToken token, SemanticModel semantic
         return false;
     }
 
+    private static bool HasLanguageComment(
+        SyntaxToken token,
+        [NotNullWhen(true)] out string? identifier,
+        [NotNullWhen(true)] out IEnumerable<string>? options)
+    {
+        if (HasLanguageComment(token.GetPreviousToken().TrailingTrivia, out identifier, out options))
+        {
+            return true;
+        }
+
+        for (var node = token.Parent; node != null; node = node.Parent)
+        {
+            if (HasLanguageComment(node.GetLeadingTrivia(), out identifier, out options))
+            {
+                return true;
+            }
+            // Stop walking up once we hit a statement.  We don't need/want statements higher up the parent chain to
+            // have any impact on this token.
+            if (IsStatement(node))
+            {
+                break;
+            }
+        }
+
+        return false;
+    }
+
+    private static bool HasLanguageComment(
+        SyntaxTriviaList list,
+        [NotNullWhen(true)] out string? identifier,
+        [NotNullWhen(true)] out IEnumerable<string>? options)
+    {
+        foreach (var trivia in list)
+        {
+            if (HasLanguageComment(trivia, out identifier, out options))
+            {
+                return true;
+            }
+        }
+
+        identifier = null;
+        options = null;
+        return false;
+    }
+
+    private static bool HasLanguageComment(
+        SyntaxTrivia trivia,
+        [NotNullWhen(true)] out string? identifier,
+        [NotNullWhen(true)] out IEnumerable<string>? options)
+    {
+        if (IsRegularComment(trivia))
+        {
+            // Note: ToString on SyntaxTrivia is non-allocating.  It will just return the
+            // underlying text that the trivia is already pointing to.
+            var text = trivia.ToString();
+            if (_commentDetector.TryMatch(text, out identifier, out options))
+            {
+                return true;
+            }
+        }
+
+        identifier = null;
+        options = null;
+        return false;
+    }
+
+    public static bool IsStatement([NotNullWhen(true)] SyntaxNode? node)
+       => node is StatementSyntax;
+
+    public static bool IsRegularComment(this SyntaxTrivia trivia)
+        => trivia.IsSingleOrMultiLineComment() || trivia.IsShebangDirective();
+
+    public static bool IsSingleOrMultiLineComment(this SyntaxTrivia trivia)
+        => trivia.IsKind(SyntaxKind.MultiLineCommentTrivia) || trivia.IsKind(SyntaxKind.SingleLineCommentTrivia);
+
+    public static bool IsShebangDirective(this SyntaxTrivia trivia)
+        => trivia.IsKind(SyntaxKind.ShebangDirectiveTrivia);
+
     public static bool IsEqualsValueOfPropertyDeclaration(SyntaxNode? node)
         => node?.Parent is PropertyDeclarationSyntax propertyDeclaration && propertyDeclaration.Initializer == node;
 

src/Framework/AspNetCoreAnalyzers/src/Analyzers/RouteEmbeddedLanguage/Infrastructure/RouteStringSyntaxDetectorDocument.cs

@@ -13,7 +13,7 @@ namespace Microsoft.AspNetCore.Analyzers.RouteEmbeddedLanguage.Infrastructure;
 /// </summary>
 internal static class RouteStringSyntaxDetectorDocument
 {
-    internal static async ValueTask<(bool success, SyntaxToken token, SemanticModel? model)> TryGetStringSyntaxTokenAtPositionAsync(
+    internal static async ValueTask<(bool success, SyntaxToken token, SemanticModel? model, RouteOptions options)> TryGetStringSyntaxTokenAtPositionAsync(
         Document document, int position, CancellationToken cancellationToken)
     {
         var root = await document.GetSyntaxRootAsync(cancellationToken).ConfigureAwait(false);
@@ -29,11 +29,11 @@ internal static class RouteStringSyntaxDetectorDocument
             return default;
         }
 
-        if (!RouteStringSyntaxDetector.IsRouteStringSyntaxToken(token, semanticModel, cancellationToken))
+        if (!RouteStringSyntaxDetector.IsRouteStringSyntaxToken(token, semanticModel, cancellationToken, out var options))
         {
             return default;
         }
 
-        return (true, token, semanticModel);
+        return (true, token, semanticModel, options);
     }
 }

src/Framework/AspNetCoreAnalyzers/src/Analyzers/RouteEmbeddedLanguage/RouteOptions.cs

@@ -0,0 +1,19 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+
+namespace Microsoft.AspNetCore.Analyzers.RouteEmbeddedLanguage;
+
+[Flags]
+internal enum RouteOptions
+{
+    /// <summary>
+    /// HTTP route. Used to match endpoints for Minimal API, MVC, SignalR, gRPC, etc.
+    /// </summary> 
+    Http = 0,
+    /// <summary>
+    /// Component route. Used to match Razor components for Blazor.
+    /// </summary>
+    Component = 1,
+}

src/Framework/AspNetCoreAnalyzers/src/Analyzers/RouteEmbeddedLanguage/RoutePatternAnalyzer.cs

@@ -52,7 +52,7 @@ private void Analyze(
             else
             {
                 var token = child.AsToken();
-                if (!RouteStringSyntaxDetector.IsRouteStringSyntaxToken(token, context.SemanticModel, cancellationToken))
+                if (!RouteStringSyntaxDetector.IsRouteStringSyntaxToken(token, context.SemanticModel, cancellationToken, out var _))
                 {
                     continue;
                 }
@@ -175,7 +175,7 @@ private record struct InsertPoint(ISymbol ExistingParameter, bool Before);
 
     public override void Initialize(AnalysisContext context)
     {
-        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.ReportDiagnostics);
         context.EnableConcurrentExecution();
 
         context.RegisterSemanticModelAction(Analyze);