feat: Added MapEnumValueAttribute and support for explicit enum value mapping

.gitignore

@@ -10,3 +10,7 @@ obj/
 
 # dot user settings
 *.DotSettings.user
+
+# Visual Studio code coverage results
+*.coverage
+*.coveragexml

docs/docs/02-configuration/04-enum.mdx

@@ -52,6 +52,27 @@ public partial class CarMapper
 </TabItem>
 </Tabs>
 
+## Manually Mapped Enum Values
+
+When `MapEnumAttribute.ByName` is used, explicit enum values may be overridden using
+the `MapEnumValueAttibute` to the mapping method.
+
+Applied to an explicit enum value pair mapped by this method.
+Attribute is only valid on mapping method with enums as parameters and
+configured with the `ByName` strategy.
+
+```csharp
+[Mapper]
+public partial class CarMapper
+{
+    [MapEnum(EnumMappingStrategy.ByName, IgnoreCase = true)]
+    // highlight-start
+    [MapEnumValue(CarFeature.AWD, CarFeatureDto.AllWheelDrive)]
+    // highlight-end
+    public partial CarFeatureDto MapFeature(CarFeature feature);
+}
+```
+
 ### Strict enum mappings
 
 To enforce strict enum mappings

src/Riok.Mapperly.Abstractions/MapEnumValueAttribute.cs

@@ -0,0 +1,29 @@
+namespace Riok.Mapperly.Abstractions;
+
+/// <summary>
+/// Customizes how enum values are mapped
+/// </summary>
+[AttributeUsage(AttributeTargets.Method)]
+public sealed class MapEnumValueAttribute : Attribute
+{
+    /// <summary>
+    /// Customizes how enum values are mapped
+    /// </summary>
+    /// <param name="source">The enum value to map from</param>
+    /// <param name="target">The enum value to map to</param>
+    public MapEnumValueAttribute(object source, object target)
+    {
+        Source = (Enum)source;
+        Target = (Enum)target;
+    }
+
+    /// <summary>
+    /// What to map to
+    /// </summary>
+    public Enum Target { get; }
+
+    /// <summary>
+    /// What to map from
+    /// </summary>
+    public Enum Source { get; }
+}

src/Riok.Mapperly.Abstractions/PublicAPI.Shipped.txt

@@ -8,6 +8,10 @@ Riok.Mapperly.Abstractions.MapEnumAttribute.IgnoreCase.get -> bool
 Riok.Mapperly.Abstractions.MapEnumAttribute.IgnoreCase.set -> void
 Riok.Mapperly.Abstractions.MapEnumAttribute.MapEnumAttribute(Riok.Mapperly.Abstractions.EnumMappingStrategy strategy) -> void
 Riok.Mapperly.Abstractions.MapEnumAttribute.Strategy.get -> Riok.Mapperly.Abstractions.EnumMappingStrategy
+Riok.Mapperly.Abstractions.MapEnumValueAttribute
+Riok.Mapperly.Abstractions.MapEnumValueAttribute.MapEnumValueAttribute(object! source, object! target) -> void
+Riok.Mapperly.Abstractions.MapEnumValueAttribute.Source.get -> System.Enum!
+Riok.Mapperly.Abstractions.MapEnumValueAttribute.Target.get -> System.Enum!
 Riok.Mapperly.Abstractions.MapperAttribute
 Riok.Mapperly.Abstractions.MapperAttribute.EnabledConversions.get -> Riok.Mapperly.Abstractions.MappingConversionType
 Riok.Mapperly.Abstractions.MapperAttribute.EnabledConversions.set -> void

src/Riok.Mapperly/AnalyzerReleases.Shipped.md

@@ -96,4 +96,7 @@ RMG034  | Mapper   | Error    | Derived source type is specified multiple times,
 RMG035  | Mapper   | Error    | Derived source type is not assignable to parameter type
 RMG036  | Mapper   | Error    | Derived target type is not assignable to return type
 RMG037  | Mapper   | Info     | An enum member could not be found on the source enum
-RMG038  | Mapper   | Info     | An enum member could not be found on the target enum
+RMG038  | Mapper   | Info     | An enum member could not be found on the target enum
+RMG039  | Mapper   | Error    | Enum source value is specified multiple times, a source enum value may only be specified once
+RMG040  | Mapper   | Error    | A target enum member value does not match the target enum type
+RMG041  | Mapper   | Error    | A source enum member value does not match the source enum type

src/Riok.Mapperly/Configuration/AttributeDataAccessor.cs

@@ -86,17 +86,20 @@ arg.Type as IArrayTypeSymbol
     private static object? GetEnumValue(TypedConstant arg)
     {
         var enumType = GetReflectionType(arg.Type ?? throw new InvalidOperationException("Type is null"));
+        // if we can't get the enum type then it's not available to reflection (only accessible by Roslyn) so return the TypedConstant
+        if (enumType == null)
+            return arg;
         return arg.Value == null ? null : Enum.ToObject(enumType, arg.Value);
     }
 
-    private static Type GetReflectionType(ITypeSymbol type)
+    private static Type? GetReflectionType(ITypeSymbol type)
     {
         // other special types not yet supported since they are not used yet.
         if (type.SpecialType == SpecialType.System_String)
             return typeof(string);
 
         var assemblyName = type.ContainingAssembly.Name;
         var qualifiedTypeName = Assembly.CreateQualifiedName(assemblyName, type.ToDisplayString());
-        return Type.GetType(qualifiedTypeName) ?? throw new InvalidOperationException($"Type {qualifiedTypeName} not found");
+        return Type.GetType(qualifiedTypeName);
     }
 }

src/Riok.Mapperly/Configuration/MapEnumValue.cs

@@ -0,0 +1,12 @@
+using Microsoft.CodeAnalysis;
+using Riok.Mapperly.Abstractions;
+
+namespace Riok.Mapperly.Configuration;
+
+/// <summary>
+/// Roslyn representation of <see cref="MapEnumValueAttribute"/>
+/// Keep in sync with <see cref="MapEnumValueAttribute"/>
+/// </summary>
+/// <param name="Source">The source constant of the enum value mapping.</param>
+/// <param name="Target">The target constant of the enum value mapping.</param>
+public record MapEnumValue(TypedConstant Source, TypedConstant Target);

src/Riok.Mapperly/Descriptors/MappingBuilders/EnumMappingBuilder.cs

@@ -1,5 +1,6 @@
 using Microsoft.CodeAnalysis;
 using Riok.Mapperly.Abstractions;
+using Riok.Mapperly.Configuration;
 using Riok.Mapperly.Descriptors.Mappings;
 using Riok.Mapperly.Diagnostics;
 using Riok.Mapperly.Helpers;
@@ -76,6 +77,7 @@ private static TypeMapping BuildEnumToEnumCastMapping(MappingBuilderContext ctx)
 
     private static TypeMapping BuildNameMapping(MappingBuilderContext ctx, bool ignoreCase)
     {
+        var targetFieldsByExplicitValue = BuildExplicitValueMapping(ctx);
         var targetFieldsByName = ctx.Target.GetMembers().OfType<IFieldSymbol>().ToDictionary(x => x.Name);
         var sourceFieldsByName = ctx.Source.GetMembers().OfType<IFieldSymbol>().ToDictionary(x => x.Name);
 
@@ -86,11 +88,14 @@ private static TypeMapping BuildNameMapping(MappingBuilderContext ctx, bool igno
                 .DistinctBy(x => x.Key, StringComparer.OrdinalIgnoreCase)
                 .ToDictionary(x => x.Key, x => x.Value, StringComparer.OrdinalIgnoreCase);
             getTargetField = source =>
-                targetFieldsByName.GetValueOrDefault(source.Name) ?? targetFieldsByNameIgnoreCase.GetValueOrDefault(source.Name);
+                targetFieldsByExplicitValue.GetValueOrDefault(source)
+                ?? targetFieldsByName.GetValueOrDefault(source.Name)
+                ?? targetFieldsByNameIgnoreCase.GetValueOrDefault(source.Name);
         }
         else
         {
-            getTargetField = source => targetFieldsByName.GetValueOrDefault(source.Name);
+            getTargetField = source =>
+                targetFieldsByExplicitValue.GetValueOrDefault(source) ?? targetFieldsByName.GetValueOrDefault(source.Name);
         }
 
         var enumMemberMappings = ctx.Source
@@ -131,4 +136,51 @@ private static TypeMapping BuildNameMapping(MappingBuilderContext ctx, bool igno
 
         return new EnumNameMapping(ctx.Source, ctx.Target, enumMemberMappings);
     }
+
+    private static Dictionary<IFieldSymbol, IFieldSymbol> BuildExplicitValueMapping(MappingBuilderContext ctx)
+    {
+        var values = ctx.ListConfiguration<MapEnumValueAttribute, MapEnumValue>();
+        var targetFieldsByExplicitValue = new Dictionary<IFieldSymbol, IFieldSymbol>(SymbolEqualityComparer.Default);
+        foreach (var (sourceConstant, targetConstant) in values)
+        {
+            var source = sourceConstant.Type!.GetMembers().OfType<IFieldSymbol>().First(e => sourceConstant.Value!.Equals(e.ConstantValue));
+            var target = targetConstant.Type!.GetMembers().OfType<IFieldSymbol>().First(e => targetConstant.Value!.Equals(e.ConstantValue));
+            if (SymbolEqualityComparer.Default.Equals(sourceConstant.Type, ctx.Source))
+            {
+                if (SymbolEqualityComparer.Default.Equals(targetConstant.Type, ctx.Target))
+                {
+                    if (targetFieldsByExplicitValue.ContainsKey(source))
+                    {
+                        ctx.ReportDiagnostic(DiagnosticDescriptors.EnumSourceValueDuplicated, source, ctx.Source, ctx.Target);
+                    }
+                    else
+                    {
+                        targetFieldsByExplicitValue.Add(source, target);
+                    }
+                }
+                else
+                {
+                    ctx.ReportDiagnostic(
+                        DiagnosticDescriptors.TargetEnumValueDoesNotMatchTargetEnumType,
+                        target,
+                        targetConstant.Value ?? 0,
+                        target.Type,
+                        ctx.Target
+                    );
+                }
+            }
+            else
+            {
+                ctx.ReportDiagnostic(
+                    DiagnosticDescriptors.SourceEnumValueDoesNotMatchSourceEnumType,
+                    source,
+                    sourceConstant.Value ?? 0,
+                    source.Type,
+                    ctx.Source
+                );
+            }
+        }
+
+        return targetFieldsByExplicitValue;
+    }
 }

src/Riok.Mapperly/Diagnostics/DiagnosticDescriptors.cs

@@ -338,4 +338,31 @@ internal static class DiagnosticDescriptors
         DiagnosticSeverity.Info,
         true
     );
+
+    public static readonly DiagnosticDescriptor EnumSourceValueDuplicated = new DiagnosticDescriptor(
+        "RMG039",
+        "Enum source value is specified multiple times, a source enum value may only be specified once",
+        "Enum source value {0} is specified multiple times, a source enum value may only be specified once",
+        DiagnosticCategories.Mapper,
+        DiagnosticSeverity.Error,
+        true
+    );
+
+    public static readonly DiagnosticDescriptor TargetEnumValueDoesNotMatchTargetEnumType = new DiagnosticDescriptor(
+        "RMG040",
+        "A target enum member value does not match the target enum type",
+        "Enum member {0} ({1}) on {2} does not match type of target enum {3}",
+        DiagnosticCategories.Mapper,
+        DiagnosticSeverity.Error,
+        true
+    );
+
+    public static readonly DiagnosticDescriptor SourceEnumValueDoesNotMatchSourceEnumType = new DiagnosticDescriptor(
+        "RMG041",
+        "A source enum member value does not match the source enum type",
+        "Enum member {0} ({1}) on {2} does not match type of source enum {3}",
+        DiagnosticCategories.Mapper,
+        DiagnosticSeverity.Error,
+        true
+    );
 }

test/Riok.Mapperly.IntegrationTests/Dto/TestEnumDtoExplicitLarger.cs

@@ -0,0 +1,10 @@
+namespace Riok.Mapperly.IntegrationTests.Dto
+{
+    public enum TestEnumDtoExplicitLarger
+    {
+        Value10 = 10_000,
+        Value20 = 20_000,
+        Value30 = 30_000,
+        Value40 = 30_000
+    }
+}

test/Riok.Mapperly.IntegrationTests/Mapper/TestMapper.cs

@@ -62,6 +62,10 @@ public TestObjectDto MapToDto(TestObject src)
         [MapEnum(EnumMappingStrategy.ByName)]
         public partial TestEnumDtoByName MapToEnumDtoByName(TestEnum v);
 
+        [MapEnum(EnumMappingStrategy.ByName)]
+        [MapEnumValue(TestEnumDtoExplicitLarger.Value40, TestEnum.Value30)]
+        public partial TestEnum MapToEnumDtoByNameWithExplicit(TestEnumDtoExplicitLarger v);
+
         [MapperIgnoreTarget(nameof(TestObjectDto.IgnoredIntValue))]
         [MapperIgnoreSource(nameof(TestObject.IgnoredStringValue))]
         public partial void UpdateDto(TestObject source, TestObjectDto target);

test/Riok.Mapperly.IntegrationTests/_snapshots/NET_48/MapperTest.SnapshotGeneratedSource.verified.cs

@@ -185,6 +185,17 @@ public partial int ParseableInt(string value)
             };
         }
 
+        public partial global::Riok.Mapperly.IntegrationTests.Models.TestEnum MapToEnumDtoByNameWithExplicit(global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger v)
+        {
+            return v switch
+            {
+                global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger.Value10 => global::Riok.Mapperly.IntegrationTests.Models.TestEnum.Value10,
+                global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger.Value20 => global::Riok.Mapperly.IntegrationTests.Models.TestEnum.Value20,
+                global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger.Value30 => global::Riok.Mapperly.IntegrationTests.Models.TestEnum.Value30,
+                _ => throw new System.ArgumentOutOfRangeException(nameof(v), v, "The value of enum TestEnumDtoExplicitLarger is not supported"),
+            };
+        }
+
         public partial void UpdateDto(global::Riok.Mapperly.IntegrationTests.Models.TestObject source, global::Riok.Mapperly.IntegrationTests.Dto.TestObjectDto target)
         {
             if (source.NullableFlattening != null)

test/Riok.Mapperly.IntegrationTests/_snapshots/Roslyn_4_4_OR_LOWER/MapperTest.SnapshotGeneratedSource.verified.cs

@@ -179,6 +179,17 @@ public partial int ParseableInt(string value)
             };
         }
 
+        public partial global::Riok.Mapperly.IntegrationTests.Models.TestEnum MapToEnumDtoByNameWithExplicit(global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger v)
+        {
+            return v switch
+            {
+                global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger.Value10 => global::Riok.Mapperly.IntegrationTests.Models.TestEnum.Value10,
+                global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger.Value20 => global::Riok.Mapperly.IntegrationTests.Models.TestEnum.Value20,
+                global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger.Value30 => global::Riok.Mapperly.IntegrationTests.Models.TestEnum.Value30,
+                _ => throw new System.ArgumentOutOfRangeException(nameof(v), v, "The value of enum TestEnumDtoExplicitLarger is not supported"),
+            };
+        }
+
         public partial void UpdateDto(global::Riok.Mapperly.IntegrationTests.Models.TestObject source, global::Riok.Mapperly.IntegrationTests.Dto.TestObjectDto target)
         {
             if (source.NullableFlattening != null)

test/Riok.Mapperly.IntegrationTests/_snapshots/Roslyn_4_5/MapperTest.SnapshotGeneratedSource.verified.cs

@@ -185,6 +185,17 @@ public partial int ParseableInt(string value)
             };
         }
 
+        public partial global::Riok.Mapperly.IntegrationTests.Models.TestEnum MapToEnumDtoByNameWithExplicit(global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger v)
+        {
+            return v switch
+            {
+                global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger.Value10 => global::Riok.Mapperly.IntegrationTests.Models.TestEnum.Value10,
+                global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger.Value20 => global::Riok.Mapperly.IntegrationTests.Models.TestEnum.Value20,
+                global::Riok.Mapperly.IntegrationTests.Dto.TestEnumDtoExplicitLarger.Value30 => global::Riok.Mapperly.IntegrationTests.Models.TestEnum.Value30,
+                _ => throw new System.ArgumentOutOfRangeException(nameof(v), v, "The value of enum TestEnumDtoExplicitLarger is not supported"),
+            };
+        }
+
         public partial void UpdateDto(global::Riok.Mapperly.IntegrationTests.Models.TestObject source, global::Riok.Mapperly.IntegrationTests.Dto.TestObjectDto target)
         {
             if (source.NullableFlattening != null)
@@ -338,4 +349,4 @@ private string MapToString1(global::Riok.Mapperly.IntegrationTests.Dto.TestEnumD
             return target;
         }
     }
-}
+}