Add @schema decorator to mark namespaces as GraphQL schemas

Using the `TypeSpec.GraphQL.@schema` decorator on a namespace indicates that the decorated namespace represents a GraphQL schema that should be generated by the GraphQL emitter.

Because this allows for multiple schemas to be specified in a TypeSpec source, our test host is reworked to provide a `GraphQLTestResult` corresponding to each schema produced.

This commit does not actually implement any emitter functionality, but populates a state map that will be used by the emitter in the future.

Author: steverice

packages/graphql/lib/main.tsp

@@ -0,0 +1 @@
+import "./schema.tsp";

packages/graphql/lib/schema.tsp

@@ -0,0 +1,23 @@
+import "../dist/src/lib/schema.js";
+
+using TypeSpec.Reflection;
+
+namespace TypeSpec.GraphQL;
+
+namespace Schema {
+  model SchemaOptions {
+    name?: string;
+  }
+}
+
+/**
+ * Mark this namespace as describing a GraphQL schema and configure schema properties.
+ *
+ * @example
+ *
+ * ```typespec
+ * @schema(#{name: "MySchema"})
+ * namespace MySchema {};
+ * ```
+ */
+extern dec schema(target: Namespace, options?: valueof Schema.SchemaOptions);

packages/graphql/package.json

@@ -20,6 +20,7 @@
   "main": "dist/src/index.js",
   "exports": {
     ".": {
+      "typespec": "./lib/main.tsp",
       "types": "./dist/src/index.d.ts",
       "default": "./dist/src/index.js"
     },
@@ -31,6 +32,12 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "graphql": {
+    "documents": "test/**/*.{js,ts}"
+  },
+  "dependencies": {
+    "graphql": "^16.9.0"
+  },
   "scripts": {
     "clean": "rimraf ./dist ./temp",
     "build": "tsc",

packages/graphql/src/index.ts

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

packages/graphql/src/lib.ts

@@ -1,5 +1,7 @@
 import { createTypeSpecLibrary, type JSONSchemaType } from "@typespec/compiler";
 
+export const NAMESPACE = "TypeSpec.GraphQL";
+
 export interface GraphQLEmitterOptions {
   /**
    * Name of the output file.
@@ -95,8 +97,11 @@ export const libDef = {
   emitter: {
     options: EmitterOptionsSchema as JSONSchemaType<GraphQLEmitterOptions>,
   },
+  state: {
+    schema: { description: "State for the @schema decorator." },
+  },
 } as const;
 
 export const $lib = createTypeSpecLibrary(libDef);
 
-export const { reportDiagnostic, createDiagnostic } = $lib;
+export const { reportDiagnostic, createDiagnostic, stateKeys: GraphQLKeys } = $lib;

packages/graphql/src/lib/schema.ts

@@ -0,0 +1,77 @@
+import {
+  type DecoratorContext,
+  type DecoratorFunction,
+  type Namespace,
+  type Program,
+  validateDecoratorUniqueOnNode,
+} from "@typespec/compiler";
+
+import { GraphQLKeys, NAMESPACE } from "../lib.js";
+import { useStateMap } from "./state-map.js";
+
+// This will set the namespace for decorators implemented in this file
+export const namespace = NAMESPACE;
+
+export interface SchemaDetails {
+  name?: string;
+}
+
+export interface Schema extends SchemaDetails {
+  type: Namespace;
+}
+
+const [getSchema, setSchema, getSchemaMap] = useStateMap<Namespace, Schema>(GraphQLKeys.schema);
+
+/**
+ * List all the schemas defined in the TypeSpec program
+ * @param program Program
+ * @returns List of schemas.
+ */
+export function listSchemas(program: Program): Schema[] {
+  return [...getSchemaMap(program).values()];
+}
+
+export {
+  /**
+   * Get the schema information for the given namespace.
+   * @param program Program
+   * @param namespace Schema namespace
+   * @returns Schema information or undefined if namespace is not a schema namespace.
+   */
+  getSchema,
+};
+
+/**
+ * Check if the namespace is defined as a schema.
+ * @param program Program
+ * @param namespace Namespace
+ * @returns Boolean
+ */
+export function isSchema(program: Program, namespace: Namespace): boolean {
+  return getSchemaMap(program).has(namespace);
+}
+
+/**
+ * Mark the given namespace as a schema.
+ * @param program Program
+ * @param namespace Namespace
+ * @param details Schema details
+ */
+export function addSchema(
+  program: Program,
+  namespace: Namespace,
+  details: SchemaDetails = {},
+): void {
+  const schemaMap = getSchemaMap(program);
+  const existing = schemaMap.get(namespace) ?? {};
+  setSchema(program, namespace, { ...existing, ...details, type: namespace });
+}
+
+export const $schema: DecoratorFunction = (
+  context: DecoratorContext,
+  target: Namespace,
+  options: SchemaDetails = {},
+) => {
+  validateDecoratorUniqueOnNode(context, target, $schema);
+  addSchema(context.program, target, options);
+};

packages/graphql/src/lib/state-map.ts

@@ -0,0 +1,10 @@
+import type { Type } from "@typespec/compiler";
+import { unsafe_useStateMap, unsafe_useStateSet } from "@typespec/compiler/experimental";
+
+export function useStateMap<K extends Type, V>(key: symbol) {
+  return unsafe_useStateMap<K, V>(key);
+}
+
+export function useStateSet<K extends Type>(key: symbol) {
+  return unsafe_useStateSet<K>(key);
+}

packages/graphql/src/schema-emitter.ts

@@ -18,7 +18,7 @@ export function createGraphQLEmitter(
       const filePath = interpolatePath(options.outputFile, { "schema-name": "schema" });
       await emitFile(program, {
         path: filePath,
-        content: "Hello world",
+        content: "",
         newLine: options.newLine,
       });
     }

packages/graphql/src/tsp-index.ts

@@ -0,0 +1,9 @@
+import type { DecoratorImplementations } from "@typespec/compiler";
+import { NAMESPACE } from "./lib.js";
+import { $schema } from "./lib/schema.js";
+
+export const $decorators: DecoratorImplementations = {
+  [NAMESPACE]: {
+    schema: $schema,
+  },
+};

packages/graphql/src/types.d.ts

@@ -0,0 +1,18 @@
+import type { Diagnostic } from "@typespec/compiler";
+import type { GraphQLSchema } from "graphql";
+import type { Schema } from "./lib/schema.ts";
+
+/**
+ * A record containing the GraphQL schema corresponding to
+ * a particular schema definition.
+ */
+export interface GraphQLSchemaRecord {
+  /** The declared schema that generated this GraphQL schema */
+  readonly schema: Schema;
+
+  /** The GraphQLSchema */
+  readonly graphQLSchema: GraphQLSchema;
+
+  /** The diagnostics created for this schema */
+  readonly diagnostics: readonly Diagnostic[];
+}