Add GraphQL ID scalar and built-in name collision warning

packages/graphql/lib/main.tsp

@@ -1,5 +1,6 @@
 import "./interface.tsp";
 import "./operation-fields.tsp";
 import "./operation-kind.tsp";
+import "./scalars.tsp";
 import "./schema.tsp";
 import "./specified-by.tsp";

packages/graphql/lib/scalars.tsp

@@ -0,0 +1,17 @@
+namespace TypeSpec.GraphQL;
+
+/**
+ * Represents a GraphQL ID scalar — a unique identifier serialized as a string.
+ *
+ * @see https://spec.graphql.org/September2025/#sec-ID
+ *
+ * @example
+ *
+ * ```typespec
+ * model User {
+ *   id: GraphQL.ID;
+ *   name: string;
+ * }
+ * ```
+ */
+scalar ID extends string;

packages/graphql/package.json

@@ -24,10 +24,6 @@
       "typespec": "./lib/main.tsp",
       "types": "./dist/src/index.d.ts",
       "default": "./dist/src/index.js"
-    },
-    "./testing": {
-      "types": "./dist/src/testing/index.d.ts",
-      "default": "./dist/src/testing/index.js"
     }
   },
   "engines": {

packages/graphql/src/lib.ts

@@ -148,6 +148,12 @@ export const libDef = {
         default: paramMessage`Union variant type "${"type"}" appears multiple times after flattening nested unions. Duplicate removed.`,
       },
     },
+    "graphql-builtin-scalar-collision": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`Scalar "${"name"}" collides with GraphQL built-in type "${"builtinName"}". This may cause unexpected behavior. Consider renaming the scalar.`,
+      },
+    },
   },
   emitter: {
     options: EmitterOptionsSchema as JSONSchemaType<GraphQLEmitterOptions>,

packages/graphql/src/mutation-engine/mutations/scalar.ts

@@ -6,10 +6,37 @@ import {
   type SimpleMutationOptions,
   type SimpleMutations,
 } from "@typespec/mutator-framework";
+import { reportDiagnostic } from "../../lib.js";
 import { getScalarMapping, isStdScalar } from "../../lib/scalar-mappings.js";
 import { getSpecifiedBy, setSpecifiedByUrl } from "../../lib/specified-by.js";
 import { sanitizeNameForGraphQL } from "../../lib/type-utils.js";
 
+/**
+ * GraphQL built-in scalar type names.
+ * @see https://spec.graphql.org/September2025/#sec-Scalars.Built-in-Scalars
+ */
+const GRAPHQL_BUILTIN_SCALARS = new Set(["String", "Int", "Float", "Boolean", "ID"]);
+
+/**
+ * Check whether a scalar is the GraphQL library's `ID` scalar, or extends it.
+ * Walks the baseScalar chain looking for a scalar named "ID" in the
+ * TypeSpec.GraphQL namespace.
+ */
+function isGraphQLIdScalar(scalar: Scalar): boolean {
+  let current: Scalar | undefined = scalar;
+  while (current) {
+    if (
+      current.name === "ID" &&
+      current.namespace?.name === "GraphQL" &&
+      current.namespace?.namespace?.name === "TypeSpec"
+    ) {
+      return true;
+    }
+    current = current.baseScalar;
+  }
+  return false;
+}
+
 /** GraphQL-specific Scalar mutation */
 export class GraphQLScalarMutation extends SimpleScalarMutation<SimpleMutationOptions> {
   constructor(
@@ -28,7 +55,13 @@ export class GraphQLScalarMutation extends SimpleScalarMutation<SimpleMutationOp
     const mapping = getScalarMapping(program, this.sourceType);
     const isDirectStd = isStdScalar(tk, this.sourceType);
 
-    if (mapping && isDirectStd) {
+    if (isGraphQLIdScalar(this.sourceType)) {
+      // GraphQL library scalar ID (or extends it) → built-in GraphQL ID type
+      this.mutationNode.mutate((scalar) => {
+        scalar.name = "ID";
+        scalar.baseScalar = undefined;
+      });
+    } else if (mapping && isDirectStd) {
       // Std library scalar that maps to a custom GraphQL scalar (e.g. int64 → Long)
       this.mutationNode.mutate((scalar) => {
         scalar.name = mapping.graphqlName;
@@ -38,8 +71,16 @@ export class GraphQLScalarMutation extends SimpleScalarMutation<SimpleMutationOp
       // User-defined custom scalar — sanitize name, strip extends.
       // May still have a mapping via extends chain (e.g. scalar MyInt extends int64),
       // which is used for @specifiedBy below but not for renaming.
+      const sanitizedName = sanitizeNameForGraphQL(this.sourceType.name);
+      if (GRAPHQL_BUILTIN_SCALARS.has(sanitizedName)) {
+        reportDiagnostic(program, {
+          code: "graphql-builtin-scalar-collision",
+          target: this.sourceType,
+          format: { name: this.sourceType.name, builtinName: sanitizedName },
+        });
+      }
       this.mutationNode.mutate((scalar) => {
-        scalar.name = sanitizeNameForGraphQL(scalar.name);
+        scalar.name = sanitizedName;
         scalar.baseScalar = undefined;
       });
     }

packages/graphql/test/mutation-engine/graphql-mutation-engine.test.ts

@@ -301,6 +301,46 @@ describe("GraphQL Mutation Engine - Scalars", () => {
     );
   });
 
+  it("maps scalar extending GraphQL.ID to built-in ID type", async () => {
+    const { MyId } = await tester.compile(
+      t.code`scalar ${t.scalar("MyId")} extends GraphQL.ID;`,
+    );
+
+    const engine = createTestEngine(tester.program);
+    const mutation = engine.mutateScalar(MyId);
+
+    expect(mutation.mutatedType.name).toBe("ID");
+  });
+
+  it("maps multi-hop extends chain through GraphQL.ID to built-in ID type", async () => {
+    const { SubId } = await tester.compile(
+      t.code`
+        scalar MyId extends GraphQL.ID;
+        scalar ${t.scalar("SubId")} extends MyId;
+      `,
+    );
+
+    const engine = createTestEngine(tester.program);
+    const mutation = engine.mutateScalar(SubId);
+
+    expect(mutation.mutatedType.name).toBe("ID");
+  });
+
+  it("warns when user-defined scalar collides with GraphQL built-in name", async () => {
+    const { Float } = await tester.compile(
+      t.code`scalar ${t.scalar("Float")} extends string;`,
+    );
+
+    const engine = createTestEngine(tester.program);
+    engine.mutateScalar(Float);
+
+    const warnings = tester.program.diagnostics.filter(
+      (d) => d.code === "@typespec/graphql/graphql-builtin-scalar-collision",
+    );
+    expect(warnings.length).toBe(1);
+    expect(warnings[0].message).toContain("Float");
+  });
+
 });
 
 describe("GraphQL Mutation Engine - Edge Cases", () => {

packages/graphql/test/test-host.ts

@@ -1,85 +1,41 @@
-import { type Diagnostic, type Program, resolvePath, type Type } from "@typespec/compiler";
-import {
-  createTester,
-  createTestHost,
-  createTestWrapper,
-  expectDiagnosticEmpty,
-  resolveVirtualPath,
-} from "@typespec/compiler/testing";
+import { type Diagnostic, resolvePath } from "@typespec/compiler";
+import { createTester, expectDiagnosticEmpty } from "@typespec/compiler/testing";
 import { ok } from "assert";
 import type { GraphQLSchema } from "graphql";
 import { buildSchema } from "graphql";
 import { expect } from "vitest";
 import type { GraphQLEmitterOptions } from "../src/lib.js";
-import { GraphQLTestLibrary } from "../src/testing/index.js";
+
+const outputFileName = "schema.graphql";
 
 export const Tester = createTester(resolvePath(import.meta.dirname, ".."), {
-  libraries: [GraphQLTestLibrary.name],
+  libraries: ["@typespec/graphql"],
 })
   .importLibraries()
   .using("TypeSpec.GraphQL");
 
-export async function createGraphQLTestHost() {
-  return createTestHost({
-    libraries: [GraphQLTestLibrary],
-  });
-}
+export const EmitterTester = Tester.emit("@typespec/graphql");
 
 export interface GraphQLTestResult {
   readonly graphQLSchema?: GraphQLSchema;
   readonly graphQLOutput?: string;
   readonly diagnostics: readonly Diagnostic[];
 }
 
-export async function createGraphQLTestRunner() {
-  const host = await createGraphQLTestHost();
-
-  return createTestWrapper(host, {
-    autoUsings: ["TypeSpec.GraphQL"],
-    compilerOptions: {
-      noEmit: false,
-      emit: ["@typespec/graphql"],
-    },
-  });
-}
-
-export async function diagnose(code: string): Promise<readonly Diagnostic[]> {
-  const runner = await createGraphQLTestRunner();
-  return runner.diagnose(code);
-}
-
-export async function compileAndDiagnose<T extends Record<string, Type>>(
-  code: string,
-): Promise<[Program, T, readonly Diagnostic[]]> {
-  const runner = await createGraphQLTestRunner();
-  const [testTypes, diagnostics] = await runner.compileAndDiagnose(code);
-  return [runner.program, testTypes as T, diagnostics];
-}
-
 export async function emitWithDiagnostics(
   code: string,
   options: GraphQLEmitterOptions = {},
 ): Promise<readonly GraphQLTestResult[]> {
-  const runner = await createGraphQLTestRunner();
-  const outputFile = resolveVirtualPath("schema.graphql");
-  const compilerOptions = { ...options, "output-file": outputFile };
-  const diagnostics = await runner.diagnose(code, {
-    noEmit: false,
-    emit: ["@typespec/graphql"],
-    options: {
-      "@typespec/graphql": compilerOptions,
+  const outputFile = `{emitter-output-dir}/${outputFileName}`;
+  const [result, diagnostics] = await EmitterTester.compileAndDiagnose(code, {
+    compilerOptions: {
+      options: {
+        "@typespec/graphql": { ...options, "output-file": outputFile },
+      },
     },
   });
 
-  /**
-   * There doesn't appear to be a good way to hook into the emit process and get the GraphQLSchema
-   * that's produced by the emitter. So we're going to read the file that was emitted and parse it.
-   *
-   * This is the same way it's done in @typespec/openapi3:
-   * https://github.com/microsoft/typespec/blame/1cf8601d0f65f707926d58d56566fb0cb4d4f4ff/packages/openapi3/test/test-host.ts#L105
-   */
-
-  const content = runner.fs.get(outputFile);
+  const content = result.outputs[outputFileName];
   const schema = content
     ? buildSchema(content, {
         assumeValidSDL: true,