@@ -99,6 +99,57 @@ They must extend `GraphQLOperation[S]`, defining the following members:
9999 }
100100```
101101
102+ #### Validating operations against the schema
103+
104+ Hand-written operations and subqueries (those defined manually, without the code generator) are
105+ validated against the schema by the ` GraphQLValidate ` rule, which reuses the same checks as the
106+ generator — no code generation involved. Any definition extending ` GraphQLOperation[S] ` /
107+ ` GraphQLOperation.Typed[S, ...] ` (checked via its ` document ` ) or ` GraphQLSubquery[S] ` /
108+ ` GraphQLSubquery.Typed[S, ...] ` (checked via its ` subquery ` ) is validated; fields, arguments,
109+ variables and deprecations that don't typecheck against schema ` S ` are reported as scalafix
110+ diagnostics. Operations that * are* generated (annotated with ` @GraphQL ` ) are validated during
111+ generation.
112+
113+ A subquery declares the GraphQL root type(s) its selection applies to with a
114+ ` @clue.annotation.GraphQLType ` annotation:
115+
116+ ``` scala
117+ @ GraphQLType (" Character"
118+ abstract class FriendFields extends GraphQLSubquery .Typed [StarWars , Json ] {
119+ val subquery = " { id name }"
120+ }
121+ ```
122+
123+ Hand-written subqueries may declare ** multiple** types (the selection is validated against each:
124+ ` @GraphQLType("Human", "Droid") ` ). A subquery processed by the generator (` @GraphQL ` ) must declare
125+ ** exactly one** type. ` @GraphQLType ` is only valid on a subquery, not on a ` GraphQLOperation ` .
126+
127+ The schema location is configured (once) in ` .scalafix.conf ` :
128+
129+ ``` hocon
130+ Clue.schemaDirs = ["path/to/schemas"]
131+ ```
132+
133+ ** With ` sbt-clue ` :** validation runs automatically ** on every compile** — the plugin enables
134+ scalafix's on-compile hook for the validation rule, so an invalid hand-written operation/subquery
135+ fails the build. ` <project>/clueCheck ` runs the same check on demand (e.g. in CI). The generator
136+ separately validates the annotated sources under ` src/clue/scala ` during generation. A
137+ ` @GraphQL ` /` @GraphQLSchema ` /` @GraphQLStub ` annotation found outside the clue source directory is
138+ reported as a ** warning** (those are only processed by the generator, so the annotation has no effect
139+ there). (Don't add ` rules = [GraphQLGen] ` to ` .scalafix.conf ` — a plain ` scalafixAll ` would then
140+ expand the annotated generator inputs in place.)
141+
142+ ** Without the plugin** (running scalafix directly), use the validation-only ` GraphQLValidate ` rule
143+ (it reads the same ` Clue ` config) and run ` scalafixAll ` / ` scalafixCheckAll ` :
144+
145+ ``` hocon
146+ rules = [GraphQLValidate]
147+ Clue.schemaDirs = ["path/to/schemas"]
148+ ```
149+
150+ A subquery with no ` @GraphQLType ` annotation has no declared root type, so it can't be validated —
151+ this is reported as a warning rather than silently skipped.
152+
102153### 3) Invoke operations
103154
104155#### Example
0 commit comments