@znight/messaging 0.0.0-stage → 0.1.0

package/src/compiler/constants.ts

@@ -0,0 +1,73 @@
+/**
+ * Constants shared by the compiler extension modules. This module must stay free of runtime imports:
+ * the extension entry is loaded by the compiler, which must never load the messaging runtime (spec §2).
+ */
+import type { ErrorCode } from '@znight/core'
+
+/** Name of the extension, also the key of `metadata.extensions.messaging`. */
+export const EXTENSION_NAME = 'messaging'
+
+/** Module the generated code imports its helpers and types from. */
+export const RUNTIME_MODULE = '@znight/messaging'
+
+/** Canonical identities of the decorators owned by the extension. */
+export const MessagingDecorator: {
+  readonly Consumer: '@znight/messaging#Consumer'
+  readonly OnMessage: '@znight/messaging#OnMessage'
+  readonly Retry: '@znight/messaging#Retry'
+  readonly OnError: '@znight/messaging#OnError'
+  readonly Message: '@znight/messaging#Message'
+  readonly Headers: '@znight/messaging#Headers'
+  readonly Ctx: '@znight/messaging#Ctx'
+} = Object.freeze({
+  Consumer: '@znight/messaging#Consumer',
+  OnMessage: '@znight/messaging#OnMessage',
+  Retry: '@znight/messaging#Retry',
+  OnError: '@znight/messaging#OnError',
+  Message: '@znight/messaging#Message',
+  Headers: '@znight/messaging#Headers',
+  Ctx: '@znight/messaging#Ctx',
+})
+
+/** Identity of the `InboundMessage` interface (`@Ctx()` parameters). */
+export const INBOUND_MESSAGE_IDENTITY = '@znight/messaging#InboundMessage'
+
+/** Decorators applied to methods. */
+export const METHOD_DECORATORS: ReadonlySet<string> = new Set([
+  MessagingDecorator.OnMessage,
+  MessagingDecorator.Retry,
+  MessagingDecorator.OnError,
+])
+
+/** Decorators applied to handler parameters. */
+export const PARAMETER_DECORATORS: ReadonlySet<string> = new Set([
+  MessagingDecorator.Message,
+  MessagingDecorator.Headers,
+  MessagingDecorator.Ctx,
+])
+
+/** ZNIGHT005: invalid decorator usage (target, arguments, several decorators...). */
+export const INVALID_DECORATOR: ErrorCode = 'ZNIGHT005'
+/** ZNIGHT011: invalid message consumer (no handler, overlapping types, retry options...). */
+export const INVALID_CONSUMER: ErrorCode = 'ZNIGHT011'
+/** ZNIGHT017: non-primitive `@Message()` payload without schema. */
+export const UNVALIDATED_INPUT: ErrorCode = 'ZNIGHT017'
+
+/**
+ * Default backoff of `@Retry` (must equal the runtime `DEFAULT_BACKOFF`; checked by the tests, the
+ * runtime module cannot be imported here).
+ */
+export const DEFAULT_BACKOFF = 'exponential'
+/** Default base delay of `@Retry`, in milliseconds (the runtime `DEFAULT_RETRY_DELAY_MS`). */
+export const DEFAULT_RETRY_DELAY_MS = 1000
+/** Largest `attempts` accepted by the runtime (`normalizeRetry`). */
+export const MAX_RETRY_ATTEMPTS = 10_000
+
+/** Scopes a consumer provider may have. */
+export const CONSUMER_SCOPES: readonly string[] = ['singleton', 'request', 'transient']
+
+/** Deterministic string comparison (never `localeCompare`). */
+export function compareStrings(a: string, b: string): number {
+  if (a === b) return 0
+  return a < b ? -1 : 1
+}

package/src/compiler/data.ts

@@ -0,0 +1,75 @@
+/**
+ * Data stored by the extension during analysis (`ctx.store()`), read back by `validate` and
+ * `generate`. Plain data only (plus the `ValueRef`s of schemas), in source order.
+ */
+import type { Location, StaticValue, ValueRef } from '@znight/compiler'
+import type { Token } from '@znight/core'
+
+/** A normalized `@Retry` policy (`MessageHandlerDefinition.retry`). */
+export interface RetryPolicyData {
+  readonly attempts: number
+  readonly backoff: 'fixed' | 'exponential'
+  readonly delay: number
+  readonly maxDelay?: number
+}
+
+/** How the invoker computes one argument of a handler. */
+export type HandlerParamData =
+  /** `@Message()`: `m.payload as never`. */
+  | { readonly kind: 'payload' }
+  /** `@Message(schema)`: `await validateMessage(schema, m.payload)`. */
+  | { readonly kind: 'validated'; readonly schema: ValueRef }
+  /** `@Headers()`: `m.headers`. */
+  | { readonly kind: 'headers' }
+  /** `@Headers(name)`: `messageHeader(m, name)`. */
+  | { readonly kind: 'header'; readonly name: string }
+  /** `@Ctx()`: `m` (`m as InboundMessage<never>` when the parameter narrows the payload type). */
+  | { readonly kind: 'message'; readonly narrow: boolean }
+  /** Optional parameter without messaging decorator, or invalid parameter (reported): `undefined`. */
+  | { readonly kind: 'undefined' }
+
+/** One `@OnMessage` decorator of a method. */
+export interface HandlerData {
+  readonly method: string
+  /** `@OnMessage(type)`; `undefined` for the default handler. */
+  readonly type: string | undefined
+  readonly retry: RetryPolicyData | undefined
+  readonly params: readonly HandlerParamData[]
+  /** Display name of the class declaring the method (messages). */
+  readonly declaredBy: string
+  /** Location of the `@OnMessage` decorator. */
+  readonly location: Location
+}
+
+/** A `@Consumer` class. */
+export interface ConsumerData {
+  readonly kind: 'consumer'
+  /** Provider token of the consumer. */
+  readonly token: Token
+  readonly identity: string
+  readonly displayName: string
+  /** Empty when the queue is invalid (a diagnostic was reported). */
+  readonly queue: string
+  /** `@Consumer` options without `queue` and `scope` (`undefined` when empty). */
+  readonly options: Readonly<Record<string, StaticValue>> | undefined
+  /** Handlers of the class and its analysable base classes, in declaration order (bases first). */
+  readonly handlers: readonly HandlerData[]
+  readonly errorHandler: string | undefined
+  /** Identities of the class and of its analysable base classes (nearest first). */
+  readonly chain: readonly string[]
+  /** Location of the `@Consumer` decorator. */
+  readonly location: Location
+}
+
+/** A class carrying messaging member decorators without `@Consumer` (a base class, or a mistake). */
+export interface MemberClassData {
+  readonly kind: 'members'
+  readonly identity: string
+  readonly displayName: string
+  readonly abstract: boolean
+  /** Method decorators (`@OnMessage`, `@OnError`, `@Retry`), in source order. */
+  readonly decorators: readonly { readonly name: string; readonly location: Location }[]
+}
+
+/** Everything the extension stores. */
+export type MessagingData = ConsumerData | MemberClassData

package/src/compiler/generate.ts

@@ -0,0 +1,131 @@
+/**
+ * `generate` of the messaging extension: `metadata.extensions.messaging` (README "Compiler contract",
+ * spec §9.2). Consumers are sorted by token; handlers keep their declaration order.
+ *
+ * ```ts
+ * {
+ *   consumers: [{
+ *     token: 'src/orders/order.consumer.ts#OrderConsumer',
+ *     queue: 'orders',
+ *     handlers: [{
+ *       method: 'placed',
+ *       type: 'order.placed',
+ *       retry: { attempts: 5, backoff: 'exponential', delay: 500, maxDelay: 30000 },
+ *       invoke: async (c: OrderConsumer, m: InboundMessage) => c.placed(await validateMessage(OrderPlaced, m.payload)),
+ *     }],
+ *     errorHandler: 'onError',
+ *   }],
+ * }
+ * ```
+ */
+import type { GenerateContext, GenInput, GenNode } from '@znight/compiler'
+import type { ConsumerData, HandlerData, HandlerParamData, MessagingData } from './data.ts'
+
+import { compareStrings, RUNTIME_MODULE } from './constants.ts'
+
+type Context = GenerateContext<MessagingData>
+
+/**
+ * Imports of the runtime helpers, created on first use only: an import the module does not use would
+ * break `noUnusedLocals`.
+ */
+interface Helpers {
+  inboundMessage(): GenNode
+  validateMessage(): GenNode
+  messageHeader(): GenNode
+}
+
+/** Builds the messaging section; `undefined` (no section) when the application has no consumer. */
+export function generateMessaging(ctx: Context): GenNode | undefined {
+  const consumers = ctx.stored
+    .filter((data): data is ConsumerData => data.kind === 'consumer')
+    .sort((a, b) => compareStrings(a.token, b.token))
+  if (consumers.length === 0) return undefined
+  const helpers = lazyHelpers(ctx)
+  return ctx.obj([['consumers', ctx.arr(consumers.map(consumer => consumerNode(ctx, consumer, helpers)))]])
+}
+
+function consumerNode(ctx: Context, consumer: ConsumerData, helpers: Helpers): GenNode {
+  let classType: GenNode | undefined
+  const consumerType = (): GenNode => {
+    classType ??= ctx.importType(consumer.identity)
+    return classType
+  }
+  const entries: [string, GenInput][] = [
+    ['token', consumer.token],
+    ['queue', consumer.queue],
+  ]
+  if (consumer.options !== undefined) entries.push(['options', ctx.lit(consumer.options)])
+  entries.push([
+    'handlers',
+    ctx.arr(consumer.handlers.map(handler => handlerNode(ctx, handler, consumerType, helpers))),
+  ])
+  if (consumer.errorHandler !== undefined) entries.push(['errorHandler', consumer.errorHandler])
+  return ctx.obj(entries)
+}
+
+function handlerNode(ctx: Context, handler: HandlerData, consumerType: () => GenNode, helpers: Helpers): GenNode {
+  const entries: [string, GenInput][] = [['method', handler.method]]
+  if (handler.type !== undefined) entries.push(['type', handler.type])
+  if (handler.retry !== undefined) entries.push(['retry', ctx.lit({ ...handler.retry })])
+  entries.push(['invoke', invokeNode(ctx, handler, consumerType, helpers)])
+  return ctx.obj(entries)
+}
+
+/**
+ * `(c: Consumer, m: InboundMessage) => c.method(...args)`, `async` only when it awaits a schema
+ * validation. `m` is omitted when no argument uses it (`noUnusedParameters`).
+ */
+function invokeNode(ctx: Context, handler: HandlerData, consumerType: () => GenNode, helpers: Helpers): GenNode {
+  const params = [...handler.params]
+  while (params.length > 0 && params[params.length - 1]?.kind === 'undefined') params.pop()
+  if (params.length === 0) {
+    return ctx.arrow([['c', consumerType()]], c => ctx.call(ctx.member(c, handler.method)))
+  }
+  return ctx.arrow(
+    [
+      ['c', consumerType()],
+      ['m', helpers.inboundMessage()],
+    ],
+    (c, m) =>
+      ctx.call(
+        ctx.member(c, handler.method),
+        params.map(param => argumentNode(ctx, param, m as GenNode, helpers)),
+      ),
+    { async: params.some(param => param.kind === 'validated') },
+  )
+}
+
+function argumentNode(ctx: Context, param: HandlerParamData, m: GenNode, helpers: Helpers): GenNode {
+  switch (param.kind) {
+    case 'payload':
+      return ctx.code`${ctx.member(m, 'payload')} as never`
+    case 'validated':
+      return ctx.code`await ${ctx.call(helpers.validateMessage(), [ctx.importValue(param.schema), ctx.member(m, 'payload')])}`
+    case 'headers':
+      return ctx.member(m, 'headers')
+    case 'header':
+      return ctx.call(helpers.messageHeader(), [m, param.name])
+    case 'message':
+      return param.narrow ? ctx.code`${m} as ${helpers.inboundMessage()}<never>` : m
+    case 'undefined':
+      return ctx.lit(undefined)
+  }
+}
+
+function lazyHelpers(ctx: Context): Helpers {
+  const cache = new Map<string, GenNode>()
+  const get = (name: string, type: boolean): GenNode => {
+    let node = cache.get(name)
+    if (node === undefined) {
+      node = ctx.importFrom(RUNTIME_MODULE, name, type ? { type: true } : {})
+      cache.set(name, node)
+    }
+    return node
+  }
+  return {
+    inboundMessage: () => get('InboundMessage', true),
+    validateMessage: () => get('validateMessage', false),
+    messageHeader: () => get('messageHeader', false),
+  }
+}

package/src/compiler/index.ts

@@ -0,0 +1,52 @@
+/**
+ * `@znight/messaging/compiler`: the compiler extension of `@znight/messaging` (spec §5, §6.5, §9.2).
+ *
+ * Loaded by `@znight/compiler` through the package manifest (`package.json#znight.compiler`). It reads
+ * `@Consumer` classes and their `@OnMessage` / `@Retry` / `@OnError` methods and `@Message` /
+ * `@Headers` / `@Ctx` parameters, registers consumers as providers, reports invalid consumers at build
+ * time and generates `metadata.extensions.messaging`.
+ *
+ * This entry only `import type`s from `@znight/compiler` and never loads the messaging runtime.
+ */
+import type { CompilerExtension, DecoratorSpec } from '@znight/compiler'
+import type { MessagingData } from './data.ts'
+
+import { analyzeMessagingClass } from './analyze.ts'
+import { EXTENSION_NAME, MessagingDecorator } from './constants.ts'
+import { generateMessaging } from './generate.ts'
+import { validateMessaging } from './validate.ts'
+
+export type {
+  ConsumerData,
+  HandlerData,
+  HandlerParamData,
+  MemberClassData,
+  MessagingData,
+  RetryPolicyData,
+} from './data.ts'
+
+/**
+ * Decorators owned by the extension. `static` arguments must be statically evaluable (queue names,
+ * types, retry options, header names); the `@Message` schema is a `value` (an exported binding).
+ */
+const decorators: Readonly<Record<string, DecoratorSpec>> = Object.freeze({
+  [MessagingDecorator.Consumer]: { targets: ['class'], params: ['static'] },
+  [MessagingDecorator.OnMessage]: { targets: ['method'], params: ['static'] },
+  [MessagingDecorator.Retry]: { targets: ['method'], params: ['static'] },
+  [MessagingDecorator.OnError]: { targets: ['method'], params: [] },
+  [MessagingDecorator.Message]: { targets: ['parameter'], params: ['value'] },
+  [MessagingDecorator.Headers]: { targets: ['parameter'], params: ['static'] },
+  [MessagingDecorator.Ctx]: { targets: ['parameter'], params: [] },
+} satisfies Record<string, DecoratorSpec>)
+
+/** The `@znight/messaging` compiler extension. */
+export const messagingCompilerExtension: CompilerExtension<MessagingData> = Object.freeze({
+  apiVersion: 1,
+  name: EXTENSION_NAME,
+  decorators,
+  analyzeClass: analyzeMessagingClass,
+  validate: validateMessaging,
+  generate: generateMessaging,
+})
+
+export default messagingCompilerExtension

package/src/compiler/patterns.ts

@@ -0,0 +1,54 @@
+/**
+ * Message type patterns of `@OnMessage(type)`, with the semantics of the runtime handler selection
+ * (`consumers.ts`): a type containing `*` is a pattern where `*` matches any sequence of characters;
+ * any other type is matched exactly. Exact types are tried first, then patterns in declaration order.
+ */
+
+/** Whether `type` is a pattern (contains `*`). */
+export function isPattern(type: string): boolean {
+  return type.includes('*')
+}
+
+/** Whether `type` matches `pattern` (`*` matches any sequence of characters, the runtime semantics). */
+export function matchesPattern(pattern: string, type: string): boolean {
+  return covers(pattern, type, false)
+}
+
+/**
+ * Whether every message type matched by `inner` is also matched by `outer`, so that `inner`, tried
+ * after `outer`, can never be selected. The check is sound (never reports a pattern that can be
+ * selected): `outer` must match `inner` where each `*` of `inner` can only be consumed by a `*` of
+ * `outer`.
+ */
+export function patternCovers(outer: string, inner: string): boolean {
+  return covers(outer, inner, true)
+}
+
+/** Glob matching of `subject` by `pattern`; with `starsAreWildcards`, `*` of `subject` only match `*` of `pattern`. */
+function covers(pattern: string, subject: string, starsAreWildcards: boolean): boolean {
+  const p = collapseStars(pattern)
+  const s = starsAreWildcards ? collapseStars(subject) : subject
+  // previous[j]: p[0, i - 1) matches s[0, j)
+  let previous: boolean[] = new Array<boolean>(s.length + 1).fill(false)
+  previous[0] = true
+  for (let i = 1; i <= p.length; i++) {
+    const char = p[i - 1]
+    const current: boolean[] = new Array<boolean>(s.length + 1).fill(false)
+    current[0] = char === '*' && previous[0] === true
+    for (let j = 1; j <= s.length; j++) {
+      if (char === '*') {
+        current[j] = previous[j] === true || current[j - 1] === true
+      } else {
+        const subjectChar = s[j - 1]
+        current[j] = previous[j - 1] === true && subjectChar === char && !(starsAreWildcards && subjectChar === '*')
+      }
+    }
+    previous = current
+  }
+  return previous[s.length] === true
+}
+
+/** `a**b` → `a*b` (same language). */
+function collapseStars(pattern: string): string {
+  return pattern.replace(/\*{2,}/g, '*')
+}

package/src/compiler/retry.ts

@@ -0,0 +1,136 @@
+/**
+ * Compile-time validation and normalization of `@Retry` options. Mirrors the runtime
+ * `normalizeRetry()` (same rules and defaults) so that invalid policies fail the build instead of the
+ * boot; it also rejects unknown options (typos) and warns about options without effect.
+ */
+import type { AnalyzeContext, DecoratorInfo, StaticValue } from '@znight/compiler'
+import type { MessagingData, RetryPolicyData } from './data.ts'
+
+import {
+  DEFAULT_BACKOFF,
+  DEFAULT_RETRY_DELAY_MS,
+  INVALID_CONSUMER,
+  INVALID_DECORATOR,
+  MAX_RETRY_ATTEMPTS,
+} from './constants.ts'
+import { closest, describeValue, isRecord, propertyLocation } from './values.ts'
+
+const RETRY_OPTIONS: readonly string[] = ['attempts', 'backoff', 'delay', 'maxDelay']
+
+/**
+ * Validates the argument of a `@Retry` decorator and fills the runtime defaults. Returns `undefined`
+ * (after reporting the problems) when the options are invalid.
+ *
+ * @param where the handler (`OrderConsumer.placed()`), used in messages
+ */
+export function normalizeRetryDecorator(
+  decorator: DecoratorInfo,
+  where: string,
+  ctx: AnalyzeContext<MessagingData>,
+): RetryPolicyData | undefined {
+  if (!decorator.called) return undefined // `@Retry` without call: already reported
+  const arg = decorator.args[0]
+  if (arg === undefined) {
+    ctx.report({
+      code: INVALID_DECORATOR,
+      severity: 'error',
+      message: `@Retry on ${where} requires options: @Retry({ attempts: 3 })`,
+      location: decorator.location,
+      hints: ['attempts counts the first delivery: { attempts: 3 } means 1 delivery + 2 retries'],
+    })
+    return undefined
+  }
+  if (!arg.evaluated) return undefined // not statically evaluable: already reported
+  const options = arg.value
+  if (!isRecord(options)) {
+    ctx.report({
+      code: INVALID_DECORATOR,
+      severity: 'error',
+      message: `@Retry on ${where} expects an options object ({ attempts, backoff?, delay?, maxDelay? }), got ${describeValue(options)}`,
+      location: arg.location,
+    })
+    return undefined
+  }
+
+  let valid = true
+  const fail = (key: string, message: string, hints?: readonly string[]): void => {
+    valid = false
+    ctx.report({
+      code: INVALID_CONSUMER,
+      severity: 'error',
+      message: `@Retry on ${where}: ${message}`,
+      location: propertyLocation(ctx.project, arg, key),
+      ...(hints === undefined ? {} : { hints }),
+    })
+  }
+
+  for (const key of Object.keys(options)) {
+    if (RETRY_OPTIONS.includes(key)) continue
+    const suggestion = closest(key, RETRY_OPTIONS)
+    fail(key, `unknown option "${key}"`, [
+      suggestion === undefined
+        ? `Valid options: ${RETRY_OPTIONS.join(', ')}`
+        : `Did you mean "${suggestion}"? Valid options: ${RETRY_OPTIONS.join(', ')}`,
+    ])
+  }
+
+  const attempts = options['attempts']
+  if (attempts === undefined) {
+    fail('attempts', '"attempts" is required', [
+      'attempts counts the first delivery: { attempts: 3 } means 1 delivery + 2 retries',
+    ])
+  } else if (!isInteger(attempts) || attempts < 1 || attempts > MAX_RETRY_ATTEMPTS) {
+    fail(
+      'attempts',
+      `"attempts" must be an integer between 1 and ${MAX_RETRY_ATTEMPTS}, got ${describeValue(attempts)}`,
+      ['attempts counts the first delivery: { attempts: 3 } means 1 delivery + 2 retries'],
+    )
+  }
+
+  const rawBackoff = options['backoff']
+  const backoff = rawBackoff === undefined ? DEFAULT_BACKOFF : rawBackoff
+  if (backoff !== 'fixed' && backoff !== 'exponential') {
+    fail('backoff', `"backoff" must be 'fixed' or 'exponential', got ${describeValue(backoff)}`)
+  }
+
+  const rawDelay = options['delay']
+  const delay = rawDelay === undefined ? DEFAULT_RETRY_DELAY_MS : rawDelay
+  const delayValid = isDuration(delay)
+  if (!delayValid) {
+    fail('delay', `"delay" must be a finite number of milliseconds >= 0, got ${describeValue(delay)}`)
+  }
+
+  const maxDelay = options['maxDelay']
+  if (maxDelay !== undefined) {
+    if (!isDuration(maxDelay) || (delayValid && maxDelay < delay)) {
+      fail(
+        'maxDelay',
+        `"maxDelay" must be a finite number of milliseconds >= delay${delayValid ? ` (${delay})` : ''}, got ${describeValue(maxDelay)}`,
+      )
+    } else if (backoff === 'fixed') {
+      ctx.report({
+        code: INVALID_CONSUMER,
+        severity: 'warning',
+        message: `@Retry on ${where}: "maxDelay" has no effect with backoff 'fixed' (every retry waits "delay")`,
+        location: propertyLocation(ctx.project, arg, 'maxDelay'),
+        hints: ["Remove maxDelay, or use backoff: 'exponential'"],
+      })
+    }
+  }
+
+  if (!valid || !isInteger(attempts) || (backoff !== 'fixed' && backoff !== 'exponential') || !isDuration(delay)) {
+    return undefined
+  }
+  const policy: RetryPolicyData = isDuration(maxDelay)
+    ? { attempts, backoff, delay, maxDelay }
+    : { attempts, backoff, delay }
+  return Object.freeze(policy)
+}
+
+function isInteger(value: StaticValue): value is number {
+  return typeof value === 'number' && Number.isInteger(value)
+}
+
+function isDuration(value: StaticValue): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+}

package/src/compiler/validate.ts

@@ -0,0 +1,57 @@
+/**
+ * `validate` of the messaging extension: checks that need every consumer of the application.
+ */
+import type { ValidateContext } from '@znight/compiler'
+import type { ConsumerData, MemberClassData, MessagingData } from './data.ts'
+
+import { compareStrings, INVALID_CONSUMER, INVALID_DECORATOR } from './constants.ts'
+
+/** Cross-consumer checks: one consumer per queue, messaging decorators outside of consumers. */
+export function validateMessaging(ctx: ValidateContext<MessagingData>): void {
+  const consumers = ctx.stored
+    .filter((data): data is ConsumerData => data.kind === 'consumer')
+    .sort((a, b) => compareStrings(a.token, b.token))
+
+  // a queue is consumed by a single @Consumer class (the plugin refuses to boot otherwise)
+  const byQueue = new Map<string, ConsumerData>()
+  for (const consumer of consumers) {
+    if (consumer.queue === '') continue
+    const first = byQueue.get(consumer.queue)
+    if (first === undefined) {
+      byQueue.set(consumer.queue, consumer)
+      continue
+    }
+    ctx.report({
+      code: INVALID_CONSUMER,
+      severity: 'error',
+      message: `${first.displayName} and ${consumer.displayName} both consume "${consumer.queue}"`,
+      location: consumer.location,
+      hints: [
+        'A queue is consumed by a single @Consumer class: merge the handlers, or route by type with @OnMessage(type)',
+      ],
+      related: [{ message: `${first.displayName} consumes "${consumer.queue}"`, location: first.location }],
+    })
+  }
+
+  // @OnMessage / @OnError / @Retry on a class that is neither a consumer nor one of its base classes
+  const bases = new Set(consumers.flatMap(consumer => consumer.chain))
+  for (const data of ctx.stored) {
+    if (data.kind !== 'members' || data.abstract || bases.has(data.identity)) continue
+    reportNotAConsumer(data, ctx)
+  }
+}
+
+function reportNotAConsumer(data: MemberClassData, ctx: ValidateContext<MessagingData>): void {
+  for (const decorator of data.decorators) {
+    ctx.report({
+      code: INVALID_DECORATOR,
+      severity: 'error',
+      message: `@${decorator.name} has no effect: ${data.displayName} is not a @Consumer`,
+      location: decorator.location,
+      hints: [
+        `Add @Consumer('queue') to ${data.displayName}, or extend it from a @Consumer class`,
+        'Base classes holding shared handlers should be abstract',
+      ],
+    })
+  }
+}

package/src/compiler/values.ts

@@ -0,0 +1,76 @@
+/**
+ * Helpers on statically evaluated decorator arguments and their source locations.
+ */
+import type { ArgInfo, Location, Project, StaticValue } from '@znight/compiler'
+
+type Expression = ArgInfo['node']
+
+/** An evaluated object literal (not an array, not a reference to an exported binding). */
+export function isRecord(value: StaticValue): value is Readonly<Record<string, StaticValue>> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const prototype: unknown = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+/** Short description of a value for messages (`"orders"`, `42`, `an array`...). */
+export function describeValue(value: StaticValue): string {
+  if (value === undefined) return 'undefined'
+  if (value === null) return 'null'
+  if (typeof value === 'string') return JSON.stringify(value)
+  if (typeof value === 'bigint') return `${value}n`
+  if (typeof value !== 'object') return String(value)
+  if (Array.isArray(value)) return 'an array'
+  return isRecord(value) ? 'an object' : `a reference to '${(value as { readonly text?: string }).text ?? '?'}'`
+}
+
+/**
+ * Location of the property `key` of an object literal argument (`attempts: 0` in
+ * `@Retry({ attempts: 0 })`), or of the whole argument when it is not an inline object literal.
+ */
+export function propertyLocation(project: Project, arg: ArgInfo, key: string): Location {
+  let node: Expression = arg.node
+  while (
+    node.type === 'TSAsExpression' ||
+    node.type === 'TSSatisfiesExpression' ||
+    node.type === 'TSNonNullExpression' ||
+    node.type === 'ParenthesizedExpression'
+  ) {
+    node = node.expression
+  }
+  if (node.type !== 'ObjectExpression') return arg.location
+  for (const property of node.properties) {
+    if (property.type !== 'Property' || property.computed) continue
+    const { key: name } = property
+    const found =
+      name.type === 'Identifier' ? name.name : name.type === 'Literal' && typeof name.value === 'string' && name.value
+    if (found === key) return project.getFile(arg.location.file)?.location(property) ?? arg.location
+  }
+  return arg.location
+}
+
+/** Closest candidate of `name` among `candidates` (typos: `attempt` → `attempts`), if any. */
+export function closest(name: string, candidates: readonly string[]): string | undefined {
+  let best: string | undefined
+  let bestDistance = Math.max(2, Math.floor(name.length / 3)) + 1
+  for (const candidate of candidates) {
+    const distance = editDistance(name.toLowerCase(), candidate.toLowerCase())
+    if (distance < bestDistance) {
+      best = candidate
+      bestDistance = distance
+    }
+  }
+  return best
+}
+
+function editDistance(a: string, b: string): number {
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index)
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i]
+    for (let j = 1; j <= b.length; j++) {
+      const substitution = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1)
+      current[j] = Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution)
+    }
+    previous = current
+  }
+  return previous[b.length] ?? 0
+}