[ApiDiff] Implementation of the new ApiDiff that reuses GenAPI features

CODEOWNERS

@@ -85,10 +85,15 @@
 
 # Compatibility tools owned by runtime team
 /src/Compatibility/ @dotnet/area-infrastructure-libraries
+
+# Area-ApiCompat
 /test/Microsoft.DotNet.ApiCompatibility*/ @dotnet/area-infrastructure-libraries
 /test/Microsoft.DotNet.ApiCompat*/ @dotnet/area-infrastructure-libraries
 /test/Microsoft.DotNet.PackageValidation*/ @dotnet/area-infrastructure-libraries
 
+# Area-ApiDiff
+/test/Microsoft.DotNet.ApiDiff.Tests/ @dotnet/area-infrastructure-libraries
+
 # Area-GenAPI
 /src/Compatibility/GenAPI/ @dotnet/area-infrastructure-libraries
 /src/Compatibility/Microsoft.DotNet.ApiSymbolExtensions/ @dotnet/area-infrastructure-libraries

eng/Signing.props

@@ -25,10 +25,19 @@
     <FileSignInfo Include="PackageWithFakeNativeDep.dll" CertificateName="None" />
     <FileSignInfo Include="dotnet-tool-with-output-name.dll" CertificateName="None" />
 
-    <!-- Third party DLLs used by tests -->
+    <!-- Third party DLLs used by tests-->
     <FileSignInfo Include="Castle.Core.dll" CertificateName="None" />
     <FileSignInfo Include="Moq.dll" CertificateName="None" />
 
+    <!-- Third party DLLs used in src projects not participating in source-build -->
+    <FileSignInfo Include="Argon.dll" CertificateName="None" />
+    <FileSignInfo Include="DiffEngine.dll" CertificateName="None" />
+    <FileSignInfo Include="DiffPlex.dll" CertificateName="None" />
+    <FileSignInfo Include="EmptyFiles.dll" CertificateName="None" />
+    <FileSignInfo Include="SimpleInfoName.dll" CertificateName="None" />
+    <FileSignInfo Include="Verify.dll" CertificateName="None" />
+    <FileSignInfo Include="Verify.DiffPlex.dll" CertificateName="None" />
+
     <!-- Binary test asset -->
     <FileSignInfo Include="testwpf.dll" CertificateName="None" />
 

src/Compatibility/ApiDiff/Directory.Build.props

@@ -0,0 +1,9 @@
+<Project>
+
+  <Import Project="..\Directory.Build.props" />
+
+  <PropertyGroup>
+    <SkipMicrosoftCodeAnalysisCSharpPinning>true</SkipMicrosoftCodeAnalysisCSharpPinning>
+  </PropertyGroup>
+
+</Project>

src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff.Tool/GenAPIDiffConfigurationBinder.cs

@@ -0,0 +1,63 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.CommandLine;
+using System.CommandLine.Binding;
+
+namespace Microsoft.DotNet.ApiDiff;
+
+// Binds System.CommandLine options to a DiffConfiguration object.
+internal class GenAPIDiffConfigurationBinder : BinderBase<DiffConfiguration>
+{
+    private readonly Option<string> _optionBeforeAssembliesFolderPath;
+    private readonly Option<string> _optionBeforeAssemblyReferencesFolderPath;
+    private readonly Option<string> _optionAfterAssembliesFolderPath;
+    private readonly Option<string> _optionAfterAssemblyReferencesFolderPath;
+    private readonly Option<string> _optionOutputFolderPath;
+    private readonly Option<string> _optionTableOfContentsTitle;
+    private readonly Option<string[]?> _optionAttributesToExclude;
+    private readonly Option<string[]?> _optionApisToExclude;
+    private readonly Option<bool> _optionAddPartialModifier;
+    private readonly Option<bool> _optionHideImplicitDefaultConstructors;
+    private readonly Option<bool> _optionDebug;
+
+    internal GenAPIDiffConfigurationBinder(Option<string> optionBeforeAssembliesFolderPath,
+                                           Option<string> optionBeforeAssemblyReferencesFolderPath,
+                                           Option<string> optionAfterAssembliesFolderPath,
+                                           Option<string> optionAfterAssemblyReferencesFolderPath,
+                                           Option<string> optionOutputFolderPath,
+                                           Option<string> optionTableOfContentsTitle,
+                                           Option<string[]?> optionAttributesToExclude,
+                                           Option<string[]?> optionApisToExclude,
+                                           Option<bool> optionAddPartialModifier,
+                                           Option<bool> optionHideImplicitDefaultConstructors,
+                                           Option<bool> optionDebug)
+    {
+        _optionBeforeAssembliesFolderPath = optionBeforeAssembliesFolderPath;
+        _optionBeforeAssemblyReferencesFolderPath = optionBeforeAssemblyReferencesFolderPath;
+        _optionAfterAssembliesFolderPath = optionAfterAssembliesFolderPath;
+        _optionAfterAssemblyReferencesFolderPath = optionAfterAssemblyReferencesFolderPath;
+        _optionOutputFolderPath = optionOutputFolderPath;
+        _optionTableOfContentsTitle = optionTableOfContentsTitle;
+        _optionAttributesToExclude = optionAttributesToExclude;
+        _optionApisToExclude = optionApisToExclude;
+        _optionAddPartialModifier = optionAddPartialModifier;
+        _optionHideImplicitDefaultConstructors = optionHideImplicitDefaultConstructors;
+        _optionDebug = optionDebug;
+    }
+
+    protected override DiffConfiguration GetBoundValue(BindingContext bindingContext) =>
+        new DiffConfiguration(
+            BeforeAssembliesFolderPath: bindingContext.ParseResult.GetValueForOption(_optionBeforeAssembliesFolderPath) ?? throw new NullReferenceException("Null before assemblies directory."),
+            BeforeAssemblyReferencesFolderPath: bindingContext.ParseResult.GetValueForOption(_optionBeforeAssemblyReferencesFolderPath),
+            AfterAssembliesFolderPath: bindingContext.ParseResult.GetValueForOption(_optionAfterAssembliesFolderPath) ?? throw new NullReferenceException("Null after assemblies directory."),
+            AfterAssemblyReferencesFolderPath: bindingContext.ParseResult.GetValueForOption(_optionAfterAssemblyReferencesFolderPath),
+            OutputFolderPath: bindingContext.ParseResult.GetValueForOption(_optionOutputFolderPath) ?? throw new NullReferenceException("Null output directory."),
+            TableOfContentsTitle: bindingContext.ParseResult.GetValueForOption(_optionTableOfContentsTitle) ?? throw new NullReferenceException("Null table of contents title."),
+            AttributesToExclude: bindingContext.ParseResult.GetValueForOption(_optionAttributesToExclude),
+            ApisToExclude: bindingContext.ParseResult.GetValueForOption(_optionApisToExclude),
+            AddPartialModifier: bindingContext.ParseResult.GetValueForOption(_optionAddPartialModifier),
+            HideImplicitDefaultConstructors: bindingContext.ParseResult.GetValueForOption(_optionHideImplicitDefaultConstructors),
+            Debug: bindingContext.ParseResult.GetValueForOption(_optionDebug)
+        );
+}

src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff.Tool/Microsoft.DotNet.ApiDiff.Tool.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>$(NetToolMinimum)</TargetFramework>
+    <OutputType>Exe</OutputType>
+    <IsPackable>true</IsPackable>
+    <PackAsTool>true</PackAsTool>
+    <ToolCommandName>apidiff</ToolCommandName>
+    <PackageDescription>Tool to emit markdown diffs between sets of assemblies.</PackageDescription>
+    <DotNetBuildSourceOnly>false</DotNetBuildSourceOnly>
+    <ExcludeFromSourceOnlyBuild>true</ExcludeFromSourceOnlyBuild>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\Microsoft.DotNet.ApiSymbolExtensions\Microsoft.DotNet.ApiSymbolExtensions.csproj" />
+    <ProjectReference Include="..\Microsoft.DotNet.ApiDiff\Microsoft.DotNet.ApiDiff.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="System.CommandLine" VersionOverride="2.0.0-beta4.22272.1" />
+  </ItemGroup>
+
+</Project>

src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff.Tool/Program.cs

@@ -0,0 +1,175 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.CommandLine;
+using System.Diagnostics;
+using Microsoft.DotNet.ApiSymbolExtensions.Logging;
+
+namespace Microsoft.DotNet.ApiDiff.Tool;
+
+/// <summary>
+/// Entrypoint for the genapidiff tool, which generates a markdown diff of two
+/// different versions of the same assembly, using the specified command line options.
+/// </summary>
+public static class Program
+{
+    public static async Task Main(string[] args)
+    {
+        RootCommand rootCommand = new("genapidiff");
+
+        Option<string> optionBeforeAssembliesFolderPath = new(["--before", "-b"])
+        {
+            Description = "The path to the folder containing the old (before) assemblies.",
+            Arity = ArgumentArity.ExactlyOne,
+            IsRequired = true
+        };
+
+        Option<string> optionBeforeRefAssembliesFolderPath = new(["--refbefore", "-rb"])
+        {
+            Description = "The path to the folder containing the old (before) reference assemblies.",
+            Arity = ArgumentArity.ExactlyOne,
+            IsRequired = false
+        };
+
+        Option<string> optionAfterAssembliesFolderPath = new(["--after", "-a"])
+        {
+            Description = "The path to the folder containing the new (after) assemblies.",
+            Arity = ArgumentArity.ExactlyOne,
+            IsRequired = false
+        };
+
+        Option<string> optionAfterRefAssembliesFolderPath = new(["--refafter", "-ra"])
+        {
+            Description = "The path to the folder containing the new (after) reference assemblies.",
+            Arity = ArgumentArity.ExactlyOne,
+            IsRequired = false
+        };
+
+        Option<string> optionOutputFolderPath = new(["--output", "-o"])
+        {
+            Description = "The path to the output folder.",
+            Arity = ArgumentArity.ExactlyOne,
+            IsRequired = true
+        };
+
+        Option<string> optionTableOfContentsTitle = new(["--tableOfContentsTitle", "-tc"])
+        {
+            Description = "The title of the markdown file that is placed in the output folder with a table of contents.",
+            Arity = ArgumentArity.ExactlyOne,
+            IsRequired = true
+        };
+
+        Option<string[]?> optionAttributesToExclude = new(["--attributesToExclude", "-eattrs"], () => null)
+        {
+            Description = "Attributes to exclude from the diff.",
+            Arity = ArgumentArity.ZeroOrMore,
+            IsRequired = false
+        };
+
+        Option<string[]?> optionApisToExclude = new(["--apisToExclude", "-eapis"], () => null)
+        {
+            Description = "APIs to exclude from the diff.",
+            Arity = ArgumentArity.ZeroOrMore,
+            IsRequired = false
+        };
+
+        Option<bool> optionAddPartialModifier = new(["--addPartialModifier", "-apm"], () => false)
+        {
+            Description = "Add the 'partial' modifier to types."
+        };
+
+        Option<bool> optionHideImplicitDefaultConstructors = new(["--hideImplicitDefaultConstructors", "-hidc"], () => false)
+        {
+            Description = "Hide implicit default constructors from types."
+        };
+
+        Option<bool> optionDebug = new(["--attachDebugger", "-d"], () => false)
+        {
+            Description = "Stops the tool at startup, prints the process ID and waits for a debugger to attach."
+        };
+
+        // Custom ordering for the help menu.
+        rootCommand.Add(optionBeforeAssembliesFolderPath);
+        rootCommand.Add(optionBeforeRefAssembliesFolderPath);
+        rootCommand.Add(optionAfterAssembliesFolderPath);
+        rootCommand.Add(optionAfterRefAssembliesFolderPath);
+        rootCommand.Add(optionOutputFolderPath);
+        rootCommand.Add(optionTableOfContentsTitle);
+        rootCommand.Add(optionAttributesToExclude);
+        rootCommand.Add(optionApisToExclude);
+        rootCommand.Add(optionAddPartialModifier);
+        rootCommand.Add(optionHideImplicitDefaultConstructors);
+        rootCommand.Add(optionDebug);
+
+        GenAPIDiffConfigurationBinder c = new(optionBeforeAssembliesFolderPath,
+                                              optionBeforeRefAssembliesFolderPath,
+                                              optionAfterAssembliesFolderPath,
+                                              optionAfterRefAssembliesFolderPath,
+                                              optionOutputFolderPath,
+                                              optionTableOfContentsTitle,
+                                              optionAttributesToExclude,
+                                              optionApisToExclude,
+                                              optionAddPartialModifier,
+                                              optionHideImplicitDefaultConstructors,
+                                              optionDebug);
+
+        rootCommand.SetHandler(HandleCommand, c);
+        await rootCommand.InvokeAsync(args);
+    }
+
+    private static void HandleCommand(DiffConfiguration diffConfig)
+    {
+        var log = new ConsoleLog(MessageImportance.Normal);
+
+        string attributesToExclude = diffConfig.AttributesToExclude != null ? string.Join(", ", diffConfig.AttributesToExclude) : string.Empty;
+        string apisToExclude = diffConfig.ApisToExclude != null ? string.Join(", ", diffConfig.ApisToExclude) : string.Empty;
+
+        // Custom ordering to match help menu.
+        log.LogMessage("Selected options:");
+        log.LogMessage($" - 'Before' source assemblies:         {diffConfig.BeforeAssembliesFolderPath}");
+        log.LogMessage($" - 'After'  source assemblies:         {diffConfig.AfterAssembliesFolderPath}");
+        log.LogMessage($" - 'Before' reference assemblies:      {diffConfig.BeforeAssemblyReferencesFolderPath}");
+        log.LogMessage($" - 'After'  reference assemblies:      {diffConfig.AfterAssemblyReferencesFolderPath}");
+        log.LogMessage($" - Output:                             {diffConfig.OutputFolderPath}");
+        log.LogMessage($" - Attributes to exclude:              {attributesToExclude}");
+        log.LogMessage($" - APIs to exclude:                    {apisToExclude}");
+        log.LogMessage($" - Table of contents title:            {diffConfig.TableOfContentsTitle}");
+        log.LogMessage($" - Add partial modifier to types:      {diffConfig.AddPartialModifier}");
+        log.LogMessage($" - Hide implicit default constructors: {diffConfig.HideImplicitDefaultConstructors}");
+        log.LogMessage($" - Debug:                              {diffConfig.Debug}");
+        log.LogMessage("");
+
+        if (diffConfig.Debug)
+        {
+            WaitForDebugger();
+        }
+
+        IDiffGenerator diffGenerator = DiffGeneratorFactory.Create(log,
+                                                                   diffConfig.BeforeAssembliesFolderPath,
+                                                                   diffConfig.BeforeAssemblyReferencesFolderPath,
+                                                                   diffConfig.AfterAssembliesFolderPath,
+                                                                   diffConfig.AfterAssemblyReferencesFolderPath,
+                                                                   diffConfig.OutputFolderPath,
+                                                                   diffConfig.TableOfContentsTitle,
+                                                                   diffConfig.AttributesToExclude,
+                                                                   diffConfig.ApisToExclude,
+                                                                   diffConfig.AddPartialModifier,
+                                                                   diffConfig.HideImplicitDefaultConstructors,
+                                                                   writeToDisk: true,
+                                                                   diagnosticOptions: null // TODO: If needed, add CLI option to pass specific diagnostic options
+                                                                   );
+
+        diffGenerator.Run();
+    }
+
+    private static void WaitForDebugger()
+    {
+        while (!Debugger.IsAttached)
+        {
+            Console.WriteLine($"Attach to process {Environment.ProcessId}...");
+            Thread.Sleep(1000);
+        }
+        Console.WriteLine("Debugger attached!");
+        Debugger.Break();
+    }
+}

src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff/DiffConfiguration.cs

@@ -0,0 +1,21 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.DotNet.ApiDiff;
+
+/// <summary>
+/// Defines the necessary configuration options for API diff.
+/// </summary>
+public record DiffConfiguration(
+    string AfterAssembliesFolderPath,
+    string? AfterAssemblyReferencesFolderPath,
+    string BeforeAssembliesFolderPath,
+    string? BeforeAssemblyReferencesFolderPath,
+    string OutputFolderPath,
+    string TableOfContentsTitle,
+    string[]? AttributesToExclude,
+    string[]? ApisToExclude,
+    bool AddPartialModifier,
+    bool HideImplicitDefaultConstructors,
+    bool Debug
+);