Add .NET package search to Cake scripts

This commit introduces a significant enhancement to the Cake build automation system by adding support for .NET package search directly within Cake build scripts. The implementation includes the introduction of a new method `DotNetSearchPackage` along with several new classes (`DotNetPackageSearcher`, `DotNetPackageSearchItem`, `DotNetPackageSearchSettings`) designed to facilitate the search for .NET packages using various settings and parameters.

Additionally, this update includes the creation of unit tests and fixtures (`DotNetPackageSearcherFixture`, `DotNetPackageSearcherTests`, `DotNetPackageSearchSettingsTests`) to ensure the reliability and correctness of the package search functionality. A new configuration file (`Cake.lutconfig`) has been added to support live unit testing within the project, optimizing the development workflow.

The changes also encompass updates to the namespace and using directives, specifically adding `using Cake.Common.Tools.DotNet.Package.Search;` in `DotNetAliases.cs` and introducing a new namespace `Cake.Common.Tools.DotNet.Package.Search` for better organization of the new functionality.

Comprehensive XML documentation comments have been included to provide clear examples and guidance on how to utilize the new package search feature within Cake build scripts, aiming to enhance the developer experience by making it easier to find and reference .NET packages during the build process.

src/Cake.Common.Tests/Fixtures/Tools/DotNet/Package/Search/DotNetPackageSearcherFixture.cs

@@ -0,0 +1,52 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Collections.Generic;
+using Cake.Common.Tools.DotNet.Package.Search;
+
+namespace Cake.Common.Tests.Fixtures.Tools.DotNet.Package.Search
+{
+    internal class DotNetPackageSearcherFixture : DotNetFixture<DotNetPackageSearchSettings>
+    {
+        public string SearchTerm { get; set; }
+
+        public IAsyncEnumerable<DotNetPackageSearchItem> Result { get; internal set; }
+
+        protected override void RunTool()
+        {
+            var tool = new DotNetPackageSearcher(FileSystem, Environment, ProcessRunner, Tools);
+            tool.Search(SearchTerm, Settings);
+        }
+
+        internal void GivenNormalPackageResult()
+        {
+            ProcessRunner.Process.SetStandardOutput(new string[]
+            {
+                "{",
+                "  \"version\": 2,",
+                "  \"problems\": [],",
+                "  \"searchResult\": [",
+                "    {",
+                "      \"sourceName\": \"nuget.org\",",
+                "      \"packages\": [",
+                "        {",
+                "          \"id\": \"Cake\",",
+                "          \"latestVersion\": \"0.22.2\"",
+                "        },",
+                "        {",
+                "          \"id\": \"Cake.Core\",",
+                "          \"latestVersion\": \"0.22.2\"",
+                "        },",
+                "        {",
+                "          \"id\": \"Cake.CoreCLR\",",
+                "          \"latestVersion\": \"0.22.2\"",
+                "        }",
+                "      ]",
+                "    }",
+                "  ]",
+                "}",
+            });
+        }
+    }
+}

src/Cake.Common.Tests/Unit/Tools/DotNet/Package/Search/DotNetPackageSearchSettingsTests.cs

@@ -0,0 +1,51 @@
+using Cake.Common.Tools.DotNet.Package.Search;
+using Xunit;
+
+namespace Cake.Common.Tests.Unit.Tools.DotNet.Package.Search
+{
+    public sealed class DotNetPackageSearchSettingsTests
+    {
+        public sealed class TheConstructor
+        {
+            [Fact]
+            public void Should_Set_ExactMatch_To_False_By_Default()
+            {
+                // Given, When
+                var settings = new DotNetPackageSearchSettings();
+
+                // Then
+                Assert.False(settings.ExactMatch);
+            }
+
+            [Fact]
+            public void Should_Set_Take_To_Null_By_Default()
+            {
+                // Given, When
+                var settings = new DotNetPackageSearchSettings();
+
+                // Then
+                Assert.Null(settings.Take);
+            }
+
+            [Fact]
+            public void Should_Set_Skip_To_Null_By_Default()
+            {
+                // Given, When
+                var settings = new DotNetPackageSearchSettings();
+
+                // Then
+                Assert.Null(settings.Skip);
+            }
+
+            [Fact]
+            public void Should_Set_Prerelease_To_False_By_Default()
+            {
+                // Given, When
+                var settings = new DotNetPackageSearchSettings();
+
+                // Then
+                Assert.False(settings.Prerelease);
+            }
+        }
+    }
+}

src/Cake.Common.Tests/Unit/Tools/DotNet/Package/Search/DotNetPackageSearcherTests.cs

@@ -0,0 +1,263 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Cake.Common.Tests.Fixtures.Tools.DotNet.Package.Search;
+using Cake.Common.Tools.DotNet;
+using Cake.Testing;
+using Xunit;
+
+namespace Cake.Common.Tests.Unit.Tools.DotNet.Package.Search
+{
+    public sealed class DotNetPackageSearcherTests
+    {
+        public sealed class TheSearchMethod
+        {
+            [Fact]
+            public void Should_Throw_If_Target_Package_Id_Is_Null()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture
+                {
+                    SearchTerm = null
+                };
+
+                // When
+                var result = Record.Exception(() => fixture.Run());
+
+                // Then
+                AssertEx.IsArgumentNullException(result, "searchTerm");
+            }
+
+            [Fact]
+            public void Should_Throw_If_Settings_Are_Null()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.Settings = null;
+
+                // When
+                var result = Record.Exception(() => fixture.Run());
+
+                // Then
+                AssertEx.IsArgumentNullException(result, "settings");
+            }
+
+            [Fact]
+            public void Should_Throw_If_NuGet_Executable_Was_Not_Found()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.GivenDefaultToolDoNotExist();
+
+                // When
+                var result = Record.Exception(() => fixture.Run());
+
+                // Then
+                AssertEx.IsCakeException(result, "NuGet: Could not locate executable.");
+            }
+
+            [Theory]
+            [InlineData("/bin/nuget/nuget.exe", "/bin/nuget/nuget.exe")]
+            [InlineData("./tools/nuget/nuget.exe", "/Working/tools/nuget/nuget.exe")]
+            public void Should_Use_NuGet_Executable_From_Tool_Path_If_Provided(string toolPath, string expected)
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.Settings.ToolPath = toolPath;
+                fixture.GivenSettingsToolPathExist();
+
+                // When
+                var result = fixture.Run();
+
+                // Then
+                Assert.Equal(expected, result.Path.FullPath);
+            }
+
+            [Fact]
+            public void Should_Throw_If_Process_Was_Not_Started()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.GivenProcessCannotStart();
+
+                // When
+                var result = Record.Exception(() => fixture.Run());
+
+                // Then
+                AssertEx.IsCakeException(result, "NuGet: Process was not started.");
+            }
+
+            [Fact]
+            public void Should_Throw_If_Process_Has_A_Non_Zero_Exit_Code()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.GivenProcessExitsWithCode(1);
+
+                // When
+                var result = Record.Exception(() => fixture.Run());
+
+                // Then
+                AssertEx.IsCakeException(result, "NuGet: Process returned an error (exit code 1).");
+            }
+
+            [Fact]
+            public void Should_Find_NuGet_Executable_If_Tool_Path_Not_Provided()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+
+                // When
+                var result = fixture.Run();
+
+                // Then
+                Assert.Equal("/Working/tools/NuGet.exe", result.Path.FullPath);
+            }
+
+            [Fact]
+            public void Should_Add_Mandatory_Arguments()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.SearchTerm = "Cake";
+                fixture.GivenNormalPackageResult();
+
+                // When
+                var result = fixture.Run();
+
+                // Then
+                Assert.Equal("package search \"Cake\" --verbosity normal--format json", result.Args);
+            }
+
+            [Fact]
+            public void Should_Add_ExactMatch_To_Arguments_If_True()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.SearchTerm = "Cake";
+                fixture.Settings.ExactMatch = true;
+                fixture.GivenNormalPackageResult();
+
+                // When
+                var result = fixture.Run();
+
+                // Then
+                Assert.Equal("package search \"Cake\" --exact-match ---verbosity normal--format json", result.Args);
+            }
+
+            [Fact]
+            public void Should_Add_Prerelease_To_Arguments_If_True()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.SearchTerm = "Cake";
+                fixture.Settings.Prerelease = true;
+                fixture.GivenNormalPackageResult();
+
+                // When
+                var result = fixture.Run();
+
+                // Then
+                Assert.Equal("package search \"Cake\" -Prerelease --verbosity normal--format json", result.Args);
+            }
+
+            [Fact]
+            public void Should_Add_Take_To_Arguments_If_True()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.SearchTerm = "Cake";
+                fixture.Settings.Take = 10;
+                fixture.GivenNormalPackageResult();
+
+                // When
+                var result = fixture.Run();
+
+                // Then
+                Assert.Equal("package search \"Cake\" --take 10 --verbosity normal--format json", result.Args);
+            }
+
+            [Fact]
+            public void Should_Add_Skip_To_Arguments_If_True()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.SearchTerm = "Cake";
+                fixture.Settings.Skip = 10;
+                fixture.GivenNormalPackageResult();
+
+                // When
+                var result = fixture.Run();
+
+                // Then
+                Assert.Equal("package search \"Cake\" --skip 10 --verbosity normal--format json", result.Args);
+            }
+
+            [Fact]
+            public void Should_Add_Sources_To_Arguments_If_Set()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.SearchTerm = "Cake";
+                fixture.Settings.Source = new[] { "A;B;C" };
+                fixture.GivenNormalPackageResult();
+
+                // When
+                var result = fixture.Run();
+
+                // Then
+                Assert.Equal("package search \"Cake\" --source \"A\" --source \"B\" --source \"C\" --verbosity normal--format json", result.Args);
+            }
+
+            [Fact]
+            public void Should_Add_ConfigFile_To_Arguments_If_Set()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture();
+                fixture.SearchTerm = "Cake";
+                fixture.Settings.ConfigFile = "./nuget.config";
+                fixture.GivenNormalPackageResult();
+
+                // When
+                var result = fixture.Run();
+
+                // Then
+                Assert.Equal("package search \"Cake\" --configfile \"/Working/nuget.config\" " +
+                             "--verbosity normal--format json", result.Args);
+            }
+
+            [Fact]
+            public void Should_Return_Correct_List_Of_NuGetListItems()
+            {
+                // Given
+                var fixture = new DotNetPackageSearcherFixture
+                {
+                    SearchTerm = "Cake"
+                };
+                fixture.GivenNormalPackageResult();
+
+                // When
+                var result = fixture.Run();
+
+                // Then
+                Assert.Collection(fixture.Result,
+                    item =>
+                    {
+                        Assert.Equal(item.Name, "Cake");
+                        Assert.Equal(item.Version, "0.22.2");
+                    },
+                    item =>
+                    {
+                        Assert.Equal(item.Name, "Cake.Core");
+                        Assert.Equal(item.Version, "0.22.2");
+                    },
+                    item =>
+                    {
+                        Assert.Equal(item.Name, "Cake.CoreCLR");
+                        Assert.Equal(item.Version, "0.22.2");
+                    });
+            }
+        }
+    }
+}