Invex.RepoUtils.Atom.Module 1.5.0

Invex .NET Repo Utils

A collection of .NET utilities for building and maintaining .NET repositories.

Invex.RepoUtils bundles the tooling the Invex team uses to keep its .NET repositories consistent, well-versioned, and safe to release. It ships three complementary pieces:

• A Roslyn analyzer that enforces explicit annotation of your public API surface.
• A test utilities library for snapshot-testing your public API surface.
• An Atom build module that adds reusable CI/CD targets for packing, testing, releasing, breaking-change detection, documentation generation, and Dependabot automation.

Table of contents

• Packages
• Invex.RepoUtils.PublicApiAnalyzers
  • Installation
  • Rules
  • Configuration
  • Example
• Invex.RepoUtils.TestUtils
  • Installation
  • Usage
• Invex.RepoUtils.Atom.Module
  • Targets
  • Helpers
  • Usage
• Repository structure
• Building & testing
• Versioning
• Contributing
• License

Packages

Invex.RepoUtils.PublicApiAnalyzers

A Roslyn diagnostic analyzer that helps you keep an intentional public API surface. It reports every effectively-public member that is not annotated with [PublicAPI] (or another attribute you allow), so that exposing a new type or member is always a deliberate, reviewable decision.

Installation

dotnet add package Invex.RepoUtils.PublicApiAnalyzers

The package is shipped as a development dependency (analyzer only) — it contributes no runtime assemblies to your output.

Rules

The analyzer is attribute-aware and intentionally avoids false positives:

• It walks the containing-type chain, so a member is considered annotated when it — or any of its containing types — carries a valid attribute.
• Implicitly declared members, property/event accessors, constructors, and override members are ignored.
• A member is only flagged when it is effectively public (public all the way up its containing type chain).

Configuration

By default the analyzer accepts PublicAPI / PublicAPIAttribute. You can extend the set of attributes that satisfy the rule via an .editorconfig entry. Provide a comma-separated list of attribute names (the Attribute suffix is optional — both forms are accepted):

# .editorconfig
[*.cs]
dotnet_code_quality.Invex_RepoUtils_PublicApiAnalyzers_ValidPublicApiAttributes = Experimental, MyCompanyApi

To change the severity of the rule:

[*.cs]
dotnet_diagnostic.IPAA0001.severity = error

Example

using JetBrains.Annotations;

// ⚠️ IPAA0001 — public type is not annotated.
public class Unmarked { }

// ✅ Annotated type — the type and all its public members are considered part of the API surface.
[PublicAPI]
public class Marked
{
    public int Value { get; set; }
}

Invex.RepoUtils.TestUtils

A test utility library that makes it easy to snapshot-test the public API surface of your assemblies. It uses reflection to extract all public types and their members, serialises the result to JSON, and pairs well with Verify for approval-based testing.

Installation

dotnet add package Invex.RepoUtils.TestUtils

Usage

Call PublicApiSurfaceTestUtil.GetPublicApiSurface with the assembly you want to inspect. The returned JSON string can be verified with your preferred snapshot testing library:

using Invex.RepoUtils.TestUtils;

[Test]
public Task PublicApiSurface()
{
    var surface = PublicApiSurfaceTestUtil.GetPublicApiSurface(typeof(MyLibType).Assembly);
    return Verify(surface);
}

Invex.RepoUtils.Atom.Module

An Atom build module that contributes reusable, opinionated CI/CD building blocks. Add the interfaces you need to your Atom IBuild definition and wire the provided Targets into your workflows.

Installation

dotnet add package Invex.RepoUtils.Atom.Module

Targets

Helpers

The breaking-change check compares the current build version against the most recent release tag (v{semver}). It classifies removals from the public API surface as major changes and additions as minor changes, then verifies the version has been bumped appropriately and posts a pass/fail GitHub check run with a detailed summary.

Usage

Add the desired interfaces to your build definition and reference the targets from a workflow:

[BuildDefinition]
[GenerateEntryPoint]
internal interface IBuild :
    IWorkflowBuildDefinition,
    IApproveDependabotPr,
    ICheckPrForBreakingChanges
{
    // Point the breaking-change check at your public API definition files.
    IEnumerable<RootedPath> ICheckPrForBreakingChanges.BreakingChangeFilesToCheck =>
    [
        // e.g. RootedFileSystem.AtomRootDirectory / "src/MyLib/PublicAPI.Shipped.txt",
    ];
}

See _atom/IBuild.cs for the full build definition used by this repository, including the Validate, Build, and Dependabot auto-merge workflows.

Repository structure

.
├── _atom/                                   # Atom build definition for this repo (IBuild.cs)
├── src/
│   ├── Invex.RepoUtils.Atom.Module/         # Atom CI/CD module (targets, helpers, models)
│   ├── Invex.RepoUtils.PublicApiAnalyzers/  # Roslyn public-API analyzer
│   └── Invex.RepoUtils.TestUtils/           # Test utilities for public API surface snapshots
├── tests/
│   ├── Invex.RepoUtils.Atom.Module.Tests/
│   ├── Invex.RepoUtils.PublicApiAnalyzers.Tests/
│   └── Invex.RepoUtils.TestUtils.Tests/
├── Directory.Build.props                    # Shared build settings
├── GitVersion.yml                           # Versioning configuration
└── Invex.RepoUtils.slnx                     # Solution

Building & testing

The repository targets .NET 10 and uses C# 14, with TreatWarningsAsErrors enabled.

# Restore & build the whole solution
dotnet build Invex.RepoUtils.slnx

# Run the analyzer test suite
dotnet test

The analyzer is validated across .NET 8, 9, and 10 reference assemblies in CI.

Versioning

Versions are derived automatically by GitVersion using Conventional Commits. The commit message prefix drives the bump:

Contributing

Contributions are welcome! Please:

1. Use Conventional Commit messages so versioning works correctly.
2. Annotate new public members with [PublicAPI] — the analyzer in this repo enforces it.
3. Add or update tests for analyzer changes.
4. Ensure dotnet build and dotnet test pass before opening a PR.

The Validate workflow runs the build, the test matrix, and the breaking-change check on every pull request into main.

License

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