@znight/messaging 0.0.0-stage → 0.1.1

package/dist/compiler.mjs

@@ -0,0 +1,1023 @@
+// src/compiler/constants.ts
+/** Name of the extension, also the key of `metadata.extensions.messaging`. */
+const EXTENSION_NAME = "messaging";
+/** Module the generated code imports its helpers and types from. */
+const RUNTIME_MODULE = "@znight/messaging";
+/** Canonical identities of the decorators owned by the extension. */
+const MessagingDecorator = 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"
+});
+/** Decorators applied to methods. */
+const METHOD_DECORATORS = /* @__PURE__ */ new Set([
+	MessagingDecorator.OnMessage,
+	MessagingDecorator.Retry,
+	MessagingDecorator.OnError
+]);
+/** Decorators applied to handler parameters. */
+const PARAMETER_DECORATORS = /* @__PURE__ */ new Set([
+	MessagingDecorator.Message,
+	MessagingDecorator.Headers,
+	MessagingDecorator.Ctx
+]);
+/** ZNIGHT005: invalid decorator usage (target, arguments, several decorators...). */
+const INVALID_DECORATOR = "ZNIGHT005";
+/** ZNIGHT011: invalid message consumer (no handler, overlapping types, retry options...). */
+const INVALID_CONSUMER = "ZNIGHT011";
+/** ZNIGHT017: non-primitive `@Message()` payload without schema. */
+const UNVALIDATED_INPUT = "ZNIGHT017";
+/**
+* Default backoff of `@Retry` (must equal the runtime `DEFAULT_BACKOFF`; checked by the tests, the
+* runtime module cannot be imported here).
+*/
+const DEFAULT_BACKOFF = "exponential";
+/** Default base delay of `@Retry`, in milliseconds (the runtime `DEFAULT_RETRY_DELAY_MS`). */
+const DEFAULT_RETRY_DELAY_MS = 1e3;
+/** Largest `attempts` accepted by the runtime (`normalizeRetry`). */
+const MAX_RETRY_ATTEMPTS = 1e4;
+/** Scopes a consumer provider may have. */
+const CONSUMER_SCOPES = [
+	"singleton",
+	"request",
+	"transient"
+];
+/** Deterministic string comparison (never `localeCompare`). */
+function compareStrings(a, b) {
+	if (a === b) return 0;
+	return a < b ? -1 : 1;
+}
+// src/compiler/patterns.ts
+/**
+* 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 `*`). */
+function isPattern(type) {
+	return type.includes("*");
+}
+/**
+* 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`.
+*/
+function patternCovers(outer, inner) {
+	return covers(outer, inner, true);
+}
+/** Glob matching of `subject` by `pattern`; with `starsAreWildcards`, `*` of `subject` only match `*` of `pattern`. */
+function covers(pattern, subject, starsAreWildcards) {
+	const p = collapseStars(pattern);
+	const s = starsAreWildcards ? collapseStars(subject) : subject;
+	let previous = new Array(s.length + 1).fill(false);
+	previous[0] = true;
+	for (let i = 1; i <= p.length; i++) {
+		const char = p[i - 1];
+		const current = new Array(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) {
+	return pattern.replace(/\*{2,}/g, "*");
+}
+// src/compiler/values.ts
+/** An evaluated object literal (not an array, not a reference to an exported binding). */
+function isRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+/** Short description of a value for messages (`"orders"`, `42`, `an array`...). */
+function describeValue(value) {
+	if (value === void 0) 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.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.
+*/
+function propertyLocation(project, arg, key) {
+	let node = 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;
+		if ((name.type === "Identifier" ? name.name : name.type === "Literal" && typeof name.value === "string" && name.value) === 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. */
+function closest(name, candidates) {
+	let best;
+	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, b) {
+	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;
+}
+// src/compiler/retry.ts
+const RETRY_OPTIONS = [
+	"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
+*/
+function normalizeRetryDecorator(decorator, where, ctx) {
+	if (!decorator.called) return void 0;
+	const arg = decorator.args[0];
+	if (arg === void 0) {
+		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;
+	}
+	if (!arg.evaluated) return void 0;
+	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;
+	}
+	let valid = true;
+	const fail = (key, message, hints) => {
+		valid = false;
+		ctx.report({
+			code: INVALID_CONSUMER,
+			severity: "error",
+			message: `@Retry on ${where}: ${message}`,
+			location: propertyLocation(ctx.project, arg, key),
+			...hints === void 0 ? {} : { 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 === void 0 ? `Valid options: ${RETRY_OPTIONS.join(", ")}` : `Did you mean "${suggestion}"? Valid options: ${RETRY_OPTIONS.join(", ")}`]);
+	}
+	const attempts = options["attempts"];
+	if (attempts === void 0) fail("attempts", "\"attempts\" is required", ["attempts counts the first delivery: { attempts: 3 } means 1 delivery + 2 retries"]);
+	else if (!isInteger(attempts) || attempts < 1 || attempts > 1e4) 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 === void 0 ? 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 === void 0 ? 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 !== void 0) {
+		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;
+	const policy = isDuration(maxDelay) ? {
+		attempts,
+		backoff,
+		delay,
+		maxDelay
+	} : {
+		attempts,
+		backoff,
+		delay
+	};
+	return Object.freeze(policy);
+}
+function isInteger(value) {
+	return typeof value === "number" && Number.isInteger(value);
+}
+function isDuration(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+// src/compiler/analyze.ts
+/** Types injected as is by `@Message()` without being "unvalidated input" (binary payloads). */
+const BINARY_TYPES = /* @__PURE__ */ new Set([
+	"globalThis#Uint8Array",
+	"globalThis#ArrayBuffer",
+	"globalThis#Buffer",
+	"node:buffer#Buffer",
+	"buffer#Buffer"
+]);
+/** Maximum depth of the base class chain walked for inherited handlers. */
+const MAX_CHAIN = 32;
+/** Analyses a class carrying at least one decorator of the extension. */
+function analyzeMessagingClass(cls, ctx) {
+	const own = analyzeMembers(cls, ctx);
+	const consumers = cls.decorators.filter((decorator) => decorator.identity === MessagingDecorator.Consumer);
+	const consumer = consumers[0];
+	if (consumer === void 0) {
+		const decorators = cls.methods.flatMap((method) => method.decorators.filter((decorator) => decorator.identity !== void 0 && METHOD_DECORATORS.has(decorator.identity)).map((decorator) => ({
+			name: decorator.name,
+			location: decorator.location
+		})));
+		if (decorators.length > 0) ctx.store({
+			kind: "members",
+			identity: cls.identity,
+			displayName: cls.displayName,
+			abstract: cls.abstract,
+			decorators
+		});
+		return;
+	}
+	for (const duplicate of consumers.slice(1)) ctx.report({
+		code: INVALID_DECORATOR,
+		severity: "error",
+		message: `@${duplicate.name} is applied several times on ${cls.displayName}`,
+		location: duplicate.location,
+		hints: [`Keep a single @${duplicate.name}: a class consumes one queue`]
+	});
+	const options = readConsumerOptions(consumer, cls, ctx);
+	const token = ctx.registerProvider(cls, { scope: options.scope });
+	const chain = classChain(cls, ctx);
+	const merged = /* @__PURE__ */ new Map();
+	for (let index = chain.length - 1; index >= 0; index--) {
+		const owner = chain[index];
+		for (const [name, member] of index === 0 ? own : analyzeMembers(owner, ctx)) merged.set(name, member);
+	}
+	const members = [...merged.values()];
+	const handlers = members.flatMap((member) => member.handlers);
+	if (!members.some((member) => member.onMessage > 0)) ctx.report({
+		code: INVALID_CONSUMER,
+		severity: "error",
+		message: `@Consumer ${cls.displayName} has no @OnMessage handler`,
+		location: consumer.location,
+		hints: ["Decorate at least one public method with @OnMessage() (default handler) or @OnMessage(\"type\")"]
+	});
+	checkHandlerTypes(cls.displayName, handlers, ctx);
+	const errorHandlers = members.filter((member) => member.errorHandler !== void 0);
+	const errorHandler = errorHandlers[0];
+	for (const extra of errorHandlers.slice(1)) ctx.report({
+		code: INVALID_CONSUMER,
+		severity: "error",
+		message: `@Consumer ${cls.displayName} has several @OnError methods: ${errorHandlers.map((member) => `${member.declaredBy}.${member.method}()`).join(", ")}`,
+		location: extra.errorHandler,
+		hints: ["Keep a single @OnError method per consumer"],
+		related: [{
+			message: "First @OnError method",
+			location: errorHandler?.errorHandler
+		}]
+	});
+	ctx.store({
+		kind: "consumer",
+		token,
+		identity: cls.identity,
+		displayName: cls.displayName,
+		queue: options.queue,
+		options: options.options,
+		handlers,
+		errorHandler: errorHandler?.method,
+		chain: chain.map((owner) => owner.identity),
+		location: consumer.location
+	});
+}
+/** `@Consumer(queue)` / `@Consumer({ queue, scope?, concurrency?, deadLetter?, ...driver options })`. */
+function readConsumerOptions(decorator, cls, ctx) {
+	const invalid = {
+		queue: "",
+		scope: "singleton",
+		options: void 0
+	};
+	const prefix = `@Consumer ${cls.displayName}`;
+	if (!decorator.called) return invalid;
+	const arg = decorator.args[0];
+	if (arg === void 0) {
+		ctx.report({
+			code: INVALID_DECORATOR,
+			severity: "error",
+			message: `${prefix}: the queue to consume is required`,
+			location: decorator.location,
+			hints: ["Write @Consumer('orders') or @Consumer({ queue: 'orders', concurrency: 5 })"]
+		});
+		return invalid;
+	}
+	if (!arg.evaluated) return invalid;
+	const value = arg.value;
+	if (typeof value === "string") {
+		if (value === "") ctx.report({
+			code: INVALID_CONSUMER,
+			severity: "error",
+			message: `${prefix}: the queue must be a non-empty string`,
+			location: arg.location
+		});
+		return {
+			queue: value,
+			scope: "singleton",
+			options: void 0
+		};
+	}
+	if (!isRecord(value)) {
+		ctx.report({
+			code: INVALID_DECORATOR,
+			severity: "error",
+			message: `${prefix}: expected a queue name or an options object ({ queue, scope?, concurrency?, deadLetter? }), got ${describeValue(value)}`,
+			location: arg.location
+		});
+		return invalid;
+	}
+	const fail = (key, message, hints) => {
+		ctx.report({
+			code: INVALID_CONSUMER,
+			severity: "error",
+			message: `${prefix}: ${message}`,
+			location: propertyLocation(ctx.project, arg, key),
+			...hints === void 0 ? {} : { hints }
+		});
+	};
+	let queue = "";
+	const rawQueue = value["queue"];
+	if (rawQueue === void 0) fail("queue", "the \"queue\" option is required", ["Write @Consumer({ queue: 'orders', ... })"]);
+	else if (typeof rawQueue !== "string" || rawQueue === "") fail("queue", `"queue" must be a non-empty string, got ${describeValue(rawQueue)}`);
+	else queue = rawQueue;
+	let scope = "singleton";
+	const rawScope = value["scope"];
+	if (rawScope !== void 0) {
+		if (typeof rawScope === "string" && CONSUMER_SCOPES.includes(rawScope)) scope = rawScope;
+		else fail("scope", `"scope" must be 'singleton', 'request' or 'transient', got ${describeValue(rawScope)}`);
+	}
+	const concurrency = value["concurrency"];
+	if (concurrency !== void 0 && !(typeof concurrency === "number" && Number.isSafeInteger(concurrency) && concurrency > 0)) fail("concurrency", `"concurrency" must be a positive integer, got ${describeValue(concurrency)}`);
+	const deadLetter = value["deadLetter"];
+	if (deadLetter !== void 0 && deadLetter !== false && (typeof deadLetter !== "string" || deadLetter === "")) fail("deadLetter", `"deadLetter" must be a queue name or false, got ${describeValue(deadLetter)}`);
+	else if (deadLetter === queue && queue !== "") fail("deadLetter", `the dead-letter queue cannot be the consumed queue "${queue}"`, ["Use another queue (default: the driver naming, e.g. \"orders.dlq\"), or false to disable dead-lettering"]);
+	const options = {};
+	for (const [key, option] of Object.entries(value)) {
+		if (key === "queue" || key === "scope" || option === void 0) continue;
+		options[key] = option;
+	}
+	return {
+		queue,
+		scope,
+		options: Object.keys(options).length === 0 ? void 0 : Object.freeze(options)
+	};
+}
+/** The class and its analysable base classes (nearest first). */
+function classChain(cls, ctx) {
+	const chain = [cls];
+	const seen = /* @__PURE__ */ new Set([cls.identity]);
+	let current = cls;
+	while (current.superClass !== void 0 && chain.length < MAX_CHAIN) {
+		const base = ctx.classInfo(current.superClass.identity);
+		if (base === void 0 || seen.has(base.identity)) break;
+		chain.push(base);
+		seen.add(base.identity);
+		current = base;
+	}
+	return chain;
+}
+/**
+* Handler selection checks, mirroring the runtime (`consumers.ts`): exact types first, then patterns
+* in declaration order, then the single default handler.
+*/
+function checkHandlerTypes(consumer, handlers, ctx) {
+	let fallback;
+	const exact = /* @__PURE__ */ new Map();
+	const patterns = [];
+	const label = (handler) => `${handler.declaredBy}.${handler.method}()`;
+	for (const handler of handlers) {
+		const type = handler.type;
+		if (type === void 0) {
+			if (fallback === void 0) {
+				fallback = handler;
+				continue;
+			}
+			ctx.report({
+				code: INVALID_CONSUMER,
+				severity: "error",
+				message: `@Consumer ${consumer}: ${label(fallback)} and ${label(handler)} are both default @OnMessage() handlers`,
+				location: handler.location,
+				hints: ["Give one of them a message type: @OnMessage(\"order.created\")"],
+				related: [{
+					message: "First default handler",
+					location: fallback.location
+				}]
+			});
+			continue;
+		}
+		const previous = isPattern(type) ? patterns.find((pattern) => pattern.type === type) : exact.get(type);
+		if (previous !== void 0) {
+			ctx.report({
+				code: INVALID_CONSUMER,
+				severity: "error",
+				message: `@Consumer ${consumer}: several @OnMessage handlers for type "${type}" (${label(previous)} and ${label(handler)})`,
+				location: handler.location,
+				hints: ["A message type is handled by a single method: merge the handlers"],
+				related: [{
+					message: `First handler of "${type}"`,
+					location: previous.location
+				}]
+			});
+			continue;
+		}
+		if (!isPattern(type)) {
+			exact.set(type, handler);
+			continue;
+		}
+		const covering = patterns.find((pattern) => patternCovers(pattern.type, type));
+		if (covering !== void 0) ctx.report({
+			code: INVALID_CONSUMER,
+			severity: "error",
+			message: `@Consumer ${consumer}: the pattern "${type}" of ${label(handler)} never matches: every type it matches is matched first by "${covering.type}" (${label(covering)})`,
+			location: handler.location,
+			hints: ["Patterns are tried in declaration order (after exact types): declare the more specific pattern first"],
+			related: [{
+				message: `Pattern "${covering.type}"`,
+				location: covering.location
+			}]
+		});
+		patterns.push({
+			...handler,
+			type
+		});
+	}
+}
+/** Messaging methods declared by `cls` itself, by name, in declaration order. */
+function analyzeMembers(cls, ctx) {
+	const members = /* @__PURE__ */ new Map();
+	for (const method of cls.methods) {
+		const member = analyzeMethod(cls, method, ctx);
+		if (member !== void 0) members.set(method.name, member);
+	}
+	return members;
+}
+function analyzeMethod(cls, method, ctx) {
+	const onMessage = decoratorsOf(method.decorators, MessagingDecorator.OnMessage);
+	const retry = decoratorsOf(method.decorators, MessagingDecorator.Retry);
+	const onError = decoratorsOf(method.decorators, MessagingDecorator.OnError);
+	const decoratedParams = method.params.some((param) => param.decorators.some(isParameterDecorator));
+	if (onMessage.length === 0 && retry.length === 0 && onError.length === 0 && !decoratedParams) return void 0;
+	const where = `${cls.displayName}.${method.name}()`;
+	const primary = onMessage[0] ?? onError[0];
+	if (primary !== void 0) checkMethodShape(method, primary, where, ctx);
+	for (const duplicate of [...retry.slice(1), ...onError.slice(1)]) ctx.report({
+		code: INVALID_DECORATOR,
+		severity: "error",
+		message: `@${duplicate.name} is applied several times on ${where}`,
+		location: duplicate.location,
+		hints: [`Keep a single @${duplicate.name}`]
+	});
+	if (onMessage.length > 0 && onError[0] !== void 0) ctx.report({
+		code: INVALID_DECORATOR,
+		severity: "error",
+		message: `${where} cannot be both an @OnMessage handler and the @OnError method`,
+		location: onError[0].location,
+		hints: ["Declare the error handler in a separate method"]
+	});
+	if (onMessage.length === 0 && retry[0] !== void 0) ctx.report({
+		code: INVALID_DECORATOR,
+		severity: "error",
+		message: `@Retry has no effect on ${where}: it is not an @OnMessage handler`,
+		location: retry[0].location,
+		hints: ["Add @OnMessage() to the method, or remove @Retry"]
+	});
+	let handlers = [];
+	if (onMessage.length > 0) {
+		const policy = retry[0] === void 0 ? void 0 : normalizeRetryDecorator(retry[0], where, ctx);
+		const params = analyzeHandlerParams(method, where, ctx);
+		handlers = onMessage.flatMap((decorator) => {
+			const type = messageType(decorator, where, ctx);
+			if (type === false) return [];
+			return [Object.freeze({
+				method: method.name,
+				type,
+				retry: policy,
+				params,
+				declaredBy: cls.displayName,
+				location: decorator.location
+			})];
+		});
+	} else reportStrayParameterDecorators(method, where, onError.length > 0, ctx);
+	const errorHandler = onMessage.length === 0 ? onError[0] : void 0;
+	if (errorHandler !== void 0) checkErrorHandler(method, errorHandler, where, ctx);
+	return {
+		method: method.name,
+		declaredBy: cls.displayName,
+		onMessage: onMessage.length,
+		handlers,
+		errorHandler: errorHandler?.location
+	};
+}
+/** Handlers are called by the generated code: `consumer.method(...)`. */
+function checkMethodShape(method, decorator, where, ctx) {
+	const name = `@${decorator.name}`;
+	let problem;
+	if (method.kind !== "method") problem = {
+		message: `${name} cannot be applied to the accessor ${where}`,
+		hint: "Use a regular method"
+	};
+	else if (method.static) problem = {
+		message: `${name} cannot be applied to the static method ${where}`,
+		hint: "Handlers are called on the consumer instance: remove `static`"
+	};
+	else if (method.privateName) problem = {
+		message: `${name} cannot be applied to the #private method ${where}`,
+		hint: "Use a public method: the generated code calls it"
+	};
+	else if (method.visibility !== "public") problem = {
+		message: `${where} must be public: ${name} methods are called by the generated code`,
+		hint: `Remove the '${method.visibility}' modifier`
+	};
+	else if (method.computed) problem = {
+		message: `${name} cannot be applied to ${where}: computed method names are not supported`,
+		hint: "Use a plain method name"
+	};
+	else if (method.generator) problem = {
+		message: `${name} cannot be applied to the generator method ${where}`,
+		hint: "Use a regular (or async) method"
+	};
+	if (problem !== void 0) ctx.report({
+		code: INVALID_DECORATOR,
+		severity: "error",
+		message: problem.message,
+		location: decorator.location,
+		hints: [problem.hint]
+	});
+}
+/** Type of an `@OnMessage` decorator: a string, `undefined` (default handler) or `false` (invalid). */
+function messageType(decorator, where, ctx) {
+	const arg = decorator.args[0];
+	if (arg === void 0 || arg.evaluated && arg.value === void 0) return void 0;
+	if (!arg.evaluated) return false;
+	if (typeof arg.value !== "string") {
+		ctx.report({
+			code: INVALID_DECORATOR,
+			severity: "error",
+			message: `@OnMessage on ${where} expects a message type (a string), got ${describeValue(arg.value)}`,
+			location: arg.location,
+			hints: ["Use @OnMessage() for the default handler"]
+		});
+		return false;
+	}
+	if (arg.value === "") {
+		ctx.report({
+			code: INVALID_CONSUMER,
+			severity: "error",
+			message: `The @OnMessage type of ${where} must be a non-empty string`,
+			location: arg.location,
+			hints: ["Use @OnMessage() for the default handler"]
+		});
+		return false;
+	}
+	return arg.value;
+}
+/** The `@OnError` method is called as `consumer[method](error, message)`. */
+function checkErrorHandler(method, decorator, where, ctx) {
+	const required = method.params.filter((param) => !param.optional && !param.hasDefault && !param.rest).length;
+	if (required > 2) ctx.report({
+		code: INVALID_CONSUMER,
+		severity: "error",
+		message: `The @OnError method ${where} has ${required} required parameters: it is called with (error, message)`,
+		location: method.location,
+		hints: ["Declare onError(error: unknown, message: InboundMessage)"]
+	});
+	if (method.returnType !== void 0 && !isErrorHandlerResult(ctx.types.awaited(method.returnType))) ctx.report({
+		code: INVALID_CONSUMER,
+		severity: "error",
+		message: `The @OnError method ${where} returns '${ctx.types.format(method.returnType)}': return 'ack' to acknowledge the message, or nothing to dead-letter it`,
+		location: decorator.location,
+		hints: ["Declare the return type `'ack' | undefined` (or `void`)"]
+	});
+}
+function analyzeHandlerParams(method, where, ctx) {
+	return Object.freeze(method.params.map((param) => analyzeHandlerParam(param, where, ctx)));
+}
+function analyzeHandlerParam(param, where, ctx) {
+	const decorators = parameterDecorators(param);
+	const decorator = decorators[0];
+	if (decorator === void 0) {
+		const foreign = foreignParameterDecorator(param);
+		if (foreign !== void 0) {
+			ctx.report({
+				code: INVALID_DECORATOR,
+				severity: "error",
+				message: `@${foreign.decorator.name} on parameter '${param.name}' of ${where} is imported from '${foreign.module}': @OnMessage handler parameters use ${foreign.name} from '${RUNTIME_MODULE}'`,
+				location: foreign.decorator.location,
+				hints: [`Import it from '${RUNTIME_MODULE}': import { ${foreign.name} } from '${RUNTIME_MODULE}'`]
+			});
+			return { kind: "undefined" };
+		}
+		if (param.optional || param.hasDefault || param.rest) return { kind: "undefined" };
+		ctx.report({
+			code: INVALID_CONSUMER,
+			severity: "error",
+			message: `Parameter '${param.name}' of ${where} has no @Message(), @Headers() or @Ctx() decorator`,
+			location: param.location,
+			hints: ["Every handler parameter is extracted from the message: @Message(schema?) for the payload, @Headers(name?) for the headers, @Ctx() for the InboundMessage"]
+		});
+		return { kind: "undefined" };
+	}
+	if (decorators.length > 1) ctx.report({
+		code: INVALID_DECORATOR,
+		severity: "error",
+		message: `Parameter '${param.name}' of ${where} has several messaging decorators (${decorators.map((found) => `@${found.name}`).join(", ")})`,
+		location: decorators[1].location,
+		hints: ["Keep a single one"]
+	});
+	if (param.rest) {
+		ctx.report({
+			code: INVALID_DECORATOR,
+			severity: "error",
+			message: `@${decorator.name} cannot be applied to the rest parameter '...${param.name}' of ${where}`,
+			location: decorator.location
+		});
+		return { kind: "undefined" };
+	}
+	switch (decorator.identity) {
+		case MessagingDecorator.Message: return messageParam(param, decorator, where, ctx);
+		case MessagingDecorator.Headers: return headersParam(param, decorator, where, ctx);
+		default: return {
+			kind: "message",
+			narrow: narrowsPayload(param.type, ctx.types)
+		};
+	}
+}
+/** `@Message()` / `@Message(schema)`. */
+function messageParam(param, decorator, where, ctx) {
+	const arg = decorator.args[0];
+	if (arg === void 0 || arg.evaluated && arg.value === void 0) {
+		checkUnvalidated(param, decorator, where, ctx);
+		return { kind: "payload" };
+	}
+	if (arg.ref !== void 0) {
+		if (isClassReference(arg.ref)) {
+			ctx.report({
+				code: INVALID_DECORATOR,
+				severity: "error",
+				message: `@Message(${arg.text}) on ${where}: '${arg.ref.name}' is a class, not a Standard Schema`,
+				location: arg.location,
+				hints: ["Pass a Standard Schema (Zod, Valibot, ArkType...): export const OrderPlaced = z.object({ ... })", "Or inject the raw payload with @Message() and validate it in the handler"]
+			});
+			return { kind: "undefined" };
+		}
+		return {
+			kind: "validated",
+			schema: arg.ref
+		};
+	}
+	if (!arg.evaluated) return { kind: "undefined" };
+	ctx.report({
+		code: INVALID_DECORATOR,
+		severity: "error",
+		message: `@Message on ${where} expects a Standard Schema (Zod, Valibot, ArkType...), got ${describeValue(arg.value)}`,
+		location: arg.location,
+		hints: ["Declare the schema with `export const OrderPlaced = z.object({ ... })` and pass it: @Message(OrderPlaced)"]
+	});
+	return { kind: "undefined" };
+}
+/** `@Headers()` / `@Headers(name)`. */
+function headersParam(param, decorator, where, ctx) {
+	const arg = decorator.args[0];
+	if (arg === void 0 || arg.evaluated && arg.value === void 0) return { kind: "headers" };
+	if (!arg.evaluated) return { kind: "undefined" };
+	const name = arg.value;
+	if (typeof name !== "string" || name === "") {
+		ctx.report({
+			code: INVALID_DECORATOR,
+			severity: "error",
+			message: `@Headers on ${where} expects a header name (a non-empty string), got ${describeValue(name)}`,
+			location: arg.location,
+			hints: ["Use @Headers() to inject every header"]
+		});
+		return { kind: "undefined" };
+	}
+	if (!param.optional && !param.hasDefault && !acceptsUndefined(param.type)) ctx.report({
+		code: INVALID_DECORATOR,
+		severity: "warning",
+		message: `@Headers(${JSON.stringify(name)}) injects 'string | undefined' (the header may be missing) but parameter '${param.name}' of ${where} is typed '${ctx.types.format(param.type)}'`,
+		location: param.typeLocation,
+		hints: [`Declare it '${param.name}?: string' or '${param.name}: string | undefined', or give it a default value`]
+	});
+	return {
+		kind: "header",
+		name
+	};
+}
+/** ZNIGHT017: a structured payload injected without schema is trusted blindly. */
+function checkUnvalidated(param, decorator, where, ctx) {
+	const { type } = ctx.types.stripNullish(param.type);
+	if (isSafePayloadType(type)) return;
+	const typed = type.kind === "opaque" && type.reason === "missing-annotation" ? "has no type annotation" : `is typed '${ctx.types.format(param.type)}'`;
+	ctx.report({
+		code: UNVALIDATED_INPUT,
+		severity: ctx.options.strictValidation ? "error" : "warning",
+		message: `Unvalidated message payload: parameter '${param.name}' of ${where} ${typed} but @Message() has no schema`,
+		location: decorator.location,
+		hints: ["Validate it with a Standard Schema (Zod, Valibot, ArkType...): @Message(OrderPlaced)", "Or declare the parameter as 'unknown' and check it in the handler"]
+	});
+}
+/** Methods whose parameters carry messaging decorators without being `@OnMessage` handlers. */
+function reportStrayParameterDecorators(method, where, errorHandler, ctx) {
+	const owner = errorHandler ? void 0 : foreignHandler(method);
+	for (const param of method.params) for (const decorator of parameterDecorators(param)) {
+		let hint = "Add @OnMessage() to the method, or remove the decorator";
+		if (errorHandler) hint = "@OnError methods are called with (error, message): remove the decorator";
+		else if (owner !== void 0) hint = `${where} is a @${owner.decorator.name} handler: use the parameter decorators of '${owner.module}'`;
+		ctx.report({
+			code: INVALID_DECORATOR,
+			severity: "error",
+			message: owner === void 0 ? `@${decorator.name} has no effect on parameter '${param.name}' of ${where}: it is not an @OnMessage handler` : `@${decorator.name} (from '${RUNTIME_MODULE}') has no effect on parameter '${param.name}' of ${where}: it is not an @OnMessage handler`,
+			location: decorator.location,
+			hints: [hint]
+		});
+	}
+}
+function splitIdentity(decorator) {
+	const identity = decorator.identity;
+	const separator = identity?.lastIndexOf("#") ?? -1;
+	if (identity === void 0 || separator <= 0) return void 0;
+	return {
+		decorator,
+		module: identity.slice(0, separator),
+		name: identity.slice(separator + 1)
+	};
+}
+/**
+* A parameter decorator named like a messaging one (`Headers`, `Ctx`, `Message`) but imported from
+* another package (`@znight/http` has `Headers` and `Ctx` too).
+*/
+function foreignParameterDecorator(param) {
+	for (const decorator of param.decorators) {
+		const split = splitIdentity(decorator);
+		if (split === void 0 || split.module === "@znight/messaging") continue;
+		if (PARAMETER_DECORATORS.has(`@znight/messaging#${split.name}`)) return split;
+	}
+}
+/** The decorator through which another extension handles the method (`@Get` of `@znight/http`...). */
+function foreignHandler(method) {
+	for (const decorator of method.decorators) {
+		const owner = decorator.owner;
+		if (owner === void 0 || owner === "messaging" || owner === "core" || owner === "manifest") continue;
+		const split = splitIdentity(decorator);
+		if (split !== void 0) return split;
+	}
+}
+function decoratorsOf(decorators, identity) {
+	return decorators.filter((decorator) => decorator.identity === identity);
+}
+/**
+* Messaging decorators of a parameter. De-duplicated by position: the compiler (0.1) reports the
+* decorators of a parameter with a default value (`@Headers('x') x = 'a'`) twice.
+*/
+function parameterDecorators(param) {
+	const seen = /* @__PURE__ */ new Set();
+	return param.decorators.filter((decorator) => {
+		if (!isParameterDecorator(decorator) || seen.has(decorator.location.start)) return false;
+		seen.add(decorator.location.start);
+		return true;
+	});
+}
+function isParameterDecorator(decorator) {
+	return decorator.identity !== void 0 && PARAMETER_DECORATORS.has(decorator.identity);
+}
+/** A reference to a class declaration (`@Message(OrderDto)`). */
+function isClassReference(ref) {
+	const symbol = ref.symbol;
+	return symbol.kind === "declaration" && symbol.declaration.kind === "class";
+}
+/** Primitive and binary payload types need no schema (`unknown` is honest, `any` is not). */
+function isSafePayloadType(type) {
+	switch (type.kind) {
+		case "primitive": return type.name !== "any" && type.name !== "object";
+		case "literal": return true;
+		case "union": return type.types.every(isSafePayloadType);
+		case "reference": return BINARY_TYPES.has(type.identity);
+		default: return false;
+	}
+}
+/** Whether `undefined` is assignable to the type (unknown types are given the benefit of the doubt). */
+function acceptsUndefined(type) {
+	switch (type.kind) {
+		case "primitive": return type.name === "any" || type.name === "unknown" || type.name === "undefined" || type.name === "void";
+		case "union": return type.types.some(acceptsUndefined);
+		case "opaque":
+		case "typeParameter": return true;
+		default: return false;
+	}
+}
+/** Valid results of an `@OnError` method: `'ack'`, nothing (`void`, `undefined`), or unknown types. */
+function isErrorHandlerResult(type) {
+	switch (type.kind) {
+		case "primitive": return [
+			"void",
+			"undefined",
+			"any",
+			"unknown",
+			"never"
+		].includes(type.name);
+		case "literal": return type.value === "ack";
+		case "union": return type.types.every(isErrorHandlerResult);
+		case "promise": return isErrorHandlerResult(type.inner);
+		case "opaque":
+		case "typeParameter": return true;
+		default: return false;
+	}
+}
+/** `@Ctx() message: InboundMessage<Order>` narrows the payload: the invoker casts `m`. */
+function narrowsPayload(type, types) {
+	const { type: inner } = types.stripNullish(type);
+	if (inner.kind !== "reference" || inner.identity !== "@znight/messaging#InboundMessage") return false;
+	const payload = inner.typeArgs[0];
+	return payload !== void 0 && !(payload.kind === "primitive" && (payload.name === "unknown" || payload.name === "any"));
+}
+// src/compiler/generate.ts
+/** Builds the messaging section; `undefined` (no section) when the application has no consumer. */
+function generateMessaging(ctx) {
+	const consumers = ctx.stored.filter((data) => data.kind === "consumer").sort((a, b) => compareStrings(a.token, b.token));
+	if (consumers.length === 0) return void 0;
+	const helpers = lazyHelpers(ctx);
+	return ctx.obj([["consumers", ctx.arr(consumers.map((consumer) => consumerNode(ctx, consumer, helpers)))]]);
+}
+function consumerNode(ctx, consumer, helpers) {
+	let classType;
+	const consumerType = () => {
+		classType ??= ctx.importType(consumer.identity);
+		return classType;
+	};
+	const entries = [["token", consumer.token], ["queue", consumer.queue]];
+	if (consumer.options !== void 0) entries.push(["options", ctx.lit(consumer.options)]);
+	entries.push(["handlers", ctx.arr(consumer.handlers.map((handler) => handlerNode(ctx, handler, consumerType, helpers)))]);
+	if (consumer.errorHandler !== void 0) entries.push(["errorHandler", consumer.errorHandler]);
+	return ctx.obj(entries);
+}
+function handlerNode(ctx, handler, consumerType, helpers) {
+	const entries = [["method", handler.method]];
+	if (handler.type !== void 0) entries.push(["type", handler.type]);
+	if (handler.retry !== void 0) 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, handler, consumerType, helpers) {
+	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, helpers))), { async: params.some((param) => param.kind === "validated") });
+}
+function argumentNode(ctx, param, m, helpers) {
+	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(void 0);
+	}
+}
+function lazyHelpers(ctx) {
+	const cache = /* @__PURE__ */ new Map();
+	const get = (name, type) => {
+		let node = cache.get(name);
+		if (node === void 0) {
+			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)
+	};
+}
+// src/compiler/validate.ts
+/** Cross-consumer checks: one consumer per queue, messaging decorators outside of consumers. */
+function validateMessaging(ctx) {
+	const consumers = ctx.stored.filter((data) => data.kind === "consumer").sort((a, b) => compareStrings(a.token, b.token));
+	const byQueue = /* @__PURE__ */ new Map();
+	for (const consumer of consumers) {
+		if (consumer.queue === "") continue;
+		const first = byQueue.get(consumer.queue);
+		if (first === void 0) {
+			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
+			}]
+		});
+	}
+	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, ctx) {
+	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"]
+	});
+}
+// src/compiler/index.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 = 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: []
+	}
+});
+/** The `@znight/messaging` compiler extension. */
+const messagingCompilerExtension = Object.freeze({
+	apiVersion: 1,
+	name: EXTENSION_NAME,
+	decorators,
+	analyzeClass: analyzeMessagingClass,
+	validate: validateMessaging,
+	generate: generateMessaging
+});
+export { messagingCompilerExtension as default, messagingCompilerExtension };
+
+//# sourceMappingURL=compiler.mjs.map