feat: Justification Property in Ignore Attributes and Diagnostic

docs/docs/configuration/analyzer-diagnostics/RMG096.mdx

@@ -0,0 +1,30 @@
+---
+sidebar_label: RMG096
+description: 'Mapperly analyzer diagnostic RMG096 — Ignored mapping is missing Justification'
+---
+
+# RMG096 — Ignored mapping is missing Justification
+
+If Mapperly detects a mapping ignore without a Justification, `RMG096` is emitted.
+
+The following attributes may raise this diagnostic:
+
+- `MapperIgnoreSource`
+- `MapperIgnoreTarget`
+- `MapperIgnoreSourceValue`
+- `MapperIgnoreTargetValue`
+
+To fix this, add a Justification to the attribute, for example:
+
+```csharp
+public partial class Mapper {
+	[MapperIgnoreSource(nameof(SourceClass.IgnoredProperty), Justification = "This source member is not relevant for the target mapping")]
+	public partial TargetClass Map(SourceClass source);
+}
+
+class SourceClass {
+	string IgnoredProperty { get; set; }
+}
+
+class TargetClass { }
+```

src/Riok.Mapperly.Abstractions/MapperIgnoreSourceAttribute.cs

@@ -22,4 +22,14 @@ public MapperIgnoreSourceAttribute(string source)
     /// Gets the source property name which should be ignored from the mapping.
     /// </summary>
     public string Source { get; }
+
+    /// <summary>
+    /// Gets or sets the justification for ignoring the source property.
+    /// This is only used for documentation purposes and does not have any effect on the mapping.
+    /// </summary>
+    /// <remarks>
+    /// You can enforce the presence of Justifications by setting the diagnostic severity of <c>RMG096</c> in your
+    /// <c>.editorconfig</c> to any value other than <c>hidden</c>.
+    /// </remarks>
+    public string? Justification { get; set; }
 }

src/Riok.Mapperly/AnalyzerReleases.Shipped.md

@@ -214,3 +214,4 @@ RMG092 | Mapper | Error | Source type is not assignable to the included source t
 RMG093 | Mapper | Error | Target type is not assignable to the included target type
 RMG094 | Mapper | Error | Circular existing target mapping without setter detected
 RMG095 | Mapper | Warning | Invalid MSBuild configuration option
+RMG096 | Mapper | Hidden | A MapperIgnore* attribute does not specify a Justification

src/Riok.Mapperly/Configuration/MapperConfigurationReader.cs

@@ -217,16 +217,16 @@ private MembersMappingConfiguration BuildMembersConfig(MappingConfigurationRefer
         if (configRef.Method == null)
             return MapperConfiguration.Members;
 
-        var ignoredSourceMembers = _dataAccessor
+        var ignoreSourceMemberAttributes = _dataAccessor
             .Access<MapperIgnoreSourceAttribute>(configRef.Method)
-            .Select(x => x.Source)
-            .WhereNotNull()
+            .WhereNotNullBy(static attr => attr.Source)
             .ToList();
-        var ignoredTargetMembers = _dataAccessor
+        var ignoredSourceMembers = ignoreSourceMemberAttributes.Select(x => x.Source).ToList();
+        var ignoreTargetMemberAttributes = _dataAccessor
             .Access<MapperIgnoreTargetAttribute>(configRef.Method)
-            .Select(x => x.Target)
-            .WhereNotNull()
+            .WhereNotNullBy(static attr => attr.Target)
             .ToList();
+        var ignoredTargetMembers = ignoreTargetMemberAttributes.Select(x => x.Target).ToList();
         var memberValueConfigurations = _dataAccessor.Access<MapValueAttribute, MemberValueMappingConfiguration>(configRef.Method).ToList();
         var memberConfigurations = _dataAccessor
             .Access<MapPropertyAttribute, MemberMappingConfiguration>(configRef.Method)
@@ -259,6 +259,15 @@ private MembersMappingConfiguration BuildMembersConfig(MappingConfigurationRefer
             return MapperConfiguration.Members;
         }
 
+        foreach (var missingIgnoreSourceJustificationAttribute in ignoreSourceMemberAttributes.Where(attr => attr.Justification is null))
+        {
+            _diagnostics.ReportDiagnostic(
+                DiagnosticDescriptors.MapperIgnoreAttributeMissingJustification,
+                configRef.Method,
+                missingIgnoreSourceJustificationAttribute.Source
+            );
+        }
+
         foreach (var invalidMemberConfig in memberValueConfigurations.Where(x => !x.IsValid))
         {
             _diagnostics.ReportDiagnostic(DiagnosticDescriptors.InvalidMapValueAttributeUsage, invalidMemberConfig.Location);

src/Riok.Mapperly/Diagnostics/DiagnosticDescriptors.cs

@@ -808,6 +808,15 @@ public static class DiagnosticDescriptors
         true
     );
 
+    public static readonly DiagnosticDescriptor MapperIgnoreAttributeMissingJustification = new(
+        "RMG096",
+        "Ignored mapping is missing Justification",
+        "The ignored mapping of {0} does not specify a Justification, consider adding one for documentation purposes",
+        DiagnosticCategories.Mapper,
+        DiagnosticSeverity.Hidden,
+        true
+    );
+
     private static string BuildHelpUri(string id)
     {
 #if ENV_NEXT

src/Riok.Mapperly/Helpers/EnumerableExtensions.cs

@@ -18,6 +18,14 @@ public static IEnumerable<T> WhereNotNull<T>(this IEnumerable<T?> enumerable)
 #nullable restore
     }
 
+    public static IEnumerable<TItem> WhereNotNullBy<TItem, TSelector>(this IEnumerable<TItem> enumerable, Func<TItem, TSelector?> selector)
+        where TSelector : notnull
+    {
+#nullable disable
+        return enumerable.Where(x => selector(x) != null);
+#nullable restore
+    }
+
     public static IEnumerable<T> SkipLast<T>(this IEnumerable<T> enumerable)
     {
         using var enumerator = enumerable.GetEnumerator();

test/Riok.Mapperly.Abstractions.Tests/_snapshots/PublicApiTest.PublicApiHasNotChanged.verified.cs

@@ -178,6 +178,7 @@ public MapperIgnoreObsoleteMembersAttribute(Riok.Mapperly.Abstractions.IgnoreObs
     public sealed class MapperIgnoreSourceAttribute : System.Attribute
     {
         public MapperIgnoreSourceAttribute(string source) { }
+        public string? Justification { get; set; }
         public string Source { get; }
     }
     [System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple=true)]

test/Riok.Mapperly.Tests/DocumentationDiagnostics/MapperIgnoreJustificationTests.cs

@@ -0,0 +1,62 @@
+using System.Collections.Immutable;
+using Microsoft.CodeAnalysis;
+using Riok.Mapperly.Diagnostics;
+
+namespace Riok.Mapperly.Tests.DocumentationDiagnostics;
+
+public class MapperIgnoreJustificationTests
+{
+    private TestHelperOptions TestHelperOptions =>
+        TestHelperOptions.Default with
+        {
+            IgnoredDiagnostics = TestHelperOptions
+                .DefaultIgnoredDiagnostics.Except([DiagnosticDescriptors.MapperIgnoreAttributeMissingJustification])
+                .ToImmutableHashSet(),
+            AllowedDiagnosticSeverities = new HashSet<DiagnosticSeverity>() { DiagnosticSeverity.Hidden },
+        };
+
+    [Fact]
+    public void MapperIgnoreSourceShouldNotReportAttributeWithJustification()
+    {
+        var source = TestSourceBuilder.MapperWithBodyAndTypes(
+            "[MapperIgnoreSource(nameof(A.Value), Justification = \"Justification\")] partial B Map(A source);",
+            """
+            class A 
+            {
+                public int Value { get; set; }
+            }
+            """,
+            """
+            class B { }
+            """
+        );
+
+        TestHelper.GenerateMapper(source, TestHelperOptions).Should().HaveAssertedAllDiagnostics();
+    }
+
+    [Fact]
+    public void MapperIgnoreSourceShouldReportMissingJustification()
+    {
+        var source = TestSourceBuilder.MapperWithBodyAndTypes(
+            "[MapperIgnoreSource(nameof(A.Value))] partial B Map(A source);",
+            """
+            class A 
+            {
+                public int Value { get; set; }
+            }
+            """,
+            """
+            class B { }
+            """
+        );
+
+        TestHelper
+            .GenerateMapper(source, TestHelperOptions)
+            .Should()
+            .HaveDiagnostic(
+                DiagnosticDescriptors.MapperIgnoreAttributeMissingJustification,
+                "The ignored mapping of Value does not specify a Justification, consider adding one for documentation purposes"
+            )
+            .HaveAssertedAllDiagnostics();
+    }
+}

test/Riok.Mapperly.Tests/Mapping/DerivedTypeTest.cs

@@ -228,7 +228,7 @@ public Task WithBaseTypeMapPropertyAndSeparateMethodShouldWork()
             [MapProperty(nameof(A.BaseValueA), nameof(B.BaseValueB)]
             public partial B Map(A src);
 
-            [MapperIgnoreSource(nameof(A.BaseValueA)]
+            [MapperIgnoreSource(nameof(A.BaseValueA), Justification = "BaseValueA is ignored for testing purposes")]
             [MapperIgnoreTarget(nameof(B.BaseValueB)]
             public partial BSubType1 Map(ASubType1 src);
             """,

test/Riok.Mapperly.Tests/Mapping/IncludeMappingConfigurationTest.cs

@@ -47,7 +47,7 @@ public Task UsesMapperIgnoreSourceFromTargetMapper()
     {
         var source = TestSourceBuilder.MapperWithBodyAndTypes(
             """
-            [MapperIgnoreSource(nameof(A.Ignored))]
+            [MapperIgnoreSource(nameof(A.Ignored), Justification = "Property is ignored for testing purposes")]
             partial B MapOther(A a);
 
             [IncludeMappingConfiguration(nameof(MapOther))]

test/Riok.Mapperly.Tests/Mapping/ReferenceHandlingTest.cs

@@ -436,7 +436,7 @@ public Task MultipleUserDefinedWithSpecifiedDefault()
             """
             public partial B Map(A a);
             private partial D MapD(C source);
-            [MapperIgnoreSource("IntValue")]
+            [MapperIgnoreSource("IntValue", Justification = "IntValue is ignored for testing purposes")]
             [MapperIgnoreTarget("IntValue")]
             [UserMapping(Default = true)]
             private partial D MapDIgnore(C source);

test/Riok.Mapperly.Tests/TestHelperOptions.cs

@@ -19,13 +19,18 @@ public record TestHelperOptions(
     IReadOnlyDictionary<string, string>? AnalyzerConfigOptions = null
 )
 {
+    public static readonly IReadOnlySet<DiagnosticDescriptor> DefaultIgnoredDiagnostics = new HashSet<DiagnosticDescriptor>
+    {
+        // ignore NoMemberMappings as a lot of tests use this for simplicity
+        DiagnosticDescriptors.NoMemberMappings,
+        // ignore missing Justification properties unless specifically tested for,
+        // in which case the diagnostic is removed before using the options.
+        DiagnosticDescriptors.MapperIgnoreAttributeMissingJustification,
+    };
+
     public static readonly TestHelperOptions Default = new(
         AllowedDiagnosticSeverities: new HashSet<DiagnosticSeverity>(),
-        IgnoredDiagnostics: new HashSet<DiagnosticDescriptor>
-        {
-            // ignore NoMemberMappings as a lot of tests use this for simplicity
-            DiagnosticDescriptors.NoMemberMappings,
-        }
+        IgnoredDiagnostics: DefaultIgnoredDiagnostics
     );
 
     public static readonly TestHelperOptions DisabledNullable = Default with { NullableOption = NullableContextOptions.Disable };