Add authoring analyzers for [ApiContract] and [ContractVersion]

src/Authoring/WinRT.SourceGenerator2/AnalyzerReleases.Shipped.md

@@ -15,4 +15,10 @@ CSWINRT2005 | WindowsRuntime.SourceGenerator | Error | Null indexer type in '[Ge
 CSWINRT2006 | WindowsRuntime.SourceGenerator | Error | Property name not found for '[GeneratedCustomPropertyProvider]'
 CSWINRT2007 | WindowsRuntime.SourceGenerator | Error | Indexer type not found for '[GeneratedCustomPropertyProvider]'
 CSWINRT2008 | WindowsRuntime.SourceGenerator | Error | Static indexer for '[GeneratedCustomPropertyProvider]'
-CSWINRT2009 | WindowsRuntime.SourceGenerator | Warning | Cast to '[ComImport]' type not supported
+CSWINRT2009 | WindowsRuntime.SourceGenerator | Warning | Cast to '[ComImport]' type not supported
+CSWINRT2010 | WindowsRuntime.SourceGenerator | Warning | API contract enum type with enum cases
+CSWINRT2011 | WindowsRuntime.SourceGenerator | Warning | Invalid 'ContractVersionAttribute' target for version-only constructor
+CSWINRT2012 | WindowsRuntime.SourceGenerator | Warning | Invalid 'ContractVersionAttribute' target for contract-type constructor
+CSWINRT2013 | WindowsRuntime.SourceGenerator | Warning | Invalid 'ContractVersionAttribute' contract type argument
+CSWINRT2014 | WindowsRuntime.SourceGenerator | Warning | API contract type missing 'ContractVersionAttribute'
+CSWINRT2015 | WindowsRuntime.SourceGenerator | Info | Public authored type missing 'ContractVersionAttribute'

src/Authoring/WinRT.SourceGenerator2/Diagnostics/Analyzers/ApiContractTypeRequiresContractVersionAnalyzer.cs

@@ -0,0 +1,78 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Collections.Immutable;
+using System.Linq;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.Diagnostics;
+
+namespace WindowsRuntime.SourceGenerator.Diagnostics;
+
+/// <summary>
+/// A diagnostic analyzer that validates that <c>[ApiContract]</c> enum types declare their contract version using <c>[ContractVersion]</c>.
+/// </summary>
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public sealed class ApiContractTypeRequiresContractVersionAnalyzer : DiagnosticAnalyzer
+{
+    /// <inheritdoc/>
+    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } = [DiagnosticDescriptors.ApiContractTypeMissingContractVersion];
+
+    /// <inheritdoc/>
+    public override void Initialize(AnalysisContext context)
+    {
+        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+        context.EnableConcurrentExecution();
+
+        context.RegisterCompilationStartAction(static context =>
+        {
+            // This analyzer only applies to Windows Runtime component authoring scenarios
+            if (!context.Options.AnalyzerConfigOptionsProvider.GlobalOptions.GetCsWinRTComponent())
+            {
+                return;
+            }
+
+            // Get the '[ApiContract]' symbol
+            if (context.Compilation.GetTypeByMetadataName("Windows.Foundation.Metadata.ApiContractAttribute") is not { } apiContractAttributeType)
+            {
+                return;
+            }
+
+            // Get the '[ContractVersion]' symbol
+            if (context.Compilation.GetTypeByMetadataName("Windows.Foundation.Metadata.ContractVersionAttribute") is not { } contractVersionAttributeType)
+            {
+                return;
+            }
+
+            context.RegisterSymbolAction(context =>
+            {
+                // Only enum types can be valid API contract types
+                if (context.Symbol is not INamedTypeSymbol { TypeKind: TypeKind.Enum } typeSymbol)
+                {
+                    return;
+                }
+
+                // Immediately bail if the type is not an API contract type
+                if (!typeSymbol.HasAttributeWithType(apiContractAttributeType))
+                {
+                    return;
+                }
+
+                // Check whether any '[ContractVersion]' attribute using a version-only constructor is applied
+                foreach (AttributeData attribute in typeSymbol.GetAttributes(contractVersionAttributeType))
+                {
+                    // The version-only constructors are '(uint)' and '(string, uint)'.
+                    // The contract-type constructor is '(Type, uint)', which we want to ignore here.
+                    if (attribute.AttributeConstructor?.Parameters is [{ Type.SpecialType: SpecialType.System_UInt32 or SpecialType.System_String }, ..])
+                    {
+                        return;
+                    }
+                }
+
+                context.ReportDiagnostic(Diagnostic.Create(
+                    DiagnosticDescriptors.ApiContractTypeMissingContractVersion,
+                    typeSymbol.Locations.FirstOrDefault(),
+                    typeSymbol));
+            }, SymbolKind.NamedType);
+        });
+    }
+}

src/Authoring/WinRT.SourceGenerator2/Diagnostics/Analyzers/PublicTypeRequiresContractVersionAnalyzer.cs

@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Collections.Immutable;
+using System.Linq;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.Diagnostics;
+
+namespace WindowsRuntime.SourceGenerator.Diagnostics;
+
+/// <summary>
+/// A diagnostic analyzer that reports when a public authored type is missing a <c>[ContractVersion]</c> attribute.
+/// </summary>
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public sealed class PublicTypeRequiresContractVersionAnalyzer : DiagnosticAnalyzer
+{
+    /// <inheritdoc/>
+    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } = [DiagnosticDescriptors.PublicTypeMissingContractVersion];
+
+    /// <inheritdoc/>
+    public override void Initialize(AnalysisContext context)
+    {
+        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+        context.EnableConcurrentExecution();
+
+        context.RegisterCompilationStartAction(static context =>
+        {
+            // This analyzer only applies to Windows Runtime component authoring scenarios
+            if (!context.Options.AnalyzerConfigOptionsProvider.GlobalOptions.GetCsWinRTComponent())
+            {
+                return;
+            }
+
+            // Get the '[ContractVersion]' symbol
+            if (context.Compilation.GetTypeByMetadataName("Windows.Foundation.Metadata.ContractVersionAttribute") is not { } contractVersionAttributeType)
+            {
+                return;
+            }
+
+            // Get the '[ApiContract]' symbol (used to skip API contract types, which are validated by a different analyzer)
+            INamedTypeSymbol? apiContractAttributeType = context.Compilation.GetTypeByMetadataName("Windows.Foundation.Metadata.ApiContractAttribute");
+
+            context.RegisterSymbolAction(context =>
+            {
+                // Only consider top-level public types
+                if (context.Symbol is not INamedTypeSymbol { DeclaredAccessibility: Accessibility.Public, ContainingType: null } typeSymbol)
+                {
+                    return;
+                }
+
+                // Skip API contract types: those are handled by 'ApiContractTypeRequiresContractVersionAnalyzer'
+                if (apiContractAttributeType is not null &&
+                    typeSymbol is { TypeKind: TypeKind.Enum } &&
+                    typeSymbol.HasAttributeWithType(apiContractAttributeType))
+                {
+                    return;
+                }
+
+                // Skip if any '[ContractVersion]' attribute is already applied (validity of the
+                // specific constructor used is reported by the other 'ContractVersion' analyzers)
+                if (typeSymbol.HasAttributeWithType(contractVersionAttributeType))
+                {
+                    return;
+                }
+
+                context.ReportDiagnostic(Diagnostic.Create(
+                    DiagnosticDescriptors.PublicTypeMissingContractVersion,
+                    typeSymbol.Locations.FirstOrDefault(),
+                    typeSymbol));
+            }, SymbolKind.NamedType);
+        });
+    }
+}

src/Authoring/WinRT.SourceGenerator2/Diagnostics/Analyzers/ValidApiContractEnumTypeAnalyzer.cs

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Collections.Immutable;
+using System.Linq;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.Diagnostics;
+
+namespace WindowsRuntime.SourceGenerator.Diagnostics;
+
+/// <summary>
+/// A diagnostic analyzer that validates that <c>[ApiContract]</c> enum types do not define any enum cases.
+/// </summary>
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public sealed class ValidApiContractEnumTypeAnalyzer : DiagnosticAnalyzer
+{
+    /// <inheritdoc/>
+    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } = [DiagnosticDescriptors.ApiContractEnumWithCases];
+
+    /// <inheritdoc/>
+    public override void Initialize(AnalysisContext context)
+    {
+        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+        context.EnableConcurrentExecution();
+
+        context.RegisterCompilationStartAction(static context =>
+        {
+            // This analyzer only applies to Windows Runtime component authoring scenarios
+            if (!context.Options.AnalyzerConfigOptionsProvider.GlobalOptions.GetCsWinRTComponent())
+            {
+                return;
+            }
+
+            // Get the '[ApiContract]' symbol
+            if (context.Compilation.GetTypeByMetadataName("Windows.Foundation.Metadata.ApiContractAttribute") is not { } attributeType)
+            {
+                return;
+            }
+
+            context.RegisterSymbolAction(context =>
+            {
+                // Only enum types can be annotated with '[ApiContract]'
+                if (context.Symbol is not INamedTypeSymbol { TypeKind: TypeKind.Enum } typeSymbol)
+                {
+                    return;
+                }
+
+                // Immediately bail if the type doesn't have the attribute
+                if (!typeSymbol.HasAttributeWithType(attributeType))
+                {
+                    return;
+                }
+
+                // Warn if the enum defines any enum cases (i.e. any fields other than the implicit value field)
+                if (typeSymbol.GetMembers().Any(static member => member is IFieldSymbol { IsConst: true }))
+                {
+                    context.ReportDiagnostic(Diagnostic.Create(
+                        DiagnosticDescriptors.ApiContractEnumWithCases,
+                        typeSymbol.Locations.FirstOrDefault(),
+                        typeSymbol));
+                }
+            }, SymbolKind.NamedType);
+        });
+    }
+}

src/Authoring/WinRT.SourceGenerator2/Diagnostics/Analyzers/ValidContractVersionAttributeAnalyzer.cs

@@ -0,0 +1,126 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Collections.Immutable;
+using System.Linq;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.Diagnostics;
+
+namespace WindowsRuntime.SourceGenerator.Diagnostics;
+
+/// <summary>
+/// A diagnostic analyzer that validates applications of <c>[ContractVersion]</c> attributes.
+/// </summary>
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public sealed class ValidContractVersionAttributeAnalyzer : DiagnosticAnalyzer
+{
+    /// <inheritdoc/>
+    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } = [
+        DiagnosticDescriptors.ContractVersionAttributeRequiresApiContractTarget,
+        DiagnosticDescriptors.ContractVersionAttributeNotAllowedOnApiContractTarget,
+        DiagnosticDescriptors.ContractVersionAttributeInvalidContractTypeArgument];
+
+    /// <inheritdoc/>
+    public override void Initialize(AnalysisContext context)
+    {
+        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+        context.EnableConcurrentExecution();
+
+        context.RegisterCompilationStartAction(static context =>
+        {
+            // This analyzer only applies to Windows Runtime component authoring scenarios
+            if (!context.Options.AnalyzerConfigOptionsProvider.GlobalOptions.GetCsWinRTComponent())
+            {
+                return;
+            }
+
+            // Get the '[ContractVersion]' symbol
+            if (context.Compilation.GetTypeByMetadataName("Windows.Foundation.Metadata.ContractVersionAttribute") is not { } contractVersionAttributeType)
+            {
+                return;
+            }
+
+            // Get the '[ApiContract]' symbol
+            if (context.Compilation.GetTypeByMetadataName("Windows.Foundation.Metadata.ApiContractAttribute") is not { } apiContractAttributeType)
+            {
+                return;
+            }
+
+            context.RegisterSymbolAction(context =>
+            {
+                if (context.Symbol is not INamedTypeSymbol typeSymbol)
+                {
+                    return;
+                }
+
+                bool isApiContractType = IsApiContractType(typeSymbol, apiContractAttributeType);
+
+                foreach (AttributeData attribute in typeSymbol.GetAttributes(contractVersionAttributeType))
+                {
+                    // We can have multiple '[ContractVersion]' uses, so we need to iterate and check each of them
+                    if (attribute.AttributeConstructor is not { } constructor)
+                    {
+                        continue;
+                    }
+
+                    ImmutableArray<IParameterSymbol> parameters = constructor.Parameters;
+
+                    // Identify the constructor by its first parameter type:
+                    //   - 'ContractVersionAttribute(uint)'
+                    //   - 'ContractVersionAttribute(string, uint)'
+                    //   - 'ContractVersionAttribute(Type, uint)'
+                    bool isVersionOnlyConstructor = parameters is
+                        [{ Type.SpecialType: SpecialType.System_UInt32 }] or
+                        [{ Type.SpecialType: SpecialType.System_String }, _];
+
+                    bool isContractTypeConstructor = parameters is
+                        [{ Type: INamedTypeSymbol { MetadataName: "Type", ContainingNamespace.Name: "System" } }, _];
+
+                    // The version-only constructors must be applied to API contract types
+                    if (isVersionOnlyConstructor && !isApiContractType)
+                    {
+                        context.ReportDiagnostic(Diagnostic.Create(
+                            DiagnosticDescriptors.ContractVersionAttributeRequiresApiContractTarget,
+                            attribute.GetLocation(context.CancellationToken) ?? typeSymbol.Locations.FirstOrDefault(),
+                            typeSymbol));
+                    }
+                    else if (isContractTypeConstructor)
+                    {
+                        // The contract-type constructor must not be applied to API contract types
+                        if (isApiContractType)
+                        {
+                            context.ReportDiagnostic(Diagnostic.Create(
+                                DiagnosticDescriptors.ContractVersionAttributeNotAllowedOnApiContractTarget,
+                                attribute.GetLocation(context.CancellationToken) ?? typeSymbol.Locations.FirstOrDefault(),
+                                typeSymbol));
+                        }
+
+                        // The contract type argument must be a valid API contract type
+                        if (attribute.ConstructorArguments is [{ Value: INamedTypeSymbol contractTypeArgument }, ..] &&
+                            !IsApiContractType(contractTypeArgument, apiContractAttributeType))
+                        {
+                            context.ReportDiagnostic(Diagnostic.Create(
+                                DiagnosticDescriptors.ContractVersionAttributeInvalidContractTypeArgument,
+                                attribute.GetArgumentLocation(argumentIndex: 0, context.CancellationToken)
+                                    ?? attribute.GetLocation(context.CancellationToken)
+                                    ?? typeSymbol.Locations.FirstOrDefault(),
+                                typeSymbol,
+                                contractTypeArgument));
+                        }
+                    }
+                }
+            }, SymbolKind.NamedType);
+        });
+    }
+
+    /// <summary>
+    /// Checks whether a type is a valid API contract type (an enum type annotated with <c>[ApiContract]</c>).
+    /// </summary>
+    /// <param name="typeSymbol">The type symbol to check.</param>
+    /// <param name="apiContractAttributeType">The <c>[ApiContract]</c> attribute symbol.</param>
+    /// <returns>Whether <paramref name="typeSymbol"/> is a valid API contract type.</returns>
+    private static bool IsApiContractType(INamedTypeSymbol typeSymbol, INamedTypeSymbol apiContractAttributeType)
+    {
+        return typeSymbol is { TypeKind: TypeKind.Enum } && typeSymbol.HasAttributeWithType(apiContractAttributeType);
+    }
+}