[graphql] Add @typespec/graphql emitter

[FionaBronwen]

Summary

This PR introduces @typespec/graphql, a new emitter that generates GraphQL SDL (Schema Definition Language) from TypeSpec definitions.

Features

• Schema generation: Emit complete GraphQL schemas from TypeSpec models and operations
• Operation types: Support for @query, @mutation, and @subscription decorators
• Interface composition: Use @Interface and @compose for GraphQL interface inheritance
  patterns
• Visibility filtering: Automatic input/output type generation based on @visibility decorators
• Custom scalars: @specifiedBy decorator for custom scalar URL specifications
• Schema customization: @schema decorator for multi-schema scenarios

Architecture

The emitter uses a two-phase approach:

1. Mutation phase: Transforms TypeSpec types into GraphQL-compatible structures using the mutator framework, handling visibility filtering, naming conventions, and type deduplication
2. Render phase: Uses @alloy-js/graphql components to emit the final SDL output

Example

import "@typespec/graphql";

using TypeSpec.GraphQL;

@query
op getUser(@path id: string): User;

@mutation
op createUser(input: User): User;

model User {
  id: string;
  name: string;
  email: string;
}

Generates:

  type Query {
    getUser(id: String!): User!
  }

  type Mutation {
    createUser(input: UserInput!): User!
  }

  type User {
    id: String!
    name: String!
    email: String!
  }

  input UserInput {
    name: String!
    email: String!
  }

Test plan

• Unit tests for all decorators and components (318 tests passing)
• E2E tests covering schema generation scenarios
• Mutation engine tests for type transformation logic

Notes

• This emitter depends on @alloy-js/graphql which is pending publication
• Tracked in GitHub issue GraphQL Emitter Design #4933

[timotheeguerin]

The way those decorators are implemented kinda goes against the philosphy of those decorators(shouldn't really have to check the .decorators list unless there is a feature gap in the compiler)

Any reason to do that over using the stateMap/stateSet(and potentially as mentioned in another comment the upcomming auto decorators?)

[FionaBronwen]

The @nullable decorator is applied programmatically by the mutation engine after stripping | null variants from unions. (In GraphQL, unions don't have null variants, they just become null themselves.) We check .decorators rather than stateMap because we need the state to travel with cloned types. stateMap entries point to the original type objects and would be lost after cloning during mutation. Keeping this information alongside the cloned type via a decorator, enables mutation engine chaining where each mutation phase can work on the transformed output of the previous one and still contain the nullability context.

Since auto decorators #10197 use stateMap I think we'd run into the same issue. Happy to discuss if there's a better pattern that still allows us to chain together mutation stages without auxiliary data to pass around!

[timotheeguerin]

I see the $lib contains a few error diagnostics but you don't have any onValidate. Ideally we'd like to have emitters try to not emit erors. In your care this is of course both a library providing protocol bindings and an emitter but it would be ideal if the protocol validation was able to be done in the $onValidate. This would ensure that the spec is checked regardless of if the emitter is run

[FionaBronwen]

Added $onValidate with the validations that can run before the mutation engine:

• empty-schema - no @query/@mutation/@subscription operations
• empty-enum - enum with no values
• empty-union - union with no non-null variants
• reserved-name - names starting with __

The remaining diagnostics (type-name-collision, ,
duplicate-union-variant, unrecognized-union) have to stay in $onEmit because they depend on transformations the mutation engine performs (name resolution, union flattening, etc.) which I think would be too heavyweight to run $onValidate.