feat(graphql): validate a caller-supplied select locally before invoking

graphql-js is already a runtime dependency, so parse-check the assembled
operation when a `select` is provided and fail fast with a
`graphql_invalid_selection` error instead of building a request. This rejects a
malformed selection (and any attempt to break out of the field's selection set)
with a precise local error, and never reaches the network for those.

Field- and argument-level validity stays with the upstream server (which returns
verbatim errors): a local GraphQLSchema would need a full introspection
snapshot, but the stored snapshot is the plugin's reduced shape, which
buildClientSchema cannot consume.

The select-to-operation assembly is extracted to a shared
`effectiveOperationString` so the validated string and the sent string are
identical.

Author: RhysSullivan

packages/plugins/graphql/src/sdk/invoke.ts

@@ -21,6 +21,25 @@ export const endpointForTelemetry = (endpoint: string): string => {
   return url.toString();
 };
 
+/** The operation string to send for a call. A caller-supplied `select` overrides
+ *  the default scalar-leaf selection: it is spliced into the field's selection
+ *  set (`field { <select> }`) so nested/list data can be requested per call. Falls
+ *  back to the stored default operation when `select` is absent or the binding
+ *  predates the prefix/suffix split. `select` is a control input, never a GraphQL
+ *  variable. Shared with plugin.invokeTool so the validated string matches the
+ *  sent string exactly. */
+export const effectiveOperationString = (
+  operation: OperationBinding,
+  args: Record<string, unknown>,
+): string => {
+  const customSelect = typeof args.select === "string" ? args.select.trim() : "";
+  return customSelect.length > 0 &&
+    operation.operationPrefix != null &&
+    operation.operationSuffix != null
+    ? `${operation.operationPrefix} { ${customSelect} }${operation.operationSuffix}`
+    : operation.operationString;
+};
+
 // ---------------------------------------------------------------------------
 // Response helpers
 // ---------------------------------------------------------------------------
@@ -71,18 +90,10 @@ export const invoke = Effect.fn("GraphQL.invoke")(function* (
     Object.assign(variables, args.variables);
   }
 
-  // A caller-supplied `select` overrides the default scalar-leaf selection: it is
-  // spliced into the field's selection set so nested/list data can be requested
-  // per call. `select` is a control input, not a GraphQL variable, so it never
-  // enters `variables`. Falls back to the stored default operation when absent or
-  // when the binding predates the prefix/suffix split.
-  const customSelect = typeof args.select === "string" ? args.select.trim() : "";
-  const operationString =
-    customSelect.length > 0 &&
-    operation.operationPrefix != null &&
-    operation.operationSuffix != null
-      ? `${operation.operationPrefix} { ${customSelect} }${operation.operationSuffix}`
-      : operation.operationString;
+  // `select` (a control input, not a GraphQL variable) is applied here and never
+  // enters `variables`. plugin.invokeTool validates this same string before we
+  // reach the network.
+  const operationString = effectiveOperationString(operation, args);
 
   let request = HttpClientRequest.post(requestEndpoint).pipe(
     HttpClientRequest.setHeader("Content-Type", "application/json"),

packages/plugins/graphql/src/sdk/plugin.test.ts

@@ -991,4 +991,27 @@ describe("graphqlPlugin generates valid operations against rich schemas (#1146)"
       });
     }),
   );
+
+  it.effect("rejects a malformed `select` locally, before any network call", () =>
+    Effect.gen(function* () {
+      const { server, executor } = yield* setup("gitlab_syntax");
+      // Warm the binding cache (the first invoke introspects to materialize
+      // bindings) so the malformed call below has no legitimate reason to hit the
+      // wire: if it does, validation failed to short-circuit.
+      yield* executor.execute(toolAddr("gitlab_syntax", "main", "query.currentUser"), {});
+      yield* server.clearRequests;
+
+      const result = yield* executor.execute(
+        toolAddr("gitlab_syntax", "main", "query.currentUser"),
+        { select: "active mergeRequests { nodes {" },
+      );
+
+      expect(result).toMatchObject({
+        ok: false,
+        error: { code: "graphql_invalid_selection" },
+      });
+      // Parse-check happens before the request is built, so nothing reached the server.
+      expect((yield* server.requests).length).toBe(0);
+    }),
+  );
 });

packages/plugins/graphql/src/sdk/plugin.ts

@@ -47,7 +47,8 @@ import {
   GraphqlIntrospectionError,
   GraphqlInvocationError,
 } from "./errors";
-import { invokeWithLayer } from "./invoke";
+import { effectiveOperationString, invokeWithLayer } from "./invoke";
+import { validateOperationString } from "./validate-selection";
 import { graphqlPresets } from "./presets";
 import { makeDefaultGraphqlStore, type GraphqlStore, type StoredOperation } from "./store";
 import {
@@ -1046,6 +1047,27 @@ export const graphqlPlugin = definePlugin((options?: GraphqlPluginOptions) => {
           });
         }
 
+        // Parse-check a caller-supplied `select` locally, before any network
+        // call: reject a malformed selection (and any attempt to break out of the
+        // field's selection set) with a precise error instead of a confusing
+        // server response. Field- and argument-level validity is left to the
+        // server, which returns verbatim errors.
+        const selectArg = (args as Record<string, unknown> | undefined)?.select;
+        if (typeof selectArg === "string" && selectArg.trim().length > 0) {
+          const operationString = effectiveOperationString(
+            op.binding,
+            (args ?? {}) as Record<string, unknown>,
+          );
+          const selectionErrors = validateOperationString(operationString);
+          if (selectionErrors.length > 0) {
+            return ToolResult.fail({
+              code: "graphql_invalid_selection",
+              message: selectionErrors[0]!,
+              details: { errors: selectionErrors },
+            });
+          }
+        }
+
         const headers: Record<string, string> = { ...(config.headers ?? {}) };
         const queryParams: Record<string, string> = {
           ...(config.queryParams ?? {}),

packages/plugins/graphql/src/sdk/validate-selection.ts

@@ -0,0 +1,22 @@
+import { parse } from "graphql";
+
+// Local validation for a caller-supplied `select` (see invoke / plugin.invokeTool).
+// graphql-js is already a runtime dependency of this plugin, so we reuse its
+// parser to reject a malformed selection before any network round trip, and to
+// catch any attempt to break out of the field's selection set (the spliced text
+// must parse as part of a single operation). Field- and argument-level validity
+// is left to the upstream server, which returns verbatim errors: building a local
+// GraphQLSchema would need a full introspection snapshot, but the stored snapshot
+// is a reduced shape (see introspect.ts) that buildClientSchema cannot consume.
+
+/** Parse-check an assembled operation string. Returns a one-element error array
+ *  when the selection is not valid GraphQL, or an empty array when it parses. */
+export const validateOperationString = (operationString: string): readonly string[] => {
+  // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: graphql `parse` throws on a syntax error; the thrown value is reported generically (its message is not extracted, per the typed-error lint rules)
+  try {
+    parse(operationString);
+    return [];
+  } catch {
+    return ["`select` is not a valid GraphQL selection set"];
+  }
+};