Invex.RepoUtils.Atom.Module 2.0.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 2 requires Atom 4 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 10 SDK (see global.json).

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.