feat(v1.7): [ExtractProperty] and [WrapProperty] for entity↔primitive mapping (#127)

docs/SPEC-v1.7-projection-and-conditional.md

@@ -6,9 +6,9 @@ v1.7 closes three AutoMapper-parity gaps surfaced by the [Duende.IdentityServer.
 
 | # | Feature | Issue | Effort | Status |
 |---|---------|-------|--------|--------|
-| 1 | Per-property LINQ projection (`SelectProperty`) | [#125](https://github.com/superyyrrzz/ForgeMap/issues/125) | Low | Planned |
+| 1 | Per-property LINQ projection (`SelectProperty`) | [#125](https://github.com/superyyrrzz/ForgeMap/issues/125) | Low | Implemented |
 | 2 | Conditional property assignment (`Condition`, `SkipWhen`) | [#126](https://github.com/superyyrrzz/ForgeMap/issues/126) | Medium | Implemented |
-| 3 | Entity↔primitive mapping (`[ExtractProperty]`, `[WrapProperty]`) | [#127](https://github.com/superyyrrzz/ForgeMap/issues/127) | Medium | Planned |
+| 3 | Entity↔primitive mapping (`[ExtractProperty]`, `[WrapProperty]`) | [#127](https://github.com/superyyrrzz/ForgeMap/issues/127) | Medium | Implemented |
 
 Features 1 and 3 compose naturally: `SelectProperty` extracts a primitive from each element in a collection, while `[ExtractProperty]` / `[WrapProperty]` handle the single-element case. Both target the same join-table-entity pattern from opposite ends.
 

src/ForgeMap.Abstractions/ExtractPropertyAttribute.cs

@@ -0,0 +1,28 @@
+using System;
+
+namespace ForgeMap;
+
+/// <summary>
+/// Marks a partial forge method that returns a single property of the source object.
+/// The method must have signature <c>partial TPrimitive MethodName(TEntity source)</c>.
+/// The generator emits a null-guard governed by <c>NullHandling</c>, then returns
+/// <c>source.PropertyName</c> (with built-in coercion if needed for the declared return type).
+/// Available in ForgeMap v1.7+.
+/// </summary>
+[AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = false)]
+public sealed class ExtractPropertyAttribute : Attribute
+{
+    /// <summary>
+    /// Creates a new <see cref="ExtractPropertyAttribute"/>.
+    /// </summary>
+    /// <param name="propertyName">Name of the readable instance property on the source type to return.</param>
+    public ExtractPropertyAttribute(string propertyName)
+    {
+        PropertyName = propertyName ?? throw new ArgumentNullException(nameof(propertyName));
+    }
+
+    /// <summary>
+    /// Gets the name of the source property to extract.
+    /// </summary>
+    public string PropertyName { get; }
+}

src/ForgeMap.Abstractions/WrapPropertyAttribute.cs

@@ -0,0 +1,30 @@
+using System;
+
+namespace ForgeMap;
+
+/// <summary>
+/// Marks a partial forge method that constructs a new destination object from the source primitive
+/// by assigning or binding it to the named property. The method must have signature
+/// <c>partial TEntity MethodName(TPrimitive source)</c>. The destination type must either expose a
+/// settable (<c>set</c> or <c>init</c>) property of that name or a constructor parameter of that name.
+/// The generator emits the appropriate construction form (<c>new TEntity { Prop = source }</c> or
+/// <c>new TEntity(prop: source)</c>), with null-guarding governed by <c>NullHandling</c>.
+/// Available in ForgeMap v1.7+.
+/// </summary>
+[AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = false)]
+public sealed class WrapPropertyAttribute : Attribute
+{
+    /// <summary>
+    /// Creates a new <see cref="WrapPropertyAttribute"/>.
+    /// </summary>
+    /// <param name="propertyName">Name of the destination property or constructor parameter to assign.</param>
+    public WrapPropertyAttribute(string propertyName)
+    {
+        PropertyName = propertyName ?? throw new ArgumentNullException(nameof(propertyName));
+    }
+
+    /// <summary>
+    /// Gets the name of the destination property or constructor parameter to assign.
+    /// </summary>
+    public string PropertyName { get; }
+}

src/ForgeMap.Generator/AnalyzerReleases.Unshipped.md

@@ -18,3 +18,11 @@ FM0064 | ForgeMap | Disabled | ConditionalAssignmentApplied
 FM0072 | ForgeMap | Error | SelectPropertyConflictsWithForgeFromOrWith
 FM0073 | ForgeMap | Error | SelectPropertyDestinationNotEnumerable
 FM0075 | ForgeMap | Warning | SelectPropertyNotSupportedOnForgeInto
+FM0065 | ForgeMap | Error | ExtractWrapConflictsWithMethodAttributes
+FM0066 | ForgeMap | Error | ExtractPropertyNotFound
+FM0067 | ForgeMap | Error | ExtractPropertyTypeIncompatible
+FM0068 | ForgeMap | Error | WrapPropertyNotFound
+FM0069 | ForgeMap | Error | WrapPropertyTypeIncompatible
+FM0070 | ForgeMap | Error | ExtractWrapInvalidSignature
+FM0071 | ForgeMap | Error | WrapPropertyRequiredMembersUnsatisfied
+FM0074 | ForgeMap | Disabled | ExtractWrapValueTypeReturnUnderReturnNull

src/ForgeMap.Generator/DiagnosticDescriptors.cs

@@ -505,6 +505,70 @@ internal static class DiagnosticDescriptors
         defaultSeverity: DiagnosticSeverity.Warning,
         isEnabledByDefault: true);
 
+    public static readonly DiagnosticDescriptor ExtractWrapConflictsWithMethodAttributes = new(
+        id: "FM0065",
+        title: "[ExtractProperty]/[WrapProperty] cannot combine with [ConvertWith], [ForgeFrom], [ForgeWith], or [ForgeProperty]",
+        messageFormat: "Method '{0}' has conflicting attributes: [ExtractProperty]/[WrapProperty] cannot combine with [ConvertWith], [ForgeFrom], [ForgeWith], or [ForgeProperty]",
+        category: Category,
+        defaultSeverity: DiagnosticSeverity.Error,
+        isEnabledByDefault: true);
+
+    public static readonly DiagnosticDescriptor ExtractPropertyNotFound = new(
+        id: "FM0066",
+        title: "[ExtractProperty] target property not found on source type",
+        messageFormat: "[ExtractProperty(\"{0}\")] not found on source type '{1}' for method '{2}', or not a public readable instance property",
+        category: Category,
+        defaultSeverity: DiagnosticSeverity.Error,
+        isEnabledByDefault: true);
+
+    public static readonly DiagnosticDescriptor ExtractPropertyTypeIncompatible = new(
+        id: "FM0067",
+        title: "[ExtractProperty] source property type incompatible with method return type",
+        messageFormat: "[ExtractProperty] source property type '{0}' is incompatible with method return type '{1}' for method '{2}', and no supported coercion applies",
+        category: Category,
+        defaultSeverity: DiagnosticSeverity.Error,
+        isEnabledByDefault: true);
+
+    public static readonly DiagnosticDescriptor WrapPropertyNotFound = new(
+        id: "FM0068",
+        title: "[WrapProperty] target not found on destination type",
+        messageFormat: "[WrapProperty(\"{0}\")] not found as settable/init property or constructor parameter on destination type '{1}' for method '{2}'",
+        category: Category,
+        defaultSeverity: DiagnosticSeverity.Error,
+        isEnabledByDefault: true);
+
+    public static readonly DiagnosticDescriptor WrapPropertyTypeIncompatible = new(
+        id: "FM0069",
+        title: "[WrapProperty] source parameter type incompatible with destination property/parameter type",
+        messageFormat: "[WrapProperty] source parameter type '{0}' is incompatible with destination property/parameter type '{1}' for method '{2}', and no supported coercion applies",
+        category: Category,
+        defaultSeverity: DiagnosticSeverity.Error,
+        isEnabledByDefault: true);
+
+    public static readonly DiagnosticDescriptor ExtractWrapInvalidSignature = new(
+        id: "FM0070",
+        title: "[ExtractProperty]/[WrapProperty] partial method has invalid signature",
+        messageFormat: "[ExtractProperty]/[WrapProperty] partial method '{0}' has invalid signature — must have exactly one parameter and a non-void return type",
+        category: Category,
+        defaultSeverity: DiagnosticSeverity.Error,
+        isEnabledByDefault: true);
+
+    public static readonly DiagnosticDescriptor WrapPropertyRequiredMembersUnsatisfied = new(
+        id: "FM0071",
+        title: "[WrapProperty] cannot satisfy required members of destination type",
+        messageFormat: "[WrapProperty] cannot construct '{0}' because these required members are unsatisfied: {1}. Add a constructor that accepts these members, mark them init without required, or write the partial body manually.",
+        category: Category,
+        defaultSeverity: DiagnosticSeverity.Error,
+        isEnabledByDefault: true);
+
+    public static readonly DiagnosticDescriptor ExtractWrapValueTypeReturnUnderReturnNull = new(
+        id: "FM0074",
+        title: "[ExtractProperty]/[WrapProperty] value-type return under NullHandling.ReturnNull collapses null source to default",
+        messageFormat: "[ExtractProperty]/[WrapProperty] method '{0}' returns value type '{1}' under NullHandling.ReturnNull; null sources will collapse to default({1}). Audit and consider NullHandling.ThrowException or a nullable return type if the distinction matters.",
+        category: Category,
+        defaultSeverity: DiagnosticSeverity.Info,
+        isEnabledByDefault: false);
+
     public static readonly DiagnosticDescriptor ConditionAndSkipWhenBothSet = new(
         id: "FM0060",
         title: "Condition and SkipWhen are mutually exclusive",

src/ForgeMap.Generator/ForgeCodeEmitter.AttributeDetection.cs

@@ -41,6 +41,50 @@ private bool HasConvertWithAttribute(IMethodSymbol method)
             SymbolEqualityComparer.Default.Equals(a.AttributeClass, _convertWithAttributeSymbol));
     }
 
+    private bool HasExtractPropertyAttribute(IMethodSymbol method)
+    {
+        if (_extractPropertyAttributeSymbol == null)
+            return false;
+
+        return method.GetAttributes().Any(a =>
+            SymbolEqualityComparer.Default.Equals(a.AttributeClass, _extractPropertyAttributeSymbol));
+    }
+
+    private bool HasWrapPropertyAttribute(IMethodSymbol method)
+    {
+        if (_wrapPropertyAttributeSymbol == null)
+            return false;
+
+        return method.GetAttributes().Any(a =>
+            SymbolEqualityComparer.Default.Equals(a.AttributeClass, _wrapPropertyAttributeSymbol));
+    }
+
+    /// <summary>
+    /// Returns the property-name argument from the [ExtractProperty] attribute on this method,
+    /// or null if the attribute is absent or malformed.
+    /// </summary>
+    private string? GetExtractPropertyName(IMethodSymbol method)
+    {
+        if (_extractPropertyAttributeSymbol == null) return null;
+        var attr = method.GetAttributes().FirstOrDefault(a =>
+            SymbolEqualityComparer.Default.Equals(a.AttributeClass, _extractPropertyAttributeSymbol));
+        if (attr == null || attr.ConstructorArguments.Length == 0) return null;
+        return attr.ConstructorArguments[0].Value as string;
+    }
+
+    /// <summary>
+    /// Returns the property-name argument from the [WrapProperty] attribute on this method,
+    /// or null if the attribute is absent or malformed.
+    /// </summary>
+    private string? GetWrapPropertyName(IMethodSymbol method)
+    {
+        if (_wrapPropertyAttributeSymbol == null) return null;
+        var attr = method.GetAttributes().FirstOrDefault(a =>
+            SymbolEqualityComparer.Default.Equals(a.AttributeClass, _wrapPropertyAttributeSymbol));
+        if (attr == null || attr.ConstructorArguments.Length == 0) return null;
+        return attr.ConstructorArguments[0].Value as string;
+    }
+
     private bool HasUseExistingValueAttribute(IParameterSymbol param)
     {
         if (_useExistingValueAttributeSymbol == null)