Opt-in parameter to disable auditable fields (#238)

Author: Tim-Maes

docs/09_GenerateDtosAttribute.md

@@ -1,6 +1,6 @@
 # GenerateDtos Attribute Reference
 
-The `[GenerateDtos]` and `[GenerateAuditableDtos]` attributes automatically generate standard CRUD DTOs (Create, Update, Response, Query, Upsert, Patch) for domain models, eliminating the need to manually write repetitive DTO classes.
+The `[GenerateDtos]` attribute automatically generates standard CRUD DTOs (Create, Update, Response, Query, Upsert, Patch) for domain models, eliminating the need to manually write repetitive DTO classes.
 
 ## GenerateDtos Attribute
 
@@ -27,6 +27,7 @@ public class User
 | `OutputType`         | `OutputType`| The output type for generated DTOs (default: Record).               |
 | `Namespace`          | `string?`   | Custom namespace for generated DTOs (default: same as source type). |
 | `ExcludeProperties`  | `string[]`  | Properties to exclude from all generated DTOs.                      |
+| `ExcludeAuditFields` | `bool`      | Automatically exclude common audit fields (default: false). See [Excluding Audit Fields](#excluding-audit-fields). |
 | `Prefix`             | `string?`   | Custom prefix for generated DTO names.                              |
 | `Suffix`             | `string?`   | Custom suffix for generated DTO names.                              |
 | `IncludeFields`      | `bool`      | Include public fields from the source type (default: false).        |
@@ -56,32 +57,62 @@ public class User
 | `Struct`      | Generate as structs      |
 | `RecordStruct`| Generate as record structs |
 
-## GenerateAuditableDtos Attribute
+## Excluding Audit Fields
 
-A specialized version of `GenerateDtos` that automatically excludes common audit fields: `CreatedDate`, `UpdatedDate`, `CreatedAt`, `UpdatedAt`, `CreatedBy`, `UpdatedBy`.
+Use the `ExcludeAuditFields` property to automatically exclude common audit/tracking fields from the generated DTOs.
+
+When `ExcludeAuditFields = true`, the following fields are automatically excluded:
+- `CreatedDate`, `UpdatedDate`
+- `CreatedAt`, `UpdatedAt`
+- `CreatedBy`, `UpdatedBy`
+- `CreatedById`, `UpdatedById`
 
 ### Usage
 
 ```csharp
-[GenerateAuditableDtos(Types = DtoTypes.Create | DtoTypes.Update)]
+[GenerateDtos(Types = DtoTypes.Create | DtoTypes.Update, ExcludeAuditFields = true)]
 public class AuditableEntity
 {
+    public int Id { get; set; }
     public string Name { get; set; }
     public string Description { get; set; }
-    public DateTime CreatedAt { get; set; }
-    public DateTime UpdatedAt { get; set; }
-    public string CreatedBy { get; set; }
-    public string UpdatedBy { get; set; }
+    public DateTime CreatedAt { get; set; }    // Will be excluded
+    public DateTime UpdatedAt { get; set; }    // Will be excluded
+    public string CreatedBy { get; set; }      // Will be excluded
+    public string UpdatedBy { get; set; }      // Will be excluded
 }
 ```
 
-### Parameters
+You can combine `ExcludeAuditFields` with `ExcludeProperties` to exclude additional properties:
+
+```csharp
+[GenerateDtos(ExcludeAuditFields = true, ExcludeProperties = new[] { "InternalNotes", "SecretKey" })]
+public class Product
+{
+    public int Id { get; set; }
+    public string Name { get; set; }
+    public string InternalNotes { get; set; }  // Will be excluded
+    public string SecretKey { get; set; }      // Will be excluded
+    public DateTime CreatedAt { get; set; }    // Will be excluded (audit field)
+}
+```
+
+## Obsolete: GenerateAuditableDtos Attribute
 
-Same as `GenerateDtos` with the addition of automatic exclusion of audit fields.
+> **?? Deprecated:** The `[GenerateAuditableDtos]` attribute has been replaced by `[GenerateDtos]` with `ExcludeAuditFields = true`. The old attribute will be removed in a future version.
+>
+> **Migration:**
+> ```csharp
+> // Old way (deprecated):
+> [GenerateAuditableDtos(Types = DtoTypes.Create)]
+> 
+> // New way:
+> [GenerateDtos(Types = DtoTypes.Create, ExcludeAuditFields = true)]
+> ```
 
 ## Multiple Attribute Usage
 
-Both attributes support multiple applications for fine-grained control:
+The attribute supports multiple applications for fine-grained control:
 
 ```csharp
 [GenerateDtos(Types = DtoTypes.Response, ExcludeProperties = new[] { "Password", "InternalNotes" })]

src/Facet.Attributes/GenerateDtosAttribute.cs

@@ -30,7 +30,7 @@ public enum OutputType
 }
 
 /// <summary>
-/// Generates standard CRUD DTOs (Create, Update, Response, Query, Upsert) for a domain model.
+/// Generates standard CRUD DTOs (Create, Update, Response, Query, Upsert, Patch) for a domain model.
 /// Can be applied multiple times with different configurations for fine-grained control.
 /// </summary>
 [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
@@ -52,10 +52,19 @@ public class GenerateDtosAttribute : Attribute
     public string? Namespace { get; set; }
 
     /// <summary>
-    /// Additional properties to exclude from all generated DTOs.
+    /// Properties to exclude from all generated DTOs.
     /// </summary>
     public string[] ExcludeProperties { get; set; } = Array.Empty<string>();
 
+    /// <summary>
+    /// When true, automatically excludes common audit fields from generated DTOs.
+    /// <para>
+    /// Excluded fields: CreatedDate, UpdatedDate, CreatedAt, UpdatedAt, CreatedBy, UpdatedBy, CreatedById, UpdatedById.
+    /// </para>
+    /// Default is false.
+    /// </summary>
+    public bool ExcludeAuditFields { get; set; } = false;
+
     /// <summary>
     /// Custom prefix for generated DTO names (default: none).
     /// </summary>
@@ -89,10 +98,21 @@ public class GenerateDtosAttribute : Attribute
 }
 
 /// <summary>
-/// Predefined attribute for common auditable entity scenarios.
-/// Automatically excludes common audit fields: CreatedDate, UpdatedDate, CreatedAt, UpdatedAt, CreatedBy, UpdatedBy.
-/// Can be applied multiple times with different configurations for fine-grained control.
+/// Obsolete. Use <see cref="GenerateDtosAttribute"/> with <c>ExcludeAuditFields = true</c> instead.
 /// </summary>
+/// <remarks>
+/// This attribute has been replaced by <see cref="GenerateDtosAttribute"/> with the <c>ExcludeAuditFields</c> property.
+/// </remarks>
+/// <example>
+/// <code>
+/// // Old way (deprecated):
+/// [GenerateAuditableDtos(Types = DtoTypes.Create)]
+/// 
+/// // New way:
+/// [GenerateDtos(Types = DtoTypes.Create, ExcludeAuditFields = true)]
+/// </code>
+/// </example>
+[Obsolete("Use GenerateDtosAttribute with ExcludeAuditFields = true instead. This attribute will be removed in a future version.")]
 [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
 public class GenerateAuditableDtosAttribute : Attribute
 {

src/Facet/Generators/FacetGenerators/GenerateDtosGenerator.cs

@@ -15,6 +15,7 @@ namespace Facet.Generators;
 public sealed class GenerateDtosGenerator : IIncrementalGenerator
 {
     private const string GenerateDtosAttributeName = "Facet.GenerateDtosAttribute";
+    // Keep for backward compatibility with obsolete attribute
     private const string GenerateAuditableDtosAttributeName = "Facet.GenerateAuditableDtosAttribute";
 
     // Diagnostic for generator internal errors
@@ -46,19 +47,21 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
             .ForAttributeWithMetadataName(
                 GenerateDtosAttributeName,
                 predicate: static (node, _) => node is TypeDeclarationSyntax,
-                transform: static (ctx, token) => GetGenerateDtosModels(ctx, token))
+                transform: static (ctx, token) => GetGenerateDtosModels(ctx, token, forceExcludeAuditFields: false))
             .Where(static m => m is not null)
             .SelectMany(static (models, _) => models!);
 
+        // Obsolete attribute: GenerateAuditableDtos (kept for backward compatibility)
         var generateAuditableDtosTargets = context.SyntaxProvider
             .ForAttributeWithMetadataName(
                 GenerateAuditableDtosAttributeName,
                 predicate: static (node, _) => node is TypeDeclarationSyntax,
-                transform: static (ctx, token) => GetGenerateAuditableDtosModels(ctx, token))
+                transform: static (ctx, token) => GetGenerateDtosModels(ctx, token, forceExcludeAuditFields: true))
             .Where(static m => m is not null)
             .SelectMany(static (models, _) => models!);
 
-        var allTargets = generateDtosTargets.Collect().Combine(generateAuditableDtosTargets.Collect())
+        var allTargets = generateDtosTargets.Collect()
+            .Combine(generateAuditableDtosTargets.Collect())
             .Select(static (combined, _) => combined.Left.Concat(combined.Right));
 
         context.RegisterSourceOutput(allTargets, (spc, models) =>
@@ -86,17 +89,7 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
         });
     }
 
-    private static IEnumerable<GenerateDtosTargetModel>? GetGenerateDtosModels(GeneratorAttributeSyntaxContext context, CancellationToken token)
-    {
-        return GetDtosModels(context, token, isAuditable: false);
-    }
-
-    private static IEnumerable<GenerateDtosTargetModel>? GetGenerateAuditableDtosModels(GeneratorAttributeSyntaxContext context, CancellationToken token)
-    {
-        return GetDtosModels(context, token, isAuditable: true);
-    }
-
-    private static IEnumerable<GenerateDtosTargetModel>? GetDtosModels(GeneratorAttributeSyntaxContext context, CancellationToken token, bool isAuditable)
+    private static IEnumerable<GenerateDtosTargetModel>? GetGenerateDtosModels(GeneratorAttributeSyntaxContext context, CancellationToken token, bool forceExcludeAuditFields)
     {
         token.ThrowIfCancellationRequested();
         if (context.TargetSymbol is not INamedTypeSymbol sourceSymbol) return null;
@@ -109,7 +102,7 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
         {
             token.ThrowIfCancellationRequested();
 
-            var model = GetDtosModel(context, attribute, sourceSymbol, isAuditable, token);
+            var model = GetDtosModel(context, attribute, sourceSymbol, forceExcludeAuditFields, token);
             if (model != null)
             {
                 models.Add(model);
@@ -119,7 +112,7 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
         return models.Count > 0 ? models : null;
     }
 
-    private static GenerateDtosTargetModel? GetDtosModel(GeneratorAttributeSyntaxContext context, AttributeData attribute, INamedTypeSymbol sourceSymbol, bool isAuditable, CancellationToken token)
+    private static GenerateDtosTargetModel? GetDtosModel(GeneratorAttributeSyntaxContext context, AttributeData attribute, INamedTypeSymbol sourceSymbol, bool forceExcludeAuditFields, CancellationToken token)
     {
         token.ThrowIfCancellationRequested();
 
@@ -135,6 +128,9 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
             var generateConstructors = GetNamedArg(attribute.NamedArguments, "GenerateConstructors", true);
             var generateProjections = GetNamedArg(attribute.NamedArguments, "GenerateProjections", true);
             var useFullName = GetNamedArg(attribute.NamedArguments, "UseFullName", false);
+            
+            // New property: ExcludeAuditFields (only on GenerateDtosAttribute, not on obsolete attribute)
+            var excludeAuditFields = forceExcludeAuditFields || GetNamedArg(attribute.NamedArguments, "ExcludeAuditFields", false);
 
             // Fix the ExcludeProperties handling
             var userExcludeProperties = new List<string>();
@@ -153,7 +149,7 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
             // Build exclusion list
             var excludeProperties = new HashSet<string>(userExcludeProperties, System.StringComparer.OrdinalIgnoreCase);
 
-            if (isAuditable)
+            if (excludeAuditFields)
             {
                 foreach (var field in DefaultAuditFields)
                 {
@@ -223,8 +219,6 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
         catch (Exception ex)
         {
             // Return null to skip this model, but the error is captured in the exception
-            // Note: In incremental generators, we can't report diagnostics from the transform phase.
-            // Consider adding error information to the model in the future to report in output phase.
             System.Diagnostics.Debug.WriteLine($"GenerateDtos error for {sourceSymbol.Name}: {ex.Message}");
             return null;
         }

test/Facet.Tests/TestModels/GenerateDtosTestEntities.cs

@@ -33,7 +33,8 @@ public class PatchTestEntity
     public decimal Price { get; set; }
 }
 
-[GenerateAuditableDtos(Types = DtoTypes.Create | DtoTypes.Update | DtoTypes.Response, OutputType = OutputType.Class)]
+// Uses ExcludeAuditFields = true to automatically exclude audit fields
+[GenerateDtos(Types = DtoTypes.Create | DtoTypes.Update | DtoTypes.Response, OutputType = OutputType.Class, ExcludeAuditFields = true)]
 public class TestProduct
 {
     public int Id { get; set; }
@@ -92,7 +93,8 @@ public class TestCustomNaming
     public DateTime PublishedAt { get; set; }
 }
 
-[GenerateAuditableDtos(Types = DtoTypes.All, OutputType = OutputType.RecordStruct)]
+// Uses ExcludeAuditFields = true with RecordStruct output
+[GenerateDtos(Types = DtoTypes.All, OutputType = OutputType.RecordStruct, ExcludeAuditFields = true)]
 public class TestCompactEntity
 {
     public int Id { get; set; }