Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# 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). Each side comes from a provider: `assembly`, `directory`, `nuget`, `previous-nuget` or
`github`; the result is written as `xml`, `markdown`, `asciidoc` or `github-comment`. It is also published as a
patch, minor, major). A command per source (`release`, `files`, `nuget`, `github`) 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.

## Layout
Expand Down Expand Up @@ -80,8 +80,10 @@ one release label.
- `Engine/` reproduces the reports of JustAssembly, which it replaced, quirks included: a type that became less visible
is reported as more visible, and nested types are named `.Name`. Changing a report is a change to the CLI contract.

- The CLI surface (`diff`, the provider specs and the flags) is the contract `action.yml`, the container and other
repositories' builds rely on. Removing or renaming any of it is a breaking change.
- 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.
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.
- Build targets are Make.Fs `target { }` blocks in `build/scripts/Program.fs` whose commands are Proc.Fs `sh $"…"`
lines; values come from `text` inside `shell { }` (`Versions.fs`). Do not call the C# `ProcNet` API from the build.
Expand Down
68 changes: 40 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Proc 0.14.0 added a `CancellationToken` to its `Start*` methods. Diffing it agai
each old overload deleted and its replacement added, which makes the release a major change:

```console
$ assembly-differ diff "nuget|Proc|0.13.0|netstandard2.0" "nuget|Proc|0.14.0|netstandard2.0" -t proc
$ assembly-differ nuget Proc 0.13.0 0.14.0 -t proc -f xml
[diff] Difference found: NuGetAssemblyProvider:proc.dll and NuGetAssemblyProvider:proc.dll
<Assembly Name="proc, Version=0.0.0.0, Culture=neutral, PublicKeyToken=96c599bbe3e70f5d" DiffType="Modified">
<Module Name="proc.dll" DiffType="Modified">
Expand Down Expand Up @@ -61,51 +61,63 @@ runtime installed.

## Quick start

Diff the last release on nuget.org against what you just built, as Markdown, and fail the build on a breaking change:
Compare the package you just packed with its last release on nuget.org, and fail the build on a breaking change:

```sh
assembly-differ diff "previous-nuget|MyLib|1.3.0|net8.0" "directory|src/MyLib/bin/Release/net8.0" -t MyLib -f markdown -p major
assembly-differ release build/output/MyLib.1.3.0.nupkg --fail-on major
```

`previous-nuget` finds the latest release before `1.3.0`, so the same command keeps working as you release.
The package id and version come from the `.nupkg`, and the release compared with is the newest one before `1.3.0`, so
the same command keeps working as you release.

Each side is a provider spec, and the two sides can mix:

| Spec | Assemblies |
| Command | Compares |
|---|---|
| `assembly\|<path>` | one dll |
| `directory\|<path>` | every dll in a directory, matched by file name against the other side |
| `nuget\|<id>\|<version>\|[tfm]` | a package from the NuGet sources your NuGet.config lists |
| `previous-nuget\|<id>\|<version>\|[tfm]` | the release on nuget.org before `<version>` |
| `github\|<owner/repo>\|<commit>\|<build command>\|<relative output path>` | a commit, cloned and built with the command you give |
| `release <path>` | a new build, as a `.nupkg`, a `.dll` or a directory, with the release before it on nuget.org; pass `--package` and `--version` unless `<path>` is a `.nupkg` |
| `files <old> <new>` | two local builds, each a `.dll`, a directory of dlls or a `.nupkg` |
| `nuget <id> <old-version> <new-version>` | two published versions, from the NuGet sources your NuGet.config lists |
| `github <owner/repo> <commit> <path> --build <command> --artifacts <path>` | a new build with an older commit, cloned and built with the command you give |

Every command takes the same options:

| Flag | What |
| Option | What |
|---|---|
| `-t`, `--target` | only diff these assemblies (repeatable); defaults to every assembly both sides have |
| `-f`, `--format` | `xml` (default), `markdown`, `asciidoc`, `github-comment` (a pull request comment with a collapsible diff per assembly) or `json` (`api-changes.json`: the suggested change, breaking changes and every change as a tree, for tools) |
| `-o`, `--output` | output directory or file; without it the diff only goes to the console |
| `-p`, `--prevent-change` | exit with `4` when the suggested change is at least `patch`, `minor` or `major`; `none` (the default) never fails |
| `-a`, `--allow-empty-previous-nuget` | succeed when `previous-nuget` finds no earlier release, for a first release |
| `-t`, `--target` | only compare these assemblies, by file name without extension (repeatable); defaults to every assembly both sides have |
| `-f`, `--format` | `markdown` (default), `xml`, `asciidoc`, `github-comment` (a pull request comment with a collapsible diff per assembly) or `json` (`api-changes.json`: the suggested change, breaking changes and every change as a tree, for tools) |
| `-o`, `--output` | a directory or file to write the report to, besides the console |
| `--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 |

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.

The suggested change follows semantic versioning. It is `None` when the public API is unchanged, `Patch` when only
assembly references changed, and `Minor` when API was only added or attributes changed: diffing Proc 0.12.0 against
0.13.0, which only adds `NoWrapInThread`, suggests `Minor`. It is `Major` when something was removed or changed, and
when a new interface member, abstract member or `required` member makes existing code change. Always name the `diff` subcommand: a provider spec as the first argument is read as
a command name.
assembly references changed, and `Minor` when API was only added or attributes changed: Proc 0.13.0 marks
`NoWrapInThread` `[Obsolete]`, and `assembly-differ nuget Proc 0.12.0 0.13.0` suggests `Minor`. It is `Major` when
something was removed or changed, and when a new interface member, abstract member or `required` member makes existing
code change.

More examples:

```sh
# two local builds, every dll matched by name
assembly-differ diff "directory|build/1.2.0" "directory|build/1.3.0"
assembly-differ files build/1.2.0 build/1.3.0

# two published packages
assembly-differ diff "nuget|Proc|0.13.0|netstandard2.0" "nuget|Proc|0.14.0|netstandard2.0" -t proc -f markdown
# two published packages, as Markdown
assembly-differ nuget Proc 0.13.0 0.14.0 -t proc

# the last release before 0.14.0 against a local build
assembly-differ diff "previous-nuget|Proc|0.14.0|netstandard2.0" "directory|build/proc" -t proc
# the release before 1.3.0 against a build directory
assembly-differ release src/MyLib/bin/Release/net8.0 --package MyLib --version 1.3.0 -t MyLib
```

### Provider specs

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|<path>`, `directory|<path>`, `nuget|<id>|<version>|[tfm]`, `previous-nuget|<id>|<version>|[tfm]` or
`github|<owner/repo>|<commit>|<build command>|<relative output path>`. 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.

### GitHub Action

```yaml
Expand All @@ -125,7 +137,7 @@ Container actions run on Linux runners only.
The same image works anywhere `docker run` does, such as GitLab CI or a machine without the .NET SDK:

```sh
docker run --rm -v "$(pwd)":/workspace ghcr.io/nullean/assembly-differ:edge diff "directory|/workspace/old" "directory|/workspace/new"
docker run --rm -v "$(pwd)":/workspace ghcr.io/nullean/assembly-differ:edge files /workspace/old /workspace/new
```

It is native-AOT on a chiseled `runtime-deps` base, with no shell, running as a non-root user. `edge` tracks the latest
Expand Down
7 changes: 6 additions & 1 deletion build/scripts/Program.fs
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,11 @@ let main argv =
let! result = text $"{binary} diff 'previous-nuget|Proc|0.18.0' 'nuget|Proc|0.20.0' --target Proc -f markdown"
printfn "%s" result
for expected in [ "Found previous nuget package found for Proc 0.18.0: 0.17.0"; "Suggested version change: Minor" ] do
if not (result.Contains expected) then failwithf "the native-AOT binary did not print '%s'" expected }
if not (result.Contains expected) then failwithf "the native-AOT binary did not print '%s'" expected
// the commands bind through argh's generated code; Proc 0.13.0 only marks NoWrapInThread obsolete
let! command = text $"{binary} nuget Proc 0.12.0 0.13.0 --target Proc --format json"
printfn "%s" command
if not (command.Contains "\"suggestedVersionChange\": \"Minor\"") then
failwith "the native-AOT binary's nuget command did not suggest Minor" }

app.RunAsync(argv).GetAwaiter().GetResult()
194 changes: 194 additions & 0 deletions src/assembly-differ/ApiCommands.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.IO;
using System.Linq;
using Differ.Engine;
using Differ.Providers;
using Differ.Providers.GitHub;
using Differ.Providers.NuGet;
using Differ.Providers.PreviousNuGet;
using NuGet.Frameworks;
using Nullean.Argh;

namespace Differ;

/// <summary>How a comparison is reported, and when it fails.</summary>
public sealed class ReportOptions
{
/// <summary>-t, --target, Only compare these assemblies, by file name without extension. Repeat it for more than one.</summary>
public List<string>? Target { get; set; }

/// <summary>-f, --format, The report: markdown, xml, asciidoc, github-comment or json.</summary>
[AllowedValues("markdown", "xml", "asciidoc", "github-comment", "json")]
public string Format { get; set; } = "markdown";

/// <summary>-o, --output, A directory or file to write the report to, besides the console.</summary>
public string? Output { get; set; }

/// <summary>Exit with code 4 when the suggested version change is at least this: none (never), patch, minor or major.</summary>
[AllowedValues("none", "patch", "minor", "major")]
public string FailOn { get; set; } = "none";
}

/// <summary>Compares the public API of two versions of a library and suggests the version change it calls for.</summary>
internal sealed class ApiCommands
{
/// <summary>Compares two local builds: dlls, directories of dlls, or .nupkg files.</summary>
/// <param name="old">The old build: a .dll, a directory or a .nupkg.</param>
/// <param name="new">The new build: a .dll, a directory or a .nupkg.</param>
/// <param name="framework">The target framework to take from a .nupkg, such as net8.0. Defaults to the newest both packages ship.</param>
/// <param name="report">How to report the comparison.</param>
/// <example>assembly-differ files bin/1.2.0/MyLib.dll bin/1.3.0/MyLib.dll</example>
/// <example>assembly-differ files MyLib.1.2.0.nupkg MyLib.1.3.0.nupkg --framework net8.0</example>
[CommandName("files")]
public int Files([Argument] string old, [Argument] string @new, string? framework = null, [AsParameters] ReportOptions? report = null) =>
Run(
() =>
{
var chosen = Framework(framework, old, @new);
return (Local(old, chosen), Local(@new, chosen));
},
report
);

/// <summary>Compares two published versions of a package.</summary>
/// <param name="package">The package id.</param>
/// <param name="oldVersion">The old version.</param>
/// <param name="newVersion">The new version.</param>
/// <param name="framework">The target framework to compare, such as net8.0. Defaults to the first the package ships.</param>
/// <param name="report">How to report the comparison.</param>
/// <example>assembly-differ nuget Proc 0.13.0 0.14.0</example>
[CommandName("nuget")]
public int NuGet(
[Argument] string package,
[Argument] string oldVersion,
[Argument] string newVersion,
string? framework = null,
[AsParameters] ReportOptions? report = null
) =>
Run(
() =>
{
var installer = new Providers.NuGet.NuGet();
return (new DiffSide(new NuGetAssemblyProvider(installer, Spec(package, oldVersion, framework)), "nuget"), new DiffSide(
new NuGetAssemblyProvider(installer, Spec(package, newVersion, framework)),
"nuget"
));
},
report
);

/// <summary>Compares a new build with the release before it on nuget.org.</summary>
/// <remarks>
/// Give a .nupkg and the package id and version come from it; for a .dll or a directory, pass --package and --version.
/// The release compared with is the newest one before that version.
/// </remarks>
/// <param name="path">The new build: a .nupkg, a .dll or a directory.</param>
/// <param name="package">The package id; read from a .nupkg when not given.</param>
/// <param name="version">The version being released; read from a .nupkg when not given.</param>
/// <param name="framework">The target framework to compare, such as net8.0. Defaults to the newest the .nupkg ships.</param>
/// <param name="report">How to report the comparison.</param>
/// <example>assembly-differ release build/output/MyLib.1.3.0.nupkg --fail-on major</example>
/// <example>assembly-differ release src/MyLib/bin/Release/net8.0 --package MyLib --version 1.3.0 -t MyLib</example>
[CommandName("release")]
public int Release(
[Argument] string path,
string? package = null,
string? version = null,
string? framework = null,
[AsParameters] ReportOptions? report = null
) =>
Run(
() =>
{
if (Nupkg.IsPackage(path))
{
var identity = Nupkg.Identity(path);
package ??= identity.Id;
version ??= identity.Version;
}
if (package is null || version is null)
throw new ArgumentException("pass --package and --version, or a .nupkg to read them from");

var chosen = Framework(framework, path);
return (new DiffSide(
new NuGetAssemblyProvider(new PreviousNugetLocator(), Spec(package, version, chosen?.GetShortFolderName()), "previous-nuget"),
"previous-nuget"
), Local(path, chosen));
},
report
);

/// <summary>Compares a new build with an older commit of a GitHub repository, built with the command you give.</summary>
/// <param name="repository">The repository as owner/name.</param>
/// <param name="commit">The commit, branch or tag to build as the old version.</param>
/// <param name="path">The new build: a .dll or a directory.</param>
/// <param name="build">The command that builds the old commit, run in its checkout.</param>
/// <param name="artifacts">Where the build leaves the assemblies, relative to the checkout.</param>
/// <param name="report">How to report the comparison.</param>
/// <example>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</example>
[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)
{
report ??= new ReportOptions();
var targets = new HashSet<string>(report.Target ?? [], StringComparer.OrdinalIgnoreCase);
try
{
var (oldSide, newSide) = sides();
var failOn = Enum.Parse<SuggestedVersionChange>(report.FailOn, ignoreCase: true);
return DiffRunner.Run(oldSide, newSide, new DiffSettings(targets, report.Format, report.Output, failOn, AllowEmptyPreviousNuget: false));
}
catch (Exception e) when (e is ArgumentException or FileNotFoundException or DirectoryNotFoundException)
{
Console.Error.WriteLine($"[diff] {e.Message}");
return 1;
}
catch (Exception e)
{
Console.Error.WriteLine(e);
return 1;
}
}

private static string[] Spec(string package, string version, string? framework) => framework is null ? [package, version] : [package, version, framework];

/// <summary>A local build: a .nupkg, a directory of assemblies, or one assembly.</summary>
private static DiffSide Local(string path, NuGetFramework? framework)
{
if (Nupkg.IsPackage(path))
return new DiffSide(new NupkgAssemblyProvider(path, framework ?? Nupkg.Frameworks(path).FirstOrDefault() ?? NuGetFramework.AnyFramework), "nupkg");
if (Directory.Exists(path))
return new DiffSide(new DirectoryAssemblyProvider(path), "directory");
return new DiffSide(new AssemblyProvider(path), "assembly");
}

/// <summary>The framework to compare: the one given, or the newest every .nupkg among the paths ships.</summary>
private static NuGetFramework? Framework(string? framework, params string[] paths)
{
if (framework is not null)
return NuGetFramework.ParseFolder(framework);
var packages = paths.Where(Nupkg.IsPackage).Select(Nupkg.Frameworks).ToList();
if (packages.Count == 0)
return null;
var common = packages.Skip(1).Aggregate((IEnumerable<NuGetFramework>)packages[0], (shared, next) => shared.Where(next.Contains)).FirstOrDefault();
return common ?? throw new ArgumentException("the packages ship no target framework in common; pass --framework");
}
}
Loading
Loading