chore(test): take the OpenAPI and GraphQL schemas from the Octokit packages instead of fetching them

.github/scripts/check-compat-markers.ts

@@ -16,13 +16,12 @@ import { execFileSync } from "node:child_process";
 import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-/** Built output, dependencies, the fetched spec, release-please's changelog (it quotes PR titles, so a removal PR's
- * title would outlive the marker it deleted), and the two files that spell the syntax to define and test it.
+/** Built output, dependencies, release-please's changelog (it quotes PR titles, so a removal PR's title would
+ * outlive the marker it deleted), and the two files that spell the syntax to define and test it.
  * A trailing slash skips a directory; anything else is one exact path. */
 const SKIPPED_PATHS = [
   "lib/",
   "node_modules/",
-  "test/e2e/openapi/github-openapi.trimmed.json",
   "CHANGELOG.md",
   ".github/scripts/check-compat-markers.ts",
   "test/scripts/check-compat-markers.test.ts",

.github/scripts/endpoint-docs.ts

@@ -1,6 +1,6 @@
 /**
  * The docs.github.com page behind every REST route and GraphQL operation the sections declare, for the coverage
- * page's Endpoints cells (gen-docs.ts). REST pages are the trimmed OpenAPI descriptor's own externalDocs links;
+ * page's Endpoints cells (gen-docs.ts). REST pages are the OpenAPI descriptor's own externalDocs links;
  * endpoint-docs.yml beside this file holds only what the descriptor lacks: the routes GitHub does not document and
  * every GraphQL operation. resolveAnchors() fails the docs build by name on a declared call with no page, a hand
  * entry the descriptor already covers, and a hand entry no section declares.
@@ -10,7 +10,7 @@ import { join } from "node:path";
 import { z } from "zod";
 import { readDocsYaml } from "../../src/sections/contract/docs.js";
 import { allEndpoints, allGraphqlOps } from "../../src/sections/registry.js";
-import { readSpecText } from "../../test/e2e/openapi/validate.js";
+import { loadSpec } from "../../test/e2e/openapi/validate.js";
 
 const DOCS_URL = z.string().url().startsWith("https://docs.github.com/en/");
 
@@ -118,10 +118,6 @@ export function resolveAnchors(
   return { rest, graphql };
 }
 
-function specOperations(): SpecOperations {
-  return (JSON.parse(readSpecText()) as { paths: SpecOperations }).paths;
-}
-
 /** The distinct routes and operation names the sections declare, in registry order. */
 export function declaredCalls(): { routes: string[]; operations: string[] } {
   return {
@@ -132,5 +128,5 @@ export function declaredCalls(): { routes: string[]; operations: string[] } {
 
 export const ENDPOINT_ANCHORS: EndpointAnchors = (() => {
   const { routes, operations } = declaredCalls();
-  return resolveAnchors(specOperations(), ENDPOINT_DOCS, routes, operations);
+  return resolveAnchors(loadSpec().paths, ENDPOINT_DOCS, routes, operations);
 })();

.github/scripts/endpoint-docs.yml

@@ -1,4 +1,4 @@
-# The docs.github.com page for every call the trimmed OpenAPI descriptor cannot supply: the routes GitHub does not
+# The docs.github.com page for every call the OpenAPI descriptor cannot supply: the routes GitHub does not
 # document (src/upstream-gaps/) and every GraphQL operation, keyed as the declaration spells them. Every other REST
 # route takes its page from the descriptor's own externalDocs link (endpoint-docs.ts). The lockstep test in
 # test/scripts/endpoint-docs.test.ts fails on a declared call without a page, an entry the descriptor already

.github/scripts/gen-gaps-index.ts

@@ -1,5 +1,5 @@
 /**
- * Regenerates src/upstream-gaps/index.ts WHOLESALE from the directory listing: the derivations split the two gap
+ * Regenerates src/upstream-gaps/index.ts WHOLESALE from the directory listing: the derivations split the gap
  * kinds by their `kind` field, so nothing but the file names is needed.
  *   a gap file added by hand                     -> `bun .github/scripts/gen-gaps-index.ts`
  *   graduate-upstream-gaps.ts                    -> calls regenerateIndex() itself
@@ -31,6 +31,12 @@ export function camelCaseGapName(base: string): string {
   return base.replace(/-([a-z0-9])/g, (_, ch: string) => ch.toUpperCase());
 }
 
+/** The record entry for a gap file: shorthand when the alias is the base name, a quoted key otherwise. */
+export function gapEntry(base: string): string {
+  const alias = camelCaseGapName(base);
+  return alias === base ? `${alias},` : `"${base}": ${alias},`;
+}
+
 export function gapFileBases(listing: readonly string[]): string[] {
   return listing
     .filter(isGapFileName)
@@ -43,7 +49,10 @@ export function gapFileBases(listing: readonly string[]): string[] {
 export function generateIndex(bases: readonly string[]): string {
   const sorted = [...bases].sort();
   const imports = [
-    { specifier: "./gap.js", line: `import { undocumentedRoutes } from "./gap.js";` },
+    {
+      specifier: "./gap.js",
+      line: `import { undocumentedRoutes, type UnshippedGraphqlSdl, unshippedGraphqlSdl } from "./gap.js";`,
+    },
     ...sorted.map((base) => ({
       specifier: `./${base}.js`,
       line: `import { GAP as ${camelCaseGapName(base)} } from "./${base}.js";`,
@@ -52,27 +61,25 @@ export function generateIndex(bases: readonly string[]): string {
     .sort((a, b) => (a.specifier < b.specifier ? -1 : 1))
     .map((entry) => entry.line)
     .join("\n");
-  const gapsArray =
+  const gapsRecord =
     sorted.length === 0
-      ? "const GAPS = [] as const;"
-      : [
-          "const GAPS = [",
-          ...sorted.map((base) => `  ${camelCaseGapName(base)},`),
-          "] as const;",
-        ].join("\n");
+      ? "const GAPS = {} as const;"
+      : ["const GAPS = {", ...sorted.map((base) => `  ${gapEntry(base)}`), "} as const;"].join(
+          "\n",
+        );
   return `/**
  * GENERATED by gen-gaps-index.ts - do not edit. Every pending upstream gap,
- * aggregated in sorted file order; regenerate with
+ * keyed by file base name in sorted order; regenerate with
  * \`bun .github/scripts/gen-gaps-index.ts\` after adding, deleting, or
  * transforming a gap file. The derivations below degrade gracefully to an
  * empty gaps set, so this file survives an empty directory.
  */
 
 ${imports}
 
-${gapsArray}
+${gapsRecord}
 
-type GapUnion = (typeof GAPS)[number];
+type GapUnion = (typeof GAPS)[keyof typeof GAPS];
 
 /**
  * Routes GitHub documents but the pinned @octokit/types release does not
@@ -90,11 +97,19 @@ type SpecOnlyRoute = Extract<GapUnion, { kind: "spec-only" }>["routes"][number];
  * The routes GitHub's api.github.com OpenAPI descriptor does not document:
  * every spec-only gap's, plus those of octokit-kind gaps marked
  * documentedInSpec: false. Consumed by test/e2e/openapi/paths.ts, which
- * excludes their paths from the spec trim and exempts exactly these
- * METHOD+path pairs from the e2e unknown-route check.
+ * excludes their paths from the descriptor slice the e2e validator loads
+ * and exempts exactly these METHOD+path pairs from its unknown-route check.
  */
 export const UNDOCUMENTED_ROUTES: readonly (SupplementalRoute | SpecOnlyRoute)[] =
   undocumentedRoutes<SupplementalRoute | SpecOnlyRoute>(GAPS);
+
+/**
+ * The SDL GitHub's GraphQL API serves but the pinned @octokit/graphql-schema
+ * release lacks, each with the gap file that carries it. Consumed by
+ * test/sections/graphql-queries.test.ts, which extends the published schema
+ * with it before validating the declared queries.
+ */
+export const UNSHIPPED_GRAPHQL_SDL: readonly UnshippedGraphqlSdl[] = unshippedGraphqlSdl(GAPS);
 `;
 }
 

.github/scripts/graduate-upstream-gaps.ts

@@ -98,7 +98,7 @@ export function isSpecOnly(gapSource: string): boolean {
 }
 
 /** A documentedInSpec: false gap whose tripwire fired means octokit caught up but the pinned descriptor did not: it
- * is rewritten rather than deleted, so its UNDOCUMENTED_ROUTES exemption survives until a bumped UPSTREAM_REF documents the paths. */
+ * is rewritten rather than deleted, so its UNDOCUMENTED_ROUTES exemption survives until an @octokit/openapi bump documents the paths. */
 export function isSpecPinned(gapSource: string): boolean {
   return /documentedInSpec:\s*false/.test(gapSource);
 }