@RenderedValue function declared outside the test class (object/top-level) renders the call text, not the value

[paul-brooks]

Symptom

A @RenderedValue function declared outside the test class — an extension function in an object, or a top-level function — renders the call words in the report sentence instead of being replaced by the function's return value. No exception is thrown. A member function/extension declared in the test class works fine.

Repro

object Helpers { @RenderedValue fun KensaTest.foo(p: String) = "x-$p" }, used with(Helpers) { given(somethingWith(foo("a"))) }. Sentence renders something with foo a instead of something with x-a.

Root cause

The compiler plugin captures the value for @RenderedValue functions regardless of where they're declared, but the parser only classifies a call as @RenderedValue if the function is found by reflecting findAllRelatedClasses → MethodParser.prepareMethods() (core/.../parse/MethodParser.kt:158,84). That set is the test class + @Sources classes + super/interfaces, gated by sourceCode.existsFor. An externally-declared function isn't in it, so no rendered-value token is emitted, the captured value is never looked up, and the call renders as prose.

@Sources(Helpers::class) is the intended way to widen the set but currently does not rescue this case: SourceCode.loadCharStream derives the source path from the class FQN (dev/kensa/example/Helpers.kt), so when the object/class lives in a differently-named file its source isn't found, existsFor returns false, and findAllRelatedClasses drops it (Reflect.kt:73,76).

Fix direction

• Preferred: let classification consult the captured-invocation set (works for any declaration location, no @Sources needed).
• Or: discover @RenderedValue methods from @Sources classes reflectively, without gating that discovery on source availability.

Only member @RenderedValue functions/extensions are currently tested.

[paul-brooks]

Update — narrowed after testing

@Sources does make this work, for the normal case. Verified: an object declaring @RenderedValue fun KensaTest.foo(...), placed in its own file (RenderHelpers.kt), referenced via @Sources(RenderHelpers::class) on the test → the value renders correctly. So the intended dev fix is simply add @Sources (this is the familiar mechanism).

So this is not a parser-classification rewrite. The remaining genuine gaps are narrower:

1. No regression coverage — @Sources-pulled @RenderedValue from an object/external class isn't tested, which is how it silently regressed/confused. Add a test.
2. Silent failure when @Sources is missing (or source unresolvable) — the value is captured but renders as call words, with no warning. Should diagnose (see the missing-plugin-diagnostic idea; same "captured but not rendered" principle, here suggesting @Sources).
3. Edge case: @Sources does NOT work when the referenced declaration shares a file with a differently-named class (SourceCode.loadCharStream derives the path from the class FQN → existsFor fails). Narrow; possibly document as a limitation rather than fix.
4. Docs: externally-declared @RenderedValue functions require @Sources — document explicitly.

Decision (per maintainer): keep the @Sources model. Fix = regression test + diagnostic + docs (+ optionally the same-file edge).

[paul-brooks]

Reproduced — precise root cause (with maintainer's real test)

The actual failing case is a chained call on a parameterised @RenderedValue method, e.g.:

object RenderedValues { @RenderedValue fun KensaTest.productFor(p: ProvideType) = ... }
// in a sentence:
aProduct withValue productFor(provideType).stringValue

With @Sources(RenderedValues::class), productFor enters the parser's method set, and the chained reference (.stringValue) is classified as Method (ParseContext.asChainedCall/callTypeFor, :54,69). At render, asMethodValue (TokenRenderer.kt:206) → MethodElementDescriptor.resolveValue → Method.resolveFrom (ElementDescriptor.kt:47-50) reflectively invokes the method with 0 args. The method needs 2 (extension receiver + param) → IllegalArgumentException: wrong number of arguments: 0 expected: 2 → caught → returns null → the chain renders as words (product for <arg> string value). The compiler-plugin captured value is never consulted.

Reproduced verbatim (tokens ['Given','something with','null','baz','string value'], same exception in stderr). Non-chained productFor(x) takes the captured-value path (asRenderedValueMethodExpression) and renders correctly — only the chained/bare form breaks.

Fix

@RenderedValue methods (especially with parameters) must resolve via the captured value (RenderedValueInvocationContext.nextInvocationFor), not reflective invocation, in the MethodValue/chained path — then apply the chained path (.stringValue) to that value. Defensive: Method.resolveFrom must never reflectively invoke a method with parameters (hasParameters already exists at ElementDescriptor.kt:82, unused).

This supersedes the earlier "not discovered" framing: @Sources is needed and works for the non-chained case; the chained case is a distinct reflective-resolution bug.

[paul-brooks]

Follow-up doc task — exact requirements for @Sources classes/objects

For a class/object's @RenderedValue (and @ExpandableSentence) functions to be recognised when referenced from a test, ALL of these must hold (discovered during this investigation — to be documented on kensa.dev):

1. Referenced — the class/object is listed in @Sources(X::class) on the test, OR is a superclass/interface of the test (those are followed automatically by findAllRelatedClasses).
2. Source resolvable — Kensa derives the source path from the class FQN (com/example/X.kt, SourceCode.loadCharStream), so the declaration must live in its own file named after the class, within sourceLocations. A declaration that shares a file with a differently-named class (e.g. a helper object inside a test's .kt) is NOT found → silently dropped. (This is the same-file edge case; document it as a limitation.)
3. In sourceLocations — the source dir is in the configured sourceLocations.
4. Instrumented — the declaration is in a source set the Kensa compiler plugin is applied to (required for @RenderedValue value capture). If a customised gradle source-set list omits it, capture won't happen.

Document on kensa.dev (alongside @Sources / @RenderedValue docs) after the #149/#150 fixes land.