From fa1b2910f5f189acc73ccbee62c77adf0b80596c Mon Sep 17 00:00:00 2001 From: Paulo Morgado <470455+paulomorgado@users.noreply.github.com> Date: Wed, 26 Jun 2024 19:17:14 +0100 Subject: [PATCH] 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. --- .../Search/DotNetPackageSearcherFixture.cs | 52 ++++ .../DotNetPackageSearchSettingsTests.cs | 51 ++++ .../Search/DotNetPackageSearcherTests.cs | 263 ++++++++++++++++++ src/Cake.Common/Tools/DotNet/DotNetAliases.cs | 95 +++++++ .../Package/Search/DotNetPackageSearchItem.cs | 22 ++ .../Search/DotNetPackageSearchSettings.cs | 46 +++ .../Package/Search/DotNetPackageSearcher.cs | 159 +++++++++++ src/Cake.lutconfig | 6 + 8 files changed, 694 insertions(+) create mode 100644 src/Cake.Common.Tests/Fixtures/Tools/DotNet/Package/Search/DotNetPackageSearcherFixture.cs create mode 100644 src/Cake.Common.Tests/Unit/Tools/DotNet/Package/Search/DotNetPackageSearchSettingsTests.cs create mode 100644 src/Cake.Common.Tests/Unit/Tools/DotNet/Package/Search/DotNetPackageSearcherTests.cs create mode 100644 src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearchItem.cs create mode 100644 src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearchSettings.cs create mode 100644 src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearcher.cs create mode 100644 src/Cake.lutconfig diff --git a/src/Cake.Common.Tests/Fixtures/Tools/DotNet/Package/Search/DotNetPackageSearcherFixture.cs b/src/Cake.Common.Tests/Fixtures/Tools/DotNet/Package/Search/DotNetPackageSearcherFixture.cs new file mode 100644 index 0000000000..e8f59cdc09 --- /dev/null +++ b/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 + { + public string SearchTerm { get; set; } + + public IAsyncEnumerable 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\"", + " }", + " ]", + " }", + " ]", + "}", + }); + } + } +} diff --git a/src/Cake.Common.Tests/Unit/Tools/DotNet/Package/Search/DotNetPackageSearchSettingsTests.cs b/src/Cake.Common.Tests/Unit/Tools/DotNet/Package/Search/DotNetPackageSearchSettingsTests.cs new file mode 100644 index 0000000000..62ddc07c44 --- /dev/null +++ b/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); + } + } + } +} diff --git a/src/Cake.Common.Tests/Unit/Tools/DotNet/Package/Search/DotNetPackageSearcherTests.cs b/src/Cake.Common.Tests/Unit/Tools/DotNet/Package/Search/DotNetPackageSearcherTests.cs new file mode 100644 index 0000000000..762b3b3380 --- /dev/null +++ b/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"); + }); + } + } + } +} diff --git a/src/Cake.Common/Tools/DotNet/DotNetAliases.cs b/src/Cake.Common/Tools/DotNet/DotNetAliases.cs index 520f7c0b08..695657c06d 100644 --- a/src/Cake.Common/Tools/DotNet/DotNetAliases.cs +++ b/src/Cake.Common/Tools/DotNet/DotNetAliases.cs @@ -17,6 +17,7 @@ using Cake.Common.Tools.DotNet.Pack; using Cake.Common.Tools.DotNet.Package.Add; using Cake.Common.Tools.DotNet.Package.Remove; +using Cake.Common.Tools.DotNet.Package.Search; using Cake.Common.Tools.DotNet.Publish; using Cake.Common.Tools.DotNet.Restore; using Cake.Common.Tools.DotNet.Run; @@ -2429,5 +2430,99 @@ public static void DotNetRemovePackage(this ICakeContext context, string package var adder = new DotNetPackageRemover(context.FileSystem, context.Environment, context.ProcessRunner, context.Tools); adder.Remove(packageName, project); } + + /// + /// List packages on available from source using specified settings. + /// + /// The context. + /// The search term. + /// The settings. + /// List of packages with their version. + /// + /// + /// var packageList = DotNetPackageSearch("Cake", new DotNetPackageSearchSettings { + /// AllVersions = false, + /// Prerelease = false + /// }); + /// foreach(var package in packageList) + /// { + /// Information("Found package {0}, version {1}", package.Name, package.Version); + /// } + /// + /// + [CakeMethodAlias] + [CakeAliasCategory("Package")] + [CakeNamespaceImport("Cake.Common.Tools.DotNet.Package.Search")] + public static IEnumerable DotNetSearchPackage(this ICakeContext context, string searchTerm, DotNetPackageSearchSettings settings) + { + if (context == null) + { + throw new ArgumentNullException(nameof(context)); + } + var runner = new DotNetPackageSearcher(context.FileSystem, context.Environment, context.ProcessRunner, context.Tools); + return runner.Search(searchTerm, settings); + } + + /// + /// List packages on available from source using specified settings. + /// + /// The context. + /// The package Id. + /// List of packages with their version. + /// + /// + /// var packageList = DotNetPackageSearch("Cake", new DotNetPackageSearchSettings { + /// AllVersions = false, + /// Prerelease = false + /// }); + /// foreach(var package in packageList) + /// { + /// Information("Found package {0}, version {1}", package.Name, package.Version); + /// } + /// + /// + [CakeMethodAlias] + [CakeAliasCategory("Package")] + [CakeNamespaceImport("Cake.Common.Tools.DotNet.Package.Search")] + public static IEnumerable DotNetSearchPackage(this ICakeContext context, string searchTerm) + { + if (context == null) + { + throw new ArgumentNullException(nameof(context)); + } + var runner = new DotNetPackageSearcher(context.FileSystem, context.Environment, context.ProcessRunner, context.Tools); + return runner.Search(searchTerm, new DotNetPackageSearchSettings()); + } + + /// + /// List packages on available from source using specified settings. + /// + /// The context. + /// The settings. + /// List of packages with their version. + /// + /// + /// var packageList = DotNetPackageSearch("Cake", new DotNetPackageSearchSettings { + /// AllVersions = false, + /// Prerelease = false + /// }); + /// foreach(var package in packageList) + /// { + /// Information("Found package {0}, version {1}", package.Name, package.Version); + /// } + /// + /// + [CakeMethodAlias] + [CakeAliasCategory("Package")] + [CakeNamespaceImport("Cake.Common.Tools.DotNet.Package.Search")] + public static IEnumerable DotNetSearchPackage(this ICakeContext context, DotNetPackageSearchSettings settings) + { + if (context == null) + { + throw new ArgumentNullException(nameof(context)); + } + var runner = new DotNetPackageSearcher(context.FileSystem, context.Environment, context.ProcessRunner, context.Tools); + return runner.Search(null, settings); + } } } diff --git a/src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearchItem.cs b/src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearchItem.cs new file mode 100644 index 0000000000..197fe7460c --- /dev/null +++ b/src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearchItem.cs @@ -0,0 +1,22 @@ +// 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. + +namespace Cake.Common.Tools.DotNet.Package.Search +{ + /// + /// An item as returned by . + /// + public class DotNetPackageSearchItem + { + /// + /// Gets or sets the name of the NuGetListItem. + /// + public string Name { get; set; } + + /// + /// Gets or sets the version of the NuGetListItem as string. + /// + public string Version { get; set; } + } +} diff --git a/src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearchSettings.cs b/src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearchSettings.cs new file mode 100644 index 0000000000..9599b9cb8e --- /dev/null +++ b/src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearchSettings.cs @@ -0,0 +1,46 @@ +// 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.Core.IO; +using System.Collections.Generic; + +namespace Cake.Common.Tools.DotNet.Package.Search +{ + /// + /// Represents the settings for searching .NET packages. + /// + public class DotNetPackageSearchSettings : DotNetSettings + { + /// + /// Gets or sets a value indicating whether to allow prerelease packages to be shown. + /// + public bool Prerelease { get; set; } + + /// + /// Gets or sets a value indicating whether an exact match is required. Causes and options to be ignored. + /// + public bool ExactMatch { get; set; } + + /// + /// Gets or sets the NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. + /// + /// + public FilePath ConfigFile { get; set; } + + /// + /// Gets or sets a list of package sources to search. + /// + public ICollection Source { get; set; } = new List(); + + /// + /// Gets or sets the number of results to return. + /// + public int? Take { get; set; } + + /// + /// Gets or sets the number of results to skip, to allow pagination. + /// + public int? Skip { get; set; } + } +} diff --git a/src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearcher.cs b/src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearcher.cs new file mode 100644 index 0000000000..311e78872a --- /dev/null +++ b/src/Cake.Common/Tools/DotNet/Package/Search/DotNetPackageSearcher.cs @@ -0,0 +1,159 @@ +// 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; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using Cake.Core; +using Cake.Core.IO; +using Cake.Core.Tooling; + +namespace Cake.Common.Tools.DotNet.Package.Search +{ + /// + /// .NET package searcher. + /// + public sealed class DotNetPackageSearcher : DotNetTool + { + private static readonly JsonSerializerOptions _jsonSerializerOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web); + + private readonly ICakeEnvironment _environment; + + /// + /// Initializes a new instance of the class. + /// + /// The file system. + /// The environment. + /// The process runner. + /// The tool locator. + public DotNetPackageSearcher( + IFileSystem fileSystem, + ICakeEnvironment environment, + IProcessRunner processRunner, + IToolLocator tools) : base(fileSystem, environment, processRunner, tools) + { + _environment = environment; + } + + /// + /// Searches for packages. + /// + /// The search term. + /// The search settings. + /// A collection of . + public IEnumerable Search(string searchTerm, DotNetPackageSearchSettings settings) + { + if (settings == null) + { + throw new ArgumentNullException(nameof(settings)); + } + + var processSettings = new ProcessSettings + { + RedirectStandardOutput = true + }; + + IEnumerable result = null; + RunCommand(settings, GetArguments(searchTerm, settings), processSettings, process => result = process.GetStandardOutput()); + + return Parse(result).ToList(); + } + + private ProcessArgumentBuilder GetArguments(string searchTerm, DotNetPackageSearchSettings settings) + { + var builder = new ProcessArgumentBuilder(); + + builder.Append("package search"); + + if (!string.IsNullOrEmpty(searchTerm)) + { + builder.AppendQuoted(searchTerm); + } + + if (settings.Prerelease) + { + builder.Append("--prerelease"); + } + + if (settings.ExactMatch) + { + builder.Append("--exact-match"); + } + + if (settings.Source != null && settings.Source.Count > 0) + { + foreach (var source in settings.Source) + { + builder.Append("--source"); + builder.AppendQuoted(source); + } + } + + if (settings.ConfigFile != null) + { + builder.Append("--configfile"); + builder.AppendQuoted(settings.ConfigFile.MakeAbsolute(_environment).FullPath); + } + + if (settings.Take is { } take) + { + builder.Append("--take"); + builder.Append(take.ToString()); + } + + if (settings.Skip is { } skip) + { + builder.Append("--skip"); + builder.Append(skip.ToString()); + } + + builder.Append("--verbosity normal"); + + builder.Append("--format json"); + + return builder; + } + + private static IEnumerable Parse(IEnumerable json) + { + if (json is null) + { + yield break; + } + + var jsonText = string.Join(Environment.NewLine, json); + + var result = JsonSerializer.Deserialize(jsonText, _jsonSerializerOptions); + + if (result is not null) + { + foreach (var searchResult in result.SearchResult) + { + foreach (var package in searchResult.Packages) + { + yield return new DotNetPackageSearchItem { Name = package.Id, Version = package.LatestVersion }; + } + } + } + } + + private sealed class Result + { + public List SearchResult { get; set; } + } + + private sealed class SearchResult + { + public List Packages { get; set; } + } + + private sealed class Package + { + public string Id { get; set; } + + public string LatestVersion { get; set; } + } + } +} diff --git a/src/Cake.lutconfig b/src/Cake.lutconfig new file mode 100644 index 0000000000..ff7fdf3f6c --- /dev/null +++ b/src/Cake.lutconfig @@ -0,0 +1,6 @@ + + ..\ + true + true + 180000 + \ No newline at end of file