feature: introduce source generator for enum code generation

Directory.Packages.props

@@ -12,6 +12,8 @@
     <PackageVersion Include="NUnit" Version="4.1.0" />
     <PackageVersion Include="NUnit3TestAdapter" Version="4.6.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis" Version="4.11.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.11.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging" Version="8.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Configuration" Version="8.0.0" />

Garnet.sln

@@ -1,4 +1,4 @@
-Microsoft Visual Studio Solution File, Format Version 12.00
+Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 17
 VisualStudioVersion = 17.0.31808.319
 MinimumVisualStudioVersion = 10.0.40219.1
@@ -96,6 +96,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CommandInfoUpdater", "playg
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SampleModule", "playground\SampleModule\SampleModule.csproj", "{A8CA619E-8F13-4EF8-943F-2D5E3FEBFB3F}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Garnet.gen", "libs\gen\Garnet.gen.csproj", "{E248012E-1D19-4114-924F-EFC9E859C4CD}"
+EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "GarnetJSON", "playground\GarnetJSON\GarnetJSON.csproj", "{2C8F1F5D-31E5-4D00-A46E-F3B1D9BC098F}"
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MigrateBench", "playground\MigrateBench\MigrateBench.csproj", "{6B66B394-E410-4B61-9A5A-1595FF6F5E08}"
 EndProject
@@ -289,6 +291,14 @@ Global
 		{A8CA619E-8F13-4EF8-943F-2D5E3FEBFB3F}.Release|Any CPU.Build.0 = Release|Any CPU
 		{A8CA619E-8F13-4EF8-943F-2D5E3FEBFB3F}.Release|x64.ActiveCfg = Release|Any CPU
 		{A8CA619E-8F13-4EF8-943F-2D5E3FEBFB3F}.Release|x64.Build.0 = Release|Any CPU
+		{E248012E-1D19-4114-924F-EFC9E859C4CD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E248012E-1D19-4114-924F-EFC9E859C4CD}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E248012E-1D19-4114-924F-EFC9E859C4CD}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{E248012E-1D19-4114-924F-EFC9E859C4CD}.Debug|x64.Build.0 = Debug|Any CPU
+		{E248012E-1D19-4114-924F-EFC9E859C4CD}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E248012E-1D19-4114-924F-EFC9E859C4CD}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E248012E-1D19-4114-924F-EFC9E859C4CD}.Release|x64.ActiveCfg = Release|Any CPU
+		{E248012E-1D19-4114-924F-EFC9E859C4CD}.Release|x64.Build.0 = Release|Any CPU
 		{2C8F1F5D-31E5-4D00-A46E-F3B1D9BC098F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{2C8F1F5D-31E5-4D00-A46E-F3B1D9BC098F}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{2C8F1F5D-31E5-4D00-A46E-F3B1D9BC098F}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -342,6 +352,7 @@ Global
 		{9F6E4734-6341-4A9C-A7FF-636A39D8BEAD} = {346A5A53-51E4-4A75-B7E6-491D950382CE}
 		{9BE474A2-1547-43AC-B4F2-FB48A01FA995} = {69A71E2C-00E3-42F3-854E-BE157A24834E}
 		{A8CA619E-8F13-4EF8-943F-2D5E3FEBFB3F} = {69A71E2C-00E3-42F3-854E-BE157A24834E}
+		{E248012E-1D19-4114-924F-EFC9E859C4CD} = {147FCE31-EC09-4C90-8E4D-37CA87ED18C3}
 		{2C8F1F5D-31E5-4D00-A46E-F3B1D9BC098F} = {69A71E2C-00E3-42F3-854E-BE157A24834E}
 		{6B66B394-E410-4B61-9A5A-1595FF6F5E08} = {69A71E2C-00E3-42F3-854E-BE157A24834E}
 		{697766CD-2046-46D9-958A-0FD3B46C98D4} = {01823EA4-4446-4D66-B268-DFEE55951964}

libs/common/GenerateEnumUtilsAttribute.cs

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+using System;
+
+namespace Garnet.common
+{
+    /// <summary>
+    /// Specifies that utility methods for generating enum descriptions should be generated for the target enum.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Enum)]
+    public sealed class GenerateEnumDescriptionUtilsAttribute : Attribute
+    {
+    }
+}

libs/gen/EnumsSourceGenerator.cs

@@ -0,0 +1,187 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+using System.CodeDom.Compiler;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+
+namespace Garnet;
+
+[Generator]
+public class EnumsSourceGenerator : IIncrementalGenerator
+{
+    const string GeneratedClassName = "EnumUtils";
+
+    public void Initialize(IncrementalGeneratorInitializationContext context)
+    {
+        var enumDetails = context.SyntaxProvider
+            .ForAttributeWithMetadataName(
+                "Garnet.common.GenerateEnumDescriptionUtilsAttribute",
+                predicate: static (_, _) => true,
+                transform: static (ctx, _) => TransformEnumDetails((EnumDeclarationSyntax)ctx.TargetNode, ctx.SemanticModel)
+            );
+        var enumUtils = enumDetails.Select(static (details, _) => Execute(details));
+
+        context.RegisterSourceOutput(enumUtils, (ctx, source) => ctx.AddSource($"{GeneratedClassName}.{source.EnumName}.g.cs", source.ClassSource));
+    }
+
+    private static EnumDetails TransformEnumDetails(EnumDeclarationSyntax enumDeclaration, SemanticModel semanticModel)
+    {
+        var namespaceDeclaration = enumDeclaration.FirstAncestorOrSelf<NamespaceDeclarationSyntax>();
+        var enumName = enumDeclaration.Identifier.Text;
+
+        var values = enumDeclaration.Members
+            .Select(m => (
+                m.Identifier.Text,
+                semanticModel.GetOperation(m.EqualsValue!.Value)!.ConstantValue.Value,
+                Description: m.AttributeLists
+                    .SelectMany(al => al.Attributes).Where(a => a.Name.ToString() == "Description")
+                    .SingleOrDefault()?.ArgumentList?.Arguments.Single().ToString()
+            ))
+            .ToArray();
+        return new EnumDetails(namespaceDeclaration!.Name.ToString(), enumName, new EquatableArray<(string Name, object? Value, string? Description)>(values));
+    }
+
+    private static (string EnumName, string ClassSource) Execute(EnumDetails details)
+    {
+        using var classWriter = new IndentedTextWriter(new StringWriter());
+        classWriter.WriteLine("// <auto-generated>");
+        classWriter.WriteLine($"// This code was generated by the {nameof(EnumsSourceGenerator)} source generator.");
+        classWriter.WriteLine("// </auto-generated>");
+
+        classWriter.WriteLine("using System;");
+        classWriter.WriteLine("using System.ComponentModel;");
+        classWriter.WriteLine("using System.Numerics;");
+        classWriter.WriteLine();
+        classWriter.WriteLine($"namespace {details.Namespace};");
+        classWriter.WriteLine();
+        classWriter.WriteLine("/// <summary>");
+        classWriter.WriteLine($"/// Utility methods for enums.");
+        classWriter.WriteLine("/// </summary>");
+        classWriter.WriteLine($"public static partial class {GeneratedClassName}");
+        classWriter.WriteLine("{");
+        classWriter.Indent++;
+        GenerateTryParseEnumFromDescriptionMethod(classWriter, details);
+        classWriter.WriteLine();
+        GenerateGetEnumDescriptionsMethod(classWriter, details);
+        classWriter.Indent--;
+        classWriter.WriteLine("}");
+
+        return (details.EnumName, classWriter.InnerWriter.ToString()!);
+    }
+
+    private static void GenerateTryParseEnumFromDescriptionMethod(IndentedTextWriter classWriter, EnumDetails details)
+    {
+        classWriter.WriteLine("/// <summary>");
+        classWriter.WriteLine("/// Tries to parse the enum value from the description.");
+        classWriter.WriteLine("/// </summary>");
+        classWriter.WriteLine("/// <param name=\"description\">Enum description.</param>");
+        classWriter.WriteLine("/// <param name=\"result\">Enum value.</param>");
+        classWriter.WriteLine("/// <returns>True if successful.</returns>");
+        classWriter.WriteLine($"public static bool TryParse{details.EnumName}FromDescription(string description, out {details.EnumName} result)");
+        classWriter.WriteLine("{");
+        classWriter.Indent++;
+        classWriter.WriteLine("result = default;");
+        classWriter.WriteLine("switch (description)");
+        classWriter.WriteLine("{");
+        classWriter.Indent++;
+        foreach (var (name, _, description) in details.Values)
+        {
+            bool hasDescription = false;
+            if (description is not null)
+            {
+                hasDescription = true;
+                classWriter.WriteLine($"case {description}:");
+            }
+
+            if (!hasDescription) continue;
+            classWriter.Indent++;
+            classWriter.WriteLine($"result = {details.EnumName}.{name};");
+            classWriter.WriteLine("return true;");
+            classWriter.Indent--;
+        }
+        classWriter.Indent--;
+        classWriter.WriteLine("}");
+        classWriter.WriteLine();
+        classWriter.WriteLine("return false;");
+        classWriter.Indent--;
+        classWriter.WriteLine("}");
+        classWriter.WriteLine();
+    }
+
+    private static void GenerateGetEnumDescriptionsMethod(IndentedTextWriter classWriter, EnumDetails details)
+    {
+        classWriter.WriteLine("/// <summary>");
+        classWriter.WriteLine("/// Gets the descriptions of the set flags. Assumes the enum is a flags enum.");
+        classWriter.WriteLine("/// If no description exists, returns the ToString() value of the input value.");
+        classWriter.WriteLine("/// </summary>");
+        classWriter.WriteLine("/// <param name=\"value\">Enum value.</param>");
+        classWriter.WriteLine("/// <returns>Array of descriptions.</returns>");
+        classWriter.WriteLine($"public static string[] Get{details.EnumName}Descriptions({details.EnumName} value)");
+        classWriter.WriteLine("{");
+        classWriter.Indent++;
+        foreach (var (name, value, description) in details.Values)
+        {
+            if (!IsPow2(value))
+            {
+                var toStringValue = description ?? $"\"{name}\"";
+                classWriter.WriteLine($"if (value is {details.EnumName}.{name}) return [{toStringValue}];");
+            }
+        }
+        classWriter.WriteLine("var setFlags = BitOperations.PopCount((ulong)value);");
+        classWriter.WriteLine("if (setFlags == 1)");
+        classWriter.WriteLine("{");
+        classWriter.Indent++;
+        classWriter.WriteLine("return value switch");
+        classWriter.WriteLine("{");
+        classWriter.Indent++;
+        foreach (var (name, value, description) in details.Values)
+        {
+            if (description is null) continue;
+            if (!IsPow2(value)) continue;
+            classWriter.WriteLine($"{details.EnumName}.{name} => [{description}],");
+        }
+        classWriter.WriteLine($"_ => [value.ToString()],");
+        classWriter.Indent--;
+        classWriter.WriteLine("};");
+        classWriter.Indent--;
+        classWriter.WriteLine("}");
+        classWriter.WriteLine();
+        classWriter.WriteLine("var descriptions = new string[setFlags];");
+        classWriter.WriteLine("var index = 0;");
+        foreach (var (name, value, description) in details.Values)
+        {
+            if (description is null) continue;
+            if (!IsPow2(value)) continue;
+            classWriter.WriteLine($"if ((value & {details.EnumName}.{name}) != 0) descriptions[index++] = {description};");
+        }
+        classWriter.WriteLine();
+        classWriter.WriteLine("return descriptions;");
+        classWriter.Indent--;
+        classWriter.WriteLine("}");
+    }
+
+    static bool IsPow2(object? value)
+    {
+        if (value is int x) return x != 0 && (x & (x - 1)) == 0;
+        return false;
+    }
+
+    private record struct EnumDetails(string Namespace, string EnumName, EquatableArray<(string Name, object? Value, string? Description)> Values);
+
+    private class EnumDetailsComparer : IEqualityComparer<EnumDetails>
+    {
+        public bool Equals(EnumDetails x, EnumDetails y) => x.EnumName.Equals(y.EnumName) && x.Namespace.Equals(y.Namespace) && x.Values.SequenceEqual(y.Values);
+        public int GetHashCode(EnumDetails obj)
+        {
+            var hash = new HashCode();
+            hash.Add(obj.EnumName);
+            hash.Add(obj.Namespace);
+            foreach (var value in obj.Values)
+            {
+                hash.Add(value);
+            }
+            return hash.ToHashCode();
+        }
+    }
+}