Add mutation engine for TypeSpec-to-GraphQL type transformation

Introduce a mutation engine that transforms TypeSpec types into
GraphQL-compatible forms using the mutator framework. Includes mutations
for enums, models, scalars, unions, and operations.

Also includes package hygiene: add tspMain, update node engine to >=20,
add api-extractor.json, CHANGELOG.md, fix testing casing, and clean up
dead code.

Author: FionaBronwen

packages/graphql/CHANGELOG.md

@@ -0,0 +1 @@
+# Change Log - @typespec/graphql

packages/graphql/api-extractor.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../api-extractor.base.json"
+}

packages/graphql/package.json

@@ -17,6 +17,7 @@
     "typespec"
   ],
   "type": "module",
+  "tspMain": "lib/main.tsp",
   "main": "dist/src/index.js",
   "exports": {
     ".": {
@@ -30,24 +31,23 @@
     }
   },
   "engines": {
-    "node": ">=18.0.0"
-  },
-  "graphql": {
-    "documents": "test/**/*.{js,ts}"
+    "node": ">=20.0.0"
   },
   "dependencies": {
     "@alloy-js/core": "^0.11.0",
     "@alloy-js/typescript": "^0.11.0",
+    "change-case": "^5.4.4",
     "graphql": "^16.9.0"
   },
   "scripts": {
     "clean": "rimraf ./dist ./temp",
     "build": "tsc -p .",
     "watch": "tsc --watch",
     "test": "vitest run",
+    "test:ci": "vitest run --coverage --reporter=junit --reporter=default",
     "test:watch": "vitest -w",
-    "lint": "eslint src/ test/ --report-unused-disable-directives --max-warnings=0",
-    "lint:fix": "eslint . --report-unused-disable-directives --fix"
+    "lint": "eslint . --max-warnings=0",
+    "lint:fix": "eslint . --fix"
   },
   "files": [
     "lib/*.tsp",
@@ -56,11 +56,16 @@
   ],
   "peerDependencies": {
     "@typespec/compiler": "workspace:~",
+    "@typespec/emitter-framework": "workspace:~",
     "@typespec/http": "workspace:~",
-    "@typespec/emitter-framework": "^0.5.0"
+    "@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

@@ -136,6 +136,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/interface.ts

@@ -11,6 +11,7 @@ import {
 import { useStateMap, useStateSet } from "@typespec/compiler/utils";
 import { GraphQLKeys, NAMESPACE, reportDiagnostic } from "../lib.js";
 import type { Tagged } from "../types.d.ts";
+import { propertiesEqual } from "./utils.js";
 
 // This will set the namespace for decorators implemented in this file
 export const namespace = NAMESPACE;
@@ -75,13 +76,6 @@ function validateNoCircularImplementation(
   return valid;
 }
 
-function propertiesEqual(prop1: ModelProperty, prop2: ModelProperty): boolean {
-  // TODO is there some canonical way to do this?
-  return (
-    prop1.name === prop2.name && prop1.type === prop2.type && prop1.optional === prop2.optional
-  );
-}
-
 function validateImplementsInterfaceProperties(
   context: DecoratorContext,
   modelProperties: Map<string, ModelProperty>,

packages/graphql/src/lib/operation-fields.ts

@@ -7,9 +7,6 @@ import {
   type Operation,
   type Program,
 } from "@typespec/compiler";
-
-// import { createTypeRelationChecker } from "../../../compiler/dist/src/core/type-relation-checker.js";
-
 import { useStateMap } from "@typespec/compiler/utils";
 import { GraphQLKeys, NAMESPACE, reportDiagnostic } from "../lib.js";
 import { operationsEqual } from "./utils.js";

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;
+}