Skip to content

feat(analyzers): explain why a method cannot generate and flag unbound route placeholders - #2340

Merged
glennawatson merged 5 commits into
mainfrom
feat/explain-generation-fallback
Sep 26, 2026
Merged

glennawatson merged 5 commits into
mainfrom
feat/explain-generation-fallback

Conversation

@glennawatson

@glennawatson glennawatson commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

RF006 now says exactly why a method falls back to the reflection request builder, where, and what to change; a new RF015 flags route placeholders no parameter binds.

  • RF006 names the reason, the declaration and the remedy. The warning moves from the method name to the parameter, return type or HTTP attribute responsible, for example "query parameter 'filters' has type 'object', which cannot be flattened ... Add [QueryConverter(typeof(...))] ...".
  • Compatibility advice is specific. RF006 suggests Refit.Reflection only when it can actually run the method; for declarations both builders reject it says the declaration must change.
  • RF006 carries machine-readable properties. Reason (for example UnsupportedQueryType) and, when a parameter is responsible, ParameterOrdinal.
  • New RF015 warning for unbound route placeholders. [Get("/users/{id}")] with no id parameter is reported on the {id} text, with the parameter name to add or alias. The runtime ArgumentException stays as the backstop, and RefitSettings.AllowUnmatchedRouteParameters remains the way to keep a placeholder on purpose.
  • Opt-in strict build. <RefitRequireGeneratedRequests>true</RefitRequireGeneratedRequests> turns RF006 into an error for Native AOT or generated-only projects. It is off by default; dotnet_diagnostic.RF006.severity = error is the per-folder alternative.
  • The Native AOT smoke project covers the reflection fallback again. IObservable replies are now generated, so ObserveLegacy was replaced by a member that genuinely falls back.

Why

A fallback warning that did not say which feature triggered it left users reading generated files or guessing.

  • The reason and location come from the classifier the generator and analyzer already share, so there is still one eligibility decision and a shape the generator learns to build loses its RF006 automatically.
  • Unbound placeholders were only discovered at runtime although the compiler can see them.

Breaking changes

None.

  • RF006 wording and location change, and RF015 is a new warning. A project that treats all warnings as errors and deliberately leaves placeholders unbound needs to suppress RF015 on those methods.

How this was verified

Fixtures cover every fallback reason with its exact source span and advice, plus a classifier-backed support table (request generated, JSON metadata needed, Native AOT smoke coverage).

  • Exercised the strict switch in a scratch consumer project, set both on the command line and in the project body, and published and ran the Native AOT smoke binary.

Notes for the reviewer

Start at InlineFallbackReason.cs and ClassifyInlineRequest in Parser.Request.cs, then FallbackExplanation.cs.

  • The parser changes are mostly mechanical: each site that returned "unsupported" now also records a reason.
  • The model stores a parameter ordinal rather than a Location so RequestModel stays value-equatable for incremental caching.
  • RF015 only runs on generated requests; methods on the reflection builder are reported by RF006 instead.
  • The published support table and diagnostics reference live on the website; GeneratedRequestSupportTableTests holds the fixtures that back it.

Checklist

  • I have read the Contribute guide
  • The PR title follows Conventional Commits
  • Tests cover this change, or the summary says why they do not
  • New or changed public API has XML documentation

- Setting RefitRequireGeneratedRequests to true promotes RF006 to an error.
- Runs as a target because the consumer's project body is evaluated after refit.props.
- Off by default so builds that use Refit.Reflection on purpose are unaffected.
…d route placeholders

- The shared classifier now records the first reason a request is not generated and the parameter responsible.
- RF006 reports at that parameter, return type or attribute, names the reason and remedy, and only suggests Refit.Reflection when it can run the method.
- RF006 carries Reason and ParameterOrdinal properties for tooling.
- Add RF015 for a route placeholder no parameter binds; the runtime check stays as a backstop.
- Add classifier-backed fixtures for every reason and for the published support table.
- Any declared class or struct part is serialized, not only sealed ones.
- IObservable replies are now generated, so ObserveLegacy no longer exercised the fallback.
- SearchLegacyAsync(object) falls back for real, so the trim check for #2200 covers it again.
@codecov

codecov Bot commented Sep 26, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.97%. Comparing base (a463e8a) to head (2981089).

Additional details and impacted files
@@           Coverage Diff            @@
##             main    #2340    +/-   ##
========================================
  Coverage   99.97%   99.97%            
========================================
  Files         217      219     +2     
  Lines       11528    11784   +256     
  Branches     2221     2262    +41     
========================================
+ Hits        11525    11781   +256     
  Misses          3        3            

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

- Remove IsUrlBindingSupported, which has no callers now that FindUnsupportedUrlBinding reports the ordinal.
- An RF015 placeholder always comes from a source attribute's first argument, so its location lookup needs no null guard.
- Cover method-level fallbacks located on the method, including one with no source declaration.
@sonarqubecloud

Copy link
Copy Markdown

@glennawatson
glennawatson merged commit 053873c into main Sep 26, 2026
20 checks passed
@glennawatson
glennawatson deleted the feat/explain-generation-fallback branch September 26, 2026 07:34
@github-actions

Copy link
Copy Markdown

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.

@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Oct 11, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

⌂ 换网址