From 6e435b1447889bdbd1d6ea8e017897912f67a3bf Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Sat, 14 Nov 2026 23:52:42 +0100 Subject: [PATCH] Point to Nullean.Snapshots.PublicApi and dotnet-inspect, and list the library packages The README's packages table gains Nullean.PublicApi and Nullean.PublicApi.Diff; Public API files gains how to keep the same file as a test snapshot, and where dotnet-inspect fits. The agent skill says the same. Co-Authored-By: Claude Opus 5.5 --- README.md | 18 +++++++++++++++++- .../skills/assembly-differ/SKILL.md | 4 +++- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 385bb1d..dc6edd5 100644 --- a/README.md +++ b/README.md @@ -289,7 +289,9 @@ implementers or inheritors), whether it breaks compiled code, source or both, an A change that only breaks implementers or inheritors of a type nobody outside can implement or derive from is no break; one on a type marked with an attribute named `InternalImplementationOnlyAttribute` is listed but does not ask for a -major version. `api` takes a `.dll`, a directory or a `.nupkg` instead of the solution, `--split namespace` or +major version. `api` shows a public API and what changed in it; for everything else in a package, such as its dependencies, +frameworks and files, use [dotnet-inspect](https://github.com/richlander/dotnet-inspect). `api` takes a `.dll`, a +directory or a `.nupkg` instead of the solution, `--split namespace` or `--split top-level-namespace` for a file per namespace in a large assembly, and `-f json` to print every part of each declaration as a field. @@ -318,6 +320,18 @@ It fails when the files do not match, with the report above in the log. With `co files. Its other inputs are `path`, `projects`, `target`, `framework` and `split`, as for the command, and `working-directory`, `token` and `version`; its outputs are `matches` and `suggested-change`. +### In a test + +[Nullean.Snapshots.PublicApi](https://www.nuget.org/packages/Nullean.Snapshots.PublicApi) keeps the same `.api` file +as a snapshot in a test, for repositories that would rather fail a test than a build step: + +```csharp +[Test] +public void Public_api_is_unchanged() => typeof(Widget).Assembly.Should().MatchApiSnapshot(); +``` + +A failure lists each change with the version change it calls for, who it breaks and its line in the verified file. + ### Container The same image works anywhere `docker run` does, such as GitLab CI or a machine without the .NET SDK: @@ -358,6 +372,8 @@ The tool ships as one package per platform. Install the root package; the .NET S | `assembly-differ.` | the native-AOT build for `linux-x64`, `linux-arm64`, `win-x64`, `win-arm64` and `osx-arm64` | [![NuGet](https://img.shields.io/nuget/v/assembly-differ.linux-x64?style=flat-square)](https://www.nuget.org/packages/assembly-differ.linux-x64) | | [`assembly-differ.skills`](src/assembly-differ.skills/README.md) | the agent skill for the tool, content only; a development dependency | [![NuGet](https://img.shields.io/nuget/v/assembly-differ.skills?style=flat-square)](https://www.nuget.org/packages/assembly-differ.skills) | | `assembly-differ.any` | the framework-dependent fallback (net11.0) for every other platform | [![NuGet](https://img.shields.io/nuget/v/assembly-differ.any?style=flat-square)](https://www.nuget.org/packages/assembly-differ.any) | +| [`Nullean.PublicApi`](src/Nullean.PublicApi/README.md) | the library: reads an assembly's public API into a model, and writes and parses `.api` files (netstandard2.0, net10.0) | [![NuGet](https://img.shields.io/nuget/v/Nullean.PublicApi?style=flat-square)](https://www.nuget.org/packages/Nullean.PublicApi) | +| [`Nullean.PublicApi.Diff`](src/Nullean.PublicApi.Diff/README.md) | the library: compares two APIs and says who each change breaks and the version change it calls for | [![NuGet](https://img.shields.io/nuget/v/Nullean.PublicApi.Diff?style=flat-square)](https://www.nuget.org/packages/Nullean.PublicApi.Diff) | ## Learn more diff --git a/src/assembly-differ.skills/skills/assembly-differ/SKILL.md b/src/assembly-differ.skills/skills/assembly-differ/SKILL.md index 110896d..e0a715a 100644 --- a/src/assembly-differ.skills/skills/assembly-differ/SKILL.md +++ b/src/assembly-differ.skills/skills/assembly-differ/SKILL.md @@ -56,7 +56,9 @@ Some repositories commit `.api` files (usually in `api/`): the public API as C#, change a library's public API on purpose, regenerate them with `assembly-differ api -o api` after a Release build and commit them with the change; `api --verify api` exits with 5 and lists each change by path, file and line, who it breaks (callers, implementers or inheritors), whether compiled code, source or both, and the suggested version change. To see -a package's API without decompiling it, `assembly-differ api MyLib.1.2.0.nupkg` prints it. +a package's API without decompiling it, `assembly-differ api MyLib.1.2.0.nupkg` prints it. In a test, the same file can be a snapshot: +`typeof(Widget).Assembly.Should().MatchApiSnapshot()` from the `Nullean.Snapshots.PublicApi` package. For what a package +holds beyond its API (dependencies, frameworks, files), use `dotnet-inspect` instead. ## Reading the result