Skip to content

Commit 9f19805

Browse files
authored
Merge pull request #953 from graphql-java-kickstart/agent-friendly-p11-property-map-unwrap
Unwrap property and Map field values like method values
2 parents 7ba7db9 + db5afdc commit 9f19805

10 files changed

Lines changed: 163 additions & 101 deletions

File tree

‎.claude/skills/verify-return-value-unwrapping/SKILL.md‎

Lines changed: 29 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
---
22
name: verify-return-value-unwrapping
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 TypeShape (the type walk, ContainerKind, the generic wrapper rules or the Unwrapper), 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.
3+
description: Exhaustively check, up to a bound, that the value of a resolver method, a field with no matching getter or a 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 TypeShape (the type walk, ContainerKind, the generic wrapper rules or the Unwrapper), 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.
44
---
55

66
# Verify return value unwrapping
77

88
## The property
99

10-
A user writes a resolver method, a public field or a `Map` whose type nests containers, such as
10+
A user writes a resolver method, a field with no matching getter (of any visibility) or a `Map` whose type nests containers, such as
1111
`CompletableFuture<List<Try<Payload>>>`. If the schema build accepts it, then graphql-java must get
1212
exactly the value it returned, with every container removed. Futures are waited on and generic wrappers go
1313
through their transformers. List order and nulls are kept. A failed future or a throwing transformer fails the field.
@@ -74,12 +74,26 @@ as `-Dunwrapping.args`, and prints the report. On a failure it also prints the p
7474
| 0 | `PASS`, or `PASS apart from the known findings above` |
7575
| 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 |
7676
| 2 | `MODEL ERROR`: the checkout or the check didn't compile, the build rejected a return type the check must exercise, or a `ContainerKind` in `TypeShape.kt` has no `Container` in `Check.java`, so a pass would prove nothing |
77-
| 3 | `STALE`: a known finding matches a return type that no longer fails, or fewer accepted return types than its line records |
77+
| 3 | `STALE`: a known finding matches a return type that no longer fails, or fewer accepted return types than its line records. Or the run's coverage differs from `pinnedCoverage` in `Check.java` |
7878

7979
Options: `--depth N`, `--budget N`, `--property-budget N`, `--show N` (counterexamples and stale return types printed, default 15), and `--rejected`, which lists
8080
every combination the schema build rejected, with the build's error. A depth below 3 can't build the `mustAccept`
8181
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.
82+
counts in `known-findings.txt` and `pinnedCoverage` are for those. A run with other bounds checks values only.
83+
84+
## Pinned coverage
85+
86+
`pinnedCoverage` in `Check.java` records how many return types the check generates, and for each kind how many of them
87+
the schema build rejects and how many executions run. A run at the default bounds whose counts differ is `STALE`, and the
88+
report prints the pinned and the new counts. Without the pin, a change that makes the build reject more return types,
89+
skips generating some shapes, or runs fewer values per return type would still print `PASS`, because nothing it stopped
90+
running can fail.
91+
92+
When the counts move, diff `--rejected` output against the last commit to see which return types the build now rejects
93+
or accepts, and confirm the change is intended. A change to `Check.java` itself moves the counts with no change in
94+
`--rejected`. Then copy the counts the report prints into `pinnedCoverage` in the same diff, so a reviewer sees what the
95+
check stopped or started covering. A change that rejects one return type and accepts another of the same kind, with the
96+
same number of executions, keeps the counts and gets past the pin.
8397

8498
## Reading a counterexample
8599

@@ -107,8 +121,8 @@ A real bug versus a modeling error:
107121
- **Modeling error.** The check's own idea of the value is wrong. For example, a new container variant builds a value
108122
that its declared type doesn't allow, or the error message the check expects for a `FutureTask` (in `build`, case
109123
`FUTURE_TASK`) differs from a message the library changed on purpose. Confirm against the library's own tests in
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`.
124+
`src/test/kotlin/graphql/kickstart/tools/NestedGenericWrapperTest.kt` before you edit the check. A property fails a
125+
`FutureTask` as a `Resolver field` and a Map as a `Resolver map value`, each naming the generated class and `field`.
112126
- **`MODEL ERROR` about rejected return types.** A change made the build reject a return type in `mustAccept` in
113127
`Check.java`. That's either a regression in the build, which you report, or an intended change, after which you swap in
114128
another accepted return type of the same kind.
@@ -126,12 +140,8 @@ regression in a fixed return type is a `FAIL`. A count that grows makes it `NEW`
126140
reject now fails under the line. What stays hidden is a known return type that starts failing in a different way, so
127141
after a change to the code a known finding covers, read its counterexample.
128142

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.
143+
At the sync commit the file is empty. Methods, properties and typed Maps unwrap their values through the same
144+
`TypeShape.Unwrapper`, and every return type the build accepts passes.
135145

136146
The check found two method bugs when it was written, and both are fixed. One was a `DataFetcherResult` inside an
137147
`Optional` (#939). The other was a wrapper whose transformer returns a future, directly around a declared future (#938). A
@@ -151,13 +161,15 @@ or delete it when none fail, so that a regression shows up as `FAIL`.
151161
and DataLoader futures.
152162
- Lists of more than 2 elements, more than 2 non-default choices per value, more than 3 containers, and completion
153163
orders other than the two listed. A pass says nothing beyond those bounds.
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.
164+
- Which return types the schema build should reject. The check only exercises what the build accepts. A change in how
165+
many it rejects fails through `pinnedCoverage`, but the check doesn't judge whether the new count is right.
166+
- Untyped Maps, whose value type is `Object`, properties with a getter (those run as methods), non-public fields (the
167+
generated ones are public, and the same data fetcher reads private ones), and properties and Maps on a type below the
168+
root other than `Holder`. `ResolverCompatibilityTest` pins untyped Maps and Kotlin `@JvmField`s.
157169

158170
## Coverage and sync
159171

160-
Last confirmed to describe the code at commit `6d41328d` (2026-11-05). It covers:
172+
Last confirmed to describe the code at commit `5ce3d1db` (2026-11-05). It covers:
161173

162174
| File | What |
163175
|---|---|
@@ -170,7 +182,7 @@ Last confirmed to describe the code at commit `6d41328d` (2026-11-05). It covers
170182
To see whether a change needs another look:
171183

172184
```bash
173-
git log --oneline 6d41328d..HEAD -- src/main/kotlin/graphql/kickstart/tools/resolver/TypeShape.kt src/main/kotlin/graphql/kickstart/tools/resolver/MethodFieldResolver.kt src/main/kotlin/graphql/kickstart/tools/SchemaParserOptions.kt src/main/kotlin/graphql/kickstart/tools/resolver/PropertyFieldResolver.kt src/main/kotlin/graphql/kickstart/tools/resolver/MapFieldResolver.kt
185+
git log --oneline 5ce3d1db..HEAD -- src/main/kotlin/graphql/kickstart/tools/resolver/TypeShape.kt src/main/kotlin/graphql/kickstart/tools/resolver/MethodFieldResolver.kt src/main/kotlin/graphql/kickstart/tools/SchemaParserOptions.kt src/main/kotlin/graphql/kickstart/tools/resolver/PropertyFieldResolver.kt src/main/kotlin/graphql/kickstart/tools/resolver/MapFieldResolver.kt
174186
```
175187

176188
Move the sync commit forward only after you've read those changes and confirmed that the containers, variants and

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,9 @@ happening. "docs only" means nothing does yet, so the rule depends on you readin
9191

9292
| Rule | Enforced by |
9393
|---|---|
94-
| A resolver method's return value is unwrapped by one rule that the schema build and the data fetcher share | `TypeShape`, whose one walk yields both the class the schema build matches and the layers the data fetcher unwraps. A container kind can't be added without its placement rule and its value step, since both are abstract on the enum, and `ReturnValueUnwrappingTest` fails until the bounded check builds values for it |
94+
| The value of a resolver method, a field with no matching getter or a typed Map is unwrapped by one rule that the schema build and the data fetcher share | `TypeShape`, whose one walk yields both the class the schema build matches and the layers that `TypeShape.Unwrapper` unwraps in the method, field and Map data fetchers. An untyped Map's values reach graphql-java as they are. A container kind can't be added without its placement rule and its value step, since both are abstract on the enum, and `ReturnValueUnwrappingTest` fails until the bounded check builds values for it |
9595
| A resolver method's parameter layout, type variables and source are decided once, at schema build | docs only |
96-
| 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 |
96+
| A change to how resolvers are found, bound or unwrapped keeps what a method, a property and a Map field return | `ResolverCompatibilityTest`, which compares field and Map values with a method's, and the bounded check in `ReturnValueUnwrappingTest`, which compares all three with the plain value. Neither has known findings, so a value that differs on a return type they run fails the build. The bounded check also pins how many return types it generates, and for each kind how many the build rejects and how many executions run, so a change that stops running some fails until the same diff updates `pinnedCoverage`. It doesn't judge whether a newly rejected return type should build |
9797
| One output has one builder. Don't add a second path that builds the same thing | docs only |
9898
| Read an SDL type's members merged with its extensions, never from the raw definition | `MergedType` in `MergedDefinitions.kt` and `DefinitionsBoundaryTest`, which fails on a raw member, directive or child-node read, an extension class, an SDL node walk or a `TypeDefinitionRegistry` call outside it. A read by reflection gets past it |
9999
| Every kind of SDL type starts its graphql-java type from the same recipe | `MergedType.prepare`, `DefinitionsBoundaryTest` and `TypeKindRecipeTest` |

‎src/main/kotlin/graphql/kickstart/tools/resolver/MapFieldResolver.kt‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import com.fasterxml.classmate.TypeResolver
44
import graphql.kickstart.tools.ScanDictionary
55
import graphql.kickstart.tools.SchemaParserOptions
66
import graphql.kickstart.tools.util.JavaType
7+
import graphql.kickstart.tools.util.unwrap
78
import graphql.language.FieldDefinition
89
import graphql.schema.DataFetcher
910
import graphql.schema.DataFetchingEnvironment
@@ -23,7 +24,7 @@ internal class MapFieldResolver(
2324
mapClass: JavaType
2425
) : FieldResolver(field, search, options) {
2526

26-
private var mapGenericValue: JavaType = getMapGenericType(mapClass)
27+
private val mapGenericValue: JavaType = getMapGenericType(mapClass)
2728

2829
/**
2930
* Takes a type which implements Map and tries to find the
@@ -38,25 +39,32 @@ internal class MapFieldResolver(
3839
return typeParameters.elementAtOrElse(1) { Any::class.java }
3940
}
4041

41-
override fun createDataFetcher(): DataFetcher<*> {
42-
return MapFieldResolverDataFetcher(createSourceResolver(), field.name)
42+
private val returnShape by lazy {
43+
TypeShape.returnType(field.type, mapGenericValue, search.isSubscription, search.type, options, ScanDictionary.FieldTypeReference(field.name))
4344
}
4445

45-
override fun scanForMatches(): Sequence<TypeShape> {
46-
return sequenceOf(TypeShape.returnType(field.type, mapGenericValue, isSubscription = false, search.type, options, ScanDictionary.FieldTypeReference(field.name)))
46+
private val hasTypedValues get() = resolveTypeVariables(mapGenericValue, search.type) != Any::class.java
47+
48+
override fun createDataFetcher(): DataFetcher<*> {
49+
val unwrapper = if (hasTypedValues) TypeShape.Unwrapper(returnShape, ResolverKind.MAP_VALUE, "${search.type.unwrap().name}.${field.name}") else null
50+
return MapFieldResolverDataFetcher(createSourceResolver(), field.name, unwrapper)
4751
}
4852

53+
override fun scanForMatches(): Sequence<TypeShape> = sequenceOf(returnShape)
54+
4955
override fun toString() = "MapFieldResolver{key=${field.name}}"
5056
}
5157

5258
internal class MapFieldResolverDataFetcher(
5359
private val sourceResolver: SourceResolver,
54-
private val key: String
60+
private val key: String,
61+
private val unwrapper: TypeShape.Unwrapper?
5562
) : LightDataFetcher<Any> {
5663

5764
override fun get(fieldDefinition: GraphQLFieldDefinition, sourceObject: Any?, environmentSupplier: Supplier<DataFetchingEnvironment>): Any? {
5865
if (sourceObject is Map<*, *>) {
59-
return sourceObject[key]
66+
val value = sourceObject[key]
67+
return if (value == null || unwrapper == null) value else unwrapper.unwrap(value, environmentSupplier)
6068
} else {
6169
throw RuntimeException("MapFieldResolver attempt to fetch a field from an object instance that was not a map")
6270
}

‎src/main/kotlin/graphql/kickstart/tools/resolver/MethodFieldResolver.kt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ internal class MethodFieldResolver(
114114
}
115115
}
116116

117-
val unwrapper = TypeShape.Unwrapper(returnShape, method, isSuspendFunction)
117+
val unwrapper = TypeShape.Unwrapper(returnShape, ResolverKind.METHOD, "${method.declaringClass.name}.${method.name}", isSuspendFunction)
118118

119119
return if (numberOfParameters > 0 || isSuspendFunction) {
120120
// requires arguments and environment or is a suspend function

‎src/main/kotlin/graphql/kickstart/tools/resolver/PropertyFieldResolver.kt‎

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -20,33 +20,28 @@ internal class PropertyFieldResolver(
2020
val property: Field
2121
) : FieldResolver(field, search, options) {
2222

23-
override fun createDataFetcher(): DataFetcher<*> {
24-
return PropertyFieldResolverDataFetcher(createSourceResolver(), property)
23+
private val returnShape by lazy {
24+
TypeShape.returnType(field.type, property.genericType, search.isSubscription, search.type, options, ScanDictionary.FieldTypeReference(property.toString()))
2525
}
2626

27-
override fun scanForMatches(): Sequence<TypeShape> {
28-
return sequenceOf(
29-
TypeShape.returnType(
30-
field.type,
31-
property.genericType,
32-
isSubscription = false,
33-
search.type,
34-
options,
35-
ScanDictionary.FieldTypeReference(property.toString())
36-
)
37-
)
27+
override fun createDataFetcher(): DataFetcher<*> {
28+
val unwrapper = TypeShape.Unwrapper(returnShape, ResolverKind.FIELD, "${property.declaringClass.name}.${property.name}")
29+
return PropertyFieldResolverDataFetcher(createSourceResolver(), property, unwrapper)
3830
}
3931

32+
override fun scanForMatches(): Sequence<TypeShape> = sequenceOf(returnShape)
33+
4034
override fun toString() = "PropertyFieldResolver{property=$property}"
4135
}
4236

4337
internal class PropertyFieldResolverDataFetcher(
4438
private val sourceResolver: SourceResolver,
45-
private val field: Field
39+
private val field: Field,
40+
private val unwrapper: TypeShape.Unwrapper
4641
) : LightDataFetcher<Any> {
4742

4843
override fun get(fieldDefinition: GraphQLFieldDefinition, sourceObject: Any?, environmentSupplier: Supplier<DataFetchingEnvironment>): Any? {
49-
return field.get(sourceResolver.resolve(null, sourceObject))
44+
return field.get(sourceResolver.resolve(null, sourceObject))?.let { unwrapper.unwrap(it, environmentSupplier) }
5045
}
5146

5247
override fun get(environment: DataFetchingEnvironment): Any? {

0 commit comments

Comments
 (0)