Add Trellis.Asp.ApiVersioning package: CreatedAtVersionedRoute helpers + TRLS023 analyzer

[xavierjohn]

Issue

Under query/header API versioning, today's CreatedAtRoute(...) pattern produces a Location header that silently omits the api-version parameter unless every author remembers to add ["api-version"] = "<version>" to the route-value dictionary on every 201 Created. Forgetting it produces a Location URL that 404s on dereference — invisible without integration tests.

Both 2026-05-06 lab models hit this. The pattern is documented as a Mistake-regression routing hint in the cookbook, but doc-only guidance hasn't been enough to shift behaviour (B37: "Opus regressed on this between 2026-04-29 and 2026-04-30 despite Patterns Index callout").

Fix

New package Trellis.Asp.ApiVersioning with two integrated parts that together close the failure mode at runtime + compile time:

Part A — runtime helper

Three CreatedAtVersionedRoute extension overloads on HttpResponseOptionsBuilder<TDomain> resolve and inject the api-version route value at request time:

result.ToHttpResponse(opts => opts
    .CreatedAtVersionedRoute("Customers_GetById", c => c.Id.Value));
//   ↑ Location = /customers/{id}?api-version=<requested-version>

Per-request resolution: HttpContext.RequestedApiVersion → endpoint metadata's single declared version → ApiVersioningOptions.DefaultApiVersion → throw InvalidOperationException. Skips injection on [ApiVersionNeutral] endpoints and URL-segment-versioned routes. Three overloads cover multi-key, single-id-convenience, and explicit-version-pin cases.

Part B — TRLS023 analyzer + code-fix

Warns when HttpResponseOptionsBuilder<T>.CreatedAtRoute(routeName, c => new RouteValueDictionary { ... }) is invoked on a controller with [ApiVersion(...)] and the dictionary literal does not include an "api-version" key. The code-fix mechanically rewrites to CreatedAtVersionedRoute(...). Bails to a false-negative for non-literal route values, [ApiVersionNeutral] controllers, and non-versioned controllers — preventing alarm fatigue.

This closes B37's regression risk: the analyzer catches the bug at compile time even for code that hasn't migrated to the helper.

Architecture (additive)

Trellis.Asp gains one new generic primitive — HttpResponseOptionsBuilder<TDomain>.WithRouteValueResolver(string key, Func<HttpContext, string?> resolver) — that lets any consumer register a per-request route-value injector. Trellis.Asp.ApiVersioning builds CreatedAtVersionedRoute on top of this hook. The hook is reusable for tenant id, culture code, or any other cross-cutting per-request concern; the api-versioning package's Asp.Versioning.* dependency stays contained.

Tests

Test surface	Count	Coverage
Trellis.Asp.Tests (hook layer)	3 unit tests	WithRouteValueResolver arg validation + chaining contract
Trellis.Asp.ApiVersioning.Tests	6 integration tests	Single-version, multi-version with/without default, explicit-pin, single-id-convenience, fallback ordering
Trellis.Analyzers.Tests	5 analyzer tests	Versioned controller missing key → warning; with key → no warning; non-versioned → no warning; [ApiVersionNeutral] → no warning; non-literal route values → no warning

Local verification: 924/924 Trellis.Asp; 211/211 Trellis.Analyzers (was 206 + 5 new); 6/6 new package; all 19 other framework test projects pass; local docfx build --warningsAsErrors clean.

Out of scope (deferred, tracked in BACKLOG)

• Multi-version literal-propagation generator. A first-pass ApiVersionConstants.Current source generator was implemented and reverted in this PR after recognising the design flaw: a single Current constant doesn't model services that support multiple API versions concurrently — older [ApiVersion(...)] literals stay pinned to historical values when a new version ships, so Current only covers brand-new endpoints. A correct generator would scan [ApiVersion] attributes at build time and emit a multi-version directory (KnownApiVersions.V20261112, V20261201, Current = V20261201). Tracked separately as a design spike.
• Text-asset substitution for http-client.env.json, .vscode/launch.json, api.http. The MSBuild target that mutates tracked files needs its own design pass (file-mutation vs. template-with-output, IDE behaviour, merge conflicts).
• Custom route-value key configuration — hosts using a non-default IApiVersionReader parameter name should bypass CreatedAtVersionedRoute and call WithRouteValueResolver directly for now.

[github-actions]

Test Results

5 545 tests  +24   5 530 ✅ +24   4m 35s ⏱️ +17s
   22 suites + 1      15 💤 ± 0 
   22 files   + 1       0 ❌ ± 0 

Results for commit 7e811ff. ± Comparison against base commit 0a19d40.

♻️ This comment has been updated with latest results.

[codecov]

Codecov Report

❌ Patch coverage is 71.54150% with 72 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.88%. Comparing base (0a19d40) to head (7e811ff).

Files with missing lines	Patch %	Lines
...ers/src/CreatedAtRouteMissingApiVersionAnalyzer.cs	69.23%	12 Missing and 16 partials ⚠️
.../CreatedAtRouteMissingApiVersionCodeFixProvider.cs	67.53%	12 Missing and 13 partials ⚠️
...tpResponseOptionsBuilderApiVersioningExtensions.cs	65.38%	14 Missing and 4 partials ⚠️
Trellis.Asp/src/Response/TrellisHttpResult.cs	90.90%	0 Missing and 1 partial ⚠️

❌ Your patch check has failed because the patch coverage (71.54%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #480      +/-   ##
==========================================
- Coverage   85.17%   84.88%   -0.30%     
==========================================
  Files         302      305       +3     
  Lines       11503    11754     +251     
  Branches     2471     2542      +71     
==========================================
+ Hits         9798     9977     +179     
- Misses       1167     1205      +38     
- Partials      538      572      +34     

Files with missing lines	Coverage Δ
Trellis.Analyzers/src/DiagnosticDescriptors.cs	100.00% <100.00%> (ø)
...lis.Asp/src/Response/HttpResponseOptionsBuilder.cs	100.00% <100.00%> (ø)
Trellis.Asp/src/Response/TrellisHttpResult.cs	92.02% <90.90%> (-0.19%)	⬇️
...tpResponseOptionsBuilderApiVersioningExtensions.cs	65.38% <65.38%> (ø)
.../CreatedAtRouteMissingApiVersionCodeFixProvider.cs	67.53% <67.53%> (ø)
...ers/src/CreatedAtRouteMissingApiVersionAnalyzer.cs	69.23% <69.23%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds first-class support for API-version-aware 201 Created Location headers in Trellis ASP integration by introducing a generic per-request route-value injection hook, a new Trellis.Asp.ApiVersioning package that builds CreatedAtVersionedRoute(...) on top of that hook, and a new analyzer/code-fix (TRLS023) to prevent regressions when authors use CreatedAtRoute(...) without including "api-version".

Changes:

• Add HttpResponseOptionsBuilder<TDomain>.WithRouteValueResolver(...) and apply registered resolvers during CreatedAtRoute/CreatedAtAction link generation.
• Introduce Trellis.Asp.ApiVersioning with CreatedAtVersionedRoute overloads and integration tests.
• Add TRLS023 analyzer + code fix and wire it into analyzer release tracking.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
Trellis.slnx	Adds the new Trellis.Asp.ApiVersioning projects to the solution folder structure.
Trellis.Asp/tests/HttpResponseOptionsBuilderTests.cs	Adds unit tests for WithRouteValueResolver argument validation + chaining.
Trellis.Asp/src/Response/TrellisHttpResult.cs	Applies per-request route-value resolvers when generating Location for route/action modes.
Trellis.Asp/src/Response/HttpResponseOptionsBuilder.cs	Adds WithRouteValueResolver API and plumbs resolver dictionary into built options.
Trellis.Asp.ApiVersioning/src/Trellis.Asp.ApiVersioning.csproj	Introduces the new package project and its Asp.Versioning dependencies.
Trellis.Asp.ApiVersioning/src/HttpResponseOptionsBuilderApiVersioningExtensions.cs	Adds CreatedAtVersionedRoute overloads and per-request version resolution logic.
Trellis.Asp.ApiVersioning/tests/Trellis.Asp.ApiVersioning.Tests.csproj	Adds the new test project and references needed for integration testing.
Trellis.Asp.ApiVersioning/tests/CreatedAtVersionedRouteTests.cs	Integration tests asserting Location contains (or omits) api-version correctly across configurations.
Trellis.Asp.ApiVersioning/NUGET_README.md	Package README content for NuGet.
Trellis.Analyzers/src/TrellisDiagnosticIds.cs	Adds TRLS023 diagnostic ID constant.
Trellis.Analyzers/src/DiagnosticDescriptors.cs	Adds descriptor text for TRLS023.
Trellis.Analyzers/src/CreatedAtRouteMissingApiVersionAnalyzer.cs	Implements TRLS023 detection.
Trellis.Analyzers/src/CreatedAtRouteMissingApiVersionCodeFixProvider.cs	Implements code fix rewriting CreatedAtRoute → CreatedAtVersionedRoute.
Trellis.Analyzers/tests/CreatedAtRouteMissingApiVersionAnalyzerTests.cs	Adds analyzer tests for warning/no-warning scenarios.
Trellis.Analyzers/src/AnalyzerReleases.Unshipped.md	Adds TRLS023 to the unshipped analyzer release log.
Directory.Packages.props	Adds central version for Asp.Versioning.Http.
CHANGELOG.md	Documents the new package + analyzer and the rationale.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 8 comments.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.