Derive GraphQL categories for un-annotated types (#62194)

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

Author: heiskr

src/graphql/scripts/utils/process-schemas.ts

@@ -4,6 +4,8 @@ import type {
   DocumentNode,
   ObjectTypeDefinitionNode,
   InputObjectTypeDefinitionNode,
+  EnumTypeDefinitionNode,
+  UnionTypeDefinitionNode,
   FieldDefinitionNode,
   InputValueDefinitionNode,
   ConstDirectiveNode,
@@ -394,6 +396,124 @@ export default async function processSchemas(
     if (!changed) break
   }
 
+  // (c) General reference-based inheritance. An un-annotated enum, union, or
+  // input object inherits the category of the type(s) that reference it, but
+  // only when every referrer resolves to a single category; ambiguous types
+  // (referrers disagree, or a referrer is itself ambiguous) stay in `other`.
+  // This is the derived successor to a static exception list: it catches
+  // generated/indirect types that github/github never annotates directly while
+  // still letting the upstream team own the outcome via the parent type's
+  // `docs_category`.
+  //
+  // Examples this resolves today:
+  //   - `IssueTimelineItemsItemType` / `PullRequestTimelineItemsItemType`:
+  //     runtime-generated enums used only as the `itemTypes` argument on
+  //     `Issue.timelineItems` (issues) / `PullRequest.timelineItems` (pulls).
+  //   - `RepositoryRuleType` (enum) and `RuleParameters` (union): referenced
+  //     from the annotated `RepositoryRule` object (repos).
+  //   - `RuleParametersInput` (input): referenced from the annotated
+  //     `RepositoryRuleInput` input object (repos).
+  //
+  // A "referrer category" is the category of:
+  //   - the owning object type, for a field's return type or a field argument's
+  //     type (interfaces are intentionally excluded: they are cross-cutting and
+  //     make coincidental single-category matches likely);
+  //   - the Mutation root field, for that field's arguments;
+  //   - the owning input object, for an input field's type. Input objects can
+  //     themselves be uncategorized-but-derivable, so this rule propagates
+  //     transitively through nested inputs.
+  //
+  // Implemented as a monotone fixpoint over candidate category *sets* rather
+  // than committing categories as we go: a type is only assigned once its
+  // candidate set has stopped growing, so the result is independent of
+  // definition/derivation order and a later-discovered conflicting referrer
+  // can never be missed. Explicit annotations and derivations (a)/(b) always
+  // win: we only compute candidates for ids `lookupCat` still can't resolve.
+  const derivableTargets = schemaAST.definitions.filter(
+    (
+      def,
+    ): def is EnumTypeDefinitionNode | UnionTypeDefinitionNode | InputObjectTypeDefinitionNode =>
+      def.kind === 'EnumTypeDefinition' ||
+      def.kind === 'UnionTypeDefinition' ||
+      def.kind === 'InputObjectTypeDefinition',
+  )
+  const inputDefs = schemaAST.definitions.filter(
+    (def): def is InputObjectTypeDefinitionNode => def.kind === 'InputObjectTypeDefinition',
+  )
+
+  const targetIds = new Set<string>()
+  for (const def of derivableTargets) {
+    const id = helpers.getId(def.name.value)
+    if (!lookupCat(id)) targetIds.add(id)
+  }
+
+  if (targetIds.size > 0) {
+    const candidates = new Map<string, Set<string>>()
+    for (const id of targetIds) candidates.set(id, new Set())
+
+    // Categories a type contributes when it appears as a referrer. Annotated /
+    // fallback types contribute their single category; an uncommitted derivable
+    // referrer (only ever an input object here) contributes its current
+    // candidate set so ambiguity propagates downstream.
+    const contribution = (referrerId: string): Iterable<string> => {
+      const explicit = lookupCat(referrerId)
+      if (explicit) return [explicit]
+      return candidates.get(referrerId) ?? []
+    }
+    const addRef = (targetName: string | undefined, cats: Iterable<string>): boolean => {
+      if (!targetName) return false
+      const id = helpers.getId(targetName)
+      const set = candidates.get(id)
+      if (!set) return false
+      let grew = false
+      for (const c of cats) {
+        if (!set.has(c)) {
+          set.add(c)
+          grew = true
+        }
+      }
+      return grew
+    }
+
+    // Bounded by the worst-case propagation depth; each pass only adds to sets,
+    // so this terminates well before the cap.
+    const maxPasses = targetIds.size + 2
+    for (let pass = 0; pass < maxPasses; pass++) {
+      let changed = false
+
+      for (const def of objectDefs) {
+        const name = def.name.value
+        if (name === 'Query') continue
+        const isMutation = name === 'Mutation'
+        for (const field of def.fields || []) {
+          // Mutation fields carry their own category and their payload return
+          // type is already annotated, so (like rule (a)) we only walk args.
+          const fieldCats: Iterable<string> = isMutation
+            ? ((c) => (c ? [c] : []))(getMutationCat(field.name.value))
+            : contribution(helpers.getId(name))
+          if (!isMutation && addRef(namedTypeName(field.type), fieldCats)) changed = true
+          for (const arg of field.arguments || []) {
+            if (addRef(namedTypeName(arg.type), fieldCats)) changed = true
+          }
+        }
+      }
+
+      for (const def of inputDefs) {
+        const ownerCats = contribution(helpers.getId(def.name.value))
+        for (const field of def.fields || []) {
+          if (addRef(namedTypeName(field.type), ownerCats)) changed = true
+        }
+      }
+
+      if (!changed) break
+    }
+
+    // Assign only the targets whose final candidate set is unambiguous.
+    for (const [id, cats] of candidates) {
+      if (cats.size === 1) typeCategoryMap.set(id, [...cats][0])
+    }
+  }
+
   // Normalize unknown categories (e.g. `:checks`, `:search`, `:packages`,
   // `:security_advisories`) to `other`. The upstream gh/gh allowlist permits
   // many categories that docs-internal hasn't yet built per-category landing

src/graphql/tests/derive-categories.ts

@@ -0,0 +1,150 @@
+import { describe, expect, test } from 'vitest'
+
+import processSchemas from '../scripts/utils/process-schemas'
+
+// Minimal `@docsCategory` directive declaration so `buildASTSchema` can parse
+// the fixtures below. Mirrors the real declaration emitted by github/github.
+const DIRECTIVE = `
+directive @docsCategory(name: String!) on ENUM | FIELD_DEFINITION | INPUT_OBJECT | INTERFACE | OBJECT | UNION
+`
+
+// Run processSchemas over an inline IDL and return a flat name -> category map
+// across every kind, so tests can assert where a type landed.
+async function categoriesFor(idl: string): Promise<Record<string, string>> {
+  const data = await processSchemas(`${DIRECTIVE}\n${idl}`, [])
+  const out: Record<string, string> = {}
+  for (const kind of Object.keys(data) as (keyof typeof data)[]) {
+    for (const item of data[kind] as Array<{ name?: string; category?: string }>) {
+      if (item?.name && item.category) out[item.name] = item.category
+    }
+  }
+  return out
+}
+
+// Every fixture needs a Query root; a `viewer` field keeps it non-empty.
+const QUERY = `
+type Query {
+  viewer: String
+}
+`
+
+describe('reference-based category derivation (PASS 1.5 rule c)', () => {
+  test('enum inherits from an annotated object field return type', async () => {
+    const cats = await categoriesFor(`
+      ${QUERY}
+      type RepositoryRule @docsCategory(name: "repos") {
+        type: RepositoryRuleType
+      }
+      enum RepositoryRuleType { CREATION DELETION }
+    `)
+    expect(cats.RepositoryRuleType).toBe('repos')
+  })
+
+  test('union inherits from an annotated object field', async () => {
+    const cats = await categoriesFor(`
+      ${QUERY}
+      type RepositoryRule @docsCategory(name: "repos") {
+        parameters: RuleParameters
+      }
+      type UpdateParameters @docsCategory(name: "repos") { value: String }
+      union RuleParameters = UpdateParameters
+    `)
+    expect(cats.RuleParameters).toBe('repos')
+  })
+
+  test('enum inherits from an annotated object field argument', async () => {
+    // Mirrors Issue.timelineItems(itemTypes: [IssueTimelineItemsItemType!]).
+    const cats = await categoriesFor(`
+      ${QUERY}
+      type Issue @docsCategory(name: "issues") {
+        timelineItems(itemTypes: [IssueTimelineItemsItemType!]): String
+      }
+      enum IssueTimelineItemsItemType { ASSIGNED_EVENT CLOSED_EVENT }
+    `)
+    expect(cats.IssueTimelineItemsItemType).toBe('issues')
+  })
+
+  test('input object inherits transitively through nested input fields', async () => {
+    const cats = await categoriesFor(`
+      ${QUERY}
+      input RepositoryRuleInput @docsCategory(name: "repos") {
+        parameters: RuleParametersInput
+      }
+      input RuleParametersInput { nested: NestedParametersInput }
+      input NestedParametersInput { value: String }
+    `)
+    expect(cats.RuleParametersInput).toBe('repos')
+    // Propagates another hop through the still-uncategorized input chain.
+    expect(cats.NestedParametersInput).toBe('repos')
+  })
+
+  test('ambiguous referrers keep the type on `other`', async () => {
+    const cats = await categoriesFor(`
+      ${QUERY}
+      type Issue @docsCategory(name: "issues") {
+        state: SharedEnum
+      }
+      type PullRequest @docsCategory(name: "pulls") {
+        state: SharedEnum
+      }
+      enum SharedEnum { OPEN CLOSED }
+    `)
+    expect(cats.SharedEnum).toBe('other')
+  })
+
+  test('an explicit annotation wins over conflicting referrers', async () => {
+    const cats = await categoriesFor(`
+      ${QUERY}
+      type Issue @docsCategory(name: "issues") {
+        state: AnnotatedEnum
+      }
+      type PullRequest @docsCategory(name: "pulls") {
+        state: AnnotatedEnum
+      }
+      enum AnnotatedEnum @docsCategory(name: "repos") { OPEN CLOSED }
+    `)
+    expect(cats.AnnotatedEnum).toBe('repos')
+  })
+
+  test('a type referenced only from a Query field stays on `other`', async () => {
+    const cats = await categoriesFor(`
+      type Query {
+        search(kind: QueryOnlyEnum): String
+      }
+      enum QueryOnlyEnum { REPO USER }
+    `)
+    expect(cats.QueryOnlyEnum).toBe('other')
+  })
+
+  test('interfaces are not a referrer source', async () => {
+    // Interface is annotated and references the enum, but no object does, so
+    // the enum must not inherit the interface's category.
+    const cats = await categoriesFor(`
+      ${QUERY}
+      interface Rulable @docsCategory(name: "repos") {
+        kind: InterfaceOnlyEnum
+      }
+      enum InterfaceOnlyEnum { A B }
+    `)
+    expect(cats.InterfaceOnlyEnum).toBe('other')
+  })
+
+  test('an unreferenced type stays on `other`', async () => {
+    const cats = await categoriesFor(`
+      ${QUERY}
+      enum OrphanEnum { A B }
+    `)
+    expect(cats.OrphanEnum).toBe('other')
+  })
+
+  test('an enum used only as a mutation field argument inherits the mutation category', async () => {
+    const cats = await categoriesFor(`
+      ${QUERY}
+      type Mutation {
+        createRepositoryRule(kind: MutationArgEnum): String @docsCategory(name: "repos")
+      }
+      enum MutationArgEnum { A B }
+    `)
+    expect(cats.MutationArgEnum).toBe('repos')
+  })
+})