[devmotion]

Fixes #314, fixes #315, fixes #319, fixes #320.

@grad_from_chainrules reuses the imported signature's argument list in value positions — both in the forwarding call to ReverseDiff.track and in the args = (...) tuple. A type annotation means something different there, so several signature shapes were broken:

Shape	Symptom
f(x::TrackedArray, ys::T...)	TypeError: expected T, got a value of type Tuple{T, T} — the collected varargs are asserted against the element type. Also hit with zero varargs (Tuple{}).
f(x::TrackedArray, ys::T...)	T was never escaped, so it resolved in ReverseDiff's scope: UndefVarError for any user-defined type (#319).
f(x::TrackedArray, y::Int = 2)	The default made it into call position, where track(f, x, y = 2) passes y as a keyword argument.
f(x::TrackedArray; k = 1)	_make_fwd_args rewrote the :parameters expression in place, and all three argument lists share it, so the declared defaults were dropped.

Only untyped args... — the one form the tests covered — was unaffected.

Approach

The macro now builds the generated argument lists directly from MacroTools.splitdef/splitarg/combinearg, and _make_fwd_args is removed. The forwarding call and the args tuple use argument names only.

Everything user-supplied in the signature is escaped — the function, where parameters, argument names, types and defaults — while the macro's own locals rely on standard hygiene. So a user argument named kwargs, args or back cannot clash with them. Because escaped argument names could shadow an escaped reference to the function in a method body, both generated definitions bind the function through its type instead ((func::_selftype(f))(...), track(func::_selftype(f), ...)). _selftype returns Type{T} for a type T and typeof(f) otherwise, like ChainRulesCore's helper of the same name: typeof would give DataType for constructors, and Core.Typeof is renamed in Julia 1.14.

Also in here

• where clauses are supported (@grad_from_chainrules does not support where clauses #320). The escaped static parameters are attached to the generated definitions. Works whether the parameter appears in the tracked argument (x::TrackedArray{V}), only in an untracked one (y::AbstractVector{V}), only in an argument with a default (y::V = 2), only in a keyword argument (k::V = 1), carries a bound (V <: Real), or is used only in the bound of another parameter (where {T, S <: TrackedArray{T}}). track and the special_*_exec! methods only see positional types, so they get only the parameters that positional types refer to, directly or through bounds; otherwise Julia warns about unused type variables.
• A pullback returning the wrong number of tangents now throws (@grad/@grad_from_chainrules silently reuse a tangent if a pullback returns too few tangents #315). The old @assert input_derivs isa Tuple only checked the type, and tuple broadcasting silently expands a length-1 tuple across every argument — so a pullback returning too few tangents assigned its first tangent to every argument. The same check now applies to @grad. For rrule pullbacks the expected length includes the tangent of the function itself.
• Zero tangents for tracked arguments no longer error (Zero tangents (NoTangent, ZeroTangent, nothing) for tracked arguments throw a MethodError in @grad/@grad_from_chainrules #314). NoTangent()/ZeroTangent() from an rrule and nothing from a @grad pullback reached increment_deriv!, which has no method for them. They are now no-ops.
• Constructors get their own special instructions (related to Custom rules collide with ReverseDiff's own SpecialInstructions for the same function #316). For a type, SpecialInstruction's function parameter was DataType, so the special_*_exec! methods of two constructors with the same positional signature overwrote each other — an error during package precompilation. _SpecialInstruction now uses _selftype(func), and both macros dispatch on SpecialInstruction{_selftype(f)}. @grad also uses _selftype for its track method, so it works for constructors too. No built-in instruction records a type, so only user rules are affected.
• Signatures without positional arguments are rejected. Keyword arguments do not take part in dispatch, so @grad_from_chainrules f(; k::TrackedArray) replaced the original f(; k), and the rrule then recursed into it.
• The docstring documents that overlapping imported signatures need the fully tracked combination imported too, or the generated special_*_exec! methods are ambiguous.

Note for reviewers

The f_vararg and f_kw rrules in test/ChainRulesTests.jl returned two tangents for four arguments and passed only because the varargs were untracked Ints that hit the _add_to_deriv!(d1, d2) = nothing fallback. They now return the missing NoTangent()s. That was a latent wrong-gradient bug, not a regression from this PR.

The stricter length check is a behaviour change for rules that return short tangent tuples: they now error instead of being silently broadcast. @grad is not public API, but it is used downstream, so I checked the @grad rules in the registered packages GitHub code search finds using it (Tullio, DiffEqBase, NonlinearSolveBase, SimpleNonlinearSolve, Bijectors, SphericalFunctions, ADEV): all of them return one tangent per argument.

@grad with qualified names (#318) is out of scope here and left for a follow-up that moves @grad to the same approach.

Tests

New cases in test/ChainRulesTests.jl:

• typed varargs with a user type (zero and two varargs)
• pullbacks returning too few tangents or a non-tuple, for both macros
• keyword defaults (the rrule uses a different default, so a dropped signature default is visible)
• positional defaults
• zero tangents for tracked arrays and scalars, including nothing from @grad
• where clauses in six shapes, with @test_nowarn for the unused type variable warnings
• constructors (Doubled(x::TrackedArray)), including a second constructor with the same signature (no method overwrite), a @grad constructor, and that constructors of other types are unaffected
• qualified function names
• argument names that coincide with the function or with internal names
• invalid signatures, including keyword-only ones, with their error messages

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.40%. Comparing base (608569b) to head (561dd59).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #328      +/-   ##
==========================================
+ Coverage   94.32%   94.40%   +0.08%     
==========================================
  Files          19       19              
  Lines        1710     1735      +25     
==========================================
+ Hits         1613     1638      +25     
  Misses         97       97              

☔ 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.