diff --git a/AGENTS.md b/AGENTS.md index 5cbfdee..80e713b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # assembly-differ A .NET tool that diffs the public API of two sets of assemblies and suggests the version change it needs (none, -patch, minor, major). A command per source (`release`, `files`, `nuget`, `github`) picks the two sides; the result is +patch, minor, major). A command per source (`projects`, the default, `release`, `files`, `nuget`) picks the two sides; the result is written as `markdown`, `xml`, `asciidoc`, `github-comment` or `json`. It is also published as a distroless container (`ghcr.io/nullean/assembly-differ`) and a GitHub Action (`action.yml`) that runs it. @@ -81,7 +81,7 @@ one release label. is reported as more visible, and nested types are named `.Name`. Changing a report is a change to the CLI contract. - The CLI surface is the contract `action.yml`, the container and other repositories' builds rely on: the commands - (`release`, `files`, `nuget`, `github`) and their options, and the hidden `diff` with its provider specs and flags. + (`projects`, the default, `release`, `files`, `nuget`, `pull-request`) and their options, and the hidden `diff` with its provider specs and flags. Removing or renaming any of it is a breaking change. `ApiCommands.cs` holds the commands, `DiffRunner.cs` the comparison they share with `diff`. - The build diffs this tool against its own previous release (`generateapichanges`), so a broken diff fails its own CI. diff --git a/README.md b/README.md index c636e19..b86e82b 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,18 @@ runtime installed. ## Quick start -Compare the package you just packed with its last release on nuget.org, and fail the build on a breaking change: +In a repository, build it, then run the tool without a command. It compares every library project with the latest +release of its package: + +```sh +dotnet build -c Release && assembly-differ +``` + +It reads the one solution in the directory, or else the project files in it, and skips test projects and projects with +`IsPackable` set to `false` (`--include-tests` and `--include-unpackable` compare them, and `--project` picks +projects). It does not build: a project without Release output is skipped with a warning. + +Compare the package you just packed with its last release, and fail the build on a breaking change: ```sh assembly-differ release build/output/MyLib.1.3.0.nupkg --fail-on major @@ -77,7 +88,7 @@ earlier release is a first release: there is nothing to compare, so the command | `release ` | a new build, as a `.nupkg`, a `.dll` or a directory, with the release before it; pass `--package` and `--version` unless `` is a `.nupkg` | | `files ` | two local builds, each a `.dll`, a directory of dlls or a `.nupkg` | | `nuget ` | two published versions, from the NuGet sources your NuGet.config lists | -| `github --build --artifacts ` | a new build with an older commit, cloned and built with the command you give | +| `projects` | every library project in the directory against its latest release; what runs without a command | Every command takes the same options: @@ -89,6 +100,13 @@ Every command takes the same options: | `--fail-on` | exit with `4` when the suggested change is at least `patch`, `minor` or `major`; `none` (the default) never fails | | `--framework` | the target framework to compare, such as `net8.0` (`files`, `nuget` and `release`); defaults to the newest the packages share | +To compare with an older commit, check it out and build it next to your working copy, then compare the two builds: + +```sh +git worktree add ../old v1.2.0 && dotnet build ../old -c Release +assembly-differ files ../old/src/MyLib/bin/Release/net8.0 src/MyLib/bin/Release/net8.0 +``` + A single assembly on each side is compared whatever its file name. With more, assemblies pair by file name, and one only a side has is printed; it counts as removed or added API when `--target` names it. @@ -132,7 +150,8 @@ Without write access, as on a pull request from a fork, it writes the job summar Before it had a command per source, the tool took two provider specs, and `diff` still does, unchanged, for the builds that call it: `assembly-differ diff "previous-nuget|MyLib|1.3.0|net8.0" "directory|bin" -t MyLib -p major`. A spec is `assembly|`, `directory|`, `nuget|||[tfm]`, `previous-nuget|||[tfm]` or -`github||||`. Its options are `-t`, `-o`, `-f` (default +`github||||`; `github` is deprecated in favour of the `git +worktree` recipe above. Its options are `-t`, `-o`, `-f` (default `xml`), `-p`/`--prevent-change` in place of `--fail-on`, and `-a`/`--allow-empty-previous-nuget`, which succeeds when `previous-nuget` finds no earlier release. diff --git a/src/assembly-differ/ApiCommands.cs b/src/assembly-differ/ApiCommands.cs index 5fc7d47..930b7e5 100644 --- a/src/assembly-differ/ApiCommands.cs +++ b/src/assembly-differ/ApiCommands.cs @@ -5,7 +5,6 @@ using System.Linq; using Differ.Engine; using Differ.Providers; -using Differ.Providers.GitHub; using Differ.Providers.NuGet; using Differ.Providers.PreviousNuGet; using NuGet.Frameworks; @@ -150,32 +149,6 @@ public int Release( return 0; } - /// Compares a new build with an older commit of a GitHub repository, built with the command you give. - /// The repository as owner/name. - /// The commit, branch or tag to build as the old version. - /// The new build: a .dll or a directory. - /// The command that builds the old commit, run in its checkout. - /// Where the build leaves the assemblies, relative to the checkout. - /// How to report the comparison. - /// assembly-differ github nullean/proc 0.13.0 src/Proc/bin/Release/netstandard2.0 --build "dotnet build -c Release" --artifacts src/Proc/bin/Release/netstandard2.0 - [CommandName("github")] - public int GitHub( - [Argument] string repository, - [Argument] string commit, - [Argument] string path, - string build, - string artifacts, - [AsParameters] ReportOptions? report = null - ) => - Run( - () => - (new DiffSide( - new GitHubAssemblyProviderFactory(new Git(Environment.GetEnvironmentVariable("GIT"))).Create([repository, commit, build, artifacts]), - "github" - ), Local(path, null)), - report - ); - private static int Run(Func<(DiffSide Old, DiffSide New)> sides, ReportOptions? report) => Run(() => (((DiffSide Old, DiffSide New)?)sides()), report, () => null)!.Value; diff --git a/src/assembly-differ/DiffCommand.cs b/src/assembly-differ/DiffCommand.cs index 1b9b39a..c63855d 100644 --- a/src/assembly-differ/DiffCommand.cs +++ b/src/assembly-differ/DiffCommand.cs @@ -37,7 +37,6 @@ internal sealed class DiffCommands /// /// -a, --allow-empty-previous-nuget, Don't fail when no previous nuget package could be found to diff against. /// - [DefaultCommand] [CommandName("diff")] [Hidden] public int Diff( @@ -68,6 +67,12 @@ public int Diff( if (!string.IsNullOrEmpty(part)) targets.Add(part); + if (first.StartsWith("github|", StringComparison.Ordinal) || second.StartsWith("github|", StringComparison.Ordinal)) + Console.Error.WriteLine( + "[diff] warning: the github provider is deprecated. Check out and build the old version yourself, for example with " + + "git worktree add ../old , then compare the two builds with: assembly-differ files " + ); + try { var firstProvider = providers.GetProvider(first); diff --git a/src/assembly-differ/Program.cs b/src/assembly-differ/Program.cs index e8d350f..5049cbc 100644 --- a/src/assembly-differ/Program.cs +++ b/src/assembly-differ/Program.cs @@ -1,9 +1,15 @@ using Differ; using Nullean.Argh; +// Before it had commands, the tool took two provider specs at the root, such as "nuget|Proc|0.13.0": route those to +// diff, which still takes them, so the builds that call it that way keep working. +if (args.Length > 0 && args[0].Contains('|')) + args = ["diff", .. args]; + var app = new ArghApp(); app.Map(); app.Map(); -app.MapAndRootAlias(); +app.Map(); +app.MapAndRootAlias(); return await app.RunAsync(args); diff --git a/src/assembly-differ/Projects/Dotnet.cs b/src/assembly-differ/Projects/Dotnet.cs new file mode 100644 index 0000000..63957dc --- /dev/null +++ b/src/assembly-differ/Projects/Dotnet.cs @@ -0,0 +1,84 @@ +using System; +using System.Collections.Generic; +using System.ComponentModel; +using System.Diagnostics; +using System.Text; +using System.Text.Json; + +namespace Differ.Projects; + +/// Runs the .NET SDK: dotnet sln list, dotnet msbuild -getProperty and dotnet build. +internal static class Dotnet +{ + public sealed class SdkException(string message) : Exception(message); + + public static (int ExitCode, string Output) Run(params string[] args) + { + var start = new ProcessStartInfo("dotnet") + { + RedirectStandardOutput = true, + RedirectStandardError = true, + UseShellExecute = false, + StandardOutputEncoding = Encoding.UTF8, + StandardErrorEncoding = Encoding.UTF8, + }; + foreach (var arg in args) + start.ArgumentList.Add(arg); + start.Environment["DOTNET_NOLOGO"] = "1"; + start.Environment["DOTNET_CLI_TELEMETRY_OPTOUT"] = "1"; + try + { + using var process = Process.Start(start)!; + var error = process.StandardError.ReadToEndAsync(); + var output = process.StandardOutput.ReadToEnd(); + process.WaitForExit(); + return (process.ExitCode, output + error.Result); + } + catch (Win32Exception) + { + throw new SdkException("comparing projects needs the .NET SDK on the PATH; dotnet was not found"); + } + } + + /// The projects a solution lists, as paths relative to the solution's directory. + public static IReadOnlyList SolutionProjects(string solution) + { + var (exitCode, output) = Run("sln", solution, "list"); + if (exitCode != 0) + throw new SdkException($"dotnet sln {solution} list failed:{Environment.NewLine}{output}"); + var projects = new List(); + foreach (var line in output.Split('\n', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries)) + if (line.EndsWith("proj", StringComparison.OrdinalIgnoreCase)) + projects.Add(line); + return projects; + } + + /// MSBuild properties of a project, evaluated with the global properties given. + public static Dictionary Properties(string project, IEnumerable names, params string[] globalProperties) + { + var args = new List { "msbuild", project, "-nologo" }; + foreach (var name in names) + args.Add($"-getProperty:{name}"); + foreach (var property in globalProperties) + args.Add($"-p:{property}"); + var (exitCode, output) = Run([.. args]); + if (exitCode != 0) + throw new SdkException($"dotnet msbuild could not evaluate {project}:{Environment.NewLine}{output}"); + + var properties = new Dictionary(StringComparer.OrdinalIgnoreCase); + var json = output.Trim(); + if (json.StartsWith('{')) + { + using var document = JsonDocument.Parse(json); + foreach (var property in document.RootElement.GetProperty("Properties").EnumerateObject()) + properties[property.Name] = property.Value.GetString() ?? ""; + } + else + { + // with a single -getProperty, msbuild prints the bare value + foreach (var name in names) + properties[name] = json; + } + return properties; + } +} diff --git a/src/assembly-differ/Projects/ProjectComparison.cs b/src/assembly-differ/Projects/ProjectComparison.cs new file mode 100644 index 0000000..d9d1857 --- /dev/null +++ b/src/assembly-differ/Projects/ProjectComparison.cs @@ -0,0 +1,158 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using Differ.Engine; +using Differ.Providers; +using Differ.Providers.NuGet; +using Differ.Providers.PreviousNuGet; +using NuGet.Frameworks; +using NuGet.Versioning; + +namespace Differ.Projects; + +/// A project to compare: its file, package id, assembly name and the framework compared. +internal sealed record Project(string Path, string PackageId, string AssemblyName, NuGetFramework Framework); + +/// Finds, builds and compares the projects in a directory with their latest releases. +internal static class ProjectComparison +{ + public sealed record Options(IReadOnlyList Projects, bool IncludeTests, bool IncludeUnpackable); + + public static int Run(string directory, Options options, ReportOptions report) + { + var candidates = Candidates(directory, options.Projects); + if (candidates.Count == 0) + { + Console.Error.WriteLine($"[diff] no solution or project in {directory}; run a command, or pass --project (see --help)"); + return 1; + } + + var projects = new List(); + foreach (var path in candidates) + { + var properties = Dotnet.Properties(path, ["IsPackable", "IsTestProject", "PackageId", "AssemblyName", "TargetFramework", "TargetFrameworks"]); + var name = System.IO.Path.GetFileNameWithoutExtension(path); + var explicitlyNamed = options.Projects.Count > 0; + if (!explicitlyNamed && IsTrue(properties["IsTestProject"]) && !options.IncludeTests) + { + Console.WriteLine($"[diff] Skipping {name}: a test project (--include-tests compares it)"); + continue; + } + if (!explicitlyNamed && !IsTrue(properties["IsPackable"]) && !options.IncludeUnpackable) + { + Console.WriteLine($"[diff] Skipping {name}: IsPackable is false (--include-unpackable compares it)"); + continue; + } + var frameworks = (properties["TargetFrameworks"].Length > 0 ? properties["TargetFrameworks"] : properties["TargetFramework"]) + .Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries) + .Select(NuGetFramework.Parse) + .ToList(); + if (frameworks.Count == 0) + { + Console.WriteLine($"[diff] Skipping {name}: it has no target framework"); + continue; + } + projects.Add(new Project(path, properties["PackageId"], properties["AssemblyName"], Nupkg.Newest(frameworks))); + } + if (projects.Count == 0) + { + Console.WriteLine("[diff] Nothing to compare"); + Console.WriteLine($"[diff] Suggested version change: {SuggestedVersionChange.None}"); + return 0; + } + + var oldAssemblies = new List(); + var newAssemblies = new List(); + var installer = new Providers.NuGet.NuGet(); + foreach (var project in projects) + { + var latest = PreviousRelease.Find(project.PackageId, new NuGetVersion(int.MaxValue, 0, 0)); + if (latest is null) + { + Console.WriteLine($"[diff] {project.PackageId} has no release yet: nothing to compare"); + continue; + } + var targetPath = Dotnet.Properties( + project.Path, + ["TargetPath"], + $"TargetFramework={project.Framework.GetShortFolderName()}", + "Configuration=Release" + )["TargetPath"]; + if (!File.Exists(targetPath)) + { + Console.Error.WriteLine( + $"[diff] warning: skipping {project.AssemblyName}, which has no build output at {targetPath}; build it first with: dotnet build -c Release" + ); + continue; + } + var release = $"{project.PackageId} {latest.ToNormalizedString()}"; + var released = new NuGetAssemblyProvider(installer, [project.PackageId, latest.ToNormalizedString(), project.Framework.GetShortFolderName()]) + .GetAssemblies(new HashSet(StringComparer.OrdinalIgnoreCase) { project.AssemblyName }) + .ToList(); + if (released.Count == 0) + { + // a tool package, for one, ships its assembly outside lib/ + Console.WriteLine($"[diff] {release} ships no {project.AssemblyName}.dll to compare with"); + continue; + } + Console.WriteLine($"[diff] Comparing {project.AssemblyName} ({project.Framework.GetShortFolderName()}) with {release}"); + oldAssemblies.Add(new DiffSide(new FixedAssemblyProvider(released), "nuget")); + newAssemblies.Add(new DiffSide(new FixedAssemblyProvider([new FileInfo(targetPath)]), "assembly")); + } + if (oldAssemblies.Count == 0) + { + Console.WriteLine($"[diff] Suggested version change: {SuggestedVersionChange.None}"); + return 0; + } + + var targets = new HashSet(report.Target ?? projects.Select(p => p.AssemblyName), StringComparer.OrdinalIgnoreCase); + var failOn = Enum.Parse(report.FailOn, ignoreCase: true); + return DiffRunner.Run( + new DiffSide(new CompositeAssemblyProvider(oldAssemblies.Select(s => s.Provider)), "projects"), + new DiffSide(new CompositeAssemblyProvider(newAssemblies.Select(s => s.Provider)), "projects"), + new DiffSettings(targets, report.Format, report.Output, failOn, AllowEmptyPreviousNuget: false) + ); + } + + private static bool IsTrue(string value) => string.Equals(value, "true", StringComparison.OrdinalIgnoreCase); + + /// + /// The project files to consider: the ones named, or the projects of the one solution in the directory, or the + /// project files in it. + /// + private static List Candidates(string directory, IReadOnlyList named) + { + if (named.Count > 0) + return named.Select(System.IO.Path.GetFullPath).ToList(); + + var solutions = Directory.EnumerateFiles(directory, "*.slnx").Concat(Directory.EnumerateFiles(directory, "*.sln")).ToList(); + if (solutions.Count > 1) + throw new ArgumentException($"{directory} holds more than one solution; pass --project for the projects to compare"); + if (solutions.Count == 1) + { + var solutionDirectory = System.IO.Path.GetDirectoryName(solutions[0])!; + return Dotnet.SolutionProjects(solutions[0]).Select(p => System.IO.Path.GetFullPath(System.IO.Path.Combine(solutionDirectory, p))).ToList(); + } + return Directory + .EnumerateFiles(directory, "*.csproj") + .Concat(Directory.EnumerateFiles(directory, "*.fsproj")) + .Concat(Directory.EnumerateFiles(directory, "*.vbproj")) + .ToList(); + } +} + +/// Assemblies already found, such as the ones a release was unpacked to. +internal sealed class FixedAssemblyProvider(IReadOnlyList assemblies) : IAssemblyProvider +{ + public IEnumerable GetAssemblies(HashSet targets) => + assemblies.Where(a => targets.Count == 0 || targets.Contains(System.IO.Path.GetFileNameWithoutExtension(a.Name))); +} + +/// The assemblies of several providers together, such as one per project. +internal sealed class CompositeAssemblyProvider(IEnumerable providers) : IAssemblyProvider +{ + private readonly List _providers = providers.ToList(); + + public IEnumerable GetAssemblies(HashSet targets) => _providers.SelectMany(p => p.GetAssemblies(targets)).ToList(); +} diff --git a/src/assembly-differ/Projects/ProjectsCommand.cs b/src/assembly-differ/Projects/ProjectsCommand.cs new file mode 100644 index 0000000..f2b86eb --- /dev/null +++ b/src/assembly-differ/Projects/ProjectsCommand.cs @@ -0,0 +1,45 @@ +using System; +using System.Collections.Generic; +using System.IO; +using Nullean.Argh; + +namespace Differ.Projects; + +internal sealed class ProjectsCommand +{ + /// + /// Compares every library project in the current directory with the latest release of its package. Runs when no + /// command is given. + /// + /// + /// It reads the one solution in the directory, or else the project files in it, and skips test projects and projects + /// with IsPackable set to false. It compares each project's Release build, for its newest target framework, with the + /// latest stable release of its package on the feeds your NuGet.config lists. It does not build: run + /// dotnet build -c Release first, and a project without build output is skipped with a warning. A project whose + /// package has no release yet is reported and skipped. It needs the .NET SDK, to read the projects. + /// + /// Compare this project file, whatever kind it is. Repeat it for more than one. + /// Compare test projects too. + /// Compare projects with IsPackable set to false too. + /// How to report the comparison. + /// dotnet build -c Release && assembly-differ + /// assembly-differ --project src/MyLib/MyLib.csproj --fail-on major + [DefaultCommand] + [CommandName("projects")] + public int Projects(List? project = null, bool includeTests = false, bool includeUnpackable = false, [AsParameters] ReportOptions? report = null) + { + try + { + return ProjectComparison.Run( + Directory.GetCurrentDirectory(), + new ProjectComparison.Options(project ?? [], includeTests, includeUnpackable), + report ?? new ReportOptions() + ); + } + catch (Exception e) when (e is Dotnet.SdkException or ArgumentException) + { + Console.Error.WriteLine($"[diff] {e.Message}"); + return 1; + } + } +} diff --git a/src/assembly-differ/Providers/NuGet/NuGetAssemblyProvider.cs b/src/assembly-differ/Providers/NuGet/NuGetAssemblyProvider.cs index 86b922c..a0d3849 100644 --- a/src/assembly-differ/Providers/NuGet/NuGetAssemblyProvider.cs +++ b/src/assembly-differ/Providers/NuGet/NuGetAssemblyProvider.cs @@ -58,7 +58,13 @@ public IEnumerable GetAssemblies(HashSet targets) return Enumerable.Empty(); var packageFrameworks = new HashSet(package.FrameworkVersions.Select(f => f.GetShortFolderName()), StringComparer.InvariantCultureIgnoreCase); - var frameworkVersion = packageFrameworks.First(); + var frameworkVersion = packageFrameworks.FirstOrDefault(); + if (frameworkVersion is null) + { + // a package of analyzers or build files only, for one + Console.WriteLine($"{package.Id} {_command.Version} ships no assemblies under lib/"); + return []; + } if (_command.FrameworkVersion != null) { diff --git a/src/assembly-differ/Providers/NupkgAssemblyProvider.cs b/src/assembly-differ/Providers/NupkgAssemblyProvider.cs index 7a1b6d2..30334fb 100644 --- a/src/assembly-differ/Providers/NupkgAssemblyProvider.cs +++ b/src/assembly-differ/Providers/NupkgAssemblyProvider.cs @@ -64,10 +64,14 @@ public static (string Id, string Version) Identity(string path) public static IReadOnlyList Frameworks(string path) { using var reader = new PackageArchiveReader(path); - return reader - .GetLibItems() - .Where(g => g.Items.Any(i => i.EndsWith(".dll", StringComparison.OrdinalIgnoreCase))) - .Select(g => g.TargetFramework) + return Order(reader.GetLibItems().Where(g => g.Items.Any(i => i.EndsWith(".dll", StringComparison.OrdinalIgnoreCase))).Select(g => g.TargetFramework)); + } + + /// The framework would list first. + public static NuGetFramework Newest(IEnumerable frameworks) => Order(frameworks)[0]; + + private static List Order(IEnumerable frameworks) => + frameworks .OrderByDescending( f => f.Framework switch @@ -80,5 +84,4 @@ public static IReadOnlyList Frameworks(string path) ) .ThenByDescending(f => f.Version) .ToList(); - } } diff --git a/src/assembly-differ/README.md b/src/assembly-differ/README.md index 1cc482b..da3ba76 100644 --- a/src/assembly-differ/README.md +++ b/src/assembly-differ/README.md @@ -19,6 +19,13 @@ the `assembly-differ` package itself, not those. ## Quick start +In a repository, build it, then run the tool without a command to compare every library project with its latest +release: + +```sh +dotnet build -c Release && assembly-differ +``` + Compare the package you just packed with its last release on nuget.org, and fail on a breaking change: ```sh @@ -40,7 +47,7 @@ overloads, ends with: | `release ` | a `.nupkg`, `.dll` or directory with the release before it on your NuGet.config feeds; a first release succeeds | | `files ` | two local builds: `.dll`s, directories or `.nupkg`s | | `nuget ` | two published versions | -| `github --build --artifacts ` | a build with an older commit, built with your command | +| `projects` | every library project in the directory against its latest release; what runs without a command | | Option | What | |---|---| diff --git a/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.github.64ea231d.verified.txt b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.github.64ea231d.verified.txt deleted file mode 100644 index 674a1d1..0000000 --- a/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.github.64ea231d.verified.txt +++ /dev/null @@ -1,22 +0,0 @@ -Usage: assembly-differ github --build --artifacts [options] - - Compares a new build with an older commit of a GitHub repository, built with the command you give. - -Arguments: - The repository as owner/name. - The commit, branch or tag to build as the old version. - The new build: a .dll or a directory. - -Global options: - -h, --help Show help. - -Options: - --build [required] The command that builds the old commit, run in its checkout. - --artifacts [required] Where the build leaves the assemblies, relative to the checkout. - -t, --target [repeatable] Only compare these assemblies, by file name without extension. Repeat it for more than one. - -f, --format The report: markdown, xml, asciidoc, github-comment or json. [default: markdown] [allowed: markdown|xml|asciidoc|github-comment|json] - -o, --output A directory or file to write the report to, besides the console. - --fail-on Exit with code 4 when the suggested version change is at least this: none (never), patch, minor or major. [default: none] [allowed: none|patch|minor|major] - -Examples: - assembly-differ github nullean/proc 0.13.0 src/Proc/bin/Release/netstandard2.0 --build "dotnet build -c Release" --artifacts src/Proc/bin/Release/netstandard2.0 diff --git a/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.projects.4296bad0.verified.txt b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.projects.4296bad0.verified.txt new file mode 100644 index 0000000..3382cd7 --- /dev/null +++ b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.projects.4296bad0.verified.txt @@ -0,0 +1,28 @@ +Usage: assembly-differ projects [options] + + Compares every library project in the current directory with the latest release of its package. Runs when no command is given. + +Global options: + -h, --help Show help. + +Options: + --project [repeatable] Compare this project file, whatever kind it is. Repeat it for more than one. [default: null] + --include-tests Compare test projects too. + --include-unpackable Compare projects with IsPackable set to false too. + -t, --target [repeatable] Only compare these assemblies, by file name without extension. Repeat it for more than one. + -f, --format The report: markdown, xml, asciidoc, github-comment or json. [default: markdown] [allowed: markdown|xml|asciidoc|github-comment|json] + -o, --output A directory or file to write the report to, besides the console. + --fail-on Exit with code 4 when the suggested version change is at least this: none (never), patch, minor or major. [default: none] [allowed: none|patch|minor|major] + +Notes: + + It reads the one solution in the directory, or else the project files in it, and skips test projects and projects + with IsPackable set to false. It compares each project's Release build, for its newest target framework, with the + latest stable release of its package on the feeds your NuGet.config lists. It does not build: run + dotnet build -c Release first, and a project without build output is skipped with a warning. A project whose + package has no release yet is reported and skipped. It needs the .NET SDK, to read the projects. + +Examples: + dotnet build -c Release && assembly-differ + + assembly-differ --project src/MyLib/MyLib.csproj --fail-on major diff --git a/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt new file mode 100644 index 0000000..39876aa --- /dev/null +++ b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt @@ -0,0 +1,30 @@ +Usage: assembly-differ pull-request [options] + + Puts a report on the pull request a GitHub Actions run is for: the job summary, one comment kept up to date, and the release label for the suggested version change. + +Arguments: + The api-changes.json a command wrote with --format json. + +Global options: + -h, --help Show help. + +Options: + --repository The repository as owner/name; defaults to GITHUB_REPOSITORY. [default: null] + --pull-request The pull request number; defaults to the one in GITHUB_EVENT_PATH. [default: default] + --major-label The label for a Major change, matching release-drafter's; empty sets none. [default: breaking] + --minor-label The label for a Minor change; empty sets none. [default: feature] + --patch-label The label for a Patch change; empty sets none. [default: ] + --no-comment Leave the comment alone. + --no-labels Leave the labels alone. + +Notes: + + Run a command with --format json first; this reads the api-changes.json it writes. The comment is found again by a + hidden marker and updated, and the labels this tool set are recorded in it: a later run swaps only those, never a + label a person added. It needs GITHUB_TOKEN with pull-requests: write. Without write access, as on a pull request + from a fork, it writes the job summary, warns and succeeds; outside a pull request it writes the job summary only. + +Examples: + assembly-differ release build/output/MyLib.1.3.0.nupkg -f json -o build/output + + assembly-differ pull-request build/output/api-changes.json diff --git a/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.root.460a906e.verified.txt b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.root.460a906e.verified.txt index 686a62e..f9fb3b2 100644 --- a/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.root.460a906e.verified.txt +++ b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.root.460a906e.verified.txt @@ -1,7 +1,13 @@ Usage: assembly-differ [options] (default command) - Compares the public API of two versions of a library and suggests the version change it calls for. Pick a command for where the versions come from; diff with provider specs, such as nuget|Proc|0.13.0, still works for existing builds. + Compares every library project in the current directory with the latest release of its package. Runs when no command is given. + + It reads the one solution in the directory, or else the project files in it, and skips test projects and projects + with IsPackable set to false. It compares each project's Release build, for its newest target framework, with the + latest stable release of its package on the feeds your NuGet.config lists. It does not build: run + dotnet build -c Release first, and a project without build output is skipped with a warning. A project whose + package has no release yet is reported and skipped. It needs the .NET SDK, to read the projects. Global options: -h, --help Show help. @@ -10,9 +16,9 @@ Global options: Commands: files Compares two local builds: dlls, directories of dlls, or .nupkg files. - github Compares a new build with an older commit of a GitHub - repository, built with the command you give. nuget Compares two published versions of a package. + projects Compares every library project in the current directory with the + latest release of its package. Runs when no command is given. pull-request Puts a report on the pull request a GitHub Actions run is for: the job summary, one comment kept up to date, and the release label for the suggested version change. diff --git a/tests/assembly-differ.Tests/.snapshots/ProjectsTests/A_library_without_a_release_has_nothing_to_compare.verified.txt b/tests/assembly-differ.Tests/.snapshots/ProjectsTests/A_library_without_a_release_has_nothing_to_compare.verified.txt new file mode 100644 index 0000000..4a59f0b --- /dev/null +++ b/tests/assembly-differ.Tests/.snapshots/ProjectsTests/A_library_without_a_release_has_nothing_to_compare.verified.txt @@ -0,0 +1,7 @@ +exit code: 0 +--- stdout +[diff] Skipping Internal: IsPackable is false (--include-unpackable compares it) +[diff] Skipping Lib.Tests: a test project (--include-tests compares it) +[diff] AssemblyDiffer.Tests.Projects.Lib has no release yet: nothing to compare +[diff] Suggested version change: None +--- stderr diff --git a/tests/assembly-differ.Tests/.snapshots/ProjectsTests/A_project_without_a_build_is_skipped_with_a_warning.verified.txt b/tests/assembly-differ.Tests/.snapshots/ProjectsTests/A_project_without_a_build_is_skipped_with_a_warning.verified.txt new file mode 100644 index 0000000..106b6bb --- /dev/null +++ b/tests/assembly-differ.Tests/.snapshots/ProjectsTests/A_project_without_a_build_is_skipped_with_a_warning.verified.txt @@ -0,0 +1,7 @@ +exit code: 0 +--- stdout +[diff] Skipping Internal: IsPackable is false (--include-unpackable compares it) +[diff] Skipping Lib.Tests: a test project (--include-tests compares it) +[diff] Suggested version change: None +--- stderr +[diff] warning: skipping Lib, which has no build output at {fixture}/repo/Lib/bin/Release/net11.0/Lib.dll; build it first with: dotnet build -c Release diff --git a/tests/assembly-differ.Tests/.snapshots/ProjectsTests/Compares_the_library_and_skips_tests_and_unpackable_projects.everything.verified.txt b/tests/assembly-differ.Tests/.snapshots/ProjectsTests/Compares_the_library_and_skips_tests_and_unpackable_projects.everything.verified.txt new file mode 100644 index 0000000..8773baf --- /dev/null +++ b/tests/assembly-differ.Tests/.snapshots/ProjectsTests/Compares_the_library_and_skips_tests_and_unpackable_projects.everything.verified.txt @@ -0,0 +1,12 @@ +exit code: 0 +--- stdout +[diff] Internal has no release yet: nothing to compare +[diff] Lib.Tests has no release yet: nothing to compare +[diff] Comparing Lib (net11.0) with AssemblyDiffer.Tests.Projects.Lib 1.0.0 +[diff] Difference found: CompositeAssemblyProvider:Lib.dll and CompositeAssemblyProvider:Lib.dll +## API Changes: `Lib` + +## `Lib.Widget` +### `Draw()` is deleted +[diff] Suggested version change: Major +--- stderr diff --git a/tests/assembly-differ.Tests/.snapshots/ProjectsTests/Compares_the_library_and_skips_tests_and_unpackable_projects.named.verified.txt b/tests/assembly-differ.Tests/.snapshots/ProjectsTests/Compares_the_library_and_skips_tests_and_unpackable_projects.named.verified.txt new file mode 100644 index 0000000..682ac6c --- /dev/null +++ b/tests/assembly-differ.Tests/.snapshots/ProjectsTests/Compares_the_library_and_skips_tests_and_unpackable_projects.named.verified.txt @@ -0,0 +1,5 @@ +exit code: 0 +--- stdout +[diff] Internal has no release yet: nothing to compare +[diff] Suggested version change: None +--- stderr diff --git a/tests/assembly-differ.Tests/.snapshots/ProjectsTests/Compares_the_library_and_skips_tests_and_unpackable_projects.verified.txt b/tests/assembly-differ.Tests/.snapshots/ProjectsTests/Compares_the_library_and_skips_tests_and_unpackable_projects.verified.txt new file mode 100644 index 0000000..d6184cf --- /dev/null +++ b/tests/assembly-differ.Tests/.snapshots/ProjectsTests/Compares_the_library_and_skips_tests_and_unpackable_projects.verified.txt @@ -0,0 +1,12 @@ +exit code: 0 +--- stdout +[diff] Skipping Internal: IsPackable is false (--include-unpackable compares it) +[diff] Skipping Lib.Tests: a test project (--include-tests compares it) +[diff] Comparing Lib (net11.0) with AssemblyDiffer.Tests.Projects.Lib 1.0.0 +[diff] Difference found: CompositeAssemblyProvider:Lib.dll and CompositeAssemblyProvider:Lib.dll +## API Changes: `Lib` + +## `Lib.Widget` +### `Draw()` is deleted +[diff] Suggested version change: Major +--- stderr diff --git a/tests/assembly-differ.Tests/CommandsTests.cs b/tests/assembly-differ.Tests/CommandsTests.cs index 435db1e..6c810bc 100644 --- a/tests/assembly-differ.Tests/CommandsTests.cs +++ b/tests/assembly-differ.Tests/CommandsTests.cs @@ -4,10 +4,10 @@ namespace Differ.Tests; -/// The command for each source: files, nuget, release and github. +/// The command for each source: files, nuget and release, and the help of every command. public class CommandsTests { - public static IEnumerable Helps() => ["", "files", "nuget", "release", "github"]; + public static IEnumerable Helps() => ["", "files", "nuget", "release", "projects", "pull-request"]; [Test] [MethodDataSource(nameof(Helps))] diff --git a/tests/assembly-differ.Tests/ProjectsTests.cs b/tests/assembly-differ.Tests/ProjectsTests.cs new file mode 100644 index 0000000..c227111 --- /dev/null +++ b/tests/assembly-differ.Tests/ProjectsTests.cs @@ -0,0 +1,147 @@ +using AwesomeAssertions; +using Nullean.Snapshots; + +namespace Differ.Tests; + +/// +/// The tool run without a command, in a directory holding a solution: a library whose previous release sits on a local +/// feed, a test project and a project that is not packable. The tool does not build; the tests run dotnet build +/// themselves, for real, so they take seconds each. +/// +[NotInParallel(nameof(ProjectsTests))] +public class ProjectsTests +{ + private const string PackageId = "AssemblyDiffer.Tests.Projects.Lib"; + + private sealed class Repository : IDisposable + { + public Repository(string scenario, bool released = true) + { + Fixture = Scenarios.Create(scenario); + Directory = System.IO.Directory.CreateDirectory(Path.Combine(Fixture.Root, "repo")).FullName; + var feed = System.IO.Directory.CreateDirectory(Path.Combine(Fixture.Root, "feed")).FullName; + var (oldSource, newSource) = Scenarios.All[scenario]; + + Project("Lib", newSource, $"{PackageId}"); + Project("Lib.Tests", "namespace Lib.Tests; public class Checks { }", "true"); + Project("Internal", "namespace Internal; public class Helper { }", "false"); + File.WriteAllText( + Path.Combine(Directory, "Repo.slnx"), + """ + + + + + + """ + ); + File.WriteAllText( + Path.Combine(Directory, "NuGet.config"), + $""" + + + + + + + + """ + ); + if (released) + CommandsTests.Package(Path.Combine(feed, $"{PackageId}.1.0.0.nupkg"), PackageId, "1.0.0", Fixture.OldAssembly, "net11.0"); + _ = oldSource; + } + + public Fixture Fixture { get; } + + public string Directory { get; } + + private void Project(string name, string source, string properties) + { + var directory = System.IO.Directory.CreateDirectory(Path.Combine(Directory, name)).FullName; + File.WriteAllText( + Path.Combine(directory, $"{name}.csproj"), + $""" + + + net11.0 + {name} + enable + {properties} + + + """ + ); + File.WriteAllText(Path.Combine(directory, "Source.cs"), source); + } + + private Dictionary Environment => + new() { ["NUGET_PACKAGES"] = Path.Combine(Fixture.Root, "packages"), ["MSBUILDDISABLENODEREUSE"] = "1", }; + + public void Build() + { + var start = new System.Diagnostics.ProcessStartInfo("dotnet", ["build", "Repo.slnx", "-c", "Release", "-nologo", "-v", "q"]) + { + WorkingDirectory = Directory, + RedirectStandardOutput = true, + RedirectStandardError = true, + }; + foreach (var (name, value) in Environment) + start.Environment[name] = value; + using var process = System.Diagnostics.Process.Start(start)!; + var output = process.StandardOutput.ReadToEnd() + process.StandardError.ReadToEnd(); + process.WaitForExit(); + process.ExitCode.Should().Be(0, output); + } + + public async Task Run(params string[] args) + { + var environment = Environment; + var result = await Cli.RunInAsync(Directory, environment, args); + // the release unpacks under the temporary directory, which differs per machine + var text = Report.Of(result, Fixture).Replace(Path.GetTempPath().Replace('\\', '/').TrimEnd('/'), "{temp}"); + return text.Replace("/private{temp}", "{temp}"); + } + + public void Dispose() => Fixture.Dispose(); + } + + [Test] + public async Task Compares_the_library_and_skips_tests_and_unpackable_projects() + { + using var repository = new Repository("method-removed"); + repository.Build(); + + (await repository.Run()).Should().MatchSnapshot(); + (await repository.Run("--include-tests", "--include-unpackable")).Should().MatchSnapshot(name: "everything"); + (await repository.Run("--project", "Internal/Internal.csproj")).Should().MatchSnapshot(name: "named"); + } + + [Test] + public async Task A_library_without_a_release_has_nothing_to_compare() + { + using var repository = new Repository("method-added", released: false); + repository.Build(); + + (await repository.Run("-f", "json")).Should().MatchSnapshot(); + } + + [Test] + public async Task A_project_without_a_build_is_skipped_with_a_warning() + { + using var repository = new Repository("method-removed"); + + (await repository.Run()).Should().MatchSnapshot(); + } + + [Test] + public async Task A_directory_without_projects_says_what_to_do() + { + using var fixture = Scenarios.Create("unchanged"); + + var result = await Cli.RunInAsync(fixture.Root, new Dictionary(), []); + + result.ExitCode.Should().Be(1); + Report.Scrub(result.Error, fixture).Trim().Should().Be("[diff] no solution or project in {fixture}; run a command, or pass --project (see --help)"); + } +}