You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit ff829e8
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: .claude/skills/verify-return-value-unwrapping/SKILL.md
+57-27Lines changed: 57 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,15 @@
1
1
---
2
2
name: verify-return-value-unwrapping
3
-
description: Exhaustively check, up to a bound, that a resolver method's return value reaches graphql-java fully unwrapped. Futures are awaited, generic wrappers are transformed, Optional and DataFetcherResult are handled, and list order, nulls and failures are kept, for every return type nested up to 3 containers deep. Use it before pushing any change to ReturnValueUnwrapper, TypeClassMatcher's unwrapping, GenericTypeResolver.resolve, the data fetchers in MethodFieldResolver, or the GenericWrapper defaults, and whenever a bug report says graphql-java got a CompletableFuture, Optional or wrapper object as a field value.
3
+
description: Exhaustively check, up to a bound, that the value of a resolver method, public field or typed Map reaches graphql-java fully unwrapped. Futures are awaited, generic wrappers are transformed, Optional and DataFetcherResult are handled, and list order, nulls and failures are kept, for every return type nested up to 3 containers deep. Use it before pushing any change to ReturnValueUnwrapper, TypeClassMatcher's unwrapping, GenericTypeResolver.resolve, the data fetchers in MethodFieldResolver, PropertyFieldResolver or MapFieldResolver, or the GenericWrapper defaults, and whenever a bug report says graphql-java got a CompletableFuture, Optional or wrapper object as a field value.
4
4
---
5
5
6
6
# Verify return value unwrapping
7
7
8
8
## The property
9
9
10
-
A user writes a resolver method whose return type nests containers, such as
11
-
`CompletableFuture<List<Try<Payload>>>`. If the schema build accepts that method, then graphql-java must get
12
-
exactly the value the method returned, with every container removed. Futures are waited on and generic wrappers go
10
+
A user writes a resolver method, a public field or a `Map` whose type nests containers, such as
11
+
`CompletableFuture<List<Try<Payload>>>`. If the schema build accepts it, then graphql-java must get
12
+
exactly the value it returned, with every container removed. Futures are waited on and generic wrappers go
13
13
through their transformers. List order and nulls are kept. A failed future or a throwing transformer fails the field.
14
14
A `Future` that isn't a `CompletionStage` fails the field with the "can't wait on" error.
15
15
@@ -36,18 +36,27 @@ The leaf is `Payload` (an object type), `String`, or `Object` for a union `Item
36
36
implements `Future`, so only the declared type tells a leaf from a future. Each return type runs with an all-nullable
37
37
and an all-non-null GraphQL type.
38
38
39
-
For each combination the check compiles a Java resolver class with that return type at runtime. It builds the schema
40
-
through the public `SchemaParser` API, which rejects about a quarter of the combinations, such as `Optional` below the top
41
-
level. For every accepted one it executes the query once for each value that makes at most `--budget` (default 2)
42
-
non-default choices. When the return type holds futures, it runs each value three ways: futures already completed,
39
+
Each return type runs as three kinds of resolver, each compiled as a Java class at runtime:
40
+
41
+
| Kind | Generated resolver | Data fetcher |
42
+
|---|---|---|
43
+
|`method`|`public <type> field()` on the query resolver |`MethodFieldResolver`|
44
+
|`property`|`public <type> field;` on the query resolver, which is also what a Kotlin `@JvmField` compiles to |`PropertyFieldResolver`|
45
+
|`map`|`extends HashMap<String, <type>>`, bound to `type Holder` and returned by `Query.holder`|`MapFieldResolver`|
46
+
47
+
The check builds each schema through the public `SchemaParser` API, which rejects about a fifth of the combinations, such as
48
+
`Optional` below the top level. For every accepted one it executes the query once for each value that makes at most
49
+
`--budget` (default 2) non-default choices. Properties and Maps use `--property-budget` (default 1), only the nullable
50
+
GraphQL type and only the first-created-first completion order, because what they add is how the value is read, and the
51
+
methods already cover the rest. When the return type holds futures, it runs each value three ways: futures already completed,
43
52
and pending futures completed after the data fetcher returns, first-created first and last-created first.
44
53
45
54
The expected result is what graphql-java returns when a plain data fetcher on the same schema returns the plain value,
46
55
or throws the failure. So graphql-java's own null handling and error format apply to both sides. When one value
47
56
holds several failures, any one of them failing the field counts as correct.
48
57
49
58
`ReturnValueUnwrappingTest` compiles `Check.java` and `Fixtures.java` at test time and runs the check, so `mvn verify`
50
-
runs it at the default bounds on every build. About 172,000 executions run in about 15 seconds.
59
+
runs it at the default bounds on every build. About 226,000 executions run in about 18 seconds on JDK 17.
51
60
52
61
## Run
53
62
@@ -63,13 +72,14 @@ as `-Dunwrapping.args`, and prints the report. On a failure it also prints the p
63
72
| Exit | Meaning |
64
73
|---|---|
65
74
| 0 |`PASS`, or `PASS apart from the known findings above`|
66
-
| 1 |`FAIL`: a return type that isn't a known finding breaks the property |
75
+
| 1 |`FAIL`: a return type that isn't a known finding breaks the property. `NEW`: a known finding matches more accepted return types than its line records|
67
76
| 2 |`MODEL ERROR`: the checkout or the check didn't compile, or the build rejected a return type the check must exercise, so a pass would prove nothing |
68
-
| 3 |`STALE`: a known finding no longer fails. Delete its line from `known-findings.txt`|
77
+
| 3 |`STALE`: a known finding matches a return type that no longer fails, or fewer accepted return types than its line records|
69
78
70
-
Options: `--depth N`, `--budget N`, `--show N` (counterexamples printed, default 15), and `--rejected`, which lists
79
+
Options: `--depth N`, `--budget N`, `--property-budget N`, `--show N` (counterexamples and stale return types printed, default 15), and `--rejected`, which lists
71
80
every combination the schema build rejected, with the build's error. A depth below 3 can't build the `mustAccept`
72
-
return types, so it ends in `MODEL ERROR`.
81
+
return types, so it ends in `MODEL ERROR`. `NEW` and `STALE` apply only at the default depth and budgets, because the
82
+
counts in `known-findings.txt` are for those.
73
83
74
84
## Reading a counterexample
75
85
@@ -81,7 +91,8 @@ public List<Future<Payload>> field() for field: [Payload] (21 failing execut
81
91
got: {errors=[{message=Exception while fetching data (/field[1]/data) : Expected source object to be an instance of 'unwrapcheck.Fixtures$Payload' but instead got 'java.util.concurrent.FutureTask', ...
82
92
```
83
93
84
-
The first line is the resolver method and the field's GraphQL type. `returns` is the value the method returned.
94
+
The first line is the resolver and the field's GraphQL type. A property prints as `public List<Future<Payload>> field;`
95
+
and a Map as `extends HashMap<String, List<Future<Payload>>> for Holder.field: [Payload]`. `returns` is the value the method returned.
85
96
`Later(CompletableFuture(x))` means a `Later` whose transformer returns a `CompletableFuture` of `x`. Only the first
86
97
failing value per return type is shown. Rerun with a higher `--show` to see more return types.
87
98
@@ -96,24 +107,39 @@ A real bug versus a modeling error:
96
107
-**Modeling error.** The check's own idea of the value is wrong. For example, a new container variant builds a value
97
108
that its declared type doesn't allow, or the error message the check expects for a `FutureTask` (in `build`, case
98
109
`FUTURE_TASK`) differs from a message the library changed on purpose. Confirm against the library's own tests in
99
-
`src/test/kotlin/graphql/kickstart/tools/NestedGenericWrapperTest.kt` before you edit the check.
110
+
`src/test/kotlin/graphql/kickstart/tools/NestedGenericWrapperTest.kt` before you edit the check. Properties and Maps
111
+
are expected to fail a `FutureTask` with the method's wording, naming the generated class and `field`.
100
112
-**`MODEL ERROR` about rejected return types.** A change made the build reject a return type in `mustAccept` in
101
113
`Check.java`. That's either a regression in the build, which you report, or an intended change, after which you swap in
102
114
another accepted return type of the same kind.
103
115
104
116
## Known findings
105
117
106
118
`src/test/resources/returnvalue/known-findings.txt` lists the return types that break the property at the sync commit, one per line as
107
-
`<regex over the return type as the check prints it> # <what goes wrong>`. They still
108
-
print as `KNOWN` with a counterexample on every run, and the check passes apart from them. A new break inside a known
109
-
pattern is hidden, so after a change to the code a known finding covers, read its counterexample.
110
-
111
-
At the sync commit there are none. The check found two bugs when it was written, and both are fixed. One was a
112
-
`DataFetcherResult` inside an `Optional` (#939). The other was a wrapper whose transformer returns a future, directly around
113
-
a declared future (#938). A `withTransformer` registration keeps that #938 behavior, which is why `Later` is registered
114
-
through `withCompletionStageTransformer`.
115
-
116
-
When a fix lands, the check exits 3. Delete the line then, so that a regression shows up as `FAIL`.
119
+
`<count> <regex> # <what goes wrong>`. The regex is matched against the kind and the short return type, such as
120
+
`property List<CompletableFuture<String>>`, so a pattern without a kind covers all three. The first matching line wins.
121
+
Matching return types still print as `KNOWN` with a counterexample on every run, and the check passes apart from them.
122
+
123
+
Each line must match only return types that fail, and exactly `<count>` of the return types the build accepts. A
124
+
matched return type that passes makes the check `STALE` and names it, so a partial fix has to narrow the line, and a later
125
+
regression in a fixed return type is a `FAIL`. A count that grows makes it `NEW`, because a return type the build used to
126
+
reject now fails under the line. What stays hidden is a known return type that starts failing in a different way, so
127
+
after a change to the code a known finding covers, read its counterexample.
128
+
129
+
At the sync commit, methods have none. Properties and Maps hand their value to graphql-java as it is. graphql-java awaits
130
+
only a top-level `CompletionStage`, reads a `DataFetcherResult` at the top, inside that future and as a list element, and
131
+
unboxes any `Optional`, but not a `DataFetcherResult` inside one. So every nested future, every generic wrapper, a
132
+
`DataFetcherResult` inside an `Optional`, and a `FutureTask` behind a declared `Future` fail for them. The five lines
133
+
match exactly those 2,850 return types, and their counts add up to it. A String field gets the container's `toString`,
134
+
such as `CompletableFuture@5a7cb161[Completed normally]`, with no error.
135
+
136
+
The check found two method bugs when it was written, and both are fixed. One was a `DataFetcherResult` inside an
137
+
`Optional` (#939). The other was a wrapper whose transformer returns a future, directly around a declared future (#938). A
138
+
`withTransformer` registration keeps that #938 behavior, which is why `Later` is registered through
139
+
`withCompletionStageTransformer`.
140
+
141
+
When a fix lands, the check exits 3 and names the return types that pass. Narrow the line to the rest and set its count,
142
+
or delete it when none fail, so that a regression shows up as `FAIL`.
117
143
118
144
## What this does not cover
119
145
@@ -126,10 +152,12 @@ When a fix lands, the check exits 3. Delete the line then, so that a regression
126
152
- Lists of more than 2 elements, more than 2 non-default choices per value, more than 3 containers, and completion
127
153
orders other than the two listed. A pass says nothing beyond those bounds.
128
154
- Which return types the schema build should reject. The check only exercises what the build accepts.
155
+
- Untyped Maps, whose value type is `Object`, properties with a getter (those run as methods), and properties and Maps on
156
+
a type below the root other than `Holder`. `ResolverCompatibilityTest` pins untyped Maps and Kotlin `@JvmField`s.
129
157
130
158
## Coverage and sync
131
159
132
-
Last confirmed to describe the code at commit `cd3233ca` (master, 2026-10-30). It covers:
160
+
Last confirmed to describe the code at commit `af9ba4ad` (agent-friendly, 2026-11-04). It covers:
133
161
134
162
| File | What |
135
163
|---|---|
@@ -138,11 +166,13 @@ Last confirmed to describe the code at commit `cd3233ca` (master, 2026-10-30). I
Copy file name to clipboardExpand all lines: AGENTS.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -92,6 +92,7 @@ happening. "docs only" means nothing does yet, so the rule depends on you readin
92
92
|---|---|
93
93
| A resolver method's return value is unwrapped by one rule that the schema build and the data fetcher share | docs only |
94
94
| A resolver method's parameter layout, type variables and source are decided once, at schema build | docs only |
95
+
| A change to how resolvers are found, bound or unwrapped keeps what a method, a property and a Map field return |`ResolverCompatibilityTest` and the bounded check in `ReturnValueUnwrappingTest`. Each lists exactly today's property and Map gaps as known findings, and fails when one is fixed until it's removed, or when a new failure would hide under one |
95
96
| One output has one builder. Don't add a second path that builds the same thing | docs only |
96
97
| Read an SDL type's members merged with its extensions, never from the raw definition | docs only |
97
98
| Reuse an existing structure before you add a parallel one | docs only |
0 commit comments