@znight/http 0.0.0-stage → 0.1.0

package/src/compiler/model.ts

@@ -0,0 +1,260 @@
+/**
+ * Data model of the `@znight/http` compiler extension: canonical identities of the decorators and
+ * the data stored during analysis (`ctx.store()`), read back by `validate()` and `generate()`.
+ *
+ * This module is pure (types and constants only) so that the compiler entry stays free of runtime
+ * dependencies.
+ */
+import type { ClassRef, Location, StaticValue, ValueRef } from '@znight/compiler'
+import type { HttpMethod, HttpParamSource } from '../metadata.ts'
+
+/** Package name (prefix of every decorator identity). */
+export const HTTP_PACKAGE = '@znight/http'
+
+/** Canonical identities of the decorators of `@znight/http`. */
+export const Ids: {
+  readonly Controller: string
+  readonly Param: string
+  readonly Query: string
+  readonly Body: string
+  readonly Headers: string
+  readonly Req: string
+  readonly Res: string
+  readonly Ctx: string
+  readonly HttpCode: string
+  readonly Header: string
+  readonly UseGuard: string
+  readonly UseInterceptor: string
+  readonly Validate: string
+  readonly UploadedFile: string
+  readonly UploadedFiles: string
+  readonly BodyLimit: string
+  readonly Cookie: string
+  readonly SignedCookie: string
+  readonly Sse: string
+  readonly createRouteDecorator: string
+  readonly RouteDecorator: string
+} = Object.freeze({
+  Controller: '@znight/http#Controller',
+  Param: '@znight/http#Param',
+  Query: '@znight/http#Query',
+  Body: '@znight/http#Body',
+  Headers: '@znight/http#Headers',
+  Req: '@znight/http#Req',
+  Res: '@znight/http#Res',
+  Ctx: '@znight/http#Ctx',
+  HttpCode: '@znight/http#HttpCode',
+  Header: '@znight/http#Header',
+  UseGuard: '@znight/http#UseGuard',
+  UseInterceptor: '@znight/http#UseInterceptor',
+  Validate: '@znight/http#Validate',
+  UploadedFile: '@znight/http#UploadedFile',
+  UploadedFiles: '@znight/http#UploadedFiles',
+  BodyLimit: '@znight/http#BodyLimit',
+  Cookie: '@znight/http#Cookie',
+  SignedCookie: '@znight/http#SignedCookie',
+  Sse: '@znight/http#Sse',
+  createRouteDecorator: '@znight/http#createRouteDecorator',
+  RouteDecorator: '@znight/http#RouteDecorator',
+})
+
+/** Route method decorators → HTTP method (`@Sse` declares a `GET` route). */
+export const ROUTE_METHODS: ReadonlyMap<string, HttpMethod> = new Map<string, HttpMethod>([
+  ['@znight/http#Get', 'GET'],
+  ['@znight/http#Post', 'POST'],
+  ['@znight/http#Put', 'PUT'],
+  ['@znight/http#Patch', 'PATCH'],
+  ['@znight/http#Delete', 'DELETE'],
+  ['@znight/http#Head', 'HEAD'],
+  ['@znight/http#Options', 'OPTIONS'],
+  ['@znight/http#All', 'ALL'],
+  ['@znight/http#Sse', 'GET'],
+])
+
+/** Parameter decorators → parameter source. */
+export const PARAM_SOURCES: ReadonlyMap<string, HttpParamSource> = new Map<string, HttpParamSource>([
+  [Ids.Param, 'param'],
+  [Ids.Query, 'query'],
+  [Ids.Body, 'body'],
+  [Ids.Headers, 'headers'],
+  [Ids.Req, 'request'],
+  [Ids.Res, 'response'],
+  [Ids.Ctx, 'context'],
+  [Ids.UploadedFile, 'file'],
+  [Ids.UploadedFiles, 'files'],
+  [Ids.Cookie, 'cookie'],
+  [Ids.SignedCookie, 'signedCookie'],
+])
+
+/** Error codes used by the extension (see `ErrorCode` in `@znight/core`). */
+export const Codes: {
+  readonly MissingProvider: 'ZNIGHT001'
+  readonly InvalidDecorator: 'ZNIGHT005'
+  readonly InvalidRoute: 'ZNIGHT007'
+  readonly UnvalidatedInput: 'ZNIGHT017'
+  readonly MissingRouteDecision: 'ZNIGHT023'
+} = Object.freeze({
+  MissingProvider: 'ZNIGHT001',
+  InvalidDecorator: 'ZNIGHT005',
+  InvalidRoute: 'ZNIGHT007',
+  UnvalidatedInput: 'ZNIGHT017',
+  MissingRouteDecision: 'ZNIGHT023',
+})
+
+/**
+ * Grammar of an explicit route decorator group name (same as the runtime `createRouteDecorator`).
+ * A decorator without `group` is its own group, named after its key (any non-empty key).
+ */
+export const GROUP_NAME: RegExp = /^[A-Za-z][\w.-]*$/
+
+/** Primitive coercions (`coerce.<kind>`). */
+export type ScalarCoercion = 'string' | 'number' | 'integer' | 'boolean' | 'bigint' | 'date'
+
+/**
+ * How a raw value (route parameter, query value, header) is converted to the declared type of a
+ * handler parameter.
+ */
+export type CoercionPlan =
+  | { readonly kind: ScalarCoercion }
+  | { readonly kind: 'enum'; readonly values: readonly (string | number | boolean)[] }
+  | { readonly kind: 'array'; readonly item: CoercionPlan }
+  | { readonly kind: 'optional'; readonly item: CoercionPlan }
+  /** No conversion: the raw value is passed as is (`unknown` / `any` parameters). */
+  | { readonly kind: 'raw' }
+
+/** The coercion of a handler parameter. */
+export interface ParamCoercion {
+  readonly plan: CoercionPlan
+  /**
+   * The coerced value does not have the declared type (branded primitives, enums, `null` without
+   * `undefined`): the generated expression is cast with `as never`.
+   */
+  readonly cast: boolean
+}
+
+/** An upload parameter (`@UploadedFile` / `@UploadedFiles`). */
+export interface UploadData {
+  /** Multipart field; `undefined`: any field. */
+  readonly field: string | undefined
+  /** `@UploadedFiles`. */
+  readonly multiple: boolean
+  /** A file must be sent (`required` option, else the parameter is not optional). */
+  readonly required: boolean
+  /** `maxSize` in bytes (`Infinity` allowed). */
+  readonly maxSize: number | undefined
+  /** `maxFiles` (`@UploadedFiles` only). */
+  readonly maxFiles: number | undefined
+  /** `mimeTypes` patterns, as written. */
+  readonly mimeTypes: readonly string[] | undefined
+  /** The injected value does not have the declared type (`node:buffer` File, `File | null`): `as never`. */
+  readonly cast: boolean
+}
+
+/** A handler parameter. */
+export interface HttpParamData {
+  /** Position in the handler signature. */
+  readonly index: number
+  /** Parameter name (messages). */
+  readonly name: string
+  readonly source: HttpParamSource
+  /** Route parameter name, query key, lower-case header name or cookie name; `undefined` for the whole object. */
+  readonly key: string | undefined
+  /** Declared (or inferred) type, formatted for humans. */
+  readonly type: string | undefined
+  /** The parameter accepts `undefined` (`?`, `| undefined`, default value). */
+  readonly optional: boolean
+  /** Standard Schema validating the value (its output is injected). */
+  readonly schema: ValueRef | undefined
+  /** Coercion of a named value without schema. */
+  readonly coercion: ParamCoercion | undefined
+  /** Upload parameter (`source` `file` / `files`). */
+  readonly upload?: UploadData
+  /**
+   * The default value of the handler parameter (`@Query('page') page = 1` → `1`), when it is
+   * statically evaluable (literals, `const` references; references to exported bindings are left
+   * out). Informational (documentation): the handler applies its own default.
+   */
+  readonly defaultValue?: StaticValue
+  /** Location of the parameter decorator. */
+  readonly location: Location
+}
+
+/** A `createRouteDecorator` value (`route.meta[key]`) and the definition of its decorator. */
+export interface MetaEntry {
+  readonly key: string
+  /** Statically evaluated value; may be or contain references to exported bindings. */
+  readonly value: StaticValue
+  /** Location of the decorator usage. */
+  readonly location: Location
+  /** Decision group (`options.group ?? key`). */
+  readonly group: string
+  /** The group is required (`options.required`). */
+  readonly required: boolean
+  /** Display name of the decorator (`Roles`). */
+  readonly decorator: string
+  /** Canonical identity of the decorator `const` (`src/auth/access.ts#Roles`). */
+  readonly identity: string
+  /** Location of the decorator definition (`export const Roles = createRouteDecorator(...)`). */
+  readonly definition: Location
+}
+
+/** Options of an `@Sse` route (`HttpRouteDefinition.sse`). */
+export interface SseRouteData {
+  /** Heartbeat in ms; `0` disables it (`heartbeat: false`). Absent: the plugin default. */
+  readonly heartbeat?: number
+  readonly retry?: number
+  readonly maxDuration?: number
+}
+
+/** A route: one route decorator of a handler. */
+export interface HttpRouteData {
+  readonly method: HttpMethod
+  /** Path of the route decorator as written (`undefined` when absent). */
+  readonly rawPath: string
+  /** `normalizePath(rawPath)`. */
+  readonly path: string
+  /** `joinPaths(controller base path, path)`. */
+  readonly fullPath: string
+  readonly handler: string
+  readonly status: number | undefined
+  /** `@Header` entries, lower-case names, in source order. */
+  readonly headers: readonly (readonly [string, string])[]
+  readonly meta: readonly MetaEntry[]
+  readonly guards: readonly ClassRef[]
+  readonly interceptors: readonly ClassRef[]
+  readonly params: readonly HttpParamData[]
+  /** `false` when a parameter could not be analysed (an error was reported; it is missing from `params`). */
+  readonly complete: boolean
+  /** `@Validate(S)` on a handler without `@Body()` parameter: the body is validated and discarded. */
+  readonly bodySchema: ValueRef | undefined
+  /** `@BodyLimit` of the method (or of the controller), in bytes. */
+  readonly bodyLimit: number | undefined
+  readonly rawResponse: boolean
+  /** `@Sse` route: its options (`{}` without options). */
+  readonly sse?: SseRouteData
+  /** Location of the route decorator. */
+  readonly location: Location
+  /** Location of the path argument (the decorator when absent). */
+  readonly pathLocation: Location
+}
+
+/** A controller (data stored by `analyzeClass`). */
+export interface HttpControllerData {
+  /** Provider token of the controller. */
+  readonly token: string
+  /** Canonical identity of the class (imported as a type by `invoke`). */
+  readonly identity: string
+  readonly displayName: string
+  /** Base path as written. */
+  readonly rawBasePath: string
+  /** `normalizePath(rawBasePath)`. */
+  readonly basePath: string
+  readonly guards: readonly ClassRef[]
+  readonly interceptors: readonly ClassRef[]
+  readonly meta: readonly MetaEntry[]
+  readonly routes: readonly HttpRouteData[]
+  /** Location of `@Controller`. */
+  readonly location: Location
+  /** Location of the base path argument (the decorator when absent). */
+  readonly pathLocation: Location
+}

package/src/compiler/route-decorators.ts

@@ -0,0 +1,405 @@
+/**
+ * User-defined route metadata decorators (`createRouteDecorator<T>(key, { group?, required? })`).
+ *
+ * A decorator is a route decorator when its callee is a `const` initialised with a call to
+ * `@znight/http#createRouteDecorator` whose first argument (the key) and optional second argument
+ * (the options) are statically evaluable. Its argument is evaluated like a `value` decorator
+ * argument (literals, `const` references, references to exported bindings); without argument the
+ * value is `true`. Decorators of one group are alternatives: one per controller or route.
+ */
+import type {
+  AnalyzeContext,
+  ClassInfo,
+  DecoratorInfo,
+  Diagnostic,
+  Location,
+  StaticValue,
+  ValueRef,
+} from '@znight/compiler'
+import type { HttpControllerData, MetaEntry } from './model.ts'
+
+import { type AstNode, child, children, isNode, unwrap } from './ast.ts'
+import { Codes, GROUP_NAME, Ids } from './model.ts'
+
+type Context = AnalyzeContext<HttpControllerData>
+type Project = Context['project']
+type ScopeInput = Parameters<Project['evaluate']>[0]
+type ExpressionInput = Parameters<Project['evaluate']>[1]
+type EntityName = Parameters<Project['resolveIdentifier']>[1]
+
+/** A route decorator definition: `export const Roles = createRouteDecorator<T>(key, options)`. */
+export interface RouteDecoratorDefinition {
+  readonly kind: 'route'
+  readonly key: string
+  /** `options.group ?? key`. */
+  readonly group: string
+  readonly required: boolean
+  /** Name of the `const` (`Roles`). */
+  readonly name: string
+  /** Location of the `const` name. */
+  readonly definition: Location
+}
+
+/** What a decorator identity refers to. */
+export type RouteDecoratorResolution =
+  | RouteDecoratorDefinition
+  | { readonly kind: 'other' }
+  | {
+      readonly kind: 'invalid'
+      readonly message: string
+      readonly hints: readonly string[]
+      /** The definition, when the problem is there. */
+      readonly definition?: Location
+    }
+
+const OTHER: RouteDecoratorResolution = Object.freeze({ kind: 'other' })
+
+/** Resolutions per analysis context (one context per compile). */
+const caches = new WeakMap<object, Map<string, RouteDecoratorResolution>>()
+
+/** Resolves a decorator identity to a route decorator definition (memoized per compile). */
+export function resolveRouteDecorator(ctx: Context, identity: string): RouteDecoratorResolution {
+  let cache = caches.get(ctx)
+  if (!cache) {
+    cache = new Map()
+    caches.set(ctx, cache)
+  }
+  let resolution = cache.get(identity)
+  if (!resolution) {
+    resolution = resolve(ctx, identity)
+    cache.set(identity, resolution)
+  }
+  return resolution
+}
+
+function resolve(ctx: Context, identity: string): RouteDecoratorResolution {
+  if (identity.startsWith('globalThis#')) {
+    return OTHER
+  }
+  const symbol = ctx.project.lookupIdentity(identity)
+  if (symbol.kind !== 'declaration') {
+    return OTHER
+  }
+  const declaration = symbol.declarations.find(candidate => candidate.kind === 'const')
+  const node = declaration?.node as unknown
+  const file = declaration ? ctx.project.getFile(declaration.file) : undefined
+  if (!declaration || !isNode(node) || !file) {
+    return OTHER
+  }
+  const scope = { file, namespace: declaration.namespace } as unknown as ScopeInput
+  const init = child(node, 'init')
+  if (!init) {
+    // `export declare const Roles: RouteDecorator<string[]>` (declaration file): the key is lost
+    const annotation = child(child(node, 'id') ?? node, 'typeAnnotation')
+    const type = annotation
+      ? ctx.project.resolveType(scope, annotation as unknown as Parameters<Project['resolveType']>[1])
+      : undefined
+    if (type?.kind === 'reference' && type.identity === Ids.RouteDecorator) {
+      return {
+        kind: 'invalid',
+        message: `the key of the route decorator ${declaration.name} cannot be read: it is declared without initializer`,
+        hints: [
+          'Route decorators must be declared in analysed sources: `export const X = createRouteDecorator(key)`',
+          'For a provider library, publish its sources ("znight": { "library": "source" })',
+        ],
+      }
+    }
+    return OTHER
+  }
+  const call = unwrap(init)
+  const callee = call.type === 'CallExpression' ? child(call, 'callee') : undefined
+  if (!callee || !isEntityName(unwrap(callee))) {
+    return OTHER
+  }
+  const resolved = ctx.project.resolveIdentifier(scope, unwrap(callee) as unknown as EntityName, 'value')
+  if (resolved.identity?.identity !== Ids.createRouteDecorator) {
+    return OTHER
+  }
+  const definition = file.location(declaration.span)
+  const [keyNode, optionsNode, ...extra] = children(call, 'arguments')
+  if (!keyNode || keyNode.type === 'SpreadElement') {
+    return {
+      kind: 'invalid',
+      message: `createRouteDecorator() requires a key (${declaration.name})`,
+      hints: [`export const ${declaration.name} = createRouteDecorator('${declaration.name.toLowerCase()}')`],
+      definition,
+    }
+  }
+  const key = ctx.project.evaluate(scope, keyNode as unknown as ExpressionInput, { refs: 'none' })
+  if (key.kind !== 'value' || typeof key.value !== 'string' || key.value === '') {
+    return {
+      kind: 'invalid',
+      message: `the key of the route decorator ${declaration.name} must be a statically evaluable non-empty string`,
+      hints: ["Use a string literal or a `const` string: createRouteDecorator('roles')"],
+      definition,
+    }
+  }
+  const optionsHints = [
+    `export const ${declaration.name} = createRouteDecorator('${key.value}', { group: 'access', required: true })`,
+  ]
+  if (extra.length > 0 || optionsNode?.type === 'SpreadElement') {
+    return {
+      kind: 'invalid',
+      message: `createRouteDecorator() takes a key and an optional { group?, required? } object (${declaration.name})`,
+      hints: optionsHints,
+      definition,
+    }
+  }
+  let options: StaticValue
+  if (optionsNode !== undefined) {
+    const evaluated = ctx.project.evaluate(scope, optionsNode as unknown as ExpressionInput, { refs: 'none' })
+    if (evaluated.kind !== 'value') {
+      return {
+        kind: 'invalid',
+        message: `the options of the route decorator ${declaration.name} must be statically evaluable (literals and \`const\` references)`,
+        hints: optionsHints,
+        definition,
+      }
+    }
+    options = evaluated.value
+  }
+  const parsed = parseRouteDecoratorOptions(key.value, options)
+  if ('error' in parsed) {
+    return {
+      kind: 'invalid',
+      message: `the options of the route decorator ${declaration.name} ${parsed.error}`,
+      hints: optionsHints,
+      definition,
+    }
+  }
+  return { kind: 'route', key: key.value, ...parsed, name: declaration.name, definition }
+}
+
+/**
+ * The group and `required` of a route decorator from its evaluated options (`undefined`: the
+ * defaults), or why the options are invalid.
+ */
+export function parseRouteDecoratorOptions(
+  key: string,
+  options: StaticValue,
+): { readonly group: string; readonly required: boolean } | { readonly error: string } {
+  if (options === undefined) {
+    return { group: key, required: false }
+  }
+  if (!isPlainObject(options)) {
+    return { error: 'must be an object { group?, required? }' }
+  }
+  const unknown = Object.keys(options).find(name => name !== 'group' && name !== 'required')
+  if (unknown !== undefined) {
+    return { error: `have an unknown property "${unknown}" (expected group and required)` }
+  }
+  // the grammar applies to an explicit group only: without one, any key is its own group
+  const group = options['group'] ?? key
+  if (typeof group !== 'string' || (group !== key && !GROUP_NAME.test(group))) {
+    const shown = typeof group === 'object' && group !== null ? 'a reference' : JSON.stringify(group)
+    return { error: `have an invalid group ${shown}: a letter followed by letters, digits, _ . or -` }
+  }
+  const required = options['required'] ?? false
+  if (typeof required !== 'boolean') {
+    return { error: 'have a non-boolean "required"' }
+  }
+  return { group, required }
+}
+
+function isPlainObject(value: unknown): value is Record<string, StaticValue> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false
+  }
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+function isEntityName(node: AstNode): boolean {
+  if (node.type === 'Identifier') {
+    return true
+  }
+  if (node.type === 'MemberExpression' && node['computed'] !== true) {
+    const object = child(node, 'object')
+    return child(node, 'property')?.type === 'Identifier' && object !== undefined && isEntityName(object)
+  }
+  return false
+}
+
+/**
+ * Metadata entries of the route decorators applied to a class or a method (source order).
+ * `target` names the class or the handler (`BookController`, `BookController.remove`). Problems are
+ * reported as ZNIGHT005: two decisions of one group on the same target included.
+ */
+export function routeMeta(
+  ctx: Context,
+  cls: ClassInfo,
+  decorators: readonly DecoratorInfo[],
+  target: string,
+): MetaEntry[] {
+  const entries: MetaEntry[] = []
+  for (const decorator of decorators) {
+    if (decorator.owner !== undefined || decorator.identity === undefined) {
+      continue
+    }
+    const resolution = resolveRouteDecorator(ctx, decorator.identity)
+    if (resolution.kind === 'other') {
+      continue
+    }
+    if (resolution.kind === 'invalid') {
+      report(
+        ctx,
+        decorator,
+        `Invalid route decorator @${decorator.name}: ${resolution.message}`,
+        resolution.hints,
+        resolution.definition === undefined
+          ? undefined
+          : { message: 'The route decorator is defined here', location: resolution.definition },
+      )
+      continue
+    }
+    const value = metaValue(ctx, cls, decorator)
+    if (value === INVALID) {
+      continue
+    }
+    const previous = entries.find(entry => entry.group === resolution.group)
+    if (previous) {
+      if (previous.key === resolution.key && resolution.group === resolution.key) {
+        report(
+          ctx,
+          decorator,
+          `@${decorator.name} sets the route metadata '${resolution.key}', already set on the same target`,
+          ['Apply each route decorator once per controller or route'],
+          { message: 'First applied here', location: previous.location },
+        )
+      } else {
+        const alternatives =
+          previous.decorator === resolution.name
+            ? `@${resolution.name} once`
+            : `one of @${previous.decorator}, @${resolution.name}`
+        report(
+          ctx,
+          decorator,
+          `@${resolution.name} sets the "${resolution.group}" decision of ${target}, already set by @${previous.decorator} on the same target`,
+          [`Keep ${alternatives}: the decorators of the "${resolution.group}" group are alternatives`],
+          { message: 'First applied here', location: previous.location },
+        )
+      }
+      continue
+    }
+    entries.push({
+      key: resolution.key,
+      value,
+      location: decorator.location,
+      group: resolution.group,
+      required: resolution.required,
+      decorator: resolution.name,
+      identity: decorator.identity,
+      definition: resolution.definition,
+    })
+  }
+  return entries
+}
+
+/** `true` when the decorator is a route metadata decorator. */
+export function isRouteMetaDecorator(ctx: Context, decorator: DecoratorInfo): boolean {
+  return (
+    decorator.owner === undefined &&
+    decorator.identity !== undefined &&
+    resolveRouteDecorator(ctx, decorator.identity).kind !== 'other'
+  )
+}
+
+const INVALID: unique symbol = Symbol('invalid')
+
+function metaValue(ctx: Context, cls: ClassInfo, decorator: DecoratorInfo): StaticValue | typeof INVALID {
+  if (!decorator.called) {
+    report(ctx, decorator, `@${decorator.name} must be called: @${decorator.name}()`, [
+      `Write @${decorator.name}(${decorator.args.length > 0 ? '...' : ''})`,
+    ])
+    return INVALID
+  }
+  const [arg, ...extra] = decorator.args
+  if (arg === undefined) {
+    return true
+  }
+  if (extra.length > 0) {
+    report(ctx, decorator, `@${decorator.name} takes at most one argument`, [
+      'Pass a single value (an array or an object)',
+    ])
+    return INVALID
+  }
+  if (arg.text.startsWith('...')) {
+    report(ctx, decorator, `@${decorator.name} does not accept spread arguments`, ['Pass the value directly'])
+    return INVALID
+  }
+  const evaluation = ctx.project.evaluate(cls.file, arg.node as unknown as ExpressionInput, { refs: 'nested' })
+  switch (evaluation.kind) {
+    case 'value':
+      return checkRefs(ctx, decorator, evaluation.value) ? evaluation.value : INVALID
+    case 'ref':
+      return checkRefs(ctx, decorator, evaluation.ref) ? evaluation.ref : INVALID
+    case 'error': {
+      ctx.report({
+        code: Codes.InvalidDecorator,
+        severity: 'error',
+        message: `Invalid argument of @${decorator.name}: ${evaluation.error.message}`,
+        location: evaluation.error.location,
+        hints: [evaluation.error.hint ?? 'Extract the value to `export const X = ...` and reference it'],
+      })
+      return INVALID
+    }
+  }
+}
+
+/** Checks that every reference of a value can be imported by the generated module. */
+function checkRefs(ctx: Context, decorator: DecoratorInfo, value: StaticValue): boolean {
+  let ok = true
+  const visit = (current: StaticValue): void => {
+    if (isValueRef(current)) {
+      const route = ctx.project.importRoute(current.symbol)
+      if (!route.ok) {
+        ok = false
+        ctx.report({
+          code: Codes.InvalidDecorator,
+          severity: 'error',
+          message: `Invalid argument of @${decorator.name}: '${current.text}' cannot be imported by the generated module (${route.error.message})`,
+          location: current.location,
+          hints: route.error.hints.length > 0 ? [...route.error.hints] : ['Export it from its module'],
+        })
+      }
+      return
+    }
+    if (Array.isArray(current)) {
+      for (const item of current) {
+        visit(item)
+      }
+    } else if (typeof current === 'object' && current !== null) {
+      for (const item of Object.values(current)) {
+        visit(item)
+      }
+    }
+  }
+  visit(value)
+  return ok
+}
+
+/** `true` for a {@link ValueRef} (the only non-plain object a static value can hold). */
+export function isValueRef(value: unknown): value is ValueRef {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false
+  }
+  const prototype = Object.getPrototypeOf(value)
+  return prototype !== Object.prototype && prototype !== null && (value as { kind?: unknown }).kind === 'ref'
+}
+
+function report(
+  ctx: Context,
+  decorator: DecoratorInfo,
+  message: string,
+  hints: readonly string[],
+  related?: { readonly message: string; readonly location: Diagnostic['location'] },
+): void {
+  ctx.report({
+    code: Codes.InvalidDecorator,
+    severity: 'error',
+    message,
+    location: decorator.location,
+    hints,
+    ...(related?.location ? { related: [{ message: related.message, location: related.location }] } : {}),
+  })
+}