@znight/graphql 0.2.0 → 0.2.1

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { f as LoaderKey, m as LoaderValue, r as BatchLoader, t as BatchLoad } from "./types-CgbV9LjD.mjs";
+import { _ as LoaderValue, h as LoaderKey, r as BatchLoader, t as BatchLoad } from "./types-DQ713UgI.mjs";
 import { GraphQLFormattedError } from "graphql";
 import { MockFunction, TestApp } from "@znight/testing";
 /** An operation for {@link executeOperation} and {@link subscribeOperation}. */

package/dist/testing.mjs

@@ -1,4 +1,4 @@
-import { n as endpointOf, r as executorOf } from "./plugin-BdBxr5NQ.mjs";
+import { n as endpointOf, r as executorOf } from "./plugin-CR_wVfRU.mjs";
 import { parseSseStream } from "@znight/http";
 import { resolveMockFn } from "@znight/testing";
 // src/testing.ts

package/dist/{types-CgbV9LjD.d.mts → types-DQ713UgI.d.mts}

@@ -213,6 +213,38 @@ interface GraphQLErrorMapper {
 }
 /** A class producing {@link GraphQLErrorMapper}s. */
 type GraphQLErrorMapperClass = abstract new (...args: never[]) => GraphQLErrorMapper;
+/**
+ * Turns the errors of a field into values of the field (errors as data, RFC 0008). It applies to
+ * the resolver-backed fields whose type is a union holding one of the object types it declares
+ * (`static types`), decided at boot; every other field keeps its errors in `errors[]`.
+ *
+ * ```ts
+ * @Injectable()
+ * export class Rejections implements GraphQLResultMapper {
+ *   static readonly types = ['NotFoundRejection']
+ *
+ *   toResult(error: unknown): NotFoundRejection | undefined {
+ *     if (error instanceof NotFoundException) return { __typename: 'NotFoundRejection', message: error.message }
+ *     return undefined
+ *   }
+ * }
+ * ```
+ */
+interface GraphQLResultMapper {
+  /**
+   * The value of the field for `error`: an object of a member of the field's union, or `undefined`
+   * to leave the error to the next mapper, then to `errors[]`. Synchronous. `error` is the raw
+   * error, a `GraphQLException` included (a guard returning `false` is `FORBIDDEN`, a Standard
+   * Schema failure of the arguments `BAD_USER_INPUT` with `extensions.issues`).
+   */
+  toResult(error: unknown, ctx: ResolverContext): unknown;
+}
+/** The object types a result mapper may produce: names of object types of the schema. */
+interface GraphQLResultTypes {
+  readonly types: readonly string[];
+}
+/** A class producing {@link GraphQLResultMapper}s, with the object types it produces (`static types`). */
+type GraphQLResultMapperClass = (abstract new (...args: never[]) => GraphQLResultMapper) & GraphQLResultTypes;
 /**
  * The implementation of a custom scalar (§5.7), given to `scalar<T>(name, definition)`. The
  * runtime maps it to graphql-js 17 `GraphQLScalarType` coercers: `serialize` → `coerceOutputValue`,
@@ -230,5 +262,5 @@ interface ScalarDefinition<T> {
   /** Literal of the document → internal value. Default: `parseValue` of the literal's JSON value. */
   parseLiteral?(literal: ConstValueNode): T;
 }
-export { GraphQLErrorCode as _, GraphQLContext as a, GraphQLExceptionOptions as b, GraphQLGuard as c, GraphQLTransport as d, LoaderKey as f, ScalarDefinition as g, ResolverContext as h, GraphQLArgs as i, GraphQLGuardClass as l, LoaderValue as m, BatchLoadClass as n, GraphQLErrorMapper as o, LoaderOptions as p, BatchLoader as r, GraphQLErrorMapperClass as s, BatchLoad as t, GraphQLOperationKind as u, GraphQLErrorCodeValue as v, GraphQLException as y };
-//# sourceMappingURL=types-CgbV9LjD.d.mts.map
+export { GraphQLExceptionOptions as C, GraphQLException as S, LoaderValue as _, GraphQLContext as a, GraphQLErrorCode as b, GraphQLGuard as c, GraphQLResultMapper as d, GraphQLResultMapperClass as f, LoaderOptions as g, LoaderKey as h, GraphQLArgs as i, GraphQLGuardClass as l, GraphQLTransport as m, BatchLoadClass as n, GraphQLErrorMapper as o, GraphQLResultTypes as p, BatchLoader as r, GraphQLErrorMapperClass as s, BatchLoad as t, GraphQLOperationKind as u, ResolverContext as v, GraphQLErrorCodeValue as x, ScalarDefinition as y };
+//# sourceMappingURL=types-DQ713UgI.d.mts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znight/graphql",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Znight GraphQL: code-first GraphQL whose schema is derived from TypeScript types at build time, on graphql-js 17",
   "license": "MIT",
   "author": "Ugho STEPHAN",
@@ -46,13 +46,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@znight/core": "0.2.0",
+    "@znight/core": "0.2.1",
     "dataloader": "^2.2.3"
   },
   "peerDependencies": {
-    "@znight/http": "^0.2.0",
-    "@znight/compiler": "^0.2.0",
-    "@znight/testing": "^0.2.0",
+    "@znight/http": "^0.2.1",
+    "@znight/compiler": "^0.2.1",
+    "@znight/testing": "^0.2.1",
     "graphql": "^17.0.2"
   },
   "peerDependenciesMeta": {
@@ -64,9 +64,9 @@
     }
   },
   "devDependencies": {
-    "@znight/http": "0.2.0",
-    "@znight/compiler": "0.2.0",
-    "@znight/testing": "0.2.0",
+    "@znight/http": "0.2.1",
+    "@znight/compiler": "0.2.1",
+    "@znight/testing": "0.2.1",
     "graphql": "17.0.2",
     "graphql-http": "1.23.1",
     "graphql-sse": "2.6.3",

package/src/compiler/analyze.ts

@@ -18,7 +18,8 @@ import type {
 } from '@znight/compiler'
 import type { Scope } from '@znight/core'
 import type { MetaEntry } from '@znight/http/compiler'
-import type { FieldData, FieldOperation, GraphQLData, ParamData } from './data.ts'
+import type { FieldData, FieldOperation, GraphQLData, ParamData, ResolverData } from './data.ts'
+import type { ResolvedGraphQLCompilerOptions } from './options.ts'
 
 import { effectiveRouteMeta, readRouteMeta } from '@znight/http/compiler'
 
@@ -41,12 +42,17 @@ const SCOPES: readonly Scope[] = ['singleton', 'request', 'transient']
 /** Shape options reading `Loader<L>` parameters: the alias is kept, `L` stays a named shape. */
 const LOADER_SHAPE = Object.freeze({ keep: Object.freeze([GraphQLIds.Loader]), jsdoc: false })
 
-/** Analyses a class carrying at least one graphql decorator (class, method or parameter). */
-export function analyzeGraphQLClass(cls: ClassInfo, ctx: Context): void {
+/**
+ * Analyses a class carrying at least one graphql decorator (class, method or parameter). In
+ * schema-first mode (RFC 0007), `@Resolver('Type')` names the SDL type of the field resolvers and
+ * `@Parent()` is optional.
+ */
+export function analyzeGraphQLClass(cls: ClassInfo, ctx: Context, options: ResolvedGraphQLCompilerOptions): void {
   const resolvers = cls.decorators.filter(decorator => decorator.identity === GraphQLIds.Resolver)
   const resolver = resolvers[0]
   if (resolver === undefined) {
     reportOutsideResolver(cls, ctx)
+    storeClaims(ctx, cls, undefined, options)
     return
   }
   for (const extra of resolvers.slice(1)) {
@@ -66,6 +72,7 @@ export function analyzeGraphQLClass(cls: ClassInfo, ctx: Context): void {
       ],
       [{ message: '@Controller is applied here', location: controller.location }],
     )
+    storeClaims(ctx, cls, resolver, options)
     return
   }
   if (ctx.options.library) {
@@ -76,6 +83,7 @@ export function analyzeGraphQLClass(cls: ClassInfo, ctx: Context): void {
       `${cls.displayName} is a @Resolver in a compiled provider library: the schema is derived from the sources`,
       ['Publish the package as a source library (without library: true), so that applications compile its resolvers'],
     )
+    storeClaims(ctx, cls, resolver, options)
     return
   }
   if (cls.abstract || cls.typeParameters.length > 0) {
@@ -88,10 +96,11 @@ export function analyzeGraphQLClass(cls: ClassInfo, ctx: Context): void {
         : `@Resolver cannot be applied to the generic class ${cls.displayName}<${cls.typeParameters.join(', ')}>`,
       [cls.abstract ? 'Resolvers are instantiated: remove `abstract`' : 'Remove the type parameters of the resolver'],
     )
+    storeClaims(ctx, cls, resolver, options)
     return
   }
 
-  const scope = resolverScope(ctx, resolver)
+  const { scope, typeName } = resolverArguments(ctx, resolver, options.schema !== false)
   ctx.registerProvider(cls, { scope })
   // resolvers are entry points of the plugin: roots of ZNIGHT019 and prune
   ctx.addRoot(cls, { reason: ROOT_REASON, location: resolver.location })
@@ -105,9 +114,79 @@ export function analyzeGraphQLClass(cls: ClassInfo, ctx: Context): void {
       reportStrayMethodDecorators(cls, method, ctx)
       continue
     }
-    fields.push(...analyzeMethod(ctx, cls, method, decorators, classMeta))
+    fields.push(...analyzeMethod(ctx, cls, method, decorators, classMeta, options.schema !== false))
+  }
+  const data: ResolverData = {
+    kind: 'resolver',
+    host: cls,
+    scope,
+    location: resolver.location,
+    guards: classGuards,
+    fields,
+    ...(typeName === undefined ? {} : { typeName }),
+  }
+  if (options.schema !== false && typeName === undefined) {
+    for (const field of fields) {
+      if (field.operation !== 'field') continue
+      error(
+        ctx,
+        Codes.InvalidResolver,
+        field.location,
+        `@ResolveField ${cls.displayName}.${field.method} needs the type it resolves a field of: name it in @Resolver (schema-first)`,
+        [
+          `@Resolver('Event') on ${cls.displayName}, where Event is the object type of the SDL declaring '${field.name}'`,
+        ],
+      )
+    }
   }
-  ctx.store({ kind: 'resolver', host: cls, scope, location: resolver.location, guards: classGuards, fields })
+  ctx.store(data)
+}
+
+/**
+ * Schema-first: a class rejected above (no `@Resolver`, abstract, a controller...) still names the
+ * fields its methods resolve, stored as an `invalid` resolver, so that these fields are not also
+ * reported as missing a resolver (one diagnostic per mistake).
+ */
+function storeClaims(
+  ctx: Context,
+  cls: ClassInfo,
+  resolver: DecoratorInfo | undefined,
+  options: ResolvedGraphQLCompilerOptions,
+): void {
+  if (options.schema === false) return
+  const typeArg = resolver?.args[0]
+  const typeName =
+    typeArg?.evaluated === true && typeof typeArg.value === 'string'
+      ? { name: typeArg.value, location: typeArg.location }
+      : undefined
+  const fields: FieldData[] = []
+  for (const method of cls.methods) {
+    for (const decorator of method.decorators.filter(isFieldDecorator)) {
+      const arg = decorator.args[0]
+      fields.push({
+        method: method.name,
+        operation: FIELD_DECORATORS.get(decorator.identity as string) as FieldOperation,
+        name: arg?.evaluated === true && typeof arg.value === 'string' ? arg.value : method.name,
+        location: decorator.location,
+        methodLocation: method.location,
+        guards: [],
+        meta: [],
+        params: [],
+        complete: false,
+      })
+    }
+  }
+  if (fields.length === 0) return
+  ctx.store({
+    kind: 'resolver',
+    host: cls,
+    scope: 'singleton',
+    location: resolver?.location ?? cls.location,
+    guards: [],
+    fields,
+    invalid: true,
+    ...(typeName === undefined ? {} : { typeName }),
+  })
 }
 
 function isFieldDecorator(decorator: DecoratorInfo): boolean {
@@ -118,9 +197,47 @@ function isParameterDecorator(decorator: DecoratorInfo): boolean {
   return decorator.identity !== undefined && PARAMETER_DECORATORS.has(decorator.identity)
 }
 
-/** `@Resolver({ scope })`. */
-function resolverScope(ctx: Context, decorator: DecoratorInfo): Scope {
-  const arg = decorator.args[0]
+/** `@Resolver()`, `@Resolver({ scope })`, `@Resolver('Event')`, `@Resolver('Event', { scope })` (schema-first). */
+function resolverArguments(
+  ctx: Context,
+  decorator: DecoratorInfo,
+  schemaFirst: boolean,
+): { scope: Scope; typeName?: { readonly name: string; readonly location: Location } } {
+  const [first, second] = decorator.args
+  if (first?.evaluated !== true || typeof first.value !== 'string') {
+    if (second !== undefined) {
+      error(ctx, Codes.InvalidDecorator, second.location, '@Resolver takes the options as its only argument here', [
+        "@Resolver({ scope: 'request' }), or @Resolver('Event', { scope: 'request' }) in schema-first mode",
+      ])
+    }
+    return { scope: resolverScope(ctx, first) }
+  }
+  const scope = resolverScope(ctx, second)
+  const name = first.value
+  if (!schemaFirst) {
+    error(
+      ctx,
+      Codes.InvalidDecorator,
+      first.location,
+      `@Resolver('${name}'): naming the type is schema-first only, the code-first schema is derived from the types`,
+      [
+        'Remove the type name: @ResolveField methods add fields to the type of their @Parent() parameter',
+        "Or switch to schema-first: graphql.configure({ schema: 'src/**/*.graphql' }) in znight.config.ts",
+      ],
+    )
+    return { scope }
+  }
+  if (!isGraphQLName(name)) {
+    error(ctx, Codes.NameConflict, first.location, `'${name}' is not a valid GraphQL type name (@Resolver)`, [
+      'GraphQL names match /^[_A-Za-z][_0-9A-Za-z]*$/ and do not start with __',
+    ])
+    return { scope }
+  }
+  return { scope, typeName: { name, location: first.location } }
+}
+
+/** The `{ scope }` options of `@Resolver`. */
+function resolverScope(ctx: Context, arg: DecoratorInfo['args'][number] | undefined): Scope {
   if (arg === undefined || !arg.evaluated || arg.value === undefined) return 'singleton'
   const value = arg.value
   if (!isRecord(value)) {
@@ -171,6 +288,7 @@ function analyzeMethod(
   method: MethodInfo,
   decorators: readonly DecoratorInfo[],
   classMeta: readonly MetaEntry[],
+  schemaFirst: boolean,
 ): FieldData[] {
   const where = `${cls.displayName}.${method.name}`
   const primary = decorators[0] as DecoratorInfo
@@ -216,7 +334,8 @@ function analyzeMethod(
     }
     seen.add(key)
     let fieldComplete = complete && explicit !== undefined
-    if (operation === 'field' && parents.length === 0) {
+    // schema-first: the type is named by @Resolver('Type'), the parent is optional (NestJS)
+    if (operation === 'field' && parents.length === 0 && !schemaFirst) {
       error(ctx, Codes.InvalidResolver, decorator.location, `@ResolveField ${where} has no @Parent() parameter`, [
         `Declare the parent object first: ${method.name}(@Parent() parent: ParentType, ...)`,
       ])

package/src/compiler/builder.ts

@@ -39,17 +39,16 @@ import type {
 } from './model.ts'
 import type { ResolvedGraphQLCompilerOptions } from './options.ts'
 
-import { requiredRouteGroups } from '@znight/http/compiler'
-
 import { isGraphQLName, RESERVED_ENUM_VALUES, ROOT_TYPE_NAMES, SPECIFIED_SCALARS } from '../names.ts'
 import { schemaHash } from '../schema-hash.ts'
 import { printSdl } from '../sdl.ts'
 import { printTypeRef } from '../type-ref.ts'
+import { checkDecisions, checkLoaders } from './checks.ts'
 import { ASYNC_ITERABLES, BASE_KEEP, Codes, compareStrings, OUTPUT_ITERABLES } from './constants.ts'
 import { externalValue } from './defaults.ts'
 import { discriminatorOf } from './discriminators.ts'
 import { defaultTagValue, deprecationOf, descriptionOf, isHidden, paramDescription, tagOf } from './docs.ts'
-import { GraphQLIds, SCALAR_ALIASES } from './ids.ts'
+import { SCALAR_ALIASES } from './ids.ts'
 import { annotationLocation } from './locate.ts'
 import { readScalars, type ScalarDeclaration } from './scalars.ts'
 import { sdlType } from './sdl-view.ts'
@@ -151,7 +150,7 @@ class SchemaBuilder {
   }
 
   build(resolvers: readonly ResolverData[]): GraphQLModel | undefined {
-    this.#checkLoaders(resolvers)
+    checkLoaders(this.#ctx, resolvers, diagnostic => this.#report(diagnostic))
     this.#indexFieldResolvers(resolvers)
     const roots = new Map<Operation, ObjectModel>()
     const rootFields = new Map<string, { readonly field: FieldData; readonly resolver: ResolverData }>()
@@ -194,7 +193,7 @@ class SchemaBuilder {
     this.#reportUnreachableFieldResolvers()
     this.#checkDefaults()
     this.#checkInputCycles()
-    this.#checkDecisions(resolvers)
+    checkDecisions(this.#ctx, resolvers, diagnostic => this.#report(diagnostic))
     if (this.#errors > 0 || !hasQuery) return undefined
     return this.#assemble(roots, resolvers)
   }
@@ -261,6 +260,7 @@ class SchemaBuilder {
         root: undefined,
         classIdentity: undefined,
         properties: [],
+        interfaces: [],
       }
       roots.set(operation, root)
       this.#claim(root, undefined)
@@ -511,34 +511,6 @@ class SchemaBuilder {
     ])
   }
 
-  /** `Loader<L>`: `L` must be a loader provider, implementing `BatchLoad<K, V>` (ZNIGHT065). */
-  #checkLoaders(resolvers: readonly ResolverData[]): void {
-    const seen = new Set<number>()
-    for (const resolver of resolvers) {
-      for (const field of resolver.fields) {
-        for (const param of field.params) {
-          if (param?.kind !== 'loader' || seen.has(param.binding.id)) continue
-          seen.add(param.binding.id)
-          const ref = this.#ctx.binding(param.binding)
-          const token = tokenOfRef(ref)
-          const provider = token === undefined ? undefined : this.#ctx.provider(token)
-          // an unbound loader is ZNIGHT001 (reported by the binding)
-          if (provider === undefined || provider.heritage.some(type => type.identity === GraphQLIds.BatchLoad)) continue
-          if (provider.kind !== 'class' || hasLoadMethod(this.#ctx, provider.classIdentity)) continue
-          this.#report({
-            code: Codes.InvalidLoader,
-            severity: 'error',
-            message: `${provider.displayName} is not a loader: Loader<${provider.displayName}> needs a provider implementing BatchLoad<K, V> (${resolver.host.displayName}.${field.method})`,
-            location: param.location,
-            hints: [
-              `export class ${provider.displayName} implements BatchLoad<ID, Value> { async load(keys: readonly ID[]): Promise<readonly (Value | Error)[]> { ... } }`,
-            ],
-          })
-        }
-      }
-    }
-  }
-
   // ------------------------------------------------------------------------------ field resolvers
 
   #indexFieldResolvers(resolvers: readonly ResolverData[]): void {
@@ -1029,6 +1001,7 @@ class SchemaBuilder {
           ? structure.identity
           : undefined,
       properties: properties.map(property => this.#discriminant(property)),
+      interfaces: [],
     }
     this.#models.set(key, model)
     if (!this.#claim(model, use)) return undefined
@@ -1508,37 +1481,6 @@ class SchemaBuilder {
     for (const model of inputs) if (!state.has(model.name)) visit(model)
   }
 
-  /** RFC 0001: every root field decides every required route decorator group (ZNIGHT023). */
-  #checkDecisions(resolvers: readonly ResolverData[]): void {
-    const applied: MetaEntry[] = []
-    for (const resolver of resolvers) for (const field of resolver.fields) applied.push(...field.meta)
-    const required = requiredRouteGroups(this.#ctx, applied)
-    if (required.length === 0) return
-    for (const resolver of resolvers) {
-      for (const field of resolver.fields) {
-        if (field.operation === 'field') continue
-        const decided = new Set(field.meta.map(entry => entry.group))
-        for (const group of required) {
-          if (decided.has(group.group)) continue
-          const root = ROOT_TYPE_NAMES[field.operation]
-          this.#report({
-            code: Codes.MissingRouteDecision,
-            severity: 'error',
-            message: `Root field ${root}.${field.name} (${resolver.host.displayName}.${field.method}) has no "${group.group}" decision`,
-            location: field.methodLocation,
-            hints: [`Add ${group.suggestion} to the method or to ${resolver.host.displayName}`],
-            related: [
-              {
-                message: `The "${group.group}" group is required`,
-                location: (group.decorators[0] as { definition: Location }).definition,
-              },
-            ],
-          })
-        }
-      }
-    }
-  }
-
   // ------------------------------------------------------------------------------------ assembly
 
   #assemble(roots: ReadonlyMap<Operation, ObjectModel>, resolvers: readonly ResolverData[]): GraphQLModel {
@@ -1557,21 +1499,6 @@ class SchemaBuilder {
 
 // ------------------------------------------------------------------------------------------ helpers
 
-/** The class (or one of its base classes) declares an instance `load` method. */
-function hasLoadMethod(ctx: Context, identity: string): boolean {
-  const seen = new Set<string>()
-  let current: string | undefined = identity
-  while (current !== undefined && !seen.has(current)) {
-    seen.add(current)
-    const cls: ClassInfo | undefined = ctx.classInfo(current)
-    if (cls === undefined) return true // not analysable (a compiled class): trust the type checker
-    if (cls.methods.some(method => method.name === 'load' && method.kind === 'method' && !method.static)) return true
-    if (cls.properties.some(property => property.name === 'load' && !property.static)) return true
-    current = cls.superClass?.identity
-  }
-  return false
-}
-
 /** A (nullable, until `#convert` decides) reference to a named type. */
 function refTo(name: string): Inner {
   return { ref: { kind: 'named', name, nonNull: false }, nullable: false }
@@ -1587,12 +1514,6 @@ function decoratorName(operation: Operation): string {
   return ROOT_TYPE_NAMES[operation]
 }
 
-/** The token of a binding result (`undefined` when binding failed). */
-function tokenOfRef(ref: ReturnType<Context['binding']>): string | undefined {
-  if (typeof ref === 'string') return ref
-  return ref !== undefined && 'token' in ref ? ref.token : undefined
-}
-
 function describeKey(model: TypeModel): string {
   return model.key.startsWith('#') ? `the ${model.kind} ${model.name}` : model.key
 }

package/src/compiler/checks.ts

@@ -0,0 +1,105 @@
+/**
+ * Checks shared by the code-first schema builder (`builder.ts`) and the schema-first one
+ * (`schema-first.ts`): loader providers (ZNIGHT065) and the route decisions of root fields
+ * (ZNIGHT023, RFC 0001).
+ */
+import type { ClassInfo, Diagnostic, Location, ValidateContext } from '@znight/compiler'
+import type { MetaEntry } from '@znight/http/compiler'
+import type { GraphQLData, ResolverData } from './data.ts'
+
+import { requiredRouteGroups } from '@znight/http/compiler'
+
+import { ROOT_TYPE_NAMES } from '../names.ts'
+import { Codes } from './constants.ts'
+import { GraphQLIds } from './ids.ts'
+
+type Context = ValidateContext<GraphQLData>
+type Report = (diagnostic: Diagnostic) => void
+
+/** `Loader<L>`: `L` must be a loader provider, implementing `BatchLoad<K, V>` (ZNIGHT065). */
+export function checkLoaders(ctx: Context, resolvers: readonly ResolverData[], report: Report): void {
+  const seen = new Set<number>()
+  for (const resolver of resolvers) {
+    for (const field of resolver.fields) {
+      for (const param of field.params) {
+        if (param?.kind !== 'loader' || seen.has(param.binding.id)) continue
+        seen.add(param.binding.id)
+        const ref = ctx.binding(param.binding)
+        const token = tokenOfRef(ref)
+        const provider = token === undefined ? undefined : ctx.provider(token)
+        // an unbound loader is ZNIGHT001 (reported by the binding)
+        if (provider === undefined || provider.heritage.some(type => type.identity === GraphQLIds.BatchLoad)) continue
+        if (provider.kind !== 'class' || hasLoadMethod(ctx, provider.classIdentity)) continue
+        report({
+          code: Codes.InvalidLoader,
+          severity: 'error',
+          message: `${provider.displayName} is not a loader: Loader<${provider.displayName}> needs a provider implementing BatchLoad<K, V> (${resolver.host.displayName}.${field.method})`,
+          location: param.location,
+          hints: [
+            `export class ${provider.displayName} implements BatchLoad<ID, Value> { async load(keys: readonly ID[]): Promise<readonly (Value | Error)[]> { ... } }`,
+          ],
+        })
+      }
+    }
+  }
+}
+
+/**
+ * RFC 0001: every root field decides every required route decorator group (ZNIGHT023). `roots`
+ * names the root types (`schema { query: RootQuery }` in schema-first).
+ */
+export function checkDecisions(
+  ctx: Context,
+  resolvers: readonly ResolverData[],
+  report: Report,
+  roots: { readonly query: string; readonly mutation?: string; readonly subscription?: string } = ROOT_TYPE_NAMES,
+): void {
+  const applied: MetaEntry[] = []
+  for (const resolver of resolvers) for (const field of resolver.fields) applied.push(...field.meta)
+  const required = requiredRouteGroups(ctx, applied)
+  if (required.length === 0) return
+  for (const resolver of resolvers) {
+    for (const field of resolver.fields) {
+      if (field.operation === 'field') continue
+      const decided = new Set(field.meta.map(entry => entry.group))
+      for (const group of required) {
+        if (decided.has(group.group)) continue
+        const root = roots[field.operation] ?? ROOT_TYPE_NAMES[field.operation]
+        report({
+          code: Codes.MissingRouteDecision,
+          severity: 'error',
+          message: `Root field ${root}.${field.name} (${resolver.host.displayName}.${field.method}) has no "${group.group}" decision`,
+          location: field.methodLocation,
+          hints: [`Add ${group.suggestion} to the method or to ${resolver.host.displayName}`],
+          related: [
+            {
+              message: `The "${group.group}" group is required`,
+              location: (group.decorators[0] as { definition: Location }).definition,
+            },
+          ],
+        })
+      }
+    }
+  }
+}
+
+/** The class (or one of its base classes) declares an instance `load` method. */
+function hasLoadMethod(ctx: Context, identity: string): boolean {
+  const seen = new Set<string>()
+  let current: string | undefined = identity
+  while (current !== undefined && !seen.has(current)) {
+    seen.add(current)
+    const cls: ClassInfo | undefined = ctx.classInfo(current)
+    if (cls === undefined) return true // not analysable (a compiled class): trust the type checker
+    if (cls.methods.some(method => method.name === 'load' && method.kind === 'method' && !method.static)) return true
+    if (cls.properties.some(property => property.name === 'load' && !property.static)) return true
+    current = cls.superClass?.identity
+  }
+  return false
+}
+
+/** The token of a binding result (`undefined` when binding failed). */
+function tokenOfRef(ref: ReturnType<Context['binding']>): string | undefined {
+  if (typeof ref === 'string') return ref
+  return ref !== undefined && 'token' in ref ? ref.token : undefined
+}