feat: add structured GraphQL exception handling with GHGraphQLException

Introduce GHGraphQLException and GHGraphQLError to provide structured
access to GraphQL error responses, including type, path, locations, and
extensions fields per the GraphQL spec. This enables callers to
programmatically inspect errors rather than parsing exception messages.

Modeled after octokit/graphql.js's GraphqlResponseError pattern.

Author: mrzhao

src/main/java/org/kohsuke/github/GHGraphQLException.java

@@ -0,0 +1,105 @@
+package org.kohsuke.github;
+
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+import org.kohsuke.github.internal.graphql.response.GHGraphQLError;
+
+import java.util.Collections;
+import java.util.List;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
+
+/**
+ * Thrown when a GitHub GraphQL request returns a successful HTTP response whose body contains a non-empty
+ * {@code errors} array.
+ *
+ * <p>
+ * This exception preserves the structured error list so callers can branch on the error {@link GHGraphQLError#getType()
+ * type}, {@link GHGraphQLError#getPath() path}, and other fields. Partial response data is exposed through
+ * {@link #getResponseData()} and the originating query through {@link #getQuery()} to ease debugging.
+ * </p>
+ *
+ * <p>
+ * HTTP-level failures (4xx/5xx) do not surface as this exception; they continue to be reported as {@link HttpException}
+ * or its subclasses, since the response cannot be parsed as a GraphQL payload.
+ * </p>
+ *
+ * @see <a href="https://spec.graphql.org/October2021/#sec-Errors">GraphQL spec — Errors</a>
+ */
+public class GHGraphQLException extends GHIOException {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Structured GraphQL errors. Marked transient because {@link GHGraphQLError} carries Jackson-populated
+     * {@code Object} fields that may not be {@link java.io.Serializable}.
+     */
+    @Nonnull
+    @SuppressFBWarnings(value = "SE_BAD_FIELD",
+            justification = "GHGraphQLError carries Jackson-populated Object fields; exception serialization is "
+                    + "best-effort and not part of the public contract")
+    private final transient List<GHGraphQLError> errors;
+
+    /** Original GraphQL query, when available; useful for debugging. */
+    private final String query;
+
+    /** Partial response data, transient because the payload type is unconstrained. */
+    private final transient Object responseData;
+
+    /**
+     * Instantiates a new GraphQL exception.
+     *
+     * @param message
+     *            human-readable summary suitable for log output
+     * @param errors
+     *            the structured GraphQL errors returned by the server, never {@code null}
+     * @param responseData
+     *            the partial {@code data} payload, or {@code null} if the server returned none
+     * @param query
+     *            the GraphQL query string sent in the originating request, or {@code null} if unknown
+     */
+    @SuppressFBWarnings(value = { "EI_EXPOSE_REP2" }, justification = "errors list is wrapped unmodifiable")
+    public GHGraphQLException(@Nonnull String message,
+            @Nonnull List<GHGraphQLError> errors,
+            @CheckForNull Object responseData,
+            @CheckForNull String query) {
+        super(message);
+        this.errors = Collections.unmodifiableList(errors);
+        this.responseData = responseData;
+        this.query = query;
+    }
+
+    /**
+     * Get the structured error entries returned by the GraphQL endpoint. The list is unmodifiable. Returns an empty
+     * list after this exception has been deserialized across a JVM boundary, since the structured errors are not
+     * preserved through serialization.
+     *
+     * @return the GraphQL errors
+     */
+    @Nonnull
+    public List<GHGraphQLError> getErrors() {
+        return errors == null ? Collections.emptyList() : errors;
+    }
+
+    /**
+     * Get the GraphQL query that produced this response, when available.
+     *
+     * @return the query string, or {@code null}
+     */
+    @CheckForNull
+    public String getQuery() {
+        return query;
+    }
+
+    /**
+     * Get the partial response data returned alongside the errors, if any. GraphQL allows servers to return both
+     * {@code data} and {@code errors} when a request only partially fails. Returns {@code null} when the server
+     * returned no data or after deserialization, e.g. across the network.
+     *
+     * @return the partial response data, or {@code null}
+     */
+    @CheckForNull
+    public Object getResponseData() {
+        return responseData;
+    }
+}

src/main/java/org/kohsuke/github/Requester.java

@@ -102,14 +102,21 @@ public <T> T fetch(@Nonnull Class<T> type) throws IOException {
      * @param type
      *            the type
      * @return an instance of {@code GHGraphQLResponse<T>}
+     * @throws GHGraphQLException
+     *             if the server returns a successful HTTP response whose body contains a non-empty {@code errors}
+     *             array.
      * @throws IOException
      *             if the server returns 4xx/5xx responses.
      */
     public <T extends GHGraphQLResponse<S>, S> S fetchGraphQL(@Nonnull Class<T> type) throws IOException {
         T response = fetch(type);
 
         if (!response.isSuccessful()) {
-            throw new IOException("GraphQL request failed by:" + response.getErrorMessages());
+            String message = response.buildErrorSummary("Request failed due to following response errors");
+            throw new GHGraphQLException(message,
+                    response.getErrors(),
+                    response.getDataUnchecked(),
+                    extractGraphQLQuery());
         }
 
         return response.getData();
@@ -201,4 +208,19 @@ public <R> PagedIterable<R> toIterable(Class<R[]> type, Consumer<R> itemInitiali
         return new GitHubPageContentsIterable<>(client, build(), type, itemInitializer);
 
     }
+
+    /**
+     * Best-effort lookup of the {@code query} parameter set by {@link GitHub#createGraphQLRequest(String)}. Returns
+     * {@code null} if the parameter is missing, e.g. when the request was assembled by hand.
+     *
+     * @return the query string sent in this request, or {@code null}
+     */
+    private String extractGraphQLQuery() {
+        for (GitHubRequest.Entry entry : build().args()) {
+            if ("query".equals(entry.key) && entry.value instanceof String) {
+                return (String) entry.value;
+            }
+        }
+        return null;
+    }
 }

src/main/java/org/kohsuke/github/internal/graphql/response/GHGraphQLError.java

@@ -0,0 +1,135 @@
+package org.kohsuke.github.internal.graphql.response;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+import javax.annotation.CheckForNull;
+
+/**
+ * A single error entry returned by a GitHub GraphQL response.
+ *
+ * <p>
+ * Per the GraphQL specification, only {@code message} is guaranteed to be present. Other fields ({@code type},
+ * {@code path}, {@code locations}, {@code extensions}) are optional and may be {@code null} depending on the error.
+ * Unknown fields are ignored to remain forward-compatible with future server-side additions.
+ * </p>
+ *
+ * @see <a href="https://spec.graphql.org/October2021/#sec-Errors">GraphQL spec — Errors</a>
+ * @see <a href="https://docs.github.com/en/graphql/reference/objects#error">GitHub GraphQL — Error</a>
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+@SuppressFBWarnings(value = { "UWF_UNWRITTEN_FIELD", "UWF_FIELD_NOT_INITIALIZED_IN_CONSTRUCTOR" },
+        justification = "Populated via Jackson deserialization")
+public class GHGraphQLError {
+
+    /**
+     * Source location of an error inside the GraphQL document.
+     */
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    @SuppressFBWarnings(value = { "UWF_UNWRITTEN_FIELD", "UWF_FIELD_NOT_INITIALIZED_IN_CONSTRUCTOR" },
+            justification = "Populated via Jackson deserialization")
+    public static class Location {
+
+        private int column;
+
+        private int line;
+
+        /**
+         * Default constructor used by Jackson.
+         */
+        public Location() {
+        }
+
+        /**
+         * Get the column index of the location, starting at 1.
+         *
+         * @return the column index
+         */
+        public int getColumn() {
+            return column;
+        }
+
+        /**
+         * Get the line index of the location, starting at 1.
+         *
+         * @return the line index
+         */
+        public int getLine() {
+            return line;
+        }
+    }
+
+    private Map<String, Object> extensions;
+
+    private List<Location> locations;
+
+    private String message;
+
+    private List<Object> path;
+
+    private String type;
+
+    /**
+     * Default constructor used by Jackson.
+     */
+    public GHGraphQLError() {
+    }
+
+    /**
+     * Get the extensions object as defined by the GraphQL spec. GitHub may include custom keys here, e.g. error code or
+     * documentation URL. May be {@code null} if not provided.
+     *
+     * @return the extensions map, or {@code null}
+     */
+    @CheckForNull
+    public Map<String, Object> getExtensions() {
+        return extensions == null ? null : Collections.unmodifiableMap(extensions);
+    }
+
+    /**
+     * Get the source locations associated with this error. Each entry points to a line/column in the GraphQL document.
+     * May be {@code null} if not provided.
+     *
+     * @return the list of locations, or {@code null}
+     */
+    @CheckForNull
+    public List<Location> getLocations() {
+        return locations == null ? null : Collections.unmodifiableList(locations);
+    }
+
+    /**
+     * Get the human-readable error message. Per the GraphQL spec this field is always present.
+     *
+     * @return the message
+     */
+    public String getMessage() {
+        return message;
+    }
+
+    /**
+     * Get the response path that failed. Each segment is either a {@link String} field name or an {@link Integer} list
+     * index, per the GraphQL spec. May be {@code null} if not provided.
+     *
+     * @return the path elements, or {@code null}
+     */
+    @CheckForNull
+    public List<Object> getPath() {
+        return path == null ? null : Collections.unmodifiableList(path);
+    }
+
+    /**
+     * Get the error type as classified by the server. GitHub commonly uses values such as {@code FORBIDDEN},
+     * {@code NOT_FOUND}, {@code RATE_LIMITED}, or {@code UNPROCESSABLE}. This is a GitHub extension to the GraphQL spec
+     * and may be {@code null}.
+     *
+     * @return the error type, or {@code null}
+     */
+    @CheckForNull
+    public String getType() {
+        return type;
+    }
+}