KirillMaster.QualityGates.Build 0.3.1

quality-gates

Reusable quality gates for modern .NET (net8 / net10). MIT licensed.

No StyleCop (Roslynator covers it). Legacy .NET Framework (net48) is not supported.

Result API caveats

• Result<T> converts implicitly from T and from Error; Result<Error> is therefore ambiguous, do not use Error as T.
• ErrorType is closed by convention: add values only together with the ToHttpResult mapping (the exhaustive switch fails the build on a missing member).
• A Result or Result<T> must be used; QG0106 reports discarded and never-read results.

Usage

<GlobalPackageReference Include="KirillMaster.QualityGates.Build" Version="0.1.0" />
<PackageVersion Include="KirillMaster.QualityGates.Architecture" Version="0.1.0" />

Without central package management add <PackageReference Include="KirillMaster.QualityGates.Build" Version="0.1.0" PrivateAssets="all" /> to each project.

Copy templates/editorconfig.template from the package (or src/KirillMaster.QualityGates.Build/templates/) to .editorconfig in the repository root.

MSBuild contract

Property names are shared with the company package so one tool can drive both; the report format is described in docs/contract.md.

NuGet audit is not part of the package props (restore does not see them). Set it in Directory.Build.props:

<NuGetAuditMode>all</NuGetAuditMode>
<WarningsNotAsErrors>$(WarningsNotAsErrors);NU1900;NU1901;NU1902;NU1903;NU1904;NU1905</WarningsNotAsErrors>

Analyzers

See docs/analyzers.md. Defaults are warnings, so TreatWarningsAsErrors makes them blocking. Thresholds are tunable in .editorconfig (qg_max_method_lines = 80). QG0031/QG0032 are opt-in.

Architecture tests

public sealed class Layering : HexagonalArchitectureTests
{
    protected override IEnumerable<Assembly> Assemblies => [typeof(Shop.Domain.Order).Assembly, typeof(Shop.Application.IOrders).Assembly];
    protected override ArchitectureConfig Config => ArchitectureConfig.Hexagonal("Shop");
}

public sealed class RepoRules : RepositoryRulesTests { }

ArchitectureConfig.FromFile("architecture.json") loads custom layers: { "layers": [ { "name": "Core", "pattern": "^X\\.Core(\\..*)?$", "mayDependOn": [], "forbiddenNamespaces": ["System.IO"] } ] }. Tests carry Category=Architecture for dotnet test --filter Category=Architecture.

Module and hexagonal rules (opt in)

Both are off until the base class overrides ModuleRulesConfig / HexagonalRulesConfig (tests Modules_follow_isolation_rules, Hexagonal_roles_follow_profile_rules). Violations carry a key and a measure; a violation is tolerated while a baseline entry with the same key has a measure at least as large ({"rules": {"FeatureIsolation": {"Bill->Fulfillment": 3}}}, RuleBaseline.From(violations).ToJson() generates it). Override FailOnStaleBaseline to also fail on entries that vanished or shrank, so the baseline only shrinks.

Generic module engine (ModulesConfig, baseline quality/modules-baseline.json). Modules are ordered regexes on the type namespace, then on the assembly name; kinds are Feature, Shared, Model, Composition.

Hexagonal profile (HexagonalProfile, baseline quality/hexagonal-baseline.json). Roles come from regexes (namespace first, then assembly): *.Core*, *.Ports.Input, *.Ports.Output, *.Adapters.*, *.Runners.*, *.Host*; every pattern can be overridden.

Use-case slice rules (opt in per rule)

List rule names in HexagonalProfile.ExtraRules (JSON: "extraRules": ["FlowDirection", "HandlerIsolation"]); they use the same baseline as the rules above, and unknown names throw. A handler is a non-abstract class implementing a Ports.Input interface that matches HandlerInterfacePattern (default ^I[A-Z]\w*Handler$); the suffix of the class does not matter. Flow levels are Runner, Handler, Domain (other Core), Port (Ports.Input and Ports.Output) and Adapter.

StableDependencies (module engine, ModulesConfig) reports A->B when I(B) > I(A) + StableDependenciesEpsilon (0.15) with I = Ce / (Ca + Ce); modules with fewer than StableDependenciesMinCoupling (4) couplings are skipped. It is a warning (written to stderr by Modules_follow_isolation_rules, override ReportWarnings) until EnforceStableDependencies is true; then it fails on new entries like the other rules.

Convention and contract helpers (test classes)

Call these from your own tests; findings are RuleViolations, so RuleBaseline works on them.

Test types (TestPattern) have no role and are only the reference source of HandlerReferenced. DI registration classes (CompositionTypePattern, e.g. ServiceCollectionExtensions) are outside the flow levels; runners may use output port DTOs (the rule covers interfaces). Selected rules whose roles match no type throw instead of passing silently. Runner and Runners segments both mean runners; Core features live under Core.Features.X or Core.Internal.X. UniqueErrorCodes counts only members typed Error (errorTypePattern) and string members named *Code (codeMemberPattern); an unreadable member is a violation.

OpenAPI breaking changes are direction-aware (request: removed enum values, new required properties, narrowed nullability; response: added enum values, dropped required, removed properties, widened nullability; also format changes, oneOf/anyOf as sets, path-level parameters, renamed path templates). Relative snapshot paths resolve against the repository root (QG_REPO_ROOT, else .git or solution above the binaries). QG_UPDATE_SNAPSHOTS is ignored when CI is set.

Snapshot files are never rewritten silently: a missing or different file fails and lists the breaking changes; set QG_UPDATE_SNAPSHOTS=1 to write it, plus QG_ALLOW_BREAKING_CHANGES=1 when the diff contains breaking changes. The OpenAPI document comes from a WebApplicationFactory test (class T) or the build-time generator.

Optional package KirillMaster.QualityGates.Testing.AspNetCore

HostSmoke.AssertStartsAsync<Program>(configure) starts the host with test configuration (ValidateOnStart and DI validation run) and probes one path for non-5xx (Z14). RouteRecorder records the routes the tests hit (factory.WithWebHostBuilder(b => b.ConfigureServices(recorder.Install))) and AssertAllRoutesHit(factory.Services, known) fails for every route in the endpoint table that no test hit (infrastructure routes openapi, swagger, health ignored; known is the ratchet list). HostSmoke.AssertSingleExceptionHandler(factory.Services) checks X1 against the registered services. Targets net10.0 and requires Microsoft.AspNetCore.Mvc.Testing 10.x (the package depends on it; do not pin another major). Fallback endpoints (MapFallback) are not routes, and a 404 answered by a catch-all route or matching no endpoint is not a hit.

Refactoring and baseline keys

Keys name modules and types (Bill->Fulfillment, Shop.Core.IFat), so a move or rename makes the old entry stale and the same violation new. Remap the baseline in the same change: RuleBaseline.FromFile(path).Remap(new Dictionary<string, string> { ["Old.Type"] = "New.Type" }).ToJson() renames exact keys, keeps the measure (the larger one if two keys collapse) and leaves unmapped keys alone. Relative baseline paths need RepositoryRoot; without it the test throws instead of using an empty baseline. FailOnStaleBaseline only checks the rules the test ran, so one baseline file can be shared.

Legacy projects (ratchet)

Set QualityGatesProfile=legacy-ratchet, put existing violations into quality/grandfathered/<Project>.GlobalSuppressions.cs and record the count in quality/baseline.json ({"maxGrandfatheredSuppressions": 42}). Suppressions_stay_under_baseline fails if the count grows or if the baseline is stale, so it can only go down.

Type cycles

HexagonalArchitectureTests.Types_have_no_new_cycles finds cycles between types of the given assemblies (strongly connected components of the type dependency graph; compiler-generated types and nested-to-containing edges are ignored). Known cycles are tolerated through quality/type-cycles.json (ArchitectureConfig.TypeCycleBaselinePath): {"cycles": [["Shop.A", "Shop.B"]]}, one member set per cycle; a cycle that gains a member counts as new. TypeCycleBaseline.From(TypeCycles.Find(...)).ToJson() generates the file. Disable with CheckTypeCycles = false.

Refactor mode

QualityGatesMode=refactor (property in Directory.Build.props or the project, /p:, or env QUALITYGATES_MODE) does three things for in-scope projects:

1. Stops compiling quality/grandfathered/*.GlobalSuppressions.cs, so every grandfathered violation is an error again.
2. Sets TreatWarningsAsErrors=true, even when the project sets false.
3. Adds quality.refactor.globalconfig (global_level = 100), which sets all QualityGates.* analyzer categories (Abstraction, Design, Errors, Hygiene, Naming, Size, Testing) to error. This also enables the opt-in QG0031/QG0032. In every profile and mode QG rules are at least warnings, so the CI new-code gate sees them on changed lines; legacy code is covered by grandfathered suppressions. Curated third-party analyzers and AnalysisLevel are not changed (they already follow the profile); an .editorconfig entry still wins over the globalconfig.

Use QualityGatesRefactorScope to work on a few projects at a time; the rest keep adopt behaviour. Mode and scope are resolved in the package .targets, and TreatWarningsAsErrors is applied by the QualityGatesResolveMode target before compilation.

Gates and where they run

See .github/workflows/ci.yml and samples/HexSample.

Develop

dotnet build -c Release
dotnet test -c Release
dotnet pack -c Release        # writes artifacts/*.nupkg

Sample against the local feed: dotnet test samples/HexSample/HexSample.sln (restores from artifacts/).

Releasing

Publishing runs in .github/workflows/release.yml and authenticates to nuget.org with Trusted Publishing (OIDC, no API key stored anywhere). The nuget.org trusted publishing policy must match owner KirillMaster, repository quality-gates, workflow file release.yml.

One-time setup: add the repository variable NUGET_USER (Settings → Secrets and variables → Actions → Variables) set to your nuget.org profile name.

Per release: bump Version in Directory.Build.props, update CHANGELOG.md, then:

git tag v0.1.0 && git push origin v0.1.0

The workflow derives the package version from the tag (v0.1.0 → 0.1.0) and pushes with --skip-duplicate. Manual run: Actions → release → Run workflow, enter version.