Add mutation engine for TypeSpec-to-GraphQL type transformation

Introduce a two-pass mutation architecture that transforms TypeSpec types
into GraphQL-compatible types before emission:

- Name sanitization (camelCase fields, PascalCase types, SCREAMING_SNAKE enums)
- GraphQL reserved keyword checking
- Scalar type mapping (TypeSpec scalars → GraphQL scalars/custom scalars)
- Numeric enum value conversion
- Nullable union unwrapping (T | null → nullable T)
- Union wrapper model generation for mixed unions
- Input type nullability handling

Includes shared utilities:
- src/lib/type-utils.ts: name helpers, nullable union detection
- src/lib/scalar-mappings.ts: TypeSpec-to-GraphQL scalar mapping table

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: FionaBronwen

packages/graphql/package.json

@@ -36,6 +36,7 @@
   "dependencies": {
     "@alloy-js/core": "^0.11.0",
     "@alloy-js/typescript": "^0.11.0",
+    "change-case": "^5.4.4",
     "graphql": "^16.9.0"
   },
   "scripts": {
@@ -56,13 +57,15 @@
   "peerDependencies": {
     "@typespec/compiler": "workspace:~",
     "@typespec/emitter-framework": "workspace:~",
-    "@typespec/http": "workspace:~"
+    "@typespec/http": "workspace:~",
+    "@typespec/mutator-framework": "workspace:~"
   },
   "devDependencies": {
     "@types/node": "~22.13.13",
     "@typespec/compiler": "workspace:~",
     "@typespec/emitter-framework": "workspace:~",
     "@typespec/http": "workspace:~",
+    "@typespec/mutator-framework": "workspace:~",
     "rimraf": "~6.0.1",
     "source-map-support": "~0.5.21",
     "typescript": "~5.8.2",

packages/graphql/src/index.ts

@@ -1,3 +1,5 @@
 export { $onEmit } from "./emitter.js";
 export { $lib } from "./lib.js";
 export { $decorators } from "./tsp-index.js";
+
+export { createGraphQLMutationEngine } from "./mutation-engine/index.js";

packages/graphql/src/lib.ts

@@ -108,6 +108,12 @@ export const libDef = {
         default: paramMessage`Property \`${"property"}\` is incompatible with \`${"interface"}\`.`,
       },
     },
+    "unrecognized-union": {
+      severity: "error",
+      messages: {
+        default: "Unrecognized union construction. Union must be named, a return type, a model property, or an alias.",
+      },
+    },
   },
   emitter: {
     options: EmitterOptionsSchema as JSONSchemaType<GraphQLEmitterOptions>,

packages/graphql/src/lib/scalar-mappings.ts

@@ -0,0 +1,191 @@
+import { type Program, type Scalar } from "@typespec/compiler";
+import { getEncode } from "@typespec/compiler";
+
+/**
+ * Represents a mapping from TypeSpec scalar to GraphQL custom scalar
+ */
+export interface ScalarMapping {
+  /** The GraphQL scalar name to emit */
+  graphqlName: string;
+  /** The base GraphQL type (String, Int, or Float) */
+  baseType: "String" | "Int" | "Float";
+  /** Optional URL to specification for @specifiedBy directive */
+  specificationUrl?: string;
+}
+
+/**
+ * Mapping table for TypeSpec standard library scalars to GraphQL custom scalars.
+ * Based on design doc: https://github.com/microsoft/typespec/issues/4933
+ */
+const SCALAR_MAPPINGS: Record<string, Record<string, ScalarMapping>> = {
+  // int64 → BigInt (String)
+  int64: {
+    default: {
+      graphqlName: "BigInt",
+      baseType: "String",
+    },
+  },
+
+  // numeric → Numeric (String)
+  numeric: {
+    default: {
+      graphqlName: "Numeric",
+      baseType: "String",
+    },
+  },
+
+  // decimal, decimal128 → BigDecimal (String)
+  decimal: {
+    default: {
+      graphqlName: "BigDecimal",
+      baseType: "String",
+    },
+  },
+  decimal128: {
+    default: {
+      graphqlName: "BigDecimal",
+      baseType: "String",
+    },
+  },
+
+  // bytes with different encodings
+  bytes: {
+    base64: {
+      graphqlName: "Bytes",
+      baseType: "String",
+      specificationUrl: "https://datatracker.ietf.org/doc/html/rfc4648",
+    },
+    base64url: {
+      graphqlName: "BytesUrl",
+      baseType: "String",
+      specificationUrl: "https://datatracker.ietf.org/doc/html/rfc4648",
+    },
+  },
+
+  // utcDateTime with different encodings
+  utcDateTime: {
+    rfc3339: {
+      graphqlName: "UTCDateTime",
+      baseType: "String",
+      specificationUrl: "https://datatracker.ietf.org/doc/html/rfc3339",
+    },
+    rfc7231: {
+      graphqlName: "UTCDateTimeHuman",
+      baseType: "String",
+      specificationUrl: "https://datatracker.ietf.org/doc/html/rfc7231",
+    },
+    unixTimestamp: {
+      graphqlName: "UTCDateTimeUnix",
+      baseType: "Int",
+    },
+  },
+
+  // offsetDateTime with different encodings
+  offsetDateTime: {
+    rfc3339: {
+      graphqlName: "OffsetDateTime",
+      baseType: "String",
+      specificationUrl: "https://datatracker.ietf.org/doc/html/rfc3339",
+    },
+    rfc7231: {
+      graphqlName: "OffsetDateTimeHuman",
+      baseType: "String",
+      specificationUrl: "https://datatracker.ietf.org/doc/html/rfc7231",
+    },
+    unixTimestamp: {
+      graphqlName: "OffsetDateTimeUnix",
+      baseType: "Int",
+    },
+  },
+
+  // unixTimestamp32 → OffsetDateTimeUnix (Int)
+  unixTimestamp32: {
+    default: {
+      graphqlName: "OffsetDateTimeUnix",
+      baseType: "Int",
+    },
+  },
+
+  // duration with different encodings
+  duration: {
+    ISO8601: {
+      graphqlName: "Duration",
+      baseType: "String",
+      specificationUrl: "https://www.iso.org/standard/70907.html",
+    },
+    seconds: {
+      graphqlName: "DurationSeconds",
+      baseType: "Int", // Could be Float based on context, defaulting to Int
+    },
+  },
+
+  // plainDate → PlainDate (String)
+  plainDate: {
+    default: {
+      graphqlName: "PlainDate",
+      baseType: "String",
+    },
+  },
+
+  // plainTime → PlainTime (String)
+  plainTime: {
+    default: {
+      graphqlName: "PlainTime",
+      baseType: "String",
+    },
+  },
+
+  // url → URL (String)
+  url: {
+    default: {
+      graphqlName: "URL",
+      baseType: "String",
+      specificationUrl: "https://url.spec.whatwg.org/",
+    },
+  },
+
+  // unknown → Unknown (String)
+  unknown: {
+    default: {
+      graphqlName: "Unknown",
+      baseType: "String",
+    },
+  },
+};
+
+/**
+ * Get the GraphQL scalar mapping for a TypeSpec scalar.
+ * Returns undefined if the scalar should be emitted as-is (custom scalar).
+ *
+ * @param program The TypeSpec program
+ * @param scalar The scalar type to map
+ * @param encoding Optional encoding to use instead of checking @encode on the scalar
+ * @returns The scalar mapping or undefined if no mapping exists
+ */
+export function getScalarMapping(
+  program: Program,
+  scalar: Scalar,
+  encoding?: string
+): ScalarMapping | undefined {
+  // Only map standard library scalars, not user-defined ones
+  if (!program.checker.isStdType(scalar)) {
+    return undefined;
+  }
+
+  const scalarName = scalar.name;
+  const mappingTable = SCALAR_MAPPINGS[scalarName];
+
+  if (!mappingTable) {
+    return undefined;
+  }
+
+  // Use provided encoding, or check for @encode decorator on the scalar
+  const actualEncoding = encoding ?? getEncode(program, scalar)?.encoding;
+
+  if (actualEncoding && mappingTable[actualEncoding]) {
+    return mappingTable[actualEncoding];
+  }
+
+  // Fall back to default mapping
+  return mappingTable.default;
+}