feat(graphql): add input/output type splitting based on usage

- Update GraphQLMutationOptions with usageFlag and mutationKey
- GraphQLModelMutation adds 'Input' suffix for input types
- GraphQLMutationEngine.mutateModel() returns ModelMutationResult with
  separate input/output mutations based on resolveUsages()
- ModelTypeMap supports GraphQLInputObjectType for input types
- Schema emitter handles both input and output model variants
- Add 5 new tests for input/output splitting behavior

Author: FionaBronwen

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

@@ -1,10 +1,13 @@
 import {
+  resolveUsages,
+  UsageFlags,
   type Enum,
   type Model,
   type Namespace,
   type Operation,
   type Program,
   type Scalar,
+  type UsageTracker,
 } from "@typespec/compiler";
 import { $ } from "@typespec/compiler/typekit";
 import {
@@ -47,25 +50,74 @@ const graphqlMutationRegistry = {
   Intrinsic: SimpleIntrinsicMutation,
 };
 
+/**
+ * Result of mutating a model with usage awareness.
+ * Contains separate mutations for input and output variants when applicable.
+ */
+export interface ModelMutationResult {
+  /** The input variant mutation (with "Input" suffix), if the model is used as input */
+  input?: GraphQLModelMutation;
+  /** The output variant mutation (no suffix), if the model is used as output */
+  output?: GraphQLModelMutation;
+}
+
 /**
  * GraphQL mutation engine that applies GraphQL-specific transformations
- * to TypeSpec types, such as name sanitization.
+ * to TypeSpec types, such as name sanitization and input/output splitting.
  */
 export class GraphQLMutationEngine {
   /** The underlying mutation engine with custom GraphQL mutation classes */
   private engine;
 
-  constructor(program: Program, _namespace: Namespace) {
+  /** Usage tracker for types in the namespace */
+  private usageTracker: UsageTracker;
+
+  constructor(program: Program, namespace: Namespace) {
     const tk = $(program);
     this.engine = new MutationEngine(tk, graphqlMutationRegistry);
+
+    // Resolve usages once at construction time
+    this.usageTracker = resolveUsages(namespace);
   }
 
   /**
-   * Mutate a model, applying GraphQL name sanitization.
+   * Get the usage flags for a model.
    */
-  mutateModel(model: Model): GraphQLModelMutation {
-    const mutation = this.engine.mutate(model, new GraphQLMutationOptions());
-    return mutation as unknown as GraphQLModelMutation;
+  getUsage(model: Model): UsageFlags {
+    const isInput = this.usageTracker.isUsedAs(model, UsageFlags.Input);
+    const isOutput = this.usageTracker.isUsedAs(model, UsageFlags.Output);
+
+    if (isInput && isOutput) {
+      return UsageFlags.Input | UsageFlags.Output;
+    } else if (isInput) {
+      return UsageFlags.Input;
+    } else if (isOutput) {
+      return UsageFlags.Output;
+    }
+    return UsageFlags.None;
+  }
+
+  /**
+   * Mutate a model with usage awareness.
+   * Returns separate input/output mutations based on how the model is used.
+   */
+  mutateModel(model: Model): ModelMutationResult {
+    const usage = this.getUsage(model);
+    const result: ModelMutationResult = {};
+
+    // Create output mutation if used as output (or no usage info)
+    if (usage & UsageFlags.Output || usage === UsageFlags.None) {
+      const outputOptions = new GraphQLMutationOptions(UsageFlags.Output);
+      result.output = this.engine.mutate(model, outputOptions) as unknown as GraphQLModelMutation;
+    }
+
+    // Create input mutation if used as input
+    if (usage & UsageFlags.Input) {
+      const inputOptions = new GraphQLMutationOptions(UsageFlags.Input);
+      result.input = this.engine.mutate(model, inputOptions) as unknown as GraphQLModelMutation;
+    }
+
+    return result;
   }
 
   /**
@@ -102,4 +154,3 @@ export function createGraphQLMutationEngine(
 ): GraphQLMutationEngine {
   return new GraphQLMutationEngine(program, namespace);
 }
-

packages/graphql/src/mutation-engine/index.ts

@@ -1,4 +1,8 @@
-export { GraphQLMutationEngine, createGraphQLMutationEngine } from "./engine.js";
+export {
+  GraphQLMutationEngine,
+  createGraphQLMutationEngine,
+  type ModelMutationResult,
+} from "./engine.js";
 export {
   GraphQLEnumMemberMutation,
   GraphQLEnumMutation,

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

@@ -1,4 +1,4 @@
-import type { MemberType, Model } from "@typespec/compiler";
+import { UsageFlags, type MemberType, type Model } from "@typespec/compiler";
 import {
   SimpleModelMutation,
   type MutationInfo,
@@ -7,11 +7,15 @@ import {
   type SimpleMutations,
 } from "@typespec/mutator-framework";
 import { sanitizeNameForGraphQL } from "../../lib/type-utils.js";
+import type { GraphQLMutationOptions } from "../options.js";
 
 /**
  * GraphQL-specific Model mutation that sanitizes names for GraphQL compatibility.
+ * Adds "Input" suffix when the model is used as an input type.
  */
 export class GraphQLModelMutation extends SimpleModelMutation<SimpleMutationOptions> {
+  private graphqlOptions: GraphQLMutationOptions;
+
   constructor(
     engine: SimpleMutationEngine<SimpleMutations<SimpleMutationOptions>>,
     sourceType: Model,
@@ -20,12 +24,20 @@ export class GraphQLModelMutation extends SimpleModelMutation<SimpleMutationOpti
     info: MutationInfo,
   ) {
     super(engine as any, sourceType, referenceTypes, options, info);
+    this.graphqlOptions = options as GraphQLMutationOptions;
   }
 
   mutate() {
     // Apply GraphQL name sanitization
     this.mutationNode.mutate((model) => {
-      model.name = sanitizeNameForGraphQL(model.name);
+      let name = sanitizeNameForGraphQL(model.name);
+
+      // Add "Input" suffix for input types
+      if (this.graphqlOptions.usageFlag === UsageFlags.Input) {
+        name = `${name}Input`;
+      }
+
+      model.name = name;
     });
     super.mutate();
   }

packages/graphql/src/mutation-engine/options.ts

@@ -1,9 +1,35 @@
+import { UsageFlags } from "@typespec/compiler";
 import { SimpleMutationOptions } from "@typespec/mutator-framework";
 
 /**
  * GraphQL-specific mutation options.
  *
- * Currently a simple wrapper around SimpleMutationOptions.
- * Can be extended in the future to support additional GraphQL-specific options.
+ * Extends SimpleMutationOptions with usage-aware mutation key support,
+ * enabling separate mutations for input vs output type variants.
  */
-export class GraphQLMutationOptions extends SimpleMutationOptions {}
+export class GraphQLMutationOptions extends SimpleMutationOptions {
+  /**
+   * The usage flag indicating whether this mutation is for input or output usage.
+   * Used to generate separate mutations for the same type when used in both contexts.
+   */
+  readonly usageFlag: UsageFlags;
+
+  constructor(usageFlag: UsageFlags = UsageFlags.None) {
+    super();
+    this.usageFlag = usageFlag;
+  }
+
+  /**
+   * Override mutationKey to include usage flag.
+   * This ensures the mutation engine caches separate mutations for input vs output variants.
+   */
+  override get mutationKey(): string {
+    const baseKey = super.mutationKey;
+    if (this.usageFlag === UsageFlags.Input) {
+      return `${baseKey}:input`;
+    } else if (this.usageFlag === UsageFlags.Output) {
+      return `${baseKey}:output`;
+    }
+    return baseKey;
+  }
+}

packages/graphql/src/schema-emitter.ts

@@ -10,7 +10,10 @@ import {
 import { GraphQLSchema, validateSchema } from "graphql";
 import { type GraphQLEmitterOptions } from "./lib.js";
 import type { Schema } from "./lib/schema.js";
-import { createGraphQLMutationEngine, type GraphQLMutationEngine } from "./mutation-engine/index.js";
+import {
+  createGraphQLMutationEngine,
+  type GraphQLMutationEngine,
+} from "./mutation-engine/index.js";
 import { GraphQLTypeRegistry } from "./registry.js";
 
 class GraphQLSchemaEmitter {
@@ -64,19 +67,35 @@ class GraphQLSchemaEmitter {
         this.registry.addEnum(mutation.mutatedType);
       },
       model: (node: Model) => {
-        // Mutate the model (applies name sanitization)
-        const mutation = this.engine!.mutateModel(node);
-        this.registry.addModel(mutation.mutatedType);
+        // Mutate the model - returns input/output variants
+        const result = this.engine!.mutateModel(node);
+
+        // Register output variant if present
+        if (result.output) {
+          this.registry.addModel(result.output.mutatedType);
+        }
+
+        // Register input variant if present
+        if (result.input) {
+          this.registry.addModel(result.input.mutatedType);
+        }
       },
       exitEnum: (node: Enum) => {
         // Use mutated name for materialization
         const mutation = this.engine!.mutateEnum(node);
         this.registry.materializeEnum(mutation.mutatedType.name);
       },
       exitModel: (node: Model) => {
-        // Use mutated name for materialization
-        const mutation = this.engine!.mutateModel(node);
-        this.registry.materializeModel(mutation.mutatedType.name);
+        // Materialize both input and output variants
+        const result = this.engine!.mutateModel(node);
+
+        if (result.output) {
+          this.registry.materializeModel(result.output.mutatedType.name);
+        }
+
+        if (result.input) {
+          this.registry.materializeModel(result.input.mutatedType.name);
+        }
       },
     };
   }

packages/graphql/src/type-maps/model.ts

@@ -1,19 +1,24 @@
 import type { Model } from "@typespec/compiler";
 import {
+  GraphQLInputObjectType,
   GraphQLObjectType,
   GraphQLString,
   type GraphQLFieldConfigMap,
+  type GraphQLInputFieldConfigMap,
+  type GraphQLInputType,
+  type GraphQLNamedType,
   type GraphQLOutputType,
 } from "graphql";
 import { TypeMap, type TSPContext, type TypeKey } from "../type-maps.js";
 
 /**
- * TypeMap for converting TypeSpec Models to GraphQL ObjectTypes.
+ * TypeMap for converting TypeSpec Models to GraphQL ObjectTypes or InputObjectTypes.
  *
  * Handles registration of TSP models and lazy materialization into
- * GraphQLObjectType instances.
+ * GraphQLObjectType (for output) or GraphQLInputObjectType (for input).
+ * Input types are identified by names ending in "Input" (added by GraphQLModelMutation).
  */
-export class ModelTypeMap extends TypeMap<Model, GraphQLObjectType> {
+export class ModelTypeMap extends TypeMap<Model, GraphQLNamedType> {
   /**
    * Derives the type key from the context.
    * Uses graphqlName override if provided, otherwise uses the model's name.
@@ -23,18 +28,31 @@ export class ModelTypeMap extends TypeMap<Model, GraphQLObjectType> {
   }
 
   /**
-   * Materializes a TypeSpec Model into a GraphQL ObjectType.
+   * Materializes a TypeSpec Model into a GraphQL ObjectType or InputObjectType.
    */
-  protected materialize(context: TSPContext<Model>): GraphQLObjectType {
+  protected materialize(context: TSPContext<Model>): GraphQLNamedType {
     const tspModel = context.type;
     const name = context.graphqlName ?? tspModel.name;
 
+    // Determine if this is an input type based on name suffix
+    const isInput = name.endsWith("Input");
+
+    if (isInput) {
+      return this.materializeInputType(tspModel, name);
+    } else {
+      return this.materializeOutputType(tspModel, name);
+    }
+  }
+
+  /**
+   * Materialize as a GraphQLObjectType (output type).
+   */
+  private materializeOutputType(tspModel: Model, name: string): GraphQLObjectType {
     const fields: GraphQLFieldConfigMap<unknown, unknown> = {};
 
     for (const [propName, prop] of tspModel.properties) {
       fields[propName] = {
-        type: this.mapPropertyType(prop.type),
-        // TODO: Add description from doc comments
+        type: this.mapOutputType(prop.type),
       };
     }
 
@@ -44,11 +62,38 @@ export class ModelTypeMap extends TypeMap<Model, GraphQLObjectType> {
     });
   }
 
+  /**
+   * Materialize as a GraphQLInputObjectType (input type).
+   */
+  private materializeInputType(tspModel: Model, name: string): GraphQLInputObjectType {
+    const fields: GraphQLInputFieldConfigMap = {};
+
+    for (const [propName, prop] of tspModel.properties) {
+      fields[propName] = {
+        type: this.mapInputType(prop.type),
+      };
+    }
+
+    return new GraphQLInputObjectType({
+      name,
+      fields,
+    });
+  }
+
   /**
    * Map a TypeSpec property type to a GraphQL output type.
    * TODO: Implement full type mapping with references to other registered types.
    */
-  private mapPropertyType(_type: unknown): GraphQLOutputType {
+  private mapOutputType(_type: unknown): GraphQLOutputType {
+    // Placeholder - will need to resolve references to other types
+    return GraphQLString;
+  }
+
+  /**
+   * Map a TypeSpec property type to a GraphQL input type.
+   * TODO: Implement full type mapping with references to other registered types.
+   */
+  private mapInputType(_type: unknown): GraphQLInputType {
     // Placeholder - will need to resolve references to other types
     return GraphQLString;
   }