Invex.RepoUtils.Atom.Module 3.2.0

Invex .NET Repo Utils

Invex.RepoUtils bundles the tooling the Invex team uses to keep its .NET repositories consistent, well-versioned and safe to release: a Roslyn analyzer that makes every public API exposure deliberate, a test utility that snapshots the public API surface, and an Atom build module that turns those snapshots into CI checks and automates PR and package housekeeping.

Packages

Features

• Intentional public API. Rule IPAA0001 reports every effectively-public member that is not annotated with [PublicAPI] or another attribute you allow.
• API surface snapshots. PublicApiSurfaceTestUtil.GetPublicApiSurface serialises an assembly's public types and member names to JSON for approval testing with Verify.
• Breaking-change gate. The CheckPrForBreakingChanges target diffs your API snapshot files against the latest v{semver} release and fails the PR check when the version bump is too small.
• Dependabot auto-merge. The ApproveDependabotPr target enables auto-merge on Dependabot pull requests with a dedicated PAT.
• Wait for Copilot review. The WaitForCopilotReview target blocks until GitHub Copilot has finished reviewing a pull request.
• DocFX and NuGet housekeeping. Helpers build, serve and publish a DocFX site to gh-pages and unlist superseded prerelease packages.

Installation

dotnet add package Invex.RepoUtils.PublicApiAnalyzers   # in library projects
dotnet add package Invex.RepoUtils.TestUtils            # in test projects
dotnet add package Invex.RepoUtils.Atom.Module          # in your Atom build project (_atom)

• Invex.RepoUtils.PublicApiAnalyzers is a development dependency (analyzer only) and adds no runtime assemblies. It recognises PublicAPI / PublicAPIAttribute by name but does not ship the attribute: add JetBrains.Annotations or define an equivalent attribute.
• Invex.RepoUtils.TestUtils depends on JetBrains.Annotations (and System.Text.Json on netstandard2.0). It returns a JSON string, so pair it with a snapshot library such as Verify.
• Invex.RepoUtils.Atom.Module builds on Invex.Atom.Module.GitHubWorkflows, Invex.Atom.Module.Dotnet and Octokit.GraphQL. Version 3 requires Atom 5 or later.

Quick start

Annotate your public API, then snapshot it in a test:

using JetBrains.Annotations;

// IPAA0001: Public member 'Unmarked' is missing [PublicAPI] or other valid attribute
public class Unmarked { }

// No diagnostic: the type and all its public members are part of the API surface.
[PublicAPI]
public class Marked
{
    public int Value { get; set; }
}

using Invex.RepoUtils.TestUtils;

[TestFixture]
public class PublicApiTests
{
    [Test]
    public Task VerifyPublicApiSurface() =>
        VerifyJson(PublicApiSurfaceTestUtil.GetPublicApiSurface(typeof(Marked).Assembly));
}

Commit the resulting *.verified.txt file so every API change shows up in review.

Usage

Configure the analyzer

Extend the attributes that satisfy IPAA0001 or change its severity in .editorconfig:

[*.cs]
dotnet_code_quality.Invex_RepoUtils_PublicApiAnalyzers_ValidPublicApiAttributes = Experimental, MyCompanyApi
dotnet_diagnostic.IPAA0001.severity = error

See Public API Analyzers and its rules and configuration pages.

Snapshot the public API surface

GetPublicApiSurface lists every top-level public type with its public member names, excluding accessors and operators. The snapshot files double as the input to the breaking-change check.

See Test Utilities.

Gate pull requests on breaking changes

Add ICheckPrForBreakingChanges to your Atom build and point it at your snapshot files:

[BuildDefinition]
[GenerateEntryPoint]
internal interface IBuild : IWorkflowBuildDefinition, ICheckPrForBreakingChanges
{
    IEnumerable<RootedPath> ICheckPrForBreakingChanges.BreakingChangeFilesToCheck =>
        RootedFileSystem
            .Directory
            .GetFiles(RootedFileSystem.AtomRootDirectory / "tests", "*.verified.txt", SearchOption.AllDirectories)
            .Select(RootedFileSystem.CreateRootedPath);
}

Removed lines count as major changes and added lines as minor changes; the target posts a pass/fail GitHub check run. See Breaking Change Detection.

Automate pull requests and releases

IApproveDependabotPr, IWaitForCopilotReview, IDocFxHelper and INugetPackageUnlistHelper cover Dependabot auto-merge, waiting for Copilot, DocFX publishing and prerelease cleanup. See Atom Build Module, Targets and Helpers.

Documentation

Full documentation: https://invex-games.github.io/dotnet-repo-utils/

Development

The repository requires the .NET 11 SDK (see global.json), plus the .NET 10 runtime (or SDK) for the net10.0 tests and build project. Tests run on net10.0 and net11.0.

dotnet build Invex.RepoUtils.slnx
dotnet test Invex.RepoUtils.slnx

Preview the documentation site with the Atom build definition:

atom BuildDocs
atom ServeDocs
# equivalently
dotnet run --project _atom/_atom.csproj -- ServeDocs

See Contributing for the repository layout, CI workflows and pull request process.

License

Licensed under the MIT License. Copyright © 2026 Invex Games.