Add LogMethodMarkup source-generation support (Fixes #1)

Author: xoofx

site/docs/aot.md

@@ -22,7 +22,7 @@ Replace `win-x64` with your runtime identifier.
 
 ## Guidance
 
-- Prefer source-generated APIs (`[LogMethod]`, `[LogFormatter]`) for predictable codegen.
+- Prefer source-generated APIs (`[LogMethod]`, `[LogMethodMarkup]`, `[LogFormatter]`) for predictable codegen.
 - Avoid reflection-based custom sinks on the hot path.
 - Keep custom formatters span-based (`TryFormat`) to avoid trimming surprises around serializer/runtime helpers.
 - If your sink depends on external libraries, validate their trimming/AOT compatibility separately.
@@ -33,4 +33,3 @@ Replace `win-x64` with your runtime identifier.
 - Run startup/shutdown log paths.
 - Run representative `Info`, `Warn`, `Error` logging with properties/scopes.
 - Validate file/JSON/terminal sink output in published binaries.
-

site/docs/microsoft-extensions-logging.md

@@ -21,7 +21,7 @@ Migration is API-level: update startup configuration and logging call sites.
 | `LogLevel` | `LogLevel` |
 | `EventId` | `LogEventId` |
 | `BeginScope(...)` | `BeginScope(LogProperties)` |
-| `LoggerMessageAttribute` | `[LogMethod]` |
+| `LoggerMessageAttribute` | `[LogMethod]` / `[LogMethodMarkup]` |
 | `appsettings` provider config | `LogManagerConfig` + code configuration |
 
 ## Minimal migration example
@@ -124,7 +124,7 @@ Use `Block` when correctness is more important than producer latency.
 
 1. Introduce `LogManager` startup/shutdown lifecycle.
 2. Replace logger injection with `Logger` access (`LogManager.GetLogger(...)`) at app entry points/services.
-3. Migrate high-traffic logs first to `[LogMethod]` or interpolated APIs.
+3. Migrate high-traffic logs first to `[LogMethod]` / `[LogMethodMarkup]` or interpolated APIs.
 4. Move sinks to `FileLogWriter`/`JsonFileLogWriter`/`TerminalLogWriter` as needed.
 5. Validate throughput and behavior with [Benchmarks](benchmarks.md) and app-specific load tests.
 

site/docs/packages.md

@@ -20,7 +20,7 @@ Includes:
 - Sync/async processors
 - Built-in formatters
 - Stream/file/json writers
-- Embedded source generators/analyzers (`[LogMethod]`, `[LogFormatter]`)
+- Embedded source generators/analyzers (`[LogMethod]`, `[LogMethodMarkup]`, `[LogFormatter]`)
 
 ## Terminal sink
 
@@ -47,6 +47,7 @@ Includes:
 After restore/build, generated members should appear in IDE for:
 
 - `[LogMethod]` partial methods
+- `[LogMethodMarkup]` partial methods
 - `[LogFormatter]` partial records/properties
 
 If not, verify analyzer wiring in your project file.

site/docs/readme.md

@@ -26,7 +26,7 @@ This section is organized as a practical map: start quickly, then go deeper by t
 ## Formatting and generated APIs
 
 - [Log Formatters](log-formatter.md): built-in formatters, template syntax, and custom formatter generation.
-- [Source-generated Logging](source-generator.md): `[LogMethod]` and diagnostics.
+- [Source-generated Logging](source-generator.md): `[LogMethod]`, `[LogMethodMarkup]`, and diagnostics.
 
 ## Terminal and UI output
 

site/docs/source-generator.md

@@ -9,6 +9,7 @@ title: "Source-generated Logging"
 This generator covers two features:
 
 - `[LogMethod]`: generates strongly-typed logging methods from message templates.
+- `[LogMethodMarkup]`: same as `[LogMethod]`, but generated methods mark the message as markup.
 - `[LogFormatter]`: generates high-performance text formatters from declarative templates.
 
 ## Attribute-based API
@@ -28,13 +29,29 @@ public static partial class AppLogs
 }
 ```
 
+Markup-aware generated methods use `[LogMethodMarkup]`:
+
+```csharp
+using XenoAtom.Logging;
+
+public static partial class AppLogs
+{
+    [LogMethodMarkup(LogLevel.Info, "[green]User {userId} connected[/]")]
+    public static partial void UserConnectedMarkup(Logger logger, int userId);
+}
+```
+
+`[LogMethodMarkup]` requires the `XenoAtom.Logging.Terminal` package, because generated code routes through the terminal markup APIs.
+
 The generator emits method implementations that:
 
 - perform a level check (`logger.IsEnabled(level)`)
 - construct optional `LogEventId`
-- call the matching generated `LoggerExtensions` level method
+- call the matching generated `LoggerExtensions` method (`[LogMethod]`) or `LoggerMarkupExtensions.LogMarkup` (`[LogMethodMarkup]`)
 - emit interpolation code derived from the compile-time template
 
+`[LogMethodMarkup]` sets the message markup flag (`LogMessage.IsMarkup = true`), so terminal sinks can render markup while file/stream/json sinks keep stripping tags as documented.
+
 ## Message template rules
 
 - Placeholder syntax: `{name}`, `{name,alignment}`, `{name:format}`, `{name,alignment:format}`
@@ -48,10 +65,11 @@ The generator emits method implementations that:
 
 ## Generator diagnostics
 
-- `XLG0001`: invalid `[LogMethod]` signature
+- `XLG0001`: invalid `[LogMethod]` or `[LogMethodMarkup]` signature
 - `XLG0002`: unsupported log level
 - `XLG0003`: invalid message template
 - `XLG0004`: unknown template parameter
+- `XLG0005`: missing `XenoAtom.Logging.Terminal` reference for `[LogMethodMarkup]`
 
 ## Log formatters
 

site/docs/terminal.md

@@ -120,6 +120,8 @@ logger.InfoMarkup("[green]ready[/] [gray]service started[/]");
 logger.ErrorMarkup($"[red]failed[/] request={requestId}");
 ```
 
+You can also generate markup-aware methods with `[LogMethodMarkup]`; see [Source-generated Logging](source-generator.md).
+
 When using interpolated markup messages, formatted values are escaped:
 
 ```csharp

src/XenoAtom.Logging.Generators/LogMethodDiagnostics.cs

@@ -10,7 +10,7 @@ internal static class LogMethodDiagnostics
 {
     public static readonly DiagnosticDescriptor InvalidMethodSignature = new(
         id: "XLG0001",
-        title: "Invalid [LogMethod] signature",
+        title: "Invalid [LogMethod] or [LogMethodMarkup] signature",
         messageFormat: "Method '{0}' cannot be source-generated: {1}",
         category: "XenoAtom.Logging.Generators",
         defaultSeverity: DiagnosticSeverity.Error,
@@ -40,6 +40,14 @@ internal static class LogMethodDiagnostics
         defaultSeverity: DiagnosticSeverity.Error,
         isEnabledByDefault: true);
 
+    public static readonly DiagnosticDescriptor MissingMarkupSupport = new(
+        id: "XLG0005",
+        title: "Missing markup logging support",
+        messageFormat: "Method '{0}' uses [LogMethodMarkup], but the XenoAtom.Logging.Terminal package is not referenced.",
+        category: "XenoAtom.Logging.Generators",
+        defaultSeverity: DiagnosticSeverity.Error,
+        isEnabledByDefault: true);
+
     public static readonly DiagnosticDescriptor AllocationRiskParameter = new(
         id: "XLG0100",
         title: "Potential logging allocation",

src/XenoAtom.Logging.Generators/LogMethodGenerator.cs

@@ -12,29 +12,41 @@
 namespace XenoAtom.Logging.Generators;
 
 /// <summary>
-/// Generates implementations for methods annotated with <c>[LogMethod]</c>.
+/// Generates implementations for methods annotated with <c>[LogMethod]</c> and <c>[LogMethodMarkup]</c>.
 /// </summary>
 [Generator(LanguageNames.CSharp)]
 public sealed class LogMethodGenerator : IIncrementalGenerator
 {
     /// <inheritdoc />
     public void Initialize(IncrementalGeneratorInitializationContext context)
     {
-        var generatedMethods = context.SyntaxProvider
+        var logMethods = context.SyntaxProvider
             .ForAttributeWithMetadataName(
                 LogMethodUtilities.LogMethodAttributeMetadataName,
                 static (node, _) => node is MethodDeclarationSyntax { AttributeLists.Count: > 0 },
-                static (ctx, ct) => TryCreateGenerationResult(ctx, ct))
+                static (ctx, ct) => TryCreateGenerationResult(ctx, isMarkupMethod: false, ct));
+
+        var logMarkupMethods = context.SyntaxProvider
+            .ForAttributeWithMetadataName(
+                LogMethodUtilities.LogMethodMarkupAttributeMetadataName,
+                static (node, _) => node is MethodDeclarationSyntax { AttributeLists.Count: > 0 },
+                static (ctx, ct) => TryCreateGenerationResult(ctx, isMarkupMethod: true, ct));
+
+        var generatedLogMethods = logMethods
             .Where(static result => result is not null)
             .Select(static (result, _) => result!.Value)
             .WithComparer(LogMethodGenerationResultComparer.Instance);
 
-        context.RegisterSourceOutput(
-            generatedMethods,
-            static (spc, result) => Emit(spc, result));
+        var generatedLogMarkupMethods = logMarkupMethods
+            .Where(static result => result is not null)
+            .Select(static (result, _) => result!.Value)
+            .WithComparer(LogMethodGenerationResultComparer.Instance);
+
+        context.RegisterSourceOutput(generatedLogMethods, Emit);
+        context.RegisterSourceOutput(generatedLogMarkupMethods, Emit);
     }
 
-    private static LogMethodGenerationResult? TryCreateGenerationResult(GeneratorAttributeSyntaxContext context, CancellationToken cancellationToken)
+    private static LogMethodGenerationResult? TryCreateGenerationResult(GeneratorAttributeSyntaxContext context, bool isMarkupMethod, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
         if (context.TargetSymbol is not IMethodSymbol methodSymbol)
@@ -47,12 +59,12 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
             return null;
         }
 
-        if (!LogMethodUtilities.TryGetLogMethodAttribute(methodSymbol, out var attribute) || attribute is null)
+        if (context.Attributes is not { Length: > 0 })
         {
             return null;
         }
 
-        return GenerateMethod(context.SemanticModel.Compilation, methodSymbol, attribute);
+        return GenerateMethod(context.SemanticModel.Compilation, methodSymbol, context.Attributes[0], isMarkupMethod);
     }
 
     private static void Emit(SourceProductionContext context, LogMethodGenerationResult result)
@@ -68,10 +80,21 @@ private static void Emit(SourceProductionContext context, LogMethodGenerationRes
         }
     }
 
-    private static LogMethodGenerationResult GenerateMethod(Compilation compilation, IMethodSymbol methodSymbol, AttributeData attribute)
+    private static LogMethodGenerationResult GenerateMethod(Compilation compilation, IMethodSymbol methodSymbol, AttributeData attribute, bool isMarkupMethod)
     {
         var diagnostics = ImmutableArray.CreateBuilder<Diagnostic>();
 
+        if (HasBothLogMethodAttributes(methodSymbol))
+        {
+            Report(
+                diagnostics,
+                LogMethodDiagnostics.InvalidMethodSignature,
+                methodSymbol,
+                methodSymbol.Name,
+                "Only one of [LogMethod] or [LogMethodMarkup] can be applied.");
+            return new LogMethodGenerationResult(null, null, diagnostics.ToImmutable());
+        }
+
         if (!TryValidateMethod(methodSymbol, diagnostics, out var loggerParameter, out var exceptionParameter, out var propertiesParameter))
         {
             return new LogMethodGenerationResult(null, null, diagnostics.ToImmutable());
@@ -82,6 +105,17 @@ private static LogMethodGenerationResult GenerateMethod(Compilation compilation,
             return new LogMethodGenerationResult(null, null, diagnostics.ToImmutable());
         }
 
+        if (isMarkupMethod &&
+            compilation.GetTypeByMetadataName(LogMethodUtilities.LoggerMarkupExtensionsMetadataName) is null)
+        {
+            Report(
+                diagnostics,
+                LogMethodDiagnostics.MissingMarkupSupport,
+                methodSymbol,
+                methodSymbol.Name);
+            return new LogMethodGenerationResult(null, null, diagnostics.ToImmutable());
+        }
+
         var messageTemplate = attribute.ConstructorArguments[1].Value as string;
         if (string.IsNullOrEmpty(messageTemplate))
         {
@@ -122,6 +156,7 @@ private static LogMethodGenerationResult GenerateMethod(Compilation compilation,
             propertiesParameter,
             logLevelValue,
             logMethodName!,
+            isMarkupMethod,
             GetEventIdData(attribute, methodSymbol.Name));
 
         var hintName = CreateHintName(methodSymbol);
@@ -351,6 +386,7 @@ private static string GenerateSource(
         IParameterSymbol? propertiesParameter,
         int logLevelValue,
         string logMethodName,
+        bool isMarkupMethod,
         (bool HasEventId, int EventId, string EventName) eventIdData)
     {
         var source = new StringBuilder();
@@ -439,15 +475,27 @@ private static string GenerateSource(
         arguments.Add(BuildInterpolatedMessage(compilation, tokens, templateParameters));
 
         AppendIndent(source, indent);
-        source.Append("global::XenoAtom.Logging.LoggerExtensions.");
-        source.Append(logMethodName);
-        source.Append('(');
-        source.Append(loggerIdentifier);
+        if (isMarkupMethod)
+        {
+            source.Append("global::XenoAtom.Logging.LoggerMarkupExtensions.LogMarkup(");
+            source.Append(loggerIdentifier);
+            source.Append(", global::XenoAtom.Logging.LogLevel.");
+            source.Append(LogMethodUtilities.GetLogLevelName(logLevelValue));
+        }
+        else
+        {
+            source.Append("global::XenoAtom.Logging.LoggerExtensions.");
+            source.Append(logMethodName);
+            source.Append('(');
+            source.Append(loggerIdentifier);
+        }
+
         if (arguments.Count > 0)
         {
             source.Append(", ");
             source.Append(string.Join(", ", arguments));
         }
+
         source.AppendLine(");");
 
         indent -= 4;
@@ -598,6 +646,26 @@ private static bool HasGenericContainingType(INamedTypeSymbol? containingType)
         return false;
     }
 
+    private static bool HasBothLogMethodAttributes(IMethodSymbol methodSymbol)
+    {
+        var hasLogMethod = false;
+        var hasLogMethodMarkup = false;
+        foreach (var candidate in methodSymbol.GetAttributes())
+        {
+            var attributeName = candidate.AttributeClass?.ToDisplayString();
+            if (attributeName == LogMethodUtilities.LogMethodAttributeMetadataName)
+            {
+                hasLogMethod = true;
+            }
+            else if (attributeName == LogMethodUtilities.LogMethodMarkupAttributeMetadataName)
+            {
+                hasLogMethodMarkup = true;
+            }
+        }
+
+        return hasLogMethod && hasLogMethodMarkup;
+    }
+
     private static string CreateHintName(IMethodSymbol methodSymbol)
     {
         var fullyQualifiedName = methodSymbol.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat);

src/XenoAtom.Logging.Generators/LogMethodUtilities.cs

@@ -13,7 +13,9 @@ namespace XenoAtom.Logging.Generators;
 internal static class LogMethodUtilities
 {
     public const string LogMethodAttributeMetadataName = "XenoAtom.Logging.LogMethodAttribute";
+    public const string LogMethodMarkupAttributeMetadataName = "XenoAtom.Logging.LogMethodMarkupAttribute";
     public const string LoggerMetadataName = "XenoAtom.Logging.Logger";
+    public const string LoggerMarkupExtensionsMetadataName = "XenoAtom.Logging.LoggerMarkupExtensions";
     public const string LogPropertiesMetadataName = "XenoAtom.Logging.LogProperties";
 
     private static readonly SymbolDisplayFormat TypeDisplayFormat =
@@ -22,17 +24,30 @@ internal static class LogMethodUtilities
             SymbolDisplayMiscellaneousOptions.EscapeKeywordIdentifiers);
 
     public static bool TryGetLogMethodAttribute(IMethodSymbol methodSymbol, out AttributeData? attribute)
+        => TryGetLogMethodAttribute(methodSymbol, out attribute, out _);
+
+    public static bool TryGetLogMethodAttribute(IMethodSymbol methodSymbol, out AttributeData? attribute, out bool isMarkup)
     {
         foreach (var candidate in methodSymbol.GetAttributes())
         {
-            if (candidate.AttributeClass?.ToDisplayString() == LogMethodAttributeMetadataName)
+            var attributeName = candidate.AttributeClass?.ToDisplayString();
+            if (attributeName == LogMethodAttributeMetadataName)
+            {
+                attribute = candidate;
+                isMarkup = false;
+                return true;
+            }
+
+            if (attributeName == LogMethodMarkupAttributeMetadataName)
             {
                 attribute = candidate;
+                isMarkup = true;
                 return true;
             }
         }
 
         attribute = null;
+        isMarkup = false;
         return false;
     }