@znight/graphql 0.0.0-stage → 0.2.0

package/src/compiler/generate.ts

@@ -0,0 +1,405 @@
+/**
+ * `generate` of the graphql extension (RFC 0005 §7.1, §7.3): `metadata.extensions.graphql` from the
+ * model `validate` built, and the SDL artifact when the extension is configured with `{ sdl }`.
+ *
+ * Data, not code, except `invoke`: one arrow per resolver field mapping the graphql-js arguments to
+ * the method parameters. It is synchronous unless an argument is validated with a Standard Schema
+ * whose validation turns out asynchronous: like the `invoke` of `@znight/http` routes, a
+ * synchronous validation (Zod, Valibot, ArkType without async refinements) costs no promise.
+ *
+ * ```ts
+ * ['invoke']: (r: BookResolver, p: unknown, _a: GraphQLArgs, c: GraphQLContext) =>
+ *   r.author(p as never, c.loader('src/authors-by-id.loader.ts#AuthorsById') as never),
+ * ```
+ */
+
+import type { GenerateContext, GenInput, GenNode, GenParam } from '@znight/compiler'
+import type { Token } from '@znight/core'
+import type { MetaEntry } from '@znight/http/compiler'
+import type { FieldData, GraphQLData, ParamData, ResolverData } from './data.ts'
+import type { ArgModel, FieldModel, GraphQLModel, TypeModel } from './model.ts'
+import type { ResolvedGraphQLCompilerOptions } from './options.ts'
+
+import { GRAPHQL_METADATA_VERSION } from '../metadata.ts'
+import { compareStrings } from './constants.ts'
+import { RUNTIME_MODULE } from './ids.ts'
+
+type Context = GenerateContext<GraphQLData>
+
+/** Module of `isThenable` (a required peer of `@znight/graphql`). */
+const HTTP_MODULE = '@znight/http'
+
+/** Imports created on first use: an unused import would break `noUnusedLocals`. */
+interface Imports {
+  argsType(): GenNode
+  contextType(): GenNode
+  infoType(): GenNode
+  validateArgs(): GenNode
+  isThenable(): GenNode
+  hostType(identity: string): GenNode
+}
+
+/** Builds the graphql section; `undefined` (no section) when the application has no resolver. */
+export function generateGraphQL(
+  ctx: Context,
+  model: GraphQLModel | undefined,
+  options: ResolvedGraphQLCompilerOptions,
+): GenNode | undefined {
+  if (model === undefined) return undefined
+  if (options.sdl !== false) ctx.emitFile(options.sdl, `${model.sdl}\n`)
+  const imports = createImports(ctx)
+  const entries: [string, GenInput][] = [
+    ['version', ctx.lit(GRAPHQL_METADATA_VERSION)],
+    ['schemaHash', model.schemaHash],
+    ['roots', ctx.obj(Object.entries(model.roots))],
+    ['types', ctx.arr(model.types.map(type => typeNode(ctx, imports, type)))],
+  ]
+  const groups = groupsNode(ctx, model.meta)
+  if (groups !== undefined) entries.push(['groups', groups])
+  return ctx.obj(entries)
+}
+
+function createImports(ctx: Context): Imports {
+  let args: GenNode | undefined
+  let context: GenNode | undefined
+  let info: GenNode | undefined
+  let validateArgs: GenNode | undefined
+  let isThenable: GenNode | undefined
+  const hosts = new Map<string, GenNode>()
+  return {
+    argsType: () => {
+      args ??= ctx.importFrom(RUNTIME_MODULE, 'GraphQLArgs', { type: true })
+      return args
+    },
+    contextType: () => {
+      context ??= ctx.importFrom(RUNTIME_MODULE, 'GraphQLContext', { type: true })
+      return context
+    },
+    infoType: () => {
+      info ??= ctx.importFrom('graphql', 'GraphQLResolveInfo', { type: true })
+      return info
+    },
+    validateArgs: () => {
+      validateArgs ??= ctx.importFrom(RUNTIME_MODULE, 'validateArgs')
+      return validateArgs
+    },
+    isThenable: () => {
+      isThenable ??= ctx.importFrom(HTTP_MODULE, 'isThenable')
+      return isThenable
+    },
+    hostType: identity => {
+      let node = hosts.get(identity)
+      if (node === undefined) {
+        node = ctx.importType(identity)
+        hosts.set(identity, node)
+      }
+      return node
+    },
+  }
+}
+
+function typeNode(ctx: Context, imports: Imports, type: TypeModel): GenNode {
+  const head: [string, GenInput][] = [
+    ['kind', type.kind],
+    ['name', type.name],
+  ]
+  if (type.description !== undefined && type.kind !== 'scalar') head.push(['description', type.description])
+  switch (type.kind) {
+    case 'object':
+      return ctx.obj([...head, ['fields', ctx.arr(type.fields.map(field => fieldNode(ctx, imports, field)))]])
+    case 'input':
+      return ctx.obj([...head, ['fields', ctx.arr(type.fields.map(field => inputValueNode(ctx, field)))]])
+    case 'enum':
+      return ctx.obj([
+        ...head,
+        [
+          'values',
+          ctx.arr(
+            type.values.map(value => {
+              const entries: [string, GenInput][] = [
+                ['name', value.name],
+                ['value', value.value],
+              ]
+              if (value.description !== undefined) entries.push(['description', value.description])
+              if (value.deprecationReason !== undefined) entries.push(['deprecationReason', value.deprecationReason])
+              return ctx.obj(entries)
+            }),
+          ),
+        ],
+      ])
+    case 'union': {
+      const discriminator = type.discriminator
+      let node: GenNode
+      if (discriminator === undefined || discriminator.by === 'typename') node = ctx.obj([['by', 'typename']])
+      else if (discriminator.by === 'property') {
+        node = ctx.obj([
+          ['by', 'property'],
+          ['property', discriminator.property],
+          ['values', ctx.obj(Object.entries(discriminator.values))],
+        ])
+      } else {
+        node = ctx.obj([
+          ['by', 'class'],
+          [
+            'classes',
+            ctx.arr(discriminator.classes.map(entry => ctx.arr([ctx.importValue(entry.identity), entry.name]))),
+          ],
+        ])
+      }
+      return ctx.obj([...head, ['members', ctx.lit([...type.members])], ['discriminator', node]])
+    }
+    case 'scalar':
+      // built-in scalars carry no description (the runtime builds them, sdl.ts prints them alike);
+      // user scalars bring theirs with the imported definition
+      return type.definition === undefined
+        ? ctx.obj([...head, ['builtin', ctx.lit(true)]])
+        : ctx.obj([...head, ['scalar', ctx.importValue(type.definition)]])
+  }
+}
+
+function fieldNode(ctx: Context, imports: Imports, field: FieldModel): GenNode {
+  const entries: [string, GenInput][] = [
+    ['name', field.name],
+    ['type', field.type],
+  ]
+  if (field.description !== undefined) entries.push(['description', field.description])
+  if (field.deprecationReason !== undefined) entries.push(['deprecationReason', field.deprecationReason])
+  if (field.args.length > 0) entries.push(['args', ctx.arr(field.args.map(arg => inputValueNode(ctx, arg)))])
+  if (field.binding !== undefined) {
+    entries.push(['resolver', resolverNode(ctx, imports, field.binding.resolver, field.binding.field)])
+  }
+  return ctx.obj(entries)
+}
+
+function inputValueNode(ctx: Context, arg: ArgModel): GenNode {
+  const entries: [string, GenInput][] = [
+    ['name', arg.name],
+    ['type', arg.type],
+  ]
+  if (arg.description !== undefined) entries.push(['description', arg.description])
+  if (arg.deprecationReason !== undefined) entries.push(['deprecationReason', arg.deprecationReason])
+  if (arg.defaultValue !== undefined) entries.push(['defaultValue', ctx.lit(arg.defaultValue as never)])
+  if (arg.nullAsUndefined) entries.push(['nullAsUndefined', ctx.lit(true)])
+  return ctx.obj(entries)
+}
+
+function resolverNode(ctx: Context, imports: Imports, resolver: ResolverData, field: FieldData): GenNode {
+  const guards = [...resolver.guards, ...field.guards].map(ref => ctx.tokenOf(ref) ?? ref.token)
+  const entries: [string, GenInput][] = [
+    ['token', ctx.tokenOf(resolver.host) ?? resolver.host.identity],
+    ['method', field.method],
+    ['operation', field.operation],
+    ['guards', ctx.lit(guards)],
+    ['meta', ctx.obj(field.meta.map(entry => [entry.key, ctx.lit(entry.value as never)] as const))],
+  ]
+  const loaders = field.params.flatMap(param => (param?.kind === 'loader' ? [loaderToken(ctx, param)] : []))
+  if (loaders.length > 0) entries.push(['loaders', ctx.lit(loaders)])
+  entries.push(['invoke', invokeNode(ctx, imports, resolver, field)])
+  return ctx.obj(entries)
+}
+
+/** The provider token a loader parameter is bound to. */
+function loaderToken(ctx: Context, param: Extract<ParamData, { kind: 'loader' }>): Token {
+  const ref = ctx.binding(param.binding)
+  if (typeof ref === 'string') return ref
+  if (ref !== undefined && 'token' in ref) return ref.token
+  return param.identity
+}
+
+// ------------------------------------------------------------------------------------------- invoke
+
+/** Which `invoke` parameters a field uses: `(r, p, a, c, i)`. */
+function usedParameters(field: FieldData): readonly [p: boolean, a: boolean, c: boolean, i: boolean] {
+  let p = false
+  let a = false
+  let c = false
+  let i = false
+  for (const param of field.params) {
+    switch (param?.kind) {
+      case 'parent':
+        p = true
+        break
+      case 'args':
+        a = true
+        break
+      case 'ctx':
+      case 'loader':
+        c = true
+        break
+      case 'info':
+        i = true
+        break
+    }
+  }
+  return [p, a, c, i]
+}
+
+/**
+ * `(r: Resolver, p: unknown, a: GraphQLArgs, c: GraphQLContext, i: GraphQLResolveInfo) => r.m(...)`:
+ * unused middle parameters are `_`-prefixed, trailing ones omitted (`noUnusedParameters`).
+ */
+function invokeNode(ctx: Context, imports: Imports, resolver: ResolverData, field: FieldData): GenNode {
+  const used = usedParameters(field)
+  const last = used.lastIndexOf(true)
+  const types = [() => ctx.code`unknown`, imports.argsType, imports.contextType, imports.infoType]
+  const names = ['p', 'a', 'c', 'i']
+  const params: [string, GenNode][] = [['r', imports.hostType(resolver.host.identity)]]
+  for (let index = 0; index <= last; index++) {
+    params.push([`${used[index] ? '' : '_'}${names[index] as string}`, (types[index] as () => GenNode)()])
+  }
+  const validated = field.params.flatMap((param, index) =>
+    param?.kind === 'args' && param.schema !== undefined ? [index] : [],
+  )
+  return ctx.arrow(params, (r, ...rest) => {
+    const [p, a, c, i] = rest as (GenParam | undefined)[]
+    const scope: Scope = { p, a, c, i }
+    if (validated.length === 0) return call(ctx, r, field, index => argument(ctx, scope, field, index))
+    return validatingBlock(ctx, imports, r, scope, field, validated)
+  })
+}
+
+/** The parameters of the `invoke` arrow (absent when not declared). */
+interface Scope {
+  readonly p: GenNode | undefined
+  readonly a: GenNode | undefined
+  readonly c: GenNode | undefined
+  readonly i: GenNode | undefined
+}
+
+/** `r.method(args)`. */
+function call(ctx: Context, r: GenNode, field: FieldData, argumentOf: (index: number) => GenNode): GenNode {
+  return ctx.call(
+    ctx.member(r, field.method),
+    field.params.map((_, index) => argumentOf(index)),
+  )
+}
+
+/** The expression passed for the parameter `index` (validation not applied). */
+function argument(ctx: Context, scope: Scope, field: FieldData, index: number): GenNode {
+  const param = field.params[index]
+  switch (param?.kind) {
+    case 'parent':
+      return ctx.code`${scope.p as GenNode} as never`
+    case 'ctx':
+      return scope.c as GenNode
+    case 'info':
+      return scope.i as GenNode
+    case 'loader':
+      return ctx.code`${ctx.call(ctx.member(scope.c as GenNode, 'loader'), [loaderToken(ctx, param)])} as never`
+    case 'args':
+      return ctx.code`${argsValue(ctx, scope, param.name)} as never`
+    default:
+      return ctx.lit(undefined)
+  }
+}
+
+/** `a['name']`, or `a` for `@Args()`. */
+function argsValue(ctx: Context, scope: Scope, name: string | undefined): GenNode {
+  const a = scope.a as GenNode
+  return name === undefined ? a : ctx.code`${a}[${name}]`
+}
+
+/** `validateArgs(Schema, a['input'], 'input')`. */
+function validation(
+  ctx: Context,
+  imports: Imports,
+  scope: Scope,
+  param: Extract<ParamData, { kind: 'args' }>,
+): GenNode {
+  return ctx.call(imports.validateArgs(), [
+    ctx.ref(param.schema as NonNullable<typeof param.schema>),
+    argsValue(ctx, scope, param.name),
+    param.name ?? 'args',
+  ])
+}
+
+/**
+ * The body of the `invoke` of a field validating arguments: each validation is evaluated in order
+ * into a `const`; while they return values the method is called synchronously, the first thenable
+ * resumes in an `async` arrow that awaits it and the later validations (the order of evaluation and
+ * the error reported first are those of an `async` invoke awaiting every validation).
+ *
+ * ```ts
+ * (r: BookResolver, _p: unknown, a: GraphQLArgs) => {
+ *   const v0 = validateArgs(NewBookInput, a['input'], 'input')
+ *   if (isThenable(v0)) return (async () => r.addBook(await v0 as never))()
+ *   return r.addBook(v0 as never)
+ * }
+ * ```
+ */
+function validatingBlock(
+  ctx: Context,
+  imports: Imports,
+  r: GenNode,
+  scope: Scope,
+  field: FieldData,
+  validated: readonly number[],
+): GenNode {
+  return ctx.block(
+    validated.map(index => `v${index}`),
+    (...locals) => {
+      const local = new Map(validated.map((index, position) => [index, locals[position] as GenNode]))
+      const statements: GenNode[] = []
+      for (const index of validated) {
+        const name = local.get(index) as GenNode
+        const param = field.params[index] as Extract<ParamData, { kind: 'args' }>
+        statements.push(ctx.code`const ${name} = ${validation(ctx, imports, scope, param)}`)
+        const resume = ctx.arrow(
+          [],
+          () =>
+            call(ctx, r, field, position => {
+              const value = local.get(position)
+              if (value === undefined) return argument(ctx, scope, field, position)
+              if (position < index) return ctx.code`${value} as never`
+              if (position === index) return ctx.code`await ${value} as never`
+              const later = field.params[position] as Extract<ParamData, { kind: 'args' }>
+              return ctx.code`await ${validation(ctx, imports, scope, later)} as never`
+            }),
+          { async: true },
+        )
+        statements.push(ctx.code`if (${ctx.call(imports.isThenable(), [name])}) return (${resume})()`)
+      }
+      statements.push(
+        ctx.code`return ${call(ctx, r, field, position => {
+          const value = local.get(position)
+          return value === undefined ? argument(ctx, scope, field, position) : ctx.code`${value} as never`
+        })}`,
+      )
+      return statements
+    },
+  )
+}
+
+// ------------------------------------------------------------------------------------------- groups
+
+/**
+ * `groups`: the route decorator groups the runtime needs (required, holding several keys, or named
+ * differently from their key), sorted; `undefined` when there is none (RFC 0001, as `extensions.http`).
+ */
+function groupsNode(ctx: Context, meta: readonly MetaEntry[]): GenNode | undefined {
+  const groups = new Map<string, { readonly keys: Set<string>; required: boolean }>()
+  for (const entry of meta) {
+    const group = groups.get(entry.group)
+    if (group === undefined) groups.set(entry.group, { keys: new Set([entry.key]), required: entry.required })
+    else {
+      group.keys.add(entry.key)
+      group.required ||= entry.required
+    }
+  }
+  const needed = [...groups]
+    .filter(([name, group]) => group.required || group.keys.size > 1 || !group.keys.has(name))
+    .sort(([a], [b]) => compareStrings(a, b))
+  if (needed.length === 0) return undefined
+  return ctx.obj(
+    needed.map(
+      ([name, group]) =>
+        [
+          name,
+          ctx.obj([
+            ['keys', ctx.lit([...group.keys].sort(compareStrings))],
+            ['required', group.required],
+          ]),
+        ] as const,
+    ),
+  )
+}

package/src/compiler/ids.ts

@@ -0,0 +1,128 @@
+/**
+ * Canonical identities the `@znight/graphql` compiler extension recognises (RFC 0005 §5.14,
+ * §6.2, §6.5): its decorators, `scalar<T>()`, the scalar aliases, the loader and context types, and
+ * the look-alike decorators of `@znight/http` it reports (ZNIGHT005).
+ *
+ * Constants only: this module must stay free of runtime imports (the compiler loads the extension
+ * entry, which must never load the GraphQL runtime, graphql-js or dataloader).
+ */
+
+/** Package name: the prefix of every identity below. */
+export const GRAPHQL_PACKAGE = '@znight/graphql'
+
+/** Name of the extension, also the key of `metadata.extensions.graphql`. */
+export const EXTENSION_NAME = 'graphql'
+
+/** Module the generated code imports its runtime helpers and types from. */
+export const RUNTIME_MODULE = '@znight/graphql'
+
+/** Canonical identities of the exports of `@znight/graphql` the compiler reads. */
+export const GraphQLIds: {
+  /** `@Resolver(options?)`, class decorator. */
+  readonly Resolver: string
+  /** `@Query(name?)`, method decorator. */
+  readonly Query: string
+  /** `@Mutation(name?)`, method decorator. */
+  readonly Mutation: string
+  /** `@Subscription(name?)`, method decorator. */
+  readonly Subscription: string
+  /** `@ResolveField(name?)`, method decorator. */
+  readonly ResolveField: string
+  /** `@Args(nameOrSchema?, schema?)`, parameter decorator. */
+  readonly Args: string
+  /** `@Parent()`, parameter decorator. */
+  readonly Parent: string
+  /** `@Ctx()`, parameter decorator (`GraphQLContext`). */
+  readonly Ctx: string
+  /** `@Info()`, parameter decorator (graphql-js `GraphQLResolveInfo`). */
+  readonly Info: string
+  /** `@Loader()` parameter decorator **and** the `Loader<L>` parameter type (same export name). */
+  readonly Loader: string
+  /** `@UseGuard(...guards)`, class or method decorator. */
+  readonly UseGuard: string
+  /** `scalar<T>(name, definition)`. */
+  readonly scalar: string
+  /** `type ID = string` → `ID`. */
+  readonly ID: string
+  /** `type Int = number` → `Int`. */
+  readonly Int: string
+  /** `type Float = number` → `Float`. */
+  readonly Float: string
+  /** `type JSONValue` → `JSON`. */
+  readonly JSONValue: string
+  /** `interface BatchLoad<K, V>`: what loader providers implement (ZNIGHT065). */
+  readonly BatchLoad: string
+  /** `interface GraphQLContext`: the request-scoped external (manifest `provides`). */
+  readonly GraphQLContext: string
+  /** `interface ResolverContext`: what guards receive. */
+  readonly ResolverContext: string
+  /** `abstract class PubSub`: the singleton external (manifest `provides`). */
+  readonly PubSub: string
+  /** `GraphQLPlugin`: the singleton external (manifest `provides`). */
+  readonly GraphQLPlugin: string
+} = Object.freeze({
+  Resolver: '@znight/graphql#Resolver',
+  Query: '@znight/graphql#Query',
+  Mutation: '@znight/graphql#Mutation',
+  Subscription: '@znight/graphql#Subscription',
+  ResolveField: '@znight/graphql#ResolveField',
+  Args: '@znight/graphql#Args',
+  Parent: '@znight/graphql#Parent',
+  Ctx: '@znight/graphql#Ctx',
+  Info: '@znight/graphql#Info',
+  Loader: '@znight/graphql#Loader',
+  UseGuard: '@znight/graphql#UseGuard',
+  scalar: '@znight/graphql#scalar',
+  ID: '@znight/graphql#ID',
+  Int: '@znight/graphql#Int',
+  Float: '@znight/graphql#Float',
+  JSONValue: '@znight/graphql#JSONValue',
+  BatchLoad: '@znight/graphql#BatchLoad',
+  GraphQLContext: '@znight/graphql#GraphQLContext',
+  ResolverContext: '@znight/graphql#ResolverContext',
+  PubSub: '@znight/graphql#PubSub',
+  GraphQLPlugin: '@znight/graphql#GraphQLPlugin',
+})
+
+/** Field decorators → the kind of field they declare (`GraphQLResolverBinding.operation`). */
+export const FIELD_DECORATORS: ReadonlyMap<string, 'query' | 'mutation' | 'subscription' | 'field'> = new Map([
+  [GraphQLIds.Query, 'query'],
+  [GraphQLIds.Mutation, 'mutation'],
+  [GraphQLIds.Subscription, 'subscription'],
+  [GraphQLIds.ResolveField, 'field'],
+])
+
+/** Parameter decorators → what the generated `invoke` passes (§7.3). */
+export const PARAMETER_DECORATORS: ReadonlyMap<string, 'args' | 'parent' | 'ctx' | 'info' | 'loader'> = new Map([
+  [GraphQLIds.Args, 'args'],
+  [GraphQLIds.Parent, 'parent'],
+  [GraphQLIds.Ctx, 'ctx'],
+  [GraphQLIds.Info, 'info'],
+  [GraphQLIds.Loader, 'loader'],
+])
+
+/** Scalar aliases of `@znight/graphql` → their GraphQL scalar (§6.2). */
+export const SCALAR_ALIASES: ReadonlyMap<string, 'ID' | 'Int' | 'Float' | 'JSON'> = new Map([
+  [GraphQLIds.ID, 'ID'],
+  [GraphQLIds.Int, 'Int'],
+  [GraphQLIds.Float, 'Float'],
+  [GraphQLIds.JSONValue, 'JSON'],
+])
+
+/**
+ * Decorators of `@znight/http` that look like GraphQL ones, on a resolver: ZNIGHT005 with the
+ * `@znight/graphql` decorator to import instead (§6.5).
+ */
+export const HTTP_LOOK_ALIKES: ReadonlyMap<string, string> = new Map([
+  ['@znight/http#Ctx', GraphQLIds.Ctx],
+  ['@znight/http#Query', GraphQLIds.Args],
+  ['@znight/http#Param', GraphQLIds.Args],
+  ['@znight/http#Body', GraphQLIds.Args],
+  ['@znight/http#UseGuard', GraphQLIds.UseGuard],
+])
+
+/** `@Controller` of `@znight/http`: a class cannot be both a controller and a resolver (ZNIGHT005). */
+export const HTTP_CONTROLLER = '@znight/http#Controller'
+
+/** graphql-js `GraphQLResolveInfo`, the type of `@Info()` parameters. */
+export const GRAPHQL_RESOLVE_INFO = 'graphql#GraphQLResolveInfo'

package/src/compiler/index.ts

@@ -0,0 +1,93 @@
+/**
+ * `@znight/graphql/compiler`: the compiler extension of `@znight/graphql` (RFC 0005 §6).
+ *
+ * Loaded by `@znight/compiler` through the package manifest (`package.json#znight.compiler`):
+ *
+ * - `analyzeClass`: `@Resolver` classes become providers (and roots), their field methods and
+ *   parameters are checked, guards and loaders bound with lazy edges, route decorators read;
+ * - `validate`: the schema model, derived from the TypeScript types reachable from the root fields
+ *   (§6.2–§6.6), with every ZNIGHT060–065 diagnostic and the access decisions (ZNIGHT023);
+ * - `generate`: `metadata.extensions.graphql` (§7), and the SDL artifact when configured.
+ *
+ * The default export is the extension with its default options; `configure(options)` returns a
+ * configured copy, declared in `znight.config.ts` (it replaces the discovered extension):
+ *
+ * ```ts
+ * import graphql from '@znight/graphql/compiler'
+ * export default { extensions: [graphql.configure({ sdl: 'schema.graphql' })] } satisfies ZnightOptions
+ * ```
+ *
+ * This entry only `import type`s from `@znight/compiler`, imports the runtime-free
+ * `@znight/http/compiler`, and never loads the GraphQL runtime, graphql-js nor dataloader: it
+ * reaches the import-free modules `src/type-ref.ts`, `src/sdl.ts`, `src/names.ts`,
+ * `src/metadata.ts` and `src/schema-hash.ts` (`node:crypto`) only (tests/boundaries.test.ts).
+ */
+import type { ApplicationGraph, CompilerExtension, DecoratorSpec } from '@znight/compiler'
+import type { GraphQLData } from './data.ts'
+import type { GraphQLModel } from './model.ts'
+import type { GraphQLCompilerOptions, ResolvedGraphQLCompilerOptions } from './options.ts'
+
+import { analyzeGraphQLClass } from './analyze.ts'
+import { buildModel } from './builder.ts'
+import { generateGraphQL } from './generate.ts'
+import { EXTENSION_NAME, GraphQLIds } from './ids.ts'
+import { DEFAULT_OPTIONS, resolveOptions } from './options.ts'
+
+export type { FieldData, FieldOperation, GraphQLData, ParamData, ResolverData } from './data.ts'
+export type { GraphQLCompilerOptions, ResolvedGraphQLCompilerOptions } from './options.ts'
+
+const FIELD: DecoratorSpec = { targets: ['method'], params: ['static'] }
+const NO_ARGUMENT: DecoratorSpec = { targets: ['parameter'], params: [] }
+
+/** Decorators owned by the extension, by canonical identity (static / value arguments, §4.6). */
+const decorators: Readonly<Record<string, DecoratorSpec>> = Object.freeze({
+  [GraphQLIds.Resolver]: { targets: ['class'], params: ['static'] },
+  [GraphQLIds.Query]: FIELD,
+  [GraphQLIds.Mutation]: FIELD,
+  [GraphQLIds.Subscription]: FIELD,
+  [GraphQLIds.ResolveField]: FIELD,
+  [GraphQLIds.Args]: { targets: ['parameter'], params: ['value', 'value'] },
+  [GraphQLIds.Parent]: NO_ARGUMENT,
+  [GraphQLIds.Ctx]: NO_ARGUMENT,
+  [GraphQLIds.Info]: NO_ARGUMENT,
+  [GraphQLIds.Loader]: NO_ARGUMENT,
+  [GraphQLIds.UseGuard]: { targets: ['class', 'method'], params: [], rest: 'value' },
+} satisfies Record<string, DecoratorSpec>)
+
+/** The `@znight/graphql` compiler extension, with its options and `configure()`. */
+export interface GraphQLCompilerExtension extends CompilerExtension<GraphQLData> {
+  /** The options of this copy (defaults filled in). */
+  readonly options: ResolvedGraphQLCompilerOptions
+  /** A copy of the extension with `options` merged onto the options of this one. */
+  configure(options: GraphQLCompilerOptions): GraphQLCompilerExtension
+}
+
+function createExtension(options: ResolvedGraphQLCompilerOptions): GraphQLCompilerExtension {
+  /**
+   * Models by compile, built by `validate`, read by `generate`. The key is `graph.extensions`: the
+   * validate and generate contexts of one compile get different graph objects sharing this array.
+   */
+  const models = new WeakMap<object, GraphQLModel | undefined>()
+  const modelOf = (graph: ApplicationGraph): GraphQLModel | undefined => models.get(graph.extensions)
+  return Object.freeze({
+    apiVersion: 1,
+    name: EXTENSION_NAME,
+    decorators,
+    options,
+    analyzeClass: analyzeGraphQLClass,
+    validate(ctx) {
+      models.set(ctx.graph.extensions, buildModel(ctx, options))
+    },
+    generate(ctx) {
+      return generateGraphQL(ctx, modelOf(ctx.graph), options)
+    },
+    configure(next: GraphQLCompilerOptions): GraphQLCompilerExtension {
+      return createExtension(resolveOptions(options, next))
+    },
+  } satisfies GraphQLCompilerExtension)
+}
+
+/** The `@znight/graphql` compiler extension with its default options. */
+export const graphqlCompilerExtension: GraphQLCompilerExtension = createExtension(DEFAULT_OPTIONS)
+
+export default graphqlCompilerExtension

package/src/compiler/locate.ts

@@ -0,0 +1,44 @@
+/**
+ * Source locations of diagnostics. Computed only when a diagnostic is reported: the happy path
+ * never reads source text.
+ */
+import type { Location, Project } from '@znight/compiler'
+
+/** From the member name: `name?: ` or `name(): ` (a getter), up to the annotation. */
+const MEMBER_HEAD = /^(?:[\w$]+|'[^']*'|"[^"]*")\s*\??\s*(?:\(\s*\))?\s*:\s*/
+
+const OPENING = new Set(['(', '[', '{', '<'])
+const CLOSING = new Set([')', ']', '}', '>'])
+
+/**
+ * The type annotation of a property, a property signature or a getter (`get x(): T`), from the
+ * location of the member (its name); the member itself when the annotation cannot be found.
+ */
+export function annotationLocation(project: Project, member: Location | undefined): Location | undefined {
+  if (member === undefined) return undefined
+  const file = project.getFile(member.file)
+  if (file === undefined) return member
+  const text = file.text
+  const head = MEMBER_HEAD.exec(text.slice(member.start, member.start + 256))
+  if (head === null) return member
+  const start = member.start + head[0].length
+  let depth = 0
+  let end = start
+  for (let index = start; index < text.length; index++) {
+    const char = text[index] as string
+    if (char === '=' && text[index + 1] === '>') {
+      index++
+      continue
+    }
+    // a getter body or an initializer after the annotation
+    if (depth === 0 && end > start && (char === '{' || char === '=')) break
+    if (OPENING.has(char)) depth++
+    else if (CLOSING.has(char)) {
+      if (depth === 0) break
+      depth--
+    } else if (depth === 0 && (char === ';' || char === ',')) break
+    else if (depth === 0 && char === '\n' && !/^\s*[|&]/.test(text.slice(index + 1, index + 64))) break
+    if (!/\s/.test(char)) end = index + 1
+  }
+  return end > start ? file.location({ start, end }) : member
+}