🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🌐 Web query:

Does GitHub's GraphQL API accept a query operation with empty parentheses like "query repositoryQuery() { ... }" when no variables are declared, or does it reject it as a syntax error?

💡 Result:

GitHub's GraphQL API will reject a query operation defined with empty parentheses, such as query repositoryQuery {... }, as a syntax error [1][2]. According to the official GraphQL specification, the parentheses following an operation name are specifically reserved for the VariablesDefinition [1][2]. If an operation defines no variables, the parentheses must be omitted entirely; including them when there are no variables is syntactically invalid [1][2]. To correctly format your query, you should either remove the empty parentheses or use the shorthand syntax if the operation is unnamed and has no variables [1][2]: Valid options: 1. Named query without variables: query repositoryQuery {... } 2. Unnamed shorthand: {... } If you must include the parentheses, they are only permitted when they contain at least one variable declaration [1][2].

Citations:

• 1: https://github.com/graphql/graphql-spec/blob/main/spec/Section%202%20--%20Language.md
• 2: https://spec.graphql.org/October2021/

🌐 Web query:

GraphQL spec OperationDefinition variableDefinitions empty parentheses query repositoryQuery() syntax error

💡 Result:

The GraphQL specification defines VariableDefinitions as an optional, non-empty list of variable definitions enclosed in parentheses [1][2]. Specifically, the grammar is defined as: VariablesDefinition: ( VariableDefinition+) [1][3] Because the grammar requires at least one VariableDefinition (indicated by the + quantifier in EBNF notation), providing empty parentheses () for variable definitions is syntactically invalid [1][4]. If you encounter a syntax error like repositoryQuery(), it is likely due to the inclusion of empty parentheses where no variables are defined, or a misunderstanding of how the operation name and variables are structured. To resolve this: 1. If your query requires no variables, simply omit the parentheses entirely [2]. 2. If you are attempting to name your query, the correct syntax is query RepositoryName { ... } [2]. 3. If you see code like repositoryQuery() in a client-side library (such as JavaScript/TypeScript SDKs), it is likely a function call in your code, not a GraphQL query string. Ensure you are passing the correct arguments to the function and that the actual GraphQL query string contained within it follows the valid query { ... } or query Name { ... } syntax [5][6][7]. In summary, () cannot be used in a GraphQL document to represent an empty variable definition block; if no variables are required, the parentheses must be removed [1][2].

Citations:

• 1: https://github.com/graphql/graphql-spec/blob/master/spec/Section%202%20--%20Language.md
• 2: https://spec.graphql.org/draft/
• 3: https://github.com/graphql/graphql-spec/blob/main/spec/Section%202%20--%20Language.md
• 4: https://github.com/karminski/graphql-grammar-ebnf-definition/blob/main/DOCUMENTS/June-2018-Edition/GraphQL-Grammar-EBNF-Definition-June-2018-Edition.ebnf
• 5: https://stackoverflow.com/questions/62326596/get-results-from-different-arrays-in-one-promise-all-with-github-graphql-api
• 6: https://github.com/AKJUS/github-apiv4
• 7: https://git.pikami.org/random-mirrors/cosmos-explorer/raw/commit/07b9c1d1b7cfe04421a2173ab04e9a1a31b29725/src/GitHub/GitHubClient.ts

🌐 Web query:

GitHub GraphQL API error message "Syntax Error" "query..." empty parentheses

💡 Result:

The "Syntax Error: Expected Name, found)" error when using empty parentheses in a GraphQL query occurs because the GraphQL specification does not permit empty argument lists [1][2]. In GraphQL, if a field or query does not require arguments, you must omit the parentheses entirely rather than leaving them empty [3][1][2]. If you are encountering this error while querying the GitHub GraphQL API, check your query for any fields that include empty parentheses like field() and remove them to simply use field [3][2]. For example: - Incorrect: query { repository(name: "example") { issues {... } } } - Correct: query { repository(name: "example") { issues {... } } } If you intend to provide arguments, ensure they are correctly formatted within the parentheses. If you are dealing with dynamic query generation (where arguments might sometimes be absent), you must adjust your logic to conditionally omit the parentheses when no arguments are provided, rather than defaulting to an empty set [1].

Citations:

• 1: Query with all parameters optional can't be called with empty () graphql/graphql-js#1860
• 2: Cannot create function with no parameters aws-amplify/amplify-cli#4162
• 3: Empty parentheses in type definition break entire application without helpful error msg graphql-hive/graphql-yoga#564

Remove the empty parentheses from the query header.

query repositoryQuery() { is invalid GraphQL because the VariableDefinitions block is optional when no variables are used, and parentheses cannot be empty. Use query repositoryQuery { so GitHub’s GraphQL API does not reject the generated document during showcase generation.

 const gql = `#graphql
-query repositoryQuery() {
+query repositoryQuery {
   ${repositoryMeta.map(repository => buildRepoQuery(repository)).join('\n  ')}
 }`

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/.vitepress/data/gen-files.ts` around lines 17 - 20, Update the GraphQL
query template in the repository query construction to remove the empty
parentheses from the repositoryQuery operation header, preserving the existing
generated field selections and formatting.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Check for GraphQL errors and null repository results before writing files.

resp.data is cast to Record<string, Repository> without checking resp.errors. GitHub's repository field is nullable. If a configured repository is renamed, moved, or otherwise inaccessible, its aliased field resolves to null while the HTTP response still returns 200 with an errors entry describing the field failure. The loop at Line 33 then passes repo === null into writeReadme, which crashes at Line 65 (repo.name) with an uninformative TypeError instead of a clear error naming the failing repository.

This is exactly the class of failure (renamed/inaccessible repos causing 404s) the PR is meant to fix. Surface it explicitly instead of letting it crash blindly.

 const data = resp.data as Record<string, Repository>
+if (resp.errors?.length) {
+  throw new Error(`GraphQL errors: ${JSON.stringify(resp.errors)}`)
+}
 for (const [key, repo] of Object.entries(data)) {
   const meta = repositoryMeta.find(meta => getRepoId(meta) === key)
   if (!meta) {
     throw new Error(`Repository meta not found for ${key}`)
   }
+  if (!repo) {
+    throw new Error(`Repository data not found for ${meta.owner}/${meta.name} (possibly renamed or inaccessible)`)
+  }
   writeReadme(repo, meta)
 }

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/.vitepress/data/gen-files.ts` around lines 32 - 39, Validate the GraphQL
response before iterating in the repository generation flow: surface resp.errors
with a clear failure, and reject any null aliased repository result with an
error naming its key before calling writeReadme. Remove the unsafe
Record<string, Repository> assumption or narrow it after validation, while
preserving the existing metadata lookup and writeReadme behavior for valid
repositories.