Article API: compact GraphQL reference output for LLM consumers (#60072)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

src/article-api/templates/graphql-reference.template.md

@@ -4,6 +4,14 @@
 
 {{ manualContent }}
 
+{% if connectionEdgeSummary %}
+## Connection and Edge types
+
+Connection types with only the standard pagination fields (`edges`, `nodes`, `pageInfo`, `totalCount`) and Edge types with only `cursor` and `node` are summarized here. Connection and Edge types with additional fields are documented individually below.
+
+{% for name in connectionEdgeSummary %}`{{ name }}`{% unless forloop.last %}, {% endunless %}{% endfor %}
+
+{% endif %}
 {% for item in items %}
 
 ## {{ item.name }}
@@ -17,15 +25,13 @@
 {% endif %}
 
 {% if pageType == 'queries' %}
-**Type:** [{{ item.type }}]({{ item.href }})
+**Type:** {{ item.type }}
 
 {% if item.args.size > 0 %}
 
 ### Arguments for `{{ item.name }}`
 
-| Name | Type | Description |
-| --- | --- | --- |
-{% for arg in item.args %}| `{{ arg.name }}` | [`{{ arg.type }}`]({{ arg.href }}) | {{ arg.description }} |
+{% for arg in item.args %}* `{{ arg.name }}` ({{ arg.type }}): {{ arg.description }}
 {% endfor %}
 {% endif %}
 
@@ -34,38 +40,31 @@
 
 ### Input fields for `{{ item.name }}`
 
-| Name | Type | Description |
-| --- | --- | --- |
-{% for field in item.inputFields %}| `{{ field.name }}` | [`{{ field.type }}`]({{ field.href }}) | {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %} |
+{% for field in item.inputFields %}* `{{ field.name }}` ({{ field.type }}): {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}
 {% endfor %}
 {% endif %}
 
 {% if item.returnFields.size > 0 %}
 
 ### Return fields for `{{ item.name }}`
 
-| Name | Type | Description |
-| --- | --- | --- |
-{% for field in item.returnFields %}| `{{ field.name }}` | [`{{ field.type }}`]({{ field.href }}) | {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %} |
+{% for field in item.returnFields %}* `{{ field.name }}` ({{ field.type }}): {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %}
 {% endfor %}
 {% endif %}
 
 {% elsif pageType == 'objects' %}
 {% if item.implements.size > 0 %}
+**Implements:** {% for impl in item.implements %}{{ impl.name }}{% unless forloop.last %}, {% endunless %}{% endfor %}
 
-### Implements
-
-{% for impl in item.implements %}- [`{{ impl.name }}`]({{ impl.href }})
-{% endfor %}
 {% endif %}
 
 {% if item.fields.size > 0 %}
 
 ### Fields for `{{ item.name }}`
 
-| Name | Type | Description |
-| --- | --- | --- |
-{% for field in item.fields %}| `{{ field.name }}` | [`{{ field.type }}`]({{ field.href }}) | {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %}{% if field.arguments.size > 0 %}<br><br>**Arguments:**<br>{% for arg in field.arguments %}- `{{ arg.name }}` ([`{{ arg.type.name }}`]({{ arg.type.href }})): {{ arg.description }}{% if arg.defaultValue %} Default: `{{ arg.defaultValue }}`.{% endif %}<br>{% endfor %}{% endif %} |
+{% for field in item.fields %}* `{{ field.name }}` ({{ field.type }}): {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %}{% if field.arguments.size > 0 %}
+{% for arg in field.arguments %}  * `{{ arg.name }}` ({{ arg.type.name }}): {{ arg.description }}{% if arg.defaultValue %} Default: `{{ arg.defaultValue }}`.{% endif %}
+{% endfor %}{% endif %}
 {% endfor %}
 {% endif %}
 
@@ -74,9 +73,9 @@
 
 ### Fields for `{{ item.name }}`
 
-| Name | Type | Description |
-| --- | --- | --- |
-{% for field in item.fields %}| `{{ field.name }}` | [`{{ field.type }}`]({{ field.href }}) | {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %}{% if field.arguments.size > 0 %}<br><br>**Arguments:**<br>{% for arg in field.arguments %}- `{{ arg.name }}` ([`{{ arg.type.name }}`]({{ arg.type.href }})): {{ arg.description }}{% if arg.defaultValue %} Default: `{{ arg.defaultValue }}`.{% endif %}<br>{% endfor %}{% endif %} |
+{% for field in item.fields %}* `{{ field.name }}` ({{ field.type }}): {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %}{% if field.arguments.size > 0 %}
+{% for arg in field.arguments %}  * `{{ arg.name }}` ({{ arg.type.name }}): {{ arg.description }}{% if arg.defaultValue %} Default: `{{ arg.defaultValue }}`.{% endif %}
+{% endfor %}{% endif %}
 {% endfor %}
 {% endif %}
 
@@ -85,10 +84,7 @@
 
 ### Values for `{{ item.name }}`
 
-{% for value in item.values %}**`{{ value.name }}`**
-
-{{ value.description }}
-
+{% for value in item.values %}* `{{ value.name }}`: {{ value.description }}
 {% endfor %}
 {% endif %}
 
@@ -97,7 +93,7 @@
 
 ### Possible types for `{{ item.name }}`
 
-{% for type in item.possibleTypes %}- [`{{ type.name }}`]({{ type.href }})
+{% for type in item.possibleTypes %}* {{ type.name }}
 {% endfor %}
 {% endif %}
 
@@ -106,9 +102,7 @@
 
 ### Input fields for `{{ item.name }}`
 
-| Name | Type | Description |
-| --- | --- | --- |
-{% for field in item.inputFields %}| `{{ field.name }}` | [`{{ field.type }}`]({{ field.href }}) | {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %} |
+{% for field in item.inputFields %}* `{{ field.name }}` ({{ field.type }}): {{ field.description }}{% if field.defaultValue %} Default: `{{ field.defaultValue }}`.{% endif %}{% if field.isDeprecated %} **Deprecated:** {{ field.deprecationReason }}{% endif %}
 {% endfor %}
 {% endif %}
 

src/article-api/tests/graphql-transformer.ts

@@ -55,22 +55,19 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       // Check for query description
       expect(res.body).toContain('Lookup a given repository by the owner and repository name.')
 
-      // Check for type link
-      expect(res.body).toContain('**Type:** [Repository](/en/graphql/reference/objects#repository)')
+      // Check for type (without link)
+      expect(res.body).toContain('**Type:** Repository')
     })
 
-    test('query arguments are listed in table format', async () => {
+    test('query arguments are listed in bullet format', async () => {
       const res = await getCached('/en/graphql/reference/queries')
       expect(res.statusCode).toBe(200)
 
-      // Check for arguments table for codeOfConduct query
+      // Check for arguments section for codeOfConduct query
       expect(res.body).toContain('### Arguments for `codeOfConduct`')
-      expect(res.body).toMatch(/\|\s*Name\s*\|\s*Type\s*\|\s*Description\s*\|/)
-      expect(res.body).toMatch(/\|\s*-+\s*\|\s*-+\s*\|\s*-+\s*\|/)
 
-      // Check for specific arguments
-      expect(res.body).toMatch(/\|\s*`key`\s*\|/)
-      expect(res.body).toContain('[`String!`](/en/graphql/reference/scalars#string)')
+      // Check for specific arguments in bullet format
+      expect(res.body).toContain('`key` (String!)')
       expect(res.body).toContain("The code of conduct's key.")
     })
 
@@ -84,13 +81,13 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       // Check for mutation description
       expect(res.body).toContain('Create a new repository.')
 
-      // Check for input fields table
+      // Check for input fields in bullet format
       expect(res.body).toContain('### Input fields for `createRepository`')
-      expect(res.body).toContain('| `input` |')
+      expect(res.body).toContain('`input`')
 
-      // Check for return fields table
+      // Check for return fields in bullet format
       expect(res.body).toContain('### Return fields for `createRepository`')
-      expect(res.body).toMatch(/\|\s*`repository`\s*\|/)
+      expect(res.body).toContain('`repository`')
       expect(res.body).toContain('The new repository.')
     })
 
@@ -101,30 +98,42 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       // Check for object heading - AddedToMergeQueueEvent has implements
       expect(res.body).toContain('## AddedToMergeQueueEvent')
 
-      // Check for implements section
-      expect(res.body).toContain('### Implements')
-      expect(res.body).toMatch(/[*-]\s*\[`Node`\]\(\/.*graphql\/reference\/interfaces#node\)/)
+      // Check for implements inline
+      expect(res.body).toContain('**Implements:** Node')
 
-      // Check for fields table
+      // Check for fields in bullet format
       expect(res.body).toContain('### Fields for `AddedToMergeQueueEvent`')
-      expect(res.body).toMatch(/\|\s*`id`\s*\|/)
-      expect(res.body).toMatch(/\|\s*`actor`\s*\|/)
-      expect(res.body).toMatch(/\|\s*`createdAt`\s*\|/)
+      expect(res.body).toContain('`id`')
+      expect(res.body).toContain('`actor`')
+      expect(res.body).toContain('`createdAt`')
     })
 
-    test('objects page shows field arguments inline', async () => {
+    test('objects page shows field arguments as nested bullets', async () => {
       const res = await getCached('/en/graphql/reference/objects')
       expect(res.statusCode).toBe(200)
 
       // Check for User object with repositories field that has arguments
       expect(res.body).toContain('## User')
-      expect(res.body).toContain('| `repositories` |')
+      expect(res.body).toContain('`repositories`')
 
-      // Check for inline arguments formatting
-      expect(res.body).toContain('**Arguments:**')
-      expect(res.body).toContain('- `first`')
+      // Check for nested argument bullets
+      expect(res.body).toContain('`first`')
       expect(res.body).toContain('Returns the first n elements from the list.')
-      expect(res.body).toContain('- `orderBy`')
+      expect(res.body).toContain('`orderBy`')
+    })
+
+    test('objects page collapses boilerplate Connection and Edge types', async () => {
+      const res = await getCached('/en/graphql/reference/objects')
+      expect(res.statusCode).toBe(200)
+
+      // Check for Connection/Edge summary section
+      expect(res.body).toContain('## Connection and Edge types')
+      expect(res.body).toContain('standard pagination fields')
+
+      // Boilerplate Connection/Edge types should be in the summary, not as H2 sections
+      // ActorConnection has only standard fields (edges, nodes, pageInfo, totalCount)
+      expect(res.body).toContain('`ActorConnection`')
+      expect(res.body).not.toMatch(/^## ActorConnection$/m)
     })
 
     test('interfaces page renders correctly', async () => {
@@ -137,9 +146,9 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       // Check for interface description
       expect(res.body).toContain('An object with an ID.')
 
-      // Check for fields table
+      // Check for fields in bullet format
       expect(res.body).toContain('### Fields for `Node`')
-      expect(res.body).toContain('| `id` |')
+      expect(res.body).toContain('`id`')
       expect(res.body).toContain('ID of the object.')
     })
 
@@ -153,13 +162,13 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       // Check for enum description
       expect(res.body).toContain("The repository's visibility level.")
 
-      // Check for values section
+      // Check for values in bullet format
       expect(res.body).toContain('### Values for `RepositoryVisibility`')
-      expect(res.body).toContain('**`PUBLIC`**')
+      expect(res.body).toContain('`PUBLIC`')
       expect(res.body).toContain('The repository is visible to everyone.')
-      expect(res.body).toContain('**`PRIVATE`**')
+      expect(res.body).toContain('`PRIVATE`')
       expect(res.body).toContain('The repository is visible only to those with explicit access.')
-      expect(res.body).toContain('**`INTERNAL`**')
+      expect(res.body).toContain('`INTERNAL`')
     })
 
     test('unions page renders with possible types', async () => {
@@ -172,13 +181,11 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       // Check for union description
       expect(res.body).toContain('The results of a search.')
 
-      // Check for possible types
+      // Check for possible types in bullet format (without links)
       expect(res.body).toContain('### Possible types for `SearchResultItem`')
-      expect(res.body).toMatch(/[*-]\s*\[`Bot`\]\(\/.*graphql\/reference\/objects#bot\)/)
-      expect(res.body).toMatch(
-        /[*-]\s*\[`PullRequest`\]\(\/.*graphql\/reference\/objects#pullrequest\)/,
-      )
-      expect(res.body).toMatch(/[*-]\s*\[`User`\]\(\/.*graphql\/reference\/objects#user\)/)
+      expect(res.body).toMatch(/\*\s*Bot/)
+      expect(res.body).toMatch(/\*\s*PullRequest/)
+      expect(res.body).toMatch(/\*\s*User/)
     })
 
     test('input-objects page renders correctly', async () => {
@@ -191,9 +198,9 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       // Check for input object description
       expect(res.body).toContain('Autogenerated input type of CreateRepository.')
 
-      // Check for input fields table
+      // Check for input fields in bullet format
       expect(res.body).toContain('### Input fields for `AbortQueuedMigrationsInput`')
-      expect(res.body).toMatch(/\|\s*`ownerId`\s*\|/)
+      expect(res.body).toContain('`ownerId`')
       expect(res.body).toContain('The ID of the organization that is running the migrations.')
     })
 
@@ -314,7 +321,6 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
 
       // Check that AUTOTITLE has been resolved
       expect(res.body).toMatch(/(Forming calls with GraphQL|Hello World)/)
-      expect(res.body).toContain('(/en/get-started/start-your-journey/hello-world)')
 
       // Make sure the raw AUTOTITLE tag is not present
       expect(res.body).not.toContain('[AUTOTITLE]')

src/article-api/transformers/graphql-reference-transformer.ts

@@ -97,12 +97,47 @@ export class GraphQLReferenceTransformer implements PageTransformer {
         break
     }
 
+    // For objects pages, collapse Connection/Edge types that have only standard
+    // boilerplate fields into a summary. Types with additional fields are kept.
+    let connectionEdgeSummary: string[] | null = null
+    if (schemaKey === 'objects') {
+      const BOILERPLATE_CONNECTION_FIELDS = new Set(['edges', 'nodes', 'pageInfo', 'totalCount'])
+      const BOILERPLATE_EDGE_FIELDS = new Set(['cursor', 'node'])
+      const connEdgeNames: string[] = []
+      const filteredItems: Array<Record<string, unknown>> = []
+      for (const item of preparedItems) {
+        const name = item.name as string
+        const fields = item.fields as Array<Record<string, unknown>> | undefined
+        const fieldNames = new Set((fields || []).map((f) => f.name as string))
+
+        const isBoilerplateConnection =
+          name.endsWith('Connection') &&
+          fieldNames.size === BOILERPLATE_CONNECTION_FIELDS.size &&
+          [...fieldNames].every((f) => BOILERPLATE_CONNECTION_FIELDS.has(f))
+        const isBoilerplateEdge =
+          name.endsWith('Edge') &&
+          fieldNames.size === BOILERPLATE_EDGE_FIELDS.size &&
+          [...fieldNames].every((f) => BOILERPLATE_EDGE_FIELDS.has(f))
+
+        if (isBoilerplateConnection || isBoilerplateEdge) {
+          connEdgeNames.push(name)
+        } else {
+          filteredItems.push(item)
+        }
+      }
+      if (connEdgeNames.length > 0) {
+        connectionEdgeSummary = connEdgeNames.sort()
+        preparedItems = filteredItems
+      }
+    }
+
     const templateData: Record<string, unknown> = {
       pageTitle: page.title,
       pageIntro: intro,
       manualContent,
       items: preparedItems,
       pageType: schemaKey,
+      connectionEdgeSummary,
     }
 
     const templateContent = loadTemplate(this.templateName)