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 db5afdc
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
+25-11Lines changed: 25 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,13 @@
1
1
---
2
2
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.
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, 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
11
11
`CompletableFuture<List<Try<Payload>>>`. If the schema build accepts it, then graphql-java must get
12
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.
@@ -74,12 +74,26 @@ as `-Dunwrapping.args`, and prints the report. On a failure it also prints the p
74
74
| 0 |`PASS`, or `PASS apart from the known findings above`|
75
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 |
76
76
| 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`|
78
78
79
79
Options: `--depth N`, `--budget N`, `--property-budget N`, `--show N` (counterexamples and stale return types printed, default 15), and `--rejected`, which lists
80
80
every combination the schema build rejected, with the build's error. A depth below 3 can't build the `mustAccept`
81
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.
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.
83
97
84
98
## Reading a counterexample
85
99
@@ -147,15 +161,15 @@ or delete it when none fail, so that a regression shows up as `FAIL`.
147
161
and DataLoader futures.
148
162
- Lists of more than 2 elements, more than 2 non-default choices per value, more than 3 containers, and completion
149
163
orders other than the two listed. A pass says nothing beyond those bounds.
150
-
- Which return types the schema build should reject. The check only exercises what the build accepts. With no known
151
-
findings, a return type the build stops accepting fails the check only when it's in `mustAccept`, so after a change
152
-
to the build or to a resolver's `createDataFetcher`, diff `--rejected` output against the last commit.
153
-
- Untyped Maps, whose value type is `Object`, properties with a getter (those run as methods), and properties and Maps on
154
-
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.
155
169
156
170
## Coverage and sync
157
171
158
-
Last confirmed to describe the code at commit `63c1fa6e` (2026-11-05). It covers:
172
+
Last confirmed to describe the code at commit `5ce3d1db` (2026-11-05). It covers:
159
173
160
174
| File | What |
161
175
|---|---|
@@ -168,7 +182,7 @@ Last confirmed to describe the code at commit `63c1fa6e` (2026-11-05). It covers
Copy file name to clipboardExpand all lines: AGENTS.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -91,9 +91,9 @@ happening. "docs only" means nothing does yet, so the rule depends on you readin
91
91
92
92
| Rule | Enforced by |
93
93
|---|---|
94
-
| The value of a resolver method, a public field 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 |
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 |
95
95
| 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`, 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 any value that differs fails the build |
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 |
97
97
| One output has one builder. Don't add a second path that builds the same thing | docs only |
98
98
| 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 |
99
99
| Every kind of SDL type starts its graphql-java type from the same recipe |`MergedType.prepare`, `DefinitionsBoundaryTest` and `TypeKindRecipeTest`|
0 commit comments